@ingcreators/annot-playwright 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,221 @@
 # @ingcreators/annot-playwright
 
+## 0.4.1
+
+### Patch Changes
+
+- 266b05a: **Fix `writeFile is not a function` crash on `page.screenshot({ annot:
+{ path } })`** — adds `/^node:/` to the Vite library build's
+  `rollupOptions.external` so Node builtins (`node:fs/promises`, …)
+  stay as native ESM imports in `dist/index.js` instead of being
+  inlined under Vite's browser-compat externalisation.
+
+  ### Root cause
+
+  `screenshot-patch.ts` imports `writeFile` from `node:fs/promises`
+  and calls it when `path` is set on the screenshot opts. Vite's
+  default behaviour for Node builtins in a library build is to
+  externalise them with a browser-compat shim that destructures
+  incorrectly at the consumer side — the destructured name resolves
+  to `undefined` and the runtime call throws:
+
+  ```
+  TypeError: (0 , d.writeFile) is not a function
+    at _Page.N (.../node_modules/@ingcreators/annot-playwright/dist/index.js:156:36)
+  ```
+
+  The local build emitted a `Module 'node:fs/promises' has been
+externalized for browser compatibility` warning — same root cause.
+
+  ### Fix
+
+  `packages/playwright/vite.config.ts` now mirrors the pattern used
+  by `@ingcreators/annot-product-docs`, `-product-docs-astro`,
+  `-product-docs-xlsx`, and `-mcp`: `/^node:/` in `external` keeps
+  Node builtins as `import { writeFile } from "node:fs/promises"`
+  in the output bundle, which Node resolves natively at runtime.
+
+  ### Affected consumers
+
+  Every consumer of `@ingcreators/annot-playwright@0.4.0` that passes
+  `path` on `page.screenshot({ annot: { … } })` /
+  `locator.screenshot({ annot: { … } })`. The workflow-app docs-tour
+  CI workflow (`.github/workflows/docs-tour.yml` in the `annot` repo,
+  plus the dogfooded `examples/workflow-app/` tour) is the first
+  known case in the wild.
+
+  ### Verification
+  - `pnpm --filter @ingcreators/annot-playwright build` succeeds
+    without the `externalized for browser compatibility` warning.
+  - `dist/index.js` line 4 reads
+    `import { writeFile as d } from "node:fs/promises";` (literal
+    native import — no compat shim).
+  - `pnpm --filter @ingcreators/annot-playwright typecheck` passes.
+
+- Updated dependencies [6124d59]
+- Updated dependencies [0c7ac26]
+- Updated dependencies [64dc6e8]
+- Updated dependencies [691bec5]
+- Updated dependencies [9697f27]
+  - @ingcreators/annot-annotator@0.6.0
+  - @ingcreators/annot-core@0.3.0
+
+## 0.4.0
+
+### Minor Changes
+
+- f979374: **`page.screenshot({ annot: { … } })` patch relocated to
+  annot-playwright** — Phase 1 of
+  `docs/plans/playwright-screenshot-fixture-relayer.md`. The
+  prototype patch that lets Playwright tests emit annotated PNGs by
+  adding a nested `annot:` option to `page.screenshot()` /
+  `locator.screenshot()` lives here now (it shipped first in
+  `@ingcreators/annot-product-docs-astro/playwright` but is not
+  Astro-specific). VRT / marketing-screenshot / AI-agent flows pick
+  up the API without taking an Astro dependency.
+
+  ```ts
+  import { test, expect } from "@ingcreators/annot-playwright";
+
+  test("login form callouts", async ({ page }) => {
+    await page.goto("/login");
+    await page.screenshot({
+      path: "login.png",
+      annot: {
+        overlays: [
+          {
+            type: "rect",
+            bbox: { x: 10, y: 10, width: 200, height: 30 },
+            intent: "warning",
+          },
+          {
+            type: "numberedBadge",
+            bbox: { x: 10, y: 10, width: 24, height: 24 },
+            number: 1,
+          },
+        ],
+        tags: { source: "vrt-failure", testId: "login" },
+        // editable: true is the default → output PNG is re-editable
+        //   in Annot Cloud.
+      },
+    });
+  });
+  ```
+
+  Three independent contributions compose into the output PNG:
+  - `overlays: BboxAnnotation[]` — inline annotations (rect /
+    circle / arrow / text / callout / numberedBadge / raw SVG).
+  - `tags: Record<string, string>` — provenance metadata
+    serialised into the PNG's XMP (or iTXt sidecar when no
+    overlays are present).
+  - `editable: boolean` (default `true`) — re-editable wrap
+    (annotations + original capture in XMP) vs. flat baked PNG.
+
+  `Locator.prototype.screenshot` and `Page.prototype.screenshot({
+clip })` both go through the same pipeline; page-space overlay
+  coordinates are automatically rebased into the clipped image's
+  coordinate space. Overlays whose bbox falls outside the clip are
+  dropped with a warning annotation on `test.info()`.
+
+  **Extension hook registry** — `annotSourceResolvers` is a
+  module-level array of resolvers that downstream packages push
+  into to claim extra `annot.*` fields:
+
+  ```ts
+  import { annotSourceResolvers } from "@ingcreators/annot-playwright";
+
+  annotSourceResolvers.push(async ({ annot, page }) => {
+    if (!annot.figma) return null;
+    return {
+      prepare: () => refreshFigmaCache(annot.figma),
+      resolveAnnotations: (dims) => readFigmaOverlays(annot.figma, dims),
+    };
+  });
+  ```
+
+  The resolver's `prepare()` hook fires before the raw screenshot
+  is taken (so MDX-aware adapters can refresh `annot:snapshot`
+  blocks against the live DOM); `resolveAnnotations(dims)` runs
+  after with the page-space dimensions and returns
+  `BboxAnnotation[]` to merge into the output. annot-playwright
+  stays MDX-unaware — the matching MDX resolver moves into
+  `@ingcreators/annot-product-docs` in Phase 2 of the parent plan.
+
+  **Coordinate-rebase API** — `rebaseAnnotations` /
+  `describeAnnotation` / `Clip` / `RebaseResult` exported for
+  callers who want to rebase annotations themselves without going
+  through the patch (e.g. building custom test reporters):
+
+  ```ts
+  import { rebaseAnnotations } from "@ingcreators/annot-playwright";
+
+  const { kept, dropped } = rebaseAnnotations(annotations, clip);
+  ```
+
+  **Compatibility** — additive. The existing
+  `@ingcreators/annot-product-docs-astro/playwright` subpath stays
+  working unchanged for this release; Phase 4 of the parent plan
+  converts it into a deprecated re-export.
+
+### Patch Changes
+
+- 85d40e6: **Docs + CLAUDE.md + plan archive** — Phase 5 (final) of
+  `docs/plans/_done/playwright-screenshot-fixture-relayer.md`.
+  Refreshes the doc surfaces, the operational CLAUDE.md notes,
+  and archives the relayer plan into `_done/`.
+
+  ## Doc surface updates
+  - `packages/docs-site/src/content/docs/product-docs/playwright-fixture.mdx`
+    — recommended import paths updated; new "Choosing your import"
+    section covers the `@ingcreators/annot-product-docs` (MDX)
+    vs. `@ingcreators/annot-playwright` (no MDX) split; companion
+    helpers section now imports from the canonical homes; codegen
+    workflow example swapped to `@ingcreators/annot-product-docs`.
+  - `packages/docs-site/src/content/docs/api/create-annotator.mdx`
+    — "From a Playwright test" example imports from the canonical
+    home; mentions the no-MDX alternative.
+  - `packages/playwright/README.md` — adds the
+    `page.screenshot({ annot: { … } })` (recommended) section
+    above the existing `annotator.annotateScreenshot(...)` flow;
+    documents the `annotSourceResolvers` extension hook + the
+    coordinate-rebase helpers.
+  - `packages/product-docs/README.md` — adds a `page.screenshot({
+annot })` Playwright fixture section explaining the
+    productDocs.sync + MDX-resolver bundle.
+  - `packages/product-docs-astro/README.md` — replaces the
+    Playwright fixture section with a Migration note pointing at
+    the canonical homes; documents the `0.5.0` removal target.
+
+  ## CLAUDE.md monorepo layout
+  - `playwright/` entry now describes the canonical
+    `page.screenshot({ annot })` patch + `annotSourceResolvers`
+    extension hook. Version bumped to 0.4.0.
+  - `product-docs/` entry mentions the `productDocs` fixture
+    rename + the MDX-aware resolver registration via the hook
+    registry. Version bumped to 0.3.0.
+  - `product-docs-astro/` entry calls out the deprecated
+    `/playwright` re-export shim + 0.5.0 removal target.
+    `@playwright/test` no longer a peer dep. Version bumped to
+    0.3.0.
+
+  ## Plan archive
+  - `docs/plans/playwright-screenshot-fixture-relayer.md` →
+    `docs/plans/_done/playwright-screenshot-fixture-relayer.md`.
+    Status header switched to `Done` with the four landing PRs
+    enumerated. Internal `./_done/...` link paths updated to
+    `./...` (the plan is itself inside `_done/` now).
+  - `docs/plans/README.md` — removed the active entry, added a
+    "Recently landed plans" row pointing at the archived plan
+    with a multi-phase summary covering all four landing PRs.
+  - `docs/plans/living-spec-authoring-roadmap.md` — three link
+    references updated to point at the archived path; the "How
+    this relates" line switched from "Already Draft" to "Landed
+    2026-05-22 (PRs #962 / #963 / #964 / #966)".
+
+  No source code changes; verified via `pnpm -r typecheck`,
+  `pnpm test`, `pnpm lint` regardless to confirm the doc/comment
+  edits parse cleanly.
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -52,6 +52,94 @@ The `test` import is `@playwright/test`'s `test`, extended with an
 `annotator` fixture. Everything else (`test.describe`,
 `test.beforeEach`, `expect`, …) passes straight through.
 
+## `page.screenshot({ annot: { … } })` (recommended)
+
+The `test` fixture also patches `Page.prototype.screenshot` and
+`Locator.prototype.screenshot` so any call carrying an
+`annot: { … }` option runs the annot pipeline inline — no
+separate `annotateScreenshot` call, no manual file write:
+
+```ts
+import { test } from "@ingcreators/annot-playwright";
+
+test("login form callouts", async ({ page }) => {
+  await page.goto("/login");
+  await page.screenshot({
+    path: "login.png",
+    annot: {
+      overlays: [
+        { type: "rect", bbox: { x: 10, y: 10, width: 200, height: 30 }, intent: "warning" },
+        { type: "numberedBadge", bbox: { x: 10, y: 10, width: 24, height: 24 }, number: 1 },
+      ],
+      tags: { source: "vrt-failure", testId: "login" },
+      // editable: true (default) → output PNG is re-editable in Annot Cloud.
+    },
+  });
+});
+```
+
+Three independent contributions compose into the output:
+
+- `overlays: BboxAnnotation[]` — inline annotations (rect /
+  circle / arrow / text / callout / numberedBadge / raw SVG).
+- `tags: Record<string, string>` — provenance metadata
+  serialised into the PNG's XMP (or iTXt sidecar when no
+  overlays are present).
+- `editable: boolean` (default `true`) — re-editable wrap
+  (annotations + original capture in XMP) vs. flat baked PNG.
+
+`Locator.screenshot` + `page.screenshot({ clip, annot })` both
+go through the same pipeline; page-space overlay coordinates are
+automatically rebased into the clipped image's coordinate space.
+Overlays whose bbox falls outside the clip drop with a
+`test.info()` warning.
+
+Calls without `annot` (or with `annot: true` / `{}`) fall
+through to vanilla Playwright byte-for-byte — codegen-emitted
+specs work unedited.
+
+### Extension hook registry
+
+`annotSourceResolvers` is a module-level array that downstream
+packages push into to claim extra `annot.*` fields:
+
+```ts
+import { annotSourceResolvers } from "@ingcreators/annot-playwright";
+
+annotSourceResolvers.push(async ({ annot, page }) => {
+  if (!annot.figma) return null;
+  return {
+    prepare: () => refreshFigmaCache(annot.figma),
+    resolveAnnotations: (dims) => readFigmaOverlays(annot.figma, dims),
+  };
+});
+```
+
+The resolver's `prepare()` hook fires before the raw screenshot
+is taken; `resolveAnnotations(dims)` runs after with the
+page-space dimensions and returns `BboxAnnotation[]` to merge
+into the output.
+[`@ingcreators/annot-product-docs`](https://www.npmjs.com/package/@ingcreators/annot-product-docs)
+ships an MDX-aware resolver via this hook — importing its `test`
+adds an `annot.mdx?: { id, path }` field that bundles the
+refresh-MDX + take-screenshot + bake-PNG sequence into one
+`page.screenshot()` call.
+
+### Coordinate-rebase helpers
+
+```ts
+import {
+  rebaseAnnotations,
+  describeAnnotation,
+} from "@ingcreators/annot-playwright";
+
+const { kept, dropped } = rebaseAnnotations(annotations, clip);
+```
+
+Use these when you want to drive the rebase logic without going
+through the patch (custom test reporters, third-party tools that
+ship with their own composer).
+
 ## Compose annotations with the helpers
 
 ```ts

package/dist/element-tree-adapter.d.ts

@@ -0,0 +1,134 @@
+import { ElementTree, ElementTreeViewport } from '@ingcreators/annot-core/element-tree';
+/**
+ * Options for the pure YAML → tree conversion.
+ */
+export interface PlaywrightYamlToElementTreeOptions {
+    /** Raw output of `page.locator(...).ariaSnapshot({ mode: "ai",
+     *  boxes: true })`. Required. */
+    yaml: string;
+    /** Viewport dimensions + DPR at capture time. Required. */
+    viewport: ElementTreeViewport;
+    /** Page URL at capture time. Stored in `ElementTree.source.url`. */
+    url?: string;
+    /** Tool identifier (e.g. `"annot-playwright@0.4.0"`). Stored in
+     *  `ElementTree.source.agent`. */
+    agent?: string;
+    /** Capture timestamp. Defaults to `new Date().toISOString()`. */
+    capturedAt?: string;
+}
+/**
+ * Convert Playwright's aria-snapshot YAML into an `ElementTree`.
+ *
+ * The YAML format Playwright emits in `mode: "ai"` is a
+ * 2-space-per-level indented bullet list:
+ *
+ * ```yaml
+ * - main:
+ *   - heading "Sign in" [level=1] [ref=e2]
+ *   - form [ref=e3]:
+ *     - textbox "Email" [ref=e4] [box=100,200,300,40]
+ *     - button "Sign in" [active] [ref=e6]
+ * ```
+ *
+ * Each line:
+ *   - starts with `-` at some indent
+ *   - role token (lowercase letters)
+ *   - optional `"name"` (double-quoted)
+ *   - zero or more `[token]` annotations: `[ref=eN]`, `[box=x,y,w,h]`,
+ *     `[state]`, `[key=value]`
+ *   - optional trailing `:` indicating a container
+ *
+ * Nodes without a `[ref=…]` (decorative containers) get a synthetic
+ * `ref` so every node in the resulting tree has a unique identifier.
+ */
+export declare function playwrightYamlToElementTree(opts: PlaywrightYamlToElementTreeOptions): ElementTree;
+/**
+ * Options for `attachAttributes` — the convenience that walks an
+ * already-built `ElementTree` and fills each node's `attributes` by
+ * resolving its `match: { role, name }` against the live page.
+ */
+export interface AttachAttributesOptions {
+    /** Whitelist of HTML attribute names to capture. Same shape as
+     *  `DEFAULT_ATTR_WHITELIST` in `@ingcreators/annot-product-docs`. */
+    whitelist: readonly string[];
+}
+/**
+ * Walk an ElementTree and attach HTML attribute snapshots to each
+ * node by resolving its role+name against the live page. Mutates
+ * the tree in place AND returns it for fluent chaining.
+ *
+ * Resolution strategy: for each node with both `role` and `name`,
+ * call `page.getByRole(role, { name, exact: true })`. When the
+ * locator resolves to exactly one element, evaluate the whitelist
+ * against it. Ambiguous / missing resolves are silently skipped —
+ * the drift detector raises those (intentionally not duplicating
+ * the diagnostic here).
+ */
+export declare function attachAttributes(tree: ElementTree, page: AttachAttributesPage, options: AttachAttributesOptions): Promise<ElementTree>;
+/**
+ * Options for `captureElementTree` — the high-level composition that
+ * runs an aria-snapshot, converts to an ElementTree, optionally
+ * attaches HTML attributes, and returns the canonical tree. Wraps
+ * `playwrightYamlToElementTree` + `attachAttributes` in one call so
+ * downstream callers (productDocs sync flows, screenshot resolvers,
+ * MCP tools) don't have to plumb the intermediate YAML.
+ *
+ * Phase 1e of `docs/plans/living-spec-authoring-roadmap.md`.
+ */
+export interface CaptureElementTreeOptions {
+    /** Root locator for the snapshot. Defaults to the page body. */
+    rootLocator?: CaptureElementTreeLocator;
+    /** Page URL stored in `ElementTree.source.url`. Defaults to
+     *  `page.url()` when the host page exposes that method. */
+    url?: string;
+    /** Agent string stored in `ElementTree.source.agent`. */
+    agent?: string;
+    /** Capture timestamp override (defaults to `new Date().toISOString()`). */
+    capturedAt?: string;
+    /** When set, walks the resulting tree and fills per-node `attributes`
+     *  via `attachAttributes`. Pass `[]` to skip attribute capture
+     *  entirely; pass a name list to opt in. */
+    attributeWhitelist?: readonly string[];
+}
+/**
+ * Structural subset of Playwright `Page` that `captureElementTree`
+ * needs: viewport reader + ariaSnapshot dispatch on a root locator
+ * + the role-resolver `attachAttributes` uses for attribute
+ * collection. Real Playwright `Page` instances satisfy this.
+ */
+export interface CaptureElementTreePage extends AttachAttributesPage {
+    viewportSize(): {
+        width: number;
+        height: number;
+    } | null;
+    locator(selector: string): CaptureElementTreeLocator;
+    url(): string;
+}
+export interface CaptureElementTreeLocator {
+    ariaSnapshot(options: {
+        mode: "ai";
+        boxes: boolean;
+    }): Promise<string>;
+}
+/**
+ * One-shot capture composition: snapshot → ElementTree → attributes →
+ * return. The returned tree carries `source.kind: "playwright"` and
+ * `source.url` populated from the page when not overridden.
+ */
+export declare function captureElementTree(page: CaptureElementTreePage, options?: CaptureElementTreeOptions): Promise<ElementTree>;
+/**
+ * Structural subset of Playwright `Page` that `attachAttributes`
+ * needs. Real Playwright `Page` instances satisfy this; the trimmed
+ * shape lets unit tests pass a minimal mock without pulling in
+ * Playwright's full type graph.
+ */
+export interface AttachAttributesPage {
+    getByRole(role: string, options: {
+        name: string;
+        exact: true;
+    }): AttachAttributesLocator;
+}
+export interface AttachAttributesLocator {
+    count(): Promise<number>;
+    evaluate<R, A>(fn: (el: Element, arg: A) => R, arg: A): Promise<R>;
+}

package/dist/fixture.d.ts

@@ -54,9 +54,20 @@ export interface PlaywrightAnnotator {
     annotateScreenshot(page: PageLike, opts: AnnotateScreenshotOptions): Promise<Uint8Array>;
 }
 /**
- * `test = base.extend({ annotator })` — drop-in replacement for
- * `@playwright/test`'s `test` with an `annotator` fixture available
- * in every test.
+ * `test = base.extend({ annotator, page })` — drop-in replacement
+ * for `@playwright/test`'s `test` with:
+ *
+ * - an `annotator` fixture for the legacy
+ *   `annotator.annotateScreenshot(page, opts)` convenience;
+ * - a `page` fixture override that one-time-patches
+ *   `Page.prototype.screenshot` AND `Locator.prototype.screenshot`
+ *   per worker so calls carrying `annot: { ... }` run through the
+ *   patch pipeline in [`./screenshot-patch.ts`](./screenshot-patch.ts).
+ *
+ * The patch is idempotent (guarded by the `ANNOT_PATCHED` symbol
+ * exported from [`./screenshot-hooks.ts`](./screenshot-hooks.ts)),
+ * so multiple `test.extend({ page })` layers in the fixture chain
+ * coexist safely.
  */
 export declare const test: import('@playwright/test').TestType<import('@playwright/test').PlaywrightTestArgs & import('@playwright/test').PlaywrightTestOptions & {
     annotator: PlaywrightAnnotator;

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export type { AnnotationStyle, BBox, BboxAnnotation, BboxArrowAnnotation, BboxCalloutAnnotation, BboxCircleAnnotation, BboxRectAnnotation, BboxRedactRegion, BboxTextAnnotation, Intent, Point, RawAnnotation, RedactStyle, } from '@ingcreators/annot-annotator';
 export { bboxAnnotationsToSvg } from '@ingcreators/annot-annotator';
 export { expect } from '@playwright/test';
+export { type AttachAttributesLocator, type AttachAttributesOptions, type AttachAttributesPage, attachAttributes, type CaptureElementTreeLocator, type CaptureElementTreeOptions, type CaptureElementTreePage, captureElementTree, type PlaywrightYamlToElementTreeOptions, playwrightYamlToElementTree, } from './element-tree-adapter.js';
 export { type AnnotateScreenshotOptions, annotateScreenshot, type PageLike, type PlaywrightAnnotator, test, } from './fixture.js';
 export { type ArrowOptions, arrowBetween, type BoundingBox, type RectOptions, rectForBoundingBox, type TextOptions, textAt, } from './helpers.js';
+export { type Clip, describeAnnotation, type RebaseResult, rebaseAnnotations, } from './rebase.js';
+export { ANNOT_PATCHED, type AnnotScreenshotOptions, type AnnotSourceContext, type AnnotSourceContribution, type AnnotSourceResolver, annotSourceResolvers, } from './screenshot-hooks.js';
+export { patchScreenshot } from './screenshot-patch.js';

package/dist/index.js

@@ -1,15 +1,384 @@
 import { DEFAULT_ENCODE_OPTIONS as e, arrowBetween as t, bboxAnnotationsToSvg as n, bboxAnnotationsToSvg as r, createAnnotator as i, decodeAndEncodeImage as a, rectForBoundingBox as o, textAt as s } from "@ingcreators/annot-annotator";
 import { expect as c, test as l } from "@playwright/test";
-//#region src/fixture.ts
-var u = l.extend({ annotator: async ({}, e) => {
-	let t = i();
-	await e({
-		raw: t,
-		annotateScreenshot: (e, n) => d(t, e, n)
+import { walkTree as u } from "@ingcreators/annot-core/element-tree";
+import { writeFile as d } from "node:fs/promises";
+import { writePngWithTagsOnly as f } from "@ingcreators/annot-core/xmp-bytes";
+//#region src/element-tree-adapter.ts
+function p(e) {
+	let t = e.yaml.split(/\r?\n/), n = 0, r = () => (n++, `e9${String(n).padStart(5, "0")}`), i = [], a = [];
+	for (let e of t) {
+		if (!e.trim()) continue;
+		let t = e.trimStart(), n = e.length - t.length;
+		if (!t.startsWith("- ")) continue;
+		let s = t.slice(2), c = 0;
+		for (; c < s.length;) {
+			let e = s.charCodeAt(c);
+			if (e < 97 || e > 122) break;
+			c++;
+		}
+		if (c === 0) continue;
+		let l = s.slice(0, c);
+		s = s.slice(c);
+		let u;
+		if (s.startsWith(" \"")) {
+			let e = s.indexOf("\"", 2);
+			e > 1 && (u = s.slice(2, e), s = s.slice(e + 1));
+		}
+		let d = s.trimEnd(), f = /:$/.test(d);
+		f && (d = d.slice(0, -1));
+		let p = [], m, h, g = d.match(/\[ref=(e\d+)\]/);
+		g && (m = g[1]);
+		let _ = d.match(/\[box=(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)\]/);
+		_ && (h = {
+			x: Number(_[1]),
+			y: Number(_[2]),
+			width: Number(_[3]),
+			height: Number(_[4])
+		});
+		let v = /\[([A-Za-z][A-Za-z0-9_=,.-]*)\]/g, y;
+		for (; (y = v.exec(d)) !== null;) {
+			let e = y[1] ?? "";
+			e.startsWith("ref=") || e.startsWith("box=") || p.push(e);
+		}
+		let b = {
+			ref: m ?? r(),
+			role: l,
+			...u !== void 0 && u.length > 0 ? { name: u } : {},
+			...h === void 0 ? {} : { bbox: h },
+			...p.length > 0 ? { states: p } : {}
+		};
+		for (; a.length > 0 && (a[a.length - 1]?.indent ?? -1) >= n;) o(a.pop());
+		let x = {
+			indent: n,
+			node: b,
+			children: []
+		};
+		a.length === 0 ? i.push(b) : a[a.length - 1].children.push(b), f && a.push(x);
+	}
+	for (; a.length > 0;) o(a.pop());
+	function o(e) {
+		e.children.length > 0 && (e.node.children = e.children);
+	}
+	let s;
+	return s = i.length === 1 ? i[0] : {
+		ref: r(),
+		role: "generic",
+		children: i
+	}, {
+		version: 1,
+		source: {
+			kind: "playwright",
+			capturedAt: e.capturedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+			...e.agent === void 0 ? {} : { agent: e.agent },
+			...e.url === void 0 ? {} : { url: e.url }
+		},
+		viewport: e.viewport,
+		root: s
+	};
+}
+async function m(e, t, n) {
+	let r = [];
+	u(e, (e) => {
+		!e.role || !e.name || r.push({
+			node: e,
+			role: e.role,
+			name: e.name
+		});
+	});
+	for (let { node: e, role: i, name: a } of r) {
+		let r = t.getByRole(i, {
+			name: a,
+			exact: !0
+		});
+		if (await r.count() !== 1) continue;
+		let o = await r.evaluate((e, t) => {
+			let n = {};
+			for (let r of t) {
+				let t = e.getAttribute(r);
+				t !== null && (n[r] = t);
+			}
+			return n;
+		}, n.whitelist);
+		Object.keys(o).length !== 0 && (e.attributes = o);
+	}
+	return e;
+}
+async function h(e, t = {}) {
+	let n = await (t.rootLocator ?? e.locator("body")).ariaSnapshot({
+		mode: "ai",
+		boxes: !0
+	}), r = e.viewportSize(), i = p({
+		yaml: n,
+		viewport: r ? {
+			width: r.width,
+			height: r.height,
+			scale: 1
+		} : {
+			width: 0,
+			height: 0,
+			scale: 1
+		},
+		url: t.url ?? e.url(),
+		...t.agent === void 0 ? {} : { agent: t.agent },
+		...t.capturedAt === void 0 ? {} : { capturedAt: t.capturedAt }
 	});
-} });
-async function d(t, n, i) {
-	let o = await n.screenshot({ fullPage: i.fullPage }), { width: s, height: c } = f(o), l = `data:image/png;base64,${o.toString("base64")}`, u = "annotations" in i && i.annotations !== void 0 ? r(i.annotations) : i.annotationsSvg ?? "", d = t.toPng({
+	return t.attributeWhitelist !== void 0 && t.attributeWhitelist.length > 0 && await m(i, e, { whitelist: t.attributeWhitelist }), i;
+}
+//#endregion
+//#region src/rebase.ts
+function g(e, t) {
+	let n = [], r = [];
+	for (let i of e) {
+		let e = _(i, t);
+		e ? n.push(e) : r.push(i);
+	}
+	return {
+		kept: n,
+		dropped: r
+	};
+}
+function _(e, t) {
+	switch (e.type) {
+		case "rect": return v(e, t);
+		case "numberedBadge": return y(e, t);
+		case "callout": return b(e, t);
+		case "circle": return x(e, t);
+		case "arrow": return S(e, t);
+		case "text": return C(e, t);
+		case "freehand": return T(e);
+		case "focusMask": return E(e, t);
+		case "raw": return w(e);
+	}
+}
+function v(e, t) {
+	return k(e.bbox, t) ? {
+		...e,
+		bbox: D(e.bbox, t)
+	} : null;
+}
+function y(e, t) {
+	return k(e.bbox, t) ? {
+		...e,
+		bbox: D(e.bbox, t),
+		imageWidth: t.width,
+		imageHeight: t.height
+	} : null;
+}
+function b(e, t) {
+	return !k(e.targetBbox, t) || !A(e.at, t) ? null : {
+		...e,
+		at: O(e.at, t),
+		targetBbox: D(e.targetBbox, t)
+	};
+}
+function x(e, t) {
+	return k({
+		x: e.center.x - e.radius,
+		y: e.center.y - e.radius,
+		width: e.radius * 2,
+		height: e.radius * 2
+	}, t) ? {
+		...e,
+		center: O(e.center, t)
+	} : null;
+}
+function S(e, t) {
+	return !A(e.from, t) || !A(e.to, t) ? null : {
+		...e,
+		from: O(e.from, t),
+		to: O(e.to, t)
+	};
+}
+function C(e, t) {
+	return A(e.at, t) ? {
+		...e,
+		at: O(e.at, t)
+	} : null;
+}
+function w(e) {
+	return e;
+}
+function T(e) {
+	return e;
+}
+function E(e, t) {
+	return k(e.cutout, t) ? {
+		...e,
+		cutout: D(e.cutout, t),
+		imageWidth: t.width,
+		imageHeight: t.height
+	} : null;
+}
+function D(e, t) {
+	return {
+		x: e.x - t.x,
+		y: e.y - t.y,
+		width: e.width,
+		height: e.height
+	};
+}
+function O(e, t) {
+	return {
+		x: e.x - t.x,
+		y: e.y - t.y
+	};
+}
+function k(e, t) {
+	return e.x >= t.x && e.y >= t.y && e.x + e.width <= t.x + t.width && e.y + e.height <= t.y + t.height;
+}
+function A(e, t) {
+	return e.x >= t.x && e.y >= t.y && e.x <= t.x + t.width && e.y <= t.y + t.height;
+}
+function j(e) {
+	switch (e.type) {
+		case "rect":
+		case "numberedBadge": return `${e.type}@(${e.bbox.x},${e.bbox.y},${e.bbox.width},${e.bbox.height})`;
+		case "callout": return `callout@(${e.targetBbox.x},${e.targetBbox.y},${e.targetBbox.width},${e.targetBbox.height})`;
+		case "circle": return `circle@(${e.center.x},${e.center.y},r=${e.radius})`;
+		case "arrow": return `arrow@(${e.from.x},${e.from.y})→(${e.to.x},${e.to.y})`;
+		case "text": return `text@(${e.at.x},${e.at.y})`;
+		case "freehand": return `freehand[d=${e.path.slice(0, 32)}${e.path.length > 32 ? "…" : ""}]`;
+		case "focusMask": return `focusMask@(${e.cutout.x},${e.cutout.y},${e.cutout.width},${e.cutout.height})`;
+		case "raw": return "raw[<svg fragment>]";
+	}
+}
+//#endregion
+//#region src/screenshot-hooks.ts
+var M = Symbol.for("@ingcreators/annot:screenshot-patched"), N = [], P = /* @__PURE__ */ new Set([
+	"overlays",
+	"tags",
+	"editable"
+]);
+function F(e) {
+	let t = e;
+	if (t[M]) return;
+	let n = e.screenshot;
+	e.screenshot = async function(e = {}) {
+		let t = e?.annot;
+		return I(t) ? z.call(this, n, e) : n.call(this, e);
+	}, t[M] = !0;
+}
+function I(e) {
+	if (!e || e === !0) return !1;
+	if (e.overlays && e.overlays.length > 0 || e.tags) return !0;
+	for (let t of Object.keys(e)) if (!P.has(t)) return !0;
+	return !1;
+}
+function L(e) {
+	return typeof e.boundingBox == "function";
+}
+function R(e) {
+	return L(e) ? e.page() : e;
+}
+async function z(e, t) {
+	let { annot: n, path: r, ...i } = t, a = i, o = n.editable ?? !0, s = {
+		annot: n,
+		page: R(this),
+		receiver: this
+	}, c = (await Promise.all(N.map((e) => e(s)))).filter((e) => e !== null), l = (n.overlays?.length ?? 0) > 0 || !!n.tags;
+	if (c.length === 0 && !l) return e.call(this, t);
+	for (let e of c) e.prepare && await e.prepare();
+	let u = await B(this, t.clip), f = await H({
+		rawBytes: V(await e.call(this, {
+			...a,
+			path: void 0
+		})),
+		annot: n,
+		editable: o,
+		clip: u,
+		contributions: c
+	});
+	return r && await d(r, f), Buffer.from(f);
+}
+async function B(e, t) {
+	if (L(e)) {
+		let t = await e.boundingBox();
+		if (!t) throw Error("locator.screenshot({ annot }): locator has no bounding box (probably not visible). Re-test with a stable selector / waitFor().");
+		return t;
+	}
+	return t ?? null;
+}
+function V(e) {
+	return e instanceof Uint8Array && !(e instanceof Buffer) ? e : new Uint8Array(e.buffer, e.byteOffset, e.byteLength);
+}
+async function H(e) {
+	let { rawBytes: t, annot: n, editable: r, clip: a, contributions: o } = e, s = K(t), c = [], l = a ? {
+		width: a.x + a.width,
+		height: a.y + a.height
+	} : s;
+	for (let e of o) {
+		let t = await e.resolveAnnotations(l);
+		c.push(...t);
+	}
+	n.overlays && c.push(...n.overlays);
+	let u;
+	if (a) {
+		let { kept: e, dropped: t } = g(c, a);
+		u = e, t.length > 0 && W(t);
+	} else u = c;
+	let d = o.length > 0 || !!n.overlays;
+	if (d && !r) {
+		let e = U(u), r = `data:image/png;base64,${Buffer.from(t).toString("base64")}`, a = i({ loadSystemFonts: !0 }).toPng({
+			originalDataUrl: r,
+			annotationsSvg: e,
+			width: s.width,
+			height: s.height
+		});
+		return n.tags ? f(a, n.tags) : a;
+	}
+	if (d) {
+		let e = U(u), r = `data:image/png;base64,${Buffer.from(t).toString("base64")}`;
+		return i({ loadSystemFonts: !0 }).toEditablePng({
+			originalDataUrl: r,
+			annotationsSvg: e,
+			width: s.width,
+			height: s.height,
+			tags: n.tags
+		});
+	}
+	return n.tags ? f(t, n.tags) : t;
+}
+function U(e) {
+	return e.length === 0 ? "<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>" : `<svg xmlns="http://www.w3.org/2000/svg">${r(e)}</svg>`;
+}
+function W(e) {
+	let t = e.map(j).join(", "), n = `annot fixture: dropped ${e.length} overlay(s) outside the screenshot clip — ${t}`;
+	console.warn(n), G(n, e);
+}
+function G(e, t) {
+	try {
+		let n = l.info?.();
+		if (!n?.annotations) return;
+		n.annotations.push({
+			type: "warning",
+			description: `${e} (${t.length} dropped)`
+		});
+	} catch {}
+}
+function K(e) {
+	if (e.length < 24) throw Error("Playwright annot fixture: raw screenshot too short to contain PNG IHDR.");
+	let t = new DataView(e.buffer, e.byteOffset, e.byteLength);
+	return {
+		width: t.getUint32(16, !1),
+		height: t.getUint32(20, !1)
+	};
+}
+//#endregion
+//#region src/fixture.ts
+var q = l.extend({
+	annotator: async ({}, e) => {
+		let t = i();
+		await e({
+			raw: t,
+			annotateScreenshot: (e, n) => J(t, e, n)
+		});
+	},
+	page: async ({ page: e }, t) => {
+		F(Object.getPrototypeOf(e)), F(Object.getPrototypeOf(e.locator("html"))), await t(e);
+	}
+});
+async function J(t, n, i) {
+	let o = await n.screenshot({ fullPage: i.fullPage }), { width: s, height: c } = Y(o), l = `data:image/png;base64,${o.toString("base64")}`, u = "annotations" in i && i.annotations !== void 0 ? r(i.annotations) : i.annotationsSvg ?? "", d = t.toPng({
 		originalDataUrl: l,
 		annotationsSvg: u,
 		width: s,
@@ -20,7 +389,7 @@ async function d(t, n, i) {
 		...i.encode
 	})).bytes;
 }
-function f(e) {
+function Y(e) {
 	if (e.length < 24) throw Error("PNG too short to contain IHDR chunk");
 	let t = new DataView(e.buffer, e.byteOffset, e.byteLength);
 	return {
@@ -29,4 +398,4 @@ function f(e) {
 	};
 }
 //#endregion
-export { d as annotateScreenshot, t as arrowBetween, n as bboxAnnotationsToSvg, c as expect, o as rectForBoundingBox, u as test, s as textAt };
+export { M as ANNOT_PATCHED, N as annotSourceResolvers, J as annotateScreenshot, t as arrowBetween, m as attachAttributes, n as bboxAnnotationsToSvg, h as captureElementTree, j as describeAnnotation, c as expect, F as patchScreenshot, p as playwrightYamlToElementTree, g as rebaseAnnotations, o as rectForBoundingBox, q as test, s as textAt };

package/dist/rebase.d.ts

@@ -0,0 +1,35 @@
+import { BboxAnnotation } from '@ingcreators/annot-annotator';
+export interface Clip {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface RebaseResult {
+    /** Annotations whose coordinates were rebased into clip-space. */
+    kept: BboxAnnotation[];
+    /** Annotations that fell outside `clip` and were dropped. The
+     *  caller surfaces these as `test.info().annotations` warnings. */
+    dropped: BboxAnnotation[];
+}
+/**
+ * Rebase + filter a `BboxAnnotation[]` against a clip rectangle.
+ *
+ * - `kept` = annotations whose visible coords were translated by
+ *   `(-clip.x, -clip.y)`. The new coords are in the clipped image's
+ *   coordinate space (0,0 at the top-left of the screenshot).
+ * - `dropped` = annotations whose bbox / endpoints fell outside the
+ *   clip. Returned verbatim (un-rebased) so the caller can log
+ *   which originals were skipped.
+ *
+ * `numberedBadge`'s `imageWidth` / `imageHeight` are also rebased
+ * to match the clip dimensions, so `placement: "auto"` picks the
+ * corner against the cropped image edge rather than the page edge.
+ */
+export declare function rebaseAnnotations(annotations: BboxAnnotation[], clip: Clip): RebaseResult;
+/**
+ * Format a short identifier for an annotation so dropped diagnostics
+ * stay readable. We don't have a stable id field on the DSL types —
+ * use `type` + first bbox coords as a heuristic.
+ */
+export declare function describeAnnotation(ann: BboxAnnotation): string;

package/dist/screenshot-hooks.d.ts

@@ -0,0 +1,134 @@
+import { BboxAnnotation } from '@ingcreators/annot-annotator';
+import { Locator, Page } from '@playwright/test';
+/**
+ * Idempotency guard for the prototype patch — checked + set inside
+ * `patchScreenshot`. `Symbol.for(...)` cross-module realm-stable so
+ * re-importing annot-playwright in the same worker process picks up
+ * the existing patch instead of double-wrapping.
+ */
+export declare const ANNOT_PATCHED: unique symbol;
+/**
+ * Compositional options for `page.screenshot({ annot })` /
+ * `locator.screenshot({ annot })`. Each known field is an
+ * independent contribution to the output:
+ *
+ * - `overlays` — inline `BboxAnnotation[]` (the DSL accepted by
+ *                `@ingcreators/annot-annotator`)
+ * - `tags`     — provenance metadata written verbatim into the XMP
+ * - `editable` — bake-vs-preserve toggle (default `true`)
+ *
+ * Extra fields (e.g. `mdx`, future `figma`) are claimed by resolvers
+ * registered in [`annotSourceResolvers`](#annotSourceResolvers).
+ * Downstream packages declare those fields via TypeScript module
+ * augmentation:
+ *
+ * ```ts
+ * declare module "@ingcreators/annot-playwright" {
+ *   interface AnnotScreenshotOptions {
+ *     mdx?: { id: string; path: string };
+ *   }
+ * }
+ * ```
+ *
+ * `annot: true` / `annot: {}` is treated as a no-op shorthand — the
+ * patch detects no contribution and the screenshot falls through to
+ * vanilla Playwright behaviour.
+ */
+export interface AnnotScreenshotOptions {
+    /** Caller-supplied annotations — merged with any resolver-derived
+     *  ones. Same DSL `@ingcreators/annot-annotator` accepts. */
+    overlays?: BboxAnnotation[];
+    /** Provenance metadata written verbatim into the PNG's XMP. The
+     *  fixture adds no defaults; callers who want `WELL_KNOWN_TAG_KEYS`
+     *  (`source` / `screen` / `capturedAt` / `commit`) write them. */
+    tags?: Record<string, string>;
+    /** When `true` (default): annotations stored as SVG in XMP +
+     *  original capture embedded → re-editable in Annot Cloud. When
+     *  `false`: annotations baked into the visible pixels, no XMP
+     *  layer, no embedded original — flat PNG, no round-trip. */
+    editable?: boolean;
+}
+declare module "@playwright/test" {
+    interface PageScreenshotOptions {
+        annot?: AnnotScreenshotOptions;
+    }
+    interface LocatorScreenshotOptions {
+        annot?: AnnotScreenshotOptions;
+    }
+}
+/**
+ * Context passed to every resolver registered in
+ * [`annotSourceResolvers`](#annotSourceResolvers).
+ */
+export interface AnnotSourceContext {
+    /** The `annot` option as supplied by the caller. Resolvers
+     *  inspect this for the fields they're responsible for (e.g. an
+     *  MDX resolver reads `annot.mdx`). */
+    annot: AnnotScreenshotOptions;
+    /** `Page` for `page.screenshot()`; `Locator.page()` for
+     *  `locator.screenshot()`. Resolvers should always operate
+     *  against the full page — clip rebasing happens in the patch
+     *  pipeline after resolvers return. */
+    page: Page;
+    /** The receiver of the original `screenshot(...)` call. Either
+     *  `Page` (for `page.screenshot`) or `Locator` (for
+     *  `locator.screenshot`). Most resolvers only need
+     *  [`page`](#page), but the locator handle is exposed for
+     *  resolvers that want to read its bounding box etc. */
+    receiver: Page | Locator;
+}
+/**
+ * One source-of-annotations contribution returned from a resolver.
+ *
+ * `prepare()` runs serially in registration order BEFORE the
+ * screenshot is taken — e.g. an MDX resolver rewrites the
+ * `annot:snapshot` block here so the resolved bboxes match the
+ * about-to-be-captured DOM.
+ *
+ * `resolveAnnotations(dims)` runs AFTER the raw screenshot is taken
+ * and receives the page-space dimensions (clip-aware:
+ * `{ width: clip.x + clip.width, height: clip.y + clip.height }`).
+ * Returned annotations are in page-space; the patch pipeline
+ * rebases them onto the clipped image afterwards.
+ */
+export interface AnnotSourceContribution {
+    /** Optional side effect to run BEFORE the raw screenshot is
+     *  taken. Runs serially in registration order. */
+    prepare?: () => Promise<void>;
+    /** Resolver-derived page-space annotations. The patch pipeline
+     *  rebases them onto clip-space if a clip is in effect. */
+    resolveAnnotations: (dims: {
+        width: number;
+        height: number;
+    }) => Promise<BboxAnnotation[]>;
+}
+/**
+ * A resolver inspects `ctx.annot` for fields it cares about and
+ * returns a contribution, or `null` if the call carries nothing it
+ * recognises. The registry is walked once per `page.screenshot({
+ * annot })` call; resolvers MUST be idempotent (no side effects
+ * unless triggered by their own field's presence).
+ */
+export type AnnotSourceResolver = (ctx: AnnotSourceContext) => Promise<AnnotSourceContribution | null>;
+/**
+ * Module-level resolver registry. Packages that extend the patch
+ * (e.g. `@ingcreators/annot-product-docs` for MDX-derived overlays)
+ * push their resolver at module load time:
+ *
+ * ```ts
+ * import { annotSourceResolvers } from "@ingcreators/annot-playwright";
+ *
+ * annotSourceResolvers.push(async ({ annot, page }) => {
+ *   if (!annot.mdx) return null;
+ *   return {
+ *     prepare: () => refreshMdxSnapshot(page, annot.mdx),
+ *     resolveAnnotations: (dims) => readMdxOverlays(annot.mdx, dims),
+ *   };
+ * });
+ * ```
+ *
+ * One singleton per process — the `Symbol.for(...)` lookup makes
+ * the registry stable across realm boundaries the way the
+ * idempotency symbol on the prototype is.
+ */
+export declare const annotSourceResolvers: AnnotSourceResolver[];

package/dist/screenshot-patch.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Idempotent prototype patch — wrap `screenshot` to intercept the
+ * `annot` opt while falling through to the original method when
+ * absent / empty. Exported for unit tests; production usage flows
+ * through the fixture `extend({ page })` body which calls this once
+ * per worker on the `Page` AND `Locator` prototypes.
+ */
+export declare function patchScreenshot(proto: {
+    screenshot: (opts?: unknown) => Promise<Buffer>;
+}): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-playwright",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Playwright fixture for annotated screenshots — emit annotated PNGs from failing tests without leaving the test file. Pairs `test.extend({ annotator })` with the headless renderer from @ingcreators/annot-annotator.",
   "license": "Apache-2.0",
   "author": "ingcreators",
@@ -42,13 +42,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@playwright/test": "^1.50.0",
+    "@playwright/test": "^1.61.1",
     "typescript": "^6.0.3",
-    "vite": "^8.0.13",
-    "vite-plugin-dts": "^5.0.1"
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.3"
   },
   "dependencies": {
-    "@ingcreators/annot-annotator": "0.5.0"
+    "@ingcreators/annot-annotator": "0.6.0",
+    "@ingcreators/annot-core": "0.3.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"