|
| 1 | +# When edit-session earns its dependency |
| 2 | + |
| 3 | +The useful behavior is protecting an in-progress edit from a changed document, target |
| 4 | +or revision, including an edit followed by Undo to the same original value. Preview |
| 5 | +alone is not a reason to add this library: many editors already preview and cancel well. |
| 6 | + |
| 7 | +## A demonstrated failure in a real consumer |
| 8 | + |
| 9 | +The proposed [PdfCraft Document Properties integration](https://github.com/storytold/pdfcraft/pull/4594) |
| 10 | +has two regression tests against real egui widgets and the existing document engine: |
| 11 | + |
| 12 | +| Workflow | Baseline behavior | Proposed guarded behavior | |
| 13 | +| --- | --- | --- | |
| 14 | +| Type "Old draft", apply "Newer title" elsewhere, confirm the old dialog | Overwrites the newer title with "Old draft" | Dismisses the stale dialog; keeps the newer title and revision | |
| 15 | +| Type "Old draft", apply another edit, Undo, confirm the old dialog | Applies the stale draft and loses the Redo branch | Rejects the stale revision; preserves the original value and Redo | |
| 16 | + |
| 17 | +Baseline `418ac6a2af49b7ac2fed44ca2cae8d5d1d2cec0d`: **0/2 pass**. Proposed consumer |
| 18 | +`535d990d10832baf3b0a64910c51b280c224bd5c`: **2/2 pass**. These are the recorded |
| 19 | +25 October before/after checks, not newly discovered bugs or a survey of every dialog. |
| 20 | +The [tests](https://github.com/PerchAnton/pdfcraft/blob/535d990d10832baf3b0a64910c51b280c224bd5c/crates/ui-egui/tests/it/properties_session.rs) |
| 21 | +and [consumer reproduction instructions](https://github.com/PerchAnton/pdfcraft/blob/535d990d10832baf3b0a64910c51b280c224bd5c/docs/document-properties-sessions.md) |
| 22 | +make the behavior reviewable. [Validation details](VALIDATION.md) record the environment |
| 23 | +and broader 10-scenario / 79-step widget/engine checks. |
| 24 | + |
| 25 | +This benefit comes from the complete consumer patch: the host supplies revision changes, |
| 26 | +document identities, permissions, dialog dismissal and serialized command dispatch. |
| 27 | +The library checks the context/value and returns at most one change. A correct in-tree |
| 28 | +helper can provide the same protection. Passing these tests does not establish that an |
| 29 | +external library is preferable to that helper. |
| 30 | + |
| 31 | +## Count the cost as well |
| 32 | + |
| 33 | +At the pinned consumer revision above, the production UI diff contains **267 added / |
| 34 | +50 removed lines (net +217)** across `dialogs.rs`, `lib.rs` and `properties_session.rs`. |
| 35 | +These are physical Git diff lines, including comments/formatting; tests, examples, |
| 36 | +manifests, lockfiles and documentation are excluded. This is added behavior and host |
| 37 | +integration, **not demonstrated code reduction**. Reproduce in a PdfCraft checkout |
| 38 | +containing the integration commit: |
| 39 | + |
| 40 | +```sh |
| 41 | +git diff --numstat \ |
| 42 | + 418ac6a2af49b7ac2fed44ca2cae8d5d1d2cec0d...535d990d10832baf3b0a64910c51b280c224bd5c \ |
| 43 | + -- crates/ui-egui/src |
| 44 | +``` |
| 45 | + |
| 46 | +The library has **0 runtime dependencies**, uses `no_std` and forbids unsafe code. |
| 47 | +An existing instrumented test performs **999 proposal/check pairs with 0 additional |
| 48 | +library-triggered snapshot clones** after the one clone at construction. Reset adds |
| 49 | +one clone; finishing adds none. This counts calls to `T::clone`, not allocations inside |
| 50 | +the caller's proposal, `Clone`/`PartialEq` implementation, CPU time or memory saved versus |
| 51 | +a native helper. It is not a speed claim. Reproduce: |
| 52 | + |
| 53 | +```sh |
| 54 | +cargo test --locked proposing_and_checking_do_not_clone_snapshots_per_event |
| 55 | +``` |
| 56 | + |
| 57 | +On 26 October, all **16 lifecycle tests + 1 compile-fail doctest**, formatting and strict |
| 58 | +Clippy pass locally on Rust 1.99.1/macOS arm64. The API remains alpha.2 with MSRV 1.88; |
| 59 | +the current local check does not replace the CI MSRV check. No API growth was needed |
| 60 | +to address these adoption questions. |
| 61 | + |
| 62 | +## What feedback changes our approach |
| 63 | + |
| 64 | +- [Oculante](https://github.com/woelper/oculante/pull/799#issuecomment-6400163844) |
| 65 | + already has a largely non-destructive workflow. Wait for its UI rewrite and demonstrate |
| 66 | + a specific missing guarantee before suggesting another dependency. |
| 67 | +- [SSBH Editor](https://github.com/ScanMountGoat/ssbh_editor/issues/216#issuecomment-6400206516) |
| 68 | + already offers preview and workspace reload. There is no demonstrated regression here |
| 69 | + that justifies replacing that workflow. |
| 70 | +- [Tarsier](https://github.com/Its-Just-Nans/tarsier/issues/2#issuecomment-6400421930) |
| 71 | + prefers its backup/reset approach and closed the proposal. Respect that decision. |
| 72 | +- [PdfCraft's review](https://github.com/storytold/pdfcraft/pull/4594#pullrequestreview-5641786055) |
| 73 | + identifies a real dependency-policy cost. Both the runtime library and executing the |
| 74 | + external replay tool in CI need policy-owner approval; immutable pins do not grant it. |
| 75 | + |
| 76 | +## Decision rule for the next integration |
| 77 | + |
| 78 | +1. Reproduce a stale edit, no-op history loss or duplicated lifecycle logic in the host. |
| 79 | +2. Add a regression using the host's native test facilities before changing behavior. |
| 80 | +3. Compare a small local helper with the library under the same tests. Include the host |
| 81 | + bridge, dependency review and maintenance cost in the comparison. |
| 82 | +4. Use the external library only when shared tested behavior across consumers earns that |
| 83 | + cost. A local or ecosystem-owned helper is a valid outcome. |
| 84 | + |
| 85 | +PhotoCraft and PdfCraft are proposed consumers, not adopted dependencies. We have |
| 86 | +demonstrated behavior protection in a consumer patch; we have not demonstrated lower |
| 87 | +total source size or faster editing. The next valuable milestone is a maintainer-reviewed |
| 88 | +workflow and ownership decision, not more adapters or a larger API. |
0 commit comments