@ingcreators/annot-product-docs-astro 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,154 @@
 # @ingcreators/annot-product-docs-astro
 
+## 0.3.0
+
+### Minor Changes
+
+- f5dc7cb: **`@ingcreators/annot-product-docs-astro/playwright` becomes a
+  deprecated re-export** — Phase 4 of
+  `docs/plans/playwright-screenshot-fixture-relayer.md`. The fixture
+  that originally lived here moved to `@ingcreators/annot-playwright`
+  (generic patch) + `@ingcreators/annot-product-docs` (MDX resolver)
+  in Phases 1–3 of the plan. Phase 4 deletes the duplicate code
+  from this package and converts the `/playwright` subpath into a
+  shim that re-exports the canonical surface so existing callers
+  keep compiling.
+
+  ```ts
+  // Was:
+  import { test } from "@ingcreators/annot-product-docs-astro/playwright";
+
+  // Now (recommended):
+  import { test } from "@ingcreators/annot-product-docs"; // with MDX
+  // or
+  import { test } from "@ingcreators/annot-playwright"; // without MDX
+  ```
+
+  The deprecated subpath emits a one-time
+  `process.emitWarning("DeprecationWarning", …)` at import time so
+  the migration prompt shows up in CI logs. **Reference equality
+  preserved** — `test`, `expect`, `patchScreenshot`,
+  `rebaseAnnotations`, `describeAnnotation` are reference-equal to
+  their canonical homes; a new
+  `packages/product-docs-astro/src/playwright/index.test.ts`
+  asserts this.
+
+  **Removal target**: `@ingcreators/annot-product-docs-astro@0.5.0`,
+  matching the OQ-2 decision (b) in the parent plan — visible
+  deprecation, known sunset.
+
+  ## render.ts switches to the canonical helpers
+
+  `renderAnnotatedScreen()` previously carried its own copies of
+  `resolveMdxAnnotations` / `parseSnapshotBoxes` /
+  `buildBadgeAnnotations` / `svgFromBadges` / `svgFromBboxAnnotations`
+  / `emptyAnnotationsSvg`. Phase 2 of the plan moved the canonical
+  home into `@ingcreators/annot-product-docs`; this PR deletes the
+  duplicates from `product-docs-astro/render.ts` and consumes the
+  ones in product-docs going forward.
+
+  `resolveMdxAnnotations` + `svgFromBboxAnnotations` are re-exported
+  from `render.ts` for one deprecation cycle so existing callers
+  that imported them from `@ingcreators/annot-product-docs-astro`
+  keep compiling. `parseSnapshotBoxes` is dropped from the public
+  surface — new code should import it from
+  `@ingcreators/annot-product-docs` directly.
+
+  ## peerDependencies cleanup
+
+  `@playwright/test` is removed from `peerDependencies` (and from
+  `peerDependenciesMeta`). The package no longer has a Playwright
+  relationship to advertise — the `/playwright` subpath is purely
+  a re-export shim, and its types flow through the
+  `@ingcreators/annot-product-docs` workspace dep transitively.
+  This matches the OQ-3 decision (b) in the parent plan.
+
+  ## Verified
+  - `pnpm -r typecheck` — 20 packages, all pass.
+  - `pnpm test` — 252 files, 3641 tests, 0 failures. New
+    `playwright/index.test.ts` (5 reference-equality assertions)
+    passes; the deprecation `process.emitWarning` fires on
+    import (visible in vitest output) but does not break anything.
+  - `pnpm lint` — exit 0; 29 pre-existing warnings unchanged.
+  - `pnpm --filter @ingcreators/annot-product-docs-astro build` —
+    emits `dist/index.js` (3.96 kB / 1.71 kB gzip) +
+    `dist/playwright/index.js` (0.85 kB / 0.39 kB gzip) — the
+    shrunken subpath bundle reflects the re-export-only shape.
+
+### 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.
+
+- Updated dependencies [f979374]
+- Updated dependencies [5778902]
+- Updated dependencies [96e7625]
+- Updated dependencies [85d40e6]
+  - @ingcreators/annot-playwright@0.4.0
+  - @ingcreators/annot-product-docs@0.3.0
+
+## 0.2.2
+
+### Patch Changes
+
+- Updated dependencies [f485646]
+  - @ingcreators/annot-core@0.2.1
+  - @ingcreators/annot-annotator@0.5.0
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -89,41 +89,30 @@ When the stored snapshot lacks `[box=x,y,w,h]` markers (no
 Playwright tour has run yet), the function returns the base
 PNG verbatim with `hadBoundingBoxes: false`.
 
-## Playwright fixture (`/playwright` subpath)
+## Migration — Playwright fixture moved
 
