platform: stop stale book echo when the host navigates across books

[tjcouch-sil]

Problem

When a host application (Platform.Bible) navigates the scripture reference across a book boundary — e.g. NUM 1 → "previous chapter" → LEV 27:1 — the editor echoes a corrupted reference back through onScrRefChange: the OLD book with the NEW chapter/verse (NUM 27:1). The host's navigation is overwritten and the user lands on chapter 27 of the wrong book.

What broke, and where

#457 added the BookNode book-sync listener (skipInitialization: false) to ScriptureReferencePlugin, so the ref's book follows the loaded document — a legitimate and still-desired behavior. That PR also added scrRefRef/onScrRefChangeRef refs specifically so the listener could read current values without re-registering (its comment says it should "only run when BookNodes are created/updated").

However, the listener was registered inside the pre-existing useEffect keyed on [editor, chapterNum, verseNum]. Every chapter/verse-only navigation therefore tears down and re-registers the listener, and because it uses skipInitialization: false, each re-registration replays initialization against the still-mounted old document (the new book's content loads async in the host). During that window scrRefRef.current already holds the new ref (LEV 27:1) while the stale document's BookNode still reads NUM → the listener fires onScrRefChange({ ...current, book: 'NUM' }) → NUM 27:1.

Fix — preserving #457's intent

Split the two BookNode listeners into separate effects:

• The book-sync listener now registers once per editor ([editor] deps), reading current values through the refs platform: fix BCV display so verse updates only when cursor is after the verse number #457 already added for exactly this purpose. Its mount-time initialization still performs the legitimate book correction platform: fix BCV display so verse updates only when cursor is after the verse number #457 introduced, and it still reacts to genuine BookNode created/updated mutations — it just no longer replays against a stale document on every chapter/verse navigation.
• The cursor-move listener keeps its original deps and behavior, byte-identical.

This completes the design #457's own refs and comment describe, rather than changing what the listener is for.

Testing

• New regression test: ref moves to a different book while the old document is still loaded → onScrRefChange must NOT fire with the old book. Fails on the pre-fix code with exactly the production echo shape; passes with the fix.
• The three pre-existing book-sync tests (mount-time correction) pass unmodified; full platform-editor suite 116 passed / 3 skipped; whole-monorepo test/lint/typecheck/format clean.
• Live-verified in Platform.Bible via a local yalc build: NUM 1 → previous chapter lands and stays on LEV 27:1 (polled ~5s for late echoes); same-book navigation, in-editor verse-click ref updates, in-editor book jumps, and fresh-editor loads all behave.

AI-assisted (Claude Code)

🤖 Generated with Claude Code

---

This change is 

[codesandbox]

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders

Open Preview

• dev:perf-react
• dev:perf-vanilla
• dev:platform

[lyonsil]

lgtm - This appears to fix the bug flagged by TJ without causing new bugs

[lyonsil]

@lyonsil reviewed 2 files and all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved.

[katherinejensen00]

This bug fix looks really helpful. Thanks for working on this, TJ! Just one small optional comment clarity change. I will go ahead and approve this.

@katherinejensen00 reviewed 2 files and all commit messages, and made 2 comments.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on tjcouch-sil).

---

packages/platform/src/editor/ScriptureReferencePlugin.tsx line 98 at r2 (raw file):
NIT Claude Finding

Small accuracy fix: this listener actually fires on every non-destroyed BookNode mutation (including in-editor "updated" ones), not only mount + document swap. What keeps the stray firings harmless is the code !== current.book guard, not a limited firing set — worth wording it that way so nobody later relies on a firing-frequency invariant that doesn't hold.

Suggested rewrite of the book-sync comment (replacing lines 90–99), corrected and tightened:

  // Book node sync: correct scrRef.book to match the currently loaded document's BookNode.
  // Fires on every non-destroyed BookNode mutation (initial-mount replay + later swaps); the
  // `code !== current.book` guard below is what makes stray firings harmless. Registered once
  // per editor ([editor] only), NOT re-registered on chapterNum/verseNum change: the refs
  // already keep values fresh, and re-registering would replay skipInitialization: false against
  // the still-mounted (stale) document on every navigation, echoing the OLD book with the NEW
  // chapter/verse back to the host.

[katherinejensen00]

Thanks for improving that comment, TJ! Looks good.

@katherinejensen00 reviewed 1 file and all commit messages, made 1 comment, and resolved 1 discussion.
Reviewable status: complete! all files reviewed, all discussions resolved.