# ADR-0004 — PDF viewer library for the reference workspace

- Status: proposed
- Date: 2026-05-24
- 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

(blank — to be filled by the outcome of CE-WP-0002-T02.)

## Consequences

(blank)