epiphany/crates/epiphany-editor-gui/DECISIONS.md

# epiphany-editor-gui — Decisions

This crate's first `DECISIONS.md`. Records the calls made standing up the T1a
visual golden harness (`spec/CONTRACT_EDITOR_T1A_GOLDENS.md`; plan
`spec/PLAN_EDITOR_APP.md` §Ruling C, granted as amended 2026-07-23) — pixel-level
golden baselines of the resvg-rasterized score, as ordinary `#[test]`s in this
crate, comparing decoded pixels rather than encoded PNG files. The harness lives
in `src/goldens.rs` (`#[cfg(test)]`-only; never ships in the built binary) and
`goldens/*.png`.

## 1. The comparison contract: decoded pixels, never encoded PNG bytes

A golden test decodes the committed baseline PNG and compares **dimensions
first, then raw RGBA bytes** exactly — never the encoded file bytes. Plan
§Ruling C (granted as amended 2026-07-23) is explicit about why: comparing
encoded bytes would also lock the PNG encoder's own behavior (compression
level, filter choice, chunk layout, …), so the goldens would churn on an
encoder change even when every rendered pixel is identical — exactly the
defect the amendment exists to prevent. `goldens.rs`'s
`reencoding_with_different_settings_still_passes` test makes this guarantee
executable rather than merely asserted: it encodes one pixmap twice with
deliberately different `png` encoder settings (filter type, compression
level) via the `png` crate directly (decision 7), confirms the two encoded
byte strings differ, and confirms the comparator accepts either as a baseline
for the same pixels.

On a mismatch the comparator writes failure artifacts to
`target/golden-failures/<name>/` and names them in the panic message: a
dimension mismatch writes `actual.png` + `expected.png` (no `diff.png` — a
per-pixel map is not meaningful across differing dimensions, and the
comparator fails there *before* any pixel is compared); a pixel mismatch
writes all three, `diff.png` being a per-pixel highlight of exactly the
differing pixels. Decision 8 covers how that record survives past the
ephemeral CI runner.

## 2. The bless mechanism and its policy

`EPIPHANY_BLESS_GOLDENS=1` makes `assert_golden` write/overwrite the baseline
unconditionally instead of comparing (creating `goldens/` if needed). This is
a **reviewed decision**, stated at the function's definition: never a
mechanism for turning a red test green, only for accepting a new or
deliberately-changed raster after a human has looked at it. The three initial
baselines (`ten_measure_open.png`, `ten_measure_insert.png`,
`ten_measure_slurs_castoff.png`) are the first visual record of this editor's
output in the project's history — an unreviewed baseline is an unverified
claim wearing a checkmark (plan §Ruling C, user deep-dive point 2) — and were
**visually reviewed and approved by the user on 2026-07-23** before being
committed. Any future re-bless is the same kind of event: a diff is a finding,
reviewed before it is accepted, never a fix applied to make a failing test
pass.

## 3. G3 reuses G1's baseline and deliberately bypasses the bless path

