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: extracting from the umbrella

The concrete anchor slice currently lives upstream in ../citation-evidence/src/anchor/. Workplan EANCH-WP-0001 moves it here as a standalone TypeScript package, wires the umbrella to consume this package, and verifies the round-trip. Shared-contract changes still happen in the umbrella (citation-evidence/wiki/), not here.

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 (re-exports the surfaces below)
  types.ts                      adapter-side types: SelectionCapture,
                                ResolvedAnchorTarget, AnchorResolution,
                                HighlightRenderOptions, DocumentViewerAdapter
  selectors/
    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-selector-math.test.ts
    pdf-viewer-adapter.tsx      concrete PDF DocumentViewerAdapter (from the spike)
  highlight/
    scroll-job.ts               scroll-to-target helper
    scroll-job.test.ts
    highlight-styles.css        highlight rendering styles
    debug-textlayer.css         optional text-layer debugging styles

Boundary rules for the layout:

• 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.

Public API (target surface)

import {
  createSelectors,
  resolveSelectors,
  type DocumentViewerAdapter,
  type AnchorResolution,
} from "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.