coulomb/evidence-anchor
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
evidence-anchor/SCOPE.md
tegwick bbeba96173
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 2s
Details
EANCH-WP-0004: HtmlViewer scroll parity and viewer-shell workplan 
Export HtmlViewerAdapter from package root, add scrollRequestKey parity,
register finished workplan, update SCOPE.
2026-07-09 09:58:41 +02:00

5.4 KiB
Raw Permalink Blame History

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, fuzzy recovery floor, and selector-redundancy rules
  • PDF selector math (page number + normalized page rectangles, page-local text)
  • DOM/structural selector creation and resolution for HTML/Markdown
  • the format-neutral DocumentViewerAdapter contract, the PDF adapter, and the HTML viewer
  • 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).

Still deferred (beyond EANCH-WP-0004)

  • FragmentSelector (export-only deep links)
  • human-confirmation UI for ambiguous/fuzzy matches

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: active — standalone package consumed by citation-evidence
  • Implementation: PDF + HTML/Markdown selector paths, stale/orphan/fuzzy resolution, PdfViewerAdapter, and HtmlViewerAdapter (evidence-anchor/dom)
  • Stability: evolving — shared contracts stable; HTML/MD wired in citation-work ViewerShell
  • 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

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]

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.