@weatherboard/annotation 0.1.0

package/dist/screenshot.d.cts

@@ -0,0 +1,182 @@
+/**
+ * Screenshot capture for the annotation payload (A-31).
+ *
+ * WHAT THIS ACTUALLY CAPTURES — READ THIS BEFORE BELIEVING THE FIELD NAME.
+ * This is not a page rasteriser. It captures the bitmap of a single
+ * `<img>`, `<canvas>` or `<video>` at or around the clicked element, and
+ * nothing else. Click a heading and the payload has no screenshot.
+ *
+ * WHY NOT html2canvas, WHICH THE SPEC SUGGESTS. `spec/02` offers html2canvas or
+ * "`element.toDataURL` via an offscreen canvas where feasible". html2canvas is a
+ * runtime dependency, and this package deliberately has none — it ships
+ * TypeScript source that two repositories compile into their own bundles, so a
+ * dependency here is a dependency, a version and a licence in both of them, for
+ * a field `spec/02` itself calls a nice-to-have ("do not block Phase 1 on
+ * screenshots; the source ref is what actually matters"). The platform gives us
+ * no way to rasterise arbitrary DOM: `SVGForeignObject` cannot load
+ * cross-origin CSS or fonts, and `getDisplayMedia` prompts the user. So we
+ * implement the honest subset rather than a convincing-looking approximation,
+ * and the spec's server-side fallback — render `page.url` at `build.gitSha`
+ * headless and crop to `target.boundingBox` — remains the route to a real
+ * picture of the page.
+ *
+ * The subset is worth having on its own: "this image is the wrong one" and
+ * "this video poster is stretched" are common reports, and for those the
+ * element's own bitmap is the entire evidence.
+ *
+ * NOTHING HERE MAY BREAK A CAPTURE. Every entry point resolves rather than
+ * rejects. A tainted canvas (any cross-origin image without CORS headers, which
+ * is most of them) makes `toDataURL` throw `SecurityError`; a detached element
+ * makes `drawImage` throw; a huge bitmap makes it slow. All of those must end
+ * with `screenshot` absent from an otherwise complete payload, never with a
+ * capture the reviewer loses.
+ */
+/** The canvas surface this module needs. Narrow so tests need no browser. */
+export interface CanvasLike {
+    width: number;
+    height: number;
+    getContext(id: "2d"): CanvasContextLike | null;
+    toDataURL(type?: string, quality?: number): string;
+}
+export interface CanvasContextLike {
+    drawImage(source: unknown, dx: number, dy: number, dw: number, dh: number): void;
+}
+/**
+ * The subset of an element this module reads.
+ *
+ * Deliberately structural rather than `instanceof HTMLImageElement`: the SDK
+ * runs inside an iframe, and an element from another document fails an
+ * `instanceof` check against this realm's constructors even when it is exactly
+ * the thing we want.
+ */
+export interface CaptureCandidate {
+    tagName: string;
+    parentElement?: CaptureCandidate | null;
+    querySelector?: (selector: string) => CaptureCandidate | null;
+    /** `<img>` */
+    naturalWidth?: number;
+    naturalHeight?: number;
+    complete?: boolean;
+    /** `<video>` */
+    videoWidth?: number;
+    videoHeight?: number;
+    /** `<canvas>` */
+    width?: number;
+    height?: number;
+}
+export type Screenshot = {
+    dataUrl: string;
+    region: "element" | "viewport";
+};
+/**
+ * The byte budget for the encoded data URL.
+ *
+ * `apps/manager/src/lib/feedback/validate.ts` rejects the whole payload over
+ * `MAX_PAYLOAD_BYTES` (128KB) and names screenshots as the usual cause. 48KB
+ * leaves the rest of the payload — twenty console entries with stacks, twenty
+ * failed requests, a source chain — room to be large without the server
+ * refusing a report the reviewer has already written. A data URL is base64
+ * ASCII, so `dataUrl.length` is its byte cost in the serialised payload, near
+ * enough to compare directly.
+ *
+ * Over budget we drop the screenshot. Emitting it anyway would trade a payload
+ * with no picture for a payload the server 413s, which loses the source ref —
+ * the only part that actually matters.
+ */
+export declare const MAX_SCREENSHOT_BYTES: number;
+/**
+ * Longest edge, in device-independent pixels, of the downscaled capture.
+ *
+ * A 2000px-wide hero image encodes to well over the budget at any quality worth
+ * looking at. 480px is enough to see that the wrong photo is on the card, which
+ * is the question this field answers.
+ */
+export declare const MAX_SCREENSHOT_EDGE = 480;
+/**
+ * A ceiling on how long we will wait, not on how long the work takes.
+ *
+ * `toDataURL` is synchronous and cannot be interrupted; this bounds the wait so
+ * a pathological encode does not hold the capture open indefinitely, and the
+ * payload goes out without the screenshot instead. Said plainly because a
+ * timeout that cannot cancel its work is the kind of thing a reader assumes is
+ * stronger than it is.
+ */
+export declare const SCREENSHOT_TIMEOUT_MS = 250;
+export interface ScreenshotOptions {
+    /**
+     * Off switch. `spec/02` treats screenshots as optional, so a host that would
+     * rather not encode bitmaps on click — or that serves images this SDK would
+     * only ever taint — sets this to `false`.
+     */
+    enabled?: boolean;
+    maxBytes?: number;
+    maxEdge?: number;
+    timeoutMs?: number;
+    /**
+     * Canvas factory. Injected so the tests can drive the failure paths — taint,
+     * an oversized encode, a context that is not there — none of which are
+     * reachable from a fake DOM object alone.
+     */
+    createCanvas?: () => CanvasLike | null;
+}
+interface ResolvedOptions {
+    enabled: boolean;
+    maxBytes: number;
+    maxEdge: number;
+    timeoutMs: number;
+    createCanvas: () => CanvasLike | null;
+}
+export declare function resolveScreenshotOptions(options: ScreenshotOptions | false | undefined, doc?: Document): ResolvedOptions;
+export declare function isMediaElement(el: CaptureCandidate | null | undefined): boolean;
+/**
+ * The nearest thing with a bitmap: the element itself, then a descendant, then
+ * an ancestor.
+ *
+ * Descendant before ancestor because a click lands on whatever is topmost, and
+ * on a card that is usually the overlay or the link wrapping the photo — the
+ * photo the reviewer means is inside it, not above it.
+ */
+export declare function findCaptureSource(el: CaptureCandidate | null, maxHops?: number): CaptureCandidate | null;
+/**
+ * The source's own pixel dimensions, or null if it has none.
+ *
+ * A broken `<img>` reports `naturalWidth === 0`, and that is the honest answer:
+ * there is no bitmap to capture. The report still carries the source ref and
+ * the DOM path, which is what a "this image is broken" ticket needs anyway.
+ */
+export declare function intrinsicSize(el: CaptureCandidate): {
+    w: number;
+    h: number;
+} | null;
+/** Fit inside `maxEdge` without ever upscaling — enlarging invents detail. */
+export declare function fitWithin(size: {
+    w: number;
+    h: number;
+}, maxEdge: number): {
+    w: number;
+    h: number;
+};
+/**
+ * Capture synchronously, or return null. Exported for the tests, which need to
+ * assert the drop decisions without a timer in the way.
+ */
+export declare function captureScreenshotSync(el: CaptureCandidate | null, options: ResolvedOptions): Screenshot | null;
+/**
+ * The entry point the SDK calls. Resolves to a screenshot or to null, within
+ * `timeoutMs`, and never rejects.
+ */
+export declare function captureScreenshot(el: CaptureCandidate | null, options: ResolvedOptions): Promise<Screenshot | null>;
+/**
+ * Merge a capture into a payload, or hand the payload back untouched.
+ *
+ * The payload goes in already complete and comes out still complete. The
+ * failure mode this shape exists to make impossible is a screenshot problem
+ * costing the reviewer the source ref — so the payload is never awaited into
+ * existence, only decorated, and `screenshot` is added as a key or not at all
+ * rather than set to `undefined` (which `JSON.stringify` drops anyway, but
+ * which reads as "we tried and got nothing" to anyone inspecting the object).
+ */
+export declare function attachScreenshot<T extends object>(payload: T, el: CaptureCandidate | null, options: ResolvedOptions): Promise<T & {
+    screenshot?: Screenshot;
+}>;
+export {};

