@weatherboard/annotation 0.1.0 → 0.2.0

package/dist/toolbar.d.mts

@@ -0,0 +1,185 @@
+import type { AnnotationSdk, AnnotationSdkOptions, CommentCollector } from "./sdk.mjs";
+import { type Arming } from "./arming.mjs";
+import type { EgressOutcome } from "./transport.mjs";
+/**
+ * The toolbar and the post-it (A-240).
+ *
+ * ===========================================================================
+ * WHY THIS EXISTS AT ALL
+ * ===========================================================================
+ *
+ * `sdk.ts` built its payload with `comment: ""` and a comment saying why: *the
+ * parent frame collects the human's words and merges them in verbatim*. First
+ * party there is no parent — see `docs/plans/first-party-annotation.md` — so a
+ * capture would file an issue carrying a screenshot, a `file:line` and NOTHING
+ * SAYING WHAT IS WRONG WITH IT. This is the surface that collects the words,
+ * and the surface that turns annotation mode on in the first place.
+ *
+ * The toggle is the point rather than a convenience. The reviewer navigates the
+ * real app with annotation OFF — clicking rows, opening dialogs, finishing a
+ * wizard — and switches it ON when they arrive somewhere worth commenting on.
+ * That is what stops click-only screens being a wall, and it is why this is a
+ * toolbar and not a mode the page boots into.
+ *
+ * ===========================================================================
+ * IT RENDERS INSIDE SOMEBODY ELSE'S PRODUCT, AND THAT DECIDES ALMOST EVERYTHING
+ * ===========================================================================
+ *
+ * 1. **Shadow DOM, closed to the product's CSS in both directions.** The
+ *    product cannot restyle this and this cannot restyle the product. A
+ *    toolbar inheriting a host's `* { box-sizing: border-box }` — or its
+ *    `button { text-transform: uppercase }` — is a bug report about our own UI,
+ *    filed against their product, by a tool whose entire output is bug reports.
+ *    `:host { all: initial }` is the half people forget: a shadow root stops
+ *    SELECTORS crossing, not INHERITANCE. `e2e/toolbar.spec.ts` proves both
+ *    halves against a deliberately hostile fixture, and proves them the only
+ *    way that means anything — by deleting each and watching it go red.
+ *
+ *    THE ONE THING IT CANNOT DEFEND, said out loud rather than left to be
+ *    discovered: the HOST is in the light DOM, so the product's own selectors
+ *    reach it. `#ai-annotation-toolbar { position: static }` in a customer's
+ *    stylesheet beats `:host`, and puts this in the flow. Nothing shadow DOM
+ *    offers prevents that; the id is documented so that a collision is at
+ *    least legible when somebody hits it.
+ *
+ * 2. **It must not alter what is being reviewed.** Everything is `position:
+ *    fixed` and nothing is ever appended to the flow, so there is no layout
+ *    shift and no scrollbar; and NOTHING IS FOCUSED ON MOUNT. The reviewer is
+ *    here to judge pixels, and a tool that moves one of them has answered the
+ *    question wrongly before anybody clicks anything.
+ *
+ *    `position: fixed` is doing ALL of that work, and the viewport clamp in
+ *    `position()` is doing NONE of it — see the note there, which used to
+ *    claim otherwise.
+ *
+ * 3. **No product may be named here (A-98).** Every string in `DEFAULT_LABELS`
+ *    is generic, and every one of them is overridable by the mounting app. The
+ *    only text this renders that it did not author is the target's own
+ *    `file:line`, which is the customer's source path and belongs to them.
+ *
+ * ===========================================================================
+ * WHY THE CSS IS A TEMPLATE STRING AND WHAT THAT COSTS
+ * ===========================================================================
+ *
+ * A `<style>` element inside the shadow root, whose `textContent` is the string
+ * below. Not inline styles: `overlay.ts` uses those and carries nine entries in
+ * `audit-allowance.json` for it, and that ledger may only ever get shorter.
+ *
+ * TWO AUDITS READ THIS REPOSITORY AND THEY DISAGREE ABOUT THIS FILE, which is
+ * worth knowing before trusting either.
+ *
+ * `packages/design-audit` — `pnpm verify`'s ratchet — applies its colour,
+ * space, radius and type rules to `.css` FILES ONLY: `scan.ts` classifies
+ * every `.ts` as `tsx`, where the only rules are `inline-style` and the
+ * class-name pair. It sees nothing here.
+ *
+ * **The `design-system` CI job does.** It reads CSS out of `.ts` source, and
+ * the ledger it judges against — at the repository root, alongside
+ * `audit-allowance.json` and under the same only-ever-shorter rule — already
+ * carries `overlay.ts` for exactly that. THIS WAS MEASURED RATHER THAN
+ * REASONED: the first version of this file was written believing nothing
+ * audited it, said so in this comment, and that job failed the pull request
+ * with `untokenised-colour` and `untokenised-space` against it. The check won
+ * and the assumption is corrected here, where the assumption was.
+ *
+ * Hence the token block at the top of `CSS`. Every colour, space and radius
+ * below is a `var()` into it, so there is one place to change them and the
+ * gate can see that there is. They are `--ai-*` and NOT the design system's
+ * `--color-*` / `--space-*`, and that is forced rather than chosen: this
+ * package has zero dependencies on purpose, so the dictionary is not
+ * importable — and inside a shadow root a custom property resolves against the
+ * PRODUCT'S, so `var(--color-fg)` would paint this toolbar with whatever the
+ * customer happens to mean by that name. A local, prefixed block cannot
+ * collide with theirs.
+ */
+/**
+ * Every word this renders. Generic by default, and all of them injectable.
+ *
+ * Every field is RENDERED SOMEWHERE. A label nobody displays is an API promise
+ * that cannot be kept and bytes on every page of every managed product; three
+ * were written and deleted before this shipped for exactly that reason.
+ */
+export interface AnnotationToolbarLabels {
+    /** Names the whole surface for a screen reader. */
+    region: string;
+    expand: string;
+    collapse: string;
+    start: string;
+    stop: string;
+    done: string;
+    comment: string;
+    placeholder: string;
+    send: string;
+    cancel: string;
+    sent: string;
+    issue: string;
+    failed: string;
+    retry: string;
+}
+export declare const DEFAULT_LABELS: AnnotationToolbarLabels;
+/** The host's id. Our own node; nothing outside this package looks it up. */
+export declare const TOOLBAR_ID = "ai-annotation-toolbar";
+export interface AnnotationToolbarOptions {
+    /**
+     * Whether this page may offer an annotation UI at all.
+     *
+     * INJECTED, and deliberately not decided here. How arming is decided — the
+     * token in the URL, the cookie, the `replaceState` that strips it, the
+     * production kill-switch — is A-241, and a toolbar that read the URL itself
+     * would be a second answer to a question that must have exactly one.
+     *
+     * Unarmed, NOTHING IS APPENDED TO THE DOCUMENT. Not hidden: absent.
+     */
+    armed?: boolean;
+    doc?: Document;
+    /** Only for the viewport clamp, so a fake one is two numbers. */
+    win?: Pick<Window, "innerWidth" | "innerHeight">;
+    labels?: Partial<AnnotationToolbarLabels>;
+    /** *Done* — the reviewer is finished. A-241 owns what that clears. */
+    onDone?: () => void;
+}
+export interface AnnotationToolbar {
+    /** Is this node ours? Hand it to `AnnotationSdkOptions.ignoreElement`. */
+    owns: (node: unknown) => boolean;
+    /** Wire the toggle to a live SDK. */
+    attach: (sdk: AnnotationSdk) => void;
+    /** Hand to `AnnotationSdkOptions.collectComment`. */
+    collectComment: CommentCollector;
+    /** Hand to `AnnotationSdkOptions.onCaptureResult`. */
+    showResult: (outcome: EgressOutcome, retry: () => void) => void;
+    /** Whether the panel is open. For tests and for the mounting app. */
+    isExpanded: () => boolean;
+    destroy: () => void;
+}
+export declare function createAnnotationToolbar(options?: AnnotationToolbarOptions): AnnotationToolbar;
+export interface MountAnnotationOptions extends AnnotationSdkOptions {
+    toolbar?: AnnotationToolbarOptions;
+    /**
+     * The arming decision, from `readArming()` (A-241).
+     *
+     * Passing it is how the two gates get applied without every consumer
+     * re-deriving them: `armed` decides whether a toolbar exists at all, and
+     * *Done* calls `disarm` so the cookie and the stored capture token go with it.
+     *
+     * OPTIONAL because the frame path still mounts a toolbar-less SDK and has no
+     * deep link to read. Supplying both this and `toolbar.armed` throws — two
+     * answers to a question that must have exactly one.
+     */
+    arming?: Arming;
+}
+export interface MountedAnnotation {
+    sdk: AnnotationSdk;
+    toolbar: AnnotationToolbar;
+    destroy: () => void;
+}
+/**
+ * Build the SDK and the toolbar and connect them (A-240).
+ *
+ * Three wires, and each one is a silent failure if it is missing:
+ * `collectComment` absent files an issue with an empty comment;
+ * `onCaptureResult` absent leaves a reviewer who cannot tell a sent capture
+ * from a lost one; `ignoreElement` absent captures our own toolbar. None of
+ * them throws when omitted, which is exactly why they belong in one function
+ * rather than in three lines of every consumer's bootstrap.
+ */
+export declare function mountAnnotation(options: MountAnnotationOptions): MountedAnnotation;

