docs(document-viewer): add the Phase 3 execution handover

[BigSimmo]

Summary

• Adds docs/plans/document-viewer-phase3-handover.md — an execution brief for Phase 3 of docs/plans/document-viewer-redesign-plan.md. Phases 0–2 merged as PR feat(document-viewer): rework the viewer for phone and PWA reading #1741; Phase 3 was never started, so the viewer still rasters one page at a time and every page flip on a long guideline is a cold render.
• Corrects #279 in docs/outstanding-issues.md, which carried a refuted remedy.
• Fixes the recommended-queue preamble in docs/outstanding-issues.md, which falsely claimed to list every open row.
• Records the review in docs/branch-review-ledger.md (append-only, with a superseding row).

Scope is every Phase 3 capability except crop → page overlay. That exclusion is deliberate: bbox is SELECTed at src/lib/document-detail.ts:441 but absent from DocumentDetailImage in src/lib/document-detail-contract.ts, so plumbing it is a wider contract change than this phase should carry.

Correction to #279

#279 claimed the viewer canvas cannot be gated in a browser and proposed either bumping the pinned Playwright build or pinning pdfjs-dist down. Both would have been unnecessary dependency surgery. Measured:

	value
Container Chromium (/opt/pw-browsers/chromium-1194)	141.0.7390.37
Chromium pinned playwright@1.62.1 expects (browsers.json rev 1234)	151.0.7922.34
Chromium CI actually runs (lighthouse-budget.json:27)	HeadlessChrome/151.0.0.0
pdfjs-dist@6.2.108 calls Map.prototype.getOrInsertComputed	pdf.mjs:2454, 6889, 6896

getOrInsertComputed ships in Chromium 151 and not 141, so the raster failure is container-only — CI's browser already runs pdf.js 6. Writing that gate is Task 0 of the brief, and #279 now records the measurement with an explicit "do not bump Playwright, do not pin pdfjs-dist down".

Verification

npm run verify:pr-local classified this as recognised low-risk documentation scope and completed the ten applicable gates with none failed:

- completed: check:runtime, check:installed-lock-parity, format:changed, sitemap:check,
docs:check-index, docs:check-inventory, docs:check-scripts, docs:check-links,
check:branch-review-ledger, check:outstanding-issues
- failed: (none)
- not reached: (none)

The risk router skipped lint, typecheck, the full unit suite, RAG fixture validation, and build — no executable product code changed.

• docs:check-links passed with 1688 repo path references resolving, which is what validates the ~40 file/line citations in the brief.
• check:outstanding-issues passed: 287 rows, unique ids, next-id=290, and no ids deleted from base — the check that caught the silent row loss described below.
• git merge-tree --write-tree origin/main HEAD exits 0.
• Every viewer line reference was re-read against main at 50ef12e after rebasing off a 64-commit-stale base; the viewer files were unchanged across that range.

Risk and rollout

Documentation only — no product, test, config, or dependency changes, and nothing here reaches a runtime path. Rollout is the merge itself; rollback is git revert. The brief instructs future work rather than performing any, so it carries no behavioural risk of its own.

