@keboola/validate-ui 0.4.0 → 0.5.2

package/dist/runner-ZOonToZg.js

@@ -0,0 +1,1308 @@
+import { chromium } from "playwright";
+import { createReadStream } from "node:fs";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { extname, join, normalize, resolve, sep } from "node:path";
+import axe from "axe-core";
+import { z } from "zod";
+import Anthropic from "@anthropic-ai/sdk";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import { brands, checkInteractiveContrast } from "@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 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 = join(rootDir, "index.html");
+	const rootResolved = resolve(rootDir);
+	const server = createServer((request, response) => {
+		const send = (filePath, status = 200) => {
+			response.writeHead(status, { "content-type": CONTENT_TYPES[extname(filePath)] ?? "application/octet-stream" });
+			const stream = 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 = normalize(rawPath).replace(/^(\.\.[/\\])+/, "");
+		const candidate = join(rootDir, relative);
+		const candidateResolved = resolve(candidate);
+		if (candidateResolved !== rootResolved && !candidateResolved.startsWith(rootResolved + sep)) {
+			notFound();
+			return;
+		}
+		stat(candidate).then((info) => {
+			send(info.isDirectory() ? indexPath : candidate);
+		}).catch(() => {
+			if (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.addScriptTag({ content: axe.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(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 = z.object({
+	matchesBrief: z.boolean(),
+	missingStates: z.array(z.string()),
+	reasons: z.array(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 = z.object({
+	/** Stable id: data-region → data-testid → role → aria-label → heading slug. */
+	key: z.string(),
+	/** Human label for the report. */
+	label: z.string(),
+	state: z.enum(REGION_STATES),
+	/** Normalized numeric / currency / percent tokens found in the region. */
+	values: z.array(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 = z.object({
+	/** Route the snapshot was captured at, e.g. `/financials`. */
+	route: z.string(),
+	regions: 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 = z.object({
+	region: z.string().optional(),
+	value: z.string().optional(),
+	reason: 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 = z.object({
+	expectedAbsent: z.array(ExpectedAbsentRule).optional(),
+	emptyStateMarkers: z.array(z.string()).optional(),
+	errorStateMarkers: z.array(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 writeFile(path, JSON.stringify(snapshot, null, 2));
+};
+/** Read and validate a recorded snapshot from disk. */
+const loadSnapshot = async (path) => {
+	const raw = await 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 = PNG.sync.read(Buffer.from(a));
+	const imgB = 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: pixelmatch(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) => 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 = 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 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 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(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
+export { prepareForScreenshot as A, accessibilityAxis as C, MOBILE_VIEWPORT as D, DESKTOP_VIEWPORT as E, capture as O, briefConformanceAxis as S, DEFAULT_VIEWPORTS as T, REGION_STATES as _, runAxes as a, comparePass as b, visualBrandAxis as c, captureSnapshot as d, loadSnapshot as f, ExpectedAbsentRule as g, CompareSnapshot as h, aggregatePass as i, capturePage as k, runtimeHealthAxis as l, CompareConfig as m, routeSnapshotFile as n, validate as o, saveSnapshot as p, dedupeSharedChrome as r, ALL_AXES as s, compareRoutes as t, compareAxis as u, Region as v, serveStatic as w, diffSnapshots as x, extractRegions as y };
+
+//# sourceMappingURL=runner-ZOonToZg.js.map