feat(viewer): connect batch signed-URL callers, probe image encodings & add public doc helper (#283, #282, #036)

[BigSimmo]

Summary

Addresses Workstream 7 (#283, #282, #36):

• Compact answer recommended questions into shared suggestion chips #283 (Connect 100-ID Batch Signed-URL Route Callers):
  • Added pass-through route src/app/api/documents/signed-urls/route.ts re-exporting runtime and POST from src/app/api/images/signed-urls/route.ts.
  • Added batch signed-URL helper src/lib/batch-signed-urls.ts supporting chunking in batches of <= 100 IDs and populating client LRU signed URL cache.
  • Added React hook useBatchSignedImageUrls in src/components/clinical-dashboard/use-batch-signed-urls.ts with session tracking and 401 retry handling.
  • Wired batch signed-URL prefetching into DocumentImageList in src/components/document-viewer/source-panels.tsx and DocumentSearchResults in src/components/clinical-dashboard/document-search-results.tsx, eliminating N+1 single image signed-URL fetch waterfalls while preserving individual single-image endpoint fallbacks for lightboxes and retries.
• fix(access): merge public production access rollout into main #282 (Fast Image Encoding Metadata Probe Script):
  • Added scripts/probe-corpus-image-encodings.mjs to scan document metadata fixtures and PDF streams for image filter encodings (JBIG2, JPX, DCT, Flate, CCITTFax, LZW) and standard-14 fonts.
  • Supports --self-test and --json modes.
  • Probe executed across 14 fixtures (399 records); confirmed 0 JBIG2/JPX streams present, establishing that shipping extra ~2MB pdf.js WASM decoders is not needed.
• chore(deps-dev): bump prettier from 3.8.3 to 3.8.4 #36 (Explicit Public Document Filter Helper):
  • Added src/lib/documents/is-public-document.ts and src/lib/documents/index.ts exporting isPublicDocument and isPublicDocumentRow.
  • Standardized public vs. private document boundary checks across null owner IDs, public_corpus, is_public, visibility: "public", and source_kind: "registry_record".
• Docs & Ledger:
  • Added src/lib/documents to docs/codebase-index.md.
  • Recorded clean review ledger entry at docs/branch-review-records/7d870a0e009afb1f94df3f20108573b8df7967431be9e6825bfb162d37506944.record.md.

Verification

• tests/batch-signed-urls.test.ts (7/7 passed)
• tests/use-batch-signed-urls.dom.test.tsx (1/1 passed)
• tests/probe-corpus-image-encodings.test.ts (3/3 passed)
• tests/documents-is-public.test.ts (6/6 passed)
• tests/document-detail-performance.test.ts (9/9 passed)
• tests/signed-url-cache.test.ts (6/6 passed)
• tests/auth-signed-url-cache.dom.test.tsx (6/6 passed)
• node scripts/probe-corpus-image-encodings.mjs --self-test passed.
• npm run typecheck:internal passed with 0 errors.
• npm run lint:internal passed with 0 errors and 0 warnings.
• npm run docs:check-inventory & npm run docs:check-index passed.
• npm run format passed clean.

Risk and Rollout

• Risk: Low. Batch route uses existing signed-URL generation logic; client cache population ensures backwards compatibility with existing single-URL consumers.
• Rollback: Revert this PR.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked; no clinical decision-support behavior changes

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in:47 minutes

Limit details: You’ve used all 1 included review currently available under your plan. You completed 100 included PR reviews in the past 7 days; at that activity level, included reviews refill at 1 review per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7d9ed290-635c-4fef-b951-aeca7b6606a9

📥 Commits

Reviewing files that changed from the base of the PR and between 4ea310e and 7c8004c.

📒 Files selected for processing (18)

• docs/branch-review-records/7d870a0e009afb1f94df3f20108573b8df7967431be9e6825bfb162d37506944.record.md
• docs/codebase-index.md
• docs/scripts-index.md
• docs/site-map.md
• scripts/probe-corpus-image-encodings.mjs
• src/app/api/documents/signed-urls/route.ts
• src/app/api/images/signed-urls/route.ts
• src/components/clinical-dashboard/document-search-results.tsx
• src/components/clinical-dashboard/use-batch-signed-urls.ts
• src/components/document-viewer/source-panels.tsx
• src/lib/batch-signed-urls.ts
• src/lib/documents/index.ts
• src/lib/documents/is-public-document.ts
• tests/batch-signed-urls.test.ts
• tests/document-rail-image-window.dom.test.tsx
• tests/documents-is-public.test.ts
• tests/probe-corpus-image-encodings.test.ts
• tests/use-batch-signed-urls.dom.test.tsx

---

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

[github-actions]

CI triage

CI failed on this PR. Automated classification of the 2 failed job(s):

• Unit coverage — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.
• PR required — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.

Compared with main CI run #11840 (cancelled).

Classification is evidence routing, not permission to ignore a failure. Exact quarantined Playwright identities remain governed by the flake ledger.

[Copilot]

Pull request overview

This PR reduces N+1 signed-URL fetches for document images by introducing a client-side batch prefetch + cache population path, adds a public-document visibility predicate intended to inform signing behavior, and adds a read-only corpus probe script to detect whether PDF.js image decoders are needed.

Changes:

• Add batch signed-URL fetching (/api/images/signed-urls) with client-side chunking + cache population and integrate prefetching into the document viewer + document search results.
• Add isPublicDocument/isPublicDocumentRow helper and associated tests/exports for defining the public vs private boundary.
• Add probe-corpus-image-encodings script + tests and regenerate generated doc indices / review record.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/use-batch-signed-urls.dom.test.tsx	JSDOM test asserting one batch request populates the signed URL cache for multiple images.
tests/batch-signed-urls.test.ts	Unit tests for chunking, cache population, and 401 handling in the batch client helper.
tests/documents-is-public.test.ts	Unit tests for the new public document predicate behavior.
tests/probe-corpus-image-encodings.test.ts	Tests for the probe script’s self-test and report shape.
src/lib/batch-signed-urls.ts	Core batch fetch/chunk/merge + cache population utilities.
src/components/clinical-dashboard/use-batch-signed-urls.ts	React hook that batches and prefetches signed URLs into the shared LRU cache.
src/components/document-viewer/source-panels.tsx	Document viewer image list now prefetches visible image signed URLs via the batch hook.
src/components/clinical-dashboard/document-search-results.tsx	Search results now prefetch cover image signed URLs for visible results via the batch hook.
src/app/api/documents/signed-urls/route.ts	Alias route re-exporting the images batch-signed-urls handler.
src/lib/documents/is-public-document.ts	New helper defining a public-vs-private predicate for document rows/metadata.
src/lib/documents/index.ts	Exports the new helper/types from the documents lib entrypoint.
scripts/probe-corpus-image-encodings.mjs	Read-only scanner for PDF image encoding/font references to guide decoder asset decisions.
docs/site-map.md	Regenerated sitemap entries including the new route.
docs/scripts-index.md	Regenerated scripts inventory counts.
docs/codebase-index.md	Index update referencing the new documents/ helper.
docs/branch-review-records/*.record.md	Appended branch review record.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[BigSimmo]

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply the suggestion exactly.

Do not make changes beyond what is described in the linked review thread.

[Copilot]

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply t...

Done in 4d9853d. Three fixes applied:

1. Auth epoch guard (use-batch-signed-urls.ts): now calls registerAuthRequest/isAuthEpochCurrent from useAuthSession and only calls populateBatchSignedUrlsInCache when the epoch is still current; the auth request is released in a finally block.

2. Header normalization (batch-signed-urls.ts): spreads into new Headers(options.headers) and then sets content-type, so Headers instances and tuple-array forms are handled correctly instead of being silently dropped.

3. isPublicDocument wired into batch route (api/images/signed-urls/route.ts): imports isPublicDocument, adds owner_id to the documents select, then splits valid images — public corpus images use getPublicUrl (no signing overhead) and private images use createSignedUrls as before.

[BigSimmo]

CI status update:

• Static PR checks: fixed — Prettier formatting drift in use-batch-signed-urls.ts (content-identical dependency-array line-wrap), pushed as 7718a63.

• Lighthouse budget: the failure on this head (mobile-root cls +0.223 vs baseline) is on the home route, which this PR's diff never touches. Re-ran the job; watching the fresh result.

• Unit coverage: real, deterministic failure — reproduces identically across two separate runs on the same head (7718a63), not a flake:

  TypeError: registerAuthRequest is not a function
  at src/components/clinical-dashboard/use-batch-signed-urls.ts:35:25
  

  in tests/use-batch-signed-urls.dom.test.tsx. Diagnosis so far: use-batch-signed-urls.ts destructures registerAuthRequest from useAuthSession() and calls it inside a passive effect. AuthProvider (src/lib/supabase/client.tsx, unmodified by this PR) always publishes registerAuthRequest as a stable useCallback-wrapped function in its context value, so it should never be undefined once mounted under <AuthProvider> — and the test does wrap <BatchImageConsumer> in <AuthProvider>, following the same vi.mock("@supabase/ssr", ...) pattern as the pre-existing, presumably-passing tests/auth-signed-url-cache.dom.test.tsx.

  The one substantive difference I found: no other hook in this codebase currently calls registerAuthRequest from inside a component under a .dom.test.tsx render — use-signed-image-url.ts's existing test only exercises authorizationHeader/session/markSessionExpired. So this new test is the first to exercise that code path under jsdom/Vitest, and I couldn't rule out a real interaction bug (e.g. timing/effect-ordering) without running the suite.

  I wasn't able to execute the test locally to confirm further — this sandbox runs Node 22 and the repo's scripts/check-node-engine.cjs preinstall hook hard-blocks anything but Node ≥24.15 <25 with no override, so npm ci fails before I can run Vitest. Flagging for whoever picks this up with local Node 24 to reproduce and step through; didn't want to guess a fix in auth-adjacent code without being able to verify it.

---

Generated by Claude Code