Sync verse-0 (superscription) selection to the global scroll-group ref

Author: alex-rawlings-yyc

src/__tests__/components/InterlinearNavContext.test.tsx

@@ -101,6 +101,25 @@ describe('InterlinearNavContext', () => {
     expect(result.current.liveScrRef).toEqual({ book: 'GEN', chapterNum: 3, verseNum: 7 });
   });
 
+  it('passes a same-chapter verse-0 echo through when it matches a fresh internal-nav marker', () => {
+    // Selecting a verse-0 superscription navigates the host to verse 0 of the chapter already shown,
+    // so the host's echo is shaped exactly like the spurious post-nav chapter echo. A fresh
+    // internal-nav marker for that verse-0 key marks it as our own deliberate move, so the stickiness
+    // exception lets it through to the superscription rather than holding the prior verse.
+    const { result, setRef, rerender } = renderNavMutable({
+      book: 'GEN',
+      chapterNum: 3,
+      verseNum: 7,
+    });
+
+    act(() => result.current.navigate({ book: 'GEN', chapterNum: 3, verseNum: 0 }, 'internal'));
+
+    act(() => setRef({ book: 'GEN', chapterNum: 3, verseNum: 0 }));
+    rerender();
+
+    expect(result.current.liveScrRef).toEqual({ book: 'GEN', chapterNum: 3, verseNum: 0 });
+  });
+
   it('passes a verse-0 reference for a different chapter through as a real chapter jump', () => {
     // A verse-0 reference for a chapter other than the one shown is a genuine chapter navigation, not
     // an echo, so it is honored as verse 0 (the loader maps it to verse 1 if that chapter has no

src/__tests__/components/Interlinearizer.test.tsx

@@ -533,9 +533,10 @@ describe('Interlinearizer', () => {
     expect(mockNavigate).toHaveBeenCalledWith({ book: 'GEN', chapterNum: 1, verseNum: 2 });
   });
 
-  it('focuses a verse-0 token on select without writing a verse-0 reference to the host', () => {
-    // Verse 0 (a superscription) cannot be expressed as a host scroll-group reference, so selecting
-    // one of its tokens must focus it locally without calling navigate.
+  it('writes a verse-0 reference to the host when a verse-0 token is selected', () => {
+    // Selecting a superscription token navigates the host to verse 0 like any other verse; the
+    // internal-nav marker keeps the host's chapter echo from bouncing the view (the stickiness
+    // exception in InterlinearNavContext). Default scrRef is GEN 1:1, so this is a real verse change.
     const mockNavigate = jest.fn();
     renderInterlinearizer({ book: GEN_SUPERSCRIPTION_BOOK, navigate: mockNavigate });
 
@@ -546,10 +547,10 @@ describe('Interlinearizer', () => {
       );
     });
 
-    expect(mockNavigate).not.toHaveBeenCalled();
+    expect(mockNavigate).toHaveBeenCalledWith({ book: 'GEN', chapterNum: 1, verseNum: 0 });
   });
 
-  it('focuses a verse-0 token from the strip without writing a verse-0 reference to the host', () => {
+  it('writes a verse-0 reference to the host when a verse-0 token is focused from the strip', () => {
     const mockNavigate = jest.fn();
     renderInterlinearizer({
       book: GEN_SUPERSCRIPTION_BOOK,
@@ -565,7 +566,7 @@ describe('Interlinearizer', () => {
       onFocusedTokenRefChange('GEN 1:0:0');
     });
 
-    expect(mockNavigate).not.toHaveBeenCalled();
+    expect(mockNavigate).toHaveBeenCalledWith({ book: 'GEN', chapterNum: 1, verseNum: 0 });
     expect(capturedContinuousViewProps.focusedTokenRef).toBe('GEN 1:0:0');
   });
 

src/__tests__/components/SegmentView.test.tsx

@@ -329,8 +329,8 @@ describe('SegmentView', () => {
 
     await userEvent.click(screen.getByTestId('segment-container'));
 
-    // Passes the first word token so the segment gains focus (and the active highlight) on click —
-    // the path that lets a verse-0 superscription become active without a host write.
+    // Passes the first word token so the segment gains focus (and the active highlight) on click,
+    // letting the parent both highlight the segment and navigate to its verse.
     expect(handleSelect).toHaveBeenCalledTimes(1);
     expect(handleSelect).toHaveBeenCalledWith({ book: 'GEN', chapter: 1, verse: 1 }, 'tok-0');
   });

src/components/InterlinearNavContext.tsx

@@ -114,15 +114,19 @@ export interface InterlinearNav {
   rawScrRef: SerializedVerseRef;
   /**
    * The active reference, equal to `rawScrRef` except that a verse-0 reference naming the chapter
-   * already shown is held sticky on the current verse. A verse-0 reference is otherwise passed
-   * through verbatim: when it names a chapter with a verse-0 superscription segment, that segment
-   * becomes the active verse. Whether a given chapter actually has verse-0 content is unknown here
-   * (the book is not loaded at this layer), so the loader resolves a verse-0 reference with no
-   * matching segment back to the chapter's first numbered verse before rendering.
+   * already shown is held sticky on the current verse — unless it matches a fresh internal-nav
+   * marker (the extension's own move to that chapter's superscription), which passes through. A
+   * verse-0 reference is otherwise passed through verbatim: when it names a chapter with a verse-0
+   * superscription segment, that segment becomes the active verse. Whether a given chapter actually
+   * has verse-0 content is unknown here (the book is not loaded at this layer), so the loader
+   * resolves a verse-0 reference with no matching segment back to the chapter's first numbered
+   * verse before rendering.
    *
    * The sticky exception exists because, after a verse navigation, the host re-broadcasts the
    * chapter as a separate `verseNum: 0` reference (an echo of the current location, not a real
-   * move); treating that as a jump to verse 0 would yank the view off the verse the user is on.
+   * move); treating that as a jump to verse 0 would yank the view off the verse the user is on. The
+   * marker carve-out distinguishes that spurious echo from a deliberate verse-0 navigation the
+   * extension itself just made (which is shaped identically).
    */
   liveScrRef: SerializedVerseRef;
   /**
@@ -227,20 +231,42 @@ export function InterlinearNavProvider({
    */
   const liveScrRefRef = useRef<SerializedVerseRef>(rawScrRef);
 
+  /**
+   * Verse keys of internal navigations still awaiting their host round-trip, each mapped to its
+   * `Date.now()` stamp. `navigate(ref, 'internal')` records `verseKey(ref)`; `consumeInternalNav`
+   * removes it on match. Keyed (not a single value) so that rapid successive clicks both stay
+   * pending and neither host delivery is misread as external. The stamp gives each marker a TTL
+   * ({@link INTERNAL_NAV_TTL_MS} — see its doc for why stranded markers must expire), honored by ALL
+   * readers: `consumeInternalNav` (which also evicts expired markers), the verse-0 stickiness
+   * exception below, and the render-phase mid-reveal guard (both pure reads — no eviction during
+   * render).
+   */
+  const pendingInternalNavRef = useRef<Map<string, number>>(new Map());
+
   // After a verse navigation the host re-broadcasts the *chapter* to the scroll group as a separate
   // `verseNum: 0` reference (an echo of the current location, not a real move). Treating that as a
   // jump to verse 0 would yank the views off the verse the user is actually on, so a verse-0
   // reference that names the book+chapter already shown is held sticky: keep the current `liveScrRef`
-  // (its real verse). Every other reference — including a verse-0 reference for a *different* chapter
-  // (a genuine chapter jump, which the loader resolves to the verse-0 superscription when one exists,
-  // else to verse 1) — passes through verbatim. The duplicate-delivery guard reuses the previously
-  // committed object when a re-send is value-equal, so a duplicate never reads as a fresh navigation.
+  // (its real verse).
+  //
+  // The exception is a verse-0 reference the extension itself just navigated to — selecting a
+  // chapter's verse-0 superscription segment writes `verseNum: 0` for the chapter already shown,
+  // which is shaped exactly like the spurious echo. A fresh internal-nav marker for that verse-0 key
+  // distinguishes the two: when one exists, this is our own deliberate move to the superscription, so
+  // it passes through (and `consumeInternalNav` clears the marker downstream). A pure read here — no
+  // eviction during render, matching the render-phase mid-reveal guard.
+  //
+  // Every other reference — including a verse-0 reference for a *different* chapter (a genuine chapter
+  // jump, which the loader resolves to the verse-0 superscription when one exists, else to verse 1) —
+  // passes through verbatim. The duplicate-delivery guard reuses the previously committed object when
+  // a re-send is value-equal, so a duplicate never reads as a fresh navigation.
   const liveScrRef = useMemo(() => {
     const prev = liveScrRefRef.current;
     if (
       rawScrRef.verseNum === 0 &&
       rawScrRef.book === prev.book &&
-      rawScrRef.chapterNum === prev.chapterNum
+      rawScrRef.chapterNum === prev.chapterNum &&
+      !isInternalNavMarkerFresh(pendingInternalNavRef.current.get(verseKey(rawScrRef)))
     ) {
       return prev;
     }
@@ -254,17 +280,6 @@ export function InterlinearNavProvider({
   const prevLiveScrRef = liveScrRefRef.current;
   liveScrRefRef.current = liveScrRef;
 
-  /**
-   * Verse keys of internal navigations still awaiting their host round-trip, each mapped to its
-   * `Date.now()` stamp. `navigate(ref, 'internal')` records `verseKey(ref)`; `consumeInternalNav`
-   * removes it on match. Keyed (not a single value) so that rapid successive clicks both stay
-   * pending and neither host delivery is misread as external. The stamp gives each marker a TTL
-   * ({@link INTERNAL_NAV_TTL_MS} — see its doc for why stranded markers must expire), honored by
-   * BOTH readers: `consumeInternalNav` (which also evicts expired markers) and the render-phase
-   * mid-reveal guard (a pure read — no eviction during render).
-   */
-  const pendingInternalNavRef = useRef<Map<string, number>>(new Map());
-
   const navigate = useCallback(
     (newScrRef: SerializedVerseRef, origin: NavOrigin = 'external') => {
       if (origin === 'internal') pendingInternalNavRef.current.set(verseKey(newScrRef), Date.now());

src/components/Interlinearizer.tsx

@@ -212,9 +212,9 @@ function InterlinearizerInner({
    * reference. (The loader's `viewScrRef` freeze normally keeps the two in sync, so this guards a
    * transient.)
    *
-   * Also never navigates to a verse-0 segment (a chapter superscription): the host scroll-group
-   * reference cannot hold verse 0 (it echoes the chapter back), so the token is focused locally
-   * without writing a reference the host would bounce.
+   * A verse-0 segment (a chapter superscription) navigates like any other: the write records an
+   * internal-nav marker so the host's chapter echo is recognized as our own move rather than
+   * bouncing the view back. (See the verse-0 stickiness exception in `InterlinearNavContext`.)
    *
    * @param tokenRef - The word-token ref to focus.
    */
@@ -227,7 +227,7 @@ function InterlinearizerInner({
       if (!seg) return;
       const { current } = scrRefRef;
       if (seg.startRef.book !== current.book) return;
-      if (seg.startRef.verse === 0 || isSameVerse(seg.startRef, current)) return;
+      if (isSameVerse(seg.startRef, current)) return;
       navigate(toSerializedVerseRef(seg.startRef), 'internal');
     },
     [segmentById, tokenSegmentMap, navigate, scrRefRef],
@@ -236,17 +236,17 @@ function InterlinearizerInner({
   /**
    * Updates the active scripture reference (when the verse actually changed) and, when a specific
    * token was clicked, focuses that token. Skips the write to PAPI when the clicked verse matches
-   * the current one, avoiding a gratuitous echo round-trip. Also skips the write for a verse-0
-   * segment (a chapter superscription) — the host scroll-group reference cannot hold verse 0 — so
-   * the superscription's tokens are still focusable even though it can't become the active verse.
+   * the current one, avoiding a gratuitous echo round-trip. A verse-0 segment (a chapter
+   * superscription) writes like any other verse — the internal-nav marker keeps the host's chapter
+   * echo from bouncing the view (see the verse-0 stickiness exception in `InterlinearNavContext`).
    *
    * @param ref - The verse coordinate that was selected.
    * @param tokenRef - The token that was clicked; omitted when the whole segment was selected.
    */
   const handleSegmentSelect = useCallback(
     (ref: ScriptureRef, tokenRef?: string) => {
       const { current } = scrRefRef;
-      if (ref.verse !== 0 && !isSameVerse(ref, current)) {
+      if (!isSameVerse(ref, current)) {
         navigate(toSerializedVerseRef(ref), 'internal');
       }
       if (tokenRef) setFocusedTokenRef(tokenRef);

src/components/SegmentListView.tsx

@@ -181,11 +181,12 @@ export default function SegmentListView({
     recenterOnActive();
   }, [continuousScroll, recenterOnActive]);
 
-  // Segment that wears the active highlight. It follows the focused token's segment so a verse-0
-  // superscription — which cannot become the host's active verse — still highlights when one of its
-  // tokens is focused. Normal navigation keeps the focused token inside the active verse, so this
-  // resolves to the same segment as the `displayScrRef` verse; it only diverges for a verse-0 focus.
-  // Falls back to the active verse when nothing is focused (e.g. the active verse has no word token).
+  // Segment that wears the active highlight. It follows the focused token's segment so the highlight
+  // lands on the segment whose token is focused — including a verse-0 superscription. Normal
+  // navigation keeps the focused token inside the active verse, so this resolves to the same segment
+  // as the `displayScrRef` verse; it can diverge briefly when a focus move and the host echo it
+  // triggers are not yet reconciled. Falls back to the active verse when nothing is focused (e.g. the
+  // active verse has no word token).
   const activeSegmentId = displayFocusedTokenRef
     ? tokenSegmentMap.get(displayFocusedTokenRef)
     : undefined;