There is no `ten_measure_undo.png`. G3 (post-undo) asserts the raster equals
**G1's own baseline file** byte-for-byte in decoded RGBA — undo must return
the pixels, not just the model — by calling `assert_golden_at` directly
against `baseline_path("ten_measure_open")`, never `assert_golden`. Routing G3
through `assert_golden` would let `EPIPHANY_BLESS_GOLDENS=1` overwrite
`ten_measure_open.png`: an initial bless run performed before undo is known to
be correct would silently bless a broken undo's post-undo pixels as the new
"as opened" baseline, after which every future run would compare undo against
its own bug instead of against G1. Bypassing `assert_golden` removes that
failure mode entirely — this comparison always compares, and can never bless
itself green. (G3 replays G2's scripted insert on its own fresh session
rather than continuing G2's, so the two tests stay independent of each
other's mutations.)

## 4. The casting-off fixture, and what its system-count assertion actually guards

G4 uses `ten_measure_with_slurs(0)` (`fixtures.rs:777`) specifically for its
three slurs, one of which is forced across a system break — the cross-system
slur-split path (`casting.rs:2262`) — the layout path real documents take,
not exercised by any single-system fixture.

An empirical finding changed the contract's original framing: at
`px_per_staff_space: 12.0`, **`ten_measure_single_staff(0)` itself already
casts off into two systems** (ten measures of quarter notes don't fit one
line at this scale) — casting-off is not unique to the slurred fixture. All
three baselines (G1/G2/G3's shared raster and G4's) are therefore
multi-system layouts. Consequently G4's `system_count > 1` assertion does not
guard "this is the slurred fixture, not the plain one" — a mutation
substituting `ten_measure_single_staff(0)` for the slurs fixture leaves the
system count at 2 either way, so that assertion still passes under the
mutation. What it guards is the more durable claim it was written for:
*casting-off itself has not stopped triggering* at this geometry — if it ever
did, this would fail as a named system-count value error rather than a
mystery pixel diff. The mutation instead dies on the golden pixel comparison
(dimensions differ: G4's baseline is taller, carrying the slur curves and the
wider slurred content), which is where the fixture-identity guarantee
actually lives.

## 5. Known engraving gaps, locked knowingly

The goldens lock the **current, real** output of the Minimal-tier engraver —
bugs and rough edges included, by design (plan §Ruling C: "a golden locks
whatever it sees"). Two are worth naming explicitly, both blessed by the user
with this record in hand on 2026-07-23:

- **No clef restatement on second and subsequent systems.** A new system does
  not redraw the governing clef at its start, unlike conventional engraving
  practice.
- **The second system's spacing is noticeably denser than the first's.** The
  casting-off balance between systems is not yet even.

Both are engraving-track items (`epiphany-engrave`'s casting/spacing passes;
plan §3.7), not `epiphany-editor-gui` work — this crate only observes the
rendered score, it does not engrave it. When engraving improves, the fix will
change these three PNGs' pixels, and the golden harness will surface that as
a reviewable diff to bless deliberately. That is the harness doing its job,
not a defect of it.

## 6. The baselines pin the raster stack

Determinism basis: `GlyphMode::PathOutline` uses no fonts (inlined Bravura
outline paths), and `resvg`/`tiny-skia` are pure Rust with deterministic
rasterization; CI and dev are both Linux. Standing consequence: **the
baselines pin the raster stack**, so any `Cargo.lock` movement of
`resvg`, `tiny-skia`, or `png` is a golden-review event — the diff must be
inspected and deliberately re-blessed — never a silent re-bless folded into
an unrelated dependency bump. If cross-platform rasterization drift is ever
observed, the fallback is a bounded per-pixel tolerance, recorded as that
decision when it happens, not pre-engineered here.

## 7. The `png` dev-dependency

`tiny_skia::Pixmap::encode_png`/`decode_png` (used throughout the comparator
and the bless path) expose no encoder configuration — every call from a given
pixmap produces byte-identical output. Proving decision 1 executable (that
two *differently*-encoded PNGs of the same pixels both compare equal) needs
an encoder with configurable filter/compression settings, which only the
underlying `png` crate exposes directly. `png` is therefore a **dev-only**
dependency, used exclusively inside `goldens.rs`'s own test module — never in
the comparator or bless code paths, which stay on
`resvg::tiny_skia::Pixmap::{encode_png,decode_png}` exclusively, and never at
runtime.

Declared as a caret requirement (`png = "0.17.16"`), not an exact `=` pin (a
W1-review amendment): `tiny-skia` 0.11.4 already resolves `png 0.17.16` in
`Cargo.lock`, so the caret requirement is a dev-only edge onto that same
dependency-tree node today — and stays unified with it after any future
`tiny-skia` bump that moves its own `png` requirement forward, rather than
forking a second `png` version into the tree (which an exact pin would force
the day `tiny-skia` moves).

## 8. CI failure artifacts

A comparator panic's assertion message names `actual.png`/`expected.png`/
`diff.png` paths under `target/golden-failures/<name>/` — useful for local
reproduction, but those paths name the CI runner's own ephemeral filesystem,
gone the moment the job ends. The reviewable record is the `editor-gui` job's
one additive step (`.github/workflows/ci.yml`): an `if: failure()`
`actions/upload-artifact@v4` step uploading `target/golden-failures/` as the
`golden-failures` artifact (`if-no-files-found: ignore`, since it produces
nothing on a green run). This is the tranche's only CI change; nothing else
in `ci.yml` moves.

## 9. Rubber-band selection (2026-07-23, T2-W2) — drag threshold and anchor accent

Dispatched under `spec/CONTRACT_EDITOR_T2_SELECTION.md` §W2, over W1's
selection-set API (`selections()`, `anchor()`, `toggle_at`, `select_within`).
`main.rs` only; no golden pixel moves — the overlay is drawn by `score_view`
after the score texture is painted, entirely outside `goldens.rs`'s headless
raster path, so none of it is exercised by a golden test.

**Sensing.** The score view's `Sense` widens from `click()` to
`click_and_drag()`. A plain click still resolves through
`Response::clicked()`, unchanged. A drag is tracked in a new pure `DragRect`
(origin + current screen `Pos2`, no `egui::Response`/`Context` dependency, so
it is unit-testable headlessly), updated across frames via
`drag_started`/`dragged`, and resolved on `drag_stopped`.

**The drag threshold, and why it exists even though egui has its own.**
`DragRect::RUBBER_BAND_THRESHOLD = 4.0` screen points: below it, a completed
drag resolves as a plain click/toggle at the release point, not a
rubber-band `select_within`. This exists on top of egui's own click-distance
tolerance (`InputOptions::max_click_dist`, 6.0 points) because a widget
sensing both click and drag reclassifies a **long, still press-and-hold**
(no meaningful movement, held past `max_click_duration`, 0.8s) as "dragging"
purely on elapsed time (`PointerState::is_decidedly_dragging`) — a gesture a
user experiences as a click would otherwise silently become a near-empty
rubber-band replace of the current selection. `DragRect::is_rubber_band`
(`distance >= threshold`) and the release dispatch
(`resolve_release(&DragRect, ctrl) -> ReleaseAction`) are pure and directly
unit-tested, including the exact boundary (`>=`, not `>`).

**World-space query stays unnormalized.** `select_within`'s `BoundingBox`
normalizes its own corners (its doc: "rect's corners are order-independent");
the release handler therefore maps `drag.origin`/`drag.current` straight
through `ViewMap::screen_to_world` with no pre-normalization of its own.
`DragRect::screen_rect`'s own min/max normalization is a separate concern
(painting a valid, non-inverted rectangle for the live overlay) and never
feeds the world-space query.

**Ctrl/Cmd-click and the below-threshold-drag release** both resolve through
one shared `EditorApp::resolve_click(world, grid, toggle)`: `toggle` calls
`toggle_at`; otherwise `click`, with the exact same "empty — pencil would
insert…" reporting the single-selection code already had. This keeps the
plain-click behavior — including its status-line wording — identical to
before this packet for both call sites.

**Anchor accent.** Every member in `session.selections()` gets the existing
2.0pt blue stroke (unchanged from the prior single-selection code, now
looped); `session.anchor()` additionally gets a second pass with a 3.0pt
orange stroke on top. A single-member selection's sole member is trivially
the anchor, so it now receives both passes (blue then orange) where it
previously received only the blue one — a deliberate, undocumented-by-any-
golden visual change (the overlay is outside the golden raster path per
above), not a behavior change: `click`'s selection-logic contract (single
member, replaces the set) is unchanged, only its paint style gained an
always-present anchor accent.

**Debug panel and help text.** Adds a `selected: N member(s)` line and
relabels the existing selection lines as the anchor's (`session.anchor()`
directly, replacing the `session.selection()` compatibility read — the two
are equal by construction, `selection()` is `anchor().copied()`). The help
text now documents drag-to-select and Ctrl/Cmd-click, and states which
toolbar/key intents act on the whole selection (`delete_selection`,
`alter_selection` — both batch over every/every-pitch member per W1's
`DECISIONS.md`) versus the anchor alone (`move_selection_staff_step`,
`add_note_to_selection`, `insert_note_after_selection`,
`set_selection_duration` — verified against each function's own
`self.selection.anchor()` read in `epiphany-editor-core/src/lib.rs`, not
assumed from the contract's own summary, which groups `alter` with the
anchor-only intents even though its implementation batches).

