@weatherboard/annotation 0.1.0 → 0.2.0

package/dist/transport.d.mts

@@ -0,0 +1,218 @@
+import { type FrameToParent } from "./protocol.mjs";
+/**
+ * Egress (A-239).
+ *
+ * ===========================================================================
+ * WHY THIS IS A SEAM AND NOT A BRANCH IN `sdk.ts`
+ * ===========================================================================
+ *
+ * `sdk.ts` had exactly one way out — `win.parent.postMessage(...)` — and
+ * first-party there is no parent: `win.parent === win`. Every capture then
+ * posts a message to the page that sent it and nothing receives it. **That
+ * fails silently**, which is the shape to be careful of here: the overlay
+ * behaves correctly, the reviewer clicks, and no issue is ever filed.
+ *
+ * See `docs/plans/first-party-annotation.md`. The console stops framing the
+ * product and links out to it instead, so the capture has to leave the page
+ * over HTTP. The frame is NOT being deleted — `postMessageTransport` is
+ * today's behaviour, extracted unchanged, and it is still the default.
+ *
+ * ===========================================================================
+ * TWO PROPERTIES THAT HAD TO SURVIVE
+ * ===========================================================================
+ *
+ * 1. **Never a wildcard, in either direction.** `assertConcreteOrigin` still
+ *    guards the message path, and `assertConcreteEndpoint` is its equivalent
+ *    for HTTP. Both throw AT CONSTRUCTION rather than at first capture,
+ *    because a misconfiguration that only surfaces when a reviewer finally
+ *    clicks something is a misconfiguration nobody finds in review.
+ *
+ * 2. **The screenshot never costs the capture**, and neither may the network.
+ *    `attachScreenshot` resolves within its own timeout and never rejects, so
+ *    the payload goes out either way. An HTTP transport would reintroduce
+ *    exactly the failure mode that was designed out — a slow network losing a
+ *    capture — unless it carries its own timeout and its own `catch`, and
+ *    unless a failed send is REPORTABLE rather than swallowed. A dropped
+ *    capture that looks like a successful one is the worst outcome available
+ *    here, so `send` rejects loudly and `createEgress` routes that to the
+ *    caller.
+ */
+/** Every message the page half can emit. */
+export type FrameMessageKind = FrameToParent["type"];
+/**
+ * What the far end said about a capture it accepted (A-240).
+ *
+ * Everything on it is optional and always will be. `postMessageTransport`
+ * cannot answer at all — `postMessage` has no reply — and the ingest may
+ * answer with nothing. A reviewer who is told *sent* and given no link is in a
+ * strictly better position than one told nothing, so an absent `issueUrl` is a
+ * successful send and never a failed one.
+ */
+export interface SendReceipt {
+    /**
+     * The issue this capture became, when the far end names one.
+     *
+     * ANY VALUE HERE ENDS UP IN A THIRD PARTY'S DOM as an `href`, so the type
+     * alone is not the contract — see `safeIssueUrl`, which is what every value
+     * crossing the network boundary is put through before it gets to be one.
+     */
+    issueUrl?: string;
+}
+/**
+ * A URL from the network that is safe to put in somebody else's page (A-240).
+ *
+ * ===========================================================================
+ * WHY THIS IS NOT PARANOIA
+ * ===========================================================================
+ *
+ * `httpTransport` reads `issueUrl` out of a RESPONSE BODY and the toolbar sets
+ * it as an `<a href>` INSIDE THE CUSTOMER'S PAGE. `javascript:alert(1)` there
+ * executes in the product's origin the moment the reviewer clicks *View
+ * issue* — a script injection into a third party's site, shipped by us, on
+ * every page of every managed product.
+ *
+ * `assertConcreteEndpoint` does not cover this and was never going to:
+ * it constrains WHERE WE SEND, and this is WHAT COMES BACK. An ingest that is
+ * misconfigured, compromised, or simply behind a proxy that rewrites bodies is
+ * exactly the case a transport has to survive, and "our own console would
+ * never" is not a security boundary.
+ *
+ * It lives HERE and not in the toolbar so the guarantee travels with the
+ * receipt rather than with one renderer of it. The toolbar calls it too — see
+ * `showResult` — because it renders receipts from ANY transport, including one
+ * a consumer wrote, which never passes through this function.
+ *
+ * Anything not `http(s)` is dropped rather than repaired. A dropped link is a
+ * toast that says the capture was sent and offers no link, which is the
+ * outcome the receipt is already designed to survive.
+ */
+export declare function safeIssueUrl(value: unknown): string | undefined;
+export interface AnnotationTransport {
+    /** For diagnostics and for tests; never sent anywhere. */
+    readonly name: string;
+    /**
+     * May this transport carry this kind of message?
+     *
+     * The interface needs this because `annotate:hover` fires once per animation
+     * frame while the reviewer moves the mouse. Over `postMessage` that is a
+     * structured clone to a frame that is already listening; over HTTP it is one
+     * request per frame, which is a denial of service aimed at our own console.
+     *
+     * A transport that DROPPED such a message silently would be the same bug
+     * this issue exists to remove, one layer down. So declining is an explicit
+     * answer the SDK asks for and respects, and `send` is never called for a
+     * kind that was declined.
+     */
+    carries(kind: FrameMessageKind): boolean;
+    /**
+     * Deliver the message. May be synchronous.
+     *
+     * A returned promise MUST reject on failure. Resolving on a failed send is
+     * the one thing a transport may not do.
+     */
+    send(message: FrameToParent): void | Promise<void | SendReceipt>;
+}
+/** What went wrong, handed back to whoever constructed the SDK. */
+export interface EgressFailure {
+    message: FrameToParent;
+    transport: string;
+    error: unknown;
+}
+export type EgressErrorHandler = (failure: EgressFailure) => void;
+/**
+ * The parent-window transport — today's behaviour, extracted unchanged.
+ *
+ * It carries everything: the frame is a live listener on the other end of a
+ * cheap channel, and the handshake (`annotate:ready`) and the hover highlight
+ * both belong to it.
+ */
+export declare function postMessageTransport(parentOrigin: string, win?: Pick<Window, "parent">): AnnotationTransport;
+/**
+ * Reject anything that is not one concrete `http(s)` URL.
+ *
+ * `assertConcreteOrigin`'s argument, applied to an endpoint. A relative URL
+ * resolves against whatever page the SDK happens to be on — so a capture
+ * POSTs into the CUSTOMER'S OWN app, 404s, and is lost; and a `javascript:`
+ * or `data:` endpoint is a script-injection seam handed to whoever controls
+ * the deep link. Neither is a thing to discover at first capture.
+ */
+export declare function assertConcreteEndpoint(endpoint: string): string;
+/** Node's `fetch` and the browser's, narrowed to what we use. */
+export type FetchLike = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    credentials?: "omit";
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    /**
+     * Optional because `serve()`'s loopback responses are read through the
+     * platform `fetch`, which has it, while a stub written to assert the `init`
+     * need not. A transport that made the body mandatory would be asserting
+     * something about the ingest that the ingest does not promise.
+     */
+    json?: () => Promise<unknown>;
+}>;
+export interface HttpTransportOptions {
+    /** The console's ingest URL. Absolute, `http(s)`, never `*`. */
+    endpoint: string;
+    /**
+     * The capture token from the deep link — signed by the console, carried by
+     * the product, never validated by it. See the plan's *Authentication*
+     * section for why this is a second credential and not the arming one.
+     */
+    captureToken: string;
+    /**
+     * Own timeout, own catch. The default is deliberately short: a capture the
+     * reviewer is told failed can be retried, and a request that hangs is
+     * indistinguishable from one that worked.
+     */
+    timeoutMs?: number;
+    /** Injectable only so the tests can drive a transport with no `fetch` at all. */
+    fetch?: FetchLike;
+}
+export declare const HTTP_TRANSPORT_TIMEOUT_MS = 8000;
+/**
+ * The first-party transport: POST the capture to the console's ingest.
+ *
+ * It carries `annotate:capture` AND NOTHING ELSE. `annotate:hover` is one
+ * request per animation frame, and `annotate:ready` / `annotate:cancel` are
+ * handshake with a parent window that does not exist first-party — sending
+ * them would be filing HTTP requests nobody asked for.
+ */
+export declare function httpTransport(options: HttpTransportOptions): AnnotationTransport;
+/**
+ * What became of one message (A-240).
+ *
+ * `createEgress` used to return `void`, which was enough while the only reader
+ * of a failure was `console.error`. The composer has to TELL THE REVIEWER — the
+ * issue link on success, a retry on failure — and it cannot do that from a
+ * function that answers nothing. So the outcome is returned as a value, and the
+ * promise NEVER REJECTS: a rejection here would be a second way for a lost
+ * capture to disappear, one `await`-less caller away from silence.
+ *
+ * `declined` is its own case rather than a failure, because it is not one:
+ * `annotate:hover` over HTTP is a kind the transport correctly refuses, and
+ * calling that a failed capture would put a red toast in front of a reviewer
+ * who did nothing wrong. It is only a problem if `annotate:capture` is what was
+ * declined, and that is the caller's judgement rather than this function's.
+ */
+export type EgressOutcome = {
+    status: "sent";
+    receipt: SendReceipt;
+} | {
+    status: "declined";
+} | {
+    status: "failed";
+    error: unknown;
+};
+/**
+ * The SDK's one way out, given a transport.
+ *
+ * Pure and DOM-free on purpose, so the two things worth arguing about — that a
+ * declined kind is never sent, and that a failed send reaches the caller — are
+ * testable without a browser. `sdk.ts` holds no other egress path.
+ */
+export declare function createEgress(transport: AnnotationTransport, onError?: EgressErrorHandler): (message: FrameToParent) => Promise<EgressOutcome>;

