@keboola/validate-ui 0.2.0 → 0.4.0

package/dist/cli.js

@@ -1,16 +1,452 @@
 #!/usr/bin/env node
+import { stat, readFile } from 'fs/promises';
 import { resolve, join, normalize, sep, extname } from 'path';
 import process2 from 'process';
 import { chromium } from 'playwright';
-import axe from 'axe-core';
 import { z } from 'zod';
+import axe from 'axe-core';
 import Anthropic from '@anthropic-ai/sdk';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
+import { brands, checkInteractiveContrast } from '@keboola/brand-registry';
 import { createReadStream } from 'fs';
-import { stat } from 'fs/promises';
 import { createServer } from 'http';
 
+// src/prepare-screenshot.ts
+var 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;
+    }`
+  });
+};
+var parkMouseOffElements = async (page) => {
+  await page.mouse.move(0, 0);
+};
+var waitForFonts = async (page) => {
+  await page.evaluate(() => document.fonts.ready.then(() => void 0));
+};
+var prepareForScreenshot = async (page) => {
+  await disableAnimations(page);
+  await parkMouseOffElements(page);
+  await waitForFonts(page);
+};
+
+// src/capture.ts
+var DESKTOP_VIEWPORT = { label: "desktop", width: 1280, height: 800 };
+var DEFAULT_TIMEOUT_MS = 3e4;
+var 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 };
+};
+var capturePage = async (page, url, viewport, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+  const recorders = attachRecorders(page);
+  await page.setViewportSize({ width: viewport.width, height: viewport.height });
+  await page.goto(url, { waitUntil: "networkidle", timeout: timeoutMs });
+  await prepareForScreenshot(page);
+  const screenshot = await page.screenshot({ fullPage: true });
+  const dom = await page.content();
+  const renderedText = (await page.evaluate(() => document.body.innerText)).trim();
+  return {
+    url,
+    viewport,
+    screenshot,
+    dom,
+    renderedText,
+    console: recorders.console,
+    network: recorders.network
+  };
+};
+
+// src/compare/dedup.ts
+var groupKey = (finding) => `${finding.kind}::${finding.valueSignature}`;
+var 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 };
+};
+
+// src/compare/diff.ts
+var matchesGlob = (pattern, value) => {
+  if (!pattern.includes("*")) return pattern === value;
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`).test(value);
+};
+var 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;
+};
+var signature = (regionKey, tokens) => `${regionKey}::${[...tokens].sort().join("|")}`;
+var regionRemovalRule = (rules, key) => rules.find(
+  (rule) => rule.value === void 0 && rule.region !== void 0 && matchesGlob(rule.region, key)
+);
+var valueRuleMatches = (rule, key, value) => rule.value !== void 0 && matchesGlob(rule.value, value) && (rule.region === void 0 || matchesGlob(rule.region, key));
+var 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 } }
+});
+var degradedFinding = (region) => ({
+  regionKey: region.key,
+  kind: "region-degraded",
+  valueSignature: signature(region.key, [region.state]),
+  message: `region "${region.label}" degraded to ${region.state} state \u2014 not compared as value loss`,
+  severity: "minor"
+});
+var addedFinding = (region) => ({
+  regionKey: region.key,
+  kind: "region-added",
+  valueSignature: signature(region.key, []),
+  message: `region "${region.label}" is new`,
+  severity: "minor"
+});
+var 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;
+};
+var 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;
+};
+var comparePass = (findings) => !findings.some(
+  (f) => f.suppressed === void 0 && (f.severity === "serious" || f.severity === "critical")
+);
+
+// src/compare/regions.ts
+var 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(",");
+var DEFAULT_EMPTY_MARKERS = [
+  "no data",
+  "no results",
+  "nothing to show",
+  "nothing here",
+  "get started"
+];
+var DEFAULT_ERROR_MARKERS = [
+  "something went wrong",
+  "failed to load",
+  "could not load",
+  "unavailable",
+  "try again"
+];
+var extractRegions = async (page, config = {}) => {
+  const emptyMarkers = [...DEFAULT_EMPTY_MARKERS, ...config.emptyStateMarkers ?? []];
+  const errorMarkers = [...DEFAULT_ERROR_MARKERS, ...config.errorStateMarkers ?? []];
+  return page.evaluate(
+    ({ selector, emptyMarkers: emptyMarkers2, errorMarkers: errorMarkers2 }) => {
+      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";
+        }
+        return void 0;
+      };
+      const headingOf = (el) => {
+        const heading = el.querySelector("h1,h2,h3,h4,h5,h6");
+        const text = heading?.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 (errorMarkers2.some((marker) => lower.includes(marker))) return "error";
+        if (lower.includes("loading")) return "loading";
+        if (emptyMarkers2.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 candidates = Array.from(document.querySelectorAll(selector));
+      const regions = candidates.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 }
+  );
+};
+var REGION_STATES = ["ok", "empty", "error", "loading"];
+var 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())
+});
+var 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"
+  }
+);
+var 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`"
+});
+var CompareConfig = z.object({
+  expectedAbsent: z.array(ExpectedAbsentRule).optional(),
+  emptyStateMarkers: z.array(z.string()).optional(),
+  errorStateMarkers: z.array(z.string()).optional()
+});
+
+// src/compare/snapshot.ts
+var captureSnapshot = async (page, route, config) => ({
+  route,
+  regions: await extractRegions(page, config)
+});
+var loadSnapshot = async (path) => {
+  const raw = await readFile(path, "utf8");
+  return CompareSnapshot.parse(JSON.parse(raw));
+};
+
+// src/compare/runner.ts
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+var joinUrl = (base, route) => `${base.replace(/\/$/, "")}/${route.replace(/^\//, "")}`;
+var routeSnapshotFile = (route) => `${route.replace(/^\//, "").replace(/\/+$/, "").replace(/\//g, "_") || "index"}.json`;
+var 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_MS2;
+  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)
+    }));
+    const pass = comparePass(sharedChrome) && routes.every((route) => route.pass);
+    return { routes, sharedChrome, pass };
+  } finally {
+    if (ownsBrowser) await browser.close();
+  }
+};
 var IMPACTS = ["critical", "serious", "moderate", "minor"];
 var toSeverity = (impact) => impact && IMPACTS.includes(impact) ? impact : "minor";
 var wcagTag = (tags) => tags.find((tag) => tag.startsWith("wcag")) ?? tags[0];
