@ingcreators/annot-product-docs 0.1.0 → 0.2.0

package/dist/index.js

@@ -0,0 +1,860 @@
+import { mkdir as e, readFile as t, readdir as n, writeFile as r } from "node:fs/promises";
+import { dirname as i, join as a, relative as o, resolve as s } from "node:path";
+import { test as c } from "@ingcreators/annot-playwright";
+import l from "js-yaml";
+import u from "remark-frontmatter";
+import d from "remark-mdx";
+import f from "remark-parse";
+import { unified as p } from "unified";
+import { visit as m } from "unist-util-visit";
+import { z as h } from "zod";
+//#region src/resolver.ts
+function g(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 _(e, t, n) {
+	let r = te(t.filter((t) => t.role === e.role && t.name === e.name), e.under);
+	if (r.length === 0) return ne(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 = v(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 ee(e, t, n) {
+	let r = [];
+	for (let i of e) r.push({
+		overlay: i,
+		result: await _(i.match, t, n)
+	});
+	return r;
+}
+function v(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 te(e, t) {
+	return t ? e.filter((e) => e.ancestors.some((e) => e.role === t.role && e.name === t.name)) : e;
+}
+function ne(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 = re(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 re(e, t) {
+	if (t.length === 0) return null;
+	let n = t[0], r = y(e, n);
+	for (let i of t.slice(1)) {
+		let t = y(e, i);
+		t > r && (n = i, r = t);
+	}
+	return r > .3 ? n : null;
+}
+function y(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 b(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 = se(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 (!oe(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 && C(r) !== C(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 ie(e) {
+	return b({
+		screen: e.screen,
+		liveSnapshot: g(e.liveSnapshotYaml),
+		storedAttributesYaml: e.storedAttributesYaml,
+		freshAttributesYaml: e.freshAttributesYaml
+	});
+}
+function x(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 ae = new Set([
+	"button",
+	"checkbox",
+	"combobox",
+	"link",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"option",
+	"radio",
+	"searchbox",
+	"slider",
+	"spinbutton",
+	"switch",
+	"tab",
+	"textbox",
+	"treeitem"
+]);
+function oe(e) {
+	return ae.has(e);
+}
+function se(e, t) {
+	if (t.length === 0) return null;
+	let n = t[0], r = S(e, n);
+	for (let i of t.slice(1)) {
+		let t = S(e, i);
+		t > r && (n = i, r = t);
+	}
+	return r > .3 ? n : null;
+}
+function S(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 C(e) {
+	return e.split(/\r?\n/).map((e) => e.trimEnd()).filter((e) => e.length > 0).join("\n");
+}
+function w(e) {
+	return e.overlays.length > 0;
+}
+function T(e) {
+	return e.filter(w);
+}
+//#endregion
+//#region src/config.ts
+var E = h.enum([
+	"cover",
+	"history",
+	"list",
+	"screen",
+	"reference"
+]), ce = h.object({
+	book: h.string().optional(),
+	sheet: h.string().optional(),
+	sheets: h.record(h.string(), h.string()).optional(),
+	role: E.optional(),
+	order: h.number().optional()
+}).strict().refine((e) => !(e.sheet && e.sheets), "Specify either `xlsx.sheet` (single sheet) or `xlsx.sheets` (multi-sheet), not both."), le = h.record(h.string(), h.unknown()), D = h.object({
+	id: h.string().min(1, "`annot.id` is required."),
+	title: h.string().optional(),
+	purpose: h.string().optional(),
+	meta: le.optional(),
+	xlsx: ce.optional()
+}).strict(), ue = h.object({
+	template: h.string().optional(),
+	templateSheets: h.object({
+		cover: h.string().optional(),
+		history: h.string().optional(),
+		list: h.string().optional(),
+		screen: h.string().optional(),
+		reference: h.string().optional()
+	}).strict().optional()
+}).strict(), O = h.object({
+	meta: h.record(h.string(), h.unknown()).optional(),
+	xlsx: h.object({
+		defaultBook: h.string().optional(),
+		books: h.record(h.string(), ue).optional()
+	}).strict().optional()
+}).strict();
+function de(e) {
+	let t = O.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 fe(e) {
+	return (e.xlsx?.role ?? "screen") === "screen";
+}
+//#endregion
+//#region src/mdx.ts
+var k = "annot:snapshot", pe = "/annot:snapshot", A = "annot:attributes", me = "/annot:attributes", he = /^\s*\/\*\s*([^\s*]+)\s*([\s\S]*?)\*\/\s*$/;
+async function j(e) {
+	return M(await t(e, "utf8"), { filePath: e });
+}
+function M(e, t = {}) {
+	let n = p().use(f).use(u, ["yaml"]).use(d).parse(e), r = N(n, t.filePath);
+	if (!r) return null;
+	let i = [], a = [], o = [], s = [], c = {};
+	return m(n, (t) => {
+		switch (t.type) {
+			case "mdxJsxFlowElement":
+			case "mdxJsxTextElement":
+				F(t, e, {
+					screens: i,
+					transitions: a,
+					history: o,
+					screenLists: s
+				});
+				return;
+			case "mdxFlowExpression":
+			case "mdxTextExpression":
+				_e(t, c);
+				return;
+		}
+	}), {
+		frontmatter: r,
+		screens: i,
+		transitions: a,
+		history: o,
+		screenLists: s,
+		commentBlocks: c,
+		source: e
+	};
+}
+function N(e, t) {
+	let n = e.children.find((e) => e.type === "yaml");
+	if (!n || !n.value) return null;
+	let r = l.load(n.value);
+	if (!r || typeof r != "object") return null;
+	let i = r.annot;
+	if (!i || typeof i != "object") return null;
+	let a = D.safeParse(i);
+	if (!a.success) {
+		let e = t ? ` in ${t}` : "";
+		throw Error(`Invalid \`annot:\` frontmatter${e}:\n${P(a.error)}`);
+	}
+	return a.data;
+}
+function P(e) {
+	return e.issues.map((e) => `  - ${e.path.length ? e.path.join(".") + ": " : ""}${e.message}`).join("\n");
+}
+function F(e, t, n) {
+	let r = e;
+	switch (r.name) {
+		case "Screen":
+			n.screens.push(I(r, t));
+			return;
+		case "Transition":
+			n.transitions.push(R(r, t));
+			return;
+		case "HistoryEntry":
+			n.history.push(ge(r, t));
+			return;
+		case "ScreenList":
+			n.screenLists.push(z(r));
+			return;
+	}
+}
+function I(e, t) {
+	let n = B(e), r = [], i = (n) => {
+		let a = n;
+		if (a.name === "Overlay") {
+			r.push(L(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 = V(n.id);
+	if (!a) throw Error("<Screen> requires an `id` prop.");
+	return {
+		id: a,
+		src: V(n.src),
+		overlays: r
+	};
+}
+function L(e, t) {
+	let n = B(e), r = n.match;
+	if (!H(r)) throw Error("<Overlay> requires a `match` prop with at least `{ role, name }`.");
+	return {
+		match: r,
+		intent: V(n.intent),
+		number: ye(n.number),
+		body: U(e, t)
+	};
+}
+function R(e, t) {
+	let n = B(e), r = n.trigger;
+	if (!H(r)) throw Error("<Transition> requires a `trigger` prop with at least `{ role, name }`.");
+	return {
+		trigger: r,
+		on: V(n.on),
+		to: V(n.to),
+		body: U(e, t)
+	};
+}
+function ge(e, t) {
+	let n = B(e), r = V(n.version) ?? "", i = V(n.date) ?? "", a = V(n.author) ?? "";
+	if (!r || !i) throw Error("<HistoryEntry> requires `version` and `date` props.");
+	return {
+		version: r,
+		date: i,
+		author: a,
+		body: U(e, t)
+	};
+}
+function z(e) {
+	let t = B(e);
+	return {
+		book: V(t.book),
+		sort: V(t.sort)
+	};
+}
+function _e(e, t) {
+	let n = e.value;
+	if (typeof n != "string") return;
+	let r = n.match(he);
+	if (!r) return;
+	let i = (r[1] ?? "").trim(), a = (r[2] ?? "").trim();
+	switch (i) {
+		case k:
+			t.snapshot = a;
+			return;
+		case A:
+			t.attributes = a;
+			return;
+		case pe:
+		case me: return;
+	}
+}
+function B(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] = ve(r.value));
+	}
+	return t;
+}
+function ve(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 V(e) {
+	return typeof e == "string" ? e : void 0;
+}
+function ye(e) {
+	return typeof e == "number" ? e : void 0;
+}
+function H(e) {
+	if (!e || typeof e != "object") return !1;
+	let t = e;
+	return !(typeof t.role != "string" || typeof t.name != "string" || t.under !== void 0 && !H(t.under));
+}
+function U(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 W(e, t) {
+	let n = e;
+	return t.snapshot !== void 0 && (n = G(n, k, t.snapshot)), t.attributes !== void 0 && (n = G(n, A, t.attributes)), n;
+}
+function G(e, t, n) {
+	let r = new RegExp(String.raw`\{\s*/\*\s*` + xe(t) + String.raw`\s*[\s\S]*?\*/\s*\}`, "m"), i = be(t, n);
+	return r.test(e) ? e.replace(r, i) : `${e.trimEnd()}\n\n${i}\n`;
+}
+function be(e, t) {
+	let n = t.trim();
+	return n ? `{/* ${e}\n${n}\n*/}` : `{/* ${e} */}`;
+}
+function xe(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"
+], Se = c.extend({ screen: async ({ page: e }, t) => {
+	await t({ capture: (t) => q(e, t) });
+} });
+async function q(e, t) {
+	let n = await j(t.mdxPath);
+	if (!n) throw Error(`captureScreen: ${t.mdxPath} has no \`annot:\` frontmatter — refusing to write.`);
+	let i = n.screens.find((e) => e.id === t.id);
+	if (!i) throw Error(`captureScreen: ${t.mdxPath} has no <Screen id="${t.id}"> block.`);
+	let a = await (t.rootLocator ?? e.locator("body")).ariaSnapshot({
+		mode: "ai",
+		boxes: !0
+	}), o = await J(e, i.overlays, t.attributeWhitelist ?? K), s = W(n.source, {
+		snapshot: a.trim(),
+		attributes: o
+	});
+	await r(t.mdxPath, s, "utf8");
+}
+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/cli.ts
+async function Ce(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(we), +!!a;
+	try {
+		switch (a) {
+			case "init": return await Te(o, {
+				cwd: i,
+				stdout: n,
+				stderr: r
+			});
+			case "sync": return await ke(o, {
+				...t,
+				cwd: i,
+				stdout: n,
+				stderr: r
+			});
+			case "lint": return await Ae(o, {
+				...t,
+				cwd: i,
+				stdout: n,
+				stderr: r
+			});
+		}
+	} catch (e) {
+		return r(`annot docs ${a}: ${e.message}`), 1;
+	}
+}
+var we = [
+	"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 Te(t, n) {
+	let { cwd: a, stdout: o } = n, c = [
+		{
+			path: "annot-docs.config.ts",
+			content: Ee
+		},
+		{
+			path: "tests/docs/example.spec.ts",
+			content: De
+		},
+		{
+			path: "docs/books/example/SC-001-login.mdx",
+			content: Oe
+		}
+	], l = 0;
+	for (let t of c) {
+		let n = s(a, t.path);
+		try {
+			await e(i(n), { recursive: !0 }), await r(n, t.content, { flag: "wx" }), o(`  created ${t.path}`), l++;
+		} catch (e) {
+			if (e.code === "EEXIST") o(`  exists  ${t.path} (skipped)`);
+			else throw e;
+		}
+	}
+	return o(l === 0 ? "annot docs init: nothing to do (all targets exist)" : `annot docs init: wrote ${l} file(s)`), 0;
+}
+var Ee = "// 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", De = "// 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, screen }) => {\n  await page.goto(\"/login\");\n  await screen.capture({\n    id: \"login\",\n    mdxPath: \"docs/books/example/SC-001-login.mdx\",\n  });\n});\n", Oe = "---\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 ke(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 c = await $(await Q(s(n, a.root ?? "docs")));
+	if (c.length === 0) return r(`annot docs sync: no MDX files with \`annot:\` frontmatter under ${a.root ?? "docs"}.`), 0;
+	r(`annot docs sync: ${c.length} MDX file(s) → ${a.url}`);
+	let { newPage: l, close: u } = await Y(a.url, t);
+	try {
+		for (let e of c) {
+			let t = await j(e);
+			if (!t) continue;
+			let i = T(t.screens);
+			if (i.length === 0) {
+				r(`  skip   ${o(n, e)} (no <Screen> blocks)`);
+				continue;
+			}
+			for (let t of i) {
+				let { page: i, dispose: a } = await l(t.src ?? "/");
+				try {
+					await q(i, {
+						id: t.id,
+						mdxPath: e
+					}), r(`  synced ${o(n, e)} (screen=${t.id})`);
+				} finally {
+					await a();
+				}
+			}
+		}
+	} finally {
+		await u();
+	}
+	return 0;
+}
+async function Ae(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 c = await $(await Q(s(n, a.root ?? "docs")));
+	if (c.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: ${c.length} MDX file(s) → ${a.url}`);
+	let l = [], u = /* @__PURE__ */ new Set(), { newPage: d, close: f } = await Y(a.url, t);
+	try {
+		for (let e of c) {
+			let t = await j(e);
+			if (t) for (let r of T(t.screens)) {
+				let { page: t, dispose: i } = await d(r.src ?? "/");
+				try {
+					let i = b({
+						screen: r,
+						liveSnapshot: g(await t.locator("body").ariaSnapshot({ mode: "ai" }))
+					});
+					for (let t of i) l.push({
+						file: o(n, e),
+						finding: t
+					}), u.add(e);
+				} finally {
+					await i();
+				}
+			}
+		}
+	} finally {
+		await f();
+	}
+	if (a.json) {
+		let e = x(l.map((e) => e.finding));
+		r(JSON.stringify({
+			findings: l.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 l) r(`${je(t.severity)} ${e} [${t.screenId}] ${t.kind}: ${t.message}`);
+		let e = x(l.map((e) => e.finding));
+		r(`annot docs lint: ${e.errors} error(s), ${e.warnings} warning(s), ${e.infos} info(s).`);
+	}
+	let p = 0;
+	if (a.fix && u.size > 0) {
+		let { newPage: e, close: n } = await Y(a.url, t);
+		try {
+			for (let t of u) {
+				let n = await j(t);
+				if (n) for (let r of T(n.screens)) {
+					let { page: n, dispose: i } = await e(r.src ?? "/");
+					try {
+						await q(n, {
+							id: r.id,
+							mdxPath: t
+						}), p++;
+					} finally {
+						await i();
+					}
+				}
+			}
+		} finally {
+			await n();
+		}
+		a.json || r(`annot docs lint --fix: refreshed snapshot/attributes for ${p} screen(s).`);
+	}
+	let m = x(l.map((e) => e.finding));
+	return a.ci ? +(m.errors + m.warnings > 0) : +(m.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 = [], r = [e];
+	for (; r.length > 0;) {
+		let e = r.pop(), i;
+		try {
+			i = await n(e, { withFileTypes: !0 });
+		} catch (e) {
+			if (e.code === "ENOENT") continue;
+			throw e;
+		}
+		for (let n of i) {
+			let i = a(e, n.name);
+			if (n.isDirectory()) {
+				if (n.name === "node_modules" || n.name.startsWith(".")) continue;
+				r.push(i);
+			} else n.isFile() && n.name.endsWith(".mdx") && t.push(i);
+		}
+	}
+	return t.sort();
+}
+async function $(e) {
+	let t = [];
+	for (let n of e) try {
+		await j(n) && t.push(n);
+	} catch {}
+	return t;
+}
+function je(e) {
+	switch (e) {
+		case "error": return "ERROR  ";
+		case "warning": return "WARN   ";
+		case "info": return "INFO   ";
+	}
+}
+//#endregion
+export { K as DEFAULT_ATTR_WHITELIST, O as annotDocsConfigSchema, D as annotFrontmatterSchema, q as captureScreen, J as collectAttributesYaml, de as defineConfig, b as detectDrift, ie as detectDriftFromYaml, $ as filterAnnotMdxFiles, w as isLintableScreen, fe as isScreenRole, T as lintableScreens, Ce as main, M as parseMdx, j as parseMdxFile, g as parseSnapshot, _ as resolveMatch, ee as resolveOverlays, x as summariseDrift, Se as test, W as updateCommentBlocks, Q as walkMdx };