feat(viewer): Phase 2b unify whole-document images with ImageLightbox

[BigSimmo]

Summary

• Phase 2b of the unified viewer chrome plan: whole-document images use the same immersive ImageLightbox as rail crops.
• ImageLightbox accepts either endpoint (existing signed-URL fetch) or parent-owned url (document signed URL). URL mode never reads or writes the signed-URL LRU.
• NonPdfSourcePreview primary action opens the lightbox; Open/Download remain secondary. Card-like preview chrome flattened into the frame surround.
• Auth-clear: blanking the parent signed URL unmounts/blanks the lightbox; URL mode cannot revive a prior identity from cache.

Verification

• Focused DOM: tests/image-lightbox-url-mode.dom.test.tsx, document-viewer-non-pdf-preview.dom.test.tsx, signed-image.dom.test.tsx, auth-signed-url-cache.dom.test.tsx, use-viewer-gestures.dom.test.tsx — 25 passed
• npm run verify:pr-local — exit 0
  • Decisive: Test Files 522 passed (522) / Tests 5543 passed | 1 skipped (5544)
  • Decisive: Offline RAG fixture and manifest validation passed (36 golden cases, 23 suites).
• Note: first verify:pr-local attempt hit an unrelated design-system-adoption 30s timeout under suite load; that test passed alone and the full gate passed on retry.
• UI verification not run: lightbox Sheet ownership unchanged for phone chrome; composer/reserves untouched. Prefer npm run ensure + photo QA before widening.
• Release verification not run: not a release claim.

Risk and rollout

• Risk: auth-clear leak via LRU in URL mode; mitigated by never calling useSignedImageUrl fetch path when url is provided, plus blank/unmount tests.
• Rollback: revert this PR; NonPdf returns to inline-only + new-tab open.
• 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 — source preview chrome only; ranking/retrieval surfaces untouched.
• Flightplan: ui, privacy. Does not start 2c (filmstrip), 2d, or 2e.

Summary by CodeRabbit

• New Features

  • Added immersive lightbox viewing for non-PDF image previews.
  • Added support for displaying images from direct URLs or private signed links.
  • Added overlay controls, retry handling, and automatic cleanup when images are unavailable.
  • Preserved Open and Download recovery options for failed previews.

• Bug Fixes

  • Improved image-load failure handling and stale-image URL clearing.

• Tests

  • Added coverage for lightbox opening, direct URLs, retries, fallback controls, and URL cleanup.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Image lightbox source handling

Layer / File(s)	Summary
Source mode and retry behavior src/components/clinical-dashboard/image-lightbox.tsx, tests/image-lightbox-url-mode.dom.test.tsx	ImageLightbox now accepts either an endpoint or a direct URL. Direct URLs bypass signed-URL fetching and handle failures locally. Tests cover stale URL clearing, retry behavior, and cache bypassing.
Non-PDF immersive preview src/components/document-viewer/non-pdf-source-preview.tsx, tests/document-viewer-non-pdf-preview.dom.test.tsx	Non-PDF previews open the shared lightbox through expansion controls. Open and Download links remain available. Closing restores focus and tests verify URL mode and unmount behavior.

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

Sequence Diagram(s)

sequenceDiagram
participant InlineImagePreview
participant ImageLightbox
participant DirectImage
InlineImagePreview->>ImageLightbox: Open with direct URL
ImageLightbox->>DirectImage: Render image source
DirectImage-->>ImageLightbox: Report load success or failure
ImageLightbox-->>InlineImagePreview: Close and restore focus

Loading

Possibly related PRs

• BigSimmo/Database#1025: Extracted the document viewer component that now integrates with ImageLightbox.
• BigSimmo/Database#1374: Also modifies ImageLightbox source and signed-URL handling.
• BigSimmo/Database#1660: Overlaps in ImageLightbox and NonPdfSourcePreview behavior.

Suggested reviewers:claude

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: unifying whole-document images with ImageLightbox in Phase 2b.
Description check	✅ Passed	The description covers the change, verification, risks, rollback, governance checks, and explicit reasons for skipped UI and release verification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

📝 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-phase2b-photo-lightbox-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.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/components/document-viewer/non-pdf-source-preview.tsx (1)

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

Move the image height into a theme token.

max-h-[min(70vh,36rem)] introduces a hardcoded design value. Define a named Tailwind 4 @theme token in src/app/globals.css and consume that token here.

As per coding guidelines, “Use Tailwind 4 @theme tokens in src/app/globals.css … rather than introducing hardcoded design values.”

🤖 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/non-pdf-source-preview.tsx` around lines 158 -
166, Replace the hardcoded max-height value on the image in the non-PDF preview
with a named Tailwind 4 theme token. Define the token in the `@theme` section of
globals.css, then reference that token from the image class while preserving the
existing sizing behavior.

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 `@src/components/clinical-dashboard/image-lightbox.tsx`:
- Around line 98-105: Update the lightbox component’s open-state effect to
detect a transition from open to closed and reset directFailed when that
transition occurs. Keep handleClose’s existing reset behavior and avoid clearing
the failure state on initial render or while the lightbox remains open.
In `@src/components/document-viewer/non-pdf-source-preview.tsx`:
- Around line 168-181: Update the lightbox opening logic shared by the image
overlay button and the “View immersive” button to record the invoking element in
a shared ref before setting lightboxOpen. Pass that shared ref as returnFocusRef
so closing the lightbox restores focus to whichever control opened it, including
the “View immersive” button.
---
Nitpick comments:
In `@src/components/document-viewer/non-pdf-source-preview.tsx`:
- Around line 158-166: Replace the hardcoded max-height value on the image in
the non-PDF preview with a named Tailwind 4 theme token. Define the token in the
`@theme` section of globals.css, then reference that token from the image class
while preserving the existing sizing behavior.

🪄 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: 59777cce-3571-4a36-9379-debcf353442d

📥 Commits

Reviewing files that changed from the base of the PR and between 1797ba3 and 3a8b550.

📒 Files selected for processing (4)

• src/components/clinical-dashboard/image-lightbox.tsx
• src/components/document-viewer/non-pdf-source-preview.tsx
• tests/document-viewer-non-pdf-preview.dom.test.tsx
• tests/image-lightbox-url-mode.dom.test.tsx

[Copilot]

Pull request overview

Unifies whole-document image previews with the shared immersive lightbox while preserving parent-owned signed-URL handling.

Changes:

• Adds direct-URL mode to ImageLightbox.
• Adds lightbox controls to non-PDF image previews.
• Adds URL-mode, retry, and auth-clear tests.

Review finding (P2):non-pdf-source-preview.tsx:210 always restores focus to the image-overlay button. If opened via “View immersive,” closing moves focus to a different control. Track the activated opener and test focus restoration for both buttons.

Static review only; reported tests were not rerun.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
src/components/clinical-dashboard/image-lightbox.tsx	Adds parent-owned URL mode.
src/components/document-viewer/non-pdf-source-preview.tsx	Integrates immersive image viewing.
tests/image-lightbox-url-mode.dom.test.tsx	Tests URL isolation, clearing, and retry.
tests/document-viewer-non-pdf-preview.dom.test.tsx	Tests preview integration and URL clearing.

---

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