gridcraft/docs/egui-037-local-followups.md

egui 0.37 local port — follow-ups and gates

Status: local implementation on GridCraft b8771d51fb4da60bd48c13cf313d6d6014dc5e66 with canonical immutable dependency pins. Final managed full CI egui037-gridcraft-candidate-20261024-full-ci-queue-07 succeeded at 2026-10-24 05:21 UTC after both accessibility repairs: all ten stages passed, with 2,249 tests passed, none failed and one existing release timing experiment ignored. The representative explicit accessibility/capture checks passed. The required local precommit CI gate is complete for the formatted runtime source; this final refresh changes only the two migration documents. Native/platform/performance acceptance remains separate. No code push or PR publication is authorized; each requires fresh human approval of contents and validation.

Current integration inputs

• Root Cargo patches select the egui family at 173cc7375d35dc5fbc5b5d0994fdf787f547c5d1 and winit at ae48c756a3b81125eb796c0cc6dccf60990d1181. Selected egui packages are 0.37.0; there is no machine-local path override or second egui 0.36 source.
• craft-ui and craft-print both pin c488caa9fbc2fb1a86e4674887e9b80b598ebbfa. The shared capture slot is consumed through that revision. Canonical Cargo.lock SHA256 is 98209e84412b8ce08bf290ab706c20909389ca6d1e6668aca929f717ad55ea2f.
• CI, release and FreeBSD select craft-fonts b076417b5880bd4154bd22f00695b1d28c6bea83. Local validation uses command-scoped private Git mirrors for unpublished immutable inputs; clean remote fetching after approved publication remains a separate gate.
• The shared capture contract fits GridCraft's requirements without changes: one slot per request, take() at most once, cancel()/drop makes late callbacks inert, a per-image byte bound, and a viewport waker that runs after the slot lock is released. GridCraft adds only its admission budget, request records, geometry epoch and output routing around it.
• The CaptureSlot callback holds only a weak reference and never encodes, writes a file or sends a control reply; GridCraft drains the slot from logic and writes outside the slot.

Capture lifecycle repair (2026-10-23)

The previous managed run of this checkout (egui037-gridcraft-candidate-20261023-tests-01) finished with 154 passed and 8 failed: five screenshot/lifecycle tests dropped an unapplied TexturesDelta, two more lifecycle tests failed on the same atlas delta, and formula_bar::spill_tests::formula_bar_click_and_theme_presentation reported the Name Box TextInput without an accessible name. Those failures are historical; final full CI07 passed the repaired lifecycle and accessibility tests.

The local source now addresses the fresh review's capture findings:

• A completion that arrives after the request deadline is refused with the timeout error before any encoding or file write; timeouts, geometry mismatches, oversize images and removed requests all release their reservation. Every screenshot reply carries its request token.
• Screenshot deadlines and AutoSave pacing use a monotonic clock (std::time::Instant natively, performance.now() on wasm). now_ms() stays the wall clock for user-visible timestamps such as Backstage's "last changed".
• CaptureGeometry::current reads ViewportInfo (refreshed by run_logic) for the viewport inner_rect and native_pixels_per_point * zoom, falling back to the last screen rect; a hidden resize is therefore seen without a UI pass. Issuance and drain update the geometry and its epoch through one helper, and the slot is created at issuance with a per-image bound equal to the aggregate reservation (which includes the accepted one-pixel rounding).
• A request admitted while the window has no size (minimized or not laid out) reserves UNKNOWN_CAPTURE_BYTES and waits for a real size; it times out with a size-specific message. Drain runs before admission, and settling counts one non-discarded egui pass per request.
• The geometry identity intentionally includes zoom, visible and occluded even when the expected physical size is unchanged. A capture is bound to one layout generation; the two-retry budget followed by an explicit error is the accepted bounded failure, not a reason to compare only the expected size.
• A synthetic step consumed by a font-gated ui early return is offered again on the next pass (the hook tracks the cumulative_pass_nr at injection), and font-set changes wait while an input step is pending. Re-offering the step is safe: the early-returning pass handled no input, so egui's state changes from those events (keys down, pointer down) have not applied a step.
• The Name Box and the formula-bar/in-cell editors carry explicit accessible names, so the strict kittest accessibility check passes without disabling it or the missing-glyph policy.

Shared eframe web follow-up: RequestPaintWhileHidden

Native egui-winit handles ActionRequested::wants_paint() for RequestPaintWhileHidden and paints the hidden viewport. The pinned eframe web runner does not: a hidden tab runs only run_logic, and handle_viewport_commands handles Screenshot/SetTheme while every other command — including RequestPaintWhileHidden — falls into its unhandled-command log. A queued ui.screenshot or a queued ui.key/ui.text step in a hidden browser tab therefore cannot reach its ui pass until the tab is visible; the screenshot request reports its timeout instead. The fix belongs in the shared eframe web runner (paint a hidden tab on request, with the same queued-work trigger GridCraft sends from logic on native), not in a GridCraft-local channel. GridCraft therefore sends RequestPaintWhileHidden only off wasm (a visible web tab still gets request_repaint). The control protocol documents this web limitation instead of claiming hidden web screenshots work.

