@ingcreators/annot-product-docs 0.1.0 → 0.3.0

package/dist/index.js

@@ -0,0 +1,947 @@
+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";
+//#region src/config.ts
+var ne = f.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()
+	}).strict().optional()
+}).strict();
+function oe(e) {
+	let t = v.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) {
+	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 });
+}
+function S(e, t = {}) {
+	let n = u().use(l).use(s, ["yaml"]).use(c).parse(e), r = de(n, t.filePath);
+	if (!r) return null;
+	let i = [], a = [], o = [], f = [], p = {};
+	return d(n, (t) => {
+		switch (t.type) {
+			case "mdxJsxFlowElement":
+			case "mdxJsxTextElement":
+				pe(t, e, {
+					screens: i,
+					transitions: a,
+					history: o,
+					screenLists: f
+				});
+				return;
+			case "mdxFlowExpression":
+			case "mdxTextExpression":
+				ye(t, p);
+				return;
+		}
+	}), {
+		frontmatter: r,
+		screens: i,
+		transitions: a,
+		history: o,
+		screenLists: f,
+		commentBlocks: p,
+		source: e
+	};
+}
+function de(e, t) {
+	let n = e.children.find((e) => e.type === "yaml");
+	if (!n || !n.value) return null;
+	let r = o.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);
+	if (!a.success) {
+		let e = t ? ` in ${t}` : "";
+		throw Error(`Invalid \`annot:\` frontmatter${e}:\n${fe(a.error)}`);
+	}
+	return a.data;
+}
+function fe(e) {
+	return e.issues.map((e) => `  - ${e.path.length ? e.path.join(".") + ": " : ""}${e.message}`).join("\n");
+}
+function pe(e, t, n) {
+	let r = e;
+	switch (r.name) {
+		case "Screen":
+			n.screens.push(me(r, t));
+			return;
+		case "Transition":
+			n.transitions.push(ge(r, t));
+			return;
+		case "HistoryEntry":
+			n.history.push(_e(r, t));
+			return;
+		case "ScreenList":
+			n.screenLists.push(ve(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));
+			return;
+		}
+		if (!(a.name === "Screen" && a !== e)) for (let e of a.children ?? []) i(e);
+	};
+	for (let t of e.children ?? []) i(t);
+	let a = w(n.id);
+	if (!a) throw Error("<Screen> requires an `id` prop.");
+	return {
+		id: a,
+		src: w(n.src),
+		overlays: r
+	};
+}
+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 }`.");
+	return {
+		match: r,
+		intent: w(n.intent),
+		number: xe(n.number),
+		body: E(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 }`.");
+	return {
+		trigger: r,
+		on: w(n.on),
+		to: w(n.to),
+		body: E(e, t)
+	};
+}
+function _e(e, t) {
+	let n = C(e), r = w(n.version) ?? "", i = w(n.date) ?? "", a = w(n.author) ?? "";
+	if (!r || !i) throw Error("<HistoryEntry> requires `version` and `date` props.");
+	return {
+		version: r,
+		date: i,
+		author: a,
+		body: E(e, t)
+	};
+}
+function ve(e) {
+	let t = C(e);
+	return {
+		book: w(t.book),
+		sort: w(t.sort)
+	};
+}
+function ye(e, t) {
+	let n = e.value;
+	if (typeof n != "string") return;
+	let r = n.match(ue);
+	if (!r) return;
+	let i = (r[1] ?? "").trim(), a = (r[2] ?? "").trim();
+	switch (i) {
+		case y:
+			t.snapshot = a;
+			return;
+		case b:
+			t.attributes = a;
+			return;
+		case ce:
+		case le: return;
+	}
+}
+function C(e) {
+	let t = {};
+	for (let n of e.attributes ?? []) {
+		let e = n;
+		if (e.type !== "mdxJsxAttribute" || !e.name) continue;
+		if (e.value === null || e.value === void 0) {
+			t[e.name] = !0;
+			continue;
+		}
+		if (typeof e.value == "string") {
+			t[e.name] = e.value;
+			continue;
+		}
+		let r = e.value;
+		r.type === "mdxJsxAttributeValueExpression" && typeof r.value == "string" && (t[e.name] = be(r.value));
+	}
+	return t;
+}
+function be(e) {
+	let t = e.trim();
+	if (t) {
+		if (t === "true") return !0;
+		if (t === "false") return !1;
+		if (t === "null") return null;
+		if (/^-?\d+(\.\d+)?$/.test(t)) return Number.parseFloat(t);
+		if (t.startsWith("\"") && t.endsWith("\"")) try {
+			return JSON.parse(t);
+		} catch {
+			return t.slice(1, -1);
+		}
+		if (t.startsWith("'") && t.endsWith("'")) {
+			let e = t.slice(1, -1), n = e.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+			try {
+				return JSON.parse(`"${n}"`);
+			} catch {
+				return e;
+			}
+		}
+		if (t.startsWith("{") && t.endsWith("}") || t.startsWith("[") && t.endsWith("]")) {
+			let e = t.replace(/([{,]\s*)([A-Za-z_$][A-Za-z0-9_$]*)(\s*:)/g, "$1\"$2\"$3").replace(/'([^'\\]*)'/g, "\"$1\"").replace(/,(\s*[}\]])/g, "$1");
+			try {
+				return JSON.parse(e);
+			} catch {
+				return t;
+			}
+		}
+		return t;
+	}
+}
+function w(e) {
+	return typeof e == "string" ? e : void 0;
+}
+function xe(e) {
+	return typeof e == "number" ? e : void 0;
+}
+function T(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));
+}
+function E(e, t) {
+	let n = e.position;
+	if (!n) return "";
+	let r = t.slice(n.start.offset, n.end.offset);
+	if (/\/>\s*$/.test(r)) return "";
+	let i = r.indexOf(">"), a = r.lastIndexOf("</");
+	return i < 0 || a < 0 || a <= i ? "" : r.slice(i + 1, a).trim();
+}
+function D(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;
+}
+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);
+	return r.test(e) ? e.replace(r, i) : `${e.trimEnd()}\n\n${i}\n`;
+}
+function Se(e, t) {
+	let n = t.trim();
+	return n ? `{/* ${e}\n${n}\n*/}` : `{/* ${e} */}`;
+}
+function Ce(e) {
+	return e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/fixture.ts
+var k = [
+	"type",
+	"required",
+	"placeholder",
+	"maxlength",
+	"minlength",
+	"pattern",
+	"min",
+	"max",
+	"step",
+	"disabled",
+	"readonly",
+	"checked",
+	"aria-required",
+	"aria-disabled",
+	"aria-readonly"
+], we = t.extend({
+	productDocs: async ({ page: e }, t) => {
+		await t({ sync: (t) => A(e, t) });
+	},
+	screen: async ({ page: e }, t) => {
+		let n = (t) => A(e, t);
+		await t({
+			sync: n,
+			capture: n
+		});
+	}
+});
+async function A(e, t) {
+	let n = await x(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, {
+		snapshot: i.trim(),
+		attributes: o
+	});
+	await a(t.mdxPath, s, "utf8");
+}
+var Te = A;
+async function j(e, t, n) {
+	let r = [];
+	for (let i of t) {
+		let t = e.getByRole(i.match.role, {
+			name: i.match.name,
+			exact: !0
+		});
+		if (await t.count() !== 1) continue;
+		let a = await t.evaluate((e, t) => {
+			let n = {};
+			for (let r of t) {
+				let t = e.getAttribute(r);
+				t !== null && (n[r] = t);
+			}
+			return n;
+		}, n), o = Object.keys(a);
+		if (o.length !== 0) {
+			r.push(`${i.match.role} "${i.match.name}":`);
+			for (let e of o) r.push(`  ${e}: ${a[e]}`);
+		}
+	}
+	return r.join("\n");
+}
+//#endregion
+//#region src/mdx-annotations.ts
+function M(e) {
+	let t = [];
+	for (let n of e.split(/\r?\n/)) {
+		if (!n.trim()) continue;
+		let e = n.match(/^\s*-\s+([a-z]+)(?:\s+"([^"]*?)")?/);
+		if (!e) continue;
+		let r = e[1] ?? "", i = e[2] ?? "", a = n.match(/\[ref=(e\d+)\]/)?.[1], o = n.match(/\[box=(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)\]/);
+		!a || !o || t.push({
+			role: r,
+			name: i,
+			ref: a,
+			box: {
+				x: Number.parseFloat(o[1] ?? "0"),
+				y: Number.parseFloat(o[2] ?? "0"),
+				width: Number.parseFloat(o[3] ?? "0"),
+				height: Number.parseFloat(o[4] ?? "0")
+			}
+		});
+	}
+	return t;
+}
+function N(e, t, n) {
+	let r = [], i = 1;
+	for (let a of e) {
+		let e = t.find((e) => e.role === a.match.role && e.name === a.match.name);
+		if (!e) continue;
+		let o = a.number ?? i++;
+		r.push({
+			type: "numberedBadge",
+			bbox: e.box,
+			number: o,
+			placement: "auto",
+			imageWidth: n.width,
+			imageHeight: n.height,
+			intent: a.intent === "action" ? "warning" : a.intent === "required" ? "error" : "info"
+		});
+	}
+	return r;
+}
+async function P(e) {
+	let t = e.cwd ?? process.cwd(), n = await x(ee(e.mdxPath) ? e.mdxPath : h(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);
+}
+function Ee(e) {
+	return `<svg xmlns="http://www.w3.org/2000/svg">${g(e)}</svg>`;
+}
+function De(e) {
+	return e.length === 0 ? F() : `<svg xmlns="http://www.w3.org/2000/svg">${g(e)}</svg>`;
+}
+function F() {
+	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 }) => {
+	if (!e.mdx) return null;
+	let { id: n, path: r } = e.mdx;
+	return {
+		prepare: () => A(t, {
+			id: n,
+			mdxPath: r
+		}),
+		resolveAnnotations: (e) => P({
+			mdxPath: r,
+			screenId: n,
+			dims: e
+		})
+	};
+}, R = L;
+R[I] || (R[I] = !0, e.push(L));
+//#endregion
+//#region src/resolver.ts
+function z(e) {
+	let t = [], n = e.split(/\r?\n/), r = [];
+	for (let e of n) {
+		if (!e.trim()) continue;
+		let n = e.length - e.replace(/^\s+/, "").length, i = Math.floor(n / 2), a = e.match(/^\s*-\s+([a-z]+)(?:\s+"([^"]*?)")?/);
+		if (!a) continue;
+		let o = a[1] ?? "", s = a[2] ?? "";
+		for (; r.length > 0 && (r[r.length - 1]?.depth ?? -1) >= i;) r.pop();
+		let c = r.map((e) => ({
+			role: e.role,
+			name: e.name
+		})), l = e.match(/\[ref=(e\d+)\]/);
+		l && t.push({
+			role: o,
+			name: s,
+			ref: l[1] ?? "",
+			depth: i,
+			ancestors: c
+		}), /:\s*$/.test(e) && r.push({
+			depth: i,
+			role: o,
+			name: s
+		});
+	}
+	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);
+	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();
+	return o === 0 ? {
+		ok: !1,
+		kind: "live-mismatch",
+		reason: `Snapshot says element exists but live locator failed: role="${e.role}" name="${e.name}".`
+	} : o > 1 ? {
+		ok: !1,
+		kind: "ambiguous",
+		reason: `Live locator returns ${o} elements for role="${e.role}" name="${e.name}".`
+	} : {
+		ok: !0,
+		locator: a,
+		entry: i
+	};
+}
+async function Oe(e, t, n) {
+	let r = [];
+	for (let i of e) r.push({
+		overlay: i,
+		result: await B(i.match, t, n)
+	});
+	return r;
+}
+function ke(e, t) {
+	let n = e.getByRole(t.role, {
+		name: t.name,
+		exact: !0
+	});
+	return t.under && (n = e.getByRole(t.under.role, {
+		name: t.under.name,
+		exact: !0
+	}).getByRole(t.role, {
+		name: t.name,
+		exact: !0
+	})), n;
+}
+function Ae(e, t) {
+	return t ? e.filter((e) => e.ancestors.some((e) => e.role === t.role && e.name === t.name)) : e;
+}
+function je(e, t) {
+	let n = t.filter((t) => t.name === e.name);
+	if (n.length === 1 && n[0].role !== e.role) return {
+		ok: !1,
+		kind: "role-changed",
+		reason: `Element with name="${e.name}" exists but has role="${n[0].role}", not "${e.role}".`,
+		suggestion: n[0].role
+	};
+	let r = t.filter((t) => t.role === e.role);
+	if (r.length > 0) {
+		let t = Me(e.name, r.map((e) => e.name));
+		if (t) return {
+			ok: !1,
+			kind: "renamed",
+			reason: `No element with role="${e.role}" name="${e.name}". Closest match: name="${t}".`,
+			suggestion: t
+		};
+	}
+	return {
+		ok: !1,
+		kind: "not-found",
+		reason: `No element with role="${e.role}" name="${e.name}".`
+	};
+}
+function Me(e, t) {
+	if (t.length === 0) return null;
+	let n = t[0], r = V(e, n);
+	for (let i of t.slice(1)) {
+		let t = V(e, i);
+		t > r && (n = i, r = t);
+	}
+	return r > .3 ? n : null;
+}
+function V(e, t) {
+	if (!e || !t) return 0;
+	let n = (e) => {
+		let t = /* @__PURE__ */ new Set();
+		for (let n = 0; n < e.length - 2; n++) t.add(e.slice(n, n + 3));
+		return t;
+	}, r = n(e), i = n(t);
+	if (r.size === 0 || i.size === 0) return 0;
+	let a = 0;
+	for (let e of r) i.has(e) && a++;
+	return a / Math.max(r.size, i.size);
+}
+//#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) {
+		let r = n.filter((t) => t.role === e.match.role && t.name === e.match.name);
+		if (r.length > 1) {
+			a.push({
+				severity: "error",
+				kind: "duplicated",
+				screenId: t.id,
+				message: `Multiple elements match role="${e.match.role}" name="${e.match.name}". Use \`under\` to disambiguate.`,
+				match: e.match
+			});
+			continue;
+		}
+		if (r.length === 1) continue;
+		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({
+				severity: "warning",
+				kind: "role-changed",
+				screenId: t.id,
+				message: `Element with name="${e.match.name}" exists but has role="${n.role}", not "${e.match.role}".`,
+				match: e.match,
+				suggestion: { role: n.role }
+			});
+			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));
+			if (n) {
+				o.add(`${e.match.role}|${n}`), a.push({
+					severity: "warning",
+					kind: "renamed",
+					screenId: t.id,
+					message: `No element with role="${e.match.role}" name="${e.match.name}". Closest match: name="${n}".`,
+					match: e.match,
+					suggestion: { name: n }
+				});
+				continue;
+			}
+		}
+		a.push({
+			severity: "error",
+			kind: "removed",
+			screenId: t.id,
+			message: `No element with role="${e.match.role}" name="${e.match.name}".`,
+			match: e.match
+		});
+	}
+	let s = new Set(t.overlays.map((e) => `${e.match.role}|${e.match.name}`));
+	for (let e of n) {
+		if (!Fe(e.role)) continue;
+		let n = `${e.role}|${e.name}`;
+		s.has(n) || o.has(n) || a.push({
+			severity: "warning",
+			kind: "added",
+			screenId: t.id,
+			message: `New ${e.role} "${e.name}" on the page has no <Overlay>.`,
+			suggestion: {
+				role: e.role,
+				name: e.name
+			}
+		});
+	}
+	return r !== void 0 && i !== void 0 && G(r) !== G(i) && a.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;
+}
+function Ne(e) {
+	return H({
+		screen: e.screen,
+		liveSnapshot: z(e.liveSnapshotYaml),
+		storedAttributesYaml: e.storedAttributesYaml,
+		freshAttributesYaml: e.freshAttributesYaml
+	});
+}
+function U(e) {
+	let t = 0, n = 0, r = 0;
+	for (let i of e) i.severity === "error" ? t++ : i.severity === "warning" ? n++ : r++;
+	return {
+		errors: t,
+		warnings: n,
+		infos: r
+	};
+}
+var Pe = new Set([
+	"button",
+	"checkbox",
+	"combobox",
+	"link",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"option",
+	"radio",
+	"searchbox",
+	"slider",
+	"spinbutton",
+	"switch",
+	"tab",
+	"textbox",
+	"treeitem"
+]);
+function Fe(e) {
+	return Pe.has(e);
+}
+function Ie(e, t) {
+	if (t.length === 0) return null;
+	let n = t[0], r = W(e, n);
+	for (let i of t.slice(1)) {
+		let t = W(e, i);
+		t > r && (n = i, r = t);
+	}
+	return r > .3 ? n : null;
+}
+function W(e, t) {
+	if (!e || !t) return 0;
+	let n = (e) => {
+		let t = /* @__PURE__ */ new Set();
+		for (let n = 0; n < e.length - 2; n++) t.add(e.slice(n, n + 3));
+		return t;
+	}, r = n(e), i = n(t);
+	if (r.size === 0 || i.size === 0) return 0;
+	let a = 0;
+	for (let e of r) i.has(e) && a++;
+	return a / Math.max(r.size, i.size);
+}
+function G(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 q(e) {
+	return e.filter(K);
+}
+//#endregion
+//#region src/cli.ts
+async function Le(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;
+	try {
+		switch (a) {
+			case "init": return await ze(o, {
+				cwd: i,
+				stdout: n,
+				stderr: r
+			});
+			case "sync": return await He(o, {
+				...t,
+				cwd: i,
+				stdout: n,
+				stderr: r
+			});
+			case "lint": return await Ue(o, {
+				...t,
+				cwd: i,
+				stdout: n,
+				stderr: r
+			});
+		}
+	} catch (e) {
+		return r(`annot docs ${a}: ${e.message}`), 1;
+	}
+}
+var Re = [
+	"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",
+	"",
+	"Options:",
+	"  --url <baseUrl>            Base URL Playwright navigates to (sync / lint)",
+	"  --root <dir>               Override MDX search root (default: docs/)",
+	"  --help                     Show this help"
+].join("\n");
+async function ze(e, t) {
+	let { cwd: r, stdout: i } = t, o = [
+		{
+			path: "annot-docs.config.ts",
+			content: Be
+		},
+		{
+			path: "tests/docs/example.spec.ts",
+			content: J
+		},
+		{
+			path: "docs/books/example/SC-001-login.mdx",
+			content: Ve
+		}
+	], s = 0;
+	for (let e of o) {
+		let t = h(r, e.path);
+		try {
+			await n(p(t), { recursive: !0 }), await a(t, e.content, { flag: "wx" }), i(`  created ${e.path}`), s++;
+		} catch (t) {
+			if (t.code === "EEXIST") i(`  exists  ${e.path} (skipped)`);
+			else throw 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) {
+	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")));
+	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);
+	try {
+		for (let e of o) {
+			let t = await x(e);
+			if (!t) continue;
+			let i = q(t.screens);
+			if (i.length === 0) {
+				r(`  skip   ${m(n, e)} (no <Screen> blocks)`);
+				continue;
+			}
+			for (let t of i) {
+				let { page: i, dispose: a } = await s(t.src ?? "/");
+				try {
+					await A(i, {
+						id: t.id,
+						mdxPath: e
+					}), r(`  synced ${m(n, e)} (screen=${t.id})`);
+				} finally {
+					await a();
+				}
+			}
+		}
+	} finally {
+		await c();
+	}
+	return 0;
+}
+async function Ue(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")));
+	if (o.length === 0) return a.json ? r(JSON.stringify({
+		findings: [],
+		summary: {
+			errors: 0,
+			warnings: 0,
+			infos: 0
+		}
+	})) : 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);
+	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 ?? "/");
+				try {
+					let i = H({
+						screen: r,
+						liveSnapshot: z(await t.locator("body").ariaSnapshot({ mode: "ai" }))
+					});
+					for (let t of i) s.push({
+						file: m(n, e),
+						finding: t
+					}), c.add(e);
+				} finally {
+					await i();
+				}
+			}
+		}
+	} finally {
+		await u();
+	}
+	if (a.json) {
+		let e = U(s.map((e) => e.finding));
+		r(JSON.stringify({
+			findings: s.map(({ file: e, finding: t }) => ({
+				file: e,
+				severity: t.severity,
+				kind: t.kind,
+				screenId: t.screenId,
+				message: t.message,
+				match: t.match,
+				suggestion: t.suggestion
+			})),
+			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));
+		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);
+		try {
+			for (let t of c) {
+				let n = await x(t);
+				if (n) for (let r of q(n.screens)) {
+					let { page: n, dispose: i } = await e(r.src ?? "/");
+					try {
+						await A(n, {
+							id: r.id,
+							mdxPath: t
+						}), d++;
+					} finally {
+						await i();
+					}
+				}
+			}
+		} finally {
+			await n();
+		}
+		a.json || r(`annot docs lint --fix: refreshed snapshot/attributes for ${d} screen(s).`);
+	}
+	let f = U(s.map((e) => e.finding));
+	return a.ci ? +(f.errors + f.warnings > 0) : +(f.errors > 0);
+}
+async function Y(e, t) {
+	if (t.newPage) return {
+		async newPage(n) {
+			let { page: r, close: i } = await t.newPage(X(e, n));
+			return {
+				page: r,
+				dispose: i
+			};
+		},
+		async close() {}
+	};
+	let { chromium: n } = await import("playwright-core"), r = await n.launch({ headless: !0 });
+	return {
+		async newPage(t) {
+			let n = await r.newContext(), i = await n.newPage();
+			return await i.goto(X(e, t)), {
+				page: i,
+				dispose: async () => {
+					await n.close();
+				}
+			};
+		},
+		async close() {
+			await r.close();
+		}
+	};
+}
+function X(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);
+	}
+	return t;
+}
+async function Q(e) {
+	let t = [], n = [e];
+	for (; n.length > 0;) {
+		let e = n.pop(), r;
+		try {
+			r = await i(e, { withFileTypes: !0 });
+		} catch (e) {
+			if (e.code === "ENOENT") continue;
+			throw e;
+		}
+		for (let i of r) {
+			let r = te(e, i.name);
+			if (i.isDirectory()) {
+				if (i.name === "node_modules" || i.name.startsWith(".")) continue;
+				n.push(r);
+			} else i.isFile() && i.name.endsWith(".mdx") && t.push(r);
+		}
+	}
+	return t.sort();
+}
+async function $(e) {
+	let t = [];
+	for (let n of e) try {
+		await x(n) && t.push(n);
+	} catch {}
+	return t;
+}
+function We(e) {
+	switch (e) {
+		case "error": return "ERROR  ";
+		case "warning": return "WARN   ";
+		case "info": return "INFO   ";
+	}
+}
+//#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 };