package/dist/transport.d.ts

@@ -0,0 +1,218 @@
+import { type FrameToParent } from "./protocol.js";
+/**
+ * Egress (A-239).
+ *
+ * ===========================================================================
+ * WHY THIS IS A SEAM AND NOT A BRANCH IN `sdk.ts`
+ * ===========================================================================
+ *
+ * `sdk.ts` had exactly one way out — `win.parent.postMessage(...)` — and
+ * first-party there is no parent: `win.parent === win`. Every capture then
+ * posts a message to the page that sent it and nothing receives it. **That
+ * fails silently**, which is the shape to be careful of here: the overlay
+ * behaves correctly, the reviewer clicks, and no issue is ever filed.
+ *
+ * See `docs/plans/first-party-annotation.md`. The console stops framing the
+ * product and links out to it instead, so the capture has to leave the page
+ * over HTTP. The frame is NOT being deleted — `postMessageTransport` is
+ * today's behaviour, extracted unchanged, and it is still the default.
+ *
+ * ===========================================================================
+ * TWO PROPERTIES THAT HAD TO SURVIVE
+ * ===========================================================================
+ *
+ * 1. **Never a wildcard, in either direction.** `assertConcreteOrigin` still
+ *    guards the message path, and `assertConcreteEndpoint` is its equivalent
+ *    for HTTP. Both throw AT CONSTRUCTION rather than at first capture,
+ *    because a misconfiguration that only surfaces when a reviewer finally
+ *    clicks something is a misconfiguration nobody finds in review.
+ *
+ * 2. **The screenshot never costs the capture**, and neither may the network.
+ *    `attachScreenshot` resolves within its own timeout and never rejects, so
+ *    the payload goes out either way. An HTTP transport would reintroduce
+ *    exactly the failure mode that was designed out — a slow network losing a
+ *    capture — unless it carries its own timeout and its own `catch`, and
+ *    unless a failed send is REPORTABLE rather than swallowed. A dropped
+ *    capture that looks like a successful one is the worst outcome available
+ *    here, so `send` rejects loudly and `createEgress` routes that to the
+ *    caller.
+ */
+/** Every message the page half can emit. */
+export type FrameMessageKind = FrameToParent["type"];
+/**
+ * What the far end said about a capture it accepted (A-240).
+ *
+ * Everything on it is optional and always will be. `postMessageTransport`
+ * cannot answer at all — `postMessage` has no reply — and the ingest may
+ * answer with nothing. A reviewer who is told *sent* and given no link is in a
+ * strictly better position than one told nothing, so an absent `issueUrl` is a
+ * successful send and never a failed one.
+ */
+export interface SendReceipt {
+    /**
+     * The issue this capture became, when the far end names one.
+     *
+     * ANY VALUE HERE ENDS UP IN A THIRD PARTY'S DOM as an `href`, so the type
+     * alone is not the contract — see `safeIssueUrl`, which is what every value
+     * crossing the network boundary is put through before it gets to be one.
+     */
+    issueUrl?: string;
+}
+/**
+ * A URL from the network that is safe to put in somebody else's page (A-240).
+ *
+ * ===========================================================================
+ * WHY THIS IS NOT PARANOIA
+ * ===========================================================================
+ *
+ * `httpTransport` reads `issueUrl` out of a RESPONSE BODY and the toolbar sets
+ * it as an `<a href>` INSIDE THE CUSTOMER'S PAGE. `javascript:alert(1)` there
+ * executes in the product's origin the moment the reviewer clicks *View
+ * issue* — a script injection into a third party's site, shipped by us, on
+ * every page of every managed product.
+ *
+ * `assertConcreteEndpoint` does not cover this and was never going to:
+ * it constrains WHERE WE SEND, and this is WHAT COMES BACK. An ingest that is
+ * misconfigured, compromised, or simply behind a proxy that rewrites bodies is
+ * exactly the case a transport has to survive, and "our own console would
+ * never" is not a security boundary.
+ *
+ * It lives HERE and not in the toolbar so the guarantee travels with the
+ * receipt rather than with one renderer of it. The toolbar calls it too — see
+ * `showResult` — because it renders receipts from ANY transport, including one
+ * a consumer wrote, which never passes through this function.
+ *
+ * Anything not `http(s)` is dropped rather than repaired. A dropped link is a
+ * toast that says the capture was sent and offers no link, which is the
+ * outcome the receipt is already designed to survive.
+ */
+export declare function safeIssueUrl(value: unknown): string | undefined;
+export interface AnnotationTransport {
+    /** For diagnostics and for tests; never sent anywhere. */
+    readonly name: string;
+    /**
+     * May this transport carry this kind of message?
+     *
+     * The interface needs this because `annotate:hover` fires once per animation
+     * frame while the reviewer moves the mouse. Over `postMessage` that is a
+     * structured clone to a frame that is already listening; over HTTP it is one
+     * request per frame, which is a denial of service aimed at our own console.
+     *
+     * A transport that DROPPED such a message silently would be the same bug
+     * this issue exists to remove, one layer down. So declining is an explicit
+     * answer the SDK asks for and respects, and `send` is never called for a
+     * kind that was declined.
+     */
+    carries(kind: FrameMessageKind): boolean;
+    /**
+     * Deliver the message. May be synchronous.
+     *
+     * A returned promise MUST reject on failure. Resolving on a failed send is
+     * the one thing a transport may not do.
+     */
+    send(message: FrameToParent): void | Promise<void | SendReceipt>;
+}
+/** What went wrong, handed back to whoever constructed the SDK. */
+export interface EgressFailure {
+    message: FrameToParent;
+    transport: string;
+    error: unknown;
+}
+export type EgressErrorHandler = (failure: EgressFailure) => void;
+/**
+ * The parent-window transport — today's behaviour, extracted unchanged.
+ *
+ * It carries everything: the frame is a live listener on the other end of a
+ * cheap channel, and the handshake (`annotate:ready`) and the hover highlight
+ * both belong to it.
+ */
+export declare function postMessageTransport(parentOrigin: string, win?: Pick<Window, "parent">): AnnotationTransport;
+/**
+ * Reject anything that is not one concrete `http(s)` URL.
+ *
+ * `assertConcreteOrigin`'s argument, applied to an endpoint. A relative URL
+ * resolves against whatever page the SDK happens to be on — so a capture
+ * POSTs into the CUSTOMER'S OWN app, 404s, and is lost; and a `javascript:`
+ * or `data:` endpoint is a script-injection seam handed to whoever controls
+ * the deep link. Neither is a thing to discover at first capture.
+ */
+export declare function assertConcreteEndpoint(endpoint: string): string;
+/** Node's `fetch` and the browser's, narrowed to what we use. */
+export type FetchLike = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    credentials?: "omit";
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    /**
+     * Optional because `serve()`'s loopback responses are read through the
+     * platform `fetch`, which has it, while a stub written to assert the `init`
+     * need not. A transport that made the body mandatory would be asserting
+     * something about the ingest that the ingest does not promise.
+     */
+    json?: () => Promise<unknown>;
+}>;
+export interface HttpTransportOptions {
+    /** The console's ingest URL. Absolute, `http(s)`, never `*`. */
+    endpoint: string;
+    /**
+     * The capture token from the deep link — signed by the console, carried by
+     * the product, never validated by it. See the plan's *Authentication*
+     * section for why this is a second credential and not the arming one.
+     */
+    captureToken: string;
+    /**
+     * Own timeout, own catch. The default is deliberately short: a capture the
+     * reviewer is told failed can be retried, and a request that hangs is
+     * indistinguishable from one that worked.
+     */
+    timeoutMs?: number;
+    /** Injectable only so the tests can drive a transport with no `fetch` at all. */
+    fetch?: FetchLike;
+}
+export declare const HTTP_TRANSPORT_TIMEOUT_MS = 8000;
+/**
+ * The first-party transport: POST the capture to the console's ingest.
+ *
+ * It carries `annotate:capture` AND NOTHING ELSE. `annotate:hover` is one
+ * request per animation frame, and `annotate:ready` / `annotate:cancel` are
+ * handshake with a parent window that does not exist first-party — sending
+ * them would be filing HTTP requests nobody asked for.
+ */
+export declare function httpTransport(options: HttpTransportOptions): AnnotationTransport;
+/**
+ * What became of one message (A-240).
+ *
+ * `createEgress` used to return `void`, which was enough while the only reader
+ * of a failure was `console.error`. The composer has to TELL THE REVIEWER — the
+ * issue link on success, a retry on failure — and it cannot do that from a
+ * function that answers nothing. So the outcome is returned as a value, and the
+ * promise NEVER REJECTS: a rejection here would be a second way for a lost
+ * capture to disappear, one `await`-less caller away from silence.
+ *
+ * `declined` is its own case rather than a failure, because it is not one:
+ * `annotate:hover` over HTTP is a kind the transport correctly refuses, and
+ * calling that a failed capture would put a red toast in front of a reviewer
+ * who did nothing wrong. It is only a problem if `annotate:capture` is what was
+ * declined, and that is the caller's judgement rather than this function's.
+ */
+export type EgressOutcome = {
+    status: "sent";
+    receipt: SendReceipt;
+} | {
+    status: "declined";
+} | {
+    status: "failed";
+    error: unknown;
+};
+/**
+ * The SDK's one way out, given a transport.
+ *
+ * Pure and DOM-free on purpose, so the two things worth arguing about — that a
+ * declined kind is never sent, and that a failed send reaches the caller — are
+ * testable without a browser. `sdk.ts` holds no other egress path.
+ */
+export declare function createEgress(transport: AnnotationTransport, onError?: EgressErrorHandler): (message: FrameToParent) => Promise<EgressOutcome>;