## Clipboard wiring (2026-07-24, T2-W4b)

Dispatched as the W4b packet's Half 2, over `epiphany-editor-core`'s
`copy_selection`/`paste_over_selection`/`CopyOutcome`/`PasteOutcome`
(fragment.rs's clipboard fragment projection, Ruling E). `main.rs` only; no
golden pixel moves for the same structural reason W2's overlay didn't
(decision 9): `goldens.rs` builds its own session and calls
`render`/`rasterize_pixmap` directly, never through `EditorApp`, so nothing
this packet touches (toolbar, keys, status line, a new `last_paste_text`
field) is reachable from a golden test. Verified, not assumed: the three
baseline PNGs (`ten_measure_open.png` 53638B, `ten_measure_insert.png`
54590B, `ten_measure_slurs_castoff.png` 57891B) are byte-identical
(`md5sum` before/after) and untouched by `git status` throughout this
packet.

**The clipboard mechanism egui 0.29 actually offers — verified against the
vendored source (`~/.cargo/registry/…/egui-0.29.1`,
`~/.cargo/registry/…/eframe-0.29.1`), not assumed from memory of a newer
egui:**

* **Write (copy): `egui::Context::output_mut`/`egui::Ui::output_mut`,
  setting `PlatformOutput::copied_text`.** This is the *only* clipboard-write
  surface in 0.29 (`egui/src/data/output.rs:107`, `egui/src/context.rs:1423`)
  — the backend (`eframe`'s `egui-winit` integration) reads it after the
  frame and pushes it to the OS clipboard. `do_copy` sets
  `ctx.output_mut(|o| o.copied_text = outcome.fragment.clone())` on a
  successful `copy_selection`.
* **Read (paste): there is no synchronous "read the OS clipboard now" call
  anywhere in `eframe::Frame`'s or `egui::Context`'s public API** — checked
  directly (`grep -rn "pub fn" eframe-0.29.1/src/epi.rs`; the only clipboard
  reference in `eframe`'s own source is `egui_winit.clipboard_text()`
  inside the native integration's *internal* event-translation code,
  `native/glow_integration.rs:681`, never exposed to app code). The **only**
  way an app learns paste content is by consuming
  **`egui::Event::Paste(String)`** from the input event queue
  (`egui/src/data/input.rs:388`) — the backend detects an OS paste gesture
  (Ctrl/Cmd+V, or an OS-level paste menu action), reads the clipboard
  itself, and injects the text as one event, once, for that frame only.
  `EditorApp::handle_clipboard_events` reads `ctx.input(|i| &i.events)`
  every frame via the new pure helper `paste_event_text(&[egui::Event]) ->
  Option<&str>` and, on a hit, both **acts immediately** (pastes over the
  current selection) and **caches the text** (`last_paste_text`) for the
  toolbar "Paste" button — which has no other way to act between paste
  gestures, since a button click generates no `Event::Paste` of its own and
  there is nothing else to read it from.

**Why Copy is a plain keyboard edge but Paste cannot be.** `handle_keys`'s
existing pattern is a boolean edge-read (`i.modifiers.command &&
i.key_pressed(egui::Key::...)`), used for every other shortcut in this file.
Ctrl/Cmd+C fits it exactly: `do_copy` needs nothing from egui *except* that
the chord fired — the text it writes out comes from `copy_selection()`, not
from any event payload — so `Keys` gained one more field (`copy`) the same
way. Ctrl/Cmd+V structurally cannot fit that pattern: a bare `key_pressed`
edge tells you *that* a paste gesture happened, never *what* was pasted, and
only `Event::Paste`'s own `String` payload carries that. So paste has no
`Keys` field at all — `handle_clipboard_events` (called once per frame from
`update`, alongside `handle_keys`) is the whole mechanism, and it is what
makes Ctrl/Cmd+V "just work": egui's own native integration already turns
that chord into the event, this app only has to consume it.

**No-selection paste policy.** `paste_over_selection` itself returns
`Err(EditorError::NoSelection)` when nothing is selected — Display: "no
selection", accurate but not actionable in a clipboard context (a user
who never selected anything doesn't know that's what "no selection" means
here). `do_paste` pre-checks `session.anchor().is_none()` and reports
**"select a destination first"** instead, without ever calling
`paste_over_selection` — a GUI-level policy decision, not a change to the
core session's error semantics. Every *other* outcome — a successful paste
(reports events/slur/tie counts from `PasteOutcome`) or any other
`EditorError` — surfaces `{err}` verbatim, per the packet's brief ("the
fragment error Display strings are user-grade"); `FragmentError`'s and
`EditorError`'s `Display` impls (`epiphany-editor-core/src/fragment.rs`,
`lib.rs`) are already written for a human reader, so this crate adds no
translation layer over them.