Clinical Governance Preflight: not applicable to this PR.classifyPullRequestFiles returns clinicalRisk: false for docs/**, and the behavioural trigger in AGENTS.md:257 does not fire either — no ingestion, answer generation, search/ranking, source rendering, document access, privacy, production config, or clinical output changes here. Note that the brief itself requires the preflight for the Phase 3 implementation work, which does change source rendering and document access.

RAG impact: no retrieval behaviour change — no protected ranking surface is touched (src/lib/rag/**, clinical-search, retrieval-selection, ranking-config, answer-ranking, the eval harness, the golden fixture, the retrieval RPCs).

Notes

• Resolving the merge conflict surfaced a duplicate #286: main's in-page-nav series and this branch's authorizationHeader row independently claimed the same id. Kept both, renumbered the branch's to #289. The auto-merge silently dropped the branch's detail row rather than conflicting on it — only the queue hunk raised a marker. That row is restored; it is the failure mode archive row #112 documents, where the guard catches duplicate ids but not a vanished one.
• All review threads addressed. Four findings fixed, two declined with reasons on the thread (both accepted by the reviewer), and one of my own rebuttals was wrong and reversed — the queue preamble genuinely did claim completeness.

Summary by CodeRabbit

• Documentation
  • Added a Phase 3 document-viewer handover guide covering multi-page viewing, rail virtualization, keyboard controls, rendering compatibility, signed URLs, and verification requirements.
  • Documented browser compatibility findings, synchronization constraints, preservation requirements, governance gates, and deferred evaluation areas.
  • Updated review, synchronization, and project handoff records, including corrections to prior browser diagnosis.
  • Refined the recommended outstanding-issues queue, added issue #289, and corrected issue #279 to clarify container-only PDF compatibility concerns and follow-up coverage.

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

📝 Walkthrough

Walkthrough

The PR adds a Phase 3 document-viewer handover plan. It documents rendering, virtualization, keyboard controls, verification, governance, signed-URL constraints, review-ledger updates, and outstanding issues.

Changes

Document viewer Phase 3 handover

Layer / File(s)	Summary
Phase 3 rendering and interaction plan docs/plans/document-viewer-phase3-handover.md	Defines canvas verification, PDF and image-rail virtualization, keyboard bindings, signed-URL handling, and conditional OffscreenCanvas evaluation.
Verification and delivery controls docs/plans/document-viewer-phase3-handover.md	Adds verification commands, compatibility gates, prohibited actions, commit requirements, governance conditions, and deferred-work procedures.
Review and authorization issue records docs/branch-review-ledger.md, docs/outstanding-issues.md	Records review synchronization, browser compatibility findings, the corrected Phase 3 handover, issue #289, and issue #279 updates.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• BigSimmo/Database#489: Covers related document-viewer layout, virtualization, deep-linking, and compatibility work.
• BigSimmo/Database#1687: Covers related DocumentFrame and PdfCanvasViewer rendering controls.
• BigSimmo/Database#1704: Covers related signed-URL and parent-provided URL behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding the Phase 3 document-viewer execution handover.
Description check	✅ Passed	The description covers the required summary, verification, risk and rollout, governance rationale, and notes with specific evidence.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/document-viewer-optimization-tu8tnj

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:b8c94dff23

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 4

🤖 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 `@docs/branch-review-ledger.md`:
- Line 810: Update the verification statement in the ledger entry to say “all
ten applicable gates completed; executable-code checks skipped by the docs-only
risk router,” and append the specific skipped check names if they are available
from the PR objectives or surrounding record.
In `@docs/plans/document-viewer-phase3-handover.md`:
- Around line 143-150: The Phase 3 plan must make the signed-URL fixes mandatory
before Task 3: require the dedupe key to use the lowercase authorization header,
move cache writes outside the shared promise so superseded responses cannot
repopulate cleared entries, and add regression tests for both behaviors before
modifying use-signed-image-url.ts. Track the cache-write fix separately if issue
`#286` covers only header casing.
- Around line 7-11: Update the Phase 3 scope and Task 3 references to resolve
the governance mismatch: either defer signed-URL API batching, or explicitly
list src/app/api/images/signed-urls/route.ts as a scope exception and require
the governance preflight triggered by clinicalRiskPatterns. Apply the same
clarification to the corresponding sections noted in the review.
- Line 146: Update the inline code span in the dedupe-key example to remove the
trailing space, changing the referenced key from `endpoint ` to `endpoint` while
preserving the surrounding text.

🪄 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: b6f0bad5-62da-4303-8bbf-82b191fa80e8

📥 Commits

Reviewing files that changed from the base of the PR and between 50ef12e and a7fd780.

📒 Files selected for processing (3)

• docs/branch-review-ledger.md
• docs/outstanding-issues.md
• docs/plans/document-viewer-phase3-handover.md

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@docs/branch-review-ledger.md`:
- Line 820: Update the line containing the `pr-handoff-stop` failure in the
ledger entry to replace the bare `#286` with a stable reference, such as the
issue title or both the historical failure identifier and current issue
identifier. Preserve the existing test-result context and distinguish it from
the in-page-navigation issue currently associated with `#286`.
- Line 828: Synchronize issue `#279` with its durable disposition: update the
corresponding entry through the /issues workflow to record the required CI
compatibility check or Playwright/pdfjs version change, or explicitly state in
the handover row that it is not authoritative for `#279`’s disposition. Use the
issue `#279` entry and the handover record as the target symbols.
In `@docs/outstanding-issues.md`:
- Around line 166-169: Regenerate the outstanding-issues queue from the complete
open-row set so it includes every open issue, including `#258`, `#260`–#262,
`#264`–#270, and `#271`–#285, rather than jumping from `#257` to `#286`. Update the
queue section while preserving its existing row format and completeness claim.

🪄 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: 82f2941b-0ea6-4158-9bc8-e01516abec83

📥 Commits

Reviewing files that changed from the base of the PR and between a7fd780 and 18257ad.

📒 Files selected for processing (3)

• docs/branch-review-ledger.md
• docs/outstanding-issues.md
• docs/plans/document-viewer-phase3-handover.md