sillsdev / sillsdev/interlinearizer-extension
Evaluate the navigation diagrams as permanent documentation
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 2
- Forks
- 0
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 55
Description
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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the six artifacts under docs/navigation with main and the cited branch commit 0ab3de6, then read src/hooks/usePhraseWindowHalf.ts and the README references. Done means each diagram has an explicit accept-or-reject decision, a documented permanent location if accepted, and human verification of claims that currently describe branch-only behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100