**Toolbar buttons.** "Copy" is always clickable (unguarded), matching this
toolbar's existing convention for every other selection-dependent action
(Delete, Transpose, Move, …) — none of them are `add_enabled`-gated on
selection state; a `NoSelection`/`WrongSelection` error is left to surface
normally through the status line. "Paste" **is** gated
(`add_enabled(self.last_paste_text.is_some(), …)`), because unlike a
domain error, "nothing has ever arrived to paste" is a structural
precondition with no session-side error to report at all — the same class
of gate `can_undo`/`can_redo` already use for Undo/Redo.

**Pencil mode is untouched.** Clipboard actions (buttons, keys, and
`handle_clipboard_events`) run unconditionally regardless of `self.pencil`
— no new interaction with the pencil click-to-insert path, no new branch in
`score_view`. Pencil's own behavior, and every existing test/golden that
exercises it, is unchanged.

**Testing scope, stated honestly.** `paste_event_text` is pure (no
`egui::Context`/`InputState`/native-backend dependency) and gets four real
unit tests, each proven live by a mutation (dropping `.rev()` — breaks
"last `Paste` in the frame wins" — and matching the wrong `Event` variant
— both confirmed to fail the expected tests, then reverted). Everything
else this packet added — `do_copy`/`do_paste`/`do_paste_from_cache`/
`handle_clipboard_events`'s own dispatch, the toolbar buttons, the
`Keys::copy` edge, the help text — is **egui-side dispatch, reviewed but
not unit-tested**: there is no headless way in this crate to synthesize an
`egui::Context` frame, drive `ctx.input`/`output_mut`, or simulate an OS
clipboard/paste gesture (the same limitation the rest of `main.rs`
already lives with — `goldens.rs` exists precisely because rendering has
no headless story either, and `resolve_release`/`DragRect` were pulled out
pure for the same reason W2 needed to unit-test *something* about
release-time dispatch). `cargo test -p epiphany-editor-gui` green (20/20,
including all four golden tests) is this packet's regression gate for that
untested surface, per the brief.

