Extract useLatestRef/useRecenterSnap hooks, fix verse-0 echo nav

Author: alex-rawlings-yyc

src/__tests__/components/InterlinearNavContext.test.tsx

@@ -105,6 +105,38 @@ describe('InterlinearNavContext', () => {
     expect(result.current.rawScrRef).toEqual(ref);
   });
 
+  it('keeps the current verse when the host echoes a verse-0 reference for the chapter already shown', () => {
+    // After a verse navigation the host re-broadcasts the chapter as a separate verse-0 reference.
+    // Normalizing that to verse 1 would read as a fresh move off the verse the user is on, so a
+    // verse-0 echo for the same book+chapter must stay sticky on the current verse.
+    const { result, setRef, rerender } = renderNavMutable({
+      book: 'GEN',
+      chapterNum: 3,
+      verseNum: 7,
+    });
+    expect(result.current.liveScrRef).toEqual({ book: 'GEN', chapterNum: 3, verseNum: 7 });
+
+    act(() => setRef({ book: 'GEN', chapterNum: 3, verseNum: 0 }));
+    rerender();
+
+    expect(result.current.liveScrRef).toEqual({ book: 'GEN', chapterNum: 3, verseNum: 7 });
+  });
+
+  it('normalizes a verse-0 reference that names a different chapter (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 still normalizes to that chapter's first verse.
+    const { result, setRef, rerender } = renderNavMutable({
+      book: 'GEN',
+      chapterNum: 3,
+      verseNum: 7,
+    });
+
+    act(() => setRef({ book: 'GEN', chapterNum: 4, verseNum: 0 }));
+    rerender();
+
+    expect(result.current.liveScrRef).toEqual({ book: 'GEN', chapterNum: 4, verseNum: 1 });
+  });
+
   it('throws when used outside a provider', () => {
     expect(() => renderHook(() => useInterlinearNav())).toThrow(
       'useInterlinearNav must be used within an InterlinearNavProvider',

src/__tests__/components/InterlinearizerLoader.test.tsx

@@ -1190,27 +1190,20 @@ describe('InterlinearizerLoader', () => {
       expect(fadeOpacity()).toBe('0');
     });
 
-    it('freezes the scrRef handed to Interlinearizer until the new book loads', () => {
+    it('shows the Loading curtain (not the old book) during a cross-book swap', () => {
       const { setRef, rerenderNow } = renderLoader({ book: 'GEN', chapterNum: 1, verseNum: 5 });
-      expect(capturedInterlinearizerProps?.scrRef).toEqual({
-        book: 'GEN',
-        chapterNum: 1,
-        verseNum: 5,
-      });
+      expect(screen.getByTestId('interlinearizer')).toBeInTheDocument();
 
-      // Cross-book jump to MAT while the loaded book is still GEN (the window before the USJ arrives
-      // / Interlinearizer remounts). The still-mounted views must keep receiving the last in-book GEN
-      // reference, never the out-of-book MAT one — otherwise they reseed focus and scroll toward a
-      // verse absent from the mounted book, the pre-fade shuffle this freeze exists to prevent.
+      // Cross-book jump to MAT while the loaded book is still GEN (the window before the USJ arrives /
+      // Interlinearizer remounts). Rather than leave the previous book's views mounted — where they
+      // would show through the fade as the swap happens — the loader shows the Loading curtain, so
+      // nothing of either book is visible until the new one mounts and fades in.
       setRef({ book: 'MAT', chapterNum: 5, verseNum: 3 });
       rerenderNow();
-      expect(capturedInterlinearizerProps?.scrRef).toEqual({
-        book: 'GEN',
-        chapterNum: 1,
-        verseNum: 5,
-      });
+      expect(screen.queryByTestId('interlinearizer')).not.toBeInTheDocument();
+      expect(screen.getByText('Loading…')).toBeInTheDocument();
 
-      // Once MAT's book data arrives, Interlinearizer remounts on it and receives the live MAT ref.
+      // Once MAT's book data arrives, Interlinearizer mounts on it and receives the live MAT ref.
       mockBookData({ book: { ...GEN_1_1_BOOK, id: 'MAT', bookRef: 'MAT' } });
       rerenderNow();
       expect(capturedInterlinearizerProps?.scrRef).toEqual({

src/components/ContinuousView.tsx

@@ -13,6 +13,7 @@ import type { LinkSlot, TokenGroup } from '../types/token-layout';
 import { buildRenderUnits, groupTokens, resolveFocusContext } from '../utils/token-layout';
 import { useArcPaths } from '../hooks/useArcPaths';
 import { usePhraseHoverState } from '../hooks/usePhraseHoverState';
+import useLatestRef from '../hooks/useLatestRef';
 import MemoizedArcOverlay from './ArcOverlay';
 import { RECENTER_FADE_MS, RECENTER_FADE_TRANSITION_STYLE } from './recenter-fade';
 
@@ -330,17 +331,15 @@ export default function ContinuousView({
     focusedTokenRef !== undefined ? tokenSegmentMap.get(focusedTokenRef) : undefined;
 
   /** Ref mirror of the target so the post-scroll timeout reads the latest value without a dep. */
-  const targetActiveSegmentIdRef = useRef(targetActiveSegmentId);
-  targetActiveSegmentIdRef.current = targetActiveSegmentId;
+  const targetActiveSegmentIdRef = useLatestRef(targetActiveSegmentId);
 
   /** Snaps the committed active segment to the current target; runs after an internal-nav scroll. */
   const commitPendingActiveSegment = useCallback(() => {
     setCommittedActiveSegmentId(targetActiveSegmentIdRef.current);
-  }, []);
+  }, [targetActiveSegmentIdRef]);
 
   /** Ref mirror of `onFocusedTokenRefChange` so callbacks never need it as a dep. */
-  const onFocusedTokenRefChangeRef = useRef(onFocusedTokenRefChange);
-  onFocusedTokenRefChangeRef.current = onFocusedTokenRefChange;
+  const onFocusedTokenRefChangeRef = useLatestRef(onFocusedTokenRefChange);
 
   /**
    * Emits a focus change that originated _inside_ the strip (arrow nav, phrase click, edit-mode
@@ -352,10 +351,13 @@ export default function ContinuousView({
    *
    * @param ref - The word-token ref to focus.
    */
-  const emitInternalFocus = useCallback((ref: string) => {
-    internalFocusedTokenRefRef.current = ref;
-    onFocusedTokenRefChangeRef.current(ref);
-  }, []);
+  const emitInternalFocus = useCallback(
+    (ref: string) => {
+      internalFocusedTokenRefRef.current = ref;
+      onFocusedTokenRefChangeRef.current(ref);
+    },
+    [onFocusedTokenRefChangeRef],
+  );
 
   // Notify the parent of the initially-focused token on mount so the segment list scrolls the
   // active verse into view on first render. Only fires when no token was already focused.

src/components/InterlinearNavContext.tsx

@@ -165,7 +165,31 @@ export function InterlinearNavProvider({
 }>) {
   const [rawScrRef, setScrRef, scrollGroupId, setScrollGroupId] = useWebViewScrollGroupScrRef();
 
-  const liveScrRef = useMemo(() => normalizeScrRef(rawScrRef), [rawScrRef]);
+  /**
+   * The last committed {@link liveScrRef}, mirrored so the verse-0 stickiness below can compare the
+   * incoming `rawScrRef` against the verse currently shown.
+   */
+  const liveScrRefRef = useRef<SerializedVerseRef>(normalizeScrRef(rawScrRef));
+
+  // 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). Normalizing that to
+  // verse 1 unconditionally would read as a fresh navigation to the chapter's first verse, fading and
+  // recentering the views off the verse the user is actually on. So a verse-0 reference that names the
+  // book+chapter already shown is treated as sticky: keep the current `liveScrRef` (its real verse)
+  // rather than snapping to verse 1. A verse-0 reference for a *different* chapter is a genuine
+  // chapter jump and normalizes to verse 1 as before.
+  const liveScrRef = useMemo(() => {
+    const prev = liveScrRefRef.current;
+    if (
+      rawScrRef.verseNum === 0 &&
+      rawScrRef.book === prev.book &&
+      rawScrRef.chapterNum === prev.chapterNum
+    ) {
+      return prev;
+    }
+    return normalizeScrRef(rawScrRef);
+  }, [rawScrRef]);
+  liveScrRefRef.current = liveScrRef;
 
   /**
    * Verse keys of internal navigations still awaiting their host round-trip. A `navigate(ref,

src/components/InterlinearizerLoader.tsx

@@ -5,7 +5,7 @@ import type { InterlinearProject, TextAnalysis } from 'interlinearizer';
 import { TabToolbar } from 'platform-bible-react';
 import type { SelectMenuItemHandler } from 'platform-bible-react';
 import { isPlatformError } from 'platform-bible-utils';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import useInterlinearizerBookData from '../hooks/useInterlinearizerBookData';
 import useOptimisticBooleanSetting from '../hooks/useOptimisticBooleanSetting';
 import type { InterlinearProjectSummary } from '../types/interlinear-project-summary';
@@ -221,7 +221,14 @@ function InterlinearizerLoaderInner({
     isHideInactiveLinkButtonsLoading ||
     isSimplifyPhrasesLoading ||
     isChapterLabelInVerseLoading;
-  const showLoading = isLoading || isAnalysisLoading || isSettingLoading;
+  // True during a cross-book swap: the live `scrRef` already names the new book but the loaded `book`
+  // is still the previous one (its USJ hasn't arrived yet). The old `Interlinearizer` is still
+  // mounted here; showing it (even frozen on its last in-book reference) lets the previous book's
+  // components stay visible while the new book loads, so the swap is seen before the fade hides it.
+  // Treating this window as loading swaps the old view for the Loading… curtain immediately, so
+  // nothing of either book shows until the new one has mounted and fades in.
+  const isCrossBookSwap = !!book && scrRef.book !== book.bookRef;
+  const showLoading = isLoading || isAnalysisLoading || isSettingLoading || isCrossBookSwap;
   const isLoaded = !hasError && !showLoading && !!book;
 
   // Abort any in-flight cross-book fade when the new book fails to load, so the error is revealed
@@ -230,22 +237,6 @@ function InterlinearizerLoaderInner({
     if (hasError) cancelFade();
   }, [hasError, cancelFade]);
 
-  /**
-   * The scripture reference handed to {@link Interlinearizer}. While a cross-book navigation is in
-   * flight, `scrRef` already names the new book but the loaded `book` is still the previous one
-   * (its USJ hasn't arrived), so the still-mounted views would react to a verse absent from the
-   * mounted book — reseeding focus and scrolling toward it, a visible shuffle behind/before the
-   * fade. Gating on `book.bookRef` keeps the views on a reference that matches the book they
-   * actually render: the live `scrRef` only once the loaded book matches it, otherwise the last
-   * in-book reference. Once the new book's USJ arrives, `Interlinearizer` remounts on it (it is
-   * keyed by `book.bookRef`, so a book change tears down the old instance rather than updating it
-   * in place with carried-over scroll/focus state) and immediately receives the live (new-book)
-   * reference, so it seeds focus on the intended verse and reports settled.
-   */
-  const lastInBookScrRefRef = useRef(scrRef);
-  if (book && scrRef.book === book.bookRef) lastInBookScrRefRef.current = scrRef;
-  const viewScrRef = book && scrRef.book === book.bookRef ? scrRef : lastInBookScrRefRef.current;
-
   const [modal, setModal] = useState<ModalState>('none');
 
   const [phraseMode, setPhraseMode] = useState<PhraseMode>({ kind: 'view' });
@@ -376,7 +367,7 @@ function InterlinearizerLoaderInner({
             key={`${activeProject?.id ?? ''}:${book.bookRef}`}
             book={book}
             continuousScroll={continuousScroll}
-            scrRef={viewScrRef}
+            scrRef={scrRef}
             analysisLanguage={analysisLanguage}
             initialAnalysis={activeProjectAnalysis}
             onSaveAnalysis={handleSaveAnalysis}

src/hooks/useLatestRef.ts

@@ -0,0 +1,19 @@
+import type { RefObject } from 'react';
+import { useRef } from 'react';
+
+/**
+ * Mirrors a value into a ref whose `.current` always holds the latest render's value, reassigned on
+ * every render (before effects run). Lets a `useCallback`/effect read the current value through the
+ * ref without listing it as a dependency, so the callback keeps a stable identity even when the
+ * value changes identity each render — the PAPI host, for instance, hands `scrRef` back as a fresh
+ * object on many renders, and closing over it directly would churn the identity of any callback
+ * that reads it. Reading through the ref decouples that churn.
+ *
+ * @param value - The value to mirror; the returned ref's `.current` is set to it on every render.
+ * @returns A stable ref object whose `.current` tracks the latest `value`.
+ */
+export default function useLatestRef<T>(value: T): RefObject<T> {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}