@weatherboard/annotation 0.1.0 → 0.2.0

package/dist/sdk.d.cts

@@ -1,4 +1,5 @@
-import { type AnnotationPayload, type BuildInfo } from "./protocol.cjs";
+import { type AnnotationPayload, type BuildInfo, type TargetInfo } from "./protocol.cjs";
+import { type AnnotationTransport, type EgressErrorHandler, type EgressOutcome } from "./transport.cjs";
 import { type ScreenshotOptions } from "./screenshot.cjs";
 /**
  * The annotation SDK (A-36).
@@ -11,13 +12,52 @@ export interface AnnotationState {
     failedRequests: AnnotationPayload["state"]["failedRequests"];
     featureFlags: Record<string, unknown>;
 }
+/**
+ * What the reviewer clicked, handed to whoever collects the words (A-240).
+ *
+ * The target is the RESOLVED one, taken from the payload that was already
+ * assembled — not the element, and not something to re-read. See `onClick` for
+ * why that distinction is the whole of this feature's correctness.
+ */
+export interface CommentRequest {
+    target: TargetInfo;
+    /** Viewport coordinates of the click, so a composer can sit near it. */
+    point: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Ask the human for their words (A-240).
+ *
+ * Resolves with the comment, or with `null` for cancel — and cancel means
+ * NOTHING IS SENT, which is why it is a distinct value rather than an empty
+ * string. An empty string is a reviewer who had nothing to add; `null` is a
+ * reviewer who changed their mind, and filing an issue for the second is the
+ * kind of thing that gets an annotation tool switched off.
+ *
+ * Absent, the payload keeps `comment: ""` and the frame path is unchanged: the
+ * parent window is still the thing that collects the words there.
+ */
+export type CommentCollector = (request: CommentRequest) => Promise<string | null>;
 export interface AnnotationSdkOptions {
     /**
-     * The management app's origin. Required and concrete — see
+     * The management app's origin, when there is one. Concrete — see
      * `assertConcreteOrigin`. Messages from anywhere else are ignored, and we
      * never post to anywhere else.
+     *
+     * OPTIONAL SINCE A-240, and only because first-party there is no parent to
+     * listen to. It used to be required for a reason that survives: the inbound
+     * `message` listener needs a concrete origin to compare against, and a
+     * listener with nothing to compare against is one that accepts instructions
+     * from any page that can reach this one. So the resolution is not a default
+     * origin — it is NO LISTENER AT ALL. Omitting this makes the SDK deaf to
+     * `postMessage`, which is exactly right for a page with no parent, and it is
+     * the only construction in which that is true.
+     *
+     * Supply it and the frame path is bit-for-bit what it was.
      */
-    parentOrigin: string;
+    parentOrigin?: string;
     build: BuildInfo;
     /**
      * The matched route pattern, e.g. `/pub/[slug]`.
@@ -40,6 +80,55 @@ export interface AnnotationSdkOptions {
      * else, so most clicks produce no screenshot at all, by design.
      */
     screenshot?: ScreenshotOptions | false;
+    /**
+     * How a capture leaves the page (A-239).
+     *
+     * Defaults to `postMessageTransport(parentOrigin)`, which is what this SDK
+     * has always done. Pass `httpTransport(...)` when the product is being
+     * annotated first-party, where `win.parent === win` and a posted message is
+     * received by nobody — see `transport.ts` and
+     * `docs/plans/first-party-annotation.md`.
+     */
+    transport?: AnnotationTransport;
+    /**
+     * Called when a message could not be delivered.
+     *
+     * The frame path effectively never fails, so this is new surface for the
+     * HTTP one, and it exists because the alternative is a dropped capture that
+     * looks like a successful one. With no handler the failure is logged rather
+     * than swallowed; A-240 is what puts it in front of the reviewer.
+     */
+    onEgressError?: EgressErrorHandler;
+    /**
+     * Collect the reviewer's words after a click (A-240).
+     *
+     * Omit it and the SDK behaves exactly as it did: `comment: ""`, and the
+     * parent frame merges the human's words in.
+     */
+    collectComment?: CommentCollector;
+    /**
+     * What became of the capture, plus a thunk that sends the SAME payload again.
+     *
+     * The retry re-sends what was captured rather than re-capturing: the reviewer
+     * has moved on by then — a dialog is open, a row is selected, the page has
+     * scrolled — and re-reading it would file an issue about a screen nobody
+     * complained about.
+     */
+    onCaptureResult?: (outcome: EgressOutcome, retry: () => void) => void;
+    /**
+     * Elements annotation mode must pretend it cannot see.
+     *
+     * The toolbar renders INTO THE PAGE IT IS ANNOTATING, so with annotation on,
+     * a click on *Stop* is a click on the page and would be captured — filing an
+     * issue about our own button and swallowing the press that was meant to end
+     * the session. Shadow DOM makes it worse rather than better: retargeting
+     * reports the event's target as the shadow HOST, so the capture would not
+     * even name the button.
+     *
+     * Injected rather than hard-coded to an id, because a hard-coded id is a
+     * second definition of who owns that node.
+     */
+    ignoreElement?: (el: Element) => boolean;
 }
 export interface AnnotationSdk {
     enable(): void;

package/dist/sdk.d.mts

@@ -1,4 +1,5 @@
-import { type AnnotationPayload, type BuildInfo } from "./protocol.mjs";
+import { type AnnotationPayload, type BuildInfo, type TargetInfo } from "./protocol.mjs";
+import { type AnnotationTransport, type EgressErrorHandler, type EgressOutcome } from "./transport.mjs";
 import { type ScreenshotOptions } from "./screenshot.mjs";
 /**
  * The annotation SDK (A-36).
@@ -11,13 +12,52 @@ export interface AnnotationState {
     failedRequests: AnnotationPayload["state"]["failedRequests"];
     featureFlags: Record<string, unknown>;
 }
+/**
+ * What the reviewer clicked, handed to whoever collects the words (A-240).
+ *
+ * The target is the RESOLVED one, taken from the payload that was already
+ * assembled — not the element, and not something to re-read. See `onClick` for
+ * why that distinction is the whole of this feature's correctness.
+ */
+export interface CommentRequest {
+    target: TargetInfo;
+    /** Viewport coordinates of the click, so a composer can sit near it. */
+    point: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Ask the human for their words (A-240).
+ *
+ * Resolves with the comment, or with `null` for cancel — and cancel means
+ * NOTHING IS SENT, which is why it is a distinct value rather than an empty
+ * string. An empty string is a reviewer who had nothing to add; `null` is a
+ * reviewer who changed their mind, and filing an issue for the second is the
+ * kind of thing that gets an annotation tool switched off.
+ *
+ * Absent, the payload keeps `comment: ""` and the frame path is unchanged: the
+ * parent window is still the thing that collects the words there.
+ */
+export type CommentCollector = (request: CommentRequest) => Promise<string | null>;
 export interface AnnotationSdkOptions {
     /**
-     * The management app's origin. Required and concrete — see
+     * The management app's origin, when there is one. Concrete — see
      * `assertConcreteOrigin`. Messages from anywhere else are ignored, and we
      * never post to anywhere else.
+     *
+     * OPTIONAL SINCE A-240, and only because first-party there is no parent to
+     * listen to. It used to be required for a reason that survives: the inbound
+     * `message` listener needs a concrete origin to compare against, and a
+     * listener with nothing to compare against is one that accepts instructions
+     * from any page that can reach this one. So the resolution is not a default
+     * origin — it is NO LISTENER AT ALL. Omitting this makes the SDK deaf to
+     * `postMessage`, which is exactly right for a page with no parent, and it is
+     * the only construction in which that is true.
+     *
+     * Supply it and the frame path is bit-for-bit what it was.
      */
-    parentOrigin: string;
+    parentOrigin?: string;
     build: BuildInfo;
     /**
      * The matched route pattern, e.g. `/pub/[slug]`.
@@ -40,6 +80,55 @@ export interface AnnotationSdkOptions {
      * else, so most clicks produce no screenshot at all, by design.
      */
     screenshot?: ScreenshotOptions | false;
+    /**
+     * How a capture leaves the page (A-239).
+     *
+     * Defaults to `postMessageTransport(parentOrigin)`, which is what this SDK
+     * has always done. Pass `httpTransport(...)` when the product is being
+     * annotated first-party, where `win.parent === win` and a posted message is
+     * received by nobody — see `transport.ts` and
+     * `docs/plans/first-party-annotation.md`.
+     */
+    transport?: AnnotationTransport;
+    /**
+     * Called when a message could not be delivered.
+     *
+     * The frame path effectively never fails, so this is new surface for the
+     * HTTP one, and it exists because the alternative is a dropped capture that
+     * looks like a successful one. With no handler the failure is logged rather
+     * than swallowed; A-240 is what puts it in front of the reviewer.
+     */
+    onEgressError?: EgressErrorHandler;
+    /**
+     * Collect the reviewer's words after a click (A-240).
+     *
+     * Omit it and the SDK behaves exactly as it did: `comment: ""`, and the
+     * parent frame merges the human's words in.
+     */
+    collectComment?: CommentCollector;
+    /**
+     * What became of the capture, plus a thunk that sends the SAME payload again.
+     *
+     * The retry re-sends what was captured rather than re-capturing: the reviewer
+     * has moved on by then — a dialog is open, a row is selected, the page has
+     * scrolled — and re-reading it would file an issue about a screen nobody
+     * complained about.
+     */
+    onCaptureResult?: (outcome: EgressOutcome, retry: () => void) => void;
+    /**
+     * Elements annotation mode must pretend it cannot see.
+     *
+     * The toolbar renders INTO THE PAGE IT IS ANNOTATING, so with annotation on,
+     * a click on *Stop* is a click on the page and would be captured — filing an
+     * issue about our own button and swallowing the press that was meant to end
+     * the session. Shadow DOM makes it worse rather than better: retargeting
+     * reports the event's target as the shadow HOST, so the capture would not
+     * even name the button.
+     *
+     * Injected rather than hard-coded to an id, because a hard-coded id is a
+     * second definition of who owns that node.
+     */
+    ignoreElement?: (el: Element) => boolean;
 }
 export interface AnnotationSdk {
     enable(): void;

package/dist/sdk.d.ts

@@ -1,4 +1,5 @@
-import { type AnnotationPayload, type BuildInfo } from "./protocol.js";
+import { type AnnotationPayload, type BuildInfo, type TargetInfo } from "./protocol.js";
+import { type AnnotationTransport, type EgressErrorHandler, type EgressOutcome } from "./transport.js";
 import { type ScreenshotOptions } from "./screenshot.js";
 /**
  * The annotation SDK (A-36).
@@ -11,13 +12,52 @@ export interface AnnotationState {
     failedRequests: AnnotationPayload["state"]["failedRequests"];
     featureFlags: Record<string, unknown>;
 }
+/**
+ * What the reviewer clicked, handed to whoever collects the words (A-240).
+ *
+ * The target is the RESOLVED one, taken from the payload that was already
+ * assembled — not the element, and not something to re-read. See `onClick` for
+ * why that distinction is the whole of this feature's correctness.
+ */
+export interface CommentRequest {
+    target: TargetInfo;
+    /** Viewport coordinates of the click, so a composer can sit near it. */
+    point: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Ask the human for their words (A-240).
+ *
+ * Resolves with the comment, or with `null` for cancel — and cancel means
+ * NOTHING IS SENT, which is why it is a distinct value rather than an empty
+ * string. An empty string is a reviewer who had nothing to add; `null` is a
+ * reviewer who changed their mind, and filing an issue for the second is the
+ * kind of thing that gets an annotation tool switched off.
+ *
+ * Absent, the payload keeps `comment: ""` and the frame path is unchanged: the
+ * parent window is still the thing that collects the words there.
+ */
+export type CommentCollector = (request: CommentRequest) => Promise<string | null>;
 export interface AnnotationSdkOptions {
     /**
-     * The management app's origin. Required and concrete — see
+     * The management app's origin, when there is one. Concrete — see
      * `assertConcreteOrigin`. Messages from anywhere else are ignored, and we
      * never post to anywhere else.
+     *
+     * OPTIONAL SINCE A-240, and only because first-party there is no parent to
+     * listen to. It used to be required for a reason that survives: the inbound
+     * `message` listener needs a concrete origin to compare against, and a
+     * listener with nothing to compare against is one that accepts instructions
+     * from any page that can reach this one. So the resolution is not a default
+     * origin — it is NO LISTENER AT ALL. Omitting this makes the SDK deaf to
+     * `postMessage`, which is exactly right for a page with no parent, and it is
+     * the only construction in which that is true.
+     *
+     * Supply it and the frame path is bit-for-bit what it was.
      */
-    parentOrigin: string;
+    parentOrigin?: string;
     build: BuildInfo;
     /**
      * The matched route pattern, e.g. `/pub/[slug]`.
@@ -40,6 +80,55 @@ export interface AnnotationSdkOptions {
      * else, so most clicks produce no screenshot at all, by design.
      */
     screenshot?: ScreenshotOptions | false;
+    /**
+     * How a capture leaves the page (A-239).
+     *
+     * Defaults to `postMessageTransport(parentOrigin)`, which is what this SDK
+     * has always done. Pass `httpTransport(...)` when the product is being
+     * annotated first-party, where `win.parent === win` and a posted message is
+     * received by nobody — see `transport.ts` and
+     * `docs/plans/first-party-annotation.md`.
+     */
+    transport?: AnnotationTransport;
+    /**
+     * Called when a message could not be delivered.
+     *
+     * The frame path effectively never fails, so this is new surface for the
+     * HTTP one, and it exists because the alternative is a dropped capture that
+     * looks like a successful one. With no handler the failure is logged rather
+     * than swallowed; A-240 is what puts it in front of the reviewer.
+     */
+    onEgressError?: EgressErrorHandler;
+    /**
+     * Collect the reviewer's words after a click (A-240).
+     *
+     * Omit it and the SDK behaves exactly as it did: `comment: ""`, and the
+     * parent frame merges the human's words in.
+     */
+    collectComment?: CommentCollector;
+    /**
+     * What became of the capture, plus a thunk that sends the SAME payload again.
+     *
+     * The retry re-sends what was captured rather than re-capturing: the reviewer
+     * has moved on by then — a dialog is open, a row is selected, the page has
+     * scrolled — and re-reading it would file an issue about a screen nobody
+     * complained about.
+     */
+    onCaptureResult?: (outcome: EgressOutcome, retry: () => void) => void;
+    /**
+     * Elements annotation mode must pretend it cannot see.
+     *
+     * The toolbar renders INTO THE PAGE IT IS ANNOTATING, so with annotation on,
+     * a click on *Stop* is a click on the page and would be captured — filing an
+     * issue about our own button and swallowing the press that was meant to end
+     * the session. Shadow DOM makes it worse rather than better: retargeting
+     * reports the event's target as the shadow HOST, so the capture would not
+     * even name the button.
+     *
+     * Injected rather than hard-coded to an id, because a hard-coded id is a
+     * second definition of who owns that node.
+     */
+    ignoreElement?: (el: Element) => boolean;
 }
 export interface AnnotationSdk {
     enable(): void;

package/dist/toolbar.d.cts

@@ -0,0 +1,185 @@
+import type { AnnotationSdk, AnnotationSdkOptions, CommentCollector } from "./sdk.cjs";
+import { type Arming } from "./arming.cjs";
+import type { EgressOutcome } from "./transport.cjs";
+/**
+ * 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;