## Note-entry mode + G5 (2026-07-24, T3-W2)

Dispatched under `spec/CONTRACT_EDITOR_T3_CARET.md` §W2, over W1's caret seam
(`EditorSession::{caret, set_caret_at, set_entry_duration, advance, retreat,
enter_nominal, enter_pitch, enter_rest, x_at_position}`, `Caret`). `main.rs`
(mode, keys, palette gating, click dispatch, caret overlay, help/debug text)
and `goldens.rs` (the new G5 test) only — **no editor-core change was
needed**, confirmed by grep-checking the packet's own suggestion of a "tiny
pub accessor": every piece the caret overlay needs (`score().voices()`,
`score().staff_instances()`, `resolved().strokes`, `x_at_position()`) was
already public.

**Mode exclusivity.** `pencil: bool` and the new `entry_mode: bool` are
mutually exclusive: turning either on always clears the other. Implemented
once, as a pure `toggle_exclusive(this, other) -> (bool, bool)` (mirrors
`resolve_release`'s role from T2-W2 — pulled out so the invariant itself is
unit-tested, not eyeballed at each of its four call sites: the P/N keys and
the two toolbar `toggle_value`s). `toggle_exclusive`'s contract is
intentionally asymmetric: turning `this` **on** forces `other` off; turning
`this` **off** leaves `other` exactly as it was (never assumes the
invariant already holds coming in, only guarantees it holds going out).

