Skip to content

Latest commit

 

History

History
126 lines (101 loc) · 8.99 KB

DECISION.md

File metadata and controls

126 lines (101 loc) · 8.99 KB

Two candidate projects for PhotoCraft and PdfCraft

Research date: 24 October 2026 (Europe/Kyiv). The implementation is an experiment; no maintainer has agreed to adopt either project. The first consumer focus is PhotoCraft, followed by PdfCraft.

Follow-up — 25 October 2026

The narrow consumers are now proposed in PhotoCraft #9190 (Edit Selected Guides) and PdfCraft #4594 (Document Properties). The latter uses alpha 2 without adding any application-specific API to the library. Its baseline regressions reproduce stale metadata overwrites and loss of Redo after Undo; the adapter drives real widgets and checks engine save/reopen. Validation records the scoped checks. These are tested consumer patches, not upstream adoption. The research and candidate-selection notes below describe the earlier 24 October snapshot.

What the repositories show

PhotoCraft and PdfCraft are Rust applications using egui 0.36 and pinned dependencies from craft-libs. Bubbles is a Go component library; delta is a Rust terminal application that depends on bat. They are separate contribution targets, not one shared runtime stack. A single new Rust GUI dependency would not fit all of them automatically.

The Craft ecosystem already shares atomic saves, settings, printing, keymaps and UI components. Building replacements without a demonstrated missing capability would have a high maintenance/adoption cost. See the two application manifests: PhotoCraft, PdfCraft.

The shared UI audit identifies edit buffers, commit/cancel/drag lifecycle and caller-owned undo as a useful shared boundary. Its initial numeric-control examples are FilmCraft/EffectCraft/LightCraft, not proof that PhotoCraft/PdfCraft have agreed to the same API. Issue 67 and issue 77 also show active work in this area. Some discussion comments contain incorrect repository references and are corrected later in the thread; source code, not the original comment, is the reliable implementation evidence.

Candidate 1: edit-session

Value proposition: provide one small, toolkit-independent lifecycle for a draft edit, with host-supplied validation and document/target/revision checks. Preview does not enter live history; commit returns one proposed change; cancel returns none; no-ops preserve redo.

The strongest initial product workflow found is PhotoCraft #8414: live preview of Select

Modify (Border, Smooth, Expand, Contract, Feather), Cancel restoring the original selection, and OK committing the preview. The issue was open/unassigned at the check, with one bot comment. A targeted PR-number search returned no matches; this is not an exhaustive guarantee that nobody is implementing equivalent work under another title.

PhotoCraft already has adjustment previews and a bounded preview worker. Reuse those rendering/worker facilities where appropriate. The new draft type does not replace their pixel computation, cancellation scheduling, cache keys or selection-mask semantics. Whether a separate dependency improves that implementation must be measured in a real patch.

For PdfCraft, #3846 asks for a manual fine-angle rotation control with preview and undo. It was open/unassigned with one bot comment; the targeted PR-number search found no matching PR. This is a later consumer candidate, not a small integration: page bounds, clipping, annotations, links and save/reopen fidelity require separate engine work. A draft library does not solve those geometry problems.

An even narrower future PdfCraft pilot may be preferable after inspecting a current dialog. Its existing text-preview API already leaves bytes, dirty state and undo unchanged; preserve that behavior. Do not use the prototype as a justification to replace a working preview mechanism.

The initial opacity probe used real PhotoCraft Document/History types. The published adapter now lives in interaction-check and uses the real Session command façade with this library as an immutable Git dependency. It still does not exercise the GUI or reproduce/fix #7601 or #8414. Upstream manifests have not been changed.

Candidate 2: interaction-check

Value proposition: share small, reviewable semantic traces and assertions across development environments. A useful bug report can include an executable sequence with an explicit result after each step: drag, cancel, switch target, undo, redo, inspect.

The initial JSONL runner is independent of the library. Its first adapter uses the library plus actual PhotoCraft components. Future adapters should use existing application command channels or test harnesses, not add a new remote-control protocol to the shipped apps.

PhotoCraft documents a JSON control channel; PdfCraft documents stdio MCP. The protocols have different execution contexts; PdfCraft's MCP process does not control a running desktop app. A headless command trace is not evidence of pointer, IME or rendering correctness.

egui_kittest already tests widgets, accessibility and snapshots. teatest tests Bubble Tea programs. PdfCraft already uses proptest and has a separate Hegel pilot proposal. The contribution here is trace portability and evidence, not a replacement testing framework.

Alternatives considered

Direction Evidence Decision
Complete new GUI toolkit egui and craft-ui already underpin the apps Too much replacement and migration for this goal
Command palette / fuzzy matcher Both apps have palettes; egui-palette, egui-command and nucleo exist We did not find a sufficiently distinct first capability
Atomic save / settings / printing Already provided by craft-libs Extend existing components for concrete missing behavior
Draft editing lifecycle Repeated preview/commit/cancel responsibilities; real feature requests First small prototype, adoption conditional on a real consumer patch
Portable semantic replay Existing harnesses are useful; cross-project scenario exchange is a separate seam Second prototype, start as a companion and prove independent reuse

Alternative references: egui-palette, egui-command, nucleo, undo. An undo history crate and this draft lifecycle solve different parts of the flow; the application's current history must remain authoritative.

Adoption gates

  1. Characterize the current PhotoCraft Select > Modify workflow with its existing UI harness; inspect fresh issue/PR activity and prove the missing behavior at a pinned source revision.
  2. Implement one previewed operation with tests for cancellation, document/selection changes, stale worker results, one undo step, redo and no-op behavior. Verify the actual rendered selection and final pixels, not only parameter values. Cover applicable modes and depths.
  3. Compare the patch using the library with a local helper. A reusable dependency must remove enough duplication and provide enough tested behavior to justify its maintenance cost.
  4. Build a second real PdfCraft adapter before calling the API generally reusable. Keep app-specific commands, rendering, geometry and policy outside the core.
  5. The independent repositories are PerchAnton/edit-session and PerchAnton/interaction-check, licensed MIT OR Apache-2.0. Propose a narrow reviewable integration; maintainers may prefer a craft-libs component or an in-tree helper. Adoption is their decision, and both prototypes should remain useful without requiring a framework migration.

The two source directories are independently runnable prototypes, not two finished products. Prioritize the PhotoCraft contribution; grow the replay tool only when actual scenarios need it.