tegwick
08b3105454
Finish SCOPE.md (boundary, maturity, deps, non-goals + capability blocks), rewrite README.md as an extraction-oriented package doc with the initial src/ module layout (selectors/pdf/highlight) and public API surface. Selector types stay in citation-engine; selector behavior + viewer contract owned here (ADR-0006 / SharedContracts §8). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
82 lines
3.5 KiB
Markdown
82 lines
3.5 KiB
Markdown
# 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.
|