@ingcreators/annot-product-docs 0.3.0 → 0.4.1

package/dist/index.js

@@ -1,84 +1,93 @@
-import { annotSourceResolvers as e, test as t } from "@ingcreators/annot-playwright";
-import { mkdir as n, readFile as r, readdir as i, writeFile as a } from "node:fs/promises";
-import o from "js-yaml";
-import s from "remark-frontmatter";
-import c from "remark-mdx";
-import l from "remark-parse";
-import { unified as u } from "unified";
-import { visit as d } from "unist-util-visit";
-import { z as f } from "zod";
-import { dirname as p, isAbsolute as ee, join as te, relative as m, resolve as h } from "node:path";
-import { bboxAnnotationsToSvg as g } from "@ingcreators/annot-annotator";
+import { annotSourceResolvers as e, playwrightYamlToElementTree as t, test as n } from "@ingcreators/annot-playwright";
+import { mkdir as r, readFile as i, readdir as a, writeFile as o } from "node:fs/promises";
+import s, { dump as c, load as l } from "js-yaml";
+import u from "remark-frontmatter";
+import d from "remark-mdx";
+import f from "remark-parse";
+import { unified as ee } from "unified";
+import { visit as te } from "unist-util-visit";
+import { z as p } from "zod";
+import { basename as ne, dirname as m, isAbsolute as h, join as re, relative as g, resolve as _ } from "node:path";
+import { bboxAnnotationsToSvg as v } from "@ingcreators/annot-annotator";
+import { findByMatch as ie, walkTree as ae, writeElementTreePng as oe } from "@ingcreators/annot-core";
 //#region src/config.ts
