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>
150 lines
5.6 KiB
Markdown
150 lines
5.6 KiB
Markdown
# SCOPE
|
|
|
|
> This file helps you quickly understand what this repository is about,
|
|
> when it is relevant, and when it is not.
|
|
> It is intentionally lightweight and may be incomplete.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
Selector creation, resolution, re-anchoring, and highlight/scroll contracts that
|
|
keep citation-evidence annotations attached to their source passages.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
An **anchor** is a resolvable reference to a passage in a document, represented
|
|
by several complementary *selectors* (visual, text, structural, context). Given
|
|
a stored selector set and a document representation, this repo answers: *where is
|
|
this passage now, and how confident are we?* — returning a confidence-scored
|
|
result (`resolved` / `ambiguous` / `unresolved` / `stale`) rather than a silent
|
|
guess. It also owns the `DocumentViewerAdapter` contract every viewer implements.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
- selector **creation** from a captured viewer selection (`createSelectors`)
|
|
- selector **resolution** against a document representation (`resolveSelectors`)
|
|
- the exact-match confidence ladder and selector-redundancy rules
|
|
- PDF selector math (page number + normalized page rectangles, page-local text)
|
|
- the format-neutral `DocumentViewerAdapter` contract and the first PDF adapter
|
|
- scroll-to-target and highlight-render contracts + helpers
|
|
- anchor confidence scoring and ambiguous/unresolved/stale reporting
|
|
|
|
Selector *behavior* lives here; selector *type interfaces* live in
|
|
`citation-engine` (see ADR-0006 and SharedContracts §8).
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- selector *type definitions* — owned by `citation-engine` (`shared/selector`)
|
|
- persistence policy, the canonical evidence domain model, citation-card rendering
|
|
- document ingestion, OCR, metadata extraction, external source lookup
|
|
- form-field binding semantics, guide-overlay UI, application shell / deployment
|
|
- becoming a viewer implementation itself (it defines the adapter, not the viewer)
|
|
|
|
During the umbrella-first MVP these belong to the appropriate citation-evidence
|
|
subsystem. This repo may depend on **`citation-engine` only** (DependencyMap §4).
|
|
|
|
### Not in this extraction slice (EANCH-WP-0001)
|
|
|
|
- full HTML/Markdown (`DomSelectionCapture`) selector implementation
|
|
- production-grade fuzzy / recovery-oriented re-anchoring
|
|
- `stale` and orphaned-annotation semantics beyond what upstream already ships
|
|
|
|
These are real INTENT.md goals but are **registered as follow-on work**, not
|
|
built during the initial extract-and-verify pass.
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- creating anchors from a user text selection in a document viewer
|
|
- resolving stored selectors back into a representation to reopen a citation
|
|
- implementing a new `DocumentViewerAdapter` (PDF today; HTML/Markdown later)
|
|
- scrolling to and highlighting a cited passage
|
|
|
|
---
|
|
|
|
## Not Relevant When
|
|
|
|
- you need selector *type* shapes only — import from `citation-engine`
|
|
- you are working on ingestion, persistence, binding, or the app shell
|
|
- you need the integrated review workspace UX — that is `citation-work` / umbrella
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
- Status: experimental — extracting from the umbrella into a standalone package
|
|
- Implementation: partial — pure selector + PDF adapter slice exists upstream in
|
|
`../citation-evidence/src/anchor/`; extraction tracked by EANCH-WP-0001
|
|
- Stability: evolving — shared contracts stable, this repo's package API forming
|
|
- Usage: internal (consumed by `citation-evidence` during MVP)
|
|
|
|
---
|
|
|
|
## How It Fits
|
|
|
|
- Upstream dependencies: `citation-engine` (shared selector/document/annotation types)
|
|
- Downstream consumers: `citation-evidence` (umbrella), later `citation-work`,
|
|
`evidence-source`, `evidence-binder`
|
|
- Often used with: a concrete document viewer (PDF.js + react-pdf-highlighter-plus)
|
|
|
|
---
|
|
|
|
## Terminology
|
|
|
|
- Preferred terms: anchor, selector, resolution, re-anchoring, highlight contract
|
|
- Also known as: "the anchoring layer"
|
|
- Potentially confusing terms: `Selector` (the *type* is engine-owned; the
|
|
*behavior* is anchor-owned — see ADR-0006)
|
|
|
|
---
|
|
|
|
## Related / Overlapping Repositories
|
|
|
|
- `citation-engine` — owns shared selector/document/annotation type interfaces
|
|
- `citation-evidence` — umbrella; current home of the code being extracted
|
|
- `evidence-source` — document ingestion / representations (consumer)
|
|
- `citation-work` — review workspace UX (consumer)
|
|
- `evidence-binder` — evidence-to-target binding (consumer)
|
|
|
|
---
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: `INTENT.md` (intended responsibilities), then this file
|
|
- Key files / directories: upstream `../citation-evidence/src/anchor/` is the
|
|
extraction source; post-extraction the package layout is in `README.md`
|
|
- Entry points: `createSelectors`, `resolveSelectors`, `DocumentViewerAdapter`
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: library
|
|
title: Durable citation anchoring (selectors + resolution)
|
|
description: Create redundant selectors for a document passage and resolve them back into a representation with a confidence-scored result, so citations survive zoom, re-render, and light source edits.
|
|
keywords: [anchor, selector, resolution, citation, highlight, pdf]
|
|
```
|
|
|
|
```capability
|
|
type: interface
|
|
title: DocumentViewerAdapter contract
|
|
description: A format-neutral viewer adapter contract (selection capture, selector creation, resolution, scroll-to-target, highlight render) that any document viewer implements; PDF adapter provided first.
|
|
keywords: [viewer, adapter, highlight, scroll, pdf, contract]
|
|
```
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
Shared contracts are maintained in the umbrella and must not be contradicted here:
|
|
`citation-evidence/wiki/SharedContracts.md`, `wiki/DependencyMap.md`,
|
|
`docs/decisions/ADR-0006-selector-ownership-split.md`.
|