Improve docs, minor fixes

Author: alex-rawlings-yyc

__mocks__/lucide-react.tsx

@@ -4,12 +4,22 @@
 
 import type { ReactElement } from 'react';
 
-/** @param props - SVG props forwarded from the component. */
+/**
+ * Stub for the Trash2 icon; renders a bare SVG element so tests can locate the icon by test ID.
+ *
+ * @param props - SVG props forwarded from the component, including optional className and size.
+ * @returns A ReactElement SVG element used as a trash icon stub in tests.
+ */
 export function Trash2(props: Readonly<{ className?: string; size?: number }>): ReactElement {
   return <svg data-testid="trash-icon" {...props} />;
 }
 
-/** @param props - SVG props forwarded from the component. */
+/**
+ * Stub for the Info icon; renders a bare SVG element so tests can locate the icon by test ID.
+ *
+ * @param props - SVG props forwarded from the component, including optional className and size.
+ * @returns A ReactElement SVG element used as an info icon stub in tests.
+ */
 export function Info(props: Readonly<{ className?: string; size?: number }>): ReactElement {
   return <svg data-testid="info-icon" {...props} />;
 }

src/__tests__/components/ContinuousView.test.tsx

@@ -185,6 +185,8 @@ function makeSingleTokenBook(): Book {
  * A book whose GEN 1:1 segment has word tokens and whose GEN 1:2 segment has only a punctuation
  * token (no word tokens). Used to exercise code paths that run when a segment exists in the book
  * but contributes nothing to phraseEntries / segmentStartIndex.
+ *
+ * @returns A two-segment Book where the second segment has no word tokens.
  */
 function makeMixedBook(): Book {
   return {

src/__tests__/components/InterlinearizerLoader.test.tsx

@@ -71,6 +71,48 @@ type MockProject = {
 
 const testProjectId = 'test-project-id';
 
+jest.mock('../../hooks/useInterlinearizerBookData');
+jest.mock('../../hooks/useOptimisticBooleanSetting');
+
+jest.mock('../../components/ContinuousView', () => ({
+  __esModule: true,
+  default: () => <div data-testid="continuous-view" />,
+}));
+
+jest.mock('../../components/Interlinearizer', () => ({
+  __esModule: true,
+  default: () => <div data-testid="interlinearizer" />,
+}));
+
+jest.mock('../../components/ContinuousScrollToggle', () => ({
+  __esModule: true,
+  default: ({
+    checked,
+    disabled,
+    onCheckedChange,
+  }: {
+    checked: boolean;
+    disabled: boolean;
+    label: string;
+    onCheckedChange: (v: boolean) => void;
+  }) => (
+    <input
+      type="checkbox"
+      data-testid="continuous-scroll-toggle"
+      checked={checked}
+      disabled={disabled}
+      onChange={(e) => {
+        if (!disabled) onCheckedChange(e.target.checked);
+      }}
+    />
+  ),
+}));
+
+jest.mock('../../components/ScriptureNavControls', () => ({
+  __esModule: true,
+  default: () => <div data-testid="scripture-nav-controls" />,
+}));
+
 const STUB_ACTIVE_PROJECT: MockProject = {
   id: 'proj-1',
   createdAt: '2026-01-01T00:00:00Z',
@@ -81,6 +123,19 @@ const STUB_ACTIVE_PROJECT: MockProject = {
 
 jest.mock('../../components/ProjectModals', () => ({
   __esModule: true,
+  /**
+   * Minimal ProjectModals stand-in that drives modal state and active-project state through the
+   * same `useWebViewState` hook the real component uses, so tests can assert on state transitions
+   * without mounting the full modal tree.
+   *
+   * @param modal - Current modal identifier controlling which stub panel is rendered.
+   * @param setModal - Callback to transition to a different modal state.
+   * @param activeProject - The currently active interlinear project, or undefined when none is
+   *   selected.
+   * @param useWebViewState - Injected hook used to read and write persisted WebView state; must
+   *   support the `'activeProject'` key.
+   * @returns A JSX element containing the stub modal panels keyed by `modal`.
+   */
   default: function StubProjectModals({
     modal,
     setModal,

src/__tests__/main.test.ts

@@ -26,6 +26,9 @@ interface PapiBackendTestMock {
 /**
  * Type guard for the mocked @papi/backend default export. Allows destructuring mocks without type
  * assertions.
+ *
+ * @param m - The value to test, typically the default export of the mocked module.
+ * @returns `true` if `m` exposes all expected `__mock*` properties.
  */
 function isPapiBackendTestMock(m: unknown): m is PapiBackendTestMock {
   return (
@@ -74,6 +77,12 @@ type WebViewProvider = {
   ): Promise<WebViewDefinition | undefined>;
 };
 
+/**
+ * Type guard that narrows an unknown value to a {@link WebViewProvider}.
+ *
+ * @param x - The value to test.
+ * @returns `true` if `x` has a callable `getWebView` method.
+ */
 function isWebViewProvider(x: unknown): x is WebViewProvider {
   return !!x && typeof x === 'object' && 'getWebView' in x && typeof x.getWebView === 'function';
 }
@@ -85,12 +94,26 @@ function getRegisteredProvider(): WebViewProvider {
   return raw;
 }
 
+/**
+ * Finds the handler registered for `commandName` in the most recent `activate()` call.
+ *
+ * @param commandName - The fully-qualified command name to look up.
+ * @returns The registered handler function, or `undefined` if none was registered for that name.
+ */
 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];
   return isCallable(rawHandler) ? rawHandler : undefined;
 }
 
+/**
+ * Activates the extension and returns a typed wrapper around the `interlinearizer.openForWebView`
+ * command handler.
+ *
+ * @returns A function that invokes the handler with an optional WebView ID and resolves to the
+ *   opened WebView ID string, or `undefined` if the handler returns a non-string.
+ * @throws If the handler was not registered during `activate()`.
+ */
 async function getOpenForWebViewHandler(): Promise<
   (webViewId?: string) => Promise<string | undefined>
 > {
@@ -128,6 +151,14 @@ function getCloseWebViewCallback(): (event: { webView: SavedWebViewDefinition })
   return (event) => cb(event);
 }
 
+/**
+ * Activates the extension and returns a typed wrapper around the `interlinearizer.createProject`
+ * command handler.
+ *
+ * @returns A function that invokes the handler with a source project ID and analysis languages,
+ *   resolving to the JSON-stringified project or `undefined` if the handler returns a non-string.
+ * @throws If the handler was not registered during `activate()`.
+ */
 async function getCreateProjectHandler(): Promise<
   (sourceProjectId: string, analysisLanguages: string[]) => Promise<string | undefined>
 > {
@@ -144,6 +175,14 @@ async function getCreateProjectHandler(): Promise<
   };
 }
 
+/**
+ * Activates the extension and returns a typed wrapper around the `interlinearizer.deleteProject`
+ * command handler.
+ *
+ * @returns A function that invokes the handler with a project UUID and resolves when deletion
+ *   completes.
+ * @throws If the handler was not registered during `activate()`.
+ */
 async function getDeleteProjectHandler(): Promise<(id: string) => Promise<void>> {
   const context = createTestActivationContext();
   await activate(context);
@@ -154,6 +193,14 @@ async function getDeleteProjectHandler(): Promise<(id: string) => Promise<void>>
   };
 }
 
+/**
+ * Activates the extension and returns a typed wrapper around the
+ * `interlinearizer.getProjectsForSource` command handler.
+ *
+ * @returns A function that invokes the handler with a source project ID and resolves to the
+ *   JSON-stringified project array (falls back to `'[]'` if the handler returns a non-string).
+ * @throws If the handler was not registered during `activate()`.
+ */
 async function getProjectsForSourceHandler(): Promise<
   (sourceProjectId: string) => Promise<string>
 > {
@@ -167,6 +214,15 @@ async function getProjectsForSourceHandler(): Promise<
   };
 }
 
+/**
+ * Activates the extension and returns a typed wrapper around the
+ * `interlinearizer.updateProjectMetadata` command handler.
+ *
+ * @returns A function that invokes the handler with a project UUID and updated fields, resolving to
+ *   the JSON-stringified updated project or `undefined` if the project was not found or the handler
+ *   returns a non-string.
+ * @throws If the handler was not registered during `activate()`.
+ */
 async function getUpdateProjectMetadataHandler(): Promise<
   (
     id: string,

src/main.ts

@@ -336,7 +336,7 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
         result: {
           name: 'return value',
           summary:
-            'JSON-stringified InterlinearProject for the new project, or undefined if storage failed',
+            'JSON-stringified InterlinearProject for the new project; rejects (throws) on storage failure',
           schema: { type: 'string' },
         },
       },
@@ -409,7 +409,7 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
         result: {
           name: 'return value',
           summary:
-            'JSON-stringified updated InterlinearProject, or undefined if not found or if a storage failure occurred',
+            'JSON-stringified updated InterlinearProject, or undefined if no project with that ID exists; rejects (throws) on storage failure',
           schema: { type: 'string' },
         },
       },

src/types/interlinearizer.d.ts

@@ -18,6 +18,12 @@ declare module 'papi-shared-types' {
      * Opens the Interlinearizer for the project associated with the given WebView ID. Called from
      * WebView context menus, which pass the tab's WebView ID as the argument. Falls back to a
      * project picker dialog if the WebView has no project or no ID is given.
+     *
+     * @param webViewId - ID of the WebView tab whose associated project should be opened; when
+     *   omitted or when the WebView has no linked project, a project-picker dialog is shown
+     *   instead.
+     * @returns A promise that resolves to the opened WebView ID, or `undefined` if the user
+     *   dismissed the picker without selecting a project.
      */
     'interlinearizer.openForWebView': (webViewId?: string) => Promise<string | undefined>;
 
@@ -54,6 +60,11 @@ declare module 'papi-shared-types' {
      *
      * @param sourceProjectId Platform.Bible project ID of the source text to query.
      * @returns A JSON string containing an `InterlinearProject[]`; `"[]"` when none exist.
+     * @throws {SyntaxError} If the project-IDs index or any stored project record contains invalid
+     *   JSON.
+     * @throws If `papi.storage.readUserData` rejects for a reason other than the file not existing
+     *   (propagated from the storage layer). Callers can use this to distinguish a storage outage
+     *   from a legitimately empty list.
      */
     'interlinearizer.getProjectsForSource': (sourceProjectId: string) => Promise<string>;