@weatherboard/annotation 0.1.0

package/dist/sdk.d.ts

@@ -0,0 +1,52 @@
+import { type AnnotationPayload, type BuildInfo } from "./protocol.js";
+import { type ScreenshotOptions } from "./screenshot.js";
+/**
+ * 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/state.d.cts

@@ -0,0 +1,62 @@
+import type { AnnotationState } from "./sdk.cjs";
+/**
+ * Page state, captured continuously (A-35).
+ *
+ * The timing is the whole point. By the time someone notices something is wrong
+ * and clicks it, the interesting error has already happened — reading
+ * `console` at capture time gets you nothing, because there is nothing to read.
+ * So the buffers fill from page load and the click just takes a copy.
+ *
+ * Which means this code runs on every page, for every user in the enabled
+ * environments, in front of the app's own error handling. It is written to be
+ * boring: patch, record, call through, never throw.
+ */
+/** Twenty each, per the spec. Enough for context, small enough to post. */
+export declare const DEFAULT_LIMIT = 20;
+/**
+ * A fixed-size window over the most recent N items.
+ *
+ * Oldest-out rather than newest-dropped: a page that logs steadily would
+ * otherwise pin the buffer to whatever happened at boot and never show the
+ * error the reviewer is looking at.
+ */
+export declare class RingBuffer<T> {
+    #private;
+    constructor(limit?: number);
+    push(item: T): void;
+    /** A copy, so a consumer holding the payload cannot see it mutate underneath them. */
+    toArray(): T[];
+    get size(): number;
+}
+/**
+ * Render one console argument as text, without ever throwing.
+ *
+ * Console arguments are arbitrary: DOM nodes, circular objects, proxies that
+ * throw on property access. Anything that fails here would fail *inside the
+ * app's own `console.error` call*, turning a logged error into a thrown one.
+ */
+export declare function describeArg(arg: unknown): string;
+export declare function formatConsoleArgs(args: unknown[]): string;
+/** The first `Error` among the arguments carries the only stack worth keeping. */
+export declare function firstStack(args: unknown[]): string | undefined;
+/** A response is interesting when it is not 2xx. `0` marks a request that never got one. */
+export declare function isFailedStatus(status: number): boolean;
+export interface StateCollector {
+    getState(): AnnotationState;
+    /** Restore every patched global. Exposed mainly so tests can prove it is reversible. */
+    destroy(): void;
+}
+export interface StateCollectorOptions {
+    limit: number;
+    /** Feature flags are the app's to know; this module does not guess at them. */
+    getFeatureFlags: () => Record<string, unknown>;
+    now: () => string;
+}
+export declare const defaultStateCollectorOptions: () => StateCollectorOptions;
+/**
+ * Patch `console`, `fetch` and `XMLHttpRequest`, and record what goes wrong.
+ *
+ * Install this as early as the bundle allows — an error thrown before the patch
+ * is an error the payload will not carry.
+ */
+export declare function installStateCollector(win: Window & typeof globalThis, options?: StateCollectorOptions): StateCollector;

package/dist/state.d.mts

