@ingcreators/annot-playwright 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,161 @@
 # @ingcreators/annot-playwright
 
+## 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/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

@@ -3,3 +3,6 @@ export { bboxAnnotationsToSvg } from '@ingcreators/annot-annotator';
 export { expect } from '@playwright/test';
 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,249 @@
 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 { writePngWithTagsOnly as u } from "@ingcreators/annot-core/xmp-bytes";
+//#endregion
+//#region src/rebase.ts
+var d = (/* @__PURE__ */ ((e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t.exports))(((e, t) => {
+	t.exports = {};
+})))();
+function f(e, t) {
+	let n = [], r = [];
+	for (let i of e) {
+		let e = p(i, t);
+		e ? n.push(e) : r.push(i);
+	}
+	return {
+		kept: n,
+		dropped: r
+	};
+}
+function p(e, t) {
+	switch (e.type) {
+		case "rect": return m(e, t);
+		case "numberedBadge": return h(e, t);
+		case "callout": return g(e, t);
+		case "circle": return _(e, t);
+		case "arrow": return v(e, t);
+		case "text": return y(e, t);
+		case "raw": return b(e);
+	}
+}
+function m(e, t) {
+	return C(e.bbox, t) ? {
+		...e,
+		bbox: x(e.bbox, t)
+	} : null;
+}
+function h(e, t) {
+	return C(e.bbox, t) ? {
+		...e,
+		bbox: x(e.bbox, t),
+		imageWidth: t.width,
+		imageHeight: t.height
+	} : null;
+}
+function g(e, t) {
+	return !C(e.targetBbox, t) || !w(e.at, t) ? null : {
+		...e,
+		at: S(e.at, t),
+		targetBbox: x(e.targetBbox, t)
+	};
+}
+function _(e, t) {
+	return C({
+		x: e.center.x - e.radius,
+		y: e.center.y - e.radius,
+		width: e.radius * 2,
+		height: e.radius * 2
+	}, t) ? {
+		...e,
+		center: S(e.center, t)
+	} : null;
+}
+function v(e, t) {
+	return !w(e.from, t) || !w(e.to, t) ? null : {
+		...e,
+		from: S(e.from, t),
+		to: S(e.to, t)
+	};
+}
+function y(e, t) {
+	return w(e.at, t) ? {
+		...e,
+		at: S(e.at, t)
+	} : null;
+}
+function b(e) {
+	return e;
+}
+function x(e, t) {
+	return {
+		x: e.x - t.x,
+		y: e.y - t.y,
+		width: e.width,
+		height: e.height
+	};
+}
+function S(e, t) {
+	return {
+		x: e.x - t.x,
+		y: e.y - t.y
+	};
+}
+function C(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 w(e, t) {
+	return e.x >= t.x && e.y >= t.y && e.x <= t.x + t.width && e.y <= t.y + t.height;
+}
+function T(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 "raw": return "raw[<svg fragment>]";
+	}
+}
+//#endregion
+//#region src/screenshot-hooks.ts
+var E = Symbol.for("@ingcreators/annot:screenshot-patched"), D = [], O = new Set([
+	"overlays",
+	"tags",
+	"editable"
+]);
+function k(e) {
+	let t = e;
+	if (t[E]) return;
+	let n = e.screenshot;
+	e.screenshot = async function(e = {}) {
+		let t = e?.annot;
+		return A(t) ? N.call(this, n, e) : n.call(this, e);
+	}, t[E] = !0;
+}
+function A(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 (!O.has(t)) return !0;
+	return !1;
+}
+function j(e) {
+	return typeof e.boundingBox == "function";
+}
+function M(e) {
+	return j(e) ? e.page() : e;
+}
+async function N(e, t) {
+	let { annot: n, path: r, ...i } = t, a = i, o = n.editable ?? !0, s = {
+		annot: n,
+		page: M(this),
+		receiver: this
+	}, c = (await Promise.all(D.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 P(this, t.clip), f = await I({
+		rawBytes: F(await e.call(this, {
+			...a,
+			path: void 0
+		})),
+		annot: n,
+		editable: o,
+		clip: u,
+		contributions: c
 	});
-} });
-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 r && await (0, d.writeFile)(r, f), Buffer.from(f);
+}
+async function P(e, t) {
+	if (j(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 F(e) {
+	return e instanceof Uint8Array && !(e instanceof Buffer) ? e : new Uint8Array(e.buffer, e.byteOffset, e.byteLength);
+}
+async function I(e) {
+	let { rawBytes: t, annot: n, editable: r, clip: a, contributions: o } = e, s = B(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 d;
+	if (a) {
+		let { kept: e, dropped: t } = f(c, a);
+		d = e, t.length > 0 && R(t);
+	} else d = c;
+	let p = o.length > 0 || !!n.overlays;
+	if (p && !r) {
+		let e = L(d), 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 ? u(a, n.tags) : a;
+	}
+	if (p) {
+		let e = L(d), 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 ? u(t, n.tags) : t;
+}
+function L(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 R(e) {
+	let t = e.map(T).join(", "), n = `annot fixture: dropped ${e.length} overlay(s) outside the screenshot clip — ${t}`;
+	console.warn(n), z(n, e);
+}
+function z(e, t) {
+	try {
+		let n = l.info?.();
+		if (!n?.annotations) return;
+		n.annotations.push({
+			type: "warning",
+			description: `${e} (${t.length} dropped)`
+		});
+	} catch {}
+}
+function B(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 V = l.extend({
+	annotator: async ({}, e) => {
+		let t = i();
+		await e({
+			raw: t,
+			annotateScreenshot: (e, n) => H(t, e, n)
+		});
+	},
+	page: async ({ page: e }, t) => {
+		k(Object.getPrototypeOf(e)), k(Object.getPrototypeOf(e.locator("html"))), await t(e);
+	}
+});
+async function H(t, n, i) {
+	let o = await n.screenshot({ fullPage: i.fullPage }), { width: s, height: c } = U(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 +254,7 @@ async function d(t, n, i) {
 		...i.encode
 	})).bytes;
 }
-function f(e) {
+function U(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 +263,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 { E as ANNOT_PATCHED, D as annotSourceResolvers, H as annotateScreenshot, t as arrowBetween, n as bboxAnnotationsToSvg, T as describeAnnotation, c as expect, k as patchScreenshot, f as rebaseAnnotations, o as rectForBoundingBox, V 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.0",
   "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",
@@ -48,7 +48,8 @@
     "vite-plugin-dts": "^5.0.1"
   },
   "dependencies": {
-    "@ingcreators/annot-annotator": "0.5.0"
+    "@ingcreators/annot-annotator": "0.5.0",
+    "@ingcreators/annot-core": "0.2.1"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"