Six diagrams of the book/segment/verse/phrase/token navigation surface were produced while reviewing #235. This issue is to decide which, if any, become permanent docs. If any, where/how should they live in the docs?
The navigation surface spans several independent axes:
- structure,
- coordinate spaces,
- entry points,
- per-scenario causality,
- concurrent state,
- frame-level timing.
No single diagram covers it, so each of the six takes one axis.
The gain: onboarding and change-safety: much of this behavior currently exists only as reasoning inside long doc comments.
The cost: staleness, since each diagram cites specific functions and constants and nothing will flag them when those move. Also, 4 of the diagrams are SVGs, which aren't diffable when updated.
Developed from branch perf/continuous-view-responsiveness @ 0ab3de6 (the open continuous-view perf PR, unmerged). They describe that branch, not main: src/hooks/usePhraseWindowHalf.ts, the holdCentered loop, and the deferred mid-glide re-centre are all branch-only.
Authored by Claude Opus 5 (1M context) — model claude-opus-5[1m] — read from the source on that branch. Every claim traces to a file listed in the README, but none of it has been independently verified by a human.
Temporarily housed at docs/navigation-diagrams, commit 7ab4df0, branched off main.
--
The six, to accept or reject individually
01-structure-bands.svg — To-scale band diagram of one stretch of LUK, marking the four places where verse, segment, token, phrase and window boundaries fail to line up.02-coordinate-spaces.svg — The eight addresses one text position has, and which of the sixteen conversions between them are lossy, partial, or one-to-many.03-entry-point-matrix.md — Sixteen ways navigation can start, against what each subsystem does about each, plus the asymmetries the empty cells expose.04-scenarios.md — Six mermaid sequence diagrams: external nav, cross-book jump, arrow step, list click, boundary edit mid-glide, and mode toggle.05-concurrent-clocks.svg — Harel statechart of the five state machines that run simultaneously, and the six couplings that are the only channels between them.06-timing-waterfall.svg — Two navigations plotted against frames and the real constants, showing why the settle is event-driven rather than timed.
Six diagrams of the book/segment/verse/phrase/token navigation surface were produced while reviewing #235. This issue is to decide which, if any, become permanent docs. If any, where/how should they live in the docs?
The navigation surface spans several independent axes:
No single diagram covers it, so each of the six takes one axis.
The gain: onboarding and change-safety: much of this behavior currently exists only as reasoning inside long doc comments.
The cost: staleness, since each diagram cites specific functions and constants and nothing will flag them when those move. Also, 4 of the diagrams are SVGs, which aren't diffable when updated.
Developed from branch
perf/continuous-view-responsiveness@0ab3de6(the open continuous-view perf PR, unmerged). They describe that branch, notmain:src/hooks/usePhraseWindowHalf.ts, theholdCenteredloop, and the deferred mid-glide re-centre are all branch-only.Authored by Claude Opus 5 (1M context) — model
claude-opus-5[1m]— read from the source on that branch. Every claim traces to a file listed in the README, but none of it has been independently verified by a human.Temporarily housed at
docs/navigation-diagrams, commit7ab4df0, branched offmain.--
The six, to accept or reject individually
01-structure-bands.svg— To-scale band diagram of one stretch of LUK, marking the four places where verse, segment, token, phrase and window boundaries fail to line up.02-coordinate-spaces.svg— The eight addresses one text position has, and which of the sixteen conversions between them are lossy, partial, or one-to-many.03-entry-point-matrix.md— Sixteen ways navigation can start, against what each subsystem does about each, plus the asymmetries the empty cells expose.04-scenarios.md— Six mermaid sequence diagrams: external nav, cross-book jump, arrow step, list click, boundary edit mid-glide, and mode toggle.05-concurrent-clocks.svg— Harel statechart of the five state machines that run simultaneously, and the six couplings that are the only channels between them.06-timing-waterfall.svg— Two navigations plotted against frames and the real constants, showing why the settle is event-driven rather than timed.