[alex-rawlings-yyc]

Closes #436. Part of Phase 2 (#425).

Host. bookService serves two new commands, interlinearizer.getBookOutline and interlinearizer.getSegments. Both are addressed by source project and book, and both take the WebView's boundary delta as JSON. The host segments the kept tokenized book by that delta, re-anchoring splits as reanchorSegmentation does, and keeps the result for the latest delta, so an outline and its pages segment the book once. The outline lists every segment's id, start, verse starts, heading, token and word-token counts and text length, without its text. A page is a run of whole segments at outline indexes. Both carry the book's textVersion. Page requests reuse the kept book without reading the language tag again.

WebView. The new useSegmentPages hook fetches the outline and then the pages around the opening verse, and publishes them together. On a boundary edit it also fetches the pages around the range last shown, so the old list stays up until the new one is ready. Pages load into a store outside React state, one request per run of missing pages, and only the segment list re-renders when one arrives. SegmentListView reads labels, chapters, merge eligibility and height prediction from the outline. Mounted segments come from their pages, with a placeholder at the predicted height until a page arrives. useBookIndexes, focus, the continuous strip and stale free-translation placement still use the locally segmented whole book, as the plan allows until #437, #450, #451 and #455.

Behavior changes. A textVersion mismatch between the host and the WebView's tokenized book reloads the book, so a Scripture edit now shows at the next outline or page fetch. #438 makes that immediate.

Perf harness. The host times getBookOutline and getSegments, with resegment and serialize steps. The WebView records outline-fetch, outline-parse, page-fetch and page-parse. Opening the view samples the outline call with transport, and each page call on the host side.

Verified.

• In the app over CDP, on WEB, the rendered segment list matched the host's outline with no placeholders left once loaded. That held on opening Genesis, after merging 1:2 into 1:1 and undoing it, after scrolling to the end of the book, after jumping to 30:1, and after switching to Exodus. The existing CDP feature tests pass.
• In a dev build on Psalms, compared with main over paint-gated drags, jumps and steady scrolls, the branch costs the same within run-to-run noise. A page fetch takes about 15 ms, of which 0.4–2 ms is host time.

---

This change is 

Summary by CodeRabbit

• New Features

  • Segment pages load as needed while navigating the interlinearizer, with placeholders shown for segments that are not yet loaded.
  • Added support for retrieving book outlines and specific segment ranges, including custom segmentation.
  • Reloading book data now fetches the latest version.

• Performance

  • Performance measurements now include outline and segment-page fetches and parsing.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 58c0f4f5-13ae-434f-8e3f-1fa9c503d848

📝 Walkthrough

The host now serves book outlines and segment pages. The client fetches pages around the visible window and navigation anchor, then renders placeholders for unloaded segments. Performance measurements now include outline and page fetch and parse timings.

Changes: Paged segment data flow