**Letter-key interpretation is mode-gated**, pulled out as a second pure
function `resolve_letter(entry_mode, nominal) -> LetterAction` (`Enter`,
`AddChordNote`, or `None`) — the packet's own named candidate for "the
obvious testable pure fn". In entry mode every letter A–G enters that
natural; outside it, only `A` keeps its pre-existing "add chord note to the
anchor" meaning (B–G stay unbound outside entry mode, as they always were).
`handle_keys` reads whichever of the seven letter keys fired this frame (at
most one in practice — one key event — but the lookup takes the first match
either way) into `Keys::letter: Option<CmnNominal>`, then dispatches through
`resolve_letter`.

**Key map, verified against the code rather than assumed from the
contract's own summary** (the contract said "←/→ ... they currently move
selection pitch", which does not match `handle_keys` as it stood — ↑/↓ move
pitch, ←/→ were unbound; the coordinator's dispatch caught this and it is
recorded here as the corrected, verified fact):

* **N** — toggles note-entry mode (mutually exclusive with pencil).
* **A–G**, entry mode on — `enter_nominal`. **A**, entry mode off — the
  existing "add chord note" (unchanged). **B–G**, entry mode off — no
  binding (unchanged: they never had one).
* **R** — `enter_rest`, entry mode only. Verified free: `handle_keys` never
  read `egui::Key::R` before this packet.
* **←/→** — `retreat`/`advance`, entry mode only. Both new bindings (neither
  was bound before); outside entry mode they remain inert, same as before
  this packet.
* **↑/↓** — unchanged in every mode: `move_selection_staff_step`.
* Duration palette (toolbar buttons `1`/`1/2`/`1/4`/`1/8`/`1/16`) — while
  entry mode is on, `set_entry_duration`; otherwise unchanged
  (`set_selection_duration`). Gated per-click on `self.entry_mode`, not
  a separate widget.

**Click dispatch.** `score_view`'s three-way branch is now `pencil` →
`insert_note_at` (unchanged) → else `entry_mode` → `set_caret_at` (new) →
else the existing select/toggle path. Pencil's branch keeps its early
`return` after `request_repaint()` (needed because `insert_note_at` mutates
the score, staling the hit-test map the overlay code below would otherwise
paint against this same frame). `set_caret_at` needs no such guard — it
mutates no score/layout state at all, so the overlay code safely runs in
the same frame using the just-updated caret. Rubber-band drag tracking
(`DragRect`) is now gated on `!self.pencil && !self.entry_mode` (widened
from `!self.pencil` alone) — an extension beyond the contract's literal
text (which only names "a click in entry mode"), decided for the same
reason pencil already excludes dragging: a click in either mode does
something other than select, so a drag gesture in either mode has no
selection to build either. Flagged as this packet's own call, not
contract-mandated.

