@keboola/validate-ui 0.4.0 → 0.5.2

package/dist/index.d.ts

@@ -1,25 +1,26 @@
-import { Page, Browser } from 'playwright';
-import { z } from 'zod';
-
+import { Browser, Page } from "playwright";
+import { z } from "zod";
+import "@keboola/brand-registry";
+//#region src/compare/types.d.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).
  */
-declare const REGION_STATES: readonly ["ok", "empty", "error", "loading"];
+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>;
+  key: z.ZodString;
+  label: z.ZodString;
+  state: z.ZodEnum<{
+    empty: "empty";
+    error: "error";
+    loading: "loading";
+    ok: "ok";
+  }>;
+  values: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 type Region = z.infer<typeof Region>;
 /**
@@ -28,30 +29,30 @@ type Region = z.infer<typeof Region>;
  * 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>>;
+  route: z.ZodString;
+  regions: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    state: z.ZodEnum<{
+      empty: "empty";
+      error: "error";
+      loading: "loading";
+      ok: "ok";
+    }>;
+    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;
-    };
+  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})
@@ -60,42 +61,43 @@ type CompareFinding = Finding & {
  * 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;
+  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>>;
+  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>;
-
+//#endregion
+//#region src/types.d.ts
 /** A named viewport the harness renders and captures at. */
 type Viewport = {
-    label: string;
-    width: number;
-    height: number;
+  label: string;
+  width: number;
+  height: number;
 };
 /** A single console / page-error message emitted while the page loaded. */
 type ConsoleEntry = {
-    type: string;
-    text: string;
-    location?: string;
+  type: string;
+  text: string;
+  location?: string;
 };
 /** A network response or failed request observed during load. */
 type NetworkEntry = {
-    url: string;
-    method: string;
-    /** HTTP status, or 0 for a request that failed before a response. */
-    status: number;
-    failure?: string;
+  url: string;
+  method: string;
+  /** HTTP status, or 0 for a request that failed before a response. */
+  status: number;
+  failure?: string;
 };
 /**
  * Ground truth captured from a rendered page — the input every verdict axis
@@ -103,43 +105,43 @@ type NetworkEntry = {
  * so it is safe to serialize and pass to a VLM.
  */
 type CaptureArtifact = {
-    url: string;
-    viewport: Viewport;
-    /** Full-page PNG bytes. */
-    screenshot: Uint8Array;
-    /** Serialized outer HTML of the document after load. */
-    dom: string;
-    /**
-     * Trimmed `body.innerText` read from the live DOM when available. An empty
-     * string is a reliable white-screen signal — more robust than parsing
-     * {@link dom}. Absent only when an artifact is built without a live page.
-     */
-    renderedText?: string;
-    console: ConsoleEntry[];
-    network: NetworkEntry[];
+  url: string;
+  viewport: Viewport;
+  /** Full-page PNG bytes. */
+  screenshot: Uint8Array;
+  /** Serialized outer HTML of the document after load. */
+  dom: string;
+  /**
+   * Trimmed `body.innerText` read from the live DOM when available. An empty
+   * string is a reliable white-screen signal — more robust than parsing
+   * {@link dom}. Absent only when an artifact is built without a live page.
+   */
+  renderedText?: string;
+  console: ConsoleEntry[];
+  network: NetworkEntry[];
 };