package/dist/screenshot.d.mts

@@ -0,0 +1,182 @@
+/**
+ * Screenshot capture for the annotation payload (A-31).
+ *
+ * WHAT THIS ACTUALLY CAPTURES — READ THIS BEFORE BELIEVING THE FIELD NAME.
+ * This is not a page rasteriser. It captures the bitmap of a single
+ * `<img>`, `<canvas>` or `<video>` at or around the clicked element, and
+ * nothing else. Click a heading and the payload has no screenshot.
+ *
+ * WHY NOT html2canvas, WHICH THE SPEC SUGGESTS. `spec/02` offers html2canvas or
+ * "`element.toDataURL` via an offscreen canvas where feasible". html2canvas is a
+ * runtime dependency, and this package deliberately has none — it ships
+ * TypeScript source that two repositories compile into their own bundles, so a
+ * dependency here is a dependency, a version and a licence in both of them, for
+ * a field `spec/02` itself calls a nice-to-have ("do not block Phase 1 on
+ * screenshots; the source ref is what actually matters"). The platform gives us
+ * no way to rasterise arbitrary DOM: `SVGForeignObject` cannot load
+ * cross-origin CSS or fonts, and `getDisplayMedia` prompts the user. So we
+ * implement the honest subset rather than a convincing-looking approximation,
+ * and the spec's server-side fallback — render `page.url` at `build.gitSha`
+ * headless and crop to `target.boundingBox` — remains the route to a real
+ * picture of the page.
+ *
+ * The subset is worth having on its own: "this image is the wrong one" and
+ * "this video poster is stretched" are common reports, and for those the
+ * element's own bitmap is the entire evidence.
+ *
+ * NOTHING HERE MAY BREAK A CAPTURE. Every entry point resolves rather than
+ * rejects. A tainted canvas (any cross-origin image without CORS headers, which
+ * is most of them) makes `toDataURL` throw `SecurityError`; a detached element
+ * makes `drawImage` throw; a huge bitmap makes it slow. All of those must end
+ * with `screenshot` absent from an otherwise complete payload, never with a
+ * capture the reviewer loses.
+ */
+/** The canvas surface this module needs. Narrow so tests need no browser. */
+export interface CanvasLike {
+    width: number;
+    height: number;
+    getContext(id: "2d"): CanvasContextLike | null;
+    toDataURL(type?: string, quality?: number): string;
+}
+export interface CanvasContextLike {
+    drawImage(source: unknown, dx: number, dy: number, dw: number, dh: number): void;
+}
+/**
+ * The subset of an element this module reads.
+ *
+ * Deliberately structural rather than `instanceof HTMLImageElement`: the SDK
+ * runs inside an iframe, and an element from another document fails an
+ * `instanceof` check against this realm's constructors even when it is exactly
+ * the thing we want.
+ */
+export interface CaptureCandidate {
+    tagName: string;
+    parentElement?: CaptureCandidate | null;
+    querySelector?: (selector: string) => CaptureCandidate | null;
+    /** `<img>` */
+    naturalWidth?: number;
+    naturalHeight?: number;
+    complete?: boolean;
+    /** `<video>` */
+    videoWidth?: number;
+    videoHeight?: number;
+    /** `<canvas>` */
+    width?: number;
+    height?: number;
+}
+export type Screenshot = {
+    dataUrl: string;
+    region: "element" | "viewport";
+};
+/**
+ * The byte budget for the encoded data URL.
+ *
+ * `apps/manager/src/lib/feedback/validate.ts` rejects the whole payload over
+ * `MAX_PAYLOAD_BYTES` (128KB) and names screenshots as the usual cause. 48KB
+ * leaves the rest of the payload — twenty console entries with stacks, twenty
+ * failed requests, a source chain — room to be large without the server
+ * refusing a report the reviewer has already written. A data URL is base64
+ * ASCII, so `dataUrl.length` is its byte cost in the serialised payload, near
+ * enough to compare directly.
+ *
+ * Over budget we drop the screenshot. Emitting it anyway would trade a payload
+ * with no picture for a payload the server 413s, which loses the source ref —
+ * the only part that actually matters.
+ */
+export declare const MAX_SCREENSHOT_BYTES: number;
+/**
+ * Longest edge, in device-independent pixels, of the downscaled capture.
+ *
+ * A 2000px-wide hero image encodes to well over the budget at any quality worth
+ * looking at. 480px is enough to see that the wrong photo is on the card, which
+ * is the question this field answers.
+ */
+export declare const MAX_SCREENSHOT_EDGE = 480;
+/**
+ * A ceiling on how long we will wait, not on how long the work takes.
+ *
+ * `toDataURL` is synchronous and cannot be interrupted; this bounds the wait so
+ * a pathological encode does not hold the capture open indefinitely, and the
+ * payload goes out without the screenshot instead. Said plainly because a
+ * timeout that cannot cancel its work is the kind of thing a reader assumes is
+ * stronger than it is.
+ */
+export declare const SCREENSHOT_TIMEOUT_MS = 250;
+export interface ScreenshotOptions {
+    /**
+     * Off switch. `spec/02` treats screenshots as optional, so a host that would
+     * rather not encode bitmaps on click — or that serves images this SDK would
+     * only ever taint — sets this to `false`.
+     */
+    enabled?: boolean;
+    maxBytes?: number;
+    maxEdge?: number;
+    timeoutMs?: number;
+    /**
+     * Canvas factory. Injected so the tests can drive the failure paths — taint,
+     * an oversized encode, a context that is not there — none of which are
+     * reachable from a fake DOM object alone.
+     */
+    createCanvas?: () => CanvasLike | null;
+}
+interface ResolvedOptions {
+    enabled: boolean;
+    maxBytes: number;
+    maxEdge: number;
+    timeoutMs: number;
+    createCanvas: () => CanvasLike | null;
+}
+export declare function resolveScreenshotOptions(options: ScreenshotOptions | false | undefined, doc?: Document): ResolvedOptions;
+export declare function isMediaElement(el: CaptureCandidate | null | undefined): boolean;
+/**
+ * The nearest thing with a bitmap: the element itself, then a descendant, then
+ * an ancestor.
+ *
+ * Descendant before ancestor because a click lands on whatever is topmost, and
+ * on a card that is usually the overlay or the link wrapping the photo — the
+ * photo the reviewer means is inside it, not above it.
+ */
+export declare function findCaptureSource(el: CaptureCandidate | null, maxHops?: number): CaptureCandidate | null;
+/**
+ * The source's own pixel dimensions, or null if it has none.
+ *
+ * A broken `<img>` reports `naturalWidth === 0`, and that is the honest answer:
+ * there is no bitmap to capture. The report still carries the source ref and
+ * the DOM path, which is what a "this image is broken" ticket needs anyway.
+ */
+export declare function intrinsicSize(el: CaptureCandidate): {
+    w: number;
+    h: number;
+} | null;
+/** Fit inside `maxEdge` without ever upscaling — enlarging invents detail. */
+export declare function fitWithin(size: {
+    w: number;
+    h: number;
+}, maxEdge: number): {
+    w: number;
+    h: number;
+};
+/**
+ * Capture synchronously, or return null. Exported for the tests, which need to
+ * assert the drop decisions without a timer in the way.
+ */
+export declare function captureScreenshotSync(el: CaptureCandidate | null, options: ResolvedOptions): Screenshot | null;
+/**
+ * The entry point the SDK calls. Resolves to a screenshot or to null, within
+ * `timeoutMs`, and never rejects.
+ */
+export declare function captureScreenshot(el: CaptureCandidate | null, options: ResolvedOptions): Promise<Screenshot | null>;
+/**
+ * Merge a capture into a payload, or hand the payload back untouched.
+ *
+ * The payload goes in already complete and comes out still complete. The
+ * failure mode this shape exists to make impossible is a screenshot problem
+ * costing the reviewer the source ref — so the payload is never awaited into
+ * existence, only decorated, and `screenshot` is added as a key or not at all
+ * rather than set to `undefined` (which `JSON.stringify` drops anyway, but
+ * which reads as "we tried and got nothing" to anyone inspecting the object).
+ */
+export declare function attachScreenshot<T extends object>(payload: T, el: CaptureCandidate | null, options: ResolvedOptions): Promise<T & {
+    screenshot?: Screenshot;
+}>;
+export {};