E21b — application qualification remains open

The final canonical egui fork includes IMEOutput::surrounding_text, owner/context generation and the Wayland outgoing adapter; the earlier statement that no shared producer/adapter exists is superseded. GridCraft must qualify its actual formula-bar, in-cell and text-box editing paths, including available-empty versus unavailable, stale epoch/serial deletion and commit, deletion-only batches, composition ownership and two-surface isolation. Full CI07 is not a native IME or complete E21b/W27 acceptance result. No application-local API stub is introduced.

Review repair (2026-10-24)

• RequestPaintWhileHidden is sent only for a queued/settling request that has a capturable size; an issued capture relies on the Screenshot command's wants_paint, and a minimized request no longer forces full hidden frames while it waits.
• A slot-level per-image refusal (an image larger than the reservation) now spends the same bounded retry as a smaller image, instead of failing only when the window grew.
• The shared deterministic harness, the Text Box accessible-name translations, the explicit PasteImage/MiddleClickPaste no-op choice, the lifecycle once-per-host-frame tests (autosave, title, print poll, discard after issuance) and wheel unit/source/phase coverage are in the working tree. Final full CI07 exercised these repairs and the explicit accessibility assertions below successfully.

Remaining acceptance gates

• Required local CI is complete: full CI07 passed i18n-report, fmt, strict workspace all-target clippy, workspace tests, doctest, assets (34 attributed files), layers, WASM, parity and keytips. The existing timing-sensitive recalc_with_range_formulas_scales_linearly test remains ignored by the normal CI command; it is not a performance result. No additional CI execution is claimed for this documentation-only refresh.
• Strict egui_kittest harness qualification completed for the selected end states: tests/common/mod.rs now installs theme::pinned_font_definitions() (bundled faces plus the pinned craft-fonts input, no host system scan), SheetApp::use_prepared_fonts() keeps that set through the first logic pass, and MissingGlyphPolicy::Panic stays on. Since run_steps does not invoke kittest's accessibility checker, selected ribbon, locale, pane/menu, dialog, active-editor, backstage, text-box and capture/repaint end states now call check_accessibility() explicitly; these assertions passed in CI07, without claiming coverage of every UI state. CRAFT_FONTS_DIR (and CRAFT_FONTS_REQUIRED=1 for acceptance) is the CI contract; without it the deterministic bundled set is used and the all-catalog language test records the Ja/Ko/Zh gap.
• End-to-end hidden/occluded ui.screenshot with a capturable current size and a minimized request that waits for restore (or times out), through a real wgpu/kittest or native window; the per-image/aggregate budget stress cases, resize-back/DPI/zoom epoch retries, and native clipboard/PRIMARY/IME evidence. No native hidden/minimize/restore run has been performed for this source.
• Native Linux, Windows clone, browser and macOS workflows; performance, text-tessellation, Windows renderer-construction and print measurements against the recorded baseline.
• Accessibility roles/names beyond the mechanical Role port (G3) and native screen-reader smoke tests.

Font provisioning (2026-10-23, font-coverage integration)

The font gap is addressed in the font set itself. Test harnesses keep MissingGlyphPolicy::Panic and the enabled accessibility-check policy; the representative explicit checks above are needed to execute that policy on run_steps fixtures. No test calls allow_missing_glyphs() or disables the accessibility check, and production still renders Tofu for a character no face has.

