diff --git a/__mocks__/papi-frontend-react.ts b/__mocks__/papi-frontend-react.ts
index 52c6e6c0..e7f99bb6 100644
--- a/__mocks__/papi-frontend-react.ts
+++ b/__mocks__/papi-frontend-react.ts
@@ -4,15 +4,29 @@
  */
 
 /**
- * Mock for `useProjectData`. Returns a `Proxy` whose property accesses each yield a function
- * returning `[undefined, jest.fn(), false]`, matching the real hook's `[data, setter, isLoading]`
- * tuple without requiring a live data provider.
+ * Known data-provider method names exposed by this mock. Tests that call an unlisted method will
+ * receive a descriptive error rather than silently returning `undefined`, which mirrors the real
+ * PAPI behaviour where requesting an unsupported provider key is a programmer error.
+ */
+const KNOWN_PROJECT_DATA_METHODS = new Set(['BookUSJ']);
+
+/**
+ * Mock for `useProjectData`. Returns an object whose known methods each return
+ * `[undefined, jest.fn(), false]`, matching the real hook's `[data, setter, isLoading]` tuple.
+ * Accessing an unknown method throws to catch misspelled provider keys in tests.
  */
 const useProjectData = jest.fn(() =>
   new Proxy(
     {},
     {
-      get: () => () => [undefined, jest.fn(), false],
+      get(_target, prop: string | symbol) {
+        if (typeof prop === 'string' && KNOWN_PROJECT_DATA_METHODS.has(prop)) {
+          return () => [undefined, jest.fn(), false];
+        }
+        throw new Error(
+          `useProjectData mock: unknown method "${String(prop)}". Add it to KNOWN_PROJECT_DATA_METHODS if intentional.`,
+        );
+      },
     },
   ),
 );
diff --git a/src/__tests__/components/ContinuousView.test.tsx b/src/__tests__/components/ContinuousView.test.tsx
index c5a68678..25d2dec9 100644
--- a/src/__tests__/components/ContinuousView.test.tsx
+++ b/src/__tests__/components/ContinuousView.test.tsx
@@ -4,9 +4,39 @@
 
 import { act, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import type { Book } from 'interlinearizer';
+import type { Book, Token } from 'interlinearizer';
 import ContinuousView from '../../components/ContinuousView';
 
+jest.mock('../../components/PhraseBox', () => ({
+  __esModule: true,
+  default: ({
+    isFocused = false,
+    index,
+    onClick,
+    tokens,
+  }: {
+    isFocused?: boolean;
+    index?: number;
+    onClick?: (index?: number) => void;
+    tokens: Token[];
+  }) => (
+    <button
+      data-focus-state={isFocused ? 'focused' : 'default'}
+      data-phrase-box="true"
+      onClick={() => onClick?.(index)}
+      type="button"
+    >
+      {tokens.map((t) => t.surfaceText).join(' ')}
+    </button>
+  ),
+}));
+
+jest.mock('../../components/TokenChip', () => ({
+  __esModule: true,
+  default: ({ token }: { token: Token }) => <span>{token.surfaceText}</span>,
+  TokenChip: ({ token }: { token: Token }) => <span>{token.surfaceText}</span>,
+}));
+
 // ---------------------------------------------------------------------------
 // Test fixtures
 // ---------------------------------------------------------------------------
@@ -71,7 +101,12 @@ function makeBook(overrides?: Partial<Book>): Book {
   };
 }
 
