evidence-anchor/README.md

evidence-anchor

Selector creation, resolution, and the DocumentViewerAdapter contract that every document viewer in the citation-evidence workspace implements. This repo turns annotations from static marks into durable, reopenable source references.

• Owns: selector behavior — createSelectors, resolveSelectors, PDF selector math, the viewer-adapter contract, and highlight/scroll helpers.
• Does not own: selector type interfaces — those live in citation-engine (shared/selector). See ADR-0006 and SharedContracts.md §8.
• May depend on: citation-engine only (DependencyMap §4). Nothing from binder/, source/, or work/ may flow back into it.

See SCOPE.md for the boundary and INTENT.md for the long-range intent.

Status: extracted; umbrella consumes this package

The anchor slice has been extracted from the umbrella and now lives here. citation-evidence consumes it as @citation-evidence/evidence-anchor (link:../evidence-anchor); its former src/anchor/ directory is gone and the @anchor alias is retired. Shared-contract changes still happen in the umbrella (citation-evidence/wiki/), not here.

Remaining anchor work beyond this MVP slice (stale/orphan semantics, fuzzy re-anchoring, HTML/Markdown selectors, promoting the PDF spike to a production adapter) is tracked as follow-on work — see workplans/.

Install model

Sibling-checkout, linked-package model — this repo is checked out next to its consumers and consumed via a local link (e.g. link:../evidence-anchor), not published to a registry during MVP. Its only shared-type dependency is citation-engine, imported through the engine's public shared entrypoint (@citation-evidence/engine/shared) rather than umbrella-only @shared/* aliases.

Package layout (initial extracted version)

src/
  index.ts                      public entrypoint — full barrel (core + pdf)
  types.ts                      adapter-side types: SelectionCapture,
                                ResolvedAnchorTarget, AnchorResolution,
                                HighlightRenderOptions, DocumentViewerAdapter
  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/                          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-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 (enforced by eslint.config.js):

• 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) is the full barrel — selector creation/resolution, the adapter types/contract, and the PDF adapter — so consumers resolve every anchor symbol (and their test vi.mock(...) calls) from a single specifier, matching the umbrella's prior @anchor/index;
• a focused, viewer-free entry is also published at evidence-anchor/pdf for consumers that want the PDF surface explicitly. The concrete adapter is still the explicitly-named PdfSpikeViewer spike; promoting it to a production PDFViewerAdapter is registered follow-on work (T06).

Public API (target surface)

import {
  createSelectors,
  resolveSelectors,
  type DocumentViewerAdapter,
  type AnchorResolution,
} from "@citation-evidence/evidence-anchor";

Resolution is explicit about uncertainty — AnchorResolution.status is one of resolved / ambiguous / unresolved / stale with a 0..1 confidence, so a caller can highlight, ask the user to confirm, or mark a citation stale rather than silently highlight the wrong passage.