@weatherboard/annotation 0.1.0

package/dist/protocol.d.mts

@@ -0,0 +1,309 @@
+/**
+ * The annotation postMessage protocol (A-36).
+ *
+ * Mirrors `docs/contracts/types.ts`. That file is the
+ * cross-component contract; this is the runtime copy the product bundle ships,
+ * because the product cannot import from a docs directory. Changing a shape
+ * here is a change to both — say so in the PR.
+ */
+export declare const SDK_VERSION = "1";
+/**
+ * ===========================================================================
+ * THE ATTRIBUTES — THE OTHER WIRE (A-186)
+ * ===========================================================================
+ *
+ * These live in `protocol.ts`, not in `target.ts` where they are read, because
+ * they are a contract between TWO PACKAGES that a consumer installs separately:
+ * `@weatherboard/annotation-next` WRITES them at build time and this package
+ * READS them at runtime. Two spellings of `data-src` is not a bug anybody
+ * catches — the transform runs, the attributes appear, and every capture comes
+ * back with no source ref at all, which is indistinguishable from the transform
+ * not running.
+ *
+ * `annotation-next` imports these from `@weatherboard/annotation/protocol`
+ * rather than declaring its own, which is why the subpath has no DOM in it: a
+ * build tool importing the page SDK to learn two strings would be absurd.
+ */
+export declare const SRC_ATTR = "data-src";
+export declare const NAME_ATTR = "data-src-name";
+export interface SourceRef {
+    file: string;
+    line: number;
+    column?: number;
+}
+export interface BuildInfo {
+    /** Mandatory. Feedback not pinned to a revision is ambiguous the moment someone merges. */
+    gitSha: string;
+    /**
+     * Where this build came from.
+     *
+     * `"development"` was added in A-37, when the SDK was first mounted in a
+     * real app and the two halves turned out not to agree: `resolveBuildInfo` in
+     * `resolveBuildInfo` in the product's own Next config package — the module
+     * that stamps the build-env variable, and the only producer of this field —
+     * emits
+     * `production | preview | development`, mirroring `VERCEL_ENV`. This union
+     * instead offered `"staging"`, which nothing produces: a staging deploy IS a
+     * Vercel preview and reports itself as one. Widening rather than forcing the
+     * mount to lie: a locally-annotated build calling itself a preview would put
+     * someone's laptop in the corpus as though it were a deployment.
+     */
+    env: "production" | "preview" | "staging" | "development";
+    branch?: string;
+    /** Set when reviewing an agent's preview deploy, so feedback routes to that run's session. */
+    previewRunId?: string;
+}
+export interface ConsoleEntry {
+    level: "error" | "warn";
+    message: string;
+    stack?: string;
+    at: string;
+}
+export interface NetworkEntry {
+    url: string;
+    method: string;
+    status: number;
+    at: string;
+}
+export interface TargetInfo {
+    /**
+     * What the reviewer selected — one element, or an area (A-179).
+     *
+     * -------------------------------------------------------------------------
+     * WHY THIS EXISTS RATHER THAN BEING INFERRED
+     * -------------------------------------------------------------------------
+     *
+     * A region capture and an element capture are the same SHAPE: a bounding box,
+     * a chain of source refs, a DOM path. Nothing in the values distinguishes
+     * them, and the two mean opposite things about the chain — for an element it
+     * is ANCESTORS, innermost first, so entry two contains entry one; for a
+     * region it is SIBLINGS the rectangle happened to cross, which contain
+     * nothing of each other.
+     *
+     * A reader that guesses will describe a region's siblings as a call-site
+     * chain, which is a confident false statement about the page. `describeCapture`
+     * hands that description to a model that writes acceptance criteria from it.
+     *
+     * -------------------------------------------------------------------------
+     * WHY IT IS OPTIONAL, AND WHY ABSENT MEANS `element`
+     * -------------------------------------------------------------------------
+     *
+     * The two halves of this protocol live in different repositories and deploy
+     * independently (see the note on the legacy parameter names below). Every
+     * capture in the store today, and every capture from a product bundle that
+     * predates region selection, has no such field — and all of them are element
+     * captures. Absent therefore has to mean `element`, or this field would
+     * retroactively make the entire history ambiguous.
+     *
+     * Required-with-a-default would have the same effect and a worse failure: an
+     * older bundle omits it, the type says it is there, and every reader believes
+     * a value nobody sent.
+     */
+    selection?: "element" | "region";
+    source?: SourceRef;
+    /**
+     * Every `data-src` from the clicked element up to the document root, innermost
+     * first — an addition to the contract, and the reason is structural.
+     *
+     * Only host elements carry a ref (A-33), so `source` names the file that
+     * *writes the markup*. For a composed design-system component that is
+     * `MediaCard.tsx`, not the `GuideDetailCard.tsx` a human would say they
+     * clicked. The chain is what lets the PM agent and the coding agent see both,
+     * and pick the call site over the leaf when the feedback is about content
+     * rather than the component itself.
+     */
+    sourceChain?: SourceRef[];
+    componentName?: string;
+    /** CSS selector fallback, for when no ancestor carries a ref at all. */
+    domPath: string;
+    boundingBox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Truncated to 200 characters. */
+    textContent?: string;
+}
+export interface AnnotationPayload {
+    schemaVersion: 1;
+    capturedAt: string;
+    build: BuildInfo;
+    page: {
+        url: string;
+        /** The matched route pattern, not the resolved URL. */
+        route: string;
+        viewport: {
+            w: number;
+            h: number;
+            dpr: number;
+        };
+        userAgent: string;
+    };
+    target: TargetInfo;
+    state: {
+        consoleErrors: ConsoleEntry[];
+        failedRequests: NetworkEntry[];
+        featureFlags: Record<string, unknown>;
+    };
+    screenshot?: {
+        dataUrl: string;
+        region: "element" | "viewport";
+    };
+    /** The human's words, verbatim. The parent frame fills this in; we never rewrite it. */
+    comment: string;
+}
+export type ParentToFrame = {
+    type: "annotate:enable";
+} | {
+    type: "annotate:disable";
+} | {
+    type: "annotate:ping";
+};
+export type FrameToParent = {
+    type: "annotate:ready";
+    sdkVersion: string;
+    build: BuildInfo;
+} | {
+    type: "annotate:hover";
+    target: TargetInfo;
+} | {
+    type: "annotate:capture";
+    payload: AnnotationPayload;
+} | {
+    type: "annotate:cancel";
+};
+/**
+ * Is this a message we recognise?
+ *
+ * Origin is checked separately and first — a well-formed message from the wrong
+ * origin is the case this guard must not be trusted to catch.
+ */
+export declare function isParentMessage(data: unknown): data is ParentToFrame;
+/**
+ * Reject wildcards outright rather than treating them as "any origin".
+ *
+ * `postMessage(msg, "*")` broadcasts the payload to whatever happens to be
+ * framing us, and an annotation payload carries page content, console errors and
+ * failed request URLs. The spec's rule is no wildcards in either direction; this
+ * makes it impossible to configure one by accident.
+ */
+export declare function assertConcreteOrigin(origin: string): string;
+/**
+ * The query parameter that arms the SDK in a managed product, and the cookie
+ * that records it.
+ *
+ * THESE LIVE IN THE PROTOCOL BECAUSE THE TWO HALVES ARE NOW IN DIFFERENT
+ * REPOSITORIES. The managed product's middleware looks for the parameter and
+ * sets the cookie; the management app appends the parameter and the SDK reads
+ * the cookie. While both halves were one monorepo, a test could read the other
+ * side's source and assert the strings matched — that gate does not survive a
+ * repository split, and a mismatch produces no error at all: the frame loads,
+ * the cookie is never set, the SDK never boots, and the reviewer sees "waiting
+ * for the page to announce itself" with nothing to go on.
+ *
+ * So they stop being two spellings that agree and become one exported
+ * constant. A managed product that imports this package cannot drift from it.
+ */
+export declare const ANNOTATION_TOKEN_PARAM = "ai_annotate";
+export declare const ANNOTATION_ARMED_COOKIE = "ai_annotate_armed";
+/**
+ * The names these used to have (A-98).
+ *
+ * -------------------------------------------------------------------------
+ * WHY THE RENAME, AND WHY IT COULD NOT JUST BE DONE
+ * -------------------------------------------------------------------------
+ *
+ * They were `pits_annotate` and `pits_annotate_armed` — one managed product's
+ * initialism, in a contract every managed product's bundle has to implement.
+ * Onboarding a second product meant asking an unrelated codebase to adopt the
+ * first product's name in its cookies and its query strings. That is the bug
+ * A-98 is about, and it is a bug in a wire protocol rather than in a variable
+ * name, which is what makes it expensive.
+ *
+ * The two halves live in DIFFERENT REPOSITORIES and deploy independently. A
+ * clean rename is therefore a breaking change to every product bundle
+ * simultaneously, and its failure mode is silence: the frame loads, the cookie
+ * is never set, the SDK never boots, and the reviewer sees "waiting for the
+ * page to announce itself" with nothing to go on. Nothing throws, nothing logs,
+ * and the natural reading is that the agent broke the site.
+ *
+ * -------------------------------------------------------------------------
+ * THE MIGRATION: READ BOTH, WRITE BOTH, THEN STOP WRITING THE OLD ONE
+ * -------------------------------------------------------------------------
+ *
+ * 1. **Now.** Every reader accepts either name. Every writer emits BOTH, so a
+ *    product still running the old bundle arms on the legacy name and one
+ *    running the new bundle arms on the new one. Deploy order stops mattering,
+ *    which is the whole point — there is no window in which a reviewer sees the
+ *    silent failure above.
+ * 2. **After every managed product's bundle is on this version** (A-102). Drop
+ *    the legacy names from the writers, then from the readers. Two steps, not
+ *    one: a reader that stops accepting the old name before the writers stop
+ *    emitting it re-creates the outage in the other direction.
+ *
+ * The legacy names are exported rather than inlined so the deletion in step 2
+ * is `git grep LEGACY_` rather than an archaeology exercise.
+ */
+export declare const LEGACY_ANNOTATION_TOKEN_PARAM = "pits_annotate";
+export declare const LEGACY_ANNOTATION_ARMED_COOKIE = "pits_annotate_armed";
+/**
+ * ===========================================================================
+ * AND THE NAMES ARE NOT CHANGING AGAIN FOR THE PUBLISHED PACKAGE (A-184)
+ * ===========================================================================
+ *
+ * When this becomes `@weatherboard/annotation` the obvious next thought is that
+ * the wire names should match the package — `weatherboard_annotate`. They
+ * should not, and the reason is the migration described above rather than
+ * taste.
+ *
+ * That migration is STILL IN FLIGHT. Readers accept both spellings; writers
+ * emit both; step 2 waits on every managed product's bundle being current.
+ * A third spelling introduced now does not replace the second, it joins it:
+ * every reader accepts three names, every writer emits three, and the window in
+ * which a product can be on any of them widens instead of closing.
+ *
+ * The cost is not the code. It is that each rename buys another instance of the
+ * failure this file exists to prevent — the frame loads, the cookie is never
+ * set, the SDK never boots, and the reviewer sees "waiting for the page to
+ * announce itself" with nothing to go on. Twice is a migration. Three times is
+ * a habit, and the third one would be paid by consumers who never asked for
+ * either.
+ *
+ * `ai_annotate` is already product-neutral, which was the entire point of A-98.
+ * A published package needs names that name no product; it does not need names
+ * that name the package. Nobody reading a query string cares which npm scope
+ * the library came from.
+ *
+ * The one real objection is collision: `ai_` is a common prefix and some other
+ * tool could plausibly use it. That is survivable by construction — arming
+ * requires the parameter to carry a token the product compares exactly, so a
+ * coincidental `?ai_annotate=` from an unrelated tool arms nothing. A colliding
+ * COOKIE cannot false-positive either; `isAnnotationArmed` matches on the
+ * delimiter rather than by substring, for exactly this reason.
+ *
+ * If a rename is ever genuinely warranted, it happens ONCE, after step 2 has
+ * landed and the reader accepts one name again — not layered on top of an
+ * unfinished one.
+ */
+/** Both spellings of the query parameter, current first. */
+export declare const ANNOTATION_TOKEN_PARAMS: readonly ["ai_annotate", "pits_annotate"];
+/** Both spellings of the cookie, current first. */
+export declare const ANNOTATION_ARMED_COOKIES: readonly ["ai_annotate_armed", "pits_annotate_armed"];
+/**
+ * Whether a cookie jar carries the armed cookie, under either name.
+ *
+ * Delimiter-aware rather than a substring test: a cookie named
+ * `not_ai_annotate_armed`, or another cookie whose VALUE contains the name,
+ * satisfies `includes` — and arming an annotation channel on a coincidence is
+ * not a failure anyone would think to look for.
+ */
+export declare function isAnnotationArmed(cookie: string): boolean;
+/**
+ * The arming token from a URL's query string, under either name.
+ *
+ * Current name wins when both are present. They should never disagree — the
+ * management app writes both from one value — but if they ever do, the one this
+ * version of the protocol owns is the one to believe.
+ */
+export declare function readAnnotationToken(params: URLSearchParams): string | null;