Layer / File(s)	Summary
Outline and page host APIs src/types/segment-pages.ts, src/utils/book-outline.ts, src/services/bookService.ts, src/main.ts, src/types/interlinearizer.d.ts, src/utils/segmentation.ts, src/__tests__/services/*, src/__tests__/main.test.ts, src/__tests__/utils/book-outline.test.ts, src/__tests__/utils/segmentation.test.ts	The host commands return a book outline or a requested segment range. The service retains tokenized books and caches segmentation results.
Client page loading src/hooks/useSegmentPages.ts, src/hooks/useInterlinearizerBookData.ts, src/__tests__/hooks/useSegmentPages.test.ts, src/__tests__/hooks/useInterlinearizerBookData.test.ts	useSegmentPages loads an outline and batches missing page requests. It tracks loading, errors, retries, and stale responses. The book-data hook provides a reload callback.
Paged segment-list rendering src/components/InterlinearizerLoader.tsx, src/components/Interlinearizer.tsx, src/components/SegmentListView.tsx, src/hooks/useSegmentHeights.ts, src/hooks/useSegmentWindow.ts, src/utils/segment-heights.ts, src/utils/segment-labels.ts, src/utils/verse-ref.ts, src/utils/verse-superscripts.ts, src/__tests__/components/*, src/__tests__/hooks/useSegmentHeights.test.ts, src/__tests__/hooks/useSegmentWindow.test.ts, src/__tests__/utils/segment-heights.test.ts, src/__tests__/test-helpers.ts, AGENTS.md	The loader waits for pages and combines page and book errors. The segment list uses outline metadata for labels, heights, and windowing, and renders placeholders until segment data is available.
Paged-data performance measures e2e-tests/tests/perf/*, perf/summary/cli.ts	The open and book-switch measurements include outline and page fetch and parse timings. The summary adds labels for these measures and the resegment phase.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant InterlinearizerLoader
  participant useSegmentPages
  participant OutlineCommand as interlinearizer.getBookOutline
  participant SegmentCommand as interlinearizer.getSegments
  participant BookService as bookService
  participant SegmentListView
  InterlinearizerLoader->>useSegmentPages: supply verse book and segmentation
  useSegmentPages->>OutlineCommand: request outline
  OutlineCommand->>BookService: getBookOutline
  BookService-->>OutlineCommand: serialized outline
  OutlineCommand-->>useSegmentPages: outline
  useSegmentPages->>SegmentCommand: request initial page range
  SegmentCommand->>BookService: getSegments
  BookService-->>SegmentCommand: serialized segment page
  SegmentCommand-->>useSegmentPages: segment page
  useSegmentPages-->>InterlinearizerLoader: publish pages
  InterlinearizerLoader->>SegmentListView: pass pages
  SegmentListView->>useSegmentPages: load pages around window and anchor

Loading

Merge Risk: 🔵 Low · up to 45e87

A transient failure while opening a book can leave it on an error panel until the user changes books or otherwise restarts loading. Add a bounded retry before merging.

Pre-merge checks: 5

Check name	Status	Explanation
Linked Issues check		Issue #436 is the active direct target. The PR adds interlinearizer.getBookOutline and interlinearizer.getSegments, applies the source project, book, and boundary delta, caches the tokenized book …
Out of Scope Changes check		The changed files support issue #436. Service, command, type, hook, component, utility, test, and performance changes implement or verify the outline and segment-page flow. Retry handling and outline-…
Docstring Coverage		Docstring coverage is 86.25% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 80 functions across 32 files.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: adding host support for serving book outlines and segment pages.

Full details: Linked Issues check

Explanation

Issue #436 is the active direct target. The PR adds interlinearizer.getBookOutline and interlinearizer.getSegments, applies the source project, book, and boundary delta, caches the tokenized book and latest segmentation, returns outline metadata and segment pages with textVersion, and records fetch and processing timings. useSegmentPages loads the outline and pages, retains the prior list during replacement, retries failed page runs, and reloads on text-version changes. SegmentListView uses outline data for labels, heights, windowing, and merge eligibility, and uses height-preserving placeholders for unloaded pages. Tests cover command forwarding, service behavior, hook loading and recovery, and component rendering. Local free-translation placement remains local as allowed by #436 pending #450.

Full details: Out of Scope Changes check

Explanation

The changed files support issue #436. Service, command, type, hook, component, utility, test, and performance changes implement or verify the outline and segment-page flow. Retry handling and outline-error recovery support the required page loading behavior. No demonstrated unrelated product change or unrelated cleanup is present.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alex-rawlings-yyc]

Added #451 to the description's list.

Retried: the outline and the opening pages now go through one attempt that retries on PAGE_RETRY_DELAYS_MS while the request is current, and the error panel shows only once those run out. After a boundary edit the current list stays up through the retries, but a final failure still shows the panel rather than leaving the list on the old boundaries with nothing refetching. One knock-on: a failure that will never succeed now takes about 21 s to reach the panel.

@alex-rawlings-yyc made 10 comments.
Reviewable status: 0 of 33 files reviewed, 9 unresolved discussions (waiting on alex-rawlings-yyc and imnasnainaec).

[imnasnainaec]

@imnasnainaec reviewed 34 files and all commit messages, and resolved 9 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on alex-rawlings-yyc).