# 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/`](../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)

```text
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)

```ts
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.