package/dist/protocol.d.ts

@@ -0,0 +1,309 @@
+/**
+ * The annotation postMessage protocol (A-36).
+ *
+ * Mirrors `docs/contracts/types.ts`. That file is the
+ * cross-component contract; this is the runtime copy the product bundle ships,
+ * because the product cannot import from a docs directory. Changing a shape
+ * here is a change to both — say so in the PR.
+ */
+export declare const SDK_VERSION = "1";
+/**
+ * ===========================================================================
+ * THE ATTRIBUTES — THE OTHER WIRE (A-186)
+ * ===========================================================================
+ *
+ * These live in `protocol.ts`, not in `target.ts` where they are read, because
+ * they are a contract between TWO PACKAGES that a consumer installs separately:
+ * `@weatherboard/annotation-next` WRITES them at build time and this package
+ * READS them at runtime. Two spellings of `data-src` is not a bug anybody
+ * catches — the transform runs, the attributes appear, and every capture comes
+ * back with no source ref at all, which is indistinguishable from the transform
+ * not running.
+ *
+ * `annotation-next` imports these from `@weatherboard/annotation/protocol`
+ * rather than declaring its own, which is why the subpath has no DOM in it: a
+ * build tool importing the page SDK to learn two strings would be absurd.
+ */
+export declare const SRC_ATTR = "data-src";
+export declare const NAME_ATTR = "data-src-name";
+export interface SourceRef {
+    file: string;
+    line: number;
+    column?: number;
+}
+export interface BuildInfo {
+    /** Mandatory. Feedback not pinned to a revision is ambiguous the moment someone merges. */
+    gitSha: string;
+    /**
+     * Where this build came from.
+     *
+     * `"development"` was added in A-37, when the SDK was first mounted in a
+     * real app and the two halves turned out not to agree: `resolveBuildInfo` in
+     * `resolveBuildInfo` in the product's own Next config package — the module
+     * that stamps the build-env variable, and the only producer of this field —
+     * emits
+     * `production | preview | development`, mirroring `VERCEL_ENV`. This union
+     * instead offered `"staging"`, which nothing produces: a staging deploy IS a
+     * Vercel preview and reports itself as one. Widening rather than forcing the
+     * mount to lie: a locally-annotated build calling itself a preview would put
+     * someone's laptop in the corpus as though it were a deployment.
+     */
+    env: "production" | "preview" | "staging" | "development";
+    branch?: string;
+    /** Set when reviewing an agent's preview deploy, so feedback routes to that run's session. */
+    previewRunId?: string;
+}
+export interface ConsoleEntry {
+    level: "error" | "warn";
+    message: string;
+    stack?: string;
+    at: string;
+}
+export interface NetworkEntry {
+    url: string;
+    method: string;
+    status: number;
+    at: string;
+}
+export interface TargetInfo {
+    /**
+     * What the reviewer selected — one element, or an area (A-179).
+     *
+     * -------------------------------------------------------------------------
+     * WHY THIS EXISTS RATHER THAN BEING INFERRED
+     * -------------------------------------------------------------------------
+     *
+     * A region capture and an element capture are the same SHAPE: a bounding box,
+     * a chain of source refs, a DOM path. Nothing in the values distinguishes
+     * them, and the two mean opposite things about the chain — for an element it
+     * is ANCESTORS, innermost first, so entry two contains entry one; for a
+     * region it is SIBLINGS the rectangle happened to cross, which contain
+     * nothing of each other.
+     *
+     * A reader that guesses will describe a region's siblings as a call-site
+     * chain, which is a confident false statement about the page. `describeCapture`
+     * hands that description to a model that writes acceptance criteria from it.
+     *
+     * -------------------------------------------------------------------------
+     * WHY IT IS OPTIONAL, AND WHY ABSENT MEANS `element`
+     * -------------------------------------------------------------------------
+     *
+     * The two halves of this protocol live in different repositories and deploy
+     * independently (see the note on the legacy parameter names below). Every
+     * capture in the store today, and every capture from a product bundle that
+     * predates region selection, has no such field — and all of them are element
+     * captures. Absent therefore has to mean `element`, or this field would
+     * retroactively make the entire history ambiguous.
+     *
+     * Required-with-a-default would have the same effect and a worse failure: an
+     * older bundle omits it, the type says it is there, and every reader believes
+     * a value nobody sent.
+     */
+    selection?: "element" | "region";
+    source?: SourceRef;
+    /**
+     * Every `data-src` from the clicked element up to the document root, innermost
+     * first — an addition to the contract, and the reason is structural.
+     *
+     * Only host elements carry a ref (A-33), so `source` names the file that
+     * *writes the markup*. For a composed design-system component that is
+     * `MediaCard.tsx`, not the `GuideDetailCard.tsx` a human would say they
+     * clicked. The chain is what lets the PM agent and the coding agent see both,
+     * and pick the call site over the leaf when the feedback is about content
+     * rather than the component itself.
+     */
+    sourceChain?: SourceRef[];
+    componentName?: string;
+    /** CSS selector fallback, for when no ancestor carries a ref at all. */
+    domPath: string;
+    boundingBox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Truncated to 200 characters. */
+    textContent?: string;
+}
+export interface AnnotationPayload {
+    schemaVersion: 1;
+    capturedAt: string;
+    build: BuildInfo;
+    page: {
+        url: string;
+        /** The matched route pattern, not the resolved URL. */
+        route: string;
+        viewport: {
+            w: number;
+            h: number;
+            dpr: number;
+        };
+        userAgent: string;
+    };
+    target: TargetInfo;
+    state: {
+        consoleErrors: ConsoleEntry[];
+        failedRequests: NetworkEntry[];
+        featureFlags: Record<string, unknown>;
+    };
+    screenshot?: {
+        dataUrl: string;
+        region: "element" | "viewport";
+    };
+    /** The human's words, verbatim. The parent frame fills this in; we never rewrite it. */
+    comment: string;
+}
+export type ParentToFrame = {
+    type: "annotate:enable";
+} | {
+    type: "annotate:disable";
+} | {
+    type: "annotate:ping";
+};
+export type FrameToParent = {
+    type: "annotate:ready";
+    sdkVersion: string;
+    build: BuildInfo;
+} | {
+    type: "annotate:hover";
+    target: TargetInfo;
+} | {
+    type: "annotate:capture";
+    payload: AnnotationPayload;
+} | {
+    type: "annotate:cancel";
+};
+/**
+ * Is this a message we recognise?
+ *
+ * Origin is checked separately and first — a well-formed message from the wrong
+ * origin is the case this guard must not be trusted to catch.
+ */
+export declare function isParentMessage(data: unknown): data is ParentToFrame;
+/**
+ * Reject wildcards outright rather than treating them as "any origin".
+ *
+ * `postMessage(msg, "*")` broadcasts the payload to whatever happens to be
+ * framing us, and an annotation payload carries page content, console errors and
+ * failed request URLs. The spec's rule is no wildcards in either direction; this
+ * makes it impossible to configure one by accident.
+ */
+export declare function assertConcreteOrigin(origin: string): string;
+/**
+ * The query parameter that arms the SDK in a managed product, and the cookie
+ * that records it.
+ *
+ * THESE LIVE IN THE PROTOCOL BECAUSE THE TWO HALVES ARE NOW IN DIFFERENT
+ * REPOSITORIES. The managed product's middleware looks for the parameter and
+ * sets the cookie; the management app appends the parameter and the SDK reads
+ * the cookie. While both halves were one monorepo, a test could read the other
+ * side's source and assert the strings matched — that gate does not survive a
+ * repository split, and a mismatch produces no error at all: the frame loads,
+ * the cookie is never set, the SDK never boots, and the reviewer sees "waiting
+ * for the page to announce itself" with nothing to go on.
+ *
+ * So they stop being two spellings that agree and become one exported
+ * constant. A managed product that imports this package cannot drift from it.
+ */
+export declare const ANNOTATION_TOKEN_PARAM = "ai_annotate";
+export declare const ANNOTATION_ARMED_COOKIE = "ai_annotate_armed";
+/**
+ * The names these used to have (A-98).
+ *
+ * -------------------------------------------------------------------------
+ * WHY THE RENAME, AND WHY IT COULD NOT JUST BE DONE
+ * -------------------------------------------------------------------------
+ *
+ * They were `pits_annotate` and `pits_annotate_armed` — one managed product's
+ * initialism, in a contract every managed product's bundle has to implement.
+ * Onboarding a second product meant asking an unrelated codebase to adopt the
+ * first product's name in its cookies and its query strings. That is the bug
+ * A-98 is about, and it is a bug in a wire protocol rather than in a variable
+ * name, which is what makes it expensive.
+ *
+ * The two halves live in DIFFERENT REPOSITORIES and deploy independently. A
+ * clean rename is therefore a breaking change to every product bundle
+ * simultaneously, and its failure mode is silence: the frame loads, the cookie
+ * is never set, the SDK never boots, and the reviewer sees "waiting for the
+ * page to announce itself" with nothing to go on. Nothing throws, nothing logs,
+ * and the natural reading is that the agent broke the site.
+ *
+ * -------------------------------------------------------------------------
+ * THE MIGRATION: READ BOTH, WRITE BOTH, THEN STOP WRITING THE OLD ONE
+ * -------------------------------------------------------------------------
+ *
+ * 1. **Now.** Every reader accepts either name. Every writer emits BOTH, so a
+ *    product still running the old bundle arms on the legacy name and one
+ *    running the new bundle arms on the new one. Deploy order stops mattering,
+ *    which is the whole point — there is no window in which a reviewer sees the
+ *    silent failure above.
+ * 2. **After every managed product's bundle is on this version** (A-102). Drop
+ *    the legacy names from the writers, then from the readers. Two steps, not
+ *    one: a reader that stops accepting the old name before the writers stop
+ *    emitting it re-creates the outage in the other direction.
+ *
+ * The legacy names are exported rather than inlined so the deletion in step 2
+ * is `git grep LEGACY_` rather than an archaeology exercise.
+ */
+export declare const LEGACY_ANNOTATION_TOKEN_PARAM = "pits_annotate";
+export declare const LEGACY_ANNOTATION_ARMED_COOKIE = "pits_annotate_armed";
+/**
+ * ===========================================================================
+ * AND THE NAMES ARE NOT CHANGING AGAIN FOR THE PUBLISHED PACKAGE (A-184)
+ * ===========================================================================
+ *
+ * When this becomes `@weatherboard/annotation` the obvious next thought is that
+ * the wire names should match the package — `weatherboard_annotate`. They
+ * should not, and the reason is the migration described above rather than
+ * taste.
+ *
+ * That migration is STILL IN FLIGHT. Readers accept both spellings; writers
+ * emit both; step 2 waits on every managed product's bundle being current.
+ * A third spelling introduced now does not replace the second, it joins it:
+ * every reader accepts three names, every writer emits three, and the window in
+ * which a product can be on any of them widens instead of closing.
+ *
+ * The cost is not the code. It is that each rename buys another instance of the
+ * failure this file exists to prevent — the frame loads, the cookie is never
+ * set, the SDK never boots, and the reviewer sees "waiting for the page to
+ * announce itself" with nothing to go on. Twice is a migration. Three times is
+ * a habit, and the third one would be paid by consumers who never asked for
+ * either.
+ *
+ * `ai_annotate` is already product-neutral, which was the entire point of A-98.
+ * A published package needs names that name no product; it does not need names
+ * that name the package. Nobody reading a query string cares which npm scope
+ * the library came from.
+ *
+ * The one real objection is collision: `ai_` is a common prefix and some other
+ * tool could plausibly use it. That is survivable by construction — arming
+ * requires the parameter to carry a token the product compares exactly, so a
+ * coincidental `?ai_annotate=` from an unrelated tool arms nothing. A colliding
+ * COOKIE cannot false-positive either; `isAnnotationArmed` matches on the
+ * delimiter rather than by substring, for exactly this reason.
+ *
+ * If a rename is ever genuinely warranted, it happens ONCE, after step 2 has
+ * landed and the reader accepts one name again — not layered on top of an
+ * unfinished one.
+ */
+/** Both spellings of the query parameter, current first. */
+export declare const ANNOTATION_TOKEN_PARAMS: readonly ["ai_annotate", "pits_annotate"];
+/** Both spellings of the cookie, current first. */
+export declare const ANNOTATION_ARMED_COOKIES: readonly ["ai_annotate_armed", "pits_annotate_armed"];
+/**
+ * Whether a cookie jar carries the armed cookie, under either name.
+ *
+ * Delimiter-aware rather than a substring test: a cookie named
+ * `not_ai_annotate_armed`, or another cookie whose VALUE contains the name,
+ * satisfies `includes` — and arming an annotation channel on a coincidence is
+ * not a failure anyone would think to look for.
+ */
+export declare function isAnnotationArmed(cookie: string): boolean;
+/**
+ * The arming token from a URL's query string, under either name.
+ *
+ * Current name wins when both are present. They should never disagree — the
+ * management app writes both from one value — but if they ever do, the one this
+ * version of the protocol owns is the one to believe.
+ */
+export declare function readAnnotationToken(params: URLSearchParams): string | null;

