@ingcreators/annot-playwright 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @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

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/index.d.ts

@@ -1,6 +1,7 @@
 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';

package/dist/index.js

@@ -1,15 +1,135 @@
 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";
-import { writePngWithTagsOnly as u } from "@ingcreators/annot-core/xmp-bytes";
+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 }
+	});
+	return t.attributeWhitelist !== void 0 && t.attributeWhitelist.length > 0 && await m(i, e, { whitelist: t.attributeWhitelist }), i;
+}
 //#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) {
+function g(e, t) {
 	let n = [], r = [];
 	for (let i of e) {
-		let e = p(i, t);
+		let e = _(i, t);
 		e ? n.push(e) : r.push(i);
 	}
 	return {
@@ -17,66 +137,79 @@ function f(e, t) {
 		dropped: r
 	};
 }
-function p(e, t) {
+function _(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);
+		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 m(e, t) {
-	return C(e.bbox, t) ? {
+function v(e, t) {
+	return k(e.bbox, t) ? {
 		...e,
-		bbox: x(e.bbox, t)
+		bbox: D(e.bbox, t)
 	} : null;
 }
-function h(e, t) {
-	return C(e.bbox, t) ? {
+function y(e, t) {
+	return k(e.bbox, t) ? {
 		...e,
-		bbox: x(e.bbox, t),
+		bbox: D(e.bbox, t),
 		imageWidth: t.width,
 		imageHeight: t.height
 	} : null;
 }
-function g(e, t) {
-	return !C(e.targetBbox, t) || !w(e.at, t) ? null : {
+function b(e, t) {
+	return !k(e.targetBbox, t) || !A(e.at, t) ? null : {
 		...e,
-		at: S(e.at, t),
-		targetBbox: x(e.targetBbox, t)
+		at: O(e.at, t),
+		targetBbox: D(e.targetBbox, t)
 	};
 }
-function _(e, t) {
-	return C({
+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: S(e.center, t)
+		center: O(e.center, t)
 	} : null;
 }
-function v(e, t) {
-	return !w(e.from, t) || !w(e.to, t) ? null : {
+function S(e, t) {
+	return !A(e.from, t) || !A(e.to, t) ? null : {
 		...e,
-		from: S(e.from, t),
-		to: S(e.to, t)
+		from: O(e.from, t),
+		to: O(e.to, t)
 	};
 }
-function y(e, t) {
-	return w(e.at, t) ? {
+function C(e, t) {
+	return A(e.at, t) ? {
 		...e,
-		at: S(e.at, t)
+		at: O(e.at, t)
 	} : null;
 }
-function b(e) {
+function w(e) {
 	return e;
 }
-function x(e, t) {
+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,
@@ -84,19 +217,19 @@ function x(e, t) {
 		height: e.height
 	};
 }
-function S(e, t) {
+function O(e, t) {
 	return {
 		x: e.x - t.x,
 		y: e.y - t.y
 	};
 }
-function C(e, t) {
+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 w(e, t) {
+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 T(e) {
+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})`;
@@ -104,47 +237,49 @@ function T(e) {
 		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 E = Symbol.for("@ingcreators/annot:screenshot-patched"), D = [], O = new Set([
+var M = Symbol.for("@ingcreators/annot:screenshot-patched"), N = [], P = /* @__PURE__ */ new Set([
 	"overlays",
 	"tags",
 	"editable"
 ]);
-function k(e) {
+function F(e) {
 	let t = e;
-	if (t[E]) return;
+	if (t[M]) 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;
+		return I(t) ? z.call(this, n, e) : n.call(this, e);
+	}, t[M] = !0;
 }
-function A(e) {
+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 (!O.has(t)) return !0;
+	for (let t of Object.keys(e)) if (!P.has(t)) return !0;
 	return !1;
 }
-function j(e) {
+function L(e) {
 	return typeof e.boundingBox == "function";
 }
-function M(e) {
-	return j(e) ? e.page() : e;
+function R(e) {
+	return L(e) ? e.page() : e;
 }
-async function N(e, t) {
+async function z(e, t) {
 	let { annot: n, path: r, ...i } = t, a = i, o = n.editable ?? !0, s = {
 		annot: n,
-		page: M(this),
+		page: R(this),
 		receiver: this
-	}, c = (await Promise.all(D.map((e) => e(s)))).filter((e) => e !== null), l = (n.overlays?.length ?? 0) > 0 || !!n.tags;
+	}, 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 P(this, t.clip), f = await I({
-		rawBytes: F(await e.call(this, {
+	let u = await B(this, t.clip), f = await H({
+		rawBytes: V(await e.call(this, {
 			...a,
 			path: void 0
 		})),
@@ -153,21 +288,21 @@ async function N(e, t) {
 		clip: u,
 		contributions: c
 	});
-	return r && await (0, d.writeFile)(r, f), Buffer.from(f);
+	return r && await d(r, f), Buffer.from(f);
 }
-async function P(e, t) {
-	if (j(e)) {
+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 F(e) {
+function V(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 ? {
+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;
@@ -176,23 +311,23 @@ async function I(e) {
 		c.push(...t);
 	}
 	n.overlays && c.push(...n.overlays);
-	let d;
+	let u;
 	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({
+		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 ? u(a, n.tags) : a;
+		return n.tags ? f(a, n.tags) : a;
 	}
-	if (p) {
-		let e = L(d), r = `data:image/png;base64,${Buffer.from(t).toString("base64")}`;
+	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,
@@ -201,16 +336,16 @@ async function I(e) {
 			tags: n.tags
 		});
 	}
-	return n.tags ? u(t, n.tags) : t;
+	return n.tags ? f(t, n.tags) : t;
 }
-function L(e) {
+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 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 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 z(e, t) {
+function G(e, t) {
 	try {
 		let n = l.info?.();
 		if (!n?.annotations) return;
@@ -220,7 +355,7 @@ function z(e, t) {
 		});
 	} catch {}
 }
-function B(e) {
+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 {
@@ -230,20 +365,20 @@ function B(e) {
 }
 //#endregion
 //#region src/fixture.ts
-var V = l.extend({
+var q = l.extend({
 	annotator: async ({}, e) => {
 		let t = i();
 		await e({
 			raw: t,
-			annotateScreenshot: (e, n) => H(t, e, n)
+			annotateScreenshot: (e, n) => J(t, e, n)
 		});
 	},
 	page: async ({ page: e }, t) => {
-		k(Object.getPrototypeOf(e)), k(Object.getPrototypeOf(e.locator("html"))), await t(e);
+		F(Object.getPrototypeOf(e)), F(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({
+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,
@@ -254,7 +389,7 @@ async function H(t, n, i) {
 		...i.encode
 	})).bytes;
 }
-function U(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 {
@@ -263,4 +398,4 @@ function U(e) {
 	};
 }
 //#endregion
-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 };
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-playwright",
-  "version": "0.4.0",
+  "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,14 +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-core": "0.2.1"
+    "@ingcreators/annot-annotator": "0.6.0",
+    "@ingcreators/annot-core": "0.3.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"