package/fixtures/README.md

@@ -0,0 +1,35 @@
+# Fixtures — one per protocol shape that exists in the wild
+
+These are not test data. They are a **record of what has been sent**, and every
+reader in this repository is checked against all of them (A-189).
+
+Each file is a shape some deployed bundle emits or has emitted. They are added
+when a field is added and **retired only deliberately**, by a change that says in
+its own commit message why no consumer can still be emitting that shape.
+
+| Fixture | What it records | Why it cannot be dropped |
+|---|---|---|
+| `v1-minimal.json` | Every optional field absent | The floor. A reader that needs any optional field fails here first. |
+| `v1-no-source-ref.json` | No `source`, no `sourceChain`, with console and network entries | Production carries no source refs at all, and a page whose element has no annotated ancestor is ordinary. |
+| `v1-source-chain.json` | `source` + `sourceChain` + `componentName` | The composed-component case: the file that writes the markup is not the call site. |
+| `v1-screenshot.json` | `screenshot` present | Added by A-31; the largest payload shape and the one that meets the size limit. |
+| `v1-region-selection.json` | `selection: "region"` | Added by A-179. **Absent means `element`** — every fixture above proves that reading. |
+
+## What these are for
+
+A hundred consumers will not upgrade at the same time, and some will not upgrade
+at all. Fixtures rather than types, because **a type change that alters meaning
+while keeping the shape is exactly what a type checker cannot see** — making
+`selection` required with a default would compile, and would make every payload
+above claim a value nobody sent.
+
+## Adding one
+
+Add a fixture in the same change that adds the field, and give it a row above.
+A field added without a fixture is a field nothing proves is optional.
+
+## Retiring one
+
+Only when no deployed bundle can still emit it — which for a published package
+means a major version and evidence, not a guess. The test names the fixture that
+is missing, so retiring one is a deliberate act rather than a silent deletion.