package/dist/toolbar.d.ts

@@ -0,0 +1,185 @@
+import type { AnnotationSdk, AnnotationSdkOptions, CommentCollector } from "./sdk.js";
+import { type Arming } from "./arming.js";
+import type { EgressOutcome } from "./transport.js";
+/**
+ * The toolbar and the post-it (A-240).
+ *
+ * ===========================================================================
+ * WHY THIS EXISTS AT ALL
+ * ===========================================================================
+ *
+ * `sdk.ts` built its payload with `comment: ""` and a comment saying why: *the
+ * parent frame collects the human's words and merges them in verbatim*. First
+ * party there is no parent — see `docs/plans/first-party-annotation.md` — so a
+ * capture would file an issue carrying a screenshot, a `file:line` and NOTHING
+ * SAYING WHAT IS WRONG WITH IT. This is the surface that collects the words,
+ * and the surface that turns annotation mode on in the first place.
+ *
+ * The toggle is the point rather than a convenience. The reviewer navigates the
+ * real app with annotation OFF — clicking rows, opening dialogs, finishing a
+ * wizard — and switches it ON when they arrive somewhere worth commenting on.
+ * That is what stops click-only screens being a wall, and it is why this is a
+ * toolbar and not a mode the page boots into.
+ *
+ * ===========================================================================
+ * IT RENDERS INSIDE SOMEBODY ELSE'S PRODUCT, AND THAT DECIDES ALMOST EVERYTHING
+ * ===========================================================================
+ *
+ * 1. **Shadow DOM, closed to the product's CSS in both directions.** The
+ *    product cannot restyle this and this cannot restyle the product. A
+ *    toolbar inheriting a host's `* { box-sizing: border-box }` — or its
+ *    `button { text-transform: uppercase }` — is a bug report about our own UI,
+ *    filed against their product, by a tool whose entire output is bug reports.
+ *    `:host { all: initial }` is the half people forget: a shadow root stops
+ *    SELECTORS crossing, not INHERITANCE. `e2e/toolbar.spec.ts` proves both
+ *    halves against a deliberately hostile fixture, and proves them the only
+ *    way that means anything — by deleting each and watching it go red.
+ *
+ *    THE ONE THING IT CANNOT DEFEND, said out loud rather than left to be
+ *    discovered: the HOST is in the light DOM, so the product's own selectors
+ *    reach it. `#ai-annotation-toolbar { position: static }` in a customer's
+ *    stylesheet beats `:host`, and puts this in the flow. Nothing shadow DOM
+ *    offers prevents that; the id is documented so that a collision is at
+ *    least legible when somebody hits it.
+ *
+ * 2. **It must not alter what is being reviewed.** Everything is `position:
+ *    fixed` and nothing is ever appended to the flow, so there is no layout
+ *    shift and no scrollbar; and NOTHING IS FOCUSED ON MOUNT. The reviewer is
+ *    here to judge pixels, and a tool that moves one of them has answered the
+ *    question wrongly before anybody clicks anything.
+ *
+ *    `position: fixed` is doing ALL of that work, and the viewport clamp in
+ *    `position()` is doing NONE of it — see the note there, which used to
+ *    claim otherwise.
+ *
+ * 3. **No product may be named here (A-98).** Every string in `DEFAULT_LABELS`
+ *    is generic, and every one of them is overridable by the mounting app. The
+ *    only text this renders that it did not author is the target's own
+ *    `file:line`, which is the customer's source path and belongs to them.
+ *
+ * ===========================================================================
+ * WHY THE CSS IS A TEMPLATE STRING AND WHAT THAT COSTS
+ * ===========================================================================
+ *
+ * A `<style>` element inside the shadow root, whose `textContent` is the string
+ * below. Not inline styles: `overlay.ts` uses those and carries nine entries in
+ * `audit-allowance.json` for it, and that ledger may only ever get shorter.
+ *
+ * TWO AUDITS READ THIS REPOSITORY AND THEY DISAGREE ABOUT THIS FILE, which is
+ * worth knowing before trusting either.
+ *
+ * `packages/design-audit` — `pnpm verify`'s ratchet — applies its colour,
+ * space, radius and type rules to `.css` FILES ONLY: `scan.ts` classifies
+ * every `.ts` as `tsx`, where the only rules are `inline-style` and the
+ * class-name pair. It sees nothing here.
+ *
+ * **The `design-system` CI job does.** It reads CSS out of `.ts` source, and
+ * the ledger it judges against — at the repository root, alongside
+ * `audit-allowance.json` and under the same only-ever-shorter rule — already
+ * carries `overlay.ts` for exactly that. THIS WAS MEASURED RATHER THAN
+ * REASONED: the first version of this file was written believing nothing
+ * audited it, said so in this comment, and that job failed the pull request
+ * with `untokenised-colour` and `untokenised-space` against it. The check won
+ * and the assumption is corrected here, where the assumption was.
+ *
+ * Hence the token block at the top of `CSS`. Every colour, space and radius
+ * below is a `var()` into it, so there is one place to change them and the
+ * gate can see that there is. They are `--ai-*` and NOT the design system's
+ * `--color-*` / `--space-*`, and that is forced rather than chosen: this
+ * package has zero dependencies on purpose, so the dictionary is not
+ * importable — and inside a shadow root a custom property resolves against the
+ * PRODUCT'S, so `var(--color-fg)` would paint this toolbar with whatever the
+ * customer happens to mean by that name. A local, prefixed block cannot
+ * collide with theirs.
+ */
+/**
+ * Every word this renders. Generic by default, and all of them injectable.
+ *
+ * Every field is RENDERED SOMEWHERE. A label nobody displays is an API promise
+ * that cannot be kept and bytes on every page of every managed product; three
+ * were written and deleted before this shipped for exactly that reason.
+ */
+export interface AnnotationToolbarLabels {
+    /** Names the whole surface for a screen reader. */
+    region: string;
+    expand: string;
+    collapse: string;
+    start: string;
+    stop: string;
+    done: string;
+    comment: string;
+    placeholder: string;
+    send: string;
+    cancel: string;
+    sent: string;
+    issue: string;
+    failed: string;
+    retry: string;
+}
+export declare const DEFAULT_LABELS: AnnotationToolbarLabels;
+/** The host's id. Our own node; nothing outside this package looks it up. */
+export declare const TOOLBAR_ID = "ai-annotation-toolbar";
+export interface AnnotationToolbarOptions {
+    /**
+     * Whether this page may offer an annotation UI at all.
+     *
+     * INJECTED, and deliberately not decided here. How arming is decided — the
+     * token in the URL, the cookie, the `replaceState` that strips it, the
+     * production kill-switch — is A-241, and a toolbar that read the URL itself
+     * would be a second answer to a question that must have exactly one.
+     *
+     * Unarmed, NOTHING IS APPENDED TO THE DOCUMENT. Not hidden: absent.
+     */
+    armed?: boolean;
+    doc?: Document;
+    /** Only for the viewport clamp, so a fake one is two numbers. */
+    win?: Pick<Window, "innerWidth" | "innerHeight">;
+    labels?: Partial<AnnotationToolbarLabels>;
+    /** *Done* — the reviewer is finished. A-241 owns what that clears. */
+    onDone?: () => void;
+}
+export interface AnnotationToolbar {
+    /** Is this node ours? Hand it to `AnnotationSdkOptions.ignoreElement`. */
+    owns: (node: unknown) => boolean;
+    /** Wire the toggle to a live SDK. */
+    attach: (sdk: AnnotationSdk) => void;
+    /** Hand to `AnnotationSdkOptions.collectComment`. */
+    collectComment: CommentCollector;
+    /** Hand to `AnnotationSdkOptions.onCaptureResult`. */
+    showResult: (outcome: EgressOutcome, retry: () => void) => void;
+    /** Whether the panel is open. For tests and for the mounting app. */
+    isExpanded: () => boolean;
+    destroy: () => void;
+}
+export declare function createAnnotationToolbar(options?: AnnotationToolbarOptions): AnnotationToolbar;
+export interface MountAnnotationOptions extends AnnotationSdkOptions {
+    toolbar?: AnnotationToolbarOptions;
+    /**
+     * The arming decision, from `readArming()` (A-241).
+     *
+     * Passing it is how the two gates get applied without every consumer
+     * re-deriving them: `armed` decides whether a toolbar exists at all, and
+     * *Done* calls `disarm` so the cookie and the stored capture token go with it.
+     *
+     * OPTIONAL because the frame path still mounts a toolbar-less SDK and has no
+     * deep link to read. Supplying both this and `toolbar.armed` throws — two
+     * answers to a question that must have exactly one.
+     */
+    arming?: Arming;
+}
+export interface MountedAnnotation {
+    sdk: AnnotationSdk;
+    toolbar: AnnotationToolbar;
+    destroy: () => void;
+}
+/**
+ * Build the SDK and the toolbar and connect them (A-240).
+ *
+ * Three wires, and each one is a silent failure if it is missing:
+ * `collectComment` absent files an issue with an empty comment;
+ * `onCaptureResult` absent leaves a reviewer who cannot tell a sent capture
+ * from a lost one; `ignoreElement` absent captures our own toolbar. None of
+ * them throws when omitted, which is exactly why they belong in one function
+ * rather than in three lines of every consumer's bootstrap.
+ */
+export declare function mountAnnotation(options: MountAnnotationOptions): MountedAnnotation;

package/dist/transport.d.cts

@@ -0,0 +1,218 @@
+import { type FrameToParent } from "./protocol.cjs";
+/**
+ * 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>;