package/dist/protocol.mjs

@@ -0,0 +1,2 @@
+var g="1",l="data-src",m="data-src-name",o=new Set(["annotate:enable","annotate:disable","annotate:ping"]);function d(t){if(typeof t!="object"||t===null)return!1;let e=t.type;return typeof e=="string"&&o.has(e)}function A(t){if(!t||t==="*")throw new Error("[annotation] a concrete parent origin is required; '*' would broadcast annotation payloads to any embedder.");return t}var a="ai_annotate",s="ai_annotate_armed",i="pits_annotate",c="pits_annotate_armed",p=[a,i],u=[s,c];function f(t){return t.split(";").some(e=>{let n=e.trimStart();return u.some(r=>n.startsWith(`${r}=`))})}function T(t){for(let e of p){let n=t.get(e);if(n!==null&&n.length>0)return n}return null}export{s as ANNOTATION_ARMED_COOKIE,u as ANNOTATION_ARMED_COOKIES,a as ANNOTATION_TOKEN_PARAM,p as ANNOTATION_TOKEN_PARAMS,c as LEGACY_ANNOTATION_ARMED_COOKIE,i as LEGACY_ANNOTATION_TOKEN_PARAM,m as NAME_ATTR,g as SDK_VERSION,l as SRC_ATTR,A as assertConcreteOrigin,f as isAnnotationArmed,d as isParentMessage,T as readAnnotationToken};
+//# sourceMappingURL=protocol.mjs.map