@@ -0,0 +1,62 @@
+import type { AnnotationState } from "./sdk.mjs";
+/**
+ * Page state, captured continuously (A-35).
+ *
+ * The timing is the whole point. By the time someone notices something is wrong
+ * and clicks it, the interesting error has already happened — reading
+ * `console` at capture time gets you nothing, because there is nothing to read.
+ * So the buffers fill from page load and the click just takes a copy.
+ *
+ * Which means this code runs on every page, for every user in the enabled
+ * environments, in front of the app's own error handling. It is written to be
+ * boring: patch, record, call through, never throw.
+ */
+/** Twenty each, per the spec. Enough for context, small enough to post. */
+export declare const DEFAULT_LIMIT = 20;
+/**
+ * A fixed-size window over the most recent N items.
+ *
+ * Oldest-out rather than newest-dropped: a page that logs steadily would
+ * otherwise pin the buffer to whatever happened at boot and never show the
+ * error the reviewer is looking at.
+ */
+export declare class RingBuffer<T> {
+    #private;
+    constructor(limit?: number);
+    push(item: T): void;
+    /** A copy, so a consumer holding the payload cannot see it mutate underneath them. */
+    toArray(): T[];
+    get size(): number;
+}
+/**
+ * Render one console argument as text, without ever throwing.
+ *
+ * Console arguments are arbitrary: DOM nodes, circular objects, proxies that
+ * throw on property access. Anything that fails here would fail *inside the
+ * app's own `console.error` call*, turning a logged error into a thrown one.
+ */
+export declare function describeArg(arg: unknown): string;
+export declare function formatConsoleArgs(args: unknown[]): string;
+/** The first `Error` among the arguments carries the only stack worth keeping. */
+export declare function firstStack(args: unknown[]): string | undefined;
+/** A response is interesting when it is not 2xx. `0` marks a request that never got one. */
+export declare function isFailedStatus(status: number): boolean;
+export interface StateCollector {
+    getState(): AnnotationState;
+    /** Restore every patched global. Exposed mainly so tests can prove it is reversible. */
+    destroy(): void;
+}
+export interface StateCollectorOptions {
+    limit: number;
+    /** Feature flags are the app's to know; this module does not guess at them. */
+    getFeatureFlags: () => Record<string, unknown>;
+    now: () => string;
+}
+export declare const defaultStateCollectorOptions: () => StateCollectorOptions;
+/**
+ * Patch `console`, `fetch` and `XMLHttpRequest`, and record what goes wrong.
+ *
+ * Install this as early as the bundle allows — an error thrown before the patch
+ * is an error the payload will not carry.
+ */
+export declare function installStateCollector(win: Window & typeof globalThis, options?: StateCollectorOptions): StateCollector;

package/dist/state.d.ts

@@ -0,0 +1,62 @@
+import type { AnnotationState } from "./sdk.js";
+/**
+ * Page state, captured continuously (A-35).
+ *
+ * The timing is the whole point. By the time someone notices something is wrong
+ * and clicks it, the interesting error has already happened — reading
+ * `console` at capture time gets you nothing, because there is nothing to read.
+ * So the buffers fill from page load and the click just takes a copy.
+ *
+ * Which means this code runs on every page, for every user in the enabled
+ * environments, in front of the app's own error handling. It is written to be
+ * boring: patch, record, call through, never throw.
+ */
+/** Twenty each, per the spec. Enough for context, small enough to post. */
+export declare const DEFAULT_LIMIT = 20;
+/**
+ * A fixed-size window over the most recent N items.
+ *
+ * Oldest-out rather than newest-dropped: a page that logs steadily would
+ * otherwise pin the buffer to whatever happened at boot and never show the
+ * error the reviewer is looking at.
+ */
+export declare class RingBuffer<T> {
+    #private;
+    constructor(limit?: number);
+    push(item: T): void;
+    /** A copy, so a consumer holding the payload cannot see it mutate underneath them. */
+    toArray(): T[];
+    get size(): number;
+}
+/**
+ * Render one console argument as text, without ever throwing.
+ *
+ * Console arguments are arbitrary: DOM nodes, circular objects, proxies that
+ * throw on property access. Anything that fails here would fail *inside the
+ * app's own `console.error` call*, turning a logged error into a thrown one.
+ */
+export declare function describeArg(arg: unknown): string;
+export declare function formatConsoleArgs(args: unknown[]): string;
+/** The first `Error` among the arguments carries the only stack worth keeping. */
+export declare function firstStack(args: unknown[]): string | undefined;
+/** A response is interesting when it is not 2xx. `0` marks a request that never got one. */
+export declare function isFailedStatus(status: number): boolean;
+export interface StateCollector {
+    getState(): AnnotationState;
+    /** Restore every patched global. Exposed mainly so tests can prove it is reversible. */
+    destroy(): void;
+}
+export interface StateCollectorOptions {
+    limit: number;
+    /** Feature flags are the app's to know; this module does not guess at them. */
+    getFeatureFlags: () => Record<string, unknown>;
+    now: () => string;
+}
+export declare const defaultStateCollectorOptions: () => StateCollectorOptions;
+/**
+ * Patch `console`, `fetch` and `XMLHttpRequest`, and record what goes wrong.
+ *
+ * Install this as early as the bundle allows — an error thrown before the patch
+ * is an error the payload will not carry.
+ */
+export declare function installStateCollector(win: Window & typeof globalThis, options?: StateCollectorOptions): StateCollector;

package/dist/target.d.cts

