@weatherboard/annotation 0.2.2 → 0.4.0

package/dist/markers.d.mts

@@ -0,0 +1,283 @@
+import { resolveAnchor } from "./anchor.mjs";
+import type { AnnotationMarker, AnnotationReader } from "./read.mjs";
+/**
+ * Markers on the components a reviewer annotated, and the panel behind them
+ * (A-277).
+ *
+ * ===========================================================================
+ * WHY THIS IS A SIXTH ENTRY POINT AND NOT PART OF `.`
+ * ===========================================================================
+ *
+ * `./anchor` and `./read` both make the same argument and it applies here with
+ * the most weight: this runs only in a product that RENDERS markers, and the SDK
+ * that only captures does not need a byte of it. Folding it into `index` would
+ * put the marker layer, the panel and its stylesheet into the bundle of every
+ * page of every managed product, including the ones that will never show one.
+ *
+ * ===========================================================================
+ * THE COUNT LINE IS THE FEATURE. THE ICONS ARE THE GARNISH.
+ * ===========================================================================
+ *
+ * On a read path **zero markers is exactly what "working, nothing here" looks
+ * like**, and the runbook lists twelve distinct causes that produce it. So an
+ * armed page ALWAYS renders the line, before and after the read, whatever the
+ * answer — *"3 annotations here, 1 shown"* — and that is not a status indicator,
+ * it is the only thing that makes an anchor which cannot place VISIBLE rather
+ * than silent.
+ *
+ * The sentence is built from the PAGE's own tally, with the envelope's `total`
+ * as the denominator. It is deliberately not built from the envelope's
+ * `anchored`: the server has no DOM and cannot know whether a marker lands, and
+ * two numbers called "placed" meaning different things is the shape this
+ * repository keeps getting burned by. `anchored` is a diagnostic for the
+ * runbook — it separates *the console has nothing for this page* from *the
+ * console has three and your DOM matched none of them* — and it is exposed on
+ * `MarkerRender` rather than rendered as though it were the page's answer.
+ *
+ * ===========================================================================
+ * MOST MARKERS ON A LIST PAGE ARE ROUTE-LEVEL, AND THAT IS A DESIGNED STATE
+ * ===========================================================================
+ *
+ * MEASURED by A-275 against live staging pages: on a listing page only about
+ * **25%** of annotated elements resolve uniquely, and about 75% are ambiguous
+ * identical siblings. That is not a defect to be worked around — a source ref
+ * names a COMPONENT, and two identical cards are genuinely indistinguishable
+ * from one. Wrong-placement was **0** across every mutation tested, and it is
+ * zero because the resolver refuses rather than guesses.
+ *
+ * So this layer is built for the refusing case rather than treating it as
+ * degraded:
+ *
+ * - an `"ambiguous"` anchor NEVER gets a marker. A marker on the wrong element
+ *   does not degrade this feature, it inverts it.
+ * - markers that resolve to the SAME element are drawn as one icon carrying a
+ *   count, and the panel lists all of them. Without that, a route anchor — the
+ *   honest home for a region capture and for any page with no source refs —
+ *   would stack every marker on the page at one point, and three captures would
+ *   render as one icon with two hidden underneath it.
+ * - a route anchor resolves to `document.body`, so its cluster sits in the
+ *   page's own top-right corner and reads as *"about this page"*. That is what
+ *   the anchor means.
+ *
+ * ===========================================================================
+ * IT NEVER RE-RESOLVES SOMETHING IT DID NOT READ FROM THE CONSOLE
+ * ===========================================================================
+ *
+ * `resolveAnchor` is IMPORTED from `./anchor` and nothing here reimplements any
+ * part of it. That is A-275's whole point: the function that measured the scheme
+ * and the function that places the markers must be one function, or the
+ * measurement is about code nobody runs.
+ *
+ * ===========================================================================
+ * THIS RUNS INSIDE SOMEBODY ELSE'S PRODUCTION SITE
+ * ===========================================================================
+ *
+ * Everything rendered here came off the network. `read.ts` sanitises it — bounded
+ * strings, control characters dropped, a marker that cannot be read skipped — and
+ * this file adds the second half of that guarantee: every value reaches the DOM
+ * through `textContent` and never through `innerHTML`, so a console that has been
+ * compromised or has merely gone wrong cannot put markup into a customer's page.
+ * There is no `href` anywhere in this layer, which is why `safeIssueUrl` has no
+ * caller here.
+ *
+ * The whole layer lives in a shadow root, so the product's stylesheet cannot
+ * reach in and this cannot reach out.
+ */
+/** The layer's host node. Namespaced, and never product-named (A-98). */
+export declare const MARKERS_ID = "ai-annotation-markers";
+export interface AnnotationMarkerLabels {
+    /** The region the whole layer announces itself as. */
+    region: string;
+    /**
+     * Built with the three counts: `(total, shown, resolvedHidden) => string`.
+     *
+     * `resolvedHidden` is a third argument rather than a separate line because a
+     * count in one place and a caveat in another is how a reader concludes the
+     * first number was the whole answer. A consumer overriding this with a
+     * two-parameter function still typechecks and still gets the first two
+     * numbers — but it will not say what is being held back, which is the one
+     * thing this argument exists for.
+     */
+    count: (total: number, shown: number, resolvedHidden: number) => string;
+    /**
+     * The control that widens the read, and the label it carries in each state.
+     *
+     * A count with no way to act on it is a fact a reviewer can do nothing with;
+     * a control with no count is one nobody knows to press. Both, or neither.
+     */
+    showResolved: (resolvedHidden: number) => string;
+    hideResolved: string;
+    /** Shown before the first read completes. */
+    loading: string;
+    /** The console answered and refused. `reason` is the envelope's, or empty. */
+    refused: (reason: string) => string;
+    /** The read did not complete at all — no status, no body. */
+    unreachable: string;
+    /** No read token, so nothing was even attempted. */
+    noCredential: string;
+    /** Freshness, from `asOf`. */
+    asOf: (age: string) => string;
+    freshnessUnknown: string;
+    close: string;
+}
+export declare const DEFAULT_MARKER_LABELS: AnnotationMarkerLabels;
+export interface AnnotationMarkersOptions {
+    /**
+     * The read client, from `createAnnotationReader`. Required: a marker layer
+     * with no way to read is a layer that renders an empty page confidently.
+     */
+    reader: AnnotationReader | null;
+    /**
+     * May this page render markers at all?
+     *
+     * `false` renders NOTHING — no host node, no shadow root, no stylesheet —
+     * exactly as `createAnnotationToolbar` does, and for the same reason: an
+     * unarmed page that shipped this code must leave no residue in a customer's
+     * DOM. Every method still answers, so a caller does not have to branch.
+     */
+    armed?: boolean;
+    doc?: Document;
+    win?: Window;
+    /**
+     * The path to ask about. Defaults to `location.pathname`.
+     *
+     * The RESOLVED path and never the route pattern. A pattern is one value for
+     * every page of a dynamic route, so asking by pattern returns another page's
+     * captures — measured at 161 of 414 anchors placing confidently on the wrong
+     * `[slug]`, with zero refusals, in `docs/decisions/a-275-anchor-placement.md`.
+     */
+    path?: string;
+    labels?: Partial<AnnotationMarkerLabels>;
+    /**
+     * Start with the resolved captures showing (A-288/A-323). Defaults to `false`.
+     *
+     * The default matches the console's, deliberately: a layer that asked for
+     * everything on every page would put the default back where A-288 decided it
+     * should not be, from the other side of the wire, and nobody would see it in
+     * the console's code.
+     */
+    showResolved?: boolean;
+    /** For the age in the freshness line. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** What one render actually put on the page. Returned so a caller can assert on it. */
+export interface MarkerRender {
+    /** The envelope's `total` — what the console holds for this path. */
+    total: number;
+    /** Markers whose anchor resolved to exactly one element, and were drawn. */
+    shown: number;
+    /** Anchors that resolved to more than one element. NEVER drawn. */
+    ambiguous: number;
+    /** Anchors that matched nothing in this document. */
+    unresolved: number;
+    /**
+     * The CONSOLE's count of anchors it could serve as placeable at all.
+     *
+     * Carried through for the runbook's checklist and deliberately NOT rendered as
+     * though it were `shown`. See this file's header.
+     */
+    anchored: number;
+    /**
+     * The envelope's `resolvedHidden` — finished captures the console held back.
+     *
+     * Zero while `showingResolved` is true, because nothing is then being held
+     * back. That is the console's number and not an inference: a layer that
+     * remembered the previous read's figure would keep reporting it after the
+     * capture had been archived.
+     */
+    resolvedHidden: number;
+    /** Whether this render asked for `?resolved=include`. */
+    showingResolved: boolean;
+    /** Distinct elements drawn on. Lower than `shown` wherever markers clustered. */
+    clusters: number;
+    /** The envelope's `asOf` — the console's Linear cursor, or `""`. */
+    asOf: string;
+    /** The line a human reads. Exactly the text in the DOM. */
+    line: string;
+}
+export interface AnnotationMarkers {
+    /** Read, resolve, draw. Never rejects: a failure is a rendered sentence. */
+    refresh(): Promise<MarkerRender>;
+    /** Is this node ours? For an SDK that must not capture its own furniture. */
+    owns(node: unknown): boolean;
+    /** The last render, or null before the first. */
+    last(): MarkerRender | null;
+    destroy(): void;
+}
+export interface Spot {
+    left: number;
+    top: number;
+}
+/**
+ * A position for this pin that no already-placed pin occupies — or, when there
+ * is none, the ideal one, OVERLAPPING.
+ *
+ * ===========================================================================
+ * IT GIVES UP. THAT IS THE WHOLE POINT OF THIS FUNCTION EXISTING.
+ * ===========================================================================
+ *
+ * This was a bare `while` loop with no exit but success, and it could not
+ * terminate. Once `left` floored at `MARGIN` the wrap computed
+ * `Math.max(MARGIN, MARGIN - STEP) === MARGIN` and `top = MARGIN`, so the search
+ * returned to a position it had already rejected and tried it again, forever.
+ *
+ * REPRODUCED, not reasoned about: two clusters on two distinct elements with
+ * `innerWidth` and `innerHeight` both 0 — `refresh()` never returned, killed at
+ * 20s. `position()` is called by `draw()` and by every `scroll` and `resize`
+ * listener, so that is **a locked main thread inside a customer's production
+ * page**, which is strictly worse than the thrown read `refresh()` refuses to
+ * allow.
+ *
+ * A zero-sized viewport is not exotic: a hidden iframe, a prerender, a host that
+ * stubs `win`. Two pins are then enough. A short embedded viewport reaches it
+ * honestly too — 300×200 offers about 77 slots against a possible 100 pins.
+ *
+ * And the irony is the useful part. `linkedom` returns zeros for every rect,
+ * which is exactly why the clamp above had to be found in a browser — and it is
+ * exactly why no fixture test saw this. **The zero-rect case is a layout hazard
+ * AND a termination hazard, and the first fix addressed only the layout.**
+ *
+ * So the walk is bounded twice over: `MAX_PROBES`, and a `left` that has run out
+ * of columns. When it gives up, the pin goes at its clamped ideal and is allowed
+ * to sit on top of another. **An overlapping marker is a visible imperfection; a
+ * locked main thread is the product broken.**
+ *
+ * Exported so `markers.test.ts` can assert termination directly, under
+ * `linkedom`, with no browser: only the QUALITY of the placement needs one.
+ */
+export declare function freeSpot(ideal: Spot, taken: readonly Spot[], maxTop: number): Spot;
+/**
+ * A duration a human reads. Two units at most, mirroring `fleet/freshness.ts` —
+ * the point of the line is "is this minutes or hours", and the seconds in
+ * "2h 10m 4s" are noise that makes the answer take longer to find.
+ *
+ * Reimplemented rather than imported because that module is server-side and this
+ * package must not depend on the console. It is eleven lines of arithmetic with
+ * a test on it, which is the honest version of that trade.
+ */
+export declare function formatMarkerAge(ms: number): string;
+/**
+ * Group markers by the element each one resolves to, refusing the ambiguous.
+ *
+ * Exported and pure so the placement rule is testable over a parsed fixture
+ * without a browser — the same split `anchor.test.ts` uses, and the reason this
+ * layer's most important behaviour (`ambiguous` is never drawn) is covered by
+ * `pnpm verify` rather than only by a browser nobody schedules.
+ */
+export declare function placeMarkers(markers: readonly AnnotationMarker[], doc: Parameters<typeof resolveAnchor>[1]): {
+    clusters: {
+        element: unknown;
+        markers: AnnotationMarker[];
+    }[];
+    ambiguous: number;
+    unresolved: number;
+};
+/**
+ * Mount the marker layer.
+ *
+ * Does not read anything until `refresh()` is called, so a caller decides when
+ * the page is settled enough to measure. The count line renders `loading`
+ * immediately, because an armed page with nothing on it at all is the state this
+ * whole layer exists to make impossible.
+ */
+export declare function mountAnnotationMarkers(options: AnnotationMarkersOptions): AnnotationMarkers;

package/dist/markers.d.ts

@@ -0,0 +1,283 @@
+import { resolveAnchor } from "./anchor.js";
+import type { AnnotationMarker, AnnotationReader } from "./read.js";
+/**
+ * Markers on the components a reviewer annotated, and the panel behind them
+ * (A-277).
+ *
+ * ===========================================================================
+ * WHY THIS IS A SIXTH ENTRY POINT AND NOT PART OF `.`
+ * ===========================================================================
+ *
+ * `./anchor` and `./read` both make the same argument and it applies here with
+ * the most weight: this runs only in a product that RENDERS markers, and the SDK
+ * that only captures does not need a byte of it. Folding it into `index` would
+ * put the marker layer, the panel and its stylesheet into the bundle of every
+ * page of every managed product, including the ones that will never show one.
+ *
+ * ===========================================================================
+ * THE COUNT LINE IS THE FEATURE. THE ICONS ARE THE GARNISH.
+ * ===========================================================================
+ *
+ * On a read path **zero markers is exactly what "working, nothing here" looks
+ * like**, and the runbook lists twelve distinct causes that produce it. So an
+ * armed page ALWAYS renders the line, before and after the read, whatever the
+ * answer — *"3 annotations here, 1 shown"* — and that is not a status indicator,
+ * it is the only thing that makes an anchor which cannot place VISIBLE rather
+ * than silent.
+ *
+ * The sentence is built from the PAGE's own tally, with the envelope's `total`
+ * as the denominator. It is deliberately not built from the envelope's
+ * `anchored`: the server has no DOM and cannot know whether a marker lands, and
+ * two numbers called "placed" meaning different things is the shape this
+ * repository keeps getting burned by. `anchored` is a diagnostic for the
+ * runbook — it separates *the console has nothing for this page* from *the
+ * console has three and your DOM matched none of them* — and it is exposed on
+ * `MarkerRender` rather than rendered as though it were the page's answer.
+ *
+ * ===========================================================================
+ * MOST MARKERS ON A LIST PAGE ARE ROUTE-LEVEL, AND THAT IS A DESIGNED STATE
+ * ===========================================================================
+ *
+ * MEASURED by A-275 against live staging pages: on a listing page only about
+ * **25%** of annotated elements resolve uniquely, and about 75% are ambiguous
+ * identical siblings. That is not a defect to be worked around — a source ref
+ * names a COMPONENT, and two identical cards are genuinely indistinguishable
+ * from one. Wrong-placement was **0** across every mutation tested, and it is
+ * zero because the resolver refuses rather than guesses.
+ *
+ * So this layer is built for the refusing case rather than treating it as
+ * degraded:
+ *
+ * - an `"ambiguous"` anchor NEVER gets a marker. A marker on the wrong element
+ *   does not degrade this feature, it inverts it.
+ * - markers that resolve to the SAME element are drawn as one icon carrying a
+ *   count, and the panel lists all of them. Without that, a route anchor — the
+ *   honest home for a region capture and for any page with no source refs —
+ *   would stack every marker on the page at one point, and three captures would
+ *   render as one icon with two hidden underneath it.
+ * - a route anchor resolves to `document.body`, so its cluster sits in the
+ *   page's own top-right corner and reads as *"about this page"*. That is what
+ *   the anchor means.
+ *
+ * ===========================================================================
+ * IT NEVER RE-RESOLVES SOMETHING IT DID NOT READ FROM THE CONSOLE
+ * ===========================================================================
+ *
+ * `resolveAnchor` is IMPORTED from `./anchor` and nothing here reimplements any
+ * part of it. That is A-275's whole point: the function that measured the scheme
+ * and the function that places the markers must be one function, or the
+ * measurement is about code nobody runs.
+ *
+ * ===========================================================================
+ * THIS RUNS INSIDE SOMEBODY ELSE'S PRODUCTION SITE
+ * ===========================================================================
+ *
+ * Everything rendered here came off the network. `read.ts` sanitises it — bounded
+ * strings, control characters dropped, a marker that cannot be read skipped — and
+ * this file adds the second half of that guarantee: every value reaches the DOM
+ * through `textContent` and never through `innerHTML`, so a console that has been
+ * compromised or has merely gone wrong cannot put markup into a customer's page.
+ * There is no `href` anywhere in this layer, which is why `safeIssueUrl` has no
+ * caller here.
+ *
+ * The whole layer lives in a shadow root, so the product's stylesheet cannot
+ * reach in and this cannot reach out.
+ */
+/** The layer's host node. Namespaced, and never product-named (A-98). */
+export declare const MARKERS_ID = "ai-annotation-markers";
+export interface AnnotationMarkerLabels {
+    /** The region the whole layer announces itself as. */
+    region: string;
+    /**
+     * Built with the three counts: `(total, shown, resolvedHidden) => string`.
+     *
+     * `resolvedHidden` is a third argument rather than a separate line because a
+     * count in one place and a caveat in another is how a reader concludes the
+     * first number was the whole answer. A consumer overriding this with a
+     * two-parameter function still typechecks and still gets the first two
+     * numbers — but it will not say what is being held back, which is the one
+     * thing this argument exists for.
+     */
+    count: (total: number, shown: number, resolvedHidden: number) => string;
+    /**
+     * The control that widens the read, and the label it carries in each state.
+     *
+     * A count with no way to act on it is a fact a reviewer can do nothing with;
+     * a control with no count is one nobody knows to press. Both, or neither.
+     */
+    showResolved: (resolvedHidden: number) => string;
+    hideResolved: string;
+    /** Shown before the first read completes. */
+    loading: string;
+    /** The console answered and refused. `reason` is the envelope's, or empty. */
+    refused: (reason: string) => string;
+    /** The read did not complete at all — no status, no body. */
+    unreachable: string;
+    /** No read token, so nothing was even attempted. */
+    noCredential: string;
+    /** Freshness, from `asOf`. */
+    asOf: (age: string) => string;
+    freshnessUnknown: string;
+    close: string;
+}
+export declare const DEFAULT_MARKER_LABELS: AnnotationMarkerLabels;
+export interface AnnotationMarkersOptions {
+    /**
+     * The read client, from `createAnnotationReader`. Required: a marker layer
+     * with no way to read is a layer that renders an empty page confidently.
+     */
+    reader: AnnotationReader | null;
+    /**
+     * May this page render markers at all?
+     *
+     * `false` renders NOTHING — no host node, no shadow root, no stylesheet —
+     * exactly as `createAnnotationToolbar` does, and for the same reason: an
+     * unarmed page that shipped this code must leave no residue in a customer's
+     * DOM. Every method still answers, so a caller does not have to branch.
+     */
+    armed?: boolean;
+    doc?: Document;
+    win?: Window;
+    /**
+     * The path to ask about. Defaults to `location.pathname`.
+     *
+     * The RESOLVED path and never the route pattern. A pattern is one value for
+     * every page of a dynamic route, so asking by pattern returns another page's
+     * captures — measured at 161 of 414 anchors placing confidently on the wrong
+     * `[slug]`, with zero refusals, in `docs/decisions/a-275-anchor-placement.md`.
+     */
+    path?: string;
+    labels?: Partial<AnnotationMarkerLabels>;
+    /**
+     * Start with the resolved captures showing (A-288/A-323). Defaults to `false`.
+     *
+     * The default matches the console's, deliberately: a layer that asked for
+     * everything on every page would put the default back where A-288 decided it
+     * should not be, from the other side of the wire, and nobody would see it in
+     * the console's code.
+     */
+    showResolved?: boolean;
+    /** For the age in the freshness line. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** What one render actually put on the page. Returned so a caller can assert on it. */
+export interface MarkerRender {
+    /** The envelope's `total` — what the console holds for this path. */
+    total: number;
+    /** Markers whose anchor resolved to exactly one element, and were drawn. */
+    shown: number;
+    /** Anchors that resolved to more than one element. NEVER drawn. */
+    ambiguous: number;
+    /** Anchors that matched nothing in this document. */
+    unresolved: number;
+    /**
+     * The CONSOLE's count of anchors it could serve as placeable at all.
+     *
+     * Carried through for the runbook's checklist and deliberately NOT rendered as
+     * though it were `shown`. See this file's header.
+     */
+    anchored: number;
+    /**
+     * The envelope's `resolvedHidden` — finished captures the console held back.
+     *
+     * Zero while `showingResolved` is true, because nothing is then being held
+     * back. That is the console's number and not an inference: a layer that
+     * remembered the previous read's figure would keep reporting it after the
+     * capture had been archived.
+     */
+    resolvedHidden: number;
+    /** Whether this render asked for `?resolved=include`. */
+    showingResolved: boolean;
+    /** Distinct elements drawn on. Lower than `shown` wherever markers clustered. */
+    clusters: number;
+    /** The envelope's `asOf` — the console's Linear cursor, or `""`. */
+    asOf: string;
+    /** The line a human reads. Exactly the text in the DOM. */
+    line: string;
+}
+export interface AnnotationMarkers {
+    /** Read, resolve, draw. Never rejects: a failure is a rendered sentence. */
+    refresh(): Promise<MarkerRender>;
+    /** Is this node ours? For an SDK that must not capture its own furniture. */
+    owns(node: unknown): boolean;
+    /** The last render, or null before the first. */
+    last(): MarkerRender | null;
+    destroy(): void;
+}
+export interface Spot {
+    left: number;
+    top: number;
+}
+/**
+ * A position for this pin that no already-placed pin occupies — or, when there
+ * is none, the ideal one, OVERLAPPING.
+ *
+ * ===========================================================================
+ * IT GIVES UP. THAT IS THE WHOLE POINT OF THIS FUNCTION EXISTING.
+ * ===========================================================================
+ *
+ * This was a bare `while` loop with no exit but success, and it could not
+ * terminate. Once `left` floored at `MARGIN` the wrap computed
+ * `Math.max(MARGIN, MARGIN - STEP) === MARGIN` and `top = MARGIN`, so the search
+ * returned to a position it had already rejected and tried it again, forever.
+ *
+ * REPRODUCED, not reasoned about: two clusters on two distinct elements with
+ * `innerWidth` and `innerHeight` both 0 — `refresh()` never returned, killed at
+ * 20s. `position()` is called by `draw()` and by every `scroll` and `resize`
+ * listener, so that is **a locked main thread inside a customer's production
+ * page**, which is strictly worse than the thrown read `refresh()` refuses to
+ * allow.
+ *
+ * A zero-sized viewport is not exotic: a hidden iframe, a prerender, a host that
+ * stubs `win`. Two pins are then enough. A short embedded viewport reaches it
+ * honestly too — 300×200 offers about 77 slots against a possible 100 pins.
+ *
+ * And the irony is the useful part. `linkedom` returns zeros for every rect,
+ * which is exactly why the clamp above had to be found in a browser — and it is
+ * exactly why no fixture test saw this. **The zero-rect case is a layout hazard
+ * AND a termination hazard, and the first fix addressed only the layout.**
+ *
+ * So the walk is bounded twice over: `MAX_PROBES`, and a `left` that has run out
+ * of columns. When it gives up, the pin goes at its clamped ideal and is allowed
+ * to sit on top of another. **An overlapping marker is a visible imperfection; a
+ * locked main thread is the product broken.**
+ *
+ * Exported so `markers.test.ts` can assert termination directly, under
+ * `linkedom`, with no browser: only the QUALITY of the placement needs one.
+ */
+export declare function freeSpot(ideal: Spot, taken: readonly Spot[], maxTop: number): Spot;
+/**
+ * A duration a human reads. Two units at most, mirroring `fleet/freshness.ts` —
+ * the point of the line is "is this minutes or hours", and the seconds in
+ * "2h 10m 4s" are noise that makes the answer take longer to find.
+ *
+ * Reimplemented rather than imported because that module is server-side and this
+ * package must not depend on the console. It is eleven lines of arithmetic with
+ * a test on it, which is the honest version of that trade.
+ */
+export declare function formatMarkerAge(ms: number): string;
+/**
+ * Group markers by the element each one resolves to, refusing the ambiguous.
+ *
+ * Exported and pure so the placement rule is testable over a parsed fixture
+ * without a browser — the same split `anchor.test.ts` uses, and the reason this
+ * layer's most important behaviour (`ambiguous` is never drawn) is covered by
+ * `pnpm verify` rather than only by a browser nobody schedules.
+ */
+export declare function placeMarkers(markers: readonly AnnotationMarker[], doc: Parameters<typeof resolveAnchor>[1]): {
+    clusters: {
+        element: unknown;
+        markers: AnnotationMarker[];
+    }[];
+    ambiguous: number;
+    unresolved: number;
+};
+/**
+ * Mount the marker layer.
+ *
+ * Does not read anything until `refresh()` is called, so a caller decides when
+ * the page is settled enough to measure. The count line renders `loading`
+ * immediately, because an armed page with nothing on it at all is the state this
+ * whole layer exists to make impossible.
+ */
+export declare function mountAnnotationMarkers(options: AnnotationMarkersOptions): AnnotationMarkers;

package/dist/markers.mjs

@@ -0,0 +1,64 @@
+var C="data-src";var B=8;function S(e){if(!e)return null;let t=e.lastIndexOf(":");if(t<=0)return null;let n=e.lastIndexOf(":",t-1);if(n<=0)return null;let r=e.slice(0,n),o=Number(e.slice(n+1,t)),i=Number(e.slice(t+1));return!r||!Number.isFinite(o)||!Number.isFinite(i)?null:{file:r,line:o,column:i}}function j(e,t=B){let n=[],r=e;for(;r&&n.length<t;){let o=S(r.getAttribute(C));if(o){let i=n[n.length-1];i&&i.file===o.file&&i.line===o.line||n.push(o)}r=r.parentElement}return n}function q(e){let t=e;for(;t;){if(S(t.getAttribute(C)))return t;t=t.parentElement}return null}function H(e,t){return e.file!==t.file||e.line!==t.line?!1:e.column===void 0||t.column===void 0?!0:e.column===t.column}function J(e,t){if(e.length===0)return!1;if(e.length<B){if(t.length!==e.length)return!1}else if(t.length<e.length)return!1;return e.every((n,r)=>{let o=t[r];return o!==void 0&&H(n,o)})}function Z(e,t){let n={file:e.file,line:e.line};e.column!==void 0&&(n.column=e.column);let r=t.querySelectorAll(`[${C}]`),o=[];for(let i=0;i<r.length;i++){let s=r[i],c=S(s.getAttribute(C));if(!c||!H(n,c))continue;let d=S(q(s.parentElement)?.getAttribute(C)??null);d&&H(d,c)||o.push(s)}return o}function V(e,t){switch(e.kind){case"route":{if(!e.path)return"none";let n=t.location?.pathname;return!n||n!==e.path?"none":t.body??"none"}case"dom-path":{if(!e.path)return"none";let n;try{n=t.querySelectorAll(e.path)}catch{return"none"}return n.length===0?"none":n.length>1?"ambiguous":n[0]}case"source-ref":{if(e.chain.length===0)return"none";let n=Z(e,t).filter(r=>J(e.chain,j(r)));return n.length===0?"none":n.length>1?"ambiguous":n[0]}default:return"none"}}var X="ai-annotation-markers",Q="2147483002",ee={region:"Annotations on this page",count:(e,t,n)=>{let r=e===0?"No annotations on this page":`${e} annotation${e===1?"":"s"} here, ${t} shown`;return n>0?`${r} \xB7 ${n} resolved`:r},showResolved:e=>`Show ${e} resolved annotation${e===1?"":"s"}`,hideResolved:"Hide resolved annotations",loading:"Looking for annotations\u2026",refused:e=>e==="retired-link"?"This annotation link is an older format the console no longer accepts. Open Request changes again.":e==="rate-limited"?"The console is rate-limiting this page's reads. Wait a moment.":"The console refused this page's read.",unreachable:"Could not reach the console for this page's annotations.",noCredential:"No read credential, so annotations were not requested.",asOf:e=>`status as of ${e} ago`,freshnessUnknown:"the console cannot say how fresh these statuses are",close:"Close"},K={total:0,shown:0,ambiguous:0,unresolved:0,anchored:0,resolvedHidden:0,showingResolved:!1,clusters:0,asOf:"",line:""},ne=`
+:host{
+ --ai-bg:#fff;
+ --ai-fg:#18181b;
+ --ai-line:#d4d4d8;
+ --ai-line-soft:#e4e4e7;
+ --ai-muted:#52525b;
+ --ai-accent:#2563eb;
+ --ai-accent-line:#1d4ed8;
+ --ai-invert-bg:#18181b;
+ --ai-invert-fg:#fafafa;
+ --ai-space-1:4px;
+ --ai-space-2:6px;
+ --ai-space-3:8px;
+ --ai-space-4:10px;
+ --ai-space-5:12px;
+ --ai-radius-control:6px;
+ --ai-radius-card:8px;
+ --ai-radius-pill:999px;
+ --ai-pin:22px;
+ --ai-edge:16px;
+ all:initial;position:fixed;inset:0;z-index:${Q};pointer-events:none;
+ font:13px/1.45 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+ color:var(--ai-fg);color-scheme:light}
+*,*::before,*::after{box-sizing:border-box}
+[hidden]{display:none!important}
+.count{
+ position:absolute;left:var(--ai-edge);bottom:var(--ai-edge);pointer-events:auto;
+ background:var(--ai-invert-bg);color:var(--ai-invert-fg);
+ border-radius:var(--ai-radius-pill);
+ padding:var(--ai-space-2) var(--ai-space-5);max-width:min(60vw,420px);
+ display:flex;align-items:center;gap:var(--ai-space-3);flex-wrap:wrap}
+.toggle{
+ pointer-events:auto;font:inherit;font-size:12px;white-space:nowrap;
+ background:var(--ai-invert-bg);color:var(--ai-invert-fg);
+ border:1px solid var(--ai-invert-fg);border-radius:var(--ai-radius-pill);
+ padding:0 var(--ai-space-3);cursor:pointer}
+.toggle:focus-visible{outline:2px solid var(--ai-invert-fg);outline-offset:2px}
+.pin{
+ position:absolute;pointer-events:auto;
+ width:var(--ai-pin);height:var(--ai-pin);
+ display:flex;align-items:center;justify-content:center;
+ border:1px solid var(--ai-accent-line);border-radius:var(--ai-radius-pill);
+ background:var(--ai-accent);color:var(--ai-invert-fg);
+ font:600 11px/1 ui-sans-serif,system-ui,sans-serif;cursor:pointer;padding:0}
+.pin:focus-visible{outline:2px solid var(--ai-fg);outline-offset:2px}
+.panel{
+ position:absolute;pointer-events:auto;width:min(320px,80vw);
+ background:var(--ai-bg);border:1px solid var(--ai-line);
+ border-radius:var(--ai-radius-card);padding:var(--ai-space-5);
+ max-height:50vh;overflow:auto}
+.entry+.entry{margin-top:var(--ai-space-5);border-top:1px solid var(--ai-line-soft);
+ padding-top:var(--ai-space-5)}
+.who{color:var(--ai-muted);font-size:12px;margin:0 0 var(--ai-space-1)}
+.what{margin:0 0 var(--ai-space-2);white-space:pre-wrap;overflow-wrap:anywhere}
+.state{margin:0;font-size:12px;color:var(--ai-muted)}
+.fresh{margin:var(--ai-space-2) 0 0;font-size:11px;color:var(--ai-muted)}
+.close{
+ pointer-events:auto;margin-top:var(--ai-space-4);font:inherit;
+ background:var(--ai-bg);color:var(--ai-fg);border:1px solid var(--ai-line);
+ border-radius:var(--ai-radius-control);
+ padding:var(--ai-space-1) var(--ai-space-4);cursor:pointer}
+`,T=22,v=4,W=(e,t,n)=>Math.min(Math.max(e,t),n),G=T+2,te=128;function re(e,t,n){let{left:r,top:o}=e,i=(s,c)=>t.some(d=>Math.abs(d.left-s)<T&&Math.abs(d.top-c)<T);for(let s=0;s<te;s+=1){if(!i(r,o))return{left:r,top:o};if(o+=G,o>n&&(o=v,r-=G,r<v))break}return{left:e.left,top:e.top}}function u(e,t,n){let r=e.createElement(t);if(n)for(let o of Object.keys(n))r.setAttribute(o,n[o]??"");return r}function oe(e){let t=Math.max(0,Math.floor(e/1e3));if(t<60)return`${t}s`;let n=Math.floor(t/60);if(n<60)return`${n}m`;let r=Math.floor(n/60);if(r<24){let s=n%60;return s===0?`${r}h`:`${r}h ${s}m`}let o=Math.floor(r/24),i=r%24;return i===0?`${o}d`:`${o}d ${i}h`}function ae(e,t){let n=new Map,r=0,o=0;for(let i of e){let s=V(i.anchor,t);if(s==="ambiguous"){r+=1;continue}if(s==="none"){o+=1;continue}let c=n.get(s);c?c.push(i):n.set(s,[i])}return{clusters:[...n].map(([i,s])=>({element:i,markers:s})),ambiguous:r,unresolved:o}}function fe(e){let t={...ee,...e.labels};if(e.armed===!1)return{refresh:()=>Promise.resolve(K),owns:()=>!1,last:()=>null,destroy:()=>{}};let n=e.doc??document,r=e.win??n.defaultView??window,o=e.now??Date.now,i=u(n,"div",{id:X}),s=i.attachShadow({mode:"open"}),c=u(n,"style");c.textContent=ne,s.appendChild(c);let d=u(n,"style");s.appendChild(d);let O=u(n,"div",{class:"count",role:"status","aria-label":t.region}),k=u(n,"span",{class:"count-text"});k.textContent=t.loading,O.appendChild(k);let A=u(n,"button",{type:"button",class:"toggle",hidden:""});O.appendChild(A),s.appendChild(O);let h=u(n,"div",{class:"panel",role:"dialog","aria-modal":"false","aria-label":t.region,hidden:""});s.appendChild(h),n.body.appendChild(i);let M=null,E=[],N=!1,R=e.showResolved===!0;function _(a){if(R)A.textContent=t.hideResolved;else if(a>0)A.textContent=t.showResolved(a);else{A.setAttribute("hidden",""),A.textContent="";return}A.setAttribute("aria-pressed",R?"true":"false"),A.removeAttribute("hidden")}function P(){if(E.length===0){d.textContent="";return}let a=r.innerWidth||0,p=r.innerHeight||0,g=[],b=[];E.forEach(({element:w},l)=>{let y=w.getBoundingClientRect(),f=W(Math.round(y.right-11),v,Math.max(v,a-T-v)),m=W(Math.round(y.top-11),v,Math.max(v,p-T-v)),x=re({left:f,top:m},g,p-T-v);g.push(x),b.push(`.pin[data-i="${l}"]{left:${x.left}px;top:${x.top}px}`)}),d.textContent=b.join("")}let L=()=>{N||P()};r.addEventListener("scroll",L,!0),r.addEventListener("resize",L);function I(){for(h.setAttribute("hidden","");h.firstChild;)h.removeChild(h.firstChild)}function Y(a,p){I();for(let f of a){let m=u(n,"div",{class:"entry"}),x=u(n,"p",{class:"who"}),D=f.createdAt?new Date(f.createdAt):null;x.textContent=D!==null&&!Number.isNaN(D.getTime())?`${f.reviewer} \xB7 ${D.toISOString().slice(0,10)}`:f.reviewer,m.appendChild(x);let U=u(n,"p",{class:"what"});U.textContent=f.comment,m.appendChild(U);let z=u(n,"p",{class:"state"});z.textContent=f.status.display,m.appendChild(z),h.appendChild(m)}let g=u(n,"p",{class:"fresh"}),b=M?.asOf??"",w=b===""?NaN:Date.parse(b);g.textContent=Number.isNaN(w)?t.freshnessUnknown:t.asOf(oe(o()-w)),h.appendChild(g);let l=u(n,"button",{type:"button",class:"close"});l.textContent=t.close,l.addEventListener("click",()=>I()),h.appendChild(l);let y=p.getBoundingClientRect();d.textContent=`${d.textContent??""}.panel{left:${Math.round(Math.max(8,y.right-320))}px;top:${Math.round(y.top+20)}px}`,h.removeAttribute("hidden")}function $(a,p){for(let{pin:l}of E)l.remove();if(E=[],I(),a===null){k.textContent=p??t.unreachable,_(0);let l={...K,showingResolved:R,line:k.textContent};return M=l,P(),l}let g=ae(a.annotations,n),b=0;g.clusters.forEach((l,y)=>{let f=l.element,m=u(n,"button",{type:"button",class:"pin","data-i":String(y),"aria-label":`${l.markers.length} annotation${l.markers.length===1?"":"s"}`});m.textContent=l.markers.length===1?"1":String(l.markers.length),m.addEventListener("click",x=>{x.preventDefault(),x.stopPropagation(),Y(l.markers,f)}),s.appendChild(m),E.push({pin:m,element:f}),b+=l.markers.length}),k.textContent=a.ok||a.reason===void 0?t.count(a.total,b,a.resolvedHidden):t.refused(a.reason),_(a.resolvedHidden);let w={total:a.total,shown:b,ambiguous:g.ambiguous,unresolved:g.unresolved,anchored:a.anchored,resolvedHidden:a.resolvedHidden,showingResolved:R,clusters:g.clusters.length,asOf:a.asOf,line:k.textContent??""};return M=w,P(),w}A.addEventListener("click",a=>{a.preventDefault(),a.stopPropagation(),!N&&(R=!R,_(M?.resolvedHidden??0),k.textContent=t.loading,F.refresh())});let F={async refresh(){if(N)return K;if(e.reader===null)return $(null,t.noCredential);let a=e.path??n.location?.pathname??"/";try{let p=await e.reader.read(a,{includeResolved:R});return $(p,null)}catch{return $(null,t.unreachable)}},owns(a){if(a===i)return!0;let p=a;return typeof p?.closest=="function"?p.closest(`#${X}`)===i:!1},last:()=>M,destroy(){N=!0,r.removeEventListener("scroll",L,!0),r.removeEventListener("resize",L);for(let{pin:a}of E)a.remove();E=[],i.remove()}};return F}export{ee as DEFAULT_MARKER_LABELS,X as MARKERS_ID,oe as formatMarkerAge,re as freeSpot,fe as mountAnnotationMarkers,ae as placeMarkers};
+//# sourceMappingURL=markers.mjs.map