package/fixtures/v1-minimal.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "capturedAt": "2026-08-23T10:00:00.000Z",
+  "build": { "gitSha": "464d52e1", "env": "preview" },
+  "page": {
+    "url": "https://example.test/",
+    "route": "/",
+    "viewport": { "w": 1440, "h": 900, "dpr": 2 },
+    "userAgent": "Mozilla/5.0"
+  },
+  "target": {
+    "domPath": "body > div",
+    "boundingBox": { "x": 0, "y": 0, "w": 100, "h": 40 }
+  },
+  "state": { "consoleErrors": [], "failedRequests": [], "featureFlags": {} },
+  "comment": ""
+}

package/fixtures/v1-no-source-ref.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "capturedAt": "2026-08-24T11:30:00.000Z",
+  "build": { "gitSha": "a00d6c8d", "env": "preview", "branch": "main" },
+  "page": {
+    "url": "https://example.test/guides/soho",
+    "route": "/guides/[slug]",
+    "viewport": { "w": 390, "h": 844, "dpr": 3 },
+    "userAgent": "Mozilla/5.0"
+  },
+  "target": {
+    "domPath": "main > section > p",
+    "boundingBox": { "x": 12, "y": 340, "w": 366, "h": 22 },
+    "textContent": "Open until 11pm"
+  },
+  "state": {
+    "consoleErrors": [{ "level": "error", "message": "Failed to load", "at": "2026-08-24T11:29:58.000Z" }],
+    "failedRequests": [{ "url": "https://example.test/api/hours", "status": 500, "at": "2026-08-24T11:29:57.000Z" }],
+    "featureFlags": {}
+  },
+  "comment": ""
+}

