@keboola/validate-ui 0.5.0 → 0.5.3

package/dist/runner-CEdpbEON.cjs

@@ -0,0 +1,1518 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let playwright = require("playwright");
+let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let node_http = require("node:http");
+let node_path = require("node:path");
+let axe_core = require("axe-core");
+axe_core = __toESM(axe_core, 1);
+let zod = require("zod");
+let _anthropic_ai_sdk = require("@anthropic-ai/sdk");
+_anthropic_ai_sdk = __toESM(_anthropic_ai_sdk, 1);
+let pixelmatch = require("pixelmatch");
+pixelmatch = __toESM(pixelmatch, 1);
+let pngjs = require("pngjs");
+let _keboola_brand_registry = require("@keboola/brand-registry");
+//#region src/prepare-screenshot.ts
+const disableAnimations = async (page) => {
+	await page.addStyleTag({ content: `*, *::before, *::after {
+      animation-duration: 0s !important;
+      animation-delay: 0s !important;
+      transition-duration: 0s !important;
+      transition-delay: 0s !important;
+      caret-color: transparent !important;
+    }` });
+};
+const parkMouseOffElements = async (page) => {
+	await page.mouse.move(0, 0);
+};
+const waitForFonts = async (page) => {
+	await page.evaluate(() => document.fonts.ready.then(() => void 0));
+};
+/**
+* Settle the page before a screenshot: freeze animations first (so parking the
+* mouse can't trigger a transition), park the cursor off any element, and wait
+* for web fonts. Deterministic output makes visual diffs meaningful.
+*/
+const prepareForScreenshot = async (page) => {
+	await disableAnimations(page);
+	await parkMouseOffElements(page);
+	await waitForFonts(page);
+};
+//#endregion
+//#region src/capture.ts
+const DESKTOP_VIEWPORT = {
+	label: "desktop",
+	width: 1280,
+	height: 800
+};
+const MOBILE_VIEWPORT = {
+	label: "mobile",
+	width: 390,
+	height: 844
+};
+const DEFAULT_VIEWPORTS = [DESKTOP_VIEWPORT, MOBILE_VIEWPORT];
+const DEFAULT_TIMEOUT_MS$1 = 3e4;
+const attachRecorders = (page) => {
+	const consoleEntries = [];
+	const networkEntries = [];
+	page.on("console", (message) => {
+		consoleEntries.push({
+			type: message.type(),
+			text: message.text(),
+			location: message.location().url || void 0
+		});
+	});
+	page.on("pageerror", (error) => {
+		consoleEntries.push({
+			type: "pageerror",
+			text: error.message
+		});
+	});
+	page.on("requestfailed", (request) => {
+		networkEntries.push({
+			url: request.url(),
+			method: request.method(),
+			status: 0,
+			failure: request.failure()?.errorText
+		});
+	});
+	page.on("response", (response) => {
+		networkEntries.push({
+			url: response.url(),
+			method: response.request().method(),
+			status: response.status()
+		});
+	});
+	return {
+		console: consoleEntries,
+		network: networkEntries
+	};
+};
+/**
+* Render `url` in an already-open page at `viewport` and capture ground truth.
+* Recorders are attached before navigation so nothing is missed. The caller
+* owns the page lifecycle — this is the building block {@link capture} and the
+* orchestrator reuse.
+*/
+const capturePage = async (page, url, viewport, timeoutMs = DEFAULT_TIMEOUT_MS$1) => {
+	const recorders = attachRecorders(page);
+	await page.setViewportSize({
+		width: viewport.width,
+		height: viewport.height
+	});
+	await page.goto(url, {
+		waitUntil: "networkidle",
+		timeout: timeoutMs
+	});
+	await prepareForScreenshot(page);
+	return {
+		url,
+		viewport,
+		screenshot: await page.screenshot({ fullPage: true }),
+		dom: await page.content(),
+		renderedText: (await page.evaluate(() => document.body.innerText)).trim(),
+		console: recorders.console,
+		network: recorders.network
+	};
+};
+/**
+* Launch a headless browser (unless one is supplied), render `url` at each
+* viewport in a fresh context, and return one artifact per viewport.
+*/
+const capture = async (url, options = {}) => {
+	const viewports = options.viewports ?? DEFAULT_VIEWPORTS;
+	const browser = options.browser ?? await playwright.chromium.launch();
+	const ownsBrowser = !options.browser;
+	try {
+		const artifacts = [];
+		for (const viewport of viewports) {
+			const context = await browser.newContext({ viewport: {
+				width: viewport.width,
+				height: viewport.height
+			} });
+			const page = await context.newPage();
+			try {
+				artifacts.push(await capturePage(page, url, viewport, options.timeoutMs));
+			} finally {
+				await context.close();
+			}
+		}
+		return artifacts;
+	} finally {
+		if (ownsBrowser) await browser.close();
+	}
+};
+//#endregion
+//#region src/serve.ts
+const CONTENT_TYPES = {
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".woff2": "font/woff2",
+	".woff": "font/woff"
+};
+/**
+* Serve a built SPA directory (e.g. `apps/boilerplate/dist`) on an ephemeral
+* port with client-side-routing fallback to `index.html`, so a validator can
+* render any client route without a dev server. Node stdlib only — no runtime
+* dependency added.
+*/
+const serveStatic = async (rootDir) => {
+	const indexPath = (0, node_path.join)(rootDir, "index.html");
+	const rootResolved = (0, node_path.resolve)(rootDir);
+	const server = (0, node_http.createServer)((request, response) => {
+		const send = (filePath, status = 200) => {
+			response.writeHead(status, { "content-type": CONTENT_TYPES[(0, node_path.extname)(filePath)] ?? "application/octet-stream" });
+			const stream = (0, node_fs.createReadStream)(filePath);
+			stream.on("error", (error) => {
+				console.error(`serveStatic: failed to read ${filePath}:`, error);
+				if (!response.headersSent) response.writeHead(500);
+				response.end();
+			});
+			stream.pipe(response);
+		};
+		const notFound = () => {
+			response.writeHead(404);
+			response.end();
+		};
+		let rawPath;
+		try {
+			rawPath = decodeURIComponent((request.url ?? "/").split("?")[0] ?? "/");
+		} catch {
+			response.writeHead(400);
+			response.end();
+			return;
+		}
+		const relative = (0, node_path.normalize)(rawPath).replace(/^(\.\.[/\\])+/, "");
+		const candidate = (0, node_path.join)(rootDir, relative);
+		const candidateResolved = (0, node_path.resolve)(candidate);
+		if (candidateResolved !== rootResolved && !candidateResolved.startsWith(rootResolved + node_path.sep)) {
+			notFound();
+			return;
+		}
+		(0, node_fs_promises.stat)(candidate).then((info) => {
+			send(info.isDirectory() ? indexPath : candidate);
+		}).catch(() => {
+			if ((0, node_path.extname)(candidate) === "") {
+				send(indexPath);
+				return;
+			}
+			notFound();
+		});
+	});
+	await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const address = server.address();
+	if (address === null || typeof address === "string") throw new Error("serveStatic: failed to bind an ephemeral port");
+	return {
+		url: `http://127.0.0.1:${address.port}`,
+		close: () => new Promise((resolve, reject) => {
+			server.close((error) => error ? reject(error) : resolve());
+		})
+	};
+};
+//#endregion
+//#region src/axes/clipped-text.ts
+/**
+* Elements whose content is cut off with no way for the user to reveal it.
+*
+* This exists because a page can be free of console errors, axe violations and layout
+* overflow while still showing the user the wrong thing. The case that prompted it: an
+* editable financial grid whose cells were narrower than their own padding, so a value of
+* `800` rendered as `8`. Every other axis scored it 100.
+*
+* Deliberate truncation is not a finding. Text clipped with `text-overflow: ellipsis`
+* announces itself, and a scrollable box (`overflow: auto | scroll`) can be scrolled to
+* the rest. Only silent loss is reported — `overflow: hidden | clip` with no ellipsis, and
+* `<input>`s whose value is wider than the box that holds it (a single-line input is never
+* scrollable by eye; the user has to select into it to discover the rest). A `<textarea>`
+* is judged like any other box: it renders a real scrollbar when its content overflows
+* horizontally, so it is only a finding once something hides the overflow.
+*/
+/** Ignore sub-pixel and rounding noise — real clipping is wider than a stray pixel. */
+const CLIP_TOLERANCE_PX = 2;
+/** Cap the reported list so one systematically broken component can't flood the report. */
+const MAX_REPORTED = 10;
+/**
+* Runs in the page. Kept self-contained (no imports, no outer-scope references) because it
+* is serialised into the browser context.
+*/
+/* c8 ignore start -- executes in the browser, not under node coverage */
+const findClippedElements = ({ tolerance, max }) => {
+	const describe = (el) => {
+		const tag = el.tagName.toLowerCase();
+		const label = el.getAttribute("aria-label");
+		if (label) return `${tag}[aria-label="${label}"]`;
+		if (el.id) return `${tag}#${el.id}`;
+		const name = el.getAttribute("name");
+		if (name) return `${tag}[name="${name}"]`;
+		return `${tag}${typeof el.className === "string" && el.className.trim() ? `.${el.className.trim().split(/\s+/).slice(0, 2).join(".")}` : ""}`;
+	};
+	const results = [];
+	const reported = /* @__PURE__ */ new Set();
+	const hasReportedAncestor = (el) => {
+		let parent = el.parentElement;
+		while (parent) {
+			if (reported.has(parent)) return true;
+			parent = parent.parentElement;
+		}
+		return false;
+	};
+	for (const el of document.querySelectorAll("*")) {
+		if (results.length >= max) break;
+		if (hasReportedAncestor(el)) continue;
+		const style = window.getComputedStyle(el);
+		if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") continue;
+		if (el.clientWidth <= 1 || el.clientHeight <= 1) continue;
+		const overflowX = style.overflowX;
+		const isFormValue = el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement;
+		const isSingleLineInput = el instanceof HTMLInputElement;
+		if (!isSingleLineInput && overflowX !== "hidden" && overflowX !== "clip") continue;
+		if (!isSingleLineInput && style.textOverflow === "ellipsis") continue;
+		if (el.scrollWidth - el.clientWidth <= tolerance) continue;
+		const text = isFormValue ? el.value : (el.textContent ?? "").trim();
+		if (!text) continue;
+		reported.add(el);
+		results.push({
+			selector: describe(el),
+			text: text.length > 40 ? `${text.slice(0, 40)}…` : text,
+			visibleWidth: Math.round(el.clientWidth),
+			contentWidth: Math.round(el.scrollWidth),
+			isInput: isFormValue
+		});
+	}
+	return results;
+};
+/* c8 ignore stop */
+/** Format one clipped element as a finding. */
+const toFinding$1 = (clipped) => ({
+	message: `Content is cut off with no way to reveal it (${clipped.selector})`,
+	severity: "serious",
+	detail: `${clipped.isInput ? "Input value" : "Text"} "${clipped.text}" needs ${clipped.contentWidth}px but has ${clipped.visibleWidth}px. Widen the element, or make the truncation explicit with \`text-overflow: ellipsis\`.`
+});
+/**
+* Report every element whose content is silently cut off. Returns no findings when the
+* page cannot be inspected, so a caller can always spread the result.
+*/
+const clippedTextFindings = async (page) => {
+	try {
+		return (await page.evaluate(findClippedElements, {
+			tolerance: CLIP_TOLERANCE_PX,
+			max: MAX_REPORTED
+		})).map(toFinding$1);
+	} catch (error) {
+		console.error("clipped-text: could not inspect the page", error);
+		return [];
+	}
+};
+//#endregion
+//#region src/axes/accessibility.ts
+const IMPACTS = [
+	"critical",
+	"serious",
+	"moderate",
+	"minor"
+];
+const toSeverity = (impact) => impact && IMPACTS.includes(impact) ? impact : "minor";
+/** First `wcag*` tag if present, else the first tag, else undefined. */
+const wcagTag = (tags) => tags.find((tag) => tag.startsWith("wcag")) ?? tags[0];
+const toFinding = (violation) => {
+	const targets = violation.nodes.map((node) => node.target.join(" ")).filter((target) => target.length > 0).join(", ");
+	const wcag = wcagTag(violation.tags);
+	return {
+		message: `${violation.help || violation.description}${targets ? ` (${targets})` : ""}`,
+		severity: toSeverity(violation.impact),
+		ref: [wcag, violation.id].filter(Boolean).join(" · ")
+	};
+};
+/**
+* A3 · Accessibility verdict — UT-4494.
+*
+* Injects axe-core into `context.page` and maps each violation to a Finding
+* (WCAG tag + rule id as `ref`, axe impact as severity). Pass rule: a page
+* passes when no violation has impact `critical` or `serious` — moderate/minor
+* violations are reported but don't fail the axis. Falls back to a clear
+* finding rather than throwing when no live page is provided.
+*/
+/** Not-assessed outcome — a11y can't fail if it never ran. */
+const notAssessed = (message) => ({
+	axis: "a11y",
+	pass: true,
+	findings: [{
+		message,
+		severity: "minor"
+	}]
+});
+const accessibilityAxis = {
+	name: "a11y",
+	run: async (context) => {
+		const { page } = context;
+		if (!page) return notAssessed("a11y skipped: no live page provided");
+		await page.evaluate(axe_core.default.source);
+		const results = await page.evaluate(() => {
+			const injected = window.axe;
+			return injected ? injected.run(document) : null;
+		});
+		if (results === null) return notAssessed("a11y not assessed: axe-core failed to inject (page CSP?)");
+		const findings = [...results.violations.map(toFinding), ...await clippedTextFindings(page)];
+		return {
+			axis: "a11y",
+			pass: !findings.some((finding) => finding.severity === "critical" || finding.severity === "serious"),
+			findings
+		};
+	}
+};
+//#endregion
+//#region src/axes/vlm-provider.ts
+/** Concatenate a message's text blocks. */
+const textFromMessage = (message) => message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+const makeProvider = (backend, clientOptions) => {
+	const client = new _anthropic_ai_sdk.default(clientOptions);
+	return {
+		backend,
+		judge: async ({ screenshotBase64, prompt, model }) => {
+			const message = await client.messages.create({
+				model,
+				max_tokens: 1024,
+				messages: [{
+					role: "user",
+					content: [{
+						type: "image",
+						source: {
+							type: "base64",
+							media_type: "image/png",
+							data: screenshotBase64
+						}
+					}, {
+						type: "text",
+						text: prompt
+					}]
+				}]
+			});
+			return textFromMessage(message);
+		}
+	};
+};
+const nonEmpty = (value) => value !== void 0 && value !== "";
+/**
+* Pick a VLM backend from the environment, or `undefined` when none is
+* configured (the axis then skips gracefully).
+*
+* Preference order mirrors how kai-agent routes Claude for internal/team use
+* (`apps/kai-agent/src/services/entrypoint-builder.ts`): the Keboola LLM path
+* points the Anthropic SDK at a Keboola-hosted proxy via `baseURL` and
+* authenticates with a Keboola-minted token sent as `x-api-key` (the SDK's
+* `apiKey`). kai-agent injects that pair through the SDK-native
+* `ANTHROPIC_BASE_URL` + `ANTHROPIC_API_KEY` env vars; we accept those, and
+* prefer the explicit `VALIDATE_UI_LLM_BASE_URL` / `VALIDATE_UI_LLM_TOKEN`
+* (with `KBC_TOKEN` as a Keboola-convention alias) when set. The proxy path is
+* preferred because the team plan has no dedicated raw key.
+*
+* When no proxy `baseURL` is configured, a bare `ANTHROPIC_API_KEY` selects the
+* raw Anthropic backend — the original behavior and the fallback.
+*
+* Both backends pass the resolved key (and, for the proxy, `baseURL`) into the
+* `Anthropic` constructor explicitly, so resolution never reads ambient
+* `process.env` behind the injected `env` arg.
+*/
+const resolveVlmProvider = (env = process.env) => {
+	const baseUrl = env.VALIDATE_UI_LLM_BASE_URL ?? env.ANTHROPIC_BASE_URL;
+	const proxyToken = env.VALIDATE_UI_LLM_TOKEN ?? env.KBC_TOKEN ?? env.ANTHROPIC_API_KEY;
+	if (nonEmpty(baseUrl) && nonEmpty(proxyToken)) return makeProvider("keboola-llm", {
+		baseURL: baseUrl,
+		apiKey: proxyToken
+	});
+	if (nonEmpty(env.ANTHROPIC_API_KEY)) return makeProvider("raw-anthropic", { apiKey: env.ANTHROPIC_API_KEY });
+};
+//#endregion
+//#region src/axes/brief-conformance.ts
+/** Structured judgement the VLM must return, validated before interpretation. */
+const JudgeResult = zod.z.object({
+	matchesBrief: zod.z.boolean(),
+	missingStates: zod.z.array(zod.z.string()),
+	reasons: zod.z.array(zod.z.string())
+});
+const MODEL = process.env.VALIDATE_UI_MODEL ?? "claude-sonnet-4-6";
+const DOM_EXCERPT_LIMIT = 12e3;
+/**
+* Pure interpreter: turn a validated {@link JudgeResult} into a {@link Verdict}.
+* A brief mismatch is serious; each missing state is a moderate gap.
+*/
+const interpretJudgeResult = (result) => {
+	const findings = [];
+	if (!result.matchesBrief) findings.push({
+		message: `UI does not match the brief: ${result.reasons.join("; ")}`,
+		severity: "serious"
+	});
+	for (const state of result.missingStates) findings.push({
+		message: `missing state: ${state}`,
+		severity: "moderate"
+	});
+	return {
+		axis: "brief-conformance",
+		pass: result.matchesBrief && result.missingStates.length === 0,
+		findings
+	};
+};
+const skip$1 = (message) => ({
+	axis: "brief-conformance",
+	pass: true,
+	findings: [{
+		message,
+		severity: "minor"
+	}]
+});
+const RUBRIC = [
+	"You are judging whether a rendered UI conforms to the brief it was generated from.",
+	"Assess two things:",
+	"1. matchesBrief — does the screenshot + DOM implement what the brief describes?",
+	"2. missingStates — which UI states the brief implies are NOT represented.",
+	"   Use short lowercase labels like \"empty\", \"loading\", \"error\".",
+	"Reply with ONLY a JSON object, no prose, matching exactly:",
+	"{ \"matchesBrief\": boolean, \"missingStates\": string[], \"reasons\": string[] }",
+	"reasons: brief explanations for any mismatch (empty array if it matches)."
+].join("\n");
+const briefConformanceAxis = {
+	name: "brief-conformance",
+	run: async (context) => {
+		const brief = context.brief?.trim();
+		if (brief === void 0 || brief === "") return skip$1("no brief provided; conformance not assessed");
+		const provider = resolveVlmProvider();
+		if (provider === void 0) return skip$1("brief-conformance skipped: no VLM backend configured (set VALIDATE_UI_LLM_BASE_URL + VALIDATE_UI_LLM_TOKEN for the Keboola LLM path, or ANTHROPIC_API_KEY for a raw key)");
+		const { artifact } = context;
+		const screenshotBase64 = Buffer.from(artifact.screenshot).toString("base64");
+		const domExcerpt = artifact.dom.slice(0, DOM_EXCERPT_LIMIT);
+		const reply = await provider.judge({
+			model: MODEL,
+			screenshotBase64,
+			prompt: `${RUBRIC}\n\nBrief:\n${brief}\n\nDOM excerpt:\n${domExcerpt}`
+		});
+		try {
+			const parsed = JudgeResult.parse(JSON.parse(reply));
+			return interpretJudgeResult(parsed);
+		} catch (error) {
+			console.error("brief-conformance: failed to parse judge response", error);
+			return {
+				axis: "brief-conformance",
+				pass: false,
+				findings: [{
+					message: "could not parse judge response",
+					severity: "moderate"
+				}]
+			};
+		}
+	}
+};
+//#endregion
+//#region src/compare/diff.ts
+/** Match a `*`-glob (or exact string) against a region key. */
+const matchesGlob = (pattern, value) => {
+	if (!pattern.includes("*")) return pattern === value;
+	const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+	return new RegExp(`^${escaped}$`).test(value);
+};
+/** Multiset difference: tokens present more often in `from` than in `to`. */
+const multisetMissing = (from, to) => {
+	const remaining = /* @__PURE__ */ new Map();
+	for (const value of to) remaining.set(value, (remaining.get(value) ?? 0) + 1);
+	const missing = [];
+	for (const value of from) {
+		const count = remaining.get(value) ?? 0;
+		if (count > 0) remaining.set(value, count - 1);
+		else missing.push(value);
+	}
+	return missing;
+};
+/** Stable signature of a delta — identical across routes for the same shared element. */
+const signature = (regionKey, tokens) => `${regionKey}::${[...tokens].sort().join("|")}`;
+/** The rule that suppresses removing a whole region (region match, no value scope). */
+const regionRemovalRule = (rules, key) => rules.find((rule) => rule.value === void 0 && rule.region !== void 0 && matchesGlob(rule.region, key));
+/** Does a value rule apply to this (region, value) pair? */
+const valueRuleMatches = (rule, key, value) => rule.value !== void 0 && matchesGlob(rule.value, value) && (rule.region === void 0 || matchesGlob(rule.region, key));
+const removedFinding = (region, rule) => ({
+	regionKey: region.key,
+	kind: "region-removed",
+	valueSignature: signature(region.key, region.values),
+	message: rule === void 0 ? `region "${region.label}" was removed` : `region "${region.label}" removed as expected`,
+	severity: rule === void 0 ? "serious" : "minor",
+	...rule !== void 0 && { suppressed: { reason: rule.reason } }
+});
+const degradedFinding = (region) => ({
+	regionKey: region.key,
+	kind: "region-degraded",
+	valueSignature: signature(region.key, [region.state]),
+	message: `region "${region.label}" degraded to ${region.state} state — not compared as value loss`,
+	severity: "minor"
+});
+const addedFinding = (region) => ({
+	regionKey: region.key,
+	kind: "region-added",
+	valueSignature: signature(region.key, []),
+	message: `region "${region.label}" is new`,
+	severity: "minor"
+});
+/**
+* Diff one region present on both sides. Returns the value-missing findings
+* (active and/or suppressed), or none when values are unchanged.
+*/
+const diffRegionValues = (oldRegion, newRegion, rules) => {
+	const missing = multisetMissing(oldRegion.values, newRegion.values);
+	if (missing.length === 0) return [];
+	const active = [];
+	const suppressed = [];
+	const reasons = /* @__PURE__ */ new Set();
+	for (const value of missing) {
+		const rule = rules.find((r) => valueRuleMatches(r, newRegion.key, value));
+		if (rule === void 0) active.push(value);
+		else {
+			suppressed.push(value);
+			reasons.add(rule.reason);
+		}
+	}
+	const findings = [];
+	if (active.length > 0) findings.push({
+		regionKey: newRegion.key,
+		kind: "value-missing",
+		valueSignature: signature(newRegion.key, active),
+		message: `region "${newRegion.label}" is missing ${active.length} value(s)`,
+		severity: "moderate",
+		detail: active.join(", ")
+	});
+	if (suppressed.length > 0) findings.push({
+		regionKey: newRegion.key,
+		kind: "value-missing",
+		valueSignature: signature(newRegion.key, suppressed),
+		message: `region "${newRegion.label}" is missing ${suppressed.length} expected value(s)`,
+		severity: "minor",
+		detail: suppressed.join(", "),
+		suppressed: { reason: [...reasons].join("; ") }
+	});
+	return findings;
+};
+/**
+* Semantic old-vs-new diff of two snapshots. Walks regions by key and localizes
+* every delta to a region: a removed region is `serious` unless allowlisted; a
+* region that degraded to an empty/error state is reported informationally and
+* NOT diffed as value loss; surviving regions get a per-region value-multiset
+* diff with allowlist suppression; new regions are non-regression notes. Pure —
+* no browser, no I/O.
+*/
+const diffSnapshots = (oldSnap, newSnap, config = {}) => {
+	const rules = config.expectedAbsent ?? [];
+	const newByKey = new Map(newSnap.regions.map((region) => [region.key, region]));
+	const oldKeys = new Set(oldSnap.regions.map((region) => region.key));
+	const findings = [];
+	for (const oldRegion of oldSnap.regions) {
+		const newRegion = newByKey.get(oldRegion.key);
+		if (newRegion === void 0) {
+			findings.push(removedFinding(oldRegion, regionRemovalRule(rules, oldRegion.key)));
+			continue;
+		}
+		if (oldRegion.state === "ok" && newRegion.state !== "ok") {
+			findings.push(degradedFinding(newRegion));
+			continue;
+		}
+		findings.push(...diffRegionValues(oldRegion, newRegion, rules));
+	}
+	for (const newRegion of newSnap.regions) if (!oldKeys.has(newRegion.key)) findings.push(addedFinding(newRegion));
+	return findings;
+};
+/** A compare run passes when no active (non-suppressed) delta is serious/critical. */
+const comparePass = (findings) => !findings.some((f) => f.suppressed === void 0 && (f.severity === "serious" || f.severity === "critical"));
+//#endregion
+//#region src/compare/regions.ts
+const CANDIDATE_SELECTOR = [
+	"[data-region]",
+	"main",
+	"nav",
+	"header",
+	"aside",
+	"footer",
+	"section[aria-label]",
+	"[role=main]",
+	"[role=navigation]",
+	"[role=banner]",
+	"[role=complementary]",
+	"[role=contentinfo]",
+	"[role=region]"
+].join(",");
+const DEFAULT_EMPTY_MARKERS = [
+	"no data",
+	"no results",
+	"nothing to show",
+	"nothing here",
+	"get started"
+];
+const DEFAULT_ERROR_MARKERS = [
+	"something went wrong",
+	"failed to load",
+	"could not load",
+	"unavailable",
+	"try again"
+];
+/**
+* Reduce the live page to its diffable regions, in the browser. An explicit
+* `[data-region]` is an authoritative boundary (its subtree is one region);
+* elsewhere boundaries are the outermost-empty ("leaf") landmarks/sections, so
+* regions never overlap or double-count values. Each region's key is resolved by
+* precedence
+* (`data-region` → `data-testid` → role → `aria-label` → nearest heading), its
+* state from `data-state`/text markers, and its values as normalized numeric
+* tokens. Symmetric across old and new so the two sides diff cleanly.
+*/
+const extractRegions = async (page, config = {}) => {
+	const emptyMarkers = [...DEFAULT_EMPTY_MARKERS, ...config.emptyStateMarkers ?? []];
+	const errorMarkers = [...DEFAULT_ERROR_MARKERS, ...config.errorStateMarkers ?? []];
+	return page.evaluate(({ selector, emptyMarkers, errorMarkers }) => {
+		const STATES = [
+			"ok",
+			"empty",
+			"error",
+			"loading"
+		];
+		const isState = (value) => STATES.includes(value);
+		const slugify = (raw) => raw.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "region";
+		const roleOf = (el) => {
+			const explicit = el.getAttribute("role");
+			if (explicit !== null && explicit !== "") return explicit;
+			const tag = el.tagName.toLowerCase();
+			if (tag === "main") return "main";
+			if (tag === "nav") return "navigation";
+			if (tag === "aside") return "complementary";
+			if (tag === "header" || tag === "footer") {
+				if (el.closest("main,nav,section,article,aside") !== null) return void 0;
+				return tag === "header" ? "banner" : "contentinfo";
+			}
+		};
+		const headingOf = (el) => {
+			const text = el.querySelector("h1,h2,h3,h4,h5,h6")?.textContent?.trim();
+			return text !== void 0 && text !== "" ? text : void 0;
+		};
+		const keyOf = (el) => {
+			const region = el.getAttribute("data-region");
+			if (region !== null && region !== "") return slugify(region);
+			const testid = el.getAttribute("data-testid");
+			if (testid !== null && testid !== "") return slugify(testid);
+			const role = roleOf(el);
+			if (role !== void 0) return role;
+			const label = el.getAttribute("aria-label");
+			if (label !== null && label !== "") return slugify(label);
+			const heading = headingOf(el);
+			if (heading !== void 0) return slugify(heading);
+			return slugify(el.tagName);
+		};
+		const labelOf = (el, key) => {
+			const label = el.getAttribute("aria-label");
+			if (label !== null && label.trim() !== "") return label.trim();
+			const heading = headingOf(el);
+			if (heading !== void 0) return heading;
+			const testid = el.getAttribute("data-testid");
+			if (testid !== null && testid !== "") return testid;
+			return key;
+		};
+		const textOf = (el) => (el.innerText || el.textContent || "").trim();
+		const stateOf = (el, text) => {
+			const explicit = (el.getAttribute("data-state") ?? "").toLowerCase();
+			if (isState(explicit)) return explicit;
+			const lower = text.toLowerCase();
+			if (errorMarkers.some((marker) => lower.includes(marker))) return "error";
+			if (lower.includes("loading")) return "loading";
+			if (emptyMarkers.some((marker) => lower.includes(marker))) return "empty";
+			return "ok";
+		};
+		const valuesOf = (text) => (text.match(/-?\$?\s?\d[\d,]*(?:\.\d+)?%?/g) ?? []).map((token) => token.replace(/[$\s,]/g, "")).filter((token) => token !== "" && token !== "-");
+		const qualifies = (el) => {
+			const dataRegion = el.getAttribute("data-region");
+			if (dataRegion !== null && dataRegion !== "") {
+				const parent = el.parentElement;
+				return parent === null || parent.closest("[data-region]") === null;
+			}
+			return el.querySelector(selector) === null && el.closest("[data-region]") === null;
+		};
+		const regions = Array.from(document.querySelectorAll(selector)).filter(qualifies);
+		const elements = regions.length > 0 ? regions : [document.body];
+		const used = {};
+		const uniqueKey = (key) => {
+			const count = (used[key] ?? 0) + 1;
+			used[key] = count;
+			return count === 1 ? key : `${key}-${count}`;
+		};
+		return elements.map((el) => {
+			const text = textOf(el);
+			const key = uniqueKey(keyOf(el));
+			return {
+				key,
+				label: labelOf(el, key),
+				state: stateOf(el, text),
+				values: valuesOf(text)
+			};
+		});
+	}, {
+		selector: CANDIDATE_SELECTOR,
+		emptyMarkers,
+		errorMarkers
+	});
+};
+//#endregion
+//#region src/compare/types.ts
+/**
+* Backend/render state of a region. A region that rendered its data is `ok`;
+* `empty`/`error`/`loading` are non-data states — an old→new transition into one
+* of them is a degrade, not a value regression (a backend was unavailable, or an
+* intentional empty state is showing).
+*/
+const REGION_STATES = [
+	"ok",
+	"empty",
+	"error",
+	"loading"
+];
+/** One diffable region of a page — a landmark, labelled section, or component. */
+const Region = zod.z.object({
+	/** Stable id: data-region → data-testid → role → aria-label → heading slug. */
+	key: zod.z.string(),
+	/** Human label for the report. */
+	label: zod.z.string(),
+	state: zod.z.enum(REGION_STATES),
+	/** Normalized numeric / currency / percent tokens found in the region. */
+	values: zod.z.array(zod.z.string())
+});
+/**
+* A page reduced to its diffable regions — the currency both input paths (a live
+* boot or a recorded JSON file) produce and the differ consumes. Pure JSON, so
+* it is safe to serialize to disk and re-load; {@link loadSnapshot} validates it.
+*/
+const CompareSnapshot = zod.z.object({
+	/** Route the snapshot was captured at, e.g. `/financials`. */
+	route: zod.z.string(),
+	regions: zod.z.array(Region)
+}).refine((snap) => new Set(snap.regions.map((region) => region.key)).size === snap.regions.length, { message: "region keys must be unique" });
+/**
+* One expected-absent rule. `region` (exact or `*`-glob against {@link Region.key})
+* alone suppresses a whole `region-removed`; add `value` to suppress a specific
+* missing value token (optionally scoped to a region). `reason` is required and
+* surfaced in the report so suppression is auditable, never silent.
+*/
+const ExpectedAbsentRule = zod.z.object({
+	region: zod.z.string().optional(),
+	value: zod.z.string().optional(),
+	reason: zod.z.string().min(1)
+}).refine((rule) => rule.region !== void 0 || rule.value !== void 0, { message: "expectedAbsent rule needs at least one of `region` or `value`" });
+/** Semantic-compare configuration — the allowlist plus extra state markers. */
+const CompareConfig = zod.z.object({
+	expectedAbsent: zod.z.array(ExpectedAbsentRule).optional(),
+	emptyStateMarkers: zod.z.array(zod.z.string()).optional(),
+	errorStateMarkers: zod.z.array(zod.z.string()).optional()
+});
+//#endregion
+//#region src/compare/snapshot.ts
+/** Reduce a loaded live page to a {@link CompareSnapshot} for the given route. */
+const captureSnapshot = async (page, route, config) => ({
+	route,
+	regions: await extractRegions(page, config)
+});
+/** Persist a snapshot as pretty JSON so an "old" side can be recorded once and re-diffed. */
+const saveSnapshot = async (snapshot, path) => {
+	await (0, node_fs_promises.writeFile)(path, JSON.stringify(snapshot, null, 2));
+};
+/** Read and validate a recorded snapshot from disk. */
+const loadSnapshot = async (path) => {
+	const raw = await (0, node_fs_promises.readFile)(path, "utf8");
+	return CompareSnapshot.parse(JSON.parse(raw));
+};
+//#endregion
+//#region src/axes/compare.ts
+const skip = (message) => ({
+	axis: "compare",
+	pass: true,
+	findings: [{
+		message,
+		severity: "minor"
+	}]
+});
+/**
+* A5 · Semantic old-vs-new compare verdict — UT-4572.
+*
+* Activates only when `context.comparison` (an "old" {@link CompareSnapshot}) is
+* supplied; otherwise it degrades to a passing skip, so ordinary single-page runs
+* are unaffected. Extracts the "new" snapshot from the live `context.page`, then
+* runs the pure {@link diffSnapshots}: deltas are localized per region, declared
+* expected-absent deltas are suppressed (not dropped), and a region that degraded
+* to an empty/error state is reported informationally rather than as value loss.
+*/
+const compareAxis = {
+	name: "compare",
+	run: async (context) => {
+		const { comparison, compareConfig, page } = context;
+		if (comparison === void 0) return skip("no comparison snapshot provided; old-vs-new not assessed");
+		if (page === void 0) return skip("compare needs a live page to extract the new snapshot");
+		const newSnapshot = await captureSnapshot(page, comparison.route, compareConfig);
+		const findings = diffSnapshots(comparison, newSnapshot, compareConfig);
+		return {
+			axis: "compare",
+			pass: comparePass(findings),
+			findings
+		};
+	}
+};
+//#endregion
+//#region src/axes/runtime-health.ts
+const ERROR_MARKERS = [
+	"something went wrong",
+	"vite-error-overlay",
+	"vite-plugin-checker-error-overlay",
+	"react-error-overlay"
+];
+const pageErrorFindings = (console) => console.filter((entry) => entry.type === "pageerror").map((entry) => ({
+	message: `Uncaught page error: ${entry.text}`,
+	severity: "critical",
+	detail: entry.location
+}));
+const RESOURCE_LOAD_ECHO = "failed to load resource";
+const isResourceLoadEcho = (entry) => entry.text.toLowerCase().includes(RESOURCE_LOAD_ECHO);
+/**
+* Real app console errors only — the generic "Failed to load resource" echoes
+* are dropped (the network finding for the same URL is more useful). Identical
+* texts are deduped since one noisy error often logs on every render.
+*/
+const consoleErrorFindings = (console) => {
+	const seen = /* @__PURE__ */ new Set();
+	const findings = [];
+	for (const entry of console) {
+		if (entry.type !== "error" || isResourceLoadEcho(entry) || seen.has(entry.text)) continue;
+		seen.add(entry.text);
+		findings.push({
+			message: `Console error: ${entry.text}`,
+			severity: "serious",
+			detail: entry.location
+		});
+	}
+	return findings;
+};
+/** Turn one network entry into a finding, or null for a healthy (<400) response. */
+const toNetworkFinding = (entry) => {
+	if (entry.status === 0) return {
+		message: `Request failed: ${entry.method} ${entry.url}`,
+		severity: "serious",
+		detail: entry.failure,
+		ref: entry.url
+	};
+	if (entry.status >= 500) return {
+		message: `Server error ${entry.status}: ${entry.method} ${entry.url}`,
+		severity: "serious",
+		ref: entry.url
+	};
+	if (entry.status >= 400) return {
+		message: `Client error ${entry.status}: ${entry.method} ${entry.url}`,
+		severity: "moderate",
+		ref: entry.url
+	};
+	return null;
+};
+const SEVERITY_RANK = {
+	critical: 3,
+	serious: 2,
+	moderate: 1,
+	minor: 0
+};
+/**
+* One finding per URL. A single failing resource surfaces as a `requestfailed`,
+* a 4xx/5xx response, and a console echo — all the same root cause. Collapse
+* them by URL, keeping the most severe (a request-failure or explicit HTTP
+* status over the generic browser echo).
+*/
+const networkFindings = (network) => {
+	const byUrl = /* @__PURE__ */ new Map();
+	for (const entry of network) {
+		const finding = toNetworkFinding(entry);
+		if (finding === null) continue;
+		const existing = byUrl.get(entry.url);
+		if (existing === void 0 || SEVERITY_RANK[finding.severity] > SEVERITY_RANK[existing.severity]) byUrl.set(entry.url, finding);
+	}
+	return [...byUrl.values()];
+};
+/** An error overlay / boundary in the DOM means a crashed render, not real content. */
+const errorMarkerFinding = (dom) => {
+	const lower = dom.toLowerCase();
+	const marker = ERROR_MARKERS.find((m) => lower.includes(m));
+	return marker === void 0 ? null : {
+		message: "Error boundary / error overlay rendered instead of the app",
+		severity: "critical",
+		detail: marker
+	};
+};
+/**
+* White-screen check on the reliable live-DOM signal (`renderedText`). Skipped
+* when absent — parsing the HTML string for "emptiness" gives false positives.
+*/
+const whiteScreenFinding = (renderedText) => renderedText !== void 0 && renderedText.length === 0 ? {
+	message: "White screen: page rendered no visible text",
+	severity: "critical"
+} : null;
+/**
+* A2 · Runtime-health verdict — UT-4493.
+*
+* Pure over `context.artifact` (no live page). Collects uncaught page errors,
+* console errors, failed/4xx/5xx requests, and white-screen / error-overlay
+* signals into `findings`.
+*/
+const runtimeHealthAxis = {
+	name: "runtime-health",
+	run: (context) => {
+		const { artifact } = context;
+		const findings = [
+			...pageErrorFindings(artifact.console),
+			...consoleErrorFindings(artifact.console),
+			...networkFindings(artifact.network)
+		];
+		const errorMarker = errorMarkerFinding(artifact.dom);
+		if (errorMarker !== null) findings.push(errorMarker);
+		const whiteScreen = whiteScreenFinding(artifact.renderedText);
+		if (whiteScreen !== null) findings.push(whiteScreen);
+		const fatal = ["critical", "serious"];
+		const pass = !findings.some((f) => fatal.includes(f.severity));
+		return Promise.resolve({
+			axis: "runtime-health",
+			pass,
+			findings
+		});
+	}
+};
+//#endregion
+//#region src/axes/visual-brand.ts
+const DRIFT_THRESHOLD = .01;
+const RESKIN_THRESHOLD = .005;
+const DRIFT_PIXEL_THRESHOLD = .1;
+const RESKIN_PIXEL_THRESHOLD = .02;
+const DEFAULT_ALT_BRAND = "example-customer";
+/** Decode two PNGs and return their pixel mismatch ratio (0 = identical, 1 = every pixel differs). */
+const pngMismatchRatio = (a, b, pixelThreshold = DRIFT_PIXEL_THRESHOLD) => {
+	const imgA = pngjs.PNG.sync.read(Buffer.from(a));
+	const imgB = pngjs.PNG.sync.read(Buffer.from(b));
+	if (imgA.width !== imgB.width || imgA.height !== imgB.height) return {
+		ratio: 1,
+		sizeMismatch: true
+	};
+	const total = imgA.width * imgA.height;
+	if (total === 0) return {
+		ratio: 0,
+		sizeMismatch: false
+	};
+	return {
+		ratio: (0, pixelmatch.default)(imgA.data, imgB.data, void 0, imgA.width, imgA.height, { threshold: pixelThreshold }) / total,
+		sizeMismatch: false
+	};
+};
+const baselineFinding = (screenshot, baseline) => {
+	const { ratio, sizeMismatch } = pngMismatchRatio(screenshot, baseline);
+	if (sizeMismatch) return {
+		message: "screenshot dimensions differ from baseline",
+		severity: "moderate"
+	};
+	if (ratio > DRIFT_THRESHOLD) return {
+		message: `visual drift ${(ratio * 100).toFixed(1)}% vs baseline`,
+		severity: "moderate",
+		detail: `${(ratio * 100).toFixed(2)}% of pixels changed`
+	};
+	return null;
+};
+/**
+* Whether the alt-brand capture actually activated that brand.
+*
+* `captureUnderBrand` requests a brand with `?brand=<id>`, which only works if the app
+* reads that param and re-resolves its `ThemeProvider`. Most apps deliberately do not:
+* the brand is build configuration, not a runtime switch, and shipping a query-param
+* brand switcher into every generated app is not something a scaffold should impose.
+*
+* Without this check, such an app captures the same brand twice, and the identical
+* screenshots are reported as "chrome did not re-skin" — a false failure for code that is
+* entirely correct. The brand is nominated via `data-brand` on the root element (written
+* by `@keboola/design`'s ThemeProvider), so absence of the requested id means the request
+* was ignored, not that the chrome failed to re-skin.
+*/
+const altBrandWasApplied = (altDom, brand) => altDom.includes(`data-brand="${brand}"`);
+const altBrandFinding = (screenshot, altScreenshot, brand, altDom) => {
+	if (!altBrandWasApplied(altDom, brand)) return {
+		message: `alt-brand re-skin not assessed: the app did not apply '${brand}' from ?brand=`,
+		severity: "minor",
+		detail: "Brand is usually build configuration rather than a runtime switch. To have this axis assess re-skinning, register the alternate brand and resolve the active id from the `brand` query parameter."
+	};
+	const { ratio } = pngMismatchRatio(screenshot, altScreenshot, RESKIN_PIXEL_THRESHOLD);
+	if (ratio < RESKIN_THRESHOLD) return {
+		message: `chrome did not re-skin under alternate brand '${brand}'`,
+		severity: "serious",
+		detail: `${(ratio * 100).toFixed(2)}% of pixels changed`
+	};
+	return null;
+};
+/**
+* Non-fatal `moderate` findings for a brand's interactive foreground↔background
+* pairings that fall below WCAG-AA (button/link labels on branded fills). Surfaces
+* the guarantee `@keboola/brand-registry` computes so an AA-failing token is a
+* build-time warning here, not a runtime axe surprise. Empty for an AA-safe brand.
+*/
+const interactiveContrastFindings = (brand) => (0, _keboola_brand_registry.checkInteractiveContrast)(brand).map((warning) => ({
+	message: `brand '${brand.id}' ${warning.message}`,
+	severity: "moderate",
+	detail: `${warning.foreground} on ${warning.background} (${warning.palette})`
+}));
+const overflowFinding = async (page) => {
+	if (await page.evaluate(() => document.documentElement.scrollWidth > document.documentElement.clientWidth)) return {
+		message: "horizontal layout overflow",
+		severity: "moderate"
+	};
+	return null;
+};
+/**
+* A4 · Visual & brand-correctness verdict — UT-4495.
+*
+* Baseline diff of `context.artifact.screenshot` vs `context.baseline`
+* (pixelmatch + pngjs), plus the alt-brand fitness function via
+* `context.captureUnderBrand`: the chrome must visibly re-skin under an
+* alternate brand. Flags layout overflow. Each check degrades to no finding when
+* its input is absent. (Asserting categorical colors — Badge/Alert/ModalIcon —
+* stay fixed pixel-wise is future work; see `altBrandFinding`.)
+*/
+const visualBrandAxis = {
+	name: "visual-brand",
+	run: async (context) => {
+		const { artifact, baseline, captureUnderBrand, page } = context;
+		const findings = [];
+		if (baseline !== void 0) {
+			const finding = baselineFinding(artifact.screenshot, baseline);
+			if (finding !== null) findings.push(finding);
+		}
+		if (captureUnderBrand !== void 0) {
+			const altArtifact = await captureUnderBrand(DEFAULT_ALT_BRAND);
+			const finding = altBrandFinding(artifact.screenshot, altArtifact.screenshot, DEFAULT_ALT_BRAND, altArtifact.dom);
+			if (finding !== null) findings.push(finding);
+			const altBrand = _keboola_brand_registry.brands.find((brand) => brand.id === DEFAULT_ALT_BRAND);
+			if (altBrand !== void 0) findings.push(...interactiveContrastFindings(altBrand));
+		}
+		if (page !== void 0) {
+			const finding = await overflowFinding(page);
+			if (finding !== null) findings.push(finding);
+		}
+		return {
+			axis: "visual-brand",
+			pass: !findings.some((f) => f.severity === "critical" || f.severity === "serious"),
+			findings
+		};
+	}
+};
+//#endregion
+//#region src/axes/index.ts
+/**
+* The registered axes, in report order. `compare` runs last and only activates
+* when a comparison snapshot is supplied, so ordinary single-page runs are
+* unaffected.
+*/
+const ALL_AXES = [
+	runtimeHealthAxis,
+	accessibilityAxis,
+	visualBrandAxis,
+	briefConformanceAxis,
+	compareAxis
+];
+//#endregion
+//#region src/aggregate.ts
+/**
+* Run each axis against the shared context, isolating failures: an axis that
+* throws becomes a failing verdict instead of aborting the whole run. The error
+* is logged (never swallowed) and surfaced as a critical finding.
+*/
+const runAxes = async (axes, context) => {
+	const verdicts = [];
+	for (const axis of axes) try {
+		verdicts.push(await axis.run(context));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`validate-ui: axis "${axis.name}" threw:`, error);
+		verdicts.push({
+			axis: axis.name,
+			pass: false,
+			findings: [{
+				message: `Axis crashed: ${message}`,
+				severity: "critical"
+			}]
+		});
+	}
+	return verdicts;
+};
+/** A run passes only when every axis passed. */
+const aggregatePass = (verdicts) => verdicts.every((v) => v.pass);
+const withBrandParam = (url, brand) => {
+	const parsed = new URL(url);
+	parsed.searchParams.set("brand", brand);
+	return parsed.toString();
+};
+/**
+* The closed loop: render `url`, capture ground truth, and run every axis over
+* it, returning one machine-readable {@link AggregateVerdict}. Keeps the page
+* open for axes that need a live DOM (a11y, visual) and provides
+* `captureUnderBrand` for the alt-brand fitness function.
+*/
+const validate = async (options) => {
+	const viewport = options.viewport ?? DESKTOP_VIEWPORT;
+	const axes = options.axes ?? ALL_AXES;
+	const browser = options.browser ?? await playwright.chromium.launch();
+	const ownsBrowser = !options.browser;
+	const context = await browser.newContext({ viewport: {
+		width: viewport.width,
+		height: viewport.height
+	} });
+	const page = await context.newPage();
+	try {
+		const axisContext = {
+			artifact: await capturePage(page, options.url, viewport, options.timeoutMs),
+			page,
+			browser,
+			brief: options.brief,
+			baseline: options.baseline,
+			comparison: options.comparison,
+			compareConfig: options.compareConfig,
+			captureUnderBrand: async (brand) => {
+				const brandContext = await browser.newContext({ viewport: {
+					width: viewport.width,
+					height: viewport.height
+				} });
+				const brandPage = await brandContext.newPage();
+				try {
+					return await capturePage(brandPage, withBrandParam(options.url, brand), viewport, options.timeoutMs);
+				} finally {
+					await brandContext.close();
+				}
+			}
+		};
+		const verdicts = await runAxes(axes, axisContext);
+		return {
+			url: options.url,
+			pass: aggregatePass(verdicts),
+			verdicts
+		};
+	} finally {
+		await context.close();
+		if (ownsBrowser) await browser.close();
+	}
+};
+//#endregion
+//#region src/compare/dedup.ts
+const groupKey = (finding) => `${finding.kind}::${finding.valueSignature}`;
+/**
+* Collapse deltas that recur across routes into a single `shared-chrome` finding.
+* A value flagged on a shared header/daily-brief element would otherwise be
+* multiplied across every route (the prototype's `8.4/7.7/-8%/67%` on all 10
+* pages); here it is reported once, tagged with the routes it spans, and dropped
+* from each route's own list. Pure — no browser, no I/O.
+*/
+const dedupeSharedChrome = (perRoute) => {
+	const routesByGroup = /* @__PURE__ */ new Map();
+	for (const { route, findings } of perRoute) for (const finding of findings) {
+		const key = groupKey(finding);
+		const routes = routesByGroup.get(key) ?? /* @__PURE__ */ new Set();
+		routes.add(route);
+		routesByGroup.set(key, routes);
+	}
+	const sharedGroups = new Set([...routesByGroup].filter(([, routes]) => routes.size >= 2).map(([key]) => key));
+	const sharedChrome = [];
+	const seenShared = /* @__PURE__ */ new Set();
+	const trimmedPerRoute = perRoute.map(({ route, findings }) => ({
+		route,
+		findings: findings.filter((finding) => !sharedGroups.has(groupKey(finding)))
+	}));
+	for (const { findings } of perRoute) for (const finding of findings) {
+		const key = groupKey(finding);
+		if (!sharedGroups.has(key) || seenShared.has(key)) continue;
+		seenShared.add(key);
+		const routes = [...routesByGroup.get(key) ?? []].sort();
+		sharedChrome.push({
+			...finding,
+			message: `${finding.message} (shared across ${routes.length} routes: ${routes.join(", ")})`
+		});
+	}
+	return {
+		sharedChrome,
+		perRoute: trimmedPerRoute
+	};
+};
+//#endregion
+//#region src/compare/runner.ts
+const DEFAULT_TIMEOUT_MS = 3e4;
+const joinUrl = (base, route) => `${base.replace(/\/$/, "")}/${route.replace(/^\//, "")}`;
+/** Recorded old snapshot filename for a route: `/a/b` → `a_b.json`, `/` → `index.json`. */
+const routeSnapshotFile = (route) => `${route.replace(/^\//, "").replace(/\/+$/, "").replace(/\//g, "_") || "index"}.json`;
+/**
+* Multi-route semantic compare. Boots each route on the new side (and the old
+* side too, unless recorded snapshots are supplied), diffs per route, then
+* collapses deltas that recur across routes into a single shared-chrome entry so
+* one shared element is not reported as N regressions. Exactly one of
+* `oldBaseUrl` / `oldSnapshotDir` must be given.
+*/
+const compareRoutes = async (options) => {
+	if (options.oldBaseUrl === void 0 === (options.oldSnapshotDir === void 0)) throw new Error("compareRoutes: provide exactly one of oldBaseUrl or oldSnapshotDir");
+	const viewport = options.viewport ?? DESKTOP_VIEWPORT;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const browser = options.browser ?? await playwright.chromium.launch();
+	const ownsBrowser = options.browser === void 0;
+	const { oldBaseUrl, oldSnapshotDir } = options;
+	const snapshotUrl = async (url, route) => {
+		const context = await browser.newContext({ viewport: {
+			width: viewport.width,
+			height: viewport.height
+		} });
+		const page = await context.newPage();
+		try {
+			await page.goto(url, {
+				waitUntil: "networkidle",
+				timeout: timeoutMs
+			});
+			await prepareForScreenshot(page);
+			return await captureSnapshot(page, route, options.config);
+		} finally {
+			await context.close();
+		}
+	};
+	const oldSnapshotFor = (route) => {
+		if (oldBaseUrl !== void 0) return snapshotUrl(joinUrl(oldBaseUrl, route), route);
+		if (oldSnapshotDir !== void 0) return loadSnapshot((0, node_path.join)(oldSnapshotDir, routeSnapshotFile(route)));
+		throw new Error("compareRoutes: provide exactly one of oldBaseUrl or oldSnapshotDir");
+	};
+	try {
+		const perRoute = [];
+		for (const route of options.routes) {
+			const oldSnapshot = await oldSnapshotFor(route);
+			const newSnapshot = await snapshotUrl(joinUrl(options.newBaseUrl, route), route);
+			perRoute.push({
+				route,
+				findings: diffSnapshots(oldSnapshot, newSnapshot, options.config)
+			});
+		}
+		const { sharedChrome, perRoute: trimmed } = dedupeSharedChrome(perRoute);
+		const routes = trimmed.map(({ route, findings }) => ({
+			route,
+			findings,
+			pass: comparePass(findings)
+		}));
+		return {
+			routes,
+			sharedChrome,
+			pass: comparePass(sharedChrome) && routes.every((route) => route.pass)
+		};
+	} finally {
+		if (ownsBrowser) await browser.close();
+	}
+};
+//#endregion
+Object.defineProperty(exports, "ALL_AXES", {
+	enumerable: true,
+	get: function() {
+		return ALL_AXES;
+	}
+});
+Object.defineProperty(exports, "CompareConfig", {
+	enumerable: true,
+	get: function() {
+		return CompareConfig;
+	}
+});
+Object.defineProperty(exports, "CompareSnapshot", {
+	enumerable: true,
+	get: function() {
+		return CompareSnapshot;
+	}
+});
+Object.defineProperty(exports, "DEFAULT_VIEWPORTS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_VIEWPORTS;
+	}
+});
+Object.defineProperty(exports, "DESKTOP_VIEWPORT", {
+	enumerable: true,
+	get: function() {
+		return DESKTOP_VIEWPORT;
+	}
+});
+Object.defineProperty(exports, "ExpectedAbsentRule", {
+	enumerable: true,
+	get: function() {
+		return ExpectedAbsentRule;
+	}
+});
+Object.defineProperty(exports, "MOBILE_VIEWPORT", {
+	enumerable: true,
+	get: function() {
+		return MOBILE_VIEWPORT;
+	}
+});
+Object.defineProperty(exports, "REGION_STATES", {
+	enumerable: true,
+	get: function() {
+		return REGION_STATES;
+	}
+});
+Object.defineProperty(exports, "Region", {
+	enumerable: true,
+	get: function() {
+		return Region;
+	}
+});
+Object.defineProperty(exports, "__toESM", {
+	enumerable: true,
+	get: function() {
+		return __toESM;
+	}
+});
+Object.defineProperty(exports, "accessibilityAxis", {
+	enumerable: true,
+	get: function() {
+		return accessibilityAxis;
+	}
+});
+Object.defineProperty(exports, "aggregatePass", {
+	enumerable: true,
+	get: function() {
+		return aggregatePass;
+	}
+});
+Object.defineProperty(exports, "briefConformanceAxis", {
+	enumerable: true,
+	get: function() {
+		return briefConformanceAxis;
+	}
+});
+Object.defineProperty(exports, "capture", {
+	enumerable: true,
+	get: function() {
+		return capture;
+	}
+});
+Object.defineProperty(exports, "capturePage", {
+	enumerable: true,
+	get: function() {
+		return capturePage;
+	}
+});
+Object.defineProperty(exports, "captureSnapshot", {
+	enumerable: true,
+	get: function() {
+		return captureSnapshot;
+	}
+});
+Object.defineProperty(exports, "compareAxis", {
+	enumerable: true,
+	get: function() {
+		return compareAxis;
+	}
+});
+Object.defineProperty(exports, "comparePass", {
+	enumerable: true,
+	get: function() {
+		return comparePass;
+	}
+});
+Object.defineProperty(exports, "compareRoutes", {
+	enumerable: true,
+	get: function() {
+		return compareRoutes;
+	}
+});
+Object.defineProperty(exports, "dedupeSharedChrome", {
+	enumerable: true,
+	get: function() {
+		return dedupeSharedChrome;
+	}
+});
+Object.defineProperty(exports, "diffSnapshots", {
+	enumerable: true,
+	get: function() {
+		return diffSnapshots;
+	}
+});
+Object.defineProperty(exports, "extractRegions", {
+	enumerable: true,
+	get: function() {
+		return extractRegions;
+	}
+});
+Object.defineProperty(exports, "loadSnapshot", {
+	enumerable: true,
+	get: function() {
+		return loadSnapshot;
+	}
+});
+Object.defineProperty(exports, "prepareForScreenshot", {
+	enumerable: true,
+	get: function() {
+		return prepareForScreenshot;
+	}
+});
+Object.defineProperty(exports, "routeSnapshotFile", {
+	enumerable: true,
+	get: function() {
+		return routeSnapshotFile;
+	}
+});
+Object.defineProperty(exports, "runAxes", {
+	enumerable: true,
+	get: function() {
+		return runAxes;
+	}
+});
+Object.defineProperty(exports, "runtimeHealthAxis", {
+	enumerable: true,
+	get: function() {
+		return runtimeHealthAxis;
+	}
+});
+Object.defineProperty(exports, "saveSnapshot", {
+	enumerable: true,
+	get: function() {
+		return saveSnapshot;
+	}
+});
+Object.defineProperty(exports, "serveStatic", {
+	enumerable: true,
+	get: function() {
+		return serveStatic;
+	}
+});
+Object.defineProperty(exports, "validate", {
+	enumerable: true,
+	get: function() {
+		return validate;
+	}
+});
+Object.defineProperty(exports, "visualBrandAxis", {
+	enumerable: true,
+	get: function() {
+		return visualBrandAxis;
+	}
+});
+
+//# sourceMappingURL=runner-CEdpbEON.cjs.map