egui-037-migration-plan.md
# PhotoCraft: egui 0.37 migration plan
Status update (2026-10-25): local implementation includes main `b278ff72459cbf9754863365edd822ba2248aa07`, preserving its JPEG dependency, Affinity import and raster changes. All nine CI stages passed: 11,590 passing test executions, zero failed, 91 ignored across 93 summaries; the ignored panic hunt, strict lint and WASM compilation passed. The current-main integration received independent review. Native/browser GUI, native IME, PRIMARY, packaged WASM size, real-world 0.36 settings and paired application performance remain open. Publication requires separate explicit approval; human review and human merge are required.
The original planning record below is historical.
Current status โ 2026-10-25: the port is implemented and reconciled with main
`486afd82cce99255e999224bcfe28de00fd766aa`. The full managed CI run passed all nine stages:
formatting, strict clippy, layers, scorecard, workspace tests, the ignored panic hunt,
doctests, WASM compilation and the translation report. It recorded 11,580 passed and
91 ignored test executions across 93 summaries, with zero failures. These totals include
overlapping test invocations and are not a count of unique tests.
The production graph uses canonical GitHub sources: egui `6d518fc799681571963842f95b55a6b68431b15a`,
winit `a517b3846ee8457d84ee4975110bfda6797c44dc`, and shared UI/print
`25da1314d443171b4adeaad2cd9454b273f35c6f`. The checked-in Cargo-generated lock has SHA256
`714ce3bc78f32bc35bd69e27c4a785ac2f38983c77df9896dcddc8e5fa79ccb2`; no absolute path
patch is required. The lifecycle/capture port, Type-tool surrounding-text and byte-deletion
adapter, reset acknowledgement handling, and selection-action changes are implemented.
The research and progress entries below retain their original sequence. Their statements
about missing APIs, private path patches, unresolved pins and absent build results are historical
and superseded by this status. Native/browser GUI and IME acceptance, PRIMARY behavior, packaged
WASM size, broad visual/accessibility sweeps and paired app performance remain open. The synthetic
settings fixtures qualify migration rules, not a captured real-world 0.36 save. Human review
and human merge are required.
Revision 2 (2026-10-23): resolves the independent review at
`plan-reviews/photocraft-v1.md`, incorporates the shared E21b/W15P contracts and the
lifecycle source audit, and removes the superseded sampling, PRIMARY, screenshot and
rollback wording. The reviewed v1 document hash is retained in the evidence ledger;
this revision needs its own independent review before publication.
Baseline: `ff4738810134d7f7e68b49f2e4f231b686282ff3` ("Release 0.14.0", 2026-10-22).
`Cargo.lock` baseline: sha256 `36a1de83fea16781dc7186d33d8064cb5dfa878a2a0847228737640b1e64e2d0`,
git blob `5c96f56119b6ddb0feb2da9cff3e23232f2dc63c`.
Target: egui/eframe/epaint family **0.37.0**, not upstream `main`. Upstream tag object
`418687fa18fdac8a9b1b6c8f4a2eb1afd2df4c47` points at commit
`841a328ba2dd8f6996beb7189ebb7fc00e668a2a`. The audited Craft fork candidate is
`aiongg/egui` `craft/0.37` at `a4f9a17f64a6bae61350fb85804c9df0d9865916`; the audited
winit candidate is `aiongg/winit` `craft/0.30.13-lang` at
`8b35388bd719e8cc86a95971ba0bc026c9a8f058`, based on `storytold/winit`
`craft/0.30.13` `ffae5198770d7730e718043f035a772b7dbc3b1b`.
Those revisions are **historical, read-only evidence**. They are not accepted revisions and
are not publication authority. Every implementation claim below must be re-run against the
final published revisions.
Research basis: upstream tag `0.37.0` source and changelogs in the read-only
checkout `/home/codex/work/CraftApps/egui037-migration-20261022/egui`, the
candidate fork commits and `PATCHES.md`, and the PhotoCraft source at the
baseline SHA. No web research was needed for the API facts below; upstream
release notes and source are the primary evidence. Historical fork/audit notes
were used only to locate refs, not as acceptance evidence.
Capture acceptance follows the suite contract: a queued-not-issued hidden request and
each settling frame must request `RequestPaintWhileHidden` from logic; only an issued
screenshot command forces paint itself. Callback arrival has no implicit wake, so the
live request owns the viewport waker. Record known issuance UI bounds and a geometry
epoch, reject/retry any intervening resize/DPI/zoom/surface change even if it changes
back, and derive pixel scale from returned dimensions only under an unchanged epoch.
Default limits are 4 requests, 128 MiB/image and 256 MiB aggregate. Count reserved
in-flight and completed images together.
## 1. Decision summary
1. Move directly to 0.37.0; do not port 0.36.2 patches to a new 0.36.x branch.
2. Keep the existing `App::logic` / `App::ui` split. PhotoCraft already uses it
(`crates/ui-egui/src/lib.rs:2244` and `:2371`), so there is no blanket
`Context`-bridge migration. The work is preserving the split across hidden
windows, screenshots, control input and multiple passes.
3. Pin the whole egui family and winit by immutable git revisions. A consumer's
`[patch]` section does not propagate to dependency manifests, so the root
workspace must patch every family crate it resolves.
4. Keep the existing `eframe` opt-out from default features. Add only the features
PhotoCraft actually needs: `wgpu`, `accesskit`, `wayland`, `x11`, `persistence`,
and the new `clipboard`. Add `monochrome_emoji_fonts` to the
`epaint_default_fonts` build-dependency. Do not enable `system_fonts` in the first
cut; the existing `cjk_fonts` system-provider path is measured separately (#8512).
5. Reproduce 0.37's `egui-icons` face and family order. The current build script
fails at once because `NOTO_EMOJI_REGULAR` and `EMOJI_ICON` are now
feature-gated (`crates/ui-egui/build.rs:42`, `:44`), and `EGUI_ICONS` is
unconditional. The glyph, accessible-name and feature fixes are part of the
first green PR, not a later fixture sweep.
6. Migrate `WidgetType` to `accesskit::Role` (the old name is a deprecated alias;
several variants were renamed), `Id::new` to `Id::unique`, `Ui::id` to
`Ui::scope_id`, panel IDs to `AsIdSalt`, screenshots to a bounded
`ScreenshotCallback` completion slot, and remove `UserData` /
`Event::Screenshot`. `Ui::scope_id` is the renamed old `Ui::id`;
`Ui::unique_id` is a new globally unique but **unstable** id and must never be
used for persisted state.
7. Migrate two persisted schemas deliberately, in the first compatible PR:
`egui::PanelState` IDs and `egui_winit::WindowSettings`. `PanelState` gains a
parent-scoped id; `WindowSettings` changes from flat fields to
`normal_geometry`. The panel migration is additive (the old key stays), but the
window rewrite is one-way. Preserve panel widths and window size/fullscreen/
maximized state explicitly; document the rollback loss of window position.
8. Adopt the language fork as a second, separately reviewed stage. E5/E12/E13/E16/
E17/E20 change text layout and AccessKit semantics; `bidi_text.rs` must not
pre-reorder text once E5 is active. This stage also adopts E21b: `IMEOutput`
gains a bounded logical surrounding-text payload, and the Type tool supplies a
real model adapter. E21b is new work, not existing E21/W27 capability.
9. Treat E11 as optional. PhotoCraft does not enable `epaint/multithreading`; the
patch's forced single-threaded glyph context is a suite fix for Servo/VectorCraft,
not a PhotoCraft requirement.
10. No PR may contain an absolute `path` patch. Final production manifests pin the
reviewed, published `storytold` full 40-hex SHAs for the whole family and winit,
including E21b and W15P. Stock 0.37.0 and the aiongg candidate revisions are
research controls, never staged release pins.
11. Every performance comparison is paired on one machine. The committed
`perf/baseline.json` is a macOS M4 Pro measurement and must not be used as a
cross-machine verdict for this Linux/Windows work.
12. Both native and web run `App::logic` and `App::ui` inside `Context::run_ui`,
once per layout pass. Logic-only ticks leave events and time stale, and a
completed `run_ui` resets `current_pass_index` to zero. Fresh input is
interpreted only in a known UI phase, with a forced hidden paint when the host
is hidden. Background timers use monotonic clocks, not
`ctx.input(|i| i.time)`, and every queue is consumed exactly once.
13. The before/after harness exists on the 0.36.2 baseline before any production
edit. The baseline PR adds the text-tessellation, renderer-construction,
selection-action and screenshot-lifecycle probes and records the paired
baseline; it does not change production behavior.
## 2. Dependency model and publication
### 2.1 Current resolved family
`Cargo.toml:55-59` pins `eframe`, `egui`, `egui_kittest` at `0.36`;
`crates/ui-egui/Cargo.toml:33` pins `egui_extras` `0.36`;
`crates/ui-egui/Cargo.toml:73` pins `epaint_default_fonts` `0.36`;
winit is `=0.30.13` (`apps/photocraft/Cargo.toml:86`) and the lock resolves
egui-family `0.36.2`, winit `0.30.13`, wgpu `30.0.1`, accesskit `0.24.1`.
`craft-ui` is pinned to `5c874d51eeb3de70e735c8ce87a59a7dedd47675`,
`craft-print` to `3d37da389a3618ab9b76109da11416e9ca4ea719`, and
`craft-docpath` to `82a24b006eefa036b43c09a67fb9a3fbd17ffe63`
(`Cargo.toml:13`, `:42-43`).
### 2.2 Target family
Target the whole compatible set together:
| Package | Target | Source |
|---|---|---|
| `egui`, `eframe`, `egui-winit`, `egui-wgpu`, `egui_glow`, `egui_extras`, `egui_kittest`, `epaint`, `emath`, `ecolor`, `epaint_default_fonts` | 0.37.0 | one reviewed, published `storytold/egui` full 40-hex final P8 revision containing E1-E21, P2b/P7/P7b/E21b and P7c |
| `winit` | 0.30.13 | one reviewed, published `storytold/winit` full 40-hex revision containing W1-W27 **and W15P** |
| `wgpu` | 30.0.1 | registry (unchanged; `egui-wgpu` 0.37 is built for wgpu 30) |
| `accesskit` / `accesskit_winit` | 0.25.1 / 0.34.1 | registry, pulled by egui 0.37 |
The root workspace needs a `[patch.crates-io]` entry for **each** of those egui-family
packages and `winit`; patching only `egui` splits the graph. The same revision for all
egui crates is required because the fork's workspace crates depend on each other by
path. `epaint_default_fonts` is a build-dependency and must be patched too.
`egui_extras` must be `version = "0.37"`; do not assume crate version numbers match
the release name (`egui_plot`, if ever added, is independently versioned).
The candidate fork currently uses a **mutable branch**:
`aiongg/egui` commit `137398e6` sets `winit = { git = ".../aiongg/winit", branch =
"craft/0.30.13-lang" }`. The plan requires replacing that with an exact `rev`. A branch
pin is not reproducible and can change between two CI runs.
Pin identities are deliberately split:
- **production pins**: reviewed, published `storytold/egui` and `storytold/winit`
full SHAs, reachable from the public URLs, carrying every selected E/W patch,
E21b and W15P, with `PATCHES.md` and removal conditions;
- **research controls**: upstream `0.37.0` (`841a328b...`), upstream `0.36.2`
(`49682f8b...`), aiongg `a4f9a17f...`/`8b35388b...` and any stock-only experiment
used to attribute #8731/#8736. These are benchmark controls and are never a
staged release, a consumer pin or a rollback baseline.
### 2.3 Targets and feature matrix
| Target | Package / binary | egui work |
|---|---|---|
| Desktop app | `photocraft` binary (`apps/photocraft`) | eframe 0.37 native, wgpu, accesskit, wayland, x11, persistence, clipboard; no `default_fonts`, no `system_fonts` in the first cut |
| Browser app | `photocraft-web` binary (`apps/photocraft-web`) | eframe web 0.37, wgpu (WebGPU + WebGL2), accesskit; browser glyph rasterizer; `web_file` |
| Browser bootstrap | `photocraft-web-boot` binary | no egui dependency; only wasm-bindgen/web-sys; keep out of the UI changes |
| Headless CLI | `photocraft-cli` | no egui dependency; control bridge/MCP only |
| UI library | `photocraft-ui-egui` | egui 0.37, eframe 0.37 (wgpu + accesskit + clipboard), `egui_extras` 0.37 (svg), `craft-ui` at the reviewed PR 199 port |
| Tests/benches | `crates/ui-egui/tests/it`, `examples/*`, `photocraft-testkit` | kittest 0.37 (wgpu, snapshot, eframe), `snapshot`, `perf_scenarios`, `interactive_bench`, `fx_bench`, `bevel_bench`, `camera_raw_bench`, `type_bench`, `large_image_bench`, `large_file_bench` |
| Platform helper | `photocraft-tablet` | no egui dependency; keep its winit-independent X11/AppKit/Windows path; E1 is only an enabler for a future native Wayland pen |
`apps/photocraft` is the only target with the direct Linux `winit` dependency
(`=0.30.13`, x11 feature, for `EventLoopBuilderExtX11`). It must resolve to the
same patched winit revision as eframe. `apps/photocraft-web` must not add a
native winit dependency.
### 2.4 Manifest and workspace audit
- The root workspace is `resolver = "3"`, edition 2024, MSRV 1.95;
members are `crates/*`, `apps/*`, `xtask`; default members include the
desktop app, CLI and xtask (`Cargo.toml:1-6`).
- `crates/*/fuzz/Cargo.toml` are independent fuzz workspaces. None depends on
egui, eframe, winit, epaint or craft-ui; no change is expected. Verify with
`rg` after the bump.
- `examples/plugins/invert-rs/Cargo.toml` is a separate `[workspace]` for a
wasm plugin and has no UI dependency.
- `apps/photocraft-web-boot` and `apps/photocraft-cli` have no egui dependency.
- There is no `vendor/` directory, `[source]` replacement, or machine-local
`.cargo/config.toml` patch in this checkout. The only `.cargo/config.toml`
defines the `xtask` alias. Do not introduce a vendor tree for this migration.
- `[profile.wasm-release.package.egui|epaint|eframe]` entries remain valid
because the package names do not change; re-check wasm size after the bump.
### 2.5 Publication and rollback
Publication gates, in order:
1. Canonical public `storytold/egui` `craft/0.37` revision, one commit per E-patch
(including E21b), with `PATCHES.md`, tests and removal conditions.
2. Canonical public `storytold/winit` `craft/0.30.13` revision, one commit per W-patch
(including W15P), with `PATCHES.md`, tests and removal conditions.
3. `storytold/craft-libs` revision on `main` containing only the reviewed port
hunks (`8614e4a`/`1764bca`) applied to current `main`. Do not pin a PR ref or
merge the stale `b68de8c`/`ec8840a` trees.
4. PhotoCraft PRs below, each with a `Cargo.lock` generated by `--locked` resolution
from the public revisions.
Rollback is the previous coherent pair: old `Cargo.lock` plus the 0.36.2 registry
family and winit 0.30.13. Keep that exact lockfile under evidence before the first
bump. A revert of the dependency commit restores the source graph.
Persistence is not symmetric. The `PanelState` migration is additive: the old
`Id::unique(name)` key remains in `ui.ron` and 0.36.2 continues to read it. The
`WindowSettings` rewrite is **one-way**: 0.36.2 cannot deserialize the nested
`normal_geometry` value and opens with default geometry after a rollback. The first
0.37 run therefore keeps a pre-migration `ui.ron.pre-0.37` backup, and the plan
documents the window-geometry/position loss rather than calling both migrations
additive. Add a reverse-compatibility test with a 0.36-shaped settings struct and
fixtures for old macOS `inner_position_pixels`, old outer position, maximized and
fullscreen.
Reachability checks before publication:
- `git ls-remote` returns the exact revision from the public URL.
- `cargo tree -d` shows one egui, one eframe, one winit.
- `rg 'path\s*=\s*"/' Cargo.toml` is empty.
- Every `[patch]` URL is `https://github.com/storytold/...` with `rev = "<40 hex>"`.
## 3. What the source actually does
### 3.1 Native entry point
`apps/photocraft/src/main.rs:720` calls `eframe::run_native`. The app creator
installs fonts/theme through `PhotocraftApp::setup_context`
(`crates/ui-egui/src/lib.rs:2850`), attaches the GPU canvas, control server,
native menu, single-instance service and platform services, then returns
`PhotocraftApp`.
`native_options` (`apps/photocraft/src/main.rs:104`) sets a custom viewport,
`persistence_path` `ui.ron`, and a `window_builder` hook `restored_window`
(`:132`) that enforces minimum size and disables restored fullscreen.
`options.centered` is decided from `ui_state::has_saved_position`
(`apps/photocraft/src/main.rs:667`, `apps/photocraft/src/ui_state.rs:33`).
`gpu_startup` configures `options.wgpu_options`; `presentation` applies present
mode and frame-latency overrides. `eframe::Error::Wgpu(_)` is the signal for the
CPU-retry path (`apps/photocraft/src/main.rs:934`,
`apps/photocraft/src/gpu_startup.rs:477`). E2/E3 add `WgpuError::ConfigureSurface`
and `CreateRenderer`; the existing `Error::Wgpu(_)` match keeps working, but the
retry decision must be tested with the new variants.
### 3.2 Web entry point
`apps/photocraft-web/src/web.rs:47` starts `eframe::WebRunner`. `WebShell`
implements `raw_input_hook`, `logic` and `ui` (`:325`, `:332`, `:362`); its
`logic` drains dropped files, serves fonts, calls the app's `logic`, and saves
presets. Its `ui` adds a browser preset-storage banner and calls the app's `ui`.
`apps/photocraft-web/index.html` is Trunk-based and the wasm is gzipped and split
into parts by `packaging/web/package.sh`. Its 24 MiB limit applies to **each shipped
file**, not to the raw wasm; the boot module inflates the parts. 0.37 adds
`send_wrapper` and changes `epaint`/`vello_cpu`; the raw wasm and the gzipped total
must both be measured against baseline, not assumed to fit a raw-wasm cap.
`docs/development.md:459` is the reference.
### 3.3 Logic versus UI, and the pass model
The pass model is the one verified in
`/home/codex/work/ssd2/task-evidence/egui037-migration-20261022/lifecycle-source-audit.md`
against 0.37.0:
- Native (`crates/eframe/src/native/epi_integration.rs::update`) and web
(`crates/eframe/src/web/app_runner.rs`) both call `App::logic` and `App::ui`
**inside `Context::run_ui`**. Each can run once per layout pass, and
`request_discard` adds passes. Logic is not once per rendered frame.
- A hidden/occluded window may be ticked through `update_logic_only` ->
`Context::run_logic`. That path still calls `prepare_raw_input` and
`App::raw_input_hook`, but does **not** begin a pass: `ctx.input().events`,
`time`, `screen_rect` and viewport geometry remain from the previous UI pass.
`ViewportCommand::RequestPaintWhileHidden` can force a real UI pass while
`visible()` is false, so visibility does not identify a logic-only callback.
- After a normally completed `run_ui`, `current_pass_index()` is zero because
`end_pass` takes the output. Do not build a first-pass guard on a stale nonzero
index. A guard may protect genuinely once-per-layout-frame work only with a
regression proving normal hidden calls still run; it must not suppress fresh
async results, control commands or widget actions.
Consequences for PhotoCraft:
`PhotocraftApp::logic` (`crates/ui-egui/src/lib.rs:2244`) does stateful work that
must survive a hidden window: frame accounting, `sync_views`, GPU checks, control
drain, native menu, commit/end operations, screenshot issue/collect, preferences
tick, monitor polling, i18n sync, work-area fit, close guard, job tick, shortcuts,
file drops, file dialogs. Because it runs per pass, every item must consume its
queue once, use a revision/generation or monotonic deadline, and tolerate a
second pass with no new input. `self.frame += 1` (`:2257`) is a logic-pass count,
not a rendered-frame identity; screenshot settling and GPU startup checks must use
`ctx.cumulative_frame_nr()` (or an equivalent UI-phase rendered-frame counter).
`PhotocraftApp::ui` (`:2371`) draws panels, windows, dialogs, notices and the
central canvas, and does UI-local persistence (`brush_picker::persist`,
`last_brush::persist`, `tool_memory::persist`, `view_cmds::persist`) plus
`native_menu::sync`, `gpu_status::check_window`, and the current synthetic-input
wakeup. Re-running a sizing pass must not duplicate persistence, commands or
notices; move work that must happen with no paint to `logic`, and make the rest
idempotent.
`raw_input_hook` (`:2338`) normalizes synthetic input, clipboard key events,
legacy pinch, pen-hold, titlebar resize and stroke tracing. It runs for the root
and deferred viewports, not immediate viewports (unless E1 is installed), and it
also runs before a hidden `run_logic`. `take_synthetic_step` (`:2356`) removes
events from the app queue even on a logic-only tick; eframe preserves the events it
appends in `pending_raw_input`, but PhotoCraft must set a `synthetic_in_flight`
flag in the hook and send `RequestPaintWhileHidden` from `logic` (which runs
after the hook in the same tick) so a UI pass consumes them. Do not start stroke
tracing or interpret fresh input as if a paint occurred: either gate it on that
flag or move the start to `App::ui`. `egui-winit` turns
Cmd/Ctrl+C/X/V into `Event::Copy`/`Cut`/`Paste`; PhotoCraft maps those back to key
presses in `shortcuts::clipboard_keys` (`crates/ui-egui/src/shortcuts.rs:282`).
### 3.4 Panels, docking and the root Ui
The root Ui is passed to `App::ui`; panels are shown on it:
`panels::title_bar` (`crates/ui-egui/src/panels.rs:592`),
`options_bar` (`:969`), `status_bar` (`:1726`), `toolbar` (`:93`),
`right_dock` (`:1792`), and `dock_panels` (`:1866`). The custom docking surface
uses `craft_ui::docking::DockArea` with the stable ID
`photocraft-panel-docking` (`crates/ui-egui/src/panel_docking.rs:424`) and an
`egui::Panel::right("shared-panel-dock")` (`:448`).
`craft_ui` is a real runtime dependency (`panel_docking.rs:4-5`,
`tab_strip.rs:11`), not a stale manifest entry. `craft_ui`'s docking and tab
components are in the 0.37 API blast radius; PR 199 is required.
### 3.5 Fonts and text
`theme::install_fonts` (`crates/ui-egui/src/theme.rs:847`) builds a
`FontDefinitions` from `egui_fonts::definitions`, prepends Inter/JetBrains Mono,
adds named `medium`/`semibold` families, scales faces with `UiFontSizePlugin`
(`:946`), calls `ctx.set_fonts`, then installs the lazy CJK/script fallback
(`crates/ui-egui/src/cjk_fonts.rs:352`, `:375`). The fallback is app-specific:
script order follows the UI locale, reads at most one system font per frame, and
tracks its own `tried`/`loaded` state. It reads system fonts even when eframe's
`system_fonts` feature is off, so #8512's discovery cost is still on PhotoCraft's
startup/first-use path and must be measured separately.
`cjk_fonts::add_to_all_families` reads `FontData.font` as bytes
(`cjk_fonts.rs:354`, `:355`, `:358`) and a test compares the pointer
(`:879`). In 0.37 `FontData.font` becomes
`Arc<dyn AsRef<[u8]> + Send + Sync>` (`epaint::text::FontData`), so those four
uses do not type-check as written.
### 3.6 Screenshots and control
`control.rs:1265` handles `ui.screenshot`; `PhotocraftApp::drain_control`
(`lib.rs:2156`) queues `(token, earliest_time, frames)` in
`queued_screenshots`; `issue_screenshots` (`:2183`) sends
`ViewportCommand::Screenshot(UserData::new(token))`; `collect_screenshots`
(`:2196`) reads `Event::Screenshot { user_data, image }` and calls
`control::save_screenshot` (`control.rs:1410`). This is exactly the API 0.37
removes: `ViewportCommand::Screenshot` now takes a `ScreenshotCallback`, and
`Event::Screenshot` / `UserData` no longer exist. The current records are removed
only by a matching callback, so a zero-sized surface, hidden viewport, device
loss or dropped capture leaves the reply pending until the 60 s deadline and
retains its image path. Section 9.3 replaces that with a bounded, cancelable
slot and an explicit timeout drain.
### 3.7 Persistence
`ui.ron` contains two independently versioned payloads:
- eframe window geometry, restored by `egui_winit::WindowSettings`;
- egui memory, including `PanelState` entries and persisted widget data.
`apps/photocraft/src/ui_state.rs` sanitizes the file before eframe reads it and
decides whether a saved position exists. `saved_position` is platform-dependent:
macOS looks for `inner_position_pixels`, everywhere else for
`outer_position_pixels` (`ui_state.rs:41-44`). 0.37 replaces the flat
`WindowSettings` with `normal_geometry: WindowGeometry` containing
`outer_position_pixels`, `scale_factor` and `inner_size_points`. The old value
does not deserialize, eframe ignores it, and a top-level probe becomes a false
positive: the window opens uncentered at the OS default. Section 9.2 specifies the
explicit pre-load rewrite and the new platform-independent position key.
`PanelState` is keyed by an `Id`. In 0.36 `Panel::left("dock")` used
`Id::new("dock")`; in 0.37 the panel ID is
`parent_ui.scope_id().with_salt(IdSalt::new("dock"))` (`Id::with`, not
`Id::with_salt` + an `AsIdSalt`). For the root Ui that is
`ctx.viewport_id().root_ui_id().with(salt)`. Existing saved panel widths are under
the old IDs and will not be restored unless migrated. Tests that read
`PanelState::load(&ctx, Id::unique("dock"))` also break
(`apps/photocraft/src/main.rs:1004`, `crates/ui-egui/src/panels.rs:6604`,
`:6934`, `crates/ui-egui/src/workspace_ui.rs:594`,
`crates/ui-egui/src/panel_docking_tests.rs:569`). `Id::unique(name)` has the same
hash as the old `Id::new(name)`, so the old key can still be read.
### 3.8 Tests and performance infrastructure
The repository already has the right harnesses:
- `crates/ui-egui/examples/snapshot.rs` renders the full UI offscreen with
`egui_kittest` + wgpu, deterministic `RendererOptions`, scripts, themes and
scales.
- `crates/ui-egui/src/panel_docking_tests.rs:179` captures theme/width/scale
docking fixtures when `CRAFT_UI_DOCKING_FIXTURES` is set.
- `crates/ui-egui/src/panels.rs:6904` captures compact chrome fixtures under
`CRAFT_UI_VISUAL_FIXTURES`.
- `perf/budgets.toml` maps P1โฆPn rows to `perf_scenarios`, `interactive_bench`,
`fx_bench`, `bevel_bench`, `camera_raw_bench`, `type_bench`,
`large_image_bench`, `large_file_bench`, plus the new `text_tessellation`
row; `xtask perf` runs them in release and writes p50/p95 (and p99 for frame
rows with enough samples), peak RSS, GPU bytes and load averages.
- `crates/ui-egui/tests/it` has wgpu kittest tests for canvas, GPU loss,
color management, exports and workspace presets.
- `apps/photocraft/tests/mac_menu_appkit.rs` is the existing real-macOS menu
check; it is not a substitute for IME/focus testing.
There are 481 `Harness::builder()` uses (source count at
`ff473881`). They will inherit 0.37's `check_accessibility: true` and
`missing_glyph_policy: Panic` (`egui_kittest/src/builder.rs:50-51`). Both defaults
are good, but they turn latent UI defects into test failures. The minimal
accessible-name, glyph-policy and feature fixes therefore belong in the first
green PR; do not disable either check globally and do not defer them to a later
fixture sweep.
### 3.9 Multiple viewports
PhotoCraft creates extra document windows with
`ctx.show_viewport_immediate(ViewportId::from_hash_of(("docwin", w.id)), ...)`
(`crates/ui-egui/src/canvas.rs:6551`). These are immediate viewports, not deferred
ones. The implications are:
- `App::raw_input_hook` does not run for immediate viewports; E1's
`ViewportHooks::raw_input` is the only per-viewport hook that does. PhotoCraft
has no consumer today, but the extra-window path must be tested with E1 present
and absent.
- The root-only services (`tool_cursor`, `monitor_status`, `caps_lock`, screenshot
capture, control server) correctly guard on `ViewportId::ROOT`
(`tool_cursor.rs:103`, `monitor_status.rs:274`); do not accidentally make them
viewport-global.
- #8748 (hidden-parent deferred children) is **closed and unmerged**, so it is not
behavior in 0.37.0. PhotoCraft has no `show_viewport_deferred` call sites
(`canvas.rs:6551`, `screen_picker.rs:296`, `camera_raw_ui.rs:1224` are all
`show_viewport_immediate`), so the upstream deferred-child bug is not directly
applicable. Still test the hidden/occluded root plus an immediate child's
open/update/close, because that is the path PhotoCraft actually uses.
- `ui.screenshot` is documented as main-window only (`docs/control-protocol.md`);
do not promise child-window screenshots in 0.37.
- Extra windows use the same `PhotocraftApp` state; a pass for a child viewport
may call `canvas_view` while the root UI is not being drawn. Keep document
mutation and undo transactions inside `logic` or the existing single-window
paths; test open/close of an extra window during a stroke, a dialog and a
screenshot request.
### 3.10 Platform cfg inventory
The migration can compile on one platform and still break another; these cfg
boundaries need an explicit check:
- Native-only: `sys-locale`, `rayon`, `winsafe`, `xcap`, `x11rb`, `wl-clipboard-rs`,
`zbus`, `muda`, `dispatch2`, `fmv-macos-events`, `core-graphics2` in
`apps/photocraft` and `crates/ui-egui`.
- macOS: `apple_events`, `mac_menu`, `mac_window`, `muda`, `dispatch2`,
`objc2*`, `photocraft-tablet::macos`, `tests/mac_menu_appkit.rs`.
- Windows: `window_frame`, `cursor`, `photocraft-tablet::windows`,
`photocraft-ipp`, `winsafe`.
- Linux: `portal_save`, `print_portal`, `icon_theme`, `tablet::spawn_x11`,
`linux_libs`, `winit` x11 event-loop builder.
- wasm32: `apps/photocraft-web/src/web.rs`, `cjk_fonts::Sources::system` (no
system fonts), `file_ui/web_preview.rs`, `gpu_canvas` web adapter limits,
`photocraft-web-boot`.
At minimum run `cargo check --target wasm32-unknown-unknown` (`cargo xtask
wasm`), Linux native, Windows native and macOS native for the changed crates.
Do not treat a Linux-only compile as platform acceptance.
## 4. 0.37 breaking changes mapped to PhotoCraft
| Change | PhotoCraft impact and exact work | Count / anchor |
|---|---|---|
| `WidgetType` is now a deprecated alias of `accesskit::Role`; many variants were renamed (`SelectableLabelโButton`, `CheckboxโCheckBox`, `ColorButtonโColorWell`, `CollapsingHeaderโDisclosureTriangle`, `OtherโUnknown`) | Mechanical mapping. `ButtonโButton`, `SelectableLabelโButton`, `CheckBoxโCheckBox`, `RadioButtonโRadioButton`, `LabelโLabel`, `ImageโImage`, `CollapsingHeaderโDisclosureTriangle`, `ComboBoxโComboBox`, `ColorButtonโColorWell`, `SliderโSlider`, `OtherโUnknown`. Keep selection in `WidgetInfo::selected`. | 114 uses in 43 files, e.g. `shape_stroke_ui/editor.rs:47`, `props_layout.rs:73`; PR 199's mapping is the reference |
| `Id::new` deprecated | `Id::new` โ `Id::unique` (same hash; persisted IDs stay stable). | 394 uses in 121 files |
| `Ui::id` deprecated | `ui.id()` โ `ui.scope_id()` (a rename of the old id). Do **not** substitute `Ui::unique_id`: that is a new globally unique but unstable id used for auto ids and AccessKit identity. | 93 uses |
| `Panel` constructors take `AsIdSalt`; IDs become parent-scoped | `direction.rs:71/76` currently takes `impl Into<egui::Id>` and passes it to `Panel::left`; change to `impl egui::AsIdSalt`. Add `panels::panel_state_id(ctx, salt) = ctx.viewport_id().root_ui_id().with(salt)` (`Id::with`, because `with_salt` takes an `IdSalt`). Migrate old `PanelState` keys in the first compatible PR and keep the old key readable. | 11 direct panel constructors; 5 `PanelState::load` sites |
| `UiBuilder::id` โ `scope_id` | No PhotoCraft call sites; `craft_ui` PR 199 has two. | `craft_ui/docking/surface.rs` |
| `TextEdit::hint_text` requires `IntoAtoms<'static>` | `widgets::text_field`/`text_field_ex` take `hint: &str` and pass it directly; `crop_size::text_field` does too. Convert to owned atoms once (`hint.to_owned()`) or change the helper parameter to `impl IntoAtoms<'static>` and update callers. | `widgets.rs:848`, `crop_size.rs:282` |
| `FontData.font` is a `Blob` (`Arc<dyn AsRef<[u8]>>`) | Use `data.bytes()` or `data.font.as_ref().as_ref()`; update pointer test. | `cjk_fonts.rs:354`, `:355`, `:358`, `:879` |
| `ViewportCommand::Screenshot` callback; `Event::Screenshot`/`UserData` removed | Replace `issue_screenshots` with a bounded, cancelable per-request completion slot (section 9.3), not an unbounded `mpsc` channel. The callback holds only a weak slot reference, stores only the image, and may run on an arbitrary callback thread. Collect in `logic`; use rendered-frame identity plus a monotonic settle deadline; keep token correlation. `clipping_indicator_tests.rs:94/:99` also use the removed API and must be migrated in the same PR. | `lib.rs:2183`, `:2196`, `:2214`; `control.rs:1265`; `clipping_indicator_tests.rs:94`, `:99` |
| `Event::PasteImage` new | egui-winit now emits image paste when the clipboard has no text. PhotoCraft's `clipboard_press` only maps `Event::Paste(_)`. Adopt it as the document paste shortcut through the existing `import_os_clipboard`/session path, never a second clipboard read; a test asserts one import and no text-paste double handling. | `shortcuts.rs:221`, `:282` |
| `Event::MiddleClickPaste` new | Text fields handle it; verify PhotoCraft's canvas/field interaction does not double-handle it. | `shortcuts::clipboard_keys` |
| `ScrollAreaState.offset` field private; `offset()` deprecated | Replace reads with `clamped_offset()`/`unclamped_offset()`. Replace the direct write `st.offset.y = target` with a request passed to `ScrollArea::vertical_scroll_offset` on the next frame, then clear the request. | `menu_nav.rs:504`, `:535`; `field_wheel.rs:173-174` |
| `egui-winit` clipboard feature is no longer implicit in eframe when default features are off | Add `clipboard` to the `eframe` feature list in the app and ui-egui. Without it, OS copy/paste silently falls back to an in-app-only clipboard. | `apps/photocraft/Cargo.toml:32`, `crates/ui-egui/Cargo.toml:34` |
| `system_font_fallback` defaults true | Workspace `eframe` has default features off, so the provider is only the "missing system fonts" warning. Set `NativeOptions::system_font_fallback = false` explicitly to preserve the existing CJK plugin and deterministic rendering; evaluate `system_fonts` separately. | `main.rs:104` |
| `default_fonts` is no longer default; emoji fonts are feature-gated; `egui-icons` is new | Add `monochrome_emoji_fonts` to the `epaint_default_fonts` build-dependency; deflate `EGUI_ICONS`; rebuild the family stack exactly as 0.37 does (Ubuntu-Light, egui-icons, NotoEmoji, emoji-icon-font; Hack first for monospace). Update the equality test. No new font file is committed; verify `ATTRIBUTION.md` needs no row, and add one in the same PR if a packaged asset is added. | `build.rs:37-45`, `egui_fonts.rs:47-56`, `:79` |
| `Ui::id`/`Id` semantics in tests | kittest queries by IDs still work after `Id::unique`; panel-state queries do not. `Ui::unique_id` is unstable and must not become a persisted/test key. | see persistence above |
| `AccessKit` role/label checks in kittest | Add `Response::labelled_by`/`accessible_name` where a field has no hint; keep `check_accessibility` on. These minimal name fixes are in the first green PR because the default check runs on every harness. | all 481 harnesses |
| `MissingGlyphPolicy::Panic` in kittest | Audit special characters (`โ`, `โฒโผ`, `โถโ`, `ร`, `โฆ`, `โต`, `โฎ`, `egui::special_emojis`) and add a deterministic fallback or `allow_missing_glyphs()` only where tofu is intentional. Enable `monochrome_emoji_fonts`/`EGUI_ICONS` and add the glyph-coverage test in the first green PR. | 481 harnesses |
| `#8763` TextEdit click-away selection loss | Reproduce select-text-then-click-toolbar/context-action. The fork owns the selected fix (with pointer and keyboard regressions) or a tested app workaround preserving range and undo; do not silently accept. | `widgets.rs`, `text_field_menu.rs`, new kittest/native row |
| `egui` 0.37 style defaults (roomier buttons, larger radii) | PhotoCraft overrides most `Visuals`/`Spacing` fields in `theme::apply`, but atom-based `Button`/`ComboBox` and popup/table internals still change. Pixel fixtures must be regenerated and reviewed, not blindly accepted. | `theme.rs:995` |
| `ScrollArea` kinetic/rubber-band defaults | New `ScrollStyle::kinetic`; PhotoCraft's thin scrollbars keep their explicit opacity, but menu wheel/arrow scrolling and canvas pan must be re-tested. | `theme.rs:1065`, `menu_nav.rs` |
## 5. E1โE21 and E21b audit
Base: `841a328b`. The candidate branch is `a4f9a17f`, with one commit per topic
and `PATCHES.md` at that revision. All rows need a final audit against the
published commits; the notes below state what PhotoCraft specifically needs.
| # | Change | PhotoCraft relevance and decision | Required evidence / removal |
|---|---|---|---|
| E1 | eframe `NativeOptions::viewport_hooks` (per-viewport window create/destroy and raw input, immediate viewports included) | PhotoCraft does not call it today. Keep in the shared fork because craft-tablet's native Wayland pen path needs it; do not claim pen support until craft-tablet consumes it. Verify the global hook storage does not leak between contexts/tests. | Fork unit test for install/replace; PhotoCraft full-suite run; remove when upstream offers equivalent per-viewport hooks or native Wayland pen is solved another way |
| E2+E3 | egui-wgpu surface fit to `max_texture_dimension_2d`; configure/renderer errors returned as `WgpuError::ConfigureSurface` / `CreateRenderer` | Directly relevant to multi-monitor/large restored windows and `--safe-gpu` fallback. Adopt. Add a test with a synthetic surface size above the adapter limit and a forced configure error; assert no panic and a recoverable error. | `surface_fit` unit tests; PhotoCraft large-window test; remove when upstream closes emilk/egui#8361 and ships an equivalent |
| E4 | egui-winit uses winit's Wayland clipboard when available; smithay not started; PRIMARY currently falls back to arboard | Regular clipboard/file drops are relevant on Hyprland and require W15, `wayland` and `clipboard`. Adopt the regular path. **PRIMARY is not accepted through arboard**: the default is the shared W15P winit-owned PRIMARY path on the existing connection/event queue and per-seat lifecycle; arboard is only a measured fallback if W15P cannot meet a proven requirement, with compositor evidence and an explicit unresolved gate. | Regular/image/drop tests; W15P PRIMARY matrix on wlroots/KWin/Mutter; remove when upstream #8657 lands |
| E5 | epaint bidi shaping, visual row order, marks, end caret/selection; word-motion underflow fix; tests without `default_fonts` | Core for Arabic/Hebrew UI labels. Adopt only with E12/E13/E16 and with `bidi_text.rs` removed or reduced; otherwise text is reversed twice. | Arabic/Hebrew label, mixed LTR/RTL, caret/selection tests; remove when #8577 is released |
| E6 | `request_focus` on the focused widget no longer interrupts IME | Relevant to every text field and Preferences search. Adopt. | IME preedit/commit across focus requests |
| E7 | Windows letter keys from virtual-key code on non-Latin layouts | Relevant; PhotoCraft has layout-specific symbol logic. Adopt. | Windows layout matrix (Russian/Arabic/Hebrew/German) |
| E8 | TextEdit no longer clips glyphs above/below the row | Relevant to Thai/Vietnamese/Arabic marks and small fields. Adopt; pixel tests. | Text field row geometry at 1x/1.5x/2x |
| E9 | `Style::right_to_left` mirrors menus, scrollbars, headers, title bars, combo boxes, checkboxes, popups, resize grips | PhotoCraft already mirrors shell chrome explicitly in `direction.rs`. Enabling E9 while keeping those explicit layouts will double-mirror. Adopt only after a call-site audit; default `right_to_left=false` means it is inert until set. | RTL chrome fixture matrix; remove overlapping `direction` paths |
| E10 | eframe web: named keys not typed as text; letter keys from `KeyboardEvent.code`; `lang` on hidden input/speech | Relevant to browser shortcuts and IME. Adopt. | Browser keyboard/IME workflow; no wasm size regression |
| E11 | epaint glyphs rasterized on a single-threaded vello context (fixes `vello_cpu` multithreading panic) | PhotoCraft does not enable `epaint/multithreading`; forcing `num_threads: 0` could slow other consumers. Keep out of PhotoCraft's qualifying revision unless the shared fork requires it; if included, benchmark glyph rasterization and test all fonts. | epaint tests with/without multithreading; perf rows |
| E12 | `LayoutJob::direction`, RTL right alignment, ellipsis at visual end, UAX #9 L1, linear reorder keeping isolate initiators/PDI/marks | Needed with E5; replaces `bidi_text::visual_ltr` and `elide`. Adopt in the language stage. | Title bar `*ุตูุฑุฉ.psd โ PhotoCraft`, layer-name truncation, bidi controls |
| E13 | caret/hit-test/Delete/Backspace by grapheme cluster | TextEdit and Type tool. Adopt; the Type tool has its own char-based editor (`type_tool.rs:562`, `:751`, `:964`), which must be audited for combining marks/emoji. | Grapheme deletion/movement tests in both TextEdit and Type tool |
| E14 | `FontTweak::fallback_align`: fallback fonts on primary baseline, rows grow to fit; default unchanged | PhotoCraft already computes `y_offset_factor` manually. Adopt, but do not set `fallback_align` unless the manual metrics are removed; test row height and CJK/Thai/Arabic baselines. | Font fallback baseline fixtures; `cjk_fonts` tests |
| E15 | `LineBreaker` trait (`SimpleLineBreaker` preserves rules), grapheme-safe emergency breaks, `LayoutJob::language` | Default preserves behavior; the suite uses it for craft-text line breaking, and E20 uses the language. PhotoCraft document text is parley-based, so the app impact is UI text wrapping/truncation. Adopt; test wrapping/truncation. | Wrapping fixtures with Latin/CJK/Thai |
| E16 | visual cursor movement with affinity, Home/End in reading order, password mask per cluster, neutral paragraphs inherit direction | Needed for RTL and grapheme editing. Adopt with E5/E12/E13. | Caret affinity tests, mixed-direction paragraphs |
| E17 | `Context::set_language`, `UiBuilder::language`, `Response::accessible_language`, AccessKit root language, one text run per bidi level | PhotoCraft's `i18n::sync_context` (`i18n/mod.rs:409`) must call `set_language`; add AccessKit language assertions. Adopt. | AccessKit root/label language; screen-reader smoke test |
| E18 | eframe `Frame::set_ui_language` sets `Context::set_language`; web falls back to `Context::language` | Call from `PhotocraftApp::logic` when the preference changes. Adopt. | Live language switch without losing UI state |
| E19 | one letter-key rule across Windows/macOS/Linux; `RawInput::keyboard_layout_is_latin` and `latin_layout_chars` | Relevant to non-Latin shortcuts; requires winit W25. Adopt, but keep `layout_keys.rs`'s Photoshop-specific German bracket table and test that the two rules do not fight. | Layout matrix; `layout_keys` tests |
| E20 | widget text laid out in the language of its `Ui` | Adopt with E15/E17; PhotoCraft's `tl!` remains the source text. | Translated widget labels in AccessKit and layout |
| E21 | `ImeEvent::DeleteSurroundingBytes`: TextEdit deletes exact bytes an IME replaces, in the commit's undo step | Relevant to macOS press-and-hold/dictation and Wayland IME. Requires winit W26/W27. The candidate emits this on macOS and Wayland only; Windows `ime_delete_surrounding` returns `None`. Restrict E21 acceptance to macOS/Wayland. The enum variant is a compile break for exhaustive matches; `type_tool.rs` has a catch-all but must implement the deletion for the Type tool. Adopt. | macOS/Wayland IME replacement tests; undo one step. A Windows IME row is general coverage, not E21. |
| E21b | `IMEOutput` gains a bounded logical surrounding-text payload (committed text, UTF-8 byte cursor/anchor, owning widget identity; preedit excluded) and egui-winit sends it through W27 on Wayland | **New prerequisite, not existing E21/W27 capability.** The candidate never calls `set_ime_surrounding_text`; `IMEOutput` has no logical text. Adopt with E21. PhotoCraft's custom Type tool must supply a real model adapter, not `None`: `type_tool::draw_overlay` constructs the `IMEOutput`; use the layer's logical text (`current_text`/`layout`), char-to-byte via `byte_of`, exclude the `preedit` char range, clamp to the 4000-byte payload at char boundaries, remap cursor/anchor bytes, and identify the document+layer+viewport so two windows cannot share a payload. Password fields never supply text; focus loss, no IME and unavailable context clear it. | PhotoCraft adapter plus tests: delete+commit and deletion-only, preedit exclusion, reversed selection, emoji/combining/RTL logical order, caret movement, >4000-byte line, two documents, focus/reset/late serial, multipass final output, one undo; native Wayland predictive/Vietnamese trace. Revert with the custom-editor adapters as one API set. |
The E-patches are **not** a blanket "merge the branch". In particular, E5/E12/E13/E16
form a dependency cluster; E14/E15/E20 depend on text-layout changes; E9 must not
be enabled with the current explicit RTL mirroring; E11 has no PhotoCraft consumer.
E21b depends on E21/W27 and is a separate reviewed change (egui P7b), not a
retroactive description of E21.
## 6. Winit patch audit and compatibility
Base: upstream `v0.30.13` `e9809ef5`; candidate
`8b35388b` (storytold `craft/0.30.13` `ffae5198` + W17โW27). W15P is **new
work** in the reviewed published revision, not part of the candidate; the final
production pin must include it.
| # | Change | PhotoCraft decision |
|---|---|---|
| W1 | Windows 11 `WM_DPICHANGED` suggested rect | Adopt; custom title bar and mixed-DPI drags |
| W2 | Wayland destroy seat text input only when seat is removed | Adopt |
| W3 | Windows IME caret from `GCS_CURSORPOS` only when set | Adopt |
| W4 | Windows hidden maximized windows | Adopt |
| W5 | X11 focus replacement IME context | Adopt as part of W20; audit whether W20 supersedes and remove W5's refocus path |
| W6 | macOS `NSTextInputClient` commit flow | Adopt |
| W7 | macOS discard marked text when IME disabled | Adopt |
| W8 | macOS emoji picker text as `Ime::Commit` | Adopt |
| W9 | macOS Korean space not duplicated | Adopt |
| W10 | macOS first Apple Korean key | Adopt |
| W11 | X11 server DPI before panel physical DPI | Adopt |
| W12 | macOS `mouseDownCanMoveWindow` from `movable_by_window_background` | PhotoCraft calls `NSWindow::setMovable(false)` (`apps/photocraft/src/mac_window.rs`) and drags only its own gap; keep suite-wide but not PhotoCraft-required. Verify no regression. |
| W13 | Wayland pixel/continuous scroll phases report `Moved` | Adopt; zoom/pan latch tests |
| W14 | macOS opt-in cancelable termination | PhotoCraft quits via `NSApplication terminate:` (`mac_window.rs`); not required, harmless if opt-in. |
| W15 | Wayland file drops + winit clipboard data device | Adopt; needed by E4 regular clipboard and the app's drop support |
| W15P | winit-owned PRIMARY selection on the existing connection/event queue, with per-seat `PrimarySelectionManagerState`/device/source/offer lifecycle | **Required shared path.** Distinct PRIMARY protocol object; do not bind a second regular `wl_data_device`. Adopt before E4's PRIMARY acceptance. Keyboard-only focus, serial freshness, owner/seat changes, empty/absent offers, self-paste, canceled/slow transfer, password exclusion and unchanged-selection reclaim policy are native gates on wlroots/KWin/Mutter. |
| W16 | Wayland pinch/rotation gestures | Defer; PhotoCraft has `wheel_nav::fold_legacy_pinch`, which must be re-tested |
| W17 | Regression tests for W2/W3/W5โW10/W12/W13 | Adopt with the branch |
| W18 | Windows hidden system caret for IME | Adopt |
| W19 | Windows IME `VK_PROCESSKEY` not sent as key press | Adopt |
| W20 | X11 one input context per window (replaces W5 refocus) | Adopt; resolves W5 duplication |
| W21 | X11 IME spot after 100 ms quiet | Adopt |
| W22 | macOS `ImeDocument`, replacement ranges, typed text without composition | Adopt |
| W23 | macOS โ key names from layout's โ table | Adopt |
| W24 | `Window::reset_ime()` | Adopt; expose through eframe if a PhotoCraft call site needs it (currently none) |
| W25 | X11/Wayland `KeyEventExtLatinLayout` | Adopt; required by E19 |
| W26 | macOS delete replaced text by UTF-8 byte count | Adopt; required by E21 |
| W27 | Wayland text-input-v3 surrounding text + delete-surrounding | Adopt; required by E21 and E21b. The winit state/serial/payload tests are part of the E21b acceptance, not optional coverage. |
Compatibility notes:
- Winit 0.30.13 is the last 0.30 release; the 0.31 port is not a migration target.
The fork must keep the package version `0.30.13` so `=0.30.13` and
`egui-winit`'s dependency unify.
- W14 takes `dpi` from crates.io so git consumers do not get a second `dpi`.
- The fork's `rwh_06` and `x11`/`wayland` features must remain compatible with
`accesskit_winit` and eframe.
- The app's direct Linux `winit` dependency exists only for
`EventLoopBuilderExtX11` (`apps/photocraft/src/main.rs:658`); it must resolve to
the same patched revision as eframe's winit.
- Do not add `wayland-csd-adwaita` here; it is a suite feature decision, not a
PhotoCraft migration requirement.
## 7. craft-libs PR 199
PR 199 is an open API-port, not a mergeable tree. Its head
`b68de8c5f4f1c060904d211a7b1320aa0f7bce78` and the historical audit tree
`ec8840a` are stale relative to current `main` `49190884278f16c9a9f5823d7698a8ffb5deb062`:
they omit `craft-platform` and revert security, settings, docking and printing
fixes. Take only the reusable port hunks from
`8614e4a04fae516fba16c22b31ff1008cb6be10b` plus the relevant README changes from
`1764bca` and apply them on current `main`; never merge `b68de8c`/`ec8840a` as
trees and never revert the intervening fixes.
The relevant `craft-ui` port changes are:
- `crates/ui/src/buttons/mod.rs`: `WidgetType::Button` โ `Role::Button`.
- `crates/ui/src/docking/surface.rs`: `WidgetType` โ `Role`, `UiBuilder::id` โ
`scope_id`, plus a clippy `collapsible_match` fix.
- `crates/ui/src/layout/resize.rs`, `tabs/mod.rs` and tests: `Id::new` โ
`Id::unique`, `Ui::id` โ `scope_id`, `WidgetType` โ `Role`.
- `crates/ui/Cargo.toml`: `egui_extras`/`egui_kittest` 0.37.
PhotoCraft uses `craft_ui::docking::{DockArea, Layout, Node}`,
`craft_ui::tabs::{Tab, fit}`, and `craft_ui::layout` in
`panel_docking.rs`, `tab_strip.rs`, `dock.rs` and `state.rs`. The port must be
present before PhotoCraft can compile. There is no additional shared UI helper
needed for the mechanical Role/Id migration: PhotoCraft's `WidgetInfo` calls are
local and the mappings are direct. Do not invent a compatibility shim in
`craft-ui`.
Pin policy: update **only** `craft-ui` to the published revision containing those
port hunks. `craft-print` (`3d37da389a3618ab9b76109da11416e9ca4ea719`) and
`craft-docpath` (`82a24b006eefa036b43c09a67fb9a3fbd17ffe63`) are not egui
consumers and keep their current pins; bumping all three to one `main` would pull
the unrelated printer-name/description change between `3d37da3` and the port. If
the suite later requires one craft-libs revision, audit that diff and run
PhotoCraft's print tests before changing these pins. Unaffected local vendors
(`krilla`, `hayro*`, `lopdf`, `vello_common`) and unrelated source fixes are
preserved.
## 8. Lifecycle and root-Ui design
### 8.1 Logic and hidden iterations
The verified model is section 3.3, not "logic when hidden, ui when visible".
Native and web both run logic and ui inside `run_ui`, once per pass; hidden hosts
may call `update_logic_only`, which invokes `raw_input_hook` and `App::logic`
without beginning a pass. `run_logic` leaves events, input time and layout stale.
A forced hidden paint (`RequestPaintWhileHidden`) runs the normal UI phase.
| Work | Current site | Decision |
|---|---|---|
| Control requests, synthetic input queue | `logic` `drain_control`; `raw_input_hook` `take_synthetic_step` | Keep the queue in logic. `take_synthetic_step` may consume on a hidden logic tick, so set `synthetic_in_flight` in the hook, send `RequestPaintWhileHidden` from `logic` until a real UI pass consumes the preserved events, and clear the flag in `App::ui` after that pass. Do not use the end of `ui` as the only wake. |
| Screenshots | `logic` issue/collect | Keep in logic; bounded slot; the screenshot command itself requests paint while hidden, so a hidden screenshot pass is not evidence that synthetic input would have woken the app. Use rendered-frame identity + monotonic settle deadline. |
| Job polling | `jobs_ui::tick` in logic; `jobs_ui::keep_polling` at end of ui | Move `keep_polling` to logic or call from both. Consume job results by revision/sequence exactly once per pass; a repeated pass must not re-apply a result. |
| Autosave/recovery | `format::Autosaver` background thread; `on_exit` saves tool memory | Use `std::time::Instant` (or `web_time::Instant`) for intervals and deadlines, never `ctx.input(\|i\| i.time)` in logic. Ensure `on_exit` runs for both renderers. |
| Preferences/theme/fonts | `logic` syncs language and calls `install_fonts`; `ui` applies theme on first frame | Keep setup in `setup_context` when possible; `logic` must finish setup if the creator did not. |
| File drops | `logic` drains OS/web inboxes and dropped files | Keep; `RequestPaintWhileHidden` when a drop arrives with no visible frame. |
| Native menu | `logic` runs menu; `ui` syncs it | `native_menu::sync` is UI-dependent; leave in ui, but queue menu events for the next paint. |
| GPU status/device loss | `logic` calls `check_gpu`; `ui` calls `check_window` | `check_gpu` stays in logic; `check_window` can stay in ui because it reports a painted frame, not a logic-pass count. |
| UI-local persistence (`tool_memory`, `last_brush`, `view_cmds`) | end of `ui` | Only runs when UI runs; acceptable because no user edit happened while hidden, but `on_exit` must flush the last state. A second pass must not write twice. |
`shortcuts::handle`, `drain_control`, `file_ui` drops and `jobs_ui::tick` all run
per pass. Give each a consumed queue (drain once), a revision/generation check, or
a monotonic deadline; do not count logic calls as rendered frames. Do not start
stroke tracing or interpret fresh input on a logic-only tick: gate it on
`synthetic_in_flight`/a real UI phase, or move the start to `App::ui`.
Avoid a blanket `Context` bridge. Use `ctx.input`, `ctx.data`, `ctx.memory` only
where the existing code already does; do not replay the whole UI from `logic`.
Do not poll a prior UI event twice in `run_logic`; the events there are stale.
### 8.2 Multiple passes
`Context::run_ui` and `Context::run_pass` share the root Ui; plugins run inside
`root_ui`. PhotoCraft's `setup_context` registers `CursorLifecycle`,
`SingleLineDrag`, `TextFieldMenu`, `UiFontSizePlugin`, `CjkFontPlugin`.
`on_begin_pass`/`on_end_pass` and popup sizing passes can execute content more
than once per frame. `current_pass_index` is not a durable "first pass" flag: a
completed `run_ui` leaves it at zero. Guard all side effects in `ui`:
- `self.frame += 1` stays in `logic`, but is a pass count; use
`ctx.cumulative_frame_nr()` for rendered-frame delays;
- control/screenshot queues stay in `logic`;
- `notices::show` and persistence must be idempotent for repeated content passes;
- no counters inside popup/window closures that change on a sizing pass.
Action playback (`actions.rs`) and autosave (`format::Autosaver` /
`RecoveryStore`) are not UI loops: playback advances through engine commands,
and autosave is a background thread. Still, a playback step must not run twice
because a menu/popup content closure was re-run, and an autosave request must
not be duplicated by a repeated `ui` pass. Undo is engine-owned
(`photocraft-engine` history); the rule is one user action โ one command โ one
history step, never a command in a sizing pass with no user event.
Add tests for: a forced popup sizing pass (`Popup::sizing_pass`) with unchanged
document, undo stack and control replies; a playback step whose dialog content
pass repeats with unchanged step/history counts; a forced second `ui` pass with
one command; and a background completion between passes applied once.
### 8.3 Hidden-window and control input
`ui.pointer` and `ui.key` must work while the window is occluded or minimized.
Screenshots must work while occluded; while *minimized* the window has no surface
that can be trusted, so the request fails with an actionable "the window is
minimized" error instead of saving a blank/stale surface. The minimized flag is
part of the geometry epoch, so a minimize/restore between issuance and collection
retries. Send `ViewportCommand::RequestPaintWhileHidden` when synthetic input
is in flight, `input_waiters` is non-empty, or a screenshot/control reply waits on
a pass. Keep the existing reply deadlines (60 s) and `Dispatch`/`AfterInput`
semantics. A hidden window must not turn a queued request into a `timeout: not
run` error.
Test the real host order, not a once-per-frame fiction:
- visible single- and multi-pass frames;
- repeated hidden `update_logic_only` ticks after a completed multi-pass frame;
- a hidden forced UI paint with queued synthetic input, then a visible pass;
- a background completion between passes, applied once;
- bare `run_logic` followed by `run_ui` proving stale input is not replayed.
Screenshots request their own paint; a passing hidden screenshot does not prove
`RequestPaintWhileHidden` for synthetic input. The mutation check for that is
section 13.6.
## 9. Panels, docking and screenshots
### 9.1 Panel state
0.37 derives a panel id from its parent scope: for the root Ui,
`ctx.viewport_id().root_ui_id().with(salt)`. `Id::with` takes an `AsIdSalt`;
`Id::with_salt` takes an `IdSalt`, so the v1 helper's `with_salt(salt)` did not
compile. Add one helper in `panels.rs`:
```rust
pub fn panel_state_id(ctx: &egui::Context, salt: impl egui::AsIdSalt) -> egui::Id {
ctx.viewport_id().root_ui_id().with(salt)
}
```
Add a compile-level unit test for the helper (and for the `direction.rs`
`AsIdSalt` bounds), then use it in `main.rs:1004`, `panels.rs:6604`,
`panels.rs:6934`, `workspace_ui.rs:594`, `panel_docking_tests.rs:569`, and in an
idempotent first-frame migration:
```rust
for name in ["dock", "title_bar", "options_bar", "status_bar", "toolbar", "rail", "shared-panel-dock"] {
let new_id = panel_state_id(ctx, name);
if PanelState::load(ctx, new_id).is_none() {
if let Some(old) = PanelState::load(ctx, egui::Id::unique(name)) {
ctx.data_mut(|d| d.insert_persisted(new_id, old));
}
}
}
```
This migration belongs to the **first compatible PR**: it is the same PR that
changes the constructors to `AsIdSalt`. The old `Id::unique(name)` key (same hash
as the old `Id::new(name)`) stays untouched, so 0.36 rollback still reads panel
widths; the new key is what 0.37 reads. `Ui::scope_id` is the renamed old
`Ui::id`; `Ui::unique_id` is unstable and must not be used for a persisted key.
Test old and new `ui.ron` fixtures, including a real 0.14.0 save with `dock`
width 410 and `shared-panel-dock` 290; then resize in 0.37, save and restart twice,
asserting the new width survives even though the old key remains. Also test the
helper/old-key equality and partially migrated state; existing new keys always win.
### 9.2 Window settings
Current `ui_state.rs` reads the old flat schema and is platform-dependent:
macOS checks `inner_position_pixels`, others `outer_position_pixels`
(`ui_state.rs:41-44`). 0.37's `WindowSettings` is:
- `normal_geometry: { outer_position_pixels, scale_factor, inner_size_points }`
(`inner_size_points` is a plain `Vec2`, not `Option<Vec2>`);
- `fullscreen`, `maximized`.
The old value does not deserialize into 0.37. Merely "understanding both schemas"
is insufficient because eframe reads the file before PhotoCraft runs. Add an
explicit pre-load rewrite in `ui_state::sanitize` (called from
`apps/photocraft/src/main.rs:664` before `run_native`):
1. Parse the outer map of key -> RON string; leave a non-RON file alone.
2. If `window` is the old flat schema, write a new `normal_geometry` value:
preserve valid `Some(inner_size_points)` using pattern matching (never `unwrap`);
when missing, use PhotoCraft's existing configured default 1440ร900 points (`native_options`, `main.rs:110`) and
record that fallback; reject non-finite/oversize values without rewriting,
`fullscreen`, `maximized`; set `scale_factor = 1.0` for the Windows position
path. Preserve `outer_position_pixels` only on Windows (physical pixels; 0.37
re-applies the physical position after creation). On macOS/Linux drop the old
position and let the window center: the old macOS `inner_position_pixels` is
not an outer position, and the old file has no scale factor for a logical
Linux restore. Never guess a scale factor or move the window after first paint.
3. Keep a one-time `ui.ron.pre-0.37` backup before rewriting; log and leave the
file untouched if the rewrite fails.
`has_saved_position` must look for `normal_geometry.outer_position_pixels` on
every OS and return true only when eframe actually restores that position (the
Windows path). It must stop looking for macOS `inner_position_pixels`.
Fixtures: old macOS inner position, old Windows/macOS outer position,
maximized and fullscreen, a `Some`/missing `inner_size_points`, and 0.36-schema
round-trip. Test that `(616,430)`/`1100x760` yields a 1100x760 window without a
startup failure, and that macOS/Linux center while preserving size/maximized/
fullscreen. Document the rollback loss: after 0.37 writes the nested schema,
0.36 ignores the window entry unless the backup is restored; add a
reverse-compatibility test using a 0.36-shaped settings struct.
### 9.3 Screenshot callback
Replace the UserData/Event path with a **bounded, cancelable per-request
completion slot**, not one unbounded `mpsc` channel per request. Use the shared
`craft-ui` capture-slot API at the approved CL-2F revision, a P0/P1 prerequisite.
There is no local-slot alternative for PhotoCraft. Keep tokens,
paths, settle delays, deadlines and reply schemas app-owned.
Design:
```text
PendingCapture record (app-owned)
token, path, reply, deadline, issued_at, viewport_id,
document/revision generation,
issued_geometry: { logical_rect, pixels_per_point, expected_surface_size, geometry_epoch },
slot: Arc<CaptureSlot> // bounded, one result, canceled flag
CaptureSlot
result: Mutex<Option<Arc<ColorImage>>>,
canceled: AtomicBool,
wake: egui::Context // live record only
callback = move |image| {
let Some(slot) = weak_slot.upgrade() else { return }; // late/canceled: drop image
if slot.store_if_pending(image) { slot.wake.request_repaint_of(viewport_id); } // after unlock
}
```
- The callback holds only `Weak<CaptureSlot>`; the live record holds the `Arc`.
The slot may hold a `Context` clone for wakeup, but the callback must not hold a
`Context`, `PhotocraftApp`, the pending record, or a channel sender. No
callback -> Context -> callback cycle.
- Admit at most 4 pending requests, at most 128 MiB of image bytes per request and
256 MiB in aggregate across reserved in-flight and completed images. Use checked
width ร height ร 4 arithmetic and reject before issuance with a clear size/queue
error. Test equality and one-over boundaries, arithmetic overflow and cancellation
releasing capacity. Transient GPU readback/encoder RSS is measured separately;
a late oversized result is dropped, not counted as proof of a pre-allocation bound.
- The callback supplies pixels only, not frame metadata. Record issuance geometry
from the target viewport's UI and a monotonically increasing geometry epoch (resize,
DPI/zoom/surface changes), plus document/revision identity. Revalidate before issuing
and before saving. Any intervening epoch change, even a change back to the original
size, rejects/retries within the deadline; never label the image with guessed geometry.
If the epoch is unchanged, derive x/y pixel scale from returned image dimensions
versus the recorded logical bounds, check aspect/rounding and apply region cropping
with those scales. E2 can fit the surface smaller. Do not use current DPI alone to
label an older image. A native resize/DPI race must show that stale metadata cannot
produce a saved image; callback-only tests assert the same rejection policy.
- On timeout/close/cancel, mark the slot canceled and drop the record; a late
callback upgrades `Weak` to `None`, drops the image, writes no file and sends
no reply. There is no "late file/reply" path.
- Keep PNG encoding and the existing `ColorImage` -> PNG path on the app/UI
thread in `control::save_screenshot`; never encode or write on the callback
thread. The callback thread is arbitrary: `egui-wgpu` completes it from a
`map_async` callback (`egui-wgpu/src/capture.rs:193`), not a guaranteed render
thread.
- While a capture is pending, `logic` keeps a hidden-paint request alive. A
screenshot command itself requests paint while hidden
(`ViewportCommand::Screenshot` docs), so a hidden screenshot test does **not**
prove synthetic-input `RequestPaintWhileHidden`; section 13.6 tests that
separately.
- Settle with `ctx.cumulative_frame_nr()` plus a monotonic animation deadline,
not `app.frame` (a logic-pass counter) and not a 3-pass count.
Tests: two concurrent captures with distinct tokens/paths and exactly one reply
each; callback exactly once; a callback after timeout/cancel writes no file and
sends no reply; close/shutdown drains to zero retained bytes; zero-sized surface
(`egui-wgpu` returns without calling the callback) times out cleanly with an
actionable error; unsupported capture format (also returns without callbacks)
times out; delayed GPU readback; out-of-order completion; reused viewport does
not bind an old capture to a new document; admission count and aggregate memory
caps (4 requests, 128 MiB/request, 256 MiB aggregate); a 4K resize/DPI race; `focus: true` raises first and correlates; `path:
null` base64; bad path/authority is an error, not a panic.
For distinct-image/out-of-order tests, intercept emitted screenshot callbacks and
complete them manually with different synthetic images in reversed order. Kittest's
normal renderer sends the same single rendered image to all callbacks and cannot prove
that correlation. Use an adapter-qualified native/GPU row for actual capture timing,
readback and viewport pixels; keep ordinary kittest for single-frame rendered checks.
### 9.4 Docking
`craft_ui::docking` remains the owner of the layout tree; PhotoCraft keeps
`UiState.docking` serialization. The 0.37 migration must not change
`Layout<String>`/`Location<String>` serde. Test:
- float a tab, move it, redock, split resize, close/reopen, save workspace,
reload `UiState`; layout equality and panel rects;
- `Escape` during a first drag restores the legacy workspace;
- `workspace_locked` rejects moves atomically;
- floating group strip is opaque in Studio themes;
- panel IDs stay unique after tabs reorder.
### 9.5 GPU resource behavior
PhotoCraft's canvas is a custom `egui_wgpu` paint callback
(`crates/ui-egui/src/gpu_canvas.rs`), not an egui image. 0.37 changes the
surface integration, not the callback contract, but these must be checked:
- E2/E3: a root or child window larger than `max_texture_dimension_2d` is
configured at a fitted size and drawn at a matching scale; a configure or
renderer error returns `WgpuError::ConfigureSurface`/`CreateRenderer` and
reaches the CPU-retry path, not a panic.
- `GpuCanvas::new` reads the device's `max_texture_dimension_2d` and tile size;
`use_adapter_limits` requests the adapter limits on web/desktop. Confirm the
egui surface limit and the canvas texture limit are independent.
- Texture deltas: assert `TexturesDelta::set/free` are applied once per frame, no
texture leaks after a dialog closes, and screenshot readback does not retain a
full-window buffer.
- Device loss: `gpu_status`/`DeviceHealth` still switches to the CPU canvas; no
egui-wgpu panic on a lost device; `ui.gpu.simulateLoss` test remains green.
- Intel/DX12 texel guard: `texel_guard::install` still sees the same adapter;
zeroed texels are not exposed after the 0.37 vertex/format changes.
- #8736: measure Windows `Renderer::new`/pipeline creation separately from the
first frame, with โฅ20 fresh processes. The reported 0.37 cost is around 57 ms vs
14 ms for renderer construction and 197 ms -> 258 ms first frame on an
Intel/DX12 system; this is an external report, not our measurement. Do not use
a 200 ms startup allowance to hide it and do not accept clamp-only shader
filtering changes for Repeat/MirroredRepeat.
### 9.6 Accessibility
Map all 114 `WidgetInfo` calls as in ยง4. Keep `check_accessibility` on and add
`Response::labelled_by`/`accessible_name` for fields without hints. Add a
screen-wide `unnamed_widgets().is_empty()` assertion for the main screen and
each dialog. After E17/E18, assert AccessKit root language and
`Response::accessible_language`.
## 10. Fonts, glyph coverage and text
### 10.1 Build and definitions
Required edits:
- `crates/ui-egui/Cargo.toml:73`: `epaint_default_fonts = { version = "0.37", features = ["monochrome_emoji_fonts"] }` (or the git-patched package with that feature).
- `crates/ui-egui/Cargo.toml:57`: dev `egui` features `["default_fonts", "monochrome_emoji_fonts"]` so the oracle test matches.
- `build.rs:37-45`: add `("egui-icons", epaint_default_fonts::EGUI_ICONS)`; keep the two emoji fonts behind the feature.
- `egui_fonts.rs:47-56`: add `egui-icons` at 0.90; preserve 0.37 family order:
- monospace: `Hack`, `Ubuntu-Light`, `egui-icons`, `NotoEmoji-Regular`, `emoji-icon-font`
- proportional: `Ubuntu-Light`, `egui-icons`, `NotoEmoji-Regular`, `emoji-icon-font`
- `egui_fonts.rs:79`: compare to `FontDefinitions::default()` with the same features.
Do not enable `default_fonts` in production; the web size gate depends on the
deflated fonts. No new font file is committed by this change: `egui-icons`,
NotoEmoji and emoji-icon-font come from `epaint_default_fonts`. Verify
`ATTRIBUTION.md` needs no new row; if a packaged font asset is added, add its
path/author/title/source/license row in the same first PR. The font feature,
equality test, glyph coverage and accessible-name fixes are all part of the first
green PR.
### 10.2 Lazy fallback
`cjk_fonts.rs` remains the app's fallback owner. Set
`NativeOptions::system_font_fallback = false` in the first cut. If
`system_fonts` is enabled later, remove or reconcile `cjk_fonts` in the same
change; two providers would produce non-deterministic font choices.
#8512 is still on PhotoCraft's path: `cjk_fonts` reads at most one system font per
frame even with `system_fonts` off. Measure font discovery and first-use
separately from renderer construction: cold/warm startup with `system_fonts`
off, with the app's lazy CJK fallback, and with an explicitly configured system
provider; record glyph coverage before/after. Do not assume disabling the
eframe feature removes system-font discovery cost.
`ctx.add_font` / `set_fonts` now apply immediately when no text has been laid out
in the pass. Re-check `defer_after_reset`, `fonts_ready`, and the
`UiFontSizePlugin::defer_after_install` one-frame assumptions; add a test where
fonts are installed from inside the first pass and where a language change
rebuilds fonts mid-run.
### 10.3 Glyph coverage
Add a test that loads every `tl!`/menu-catalog/catalog string and asserts
`Fonts::has_glyphs` for each character after `install_fonts` (with test fonts).
Include `โ โฒ โผ โถ โ ร โฆ โต โฎ`, `egui::special_emojis`, Arabic/Hebrew/Devanagari/
Thai samples, and the CJK samples already used by `cjk_fonts` tests. A missing
glyph must fail the test, not render tofu. This test and the minimal
`allow_missing_glyphs()` exceptions (only intentional tofu) ship in the first
green PR; do not let 481 harnesses inherit `MissingGlyphPolicy::Panic` without
the glyph decisions.
## 11. Input, IME, clipboard and RTL
- `raw_input_hook` stays; add `latin_layout_chars` handling only if E19 is in the
qualifying revision. Fresh input is interpreted only in a known UI phase; the
hook may move queued synthetic events into eframe's preserved input, but it
sets `synthetic_in_flight` so `logic` forces a hidden paint and no other code
treats the logic-only tick as a paint.
- `shortcuts::clipboard_keys` handles `Event::PasteImage` as the document paste
shortcut through the existing `import_os_clipboard`/session clipboard path, not
a second clipboard read; add a test for one import.
- Middle-click PRIMARY paste is new; verify text fields and the canvas do not
both act on it.
- E4 regular clipboard and PRIMARY are separate acceptance rows. PRIMARY's
default is the shared W15P winit-owned path on the existing connection/event
queue with per-seat lifecycle and distinct PRIMARY protocol objects; never bind
a second regular `wl_data_device`. The arboard PRIMARY fallback in the candidate
is not adopted as the default. If a fallback is retained, record exact
compositor/capability evidence and keep PRIMARY an unresolved gate.
- PRIMARY native matrix (wlroots, KWin, Mutter): keyboard-only focus, serial
freshness, owner/seat changes, empty/absent offers, self-paste, canceled/slow
transfers, password selection never offered, unchanged selection not reclaimed,
and no second regular data device. Test regular/image/drop separately.
- With E21, add `ImeEvent::DeleteSurroundingBytes` to the Type tool's event match
(`type_tool.rs:964-967`) and to any other exhaustive match; implement deletion
in bytes with char-boundary checks, one undo step. E21 acceptance is
macOS/Wayland only; Windows `ime_delete_surrounding` returns `None` in the
candidate, so a green Windows IME test is not E21 coverage.
- With E21b, extend the Type tool's custom `IMEOutput` producer
(`type_tool::draw_overlay`, `type_tool.rs:1255`) with the bounded logical
surrounding-text payload: committed model text, preedit excluded, UTF-8 byte
cursor/anchor, owning document+layer+viewport identity. Use
`current_text`/`layout` and `byte_of` (char-to-byte); do not pass visually
reordered display text. Resolve `TextEdit.document` (`active_doc_id` when
`None`) and `layer` into the payload identity. When removing the preedit char
range, a caret/anchor inside or at the end of it maps to the range start.
Clamp to the payload's 4000-byte limit at char boundaries; if the selection
cannot fit, emit explicit unavailable context.
Owner/context generation is present even for `Unavailable`; `Available` empty text
is a distinct case. Clear cached and compositor state with W27's committed
disable/enable transition on owner change/unavailable/focus loss/reset/no IME;
normal updates preserve composition. Clear old pending batches. In the current
focus epoch, a mismatched `done` serial still applies incoming edits once and defers
outgoing state until a match; old epochs never edit the new owner. Latest completed
UI-pass output, including None, is authoritative. Password fields never supply text. Built-in
`TextEdit` fields inherit the upstream producer. E21b's payload is not
`Copy`; audit every `IMEOutput` constructor/destructure in PhotoCraft (the
Type tool is the only custom one) and keep `Clone`/`Eq` semantics.
- With E5/E12/E13/E16, remove `bidi_text::visual`/`visual_ltr` use
(`layer_row_ui.rs:132/137`, `panels.rs:719`) and the `unicode-bidi` dependency,
or reduce `bidi_text` to non-reordering helpers. Double reordering is the
most likely user-visible RTL regression.
- With E9, audit `direction.rs` call sites before setting `Style::right_to_left`.
Do not mirror twice.
- #8763 selection loss: reproduce "select text, click a toolbar/context action"
in PhotoCraft's custom text fields/menu. The fork owns the selected fix with
pointer and keyboard regressions (fork P7c, prerequisite in P0). A local workaround
requires a demonstrated app-specific gap and removal condition; it is not an undecided
alternative to the shared fix.
- Test keyboard/focus: Tab order, Escape, Enter, focus after dialog close,
IME preedit/commit, dead keys, grapheme deletion, RTL caret affinity, and the
selection-action row.
## 12. Implementation stages
### P0 โ fork qualification (outside PhotoCraft)
Publish/qualify canonical egui and winit revisions, including P2b bounded transfers, P7 key pairing, E21b/P7b with W27 clear/lifecycle,
W15P and P7c selection/viewport regression fixes, and publish the craft-libs port
and CL-2F capture helper on current `main`. Acceptance: `PATCHES.md` complete;
each patch and W15P/E21b/P7c test; native Linux/Windows/macOS compile and targeted
tests; public immutable full SHAs; no path/branch patches. Stock 0.37 and aiongg
candidates remain research controls. No PhotoCraft PR can claim 0.37 until this
exists.
### P0b โ baseline harness and measurement (before production)
On `ff473881` / 0.36.2, add or extend the harnesses that will judge the migration,
without changing production behavior:
- the fixed 120-label plain-text tessellation scene and a benchmark row;
- Windows renderer-construction/first-frame timing around `Renderer::new`;
- the select-text-then-click-action regression (kittest and native);
- screenshot lifecycle probes (timeout, cancel, late callback, zero-size surface)
against the 0.36 API, adapted to the 0.37 slot contract later;
- panel/window migration fixtures containing a real 0.14.0 `ui.ron`;
- the paired baseline measurements and raw JSON/machine fingerprint.
This PR and its evidence land before P1. A harness invented after production
changes is not a before/after control. Record pre-existing baseline failures
separately; do not fabricate a baseline from a failing binary.
### P1 โ first green 0.37 PR (atomic compatibility)
This is the first change set that must pass its own tests, assets, glyph,
accessibility, feature and gate checks. It includes:
- root/app/ui `Cargo.toml`, `Cargo.lock`, root `[patch.crates-io]` for the whole
family and winit; features `wgpu`, `accesskit`, `wayland`, `x11`, `persistence`,
`clipboard`; `epaint_default_fonts` with `monochrome_emoji_fonts`; dev
`default_fonts` for the oracle;
- `crates/ui-egui/build.rs`, `egui_fonts.rs`, `cjk_fonts.rs` `FontData` uses,
`TextEdit::hint_text` helpers, `theme.rs` family order;
- accessibility names and minimal glyph-policy decisions required by kittest's
default `check_accessibility`/`MissingGlyphPolicy::Panic`;
- mechanical `WidgetType`/`Id::new`/`ui.id`/panel/direction migration, including
the `panel_state_id` helper and the first-frame panel migration in this same PR;
- `lib.rs` screenshot slot, `control.rs`, `shortcuts.rs` paste handling,
`menu_nav.rs`/`field_wheel.rs` scroll offsets, `main.rs` NativeOptions,
`clipping_indicator_tests.rs`;
- `ui_state.rs` window-settings rewrite and backup, with old/new fixtures;
- E21b Type-tool producer and compatible `IMEOutput` literal, E21 byte deletion,
owner/clear/final-pass semantics, with native evidence tracked explicitly;
- screenshot completion slot and its lifecycle tests; panel/window persistence
fixtures; no duplicate replies; no lost panel widths;
- any `ATTRIBUTION.md` change needed by a packaged asset (none expected), and the
corrected perf/snapshot/wasm gate commands.
Acceptance: `cargo fmt --all -- --check`, `cargo check --workspace --all-targets`,
`cargo clippy --workspace --all-targets -- -D warnings`, `cargo xtask layers`,
`cargo xtask wasm`, `cargo test -p photocraft-ui-egui --lib --tests`,
`cargo test -p photocraft --tests`, the build.rs font equality test, glyph
coverage test, explicit expected roles/names on the main screen and every opened dialog,
`unnamed_widgets` empty as a supplementary check, `Event::PasteImage` one-import regression,
and `packaging/web/package.sh`
(per-file limit). No deprecation warnings and no globally disabled kittest check.
### P1b โ visual fixture expansion (follow-up, not a green requirement)
Files: `snapshot.rs` scripts/fixtures, `panel_docking_tests.rs`,
`panels.rs` visual capture, kittest harness helpers.
Acceptance: baseline vs candidate images for 6 representative themes ร 3 scales,
exact geometry JSON; deliberate broken probe fails. This expands coverage; it does
not carry the names/glyph/feature fixes that P1 already needs to be green.
### P2 โ extended language and native IME qualification
Files: `bidi_text.rs` removal/reduction; `direction.rs`/E9 audit;
`i18n::sync_context` + `Frame::set_ui_language`; `layout_keys.rs`; AccessKit language
and extended native tests. The final fork pin and required E21/E21b model adapter
already land atomically in P1; P2 does not introduce a second dependency stage.
Acceptance: E5/E12/E13/E16/E17/E18/E19/E20/E21/E21b tests; RTL/grapheme/IME
matrix; E21b outgoing text after commit/deletion, preedit exclusion, byte
indices, long selection, field/window switch and multipass final output; native
Wayland predictive/Vietnamese trace or an explicit unresolved gate; no wasm size
regression.
### P3 โ web browser qualification
Files: `apps/photocraft-web` only if API changes; `WebShell` behavior tests.
Acceptance: `cargo xtask wasm`, `packaging/web/package.sh`, browser workflow
(open/type/paste/drop/screenshot); every shipped file โค24 MiB and gzipped total
plus raw wasm within a stated tolerance (+3%) of baseline.
### P4 โ performance and cleanup
Files: benchmark additions only if needed; devlog and parity/localization docs.
Acceptance: paired perf protocol below; cleanup of temporary shims; no production
change without a review.
Dependency DAG:
```text
P0 forks/craft-libs (E21b, W15P)
โโโ P0b baseline harness/measurement
โโโ P1 first green compatibility (names/glyph/features/panel/window)
โโโ P1b visual expansion
โโโ P2 extended language/native qualification โโ P3 web
โโโ P4 perf/cleanup
```
Rollback: revert P1 โ old lock and 0.36 family plus the preserved `ui.ron`
backup (panel keys remain readable; window geometry needs the backup); P1b is
additive tests/fixtures; P2 reverts to the P1 fork rev, restores `bidi_text.rs`
and removes the E21b adapters as one API set; P3 is web-only; P4 is
evidence/docs.
### 12.5 Required gates
Run through the server task wrapper with one resource task and a fresh job ID per
command; do not run these directly as a delegated worker:
```sh
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test -p photocraft-ui-egui --lib --tests
cargo test -p photocraft --tests
cargo test -p photocraft-web
cargo test -p photocraft-tablet
cargo test -p photocraft-automation
cargo xtask layers
cargo xtask wasm
cargo xtask parity
cargo xtask scorecard --check
cargo test -p photocraft-engine --test panic_hunt -- --ignored
```
Conditional gates: `cargo xtask test-corpus` if `io`, `psd`, `codecs`, `compose`,
`gpu`, `text` or `format` change (not expected in the UI-only stages);
`cargo xtask perf --quick` after each stage; full `cargo xtask perf` before the
performance sign-off, including `text_tessellation` and the Windows renderer row.
Windows/macOS native checks follow the corresponding server workflow and their own
VM/helper procedures.
Do not claim a gate passed from a compile-only run. A skipped optional test
(e.g. missing `CRAFT_FONTS_DIR`) is recorded as skipped, not passed. Baseline
evidence for P0b (raw samples, machine fingerprint, lock/source hashes) must exist
before any P1 production edit is measured.
## 13. Test plan: user-observable assertions
### 13.1 Stable fixtures
- Synthetic documents with fixed seeds: 1440ร900 UI; a 400ร300 document; a
20 MP layered document; a 36 MP photo; a 14000ร14000 document. Store fixture
generation seed and SHA256.
- Themes: `ProMedium`, `Studio`, `Classic`, `Adwaita`, `BreezeDark`,
`SoftLight` (representative; full 14-theme matrix nightly).
- Scale factors: 1.0, 1.5, 2.0; viewports 800ร480, 1440ร900, 3840ร2160.
- Persistence fixtures: a real baseline `ui.ron` saved by 0.14.0, plus a
hand-edited old-schema file.
### 13.2 Geometry and hit tests
- Panels are shown in the expected order (title/options/status/toolbar/dock,
then central); no overlap; each panel is nested in the root Ui, not a child;
central canvas rect positive; clipping contains the canvas; panel state IDs
unique; panel sizes restore from both old and new `ui.ron` keys.
- Dock: float/redock/split/resize/close/reopen; exact rects within 0.5 pt.
- Menus: long menu scrolls to last row; arrows and wheel; submenu hidden-row
behavior; taskbar-aware placement.
- Toolbars: options bar controls hit at 1x/1.5x/2x; no dead zones from new
atom padding.
- Canvas: brush stroke, pan, zoom, crop box, transform handles; document pixels
and overlays.
### 13.3 Pixel comparisons
Use `snapshot --out <png> --size <w>x<h> --scale <s> --system-theme <light|dark|none>
--script <json>` for each fixture. `--system-theme` only selects the OS
appearance; select a PhotoCraft theme through the control script, e.g.
`--script '[["ui.set",{"theme":"studio"}]]'`. Compare baseline and candidate with
the same wgpu adapter/driver/DPI. Proposed tolerance:
- 99.5% of pixels have per-channel delta โค 3;
- no pixel has delta > 12;
- geometry JSON (panel rects) equals within 0.5 pt;
- text antialiasing may differ only inside this tolerance; a larger diff is a
font/style decision, not noise.
Justify any wider tolerance with the exact font/renderer change. Do not update
goldens to make a test pass.
### 13.4 Accessibility and semantics
- `unnamed_widgets()` empty for main screen and every dialog.
- Roles: buttons, checkboxes, radio buttons, sliders, spin buttons, combos,
color wells, text inputs, disclosure triangles.
- Names/labels: icon-only buttons have accessible names; text fields have labels
or placeholders; selected state is reported.
- After E17/E18: AccessKit root language and `Response::accessible_language`.
- RTL: reading order and label language; no double-reversed Arabic.
### 13.5 Keyboard, focus, selection and IME
- Tab/Shift+Tab through every field; Enter/Escape; focus returns after dialogs.
- Selection regression (#8763/#8764): select text, click a toolbar/context action;
the intended selected range reaches the action, pointer and keyboard paths
agree, and undo restores one step. Run both kittest and a real native workflow.
- IME: Japanese/Korean/Chinese preedit and commit; macOS press-and-hold;
Wayland text-input-v3; Windows IME. `DeleteSurroundingBytes` deletion and one
undo step are E21 coverage on macOS/Wayland only; Windows IME is general
coverage, because the candidate returns `None` there.
- E21b: outgoing surrounding text immediately after delete+commit and
deletion-only batches; preedit excluded; reversed selection; supplementary/
combining/RTL logical order; cursor movement; >4000-byte line; two documents;
field/window switch; focus/reset/late serial; password/no-IME clears; multipass
final output; one undo. A native Wayland Vietnamese/predictive-IME protocol trace
is an external gate.
- Non-Latin layouts: Russian/Arabic/Hebrew shortcuts; German bracket keys;
Dvorak brackets; `โV` on Dvorak-QWERTY โ.
- Clipboard: text copy/paste/cut, image paste (`Event::PasteImage`), PRIMARY
middle-click, file-list paste, empty clipboard, occupied clipboard.
- PRIMARY: keyboard-only focus, serial freshness, owner/seat changes, empty or
absent offers, self-paste, canceled/slow transfer, password exclusion,
unchanged-selection reclaim policy. Run on wlroots, KWin and Mutter; record
capabilities. A green arboard-only run is not PRIMARY acceptance.
### 13.6 Broken-behavior probes (mutation checks)
- Temporarily remove one `widget_info` label in a test-only copy โ accessibility
test must fail.
- Temporarily pre-reorder an Arabic label with `bidi_text::visual` while E5 is
active โ RTL fixture must fail.
- Temporarily set the panel state key to the old ID โ persistence test must fail.
- Temporarily return a fixed screenshot token โ correlation test must fail.
- Temporarily disable the slot's late-callback drop โ a timeout/cancel probe must
fail (no file/reply).
- Temporarily disable `RequestPaintWhileHidden` for synthetic input โ hidden
control test must time out/fail. Do this separately from a hidden screenshot:
the screenshot command itself requests paint, so it cannot prove the synthetic
path.
- Temporarily replay a consumed screenshot/control event across a second pass โ
the duplicate-reply/command test must fail.
### 13.7 Headless `Context::run_ui` and `run_logic`
Every new logic/ui boundary must be exercised without eframe, with the real
callback order:
- `Context::run_ui` with the app's `ui` body, a fixed `RawInput`, and no GPU:
assert panel geometry, control replies and state transitions.
- Pass the existing `&mut Ui` to code that needs it. `Context::root_ui` **panics**
when the root Ui is already borrowed (0.37 `context.rs:1011-1024`); test that
documented panic as a negative test and test a successful `run_pass`/`root_ui`
call separately. Never introduce a recursive `root_ui` in production.
- A hidden-tick driver must call `App::raw_input_hook` in eframe's order
(`prepare_raw_input`) before `App::logic`, not bare `run_logic`, and then run a
later `run_ui`: assert synthetic/control input is preserved and consumed once,
and that stale events/time are not replayed. Use an eframe/kittest hidden-window
driver or a direct `update_logic_only` equivalent; do not invent a native
once-per-frame host.
- A headless pass must not be treated as proof of native focus, IME, clipboard
ownership or file pickers; those need the native rows below.
### 13.8 Native and browser workflows
- Linux X11 and Wayland (wlroots/KWin and GNOME/Mutter), Windows 11, macOS.
- Real focus/IME/file pickers cannot be proven by kittest; record named hardware
rows and screenshots. macOS evidence is an unresolved gate until real hardware
rows exist; do not mark the migration complete on Linux-only evidence.
- Browser: WebGPU and WebGL2; open a file, type in a field, paste, drop a file,
take a screenshot, resize the page; verify no JS errors in the console.
- Extra document windows: open two, draw in each, close one during a stroke,
screenshot the root while a child is open, and confirm control input still
reaches the root; immediate-viewport raw input must not be duplicated.
- #8748 is closed/unmerged and PhotoCraft has no deferred viewports: record that
explicit non-applicability, then test hidden/occluded root + immediate child
open/update/close (including a child left open when the root is hidden).
## 14. Performance protocol
### 14.1 Baseline
Before P1 (the first production change), run the baseline on the **same** machine
that will run the candidate. The P0b harness is added on 0.36.2 first; stock 0.37
and the fork are controls, not replacement baselines.
- record `uname -a`, CPU model/cores, RAM, GPU adapter/vendor/driver, wgpu
backend, OS build, Rust version, `Cargo.lock` SHA256, exact command lines and
feature set;
- renderer: Vulkan (or Metal/DX12 as applicable), plus a separate `--cpu`
software-renderer run;
- DPI: 1.0 and 2.0; viewport 1440ร900, plus 3840ร2160 for large-window tests;
- profile: `--release`, `--locked`, no `CRAFT_FONTS_DIR` unless the row is
font-specific; record whether craft-fonts is embedded.
Run each row with the shared sample protocol; keep raw JSON. The repository's
existing 15-sample/5-sample bench counts and `interactive_bench --reps 5` are
smoke settings, not acceptance evidence. For migration evidence use at least:
- 10 warmups + 30 timed iterations for steady operations;
- 20 fresh processes for startup and renderer/font-discovery rows;
- at least 1,000 rendered frames for frame distributions; report p50/p95/p99 and
only claim a p99 from those frames (never from 20/30/50 samples);
- 1 warmup + 5 samples for 196 MP / 2 GB rows is an exploratory smaller run, not
tail acceptance; label it as such and do not report its p95/p99 as acceptance;
- interleave baseline/candidate (A/B/A/B) to control thermal drift;
- reject a run when load average is high or another build shares the machine;
rerun rather than accepting a noisy result. Use a paired confidence interval
where suitable and record peak RSS, allocations/texture uploads and idle
repaint/CPU separately.
### 14.2 Metrics and thresholds
Thresholds are investigation triggers, not permissions to accept a regression.
A repeatable **>5% median** or **>10% p95** change is investigated; existing
stricter repository budgets win. Do not expand tolerance after seeing a failure;
an exception needs a documented tradeoff and owner approval before acceptance.
For sub-millisecond rows require the relative increase to exceed 0.05 ms or
corroborate it with stable instruction/allocation counts.
| Metric | Baseline source | Gate |
|---|---|---|
| UI pass p50 | new `frame_bench` or `perf` `ui_ms` | investigate >5%; no looser absolute allowance |
| UI pass p95 | same | investigate >10% |
| UI pass p99 | same, only from โฅ1,000 rendered frames | report; investigate >10% when the sample supports it |
| Operation p50 / p95 | `perf_scenarios` rows / `interactive_bench` | investigate >5% / >10% |
| Peak RSS | `RssSampler` / `/usr/bin/time -l` | investigate >5%; report peak, not only completion |
| GPU bytes held | `perf_scenarios` `gpu_bytes` | investigate >5% |
| Texture uploads / vertices / UI allocations | new test-only counters from `FullOutput.textures_delta`, tessellation and a scoped allocator around the app pass | investigate >10% |
| Idle repaint/CPU | 60 s with no input: frame count, process CPU %, GPU util | any continuous repaint, new busy-loop or audio underrun is a failure |
| Startup to first frame | app log timestamps / `gpu_startup` | investigate >5% median or >10% p95; no +200 ms allowance |
| Renderer construction (#8736) | `Renderer::new`/pipeline timestamps, 20 fresh processes | investigate >5% median or >10% p95; separate from first frame |
| Font discovery (#8512) | cold/warm process trace with system fonts off/on | investigate >5% / >10%; report glyph coverage before/after |
| Text tessellation (#8731) | fixed 120-label `text_tessellation` row | investigate >5% median or >10% p95; compare 0.36, stock 0.37, fork |
| Selection action (#8763) | select-text-then-click-action regression | no lost range; pointer/keyboard agree; one undo step |
| Wasm size | `packaging/web/package.sh` output | every shipped file โค24 MiB; gzipped total and raw wasm โค +3% vs baseline |
| Click-to-pixel latency | `stroke_trace` | investigate >5% median or >10% p95 |
Do not report compile duration as UI performance. Do not compare the committed
macOS `perf/baseline.json` with a Linux/Windows run. Do not auto-accept a changed
pixel golden or a changed budget; profile and either fix or document an explicit
accepted regression with owner approval.
### 14.3 Commands
All commands run through the server task wrapper, one resource task and a fresh
job ID per intentional execution:
```sh
python3 /home/codex/work/maintenance/task.py run \
--job-id <task>-perf-baseline-01 --kind build --task <task> \
--source /home/codex/work/CraftApps/egui037-migration-20261022/photocraft \
--evidence /home/codex/work/ssd2/task-evidence/<task> \
-- bash -c 'cargo xtask perf --bench perf_scenarios'
```
`xtask perf` appends its own `--json <target>/perf/<bench>.json`; it rejects a
user-supplied `--json` as an unknown option. After the run, copy
`$CARGO_TARGET_DIR/perf/perf_scenarios.json` and `summary.md` into evidence. The
bench's own `--json` is only for invoking the example directly.
Equivalent runs for `interactive_bench`, `fx_bench`, `bevel_bench`,
`camera_raw_bench`, `type_bench`, `large_image_bench`, `large_file_bench`, the new
`text_tessellation` row, plus `cargo xtask perf --quick` as a smoke check. Copy
raw JSON, `summary.md`, logs, machine fingerprint, command line, source SHA and
lock SHA into evidence. Startup/renderer/font rows run 20 fresh processes each;
frame rows use โฅ1,000 rendered frames. Do not claim a p99 from an exploratory
small run.
## 15. Decisions and remaining gates
Resolved in revision 2 (they are requirements, not open choices):
- **E4 PRIMARY:** the shared W15P winit-owned path on the existing
connection/event queue is the default; arboard is a measured fallback and an
unresolved gate, never an adopted default.
- **WindowSettings:** preserve `inner_size_points`, `fullscreen` and `maximized`
on every OS; preserve `outer_position_pixels` on Windows only; center on
macOS/Linux; rewrite before eframe loads and keep a backup. Document the
rollback loss.
- **PanelState:** migrate in the first compatible PR; a one-time width reset is
not an accepted substitute.
- **craft-libs:** port only the `8614e4a`/`1764bca` hunks onto current `main`;
keep `craft-print`/`craft-docpath` pins and unrelated vendors. Do not merge
`b68de8c`/`ec8840a` trees.
- **PasteImage:** treat as document paste through the existing import path.
- **E21 and E21b:** implement both for the custom Type tool; E21 is
macOS/Wayland-only, E21b adds the bounded logical surrounding-text producer.
- **E21b:** new prerequisite; `None` placeholders are not acceptance.
- **Screenshot:** bounded, cancelable weak-slot completion with capture-time
geometry, no unbounded channel and no late file/reply.
- **Performance:** shared 10/30/20/1,000 sample minimums and >5% median /
>10% p95 investigation; no looser absolute allowance.
Remaining open gates:
1. **Fork publication/ownership.** Canonical `storytold/egui` and
`storytold/winit` full SHAs do not yet exist as published immutable commits
containing E21b and W15P. Choosing aiongg branches as canonical would make an
individual fork a required public dependency; choosing storytold requires
pushing there. No approval is granted in this plan.
2. **E11 inclusion.** No PhotoCraft consumer enables `epaint/multithreading`.
Decide whether the shared fork carries E11 for VectorCraft or whether
PhotoCraft's qualifying revision excludes it.
3. **E9/`direction.rs` overlap.** Keep explicit shell mirroring and leave
`Style::right_to_left` off, or switch to E9 and remove overlapping manual
mirroring. Needs RTL fixtures first.
4. **System fonts / color emoji.** Keep bundled monochrome emoji and no
`system_fonts`, or enable `system_fonts` (fontique + color fonts) and retire
the custom CJK fallback. The latter needs a separate design and size/perf
review; #8512 is measured either way.
5. **Final winit patch list.** W12/W14/W16 are not PhotoCraft-required.
Confirm whether the shared published revision includes them; W15P, W26 and
W27 are required regardless.
6. **External evidence gates.** Real macOS IME/focus, Windows native GUI and
renderer timing, Wayland compositor/IME/PRIMARY, and browser runtime evidence
remain gates. Cross-compilation, kittest and software-renderer VM results do
not satisfy them.
## 16. Historical planning limitations (superseded by current status above)
- Planning only: no build, test, clippy, wasm, GUI, IME, screenshot or performance
command was run. The historical audit log in the evidence directory shows the
same first font build failure, but it is not fresh validation.
- Revision 2 addresses the v1 findings by source inspection, but it has not been
re-reviewed. A fresh independent review of this exact document is required
before any publication approval.
- The E/W patch audit is based on the candidate commits and `PATCHES.md`;
every patch, including E21b and W15P, still needs a line-by-line review against
its upstream PR/proposal and a test audit before publication.
- E21b has no existing implementation. Its egui payload, TextEdit producer,
egui-winit Wayland adapter, PhotoCraft Type-tool adapter and native IME trace
are all future work; no claim of existing surrounding-text support remains.
- Windows, macOS, Wayland and browser behavior are unverified. Headless kittest
is not proof of native focus, IME, file pickers or compositor behavior.
- No final fork revision or `Cargo.lock` hash exists yet; the target lock cannot
be produced until P0 is published with the reviewed full SHAs.
- The performance baseline machine and exact adapter/driver are not chosen; the
thresholds above are pre-registered, not measured. P0b must add the before
harness on 0.36.2 before P1.
- No commit, push, PR, comment or external message was made. Publication still
requires explicit human approval for every push/new PR, with the exact
publication and validation shown first.
## Local implementation update โ 2026-10-23
The user clarified that reviewed plans remain local and implementation proceeds before publication. The earlier requirement to publish/land this plan first is superseded; pushes and PR publication still require explicit approval.
Canonical `storytold/photocraft` `main` now resolves to `e6d6fb45a40250f518d2e824236a8fdcaa4472c8`. The owned checkout was fast-forwarded to this revision. Earlier baseline SHAs and line anchors above are retained as historical review evidence; use this new revision and its exact lockfile for current-main integration and paired measurements. The original refs remain reachable.
Use release0.15.0 and its lockfile as integration baseline; preserve same-origin served fonts and encoded-path rejection, cumulative glyph raster budgets, Select and Mask tile-based edits/undo and new catalog keys. Retain0.14 upgrade fixtures too.
The complete static delta review and exact old/new object identities are retained in the task evidence: `canonical-diffs-refresh-20261023.json` and `overnight-consumer-review-20261023.md`. This amendment claims no new build, native GUI or performance acceptance.
## Local implementation progress โ first compatibility/lifecycle stage (2026-10-23)
Local, uncommitted work only. No build, test, format, clippy, GUI or performance command
was run for this stage; compile and runtime results are pending the parent's managed
`task.py` jobs. Nothing is published.
Repair round after `egui037-photocraft-postport-review-20261023-root-v1.md`: the test-target
compile findings were fixed (`fonts_mut` for `has_glyphs` checks, the two missing
`MouseWheelSource` fields, the missing-size window test), together with the runtime findings:
geometry-change budget revalidation, monotonic epoch comparison across resize-and-back, a
bounded pre-geometry admission queue, exact-once synthetic reinjection, withdrawal of a
cancelled synthetic batch from preserved input, a monotonic active-document generation bound to
captures and synthetic input, a minimized-window refusal, bounded PNG encode copies, the panel
rollback stamp and web-shell `raw_input_hook` forwarding. The findings that remain open are
listed at the end of this section.
Implemented in this checkout (release 0.15.0 base `e6d6fb45`):
- **Dependency family**: workspace `egui`/`eframe`/`egui_kittest` 0.37, `egui_extras` 0.37,
`epaint_default_fonts` 0.37 with `monochrome_emoji_fonts`, dev `egui` with `default_fonts`
+ `monochrome_emoji_fonts`, `eframe/clipboard` on the app, UI library and web shell, and a
direct `web-time` dependency. The working tree's `Cargo.lock` is modified by the parent's
local path patches for `egui-implementation`, `winit-implementation` and
`craft-libs-implementation`; it is not a reviewable/publishable lock until the family and
winit are pinned to published revisions and the lock is regenerated from them. The pinned
`craft-ui` revision currently lacks `craft_ui::capture` (post-port review F1).
- **Fonts**: `build.rs` deflates `egui-icons` and the feature-gated emoji faces;
`egui_fonts.rs` reproduces 0.37's faces, scale tweaks and family order; `cjk_fonts.rs` uses
`FontData::bytes()`; a glyph test covers `egui::special_emojis` in both families;
`NativeOptions::system_font_fallback = false` keeps PhotoCraft's own CJK/craft-fonts
fallback the only provider.
- **Mechanical 0.37 API port**: `WidgetType` โ `egui::Role` (with the renamed variants),
`Id::new` โ `Id::unique` (hash-preserving), `ui.id()` โ `ui.scope_id()`,
`Panel`/`direction` take `AsIdSalt`, `TextEdit::hint_text` takes owned text, `ScrollArea`
offsets use `clamped_offset()` and a request applied through `vertical_scroll_offset`,
`Event::PasteImage` maps to the document paste shortcut, and every `Event::MouseWheel`
constructor carries `MouseWheelSource::Unknown`.
- **Panel persistence**: `panels::panel_state_id(ctx, salt)` is the 0.37 parent-scoped key;
`panels::migrate_panel_state` copies the old `Id::unique(name)` `PanelState` entries, leaves
the old keys intact for a 0.36 rollback, and stamps both keys.
`panels::remember_panel_state` records the 0.37 size each pass. On a later start an old key
that changed while the new one did not (a 0.36 rollback resize) wins; a 0.37 resize is kept.
If both changed the order is unknown and the new key is kept, so a 0.37 resize after a 0.36
rollback resize can still be lost; that ambiguity is documented and tested. Called from the
first UI pass; tests cover key identity, the copy, the old-key retention, a 0.37 resize after
migration and a 0.36 rollback resize (`panels.rs`), and panel widths across two restarts
(`apps/photocraft/src/main.rs`).
- **Window settings**: `ui_state::sanitize` now rewrites a 0.36 flat `window` entry to
0.37's `normal_geometry` before eframe reads it, after a one-time `ui.ron.pre-0.37` backup.
It preserves a valid size (defaulting to 1440ร900 when absent), `fullscreen` and
`maximized`, preserves the old physical outer position only on Windows, and centres on
macOS/Linux. Corrupt sizes are left untouched. `has_saved_position` reads only the nested
outer position. Tests cover old macOS/Windows fixtures, missing size, corrupt values, the
backup, the one-way reverse-compatibility loss, and maximized/fullscreen.
- **Screenshot lifecycle** (`crates/ui-egui/src/screenshot.rs`): bounded, cancelable capture
requests using the shared `craft_ui::capture::CaptureSlot` with a weak callback. Admission
enforces 4 outstanding requests, 128 MiB per image and 256 MiB aggregate over issued,
completed-undrained, unissued and geometry-waiting requests, rejects before issuance with
checked arithmetic, and is drained before admission so a finished request releases its
budget. A request that
arrives before the first UI pass has recorded the geometry waits in a count/deadline-bounded
queue and is admitted on the next logic tick. When the geometry is finalized at issuance or
after a retry, the per-image and aggregate budgets are recomputed and the reservation updated
(or the request fails before any capture). The request identity is the document and its
monotonic activation generation (revision recorded, not an invalidation: a switch away and
back fails the capture). Geometry (size, scale, zoom, texture side, minimized) has a monotonic
epoch updated only in a real UI pass; an epoch advance between issuance and collection retries
even when the values change back, and the issuing pass must show the same activation at its
start and end. Settling counts UI passes, issuance happens only from `App::ui` after fonts are
ready, and deadlines use `web_time::Instant` (monotonic on native and wasm). Accepted images
are the issued size within a pixel or the renderer's exact texture-side fit, never an
arbitrarily smaller same-aspect surface. A late callback after timeout/cancel is inert;
encoding/writing happens on the UI thread in `control::save_screenshot_rgba`, never in the
callback. The retained image is dropped before the encoder allocates its RGBA copy, and that
copy is bounded by the same per-image limit (`finish_captures` refuses an oversized image
rather than allocating).
Same-size surface recreation with no size/scale/zoom change is not observable and remains an
explicit limitation.
- **Lifecycle**: hidden `run_logic` ticks request `RequestPaintWhileHidden` for unissued
captures and queued synthetic input; one synthetic batch is in flight at a time, and a pass
that returns early re-injects the same batch exactly once (a second hidden tick does not
append it again). A document/focus change observed in `raw_input_hook` withdraws the batch
(including events eframe already preserved) and fails the waiting replies, so cancelled input
is never applied. A change made inside `logic` after the hook cannot withdraw events the pass
has consumed, so the pass delivers them and keeps `automation_input` set instead of claiming
cancellation while the input lands. Control replies wait for a pass that actually delivered
the batch. The web shell now forwards `raw_input_hook` to the app after its touch-twin
filter, so the clipboard `PasteImage` mapping, legacy pinch, pen-hold and titlebar
normalization run in the browser too; the browser has no TCP control server, so the
synthetic queue stays empty there and synthetic-input rows remain native-only evidence.
`gpu_canvas::now_ms` is now monotonic on wasm (it was a constant 0), so autosave,
preference retry backoff, frame caps and stroke traces measure real durations; preference
retry and link-watch timing no longer read stale `run_logic` input time.
### Integration-test selector repair โ 2026-10-24 (historical pre-validation record)
The parent's managed `--lib --tests` run (`egui037-photocraft-candidate-20261024-upstream-tests-18`)
passed 3847 UI unit tests and 116 integration tests, with 16 integration failures. All 16 were
kittest/AccessKit selector assumptions, not production behaviour changes:
- kittest 0.5 reads a `Role::Label` node's text from its AccessKit `value`, so a form caption and
a control that carries the same accessible name both match `get_by_label`. Batch/Image
Processor (`Format`, `Input`, `Quality`, `Starting serial`), custom print paper
(`Paper Width`, `Paper Height`, `Top`, `Left`) and Export As (`Scale`, `Resample`) now select
the actual `TextInput`/`SpinButton`/`ComboBox` by role and name; existing coordinate searches
and ambiguous name-only lookups were removed. `custom_print_paper::shown` uses `query_all`
because a caption and its field are both valid visible matches.
- egui 0.37 exposes a `CollapsingHeader` as `Role::DisclosureTriangle`, not `Role::Button`.
Camera Raw histogram/settings and localization tests now click and assert that role; the
section IDs and translated labels are unchanged.
- A Camera Raw slider row exposes both its `Slider` and its numeric `SpinButton` under the same
name. `camera_raw_scope::alt_drag_slider` now addresses the `Slider` track directly instead
of the caption, preserving the real Alt-drag and overlay/diagnostic assertions.
These edits keep the real clicks, drags, exported bytes, history/revision and engine-field
assertions; they add no sleeps, retries or relaxed checks. They do not claim a passing run: the
parent must re-run the managed full tests and lint. The broader 481-harness accessibility
naming/glyph sweep and visual fixture regeneration remain open.
The `ui.ron` fixtures under `apps/photocraft/tests/fixtures/` are schema probes reconstructed
from the documented layouts, not recorded machine saves (see that directory's README); they
prove the migration rules, not eframe/egui deserialization of a real save.
The compiler/API port, IME producer/adapter, byte deletion, selection-action adoption, shared
capture dependency and canonical lockfile are now implemented and covered by the current host
qualification above. The later fixture corrections preserve real native viewport geometry,
transform completion order, retired document editors and foreign viewport identity; they do
not bypass the reset acknowledgement path.
Remaining acceptance work: a real 0.36 docking-layout sample, the broader accessibility/glyph
sweep, visual fixture regeneration, packaged WASM size, native/browser/IME/PRIMARY workflows
and paired app performance. The app-owned docking JSON still falls back to the legacy layout
if it cannot deserialize; DockArea's transient drag/focus state is not persisted.
No file is open. Choose one in the tree, or press Ctrl+O (โO on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.