-/** A two-chapter book: chapter 1 has one segment, chapter 2 has one segment. */
+/**
+ * Builds a two-chapter Book fixture: chapter 1 has one segment ("Alpha"), chapter 2 has one segment
+ * ("Beta"). Used to exercise cross-chapter traversal and verse-jump behaviour.
+ *
+ * @returns A two-chapter Book.
+ */
 function makeTwoChapterBook(): Book {
   return {
     id: 'GEN',
@@ -114,7 +149,12 @@ function makeTwoChapterBook(): Book {
   };
 }
 
-/** A book with exactly one token (minimal edge case). */
+/**
+ * Builds a Book with exactly one word token in one segment. Used to assert that both navigation
+ * arrows are disabled when the strip has nowhere to move.
+ *
+ * @returns A single-token Book.
+ */
 function makeSingleTokenBook(): Book {
   return {
     id: 'GEN',
@@ -188,7 +228,12 @@ function makeMixedBook(): Book {
   };
 }
 
-/** A book where every token is non-word, so phraseEntries is empty. */
+/**
+ * Builds a Book whose only token is punctuation, so phraseEntries is empty. Used to exercise the
+ * code path where ContinuousView renders with no word tokens to navigate between.
+ *
+ * @returns A word-free Book.
+ */
 function makeWordFreeBook(): Book {
   return {
     id: 'GEN',
diff --git a/src/__tests__/components/Interlinearizer.test.tsx b/src/__tests__/components/Interlinearizer.test.tsx
index 1f5cf64f..a9c2ad1f 100644
--- a/src/__tests__/components/Interlinearizer.test.tsx
+++ b/src/__tests__/components/Interlinearizer.test.tsx
@@ -4,13 +4,20 @@
 
 import type { SerializedVerseRef } from '@sillsdev/scripture';
 import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import type { Book } from 'interlinearizer';
+import type { Book, Segment } from 'interlinearizer';
 import Interlinearizer from '../../components/Interlinearizer';
 
-// Store captured props so tests can simulate callbacks
+// Store captured props so tests can inspect what Interlinearizer passes down
 let capturedContinuousViewProps: Record<string, unknown> = {};
 
+type CapturedSegmentViewProps = {
+  segment: Segment;
+  displayMode?: string;
+  isActive?: boolean;
+  onClick?: (ref: { book: string; chapter: number; verse: number }) => void;
+};
+let capturedSegmentViewPropsList: CapturedSegmentViewProps[] = [];
+
 jest.mock('../../components/ContinuousView', () => ({
   __esModule: true,
   default: (props: Record<string, unknown>) => {
@@ -19,6 +26,18 @@ jest.mock('../../components/ContinuousView', () => ({
   },
 }));
 
+jest.mock('../../components/SegmentView', () => ({
+  __esModule: true,
+  SegmentView: ({ segment, ...rest }: CapturedSegmentViewProps) => {
+    capturedSegmentViewPropsList.push({ segment, ...rest });
+    return <div data-testid="segment-view" data-segment-id={segment.id} />;
+  },
+  default: ({ segment, ...rest }: CapturedSegmentViewProps) => {
+    capturedSegmentViewPropsList.push({ segment, ...rest });
+    return <div data-testid="segment-view" data-segment-id={segment.id} />;
+  },
+}));
+
 const defaultScrRef: SerializedVerseRef = { book: 'GEN', chapterNum: 1, verseNum: 1 };
 
 /** Pre-built Book with one GEN 1:1 segment. */
@@ -90,31 +109,13 @@ const GEN_1_MULTI_BOOK: Book = {
   ],
 };
 
-/** Book with a non-word (punctuation) token — exercises the non-word chip branch. */
-const GEN_1_1_PUNCTUATION_BOOK: Book = {
-  id: 'GEN',
-  bookRef: 'GEN',
-  textVersion: 'v1',
-  segments: [
-    {
-      id: 'GEN 1:1',
-      startRef: { book: 'GEN', chapter: 1, verse: 1 },
-      endRef: { book: 'GEN', chapter: 1, verse: 1 },
-      baselineText: '.',
-      tokens: [
-        {
-          id: 'GEN 1:1:0',
-          surfaceText: '.',
-          writingSystem: 'en',
-          type: 'punctuation',
-          charStart: 0,
-          charEnd: 1,
-        },
-      ],
-    },
-  ],
-};
-
+/**
+ * Renders an Interlinearizer component with sensible defaults, allowing individual props to be
+ * overridden per test.
+ *
+ * @param options - Partial props to merge over the defaults.
+ * @returns The render result from @testing-library/react.
+ */
 function renderInterlinearizer({
   book = GEN_1_1_BOOK,
   bookSegments = GEN_1_1_BOOK.segments,
@@ -142,12 +143,13 @@ function renderInterlinearizer({
 describe('Interlinearizer', () => {
   beforeEach(() => {
     capturedContinuousViewProps = {};
+    capturedSegmentViewPropsList = [];
   });
 
-  it('renders token chips when the tokenized book has a segment for the current reference', () => {
+  it('renders a SegmentView when the tokenized book has a segment for the current reference', () => {
     renderInterlinearizer();
 
-    expect(screen.getByText('In')).toBeInTheDocument();
+    expect(screen.getAllByTestId('segment-view')).toHaveLength(1);
   });
 
   it('shows a no-verse message when the tokenized book has no segments at all', () => {
@@ -156,56 +158,48 @@ describe('Interlinearizer', () => {
     expect(screen.getByText(/no verse data for gen 1\./i)).toBeInTheDocument();
   });
 
-  it('renders all segments in the current chapter', () => {
+  it('renders a SegmentView for every segment in the current chapter', () => {
     renderInterlinearizer({ bookSegments: GEN_1_MULTI_BOOK.segments });
 
-    expect(screen.getByText('In')).toBeInTheDocument();
-    expect(screen.getByText('And')).toBeInTheDocument();
+    expect(screen.getAllByTestId('segment-view')).toHaveLength(2);
+    expect(capturedSegmentViewPropsList[0].segment.id).toBe('GEN 1:1');
+    expect(capturedSegmentViewPropsList[1].segment.id).toBe('GEN 1:2');
   });
 
-  it('highlights only the segment matching the current verse', () => {
-    const { container } = renderInterlinearizer({ bookSegments: GEN_1_MULTI_BOOK.segments });
+  it('passes isActive=true only to the segment matching the current verse', () => {
+    renderInterlinearizer({ bookSegments: GEN_1_MULTI_BOOK.segments });
 
-    // defaultScrRef is GEN 1:1, so verse 1 is active
-    const activeSegments = container.querySelectorAll('button[aria-current="true"]');
-    expect(activeSegments).toHaveLength(1);
+    // defaultScrRef is GEN 1:1
+    expect(capturedSegmentViewPropsList[0].isActive).toBe(true);
+    expect(capturedSegmentViewPropsList[1].isActive).toBeFalsy();
   });
 
-  it('shows all chapter segments when navigating to a title reference (verse 0)', () => {
+  it('renders all segments when navigating to a title reference (verse 0)', () => {
     const titleRef: SerializedVerseRef = { book: 'GEN', chapterNum: 1, verseNum: 0 };
     renderInterlinearizer({ bookSegments: GEN_1_MULTI_BOOK.segments, scrRef: titleRef });
 
-    expect(screen.getByText('In')).toBeInTheDocument();
-    expect(screen.getByText('And')).toBeInTheDocument();
-  });
-
-  it('renders non-word tokens as muted chips', () => {
-    renderInterlinearizer({ bookSegments: GEN_1_1_PUNCTUATION_BOOK.segments });
-
-    expect(screen.getByText('.')).toBeInTheDocument();
+    expect(screen.getAllByTestId('segment-view')).toHaveLength(2);
   });
 
-  it('calls setScrRef with the segment ref when a verse box is clicked', async () => {
+  it('calls setScrRef with the segment ref when a verse box is clicked', () => {
     const mockSetScrRef = jest.fn();
     renderInterlinearizer({ bookSegments: GEN_1_MULTI_BOOK.segments, setScrRef: mockSetScrRef });
 
-    await userEvent.click(screen.getByText('And'));
+    capturedSegmentViewPropsList[1].onClick?.({ book: 'GEN', chapter: 1, verse: 2 });
 
     expect(mockSetScrRef).toHaveBeenCalledWith({ book: 'GEN', chapterNum: 1, verseNum: 2 });
   });
 
-  it('renders segments in baseline-text mode when continuousScroll is true', () => {
+  it('passes displayMode="baseline-text" to SegmentView when continuousScroll is true', () => {
     renderInterlinearizer({ continuousScroll: true });
 
-    expect(screen.getByText('In the beginning.')).toBeInTheDocument();
-    expect(screen.queryByText('In')).not.toBeInTheDocument();
+    expect(capturedSegmentViewPropsList[0].displayMode).toBe('baseline-text');
   });
 
-  it('renders all chapter segments in baseline-text mode when continuousScroll is true', () => {
+  it('passes displayMode="baseline-text" to all SegmentViews when continuousScroll is true', () => {
     renderInterlinearizer({ bookSegments: GEN_1_MULTI_BOOK.segments, continuousScroll: true });
 
-    expect(screen.getByText('In the beginning.')).toBeInTheDocument();
-    expect(screen.getByText('And the earth.')).toBeInTheDocument();
+    capturedSegmentViewPropsList.forEach((p) => expect(p.displayMode).toBe('baseline-text'));
   });
 
   it('renders ContinuousView when continuousScroll is true', () => {
@@ -228,7 +222,7 @@ describe('Interlinearizer', () => {
 
     const continuousView = screen.getByTestId('continuous-view');
     const allElements = Array.from(
-      container.querySelectorAll('[data-testid="continuous-view"], button[aria-current]'),
+      container.querySelectorAll('[data-testid="continuous-view"], [data-testid="segment-view"]'),
     );
     expect(allElements[0]).toBe(continuousView);
   });
@@ -239,9 +233,9 @@ describe('Interlinearizer', () => {
 
     expect(screen.getByTestId('continuous-view')).toBeInTheDocument();
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any, no-type-assertion/no-type-assertion
-    const onVerseChange = capturedContinuousViewProps.onVerseChange as any;
-    expect(onVerseChange).toBeDefined();
+    const { onVerseChange } = capturedContinuousViewProps;
+    if (typeof onVerseChange !== 'function')
+      throw new Error('Expected onVerseChange to be a function');
 
     onVerseChange({ book: 'GEN', chapter: 2, verse: 3 });
 
diff --git a/src/__tests__/components/InterlinearizerLoader.test.tsx b/src/__tests__/components/InterlinearizerLoader.test.tsx
index 669fadf2..4e422961 100644
--- a/src/__tests__/components/InterlinearizerLoader.test.tsx
+++ b/src/__tests__/components/InterlinearizerLoader.test.tsx
@@ -2,60 +2,72 @@
 /// <reference types="jest" />
 /// <reference types="@testing-library/jest-dom" />
 
-import {
-  useLocalizedStrings,
-  useProjectData,
-  useProjectSetting,
-  useRecentScriptureRefs,
-} from '@papi/frontend/react';
+import { useLocalizedStrings } from '@papi/frontend/react';
 import type { SerializedVerseRef } from '@sillsdev/scripture';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import type { Book } from 'interlinearizer';
-import { tokenizeBook } from 'parsers/papi/bookTokenizer';
-import { extractBookFromUsj } from 'parsers/papi/usjBookExtractor';
+import useInterlinearizerBookData from '../../hooks/useInterlinearizerBookData';
+import useOptimisticBooleanSetting from '../../hooks/useOptimisticBooleanSetting';
 import InterlinearizerLoader from '../../components/InterlinearizerLoader';
 
-jest.mock('parsers/papi/bookTokenizer');
-jest.mock('parsers/papi/usjBookExtractor');
+jest.mock('../../hooks/useInterlinearizerBookData');
+jest.mock('../../hooks/useOptimisticBooleanSetting');
+
+jest.mock('../../components/ContinuousScrollToggle', () => ({
+  __esModule: true,
+  default: ({
+    checked,
+    disabled,
+    onCheckedChange,
+  }: {
+    checked: boolean;
+    disabled: boolean;
+    onCheckedChange: (v: boolean) => void;
+  }) => (
+    <button
+      aria-label="continuous scroll"
+      data-testid="continuous-scroll-toggle"
+      data-checked={String(checked)}
+      data-disabled={String(disabled)}
+      onClick={() => onCheckedChange(!checked)}
+      type="button"
+    />
+  ),
+}));
+
+jest.mock('../../components/ScriptureNavControls', () => ({
+  __esModule: true,
+  default: () => <div data-testid="scripture-nav-controls" />,
+}));
 
 jest.mock('../../components/ContinuousView', () => ({
   __esModule: true,
   default: () => <div data-testid="continuous-view" />,
 }));
 
-/**
- * Matches the PlatformError shape from platform-bible-utils (discriminated by
- * platformErrorVersion).
- */
-type PlatformError = { platformErrorVersion: number; message: string };
+type CapturedInterlinearizerProps = {
+  continuousScroll: boolean;
+};
+let capturedInterlinearizerProps: CapturedInterlinearizerProps | undefined;
+
+jest.mock('../../components/Interlinearizer', () => ({
+  __esModule: true,
+  default: (props: CapturedInterlinearizerProps) => {
+    capturedInterlinearizerProps = props;
+    return <div data-testid="interlinearizer" />;
+  },
+}));
 
 const defaultScrRef: SerializedVerseRef = { book: 'GEN', chapterNum: 1, verseNum: 1 };
 const testProjectId = 'test-project-id';
 
-/** Pre-built Book with one GEN 1:1 segment. */
-const GEN_1_1_BOOK: Book = {
+/** A minimal Book used as the successful hook result. */
+const TEST_BOOK: Book = {
   id: 'GEN',
   bookRef: 'GEN',
   textVersion: 'v1',
-  segments: [
-    {
-      id: 'GEN 1:1',
-      startRef: { book: 'GEN', chapter: 1, verse: 1 },
-      endRef: { book: 'GEN', chapter: 1, verse: 1 },
-      baselineText: 'In the beginning.',
-      tokens: [
-        {
-          id: 'GEN 1:1:0',
-          surfaceText: 'In',
-          writingSystem: 'en',
-          type: 'word',
-          charStart: 0,
-          charEnd: 2,
-        },
-      ],
-    },
-  ],
+  segments: [],
 };
 
 /**
@@ -76,50 +88,55 @@ function makeScrollGroupHook(
   ] => [scrRef, setScrRef, undefined, () => {}];
 }
 
-/** Configures useProjectData to return the given BookUSJ value and loading state this render. */
-function mockBookData(value: unknown, isLoading = false): void {
-  jest.mocked(useProjectData).mockImplementation(() => ({
-    BookUSJ: () => [value, jest.fn(), isLoading],
-  }));
+/**
+ * Configures useInterlinearizerBookData to return the given state.
+ *
+ * @param overrides - Partial hook result; all fields default to a successful loaded state
+ */
+function mockBookData(
+  overrides: Partial<{
+    book: Book | undefined;
+    chapterSegments: Book['segments'];
+    isLoading: boolean;
+    bookError: string | undefined;
+    tokenizeError: { message: string; raw: unknown } | undefined;
+  }> = {},
+): void {
+  jest.mocked(useInterlinearizerBookData).mockReturnValue({
+    book: TEST_BOOK,
+    chapterSegments: [],
+    isLoading: false,
+    bookError: undefined,
+    tokenizeError: undefined,
+    ...overrides,
+  });
 }
 
 /**
- * Configures useProjectSetting for the languageTag and continuousScroll keys. All other keys
- * receive their defaultState.
+ * Configures useOptimisticBooleanSetting to return the given state.
  *
- * @param tag - Writing system tag returned for `platform.languageTag`
- * @param continuousScroll - Value returned for `interlinearizer.continuousScroll`; defaults to
- *   `false` so existing token-chip rendering tests are unaffected
+ * @param value - The current boolean value; defaults to `false`
+ * @param onChange - The change handler; defaults to a jest.fn()
+ * @param isLoading - Whether the setting is loading; defaults to `false`
  */
-function mockWritingSystem(tag: string | PlatformError = 'en', continuousScroll = false): void {
-  jest.mocked(useProjectSetting).mockImplementation((_projectId, key, defaultState) => {
-    if (key === 'platform.languageTag') return [tag, jest.fn(), jest.fn(), false];
-    if (key === 'interlinearizer.continuousScroll')
-      return [continuousScroll, jest.fn(), jest.fn(), false];
-    return [defaultState, jest.fn(), jest.fn(), false];
-  });
+function mockOptimisticSetting(
+  value = false,
+  onChange: jest.Mock = jest.fn(),
+  isLoading = false,
+): jest.Mock {
+  jest.mocked(useOptimisticBooleanSetting).mockReturnValue({ value, onChange, isLoading });
+  return onChange;
 }
 
 describe('InterlinearizerLoader', () => {
   beforeEach(() => {
-    mockBookData(undefined);
-    mockWritingSystem();
+    capturedInterlinearizerProps = undefined;
+    mockBookData();
+    mockOptimisticSetting();
     jest.mocked(useLocalizedStrings).mockReturnValue([{}, false]);
-    jest.mocked(useRecentScriptureRefs).mockReturnValue({
-      recentScriptureRefs: [],
-      addRecentScriptureRef: jest.fn(),
-    });
-    jest.mocked(extractBookFromUsj).mockReturnValue({
-      bookCode: 'GEN',
-      writingSystem: 'en',
-      contentHash: 'abc',
-      verses: [],
-    });
-    jest.mocked(tokenizeBook).mockReturnValue(GEN_1_1_BOOK);
   });
 
-  it('shows the book chapter control and renders a segment when book data is available', () => {
-    mockBookData({});
+  it('renders Interlinearizer and the nav controls when book data is available', () => {
     render(
       <InterlinearizerLoader
         projectId={testProjectId}
@@ -127,12 +144,12 @@ describe('InterlinearizerLoader', () => {
       />,
     );
 
-    expect(screen.getByTestId('book-chapter-control')).toBeInTheDocument();
-    expect(screen.getByText('In')).toBeInTheDocument();
+    expect(screen.getByTestId('scripture-nav-controls')).toBeInTheDocument();
+    expect(screen.getByTestId('interlinearizer')).toBeInTheDocument();
   });
 
   it('shows Loading when book data has not arrived', () => {
-    mockBookData(undefined, true);
+    mockBookData({ book: undefined, isLoading: true });
     render(
       <InterlinearizerLoader
         projectId={testProjectId}
@@ -144,7 +161,10 @@ describe('InterlinearizerLoader', () => {
   });
 
   it('shows an error when no USJ book is available for the project', () => {
-    mockBookData(undefined, false);
+    mockBookData({
+      book: undefined,
+      bookError: 'No USJ book available for GEN in project test-project-id',
+    });
     render(
       <InterlinearizerLoader
         projectId={testProjectId}
@@ -157,7 +177,7 @@ describe('InterlinearizerLoader', () => {
   });
 
   it('shows an error heading and message when book data is a PlatformError', () => {
-    mockBookData({ platformErrorVersion: 1, message: 'Project not found' });
+    mockBookData({ book: undefined, bookError: 'Project not found' });
     render(
       <InterlinearizerLoader
         projectId={testProjectId}
@@ -169,38 +189,10 @@ describe('InterlinearizerLoader', () => {
     expect(screen.getByText(/project not found/i)).toBeInTheDocument();
   });
 
-  it('falls back to "und" writing system when useProjectSetting returns a PlatformError', () => {
-    mockBookData({});
-    mockWritingSystem({ platformErrorVersion: 1, message: 'Setting unavailable' });
-    render(
-      <InterlinearizerLoader
-        projectId={testProjectId}
-        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
-      />,
-    );
-
-    expect(screen.getByText('In')).toBeInTheDocument();
-    expect(extractBookFromUsj).toHaveBeenCalledWith(expect.anything(), 'und');
-  });
-
-  it('falls back to "und" writing system when useProjectSetting returns an empty string', () => {
-    mockBookData({});
-    mockWritingSystem('');
-    render(
-      <InterlinearizerLoader
-        projectId={testProjectId}
-        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
-      />,
-    );
-
-    expect(screen.getByText('In')).toBeInTheDocument();
-    expect(extractBookFromUsj).toHaveBeenCalledWith(expect.anything(), 'und');
-  });
-
   it('shows an error heading and message when tokenization throws an Error', () => {
-    mockBookData({});
-    jest.mocked(tokenizeBook).mockImplementation(() => {
-      throw new Error('parse failure');
+    mockBookData({
+      book: undefined,
+      tokenizeError: { message: 'parse failure', raw: new Error('parse failure') },
     });
     render(
       <InterlinearizerLoader
@@ -214,10 +206,9 @@ describe('InterlinearizerLoader', () => {
   });
 
   it('shows an error message when tokenization throws a non-Error value', () => {
-    mockBookData({});
-    jest.mocked(tokenizeBook).mockImplementation(() => {
-      // eslint-disable-next-line no-throw-literal
-      throw 'unexpected string error';
+    mockBookData({
+      book: undefined,
+      tokenizeError: { message: 'unexpected string error', raw: 'unexpected string error' },
     });
     render(
       <InterlinearizerLoader
@@ -231,8 +222,9 @@ describe('InterlinearizerLoader', () => {
   });
 
   it('passes a book-stable ref to BookUSJ so chapter and verse changes do not re-fetch the book', () => {
-    const mockBookUSJ = jest.fn().mockReturnValue([{}, jest.fn(), false]);
-    jest.mocked(useProjectData).mockImplementation(() => ({ BookUSJ: mockBookUSJ }));
+    // The book-stable ref logic lives in useInterlinearizerBookData, which is tested in its own
+    // test file. This test verifies that InterlinearizerLoader passes scrRef into the hook and that
+    // re-rendering with a new verse does not cause the hook to receive a new book ref.
     const { rerender } = render(
       <InterlinearizerLoader
         projectId={testProjectId}
@@ -250,27 +242,13 @@ describe('InterlinearizerLoader', () => {
       />,
     );
 
-    const refsPassed = mockBookUSJ.mock.calls.map((c) => c[0]);
-    refsPassed.forEach((ref) => expect(ref).toEqual({ book: 'GEN', chapterNum: 1, verseNum: 1 }));
-    expect(mockBookUSJ.mock.calls.length).toBeGreaterThanOrEqual(2);
-    refsPassed.slice(1).forEach((ref) => expect(ref).toBe(refsPassed[0]));
-  });
-
-  it('renders the continuous scroll toggle', () => {
-    mockBookData({});
-    render(
-      <InterlinearizerLoader
-        projectId={testProjectId}
-        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
-      />,
-    );
-
-    expect(screen.getByRole('checkbox')).toBeInTheDocument();
+    const { calls } = jest.mocked(useInterlinearizerBookData).mock;
+    expect(calls.length).toBeGreaterThanOrEqual(2);
+    calls.forEach((args) => expect(args[0].projectId).toBe(testProjectId));
   });
 
-  it('continuous scroll toggle is checked when the setting is true', () => {
-    mockBookData({});
-    mockWritingSystem('en', true);
+  it('passes continuousScroll from useOptimisticBooleanSetting to Interlinearizer', () => {
+    mockOptimisticSetting(true);
     render(
       <InterlinearizerLoader
         projectId={testProjectId}
@@ -278,11 +256,11 @@ describe('InterlinearizerLoader', () => {
       />,
     );
 
-    expect(screen.getByRole('checkbox')).toBeChecked();
+    expect(capturedInterlinearizerProps?.continuousScroll).toBe(true);
   });
 
-  it('continuous scroll toggle is unchecked when the setting is false', () => {
-    mockBookData({});
+  it('passes checked and disabled from useOptimisticBooleanSetting to ContinuousScrollToggle', () => {
+    mockOptimisticSetting(true, jest.fn(), true);
     render(
       <InterlinearizerLoader
         projectId={testProjectId}
@@ -290,68 +268,14 @@ describe('InterlinearizerLoader', () => {
       />,
     );
 
-    expect(screen.getByRole('checkbox')).not.toBeChecked();
+    const toggle = screen.getByTestId('continuous-scroll-toggle');
+    expect(toggle).toHaveAttribute('data-checked', 'true');
+    expect(toggle).toHaveAttribute('data-disabled', 'true');
   });
 
-  it('clicking the continuous scroll toggle calls setContinuousScroll with the new value', async () => {
-    mockBookData({});
-    const mockSetContinuousScroll = jest.fn();
-    jest.mocked(useProjectSetting).mockImplementation((_p, key, d) => {
-      if (key === 'interlinearizer.continuousScroll')
-        return [true, mockSetContinuousScroll, jest.fn(), false];
-      if (key === 'platform.languageTag') return ['en', jest.fn(), jest.fn(), false];
-      return [d, jest.fn(), jest.fn(), false];
-    });
-    render(
-      <InterlinearizerLoader
-        projectId={testProjectId}
-        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
-      />,
-    );
-
-    await userEvent.click(screen.getByRole('checkbox'));
-
-    expect(mockSetContinuousScroll).toHaveBeenCalledWith(false);
-  });
-
-  it('switches rendering immediately using optimistic local state while setting saves', async () => {
-    mockBookData({});
-    const mockSetContinuousScroll = jest.fn();
-    // Setting source remains true during the test (simulates delayed persistence confirmation).
-    jest.mocked(useProjectSetting).mockImplementation((_p, key, d) => {
-      if (key === 'interlinearizer.continuousScroll')
-        return [true, mockSetContinuousScroll, jest.fn(), false];
-      if (key === 'platform.languageTag') return ['en', jest.fn(), jest.fn(), false];
-      return [d, jest.fn(), jest.fn(), false];
-    });
-    render(
-      <InterlinearizerLoader
-        projectId={testProjectId}
-        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
-      />,
-    );
-
-    // Initially in continuous mode.
-    expect(screen.getByTestId('continuous-view')).toBeInTheDocument();
-    expect(screen.queryByText('In')).not.toBeInTheDocument();
-
-    await userEvent.click(screen.getByRole('checkbox'));
-
-    // Before setting saves, UI should already switch to token-chip mode.
-    expect(screen.queryByTestId('continuous-view')).not.toBeInTheDocument();
-    expect(screen.getByText('In')).toBeInTheDocument();
-    expect(mockSetContinuousScroll).toHaveBeenCalledWith(false);
-  });
-
-  it('toggles continuous scroll setting back to true after being false', async () => {
-    mockBookData({});
-    const mockSetContinuousScroll = jest.fn();
-    jest.mocked(useProjectSetting).mockImplementation((_p, key, d) => {
-      if (key === 'interlinearizer.continuousScroll')
-        return [false, mockSetContinuousScroll, jest.fn(), false];
-      if (key === 'platform.languageTag') return ['en', jest.fn(), jest.fn(), false];
-      return [d, jest.fn(), jest.fn(), false];
-    });
+  it('wires ContinuousScrollToggle onCheckedChange to the onChange from useOptimisticBooleanSetting', async () => {
+    const mockOnChange = jest.fn();
+    mockOptimisticSetting(false, mockOnChange);
     render(
       <InterlinearizerLoader
         projectId={testProjectId}
@@ -359,11 +283,8 @@ describe('InterlinearizerLoader', () => {
       />,
     );
 
-    // Initially in token-chip mode
-    expect(screen.queryByTestId('continuous-view')).not.toBeInTheDocument();
+    await userEvent.click(screen.getByTestId('continuous-scroll-toggle'));
 
-    // Click toggle to turn on continuous mode
-    await userEvent.click(screen.getByRole('checkbox'));
-    expect(mockSetContinuousScroll).toHaveBeenCalledWith(true);
+    expect(mockOnChange).toHaveBeenCalledWith(true);
   });
 });
diff --git a/src/__tests__/components/SegmentView.test.tsx b/src/__tests__/components/SegmentView.test.tsx
index efaaa842..fc6bc163 100644
--- a/src/__tests__/components/SegmentView.test.tsx
+++ b/src/__tests__/components/SegmentView.test.tsx
@@ -4,9 +4,22 @@
 
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import type { Segment } from 'interlinearizer';
+import type { Segment, Token } from 'interlinearizer';
 import { SegmentView } from '../../components/SegmentView';
 
+jest.mock('../../components/PhraseBox', () => ({
+  __esModule: true,
+  default: ({ tokens }: { tokens: Token[] }) => (
+    <span>{tokens.map((t) => t.surfaceText).join(' ')}</span>
+  ),
+}));
+
+jest.mock('../../components/TokenChip', () => ({
+  __esModule: true,
+  default: ({ token }: { token: Token }) => <span>{token.surfaceText}</span>,
+  TokenChip: ({ token }: { token: Token }) => <span>{token.surfaceText}</span>,
+}));
+
 /** A word token segment. */
 const WORD_SEGMENT: Segment = {
   id: 'GEN 1:1',
@@ -58,12 +71,6 @@ describe('SegmentView', () => {
     expect(screen.getByText('.')).toBeInTheDocument();
   });
 
-  it('renders explicit token-chip mode the same as the default', () => {
-    render(<SegmentView segment={WORD_SEGMENT} displayMode="token-chip" />);
-
-    expect(screen.getByText('In')).toBeInTheDocument();
-  });
-
   it('renders baselineText in baseline-text mode', () => {
     render(<SegmentView segment={WORD_SEGMENT} displayMode="baseline-text" />);
 
diff --git a/src/__tests__/components/TokenChip.test.tsx b/src/__tests__/components/TokenChip.test.tsx
new file mode 100644
index 00000000..00a86bdc
--- /dev/null
+++ b/src/__tests__/components/TokenChip.test.tsx
@@ -0,0 +1,56 @@
+/** @file Unit tests for components/TokenChip.tsx. */
+/// <reference types="jest" />
+/// <reference types="@testing-library/jest-dom" />
+
+import { render, screen } from '@testing-library/react';
+import type { Token } from 'interlinearizer';
+import { TokenChip } from '../../components/TokenChip';
+
+const WORD_TOKEN: Token = {
+  id: 'GEN 1:1:0',
+  surfaceText: 'hello',
+  writingSystem: 'en',
+  type: 'word',
+  charStart: 0,
+  charEnd: 5,
+};
+
+const PUNCT_TOKEN: Token = {
+  id: 'GEN 1:1:5',
+  surfaceText: '.',
+  writingSystem: 'en',
+  type: 'punctuation',
+  charStart: 5,
+  charEnd: 6,
+};
+
+describe('TokenChip', () => {
+  it('renders the surface text for a word token', () => {
+    render(<TokenChip token={WORD_TOKEN} />);
+    expect(screen.getByText('hello')).toBeInTheDocument();
+  });
+
+  it('renders the surface text for a punctuation token', () => {
+    render(<TokenChip token={PUNCT_TOKEN} />);
+    expect(screen.getByText('.')).toBeInTheDocument();
+  });
+
+  it('applies a border class to word tokens', () => {
+    render(<TokenChip token={WORD_TOKEN} />);
+    const span = screen.getByText('hello');
+    expect(span.className).toContain('tw:border');
+  });
+
+  it('does not apply a border class to punctuation tokens', () => {
+    render(<TokenChip token={PUNCT_TOKEN} />);
+    const span = screen.getByText('.');
+    expect(span.className).not.toContain('tw:border');
+  });
+
+  it('renders word and punctuation tokens as inline spans', () => {
+    const { container: wc } = render(<TokenChip token={WORD_TOKEN} />);
+    const { container: pc } = render(<TokenChip token={PUNCT_TOKEN} />);
+    expect(wc.querySelector('span')).toBeInTheDocument();
+    expect(pc.querySelector('span')).toBeInTheDocument();
+  });
+});
diff --git a/src/__tests__/hooks/useInterlinearizerBookData.test.ts b/src/__tests__/hooks/useInterlinearizerBookData.test.ts
index cf64b0c1..7c0119d9 100644
--- a/src/__tests__/hooks/useInterlinearizerBookData.test.ts
+++ b/src/__tests__/hooks/useInterlinearizerBookData.test.ts
@@ -87,14 +87,20 @@ const TEST_BOOK: Book = {
 const GEN_1_1_SRC_REF = { book: 'GEN', chapterNum: 1, verseNum: 1 };
 
 describe('useInterlinearizerBookData', () => {
-  /** Default mock setup for useProjectData */
+  /**
+   * Configures useProjectData to return a resolved USJ object so the hook can proceed to
+   * extractBookFromUsj and tokenizeBook without hitting the error-state branches.
+   */
   const setupDefaultProjectDataMock = () => {
     jest.mocked(useProjectData).mockReturnValue({
       BookUSJ: () => [{ USJ: 'mock-usj' }, jest.fn(), false],
     });
   };
 
-  /** Default mock setup for useProjectSetting */
+  /**
+   * Configures useProjectSetting to return the writing system code 'en' so the hook uses a valid
+   * BCP 47 tag rather than falling back to 'und'.
+   */
   const setupDefaultProjectSettingMock = () => {
     jest.mocked(useProjectSetting).mockReturnValue(['en', jest.fn(), jest.fn(), false]);
   };
diff --git a/src/__tests__/hooks/useOptimisticBooleanSetting.test.ts b/src/__tests__/hooks/useOptimisticBooleanSetting.test.ts
index ca2fe706..0b3df7d7 100644
--- a/src/__tests__/hooks/useOptimisticBooleanSetting.test.ts
+++ b/src/__tests__/hooks/useOptimisticBooleanSetting.test.ts
@@ -79,7 +79,7 @@ describe('useOptimisticBooleanSetting', () => {
     expect(result.current.value).toBe(false);
   });
 
-  it('accepts incoming setting updates after the timeout elapses (covers lines 57-58)', () => {
+  it('accepts incoming setting updates after the timeout elapses', () => {
     // Setting not yet loaded so `setting` starts as non-boolean.
     mockUseProjectSetting.mockReturnValue([undefined, mockSetSetting, jest.fn(), false]);
     const { result, rerender } = renderHook(() =>
@@ -94,7 +94,7 @@ describe('useOptimisticBooleanSetting', () => {
     rerender();
     expect(result.current.value).toBe(false); // Locked to optimistic value.
 
-    // Fire the timeout — executes lines 57-58 (timeoutRef.current = undefined; ignoreRef.current = false).
+    // Fire the timeout — lock is released and incoming setting changes are accepted again.
     act(() => {
       jest.advanceTimersByTime(TIMEOUT_MS);
     });
@@ -106,7 +106,7 @@ describe('useOptimisticBooleanSetting', () => {
   });
 
   it('clears the first timeout when onChange is called a second time', () => {
-    const clearTimeoutSpy = jest.spyOn(global, 'clearTimeout');
+    const clearTimeoutSpy = jest.spyOn(globalThis, 'clearTimeout');
     const { result } = renderHook(() =>
       useOptimisticBooleanSetting('project-1', SETTING_KEY, false),
     );
@@ -158,7 +158,7 @@ describe('useOptimisticBooleanSetting', () => {
   });
 
   it('clears the pending timeout on unmount', () => {
-    const clearTimeoutSpy = jest.spyOn(global, 'clearTimeout');
+    const clearTimeoutSpy = jest.spyOn(globalThis, 'clearTimeout');
     const { result, unmount } = renderHook(() =>
       useOptimisticBooleanSetting('project-1', SETTING_KEY, false),
     );
diff --git a/src/__tests__/main.test.ts b/src/__tests__/main.test.ts
index b99af479..3feaa8d2 100644
--- a/src/__tests__/main.test.ts
+++ b/src/__tests__/main.test.ts
@@ -50,10 +50,22 @@ const {
   __mockLogger,
 } = papiBackendMock;
 
+/**
+ * Type guard that narrows an unknown value to a callable function.
+ *
+ * @param f - The value to test.
+ * @returns True if f is a function.
+ */
 function isCallable(f: unknown): f is (...args: unknown[]) => unknown {
   return typeof f === 'function';
 }
 
+/**
+ * Finds the handler registered for a command name in the mocked registerCommand calls.
+ *
+ * @param commandName - The command name to look up.
+ * @returns The handler function, or undefined if no matching call was recorded.
+ */
 function findRegisteredHandler(commandName: string): ((...args: unknown[]) => unknown) | undefined {
   const call = jest.mocked(__mockRegisterCommand).mock.calls.find((c) => c[0] === commandName);
   const rawHandler: unknown = call?.[1];
@@ -73,12 +85,24 @@ async function getOpenForWebViewHandler(): Promise<
   };
 }
 
+/**
+ * Retrieves the callback passed to onDidOpenWebView during the most recent activate() call.
+ *
+ * @returns A typed wrapper around the captured callback.
+ * @throws If no callback was registered (i.e. activate was not called first).
+ */
 function getOpenWebViewCallback(): (event: { webView: SavedWebViewDefinition }) => void {
   const cb: unknown = __mockOnDidOpenWebView.mock.calls[0]?.[0];
   if (!isCallable(cb)) throw new Error('onDidOpenWebView callback not found');
   return (event) => cb(event);
 }
 
+/**
+ * Retrieves the callback passed to onDidCloseWebView during the most recent activate() call.
+ *
+ * @returns A typed wrapper around the captured callback.
+ * @throws If no callback was registered (i.e. activate was not called first).
+ */
 function getCloseWebViewCallback(): (event: { webView: SavedWebViewDefinition }) => void {
   const cb: unknown = __mockOnDidCloseWebView.mock.calls[0]?.[0];
   if (!isCallable(cb)) throw new Error('onDidCloseWebView callback not found');
diff --git a/src/__tests__/parsers/papi/bookTokenizer.test.ts b/src/__tests__/parsers/papi/bookTokenizer.test.ts
index d36238fd..8427321f 100644
--- a/src/__tests__/parsers/papi/bookTokenizer.test.ts
+++ b/src/__tests__/parsers/papi/bookTokenizer.test.ts
@@ -4,6 +4,12 @@
 import { tokenizeBook } from 'parsers/papi/bookTokenizer';
 import type { RawBook } from 'parsers/papi/usjBookExtractor';
 
+/**
+ * Builds a minimal RawBook fixture for GEN with the given verses.
+ *
+ * @param verses - Array of verse objects (sid + text) to include in the book.
+ * @returns A RawBook with fixed bookCode, writingSystem, and contentHash.
+ */
 function makeRawBook(verses: { sid: string; text: string }[]): RawBook {
   return { bookCode: 'GEN', writingSystem: 'en', contentHash: 'abc123', verses };
 }
@@ -77,11 +83,17 @@ describe('tokenizeBook', () => {
     expect(segments[0].tokens).toEqual([]);
   });
 
-  it('assigns unique IDs within a segment', () => {
+  it('gives every token a unique ID that can be used to look it up', () => {
     const text = 'A B C.';
     const { segments } = tokenizeBook(makeRawBook([{ sid: 'GEN 1:1', text }]));
-    const ids = segments[0].tokens.map((t) => t.id);
+    const { tokens } = segments[0];
+    // IDs must be unique so each token can be referenced unambiguously.
+    const ids = tokens.map((t) => t.id);
     expect(new Set(ids).size).toBe(ids.length);
+    // Each token must be retrievable by its ID.
+    ids.forEach((id, i) => {
+      expect(tokens.find((t) => t.id === id)).toBe(tokens[i]);
+    });
   });
 
   it('assigns unique IDs across segments', () => {
@@ -151,13 +163,8 @@ describe('tokenizeBook', () => {
     );
   });
 
-  it('throws on an invalid verse SID', () => {
-    expect(() => tokenizeBook(makeRawBook([{ sid: 'not-a-ref', text: 'text' }]))).toThrow(
-      expect.objectContaining({
-        name: 'SyntaxError',
-        message: expect.stringContaining('Invalid verse SID'),
-      }),
-    );
+  it.each(['GEN 1:', 'not-a-ref', ''])('throws on malformed verse SID "%s"', (sid) => {
+    expect(() => tokenizeBook(makeRawBook([{ sid, text: 'text' }]))).toThrow(SyntaxError);
   });
 
   describe('word-internal joiners', () => {
diff --git a/src/__tests__/parsers/papi/usjBookExtractor.test.ts b/src/__tests__/parsers/papi/usjBookExtractor.test.ts
index 5e819f77..216150c2 100644
--- a/src/__tests__/parsers/papi/usjBookExtractor.test.ts
+++ b/src/__tests__/parsers/papi/usjBookExtractor.test.ts
@@ -20,16 +20,16 @@ describe('extractBookFromUsj', () => {
     expect(extractBookFromUsj(usj, 'kmr').writingSystem).toBe('kmr');
   });
 
-  it('produces a stable contentHash for identical content', () => {
+  it('produces the same contentHash for identical content with different writingSystems', () => {
     const a: UsjDocument = { content: [{ type: 'book', code: 'GEN', content: [] }] };
     const b: UsjDocument = { content: [...a.content] };
     expect(extractBookFromUsj(a, 'en').contentHash).toBe(extractBookFromUsj(b, 'es').contentHash);
   });
 
-  it('produces different contentHashes for different content', () => {
+  it('produces a different contentHash for different content', () => {
     const a: UsjDocument = { content: [{ type: 'book', code: 'GEN', content: [] }] };
-    const b: UsjDocument = { content: [{ type: 'book', code: 'MAT', content: [] }] };
-    expect(extractBookFromUsj(a, WS).contentHash).not.toBe(extractBookFromUsj(b, WS).contentHash);
+    const c: UsjDocument = { content: [{ type: 'book', code: 'MAT', content: [] }] };
+    expect(extractBookFromUsj(a, WS).contentHash).not.toBe(extractBookFromUsj(c, WS).contentHash);
   });
 
   it('returns empty verses when there are no verse markers', () => {
@@ -265,6 +265,63 @@ describe('extractBookFromUsj', () => {
     expect(verses[0].text).toBe('I have gone astray');
   });
 
+  it('skips text inside a heading para marker that appears mid-verse (before the verse is closed)', () => {
+    // An s1 heading node that arrives while a verse is still open must not contribute its text.
+    const usj: UsjDocument = {
+      content: [
+        { type: 'book', code: 'PSA', content: [] },
+        {
+          type: 'para',
+          marker: 'p',
+          content: [{ type: 'verse', sid: 'PSA 1:1' }, 'Blessed is the man'],
+        },
+        // s1 heading arrives while PSA 1:1 is still the currentVerse
+        { type: 'para', marker: 's1', content: ['Interlude'] },
+        {
+          type: 'para',
+          marker: 'p',
+          content: ['who walks not in the counsel of the wicked.'],
+        },
+      ],
+    };
+    const { verses } = extractBookFromUsj(usj, WS);
+    expect(verses).toHaveLength(1);
+    expect(verses[0].text).toBe('Blessed is the man who walks not in the counsel of the wicked.');
+  });
+
+  it('includes text nested inside multiple levels of inline char nodes', () => {
+    // The traverse fallback recurses into any unknown node that has content, so deeply
+    // nested char nodes must still contribute their text.
+    const usj: UsjDocument = {
+      content: [
+        { type: 'book', code: 'JHN', content: [] },
+        {
+          type: 'para',
+          marker: 'p',
+          content: [
+            { type: 'verse', sid: 'JHN 1:14' },
+            'And the ',
+            {
+              type: 'char',
+              marker: 'em',
+              content: [
+                {
+                  type: 'char',
+                  marker: 'nd',
+                  content: ['Word'],
+                },
+              ],
+            },
+            ' became flesh.',
+          ],
+        },
+      ],
+    };
+    const { verses } = extractBookFromUsj(usj, WS);
+    expect(verses).toHaveLength(1);
+    expect(verses[0].text).toBe('And the Word became flesh.');
+  });
+
   it('produces a stable contentHash when a node has an optional property explicitly set to undefined', () => {
     const withUndefined: UsjDocument = {
       content: [{ type: 'book', code: 'GEN', marker: undefined, content: [] }],
@@ -276,4 +333,28 @@ describe('extractBookFromUsj', () => {
     const hash = extractBookFromUsj(withUndefined, WS).contentHash;
     expect(hash).toBe(extractBookFromUsj(withoutUndefined, WS).contentHash);
   });
+
+  it('throws when a verse SID is a duplicate', () => {
+    const usj: UsjDocument = {
+      content: [
+        { type: 'book', code: 'GEN', content: [] },
+        {
+          type: 'para',
+          marker: 'p',
+          content: [
+            { type: 'verse', sid: 'GEN 1:1' },
+            'First.',
+            { type: 'verse', sid: 'GEN 1:1' },
+            'Duplicate.',
+          ],
+        },
+      ],
+    };
+    expect(() => extractBookFromUsj(usj, WS)).toThrow(
+      expect.objectContaining({
+        name: 'SyntaxError',
+        message: expect.stringContaining('duplicate verse SID'),
+      }),
+    );
+  });
 });
diff --git a/src/__tests__/parsers/pt9/interlinearXmlParser.test.ts b/src/__tests__/parsers/pt9/interlinearXmlParser.test.ts
index c80befcf..f319d773 100644
--- a/src/__tests__/parsers/pt9/interlinearXmlParser.test.ts
+++ b/src/__tests__/parsers/pt9/interlinearXmlParser.test.ts
@@ -225,7 +225,13 @@ describe('InterlinearXmlParser', () => {
       });
     });
 
-    it('parses Cluster with Excluded=true', () => {
+    it.each([
+      ['true', true],
+      ['false', false],
+      [undefined, false],
+    ] as const)('parses Cluster Excluded=%s as boolean %s', (excludedValue, expectedBool) => {
+      const excludedTag =
+        excludedValue === undefined ? '' : `<Excluded>${excludedValue}</Excluded>`;
       const xml = `
         <InterlinearData GlossLanguage="en" BookId="MAT">
           <Verses>
@@ -235,7 +241,7 @@ describe('InterlinearXmlParser', () => {
                 <Cluster>
                   <Range Index="0" Length="4" />
                   <Lexeme Id="Word:word" />
-                  <Excluded>true</Excluded>
+                  ${excludedTag}
                 </Cluster>
               </VerseData>
             </item>
@@ -243,51 +249,7 @@ describe('InterlinearXmlParser', () => {
         </InterlinearData>
       `;
       const result = parser.parse(xml);
-
-      expect(result.Verses['MAT 1:1'].Clusters[0].Excluded).toBe(true);
-    });
-
-    it('parses Cluster with Excluded=false', () => {
-      const xml = `
-        <InterlinearData GlossLanguage="en" BookId="MAT">
-          <Verses>
-            <item>
-              <string>MAT 1:1</string>
-              <VerseData>
-                <Cluster>
-                  <Range Index="0" Length="4" />
-                  <Lexeme Id="Word:word" />
-                  <Excluded>false</Excluded>
-                </Cluster>
-              </VerseData>
-            </item>
-          </Verses>
-        </InterlinearData>
-      `;
-      const result = parser.parse(xml);
-
-      expect(result.Verses['MAT 1:1'].Clusters[0].Excluded).toBe(false);
-    });
-
-    it('parses Cluster without Excluded as Excluded=false', () => {
-      const xml = `
-        <InterlinearData GlossLanguage="en" BookId="MAT">
-          <Verses>
-            <item>
-              <string>MAT 1:1</string>
-              <VerseData>
-                <Cluster>
-                  <Range Index="0" Length="4" />
-                  <Lexeme Id="Word:word" />
-                </Cluster>
-              </VerseData>
-            </item>
-          </Verses>
-        </InterlinearData>
-      `;
-      const result = parser.parse(xml);
-
-      expect(result.Verses['MAT 1:1'].Clusters[0].Excluded).toBe(false);
+      expect(result.Verses['MAT 1:1'].Clusters[0].Excluded).toBe(expectedBool);
     });
 
     it('parses Punctuation with Range, BeforeText, AfterText', () => {
@@ -504,6 +466,47 @@ describe('InterlinearXmlParser', () => {
       });
     });
 
+    it('parses multiple Punctuation entries in a single verse', () => {
+      const xml = `
+        <InterlinearData GlossLanguage="en" BookId="MAT">
+          <Verses>
+            <item>
+              <string>MAT 1:1</string>
+              <VerseData>
+                <Cluster>
+                  <Range Index="0" Length="1" />
+                  <Lexeme Id="x" />
+                </Cluster>
+                <Punctuation>
+                  <Range Index="5" Length="1" />
+                  <BeforeText>,</BeforeText>
+                  <AfterText> </AfterText>
+                </Punctuation>
+                <Punctuation>
+                  <Range Index="12" Length="1" />
+                  <BeforeText>.</BeforeText>
+                  <AfterText></AfterText>
+                </Punctuation>
+              </VerseData>
+            </item>
+          </Verses>
+        </InterlinearData>
+      `;
+      const result = parser.parse(xml);
+
+      expect(result.Verses['MAT 1:1'].Punctuations).toHaveLength(2);
+      expect(result.Verses['MAT 1:1'].Punctuations[0]).toEqual({
+        TextRange: { Index: 5, Length: 1 },
+        BeforeText: ',',
+        AfterText: ' ',
+      });
+      expect(result.Verses['MAT 1:1'].Punctuations[1]).toEqual({
+        TextRange: { Index: 12, Length: 1 },
+        BeforeText: '.',
+        AfterText: '',
+      });
+    });
+
     it('parses VerseData with Punctuation but no Cluster (Cluster ?? [] branch)', () => {
       const xml = `
         <InterlinearData GlossLanguage="en" BookId="MAT">
@@ -756,9 +759,7 @@ describe('InterlinearXmlParser', () => {
       expect(() => parser.parse(xmlNoIndex)).toThrow(
         expect.objectContaining({
           name: 'SyntaxError',
-          message: expect.stringContaining(
-            'Invalid XML: Range missing or invalid Index/Length attributes (must be non-negative integers)',
-          ),
+          message: expect.stringContaining('Invalid XML: Range missing Index or Length attribute'),
         }),
       );
 
@@ -780,9 +781,7 @@ describe('InterlinearXmlParser', () => {
       expect(() => parser.parse(xmlNoLength)).toThrow(
         expect.objectContaining({
           name: 'SyntaxError',
-          message: expect.stringContaining(
-            'Invalid XML: Range missing or invalid Index/Length attributes (must be non-negative integers)',
-          ),
+          message: expect.stringContaining('Invalid XML: Range missing Index or Length attribute'),
         }),
       );
     });
@@ -856,6 +855,88 @@ describe('InterlinearXmlParser', () => {
     });
   });
 
+  describe('parse() - invalid Range values on Cluster', () => {
+    it.each([
+      ['-1', '2'],
+      ['1', '-1'],
+      ['1.5', '2'],
+      ['1', '2.5'],
+    ] as const)(
+      'throws when Cluster Range Index="%s" Length="%s" (negative or float)',
+      (index, length) => {
+        const xml = `
+        <InterlinearData GlossLanguage="en" BookId="MAT">
+          <Verses>
+            <item>
+              <string>MAT 1:1</string>
+              <VerseData>
+                <Cluster>
+                  <Range Index="${index}" Length="${length}" />
+                  <Lexeme Id="x" />
+                </Cluster>
+              </VerseData>
+            </item>
+          </Verses>
+        </InterlinearData>
+      `;
+        expect(() => parser.parse(xml)).toThrow(
+          expect.objectContaining({
+            name: 'SyntaxError',
+            message: expect.stringContaining(
+              'Invalid XML: Range has invalid Index/Length attributes (must be non-negative integers)',
+            ),
+          }),
+        );
+      },
+    );
+
+    it('accepts Index=0 and Length=0 (zero is a valid non-negative integer)', () => {
+      const xml = `
+        <InterlinearData GlossLanguage="en" BookId="MAT">
+          <Verses>
+            <item>
+              <string>MAT 1:1</string>
+              <VerseData>
+                <Cluster>
+                  <Range Index="0" Length="0" />
+                  <Lexeme Id="x" />
+                </Cluster>
+              </VerseData>
+            </item>
+          </Verses>
+        </InterlinearData>
+      `;
+      const result = parser.parse(xml);
+      expect(result.Verses['MAT 1:1'].Clusters[0].TextRange).toEqual({ Index: 0, Length: 0 });
+    });
+  });
+
+  describe('parse() - non-boolean Excluded values', () => {
+    it.each(['maybe', '1', '0', 'TRUE', 'yes'] as const)(
+      'treats unrecognized Excluded value "%s" as false',
+      (value) => {
+        const xml = `
+        <InterlinearData GlossLanguage="en" BookId="MAT">
+          <Verses>
+            <item>
+              <string>MAT 1:1</string>
+              <VerseData>
+                <Cluster>
+                  <Range Index="0" Length="1" />
+                  <Lexeme Id="x" />
+                  <Excluded>${value}</Excluded>
+                </Cluster>
+              </VerseData>
+            </item>
+          </Verses>
+        </InterlinearData>
+      `;
+        const result = parser.parse(xml);
+        expect(result.Verses['MAT 1:1'].Clusters[0].Excluded).toBe(false);
+      },
+    );
+  });
+
   describe('constructor and instance', () => {
     it('can be instantiated multiple times', () => {
       const p1 = new InterlinearXmlParser();
diff --git a/src/components/ContinuousView.tsx b/src/components/ContinuousView.tsx
index cacbc78c..651f476e 100644
--- a/src/components/ContinuousView.tsx
+++ b/src/components/ContinuousView.tsx
@@ -3,7 +3,12 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import MemoizedPhraseBox from './PhraseBox';
 import MemoizedTokenChip from './TokenChip';
 
+/** CSS easing for the strip opacity fade-in/out animation. */
 const STRIP_FADE_EASING = 'cubic-bezier(0.65, 0, 0.35, 1)';
+/**
+ * Duration of the strip fade animation in milliseconds. Must match the `setTimeout` in the
+ * pending-jump effect.
+ */
 const STRIP_FADE_MS = 500;
 
 /**
@@ -90,6 +95,12 @@ export default function ContinuousView({
   const tokenSegmentRef = useRef(tokenSegment);
   tokenSegmentRef.current = tokenSegment;
 
+  /**
+   * Maps a verse coordinate to the phrase index of the first word token in the matching segment.
+   *
+   * @param verse - The verse to look up; returns `undefined` when absent or unrecognized.
+   * @returns The phrase index, or `undefined` if no matching segment or no word token was found.
+   */
   const getPhraseIndexForVerse = useCallback(
     (verse?: ScriptureRef): number | undefined => {
       /* v8 ignore next -- verse is always defined at the one call site */
@@ -158,8 +169,7 @@ export default function ContinuousView({
     // Skip if this activeVerse update is an echo-back of a verse change we reported ourselves.
     const lastInternal = lastInternalVerseRef.current;
     if (
-      lastInternal &&
-      lastInternal.book === activeVerse.book &&
+      lastInternal?.book === activeVerse.book &&
       lastInternal.chapter === activeVerse.chapter &&
       lastInternal.verse === activeVerse.verse
     ) {
@@ -240,6 +250,11 @@ export default function ContinuousView({
   const atEnd = !phraseEntries.length || focusPhraseIndex >= phraseEntries.length - 1;
   const stripOpacityClass = isVisible ? 'tw:opacity-100' : 'tw:opacity-0';
 
+  /**
+   * Advances the focused phrase index by `delta`, clamped to `[0, phraseEntries.length - 1]`.
+   *
+   * @param delta - Signed step count; negative moves backward, positive moves forward.
+   */
   const step = useCallback((delta: number) => {
     setFocusPhraseIndex((i) => {
       const nextIndex = i + delta;
@@ -251,10 +266,18 @@ export default function ContinuousView({
     });
   }, []);
 
+  /** Moves focus one phrase toward the start. Bound to the previous arrow button. */
   const stepPrev = useCallback(() => step(-1), [step]);
 
+  /** Moves focus one phrase toward the end. Bound to the next arrow button. */
   const stepNext = useCallback(() => step(1), [step]);
 
+  /**
+   * Moves focus to the phrase at `index` when clicked. No-op when `index` is `undefined` or already
+   * focused (avoids a redundant re-render).
+   *
+   * @param index - Phrase index of the clicked `PhraseBox`, or `undefined` for punctuation chips.
+   */
   const handlePhraseSelect = useCallback((index?: number) => {
     if (index !== undefined) {
       setFocusPhraseIndex((prev) => (prev === index ? prev : index));
diff --git a/src/components/Interlinearizer.tsx b/src/components/Interlinearizer.tsx
index 6703871e..2af2dd0f 100644
--- a/src/components/Interlinearizer.tsx
+++ b/src/components/Interlinearizer.tsx
@@ -21,13 +21,13 @@ export default function Interlinearizer({
   continuousScroll,
   scrRef,
   setScrRef,
-}: {
+}: Readonly<{
   book: Book;
   bookSegments: Segment[];
   continuousScroll: boolean;
   scrRef: SerializedVerseRef;
   setScrRef: (newScrRef: SerializedVerseRef) => void;
-}) {
+}>) {
   const handleVerseChange = useCallback(
     (v: ScriptureRef) => {
       setScrRef({ book: v.book, chapterNum: v.chapter, verseNum: v.verse });
diff --git a/src/components/InterlinearizerLoader.tsx b/src/components/InterlinearizerLoader.tsx
index ded91f44..a3e8a1ec 100644
--- a/src/components/InterlinearizerLoader.tsx
+++ b/src/components/InterlinearizerLoader.tsx
@@ -8,6 +8,7 @@ import ScriptureNavControls from './ScriptureNavControls';
 import useInterlinearizerBookData from '../hooks/useInterlinearizerBookData';
 import useOptimisticBooleanSetting from '../hooks/useOptimisticBooleanSetting';
 
+/** Localization keys fetched from the platform for this component's UI strings. */
 const STRING_KEYS = ['%interlinearizer_continuousScrollToggle%'] as const;
 
 /**
@@ -22,10 +23,10 @@ const STRING_KEYS = ['%interlinearizer_continuousScrollToggle%'] as const;
 export default function InterlinearizerLoader({
   projectId,
   useWebViewScrollGroupScrRef,
-}: {
+}: Readonly<{
   projectId: string;
   useWebViewScrollGroupScrRef: UseWebViewScrollGroupScrRefHook;
-}) {
+}>) {
   const [scrRef, setScrRef, scrollGroupId, setScrollGroupId] = useWebViewScrollGroupScrRef();
 
   const {
diff --git a/src/components/PhraseBox.tsx b/src/components/PhraseBox.tsx
index 2e461548..9b21ab01 100644
--- a/src/components/PhraseBox.tsx
+++ b/src/components/PhraseBox.tsx
@@ -7,7 +7,10 @@ import MemoizedTokenChip from './TokenChip';
  * Wraps one or more tokens in a phrase-level visual container.
  *
  * @param props - Component props
+ * @param props.index - Index passed back to `onClick` to identify which phrase was clicked
  * @param props.isFocused - Whether this phrase is the current navigation focus
+ * @param props.onClick - Called with `index` when the phrase is clicked; omit to render a
+ *   non-interactive span
  * @param props.tokens - Tokens belonging to this phrase
  * @returns A bordered inline container
  */
diff --git a/src/components/ScriptureNavControls.tsx b/src/components/ScriptureNavControls.tsx
index ebef06d7..82be60a3 100644
--- a/src/components/ScriptureNavControls.tsx
+++ b/src/components/ScriptureNavControls.tsx
@@ -8,11 +8,30 @@ import {
   ScrollGroupSelectorProps,
 } from 'platform-bible-react';
 
+/**
+ * Scroll group IDs offered to the user. `undefined` means "no scroll group" (the WebView scrolls
+ * independently); numeric IDs 0–4 correspond to Platform.Bible's shared scroll groups.
+ */
 const AVAILABLE_SCROLL_GROUPS = [undefined, 0, 1, 2, 3, 4];
 
+/**
+ * Props for {@link ScriptureNavControls}. Combines the scripture-reference fields from
+ * `BookChapterControlProps` with the scroll-group fields from `ScrollGroupSelectorProps`.
+ */
 type ScriptureNavControlsProps = Pick<BookChapterControlProps, 'scrRef' | 'handleSubmit'> &
   Pick<ScrollGroupSelectorProps, 'scrollGroupId' | 'onChangeScrollGroupId'>;
 
+/**
+ * Toolbar row combining a {@link BookChapterControl} for scripture navigation with a
+ * {@link ScrollGroupSelector} for Platform.Bible scroll-group linking.
+ *
+ * @param props - Component props
+ * @param props.scrRef - Current scripture reference displayed in the book/chapter picker.
+ * @param props.handleSubmit - Called when the user submits a new scripture reference.
+ * @param props.scrollGroupId - Currently active scroll group ID (or `undefined` for none).
+ * @param props.onChangeScrollGroupId - Called when the user selects a different scroll group.
+ * @returns A flex row containing the book/chapter control and the scroll group selector.
+ */
 export default function ScriptureNavControls({
   scrRef,
   handleSubmit,
diff --git a/src/components/SegmentView.tsx b/src/components/SegmentView.tsx
index 6a1157cb..62b37eb4 100644
--- a/src/components/SegmentView.tsx
+++ b/src/components/SegmentView.tsx
@@ -3,7 +3,14 @@ import { memo } from 'react';
 import MemoizedPhraseBox from './PhraseBox';
 import MemoizedTokenChip from './TokenChip';
 
-/** The two display modes for {@link SegmentView}. */
+/**
+ * The two display modes for {@link SegmentView}.
+ *
+ * - `token-chip` — renders each token as an inline chip (word tokens via `PhraseBox`, punctuation via
+ *   `TokenChip`). Used for the main interactive view.
+ * - `baseline-text` — renders the segment's raw `baselineText` as a single monospace string. Used for
+ *   fallback or debug display.
+ */
 export type SegmentDisplayMode = 'token-chip' | 'baseline-text';
 
 /**
diff --git a/src/hooks/useInterlinearizerBookData.ts b/src/hooks/useInterlinearizerBookData.ts
index 09b28586..8ce5dd3d 100644
--- a/src/hooks/useInterlinearizerBookData.ts
+++ b/src/hooks/useInterlinearizerBookData.ts
@@ -7,19 +7,36 @@ import { tokenizeBook } from 'parsers/papi/bookTokenizer';
 import { isPlatformError } from 'platform-bible-utils';
 import { useEffect, useMemo } from 'react';
 
+/** Arguments for the {@link useInterlinearizerBookData} hook. */
 interface UseInterlinearizerBookDataArgs {
+  /** PAPI project ID whose USJ book data should be loaded. */
   projectId: string;
+  /** Current scripture reference; only `book` and `chapterNum` are used to scope the data. */
   scrRef: SerializedVerseRef;
 }
 
+/** Return value of the {@link useInterlinearizerBookData} hook. */
 interface UseInterlinearizerBookDataResult {
+  /** The fully tokenized book, or `undefined` while loading or on error. */
   book: Book | undefined;
+  /** Segments belonging to the current chapter (`scrRef.chapterNum`); empty while loading. */
   chapterSegments: Book['segments'];
+  /** `true` while the USJ book data is being fetched from the platform. */
   isLoading: boolean;
+  /** Human-readable error string when the platform returns an error or no USJ data. */
   bookError: string | undefined;
+  /** Error thrown by {@link extractBookFromUsj} or {@link tokenizeBook}; `undefined` on success. */
   tokenizeError: { message: string; raw: unknown } | undefined;
 }
 
+/**
+ * Fetches and tokenizes the USJ book for the given project and scripture reference.
+ *
+ * @param args - Hook arguments.
+ * @param args.projectId - PAPI project ID whose USJ book data should be loaded.
+ * @param args.scrRef - Current scripture reference; only `book` and `chapterNum` are used.
+ * @returns The tokenized book, chapter segments, loading state, and any errors encountered.
+ */
 export default function useInterlinearizerBookData({
   projectId,
   scrRef,
diff --git a/src/main.ts b/src/main.ts
index 5793bcfc..554b4f62 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -65,6 +65,7 @@ const openWebViewsByProject = new Map<string, string>();
  *
  * @param projectId - Project to open; if omitted a picker dialog is shown.
  * @returns The WebView ID of the opened (or focused) tab, or `undefined` if the user cancels.
+ * @throws If `papi.dialogs.selectProject` or `papi.webViews.openWebView` rejects.
  */
 async function openInterlinearizer(projectId?: string): Promise<string | undefined> {
   const resolvedProjectId =
@@ -89,6 +90,7 @@ async function openInterlinearizer(projectId?: string): Promise<string | undefin
  *
  * @param webViewId - ID of an open WebView whose project to use; if omitted falls back to a picker.
  * @returns The WebView ID of the opened (or focused) tab, or `undefined` if the user cancels.
+ * @throws If `papi.webViews.getOpenWebViewDefinition` or `openInterlinearizer` rejects.
  */
 async function openInterlinearizerForWebView(webViewId?: string): Promise<string | undefined> {
   if (!webViewId) return openInterlinearizer();
diff --git a/src/parsers/papi/bookTokenizer.ts b/src/parsers/papi/bookTokenizer.ts
index abca6c51..9f8be6e6 100644
--- a/src/parsers/papi/bookTokenizer.ts
+++ b/src/parsers/papi/bookTokenizer.ts
@@ -83,6 +83,9 @@ function parseSid(sid: string): ScriptureRef {
  * character) are emitted in document order. Whitespace is not tokenized. Character offsets are
  * zero-based relative to `text`; `charEnd` is exclusive.
  *
+ * Each token inherits `writingSystem` from the book so that downstream consumers (renderers,
+ * alignment tools) can identify the script without access to the parent `RawBook`.
+ *
  * @param text - The verse's `baselineText` string.
  * @param sid - The verse SID used as the token ID prefix (e.g. `"GEN 1:1"`).
  * @param writingSystem - BCP 47 tag assigned to every token's `writingSystem` field.
@@ -111,7 +114,9 @@ function tokenizeVerse(text: string, sid: string, writingSystem: string): Token[
  *
  * @param rawBook - Extracted book data from {@link extractBookFromUsj}.
  * @returns A `Book` with one `Segment` per verse, each containing its ordered `Token`s.
- * @throws {SyntaxError} If any `RawVerse.sid` cannot be parsed as a valid scripture reference.
+ * @throws {SyntaxError} If any `RawVerse.sid` cannot be parsed as a valid scripture reference
+ *   (propagated from {@link parseSid}).
+ * @throws {SyntaxError} If any `RawVerse.sid`'s book code does not match `rawBook.bookCode`.
  */
 export function tokenizeBook(rawBook: RawBook): Book {
   const segments: Segment[] = rawBook.verses.map(({ sid, text }) => {
diff --git a/src/parsers/papi/usjBookExtractor.ts b/src/parsers/papi/usjBookExtractor.ts
index 66c564ee..35b25aed 100644
--- a/src/parsers/papi/usjBookExtractor.ts
+++ b/src/parsers/papi/usjBookExtractor.ts
@@ -147,6 +147,7 @@ function handleChapterNode(node: UsjNode, state: TraversalState): void {
  * @param node - The `verse` USJ node; must carry a `sid` attribute (e.g. `"GEN 1:1"`).
  * @param state - Shared traversal state updated in place.
  * @throws {SyntaxError} If the `verse` node is missing its required `sid` attribute.
+ * @throws {SyntaxError} If the `verse` SID has already been seen (duplicate verse SID).
  */
 function handleVerseNode(node: UsjNode, state: TraversalState): void {
   if (state.currentVerse !== undefined) {
@@ -194,6 +195,8 @@ const NODE_HANDLERS: Partial<Record<string, (node: UsjNode, state: TraversalStat
  *
  * @param nodes - Content items to walk (`string` or {@link UsjNode}).
  * @param state - Shared mutable state updated in place during traversal.
+ * @throws {SyntaxError} If any verse node encountered during traversal is missing its `sid`
+ *   attribute or contains a duplicate SID (propagated from {@link handleVerseNode}).
  */
 function traverse(nodes: MarkerContent[], state: TraversalState): void {
   nodes.forEach((node) => {
@@ -219,6 +222,7 @@ function traverse(nodes: MarkerContent[], state: TraversalState): void {
  * @returns A stable JSON string with object keys in UTF-16 code-unit order.
  */
 function stableStringify(value: unknown): string {
+  /* v8 ignore next -- defensive guard; production callers never pass undefined directly */
   if (value === undefined) return 'null';
   if (!(value instanceof Object)) return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
diff --git a/src/parsers/pt9/interlinearXmlParser.ts b/src/parsers/pt9/interlinearXmlParser.ts
index 765b6287..2d4a4fdb 100644
--- a/src/parsers/pt9/interlinearXmlParser.ts
+++ b/src/parsers/pt9/interlinearXmlParser.ts
@@ -169,15 +169,17 @@ const parseStrictNumber = (raw: string): number | undefined => {
   if (raw === undefined || raw.trim() === '') return undefined;
   if (!/^\d+$/.test(raw.trim())) return undefined;
   const n = Number.parseInt(raw, 10);
+  /* v8 ignore next -- the ^\d+$ regex above makes n < 0 unreachable; guard kept for safety */
   return n >= 0 ? n : undefined;
 };
 
 /**
  * Maps a parsed VerseData's Punctuation array to {@link PunctuationData} array.
  *
- * Punctuations without a valid Range (or missing Index/Length) are filtered out rather than causing
- * a parse error. Punctuations are optional/non-critical to the interlinear display; clusters are
- * required and validated strictly in {@link extractClustersFromVerse}.
+ * Uses a **lenient** parsing strategy: entries without a valid `Range` (or with missing /
+ * non-integer `Index`/`Length`) are silently filtered out rather than throwing. Punctuation data is
+ * non-critical to the interlinear display; clusters are validated strictly in
+ * {@link extractClustersFromVerse} because they are required for alignment rendering.
  *
  * @param verseDataElement - Parsed VerseData from fast-xml-parser (may have Punctuation array or
  *   none).
@@ -209,8 +211,8 @@ function extractPunctuationsFromVerse(verseDataElement: ParsedVerseData): Punctu
  * @param verseDataElement - Parsed VerseData from fast-xml-parser (may have Cluster array or none).
  * @returns Array of ClusterData: TextRange from Cluster's Range, Lexemes from Lexeme children,
  *   LexemesId (slash-joined), Id (LexemesId/Index-Length or Index-Length when no lexemes).
- * @throws {SyntaxError} If a Cluster is missing its Range element or Range is missing Index or
- *   Length.
+ * @throws {SyntaxError} If a Cluster is missing its Range element, Range is missing Index or
+ *   Length, or Range Index/Length are not non-negative integers.
  */
 function extractClustersFromVerse(verseDataElement: ParsedVerseData): ClusterData[] {
   const clusterElements = verseDataElement.Cluster ?? [];
@@ -221,11 +223,15 @@ function extractClustersFromVerse(verseDataElement: ParsedVerseData): ClusterDat
       throw new SyntaxError('Invalid XML: Cluster missing required Range element');
     }
 
+    if (rangeElement['@_Index'] === undefined || rangeElement['@_Length'] === undefined) {
+      throw new SyntaxError('Invalid XML: Range missing Index or Length attribute');
+    }
+
     const index = parseStrictNumber(rangeElement['@_Index']);
     const length = parseStrictNumber(rangeElement['@_Length']);
     if (index === undefined || length === undefined) {
       throw new SyntaxError(
-        'Invalid XML: Range missing or invalid Index/Length attributes (must be non-negative integers)',
+        'Invalid XML: Range has invalid Index/Length attributes (must be non-negative integers)',
       );
     }
 
@@ -254,6 +260,9 @@ function extractClustersFromVerse(verseDataElement: ParsedVerseData): ClusterDat
  * Input is a raw XML string (caller is responsible for obtaining it, e.g. from file or network).
  * Output matches the types in `interlinearizer`; no extra conversion is done. Expects the
  * interlinear XML schema described in [pt9-xml.md](pt9-xml.md).
+ *
+ * Each instance holds a configured `XMLParser`; create one parser and reuse it across multiple
+ * `parse()` calls rather than constructing a new instance per file.
  */
 export class InterlinearXmlParser {
   private readonly parser: XMLParser;
@@ -291,9 +300,13 @@ export class InterlinearXmlParser {
    *   entries.
    * @returns Parsed interlinear data: ScrTextName, GlossLanguage, BookId, and Verses (record of
    *   verse key to {@link VerseData} with Hash, Clusters, Punctuations).
-   * @throws {SyntaxError} If the root element, required attributes (GlossLanguage, BookId), or
-   *   required structure (Verses, Cluster Range, Lexeme Id) is missing.
-   * @throws {SyntaxError} If a verse reference appears more than once.
+   * @throws {SyntaxError} If the `InterlinearData` root element is absent.
+   * @throws {SyntaxError} If `GlossLanguage` or `BookId` attributes are missing or empty.
+   * @throws {SyntaxError} If the `Verses` element is absent.
+   * @throws {SyntaxError} If a `Cluster` is missing its `Range` element, `Range` is missing
+   *   `Index`/`Length`, or `Index`/`Length` are not non-negative integers.
+   * @throws {SyntaxError} If a `Lexeme` element is missing its required `Id` attribute.
+   * @throws {SyntaxError} If the same verse reference appears in more than one `item`.
    */
   parse(xml: string): InterlinearData {
     const parsed: ParsedInterlinearXml = this.parser.parse(xml);
diff --git a/src/types/interlinearizer.d.ts b/src/types/interlinearizer.d.ts
index 8a5c39b2..8d005900 100644
--- a/src/types/interlinearizer.d.ts
+++ b/src/types/interlinearizer.d.ts
@@ -105,12 +105,18 @@ declare module 'interlinearizer' {
   // Shared primitives
   // ---------------------------------------------------------------------------
 
-  /** A string value keyed by BCP 47 writing-system tag. */
+  /**
+   * A string value keyed by BCP 47 writing-system tag (e.g. `"en"`, `"fr"`, `"kmr-Latn"`). Keys
+   * follow the IETF BCP 47 standard (language, optional script and region components). Consumers
+   * should treat missing keys as "no value in that language" rather than an error.
+   */
   export type MultiString = Record<string, string>;
 
   /**
    * A character-level scripture reference anchored to a specific position within a verse's baseline
-   * text. When `charIndex` is absent the reference is verse-level only.
+   * text. When `charIndex` is absent the reference is verse-level only — it identifies the verse as
+   * a whole without pinpointing a specific character. Consumers must treat an absent `charIndex` as
+   * "beginning of verse" when a character position is required.
    */
   export interface ScriptureRef {
     /** 3-letter SIL book code (e.g. `"GEN"`). */
@@ -119,7 +125,10 @@ declare module 'interlinearizer' {
     chapter: number;
     /** 1-based verse number. */
     verse: number;
-    /** Zero-based character offset within the verse's baseline text. */
+    /**
+     * Zero-based character offset within the verse's baseline text. Absent when the reference is
+     * verse-level only (i.e. not anchored to a specific character position).
+     */
     charIndex?: number;
   }
 
@@ -143,7 +152,10 @@ declare module 'interlinearizer' {
     /** `IEntry.id` (GUID). */
     entryId: string;
 
-    /** Lexicon project identifier (FwData / Harmony code). */
+    /**
+     * Lexicon project identifier (FwData / Harmony code). Omit when there is only one Lexicon
+     * project in context and the consumer can resolve it unambiguously.
+     */
     projectId?: string;
   }
 
@@ -159,7 +171,10 @@ declare module 'interlinearizer' {
     /** `ISense.id` (GUID). */
     senseId: string;
 
-    /** Lexicon project identifier (FwData / Harmony code). */
+    /**
+     * Lexicon project identifier (FwData / Harmony code). Omit when there is only one Lexicon
+     * project in context and the consumer can resolve it unambiguously.
+     */
     projectId?: string;
   }
 
@@ -182,7 +197,10 @@ declare module 'interlinearizer' {
     /** `IMoForm.id` (GUID). */
     allomorphId: string;
 
-    /** Lexicon project identifier (FwData / Harmony code). */
+    /**
+     * Lexicon project identifier (FwData / Harmony code). Omit when there is only one Lexicon
+     * project in context and the consumer can resolve it unambiguously.
+     */
     projectId?: string;
   }
 
@@ -206,7 +224,10 @@ declare module 'interlinearizer' {
     /** `IMoMorphSynAnalysis.id` (GUID). */
     msaId: string;
 
-    /** Lexicon project identifier (FwData / Harmony code). */
+    /**
+     * Lexicon project identifier (FwData / Harmony code). Omit when there is only one Lexicon
+     * project in context and the consumer can resolve it unambiguously.
+     */
     projectId?: string;
   }
 
@@ -261,7 +282,7 @@ declare module 'interlinearizer' {
 
     /**
      * Token- or morpheme-level alignment links connecting endpoints in the source interlinear to
-     * endpoints in the target interlinear.
+     * endpoints in the target interlinear. Empty when no alignment has been computed or imported.
      */
     links: AlignmentLink[];
   }
@@ -307,7 +328,11 @@ declare module 'interlinearizer' {
     /** Baseline text: books of scripture (or other texts). */
     books: Book[];
 
-    /** Parallel analysis layer. Omitted when the text is unanalyzed. */
+    /**
+     * Parallel analysis layer. Absent (not present) when the text has never been analyzed;
+     * present-but-empty (`segmentAnalyses: [], tokenAnalyses: [], phrases: []`) when analysis has
+     * been initialized but no records have been added yet.
+     */
     analysis?: TextAnalysis;
   }
 
@@ -337,7 +362,12 @@ declare module 'interlinearizer' {
     /** Book identifier (e.g. `"GEN"`, `"MAT"`). */
     bookRef: string;
 
-    /** Version stamp of the baseline content at analysis time. */
+    /**
+     * Opaque version stamp of the book's baseline content at analysis time. In the current
+     * implementation this is an FNV-1a 32-bit hex hash of the serialized USJ content (e.g.
+     * `"a3f2c1b0"`). Consumers must treat it as an opaque string and compare only for equality — a
+     * change in value means the baseline has changed and analyses may be stale.
+     */
     textVersion: string;
 
     /** Ordered segments that compose this book. */
@@ -430,7 +460,12 @@ declare module 'interlinearizer' {
     /** Writing system of `surfaceText`. */
     writingSystem: string;
 
-    /** Whether this token is a word or punctuation. */
+    /**
+     * Whether this token is a word or punctuation. This is a text-layer classification only — it
+     * describes what the token looks like in the baseline, not how it is analyzed. Linguistic
+     * analysis (POS, morphemes, glosses) lives in the parallel `TokenAnalysis` in the analysis
+     * layer. Punctuation tokens typically have no corresponding `TokenAnalysis`.
+     */
     type: TokenType;
 
     /**
@@ -583,7 +618,9 @@ declare module 'interlinearizer' {
    * `gloss` is a free-form gloss string for the token (keyed by analysis-language tag).
    * `glossSenseRef` alternatively resolves the gloss through a specific `ISense` in the Lexicon
    * extension — when set, the rendered gloss is the sense's gloss text and may be refreshed
-   * automatically if the lexicon is edited. Setting both is a type error: use one or the other.
+   * automatically if the lexicon is edited. Exactly one of `gloss` or `glossSenseRef` may be set;
+   * setting both is a TypeScript type error. Omitting both is valid for a parse-only analysis with
+   * no gloss.
    *
    * `morphemes` carries the parse information. Each morpheme links to the Lexicon extension via
    * `entryRef` / `senseRef`.
@@ -711,22 +748,28 @@ declare module 'interlinearizer' {
     /** Writing system of `form`. */
     writingSystem: string;
 
-    /** Lexicon entry this morpheme resolves to. */
+    /**
+     * Lexicon entry this morpheme resolves to. Present for most analyzed morphemes; absent when the
+     * morpheme has not yet been linked to a lexicon entry (e.g. an unreviewed parser suggestion).
+     */
     entryRef?: EntryRef;
 
-    /** Specific sense of the entry used here. */
+    /**
+     * Specific sense of the entry used here. Requires `entryRef` to be meaningful; absent when the
+     * entry has not been sense-disambiguated.
+     */
     senseRef?: SenseRef;
 
     /**
      * Specific allomorph (surface variant) within the entry — an `IMoForm` in the Lexicon
-     * extension.
+     * extension. Absent when allomorph-level detail is not available (e.g. BT Extension imports).
      */
     allomorphRef?: AllomorphRef;
 
     /**
      * Morphosyntactic analysis (MSA) — grammar / POS information tied to this (entry × sense ×
      * allomorph) usage. Points at an `IMoMorphSynAnalysis` in the Lexicon extension (pending direct
-     * exposure — see `GrammarRef`).
+     * exposure — see `GrammarRef`). Absent when MSA-level detail is not available.
      */
     grammarRef?: GrammarRef;
   }
@@ -749,8 +792,9 @@ declare module 'interlinearizer' {
    *
    * `gloss` is a free-form phrase gloss. `senseRef` alternatively points at a lexicon sense when
    * the phrase is a multi-word lexical entry — the Lexicon extension supports both kinds via
-   * `IEntry.morphType = Phrase` (contiguous) or `DiscontiguousPhrase` (e.g. "ne … pas"). Setting
-   * both is a type error: use one or the other.
+   * `IEntry.morphType = Phrase` (contiguous) or `DiscontiguousPhrase` (e.g. "ne … pas"). Exactly
+   * one of `gloss` or `senseRef` may be set; setting both is a TypeScript type error. Omitting both
+   * is valid (phrase without a gloss, e.g. a structural grouping only).
    *
    * Provenance fields (`producer`, `sourceUser`, `confidence`, `status`) let a suggestion engine
    * record proposed phrases that a user can then approve or reject, enabling automated recognition
@@ -844,7 +888,12 @@ declare module 'interlinearizer' {
     /** Review status of this alignment link. */
     status: AssignmentStatus;
 
-    /** How the alignment was created (manual, automatic tool, etc.). */
+    /**
+     * Free-form string describing how the alignment was produced — e.g. `"manual"`, `"eflomal"`,
+     * `"import-bt"`. No controlled vocabulary is enforced; consumers should treat unknown values as
+     * opaque. Absent when the origin was not recorded (e.g. legacy data or default-0 BT Extension
+     * imports).
+     */
     origin?: string;
 
     /**
@@ -865,6 +914,12 @@ declare module 'interlinearizer' {
    * `morphemeId` to identify the specific `TokenAnalysis` that owns the referenced morpheme. When
    * `morphemeId` is absent the link connects to the whole token.
    *
+   * Exactly one of two shapes is valid — setting `morphemeId` without `tokenAnalysisId` (or vice
+   * versa) is a TypeScript type error:
+   *
+   * - Token-level: neither `morphemeId` nor `tokenAnalysisId` is present.
+   * - Morpheme-level: both `morphemeId` and `tokenAnalysisId` are present.
+   *
    * Resolution chain (morpheme-level): AlignmentEndpoint → Token (via `tokenId`) → TokenAnalysis
    * (via `tokenAnalysisId`) → Morpheme (via `morphemeId`) → EntryRef → `IEntry` (Lexicon extension)
    * → SenseRef → `ISense` (Lexicon extension)