sillsdev / sillsdev/interlinearizer-extension

Evaluate the navigation diagrams as permanent documentation

Open
#261 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation 🟪Idea
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
  1. 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.
  2. 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.
  3. 03-entry-point-matrix.md — Sixteen ways navigation can start, against what each subsystem does about each, plus the asymmetries the empty cells expose.
  4. 04-scenarios.md — Six mermaid sequence diagrams: external nav, cross-book jump, arrow step, list click, boundary edit mid-glide, and mode toggle.
  5. 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.
  6. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.