From b9dfa12808b174b61993d359f847770378a9bf04 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 14 Jul 2026 10:03:28 +0000
Subject: [PATCH 1/3] perf(viewer): isolate the PDF subtree and decouple page
 navigation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three render-cost reductions on the document viewer, all frontend/offline:

- Page/chunk navigation no longer triggers a full document reload. The main
  load effect now distinguishes a full (re)load — new documentId or explicit
  retry — from navigation on the already-loaded document via a loadedKeyRef.
  Navigation skips the loading reset, keeps the mounted PDF/content on screen
  (no flash), preserves current content on a transient detail failure, and
  does not re-issue signed URLs.

- The app-shell scroll container (#main-content) is resolved synchronously and
  the MutationObserver only watches until it appears, then disconnects — rather
  than reacting to every app-wide DOM mutation for the viewer's lifetime.

- The heaviest subtree (PdfCanvasViewer, holding the pdf.js document and the
  canvas raster) plus NativePdfEmbed and NonPdfSourcePreview are wrapped in
  memo, and the two PDF callbacks (onUrlExpired/onLoadSuccess) are stabilised
  with useCallback. Unrelated parent re-renders — source-search keystrokes,
  composer focus, connectivity changes — no longer re-render or re-rasterise
  the viewer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DqMTk5fDNgi5GwEK5peRmj
---
 src/components/DocumentViewer.tsx             | 67 +++++++++++++------
 .../non-pdf-source-preview.tsx                |  6 +-
 .../document-viewer/pdf-canvas-viewer.tsx     | 22 ++++--
 3 files changed, 68 insertions(+), 27 deletions(-)

diff --git a/src/components/DocumentViewer.tsx b/src/components/DocumentViewer.tsx
index 09d276f2b..70237fd87 100644
--- a/src/components/DocumentViewer.tsx
+++ b/src/components/DocumentViewer.tsx
@@ -1600,18 +1600,25 @@ export function DocumentViewer({
   const [shellScrollContainer, setShellScrollContainer] = useState<HTMLElement | null>(null);
   useEffect(() => {
     let cancelled = false;
+    let observer: MutationObserver | null = null;
+    // #main-content is the app-shell scroll container: it mounts once (usually
+    // before this effect runs) and persists for the viewer's lifetime. Resolve it
+    // synchronously, and only fall back to observing the DOM until it appears —
+    // then disconnect, rather than reacting to every app-wide mutation forever.
     const sync = () => {
       if (cancelled) return;
       const main = window.document.getElementById("main-content");
+      if (!main) return;
       setShellScrollContainer((current) => (current === main ? current : main));
+      observer?.disconnect();
+      observer = null;
     };
-    const frame = window.requestAnimationFrame(sync);
-    const observer = new MutationObserver(sync);
+    observer = new MutationObserver(sync);
     observer.observe(window.document.body, { childList: true, subtree: true });
+    sync();
     return () => {
       cancelled = true;
-      window.cancelAnimationFrame(frame);
-      observer.disconnect();
+      observer?.disconnect();
     };
   }, []);
   const scrollHidden = useHideOnScroll(shellScrollContainer ? { scrollContainer: shellScrollContainer } : {});
@@ -1823,6 +1830,12 @@ export function DocumentViewer({
 
   useEffect(() => () => refreshControllerRef.current?.abort(), []);
 
+  // Distinguishes a full document (re)load — a new documentId or an explicit
+  // retry (previewAttempt) — from page/chunk navigation on the already-loaded
+  // document. Navigation only re-windows the detail; a full load also resets the
+  // preview and re-issues signed URLs.
+  const loadedKeyRef = useRef<string | null>(null);
+
   useEffect(() => {
     if (!canViewSourceDocuments && authStatus === "loading") {
       return () => undefined;
@@ -1833,8 +1846,12 @@ export function DocumentViewer({
 
     const controller = new AbortController();
     const authRequest = registerAuthRequest(controller);
+    const loadKey = `${documentId}::${previewAttempt}`;
+    const isFullReload = loadedKeyRef.current !== loadKey;
     const reset = window.setTimeout(() => {
-      if (!controller.signal.aborted) {
+      // Skip the reset on navigation so the mounted PDF and current content stay
+      // visible (no loading flash) while the new page window loads in the background.
+      if (!controller.signal.aborted && isFullReload) {
         setLoadingDocument(true);
         setViewerError(null);
         setPreviewError(null);
@@ -1871,17 +1888,21 @@ export function DocumentViewer({
           if (!response.ok) throw new Error(payload.error || "Document details could not be loaded.");
           return payload;
         });
-        const signedUrlPair = fetchSignedUrlPair(signedUrlEndpoint, downloadSignedUrlEndpoint, {
-          signal: controller.signal,
-          headers: clientDemoMode ? undefined : authorizationHeader,
-          onUnauthorized: markSessionExpired,
-          useCache: true,
-        });
+        // Navigation keeps the current signed URLs; only a full load re-issues them.
+        const signedUrlPair = isFullReload
+          ? fetchSignedUrlPair(signedUrlEndpoint, downloadSignedUrlEndpoint, {
+              signal: controller.signal,
+              headers: clientDemoMode ? undefined : authorizationHeader,
+              onUnauthorized: markSessionExpired,
+              useCache: true,
+            })
+          : Promise.resolve(null);
 
         return Promise.all([Promise.allSettled([detailRequest]), signedUrlPair]);
       })
-      .then(([[detailResult], [signedUrlResult, signedDownloadUrlResult]]) => {
+      .then(([[detailResult], signedUrlPair]) => {
         if (controller.signal.aborted || !isAuthEpochCurrent(authRequest.epoch)) return;
+        loadedKeyRef.current = loadKey;
 
         if (detailResult.status === "fulfilled") {
           const detail = detailResult.value;
@@ -1891,7 +1912,9 @@ export function DocumentViewer({
           setTableFacts(detail.tableFacts ?? []);
           setChunks(detail.chunks ?? []);
           setIndexHealth(detail.indexHealth ?? null);
-        } else {
+        } else if (isFullReload) {
+          // Only clear the viewer on a full load; a transient detail failure
+          // during navigation keeps the current content on screen.
           setDocument(null);
           setPages([]);
           setImages([]);
@@ -1911,11 +1934,14 @@ export function DocumentViewer({
           }
         }
 
-        applySignedUrlResults(signedUrlResult, signedDownloadUrlResult, signedUrlEndpoint, downloadSignedUrlEndpoint);
+        if (signedUrlPair) {
+          const [signedUrlResult, signedDownloadUrlResult] = signedUrlPair;
+          applySignedUrlResults(signedUrlResult, signedDownloadUrlResult, signedUrlEndpoint, downloadSignedUrlEndpoint);
+        }
       })
       .catch((error) => {
         if (controller.signal.aborted || !isAuthEpochCurrent(authRequest.epoch)) return;
-        setViewerError(error instanceof Error ? error.message : "Document could not be loaded.");
+        if (isFullReload) setViewerError(error instanceof Error ? error.message : "Document could not be loaded.");
       })
       .finally(() => {
         if (!controller.signal.aborted) setLoadingDocument(false);
@@ -2191,20 +2217,23 @@ export function DocumentViewer({
   // The PDF signed URL has a 10-min TTL and pdf.js holds a dead reference once it
   // expires. When the canvas reports an expiry, drop the cached URLs and re-run
   // the fetch pipeline to mint fresh ones (bounded so a broken URL can't loop).
-  const handleSignedUrlExpired = () => {
+  // Stable identity (useCallback) so the memoised PdfCanvasViewer isn't re-rendered
+  // — and its page re-rastered — every time an unrelated parent state (source-search
+  // keystroke, composer focus, online/offline) changes.
+  const handleSignedUrlExpired = useCallback(() => {
     if (signedUrlRefreshCountRef.current >= 2) return;
     signedUrlRefreshCountRef.current += 1;
     const signedUrlEndpoint = `/api/documents/${documentId}/signed-url`;
     clearCachedSignedUrl(signedUrlEndpoint);
     clearCachedSignedUrl(`${signedUrlEndpoint}?download=true`);
     refreshSignedUrls();
-  };
+  }, [documentId, refreshSignedUrls]);
   // A successful reload means the refreshed URL was accepted, so the recovery
   // worked — restore the budget for the next (unrelated) TTL expiry. A broken
   // URL never loads, so it never resets, and the cap still stops its loop.
-  const handlePdfLoadSuccess = () => {
+  const handlePdfLoadSuccess = useCallback(() => {
     signedUrlRefreshCountRef.current = 0;
-  };
+  }, []);
   const handleDocumentRenamed = (updatedDocument: ClinicalDocument) => {
     setDocument((current) => (current?.id === updatedDocument.id ? { ...current, ...updatedDocument } : current));
   };
diff --git a/src/components/document-viewer/non-pdf-source-preview.tsx b/src/components/document-viewer/non-pdf-source-preview.tsx
index 140cc5b6e..b69bd54f2 100644
--- a/src/components/document-viewer/non-pdf-source-preview.tsx
+++ b/src/components/document-viewer/non-pdf-source-preview.tsx
@@ -2,7 +2,7 @@
 
 /* eslint-disable @next/next/no-img-element */
 
-import { useState } from "react";
+import { memo, useState } from "react";
 import { CircleAlert, Download, ExternalLink, FileText } from "lucide-react";
 
 import { cn, floatingControl } from "@/components/ui-primitives";
@@ -21,7 +21,7 @@ const placeholderSurface =
  * - other (DOCX/XLSX/…) → an honest "download to view" affordance,
  * - no signed URL yet → the original placeholder.
  */
-export function NonPdfSourcePreview({
+export const NonPdfSourcePreview = memo(function NonPdfSourcePreview({
   fileType,
   title,
   signedUrl,
@@ -87,7 +87,7 @@ export function NonPdfSourcePreview({
       </div>
     </div>
   );
-}
+});
 
 /**
  * Inline image with a failure fallback. The source is a direct signed URL owned
diff --git a/src/components/document-viewer/pdf-canvas-viewer.tsx b/src/components/document-viewer/pdf-canvas-viewer.tsx
index 6f213fe9a..709c4a581 100644
--- a/src/components/document-viewer/pdf-canvas-viewer.tsx
+++ b/src/components/document-viewer/pdf-canvas-viewer.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { type KeyboardEvent as ReactKeyboardEvent, useCallback, useEffect, useRef, useState } from "react";
+import { type KeyboardEvent as ReactKeyboardEvent, memo, useCallback, useEffect, useRef, useState } from "react";
 import {
   ChevronLeft,
   ChevronRight,
@@ -44,7 +44,11 @@ function isLikelyExpiredUrl(error: unknown): boolean {
   );
 }
 
-export function PdfCanvasViewer({
+// Memoised: this is the heaviest subtree in the document view (it holds the
+// pdf.js document and re-rasters the canvas). With stable props from the parent
+// it skips re-render when unrelated parent state (search, composer, connectivity)
+// changes, so a keystroke elsewhere never re-rasterises the page.
+export const PdfCanvasViewer = memo(function PdfCanvasViewer({
   url,
   title,
   initialPage,
@@ -553,14 +557,22 @@ export function PdfCanvasViewer({
       </div>
     </div>
   );
-}
+});
 
 function nativePdfEmbedUrl(url: string, initialPage: number) {
   const page = Math.max(1, Math.trunc(initialPage || 1));
   return `${url.split("#")[0]}#page=${page}`;
 }
 
-export function NativePdfEmbed({ url, title, initialPage }: { url: string; title: string; initialPage: number }) {
+export const NativePdfEmbed = memo(function NativePdfEmbed({
+  url,
+  title,
+  initialPage,
+}: {
+  url: string;
+  title: string;
+  initialPage: number;
+}) {
   return (
     <div className="overflow-hidden rounded-lg border border-[color:var(--border)] bg-[color:var(--surface-raised)] shadow-[var(--shadow-tight)]">
       <iframe
@@ -572,4 +584,4 @@ export function NativePdfEmbed({ url, title, initialPage }: { url: string; title
       />
     </div>
   );
-}
+});

From fbf3f1899ab32c45640d6405cf1fb44bb4adb071 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 14 Jul 2026 10:03:43 +0000
Subject: [PATCH 2/3] test(viewer): cover SignedImage retry/lightbox and
 gesture input under jsdom
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add jsdom coverage for the effect-driven viewer paths the node/SSR suite can't
reach:

- signed-image.dom.test.tsx: drives the SignedImage fetch → failed → retry →
  recover flow (jsdom omits IntersectionObserver, so the image loads
  immediately) and the click-to-open lightbox that closes on Escape. The
  useAuthSession mock returns stable references so the fetch effect isn't
  re-run on every render.

- use-viewer-gestures.dom.test.tsx: asserts the native non-passive wheel branch
  (Ctrl/⌘ gating, lightbox no-modifier mode, wheelZoom off) and the pointer
  pan/pinch maths (frame-delta panning, distance-ratio zoom, touchPan opt-out).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DqMTk5fDNgi5GwEK5peRmj
---
 tests/signed-image.dom.test.tsx        |  82 ++++++++++++++++++
 tests/use-viewer-gestures.dom.test.tsx | 115 +++++++++++++++++++++++++
 2 files changed, 197 insertions(+)
 create mode 100644 tests/signed-image.dom.test.tsx
 create mode 100644 tests/use-viewer-gestures.dom.test.tsx

diff --git a/tests/signed-image.dom.test.tsx b/tests/signed-image.dom.test.tsx
new file mode 100644
index 000000000..c882abd0d
--- /dev/null
+++ b/tests/signed-image.dom.test.tsx
@@ -0,0 +1,82 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// SignedImage backs both DocumentImage (document viewer) and SourceImage (answer
+// gallery), so its failure/retry branch — untestable in the node/SSR suite because
+// it lives in effects — is exercised here under jsdom. jsdom omits
+// IntersectionObserver, so SignedImage loads immediately (its documented fallback),
+// which lets us drive the fetch → failed → retry → recover flow directly.
+
+// useSignedImageUrl lists authorizationHeader + markSessionExpired in its effect
+// deps, so the mock must return STABLE references — a fresh object/fn per render
+// would re-run the fetch effect on every state change and exhaust the one-shot
+// fetch mocks below.
+vi.mock("@/lib/supabase/client", () => {
+  const authorizationHeader = {};
+  const markSessionExpired = vi.fn();
+  return { useAuthSession: () => ({ authorizationHeader, markSessionExpired }) };
+});
+
+import { SignedImage } from "@/components/clinical-dashboard/signed-image";
+import { clearSignedUrlCache } from "@/lib/signed-url-cache";
+
+const ENDPOINT = "/api/images/dom-test/signed-url";
+
+beforeEach(() => {
+  clearSignedUrlCache();
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  clearSignedUrlCache();
+});
+
+describe("SignedImage failure/retry (jsdom)", () => {
+  it("shows a retryable failure state, then recovers when retry succeeds", async () => {
+    const user = userEvent.setup();
+    const fetchMock = vi.fn().mockResolvedValueOnce({ ok: false, status: 500, json: async () => ({ error: "boom" }) });
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(
+      <SignedImage endpoint={ENDPOINT} alt="Airway diagram" failureLabel="Image preview failed." retryLabel="Retry" />,
+    );
+
+    // The first fetch fails → failure state with a retry action.
+    expect(await screen.findByText("Image preview failed.")).toBeInTheDocument();
+    const retry = screen.getByRole("button", { name: "Retry" });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Retry: the next fetch resolves with a URL and the image recovers.
+    fetchMock.mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({ url: "/demo/airway.png" }) });
+    await user.click(retry);
+
+    const img = await screen.findByRole("img", { name: "Airway diagram" });
+    expect(img).toHaveAttribute("src", "/demo/airway.png");
+    expect(screen.queryByText("Image preview failed.")).not.toBeInTheDocument();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("opens the fullscreen lightbox when a loaded zoomable image is activated, and closes on Escape", async () => {
+    const user = userEvent.setup();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({ ok: true, status: 200, json: async () => ({ url: "/demo/airway.png" }) }),
+    );
+
+    render(<SignedImage endpoint={ENDPOINT} alt="Airway diagram" caption="Airway" zoomable />);
+
+    const img = await screen.findByRole("img", { name: "Airway diagram" });
+    // jsdom never fires a real load event; simulate decode so `loaded` flips true.
+    fireEvent.load(img);
+
+    const expand = await screen.findByRole("button", { name: "Expand image: Airway" });
+    await user.click(expand);
+
+    expect(await screen.findByTestId("image-lightbox")).toBeInTheDocument();
+    expect(screen.getByTestId("image-lightbox")).toHaveAttribute("role", "dialog");
+
+    await user.keyboard("{Escape}");
+    await waitFor(() => expect(screen.queryByTestId("image-lightbox")).not.toBeInTheDocument());
+  });
+});
diff --git a/tests/use-viewer-gestures.dom.test.tsx b/tests/use-viewer-gestures.dom.test.tsx
new file mode 100644
index 000000000..674756f2f
--- /dev/null
+++ b/tests/use-viewer-gestures.dom.test.tsx
@@ -0,0 +1,115 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { useRef } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { useViewerGestures } from "@/components/document-viewer/use-viewer-gestures";
+
+// useViewerGestures interprets raw wheel/pointer input into onZoomBy/onPanBy
+// callbacks. Its wheel branch is a *native* non-passive listener (so it can
+// preventDefault the browser's page-zoom), which the node/SSR suite can't reach;
+// jsdom dispatches real DOM events so we can assert the modifier gating and the
+// pointer pan/pinch maths here.
+
+type HarnessProps = Omit<Parameters<typeof useViewerGestures>[0], "targetRef">;
+
+function GestureHarness(props: HarnessProps) {
+  const targetRef = useRef<HTMLDivElement>(null);
+  const { handlers } = useViewerGestures({ targetRef, ...props });
+  return <div ref={targetRef} data-testid="stage" {...handlers} />;
+}
+
+function stage() {
+  return screen.getByTestId("stage");
+}
+
+describe("useViewerGestures wheel zoom (jsdom)", () => {
+  it("zooms on Ctrl/⌘ + wheel and leaves a plain wheel for native scroll", () => {
+    const onZoomBy = vi.fn();
+    render(<GestureHarness onZoomBy={onZoomBy} />);
+
+    // Plain wheel is ignored (native scroll) when a modifier is required.
+    fireEvent.wheel(stage(), { deltaY: -100 });
+    expect(onZoomBy).not.toHaveBeenCalled();
+
+    // Ctrl+wheel zooms in: deltaY < 0 → factor > 1.
+    fireEvent.wheel(stage(), { deltaY: -100, ctrlKey: true });
+    expect(onZoomBy).toHaveBeenCalledTimes(1);
+    expect(onZoomBy.mock.calls[0][0]).toBeGreaterThan(1);
+
+    // ⌘+wheel down zooms out: deltaY > 0 → factor < 1.
+    fireEvent.wheel(stage(), { deltaY: 100, metaKey: true });
+    expect(onZoomBy).toHaveBeenCalledTimes(2);
+    expect(onZoomBy.mock.calls[1][0]).toBeLessThan(1);
+  });
+
+  it("zooms on a plain wheel when the modifier is not required (lightbox mode)", () => {
+    const onZoomBy = vi.fn();
+    render(<GestureHarness onZoomBy={onZoomBy} wheelNeedsModifier={false} />);
+
+    fireEvent.wheel(stage(), { deltaY: -120 });
+    expect(onZoomBy).toHaveBeenCalledTimes(1);
+    expect(onZoomBy.mock.calls[0][0]).toBeGreaterThan(1);
+  });
+
+  it("never attaches the wheel listener when wheelZoom is off", () => {
+    const onZoomBy = vi.fn();
+    render(<GestureHarness onZoomBy={onZoomBy} wheelZoom={false} wheelNeedsModifier={false} />);
+
+    fireEvent.wheel(stage(), { deltaY: -100 });
+    expect(onZoomBy).not.toHaveBeenCalled();
+  });
+});
+
+describe("useViewerGestures pointer pan/pinch (jsdom)", () => {
+  it("pans by frame deltas during a one-pointer mouse drag", () => {
+    const onZoomBy = vi.fn();
+    const onPanBy = vi.fn();
+    render(<GestureHarness onZoomBy={onZoomBy} onPanBy={onPanBy} />);
+
+    fireEvent.pointerDown(stage(), {
+      pointerId: 1,
+      pointerType: "mouse",
+      isPrimary: true,
+      clientX: 10,
+      clientY: 10,
+    });
+    fireEvent.pointerMove(stage(), { pointerId: 1, clientX: 30, clientY: 25 });
+    expect(onPanBy).toHaveBeenCalledTimes(1);
+    expect(onPanBy).toHaveBeenCalledWith(20, 15);
+
+    fireEvent.pointerMove(stage(), { pointerId: 1, clientX: 35, clientY: 20 });
+    expect(onPanBy).toHaveBeenNthCalledWith(2, 5, -5);
+
+    fireEvent.pointerUp(stage(), { pointerId: 1 });
+    // After release the drag is over: further moves do not pan.
+    fireEvent.pointerMove(stage(), { pointerId: 1, clientX: 100, clientY: 100 });
+    expect(onPanBy).toHaveBeenCalledTimes(2);
+    expect(onZoomBy).not.toHaveBeenCalled();
+  });
+
+  it("zooms by the distance ratio during a two-pointer pinch", () => {
+    const onZoomBy = vi.fn();
+    const onPanBy = vi.fn();
+    render(<GestureHarness onZoomBy={onZoomBy} onPanBy={onPanBy} />);
+
+    // Two pointers down 10px apart seed the pinch baseline.
+    fireEvent.pointerDown(stage(), { pointerId: 1, pointerType: "touch", isPrimary: true, clientX: 0, clientY: 0 });
+    fireEvent.pointerDown(stage(), { pointerId: 2, pointerType: "touch", clientX: 10, clientY: 0 });
+
+    // Spread the second pointer to 30px apart → factor 3×.
+    fireEvent.pointerMove(stage(), { pointerId: 2, clientX: 30, clientY: 0 });
+    expect(onZoomBy).toHaveBeenCalledTimes(1);
+    expect(onZoomBy.mock.calls[0][0]).toBeCloseTo(3, 5);
+    // A pinch must never be misread as a pan.
+    expect(onPanBy).not.toHaveBeenCalled();
+  });
+
+  it("ignores touch drags when touchPan is off (native scroll keeps momentum)", () => {
+    const onPanBy = vi.fn();
+    render(<GestureHarness onZoomBy={vi.fn()} onPanBy={onPanBy} touchPan={false} />);
+
+    fireEvent.pointerDown(stage(), { pointerId: 1, pointerType: "touch", isPrimary: true, clientX: 10, clientY: 10 });
+    fireEvent.pointerMove(stage(), { pointerId: 1, clientX: 40, clientY: 40 });
+    expect(onPanBy).not.toHaveBeenCalled();
+  });
+});

From e82a811fe58051ca12095bcd67afde3b22fcdc02 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 14 Jul 2026 10:43:39 +0000
Subject: [PATCH 3/3] fix(viewer): only mark a document loaded after a
 successful detail load
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A failed full load stamped loadedKeyRef unconditionally, so the next page/chunk
navigation on the same document computed isFullReload=false and wrongly skipped
the signed-URL re-fetch and the viewer-error refresh — a document that never
loaded could never recover except via an explicit "Retry preview". (fetchSignedUrlPair
uses allSettled and never rejects, so this path is reached, not caught.)

Advance the loaded key only when the detail request actually succeeds; a failed
load keeps the previous key so subsequent navigation is still treated as a full
reload and retries the recovery work.

Extract the reload-key decision into pure documentLoadKey / isFullDocumentReload
/ nextLoadedDocumentKey helpers in document-viewer-navigation.ts and cover the
full-reload-vs-navigation gating (incl. the failed-load regression guard) in the
node suite — the branching was previously untested.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DqMTk5fDNgi5GwEK5peRmj
---
 src/components/DocumentViewer.tsx             | 22 ++++++++---
 src/lib/document-viewer-navigation.ts         | 36 +++++++++++++++++
 .../document-viewer-navigation-source.test.ts | 39 ++++++++++++++++++-
 3 files changed, 90 insertions(+), 7 deletions(-)

diff --git a/src/components/DocumentViewer.tsx b/src/components/DocumentViewer.tsx
index 70237fd87..e029f7cc6 100644
--- a/src/components/DocumentViewer.tsx
+++ b/src/components/DocumentViewer.tsx
@@ -67,7 +67,12 @@ import { NativePdfEmbed, PdfCanvasViewer } from "@/components/document-viewer/pd
 import { NonPdfSourcePreview } from "@/components/document-viewer/non-pdf-source-preview";
 import { clearCachedSignedUrl, getCachedSignedUrl, setCachedSignedUrl } from "@/lib/signed-url-cache";
 import { readLocalProjectIdentity, unsafeLocalProjectMessage } from "@/lib/local-project-identity";
-import { documentPageHref } from "@/lib/document-viewer-navigation";
+import {
+  documentLoadKey,
+  documentPageHref,
+  isFullDocumentReload,
+  nextLoadedDocumentKey,
+} from "@/lib/document-viewer-navigation";
 import { formatClinicalDate } from "@/lib/source-metadata";
 import { partitionViewerImages } from "@/lib/image-filtering";
 import { isLocalNoAuthMode } from "@/lib/client-env";
@@ -1846,8 +1851,8 @@ export function DocumentViewer({
 
     const controller = new AbortController();
     const authRequest = registerAuthRequest(controller);
-    const loadKey = `${documentId}::${previewAttempt}`;
-    const isFullReload = loadedKeyRef.current !== loadKey;
+    const loadKey = documentLoadKey(documentId, previewAttempt);
+    const isFullReload = isFullDocumentReload(loadedKeyRef.current, loadKey);
     const reset = window.setTimeout(() => {
       // Skip the reset on navigation so the mounted PDF and current content stay
       // visible (no loading flash) while the new page window loads in the background.
@@ -1902,9 +1907,14 @@ export function DocumentViewer({
       })
       .then(([[detailResult], signedUrlPair]) => {
         if (controller.signal.aborted || !isAuthEpochCurrent(authRequest.epoch)) return;
-        loadedKeyRef.current = loadKey;
-
-        if (detailResult.status === "fulfilled") {
+        const detailLoaded = detailResult.status === "fulfilled";
+        // Advance the loaded key only on a successful detail load. A failed full
+        // load must stay "not loaded" so the next page/chunk navigation is still
+        // treated as a full reload — re-fetching signed URLs and refreshing the
+        // error — rather than a cheap navigation that skips that recovery.
+        loadedKeyRef.current = nextLoadedDocumentKey(loadedKeyRef.current, loadKey, detailLoaded);
+
+        if (detailLoaded) {
           const detail = detailResult.value;
           setDocument(detail.document ?? null);
           setPages(detail.pages ?? []);
diff --git a/src/lib/document-viewer-navigation.ts b/src/lib/document-viewer-navigation.ts
index 2cf9eac2a..cd576d964 100644
--- a/src/lib/document-viewer-navigation.ts
+++ b/src/lib/document-viewer-navigation.ts
@@ -10,3 +10,39 @@ export function documentPageHref(documentId: string, page: number) {
   const params = new URLSearchParams({ page: String(normalizedPage) });
   return `/documents/${encodeURIComponent(documentId)}?${params.toString()}#pdf-preview-section`;
 }
+
+/**
+ * Identity of a full document load. A new `documentId` or an explicit retry
+ * (`previewAttempt`) starts a fresh full load; page/chunk navigation within the
+ * same document keeps the same key.
+ */
+export function documentLoadKey(documentId: string, previewAttempt: number): string {
+  return `${documentId}::${previewAttempt}`;
+}
+
+/**
+ * Whether the pending load is a *full* (re)load rather than navigation on an
+ * already-loaded document. A full load resets the viewer, re-issues signed URLs
+ * and surfaces load errors; navigation only re-windows the detail in place.
+ *
+ * The remembered key is advanced only after a *successful* detail load (see
+ * {@link nextLoadedDocumentKey}), so a failed full load stays "not loaded" and
+ * the next run retries it as a full load rather than a cheap navigation.
+ */
+export function isFullDocumentReload(loadedKey: string | null, loadKey: string): boolean {
+  return loadedKey !== loadKey;
+}
+
+/**
+ * The load key to remember once a load settles. Only a successful detail load
+ * marks the document loaded; a failed load keeps the previous key so the next
+ * navigation is still treated as a full reload (re-fetching signed URLs and
+ * updating the viewer error) instead of skipping that recovery work.
+ */
+export function nextLoadedDocumentKey(
+  previousKey: string | null,
+  loadKey: string,
+  detailLoaded: boolean,
+): string | null {
+  return detailLoaded ? loadKey : previousKey;
+}
diff --git a/tests/document-viewer-navigation-source.test.ts b/tests/document-viewer-navigation-source.test.ts
index fbfd480f2..6f5d04685 100644
--- a/tests/document-viewer-navigation-source.test.ts
+++ b/tests/document-viewer-navigation-source.test.ts
@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 
-import { documentPageHref } from "../src/lib/document-viewer-navigation";
+import {
+  documentLoadKey,
+  documentPageHref,
+  isFullDocumentReload,
+  nextLoadedDocumentKey,
+} from "../src/lib/document-viewer-navigation";
 
 describe("document viewer useful-page navigation", () => {
   it("creates a destination-page URL without carrying an unrelated citation chunk", () => {
@@ -30,3 +35,35 @@ describe("document viewer useful-page navigation", () => {
     expect(documentPageHref("doc id&value", 2)).toBe("/documents/doc%20id%26value?page=2#pdf-preview-section");
   });
 });
+
+describe("document viewer full-reload vs navigation gating", () => {
+  it("keys a load by documentId + previewAttempt", () => {
+    expect(documentLoadKey("doc-1", 0)).toBe("doc-1::0");
+    expect(documentLoadKey("doc-1", 2)).toBe("doc-1::2");
+  });
+
+  it("treats a first load, a new document, and an explicit retry as full reloads", () => {
+    // No prior load → full reload.
+    expect(isFullDocumentReload(null, documentLoadKey("doc-1", 0))).toBe(true);
+    // Same document + attempt → navigation, not a full reload.
+    expect(isFullDocumentReload("doc-1::0", documentLoadKey("doc-1", 0))).toBe(false);
+    // Different document → full reload.
+    expect(isFullDocumentReload("doc-1::0", documentLoadKey("doc-2", 0))).toBe(true);
+    // Retry (previewAttempt bump) on the same document → full reload.
+    expect(isFullDocumentReload("doc-1::0", documentLoadKey("doc-1", 1))).toBe(true);
+  });
+
+  it("advances the loaded key only after a successful detail load", () => {
+    const loadKey = documentLoadKey("doc-1", 0);
+
+    // Success stamps the key so later navigation is treated as navigation.
+    expect(nextLoadedDocumentKey(null, loadKey, true)).toBe("doc-1::0");
+    // Regression guard: a failed full load must NOT stamp the key, so the next
+    // page/chunk navigation still evaluates as a full reload and re-fetches
+    // signed URLs / refreshes the error instead of skipping that recovery.
+    expect(nextLoadedDocumentKey(null, loadKey, false)).toBeNull();
+    expect(isFullDocumentReload(nextLoadedDocumentKey(null, loadKey, false), loadKey)).toBe(true);
+    // A failed navigation keeps the previously loaded key intact.
+    expect(nextLoadedDocumentKey("doc-1::0", loadKey, false)).toBe("doc-1::0");
+  });
+});