feat(ui): BibleReaderNavigation chapter jumps (YPE-5745)

[Dustin-Kelley]

Summary

• Public BibleReaderNavigation with request and focusReference. Host can submit before BibleReader mounts. One pending request; newer replaces older; Reader consumes once.
• Chapter load only (existing book / chapter / versionId). No Web SDK change. Scroll-to-verse and focus are not in this PR.

Stack

1. YPE-5746 Search client — merged into Search (feat(core): wrap platform-core SearchClient (YPE-5746) #180)
2. This PR — YPE-5745 → Search
3. YPE-5748 native Search UI will target this branch

YPE-5747 (scroll/focus) is out of this stack.

Test plan

• Request before mount lands on first Reader render
• Newer request wins; consumed once
• focusReference changes chapter the same way as request
• BibleReaderHandle still only refreshHighlights
• Native toolbar still jumps prev/next after this merge
• pnpm typecheck / pnpm test / pnpm lint from worktree root

Made with Cursor

Confidence Score: 5/5

The PR appears safe to merge.

Summary

The PR adds a public imperative navigation object that lets hosts queue one chapter jump before or after a native Bible Reader mounts.

• Exports BibleReaderNavigation and its factory from the UI package.
• Applies pending book, chapter, and version changes during commit while preserving controlled and persisted reader-location behavior.
• Documents the API and adds coverage for replacement, one-time consumption, pre-mount requests, and focus-reference chapter changes.

Diagram

sequenceDiagram
  participant Host
  participant Navigation as BibleReaderNavigation
  participant Reader as BibleReader
  participant Store as Reader Location Store
  Host->>Navigation: request(reference)
  Navigation->>Navigation: Replace pending request and increment version
  Reader->>Navigation: Read pending request during render
  Reader->>Reader: Render requested book/chapter/version overlay
  Reader->>Navigation: Consume matching version after commit
  Reader->>Store: Persist uncontrolled location fields
  Reader-->>Host: Notify controlled field changes

Loading

_{Reviews (6) · Last reviewed commit: "docs(ui): note one Reader per navigation..."}

[cameronapak]

Review

YPE-5745

Summary

Standards: 2 must-fix. Spec: 0 must-fix. Primary concerns: the exported class exposes reader-owned queue controls, and a combined jump persists intermediate Reader Location snapshots.

Review evidence

• Scope: revision 28af625, YPE-5745, PR history, resolved threads, public declarations, Reader Location behavior, and the Search follow-up boundary.
• Method: independent Standards, Spec, and Correctness passes, followed by source-level verification of each finding.

Behavior or check	Method / command	Result	Evidence source
Navigation requirements	Jira issue and comments, README, CONTEXT.md, implementation and tests	Chapter-only scope and YPE-5748 deferral are satisfied	Coordinator
Public API surface	Generated packages/ui/build/native/bible-reader-navigation.d.ts	Reader-owned getters, subscription, and consume methods are public	Coordinator
Reader Location commit	Traced navigation setters, useControllableState, Zustand persistence, and applyReaderLocation	One jump writes separate field patches instead of one combined snapshot	Coordinator
Tests	pnpm test -- --runInBand	731 passed, 1 skipped	Coordinator
Static checks	pnpm lint; pnpm typecheck	Passed	Coordinator

• Limits: no native-device run; this PR changes coordination rather than visual presentation.
• CI and bot review: all current GitHub checks passed; prior bot findings are resolved and outdated.
• Event: REQUEST_CHANGES.

Written by Code Reviewer bot on behalf of Cam.

[cameronapak]

Review

YPE-5745

Summary

Standards: 0 must-fix. Spec: 0 must-fix. Primary concern: none. The previous public-API and Reader Location findings are resolved.

Review evidence

• Scope: revision 548bcb4, full PR behavior, changes since the prior review, resolved threads, YPE-5745, and the YPE-5748 boundary.
• Method: traced the queue encapsulation, generated declaration surface, external-store consumption, controlled and uncontrolled Reader paths, combined persistence, and single-Reader ownership documentation.

Behavior or check	Method / command	Result	Evidence source
Public navigation API	Built package and inspected generated declaration	Only request and focusReference are public	Coordinator
Combined Reader Location	Source trace and focused regression test	One complete patch persists after commit	Coordinator
Navigation and Reader tests	Focused Jest suites	14 passed	Coordinator
Full test suite	pnpm test -- --runInBand	730 passed, 1 skipped	Coordinator
Static checks and build	pnpm lint, UI typecheck, UI build	Passed	Coordinator

• Limits: no native-device run; the change is coordination rather than visual presentation. Existing asynchronous test-harness warnings remain pre-existing and non-blocking.
• CI and bot review: all current GitHub checks passed; all prior review threads are resolved.
• Event: APPROVE.

Written by Code Reviewer bot on behalf of Cam.

[cameronapak]

praise: Persisting the complete destination before the individual setters keeps Reader Location coherent without losing the first-paint overlay.

For Agents: atomic navigation commit

This resolves the prior mixed-location failure while preserving controlled callbacks and the consume-after-commit safety. The added regression test also checks the observable patch count and final stored values, so a future return to per-field writes will fail clearly.

Written by Code Reviewer bot on behalf of Cam.