package/dist/screenshot.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Screenshot capture for the annotation payload (A-31).
+ *
+ * WHAT THIS ACTUALLY CAPTURES — READ THIS BEFORE BELIEVING THE FIELD NAME.
+ * This is not a page rasteriser. It captures the bitmap of a single
+ * `<img>`, `<canvas>` or `<video>` at or around the clicked element, and
+ * nothing else. Click a heading and the payload has no screenshot.
+ *
+ * WHY NOT html2canvas, WHICH THE SPEC SUGGESTS. `spec/02` offers html2canvas or
+ * "`element.toDataURL` via an offscreen canvas where feasible". html2canvas is a
+ * runtime dependency, and this package deliberately has none — it ships
+ * TypeScript source that two repositories compile into their own bundles, so a
+ * dependency here is a dependency, a version and a licence in both of them, for
+ * a field `spec/02` itself calls a nice-to-have ("do not block Phase 1 on
+ * screenshots; the source ref is what actually matters"). The platform gives us
+ * no way to rasterise arbitrary DOM: `SVGForeignObject` cannot load
+ * cross-origin CSS or fonts, and `getDisplayMedia` prompts the user. So we
+ * implement the honest subset rather than a convincing-looking approximation,
+ * and the spec's server-side fallback — render `page.url` at `build.gitSha`
+ * headless and crop to `target.boundingBox` — remains the route to a real
+ * picture of the page.
+ *
+ * The subset is worth having on its own: "this image is the wrong one" and
+ * "this video poster is stretched" are common reports, and for those the
+ * element's own bitmap is the entire evidence.
+ *
+ * NOTHING HERE MAY BREAK A CAPTURE. Every entry point resolves rather than
+ * rejects. A tainted canvas (any cross-origin image without CORS headers, which
+ * is most of them) makes `toDataURL` throw `SecurityError`; a detached element
+ * makes `drawImage` throw; a huge bitmap makes it slow. All of those must end
+ * with `screenshot` absent from an otherwise complete payload, never with a
+ * capture the reviewer loses.
+ */
+/** The canvas surface this module needs. Narrow so tests need no browser. */
+export interface CanvasLike {
+    width: number;
+    height: number;
+    getContext(id: "2d"): CanvasContextLike | null;
+    toDataURL(type?: string, quality?: number): string;
+}
+export interface CanvasContextLike {
+    drawImage(source: unknown, dx: number, dy: number, dw: number, dh: number): void;
+}
+/**
+ * The subset of an element this module reads.
+ *
+ * Deliberately structural rather than `instanceof HTMLImageElement`: the SDK
+ * runs inside an iframe, and an element from another document fails an
+ * `instanceof` check against this realm's constructors even when it is exactly
+ * the thing we want.
+ */
+export interface CaptureCandidate {
+    tagName: string;
+    parentElement?: CaptureCandidate | null;
+    querySelector?: (selector: string) => CaptureCandidate | null;
+    /** `<img>` */
+    naturalWidth?: number;
+    naturalHeight?: number;
+    complete?: boolean;
+    /** `<video>` */
+    videoWidth?: number;
+    videoHeight?: number;
+    /** `<canvas>` */
+    width?: number;
+    height?: number;
+}
+export type Screenshot = {
+    dataUrl: string;
+    region: "element" | "viewport";
+};
+/**
+ * The byte budget for the encoded data URL.
+ *
+ * `apps/manager/src/lib/feedback/validate.ts` rejects the whole payload over
+ * `MAX_PAYLOAD_BYTES` (128KB) and names screenshots as the usual cause. 48KB
+ * leaves the rest of the payload — twenty console entries with stacks, twenty
+ * failed requests, a source chain — room to be large without the server
+ * refusing a report the reviewer has already written. A data URL is base64
+ * ASCII, so `dataUrl.length` is its byte cost in the serialised payload, near
+ * enough to compare directly.
+ *
+ * Over budget we drop the screenshot. Emitting it anyway would trade a payload
+ * with no picture for a payload the server 413s, which loses the source ref —
+ * the only part that actually matters.
+ */
+export declare const MAX_SCREENSHOT_BYTES: number;
+/**
+ * Longest edge, in device-independent pixels, of the downscaled capture.
+ *
+ * A 2000px-wide hero image encodes to well over the budget at any quality worth
+ * looking at. 480px is enough to see that the wrong photo is on the card, which
+ * is the question this field answers.
+ */
+export declare const MAX_SCREENSHOT_EDGE = 480;
+/**
+ * A ceiling on how long we will wait, not on how long the work takes.
+ *
+ * `toDataURL` is synchronous and cannot be interrupted; this bounds the wait so
+ * a pathological encode does not hold the capture open indefinitely, and the
+ * payload goes out without the screenshot instead. Said plainly because a
+ * timeout that cannot cancel its work is the kind of thing a reader assumes is
+ * stronger than it is.
+ */
+export declare const SCREENSHOT_TIMEOUT_MS = 250;
+export interface ScreenshotOptions {
+    /**
+     * Off switch. `spec/02` treats screenshots as optional, so a host that would
+     * rather not encode bitmaps on click — or that serves images this SDK would
+     * only ever taint — sets this to `false`.
+     */
+    enabled?: boolean;
+    maxBytes?: number;
+    maxEdge?: number;
+    timeoutMs?: number;
+    /**
+     * Canvas factory. Injected so the tests can drive the failure paths — taint,
+     * an oversized encode, a context that is not there — none of which are
+     * reachable from a fake DOM object alone.
+     */
+    createCanvas?: () => CanvasLike | null;
+}
+interface ResolvedOptions {
+    enabled: boolean;
+    maxBytes: number;
+    maxEdge: number;
+    timeoutMs: number;
+    createCanvas: () => CanvasLike | null;
+}
+export declare function resolveScreenshotOptions(options: ScreenshotOptions | false | undefined, doc?: Document): ResolvedOptions;
+export declare function isMediaElement(el: CaptureCandidate | null | undefined): boolean;
+/**
+ * The nearest thing with a bitmap: the element itself, then a descendant, then
+ * an ancestor.
+ *
+ * Descendant before ancestor because a click lands on whatever is topmost, and
+ * on a card that is usually the overlay or the link wrapping the photo — the
+ * photo the reviewer means is inside it, not above it.
+ */
+export declare function findCaptureSource(el: CaptureCandidate | null, maxHops?: number): CaptureCandidate | null;
+/**
+ * The source's own pixel dimensions, or null if it has none.
+ *
+ * A broken `<img>` reports `naturalWidth === 0`, and that is the honest answer:
+ * there is no bitmap to capture. The report still carries the source ref and
+ * the DOM path, which is what a "this image is broken" ticket needs anyway.
+ */
+export declare function intrinsicSize(el: CaptureCandidate): {
+    w: number;
+    h: number;
+} | null;
+/** Fit inside `maxEdge` without ever upscaling — enlarging invents detail. */
+export declare function fitWithin(size: {
+    w: number;
+    h: number;
+}, maxEdge: number): {
+    w: number;
+    h: number;
+};
+/**
+ * Capture synchronously, or return null. Exported for the tests, which need to
+ * assert the drop decisions without a timer in the way.
+ */
+export declare function captureScreenshotSync(el: CaptureCandidate | null, options: ResolvedOptions): Screenshot | null;
+/**
+ * The entry point the SDK calls. Resolves to a screenshot or to null, within
+ * `timeoutMs`, and never rejects.
+ */
+export declare function captureScreenshot(el: CaptureCandidate | null, options: ResolvedOptions): Promise<Screenshot | null>;
+/**
+ * Merge a capture into a payload, or hand the payload back untouched.
+ *
+ * The payload goes in already complete and comes out still complete. The
+ * failure mode this shape exists to make impossible is a screenshot problem
+ * costing the reviewer the source ref — so the payload is never awaited into
+ * existence, only decorated, and `screenshot` is added as a key or not at all
+ * rather than set to `undefined` (which `JSON.stringify` drops anyway, but
+ * which reads as "we tried and got nothing" to anyone inspecting the object).
+ */
+export declare function attachScreenshot<T extends object>(payload: T, el: CaptureCandidate | null, options: ResolvedOptions): Promise<T & {
+    screenshot?: Screenshot;
+}>;
+export {};

package/dist/sdk.d.cts

@@ -0,0 +1,52 @@
+import { type AnnotationPayload, type BuildInfo } from "./protocol.cjs";
+import { type ScreenshotOptions } from "./screenshot.cjs";
+/**
+ * The annotation SDK (A-36).
+ *
+ * Lives in the product bundle, listens for the management app's instructions,
+ * and turns a click into a payload pinned to a code location.
+ */
+export interface AnnotationState {
+    consoleErrors: AnnotationPayload["state"]["consoleErrors"];
+    failedRequests: AnnotationPayload["state"]["failedRequests"];
+    featureFlags: Record<string, unknown>;
+}
+export interface AnnotationSdkOptions {
+    /**
+     * The management app's origin. Required and concrete — see
+     * `assertConcreteOrigin`. Messages from anywhere else are ignored, and we
+     * never post to anywhere else.
+     */
+    parentOrigin: string;
+    build: BuildInfo;
+    /**
+     * The matched route pattern, e.g. `/pub/[slug]`.
+     *
+     * Injected rather than derived: only the app knows its own route patterns,
+     * and `location.pathname` is the resolved URL, which is what the spec
+     * explicitly does not want — `/pub/the-eagle` and `/pub/the-crown` are the
+     * same route and should group as one.
+     */
+    getRoute: () => string;
+    /**
+     * Page state at capture time. Injected so A-35's ring buffers can supply the
+     * real thing without this module knowing how they are collected.
+     */
+    getState: () => AnnotationState;
+    /**
+     * Screenshot capture (A-31). Omit for the default, or pass `false` to turn it
+     * off entirely. See `screenshot.ts` for what it can and cannot capture — the
+     * short version is that it captures a media element's own bitmap and nothing
+     * else, so most clicks produce no screenshot at all, by design.
+     */
+    screenshot?: ScreenshotOptions | false;
+}
+export interface AnnotationSdk {
+    enable(): void;
+    disable(): void;
+    isEnabled(): boolean;
+    destroy(): void;
+}
+/** State until A-35 lands its ring buffers. Empty is honest; invented is not. */
+export declare const emptyAnnotationState: () => AnnotationState;
+export declare function createAnnotationSdk(options: AnnotationSdkOptions): AnnotationSdk;

package/dist/sdk.d.mts

@@ -0,0 +1,52 @@
+import { type AnnotationPayload, type BuildInfo } from "./protocol.mjs";
+import { type ScreenshotOptions } from "./screenshot.mjs";
+/**
+ * The annotation SDK (A-36).
+ *
+ * Lives in the product bundle, listens for the management app's instructions,
+ * and turns a click into a payload pinned to a code location.
+ */
+export interface AnnotationState {
+    consoleErrors: AnnotationPayload["state"]["consoleErrors"];
+    failedRequests: AnnotationPayload["state"]["failedRequests"];
+    featureFlags: Record<string, unknown>;
+}
+export interface AnnotationSdkOptions {
+    /**
+     * The management app's origin. Required and concrete — see
+     * `assertConcreteOrigin`. Messages from anywhere else are ignored, and we
+     * never post to anywhere else.
+     */
+    parentOrigin: string;
+    build: BuildInfo;
+    /**
+     * The matched route pattern, e.g. `/pub/[slug]`.
+     *
+     * Injected rather than derived: only the app knows its own route patterns,
+     * and `location.pathname` is the resolved URL, which is what the spec
+     * explicitly does not want — `/pub/the-eagle` and `/pub/the-crown` are the
+     * same route and should group as one.
+     */
+    getRoute: () => string;
+    /**
+     * Page state at capture time. Injected so A-35's ring buffers can supply the
+     * real thing without this module knowing how they are collected.
+     */
+    getState: () => AnnotationState;
+    /**
+     * Screenshot capture (A-31). Omit for the default, or pass `false` to turn it
+     * off entirely. See `screenshot.ts` for what it can and cannot capture — the
+     * short version is that it captures a media element's own bitmap and nothing
+     * else, so most clicks produce no screenshot at all, by design.
+     */
+    screenshot?: ScreenshotOptions | false;
+}
+export interface AnnotationSdk {
+    enable(): void;
+    disable(): void;
+    isEnabled(): boolean;
+    destroy(): void;
+}
+/** State until A-35 lands its ring buffers. Empty is honest; invented is not. */
+export declare const emptyAnnotationState: () => AnnotationState;
+export declare function createAnnotationSdk(options: AnnotationSdkOptions): AnnotationSdk;