@keboola/validate-ui 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,81 @@
 import { Page, Browser } from 'playwright';
+import { z } from 'zod';
+
+/**
+ * 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).
+ */
+declare const REGION_STATES: readonly ["ok", "empty", "error", "loading"];
+type RegionState = (typeof REGION_STATES)[number];
+/** One diffable region of a page — a landmark, labelled section, or component. */
+declare const Region: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    state: z.ZodEnum<{
+        ok: "ok";
+        empty: "empty";
+        error: "error";
+        loading: "loading";
+    }>;
+    values: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type Region = z.infer<typeof Region>;
+/**
+ * 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.
+ */
+declare const CompareSnapshot: z.ZodObject<{
+    route: z.ZodString;
+    regions: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        state: z.ZodEnum<{
+            ok: "ok";
+            empty: "empty";
+            error: "error";
+            loading: "loading";
+        }>;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CompareSnapshot = z.infer<typeof CompareSnapshot>;
+/** One old-vs-new delta, always attributed to a region. */
+type CompareFinding = Finding & {
+    regionKey: string;
+    kind: 'region-removed' | 'region-degraded' | 'value-missing' | 'region-added';
+    /** Stable signature of the delta — identical across routes for shared chrome. */
+    valueSignature: string;
+    /** Present when a config rule suppressed this delta; it never fails the verdict. */
+    suppressed?: {
+        reason: string;
+    };
+};
+/**
+ * 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.
+ */
+declare const ExpectedAbsentRule: z.ZodObject<{
+    region: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    reason: z.ZodString;
+}, z.core.$strip>;
+type ExpectedAbsentRule = z.infer<typeof ExpectedAbsentRule>;
+/** Semantic-compare configuration — the allowlist plus extra state markers. */
+declare const CompareConfig: z.ZodObject<{
+    expectedAbsent: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        region: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    emptyStateMarkers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    errorStateMarkers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type CompareConfig = z.infer<typeof CompareConfig>;
 
 /** A named viewport the harness renders and captures at. */
 type Viewport = {
@@ -84,11 +161,15 @@ type AxisContext = {
     baseline?: Uint8Array;
     /** Re-render the same route under a different brand id and capture it. */
     captureUnderBrand?: (brand: string) => Promise<CaptureArtifact>;
+    /** The "old" UI reduced to regions — enables the compare axis when present. */
+    comparison?: CompareSnapshot;
+    /** Allowlist + state markers for the compare axis. */
+    compareConfig?: CompareConfig;
 };
 /**
- * A verdict axis. Each of the four axes (runtime-health, accessibility,
- * visual-brand, brief-conformance) implements this contract in its own file so
- * they can be built independently. `run` must resolve to a {@link Verdict} and
+ * A verdict axis. Each of the axes (runtime-health, accessibility,
+ * visual-brand, brief-conformance, compare) implements this contract in its own
+ * file so they can be built independently. `run` must resolve to a {@link Verdict} and
  * should not throw for expected-missing input — the aggregator converts a throw
  * into a failing verdict, but a clear finding is better.
  */
@@ -157,6 +238,10 @@ type ValidateOptions = {
     /** Reuse a browser instead of launching one. */
     browser?: Browser;
     timeoutMs?: number;
+    /** The "old" UI reduced to regions — enables the compare axis when present. */
+    comparison?: CompareSnapshot;
+    /** Allowlist + state markers for the compare axis. */
+    compareConfig?: CompareConfig;
 };
 /**
  * The closed loop: render `url`, capture ground truth, and run every axis over
@@ -170,6 +255,18 @@ declare const accessibilityAxis: Axis;
 
 declare const briefConformanceAxis: Axis;
 
+/**
+ * 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.
+ */
+declare const compareAxis: Axis;
+
 /**
  * A2 · Runtime-health verdict — UT-4493.
  *
@@ -191,7 +288,101 @@ declare const runtimeHealthAxis: Axis;
  */
 declare const visualBrandAxis: Axis;
 
-/** The four axes, in report order. */
+/**
+ * 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.
+ */
 declare const ALL_AXES: Axis[];
 
-export { ALL_AXES, type AggregateVerdict, type Axis, type AxisContext, type CaptureArtifact, type CaptureOptions, type ConsoleEntry, DEFAULT_VIEWPORTS, DESKTOP_VIEWPORT, type Finding, MOBILE_VIEWPORT, type NetworkEntry, SEVERITIES, type Severity, type StaticServer, type ValidateOptions, type Verdict, type Viewport, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, prepareForScreenshot, runAxes, runtimeHealthAxis, serveStatic, validate, visualBrandAxis };
+/**
+ * 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.
+ */
+declare const diffSnapshots: (oldSnap: CompareSnapshot, newSnap: CompareSnapshot, config?: CompareConfig) => CompareFinding[];
+/** A compare run passes when no active (non-suppressed) delta is serious/critical. */
+declare const comparePass: (findings: CompareFinding[]) => boolean;
+
+/** One route's compare findings. */
+type RouteFindings = {
+    route: string;
+    findings: CompareFinding[];
+};
+type DedupResult = {
+    /** Findings seen on ≥2 routes, collapsed to one entry tagged with the route count. */
+    sharedChrome: CompareFinding[];
+    /** Per-route findings with the shared-chrome copies removed. */
+    perRoute: RouteFindings[];
+};
+/**
+ * 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.
+ */
+declare const dedupeSharedChrome: (perRoute: RouteFindings[]) => DedupResult;
+
+/**
+ * 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.
+ */
+declare const extractRegions: (page: Page, config?: CompareConfig) => Promise<Region[]>;
+
+/** How the "old" side is sourced — booted live or loaded from recorded snapshots, never both. */
+type OldSource = {
+    oldBaseUrl: string;
+    oldSnapshotDir?: never;
+} | {
+    oldSnapshotDir: string;
+    oldBaseUrl?: never;
+};
+type CompareRoutesOptions = OldSource & {
+    /** Base URL of the new build, joined with each route. */
+    newBaseUrl: string;
+    routes: string[];
+    config?: CompareConfig;
+    browser?: Browser;
+    viewport?: Viewport;
+    timeoutMs?: number;
+};
+type RouteCompareResult = {
+    route: string;
+    findings: CompareFinding[];
+    pass: boolean;
+};
+type CompareRoutesResult = {
+    routes: RouteCompareResult[];
+    /** Deltas seen on ≥2 routes, reported once (e.g. shared chrome / daily-brief). */
+    sharedChrome: CompareFinding[];
+    pass: boolean;
+};
+/** Recorded old snapshot filename for a route: `/a/b` → `a_b.json`, `/` → `index.json`. */
+declare const routeSnapshotFile: (route: string) => string;
+/**
+ * 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.
+ */
+declare const compareRoutes: (options: CompareRoutesOptions) => Promise<CompareRoutesResult>;
+
+/** Reduce a loaded live page to a {@link CompareSnapshot} for the given route. */
+declare const captureSnapshot: (page: Page, route: string, config?: CompareConfig) => Promise<CompareSnapshot>;
+/** Persist a snapshot as pretty JSON so an "old" side can be recorded once and re-diffed. */
+declare const saveSnapshot: (snapshot: CompareSnapshot, path: string) => Promise<void>;
+/** Read and validate a recorded snapshot from disk. */
+declare const loadSnapshot: (path: string) => Promise<CompareSnapshot>;
+
+export { ALL_AXES, type AggregateVerdict, type Axis, type AxisContext, type CaptureArtifact, type CaptureOptions, CompareConfig, type CompareFinding, type CompareRoutesOptions, type CompareRoutesResult, CompareSnapshot, type ConsoleEntry, DEFAULT_VIEWPORTS, DESKTOP_VIEWPORT, type DedupResult, ExpectedAbsentRule, type Finding, MOBILE_VIEWPORT, type NetworkEntry, REGION_STATES, Region, type RegionState, type RouteCompareResult, type RouteFindings, SEVERITIES, type Severity, type StaticServer, type ValidateOptions, type Verdict, type Viewport, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, captureSnapshot, compareAxis, comparePass, compareRoutes, dedupeSharedChrome, diffSnapshots, extractRegions, loadSnapshot, prepareForScreenshot, routeSnapshotFile, runAxes, runtimeHealthAxis, saveSnapshot, serveStatic, validate, visualBrandAxis };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { chromium } from 'playwright';
 import { createReadStream } from 'fs';
-import { stat } from 'fs/promises';
+import { stat, writeFile, readFile } from 'fs/promises';
 import { createServer } from 'http';
 import { join, resolve, normalize, sep, extname } from 'path';
 import axe from 'axe-core';
@@ -333,6 +333,302 @@ ${domExcerpt}`
   }
 };
 
+// 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 saveSnapshot = async (snapshot, path) => {
+  await writeFile(path, JSON.stringify(snapshot, null, 2));
+};
+var loadSnapshot = async (path) => {
+  const raw = await readFile(path, "utf8");
+  return CompareSnapshot.parse(JSON.parse(raw));
+};
+
+// 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",
@@ -512,7 +808,8 @@ var ALL_AXES = [
   runtimeHealthAxis,
   accessibilityAxis,
   visualBrandAxis,
-  briefConformanceAxis
+  briefConformanceAxis,
+  compareAxis
 ];
 
 // src/aggregate.ts
@@ -556,6 +853,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 }
@@ -581,6 +880,93 @@ var validate = async (options) => {
   }
 };
 
-export { ALL_AXES, DEFAULT_VIEWPORTS, DESKTOP_VIEWPORT, MOBILE_VIEWPORT, SEVERITIES, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, prepareForScreenshot, runAxes, runtimeHealthAxis, serveStatic, validate, visualBrandAxis };
+// 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 };
+};
+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();
+  }
+};
+
+export { ALL_AXES, CompareConfig, CompareSnapshot, DEFAULT_VIEWPORTS, DESKTOP_VIEWPORT, ExpectedAbsentRule, MOBILE_VIEWPORT, REGION_STATES, Region, SEVERITIES, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, captureSnapshot, compareAxis, comparePass, compareRoutes, dedupeSharedChrome, diffSnapshots, extractRegions, loadSnapshot, prepareForScreenshot, routeSnapshotFile, runAxes, runtimeHealthAxis, saveSnapshot, serveStatic, validate, visualBrandAxis };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map