@weatherboard/annotation 0.2.2 → 0.3.0

package/dist/anchor.d.mts

@@ -0,0 +1,295 @@
+/**
+ * Putting a capture back on the element it came from (A-275).
+ *
+ * ===========================================================================
+ * WHY THIS IS A PACKAGE EXPORT AND NOT A MEASUREMENT HARNESS
+ * ===========================================================================
+ *
+ * The slice that produced this file was originally scoped as "measure whether
+ * anchoring can work", with rendering explicitly out of scope. That was wrong,
+ * and the reason is A-268's shape: resolving an anchor against a live DOM **is**
+ * the marker-placement code. Measuring with one implementation and shipping
+ * another later gives two implementations of one primitive, and two
+ * implementations of one primitive is a way for them to disagree — which is the
+ * principle `capture-token.ts` already names, and the defect A-268 already was.
+ *
+ * So `resolveAnchor` is the export the marker layer (A-277) imports, and the
+ * measurement in A-275 is that same function called on staging pages.
+ *
+ * **The measurement and the decision it produced are in
+ * `docs/decisions/a-275-anchor-placement.md`**, and `anchor-measure.mjs` runs it
+ * again. Read the decision before changing anything here.
+ *
+ * Every figure in this file is quoted from that document with its denominator,
+ * or is a property of the code rather than a measurement and says so. That rule
+ * exists because it was broken here: two comments claimed `MEASURED: 105 of 200`
+ * — a stale figure, from a SAMPLE the decision document explicitly retires, for a
+ * branch it was not even a statistic about. **A number labelled MEASURED that no
+ * checked-in artifact can reproduce is worse than no number**, which this
+ * package's own size-budget note already says about a different number.
+ *
+ * The headline, so it is not paraphrased loosely elsewhere: **139 of 546
+ * annotated elements on the staging home page resolve to exactly one element,
+ * and 0 of 546 resolve to the wrong one.** Every plausible improvement to the
+ * first figure is a way of trading the second one away.
+ *
+ * ===========================================================================
+ * WHY `source_file:source_line` IS NOT AN ANCHOR
+ * ===========================================================================
+ *
+ * A source ref identifies a **component**, not an **instance**. Six cards
+ * rendered from one `<PubCard/>` all carry the same `data-src`, and the file and
+ * line say nothing about which one a reviewer clicked.
+ *
+ * The first draft of this scheme fixed that with an ordinal — the element's
+ * index among the matches, in document order. A reviewer showed that this is
+ * **wrong rather than merely incomplete**, and the argument is worth keeping
+ * because it is not obvious:
+ *
+ *   An ordinal is POSITIONAL. Delete the second card, and a capture anchored to
+ *   ordinal 3 resolves to what used to be card 4. Exactly one match. A marker is
+ *   drawn, on the wrong element, and NOTHING ANYWHERE HAS A COMPLAINT — a
+ *   "cannot be confidently placed" rule never fires, because the failure IS a
+ *   confident single match.
+ *
+ * A marker on the wrong element does not degrade this feature, it inverts it:
+ * the entire value of putting the conversation on the component is that
+ * *"this one, here"* stops being ambiguous.
+ *
+ * ===========================================================================
+ * SO: A DISCONFIRMING SIGNAL, NOT A UNIQUENESS TEST
+ * ===========================================================================
+ *
+ * Uniqueness is satisfied by every silent failure above, so uniqueness cannot be
+ * the test. What the anchor stores instead is the **whole source chain** —
+ * `TargetInfo.sourceChain`, every `data-src` from the clicked element up to the
+ * root, innermost first, which the capture has carried since A-33 and which the
+ * ingest has persisted since A-287 — and a candidate must match the chain, not
+ * just the leaf.
+ *
+ * A reordered sibling still matches (its ancestors did not change). An element
+ * that MOVED does not (its ancestors did). The chain is a claim the DOM can
+ * contradict, and that is the only kind of claim worth storing.
+ *
+ * It does not make repeated siblings distinguishable, and it is not supposed to:
+ * two identical cards in one list have identical chains, so an anchor to either
+ * resolves `"ambiguous"`. That is the SAFE failure — the marker is withheld and
+ * the count says so — and it is the one an ordinal would have converted into a
+ * confident wrong answer.
+ *
+ * ===========================================================================
+ * A TAGGED UNION FROM DAY ONE
+ * ===========================================================================
+ *
+ * Not speculative generality: two capture kinds that cannot carry a usable
+ * source ref ALREADY SHIP. `TargetInfo.domPath` is the documented fallback for a
+ * page whose elements have no refs, and region captures (A-179) exist, where
+ * `sourceChain` is the siblings a rectangle crossed rather than ancestors —
+ * a chain that contains nothing of itself and would be silently read as an
+ * ancestor chain by anything that assumed one shape.
+ *
+ * Retrofitting a union onto flat columns after a year of rows is the expensive
+ * version of this, and the read response (A-276) is additive-only forever, so
+ * `kind` is what lets an older SDK skip a marker it does not understand rather
+ * than misplace it.
+ */
+import { type ElementLike } from "./target.mjs";
+import { type SourceRef, type TargetInfo } from "./protocol.mjs";
+/**
+ * An element identified by the source location that rendered it, plus the chain
+ * of source locations above it.
+ *
+ * `chain` is innermost-first and INCLUDES the leaf, exactly as
+ * `collectSourceChain` produces it — one array, not a leaf plus a tail, because
+ * two representations of one list is a way for them to disagree about whether
+ * entry zero is the element or its parent.
+ */
+export interface SourceRefAnchor {
+    kind: "source-ref";
+    file: string;
+    line: number;
+    column?: number;
+    chain: SourceRef[];
+    /**
+     * The element's index among the leaf-matching candidates at capture time.
+     *
+     * **Recorded, and deliberately never used to select.** It is here because
+     * knowing "this was the 3rd of 6" is genuinely useful when a human is looking
+     * at an unresolved anchor and asking what happened — and it is *not* here as a
+     * tie-break, for the reason set out at length in this file's header. If you
+     * are about to reach for it to turn an `"ambiguous"` into an element, that is
+     * the bug this whole scheme was rewritten to avoid; `anchor.test.ts` has a
+     * test that fails if you do.
+     */
+    ordinal?: number;
+}
+/** A CSS-ish path, for elements no build transform gave a ref. */
+export interface DomPathAnchor {
+    kind: "dom-path";
+    path: string;
+}
+/**
+ * "Something on THIS page."
+ *
+ * First-class rather than a fallback of last resort: it is the honest home for a
+ * region capture, for a canvas, for a PDF, and for any product that is not a JSX
+ * tree.
+ *
+ * ===========================================================================
+ * `path` IS NOT OPTIONAL DECORATION — IT IS WHAT MAKES "THIS PAGE" MEAN ANYTHING
+ * ===========================================================================
+ *
+ * The first version of this interface had no fields at all and `resolveAnchor`
+ * returned `doc.body` unconditionally, with a comment calling it *"always
+ * placeable"*. A reviewer pointed out that this reintroduces, through the route
+ * branch, exactly the failure the source-ref scheme was rewritten to prevent:
+ *
+ *   A capture taken on `/guides/a` resolves CONFIDENTLY on `/guides/b`. One
+ *   match, marker drawn, wrong page, counted as `placed`. No signal anywhere.
+ *
+ * That is not a rate to be estimated. `return doc.body` has no input but the
+ * document, so under it **every** route anchor placed on **every** page it was
+ * shown — 100%, by construction, and there is nothing to measure. The reason it
+ * matters is `payload.page.route`: it is the matched PATTERN rather than the
+ * URL, so "the page this came from" was never pinned in the first place. And
+ * `anchorFromTarget` sends every region capture down this branch, so it is the
+ * common case rather than the edge.
+ *
+ * The measured neighbour is the SOURCE-REF branch meeting the same problem:
+ * 414 anchors captured on one guide page resolve **identically** after a real
+ * navigation to another guide page — 161 placed, 253 ambiguous, 0 refused, the
+ * same three numbers on both — recorded with its method and denominator in
+ * `docs/decisions/a-275-anchor-placement.md` § *The limit this does not fix*.
+ * It is a different branch and a different number, cited here as evidence that
+ * the pattern-not-URL problem is real, not as a figure for this one.
+ *
+ * So a route anchor carries the RESOLVED path it was captured on, and
+ * `resolveAnchor` refuses when the document is somewhere else.
+ *
+ * ===========================================================================
+ * AND ABSENT MEANS "CANNOT PLACE", NEVER "PLACE ANYWAY"
+ * ===========================================================================
+ *
+ * `path` is optional because the field is newer than the wire, and the read-back
+ * plan's versioning rule for exactly this case is that a new anchor field is
+ * optional and **absent means cannot place** — the precedent `selection?:` set.
+ * A route anchor with no `path`, or a document that cannot say where it is,
+ * therefore resolves to `"none"`.
+ *
+ * That is a deliberate choice to under-place rather than mis-place, and it costs
+ * nothing today because no route anchor has ever been stored: markers have not
+ * shipped. It would be a real cost if this were retrofitted a year from now,
+ * which is the argument for doing it here.
+ *
+ * WHAT IT DOES NOT FIX: a SOURCE-REF anchor still resolves happily on a
+ * different `[id]` of the same route pattern — the markup is identical, so there
+ * is nothing for the chain to disagree with, and no amount of anchor design
+ * closes it. That one is the read endpoint's (A-276): scope the query on the
+ * resolved path, not on `route`. Stated here because an unstated limit gets read
+ * as a covered one.
+ */
+export interface RouteAnchor {
+    kind: "route";
+    /** `location.pathname` at capture time. Absent means the anchor cannot be placed. */
+    path?: string;
+}
+export type Anchor = SourceRefAnchor | DomPathAnchor | RouteAnchor;
+/**
+ * Where a marker goes, or why it does not go anywhere.
+ *
+ * Three outcomes and not two, because `"none"` and `"ambiguous"` are different
+ * facts about the page and a caller counting them together loses the one that
+ * says the markup moved.
+ */
+export type AnchorResolution<E extends ElementLike = ElementLike> = E | "none" | "ambiguous";
+/**
+ * The narrowest slice of `Document` this module reads. A real `Document`
+ * satisfies it, which `anchor.test.ts` asserts at compile time.
+ *
+ * `location` is here for the route branch above. It is optional because a parsed
+ * fixture has no location, and a document that cannot say where it is makes a
+ * route anchor unplaceable rather than placeable-by-default.
+ */
+export interface DocumentLike<E extends ElementLike = ElementLike> {
+    querySelectorAll(selectors: string): ArrayLike<E>;
+    body?: E | null;
+    location?: {
+        pathname: string;
+    } | null;
+}
+/**
+ * Resolve an anchor against a document.
+ *
+ * Pure: it reads the document and returns an element or a refusal, and it never
+ * mutates, measures layout, or draws anything. That is what lets the same
+ * function be a unit test over a checked-in HTML fixture, a number in a
+ * measurement run, and the marker layer's placement call.
+ *
+ * A `kind` this version does not recognise resolves to `"none"` — the read
+ * response is additive-only forever (A-276), so an SDK meeting a newer console
+ * must SKIP a marker it cannot place rather than guess at one.
+ */
+export declare function resolveAnchor<E extends ElementLike>(anchor: Anchor, doc: DocumentLike<E>): AnchorResolution<E>;
+export interface AnchorFromTargetOptions {
+    /** Document order index among leaf-matching candidates, when the caller has a document. */
+    ordinal?: number;
+    /**
+     * `location.pathname` at capture time — the RESOLVED path, not the route
+     * pattern.
+     *
+     * Pass it. A route anchor built without it can never be placed, by design; see
+     * `RouteAnchor`. It is optional here rather than required because
+     * `anchorFromTarget` is also called for element captures, where it is unused.
+     */
+    path?: string;
+}
+/**
+ * Build the anchor for a capture.
+ *
+ * The capture side of the same primitive, here rather than in `target.ts` so the
+ * union and the function that produces it cannot drift apart.
+ *
+ * **A region capture becomes a `route` anchor.** Its `sourceChain` is the
+ * siblings a rectangle crossed, which contain nothing of each other; handing
+ * that to `chainMatches` would compare a sibling list against an ancestor list
+ * and refuse — the right answer for the wrong reason, and one that would report
+ * every region capture as "the markup moved". Route-level is what a region
+ * capture actually means: something on this page, in that area.
+ */
+export declare function anchorFromTarget(target: Pick<TargetInfo, "selection" | "source" | "sourceChain" | "domPath">, options?: AnchorFromTargetOptions): Anchor;
+/**
+ * The counts a caller reports, so that "0 markers" is never the same string as
+ * "working, nothing here" (rule 1 of the read-back plan).
+ *
+ * ===========================================================================
+ * `wrong` IS NOT IN HERE AND CANNOT BE, AND THAT IS A GAP RATHER THAN A DESIGN
+ * ===========================================================================
+ *
+ * Whether a resolved element is the RIGHT element is not knowable from the live
+ * page alone — it takes a before/after comparison, which is what A-275's
+ * mutation battery does and what no runtime caller can do.
+ *
+ * So `placed` means "resolved to exactly one element", NOT "resolved
+ * correctly", and there is one measured channel where those differ: a
+ * source-ref anchor captured on one `[id]` resolves on another `[id]` of the
+ * same route pattern, because the two pages are structurally identical.
+ *
+ * MEASURED at **161 of 414 anchors** placing on a different `[id]` of the same
+ * route pattern, with zero refusals — indistinguishable, count for count, from
+ * resolving against the page they were captured on. The method, the denominator
+ * and the pages are in `docs/decisions/a-275-anchor-placement.md` § *The limit
+ * this does not fix*, and `node anchor-measure.mjs --url … --compare-url …`
+ * re-runs it in one command. Nothing in this module can detect it; the
+ * fix is for the read endpoint to scope on the resolved path (A-276), so a
+ * caller must not read `placed` as a correctness figure until it does.
+ *
+ * The route branch closes its own half of that (`RouteAnchor.path`). This
+ * comment is the record that the source-ref half is still open.
+ */
+export interface AnchorTally {
+    total: number;
+    placed: number;
+    ambiguous: number;
+    unresolved: number;
+}
+export declare function tallyAnchors<E extends ElementLike>(anchors: readonly Anchor[], doc: DocumentLike<E>): AnchorTally;

