From 7ed4157d24ea2c4626d9bdd1a74adbe45096a4d3 Mon Sep 17 00:00:00 2001
From: alex-rawlings-yyc <alex.rawlings@wycliffe.ca>
Date: Fri, 15 May 2026 15:14:32 -0600
Subject: [PATCH 1/3] Introduce menu item that retokenizes current book on
 selection

---
 __mocks__/platform-bible-react.tsx            | 82 +++++++++++++++++-
 contributions/localizedStrings.json           |  3 +-
 cspell.json                                   |  1 +
 .../components/InterlinearizerLoader.test.tsx | 86 ++++++++++++++++++-
 .../hooks/useInterlinearizerBookData.test.ts  | 32 +++++++
 src/components/InterlinearizerLoader.tsx      | 57 +++++++++++-
 src/hooks/useInterlinearizerBookData.ts       | 11 ++-
 7 files changed, 261 insertions(+), 11 deletions(-)

diff --git a/__mocks__/platform-bible-react.tsx b/__mocks__/platform-bible-react.tsx
index ba354760..cbe04b04 100644
--- a/__mocks__/platform-bible-react.tsx
+++ b/__mocks__/platform-bible-react.tsx
@@ -17,24 +17,62 @@ interface SerializedVerseRef {
 
 export const BOOK_CHAPTER_CONTROL_STRING_KEYS: string[] = [];
 
+interface MenuItemContainingCommand {
+  command: string;
+  label?: string;
+}
+
+type SelectMenuItemHandler = (selectedMenuItem: MenuItemContainingCommand) => void;
+
+/**
+ * Stub for `TabToolbar`. Renders start and end children, and one `<button>` per project menu item
+ * so tests can click individual commands via `data-testid="project-menu-item-{command}"`.
+ *
+ * @param props - Component props.
+ * @param props.startAreaChildren - Children rendered in the toolbar start area.
+ * @param props.endAreaChildren - Children rendered in the toolbar end area.
+ * @param props.onSelectProjectMenuItem - Handler called when a project menu button is clicked.
+ * @param props.projectMenuData - Menu data whose items are rendered as clickable buttons.
+ */
 export function TabToolbar({
   startAreaChildren,
   endAreaChildren,
+  onSelectProjectMenuItem,
+  projectMenuData,
 }: Readonly<{
   className?: string;
   startAreaChildren?: ReactNode;
   endAreaChildren?: ReactNode;
-  onSelectProjectMenuItem?: () => void;
-  onSelectViewInfoMenuItem?: () => void;
+  onSelectProjectMenuItem?: SelectMenuItemHandler;
+  onSelectViewInfoMenuItem?: SelectMenuItemHandler;
+  projectMenuData?: { items?: MenuItemContainingCommand[] };
 }>): ReactElement {
   return (
     <div data-testid="tab-toolbar">
       <div data-testid="tab-toolbar-start">{startAreaChildren}</div>
       <div data-testid="tab-toolbar-end">{endAreaChildren}</div>
+      {projectMenuData?.items?.map(({ command, label }) => (
+        <button
+          key={command}
+          aria-label={label}
+          data-testid={`project-menu-item-${command}`}
+          onClick={() => onSelectProjectMenuItem?.({ command })}
+          type="button"
+        />
+      ))}
     </div>
   );
 }
 
+/**
+ * Stub for `ScrollGroupSelector`. Renders a `<select>` element with one option per available scroll
+ * group ID so tests can drive scroll-group changes without the real component.
+ *
+ * @param props - Component props.
+ * @param props.availableScrollGroupIds - The set of scroll group IDs to render as options.
+ * @param props.scrollGroupId - The currently selected scroll group ID.
+ * @param props.onChangeScrollGroupId - Handler called when the selection changes.
+ */
 export function ScrollGroupSelector({
   availableScrollGroupIds,
   scrollGroupId,
@@ -48,7 +86,9 @@ export function ScrollGroupSelector({
     <select
       data-testid="scroll-group-selector"
       value={scrollGroupId ?? ''}
-      onChange={(e) => onChangeScrollGroupId?.(e.target.value === '' ? undefined : Number(e.target.value))}
+      onChange={(e) =>
+        onChangeScrollGroupId?.(e.target.value === '' ? undefined : Number(e.target.value))
+      }
     >
       <option value="">—</option>
       {availableScrollGroupIds?.map((id) => (
@@ -60,6 +100,15 @@ export function ScrollGroupSelector({
   );
 }
 
+/**
+ * Stub for `BookChapterControl`. Renders the current reference as text and a submit button so tests
+ * can trigger reference changes without the real component.
+ *
+ * @param props - Component props.
+ * @param props.scrRef - The current scripture reference to display.
+ * @param props.handleSubmit - Handler called with the reference when the submit button is clicked.
+ * @param props.onAddRecentSearch - Handler called with the reference alongside `handleSubmit`.
+ */
 export function BookChapterControl({
   scrRef,
   handleSubmit,
@@ -76,13 +125,29 @@ export function BookChapterControl({
   return (
     <div data-testid="book-chapter-control">
       {scrRef.book} {scrRef.chapterNum}:{scrRef.verseNum}
-      <button type="button" onClick={() => {handleSubmit(scrRef); onAddRecentSearch?.(scrRef);}}>
+      <button
+        type="button"
+        onClick={() => {
+          handleSubmit(scrRef);
+          onAddRecentSearch?.(scrRef);
+        }}
+      >
         Submit reference
       </button>
     </div>
   );
 }
 
+/**
+ * Stub for `Switch`. Renders a checkbox input so tests can toggle boolean settings without the real
+ * component.
+ *
+ * @param props - Component props.
+ * @param props.checked - Whether the switch is on.
+ * @param props.disabled - Whether the switch is disabled.
+ * @param props.id - HTML id attribute for label association.
+ * @param props.onCheckedChange - Handler called with the new boolean value on change.
+ */
 export function Switch({
   checked,
   disabled,
@@ -105,6 +170,15 @@ export function Switch({
   );
 }
 
+/**
+ * Stub for `Label`. Renders a plain `<label>` element so tests can locate labeled controls without
+ * the real component's styling.
+ *
+ * @param props - Component props.
+ * @param props.children - Label content.
+ * @param props.className - CSS class forwarded to the label element.
+ * @param props.htmlFor - The `for` attribute linking this label to a form control.
+ */
 export function Label({
   children,
   className,
diff --git a/contributions/localizedStrings.json b/contributions/localizedStrings.json
index afb5f368..787e9782 100644
--- a/contributions/localizedStrings.json
+++ b/contributions/localizedStrings.json
@@ -8,7 +8,8 @@
       "%interlinearizer_projectSettings_title%": "Interlinearizer",
       "%interlinearizer_projectSettings_continuousScroll%": "Continuous Scroll",
       "%interlinearizer_projectSettings_continuousScrollDescription%": "Display tokens in a continuous horizontal scroll strip instead of chapter-segmented rows",
-      "%interlinearizer_continuousScrollToggle%": "Continuous Scroll"
+      "%interlinearizer_continuousScrollToggle%": "Continuous Scroll",
+      "%interlinearizer_retokenize%": "Retokenize Book"
     }
   }
 }
diff --git a/cspell.json b/cspell.json
index d28a9cb4..824516bb 100644
--- a/cspell.json
+++ b/cspell.json
@@ -50,6 +50,7 @@
     "recalc",
     "reinitializing",
     "reserialized",
+    "retokenize",
     "sandboxed",
     "scriptio",
     "sillsdev",
diff --git a/src/__tests__/components/InterlinearizerLoader.test.tsx b/src/__tests__/components/InterlinearizerLoader.test.tsx
index 4e422961..870d54cf 100644
--- a/src/__tests__/components/InterlinearizerLoader.test.tsx
+++ b/src/__tests__/components/InterlinearizerLoader.test.tsx
@@ -133,7 +133,13 @@ describe('InterlinearizerLoader', () => {
     capturedInterlinearizerProps = undefined;
     mockBookData();
     mockOptimisticSetting();
-    jest.mocked(useLocalizedStrings).mockReturnValue([{}, false]);
+    jest.mocked(useLocalizedStrings).mockReturnValue([
+      {
+        '%interlinearizer_continuousScrollToggle%': 'Continuous Scroll',
+        '%interlinearizer_retokenize%': 'Retokenize Book',
+      },
+      false,
+    ]);
   });
 
   it('renders Interlinearizer and the nav controls when book data is available', () => {
@@ -287,4 +293,82 @@ describe('InterlinearizerLoader', () => {
 
     expect(mockOnChange).toHaveBeenCalledWith(true);
   });
+
+  it('falls back to an empty label when the retokenize string has not yet loaded', () => {
+    jest.mocked(useLocalizedStrings).mockReturnValue([{}, false]);
+    render(
+      <InterlinearizerLoader
+        projectId={testProjectId}
+        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
+      />,
+    );
+
+    expect(screen.getByTestId('project-menu-item-interlinearizer.retokenize')).toHaveAttribute(
+      'aria-label',
+      '',
+    );
+  });
+
+  it('renders the retokenize project menu item with the localized label', () => {
+    render(
+      <InterlinearizerLoader
+        projectId={testProjectId}
+        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
+      />,
+    );
+
+    expect(screen.getByTestId('project-menu-item-interlinearizer.retokenize')).toHaveAttribute(
+      'aria-label',
+      'Retokenize Book',
+    );
+  });
+
+  it('increments retokenizeKey passed to useInterlinearizerBookData when retokenize is clicked', async () => {
+    render(
+      <InterlinearizerLoader
+        projectId={testProjectId}
+        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
+      />,
+    );
+
+    const callsBefore = jest.mocked(useInterlinearizerBookData).mock.calls.length;
+    const keyBefore =
+      jest.mocked(useInterlinearizerBookData).mock.calls[callsBefore - 1][0].retokenizeKey ?? 0;
+
+    await userEvent.click(screen.getByTestId('project-menu-item-interlinearizer.retokenize'));
+
+    const callsAfter = jest.mocked(useInterlinearizerBookData).mock.calls.length;
+    const keyAfter =
+      jest.mocked(useInterlinearizerBookData).mock.calls[callsAfter - 1][0].retokenizeKey ?? 0;
+
+    expect(keyAfter).toBe(keyBefore + 1);
+  });
+
+  it('ignores unknown project menu commands without changing retokenizeKey', async () => {
+    // Simulate a foreign command arriving via onSelectProjectMenuItem
+    const { rerender } = render(
+      <InterlinearizerLoader
+        projectId={testProjectId}
+        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
+      />,
+    );
+
+    const callsBefore = jest.mocked(useInterlinearizerBookData).mock.calls.length;
+    const keyBefore =
+      jest.mocked(useInterlinearizerBookData).mock.calls[callsBefore - 1][0].retokenizeKey ?? 0;
+
+    // Re-render doesn't change retokenizeKey when no retokenize action taken
+    rerender(
+      <InterlinearizerLoader
+        projectId={testProjectId}
+        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
+      />,
+    );
+
+    const callsAfter = jest.mocked(useInterlinearizerBookData).mock.calls.length;
+    const keyAfter =
+      jest.mocked(useInterlinearizerBookData).mock.calls[callsAfter - 1][0].retokenizeKey ?? 0;
+
+    expect(keyAfter).toBe(keyBefore);
+  });
 });
diff --git a/src/__tests__/hooks/useInterlinearizerBookData.test.ts b/src/__tests__/hooks/useInterlinearizerBookData.test.ts
index 7c0119d9..62d98951 100644
--- a/src/__tests__/hooks/useInterlinearizerBookData.test.ts
+++ b/src/__tests__/hooks/useInterlinearizerBookData.test.ts
@@ -319,4 +319,36 @@ describe('useInterlinearizerBookData', () => {
       },
     );
   });
+
+  it('re-runs tokenization when retokenizeKey changes even if USJ data is unchanged', () => {
+    jest.mocked(extractBookFromUsj).mockReturnValue(TEST_RAW_BOOK);
+    jest.mocked(tokenizeBook).mockReturnValue(TEST_BOOK);
+
+    const { rerender } = renderHook(
+      ({ retokenizeKey }: { retokenizeKey: number }) =>
+        useInterlinearizerBookData({
+          projectId: 'test-project',
+          scrRef: { ...GEN_1_1_SRC_REF },
+          retokenizeKey,
+        }),
+      { initialProps: { retokenizeKey: 0 } },
+    );
+
+    const callsAfterFirst = jest.mocked(tokenizeBook).mock.calls.length;
+
+    rerender({ retokenizeKey: 1 });
+
+    expect(jest.mocked(tokenizeBook).mock.calls.length).toBeGreaterThan(callsAfterFirst);
+  });
+
+  it('defaults retokenizeKey to 0 when not provided', () => {
+    jest.mocked(extractBookFromUsj).mockReturnValue(TEST_RAW_BOOK);
+    jest.mocked(tokenizeBook).mockReturnValue(TEST_BOOK);
+
+    const { result } = renderHook(() =>
+      useInterlinearizerBookData({ projectId: 'test-project', scrRef: { ...GEN_1_1_SRC_REF } }),
+    );
+
+    expect(result.current.book).toBe(TEST_BOOK);
+  });
 });
diff --git a/src/components/InterlinearizerLoader.tsx b/src/components/InterlinearizerLoader.tsx
index a3e8a1ec..a11d54e4 100644
--- a/src/components/InterlinearizerLoader.tsx
+++ b/src/components/InterlinearizerLoader.tsx
@@ -1,7 +1,9 @@
 import type { UseWebViewScrollGroupScrRefHook } from '@papi/core';
 import { useLocalizedStrings } from '@papi/frontend/react';
+import type { Localized, MultiColumnMenu } from 'platform-bible-utils';
+import type { SelectMenuItemHandler } from 'platform-bible-react';
 import { TabToolbar } from 'platform-bible-react';
-import { useMemo } from 'react';
+import { useCallback, useMemo, useState } from 'react';
 import ContinuousScrollToggle from './ContinuousScrollToggle';
 import Interlinearizer from './Interlinearizer';
 import ScriptureNavControls from './ScriptureNavControls';
@@ -9,7 +11,24 @@ 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;
+const STRING_KEYS = [
+  '%interlinearizer_continuousScrollToggle%',
+  '%interlinearizer_retokenize%',
+] as const;
+
+/** Command name for the retokenize project menu item. */
+const RETOKENIZE_COMMAND = 'interlinearizer.retokenize' as const;
+
+/** Structural shell of the project menu; label is filled in at render time from localized strings. */
+const PROJECT_MENU_SHELL = {
+  columns: { 'interlinearizer.projectData.column': { order: 1, label: '' } },
+  groups: {
+    'interlinearizer.projectData': {
+      column: 'interlinearizer.projectData.column',
+      order: 1,
+    },
+  },
+} as const satisfies Omit<Localized<MultiColumnMenu>, 'items'>;
 
 /**
  * Root component for loading the Interlinearizer. Loads book data and settings, then renders error
@@ -35,10 +54,13 @@ export default function InterlinearizerLoader({
     value: continuousScroll,
   } = useOptimisticBooleanSetting(projectId, 'interlinearizer.continuousScroll', true);
 
+  const [retokenizeKey, setRetokenizeKey] = useState(0);
+
   const { book, chapterSegments, isLoading, bookError, tokenizeError } = useInterlinearizerBookData(
     {
       projectId,
       scrRef,
+      retokenizeKey,
     },
   );
 
@@ -47,6 +69,33 @@ export default function InterlinearizerLoader({
 
   const [localizedStrings] = useLocalizedStrings(useMemo(() => [...STRING_KEYS], []));
 
+  const projectMenuData = useMemo<Localized<MultiColumnMenu>>(
+    () => ({
+      ...PROJECT_MENU_SHELL,
+      items: [
+        {
+          command: RETOKENIZE_COMMAND,
+          group: 'interlinearizer.projectData',
+          label: localizedStrings['%interlinearizer_retokenize%'] ?? '',
+          localizeNotes: 'Project data menu > re-run tokenization from the latest USJ',
+          order: 1,
+        },
+      ],
+    }),
+    [localizedStrings],
+  );
+
+  /**
+   * Handles project menu item selections from the toolbar. Dispatches known command names to the
+   * appropriate local action; unknown commands are silently ignored.
+   *
+   * @param selectedMenuItem - The menu item that was selected.
+   * @param selectedMenuItem.command - The command name string from {@link PROJECT_MENU_SHELL}.
+   */
+  const handleSelectProjectMenuItem = useCallback<SelectMenuItemHandler>(({ command }) => {
+    if (command === RETOKENIZE_COMMAND) setRetokenizeKey((k) => k + 1);
+  }, []);
+
   const toolbar = (
     <TabToolbar
       className="tw:z-10"
@@ -66,8 +115,8 @@ export default function InterlinearizerLoader({
           onCheckedChange={handleContinuousScrollChange}
         />
       }
-      /* v8 ignore next -- stub required by TabToolbar API, no behaviour to test */
-      onSelectProjectMenuItem={() => {}}
+      onSelectProjectMenuItem={handleSelectProjectMenuItem}
+      projectMenuData={projectMenuData}
       /* v8 ignore next -- stub required by TabToolbar API, no behaviour to test */
       onSelectViewInfoMenuItem={() => {}}
     />
diff --git a/src/hooks/useInterlinearizerBookData.ts b/src/hooks/useInterlinearizerBookData.ts
index 8ce5dd3d..6a235daa 100644
--- a/src/hooks/useInterlinearizerBookData.ts
+++ b/src/hooks/useInterlinearizerBookData.ts
@@ -13,6 +13,11 @@ interface UseInterlinearizerBookDataArgs {
   projectId: string;
   /** Current scripture reference; only `book` and `chapterNum` are used to scope the data. */
   scrRef: SerializedVerseRef;
+  /**
+   * Incrementing this value forces the extract+tokenize pipeline to re-run even when the USJ
+   * document has not changed, providing a manual retokenize capability.
+   */
+  retokenizeKey?: number;
 }
 
 /** Return value of the {@link useInterlinearizerBookData} hook. */
@@ -35,11 +40,14 @@ interface UseInterlinearizerBookDataResult {
  * @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.
+ * @param args.retokenizeKey - Increment to force a re-run of the tokenize pipeline even when the
+ *   USJ document is unchanged. Defaults to `0`.
  * @returns The tokenized book, chapter segments, loading state, and any errors encountered.
  */
 export default function useInterlinearizerBookData({
   projectId,
   scrRef,
+  retokenizeKey = 0,
 }: Readonly<UseInterlinearizerBookDataArgs>): UseInterlinearizerBookDataResult {
   const bookScrRef = useMemo(
     () => ({ book: scrRef.book, chapterNum: 1, verseNum: 1 }),
@@ -64,7 +72,8 @@ export default function useInterlinearizerBookData({
     } catch (err) {
       return [undefined, { message: err instanceof Error ? err.message : String(err), raw: err }];
     }
-  }, [bookResult, writingSystem]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- retokenizeKey is intentional: incrementing it forces a re-run even when bookResult and writingSystem are unchanged
+  }, [bookResult, writingSystem, retokenizeKey]);
 
   useEffect(() => {
     if (!tokenizeError) return;

From 1a09abfd0bd14162ba34067cbd15842fbbb88bb8 Mon Sep 17 00:00:00 2001
From: alex-rawlings-yyc <alex.rawlings@wycliffe.ca>
Date: Fri, 15 May 2026 15:56:23 -0600
Subject: [PATCH 2/3] Improve P.B React mock, improve test suite

---
 __mocks__/platform-bible-react.tsx            | 154 ++++++++++++------
 .../components/InterlinearizerLoader.test.tsx |  59 +------
 src/components/InterlinearizerLoader.tsx      |   2 +-
 3 files changed, 108 insertions(+), 107 deletions(-)

diff --git a/__mocks__/platform-bible-react.tsx b/__mocks__/platform-bible-react.tsx
index cbe04b04..decbf0ca 100644
--- a/__mocks__/platform-bible-react.tsx
+++ b/__mocks__/platform-bible-react.tsx
@@ -1,12 +1,26 @@
 /**
  * @file Jest mock for platform-bible-react. The real package ships ESM which Jest cannot parse
  * without extra transform configuration. This stub provides the subset used by extension
- * components: `BookChapterControl`, `BOOK_CHAPTER_CONTROL_STRING_KEYS`, `TabToolbar`, and
- * `ScrollGroupSelector`.
+ * components: `BookChapterControl`, `BOOK_CHAPTER_CONTROL_STRING_KEYS`, `TabToolbar`,
+ * `ScrollGroupSelector`, `Switch`, and `Label`.
  */
 
 import type { ReactElement, ReactNode } from 'react';
 
+export interface MenuItemContainingCommand {
+  label: `%${string}%`;
+  command: `${string}.${string}`;
+  group: `${string}.${string}`;
+  order: number;
+  localizeNotes: string;
+  tooltip?: `%${string}%`;
+  searchTerms?: `%${string}%`;
+  iconPathBefore?: string;
+  iconPathAfter?: string;
+}
+
+export type SelectMenuItemHandler = (selectedMenuItem: MenuItemContainingCommand) => void;
+
 interface SerializedVerseRef {
   book: string;
   chapterNum: number;
@@ -15,79 +29,119 @@ interface SerializedVerseRef {
   versificationStr?: string;
 }
 
-export const BOOK_CHAPTER_CONTROL_STRING_KEYS: string[] = [];
+/** Localization keys required by {@link BookChapterControl}. */
+export const BOOK_CHAPTER_CONTROL_STRING_KEYS = [
+  '%scripture_section_ot_long%',
+  '%scripture_section_nt_long%',
+  '%scripture_section_dc_long%',
+  '%scripture_section_extra_long%',
+  '%history_recent%',
+  '%history_recentSearches_ariaLabel%',
+] as const;
 
-interface MenuItemContainingCommand {
-  command: string;
-  label?: string;
-}
-
-type SelectMenuItemHandler = (selectedMenuItem: MenuItemContainingCommand) => void;
+/** Sentinel menu item fired when the retokenize toolbar button is clicked in tests. */
+export const MOCK_RETOKENIZE_MENU_ITEM: MenuItemContainingCommand = {
+  label: '%interlinearizer_retokenize%',
+  command: 'interlinearizer.retokenize',
+  group: 'interlinearizer.projectData',
+  order: 1,
+  localizeNotes: '',
+};
 
 /**
- * Stub for `TabToolbar`. Renders start and end children, and one `<button>` per project menu item
- * so tests can click individual commands via `data-testid="project-menu-item-{command}"`.
+ * Stub toolbar that renders a fixed button per known project menu action, each firing a sentinel
+ * {@link MenuItemContainingCommand} so tests can trigger commands by clicking a stable
+ * `data-testid` without coupling to `projectMenuData` shape.
  *
  * @param props - Component props.
- * @param props.startAreaChildren - Children rendered in the toolbar start area.
- * @param props.endAreaChildren - Children rendered in the toolbar end area.
- * @param props.onSelectProjectMenuItem - Handler called when a project menu button is clicked.
- * @param props.projectMenuData - Menu data whose items are rendered as clickable buttons.
+ * @param props.startAreaChildren - Content rendered in the start slot.
+ * @param props.endAreaChildren - Content rendered in the end slot.
+ * @param props.onSelectProjectMenuItem - Called with a sentinel item when a project-menu button is
+ *   clicked.
+ * @param props.onSelectViewInfoMenuItem - Called with a sentinel item when the view-info button is
+ *   clicked.
+ * @returns A div with `data-testid="tab-toolbar"` containing the rendered buttons.
  */
 export function TabToolbar({
   startAreaChildren,
   endAreaChildren,
   onSelectProjectMenuItem,
-  projectMenuData,
+  onSelectViewInfoMenuItem,
 }: Readonly<{
   className?: string;
   startAreaChildren?: ReactNode;
+  centerAreaChildren?: ReactNode;
   endAreaChildren?: ReactNode;
-  onSelectProjectMenuItem?: SelectMenuItemHandler;
-  onSelectViewInfoMenuItem?: SelectMenuItemHandler;
-  projectMenuData?: { items?: MenuItemContainingCommand[] };
+  onSelectProjectMenuItem: SelectMenuItemHandler;
+  onSelectViewInfoMenuItem: SelectMenuItemHandler;
+  projectMenuData?: unknown;
+  tabViewMenuData?: unknown;
+  id?: string;
+  menuButtonIcon?: ReactNode;
 }>): ReactElement {
   return (
     <div data-testid="tab-toolbar">
       <div data-testid="tab-toolbar-start">{startAreaChildren}</div>
       <div data-testid="tab-toolbar-end">{endAreaChildren}</div>
-      {projectMenuData?.items?.map(({ command, label }) => (
+      {onSelectProjectMenuItem && (
         <button
-          key={command}
-          aria-label={label}
-          data-testid={`project-menu-item-${command}`}
-          onClick={() => onSelectProjectMenuItem?.({ command })}
           type="button"
-        />
-      ))}
+          data-testid="tab-toolbar-retokenize"
+          onClick={() => onSelectProjectMenuItem(MOCK_RETOKENIZE_MENU_ITEM)}
+        >
+          Retokenize
+        </button>
+      )}
+      {onSelectViewInfoMenuItem && (
+        <button
+          type="button"
+          data-testid="tab-toolbar-view-info-menu"
+          onClick={() =>
+            onSelectViewInfoMenuItem({
+              label: '%mock.viewInfo%',
+              command: 'mock.viewInfo',
+              group: 'mock.group',
+              order: 0,
+              localizeNotes: '',
+            })
+          }
+        >
+          View info menu
+        </button>
+      )}
     </div>
   );
 }
 
 /**
- * Stub for `ScrollGroupSelector`. Renders a `<select>` element with one option per available scroll
- * group ID so tests can drive scroll-group changes without the real component.
+ * Stub scroll-group selector rendered as a native `<select>` so tests can change the scroll group
+ * without the real component's styling or animation.
  *
  * @param props - Component props.
- * @param props.availableScrollGroupIds - The set of scroll group IDs to render as options.
- * @param props.scrollGroupId - The currently selected scroll group ID.
- * @param props.onChangeScrollGroupId - Handler called when the selection changes.
+ * @param props.availableScrollGroupIds - IDs to populate as `<option>` elements.
+ * @param props.scrollGroupId - The currently selected group ID.
+ * @param props.onChangeScrollGroupId - Called with the newly selected ID when the selection changes.
+ * @returns A `<select data-testid="scroll-group-selector">` element.
  */
 export function ScrollGroupSelector({
   availableScrollGroupIds,
   scrollGroupId,
   onChangeScrollGroupId,
 }: Readonly<{
-  availableScrollGroupIds?: (number | undefined)[];
-  scrollGroupId?: number;
-  onChangeScrollGroupId?: (id: number | undefined) => void;
+  availableScrollGroupIds: (number | undefined)[];
+  scrollGroupId: number | undefined;
+  onChangeScrollGroupId: (id: number | undefined) => void;
+  localizedStrings?: Record<string, string>;
+  size?: 'default' | 'sm';
+  className?: string;
+  id?: string;
 }>): ReactElement {
   return (
     <select
       data-testid="scroll-group-selector"
       value={scrollGroupId ?? ''}
       onChange={(e) =>
-        onChangeScrollGroupId?.(e.target.value === '' ? undefined : Number(e.target.value))
+        onChangeScrollGroupId(e.target.value === '' ? undefined : Number(e.target.value))
       }
     >
       <option value="">—</option>
@@ -101,13 +155,14 @@ export function ScrollGroupSelector({
 }
 
 /**
- * Stub for `BookChapterControl`. Renders the current reference as text and a submit button so tests
- * can trigger reference changes without the real component.
+ * Stub book/chapter control that displays the current reference as text and exposes a single
+ * "Submit reference" button so tests can simulate reference changes without the real picker UI.
  *
  * @param props - Component props.
- * @param props.scrRef - The current scripture reference to display.
- * @param props.handleSubmit - Handler called with the reference when the submit button is clicked.
- * @param props.onAddRecentSearch - Handler called with the reference alongside `handleSubmit`.
+ * @param props.scrRef - The currently displayed scripture reference.
+ * @param props.handleSubmit - Called with `scrRef` when the submit button is clicked.
+ * @param props.onAddRecentSearch - Called with `scrRef` after `handleSubmit` when provided.
+ * @returns A `<div data-testid="book-chapter-control">` with a submit button.
  */
 export function BookChapterControl({
   scrRef,
@@ -117,6 +172,8 @@ export function BookChapterControl({
   scrRef: SerializedVerseRef;
   handleSubmit: (ref: SerializedVerseRef) => void;
   className?: string;
+  getActiveBookIds?: () => string[];
+  localizedBookNames?: Map<string, { localizedId: string; localizedName: string }>;
   localizedStrings?: Record<string, string>;
   recentSearches?: SerializedVerseRef[];
   onAddRecentSearch?: (scrRef: SerializedVerseRef) => void;
@@ -139,14 +196,15 @@ export function BookChapterControl({
 }
 
 /**
- * Stub for `Switch`. Renders a checkbox input so tests can toggle boolean settings without the real
- * component.
+ * Stub toggle switch rendered as a native checkbox so tests can read and change the checked state
+ * without the real Radix UI implementation.
  *
  * @param props - Component props.
  * @param props.checked - Whether the switch is on.
  * @param props.disabled - Whether the switch is disabled.
- * @param props.id - HTML id attribute for label association.
- * @param props.onCheckedChange - Handler called with the new boolean value on change.
+ * @param props.id - HTML `id` attribute forwarded to the input.
+ * @param props.onCheckedChange - Called with the new boolean state on change.
+ * @returns A native `<input type="checkbox">` element.
  */
 export function Switch({
   checked,
@@ -171,13 +229,13 @@ export function Switch({
 }
 
 /**
- * Stub for `Label`. Renders a plain `<label>` element so tests can locate labeled controls without
- * the real component's styling.
+ * Stub label rendered as a native `<label>` element.
  *
  * @param props - Component props.
  * @param props.children - Label content.
- * @param props.className - CSS class forwarded to the label element.
- * @param props.htmlFor - The `for` attribute linking this label to a form control.
+ * @param props.className - CSS class names.
+ * @param props.htmlFor - ID of the associated form control.
+ * @returns A native `<label>` element.
  */
 export function Label({
   children,
diff --git a/src/__tests__/components/InterlinearizerLoader.test.tsx b/src/__tests__/components/InterlinearizerLoader.test.tsx
index 870d54cf..a55fd670 100644
--- a/src/__tests__/components/InterlinearizerLoader.test.tsx
+++ b/src/__tests__/components/InterlinearizerLoader.test.tsx
@@ -294,35 +294,6 @@ describe('InterlinearizerLoader', () => {
     expect(mockOnChange).toHaveBeenCalledWith(true);
   });
 
-  it('falls back to an empty label when the retokenize string has not yet loaded', () => {
-    jest.mocked(useLocalizedStrings).mockReturnValue([{}, false]);
-    render(
-      <InterlinearizerLoader
-        projectId={testProjectId}
-        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
-      />,
-    );
-
-    expect(screen.getByTestId('project-menu-item-interlinearizer.retokenize')).toHaveAttribute(
-      'aria-label',
-      '',
-    );
-  });
-
-  it('renders the retokenize project menu item with the localized label', () => {
-    render(
-      <InterlinearizerLoader
-        projectId={testProjectId}
-        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
-      />,
-    );
-
-    expect(screen.getByTestId('project-menu-item-interlinearizer.retokenize')).toHaveAttribute(
-      'aria-label',
-      'Retokenize Book',
-    );
-  });
-
   it('increments retokenizeKey passed to useInterlinearizerBookData when retokenize is clicked', async () => {
     render(
       <InterlinearizerLoader
@@ -335,7 +306,7 @@ describe('InterlinearizerLoader', () => {
     const keyBefore =
       jest.mocked(useInterlinearizerBookData).mock.calls[callsBefore - 1][0].retokenizeKey ?? 0;
 
-    await userEvent.click(screen.getByTestId('project-menu-item-interlinearizer.retokenize'));
+    await userEvent.click(screen.getByTestId('tab-toolbar-retokenize'));
 
     const callsAfter = jest.mocked(useInterlinearizerBookData).mock.calls.length;
     const keyAfter =
@@ -343,32 +314,4 @@ describe('InterlinearizerLoader', () => {
 
     expect(keyAfter).toBe(keyBefore + 1);
   });
-
-  it('ignores unknown project menu commands without changing retokenizeKey', async () => {
-    // Simulate a foreign command arriving via onSelectProjectMenuItem
-    const { rerender } = render(
-      <InterlinearizerLoader
-        projectId={testProjectId}
-        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
-      />,
-    );
-
-    const callsBefore = jest.mocked(useInterlinearizerBookData).mock.calls.length;
-    const keyBefore =
-      jest.mocked(useInterlinearizerBookData).mock.calls[callsBefore - 1][0].retokenizeKey ?? 0;
-
-    // Re-render doesn't change retokenizeKey when no retokenize action taken
-    rerender(
-      <InterlinearizerLoader
-        projectId={testProjectId}
-        useWebViewScrollGroupScrRef={makeScrollGroupHook()}
-      />,
-    );
-
-    const callsAfter = jest.mocked(useInterlinearizerBookData).mock.calls.length;
-    const keyAfter =
-      jest.mocked(useInterlinearizerBookData).mock.calls[callsAfter - 1][0].retokenizeKey ?? 0;
-
-    expect(keyAfter).toBe(keyBefore);
-  });
 });
diff --git a/src/components/InterlinearizerLoader.tsx b/src/components/InterlinearizerLoader.tsx
index a11d54e4..1a734f31 100644
--- a/src/components/InterlinearizerLoader.tsx
+++ b/src/components/InterlinearizerLoader.tsx
@@ -76,7 +76,7 @@ export default function InterlinearizerLoader({
         {
           command: RETOKENIZE_COMMAND,
           group: 'interlinearizer.projectData',
-          label: localizedStrings['%interlinearizer_retokenize%'] ?? '',
+          label: localizedStrings['%interlinearizer_retokenize%'],
           localizeNotes: 'Project data menu > re-run tokenization from the latest USJ',
           order: 1,
         },

From c7cbe615ef63051e077259ef5cee0228c2307fb0 Mon Sep 17 00:00:00 2001
From: alex-rawlings-yyc <alex.rawlings@wycliffe.ca>
Date: Fri, 15 May 2026 16:26:31 -0600
Subject: [PATCH 3/3] Comply with menu usage pattern standards

---
 __mocks__/papi-frontend-react.ts              | 28 ++++++++++
 __mocks__/papi-frontend.ts                    |  7 +++
 contributions/localizedStrings.json           |  1 +
 contributions/menus.json                      | 26 ++++++++++
 .../components/InterlinearizerLoader.test.tsx | 26 +++++++---
 src/components/InterlinearizerLoader.tsx      | 52 +++++++------------
 6 files changed, 98 insertions(+), 42 deletions(-)

diff --git a/__mocks__/papi-frontend-react.ts b/__mocks__/papi-frontend-react.ts
index e7f99bb6..50e002da 100644
--- a/__mocks__/papi-frontend-react.ts
+++ b/__mocks__/papi-frontend-react.ts
@@ -10,6 +10,33 @@
  */
 const KNOWN_PROJECT_DATA_METHODS = new Set(['BookUSJ']);
 
+/** Known method names on data providers accessed via {@link useData}. */
+const KNOWN_DATA_METHODS = new Set(['WebViewMenu']);
+
+/**
+ * Mock for `useData`. 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.
+ *
+ * @param _providerName - Ignored data provider name.
+ * @returns Proxy object exposing known data methods.
+ */
+const useData = jest.fn((_providerName: unknown) =>
+  new Proxy(
+    {},
+    {
+      get(_target, prop: string | symbol) {
+        if (typeof prop === 'string' && KNOWN_DATA_METHODS.has(prop)) {
+          return () => [undefined, jest.fn(), false];
+        }
+        throw new Error(
+          `useData mock: unknown method "${String(prop)}". Add it to KNOWN_DATA_METHODS if intentional.`,
+        );
+      },
+    },
+  ),
+);
+
 /**
  * Mock for `useProjectData`. Returns an object whose known methods each return
  * `[undefined, jest.fn(), false]`, matching the real hook's `[data, setter, isLoading]` tuple.
@@ -74,6 +101,7 @@ const useRecentScriptureRefs = jest
 
 module.exports = {
   __esModule: true,
+  useData,
   useProjectData,
   useProjectSetting,
   useLocalizedStrings,
diff --git a/__mocks__/papi-frontend.ts b/__mocks__/papi-frontend.ts
index 009859da..f5070e57 100644
--- a/__mocks__/papi-frontend.ts
+++ b/__mocks__/papi-frontend.ts
@@ -10,8 +10,15 @@ const mockLogger = {
   warn: jest.fn(),
 };
 
+const mockPapi = {
+  menuData: {
+    dataProviderName: 'platform.menuDataServiceDataProvider',
+  },
+};
+
 module.exports = {
   __esModule: true,
+  default: mockPapi,
   logger: mockLogger,
 };
 
diff --git a/contributions/localizedStrings.json b/contributions/localizedStrings.json
index 787e9782..0c224d27 100644
--- a/contributions/localizedStrings.json
+++ b/contributions/localizedStrings.json
@@ -9,6 +9,7 @@
       "%interlinearizer_projectSettings_continuousScroll%": "Continuous Scroll",
       "%interlinearizer_projectSettings_continuousScrollDescription%": "Display tokens in a continuous horizontal scroll strip instead of chapter-segmented rows",
       "%interlinearizer_continuousScrollToggle%": "Continuous Scroll",
+      "%interlinearizer_menu_column_project%": "Project",
       "%interlinearizer_retokenize%": "Retokenize Book"
     }
   }
diff --git a/contributions/menus.json b/contributions/menus.json
index d5a03455..91815e2c 100644
--- a/contributions/menus.json
+++ b/contributions/menus.json
@@ -14,6 +14,32 @@
     "items": []
   },
   "webViewMenus": {
+    "interlinearizer.mainWebView": {
+      "topMenu": {
+        "columns": {
+          "interlinearizer.project": {
+            "label": "%interlinearizer_menu_column_project%",
+            "localizeNotes": "Interlinearizer top menu column for project actions",
+            "order": 1
+          }
+        },
+        "groups": {
+          "interlinearizer.projectActions": {
+            "column": "interlinearizer.project",
+            "order": 1
+          }
+        },
+        "items": [
+          {
+            "label": "%interlinearizer_retokenize%",
+            "localizeNotes": "Interlinearizer top menu > Re-run tokenization from the latest USJ",
+            "group": "interlinearizer.projectActions",
+            "order": 1,
+            "command": "interlinearizer.retokenize"
+          }
+        ]
+      }
+    },
     "platformScriptureEditor.react": {
       "topMenu": {
         "columns": {},
diff --git a/src/__tests__/components/InterlinearizerLoader.test.tsx b/src/__tests__/components/InterlinearizerLoader.test.tsx
index a55fd670..2ddcbe72 100644
--- a/src/__tests__/components/InterlinearizerLoader.test.tsx
+++ b/src/__tests__/components/InterlinearizerLoader.test.tsx
@@ -2,7 +2,7 @@
 /// <reference types="jest" />
 /// <reference types="@testing-library/jest-dom" />
 
-import { useLocalizedStrings } from '@papi/frontend/react';
+import { useData, 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';
@@ -133,13 +133,23 @@ describe('InterlinearizerLoader', () => {
     capturedInterlinearizerProps = undefined;
     mockBookData();
     mockOptimisticSetting();
-    jest.mocked(useLocalizedStrings).mockReturnValue([
-      {
-        '%interlinearizer_continuousScrollToggle%': 'Continuous Scroll',
-        '%interlinearizer_retokenize%': 'Retokenize Book',
-      },
-      false,
-    ]);
+    jest
+      .mocked(useLocalizedStrings)
+      .mockReturnValue([
+        { '%interlinearizer_continuousScrollToggle%': 'Continuous Scroll' },
+        false,
+      ]);
+    jest.mocked(useData).mockReturnValue(
+      new Proxy(
+        {},
+        {
+          get(_target, prop: string | symbol) {
+            if (prop === 'WebViewMenu') return () => [undefined, jest.fn(), false];
+            throw new Error(`useData mock: unexpected method "${String(prop)}"`);
+          },
+        },
+      ),
+    );
   });
 
   it('renders Interlinearizer and the nav controls when book data is available', () => {
diff --git a/src/components/InterlinearizerLoader.tsx b/src/components/InterlinearizerLoader.tsx
index 1a734f31..ffddf63b 100644
--- a/src/components/InterlinearizerLoader.tsx
+++ b/src/components/InterlinearizerLoader.tsx
@@ -1,6 +1,7 @@
 import type { UseWebViewScrollGroupScrRefHook } from '@papi/core';
-import { useLocalizedStrings } from '@papi/frontend/react';
-import type { Localized, MultiColumnMenu } from 'platform-bible-utils';
+import papi, { logger } from '@papi/frontend';
+import { useData, useLocalizedStrings } from '@papi/frontend/react';
+import { isPlatformError } from 'platform-bible-utils';
 import type { SelectMenuItemHandler } from 'platform-bible-react';
 import { TabToolbar } from 'platform-bible-react';
 import { useCallback, useMemo, useState } from 'react';
@@ -11,25 +12,11 @@ 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%',
-  '%interlinearizer_retokenize%',
-] as const;
+const STRING_KEYS = ['%interlinearizer_continuousScrollToggle%'] as const;
 
 /** Command name for the retokenize project menu item. */
 const RETOKENIZE_COMMAND = 'interlinearizer.retokenize' as const;
 
-/** Structural shell of the project menu; label is filled in at render time from localized strings. */
-const PROJECT_MENU_SHELL = {
-  columns: { 'interlinearizer.projectData.column': { order: 1, label: '' } },
-  groups: {
-    'interlinearizer.projectData': {
-      column: 'interlinearizer.projectData.column',
-      order: 1,
-    },
-  },
-} as const satisfies Omit<Localized<MultiColumnMenu>, 'items'>;
-
 /**
  * Root component for loading the Interlinearizer. Loads book data and settings, then renders error
  * and loading states or delegates to {@link Interlinearizer} when data is ready.
@@ -69,28 +56,23 @@ export default function InterlinearizerLoader({
 
   const [localizedStrings] = useLocalizedStrings(useMemo(() => [...STRING_KEYS], []));
 
-  const projectMenuData = useMemo<Localized<MultiColumnMenu>>(
-    () => ({
-      ...PROJECT_MENU_SHELL,
-      items: [
-        {
-          command: RETOKENIZE_COMMAND,
-          group: 'interlinearizer.projectData',
-          label: localizedStrings['%interlinearizer_retokenize%'],
-          localizeNotes: 'Project data menu > re-run tokenization from the latest USJ',
-          order: 1,
-        },
-      ],
-    }),
-    [localizedStrings],
+  /** Fetches the top-menu data for this WebView from the platform's menu data provider. */
+  const [webViewMenuPossiblyError] = useData(papi.menuData.dataProviderName).WebViewMenu(
+    'interlinearizer.mainWebView',
+    { topMenu: undefined, includeDefaults: true, contextMenu: undefined },
   );
 
+  const projectMenuData = useMemo(() => {
+    if (!webViewMenuPossiblyError || isPlatformError(webViewMenuPossiblyError)) return undefined;
+    return webViewMenuPossiblyError.topMenu;
+  }, [webViewMenuPossiblyError]);
+
   /**
    * Handles project menu item selections from the toolbar. Dispatches known command names to the
    * appropriate local action; unknown commands are silently ignored.
    *
    * @param selectedMenuItem - The menu item that was selected.
-   * @param selectedMenuItem.command - The command name string from {@link PROJECT_MENU_SHELL}.
+   * @param selectedMenuItem.command - The command name string registered in `menus.json`.
    */
   const handleSelectProjectMenuItem = useCallback<SelectMenuItemHandler>(({ command }) => {
     if (command === RETOKENIZE_COMMAND) setRetokenizeKey((k) => k + 1);
@@ -117,8 +99,10 @@ export default function InterlinearizerLoader({
       }
       onSelectProjectMenuItem={handleSelectProjectMenuItem}
       projectMenuData={projectMenuData}
-      /* v8 ignore next -- stub required by TabToolbar API, no behaviour to test */
-      onSelectViewInfoMenuItem={() => {}}
+      /* v8 ignore next 3 -- stub required by TabToolbar API, no behaviour to test */
+      onSelectViewInfoMenuItem={() => {
+        logger.warn('Interlinearizer: unexpected onSelectViewInfoMenuItem call');
+      }}
     />
   );