@@ -165,6 +601,28 @@ ${domExcerpt}`
   }
 };
 
+// src/axes/compare.ts
+var skip2 = (message) => ({
+  axis: "compare",
+  pass: true,
+  findings: [{ message, severity: "minor" }]
+});
+var compareAxis = {
+  name: "compare",
+  run: async (context) => {
+    const { comparison, compareConfig, page } = context;
+    if (comparison === void 0) {
+      return skip2("no comparison snapshot provided; old-vs-new not assessed");
+    }
+    if (page === void 0) {
+      return skip2("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 };
+  }
+};
+
 // src/axes/runtime-health.ts
 var ERROR_MARKERS = [
   "something went wrong",
@@ -303,6 +761,11 @@ var altBrandFinding = (screenshot, altScreenshot, brand) => {
   }
   return null;
 };
+var interactiveContrastFindings = (brand) => checkInteractiveContrast(brand).map((warning) => ({
+  message: `brand '${brand.id}' ${warning.message}`,
+  severity: "moderate",
+  detail: `${warning.foreground} on ${warning.background} (${warning.palette})`
+}));
 var overflowFinding = async (page) => {
   const overflows = await page.evaluate(
     () => document.documentElement.scrollWidth > document.documentElement.clientWidth
@@ -329,6 +792,8 @@ var visualBrandAxis = {
         DEFAULT_ALT_BRAND
       );
       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);
@@ -344,85 +809,10 @@ var ALL_AXES = [
   runtimeHealthAxis,
   accessibilityAxis,
   visualBrandAxis,
-  briefConformanceAxis
+  briefConformanceAxis,
+  compareAxis
 ];
 
-// src/prepare-screenshot.ts
-var 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;
-    }`
-  });
-};
-var parkMouseOffElements = async (page) => {
-  await page.mouse.move(0, 0);
-};
-var waitForFonts = async (page) => {
-  await page.evaluate(() => document.fonts.ready.then(() => void 0));
-};
-var prepareForScreenshot = async (page) => {
-  await disableAnimations(page);
-  await parkMouseOffElements(page);
-  await waitForFonts(page);
-};
-
-// src/capture.ts
-var DESKTOP_VIEWPORT = { label: "desktop", width: 1280, height: 800 };
-var DEFAULT_TIMEOUT_MS = 3e4;
-var 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 };
-};
-var capturePage = async (page, url, viewport, timeoutMs = DEFAULT_TIMEOUT_MS) => {
-  const recorders = attachRecorders(page);
-  await page.setViewportSize({ width: viewport.width, height: viewport.height });
-  await page.goto(url, { waitUntil: "networkidle", timeout: timeoutMs });
-  await prepareForScreenshot(page);
-  const screenshot = await page.screenshot({ fullPage: true });
-  const dom = await page.content();
-  const renderedText = (await page.evaluate(() => document.body.innerText)).trim();
-  return {
-    url,
-    viewport,
-    screenshot,
-    dom,
-    renderedText,
-    console: recorders.console,
-    network: recorders.network
-  };
-};
-
 // src/aggregate.ts
 var runAxes = async (axes, context) => {
   const verdicts = [];
@@ -464,6 +854,8 @@ var validate = async (options) => {
       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 }
@@ -563,16 +955,24 @@ var HELP = `@keboola/validate-ui \u2014 closed-loop validation for generated Keb
 Usage:
   validate-ui --url <url> [--brief <text>] [--json]
   validate-ui --serve <dir> [--route <path>] [--brief <text>] [--json]
+  validate-ui compare --new <baseUrl> (--old <baseUrl> | --old-snapshots <dir>) --routes <a,b,c> [--config <file>] [--json]
 
 Options:
-  --url <url>       Render and validate a running URL
-  --serve <dir>     Serve a built SPA dir (e.g. apps/boilerplate/dist) and validate it
-  --route <path>    Route to open when using --serve (default: /)
-  --brief <text>    The brief the UI was generated from (feeds brief-conformance)
-  --json            Emit the aggregate verdict as JSON
-  --help, -h        Show this help
+  --url <url>            Render and validate a running URL
+  --serve <dir>          Serve a built SPA dir (e.g. apps/boilerplate/dist) and validate it
+  --route <path>         Route to open when using --serve (default: /)
+  --brief <text>         The brief the UI was generated from (feeds brief-conformance)
+  --json                 Emit the verdict as JSON
+  --help, -h             Show this help
 
-Exit code is 0 when every axis passes, 1 otherwise.
+compare options:
+  --new <baseUrl>        Base URL of the new build
+  --old <baseUrl>        Base URL of the old build (booted live)
+  --old-snapshots <dir>  Directory of recorded old snapshots (alternative to --old)
+  --routes <a,b,c>       Comma-separated routes to compare
+  --config <file>        JSON compare config (expectedAbsent allowlist + state markers)
+
+Exit code is 0 when every axis / route passes, 1 otherwise.
 `;
 var flagValue = (argv, name) => {
   const index = argv.indexOf(name);
@@ -590,14 +990,71 @@ var formatText = (verdict) => {
   }
   return lines.join("\n");
 };
+var formatCompareFinding = (finding) => {
+  const tag = finding.suppressed !== void 0 ? " (suppressed)" : "";
+  const detail = finding.detail !== void 0 ? ` \u2014 ${finding.detail}` : "";
+  return `      [${finding.severity}] ${finding.message}${detail}${tag}`;
+};
+var formatCompare = (result) => {
+  const lines = [`validate-ui compare ${result.pass ? "PASS" : "FAIL"}`];
+  if (result.sharedChrome.length > 0) {
+    lines.push("  shared across routes:");
+    for (const finding of result.sharedChrome) lines.push(formatCompareFinding(finding));
+  }
+  for (const route of result.routes) {
+    lines.push(`  ${route.pass ? "\u2713" : "\u2717"} ${route.route}`);
+    for (const finding of route.findings) lines.push(formatCompareFinding(finding));
+  }
+  return lines.join("\n");
+};
+var loadCompareConfig = async (path) => {
+  if (path === void 0) return void 0;
+  return CompareConfig.parse(JSON.parse(await readFile(resolve(path), "utf8")));
+};
+var runCompare = async (argv, asJson) => {
+  const newBaseUrl = flagValue(argv, "--new");
+  const oldBaseUrl = flagValue(argv, "--old");
+  const oldSnapshotDir = flagValue(argv, "--old-snapshots");
+  const routes = flagValue(argv, "--routes")?.split(",").map((route) => route.trim()).filter((route) => route !== "");
+  if (newBaseUrl === void 0 || routes === void 0 || routes.length === 0) {
+    process2.stderr.write("validate-ui compare: --new and --routes are required\n\n" + HELP);
+    process2.exitCode = 1;
+    return;
+  }
+  if (oldBaseUrl !== void 0 && oldSnapshotDir !== void 0) {
+    process2.stderr.write(
+      "validate-ui compare: pass only one of --old or --old-snapshots\n\n" + HELP
+    );
+    process2.exitCode = 1;
+    return;
+  }
+  const config = await loadCompareConfig(flagValue(argv, "--config"));
+  const base = { newBaseUrl, routes, config };
+  let result;
+  if (oldBaseUrl !== void 0) {
+    result = await compareRoutes({ ...base, oldBaseUrl });
+  } else if (oldSnapshotDir !== void 0) {
+    result = await compareRoutes({ ...base, oldSnapshotDir });
+  } else {
+    process2.stderr.write("validate-ui compare: provide --old or --old-snapshots\n\n" + HELP);
+    process2.exitCode = 1;
+    return;
+  }
+  process2.stdout.write((asJson ? JSON.stringify(result, null, 2) : formatCompare(result)) + "\n");
+  process2.exitCode = result.pass ? 0 : 1;
+};
 var main = async () => {
   const argv = process2.argv.slice(2);
   if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
     process2.stdout.write(HELP);
     return;
   }
-  const brief = flagValue(argv, "--brief");
   const asJson = argv.includes("--json");
+  if (argv[0] === "compare") {
+    await runCompare(argv.slice(1), asJson);
+    return;
+  }
+  const brief = flagValue(argv, "--brief");
   const serveDir = flagValue(argv, "--serve");
   let url = flagValue(argv, "--url");
   let server;