89 lines
4.9 KiB
Markdown
89 lines
4.9 KiB
Markdown
# Contract: Editor T3 — the note-entry caret
|
||
|
||
Repo root `/home/jeans/Repos/active/epiphany`. Governed by
|
||
`spec/PLAN_EDITOR_APP.md`'s T3 ladder entry (the input-method-agnostic entry
|
||
seam). T2 is complete at `62117d3`. Parallel work is active in
|
||
`epiphany-core` (the decode-vector surface) — **no packet here touches
|
||
`epiphany-core`, any `.tex`, or `epiphany-testkit`**. Execution model as
|
||
T1a/T2: Sonnet subagents per packet, coordinator line-level review with
|
||
independent mutation re-runs, user deep-dives at contract sign-off (done),
|
||
any new golden baseline, and the final report. Mutation discipline
|
||
throughout: anchor-assert before substituting, restore by reversing, never
|
||
`git checkout`.
|
||
|
||
## Design pins (contract-level calls; no new plan ruling required)
|
||
|
||
* **The caret is session-local state, never in the op log**:
|
||
`(voice, position, entry_duration)`. Undo does not move it (documented).
|
||
If its voice ceases to exist, the caret **clears** (documented; v1 keeps
|
||
the fallback trivial — the selection set's survivor rule does not apply to
|
||
a point cursor).
|
||
* **Letters enter naturals only** (alteration is a follow-up gesture via the
|
||
existing transpose intents, exactly MuseScore's model); the MIDI path
|
||
enters explicit pitches, sharps-spelled by v1 policy.
|
||
* **Octave inference for letters**: nearest to the reference pitch — the
|
||
nearest preceding note in the caret's voice (by position), else octave 4.
|
||
Equidistant tie-break: **downward**. Table-tested, not vibes-tested.
|
||
* **Entry inserts with make-room overwrite** — the pencil's exact semantics
|
||
and machinery (`make_room`), atomic; then the caret advances by the
|
||
entered duration. Positions are global rationals, so advancing crosses
|
||
barlines with no special casing.
|
||
* **`x_at_position` — the forward map** (position → world x over the same
|
||
anchors `position_at` inverts) lands in W1 so W2 can draw the caret; it is
|
||
seam API, round-trip-tested against `position_at`.
|
||
|
||
## W1 — the caret seam (`crates/epiphany-editor-core/**` only; dispatchable now)
|
||
|
||
API (indicative; crate idiom wins): `caret()`, `set_caret_at(point)` (region/
|
||
staff/voice via the existing `nearest_manifestation` path, primary voice,
|
||
position snapped via `default_grid_at`/`position_at`; entry duration
|
||
initialized from the grid step), `clear_caret()`,
|
||
`set_entry_duration(MusicalDuration)` (positive-validated),
|
||
`enter_nominal(CmnNominal)`, `enter_pitch(Pitch)`, `enter_rest()`,
|
||
`advance()`/`retreat()` (move by the entry duration, clamped at zero; no
|
||
insertion), and the pure `midi_note_to_pitch(u8) -> Pitch` (60 = C4,
|
||
69 = A4; black keys sharp-spelled — the v1 policy the spelling prepass may
|
||
later refine) feeding `enter_pitch`. `enter_nominal`/`enter_pitch`/
|
||
`enter_rest` funnel to ONE insertion core.
|
||
|
||
Tests (value-asserting) + minimum mutations: (t1) advance arithmetic across
|
||
a barline — mutation: skip the advance → dies; (t2) the octave table incl.
|
||
the equidistant tie-break — mutation: flip the tie-break → dies; (t3) entry
|
||
over occupied space reproduces the pencil's overwrite values — mutation:
|
||
bypass make-room → dies; (t4) the MIDI table (21/60/61/69/108) — mutation:
|
||
off-by-one octave → dies; (t5) `x_at_position`∘`position_at` round-trip —
|
||
mutation: anchor the wrong segment → dies; (t6) undo leaves the caret in
|
||
place AND a vanished voice clears it — mutations: move-on-undo /
|
||
keep-on-vanish → each dies.
|
||
|
||
DECISIONS.md entry records: the session-local/no-undo-move call, the octave
|
||
rule + tie-break, the naturals-only letter policy, the sharp-spelling MIDI
|
||
policy, and the `x_at_position` seam.
|
||
|
||
## W2 — GUI note-entry mode + the G5 golden (after W1 review)
|
||
|
||
`crates/epiphany-editor-gui/**` only. `N` toggles entry mode (precedence
|
||
documented against pencil — the two modes are mutually exclusive); letters
|
||
A–G → `enter_nominal`; the existing duration palette sets the entry
|
||
duration while in entry mode; ←/→ → `retreat`/`advance` (entry mode only —
|
||
they currently move selection pitch; the mode gates which); the caret draws
|
||
as a vertical line at `x_at_position` through `ViewMap`, full staff height.
|
||
**G5**: a new golden — `ten_measure_single_staff(0)`, entry mode, scripted
|
||
C-D-E-F quarters entered at the caret from the score's end — locking the
|
||
entry loop's visible result as G2 locks the pencil's. **A new baseline is a
|
||
user deep-dive: visually reviewed before blessing.** G1–G4 stay
|
||
byte-identical (53638/54590/57891 + G5's new file). Pure logic
|
||
unit-tested + mutated; egui dispatch review-only, stated honestly.
|
||
|
||
## Gate (every packet, actual output)
|
||
|
||
The standard six; conformance **9/9 with `--features golden-gate`, 8/8
|
||
without** (both run); requirement labels — report observed actuals (parallel
|
||
spec-side work may move them; never assert stale numbers); existing goldens
|
||
byte-identical. Blast radius per packet as stated. Do not commit.
|
||
|
||
## Report
|
||
|
||
Per packet, as every tranche: files + summary, exact asserted values, every
|
||
mutation with kill evidence, gate output, deviations flagged explicitly.
|