@@ -0,0 +1,74 @@
+import { NAME_ATTR, SRC_ATTR, type SourceRef, type TargetInfo } from "./protocol.cjs";
+/**
+ * Turning a clicked DOM element into something a coding agent can act on.
+ *
+ * Everything here is written against the narrowest possible slice of the DOM so
+ * it can be tested without a browser — see `ElementLike`. The parts that need a
+ * real browser (hit-testing, layout) live in `sdk.ts`.
+ */
+/**
+ * Re-exported, not declared. They moved to `protocol.ts` (A-186) because the
+ * build transform in `@weatherboard/annotation-next` writes what this file
+ * reads, and the two packages install separately. Kept exported from here so
+ * every existing importer is unaffected.
+ */
+export { NAME_ATTR, SRC_ATTR };
+export declare const MAX_TEXT = 200;
+/** Deep trees are common; a chain long enough to be useless is not worth sending. */
+export declare const MAX_CHAIN = 8;
+/** The subset of `Element` this module reads. */
+export interface ElementLike {
+    tagName: string;
+    id?: string;
+    getAttribute(name: string): string | null;
+    parentElement: ElementLike | null;
+    classList?: {
+        value?: string;
+    } | ArrayLike<string>;
+    textContent?: string | null;
+}
+/**
+ * Parse `path/to/File.tsx:42:7` into its parts.
+ *
+ * Split from the right: the line and column never contain a colon, and a path
+ * conceivably might. Returns null rather than a half-parsed ref — a ref we
+ * cannot read is worse than no ref, because downstream will believe it.
+ */
+export declare function parseSourceRef(value: string | null): SourceRef | null;
+/**
+ * Every source ref from `el` upwards, innermost first.
+ *
+ * Consecutive duplicates are collapsed: one JSX element often produces several
+ * nested DOM nodes carrying the same ref, and repeating it says nothing.
+ */
+export declare function collectSourceChain(el: ElementLike | null, max?: number): SourceRef[];
+/** The nearest ancestor (or self) carrying a ref, which is the element a human means. */
+export declare function findAnnotatedAncestor(el: ElementLike | null): ElementLike | null;
+/**
+ * A CSS-ish path to the element, used only when no ancestor carries a ref.
+ *
+ * Deliberately not guaranteed unique. It is a hint for a human reading the
+ * payload, not a selector we promise to re-resolve — StyleX class names are
+ * hashed and change between builds, so a path that looks precise would be
+ * quietly wrong on the next deploy. IDs are kept because they survive; classes
+ * are capped at two for readability.
+ */
+export declare function domPath(el: ElementLike | null, maxDepth?: number): string;
+/** Collapse whitespace and truncate, so the payload carries a label rather than a page. */
+export declare function summariseText(text: string | null | undefined): string | undefined;
+export interface ResolveTargetOptions {
+    boundingBox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/**
+ * Build the `TargetInfo` for a clicked or hovered element.
+ *
+ * `source` is the nearest ref, which names the file that writes the markup —
+ * for a composed design-system component that is the design-system file, not
+ * the call site. `sourceChain` carries the rest so the agent can choose.
+ */
+export declare function resolveTarget(el: ElementLike, options: ResolveTargetOptions): TargetInfo;

package/dist/target.d.mts

@@ -0,0 +1,74 @@
+import { NAME_ATTR, SRC_ATTR, type SourceRef, type TargetInfo } from "./protocol.mjs";
+/**
+ * Turning a clicked DOM element into something a coding agent can act on.
+ *
+ * Everything here is written against the narrowest possible slice of the DOM so
+ * it can be tested without a browser — see `ElementLike`. The parts that need a
+ * real browser (hit-testing, layout) live in `sdk.ts`.
+ */
+/**
+ * Re-exported, not declared. They moved to `protocol.ts` (A-186) because the
+ * build transform in `@weatherboard/annotation-next` writes what this file
+ * reads, and the two packages install separately. Kept exported from here so
+ * every existing importer is unaffected.
+ */
+export { NAME_ATTR, SRC_ATTR };
+export declare const MAX_TEXT = 200;
+/** Deep trees are common; a chain long enough to be useless is not worth sending. */
+export declare const MAX_CHAIN = 8;
+/** The subset of `Element` this module reads. */
+export interface ElementLike {
+    tagName: string;
+    id?: string;
+    getAttribute(name: string): string | null;
+    parentElement: ElementLike | null;
+    classList?: {
+        value?: string;
+    } | ArrayLike<string>;
+    textContent?: string | null;
+}
+/**
+ * Parse `path/to/File.tsx:42:7` into its parts.
+ *
+ * Split from the right: the line and column never contain a colon, and a path
+ * conceivably might. Returns null rather than a half-parsed ref — a ref we
+ * cannot read is worse than no ref, because downstream will believe it.
+ */
+export declare function parseSourceRef(value: string | null): SourceRef | null;
+/**
+ * Every source ref from `el` upwards, innermost first.
+ *
+ * Consecutive duplicates are collapsed: one JSX element often produces several
+ * nested DOM nodes carrying the same ref, and repeating it says nothing.
+ */
+export declare function collectSourceChain(el: ElementLike | null, max?: number): SourceRef[];
+/** The nearest ancestor (or self) carrying a ref, which is the element a human means. */
+export declare function findAnnotatedAncestor(el: ElementLike | null): ElementLike | null;
+/**
+ * A CSS-ish path to the element, used only when no ancestor carries a ref.
+ *
+ * Deliberately not guaranteed unique. It is a hint for a human reading the
+ * payload, not a selector we promise to re-resolve — StyleX class names are
+ * hashed and change between builds, so a path that looks precise would be
+ * quietly wrong on the next deploy. IDs are kept because they survive; classes
+ * are capped at two for readability.
+ */
+export declare function domPath(el: ElementLike | null, maxDepth?: number): string;
+/** Collapse whitespace and truncate, so the payload carries a label rather than a page. */
+export declare function summariseText(text: string | null | undefined): string | undefined;
+export interface ResolveTargetOptions {
+    boundingBox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/**
+ * Build the `TargetInfo` for a clicked or hovered element.
+ *
+ * `source` is the nearest ref, which names the file that writes the markup —
+ * for a composed design-system component that is the design-system file, not
+ * the call site. `sourceChain` carries the rest so the agent can choose.
+ */
+export declare function resolveTarget(el: ElementLike, options: ResolveTargetOptions): TargetInfo;

package/dist/target.d.ts

@@ -0,0 +1,74 @@
+import { NAME_ATTR, SRC_ATTR, type SourceRef, type TargetInfo } from "./protocol.js";
+/**
+ * Turning a clicked DOM element into something a coding agent can act on.
+ *
+ * Everything here is written against the narrowest possible slice of the DOM so
+ * it can be tested without a browser — see `ElementLike`. The parts that need a
+ * real browser (hit-testing, layout) live in `sdk.ts`.
+ */
+/**
+ * Re-exported, not declared. They moved to `protocol.ts` (A-186) because the
+ * build transform in `@weatherboard/annotation-next` writes what this file
+ * reads, and the two packages install separately. Kept exported from here so
+ * every existing importer is unaffected.
+ */
+export { NAME_ATTR, SRC_ATTR };
+export declare const MAX_TEXT = 200;
+/** Deep trees are common; a chain long enough to be useless is not worth sending. */
+export declare const MAX_CHAIN = 8;
+/** The subset of `Element` this module reads. */
+export interface ElementLike {
+    tagName: string;
+    id?: string;
+    getAttribute(name: string): string | null;
+    parentElement: ElementLike | null;
+    classList?: {
+        value?: string;
+    } | ArrayLike<string>;
+    textContent?: string | null;
+}
+/**
+ * Parse `path/to/File.tsx:42:7` into its parts.
+ *
+ * Split from the right: the line and column never contain a colon, and a path
+ * conceivably might. Returns null rather than a half-parsed ref — a ref we
+ * cannot read is worse than no ref, because downstream will believe it.
+ */
+export declare function parseSourceRef(value: string | null): SourceRef | null;
+/**
+ * Every source ref from `el` upwards, innermost first.
+ *
+ * Consecutive duplicates are collapsed: one JSX element often produces several
+ * nested DOM nodes carrying the same ref, and repeating it says nothing.
+ */
+export declare function collectSourceChain(el: ElementLike | null, max?: number): SourceRef[];
+/** The nearest ancestor (or self) carrying a ref, which is the element a human means. */
+export declare function findAnnotatedAncestor(el: ElementLike | null): ElementLike | null;
+/**
+ * A CSS-ish path to the element, used only when no ancestor carries a ref.
+ *
+ * Deliberately not guaranteed unique. It is a hint for a human reading the
+ * payload, not a selector we promise to re-resolve — StyleX class names are
+ * hashed and change between builds, so a path that looks precise would be
+ * quietly wrong on the next deploy. IDs are kept because they survive; classes
+ * are capped at two for readability.
+ */
+export declare function domPath(el: ElementLike | null, maxDepth?: number): string;
+/** Collapse whitespace and truncate, so the payload carries a label rather than a page. */
+export declare function summariseText(text: string | null | undefined): string | undefined;
+export interface ResolveTargetOptions {
+    boundingBox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/**
+ * Build the `TargetInfo` for a clicked or hovered element.
+ *
+ * `source` is the nearest ref, which names the file that writes the markup —
+ * for a composed design-system component that is the design-system file, not
+ * the call site. `sourceChain` carries the rest so the agent can choose.
+ */
+export declare function resolveTarget(el: ElementLike, options: ResolveTargetOptions): TargetInfo;

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@weatherboard/annotation",
+  "version": "0.1.0",
+  "description": "Click an element in a running app, get the source location that rendered it.",
+  "keywords": [
+    "annotation",
+    "feedback",
+    "source-maps",
+    "review",
+    "weatherboard"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Another-Iteration/another-iteration.git",
+    "directory": "packages/annotation"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "//exports": "IN THE WORKSPACE these point at TypeScript SOURCE, and `publishConfig` below swaps them for `dist/` at publish time. Two reasons. Source in the workspace means no build step stands between an edit here and a typecheck in `apps/manager` — the alternative is a stale `dist/` that typechecks green against code nobody is running, which is the failure this repository keeps finding. And the published shape is the one thing this arrangement cannot exercise, so it is not trusted: `.github/workflows/verify.yml` packs the real tarball, installs it into a bare project and imports it. That job is the only proof this map is right, and it is the reason the map is allowed to differ.",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./protocol": {
+      "import": {
+        "types": "./dist/protocol.d.mts",
+        "default": "./dist/protocol.mjs"
+      },
+      "require": {
+        "types": "./dist/protocol.d.cts",
+        "default": "./dist/protocol.cjs"
+      }
+    },
+    "./host": {
+      "import": {
+        "types": "./dist/host.d.mts",
+        "default": "./dist/host.mjs"
+      },
+      "require": {
+        "types": "./dist/host.d.cts",
+        "default": "./dist/host.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "//exports": "`types` INSIDE each condition, not above it. A single declaration shared by both formats hands a `require()` consumer types describing a module shape they do not get; and the ESM and CJS declarations differ in the extension their relative imports carry, which is what `moduleResolution: node16` checks. `build.mjs` explains the three spellings."
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "ADOPTING.md",
+    "LICENSE"
+  ],
+  "//sizeBudget": "Gzipped bytes per published entry point, checked by `build.mjs` on every build and therefore in CI. A budget is here rather than in a separate config because the number is part of the package's contract: this code runs on every page of every managed product, and 'it grew a bit each time' is how a 4KB SDK becomes a 40KB one with nobody having decided. Raising a number is allowed; doing it in the same commit as the growth, where a reviewer sees both, is the point.",
+  "sizeBudget": {
+    "protocol": 650,
+    "index": 5400,
+    "host": 660
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.62.1",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.21.0",
+    "typescript": "~5.7.2"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "//lint": "A-97. The root `eslint.config.mjs` is the single rule set — ESLint finds it by walking up from here, so there is nothing per-package to keep in sync. It is a script in EVERY package on purpose: A-52's verify tier runs `pnpm -r --if-present lint` and counts how many packages DECLARED it, so a package without this line is invisible to that gate rather than merely unlinted. `--max-warnings 0` because the React and Next plugins report at `warn` by default, and a gate that exits 0 while printing problems is the exact failure this repository keeps finding.",
+    "lint": "eslint . --max-warnings 0",
+    "test": "tsx --test src/*.test.ts",
+    "e2e": "playwright test",
+    "//smoke": "The consumer test — pack the real tarball, install it outside the workspace, import it four ways. NOT part of `pnpm test`, and not because it is slow: it shells out to `npm install`, which needs the network, and `verify` is forbidden to acquire one. It runs as its own CI job. See the header of smoke.mjs for why nothing else in this repository can catch what it catches.",
+    "smoke": "node smoke.mjs",
+    "//prepack": "Runs on `npm pack` and `npm publish`, which is what makes the `publishConfig` swap above safe: the tarball cannot be built without `dist/` having just been produced from this source. Without it the two could disagree and the failure would be a published package pointing at files that are not there."
+  },
+  "module": "./dist/index.mjs"
+}