package/fixtures/v1-region-selection.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "capturedAt": "2026-08-30T18:00:00.000Z",
+  "build": { "gitSha": "7e93477", "env": "preview" },
+  "page": {
+    "url": "https://example.test/guides/soho",
+    "route": "/guides/[slug]",
+    "viewport": { "w": 1440, "h": 900, "dpr": 2 },
+    "userAgent": "Mozilla/5.0"
+  },
+  "target": {
+    "selection": "region",
+    "source": { "file": "apps/web/src/GuideList.tsx", "line": 30 },
+    "sourceChain": [
+      { "file": "apps/web/src/GuideList.tsx", "line": 30 },
+      { "file": "apps/web/src/GuideCard.tsx", "line": 14 }
+    ],
+    "domPath": "main > ul",
+    "boundingBox": { "x": 100, "y": 200, "w": 600, "h": 300 }
+  },
+  "state": { "consoleErrors": [], "failedRequests": [], "featureFlags": {} },
+  "comment": ""
+}

package/fixtures/v1-screenshot.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "capturedAt": "2026-08-25T09:20:00.000Z",
+  "build": { "gitSha": "1187f3b2", "env": "preview" },
+  "page": {
+    "url": "https://example.test/",
+    "route": "/",
+    "viewport": { "w": 1440, "h": 900, "dpr": 2 },
+    "userAgent": "Mozilla/5.0"
+  },
+  "target": {
+    "source": { "file": "apps/web/src/Hero.tsx", "line": 12 },
+    "domPath": "header > img",
+    "boundingBox": { "x": 0, "y": 0, "w": 1440, "h": 400 }
+  },
+  "state": { "consoleErrors": [], "failedRequests": [], "featureFlags": {} },
+  "screenshot": { "dataUrl": "data:image/png;base64,iVBORw0KGgo=", "region": "element" },
+  "comment": ""
+}