• gridcraft-ui-egui enables egui/default_fonts and egui/monochrome_emoji_fonts. egui 0.37 moved Noto Emoji and emoji-icon-font behind the monochrome feature, and with default_fonts alone no installed face has ✕ or 📋 (Hack, which the theme adds as a fallback, has the arrows and triangles but neither of those).
• theme::font_definitions_with appends egui's bundled Hack face (arrows, triangles, ↳) behind the UI/cell and emoji faces of every family, and appends the optional craft-fonts faces at the very end. The order is: app/bundled faces, Hack/emoji, system script fallbacks, permitted craft faces last. A craft face never displaces a system face that already has the glyph.
• crates/ui-egui/build.rs embeds the faces named by CRAFT_FONTS_DIR through crates/ui-egui/src/craft_fonts_policy.rs, the single policy shared by the build script and the tests. Nothing reads a fixture path from Cargo configuration: the checked .cargo/config.toml holds only the xtask alias, so every local and managed run sets the variable explicitly. With it unset the generated table is empty and the app builds, tests and runs; a script that no installed system face and no bundled face covers stays the platform gap it was before (Tofu in production, and the strict kittest harness still panics on it by design).
• Required faces, matched by exact family and style and by their exact manifest script tags: BIZ UDPGothic Regular and Bold (Jpan,Latn), NanumGothic Regular (Hang,Kore), Noto Sans Symbols Regular (Zsym) and Noto Sans Symbols 2 Regular (Zsym). NanumGothic has no space, and Noto Sans Symbols is not Noto Sans Symbols 2.
• CRAFT_FONTS_REQUIRED=1 turns a missing CRAFT_FONTS_DIR, a missing fonts/manifest.txt, a malformed manifest row, a missing font file, an unexpected style of a required family or any missing required face into a build error.
• Barred families never enter the font set, although the shared repository keeps them for other consumers: Adobe*, Source Han*, Source Sans*, Source Serif*, Noto Sans CJK* and Noto Serif CJK*. There is deliberately no broad Noto Sans prefix, because it would also reject the permitted Noto Sans Symbols faces.
• Web (wasm32) embeds only the explicit allowlist: BIZ UDPGothic Regular and Bold, NanumGothic Regular, Noto Sans Symbols Regular and Noto Sans Symbols 2 Regular; no CJK collection and no document-only face. Those five files are 12,970,840 bytes raw. Raw font bytes, raw wasm and compressed wasm are not measured yet: the size gate is a parent acceptance item, not a claim made here.
• Native builds opt into the OFL LXGW WenKai Lite face from craft-fonts' fonts/simplified-chinese-manifest.txt (the same face DeckCraft uses). The barred Noto Sans CJK collection still never enters; system Han faces still lead when installed. CRAFT_FONTS_REQUIRED=1 native builds require the Chinese manifest, ordinary builds tolerate an older checkout without it, and WEB_ALLOWED excludes it. The Chinese samples join the strict script test only when the face is embedded.
• Native also embeds every other non-barred manifest row (for example BIZ UDMincho, Shippori Mincho, Noto Sans Arabic/Georgian/Hebrew/Thai). They are OFL and asset-policy safe, but the actual set is wider than the five required faces; the size gate must measure it rather than citing only the web allowlist.
• No-font/default mode: the bundled faces supply ↘ ◀ ↑ 📋 and the rest of the interface's symbols, which tests/symbol_glyphs.rs asserts strictly. ✕, ✓ and ⌃ have no bundled egui face, so chrome draws them instead of painting them: the Symbol gallery and the close/check controls paint the code-drawn Icon::Check/Icon::Close (icons::fallback_for_symbol, widgets::glyph_button), and a tooltip whose symbol is missing falls back to ^ (theme::symbol_fallback through theme::available_text). Only workbook text still needs a real glyph, because its characters are the user's data. The test documents ✓/⌃ as optional-input gaps rather than claiming them.
• Extended acceptance mode (CRAFT_FONTS_DIR set, and CRAFT_FONTS_REQUIRED=1 for release): tests/symbol_glyphs.rs requires the exact union ↘ ✕ ◀ ↑ 📋 ✓ ⌃ in both Proportional and CELL plus the Korean interface labels, and fails instead of skipping when a loaded or required set lacks a face. ⌃ comes from Noto Sans Symbols, ✕ ◀ ✓ from Noto Sans Symbols 2, ↘/↑ from either Symbols face (NanumGothic also has them), and 📋 from egui's emoji faces.
• The required faces live in the pinned craft-fonts checkout at b076417b5880bd4154bd22f00695b1d28c6bea83. Point CRAFT_FONTS_DIR at that checkout: the older fixtures/craft-fonts snapshot has no Korean or symbol rows, and a loaded set without the required faces fails the extended checks by design.
• theme::fallback_covers_its_script is strict whenever a system or craft-fonts face provides the script, now including Arabic and Georgian; its skip prints the script name and sample.
• The production positive-rectangle fix in formula_bar.rs, the Role::DisclosureTriangle queries, the linear per-line editor-height assertions and the explicit accessible names for the Name Box and both editors are unchanged.

Explicit G1 accessibility repair — 2026-10-24

Seven existing integration tests now check rendered ribbon/light-dark, each supported locale, pivot pane and open menu, fifteen dialogs, active cell/formula edits, backstage pages and active text-box/committed states. The existing capture callback test now uses a full SheetApp Harness, asserts the Name Box tree is present, and checks accessibility before issuance and after callback drain/repaint. Its manually supplied pixels still test callback lifecycle rather than GPU readback; the explicit no-GPU renderer prevents kittest from silently turning it into a platform test. One-callback, request-token, one-reply and released-reservation assertions remain.

All eight affected tests (seven integration tests and the capture unit test) passed in full CI07. The four CI06 failures exposed unnamed Options/ribbon ComboBoxes, custom format input and pivot layout control; visible localized labels or precise semantic names now identify them. The fresh source review found no blocker; CI07's formatting changed only wrapping/trailing commas in those four reviewed production files. Original roles, input sequences and behavior assertions remain. Full CI05 is historical pre-repair evidence and CI06 remains a failed run.

Actual native screenshots/hidden/minimize/restore, screen-reader output, application E21b IME and platform/performance acceptance remain open. Full CI07 uses the canonical lock, required craft-fonts input, command-scoped exact-source mirrors and the private Vulkan loader; it is not host-loader or clean public-fetch qualification. Exact job/log hashes, review union, complete final source inventory and documentation-only delta are preserved in local task evidence under egui037-migration-20261022/final-landing/gridcraft-final-qualification.

Revision: 2026-10-24 — replaced pending accessibility/CI statements with actual full CI07 results, corrected the shared outgoing IME inventory, and retained native/performance/publication gates.