redesign(documents): document-first viewer with sticky evidence rail

[BigSimmo]

Summary

Layout/IA overhaul of the document viewer (/documents/[id]) so opening a document feels document-first. No changes to PDF rendering or data fetching.

• Desktop (lg+): evidence rail widened 420 → 480px and made sticky (pins below the header, scrolls internally when taller than the viewport); page container 1440px; document column centred at a comfortable reading width; hero info cards flow 3-up.
• Tablet (md, 768–1023): deliberate layout instead of the raw phone stack — full-width PDF, then pinned evidence + indexed text 2-up, then details/summary 2-up.
• Phone: document-first order (anchors → PDF → pinned evidence → collapsible indexed text).
• Declutter: removed the technical Index health block; de-duplicated actions so each appears once (dropped the preview-toolbar Open/Download and the per-chunk "Open source"; kept the Canvas/Browser toggle as a single quiet control). Admin tooling stays collapsed behind the existing canUsePrivateApis disclosures.
• Shell fix: #main-content used overflow-x-hidden, which forced overflow-y: auto and made it the sticky scrollport while the window actually scrolls — silently disabling every position: sticky descendant on sm+ (including the existing PDF toolbar). Switched to overflow-x-clip on sm+ (identical clipping, no scroll container); phone keeps overflow-x-hidden.
• Updated the ui-smoke document-viewer ordering assertions for the document-first phone flow. Preserved all required testids/selectors (#source-evidence/highlighted-source-passage, pinned-source-evidence, pdf-preview, pdf-toolbar, form.document-viewer-composer) and the ?page=&chunk= deep-link pinning.

Verification

• npm run verify:pr-local — not run as the single command; ran its constituents: npm run verify:cheap green (lint, typecheck, 1489 vitest passed) and format:check (see note) locally.
• npm run verify:ui — 128 passed / 2 failed, both failures unrelated to this diff and pre-existing on main:
  • ui-tools.spec.ts:489 (mobile hero sizing) fails on a sub-pixel assertion (26 vs 25.6, 0.4px) at 390px, where this diff is a literal no-op (only sm+ overflow changed; max-sm unchanged) — a known Windows getBoundingClientRect rounding artifact.
  • ui-smoke.spec.ts:1891 (differentials /api/search routing at 1280px) — this diff touches no differentials/search code.
  • Both pass on main's CI (Linux); leaving them for the CI gate to confirm.
• npm run eval:retrieval:quality — N/A (no retrieval/ranking/selection/chunking/scoring change).

Note on format:check: locally flags only CLAUDE.md and .claude/settings.json — both outside this diff, byte-identical to origin/main, flagged solely because Windows checks them out CRLF (text=auto) while CI (Linux/LF) passes them. The three changed files are LF-clean and pass prettier. main's current CI is green with the same file contents.

Clinical Governance Preflight

N/A — UI-only layout/IA change. No ingestion, answer generation, search/ranking, source rendering, document-access, privacy, production-env, or clinical-output behavior was touched. Supabase target and server-only key handling unchanged.

Notes

• Diff is proportionate: 3 files, +64 / −136.

🤖 Generated with Claude Code

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

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c43155bd-f617-4bb5-b821-d40f6d2f8dbe

📥 Commits

Reviewing files that changed from the base of the PR and between ddb2a84 and 66e2804.

📒 Files selected for processing (2)

• docs/branch-review-ledger.md
• tests/ui-smoke.spec.ts

✅ Files skipped from review due to trivial changes (1)

• docs/branch-review-ledger.md

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/ui-smoke.spec.ts

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Improved document viewer layout across desktop and mobile, including pinned evidence alongside mobile indexed text.
  • Reworked PDF preview mode controls and refined viewer spacing/responsive table layout.
• Bug Fixes
  • Improved scroll-to-highlight behavior when the same chunk appears in multiple places (including expanding collapsed sections when needed).
  • Fixed horizontal overflow handling to restore sticky panel behavior on smaller screens.
• Documentation
  • Updated the review records ledger.
• Tests
  • Expanded/adjusted UI smoke coverage for viewer ordering, highlighting, and composer visibility while scrolling.

Walkthrough

The document viewer removes index health state and UI, improves chunk highlighting, changes PDF and evidence ordering, restructures responsive source and evidence layouts, updates overflow behavior, and revises related smoke test assertions.

Changes

Document Viewer Updates

Layer / File(s)	Summary
Remove index health and source actions src/components/DocumentViewer.tsx	Removes the index health type, state handling, failure-path resets, sidebar display, and non-search “Open source” link.
Improve chunk navigation src/components/DocumentViewer.tsx, tests/ui-smoke.spec.ts	Selects the displayed matching chunk across mobile and desktop instances, expands collapsed text when needed, scrolls it into view, and verifies the highlighted chunk.
Restructure responsive viewer layout src/components/DocumentViewer.tsx, src/components/clinical-dashboard/global-mockup-search-shell.tsx, tests/ui-smoke.spec.ts	Updates container sizing, anchor order, PDF controls, mobile source/evidence composition, sticky scrolling classes, source-image spans, global overflow behavior, mobile ordering assertions, composer scroll setup, and compact hero sizing assertions.
Update routing regression coverage tests/ui-smoke.spec.ts	Adjusts asynchronous request polling and expects the revised “Not yet checked” source status.
Record review outcome docs/branch-review-ledger.md	Adds the pull request review record, commit, outcome, and checks.

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

🚥 Pre-merge checks | ✅ 11

✅ Passed checks (11 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the document-viewer redesign and sticky evidence rail change.
Description check	✅ Passed	The description follows the template and includes summary, verification, governance, and notes with sufficient detail.
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.
Generated And Sensitive Files	✅ Passed	Diff touches only source, test, and markdown docs; no secrets, .env files, caches, build outputs, or artifact directories were added.
Verification Claims	✅ Passed	PASS: the verification section names exact commands and outcomes (verify:cheap, verify:ui, eval:retrieval:quality), and the ledger row doesn’t claim an unqualified pass.
Risky Git Or Deployment Actions	✅ Passed	No added docs/scripts/workflows recommend force-push, reset --hard, destructive clean, branch deletion, or deployment actions; touched scripts only skip reserved ports.
Supabase Project And Schema Safety	✅ Passed	PR only changes UI components, tests, and a ledger doc; no Supabase project-ref, migration, schema, RLS, policy, or env files were touched.
Runtime And Package Manager Integrity	✅ Passed	PR only touches UI/tests/docs; no package.json, lockfile, or npmrc changes, and repo still pins npm@11.17.0, Node 24.x, engine-strict=true.
Api Route Failure Handling	✅ Passed	The diff only changes UI/tests/docs; no API routes, server actions, RAG, search, ingestion, or provider code was touched, so this check is not applicable.

✨ 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 claude/document-viewer-redesign-55b68b

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/document-viewer-redesign-55b68b

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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/DocumentViewer.tsx`:
- Around line 2715-2754: Update the deep-link scroll logic associated with
IndexedTextPanel so it targets the active visible panel using its
branch-specific idPrefix rather than the first data-source-chunk-id match in DOM
order. For the mobile source-text details element, expand the collapsed <details
id="source-text-mobile"> before calling scrollIntoView; keep desktop scrolling
scoped to the visible desktop panel.

🪄 Autofix (Beta)

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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 961ba547-febb-4e1b-8130-74db714d9475

📥 Commits

Reviewing files that changed from the base of the PR and between 54bd94d and 9130c8b.

📒 Files selected for processing (3)

• src/components/DocumentViewer.tsx
• src/components/clinical-dashboard/global-mockup-search-shell.tsx
• tests/ui-smoke.spec.ts

[coderabbitai]

Actionable comments posted: 1

🤖 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/ui-tools.spec.ts`:
- Around line 534-537: Update the compact hero mobile heading size assertion in
the relevant UI tools test to enforce the exact 26px value, replacing the
insufficient zero-precision toBeCloseTo check with toBe(26). Keep the icon
dimension assertions unchanged.

🪄 Autofix (Beta)

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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b8ca9298-c0cf-4091-b09d-97260a421dda

📥 Commits

Reviewing files that changed from the base of the PR and between 546fd77 and da5772a.

📒 Files selected for processing (3)

• docs/branch-review-ledger.md
• tests/ui-smoke.spec.ts
• tests/ui-tools.spec.ts

✅ Files skipped from review due to trivial changes (1)

• docs/branch-review-ledger.md

All actionable threads are resolved on the current head; dismissing the stale blocking review for verified merge readiness.