-declare const SEVERITIES: readonly ["critical", "serious", "moderate", "minor"];
+declare const SEVERITIES: readonly ['critical', 'serious', 'moderate', 'minor'];
 type Severity = (typeof SEVERITIES)[number];
 /** One problem an axis found. */
 type Finding = {
-    message: string;
-    severity: Severity;
-    /** Optional extra context — a stack, a WCAG id, a selector, a diff ratio. */
-    detail?: string;
-    /** Optional pointer — WCAG ref, DOM selector, request URL, etc. */
-    ref?: string;
+  message: string;
+  severity: Severity;
+  /** Optional extra context — a stack, a WCAG id, a selector, a diff ratio. */
+  detail?: string;
+  /** Optional pointer — WCAG ref, DOM selector, request URL, etc. */
+  ref?: string;
 };
 /** The result of running one axis against one page. */
 type Verdict = {
-    axis: string;
-    pass: boolean;
-    findings: Finding[];
+  axis: string;
+  pass: boolean;
+  findings: Finding[];
 };
 /** The combined result of running every axis against one page. */
 type AggregateVerdict = {
-    url: string;
-    pass: boolean;
-    verdicts: Verdict[];
+  url: string;
+  pass: boolean;
+  verdicts: Verdict[];
 };
 /**
  * Everything an axis may need. Different axes use different fields — a11y and
@@ -150,21 +152,21 @@ type AggregateVerdict = {
  * missing.
  */
 type AxisContext = {
-    artifact: CaptureArtifact;
-    /** Live page for the primary capture, when the run keeps a browser open. */
-    page?: Page;
-    /** Shared browser, for axes that need to render additional pages. */
-    browser?: Browser;
-    /** The natural-language brief the UI was generated from. */
-    brief?: string;
-    /** A prior screenshot to diff the current one against. */
-    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;
+  artifact: CaptureArtifact;
+  /** Live page for the primary capture, when the run keeps a browser open. */
+  page?: Page;
+  /** Shared browser, for axes that need to render additional pages. */
+  browser?: Browser;
+  /** The natural-language brief the UI was generated from. */
+  brief?: string;
+  /** A prior screenshot to diff the current one against. */
+  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 axes (runtime-health, accessibility,
@@ -174,10 +176,11 @@ type AxisContext = {
  * into a failing verdict, but a clear finding is better.
  */
 type Axis = {
-    name: string;
-    run: (context: AxisContext) => Promise<Verdict>;
+  name: string;
+  run: (context: AxisContext) => Promise<Verdict>;
 };
-
+//#endregion
+//#region src/capture.d.ts
 declare const DESKTOP_VIEWPORT: Viewport;
 declare const MOBILE_VIEWPORT: Viewport;
 declare const DEFAULT_VIEWPORTS: Viewport[];
@@ -189,27 +192,29 @@ declare const DEFAULT_VIEWPORTS: Viewport[];
  */
 declare const capturePage: (page: Page, url: string, viewport: Viewport, timeoutMs?: number) => Promise<CaptureArtifact>;
 type CaptureOptions = {
-    viewports?: Viewport[];
-    /** Reuse an existing browser instead of launching (and closing) one. */
-    browser?: Browser;
-    timeoutMs?: number;
+  viewports?: Viewport[];
+  /** Reuse an existing browser instead of launching (and closing) one. */
+  browser?: Browser;
+  timeoutMs?: number;
 };
 /**
  * Launch a headless browser (unless one is supplied), render `url` at each
  * viewport in a fresh context, and return one artifact per viewport.
  */
 declare const capture: (url: string, options?: CaptureOptions) => Promise<CaptureArtifact[]>;
-
+//#endregion
+//#region src/prepare-screenshot.d.ts
 /**
  * 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.
  */
 declare const prepareForScreenshot: (page: Page) => Promise<void>;
-
+//#endregion
+//#region src/serve.d.ts
 type StaticServer = {
-    url: string;
-    close: () => Promise<void>;
+  url: string;
+  close: () => Promise<void>;
 };
 /**
  * Serve a built SPA directory (e.g. `apps/boilerplate/dist`) on an ephemeral
@@ -218,7 +223,8 @@ type StaticServer = {
  * dependency added.
  */
 declare const serveStatic: (rootDir: string) => Promise<StaticServer>;
-
+//#endregion
+//#region src/aggregate.d.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
@@ -228,20 +234,20 @@ declare const runAxes: (axes: Axis[], context: AxisContext) => Promise<Verdict[]
 /** A run passes only when every axis passed. */
 declare const aggregatePass: (verdicts: Verdict[]) => boolean;
 type ValidateOptions = {
-    url: string;
-    brief?: string;
-    baseline?: Uint8Array;
-    /** Viewport axes run against (a11y/visual use one). Defaults to desktop. */
-    viewport?: Viewport;
-    /** Override the axis set — defaults to all four registered axes. */
-    axes?: Axis[];
-    /** 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;
+  url: string;
+  brief?: string;
+  baseline?: Uint8Array;
+  /** Viewport axes run against (a11y/visual use one). Defaults to desktop. */
+  viewport?: Viewport;
+  /** Override the axis set — defaults to all four registered axes. */
+  axes?: Axis[];
+  /** 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
@@ -250,11 +256,14 @@ type ValidateOptions = {
  * `captureUnderBrand` for the alt-brand fitness function.
  */
 declare const validate: (options: ValidateOptions) => Promise<AggregateVerdict>;
-
+//#endregion
+//#region src/axes/accessibility.d.ts
 declare const accessibilityAxis: Axis;
-
+//#endregion
+//#region src/axes/brief-conformance.d.ts
 declare const briefConformanceAxis: Axis;
-
+//#endregion
+//#region src/axes/compare.d.ts
 /**
  * A5 · Semantic old-vs-new compare verdict — UT-4572.
  *
@@ -266,7 +275,8 @@ declare const briefConformanceAxis: Axis;
  * to an empty/error state is reported informationally rather than as value loss.
  */
 declare const compareAxis: Axis;
-
+//#endregion
+//#region src/axes/runtime-health.d.ts
 /**
  * A2 · Runtime-health verdict — UT-4493.
  *
@@ -275,7 +285,8 @@ declare const compareAxis: Axis;
  * signals into `findings`.
  */
 declare const runtimeHealthAxis: Axis;
-
+//#endregion
+//#region src/axes/visual-brand.d.ts
 /**
  * A4 · Visual & brand-correctness verdict — UT-4495.
  *
@@ -287,14 +298,16 @@ declare const runtimeHealthAxis: Axis;
  * stay fixed pixel-wise is future work; see `altBrandFinding`.)
  */
 declare const visualBrandAxis: Axis;
-
+//#endregion
+//#region src/axes/index.d.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.
  */
 declare const ALL_AXES: Axis[];
-
+//#endregion
+//#region src/compare/diff.d.ts
 /**
  * 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
@@ -306,17 +319,18 @@ declare const ALL_AXES: Axis[];
 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;
-
+//#endregion
+//#region src/compare/dedup.d.ts
 /** One route's compare findings. */
 type RouteFindings = {
-    route: string;
-    findings: CompareFinding[];
+  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[];
+  /** 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.
@@ -326,7 +340,8 @@ type DedupResult = {
  * from each route's own list. Pure — no browser, no I/O.
  */
 declare const dedupeSharedChrome: (perRoute: RouteFindings[]) => DedupResult;
-
+//#endregion
+//#region src/compare/regions.d.ts
 /**
  * Reduce the live page to its diffable regions, in the browser. An explicit
  * `[data-region]` is an authoritative boundary (its subtree is one region);
@@ -338,34 +353,35 @@ declare const dedupeSharedChrome: (perRoute: RouteFindings[]) => DedupResult;
  * tokens. Symmetric across old and new so the two sides diff cleanly.
  */
 declare const extractRegions: (page: Page, config?: CompareConfig) => Promise<Region[]>;
-
+//#endregion
+//#region src/compare/runner.d.ts
 /** How the "old" side is sourced — booted live or loaded from recorded snapshots, never both. */
 type OldSource = {
-    oldBaseUrl: string;
-    oldSnapshotDir?: never;
+  oldBaseUrl: string;
+  oldSnapshotDir?: never;
 } | {
-    oldSnapshotDir: string;
-    oldBaseUrl?: 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;
+  /** 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;
+  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;
+  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;
@@ -377,12 +393,14 @@ declare const routeSnapshotFile: (route: string) => string;
  * `oldBaseUrl` / `oldSnapshotDir` must be given.
  */
 declare const compareRoutes: (options: CompareRoutesOptions) => Promise<CompareRoutesResult>;
-
+//#endregion
+//#region src/compare/snapshot.d.ts
 /** 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>;
-
+//#endregion
 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 };
+//# sourceMappingURL=index.d.ts.map