-For Playwright specs producing screenshots of a documented
-screen, the `./playwright` subpath ships an extended `test`
-fixture that intercepts `page.screenshot()` and
-`locator.screenshot()`. Calls carrying a compositional
-`annot: { mdx | overlays | tags | editable }` option get a
-one-line capture pipeline that replaces the previous
-`page.screenshot` + `screen.capture` + `renderAnnotatedScreen`
-+ `writeFile` quartet:
+> The Playwright fixture that previously lived at
+> `@ingcreators/annot-product-docs-astro/playwright` moved out
+> of this package as part of
+> [`docs/plans/_done/playwright-screenshot-fixture-relayer.md`](https://github.com/ingcreators/annot/blob/main/docs/plans/_done/playwright-screenshot-fixture-relayer.md)
+> (Phases 1–4). Code authoring a Playwright spec should pick
+> one of the two canonical homes:
 
-```ts
-import { test } from "@ingcreators/annot-product-docs-astro/playwright";
-
-test("app overview", async ({ page }) => {
-  await page.goto("https://annot.work/app/");
-  await page.screenshot({
-    path: "public/app/shots/app-overview.png",
-    annot: {
-      mdx: { id: "app-overview", path: "src/content/docs/app/index.mdx" },
-      tags: { source: "docs-tour", capturedAt: new Date().toISOString() },
-    },
-  });
-});
-```
-
-Calls without `annot` (or with `annot: true` / `{}`) fall
-through to vanilla Playwright byte-for-byte — codegen-emitted
-calls keep working unedited. See the docs at
-[`annot.work/docs/product-docs/playwright-fixture/`](https://annot.work/docs/product-docs/playwright-fixture/)
-for the compositional vocabulary, locator screenshot semantics,
-and the codegen→hand-edit workflow.
-
-`@playwright/test` is an **optional peer** — Astro-only users
-don't need to install it.
+| Use case | Import |
+|---|---|
+| Living-product-docs tour (MDX-linked `annot.mdx`) | `import { test } from "@ingcreators/annot-product-docs";` |
+| VRT specs / marketing screenshots / AI agent flows (no MDX) | `import { test } from "@ingcreators/annot-playwright";` |
+
+The `@ingcreators/annot-product-docs-astro/playwright` subpath
+remains as a deprecated re-export so existing callers still
+compile; it emits a `DeprecationWarning` at import time and
+will be removed in `@ingcreators/annot-product-docs-astro@0.5.0`.
+`@playwright/test` is no longer a peer dep of this package —
+the canonical homes carry the relationship now.
+
+`renderAnnotatedScreen` (the Astro Image Service) lives on as
+the build-time renderer for the `<Screen>` block; this section
+isn't going anywhere.
 
 ## Tier
 

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export type { GraphDirection, GraphEdge, Match, OverlayIntent, ScreenListEntry,
 export type { ProductDocsIntegrationOptions } from './integration.js';
 export { productDocsIntegration } from './integration.js';
 export type { RenderAnnotatedScreenOptions, RenderResult, } from './render.js';
-export { parseSnapshotBoxes, renderAnnotatedScreen, resolveMdxAnnotations, svgFromBboxAnnotations, } from './render.js';
+export { renderAnnotatedScreen, resolveMdxAnnotations, svgFromBboxAnnotations } from './render.js';

package/dist/index.js

@@ -1,18 +1,124 @@
-import { a as e, c as t, i as n, n as r, o as i, r as a, s as o, t as s } from "./render-BSQOeqPB.js";
+import { createHash as e } from "node:crypto";
+import { mkdir as t, readFile as n, writeFile as r } from "node:fs/promises";
+import { dirname as i, isAbsolute as a, join as o, resolve as s } from "node:path";
+import { createAnnotator as c } from "@ingcreators/annot-annotator";
+import { buildBadgeAnnotations as l, emptyAnnotationsSvg as u, parseMdxFile as d, parseSnapshotBoxes as f, resolveMdxAnnotations as p, svgFromBadges as m, svgFromBboxAnnotations as h } from "@ingcreators/annot-product-docs";
+//#region src/cache.ts
+var g = 1;
+function _(t) {
+	let n = e("sha256");
+	return n.update("v1\n"), n.update(t.mdxSource), n.update("\0"), n.update(t.screenId), t.editable && n.update("\0editable"), n.digest("hex");
+}
+function v(e) {
+	return {
+		dir: e,
+		async get(t) {
+			try {
+				let r = await n(o(e, `${t}.png`));
+				return new Uint8Array(r.buffer, r.byteOffset, r.byteLength);
+			} catch (e) {
+				if (e.code === "ENOENT") return null;
+				throw e;
+			}
+		},
+		async set(n, a) {
+			let s = o(e, `${n}.png`);
+			await t(i(s), { recursive: !0 }), await r(s, a);
+		}
+	};
+}
+function y() {
+	let e = /* @__PURE__ */ new Map();
+	return {
+		dir: ":memory:",
+		async get(t) {
+			return e.get(t) ?? null;
+		},
+		async set(t, n) {
+			e.set(t, n);
+		}
+	};
+}
+//#endregion
 //#region src/integration.ts
-var c = "@ingcreators/annot-product-docs-astro";
-function l(e = {}) {
+var b = "@ingcreators/annot-product-docs-astro";
+function x(e = {}) {
 	let t = {
 		contentDir: e.contentDir ?? "docs",
 		configPath: e.configPath ?? "annot-docs.config.ts",
 		verbose: e.verbose ?? !1
 	};
 	return {
-		name: c,
+		name: b,
 		hooks: { "astro:config:setup": ({ logger: e }) => {
-			t.verbose && e.info(`${c} installed — contentDir=${t.contentDir} configPath=${t.configPath}`);
+			t.verbose && e.info(`${b} installed — contentDir=${t.contentDir} configPath=${t.configPath}`);
 		} }
 	};
 }
 //#endregion
-export { e as RENDER_PIPELINE_VERSION, i as cacheKey, o as createFileCache, t as createMemoryCache, s as parseSnapshotBoxes, l as productDocsIntegration, r as renderAnnotatedScreen, a as resolveMdxAnnotations, n as svgFromBboxAnnotations };
+//#region src/render.ts
+async function S(e) {
+	let t = e.cwd ?? process.cwd(), n = a(e.mdxPath) ? e.mdxPath : s(t, e.mdxPath), r = await d(n);
+	if (!r) throw Error(`renderAnnotatedScreen: ${e.mdxPath} has no \`annot:\` frontmatter — cannot render.`);
+	let o = r.screens.find((t) => t.id === e.screenId);
+	if (!o) throw Error(`renderAnnotatedScreen: ${e.mdxPath} has no <Screen id="${e.screenId}"> block.`);
+	let p = C(e.editable), h = _({
+		mdxSource: r.source,
+		screenId: e.screenId,
+		editable: p !== null
+	});
+	if (e.cache) {
+		let t = await e.cache.get(h);
+		if (t) return {
+			bytes: t,
+			fromCache: !0,
+			hadBoundingBoxes: !0
+		};
+	}
+	let g = e.basePngBytes ?? await w(r, o.src, i(n)), v = T(g), y = f(r.commentBlocks.snapshot ?? ""), b = l(o.overlays, y, v), x, S;
+	if (b.length === 0) if (S = !1, p !== null) {
+		let e = `data:image/png;base64,${Buffer.from(g).toString("base64")}`;
+		x = c({ loadSystemFonts: !0 }).toEditablePng({
+			originalDataUrl: e,
+			annotationsSvg: u(),
+			width: v.width,
+			height: v.height,
+			tags: p.tags
+		});
+	} else x = g;
+	else {
+		let e = `data:image/png;base64,${Buffer.from(g).toString("base64")}`, t = m(b), n = c({ loadSystemFonts: !0 }), r = {
+			originalDataUrl: e,
+			annotationsSvg: t,
+			width: v.width,
+			height: v.height
+		};
+		x = p === null ? n.toPng(r) : n.toEditablePng({
+			...r,
+			tags: p.tags
+		}), S = !0;
+	}
+	return e.cache && await e.cache.set(h, x), {
+		bytes: x,
+		fromCache: !1,
+		hadBoundingBoxes: S
+	};
+}
+function C(e) {
+	return e ? e === !0 ? {} : e : null;
+}
+async function w(e, t, r) {
+	if (!t) throw Error("renderAnnotatedScreen: <Screen src=...> is required — cannot render without a base image.");
+	let i = await n(a(t) ? t : s(r, t));
+	return new Uint8Array(i.buffer, i.byteOffset, i.byteLength);
+}
+function T(e) {
+	if (e.length < 24) throw Error("renderAnnotatedScreen: base PNG too short to contain IHDR.");
+	let t = new DataView(e.buffer, e.byteOffset, e.byteLength);
+	return {
+		width: t.getUint32(16, !1),
+		height: t.getUint32(20, !1)
+	};
+}
+//#endregion
+export { g as RENDER_PIPELINE_VERSION, _ as cacheKey, v as createFileCache, y as createMemoryCache, x as productDocsIntegration, S as renderAnnotatedScreen, p as resolveMdxAnnotations, h as svgFromBboxAnnotations };

package/dist/playwright/index.d.ts

@@ -1,5 +1,36 @@
+/**
+ * @deprecated Import `AnnotScreenshotOptions` from
+ * `@ingcreators/annot-playwright` — that package owns the
+ * canonical interface; `@ingcreators/annot-product-docs` augments
+ * it with `mdx`. Re-exporting here is back-compat only and will
+ * be removed in `@ingcreators/annot-product-docs-astro@0.5.0`.
+ */
+/**
+ * @deprecated Import the rebase helpers (`Clip`, `RebaseResult`,
+ * `describeAnnotation`, `rebaseAnnotations`) from
+ * `@ingcreators/annot-playwright`. Re-exporting here is
+ * back-compat only and will be removed in
+ * `@ingcreators/annot-product-docs-astro@0.5.0`.
+ */
+export type { AnnotScreenshotOptions, Clip, RebaseResult } from '@ingcreators/annot-playwright';
+/**
+ * @deprecated Import `patchScreenshot` from
+ * `@ingcreators/annot-playwright`. Re-exporting here is
+ * back-compat only and will be removed in
+ * `@ingcreators/annot-product-docs-astro@0.5.0`.
+ */
+export { describeAnnotation, patchScreenshot, rebaseAnnotations, } from '@ingcreators/annot-playwright';
+/**
+ * @deprecated Import `test` from `@ingcreators/annot-product-docs`
+ * (with MDX support) or `@ingcreators/annot-playwright` (without).
+ * Re-exporting here is back-compat only and will be removed in
+ * `@ingcreators/annot-product-docs-astro@0.5.0`.
+ */
+export { test } from '@ingcreators/annot-product-docs';
+/**
+ * @deprecated Import `expect` from `@ingcreators/annot-playwright`
+ * or `@playwright/test` directly. Re-exporting here is back-compat
+ * only and will be removed in
+ * `@ingcreators/annot-product-docs-astro@0.5.0`.
+ */
 export { expect } from '@playwright/test';
-export type { AnnotScreenshotOptions } from './fixture.js';
-export { patchScreenshot, test } from './fixture.js';
-export type { Clip, RebaseResult } from './rebase.js';
-export { describeAnnotation, rebaseAnnotations } from './rebase.js';

package/dist/playwright/index.js

@@ -1,225 +1,7 @@
-import { i as e, r as t } from "../render-BSQOeqPB.js";
-import { writeFile as n } from "node:fs/promises";
-import { createAnnotator as r } from "@ingcreators/annot-annotator";
-import { captureScreen as i, test as a } from "@ingcreators/annot-product-docs";
-import { expect as o } from "@playwright/test";
-import { writePngWithTagsOnly as s } from "@ingcreators/annot-core/xmp-bytes";
-//#region src/playwright/rebase.ts
-function c(e, t) {
-	let n = [], r = [];
-	for (let i of e) {
-		let e = l(i, t);
-		e ? n.push(e) : r.push(i);
-	}
-	return {
-		kept: n,
-		dropped: r
-	};
-}
-function l(e, t) {
-	switch (e.type) {
-		case "rect": return u(e, t);
-		case "numberedBadge": return d(e, t);
-		case "callout": return f(e, t);
-		case "circle": return p(e, t);
-		case "arrow": return m(e, t);
-		case "text": return h(e, t);
-		case "raw": return g(e);
-	}
-}
-function u(e, t) {
-	return y(e.bbox, t) ? {
-		...e,
-		bbox: _(e.bbox, t)
-	} : null;
-}
-function d(e, t) {
-	return y(e.bbox, t) ? {
-		...e,
-		bbox: _(e.bbox, t),
-		imageWidth: t.width,
-		imageHeight: t.height
-	} : null;
-}
-function f(e, t) {
-	return !y(e.targetBbox, t) || !b(e.at, t) ? null : {
-		...e,
-		at: v(e.at, t),
-		targetBbox: _(e.targetBbox, t)
-	};
-}
-function p(e, t) {
-	return y({
-		x: e.center.x - e.radius,
-		y: e.center.y - e.radius,
-		width: e.radius * 2,
-		height: e.radius * 2
-	}, t) ? {
-		...e,
-		center: v(e.center, t)
-	} : null;
-}
-function m(e, t) {
-	return !b(e.from, t) || !b(e.to, t) ? null : {
-		...e,
-		from: v(e.from, t),
-		to: v(e.to, t)
-	};
-}
-function h(e, t) {
-	return b(e.at, t) ? {
-		...e,
-		at: v(e.at, t)
-	} : null;
-}
-function g(e) {
-	return e;
-}
-function _(e, t) {
-	return {
-		x: e.x - t.x,
-		y: e.y - t.y,
-		width: e.width,
-		height: e.height
-	};
-}
-function v(e, t) {
-	return {
-		x: e.x - t.x,
-		y: e.y - t.y
-	};
-}
-function y(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 b(e, t) {
-	return e.x >= t.x && e.y >= t.y && e.x <= t.x + t.width && e.y <= t.y + t.height;
-}
-function x(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>]";
-	}
-}
+import { test as e } from "@ingcreators/annot-product-docs";
+import { describeAnnotation as t, patchScreenshot as n, rebaseAnnotations as r } from "@ingcreators/annot-playwright";
+import { expect as i } from "@playwright/test";
+//#region src/playwright/index.ts
+typeof process < "u" && typeof process.emitWarning == "function" && !globalThis.__annotProductDocsAstroPlaywrightWarned && (globalThis.__annotProductDocsAstroPlaywrightWarned = !0, process.emitWarning("@ingcreators/annot-product-docs-astro/playwright is deprecated. Import from @ingcreators/annot-product-docs (with MDX support) or @ingcreators/annot-playwright (without). This subpath will be removed in @ingcreators/annot-product-docs-astro@0.5.0.", "DeprecationWarning"));
 //#endregion
-//#region src/playwright/fixture.ts
-var S = Symbol.for("@ingcreators/annot:screenshot-patched");
-function C(e) {
-	let t = e;
-	if (t[S]) return;
-	let n = e.screenshot;
-	e.screenshot = async function(e = {}) {
-		let t = e?.annot;
-		return w(t) ? D.call(this, n, e) : n.call(this, e);
-	}, t[S] = !0;
-}
-function w(e) {
-	return !e || e === !0 ? !1 : !!(e.mdx || e.overlays && e.overlays.length > 0 || e.tags);
-}
-function T(e) {
-	return typeof e.boundingBox == "function";
-}
-function E(e) {
-	return T(e) ? e.page() : e;
-}
-async function D(e, t) {
-	let { annot: r, path: a, ...o } = t, s = o, c = r.editable ?? !0;
-	r.mdx && await i(E(this), {
-		id: r.mdx.id,
-		mdxPath: r.mdx.path
-	});
-	let l = await O(this, t.clip), u = await A({
-		rawBytes: k(await e.call(this, {
-			...s,
-			path: void 0
-		})),
-		annot: r,
-		editable: c,
-		clip: l
-	});
-	return a && await n(a, u), Buffer.from(u);
-}
-async function O(e, t) {
-	if (T(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 k(e) {
-	return e instanceof Uint8Array && !(e instanceof Buffer) ? e : new Uint8Array(e.buffer, e.byteOffset, e.byteLength);
-}
-async function A(n) {
-	let { rawBytes: i, annot: a, editable: o, clip: l } = n, u = N(i), d = [];
-	if (a.mdx) {
-		let e = l ? {
-			width: l.x + l.width,
-			height: l.y + l.height
-		} : u, n = await t({
-			mdxPath: a.mdx.path,
-			screenId: a.mdx.id,
-			dims: e
-		});
-		d.push(...n);
-	}
-	a.overlays && d.push(...a.overlays);
-	let f;
-	if (l) {
-		let { kept: e, dropped: t } = c(d, l);
-		f = e, t.length > 0 && j(t);
-	} else f = d;
-	let p = !!(a.mdx || a.overlays);
-	if (p && !o) {
-		let t = e(f), n = `data:image/png;base64,${Buffer.from(i).toString("base64")}`, o = r({ loadSystemFonts: !0 }).toPng({
-			originalDataUrl: n,
-			annotationsSvg: t,
-			width: u.width,
-			height: u.height
-		});
-		return a.tags ? s(o, a.tags) : o;
-	}
-	if (p) {
-		let t = e(f), n = `data:image/png;base64,${Buffer.from(i).toString("base64")}`;
-		return r({ loadSystemFonts: !0 }).toEditablePng({
-			originalDataUrl: n,
-			annotationsSvg: t,
-			width: u.width,
-			height: u.height,
-			tags: a.tags
-		});
-	}
-	return a.tags ? s(i, a.tags) : i;
-}
-function j(e) {
-	let t = e.map(x).join(", "), n = `annot fixture: dropped ${e.length} overlay(s) outside the screenshot clip — ${t}`;
-	console.warn(n), M(n, e);
-}
-function M(e, t) {
-	try {
-		let n = a.info?.();
-		if (!n?.annotations) return;
-		n.annotations.push({
-			type: "warning",
-			description: `${e} (${t.length} dropped)`
-		});
-	} catch {}
-}
-function N(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)
-	};
-}
-var P = a.extend({ page: async ({ page: e }, t) => {
-	C(Object.getPrototypeOf(e)), C(Object.getPrototypeOf(e.locator("html"))), await t(e);
-} });
-//#endregion
-export { x as describeAnnotation, o as expect, C as patchScreenshot, c as rebaseAnnotations, P as test };
+export { t as describeAnnotation, i as expect, n as patchScreenshot, r as rebaseAnnotations, e as test };

package/dist/render.d.ts

@@ -1,5 +1,5 @@
-import { BboxNumberedBadgeAnnotation } from '@ingcreators/annot-annotator';
 import { FileCache } from './cache.js';
+export { resolveMdxAnnotations, svgFromBboxAnnotations } from '@ingcreators/annot-product-docs';
 export interface RenderAnnotatedScreenOptions {
     /** Path to the `.mdx` file (absolute or relative to cwd). */
     mdxPath: string;
@@ -71,59 +71,3 @@ export interface RenderResult {
  *      and return the result.
  */
 export declare function renderAnnotatedScreen(options: RenderAnnotatedScreenOptions): Promise<RenderResult>;
-interface BoxedEntry {
-    role: string;
-    name: string;
-    ref: string;
-    box: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-}
-/**
- * Parse aria-snapshot YAML for entries that carry both `[ref=…]`
- * and `[box=x,y,w,h]` markers. `box` is the Playwright addition
- * available when `ariaSnapshot({ boxes: true })` was passed.
- *
- * Exposed for unit testing. Returns an empty array if no entries
- * have boxes — the caller falls back to a non-annotated render.
- */
-export declare function parseSnapshotBoxes(yaml: string): BoxedEntry[];
-/**
- * Resolve the `<Overlay>` blocks inside `screenId` against the MDX
- * file's stored `annot:snapshot` block and return a typed annotation
- * array ready to feed into `createAnnotator().toEditablePng()`.
- *
- * Exposed so the Playwright fixture can compose MDX-derived overlays
- * with caller-supplied inline overlays before rasterisation. Throws
- * the same diagnostics `renderAnnotatedScreen` would (no annot
- * frontmatter / no matching `<Screen id>`).
- *
- * Returns an empty array when no `<Overlay>` matches a bbox marker
- * — e.g. the snapshot was never captured, or `<Overlay match>`
- * targets an element that's no longer in the page.
- */
-export declare function resolveMdxAnnotations(opts: {
-    mdxPath: string;
-    screenId: string;
-    dims: {
-        width: number;
-        height: number;
-    };
-    cwd?: string;
-}): Promise<BboxNumberedBadgeAnnotation[]>;
-/**
- * Wrap a generic `BboxAnnotation[]` (the union DSL accepted by
- * `@ingcreators/annot-annotator`) into a single-root `<svg>` ready
- * for the annotator's `annotationsSvg` input. Mirrors `svgFromBadges`
- * but stays type-permissive — the Playwright fixture's inline overlays
- * can be any `BboxAnnotation` shape, not just numbered badges.
- *
- * Returns the empty wrapper `<svg/>` when `annotations` is empty —
- * lets the editor open the file with no annotations layer rather
- * than throwing.
- */
-export declare function svgFromBboxAnnotations(annotations: import('@ingcreators/annot-annotator').BboxAnnotation[]): string;
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-product-docs-astro",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Astro integration for `@ingcreators/annot-product-docs`. Wires the MDX components (`<Screen>` / `<Overlay>` / `<Transition>` / `<HistoryEntry>` / `<ScreenList>` / `<TransitionGraph>`) into an Astro site and supplies the Image Service that renders annotated PNGs from `<Screen>` blocks at build time. Phase 2 of docs/plans/living-product-docs.md.",
   "license": "Apache-2.0",
   "author": "ingcreators",
@@ -61,19 +61,14 @@
     "vite-plugin-dts": "^5.0.1"
   },
   "dependencies": {
-    "@ingcreators/annot-core": "0.2.0",
     "@ingcreators/annot-annotator": "0.5.0",
-    "@ingcreators/annot-product-docs": "0.2.0"
+    "@ingcreators/annot-core": "0.2.1",
+    "@ingcreators/annot-product-docs": "0.3.0",
+    "@ingcreators/annot-playwright": "0.4.0"
   },
   "peerDependencies": {
-    "@playwright/test": "^1.42.0",
     "astro": "^5.0.0 || ^6.0.0"
   },
-  "peerDependenciesMeta": {
-    "@playwright/test": {
-      "optional": true
-    }
-  },
   "scripts": {
     "build": "vite build",
     "typecheck": "tsc --noEmit"

package/dist/playwright/fixture.d.ts

@@ -1,72 +0,0 @@
-import { BboxAnnotation } from '@ingcreators/annot-annotator';
-/**
- * Compositional options for `page.screenshot({ annot })` /
- * `locator.screenshot({ annot })`. Each field is an independent
- * contribution to the embedded XMP record:
- *
- * - `mdx`     — refresh + resolve MDX `<Overlay>` annotations
- * - `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`)
- *
- * `annot: true` / `annot: {}` is treated as a no-op shorthand — the
- * fixture detects no contribution and the screenshot falls through
- * to vanilla Playwright behaviour.
- */
-export interface AnnotScreenshotOptions {
-    /** Refresh the MDX `annot:snapshot` block and resolve the
-     *  `<Screen id>`'s overlays. The MDX file is rewritten in-place
-     *  with the current page's aria-snapshot before overlays resolve.
-     */
-    mdx?: {
-        id: string;
-        path: string;
-    };
-    /** Caller-supplied annotations — merged with MDX-derived ones if
-     *  `mdx` is also set. 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;
-    }
-}
-/**
- * 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 first page (and once for the locator prototype).
- */
-export declare function patchScreenshot(proto: {
-    screenshot: (opts?: unknown) => Promise<Buffer>;
-}): void;
-/**
- * `test = base.extend({ page })` — drop-in for `@playwright/test`'s
- * `test` plus a one-time patch of `Page.prototype.screenshot` AND
- * `Locator.prototype.screenshot` (per worker process) so calls
- * carrying `annot: { ... }` run the annot pipeline above.
- *
- * The base `test` is `@ingcreators/annot-product-docs`'s test which
- * already extends `@ingcreators/annot-playwright` — callers get
- * `page` + `annotator` + `screen` plus the annot-aware screenshot.
- */
-export declare const test: import('@playwright/test').TestType<import('@playwright/test').PlaywrightTestArgs & import('@playwright/test').PlaywrightTestOptions & {
-    annotator: import('@ingcreators/annot-playwright').PlaywrightAnnotator;
-} & {
-    screen: import('@ingcreators/annot-product-docs').Screen;
-}, import('@playwright/test').PlaywrightWorkerArgs & import('@playwright/test').PlaywrightWorkerOptions>;

package/dist/playwright/rebase.d.ts

@@ -1,36 +0,0 @@
-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 `RenderResult.droppedOverlays` /
-     *  `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/render-BSQOeqPB.js

@@ -1,164 +0,0 @@
-import { createHash as e } from "node:crypto";
-import { mkdir as t, readFile as n, writeFile as r } from "node:fs/promises";
-import { dirname as i, isAbsolute as a, join as o, resolve as s } from "node:path";
-import { bboxAnnotationsToSvg as c, createAnnotator as l } from "@ingcreators/annot-annotator";
-import { parseMdxFile as u } from "@ingcreators/annot-product-docs";
-//#region src/cache.ts
-var d = 1;
-function f(t) {
-	let n = e("sha256");
-	return n.update("v1\n"), n.update(t.mdxSource), n.update("\0"), n.update(t.screenId), t.editable && n.update("\0editable"), n.digest("hex");
-}
-function p(e) {
-	return {
-		dir: e,
-		async get(t) {
-			try {
-				let r = await n(o(e, `${t}.png`));
-				return new Uint8Array(r.buffer, r.byteOffset, r.byteLength);
-			} catch (e) {
-				if (e.code === "ENOENT") return null;
-				throw e;
-			}
-		},
-		async set(n, a) {
-			let s = o(e, `${n}.png`);
-			await t(i(s), { recursive: !0 }), await r(s, a);
-		}
-	};
-}
-function m() {
-	let e = /* @__PURE__ */ new Map();
-	return {
-		dir: ":memory:",
-		async get(t) {
-			return e.get(t) ?? null;
-		},
-		async set(t, n) {
-			e.set(t, n);
-		}
-	};
-}
-//#endregion
-//#region src/render.ts
-async function h(e) {
-	let t = e.cwd ?? process.cwd(), n = a(e.mdxPath) ? e.mdxPath : s(t, e.mdxPath), r = await u(n);
-	if (!r) throw Error(`renderAnnotatedScreen: ${e.mdxPath} has no \`annot:\` frontmatter — cannot render.`);
-	let o = r.screens.find((t) => t.id === e.screenId);
-	if (!o) throw Error(`renderAnnotatedScreen: ${e.mdxPath} has no <Screen id="${e.screenId}"> block.`);
-	let c = g(e.editable), d = f({
-		mdxSource: r.source,
-		screenId: e.screenId,
-		editable: c !== null
-	});
-	if (e.cache) {
-		let t = await e.cache.get(d);
-		if (t) return {
-			bytes: t,
-			fromCache: !0,
-			hadBoundingBoxes: !0
-		};
-	}
-	let p = e.basePngBytes ?? await C(r, o.src, i(n)), m = w(p), h = v(r.commentBlocks.snapshot ?? ""), y = b(o.overlays, h, m), S, T;
-	if (y.length === 0) if (T = !1, c !== null) {
-		let e = `data:image/png;base64,${Buffer.from(p).toString("base64")}`;
-		S = l({ loadSystemFonts: !0 }).toEditablePng({
-			originalDataUrl: e,
-			annotationsSvg: _(),
-			width: m.width,
-			height: m.height,
-			tags: c.tags
-		});
-	} else S = p;
-	else {
-		let e = `data:image/png;base64,${Buffer.from(p).toString("base64")}`, t = x(y), n = l({ loadSystemFonts: !0 }), r = {
-			originalDataUrl: e,
-			annotationsSvg: t,
-			width: m.width,
-			height: m.height
-		};
-		S = c === null ? n.toPng(r) : n.toEditablePng({
-			...r,
-			tags: c.tags
-		}), T = !0;
-	}
-	return e.cache && await e.cache.set(d, S), {
-		bytes: S,
-		fromCache: !1,
-		hadBoundingBoxes: T
-	};
-}
-function g(e) {
-	return e ? e === !0 ? {} : e : null;
-}
-function _() {
-	return "<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>";
-}
-function v(e) {
-	let t = [];
-	for (let n of e.split(/\r?\n/)) {
-		if (!n.trim()) continue;
-		let e = n.match(/^\s*-\s+([a-z]+)(?:\s+"([^"]*?)")?/);
-		if (!e) continue;
-		let r = e[1] ?? "", i = e[2] ?? "", a = n.match(/\[ref=(e\d+)\]/)?.[1], o = n.match(/\[box=(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)\]/);
-		!a || !o || t.push({
-			role: r,
-			name: i,
-			ref: a,
-			box: {
-				x: Number.parseFloat(o[1]),
-				y: Number.parseFloat(o[2]),
-				width: Number.parseFloat(o[3]),
-				height: Number.parseFloat(o[4])
-			}
-		});
-	}
-	return t;
-}
-async function y(e) {
-	let t = e.cwd ?? process.cwd(), n = await u(a(e.mdxPath) ? e.mdxPath : s(t, e.mdxPath));
-	if (!n) throw Error(`resolveMdxAnnotations: ${e.mdxPath} has no \`annot:\` frontmatter — cannot resolve.`);
-	let r = n.screens.find((t) => t.id === e.screenId);
-	if (!r) throw Error(`resolveMdxAnnotations: ${e.mdxPath} has no <Screen id="${e.screenId}"> block.`);
-	let i = v(n.commentBlocks.snapshot ?? "");
-	return b(r.overlays, i, e.dims);
-}
-function b(e, t, n) {
-	let r = [], i = 1;
-	for (let a of e) {
-		let e = t.find((e) => e.role === a.match.role && e.name === a.match.name);
-		if (!e) continue;
-		let o = a.number ?? i++;
-		r.push({
-			type: "numberedBadge",
-			bbox: e.box,
-			number: o,
-			placement: "auto",
-			imageWidth: n.width,
-			imageHeight: n.height,
-			intent: a.intent === "action" ? "warning" : a.intent === "required" ? "error" : "info"
-		});
-	}
-	return r;
-}
-function x(e) {
-	return `<svg xmlns="http://www.w3.org/2000/svg">${c(e)}</svg>`;
-}
-function S(e) {
-	return e.length === 0 ? "<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>" : `<svg xmlns="http://www.w3.org/2000/svg">${c(e)}</svg>`;
-}
-async function C(e, t, r) {
-	if (!t) throw Error("renderAnnotatedScreen: <Screen src=...> is required — cannot render without a base image.");
-	let i = await n(a(t) ? t : s(r, t));
-	return new Uint8Array(i.buffer, i.byteOffset, i.byteLength);
-}
-function w(e) {
-	if (e.length < 24) throw Error("renderAnnotatedScreen: base PNG too short to contain IHDR.");
-	let t = new DataView(e.buffer, e.byteOffset, e.byteLength);
-	return {
-		width: t.getUint32(16, !1),
-		height: t.getUint32(20, !1)
-	};
-}
-//#endregion
-export { d as a, m as c, S as i, h as n, f as o, y as r, p as s, v as t };