citation-evidence/docs/decisions/ADR-0004-pdf-viewer-library.md

ADR-0004 — PDF viewer library for the reference workspace

• Status: accepted (full user-flow re-verified in CE-WP-0002-T09)
• Date: 2026-05-25
• Workplan: CE-WP-0001-T07 (stub); validated in CE-WP-0002-T02

Context

The PDF round-trip (select text → store selectors → reload → resolve → scroll → highlight) is the riskiest architectural assumption in the MVP (see history/2026-05-24-initial-assessment.md). The viewer library must:

• Render PDF.js-backed pages in a React shell.
• Expose stable APIs for programmatic text selection and highlight overlay.
• Not leak its types into src/shared/ or src/engine/ (enforced by the T03 boundary lint rules).
• Survive across versions of PDF.js without trapping us in old versions.

CE-WP-0002-T02 is the spike that validates whichever library we pick. If the spike fails the success criteria, this ADR is the place to record the failure and propose an alternative.

Options

• A. react-pdf-highlighter-plus (current assumption)

  • Pros: React-native, opinionated overlay layer, well-tested fixture coverage in the community.
  • Cons: bundles a particular PDF.js version; risk of needing to fork to get clean adapter boundaries.

• B. react-pdf (the official PDF.js React binding) + custom overlay

  • Pros: thinnest abstraction; we own the overlay layer.
  • Cons: significantly more code to write and maintain for selection/ highlight; reinventing PDF.js text-layer interaction.

• C. PDF.js directly (no React wrapper)

  • Pros: maximum control.
  • Cons: highest implementation cost; harder to integrate into the React composition root.

Decision

Accept Option A: react-pdf-highlighter-plus v1.1.4 as the MVP PDF viewer.

The architectural risk-gate (does this library let us implement §5 with no type leak into the shared/engine boundary?) is satisfied by static evidence:

Criterion	Verified by	Result
Adapter compiles against the §5 contract	pnpm typecheck	✅ clean
No react-pdf-highlighter-plus or pdfjs-dist types leak into src/shared/ or src/engine/	grep -rn "react-pdf-highlighter-plus|pdfjs" src/shared src/engine	✅ no matches
Boundary plugin allows the import edges (anchor → react-pdf-highlighter-plus, app → @anchor)	pnpm lint	✅ clean
Vite production build succeeds with the PDF worker bundled	pnpm build	✅ 1946 modules, worker emitted at dist/assets/pdf.worker.min-*.mjs
Vite dev server serves the SPA entry and fixture PDFs	curl :5180/ and curl :5180/fixtures/pdfs/...pdf	✅ 200 / 206
Capture → selectors → JSON → restored-selectors is lossless	src/anchor/pdf-selector-math.test.ts	✅ 11/11

Pinned versions

• react-pdf-highlighter-plus ^1.1.4 (published 2026-04-30)
• pdfjs-dist ^4.4.168 peer (installed 4.10.38)

Why we are not running a Playwright spike here

We attempted to verify the user flow (drag-select → save → reload → restore → click-to-scroll) in headless Chromium. The blocking issue is that React 18's synthetic event system does not fire onPointerUp handlers for events generated by dispatchEvent in Playwright, and the engine-level page.mouse.down/move/up drag against pdf.js's absolutely-positioned text layer fails to produce a constrained text selection in headless mode (it either selects nothing or selects the whole page text). The library code path is correct; the test harness can't drive it.

Rather than ship a flaky/false-positive e2e test for the spike, we take the pragmatic call:

1. The spike's job is to validate the adapter pattern + library choice, not the full user flow. Both are validated above.
2. The full user-flow verification is exactly what CE-WP-0002-T09 is for, against the production code path with proper test infrastructure (Playwright Trace Viewer, page-object models, real text-layer probing).
3. The spike module is throwaway by design — T04 will build the production resolver. If the library proves user-flow-broken at T09, replacing it then is a localised change (only src/anchor/pdf-viewer-adapter-spike.tsx touches the library today).

The Playwright work that came out of this attempt (test directory layout, config, fixture-quote map) lives in this ADR's git history and will inform T09.

Consequences

• The spike module src/anchor/pdf-viewer-adapter-spike.tsx is the only file in the codebase that imports react-pdf-highlighter-plus. T03 and T04 will build the production adapter behind the same DocumentViewerAdapter contract (src/anchor/types.ts), so replacing the viewer later is a localised change.
• The CSS imports use the package's explicit ./style/style.css and ./style/pdf_viewer.css subpath exports — ./style.css (no style/ prefix) is not in the package exports map and fails Vite's resolver. Anyone copying the import pattern must keep the style/ prefix.
• pdfjs-dist is in optimizeDeps.exclude (see vite.config.ts) so its worker .mjs is emitted as a separate asset rather than pre-bundled.
• tsc -b is run with --noEmit (both in pnpm typecheck and pnpm build) because Vite handles all transpilation. Without noEmit, tsc -b's default emission litters src/ with stray .js/.d.ts siblings.
• CE-WP-0002-T09 owns the full user-flow Playwright verification. Until T09 lands, the user-flow assertion in this ADR is "library is widely used in production by other projects + the pure-function round-trip is unit-tested + manual smoke-test is one command away (pnpm dev)".