package/dist/anchor.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Putting a capture back on the element it came from (A-275).
+ *
+ * ===========================================================================
+ * WHY THIS IS A PACKAGE EXPORT AND NOT A MEASUREMENT HARNESS
+ * ===========================================================================
+ *
+ * The slice that produced this file was originally scoped as "measure whether
+ * anchoring can work", with rendering explicitly out of scope. That was wrong,
+ * and the reason is A-268's shape: resolving an anchor against a live DOM **is**
+ * the marker-placement code. Measuring with one implementation and shipping
+ * another later gives two implementations of one primitive, and two
+ * implementations of one primitive is a way for them to disagree — which is the
+ * principle `capture-token.ts` already names, and the defect A-268 already was.
+ *
+ * So `resolveAnchor` is the export the marker layer (A-277) imports, and the
+ * measurement in A-275 is that same function called on staging pages.
+ *
+ * **The measurement and the decision it produced are in
+ * `docs/decisions/a-275-anchor-placement.md`**, and `anchor-measure.mjs` runs it
+ * again. Read the decision before changing anything here.
+ *
+ * Every figure in this file is quoted from that document with its denominator,
+ * or is a property of the code rather than a measurement and says so. That rule
+ * exists because it was broken here: two comments claimed `MEASURED: 105 of 200`
+ * — a stale figure, from a SAMPLE the decision document explicitly retires, for a
+ * branch it was not even a statistic about. **A number labelled MEASURED that no
+ * checked-in artifact can reproduce is worse than no number**, which this
+ * package's own size-budget note already says about a different number.
+ *
+ * The headline, so it is not paraphrased loosely elsewhere: **139 of 546
+ * annotated elements on the staging home page resolve to exactly one element,
+ * and 0 of 546 resolve to the wrong one.** Every plausible improvement to the
+ * first figure is a way of trading the second one away.
+ *
+ * ===========================================================================
+ * WHY `source_file:source_line` IS NOT AN ANCHOR
+ * ===========================================================================
+ *
+ * A source ref identifies a **component**, not an **instance**. Six cards
+ * rendered from one `<PubCard/>` all carry the same `data-src`, and the file and
+ * line say nothing about which one a reviewer clicked.
+ *
+ * The first draft of this scheme fixed that with an ordinal — the element's
+ * index among the matches, in document order. A reviewer showed that this is
+ * **wrong rather than merely incomplete**, and the argument is worth keeping
+ * because it is not obvious:
+ *
+ *   An ordinal is POSITIONAL. Delete the second card, and a capture anchored to
+ *   ordinal 3 resolves to what used to be card 4. Exactly one match. A marker is
+ *   drawn, on the wrong element, and NOTHING ANYWHERE HAS A COMPLAINT — a
+ *   "cannot be confidently placed" rule never fires, because the failure IS a
+ *   confident single match.
+ *
+ * A marker on the wrong element does not degrade this feature, it inverts it:
+ * the entire value of putting the conversation on the component is that
+ * *"this one, here"* stops being ambiguous.
+ *
+ * ===========================================================================
+ * SO: A DISCONFIRMING SIGNAL, NOT A UNIQUENESS TEST
+ * ===========================================================================
+ *
+ * Uniqueness is satisfied by every silent failure above, so uniqueness cannot be
+ * the test. What the anchor stores instead is the **whole source chain** —
+ * `TargetInfo.sourceChain`, every `data-src` from the clicked element up to the
+ * root, innermost first, which the capture has carried since A-33 and which the
+ * ingest has persisted since A-287 — and a candidate must match the chain, not
+ * just the leaf.
+ *
+ * A reordered sibling still matches (its ancestors did not change). An element
+ * that MOVED does not (its ancestors did). The chain is a claim the DOM can
+ * contradict, and that is the only kind of claim worth storing.
+ *
+ * It does not make repeated siblings distinguishable, and it is not supposed to:
+ * two identical cards in one list have identical chains, so an anchor to either
+ * resolves `"ambiguous"`. That is the SAFE failure — the marker is withheld and
+ * the count says so — and it is the one an ordinal would have converted into a
+ * confident wrong answer.
+ *
+ * ===========================================================================
+ * A TAGGED UNION FROM DAY ONE
+ * ===========================================================================
+ *
+ * Not speculative generality: two capture kinds that cannot carry a usable
+ * source ref ALREADY SHIP. `TargetInfo.domPath` is the documented fallback for a
+ * page whose elements have no refs, and region captures (A-179) exist, where
+ * `sourceChain` is the siblings a rectangle crossed rather than ancestors —
+ * a chain that contains nothing of itself and would be silently read as an
+ * ancestor chain by anything that assumed one shape.
+ *
+ * Retrofitting a union onto flat columns after a year of rows is the expensive
+ * version of this, and the read response (A-276) is additive-only forever, so
+ * `kind` is what lets an older SDK skip a marker it does not understand rather
+ * than misplace it.
+ */
+import { type ElementLike } from "./target.js";
+import { type SourceRef, type TargetInfo } from "./protocol.js";
+/**
+ * An element identified by the source location that rendered it, plus the chain
+ * of source locations above it.
+ *
+ * `chain` is innermost-first and INCLUDES the leaf, exactly as
+ * `collectSourceChain` produces it — one array, not a leaf plus a tail, because
+ * two representations of one list is a way for them to disagree about whether
+ * entry zero is the element or its parent.
+ */
+export interface SourceRefAnchor {
+    kind: "source-ref";
+    file: string;
+    line: number;
+    column?: number;
+    chain: SourceRef[];
+    /**
+     * The element's index among the leaf-matching candidates at capture time.
+     *
+     * **Recorded, and deliberately never used to select.** It is here because
+     * knowing "this was the 3rd of 6" is genuinely useful when a human is looking
+     * at an unresolved anchor and asking what happened — and it is *not* here as a
+     * tie-break, for the reason set out at length in this file's header. If you
+     * are about to reach for it to turn an `"ambiguous"` into an element, that is
+     * the bug this whole scheme was rewritten to avoid; `anchor.test.ts` has a
+     * test that fails if you do.
+     */
+    ordinal?: number;
+}
+/** A CSS-ish path, for elements no build transform gave a ref. */
+export interface DomPathAnchor {
+    kind: "dom-path";
+    path: string;
+}
+/**
+ * "Something on THIS page."
+ *
+ * First-class rather than a fallback of last resort: it is the honest home for a
+ * region capture, for a canvas, for a PDF, and for any product that is not a JSX
+ * tree.
+ *
+ * ===========================================================================
+ * `path` IS NOT OPTIONAL DECORATION — IT IS WHAT MAKES "THIS PAGE" MEAN ANYTHING
+ * ===========================================================================
+ *
+ * The first version of this interface had no fields at all and `resolveAnchor`
+ * returned `doc.body` unconditionally, with a comment calling it *"always
+ * placeable"*. A reviewer pointed out that this reintroduces, through the route
+ * branch, exactly the failure the source-ref scheme was rewritten to prevent:
+ *
+ *   A capture taken on `/guides/a` resolves CONFIDENTLY on `/guides/b`. One
+ *   match, marker drawn, wrong page, counted as `placed`. No signal anywhere.
+ *
+ * That is not a rate to be estimated. `return doc.body` has no input but the
+ * document, so under it **every** route anchor placed on **every** page it was
+ * shown — 100%, by construction, and there is nothing to measure. The reason it
+ * matters is `payload.page.route`: it is the matched PATTERN rather than the
+ * URL, so "the page this came from" was never pinned in the first place. And
+ * `anchorFromTarget` sends every region capture down this branch, so it is the
+ * common case rather than the edge.
+ *
+ * The measured neighbour is the SOURCE-REF branch meeting the same problem:
+ * 414 anchors captured on one guide page resolve **identically** after a real
+ * navigation to another guide page — 161 placed, 253 ambiguous, 0 refused, the
+ * same three numbers on both — recorded with its method and denominator in
+ * `docs/decisions/a-275-anchor-placement.md` § *The limit this does not fix*.
+ * It is a different branch and a different number, cited here as evidence that
+ * the pattern-not-URL problem is real, not as a figure for this one.
+ *
+ * So a route anchor carries the RESOLVED path it was captured on, and
+ * `resolveAnchor` refuses when the document is somewhere else.
+ *
+ * ===========================================================================
+ * AND ABSENT MEANS "CANNOT PLACE", NEVER "PLACE ANYWAY"
+ * ===========================================================================
+ *
+ * `path` is optional because the field is newer than the wire, and the read-back
+ * plan's versioning rule for exactly this case is that a new anchor field is
+ * optional and **absent means cannot place** — the precedent `selection?:` set.
+ * A route anchor with no `path`, or a document that cannot say where it is,
+ * therefore resolves to `"none"`.
+ *
+ * That is a deliberate choice to under-place rather than mis-place, and it costs
+ * nothing today because no route anchor has ever been stored: markers have not
+ * shipped. It would be a real cost if this were retrofitted a year from now,
+ * which is the argument for doing it here.
+ *
+ * WHAT IT DOES NOT FIX: a SOURCE-REF anchor still resolves happily on a
+ * different `[id]` of the same route pattern — the markup is identical, so there
+ * is nothing for the chain to disagree with, and no amount of anchor design
+ * closes it. That one is the read endpoint's (A-276): scope the query on the
+ * resolved path, not on `route`. Stated here because an unstated limit gets read
+ * as a covered one.
+ */
+export interface RouteAnchor {
+    kind: "route";
+    /** `location.pathname` at capture time. Absent means the anchor cannot be placed. */
+    path?: string;
+}
+export type Anchor = SourceRefAnchor | DomPathAnchor | RouteAnchor;
+/**
+ * Where a marker goes, or why it does not go anywhere.
+ *
+ * Three outcomes and not two, because `"none"` and `"ambiguous"` are different
+ * facts about the page and a caller counting them together loses the one that
+ * says the markup moved.
+ */
+export type AnchorResolution<E extends ElementLike = ElementLike> = E | "none" | "ambiguous";
+/**
+ * The narrowest slice of `Document` this module reads. A real `Document`
+ * satisfies it, which `anchor.test.ts` asserts at compile time.
+ *
+ * `location` is here for the route branch above. It is optional because a parsed
+ * fixture has no location, and a document that cannot say where it is makes a
+ * route anchor unplaceable rather than placeable-by-default.
+ */
+export interface DocumentLike<E extends ElementLike = ElementLike> {
+    querySelectorAll(selectors: string): ArrayLike<E>;
+    body?: E | null;
+    location?: {
+        pathname: string;
+    } | null;
+}
+/**
+ * Resolve an anchor against a document.
+ *
+ * Pure: it reads the document and returns an element or a refusal, and it never
+ * mutates, measures layout, or draws anything. That is what lets the same
+ * function be a unit test over a checked-in HTML fixture, a number in a
+ * measurement run, and the marker layer's placement call.
+ *
+ * A `kind` this version does not recognise resolves to `"none"` — the read
+ * response is additive-only forever (A-276), so an SDK meeting a newer console
+ * must SKIP a marker it cannot place rather than guess at one.
+ */
+export declare function resolveAnchor<E extends ElementLike>(anchor: Anchor, doc: DocumentLike<E>): AnchorResolution<E>;
+export interface AnchorFromTargetOptions {
+    /** Document order index among leaf-matching candidates, when the caller has a document. */
+    ordinal?: number;
+    /**
+     * `location.pathname` at capture time — the RESOLVED path, not the route
+     * pattern.
+     *
+     * Pass it. A route anchor built without it can never be placed, by design; see
+     * `RouteAnchor`. It is optional here rather than required because
+     * `anchorFromTarget` is also called for element captures, where it is unused.
+     */
+    path?: string;
+}
+/**
+ * Build the anchor for a capture.
+ *
+ * The capture side of the same primitive, here rather than in `target.ts` so the
+ * union and the function that produces it cannot drift apart.
+ *
+ * **A region capture becomes a `route` anchor.** Its `sourceChain` is the
+ * siblings a rectangle crossed, which contain nothing of each other; handing
+ * that to `chainMatches` would compare a sibling list against an ancestor list
+ * and refuse — the right answer for the wrong reason, and one that would report
+ * every region capture as "the markup moved". Route-level is what a region
+ * capture actually means: something on this page, in that area.
+ */
+export declare function anchorFromTarget(target: Pick<TargetInfo, "selection" | "source" | "sourceChain" | "domPath">, options?: AnchorFromTargetOptions): Anchor;
+/**
+ * The counts a caller reports, so that "0 markers" is never the same string as
+ * "working, nothing here" (rule 1 of the read-back plan).
+ *
+ * ===========================================================================
+ * `wrong` IS NOT IN HERE AND CANNOT BE, AND THAT IS A GAP RATHER THAN A DESIGN
+ * ===========================================================================
+ *
+ * Whether a resolved element is the RIGHT element is not knowable from the live
+ * page alone — it takes a before/after comparison, which is what A-275's
+ * mutation battery does and what no runtime caller can do.
+ *
+ * So `placed` means "resolved to exactly one element", NOT "resolved
+ * correctly", and there is one measured channel where those differ: a
+ * source-ref anchor captured on one `[id]` resolves on another `[id]` of the
+ * same route pattern, because the two pages are structurally identical.
+ *
+ * MEASURED at **161 of 414 anchors** placing on a different `[id]` of the same
+ * route pattern, with zero refusals — indistinguishable, count for count, from
+ * resolving against the page they were captured on. The method, the denominator
+ * and the pages are in `docs/decisions/a-275-anchor-placement.md` § *The limit
+ * this does not fix*, and `node anchor-measure.mjs --url … --compare-url …`
+ * re-runs it in one command. Nothing in this module can detect it; the
+ * fix is for the read endpoint to scope on the resolved path (A-276), so a
+ * caller must not read `placed` as a correctness figure until it does.
+ *
+ * The route branch closes its own half of that (`RouteAnchor.path`). This
+ * comment is the record that the source-ref half is still open.
+ */
+export interface AnchorTally {
+    total: number;
+    placed: number;
+    ambiguous: number;
+    unresolved: number;
+}
+export declare function tallyAnchors<E extends ElementLike>(anchors: readonly Anchor[], doc: DocumentLike<E>): AnchorTally;

