Three verse-0 gaps: fall-forward with no verse 1, a `\d` outside a chapter opening, and no decision record

[imnasnainaec]

Three separate verse-0 findings, surfaced by reading paranext/paranext-core#2663 (which makes the Text Collection show verse 1 at a verse-0 reference) against our own verse-0 handling. Two are defects; one is a documentation gap. They are filed together because they share a root topic, but each stands alone.

Line references are as of analysis-catalog-derivation.

Context worth stating up front, because it is what makes us different from that PR rather than behind it: core's rule is scoped to single-verse display surfaces and explicitly exempts anything rendering a whole chapter. We are a chapter surface, and verse 0 here is real, tokenizable, glossable content — not a rendering problem to route around. Nothing below proposes adopting core's fall-forward rule.

1. Verse-0 fall-forward can resolve to a verse no segment contains

activeScrRef (src/components/InterlinearizerLoader.tsx:337-357) resolves a verse-0 reference to literally verse 1 without checking that a segment exists there:

if (book.segments.some((segment) => segmentContainsVerse(segment, scrRef))) return scrRef;
if (scrRef.verseNum === 0) return { ...scrRef, verseNum: 1 };

Every other unmatched reference falls through to the nearest-preceding-verse-start search below it. Verse 0 short-circuits past that search to a hardcoded 1, so when the chapter has no verse 1 the result is a reference nothing contains, findActiveSegment returns undefined, and nothing highlights.

Our own test demonstrates the hole rather than covering it (src/__tests__/components/InterlinearizerLoader.test.tsx:532-550) — it asserts the resolution, but the fixture book's only segment is GEN 1:1, so the asserted GEN 3:1 is itself unmatched.

This is reachable in normal use, not just in fixtures: a partially drafted book whose chapter starts at verse 2, plus any of the three ways a verse-0 reference arrives (cursor placed in pre-verse-1 content, the toolbar < button, or a typed C:0 reference).

Proposed fix. For verse 0, resolve to the earliest verse start in that chapter — the mirror of the existing nearest-preceding loop, taking the minimum instead of the maximum. Search verse starts rather than segment startRefs, for the cross-chapter-segment reason already documented at that call site.

Note that the core PR faced the same input and deliberately rejected scanning forward ("verse 2 is not what 1:0 means" — it shows a "No text for this verse" empty state instead). That reasoning does not transfer: a Text Collection cell must name one specific verse or admit it is missing, whereas our job is to highlight an active segment in a continuous list, where landing on the chapter's first available segment beats highlighting nothing.

2. A \d outside a chapter opening leaks into the preceding verse's baseline text

We deliberately exclude d from HEADING_PARA_MARKERS so a Psalm superscription becomes verse-0 scripture rather than being discarded as a heading — that part is right, and core agrees d belongs to verse 0 rather than verse 1.

But the exclusion is unconditional while the verse-0 scope is not. handleChapterNode (src/parsers/papi/usjBookExtractor.ts:164-171) opens a synthetic verse-0 scope only immediately after a chapter node, while handleParaNode (:211-220) returns early only for markers in HEADING_PARA_MARKERS, otherwise recursing and appending text to whatever verse is currently open.

So a \d that is not at a chapter opening — a musical postscript closing a chapter, or one following a mid-chapter section heading — silently appends into the preceding verse's baselineText. It is then tokenized, offset-indexed, and glossable as if it were that verse's text. There is no error and nothing in the output distinguishing it.

Core takes the safer position: d sits in STRUCTURAL_MARKERS (extensions/src/platform-scripture-editor/src/scripture-text-grid/verse-display.utils.ts), which closes any open verse wherever it appears, so the content is dropped rather than misattributed.

Our extractor tests (src/__tests__/parsers/papi/usjBookExtractor.test.ts:413-494) cover d at a chapter opening, at a chapter opening with no chapter number, and at end-of-document immediately after a chapter node — none place a d after a verse.

Proposed fix. Make a d outside an open synthetic verse-0 scope a boundary: close the current verse and drop the content (matching core), or capture it as its own segment. Dropping is the smaller change and the safer default; capturing is arguably more correct for a tool whose purpose is analyzing scripture text, but it needs a SID that does not collide with a real verse. Either way, add a test with \d following a verse.

Whichever way this goes, it interacts with open question 3 in user-questions.md (chapter superscriptions as ordinary segments) and should probably be decided alongside it.

3. The verse-0 rules are not recorded anywhere as a decision

Our verse-0 model is a real design position with several interlocking parts:

• verse 0 passes through the nav context verbatim, unlike core, which normalizes it on its single-verse surface (src/components/InterlinearNavContext.tsx:242)
• resolution is display-only — activeScrRef reaches the Interlinearizer prop and never navigate, so the shared scroll group is never moved off a verse-0 reference (src/components/InterlinearizerLoader.tsx:564)
• a d superscription is scripture, not a heading (src/parsers/papi/usjBookExtractor.ts:71-74)
• verse 0 participates in boundary editing like any other segment (user-questions.md, question 3)

Today that lives in four long comments across four files, plus one open question. Nothing states the rule as a rule, and one property — the display-only guarantee — is not so much a rule as an emergent side effect: clicks are compared against the resolved reference (src/components/Interlinearizer.tsx:346 and :364), so a click on a fallen-forward verse-1 segment happens to be a no-op. That is a better design than core's explicit guard, but nothing pins it, and a refactor that compared against the host reference instead would silently start writing verse 1 into the scroll group.

The failure mode this prevents is not hypothetical; it is exactly what the core PR exists to undo. A prior PR in core shipped behavior contradicting its ticket's written acceptance, nobody flagged the divergence, and the ticket sat looking fixed for months. Core's response was an ADR recording the decision, the rejected alternatives, and the condition to revisit.

Proposed work. Add a short decisions record (a docs/decisions.md, or a section in REVIEW.md — team's call) with one entry for verse 0 stating the rule, why we diverge from core, and what would make us revisit. Then add the missing test: with the host at a chapter's verse 0 and no verse-0 segment, clicking the fallen-forward verse-1 segment must leave the scroll group at verse 0.

Also noted: an upstream bug we inherit

Not ours to fix, but it shapes how often the above is hit. BookChapterControl calls getPreviousVerseRef without bounds, whose no-versification branch floors at {chapterNum, verseNum: 0} in every chapter, not just chapter 1 — and then returns the same reference forever. We ship that control in power mode via ScriptureNavControls, so < from verse 1 of a chapter with no superscription lands on verse 0, falls forward, shows no change, and never moves again.

We already work around the sibling half of the same missing-bounds bug: getNextVerseRef overshooting the end of a chapter is precisely what the nearest-preceding fallback in activeScrRef compensates for. Passing bounds at that upstream call site would retire both workarounds. The core PR documents this and declares it out of scope, so it needs filing against paranext-core.