-var ne = f.enum([
+var se = p.enum([
 	"cover",
 	"history",
 	"list",
 	"screen",
 	"reference"
-]), re = f.object({
-	book: f.string().optional(),
-	sheet: f.string().optional(),
-	sheets: f.record(f.string(), f.string()).optional(),
-	role: ne.optional(),
-	order: f.number().optional()
-}).strict().refine((e) => !(e.sheet && e.sheets), "Specify either `xlsx.sheet` (single sheet) or `xlsx.sheets` (multi-sheet), not both."), ie = f.record(f.string(), f.unknown()), _ = f.object({
-	id: f.string().min(1, "`annot.id` is required."),
-	title: f.string().optional(),
-	purpose: f.string().optional(),
-	meta: ie.optional(),
-	xlsx: re.optional()
-}).strict(), ae = f.object({
-	template: f.string().optional(),
-	templateSheets: f.object({
-		cover: f.string().optional(),
-		history: f.string().optional(),
-		list: f.string().optional(),
-		screen: f.string().optional(),
-		reference: f.string().optional()
-	}).strict().optional()
-}).strict(), v = f.object({
-	meta: f.record(f.string(), f.unknown()).optional(),
-	xlsx: f.object({
-		defaultBook: f.string().optional(),
-		books: f.record(f.string(), ae).optional()
+]), ce = p.object({
+	book: p.string().optional(),
+	sheet: p.string().optional(),
+	sheets: p.record(p.string(), p.string()).optional(),
+	role: se.optional(),
+	order: p.number().optional()
+}).strict().refine((e) => !(e.sheet && e.sheets), "Specify either `xlsx.sheet` (single sheet) or `xlsx.sheets` (multi-sheet), not both."), le = p.record(p.string(), p.unknown()), ue = p.object({
+	id: p.string().min(1, "`annot.id` is required."),
+	title: p.string().optional(),
+	purpose: p.string().optional(),
+	meta: le.optional(),
+	xlsx: ce.optional()
+}).strict(), de = p.object({
+	template: p.string().optional(),
+	templateSheets: p.object({
+		cover: p.string().optional(),
+		history: p.string().optional(),
+		list: p.string().optional(),
+		screen: p.string().optional(),
+		reference: p.string().optional()
 	}).strict().optional()
+}).strict(), fe = p.object({
+	embedMode: p.enum([
+		"newTab",
+		"inline",
+		"disabled"
+	]).optional(),
+	cloudUrl: p.string().url("editor.cloudUrl must be an absolute URL").optional()
+}).strict(), pe = p.object({
+	meta: p.record(p.string(), p.unknown()).optional(),
+	xlsx: p.object({
+		defaultBook: p.string().optional(),
+		books: p.record(p.string(), de).optional()
+	}).strict().optional(),
+	editor: fe.optional()
 }).strict();
-function oe(e) {
-	let t = v.safeParse(e);
+function me(e) {
+	let t = pe.safeParse(e);
 	if (!t.success) {
 		let e = t.error.issues.map((e) => `  - ${e.path.length ? e.path.join(".") + ": " : ""}${e.message}`).join("\n");
 		throw Error(`Invalid \`annot-docs.config.ts\`:\n${e}`);
 	}
 	return t.data;
 }
-function se(e) {
+function he(e) {
 	return (e.xlsx?.role ?? "screen") === "screen";
 }
 //#endregion
 //#region src/mdx.ts
-var y = "annot:snapshot", ce = "/annot:snapshot", b = "annot:attributes", le = "/annot:attributes", ue = /^\s*\/\*\s*([^\s*]+)\s*([\s\S]*?)\*\/\s*$/;
-async function x(e) {
-	return S(await r(e, "utf8"), { filePath: e });
+var ge = "annot:snapshot", _e = "/annot:snapshot", ve = "annot:attributes", ye = "/annot:attributes", be = /^\s*\/\*\s*([^\s*]+)\s*([\s\S]*?)\*\/\s*$/;
+async function y(e) {
+	return xe(await i(e, "utf8"), { filePath: e });
 }
-function S(e, t = {}) {
-	let n = u().use(l).use(s, ["yaml"]).use(c).parse(e), r = de(n, t.filePath);
+function xe(e, t = {}) {
+	let n = ee().use(f).use(u, ["yaml"]).use(d).parse(e), r = Se(n, t.filePath);
 	if (!r) return null;
-	let i = [], a = [], o = [], f = [], p = {};
-	return d(n, (t) => {
+	let i = [], a = [], o = [], s = [], c = {};
+	return te(n, (t) => {
 		switch (t.type) {
 			case "mdxJsxFlowElement":
 			case "mdxJsxTextElement":
-				pe(t, e, {
+				we(t, e, {
 					screens: i,
 					transitions: a,
 					history: o,
-					screenLists: f
+					screenLists: s
 				});
 				return;
 			case "mdxFlowExpression":
 			case "mdxTextExpression":
-				ye(t, p);
+				je(t, c);
 				return;
 		}
 	}), {
@@ -86,118 +95,132 @@ function S(e, t = {}) {
 		screens: i,
 		transitions: a,
 		history: o,
-		screenLists: f,
-		commentBlocks: p,
+		screenLists: s,
+		commentBlocks: c,
 		source: e
 	};
 }
-function de(e, t) {
+function Se(e, t) {
 	let n = e.children.find((e) => e.type === "yaml");
 	if (!n || !n.value) return null;
-	let r = o.load(n.value);
+	let r = s.load(n.value);
 	if (!r || typeof r != "object") return null;
 	let i = r.annot;
 	if (!i || typeof i != "object") return null;
-	let a = _.safeParse(i);
+	let a = ue.safeParse(i);
 	if (!a.success) {
 		let e = t ? ` in ${t}` : "";
-		throw Error(`Invalid \`annot:\` frontmatter${e}:\n${fe(a.error)}`);
+		throw Error(`Invalid \`annot:\` frontmatter${e}:\n${Ce(a.error)}`);
 	}
 	return a.data;
 }
-function fe(e) {
-	return e.issues.map((e) => `  - ${e.path.length ? e.path.join(".") + ": " : ""}${e.message}`).join("\n");
+function Ce(e) {
+	return e.issues.map((e) => `  - ${e.path.length ? e.path.map(String).join(".") + ": " : ""}${e.message}`).join("\n");
 }
-function pe(e, t, n) {
+function we(e, t, n) {
 	let r = e;
 	switch (r.name) {
 		case "Screen":
-			n.screens.push(me(r, t));
+			n.screens.push(Te(r, t));
 			return;
 		case "Transition":
-			n.transitions.push(ge(r, t));
+			n.transitions.push(Oe(r, t));
 			return;
 		case "HistoryEntry":
-			n.history.push(_e(r, t));
+			n.history.push(ke(r, t));
 			return;
 		case "ScreenList":
-			n.screenLists.push(ve(r));
+			n.screenLists.push(Ae(r));
 			return;
 	}
 }
-function me(e, t) {
-	let n = C(e), r = [], i = (n) => {
-		let a = n;
-		if (a.name === "Overlay") {
-			r.push(he(a, t));
+function Te(e, t) {
+	let n = b(e), r = [], i = [], a = (n) => {
+		let o = n;
+		if (o.name === "Overlay") {
+			r.push(De(o, t));
+			return;
+		}
+		if (o.name === "AnnotCallout") {
+			i.push(Ee(o, t));
 			return;
 		}
-		if (!(a.name === "Screen" && a !== e)) for (let e of a.children ?? []) i(e);
+		if (!(o.name === "Screen" && o !== e)) for (let e of o.children ?? []) a(e);
 	};
-	for (let t of e.children ?? []) i(t);
-	let a = w(n.id);
-	if (!a) throw Error("<Screen> requires an `id` prop.");
+	for (let t of e.children ?? []) a(t);
+	let o = x(n.id);
+	if (!o) throw Error("<Screen> requires an `id` prop.");
+	let s = x(n.annotations), c = {
+		id: o,
+		src: x(n.src),
+		overlays: r,
+		callouts: i
+	};
+	return s && (c.annotations = s), c;
+}
+function Ee(e, t) {
+	let n = x(b(e).for);
+	if (!n) throw Error("<AnnotCallout> requires a `for=\"<overlay id>\"` prop.");
 	return {
-		id: a,
-		src: w(n.src),
-		overlays: r
+		for: n,
+		body: C(e, t)
 	};
 }
-function he(e, t) {
-	let n = C(e), r = n.match;
-	if (!T(r)) throw Error("<Overlay> requires a `match` prop with at least `{ role, name }`.");
+function De(e, t) {
+	let n = b(e), r = n.match;
+	if (!S(r)) throw Error("<Overlay> requires a `match` prop with at least `{ role, name }`.");
 	return {
 		match: r,
-		intent: w(n.intent),
-		number: xe(n.number),
-		body: E(e, t)
+		intent: x(n.intent),
+		number: Ne(n.number),
+		body: C(e, t)
 	};
 }
-function ge(e, t) {
-	let n = C(e), r = n.trigger;
-	if (!T(r)) throw Error("<Transition> requires a `trigger` prop with at least `{ role, name }`.");
+function Oe(e, t) {
+	let n = b(e), r = n.trigger;
+	if (!S(r)) throw Error("<Transition> requires a `trigger` prop with at least `{ role, name }`.");
 	return {
 		trigger: r,
-		on: w(n.on),
-		to: w(n.to),
-		body: E(e, t)
+		on: x(n.on),
+		to: x(n.to),
+		body: C(e, t)
 	};
 }
-function _e(e, t) {
-	let n = C(e), r = w(n.version) ?? "", i = w(n.date) ?? "", a = w(n.author) ?? "";
+function ke(e, t) {
+	let n = b(e), r = x(n.version) ?? "", i = x(n.date) ?? "", a = x(n.author) ?? "";
 	if (!r || !i) throw Error("<HistoryEntry> requires `version` and `date` props.");
 	return {
 		version: r,
 		date: i,
 		author: a,
-		body: E(e, t)
+		body: C(e, t)
 	};
 }
-function ve(e) {
-	let t = C(e);
+function Ae(e) {
+	let t = b(e);
 	return {
-		book: w(t.book),
-		sort: w(t.sort)
+		book: x(t.book),
+		sort: x(t.sort)
 	};
 }
-function ye(e, t) {
+function je(e, t) {
 	let n = e.value;
 	if (typeof n != "string") return;
-	let r = n.match(ue);
+	let r = n.match(be);
 	if (!r) return;
 	let i = (r[1] ?? "").trim(), a = (r[2] ?? "").trim();
 	switch (i) {
-		case y:
+		case ge:
 			t.snapshot = a;
 			return;
-		case b:
+		case ve:
 			t.attributes = a;
 			return;
-		case ce:
-		case le: return;
+		case _e:
+		case ye: return;
 	}
 }
-function C(e) {
+function b(e) {
 	let t = {};
 	for (let n of e.attributes ?? []) {
 		let e = n;
@@ -211,11 +234,11 @@ function C(e) {
 			continue;
 		}
 		let r = e.value;
-		r.type === "mdxJsxAttributeValueExpression" && typeof r.value == "string" && (t[e.name] = be(r.value));
+		r.type === "mdxJsxAttributeValueExpression" && typeof r.value == "string" && (t[e.name] = Me(r.value));
 	}
 	return t;
 }
-function be(e) {
+function Me(e) {
 	let t = e.trim();
 	if (t) {
 		if (t === "true") return !0;
@@ -246,18 +269,18 @@ function be(e) {
 		return t;
 	}
 }
-function w(e) {
+function x(e) {
 	return typeof e == "string" ? e : void 0;
 }
-function xe(e) {
+function Ne(e) {
 	return typeof e == "number" ? e : void 0;
 }
-function T(e) {
+function S(e) {
 	if (!e || typeof e != "object") return !1;
 	let t = e;
-	return !(typeof t.role != "string" || typeof t.name != "string" || t.under !== void 0 && !T(t.under));
+	return !(typeof t.role != "string" || typeof t.name != "string" || t.under !== void 0 && !S(t.under));
 }
-function E(e, t) {
+function C(e, t) {
 	let n = e.position;
 	if (!n) return "";
 	let r = t.slice(n.start.offset, n.end.offset);
@@ -265,24 +288,24 @@ function E(e, t) {
 	let i = r.indexOf(">"), a = r.lastIndexOf("</");
 	return i < 0 || a < 0 || a <= i ? "" : r.slice(i + 1, a).trim();
 }
-function D(e, t) {
+function w(e, t) {
 	let n = e;
-	return t.snapshot !== void 0 && (n = O(n, y, t.snapshot)), t.attributes !== void 0 && (n = O(n, b, t.attributes)), n;
+	return t.snapshot !== void 0 && (n = T(n, ge, t.snapshot)), t.attributes !== void 0 && (n = T(n, ve, t.attributes)), n;
 }
-function O(e, t, n) {
-	let r = new RegExp(String.raw`\{\s*/\*\s*` + Ce(t) + String.raw`\s*[\s\S]*?\*/\s*\}`, "m"), i = Se(t, n);
+function T(e, t, n) {
+	let r = new RegExp(String.raw`\{\s*/\*\s*` + Fe(t) + String.raw`\s*[\s\S]*?\*/\s*\}`, "m"), i = Pe(t, n);
 	return r.test(e) ? e.replace(r, i) : `${e.trimEnd()}\n\n${i}\n`;
 }
-function Se(e, t) {
+function Pe(e, t) {
 	let n = t.trim();
 	return n ? `{/* ${e}\n${n}\n*/}` : `{/* ${e} */}`;
 }
-function Ce(e) {
+function Fe(e) {
 	return e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //#endregion
 //#region src/fixture.ts
-var k = [
+var E = [
 	"type",
 	"required",
 	"placeholder",
@@ -298,34 +321,34 @@ var k = [
 	"aria-required",
 	"aria-disabled",
 	"aria-readonly"
-], we = t.extend({
+], Ie = n.extend({
 	productDocs: async ({ page: e }, t) => {
-		await t({ sync: (t) => A(e, t) });
+		await t({ sync: (t) => D(e, t) });
 	},
 	screen: async ({ page: e }, t) => {
-		let n = (t) => A(e, t);
+		let n = (t) => D(e, t);
 		await t({
 			sync: n,
 			capture: n
 		});
 	}
 });
-async function A(e, t) {
-	let n = await x(t.mdxPath);
+async function D(e, t) {
+	let n = await y(t.mdxPath);
 	if (!n) throw Error(`syncProductDocs: ${t.mdxPath} has no \`annot:\` frontmatter — refusing to write.`);
 	let r = n.screens.find((e) => e.id === t.id);
 	if (!r) throw Error(`syncProductDocs: ${t.mdxPath} has no <Screen id="${t.id}"> block.`);
 	let i = await (t.rootLocator ?? e.locator("body")).ariaSnapshot({
 		mode: "ai",
 		boxes: !0
-	}), o = await j(e, r.overlays, t.attributeWhitelist ?? k), s = D(n.source, {
+	}), a = await O(e, r.overlays, t.attributeWhitelist ?? E), s = w(n.source, {
 		snapshot: i.trim(),
-		attributes: o
+		attributes: a
 	});
-	await a(t.mdxPath, s, "utf8");
+	await o(t.mdxPath, s, "utf8");
 }
-var Te = A;
-async function j(e, t, n) {
+var Le = D;
+async function O(e, t, n) {
 	let r = [];
 	for (let i of t) {
 		let t = e.getByRole(i.match.role, {
@@ -350,7 +373,7 @@ async function j(e, t, n) {
 }
 //#endregion
 //#region src/mdx-annotations.ts
-function M(e) {
+function k(e) {
 	let t = [];
 	for (let n of e.split(/\r?\n/)) {
 		if (!n.trim()) continue;
@@ -371,7 +394,18 @@ function M(e) {
 	}
 	return t;
 }
-function N(e, t, n) {
+function Re(e) {
+	let t = [];
+	return ae(e, (e) => {
+		e.bbox && e.name && t.push({
+			role: e.role,
+			name: e.name,
+			ref: e.ref,
+			box: e.bbox
+		});
+	}), t;
+}
+function ze(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);
@@ -389,44 +423,747 @@ function N(e, t, n) {
 	}
 	return r;
 }
-async function P(e) {
-	let t = e.cwd ?? process.cwd(), n = await x(ee(e.mdxPath) ? e.mdxPath : h(t, e.mdxPath));
+function Be(e, t, n) {
+	let r = [];
+	for (let i of e) {
+		let e = t.find((e) => e.role === i.match.role && e.name === i.match.name);
+		e && r.push({
+			type: "numberedBadge",
+			bbox: e.box,
+			number: i.number,
+			placement: "auto",
+			imageWidth: n.width,
+			imageHeight: n.height,
+			intent: i.intent === "action" ? "warning" : i.intent === "required" ? "error" : "info"
+		});
+	}
+	return r;
+}
+async function Ve(e) {
+	let t = e.cwd ?? process.cwd(), n = await y(h(e.mdxPath) ? e.mdxPath : _(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 = M(n.commentBlocks.snapshot ?? "");
-	return N(r.overlays, i, e.dims);
+	let i = k(n.commentBlocks.snapshot ?? "");
+	return ze(r.overlays, i, e.dims);
+}
+function He(e) {
+	return `<svg xmlns="http://www.w3.org/2000/svg">${v(e)}</svg>`;
+}
+function Ue(e, t, n) {
+	let r = [];
+	for (let i of e) {
+		let e = Ge(i, t, n);
+		e && r.push(e);
+	}
+	return r;
+}
+function We(e, t) {
+	let n = [];
+	for (let r of e) {
+		if (r.kind !== "redact" || r.style !== "mosaic" && r.style !== "blur") continue;
+		let e = null;
+		if (r.match) {
+			let n = j(t, r.match);
+			if (!n) continue;
+			e = n.box;
+		} else r.bbox && (e = r.bbox);
+		if (!e) continue;
+		let i = {
+			bbox: e,
+			style: r.style
+		};
+		r.color !== void 0 && (i.color = r.color), n.push(i);
+	}
+	return n;
+}
+function Ge(e, t, n) {
+	switch (e.kind) {
+		case "rect": return Ke(e, t);
+		case "circle": return qe(e, t);
+		case "arrow": return Je(e, t);
+		case "text": return Xe(e, t);
+		case "callout": return Qe(e, t);
+		case "freehand": return $e(e);
+		case "redact": return tt(e, t);
+		case "focusMask": return nt(e, t, n);
+	}
 }
-function Ee(e) {
-	return `<svg xmlns="http://www.w3.org/2000/svg">${g(e)}</svg>`;
+function Ke(e, t) {
+	let n = null;
+	if (e.match) {
+		let r = j(t, e.match);
+		if (!r) return null;
+		n = r.box;
+	} else if (e.coversElements) {
+		let r = [];
+		for (let n of e.coversElements) {
+			let e = j(t, n);
+			if (!e) return null;
+			r.push(e.box);
+		}
+		n = it(r);
+	} else e.bbox && (n = e.bbox);
+	return n ? N({
+		type: "rect",
+		bbox: n
+	}, e) : null;
+}
+function qe(e, t) {
+	if (e.match) {
+		let n = j(t, e.match);
+		return n ? N({
+			type: "circle",
+			center: rt(n.box),
+			radius: e.radius ?? Math.max(n.box.width, n.box.height) / 2
+		}, e) : null;
+	}
+	return e.center && e.radius !== void 0 ? N({
+		type: "circle",
+		center: e.center,
+		radius: e.radius
+	}, e) : null;
+}
+function Je(e, t) {
+	let n = Ye(e.from, t);
+	if (!n) return null;
+	let r = Ye(e.to, t);
+	return r ? N({
+		type: "arrow",
+		from: n,
+		to: r
+	}, e) : null;
+}
+function Ye(e, t) {
+	if ("point" in e) return e.point;
+	let n = j(t, e.match);
+	return n ? rt(n.box) : null;
+}
+var A = 8;
+function Xe(e, t) {
+	let n, r;
+	if (e.anchor) {
+		let i = j(t, e.anchor.match);
+		if (!i) return null;
+		let a = Ze(i.box, e.anchor.position ?? "above");
+		n = a.at, r = a.anchor;
+	} else if (e.at) n = e.at, r = "start";
+	else return null;
+	let i = {
+		type: "text",
+		at: n,
+		content: e.text,
+		anchor: r
+	};
+	return e.fontSize !== void 0 && (i.fontSize = e.fontSize), N(i, e);
+}
+function Ze(e, t) {
+	let n = e.x + e.width / 2, r = e.y + e.height / 2;
+	switch (t) {
+		case "above": return {
+			at: {
+				x: n,
+				y: e.y - A
+			},
+			anchor: "middle"
+		};
+		case "below": return {
+			at: {
+				x: n,
+				y: e.y + e.height + A
+			},
+			anchor: "middle"
+		};
+		case "left": return {
+			at: {
+				x: e.x - A,
+				y: r
+			},
+			anchor: "end"
+		};
+		case "right": return {
+			at: {
+				x: e.x + e.width + A,
+				y: r
+			},
+			anchor: "start"
+		};
+		case "center": return {
+			at: {
+				x: n,
+				y: r
+			},
+			anchor: "middle"
+		};
+	}
+}
+function Qe(e, t) {
+	let n = null;
+	if ("match" in e.target) {
+		let r = j(t, e.target.match);
+		if (!r) return null;
+		n = r.box;
+	} else n = e.target.bbox;
+	return N({
+		type: "callout",
+		at: e.at,
+		targetBbox: n,
+		content: e.text
+	}, e);
 }
-function De(e) {
-	return e.length === 0 ? F() : `<svg xmlns="http://www.w3.org/2000/svg">${g(e)}</svg>`;
+function $e(e) {
+	return N({
+		type: "freehand",
+		path: e.path
+	}, e);
 }
-function F() {
+var et = "#222222";
+function tt(e, t) {
+	if (e.style === "mosaic" || e.style === "blur") return null;
+	let n = null;
+	if (e.match) {
+		let r = j(t, e.match);
+		if (!r) return null;
+		n = r.box;
+	} else e.bbox && (n = e.bbox);
+	return n ? {
+		type: "rect",
+		bbox: n,
+		fill: e.fill ?? et,
+		stroke: e.stroke ?? "none",
+		strokeWidth: e.strokeWidth ?? 0,
+		...e.intent ? { intent: M(e.intent) } : {}
+	} : null;
+}
+function nt(e, t, n) {
+	let r = null;
+	if ("match" in e.cutout) {
+		let n = j(t, e.cutout.match);
+		if (!n) return null;
+		let i = e.cutout.padding ?? 0;
+		r = at(n.box, i);
+	} else r = e.cutout.bbox;
+	let i = {
+		type: "focusMask",
+		cutout: r,
+		imageWidth: n.width,
+		imageHeight: n.height
+	};
+	return e.dimColor !== void 0 && (i.dimColor = e.dimColor), N(i, e);
+}
+function j(e, t) {
+	return e.find((e) => e.role === t.role && e.name === t.name);
+}
+function rt(e) {
+	return {
+		x: e.x + e.width / 2,
+		y: e.y + e.height / 2
+	};
+}
+function it(e) {
+	let t = Math.min(...e.map((e) => e.x)), n = Math.min(...e.map((e) => e.y)), r = Math.max(...e.map((e) => e.x + e.width)), i = Math.max(...e.map((e) => e.y + e.height));
+	return {
+		x: t,
+		y: n,
+		width: r - t,
+		height: i - n
+	};
+}
+function at(e, t) {
+	return t <= 0 ? e : {
+		x: e.x - t,
+		y: e.y - t,
+		width: e.width + t * 2,
+		height: e.height + t * 2
+	};
+}
+function M(e) {
+	if (e !== void 0) switch (e) {
+		case "required": return "error";
+		case "action": return "warning";
+		case "info":
+		case "warning":
+		case "error":
+		case "success":
+		case "neutral": return e;
+	}
+}
+function N(e, t) {
+	let n = M(t.intent), r = { ...e };
+	return n !== void 0 && !("intent" in r) && (r.intent = n), n !== void 0 && r.intent === void 0 && (r.intent = n), t.stroke !== void 0 && (r.stroke = t.stroke), t.strokeWidth !== void 0 && (r.strokeWidth = t.strokeWidth), t.fill !== void 0 && (r.fill = t.fill), t.color !== void 0 && (r.color = t.color), r;
+}
+function ot(e) {
+	return e.length === 0 ? st() : `<svg xmlns="http://www.w3.org/2000/svg">${v(e)}</svg>`;
+}
+function st() {
 	return "<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>";
 }
 //#endregion
 //#region src/playwright-screenshot-hook.ts
-var I = Symbol.for("@ingcreators/annot-product-docs:mdx-resolver"), L = async ({ annot: e, page: t }) => {
+var ct = Symbol.for("@ingcreators/annot-product-docs:mdx-resolver"), lt = async ({ annot: e, page: t }) => {
 	if (!e.mdx) return null;
 	let { id: n, path: r } = e.mdx;
 	return {
-		prepare: () => A(t, {
+		prepare: () => D(t, {
 			id: n,
 			mdxPath: r
 		}),
-		resolveAnnotations: (e) => P({
+		resolveAnnotations: (e) => Ve({
 			mdxPath: r,
 			screenId: n,
 			dims: e
 		})
 	};
-}, R = L;
-R[I] || (R[I] = !0, e.push(L));
+}, ut = lt;
+ut[ct] || (ut[ct] = !0, e.push(lt));
+//#endregion
+//#region src/annotations-yaml.ts
+var dt = 1, P = [
+	"rect",
+	"circle",
+	"arrow",
+	"text",
+	"callout",
+	"freehand",
+	"redact",
+	"focusMask"
+], F = class extends Error {
+	source;
+	constructor(e, t) {
+		super(e), this.source = t, this.name = "AnnotationsYamlError";
+	}
+};
+function ft(e) {
+	let t;
+	try {
+		t = l(e);
+	} catch (t) {
+		throw new F(`Failed to parse annotations yaml: ${t.message}`, e);
+	}
+	if (!t || typeof t != "object") throw new F("Annotations yaml must be a mapping", e);
+	let n = t, r = n.version;
+	if (r !== 1) throw new F(`Unsupported annotations yaml version: expected 1, got ${JSON.stringify(r)}`, e);
+	let i = n.overlays;
+	if (!Array.isArray(i)) throw new F("Annotations yaml `overlays` must be an array", e);
+	let a = {
+		version: 1,
+		overlays: i.map((e, t) => mt(e, t))
+	}, o = n.annotations;
+	if (o !== void 0) {
+		if (!Array.isArray(o)) throw new F("Annotations yaml `annotations` must be an array", e);
+		let t = o.map((e, t) => _t(e, t));
+		t.length > 0 && (a.annotations = t);
+	}
+	let s = n.meta;
+	if (s && typeof s == "object" && !Array.isArray(s)) {
+		let e = {};
+		for (let [t, n] of Object.entries(s)) typeof n == "string" && (e[t] = n);
+		Object.keys(e).length > 0 && (a.meta = e);
+	}
+	return a;
+}
+function pt(e) {
+	for (let t of e.overlays) {
+		if (typeof t.id != "string" || t.id.length === 0) throw new F(`Overlay entry missing id: ${JSON.stringify(t)}`);
+		if (!t.match || typeof t.match.role != "string" || typeof t.match.name != "string") throw new F(`Overlay entry ${t.id}: match must have string role + name`);
+		if (typeof t.number != "number" || !Number.isFinite(t.number)) throw new F(`Overlay entry ${t.id}: number must be a finite number`);
+	}
+	if (e.annotations) for (let t of e.annotations) jt(t);
+	let t = {
+		version: e.version,
+		overlays: e.overlays.map(gt)
+	};
+	return e.annotations && e.annotations.length > 0 && (t.annotations = e.annotations.map(Ot)), e.meta && Object.keys(e.meta).length > 0 && (t.meta = { ...e.meta }), c(t, {
+		lineWidth: -1,
+		noRefs: !0,
+		sortKeys: !1
+	});
+}
+function mt(e, t) {
+	if (!e || typeof e != "object") throw new F(`Overlay #${t}: not a mapping`);
+	let n = e, r = n.id;
+	if (typeof r != "string" || r.length === 0) throw new F(`Overlay #${t}: missing or empty id`);
+	let i = n.kind;
+	if (i !== "numberedBadge") throw new F(`Overlay ${r}: unsupported kind ${JSON.stringify(i)} (expected "numberedBadge")`);
+	let a = ht(n.match, r), o = n.number;
+	if (typeof o != "number" || !Number.isFinite(o)) throw new F(`Overlay ${r}: number must be a finite number`);
+	let s = {
+		id: r,
+		kind: "numberedBadge",
+		match: a,
+		number: o
+	}, c = n.intent;
+	return typeof c == "string" && (s.intent = c), s;
+}
+function ht(e, t) {
+	if (!e || typeof e != "object") throw new F(`Overlay ${t}: match must be a mapping`);
+	let n = e, r = n.role, i = n.name;
+	if (typeof r != "string" || typeof i != "string") throw new F(`Overlay ${t}: match.role and match.name must both be strings`);
+	let a = {
+		role: r,
+		name: i
+	};
+	return n.under !== void 0 && (a.under = ht(n.under, t)), a;
+}
+function gt(e) {
+	let t = {
+		id: e.id,
+		kind: e.kind,
+		match: I(e.match)
+	};
+	return e.intent !== void 0 && (t.intent = e.intent), t.number = e.number, t;
+}
+function I(e) {
+	let t = {
+		role: e.role,
+		name: e.name
+	};
+	return e.under && (t.under = I(e.under)), t;
+}
+function _t(e, t) {
+	if (!e || typeof e != "object") throw new F(`Annotation #${t}: not a mapping`);
+	let n = e, r = n.id;
+	if (typeof r != "string" || r.length === 0) throw new F(`Annotation #${t}: missing or empty id`);
+	let i = n.kind;
+	if (typeof i != "string" || !P.includes(i)) throw new F(`Annotation ${r}: unsupported kind ${JSON.stringify(i)} (expected one of ${P.join(", ")})`);
+	switch (i) {
+		case "rect": return vt(r, n);
+		case "circle": return yt(r, n);
+		case "arrow": return bt(r, n);
+		case "text": return St(r, n);
+		case "callout": return Ct(r, n);
+		case "freehand": return wt(r, n);
+		case "redact": return Tt(r, n);
+		case "focusMask": return Et(r, n);
+	}
+}
+function vt(e, t) {
+	let n = t.match !== void 0, r = t.coversElements !== void 0, i = t.bbox !== void 0;
+	B(e, "rect", {
+		match: n,
+		coversElements: r,
+		bbox: i
+	});
+	let a = {
+		id: e,
+		kind: "rect"
+	};
+	return n && (a.match = L(e, t.match)), r && (a.coversElements = Dt(e, t.coversElements)), i && (a.bbox = z(e, t.bbox)), V(t, a), a;
+}
+function yt(e, t) {
+	let n = t.match !== void 0, r = t.center !== void 0;
+	B(e, "circle", {
+		match: n,
+		center: r
+	});
+	let i = {
+		id: e,
+		kind: "circle"
+	};
+	if (n && (i.match = L(e, t.match)), r) {
+		i.center = R(e, t.center);
+		let n = t.radius;
+		if (typeof n != "number" || !Number.isFinite(n) || n < 0) throw new F(`Annotation ${e}: circle with \`center\` requires a finite non-negative \`radius\``);
+		i.radius = n;
+	} else {
+		let n = t.radius;
+		if (n !== void 0) {
+			if (typeof n != "number" || !Number.isFinite(n) || n < 0) throw new F(`Annotation ${e}: circle \`radius\` must be a finite non-negative number`);
+			i.radius = n;
+		}
+	}
+	return V(t, i), i;
+}
+function bt(e, t) {
+	let n = {
+		id: e,
+		kind: "arrow",
+		from: xt(e, "from", t.from),
+		to: xt(e, "to", t.to)
+	};
+	return V(t, n), n;
+}
+function xt(e, t, n) {
+	if (!n || typeof n != "object") throw new F(`Annotation ${e}: arrow.${t} must be a mapping with \`match\` or \`point\``);
+	let r = n, i = r.match !== void 0;
+	if (i === (r.point !== void 0)) throw new F(`Annotation ${e}: arrow.${t} requires exactly one of \`match\` / \`point\``);
+	return i ? { match: L(e, r.match) } : { point: R(e, r.point) };
+}
+function St(e, t) {
+	let n = t.text;
+	if (typeof n != "string" || n.length === 0) throw new F(`Annotation ${e}: text requires a non-empty \`text\` string`);
+	let r = t.anchor !== void 0, i = t.at !== void 0;
+	B(e, "text", {
+		anchor: r,
+		at: i
+	});
+	let a = {
+		id: e,
+		kind: "text",
+		text: n
+	};
+	if (r) {
+		let n = t.anchor;
+		if (!n || typeof n != "object") throw new F(`Annotation ${e}: text.anchor must be a mapping`);
+		let r = n, i = { match: L(e, r.match) }, o = r.position;
+		if (o !== void 0) {
+			if (typeof o != "string" || ![
+				"above",
+				"below",
+				"left",
+				"right",
+				"center"
+			].includes(o)) throw new F(`Annotation ${e}: text.anchor.position must be one of above / below / left / right / center`);
+			i.position = o;
+		}
+		a.anchor = i;
+	}
+	i && (a.at = R(e, t.at));
+	let o = t.fontSize;
+	if (o !== void 0) {
+		if (typeof o != "number" || !Number.isFinite(o) || o <= 0) throw new F(`Annotation ${e}: text.fontSize must be a finite positive number`);
+		a.fontSize = o;
+	}
+	return V(t, a), a;
+}
+function Ct(e, t) {
+	let n = t.text;
+	if (typeof n != "string" || n.length === 0) throw new F(`Annotation ${e}: callout requires a non-empty \`text\` string`);
+	let r = t.target;
+	if (!r || typeof r != "object") throw new F(`Annotation ${e}: callout.target must be a mapping with \`match\` or \`bbox\``);
+	let i = r, a = i.match !== void 0;
+	if (a === (i.bbox !== void 0)) throw new F(`Annotation ${e}: callout.target requires exactly one of \`match\` / \`bbox\``);
+	let o = a ? { match: L(e, i.match) } : { bbox: z(e, i.bbox) }, s = t.at;
+	if (s === void 0) throw new F(`Annotation ${e}: callout requires an \`at\` point`);
+	let c = {
+		id: e,
+		kind: "callout",
+		text: n,
+		target: o,
+		at: R(e, s)
+	};
+	return V(t, c), c;
+}
+function wt(e, t) {
+	let n = t.path;
+	if (typeof n != "string" || n.length === 0) throw new F(`Annotation ${e}: freehand requires a non-empty \`path\` string`);
+	let r = {
+		id: e,
+		kind: "freehand",
+		path: n
+	};
+	return V(t, r), r;
+}
+function Tt(e, t) {
+	let n = t.match !== void 0, r = t.bbox !== void 0;
+	B(e, "redact", {
+		match: n,
+		bbox: r
+	});
+	let i = {
+		id: e,
+		kind: "redact"
+	};
+	n && (i.match = L(e, t.match)), r && (i.bbox = z(e, t.bbox));
+	let a = t.style;
+	if (a !== void 0) {
+		if (a !== "solid" && a !== "mosaic" && a !== "blur") throw new F(`Annotation ${e}: redact.style must be one of "solid" / "mosaic" / "blur"`);
+		i.style = a;
+	}
+	return V(t, i), i;
+}
+function Et(e, t) {
+	let n = t.cutout;
+	if (!n || typeof n != "object") throw new F(`Annotation ${e}: focusMask.cutout must be a mapping with \`match\` or \`bbox\``);
+	let r = n, i = r.match !== void 0;
+	if (i === (r.bbox !== void 0)) throw new F(`Annotation ${e}: focusMask.cutout requires exactly one of \`match\` / \`bbox\``);
+	let a;
+	if (i) {
+		let t = L(e, r.match), n = r.padding;
+		if (n !== void 0) {
+			if (typeof n != "number" || !Number.isFinite(n) || n < 0) throw new F(`Annotation ${e}: focusMask.cutout.padding must be a finite non-negative number`);
+			a = {
+				match: t,
+				padding: n
+			};
+		} else a = { match: t };
+	} else a = { bbox: z(e, r.bbox) };
+	let o = {
+		id: e,
+		kind: "focusMask",
+		cutout: a
+	}, s = t.dimColor;
+	if (s !== void 0) {
+		if (typeof s != "string") throw new F(`Annotation ${e}: focusMask.dimColor must be a string`);
+		o.dimColor = s;
+	}
+	return V(t, o), o;
+}
+function L(e, t) {
+	if (!t || typeof t != "object") throw new F(`Annotation ${e}: match must be a mapping`);
+	let n = t, r = n.role, i = n.name;
+	if (typeof r != "string" || typeof i != "string") throw new F(`Annotation ${e}: match.role and match.name must both be strings`);
+	let a = {
+		role: r,
+		name: i
+	};
+	return n.under !== void 0 && (a.under = L(e, n.under)), a;
+}
+function Dt(e, t) {
+	if (!Array.isArray(t) || t.length === 0) throw new F(`Annotation ${e}: coversElements must be a non-empty array of match objects`);
+	return t.map((t) => L(e, t));
+}
+function R(e, t) {
+	if (!t || typeof t != "object") throw new F(`Annotation ${e}: point must be a mapping`);
+	let n = t, r = n.x, i = n.y;
+	if (typeof r != "number" || !Number.isFinite(r) || typeof i != "number" || !Number.isFinite(i)) throw new F(`Annotation ${e}: point.x and point.y must be finite numbers`);
+	return {
+		x: r,
+		y: i
+	};
+}
+function z(e, t) {
+	if (!t || typeof t != "object") throw new F(`Annotation ${e}: bbox must be a mapping`);
+	let n = t, r = n.x, i = n.y, a = n.width, o = n.height;
+	if (typeof r != "number" || !Number.isFinite(r) || typeof i != "number" || !Number.isFinite(i) || typeof a != "number" || !Number.isFinite(a) || a < 0 || typeof o != "number" || !Number.isFinite(o) || o < 0) throw new F(`Annotation ${e}: bbox requires finite numeric x / y + non-negative width / height`);
+	return {
+		x: r,
+		y: i,
+		width: a,
+		height: o
+	};
+}
+function B(e, t, n) {
+	if (Object.entries(n).filter(([, e]) => e).length !== 1) throw new F(`Annotation ${e}: ${t} requires exactly one of ${Object.keys(n).join(" / ")}`);
+}
+function V(e, t) {
+	let n = e.intent;
+	typeof n == "string" && (t.intent = n);
+	let r = e.stroke;
+	typeof r == "string" && (t.stroke = r);
+	let i = e.strokeWidth;
+	typeof i == "number" && Number.isFinite(i) && i >= 0 && (t.strokeWidth = i);
+	let a = e.fill;
+	typeof a == "string" && (t.fill = a);
+	let o = e.color;
+	typeof o == "string" && (t.color = o);
+}
+function Ot(e) {
+	let t = {
+		id: e.id,
+		kind: e.kind
+	};
+	switch (e.kind) {
+		case "rect":
+			e.match && (t.match = I(e.match)), e.coversElements && (t.coversElements = e.coversElements.map(I)), e.bbox && (t.bbox = H(e.bbox));
+			break;
+		case "circle":
+			e.match && (t.match = I(e.match)), e.center && (t.center = U(e.center)), e.radius !== void 0 && (t.radius = e.radius);
+			break;
+		case "arrow":
+			t.from = kt(e.from), t.to = kt(e.to);
+			break;
+		case "text":
+			if (t.text = e.text, e.anchor) {
+				let n = { match: I(e.anchor.match) };
+				e.anchor.position && (n.position = e.anchor.position), t.anchor = n;
+			}
+			e.at && (t.at = U(e.at)), e.fontSize !== void 0 && (t.fontSize = e.fontSize);
+			break;
+		case "callout":
+			t.text = e.text, "match" in e.target ? t.target = { match: I(e.target.match) } : t.target = { bbox: H(e.target.bbox) }, t.at = U(e.at);
+			break;
+		case "freehand":
+			t.path = e.path;
+			break;
+		case "redact":
+			e.match && (t.match = I(e.match)), e.bbox && (t.bbox = H(e.bbox)), e.style !== void 0 && (t.style = e.style);
+			break;
+		case "focusMask":
+			if ("match" in e.cutout) {
+				let n = { match: I(e.cutout.match) };
+				e.cutout.padding !== void 0 && (n.padding = e.cutout.padding), t.cutout = n;
+			} else t.cutout = { bbox: H(e.cutout.bbox) };
+			e.dimColor !== void 0 && (t.dimColor = e.dimColor);
+			break;
+	}
+	return At(t, e), t;
+}
+function kt(e) {
+	return "match" in e ? { match: I(e.match) } : { point: U(e.point) };
+}
+function H(e) {
+	return {
+		x: e.x,
+		y: e.y,
+		width: e.width,
+		height: e.height
+	};
+}
+function U(e) {
+	return {
+		x: e.x,
+		y: e.y
+	};
+}
+function At(e, t) {
+	t.intent !== void 0 && (e.intent = t.intent), t.stroke !== void 0 && (e.stroke = t.stroke), t.strokeWidth !== void 0 && (e.strokeWidth = t.strokeWidth), t.fill !== void 0 && (e.fill = t.fill), t.color !== void 0 && (e.color = t.color);
+}
+function jt(e) {
+	if (typeof e.id != "string" || e.id.length === 0) throw new F(`Annotation entry missing id: ${JSON.stringify(e)}`);
+	if (!P.includes(e.kind)) throw new F(`Annotation ${e.id}: unknown kind ${JSON.stringify(e.kind)}`);
+	switch (e.kind) {
+		case "rect":
+			if ([
+				e.match !== void 0,
+				e.coversElements !== void 0,
+				e.bbox !== void 0
+			].filter(Boolean).length !== 1) throw new F(`Annotation ${e.id}: rect requires exactly one of match / coversElements / bbox`);
+			if (e.coversElements && e.coversElements.length === 0) throw new F(`Annotation ${e.id}: rect.coversElements must be non-empty`);
+			break;
+		case "circle":
+			if ([e.match !== void 0, e.center !== void 0].filter(Boolean).length !== 1) throw new F(`Annotation ${e.id}: circle requires exactly one of match / center`);
+			if (e.center && (e.radius === void 0 || !Number.isFinite(e.radius) || e.radius < 0)) throw new F(`Annotation ${e.id}: circle with center requires a finite non-negative radius`);
+			break;
+		case "arrow":
+			if (!e.from || !e.to) throw new F(`Annotation ${e.id}: arrow requires both from + to`);
+			break;
+		case "text":
+			if (typeof e.text != "string" || e.text.length === 0) throw new F(`Annotation ${e.id}: text requires non-empty \`text\``);
+			if ([e.anchor !== void 0, e.at !== void 0].filter(Boolean).length !== 1) throw new F(`Annotation ${e.id}: text requires exactly one of anchor / at`);
+			break;
+		case "callout":
+			if (typeof e.text != "string" || e.text.length === 0) throw new F(`Annotation ${e.id}: callout requires non-empty \`text\``);
+			if (!e.target || !e.at) throw new F(`Annotation ${e.id}: callout requires target + at`);
+			break;
+		case "freehand":
+			if (typeof e.path != "string" || e.path.length === 0) throw new F(`Annotation ${e.id}: freehand requires non-empty \`path\``);
+			break;
+		case "redact":
+			if ([e.match !== void 0, e.bbox !== void 0].filter(Boolean).length !== 1) throw new F(`Annotation ${e.id}: redact requires exactly one of match / bbox`);
+			if (e.style !== void 0 && e.style !== "solid" && e.style !== "mosaic" && e.style !== "blur") throw new F(`Annotation ${e.id}: redact.style must be one of "solid" / "mosaic" / "blur"`);
+			break;
+		case "focusMask":
+			if (!e.cutout) throw new F(`Annotation ${e.id}: focusMask requires cutout`);
+			break;
+	}
+}
+//#endregion
+//#region src/deprecation.ts
+var W = /* @__PURE__ */ new Set();
+function Mt(e, t = (e) => console.warn(e)) {
+	let n = `${e.mdxPath}\0${e.screenId}`;
+	W.has(n) || (W.add(n), t(Nt(e)));
+}
+function Nt(e) {
+	return `[annot-docs] DEPRECATED: ${e.mdxPath} screen "${e.screenId}" uses ${e.overlayCount} inline <Overlay> block(s). Run \`annot docs migrate-overlays-to-annotations\` to extract them into a \`.annotations.yaml\` file + <AnnotCallout for=…> JSX. The inline <Overlay> form is supported during a deprecation window; see OQ-08 in docs/plans/living-spec-authoring-roadmap.md for the removal schedule.`;
+}
+function Pt() {
+	W.clear();
+}
 //#endregion
 //#region src/resolver.ts
-function z(e) {
+function G(e) {
 	let t = [], n = e.split(/\r?\n/), r = [];
 	for (let e of n) {
 		if (!e.trim()) continue;
@@ -452,16 +1189,16 @@ function z(e) {
 	}
 	return t;
 }
-async function B(e, t, n) {
-	let r = Ae(t.filter((t) => t.role === e.role && t.name === e.name), e.under);
-	if (r.length === 0) return je(e, t);
+async function Ft(e, t, n) {
+	let r = Rt(t.filter((t) => t.role === e.role && t.name === e.name), e.under);
+	if (r.length === 0) return zt(e, t);
 	if (r.length > 1) return {
 		ok: !1,
 		kind: "ambiguous",
 		reason: `Multiple elements match role="${e.role}" name="${e.name}". Use \`under\` to disambiguate.`,
 		candidates: r.map((e) => `[ref=${e.ref}]`)
 	};
-	let i = r[0], a = ke(n, e), o = await a.count();
+	let i = r[0], a = Lt(n, e), o = await a.count();
 	return o === 0 ? {
 		ok: !1,
 		kind: "live-mismatch",
@@ -476,15 +1213,15 @@ async function B(e, t, n) {
 		entry: i
 	};
 }
-async function Oe(e, t, n) {
+async function It(e, t, n) {
 	let r = [];
 	for (let i of e) r.push({
 		overlay: i,
-		result: await B(i.match, t, n)
+		result: await Ft(i.match, t, n)
 	});
 	return r;
 }
-function ke(e, t) {
+function Lt(e, t) {
 	let n = e.getByRole(t.role, {
 		name: t.name,
 		exact: !0
@@ -497,10 +1234,10 @@ function ke(e, t) {
 		exact: !0
 	})), n;
 }
-function Ae(e, t) {
+function Rt(e, t) {
 	return t ? e.filter((e) => e.ancestors.some((e) => e.role === t.role && e.name === t.name)) : e;
 }
-function je(e, t) {
+function zt(e, t) {
 	let n = t.filter((t) => t.name === e.name);
 	if (n.length === 1 && n[0].role !== e.role) return {
 		ok: !1,
@@ -510,7 +1247,7 @@ function je(e, t) {
 	};
 	let r = t.filter((t) => t.role === e.role);
 	if (r.length > 0) {
-		let t = Me(e.name, r.map((e) => e.name));
+		let t = Bt(e.name, r.map((e) => e.name));
 		if (t) return {
 			ok: !1,
 			kind: "renamed",
@@ -524,16 +1261,16 @@ function je(e, t) {
 		reason: `No element with role="${e.role}" name="${e.name}".`
 	};
 }
-function Me(e, t) {
+function Bt(e, t) {
 	if (t.length === 0) return null;
-	let n = t[0], r = V(e, n);
+	let n = t[0], r = Vt(e, n);
 	for (let i of t.slice(1)) {
-		let t = V(e, i);
+		let t = Vt(e, i);
 		t > r && (n = i, r = t);
 	}
 	return r > .3 ? n : null;
 }
-function V(e, t) {
+function Vt(e, t) {
 	if (!e || !t) return 0;
 	let n = (e) => {
 		let t = /* @__PURE__ */ new Set();
@@ -547,12 +1284,12 @@ function V(e, t) {
 }
 //#endregion
 //#region src/drift.ts
-function H(e) {
-	let { screen: t, liveSnapshot: n, storedAttributesYaml: r, freshAttributesYaml: i } = e, a = [], o = /* @__PURE__ */ new Set();
-	for (let e of t.overlays) {
+function K(e) {
+	let { screen: t, liveSnapshot: n, storedAttributesYaml: r, freshAttributesYaml: i, yamlOverlays: a, yamlAnnotations: o } = e, s = [], c = a ?? t.overlays, l = /* @__PURE__ */ new Set();
+	for (let e of c) {
 		let r = n.filter((t) => t.role === e.match.role && t.name === e.match.name);
 		if (r.length > 1) {
-			a.push({
+			s.push({
 				severity: "error",
 				kind: "duplicated",
 				screenId: t.id,
@@ -565,7 +1302,7 @@ function H(e) {
 		let i = n.filter((t) => t.name === e.match.name);
 		if (i.length === 1 && i[0].role !== e.match.role) {
 			let n = i[0];
-			o.add(`${n.role}|${n.name}`), a.push({
+			l.add(`${n.role}|${n.name}`), s.push({
 				severity: "warning",
 				kind: "role-changed",
 				screenId: t.id,
@@ -575,11 +1312,11 @@ function H(e) {
 			});
 			continue;
 		}
-		let s = n.filter((t) => t.role === e.match.role);
-		if (s.length > 0) {
-			let n = Ie(e.match.name, s.map((e) => e.name));
+		let a = n.filter((t) => t.role === e.match.role);
+		if (a.length > 0) {
+			let n = qt(e.match.name, a.map((e) => e.name));
 			if (n) {
-				o.add(`${e.match.role}|${n}`), a.push({
+				l.add(`${e.match.role}|${n}`), s.push({
 					severity: "warning",
 					kind: "renamed",
 					screenId: t.id,
@@ -590,7 +1327,7 @@ function H(e) {
 				continue;
 			}
 		}
-		a.push({
+		s.push({
 			severity: "error",
 			kind: "removed",
 			screenId: t.id,
@@ -598,11 +1335,11 @@ function H(e) {
 			match: e.match
 		});
 	}
-	let s = new Set(t.overlays.map((e) => `${e.match.role}|${e.match.name}`));
+	let u = new Set(c.map((e) => `${e.match.role}|${e.match.name}`));
 	for (let e of n) {
-		if (!Fe(e.role)) continue;
+		if (!Kt(e.role)) continue;
 		let n = `${e.role}|${e.name}`;
-		s.has(n) || o.has(n) || a.push({
+		u.has(n) || l.has(n) || s.push({
 			severity: "warning",
 			kind: "added",
 			screenId: t.id,
@@ -613,22 +1350,114 @@ function H(e) {
 			}
 		});
 	}
-	return r !== void 0 && i !== void 0 && G(r) !== G(i) && a.push({
+	if (o !== void 0) for (let e of o) for (let r of Zt(e)) {
+		let i = n.filter((e) => e.role === r.role && e.name === r.name);
+		if (i.length > 1) {
+			s.push({
+				severity: "error",
+				kind: "duplicated",
+				screenId: t.id,
+				message: `Annotation ${e.id}: multiple elements match role="${r.role}" name="${r.name}". Use \`under\` to disambiguate.`,
+				match: r
+			});
+			continue;
+		}
+		if (i.length === 1) continue;
+		let a = n.filter((e) => e.name === r.name);
+		if (a.length === 1 && a[0].role !== r.role) {
+			let n = a[0];
+			l.add(`${n.role}|${n.name}`), s.push({
+				severity: "warning",
+				kind: "role-changed",
+				screenId: t.id,
+				message: `Annotation ${e.id}: element with name="${r.name}" exists but has role="${n.role}", not "${r.role}".`,
+				match: r,
+				suggestion: { role: n.role }
+			});
+			continue;
+		}
+		let o = n.filter((e) => e.role === r.role);
+		if (o.length > 0) {
+			let n = qt(r.name, o.map((e) => e.name));
+			if (n) {
+				l.add(`${r.role}|${n}`), s.push({
+					severity: "warning",
+					kind: "renamed",
+					screenId: t.id,
+					message: `Annotation ${e.id}: no element with role="${r.role}" name="${r.name}". Closest match: name="${n}".`,
+					match: r,
+					suggestion: { name: n }
+				});
+				continue;
+			}
+		}
+		s.push({
+			severity: "error",
+			kind: "removed",
+			screenId: t.id,
+			message: `Annotation ${e.id}: no element with role="${r.role}" name="${r.name}".`,
+			match: r
+		});
+	}
+	if (a !== void 0) {
+		let e = new Set(a.map((e) => e.id)), n = new Set(t.callouts.map((e) => e.for));
+		for (let e of a) n.has(e.id) || s.push({
+			severity: "warning",
+			kind: "description-missing",
+			screenId: t.id,
+			message: `annotations yaml has \`overlays[].id="${e.id}"\` but no <AnnotCallout for="${e.id}"> in MDX.`,
+			match: e.match
+		});
+		for (let n of t.callouts) e.has(n.for) || s.push({
+			severity: "error",
+			kind: "description-orphan",
+			screenId: t.id,
+			message: `<AnnotCallout for="${n.for}"> has no matching entry in annotations yaml \`overlays[]\`.`
+		});
+	}
+	return r !== void 0 && i !== void 0 && Yt(r) !== Yt(i) && s.push({
 		severity: "info",
 		kind: "attribute-drift",
 		screenId: t.id,
 		message: "`annot:attributes` block no longer matches live element attributes. Run `annot docs sync` to update."
-	}), a;
+	}), s;
 }
-function Ne(e) {
-	return H({
+function Ht(e) {
+	return K({
 		screen: e.screen,
-		liveSnapshot: z(e.liveSnapshotYaml),
+		liveSnapshot: G(e.liveSnapshotYaml),
 		storedAttributesYaml: e.storedAttributesYaml,
-		freshAttributesYaml: e.freshAttributesYaml
+		freshAttributesYaml: e.freshAttributesYaml,
+		yamlOverlays: e.yamlOverlays,
+		yamlAnnotations: e.yamlAnnotations
 	});
 }
-function U(e) {
+function Ut(e) {
+	let t = [];
+	return ae(e, (e, n) => {
+		!e.role || !e.name || t.push({
+			role: e.role,
+			name: e.name,
+			ref: e.ref,
+			depth: n.length,
+			ancestors: n.filter((e) => typeof e.name == "string").map((e) => ({
+				role: e.role,
+				name: e.name
+			}))
+		});
+	}), t;
+}
+function Wt(e) {
+	return K({
+		screen: e.screen,
+		liveSnapshot: Ut(e.liveElementTree),
+		storedAttributesYaml: e.storedAttributesYaml,
+		freshAttributesYaml: e.freshAttributesYaml,
+		yamlOverlays: e.yamlOverlays,
+		yamlAnnotations: e.yamlAnnotations
+	});
+}
+function q(e) {
 	let t = 0, n = 0, r = 0;
 	for (let i of e) i.severity === "error" ? t++ : i.severity === "warning" ? n++ : r++;
 	return {
@@ -637,7 +1466,7 @@ function U(e) {
 		infos: r
 	};
 }
-var Pe = new Set([
+var Gt = /* @__PURE__ */ new Set([
 	"button",
 	"checkbox",
 	"combobox",
@@ -655,19 +1484,19 @@ var Pe = new Set([
 	"textbox",
 	"treeitem"
 ]);
-function Fe(e) {
-	return Pe.has(e);
+function Kt(e) {
+	return Gt.has(e);
 }
-function Ie(e, t) {
+function qt(e, t) {
 	if (t.length === 0) return null;
-	let n = t[0], r = W(e, n);
+	let n = t[0], r = Jt(e, n);
 	for (let i of t.slice(1)) {
-		let t = W(e, i);
+		let t = Jt(e, i);
 		t > r && (n = i, r = t);
 	}
 	return r > .3 ? n : null;
 }
-function W(e, t) {
+function Jt(e, t) {
 	if (!e || !t) return 0;
 	let n = (e) => {
 		let t = /* @__PURE__ */ new Set();
@@ -679,76 +1508,395 @@ function W(e, t) {
 	for (let e of r) i.has(e) && a++;
 	return a / Math.max(r.size, i.size);
 }
-function G(e) {
+function Yt(e) {
 	return e.split(/\r?\n/).map((e) => e.trimEnd()).filter((e) => e.length > 0).join("\n");
 }
-function K(e) {
-	return e.overlays.length > 0;
+function Xt(e) {
+	return e.overlays.length > 0 || e.annotations !== void 0 || e.callouts.length > 0;
 }
-function q(e) {
-	return e.filter(K);
+function J(e) {
+	return e.filter(Xt);
+}
+function Zt(e) {
+	switch (e.kind) {
+		case "rect": return e.match ? [e.match] : e.coversElements ? [...e.coversElements] : [];
+		case "circle": return e.match ? [e.match] : [];
+		case "arrow": {
+			let t = [];
+			return "match" in e.from && t.push(e.from.match), "match" in e.to && t.push(e.to.match), t;
+		}
+		case "text": return e.anchor ? [e.anchor.match] : [];
+		case "callout": return "match" in e.target ? [e.target.match] : [];
+		case "freehand": return [];
+		case "redact": return e.match ? [e.match] : [];
+		case "focusMask": return "match" in e.cutout ? [e.cutout.match] : [];
+	}
+}
+//#endregion
+//#region src/migrate-overlays-to-annotations.ts
+async function Qt(e, t = {}) {
+	let n = await y(e);
+	if (!n) return {
+		mdxPath: e,
+		screens: [],
+		mdxRewritten: !1
+	};
+	let i = [], a = [];
+	for (let s of n.screens) {
+		if (s.annotations !== void 0) {
+			a.push({
+				id: s.id,
+				overlayCount: 0,
+				yamlWritten: !1,
+				skipReason: "already-migrated"
+			});
+			continue;
+		}
+		if (s.overlays.length === 0) {
+			a.push({
+				id: s.id,
+				overlayCount: 0,
+				yamlWritten: !1,
+				skipReason: "no-overlays"
+			});
+			continue;
+		}
+		if (!s.src) {
+			a.push({
+				id: s.id,
+				overlayCount: s.overlays.length,
+				yamlWritten: !1,
+				skipReason: "no-src"
+			});
+			continue;
+		}
+		let c = tn({
+			mdxPath: e,
+			screenId: s.id,
+			src: s.src,
+			override: t.yamlPathFor
+		}), l = nn(m(e), c), u = an(n.source, s), d = rn(n.source, s, l);
+		if (!d || u.length !== s.overlays.length) throw Error(`migrateOverlaysToAnnotationsFile: ${e} screen "${s.id}" position data incomplete — cannot rewrite safely.`);
+		i.push(d, ...u.map((e) => e.edit));
+		let f = $t(s.overlays);
+		a.push({
+			id: s.id,
+			yamlPath: c,
+			yamlWritten: !1,
+			overlayCount: s.overlays.length
+		}), t.dryRun || (await r(m(c), { recursive: !0 }), await o(c, pt(f), "utf8"), a[a.length - 1].yamlWritten = !0);
+	}
+	let s = !1;
+	if (i.length > 0 && !t.dryRun) {
+		let t = en(n.source, i);
+		t !== n.source && (await o(e, t, "utf8"), s = !0);
+	}
+	return {
+		mdxPath: e,
+		screens: a,
+		mdxRewritten: s
+	};
+}
+function $t(e) {
+	return {
+		version: 1,
+		overlays: e.map((e, t) => {
+			let n = {
+				id: `o${t + 1}`,
+				kind: "numberedBadge",
+				match: e.match,
+				number: e.number ?? t + 1
+			};
+			return e.intent && (n.intent = e.intent), n;
+		}),
+		meta: { generator: "annot-docs migrate-overlays-to-annotations@1" }
+	};
+}
+function en(e, t) {
+	let n = [...t].sort((e, t) => t.start - e.start), r = e;
+	for (let e of n) r = r.slice(0, e.start) + e.replacement + r.slice(e.end);
+	return r;
+}
+function tn(e) {
+	if (e.override) return e.override({
+		mdxPath: e.mdxPath,
+		screenId: e.screenId,
+		src: e.src
+	});
+	let t = h(e.src) ? e.src : _(m(e.mdxPath), e.src), n = ne(t).replace(/\.(png|jpe?g|webp|gif|svg)$/i, "");
+	return _(m(t), `${n}.annotations.yaml`);
+}
+function nn(e, t) {
+	let n = g(e, t).split(/[\\/]/).join("/");
+	return n.startsWith(".") || n.startsWith("/") ? n : `./${n}`;
+}
+function rn(e, t, n) {
+	let r = new RegExp(String.raw`<Screen\b[^>]*\bid=(?:"${Y(t.id)}"|'${Y(t.id)}'|\{["']${Y(t.id)}["']\})[^>]*?(/?)>`, "m").exec(e);
+	if (!r || r.index === void 0) return null;
+	let i = r.index, a = i + r[0].length, o = r[1] === "/" ? a - 2 : a - 1, s = e.slice(i, o);
+	return {
+		start: o,
+		end: o,
+		replacement: `${/\s$/.test(s) ? "" : " "}annotations="${n}"`
+	};
+}
+function an(e, t) {
+	let n = new RegExp(String.raw`<Screen\b[^>]*\bid=(?:"${Y(t.id)}"|'${Y(t.id)}'|\{["']${Y(t.id)}["']\})[^>]*?>`, "m").exec(e);
+	if (!n || n.index === void 0) return [];
+	let r = n.index + n[0].length, i = e.indexOf("</Screen>", r);
+	if (i === -1) return [];
+	let a = i, o = [], s = r;
+	for (let n = 0; n < t.overlays.length; n++) {
+		let r = t.overlays[n], i = e.indexOf("<Overlay", s);
+		if (i === -1 || i >= a) return o;
+		let c = e.indexOf("</Overlay>", i);
+		if (c === -1 || c >= a) return o;
+		let l = c + 10, u = e.indexOf(">", i);
+		if (u === -1 || u >= c) return o;
+		let d = e.slice(u + 1, c), f = `<AnnotCallout for="${`o${n + 1}`}">${d}</AnnotCallout>`;
+		o.push({
+			overlay: r,
+			edit: {
+				start: i,
+				end: l,
+				replacement: f
+			}
+		}), s = l;
+	}
+	return o;
+}
+function Y(e) {
+	return e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/migrate-to-element-tree.ts
+var on = [
+	"type",
+	"required",
+	"placeholder",
+	"name",
+	"id",
+	"href",
+	"aria-checked",
+	"aria-expanded",
+	"aria-selected",
+	"aria-disabled",
+	"aria-invalid"
+];
+async function sn(e, t = {}) {
+	let n = await y(e);
+	if (!n) return {
+		mdxPath: e,
+		screens: [],
+		mdxRewritten: !1
+	};
+	let r = n.commentBlocks.snapshot?.trim() ?? "", a = n.commentBlocks.attributes?.trim() ?? "", s = [];
+	for (let c of n.screens) {
+		if (!r) {
+			s.push({
+				id: c.id,
+				xmpWritten: !1,
+				skipReason: "no-snapshot"
+			});
+			continue;
+		}
+		if (!c.src) {
+			s.push({
+				id: c.id,
+				xmpWritten: !1,
+				skipReason: "no-src"
+			});
+			continue;
+		}
+		let n = un(e, c.src);
+		if (!n) {
+			s.push({
+				id: c.id,
+				xmpWritten: !1,
+				skipReason: "no-src"
+			});
+			continue;
+		}
+		let l = cn({
+			snapshotYaml: r,
+			attributesYaml: a,
+			whitelist: t.attributeWhitelist ?? on
+		});
+		if (t.dryRun) {
+			s.push({
+				id: c.id,
+				pngPath: n,
+				xmpWritten: !0
+			});
+			continue;
+		}
+		await o(n, oe(await i(n), l)), s.push({
+			id: c.id,
+			pngPath: n,
+			xmpWritten: !0
+		});
+	}
+	let c = !!(n.commentBlocks.snapshot || n.commentBlocks.attributes), l = !1;
+	if (c && !t.dryRun) {
+		let t = dn(n.source);
+		t !== n.source && (await o(e, t, "utf8"), l = !0);
+	}
+	return {
+		mdxPath: e,
+		screens: s,
+		mdxRewritten: l
+	};
+}
+function cn(e) {
+	let n = t({
+		yaml: e.snapshotYaml,
+		viewport: {
+			width: 0,
+			height: 0,
+			scale: 1
+		},
+		agent: "annot-docs-migrate-to-element-tree@1",
+		capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+	}), r = ln(e.attributesYaml, e.whitelist);
+	for (let e of r) {
+		let t = ie(n, {
+			role: e.role,
+			name: e.name
+		});
+		if (t.length !== 1) continue;
+		let r = t[0];
+		Object.keys(e.attributes).length !== 0 && (r.attributes = {
+			...r.attributes ?? {},
+			...e.attributes
+		});
+	}
+	return n;
+}
+function ln(e, t) {
+	let n = [];
+	if (!e.trim()) return n;
+	let r = new Set(t), i = e.split(/\r?\n/), a = null, o = /^([a-z]+)\s+"([^"]*)"\s*:\s*$/;
+	for (let e of i) {
+		let t = e.trim();
+		if (!t) continue;
+		let i = t.match(o);
+		if (i) {
+			a = {
+				role: i[1] ?? "",
+				name: i[2] ?? "",
+				attributes: {}
+			}, n.push(a);
+			continue;
+		}
+		if (!a) continue;
+		let s = t.indexOf(":");
+		if (s <= 0) continue;
+		let c = t.slice(0, s).trim(), l = t.slice(s + 1).trim();
+		r.has(c) && ((l.startsWith("\"") && l.endsWith("\"") || l.startsWith("'") && l.endsWith("'")) && (l = l.slice(1, -1)), a.attributes[c] = l);
+	}
+	return n;
+}
+function un(e, t) {
+	return /^[a-z][a-z0-9+.-]*:/i.test(t) ? null : h(t) ? t : _(m(e), t);
+}
+function dn(e) {
+	let t = e;
+	return t = fn(t, "annot:snapshot"), t = fn(t, "annot:attributes"), t;
+}
+function fn(e, t) {
+	let n = `{/* ${t}`, r = e.indexOf(n);
+	if (r === -1) return e;
+	let i = e.indexOf("*/}", r);
+	if (i === -1) return e;
+	let a = i + 3, o = e[a] === "\n" ? a + 1 : a;
+	return e.slice(0, r) + e.slice(o);
 }
 //#endregion
 //#region src/cli.ts
-async function Le(e, t = {}) {
+async function pn(e, t = {}) {
 	let n = t.stdout ?? ((e) => process.stdout.write(`${e}\n`)), r = t.stderr ?? ((e) => process.stderr.write(`${e}\n`)), i = t.cwd ?? process.cwd(), [, , a, ...o] = e;
-	if (a !== "init" && a !== "sync" && a !== "lint") return r(Re), +!!a;
+	if (a !== "init" && a !== "sync" && a !== "lint" && a !== "migrate-to-element-tree" && a !== "migrate-overlays-to-annotations") return r(mn), +!!a;
 	try {
 		switch (a) {
-			case "init": return await ze(o, {
+			case "init": return await hn(o, {
 				cwd: i,
 				stdout: n,
 				stderr: r
 			});
-			case "sync": return await He(o, {
+			case "sync": return await yn(o, {
 				...t,
 				cwd: i,
 				stdout: n,
 				stderr: r
 			});
-			case "lint": return await Ue(o, {
+			case "lint": return await bn(o, {
 				...t,
 				cwd: i,
 				stdout: n,
 				stderr: r
 			});
+			case "migrate-to-element-tree": return await Sn(o, {
+				cwd: i,
+				stdout: n,
+				stderr: r
+			});
+			case "migrate-overlays-to-annotations": return await Cn(o, {
+				cwd: i,
+				stdout: n,
+				stderr: r
+			});
 		}
 	} catch (e) {
 		return r(`annot docs ${a}: ${e.message}`), 1;
 	}
 }
-var Re = [
+var mn = [
 	"annot docs <command> [options]",
 	"",
 	"Commands:",
 	"  init                       Scaffold annot-docs.config.ts + sample files",
 	"  sync   --url <baseUrl>     Re-capture snapshot + attrs into every annot MDX",
 	"  lint   --url <baseUrl>     Report drift between annot MDXs and the live page",
+	"  migrate-to-element-tree    Convert legacy annot:snapshot / annot:attributes",
+	"                             MDX blocks into PNG XMP annot:elementTree chunks",
+	"                             (one-time, per Phase 1g of",
+	"                             docs/plans/living-spec-authoring-roadmap.md)",
+	"  migrate-overlays-to-annotations",
+	"                             Extract inline <Overlay> JSX into",
+	"                             .annotations.yaml files and rewrite the MDX to use",
+	"                             <Screen annotations> + <AnnotCallout for> (one-time,",
+	"                             per Phase 2d of",
+	"                             docs/plans/living-spec-authoring-roadmap.md)",
 	"",
 	"Options:",
 	"  --url <baseUrl>            Base URL Playwright navigates to (sync / lint)",
 	"  --root <dir>               Override MDX search root (default: docs/)",
+	"  --dry-run                  migrate-to-element-tree only — report what would",
+	"                             be changed without writing back",
+	"  --check-descriptions       lint only — also validate <AnnotCallout for> IDs",
+	"                             against the screen's annotations yaml overlays[]",
+	"                             (Phase 2c of living-spec-authoring-roadmap.md)",
 	"  --help                     Show this help"
 ].join("\n");
-async function ze(e, t) {
-	let { cwd: r, stdout: i } = t, o = [
+async function hn(e, t) {
+	let { cwd: n, stdout: i } = t, a = [
 		{
 			path: "annot-docs.config.ts",
-			content: Be
+			content: gn
 		},
 		{
 			path: "tests/docs/example.spec.ts",
-			content: J
+			content: _n
 		},
 		{
 			path: "docs/books/example/SC-001-login.mdx",
-			content: Ve
+			content: vn
 		}
 	], s = 0;
-	for (let e of o) {
-		let t = h(r, e.path);
+	for (let e of a) {
+		let t = _(n, e.path);
 		try {
-			await n(p(t), { recursive: !0 }), await a(t, e.content, { flag: "wx" }), i(`  created ${e.path}`), s++;
+			await r(m(t), { recursive: !0 }), await o(t, e.content, { flag: "wx" }), i(`  created ${e.path}`), s++;
 		} catch (t) {
 			if (t.code === "EEXIST") i(`  exists  ${e.path} (skipped)`);
 			else throw t;
@@ -756,30 +1904,30 @@ async function ze(e, t) {
 	}
 	return i(s === 0 ? "annot docs init: nothing to do (all targets exist)" : `annot docs init: wrote ${s} file(s)`), 0;
 }
-var Be = "// Living product docs config for annot.\n// See https://github.com/ingcreators/annot/blob/main/docs/plans/living-product-docs.md\nimport { defineConfig } from \"@ingcreators/annot-product-docs\";\n\nexport default defineConfig({\n  meta: {\n    projectName: \"Example\",\n  },\n  xlsx: {\n    defaultBook: \"Screen spec\",\n    books: {\n      \"Screen spec\": {\n        // Drop your customer-supplied template here (Phase 3) and\n        // the Excel adapter will fill it. Until then the OSS\n        // default layout applies.\n        // template: \"./templates/customer-screen-spec.xlsx\",\n      },\n    },\n  },\n});\n", J = "// Tour file — runs through every screen and refreshes the\n// matching MDX's annot:snapshot / annot:attributes blocks.\n//\n// Run with: pnpm playwright test tests/docs/\n\nimport { test } from \"@ingcreators/annot-product-docs\";\n\ntest.describe.configure({ mode: \"serial\" });\n\ntest(\"login flow\", async ({ page, productDocs }) => {\n  await page.goto(\"/login\");\n  await productDocs.sync({\n    id: \"login\",\n    mdxPath: \"docs/books/example/SC-001-login.mdx\",\n  });\n});\n", Ve = "---\nannot:\n  id: SC-001\n  title: Login screen\n  meta:\n    author: TODO\n  xlsx:\n    book: Screen spec\n    sheet: SC-001 Login\n    role: screen\n    order: 100\n---\n\nimport { Screen, Overlay } from \"@ingcreators/annot-product-docs-astro\";\n\n# Login screen\n\nEnter your credentials to access the system.\n\n<Screen id=\"login\" src=\"./shots/login.png\">\n\n<Overlay match={{ role: \"textbox\", name: \"Email\" }} intent=\"required\" number={1}>\n**Email** — Enter your registered email address.\n</Overlay>\n\n<Overlay match={{ role: \"button\", name: \"Sign in\" }} intent=\"action\" number={2}>\nClick to sign in.\n</Overlay>\n\n</Screen>\n";
-async function He(e, t) {
+var gn = "// Living product docs config for annot.\n// See https://github.com/ingcreators/annot/blob/main/docs/plans/living-product-docs.md\nimport { defineConfig } from \"@ingcreators/annot-product-docs\";\n\nexport default defineConfig({\n  meta: {\n    projectName: \"Example\",\n  },\n  xlsx: {\n    defaultBook: \"Screen spec\",\n    books: {\n      \"Screen spec\": {\n        // Drop your customer-supplied template here (Phase 3) and\n        // the Excel adapter will fill it. Until then the OSS\n        // default layout applies.\n        // template: \"./templates/customer-screen-spec.xlsx\",\n      },\n    },\n  },\n});\n", _n = "// Tour file — runs through every screen and refreshes the\n// matching MDX's annot:snapshot / annot:attributes blocks.\n//\n// Run with: pnpm playwright test tests/docs/\n\nimport { test } from \"@ingcreators/annot-product-docs\";\n\ntest.describe.configure({ mode: \"serial\" });\n\ntest(\"login flow\", async ({ page, productDocs }) => {\n  await page.goto(\"/login\");\n  await productDocs.sync({\n    id: \"login\",\n    mdxPath: \"docs/books/example/SC-001-login.mdx\",\n  });\n});\n", vn = "---\nannot:\n  id: SC-001\n  title: Login screen\n  meta:\n    author: TODO\n  xlsx:\n    book: Screen spec\n    sheet: SC-001 Login\n    role: screen\n    order: 100\n---\n\nimport { Screen, Overlay } from \"@ingcreators/annot-product-docs-astro\";\n\n# Login screen\n\nEnter your credentials to access the system.\n\n<Screen id=\"login\" src=\"./shots/login.png\">\n\n<Overlay match={{ role: \"textbox\", name: \"Email\" }} intent=\"required\" number={1}>\n**Email** — Enter your registered email address.\n</Overlay>\n\n<Overlay match={{ role: \"button\", name: \"Sign in\" }} intent=\"action\" number={2}>\nClick to sign in.\n</Overlay>\n\n</Screen>\n";
+async function yn(e, t) {
 	let { cwd: n, stdout: r, stderr: i } = t, a = Z(e);
 	if (!a.url) return i("annot docs sync: --url <baseUrl> is required."), 1;
-	let o = await $(await Q(h(n, a.root ?? "docs")));
+	let o = await $(await Q(_(n, a.root ?? "docs")));
 	if (o.length === 0) return r(`annot docs sync: no MDX files with \`annot:\` frontmatter under ${a.root ?? "docs"}.`), 0;
 	r(`annot docs sync: ${o.length} MDX file(s) → ${a.url}`);
-	let { newPage: s, close: c } = await Y(a.url, t);
+	let { newPage: s, close: c } = await X(a.url, t);
 	try {
 		for (let e of o) {
-			let t = await x(e);
+			let t = await y(e);
 			if (!t) continue;
-			let i = q(t.screens);
+			let i = J(t.screens);
 			if (i.length === 0) {
-				r(`  skip   ${m(n, e)} (no <Screen> blocks)`);
+				r(`  skip   ${g(n, e)} (no <Screen> blocks)`);
 				continue;
 			}
 			for (let t of i) {
 				let { page: i, dispose: a } = await s(t.src ?? "/");
 				try {
-					await A(i, {
+					await D(i, {
 						id: t.id,
 						mdxPath: e
-					}), r(`  synced ${m(n, e)} (screen=${t.id})`);
+					}), r(`  synced ${g(n, e)} (screen=${t.id})`);
 				} finally {
 					await a();
 				}
@@ -790,10 +1938,10 @@ async function He(e, t) {
 	}
 	return 0;
 }
-async function Ue(e, t) {
+async function bn(e, t) {
 	let { cwd: n, stdout: r, stderr: i } = t, a = Z(e);
 	if (!a.url) return i("annot docs lint: --url <baseUrl> is required."), 1;
-	let o = await $(await Q(h(n, a.root ?? "docs")));
+	let o = await $(await Q(_(n, a.root ?? "docs")));
 	if (o.length === 0) return a.json ? r(JSON.stringify({
 		findings: [],
 		summary: {
@@ -803,23 +1951,30 @@ async function Ue(e, t) {
 		}
 	})) : r(`annot docs lint: no MDX files with \`annot:\` frontmatter under ${a.root ?? "docs"}.`), 0;
 	a.json || r(`annot docs lint: ${o.length} MDX file(s) → ${a.url}`);
-	let s = [], c = /* @__PURE__ */ new Set(), { newPage: l, close: u } = await Y(a.url, t);
+	let s = [], c = /* @__PURE__ */ new Set(), { newPage: l, close: u } = await X(a.url, t);
 	try {
 		for (let e of o) {
-			let t = await x(e);
-			if (t) for (let r of q(t.screens)) {
-				let { page: t, dispose: i } = await l(r.src ?? "/");
+			let t = await y(e);
+			if (t) for (let r of J(t.screens)) {
+				let { page: t, dispose: o } = await l(r.src ?? "/");
 				try {
-					let i = H({
+					let o = G(await t.locator("body").ariaSnapshot({ mode: "ai" })), l = a.checkDescriptions ? await xn(r, e, i) : void 0;
+					r.overlays.length > 0 && r.annotations === void 0 && Mt({
+						mdxPath: e,
+						screenId: r.id,
+						overlayCount: r.overlays.length
+					}, i);
+					let u = K({
 						screen: r,
-						liveSnapshot: z(await t.locator("body").ariaSnapshot({ mode: "ai" }))
+						liveSnapshot: o,
+						yamlOverlays: l
 					});
-					for (let t of i) s.push({
-						file: m(n, e),
+					for (let t of u) s.push({
+						file: g(n, e),
 						finding: t
 					}), c.add(e);
 				} finally {
-					await i();
+					await o();
 				}
 			}
 		}
@@ -827,7 +1982,7 @@ async function Ue(e, t) {
 		await u();
 	}
 	if (a.json) {
-		let e = U(s.map((e) => e.finding));
+		let e = q(s.map((e) => e.finding));
 		r(JSON.stringify({
 			findings: s.map(({ file: e, finding: t }) => ({
 				file: e,
@@ -841,20 +1996,20 @@ async function Ue(e, t) {
 			summary: e
 		}));
 	} else {
-		for (let { file: e, finding: t } of s) r(`${We(t.severity)} ${e} [${t.screenId}] ${t.kind}: ${t.message}`);
-		let e = U(s.map((e) => e.finding));
+		for (let { file: e, finding: t } of s) r(`${Tn(t.severity)} ${e} [${t.screenId}] ${t.kind}: ${t.message}`);
+		let e = q(s.map((e) => e.finding));
 		r(`annot docs lint: ${e.errors} error(s), ${e.warnings} warning(s), ${e.infos} info(s).`);
 	}
 	let d = 0;
 	if (a.fix && c.size > 0) {
-		let { newPage: e, close: n } = await Y(a.url, t);
+		let { newPage: e, close: n } = await X(a.url, t);
 		try {
 			for (let t of c) {
-				let n = await x(t);
-				if (n) for (let r of q(n.screens)) {
+				let n = await y(t);
+				if (n) for (let r of J(n.screens)) {
 					let { page: n, dispose: i } = await e(r.src ?? "/");
 					try {
-						await A(n, {
+						await D(n, {
 							id: r.id,
 							mdxPath: t
 						}), d++;
@@ -868,13 +2023,23 @@ async function Ue(e, t) {
 		}
 		a.json || r(`annot docs lint --fix: refreshed snapshot/attributes for ${d} screen(s).`);
 	}
-	let f = U(s.map((e) => e.finding));
+	let f = q(s.map((e) => e.finding));
 	return a.ci ? +(f.errors + f.warnings > 0) : +(f.errors > 0);
 }
-async function Y(e, t) {
+async function xn(e, t, n) {
+	if (!e.annotations) return;
+	let r = h(e.annotations) ? e.annotations : _(m(t), e.annotations);
+	try {
+		return ft(await i(r, "utf8")).overlays;
+	} catch (e) {
+		n(`annot docs lint --check-descriptions: failed to load ${r} (${e.message}). Skipping description cross-refs for this screen.`);
+		return;
+	}
+}
+async function X(e, t) {
 	if (t.newPage) return {
 		async newPage(n) {
-			let { page: r, close: i } = await t.newPage(X(e, n));
+			let { page: r, close: i } = await t.newPage(wn(e, n));
 			return {
 				page: r,
 				dispose: i
@@ -886,7 +2051,7 @@ async function Y(e, t) {
 	return {
 		async newPage(t) {
 			let n = await r.newContext(), i = await n.newPage();
-			return await i.goto(X(e, t)), {
+			return await i.goto(wn(e, t)), {
 				page: i,
 				dispose: async () => {
 					await n.close();
@@ -898,14 +2063,42 @@ async function Y(e, t) {
 		}
 	};
 }
-function X(e, t) {
+async function Sn(e, t) {
+	let { cwd: n, stdout: r, stderr: i } = t, a = Z(e), o = await $(await Q(_(n, a.root ?? "docs")));
+	if (o.length === 0) return r(`annot docs migrate-to-element-tree: no MDX files with \`annot:\` frontmatter under ${a.root ?? "docs"}.`), 0;
+	r(`annot docs migrate-to-element-tree: ${o.length} MDX file(s)${a.dryRun ? " (dry run)" : ""}`);
+	let s = 0, c = 0, l = 0;
+	for (let e of o) try {
+		let t = await sn(e, { dryRun: a.dryRun });
+		for (let i of t.screens) i.xmpWritten ? (s++, r(`  xmp     ${g(n, e)} (screen=${i.id})`)) : i.skipReason && (l++, r(`  skip    ${g(n, e)} (screen=${i.id}, ${i.skipReason})`));
+		t.mdxRewritten && (c++, r(`  rewrote ${g(n, e)} (legacy blocks stripped)`));
+	} catch (t) {
+		return i(`annot docs migrate-to-element-tree: ${g(n, e)}: ${t.message}`), 1;
+	}
+	return r(`annot docs migrate-to-element-tree: ${s} XMP write(s), ${c} MDX rewrite(s), ${l} skip(s).`), 0;
+}
+async function Cn(e, t) {
+	let { cwd: n, stdout: r, stderr: i } = t, a = Z(e), o = await $(await Q(_(n, a.root ?? "docs")));
+	if (o.length === 0) return r(`annot docs migrate-overlays-to-annotations: no MDX files with \`annot:\` frontmatter under ${a.root ?? "docs"}.`), 0;
+	r(`annot docs migrate-overlays-to-annotations: ${o.length} MDX file(s)${a.dryRun ? " (dry run)" : ""}`);
+	let s = 0, c = 0, l = 0;
+	for (let e of o) try {
+		let t = await Qt(e, { dryRun: a.dryRun });
+		for (let i of t.screens) i.yamlPath && !i.skipReason ? (s++, r(`  yaml    ${g(n, e)} (screen=${i.id}, overlays=${i.overlayCount}) → ${g(n, i.yamlPath)}`)) : i.skipReason && (l++, r(`  skip    ${g(n, e)} (screen=${i.id}, ${i.skipReason})`));
+		t.mdxRewritten && (c++, r(`  rewrote ${g(n, e)} (Overlay → AnnotCallout)`));
+	} catch (t) {
+		return i(`annot docs migrate-overlays-to-annotations: ${g(n, e)}: ${t.message}`), 1;
+	}
+	return r(`annot docs migrate-overlays-to-annotations: ${s} yaml write(s), ${c} MDX rewrite(s), ${l} skip(s).`), 0;
+}
+function wn(e, t) {
 	return /^https?:\/\//.test(t) ? t : t.startsWith("/") ? e.replace(/\/$/, "") + t : e;
 }
 function Z(e) {
 	let t = {};
 	for (let n = 0; n < e.length; n++) {
 		let r = e[n];
-		r === "--url" || r === "-u" ? t.url = e[++n] : r === "--root" || r === "-r" ? t.root = e[++n] : r === "--json" ? t.json = !0 : r === "--ci" ? t.ci = !0 : r === "--fix" && (t.fix = !0);
+		r === "--url" || r === "-u" ? t.url = e[++n] : r === "--root" || r === "-r" ? t.root = e[++n] : r === "--json" ? t.json = !0 : r === "--ci" ? t.ci = !0 : r === "--fix" ? t.fix = !0 : r === "--dry-run" ? t.dryRun = !0 : r === "--check-descriptions" && (t.checkDescriptions = !0);
 	}
 	return t;
 }
@@ -914,13 +2107,13 @@ async function Q(e) {
 	for (; n.length > 0;) {
 		let e = n.pop(), r;
 		try {
-			r = await i(e, { withFileTypes: !0 });
+			r = await a(e, { withFileTypes: !0 });
 		} catch (e) {
 			if (e.code === "ENOENT") continue;
 			throw e;
 		}
 		for (let i of r) {
-			let r = te(e, i.name);
+			let r = re(e, i.name);
 			if (i.isDirectory()) {
 				if (i.name === "node_modules" || i.name.startsWith(".")) continue;
 				n.push(r);
@@ -932,11 +2125,11 @@ async function Q(e) {
 async function $(e) {
 	let t = [];
 	for (let n of e) try {
-		await x(n) && t.push(n);
+		await y(n) && t.push(n);
 	} catch {}
 	return t;
 }
-function We(e) {
+function Tn(e) {
 	switch (e) {
 		case "error": return "ERROR  ";
 		case "warning": return "WARN   ";
@@ -944,4 +2137,4 @@ function We(e) {
 	}
 }
 //#endregion
-export { k as DEFAULT_ATTR_WHITELIST, v as annotDocsConfigSchema, _ as annotFrontmatterSchema, N as buildBadgeAnnotations, Te as captureScreen, j as collectAttributesYaml, oe as defineConfig, H as detectDrift, Ne as detectDriftFromYaml, F as emptyAnnotationsSvg, $ as filterAnnotMdxFiles, K as isLintableScreen, se as isScreenRole, q as lintableScreens, Le as main, S as parseMdx, x as parseMdxFile, z as parseSnapshot, M as parseSnapshotBoxes, B as resolveMatch, P as resolveMdxAnnotations, Oe as resolveOverlays, U as summariseDrift, Ee as svgFromBadges, De as svgFromBboxAnnotations, A as syncProductDocs, we as test, D as updateCommentBlocks, Q as walkMdx };
+export { dt as ANNOTATIONS_YAML_VERSION, P as ANNOTATION_KINDS, F as AnnotationsYamlError, E as DEFAULT_ATTR_WHITELIST, Pt as _resetLegacyOverlayDedupForTests, pe as annotDocsConfigSchema, ue as annotFrontmatterSchema, $t as buildAnnotationsFile, ze as buildBadgeAnnotations, Be as buildBadgeAnnotationsFromYaml, We as buildRasterRedactRegionsFromYaml, Ue as buildShapeAnnotationsFromYaml, Le as captureScreen, O as collectAttributesYaml, Zt as collectMatchKeysFromAnnotation, me as defineConfig, K as detectDrift, Wt as detectDriftFromElementTree, Ht as detectDriftFromYaml, Re as elementTreeToBoxedEntries, Ut as elementTreeToSnapshotEntries, st as emptyAnnotationsSvg, $ as filterAnnotMdxFiles, Nt as formatLegacyOverlayWarning, Xt as isLintableScreen, he as isScreenRole, J as lintableScreens, pn as main, Qt as migrateOverlaysToAnnotationsFile, ft as parseAnnotationsYaml, xe as parseMdx, y as parseMdxFile, G as parseSnapshot, k as parseSnapshotBoxes, Ft as resolveMatch, Ve as resolveMdxAnnotations, It as resolveOverlays, pt as serializeAnnotationsYaml, q as summariseDrift, He as svgFromBadges, ot as svgFromBboxAnnotations, D as syncProductDocs, Ie as test, w as updateCommentBlocks, Q as walkMdx, Mt as warnLegacyOverlay };