package/dist/anchor.mjs

@@ -0,0 +1,2 @@
+var u="data-src";function p(e){return e.selection==="region"?"region":"element"}var f=8;function s(e){if(!e)return null;let n=e.lastIndexOf(":");if(n<=0)return null;let t=e.lastIndexOf(":",n-1);if(t<=0)return null;let o=e.slice(0,t),r=Number(e.slice(t+1,n)),i=Number(e.slice(n+1));return!o||!Number.isFinite(r)||!Number.isFinite(i)?null:{file:o,line:r,column:i}}function g(e,n=f){let t=[],o=e;for(;o&&t.length<n;){let r=s(o.getAttribute(u));if(r){let i=t[t.length-1];i&&i.file===r.file&&i.line===r.line||t.push(r)}o=o.parentElement}return t}function d(e){let n=e;for(;n;){if(s(n.getAttribute(u)))return n;n=n.parentElement}return null}function l(e,n){return e.file!==n.file||e.line!==n.line?!1:e.column===void 0||n.column===void 0?!0:e.column===n.column}function h(e,n){if(e.length===0)return!1;if(e.length<f){if(n.length!==e.length)return!1}else if(n.length<e.length)return!1;return e.every((t,o)=>{let r=n[o];return r!==void 0&&l(t,r)})}function A(e,n){let t={file:e.file,line:e.line};e.column!==void 0&&(t.column=e.column);let o=n.querySelectorAll(`[${u}]`),r=[];for(let i=0;i<o.length;i++){let a=o[i],c=s(a.getAttribute(u));if(!c||!l(t,c))continue;let m=s(d(a.parentElement)?.getAttribute(u)??null);m&&l(m,c)||r.push(a)}return r}function x(e,n){switch(e.kind){case"route":{if(!e.path)return"none";let t=n.location?.pathname;return!t||t!==e.path?"none":n.body??"none"}case"dom-path":{if(!e.path)return"none";let t;try{t=n.querySelectorAll(e.path)}catch{return"none"}return t.length===0?"none":t.length>1?"ambiguous":t[0]}case"source-ref":{if(e.chain.length===0)return"none";let t=A(e,n).filter(o=>h(e.chain,g(o)));return t.length===0?"none":t.length>1?"ambiguous":t[0]}default:return"none"}}function N(e,n={}){let t=()=>n.path===void 0?{kind:"route"}:{kind:"route",path:n.path};if(p(e)==="region")return t();let o=e.sourceChain??[],r=o[0],i=e.source??r;if(i&&r&&l(i,r)){let a={kind:"source-ref",file:i.file,line:i.line,chain:o};return i.column!==void 0&&(a.column=i.column),n.ordinal!==void 0&&(a.ordinal=n.ordinal),a}return e.domPath?{kind:"dom-path",path:e.domPath}:t()}function S(e,n){let t={total:e.length,placed:0,ambiguous:0,unresolved:0};for(let o of e){let r=x(o,n);r==="ambiguous"?t.ambiguous+=1:r==="none"?t.unresolved+=1:t.placed+=1}return t}export{N as anchorFromTarget,x as resolveAnchor,S as tallyAnchors};
+//# sourceMappingURL=anchor.mjs.map