package/fixtures/v1-source-chain.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "capturedAt": "2026-08-25T09:15:00.000Z",
+  "build": { "gitSha": "1187f3b2", "env": "preview" },
+  "page": {
+    "url": "https://example.test/guides/soho",
+    "route": "/guides/[slug]",
+    "viewport": { "w": 1280, "h": 800, "dpr": 2 },
+    "userAgent": "Mozilla/5.0"
+  },
+  "target": {
+    "source": { "file": "packages/design-system/src/MediaCard.tsx", "line": 545, "column": 5 },
+    "sourceChain": [
+      { "file": "packages/design-system/src/MediaCard.tsx", "line": 545, "column": 5 },
+      { "file": "apps/web/src/GuideDetailCard.tsx", "line": 88, "column": 7 }
+    ],
+    "componentName": "MediaCard",
+    "domPath": "article > div > img",
+    "boundingBox": { "x": 40, "y": 120, "w": 320, "h": 200 },
+    "textContent": "A sunny terrace"
+  },
+  "state": { "consoleErrors": [], "failedRequests": [], "featureFlags": { "newHours": true } },
+  "comment": ""
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weatherboard/annotation",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Click an element in a running app, get the source location that rendered it.",
   "keywords": [
     "annotation",
@@ -57,16 +57,20 @@
     "access": "public",
     "//exports": "`types` INSIDE each condition, not above it. A single declaration shared by both formats hands a `require()` consumer types describing a module shape they do not get; and the ESM and CJS declarations differ in the extension their relative imports carry, which is what `moduleResolution: node16` checks. `build.mjs` explains the three spellings."
   },