package/dist/protocol.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/protocol.ts"],
+  "sourcesContent": ["/**\n * The annotation postMessage protocol (A-36).\n *\n * Mirrors `docs/contracts/types.ts`. That file is the\n * cross-component contract; this is the runtime copy the product bundle ships,\n * because the product cannot import from a docs directory. Changing a shape\n * here is a change to both \u2014 say so in the PR.\n */\n\nexport const SDK_VERSION = \"1\";\n\n/**\n * ===========================================================================\n * THE ATTRIBUTES \u2014 THE OTHER WIRE (A-186)\n * ===========================================================================\n *\n * These live in `protocol.ts`, not in `target.ts` where they are read, because\n * they are a contract between TWO PACKAGES that a consumer installs separately:\n * `@weatherboard/annotation-next` WRITES them at build time and this package\n * READS them at runtime. Two spellings of `data-src` is not a bug anybody\n * catches \u2014 the transform runs, the attributes appear, and every capture comes\n * back with no source ref at all, which is indistinguishable from the transform\n * not running.\n *\n * `annotation-next` imports these from `@weatherboard/annotation/protocol`\n * rather than declaring its own, which is why the subpath has no DOM in it: a\n * build tool importing the page SDK to learn two strings would be absurd.\n */\nexport const SRC_ATTR = \"data-src\";\nexport const NAME_ATTR = \"data-src-name\";\n\nexport interface SourceRef {\n  file: string;\n  line: number;\n  column?: number;\n}\n\nexport interface BuildInfo {\n  /** Mandatory. Feedback not pinned to a revision is ambiguous the moment someone merges. */\n  gitSha: string;\n  /**\n   * Where this build came from.\n   *\n   * `\"development\"` was added in A-37, when the SDK was first mounted in a\n   * real app and the two halves turned out not to agree: `resolveBuildInfo` in\n   * `resolveBuildInfo` in the product's own Next config package \u2014 the module\n   * that stamps the build-env variable, and the only producer of this field \u2014\n   * emits\n   * `production | preview | development`, mirroring `VERCEL_ENV`. This union\n   * instead offered `\"staging\"`, which nothing produces: a staging deploy IS a\n   * Vercel preview and reports itself as one. Widening rather than forcing the\n   * mount to lie: a locally-annotated build calling itself a preview would put\n   * someone's laptop in the corpus as though it were a deployment.\n   */\n  env: \"production\" | \"preview\" | \"staging\" | \"development\";\n  branch?: string;\n  /** Set when reviewing an agent's preview deploy, so feedback routes to that run's session. */\n  previewRunId?: string;\n}\n\nexport interface ConsoleEntry {\n  level: \"error\" | \"warn\";\n  message: string;\n  stack?: string;\n  at: string;\n}\n\nexport interface NetworkEntry {\n  url: string;\n  method: string;\n  status: number;\n  at: string;\n}\n\nexport interface TargetInfo {\n  /**\n   * What the reviewer selected \u2014 one element, or an area (A-179).\n   *\n   * -------------------------------------------------------------------------\n   * WHY THIS EXISTS RATHER THAN BEING INFERRED\n   * -------------------------------------------------------------------------\n   *\n   * A region capture and an element capture are the same SHAPE: a bounding box,\n   * a chain of source refs, a DOM path. Nothing in the values distinguishes\n   * them, and the two mean opposite things about the chain \u2014 for an element it\n   * is ANCESTORS, innermost first, so entry two contains entry one; for a\n   * region it is SIBLINGS the rectangle happened to cross, which contain\n   * nothing of each other.\n   *\n   * A reader that guesses will describe a region's siblings as a call-site\n   * chain, which is a confident false statement about the page. `describeCapture`\n   * hands that description to a model that writes acceptance criteria from it.\n   *\n   * -------------------------------------------------------------------------\n   * WHY IT IS OPTIONAL, AND WHY ABSENT MEANS `element`\n   * -------------------------------------------------------------------------\n   *\n   * The two halves of this protocol live in different repositories and deploy\n   * independently (see the note on the legacy parameter names below). Every\n   * capture in the store today, and every capture from a product bundle that\n   * predates region selection, has no such field \u2014 and all of them are element\n   * captures. Absent therefore has to mean `element`, or this field would\n   * retroactively make the entire history ambiguous.\n   *\n   * Required-with-a-default would have the same effect and a worse failure: an\n   * older bundle omits it, the type says it is there, and every reader believes\n   * a value nobody sent.\n   */\n  selection?: \"element\" | \"region\";\n  source?: SourceRef;\n  /**\n   * Every `data-src` from the clicked element up to the document root, innermost\n   * first \u2014 an addition to the contract, and the reason is structural.\n   *\n   * Only host elements carry a ref (A-33), so `source` names the file that\n   * *writes the markup*. For a composed design-system component that is\n   * `MediaCard.tsx`, not the `GuideDetailCard.tsx` a human would say they\n   * clicked. The chain is what lets the PM agent and the coding agent see both,\n   * and pick the call site over the leaf when the feedback is about content\n   * rather than the component itself.\n   */\n  sourceChain?: SourceRef[];\n  componentName?: string;\n  /** CSS selector fallback, for when no ancestor carries a ref at all. */\n  domPath: string;\n  boundingBox: { x: number; y: number; w: number; h: number };\n  /** Truncated to 200 characters. */\n  textContent?: string;\n}\n\nexport interface AnnotationPayload {\n  schemaVersion: 1;\n  capturedAt: string;\n  build: BuildInfo;\n  page: {\n    url: string;\n    /** The matched route pattern, not the resolved URL. */\n    route: string;\n    viewport: { w: number; h: number; dpr: number };\n    userAgent: string;\n  };\n  target: TargetInfo;\n  state: {\n    consoleErrors: ConsoleEntry[];\n    failedRequests: NetworkEntry[];\n    featureFlags: Record<string, unknown>;\n  };\n  screenshot?: { dataUrl: string; region: \"element\" | \"viewport\" };\n  /** The human's words, verbatim. The parent frame fills this in; we never rewrite it. */\n  comment: string;\n}\n\nexport type ParentToFrame =\n  | { type: \"annotate:enable\" }\n  | { type: \"annotate:disable\" }\n  | { type: \"annotate:ping\" };\n\nexport type FrameToParent =\n  | { type: \"annotate:ready\"; sdkVersion: string; build: BuildInfo }\n  | { type: \"annotate:hover\"; target: TargetInfo }\n  | { type: \"annotate:capture\"; payload: AnnotationPayload }\n  | { type: \"annotate:cancel\" };\n\nconst PARENT_TYPES = new Set([\"annotate:enable\", \"annotate:disable\", \"annotate:ping\"]);\n\n/**\n * Is this a message we recognise?\n *\n * Origin is checked separately and first \u2014 a well-formed message from the wrong\n * origin is the case this guard must not be trusted to catch.\n */\nexport function isParentMessage(data: unknown): data is ParentToFrame {\n  if (typeof data !== \"object\" || data === null) return false;\n  const type = (data as { type?: unknown }).type;\n  return typeof type === \"string\" && PARENT_TYPES.has(type);\n}\n\n/**\n * Reject wildcards outright rather than treating them as \"any origin\".\n *\n * `postMessage(msg, \"*\")` broadcasts the payload to whatever happens to be\n * framing us, and an annotation payload carries page content, console errors and\n * failed request URLs. The spec's rule is no wildcards in either direction; this\n * makes it impossible to configure one by accident.\n */\nexport function assertConcreteOrigin(origin: string): string {\n  if (!origin || origin === \"*\") {\n    throw new Error(\n      \"[annotation] a concrete parent origin is required; '*' would broadcast \" +\n        \"annotation payloads to any embedder.\",\n    );\n  }\n  return origin;\n}\n\n/**\n * The query parameter that arms the SDK in a managed product, and the cookie\n * that records it.\n *\n * THESE LIVE IN THE PROTOCOL BECAUSE THE TWO HALVES ARE NOW IN DIFFERENT\n * REPOSITORIES. The managed product's middleware looks for the parameter and\n * sets the cookie; the management app appends the parameter and the SDK reads\n * the cookie. While both halves were one monorepo, a test could read the other\n * side's source and assert the strings matched \u2014 that gate does not survive a\n * repository split, and a mismatch produces no error at all: the frame loads,\n * the cookie is never set, the SDK never boots, and the reviewer sees \"waiting\n * for the page to announce itself\" with nothing to go on.\n *\n * So they stop being two spellings that agree and become one exported\n * constant. A managed product that imports this package cannot drift from it.\n */\nexport const ANNOTATION_TOKEN_PARAM = \"ai_annotate\";\nexport const ANNOTATION_ARMED_COOKIE = \"ai_annotate_armed\";\n\n/**\n * The names these used to have (A-98).\n *\n * -------------------------------------------------------------------------\n * WHY THE RENAME, AND WHY IT COULD NOT JUST BE DONE\n * -------------------------------------------------------------------------\n *\n * They were `pits_annotate` and `pits_annotate_armed` \u2014 one managed product's\n * initialism, in a contract every managed product's bundle has to implement.\n * Onboarding a second product meant asking an unrelated codebase to adopt the\n * first product's name in its cookies and its query strings. That is the bug\n * A-98 is about, and it is a bug in a wire protocol rather than in a variable\n * name, which is what makes it expensive.\n *\n * The two halves live in DIFFERENT REPOSITORIES and deploy independently. A\n * clean rename is therefore a breaking change to every product bundle\n * simultaneously, and its failure mode is silence: the frame loads, the cookie\n * is never set, the SDK never boots, and the reviewer sees \"waiting for the\n * page to announce itself\" with nothing to go on. Nothing throws, nothing logs,\n * and the natural reading is that the agent broke the site.\n *\n * -------------------------------------------------------------------------\n * THE MIGRATION: READ BOTH, WRITE BOTH, THEN STOP WRITING THE OLD ONE\n * -------------------------------------------------------------------------\n *\n * 1. **Now.** Every reader accepts either name. Every writer emits BOTH, so a\n *    product still running the old bundle arms on the legacy name and one\n *    running the new bundle arms on the new one. Deploy order stops mattering,\n *    which is the whole point \u2014 there is no window in which a reviewer sees the\n *    silent failure above.\n * 2. **After every managed product's bundle is on this version** (A-102). Drop\n *    the legacy names from the writers, then from the readers. Two steps, not\n *    one: a reader that stops accepting the old name before the writers stop\n *    emitting it re-creates the outage in the other direction.\n *\n * The legacy names are exported rather than inlined so the deletion in step 2\n * is `git grep LEGACY_` rather than an archaeology exercise.\n */\nexport const LEGACY_ANNOTATION_TOKEN_PARAM = \"pits_annotate\";\nexport const LEGACY_ANNOTATION_ARMED_COOKIE = \"pits_annotate_armed\";\n\n/**\n * ===========================================================================\n * AND THE NAMES ARE NOT CHANGING AGAIN FOR THE PUBLISHED PACKAGE (A-184)\n * ===========================================================================\n *\n * When this becomes `@weatherboard/annotation` the obvious next thought is that\n * the wire names should match the package \u2014 `weatherboard_annotate`. They\n * should not, and the reason is the migration described above rather than\n * taste.\n *\n * That migration is STILL IN FLIGHT. Readers accept both spellings; writers\n * emit both; step 2 waits on every managed product's bundle being current.\n * A third spelling introduced now does not replace the second, it joins it:\n * every reader accepts three names, every writer emits three, and the window in\n * which a product can be on any of them widens instead of closing.\n *\n * The cost is not the code. It is that each rename buys another instance of the\n * failure this file exists to prevent \u2014 the frame loads, the cookie is never\n * set, the SDK never boots, and the reviewer sees \"waiting for the page to\n * announce itself\" with nothing to go on. Twice is a migration. Three times is\n * a habit, and the third one would be paid by consumers who never asked for\n * either.\n *\n * `ai_annotate` is already product-neutral, which was the entire point of A-98.\n * A published package needs names that name no product; it does not need names\n * that name the package. Nobody reading a query string cares which npm scope\n * the library came from.\n *\n * The one real objection is collision: `ai_` is a common prefix and some other\n * tool could plausibly use it. That is survivable by construction \u2014 arming\n * requires the parameter to carry a token the product compares exactly, so a\n * coincidental `?ai_annotate=` from an unrelated tool arms nothing. A colliding\n * COOKIE cannot false-positive either; `isAnnotationArmed` matches on the\n * delimiter rather than by substring, for exactly this reason.\n *\n * If a rename is ever genuinely warranted, it happens ONCE, after step 2 has\n * landed and the reader accepts one name again \u2014 not layered on top of an\n * unfinished one.\n */\n\n/** Both spellings of the query parameter, current first. */\nexport const ANNOTATION_TOKEN_PARAMS = [\n  ANNOTATION_TOKEN_PARAM,\n  LEGACY_ANNOTATION_TOKEN_PARAM,\n] as const;\n\n/** Both spellings of the cookie, current first. */\nexport const ANNOTATION_ARMED_COOKIES = [\n  ANNOTATION_ARMED_COOKIE,\n  LEGACY_ANNOTATION_ARMED_COOKIE,\n] as const;\n\n/**\n * Whether a cookie jar carries the armed cookie, under either name.\n *\n * Delimiter-aware rather than a substring test: a cookie named\n * `not_ai_annotate_armed`, or another cookie whose VALUE contains the name,\n * satisfies `includes` \u2014 and arming an annotation channel on a coincidence is\n * not a failure anyone would think to look for.\n */\nexport function isAnnotationArmed(cookie: string): boolean {\n  return cookie\n    .split(\";\")\n    .some((entry) => {\n      const trimmed = entry.trimStart();\n      return ANNOTATION_ARMED_COOKIES.some((name) => trimmed.startsWith(`${name}=`));\n    });\n}\n\n/**\n * The arming token from a URL's query string, under either name.\n *\n * Current name wins when both are present. They should never disagree \u2014 the\n * management app writes both from one value \u2014 but if they ever do, the one this\n * version of the protocol owns is the one to believe.\n */\nexport function readAnnotationToken(params: URLSearchParams): string | null {\n  for (const name of ANNOTATION_TOKEN_PARAMS) {\n    const value = params.get(name);\n    if (value !== null && value.length > 0) return value;\n  }\n  return null;\n}\n"],
+  "mappings": "AASO,IAAMA,EAAc,IAmBdC,EAAW,WACXC,EAAY,gBAsInBC,EAAe,IAAI,IAAI,CAAC,kBAAmB,mBAAoB,eAAe,CAAC,EAQ9E,SAASC,EAAgBC,EAAsC,CACpE,GAAI,OAAOA,GAAS,UAAYA,IAAS,KAAM,MAAO,GACtD,IAAMC,EAAQD,EAA4B,KAC1C,OAAO,OAAOC,GAAS,UAAYH,EAAa,IAAIG,CAAI,CAC1D,CAUO,SAASC,EAAqBC,EAAwB,CAC3D,GAAI,CAACA,GAAUA,IAAW,IACxB,MAAM,IAAI,MACR,6GAEF,EAEF,OAAOA,CACT,CAkBO,IAAMC,EAAyB,cACzBC,EAA0B,oBAwC1BC,EAAgC,gBAChCC,EAAiC,sBA2CjCC,EAA0B,CACrCJ,EACAE,CACF,EAGaG,EAA2B,CACtCJ,EACAE,CACF,EAUO,SAASG,EAAkBC,EAAyB,CACzD,OAAOA,EACJ,MAAM,GAAG,EACT,KAAMC,GAAU,CACf,IAAMC,EAAUD,EAAM,UAAU,EAChC,OAAOH,EAAyB,KAAMK,GAASD,EAAQ,WAAW,GAAGC,CAAI,GAAG,CAAC,CAC/E,CAAC,CACL,CASO,SAASC,EAAoBC,EAAwC,CAC1E,QAAWF,KAAQN,EAAyB,CAC1C,IAAMS,EAAQD,EAAO,IAAIF,CAAI,EAC7B,GAAIG,IAAU,MAAQA,EAAM,OAAS,EAAG,OAAOA,CACjD,CACA,OAAO,IACT",
+  "names": ["SDK_VERSION", "SRC_ATTR", "NAME_ATTR", "PARENT_TYPES", "isParentMessage", "data", "type", "assertConcreteOrigin", "origin", "ANNOTATION_TOKEN_PARAM", "ANNOTATION_ARMED_COOKIE", "LEGACY_ANNOTATION_TOKEN_PARAM", "LEGACY_ANNOTATION_ARMED_COOKIE", "ANNOTATION_TOKEN_PARAMS", "ANNOTATION_ARMED_COOKIES", "isAnnotationArmed", "cookie", "entry", "trimmed", "name", "readAnnotationToken", "params", "value"]
+}