feat(viewer): Phase 2c rail filmstrip syncs PDF page

[BigSimmo]

Summary

• Phase 2c of the unified viewer chrome plan: rail figures get a compact page-linked filmstrip and clickable page badges.
• Filmstrip + DocumentImage badges call navigateToPage (history.pushState + local route state) — norouter.push, no PdfCanvasViewer remount (key stays documentId + viewer mode only).
• Active PDF page is highlighted on matching figures (data-active-page, aria-current).
• SignedImage deferred IO unchanged — filmstrip is badge/toolbar only, not a second image fetch.

Verification

• Focused: document-image-filmstrip.dom.test.tsx, document-detail-performance.test.ts, document-section-nav.dom.test.tsx, document-viewer-shell.dom.test.tsx, document-section-index.test.ts — 34 passed
• npm run verify:pr-local — exit 0
  • Decisive: Test Files 522 passed (522) / Tests 5541 passed | 1 skipped (5542)
  • Decisive: Offline RAG fixture and production-contract checks passed.
• UI verification not run: phone composer/reserves unchanged; empty source-images section gating unchanged in section-index.ts.
• Release verification not run: not a release claim.

Risk and rollout

• Risk: page flip remounting pdf.js — guarded by contract test on canvas key and navigateToPage pushState path.
• Rollback: revert this PR; rail returns to vertical list without filmstrip sync.
• Provider or production effects: None

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 when clinical decision-support behavior changed

Notes

• RAG impact: no retrieval behaviour change — document viewer rail UI only; ranking/retrieval surfaces untouched.
• Flightplan: ui. Independent of open 2b (different files). Does not start 2d/2e.

Summary by CodeRabbit

• New Features

  • Added a document image filmstrip for quick page selection.
  • Highlighted the currently active page and provided accessible page controls.
  • Enabled page navigation from clinical and audit image panels.

• Bug Fixes

  • Page changes now update the viewer without unnecessary reloads, image fetching, or PDF remounts.

• Tests

  • Added coverage for page selection, active-page highlighting, navigation behavior, and performance.

[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:58 minutes

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: c32c7b97-4483-4f73-b3e5-ce742d2be425

📥 Commits

Reviewing files that changed from the base of the PR and between 15e60b6 and 812ee70.

📒 Files selected for processing (2)

• src/components/document-viewer/source-panels.tsx
• tests/document-image-filmstrip.dom.test.tsx

📝 Walkthrough

Walkthrough

The document viewer rail now supports page selection through a horizontal image filmstrip and page badges. Active-page state flows through clinical and audit images. Tests verify navigation, accessibility state, history updates, and PDF viewer mount stability.

Changes

Document page navigation

Layer / File(s)	Summary
Viewer rail navigation wiring src/components/DocumentViewer.tsx, src/components/document-viewer/document-rail-panels.tsx	The viewer passes activePage and navigateToPage to DocumentViewerRail. The rail passes these values to clinical and audit images.
Filmstrip and image page controls src/components/document-viewer/document-image-filmstrip.tsx, src/components/document-viewer/source-panels.tsx	The filmstrip renders page buttons and active-page state. DocumentImage renders accessible page controls for valid page numbers and static labels otherwise.
Page navigation validation tests/document-image-filmstrip.dom.test.tsx, tests/document-detail-performance.test.ts	Tests cover page selection, active-page attributes, history updates, and prevention of PDF viewer remounts.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
participant User
participant DocumentImageFilmstrip
participant DocumentViewerRail
participant navigateToPage
User->>DocumentImageFilmstrip: Click page button
DocumentImageFilmstrip->>DocumentViewerRail: Invoke onSelectPage(page)
DocumentViewerRail->>navigateToPage: Select page
navigateToPage-->>DocumentViewerRail: Update active page

Loading

Possibly related PRs

• BigSimmo/Database#651: Both modify document navigation to avoid unnecessary PDF reloads.
• BigSimmo/Database#1025: Both extend DocumentImage for document page navigation.
• BigSimmo/Database#1311: Both modify DocumentViewer and DocumentViewerRail navigation wiring.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the viewer filmstrip change and its PDF page synchronization behavior.
Description check	✅ Passed	The description follows the template and documents the summary, verification, risks, rollback, governance, and omitted verification gates.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/viewer-phase2c-rail-filmstrip-1db8

---

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

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[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.

[Copilot]

Pull request overview

Implements Phase 2c of the document viewer rail chrome by adding a compact, page-linked filmstrip for rail figures and wiring both the filmstrip and figure page badges to navigateToPage (pushState-based) so the PDF viewer does not remount on page jumps.

Changes:

• Add DocumentImageFilmstrip toolbar and render it above the figure cards in the rail.
• Extend DocumentImage and DocumentViewerRail to accept activePage + onSelectPage and highlight the active PDF page.
• Add DOM/performance guard tests covering the filmstrip/badges and the “no remount” contract.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/document-image-filmstrip.dom.test.tsx	Adds DOM tests for filmstrip clicks + DocumentImage page badge behavior.
tests/document-detail-performance.test.ts	Adds a string-based “contract/perf” test asserting navigateToPage wiring and stable canvas key.
src/components/DocumentViewer.tsx	Passes activePage / navigateToPage into the rail.
src/components/document-viewer/source-panels.tsx	Updates DocumentImage to support page badge navigation and active-page highlighting.
src/components/document-viewer/document-rail-panels.tsx	Renders the filmstrip + wires page-selection props through the rail.
src/components/document-viewer/document-image-filmstrip.tsx	New compact filmstrip toolbar component.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

CI triage

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

• Lighthouse budget (advisory) — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.
• 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 #8945 (cancelled).

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/components/document-viewer/document-image-filmstrip.tsx (1)

61-61: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a theme token for the filmstrip label width.

Add --container-filmstrip-label: 9rem under @theme, then replace max-w-[9rem] with max-w-filmstrip-label.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/components/document-viewer/document-image-filmstrip.tsx` at line 61, Add
the --container-filmstrip-label: 9rem token under the `@theme` configuration, then
update the label span in the document filmstrip to use max-w-filmstrip-label
instead of the hardcoded max-w-[9rem] class.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@tests/document-image-filmstrip.dom.test.tsx`:
- Around line 54-55: Update the active-page assertion for page5 in the
DocumentImageFilmstrip test to expect the emitted aria-current value "page"
instead of "true", matching DocumentImageFilmstrip’s accessibility behavior.
---
Nitpick comments:
In `@src/components/document-viewer/document-image-filmstrip.tsx`:
- Line 61: Add the --container-filmstrip-label: 9rem token under the `@theme`
configuration, then update the label span in the document filmstrip to use
max-w-filmstrip-label instead of the hardcoded max-w-[9rem] class.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2268d320-460b-45e4-8ad5-0be0362ada89

📥 Commits

Reviewing files that changed from the base of the PR and between cd2c67f and 15e60b6.

📒 Files selected for processing (6)

• src/components/DocumentViewer.tsx
• src/components/document-viewer/document-image-filmstrip.tsx
• src/components/document-viewer/document-rail-panels.tsx
• src/components/document-viewer/source-panels.tsx
• tests/document-detail-performance.test.ts
• tests/document-image-filmstrip.dom.test.tsx