+  "//files": "The fixtures ship too (A-189). They are a record of every payload shape ever sent, and a consumer writing their own reader has the same compatibility problem we do — shipping them is cheaper than them guessing which optional fields are really optional.",
   "files": [
     "dist",
+    "fixtures",
     "README.md",
     "ADOPTING.md",
+    "COMPATIBILITY.md",
     "LICENSE"
   ],
   "//sizeBudget": "Gzipped bytes per published entry point, checked by `build.mjs` on every build and therefore in CI. A budget is here rather than in a separate config because the number is part of the package's contract: this code runs on every page of every managed product, and 'it grew a bit each time' is how a 4KB SDK becomes a 40KB one with nobody having decided. Raising a number is allowed; doing it in the same commit as the growth, where a reviewer sees both, is the point.",
+  "//sizeBudget-index": "A-241 adds arming: 8700 -> 9400 for index and 700 -> 850 for protocol. MEASURED by rebuilding, four numbers. Baseline at A-240's merge commit fceb183: index 8562, protocol 646 - the two figures the previous note recorded, re-measured rather than trusted. As shipped: index 9281, protocol 788. And with the ./arming re-export block deleted from src/index.ts but everything else present: 8913. SO readArming AND ITS TYPES ARE 368 OF THE 719, AND 351 ARE NOT: 142 of that is protocol's own growth (armedCookie, clearedCookie, ANNOTATION_ARMED_VALUE, REVIEW_RUN_PARAM), which index pays too because it re-exports protocol whole, and the rest is isAnnotatableBuild with its ANNOTATABLE_ENVS allowlist, the two-gate expression in mountAnnotation, and Done's teardown. That 351 is the number worth knowing: a consumer who never calls readArming still pays it, because the kill-switch is not optional and must not be tree-shakeable. TWO REVIEW CYCLES MOVED IT AND BOTH COSTS ARE MEASURED: the fail-closed allowlist +27 (9239 -> 9266) and Done's teardown +15 (9266 -> 9281). HEADROOM IS PER ENTRY POINT AND THE TWO ARE STATED SEPARATELY, because one figure for both was false here once already: index 9400/9281 = 1.28%, against A-240's 8700/8562 = 1.61%, so tighter and DELIBERATELY NOT TOPPED UP - the budget's job is to make the next growth a decision, and quietly restoring slack each time is how it stops doing that; protocol 850/788 = 7.87%, against its previous 700/646 = 8.36%. protocol runs looser in PROPORTION only because it is small - 62 bytes is 7.87% there and would be 0.67% of index. The argument for the toolbar's own 2553 bytes is in docs/decisions/a-240-annotation-toolbar-size.md, extended there for this slice rather than restated here.",
   "sizeBudget": {
-    "protocol": 650,
-    "index": 5400,
+    "protocol": 850,
+    "index": 9400,
     "host": 660
   },
   "engines": {
@@ -84,10 +88,13 @@
     "typecheck": "tsc --noEmit",
     "//lint": "A-97. The root `eslint.config.mjs` is the single rule set — ESLint finds it by walking up from here, so there is nothing per-package to keep in sync. It is a script in EVERY package on purpose: A-52's verify tier runs `pnpm -r --if-present lint` and counts how many packages DECLARED it, so a package without this line is invisible to that gate rather than merely unlinted. `--max-warnings 0` because the React and Next plugins report at `warn` by default, and a gate that exits 0 while printing problems is the exact failure this repository keeps finding.",
     "lint": "eslint . --max-warnings 0",
-    "test": "tsx --test src/*.test.ts",
+    "//test": "`--test-timeout` is not decoration (A-240). Without it, breaking `httpTransport`'s abort did not turn this suite RED — it hung `pnpm test` forever, because the pending fetch keeps the event loop alive and node:test has no default deadline. CI times out, so it never read as a pass; but a wall-clock stall names no test and blames whatever was printed last, and this repository's standard is a NAMED FAILING TEST. 30s is a ceiling and not a budget: MEASURED, the slowest test in this suite is 203ms (`a 500 reaches the SDK's error handler`, which sleeps 200ms on purpose), so the limit is ~150x it and no honest test can reach it.",
+    "test": "tsx --test --test-timeout=30000 src/*.test.ts",
     "e2e": "playwright test",
     "//smoke": "The consumer test — pack the real tarball, install it outside the workspace, import it four ways. NOT part of `pnpm test`, and not because it is slow: it shells out to `npm install`, which needs the network, and `verify` is forbidden to acquire one. It runs as its own CI job. See the header of smoke.mjs for why nothing else in this repository can catch what it catches.",
     "smoke": "node smoke.mjs",
+    "//drift": "A-187. Compares this source's wire names against the version ALREADY PUBLISHED, when they are the same version. `smoke.mjs` proves the tarball we are about to publish; every unit test reads this source; neither looks at the registry. The hole is publish 0.1.0, then edit protocol.ts without bumping — a hundred consumers have one spelling, this console has another, and everything here is green. Needs the network, so it runs in the package-consumer job rather than in `verify`.",
+    "drift": "tsx published-drift.mjs",
     "//prepack": "Runs on `npm pack` and `npm publish`, which is what makes the `publishConfig` swap above safe: the tarball cannot be built without `dist/` having just been produced from this source. Without it the two could disagree and the failure would be a published package pointing at files that are not there."
   },
   "module": "./dist/index.mjs"