**The caret overlay's region/staff derivation** (`caret_segment`, next to
`selection_rect`): `caret.voice` → `(region, staff_instance)` via
`session.score().voices()` (matches `epiphany-editor-core`'s own internal
use of `Score::voices()`) → the staff's global `StaffId` via
`session.score().staff_instances()` → that staff's *own* rendered line
strokes, filtered from `session.resolved().strokes` by
`TypedObjectId::Staff(staff_id)` (not just any staff — a multi-staff score
needs the caret drawn on its own staff, not the topmost one) — min/max `y`
across those strokes is the "full staff height" span, no hardcoded staff-
space constant needed (unlike duplicating editor-core's private
`STAFF_SPAN`, this reads the *actual* rendered geometry). `x` comes
straight from `x_at_position(region, None, &caret.position)`. Drawn as a
2.0pt line in a distinct green (`rgb(0, 170, 90)`), separate from the
selection's blue and the anchor's orange.

**G5 — the caret-entry golden.** `ten_measure_single_staff(0)`, the *same*
fixture and the *same* `scripted_insert_target` click point G2/G3 already
use (the contract's own ask: "the same extrapolation territory G2 used") —
reused verbatim rather than deriving a second target function. Drives
`set_caret_at` then four `enter_nominal(C/D/E/F)` calls at the caret's
default (quarter, from the 4/4 meter) entry duration. **Value assertions
before pixels**, per the contract: the grid step, the caret's post-
`set_caret_at` position (independently re-derived, not just asserted equal
to G2's own — though it does land on the same whole-note-10 slot G2 proves,
since it is the identical target on the identical fixture) and entry
duration, then each of the four entries' resulting caret position as an
exact `MusicalPosition`/`RationalTime` before any raster is taken. Baseline:
`goldens/ten_measure_caret_entry.png`, 57379 bytes — generated via
`EPIPHANY_BLESS_GOLDENS=1`, **not judged correct here**: per plan §Ruling
C's user deep-dive point, a new baseline is visually reviewed and approved
by the user before being committed. G1–G4's three baselines
(`ten_measure_open.png` 53638B, `ten_measure_insert.png` 54590B,
`ten_measure_slurs_castoff.png` 57891B) are confirmed byte-identical
(`git status` reports them untouched throughout this packet).

**Mutations, each substituted, observed failing, then reversed** (never
`git checkout`): (1) `resolve_letter`'s mode gate (`if entry_mode` →
`if !entry_mode`) — kills both of its own tests (letters interpreted
backwards in and out of entry mode). (2) `toggle_exclusive`'s clear branch
(`other` always passed through unchanged) — kills
`toggle_exclusive_turning_on_clears_the_other` (`(true, true)` vs expected
`(true, false)`). (3) G5: skipping the D entry (substituting a hand-built
`EditOutcome{graph_changed: true, ..}` in place of ever calling
`enter_nominal`) — **the position assertion fires, not the pixel one**:
the test panics at `session.caret().map(|c| c.position) == Some(after)`
(`Some(MusicalPosition(41/4))` vs the expected `Some(MusicalPosition(21/2))`)
long before reaching `render_pixmap`/`assert_golden` at all — confirming
the contract's own ordering claim ("value assertions before pixels") is
real, not just documented. (4) G5's determinism double: perturbing the
second `render_pixmap` call's `px_per_staff_space` (12.0 → 13.0) — kills
the `assert_eq!(svg1, svg2, ...)` check (a large SVG-string diff), proving
the double is a real, load-bearing check and not vestigial boilerplate
copied from G1–G4.

**Testing scope, stated honestly.** `resolve_letter` and `toggle_exclusive`
are pure and unit-tested directly, same discipline as `resolve_release`/
`DragRect`. Everything else this packet added — the toolbar's two
`toggle_value` calls and their `.changed()` mutual-exclusion glue, the
`Keys` struct's new fields and their `ctx.input` reads, `do_set_caret_at`/
`do_caret_step`/`set_entry_duration`'s own bodies, `score_view`'s click/drag
branching, the caret overlay's paint call, the debug panel and help text —
is **egui-side dispatch, reviewed but not unit-tested**, for the same
structural reason T2-W2/W4b's equivalent surfaces are not: there is no
headless way in this crate to synthesize an `egui::Context` frame or drive
`ctx.input`/painter calls. `cargo test -p epiphany-editor-gui` green
(25/25, including all five golden tests) is this packet's regression gate
for that untested surface.