coulomb/evidence-anchor
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

EANCH-WP-0001 T04: extract PDF adapter + scroll/highlight helpers

Browse source 
Move pdf-viewer-adapter-spike.tsx, scroll-job.ts (+test), highlight-styles.css
and debug-textlayer.css into src/pdf/ (the adapter boundary). Rewrite the
spike's @shared import to @citation-evidence/engine/shared and its ./types to
../types. Add src/css.d.ts so tsc accepts side-effect .css imports.

Decisions:
- adapter stays the explicitly-named PdfSpikeViewer spike; promotion to a
  production PDFViewerAdapter is registered as T06 follow-on work
- viewer libs (pdfjs-dist, react, react-pdf-highlighter-plus) confined to
  src/pdf/ and exposed only via the evidence-anchor/pdf subpath; the root
  entrypoint stays pure. Boundary enforced by eslint no-restricted-imports.
- ported unit suites (pdf-selector-math round-trip + scroll-job retry) serve
  as the inspectable harness for capture->selectors->resolve->scroll.

Verified: pnpm test (30 passed), typecheck, lint all green. README layout updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-07-08 20:44:52 +02:00
parent bd7f56c111
commit 5b77dbd314
10 changed files with 720 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

35
README.md
View file

@ -34,36 +34,41 @@ aliases.
```text
src/
index.ts public entrypoint (re-exports the surfaces below)
index.ts public entrypoint — pure surface only
types.ts adapter-side types: SelectionCapture,
ResolvedAnchorTarget, AnchorResolution,
HighlightRenderOptions, DocumentViewerAdapter
selectors/
css.d.ts ambient decl for side-effect .css imports
selectors/ pure core — no viewer/UI deps
index.ts createSelectors, resolveSelectors, DEFAULT_CONTEXT_CHARS
create.ts selector creation from a captured selection
resolve.ts resolution + the exact-match confidence ladder
create.test.ts
resolve.test.ts
pdf/
pdf-selector-math.ts page number + normalized page-rectangle math
pdf/ adapter boundary — the only place viewer libs live
index.ts subpath entry `evidence-anchor/pdf`
pdf-selector-math.ts pure page + normalized-rect math (capture↔selectors)
pdf-selector-math.test.ts
pdf-viewer-adapter.tsx concrete PDF DocumentViewerAdapter (from the spike)
highlight/
scroll-job.ts scroll-to-target helper
pdf-viewer-adapter-spike.tsx concrete PDF adapter (PdfSpikeViewer)
scroll-job.ts retryable scroll-to-highlight helper
scroll-job.test.ts
highlight-styles.css highlight rendering styles
debug-textlayer.css optional text-layer debugging styles
```
Boundary rules for the layout:
Boundary rules for the layout (enforced by `eslint.config.js`):
- viewer-library imports (`pdfjs`, `react-pdf-highlighter-plus`) are confined to
`src/pdf/` — they never appear on `types.ts` or on the public surface;
- `src/selectors/` is pure (no viewer/UI deps) and depends only on
`citation-engine` shared types;
- the public entrypoint re-exports the stable surface consumers rely on:
`createSelectors`, `resolveSelectors`, the selector/resolution types, the
`DocumentViewerAdapter` contract, and the PDF adapter.
- viewer-library imports (`pdfjs-dist`, `react`, `react-pdf-highlighter-plus`)
are confined to `src/pdf/` — the pure zone (`src/selectors/**`, `src/types.ts`)
may not import them;
- `src/selectors/` is pure and depends only on `citation-engine` shared types;
- the **root** entrypoint (`evidence-anchor`) exposes only the pure surface —
`createSelectors`, `resolveSelectors`, the selector/resolution types, and the
`DocumentViewerAdapter` contract;
- the concrete PDF adapter is reached through the **`evidence-anchor/pdf`**
subpath, so pure consumers never pull PDF.js or React into their bundle. That
adapter is still the explicitly-named `PdfSpikeViewer` spike; promoting it to
a production `PDFViewerAdapter` is registered follow-on work (T06).
## Public API (target surface)