@keboola/validate-ui 0.5.3 → 0.6.1

package/dist/index.d.ts

@@ -79,13 +79,12 @@ declare const CompareConfig: z.ZodObject<{
 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;
 };
-/** A single console / page-error message emitted while the page loaded. */
+/** A console or page-error message emitted while the page loaded. */
 type ConsoleEntry = {
   type: string;
   text: string;
@@ -100,22 +99,18 @@ type NetworkEntry = {
   failure?: string;
 };
 /**
- * Ground truth captured from a rendered page — the input every verdict axis
- * reasons over. Produced by {@link capture}; never contains live browser handles
- * so it is safe to serialize and pass to a VLM.
+ * Ground truth every verdict axis reasons over, produced by {@link capture}.
+ *
+ * - Holds no live browser handles, so it is safe to serialize and pass to a VLM.
  */
 type CaptureArtifact = {
   url: string;
   viewport: Viewport;
-  /** Full-page PNG bytes. */
+  /** Full-page PNG. */
   screenshot: Uint8Array;
-  /** Serialized outer HTML of the document after load. */
+  /** Outer HTML 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.
-   */
+  /** Trimmed `body.innerText`; empty is a reliable white-screen signal. Absent without a live page. */
   renderedText?: string;
   console: ConsoleEntry[];
   network: NetworkEntry[];
@@ -126,9 +121,9 @@ type Severity = (typeof SEVERITIES)[number];
 type Finding = {
   message: string;
   severity: Severity;
-  /** Optional extra context — a stack, a WCAG id, a selector, a diff ratio. */
+  /** Extra context — a stack, a WCAG id, a selector, a diff ratio. */
   detail?: string;
-  /** Optional pointer — WCAG ref, DOM selector, request URL, etc. */
+  /** Pointer — WCAG ref, DOM selector, request URL. */
   ref?: string;
 };
 /** The result of running one axis against one page. */
@@ -144,36 +139,30 @@ type AggregateVerdict = {
   verdicts: Verdict[];
 };
 /**
- * Everything an axis may need. Different axes use different fields — a11y and
- * visual axes need the live {@link Page}; brief-conformance needs the brief;
- * the visual axis re-renders under an alternate brand via
- * {@link AxisContext.captureUnderBrand}. All optional fields may be absent, and
- * an axis must degrade to a clear finding rather than throw when its input is
- * missing.
+ * Everything an axis may need.
+ *
+ * - Any optional field may be absent; an axis then reports a clear finding instead of throwing.
  */
 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. */
+  /** Shared browser for rendering additional pages. */
   browser?: Browser;
-  /** The natural-language brief the UI was generated from. */
+  /** Natural-language brief the UI was generated from. */
   brief?: string;
-  /** A prior screenshot to diff the current one against. */
+  /** Prior screenshot to diff against. */
   baseline?: Uint8Array;
-  /** Re-render the same route under a different brand id and capture it. */
+  /** Re-render and capture the same route under another brand id. */
   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,
- * 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.
+ * A verdict axis.
+ *
+ * - `run` should not throw on missing input; the aggregator turns a throw into a failing verdict.
  */
 type Axis = {
   name: string;
@@ -203,6 +192,43 @@ type CaptureOptions = {
  */
 declare const capture: (url: string, options?: CaptureOptions) => Promise<CaptureArtifact[]>;
 //#endregion
+//#region src/viewport.d.ts
+/**
+ * The phone-first baseline every Keboola screen is designed against.
+ *
+ * - 375×812 is the narrowest width still in meaningful use; a layout that survives it
+ *   survives every wider phone.
+ * - Distinct from {@link MOBILE_VIEWPORT} (390×844), which is one of `capture`'s two
+ *   default capture sizes rather than a bar anything is held to.
+ */
+declare const PHONE_VIEWPORT: Viewport;
+/** Names `--viewport` accepts in place of a `WIDTHxHEIGHT` pair. */
+declare const VIEWPORT_PRESETS: Readonly<Record<string, Viewport>>;
+/**
+ * Widths below this count as a phone.
+ *
+ * - 768 is the tablet breakpoint: at or above it a page has room for a desktop-shaped
+ *   layout, below it the content has one column to live in.
+ * - Drives severity, not layout — see {@link isPhoneViewport}.
+ */
+declare const PHONE_MAX_WIDTH = 768;
+/**
+ * Whether a viewport is phone-class.
+ *
+ * - Horizontal overflow here is a broken page, not a cosmetic slip: the reader has to
+ *   scroll sideways to read a sentence. Axes weigh findings accordingly.
+ */
+declare const isPhoneViewport: (viewport: Viewport) => boolean;
+/**
+ * Read a `--viewport` value: a preset name, or `WIDTHxHEIGHT` in CSS pixels.
+ *
+ * - Throws on anything else rather than falling back to a default — a typo'd size would
+ *   otherwise silently evaluate the viewport the caller was trying to move off.
+ * - Zero in either dimension is rejected for the same reason; playwright accepts it and
+ *   renders nothing.
+ */
+declare const parseViewport: (spec: string) => Viewport;
+//#endregion
 //#region src/prepare-screenshot.d.ts
 /**
  * Settle the page before a screenshot: freeze animations first (so parking the
@@ -265,14 +291,10 @@ declare const briefConformanceAxis: Axis;
 //#endregion
 //#region src/axes/compare.d.ts
 /**
- * A5 · Semantic old-vs-new compare verdict — UT-4572.
+ * A5 · Semantic old-vs-new compare verdict.
  *
- * 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.
+ * - Passing skip unless `context.comparison` (an "old" {@link CompareSnapshot}) is supplied.
+ * - Diffs it against a snapshot of the live `context.page` via {@link diffSnapshots}.
  */
 declare const compareAxis: Axis;
 //#endregion
@@ -288,14 +310,10 @@ declare const runtimeHealthAxis: Axis;
 //#endregion
 //#region src/axes/visual-brand.d.ts
 /**
- * A4 · Visual & brand-correctness verdict — UT-4495.
+ * A4 · Visual & brand-correctness verdict.
  *
- * 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`.)
+ * - Baseline pixel diff; alt brand must visibly re-skin the chrome; layout overflow.
+ * - Each check yields no finding when its input is absent.
  */
 declare const visualBrandAxis: Axis;
 //#endregion
@@ -343,14 +361,10 @@ 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);
- * 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.
+ * Reduce the live page to its diffable regions, in the browser.
+ *
+ * - Regions never overlap, so no value is counted twice.
+ * - Must stay symmetric across old and new so the two sides diff cleanly.
  */
 declare const extractRegions: (page: Page, config?: CompareConfig) => Promise<Region[]>;
 //#endregion
@@ -402,5 +416,5 @@ declare const saveSnapshot: (snapshot: CompareSnapshot, path: string) => Promise
 /** 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 };
+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, PHONE_MAX_WIDTH, PHONE_VIEWPORT, REGION_STATES, Region, type RegionState, type RouteCompareResult, type RouteFindings, SEVERITIES, type Severity, type StaticServer, VIEWPORT_PRESETS, type ValidateOptions, type Verdict, type Viewport, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, captureSnapshot, compareAxis, comparePass, compareRoutes, dedupeSharedChrome, diffSnapshots, extractRegions, isPhoneViewport, loadSnapshot, parseViewport, prepareForScreenshot, routeSnapshotFile, runAxes, runtimeHealthAxis, saveSnapshot, serveStatic, validate, visualBrandAxis };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as prepareForScreenshot, C as accessibilityAxis, D as MOBILE_VIEWPORT, E as DESKTOP_VIEWPORT, O as capture, S as briefConformanceAxis, T as DEFAULT_VIEWPORTS, _ as REGION_STATES, a as runAxes, b as comparePass, c as visualBrandAxis, d as captureSnapshot, f as loadSnapshot, g as ExpectedAbsentRule, h as CompareSnapshot, i as aggregatePass, k as capturePage, l as runtimeHealthAxis, m as CompareConfig, n as routeSnapshotFile, o as validate, p as saveSnapshot, r as dedupeSharedChrome, s as ALL_AXES, t as compareRoutes, u as compareAxis, v as Region, w as serveStatic, x as diffSnapshots, y as extractRegions } from "./runner-CLpaiCIG.js";
+import { A as DEFAULT_VIEWPORTS, C as accessibilityAxis, D as VIEWPORT_PRESETS, E as PHONE_VIEWPORT, F as prepareForScreenshot, M as MOBILE_VIEWPORT, N as capture, O as isPhoneViewport, P as capturePage, S as briefConformanceAxis, T as PHONE_MAX_WIDTH, _ as REGION_STATES, a as runAxes, b as comparePass, c as visualBrandAxis, d as captureSnapshot, f as loadSnapshot, g as ExpectedAbsentRule, h as CompareSnapshot, i as aggregatePass, j as DESKTOP_VIEWPORT, k as parseViewport, l as runtimeHealthAxis, m as CompareConfig, n as routeSnapshotFile, o as validate, p as saveSnapshot, r as dedupeSharedChrome, s as ALL_AXES, t as compareRoutes, u as compareAxis, v as Region, w as serveStatic, x as diffSnapshots, y as extractRegions } from "./runner-DH04MitR.js";
 //#region src/types.ts
 const SEVERITIES = [
 	"critical",
@@ -7,6 +7,6 @@ const SEVERITIES = [
 	"minor"
 ];
 //#endregion
-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 };
+export { ALL_AXES, CompareConfig, CompareSnapshot, DEFAULT_VIEWPORTS, DESKTOP_VIEWPORT, ExpectedAbsentRule, MOBILE_VIEWPORT, PHONE_MAX_WIDTH, PHONE_VIEWPORT, REGION_STATES, Region, SEVERITIES, VIEWPORT_PRESETS, accessibilityAxis, aggregatePass, briefConformanceAxis, capture, capturePage, captureSnapshot, compareAxis, comparePass, compareRoutes, dedupeSharedChrome, diffSnapshots, extractRegions, isPhoneViewport, loadSnapshot, parseViewport, prepareForScreenshot, routeSnapshotFile, runAxes, runtimeHealthAxis, saveSnapshot, serveStatic, validate, visualBrandAxis };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["import type { Browser, Page } from 'playwright';\n\nimport type { CompareConfig, CompareSnapshot } from './compare/types';\n\n/** A named viewport the harness renders and captures at. */\nexport type Viewport = {\n  label: string;\n  width: number;\n  height: number;\n};\n\n/** A single console / page-error message emitted while the page loaded. */\nexport type ConsoleEntry = {\n  type: string;\n  text: string;\n  location?: string;\n};\n\n/** A network response or failed request observed during load. */\nexport type NetworkEntry = {\n  url: string;\n  method: string;\n  /** HTTP status, or 0 for a request that failed before a response. */\n  status: number;\n  failure?: string;\n};\n\n/**\n * Ground truth captured from a rendered page — the input every verdict axis\n * reasons over. Produced by {@link capture}; never contains live browser handles\n * so it is safe to serialize and pass to a VLM.\n */\nexport type CaptureArtifact = {\n  url: string;\n  viewport: Viewport;\n  /** Full-page PNG bytes. */\n  screenshot: Uint8Array;\n  /** Serialized outer HTML of the document after load. */\n  dom: string;\n  /**\n   * Trimmed `body.innerText` read from the live DOM when available. An empty\n   * string is a reliable white-screen signal — more robust than parsing\n   * {@link dom}. Absent only when an artifact is built without a live page.\n   */\n  renderedText?: string;\n  console: ConsoleEntry[];\n  network: NetworkEntry[];\n};\n\nexport const SEVERITIES = ['critical', 'serious', 'moderate', 'minor'] as const;\nexport type Severity = (typeof SEVERITIES)[number];\n\n/** One problem an axis found. */\nexport type Finding = {\n  message: string;\n  severity: Severity;\n  /** Optional extra context — a stack, a WCAG id, a selector, a diff ratio. */\n  detail?: string;\n  /** Optional pointer — WCAG ref, DOM selector, request URL, etc. */\n  ref?: string;\n};\n\n/** The result of running one axis against one page. */\nexport type Verdict = {\n  axis: string;\n  pass: boolean;\n  findings: Finding[];\n};\n\n/** The combined result of running every axis against one page. */\nexport type AggregateVerdict = {\n  url: string;\n  pass: boolean;\n  verdicts: Verdict[];\n};\n\n/**\n * Everything an axis may need. Different axes use different fields — a11y and\n * visual axes need the live {@link Page}; brief-conformance needs the brief;\n * the visual axis re-renders under an alternate brand via\n * {@link AxisContext.captureUnderBrand}. All optional fields may be absent, and\n * an axis must degrade to a clear finding rather than throw when its input is\n * missing.\n */\nexport type AxisContext = {\n  artifact: CaptureArtifact;\n  /** Live page for the primary capture, when the run keeps a browser open. */\n  page?: Page;\n  /** Shared browser, for axes that need to render additional pages. */\n  browser?: Browser;\n  /** The natural-language brief the UI was generated from. */\n  brief?: string;\n  /** A prior screenshot to diff the current one against. */\n  baseline?: Uint8Array;\n  /** Re-render the same route under a different brand id and capture it. */\n  captureUnderBrand?: (brand: string) => Promise<CaptureArtifact>;\n  /** The \"old\" UI reduced to regions — enables the compare axis when present. */\n  comparison?: CompareSnapshot;\n  /** Allowlist + state markers for the compare axis. */\n  compareConfig?: CompareConfig;\n};\n\n/**\n * A verdict axis. Each of the axes (runtime-health, accessibility,\n * visual-brand, brief-conformance, compare) implements this contract in its own\n * file so they can be built independently. `run` must resolve to a {@link Verdict} and\n * should not throw for expected-missing input — the aggregator converts a throw\n * into a failing verdict, but a clear finding is better.\n */\nexport type Axis = {\n  name: string;\n  run: (context: AxisContext) => Promise<Verdict>;\n};\n"],"mappings":";;AAiDA,MAAa,aAAa;CAAC;CAAY;CAAW;CAAY;AAAO"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["import type { Browser, Page } from 'playwright';\n\nimport type { CompareConfig, CompareSnapshot } from './compare/types';\n\nexport type Viewport = {\n  label: string;\n  width: number;\n  height: number;\n};\n\n/** A console or page-error message emitted while the page loaded. */\nexport type ConsoleEntry = {\n  type: string;\n  text: string;\n  location?: string;\n};\n\n/** A network response or failed request observed during load. */\nexport type NetworkEntry = {\n  url: string;\n  method: string;\n  /** HTTP status, or 0 for a request that failed before a response. */\n  status: number;\n  failure?: string;\n};\n\n/**\n * Ground truth every verdict axis reasons over, produced by {@link capture}.\n *\n * - Holds no live browser handles, so it is safe to serialize and pass to a VLM.\n */\nexport type CaptureArtifact = {\n  url: string;\n  viewport: Viewport;\n  /** Full-page PNG. */\n  screenshot: Uint8Array;\n  /** Outer HTML after load. */\n  dom: string;\n  /** Trimmed `body.innerText`; empty is a reliable white-screen signal. Absent without a live page. */\n  renderedText?: string;\n  console: ConsoleEntry[];\n  network: NetworkEntry[];\n};\n\nexport const SEVERITIES = ['critical', 'serious', 'moderate', 'minor'] as const;\nexport type Severity = (typeof SEVERITIES)[number];\n\n/** One problem an axis found. */\nexport type Finding = {\n  message: string;\n  severity: Severity;\n  /** Extra context — a stack, a WCAG id, a selector, a diff ratio. */\n  detail?: string;\n  /** Pointer — WCAG ref, DOM selector, request URL. */\n  ref?: string;\n};\n\n/** The result of running one axis against one page. */\nexport type Verdict = {\n  axis: string;\n  pass: boolean;\n  findings: Finding[];\n};\n\n/** The combined result of running every axis against one page. */\nexport type AggregateVerdict = {\n  url: string;\n  pass: boolean;\n  verdicts: Verdict[];\n};\n\n/**\n * Everything an axis may need.\n *\n * - Any optional field may be absent; an axis then reports a clear finding instead of throwing.\n */\nexport type AxisContext = {\n  artifact: CaptureArtifact;\n  /** Live page for the primary capture, when the run keeps a browser open. */\n  page?: Page;\n  /** Shared browser for rendering additional pages. */\n  browser?: Browser;\n  /** Natural-language brief the UI was generated from. */\n  brief?: string;\n  /** Prior screenshot to diff against. */\n  baseline?: Uint8Array;\n  /** Re-render and capture the same route under another brand id. */\n  captureUnderBrand?: (brand: string) => Promise<CaptureArtifact>;\n  /** The \"old\" UI reduced to regions — enables the compare axis when present. */\n  comparison?: CompareSnapshot;\n  compareConfig?: CompareConfig;\n};\n\n/**\n * A verdict axis.\n *\n * - `run` should not throw on missing input; the aggregator turns a throw into a failing verdict.\n */\nexport type Axis = {\n  name: string;\n  run: (context: AxisContext) => Promise<Verdict>;\n};\n"],"mappings":";;AA4CA,MAAa,aAAa;CAAC;CAAY;CAAW;CAAY;AAAO"}

package/dist/{runner-CEdpbEON.cjs → runner-BwEjSueH.cjs}

@@ -165,6 +165,65 @@ const capture = async (url, options = {}) => {
 	}
 };
 //#endregion
+//#region src/viewport.ts
+/**
+* The phone-first baseline every Keboola screen is designed against.
+*
+* - 375×812 is the narrowest width still in meaningful use; a layout that survives it
+*   survives every wider phone.
+* - Distinct from {@link MOBILE_VIEWPORT} (390×844), which is one of `capture`'s two
+*   default capture sizes rather than a bar anything is held to.
+*/
+const PHONE_VIEWPORT = {
+	label: "phone",
+	width: 375,
+	height: 812
+};
+/** Names `--viewport` accepts in place of a `WIDTHxHEIGHT` pair. */
+const VIEWPORT_PRESETS = {
+	desktop: DESKTOP_VIEWPORT,
+	mobile: MOBILE_VIEWPORT,
+	phone: PHONE_VIEWPORT
+};
+/**
+* Widths below this count as a phone.
+*
+* - 768 is the tablet breakpoint: at or above it a page has room for a desktop-shaped
+*   layout, below it the content has one column to live in.
+* - Drives severity, not layout — see {@link isPhoneViewport}.
+*/
+const PHONE_MAX_WIDTH = 768;
+/**
+* Whether a viewport is phone-class.
+*
+* - Horizontal overflow here is a broken page, not a cosmetic slip: the reader has to
+*   scroll sideways to read a sentence. Axes weigh findings accordingly.
+*/
+const isPhoneViewport = (viewport) => viewport.width < 768;
+const DIMENSIONS = /^(\d+)x(\d+)$/;
+/**
+* Read a `--viewport` value: a preset name, or `WIDTHxHEIGHT` in CSS pixels.
+*
+* - Throws on anything else rather than falling back to a default — a typo'd size would
+*   otherwise silently evaluate the viewport the caller was trying to move off.
+* - Zero in either dimension is rejected for the same reason; playwright accepts it and
+*   renders nothing.
+*/
+const parseViewport = (spec) => {
+	const trimmed = spec.trim();
+	const preset = VIEWPORT_PRESETS[trimmed.toLowerCase()];
+	if (preset !== void 0) return preset;
+	const match = DIMENSIONS.exec(trimmed);
+	const width = Number(match?.[1]);
+	const height = Number(match?.[2]);
+	if (match === null || width === 0 || height === 0) throw new Error(`--viewport must be WIDTHxHEIGHT (e.g. 375x812) or one of ${Object.keys(VIEWPORT_PRESETS).join(", ")}, got "${spec}"`);
+	return {
+		label: `${width}x${height}`,
+		width,
+		height
+	};
+};
+//#endregion
 //#region src/serve.ts
 const CONTENT_TYPES = {
 	".html": "text/html; charset=utf-8",
@@ -241,27 +300,15 @@ const serveStatic = async (rootDir) => {
 /**
 * 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.
+* - Not reported: `text-overflow: ellipsis`, scrollable boxes (`overflow: auto | scroll`).
+* - Reported: `overflow: hidden | clip` without ellipsis, and `<input>`s wider than their box.
+* - A `<textarea>` scrolls, so it is judged like any other box.
 */
-/** Ignore sub-pixel and rounding noise — real clipping is wider than a stray pixel. */
+/** Absorbs sub-pixel and rounding noise. */
 const CLIP_TOLERANCE_PX = 2;
-/** Cap the reported list so one systematically broken component can't flood the report. */
+/** Keeps one broken component from flooding 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.
-*/
+/** Runs in the page: serialised, so no imports or outer-scope references. */
 /* c8 ignore start -- executes in the browser, not under node coverage */
 const findClippedElements = ({ tolerance, max }) => {
 	const describe = (el) => {
@@ -309,16 +356,12 @@ const findClippedElements = ({ tolerance, max }) => {
 	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.
-*/
+/** Report every element whose content is silently cut off; `[]` when the page can't be inspected. */
 const clippedTextFindings = async (page) => {
 	try {
 		return (await page.evaluate(findClippedElements, {
@@ -389,7 +432,6 @@ const accessibilityAxis = {
 };
 //#endregion
 //#region src/axes/vlm-provider.ts
-/** Concatenate a message's text blocks. */
 const textFromMessage = (message) => message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
 const makeProvider = (backend, clientOptions) => {
 	const client = new _anthropic_ai_sdk.default(clientOptions);
@@ -420,25 +462,12 @@ const makeProvider = (backend, clientOptions) => {
 };
 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.
+* Pick a VLM backend from the environment; `undefined` makes the axis skip.
 *
-* 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.
+* 1. Keboola LLM proxy (`baseURL` + Keboola token as `apiKey`), as kai-agent's
+*    `entrypoint-builder.ts` does — the team plan has no raw key.
+* 2. Otherwise a bare `ANTHROPIC_API_KEY` selects raw Anthropic.
+* - Reads only the injected `env`, never ambient `process.env`.
 */
 const resolveVlmProvider = (env = process.env) => {
 	const baseUrl = env.VALIDATE_UI_LLM_BASE_URL ?? env.ANTHROPIC_BASE_URL;
@@ -676,14 +705,10 @@ const DEFAULT_ERROR_MARKERS = [
 	"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.
+* Reduce the live page to its diffable regions, in the browser.
+*
+* - Regions never overlap, so no value is counted twice.
+* - Must stay symmetric across old and new so the two sides diff cleanly.
 */
 const extractRegions = async (page, config = {}) => {
 	const emptyMarkers = [...DEFAULT_EMPTY_MARKERS, ...config.emptyStateMarkers ?? []];
@@ -856,14 +881,10 @@ const skip = (message) => ({
 	}]
 });
 /**
-* A5 · Semantic old-vs-new compare verdict — UT-4572.
+* A5 · Semantic old-vs-new compare verdict.
 *
-* 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.
+* - Passing skip unless `context.comparison` (an "old" {@link CompareSnapshot}) is supplied.
+* - Diffs it against a snapshot of the live `context.page` via {@link diffSnapshots}.
 */
 const compareAxis = {
 	name: "compare",
@@ -882,12 +903,18 @@ const compareAxis = {
 };
 //#endregion
 //#region src/axes/runtime-health.ts
-const ERROR_MARKERS = [
-	"something went wrong",
+const OVERLAY_MARKERS = [
 	"vite-error-overlay",
 	"vite-plugin-checker-error-overlay",
 	"react-error-overlay"
 ];
+const ERROR_TEXT_MARKERS = ["something went wrong"];
+/**
+* The serialized DOM minus content that is never rendered as page content —
+* `<script>`, `<style>`, `<template>`, `<noscript>` bodies and comments — so a
+* marker named inside them is not mistaken for a rendered overlay.
+*/
+const stripNonRendered = (dom) => dom.replace(/<!--[\s\S]*?-->/g, "").replace(/<(script|style|template|noscript)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, "");
 const pageErrorFindings = (console) => console.filter((entry) => entry.type === "pageerror").map((entry) => ({
 	message: `Uncaught page error: ${entry.text}`,
 	severity: "critical",
@@ -956,10 +983,17 @@ const networkFindings = (network) => {
 	}
 	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));
+/**
+* An error overlay in the DOM, or error-boundary copy in the rendered text,
+* means a crashed render rather than real content. Overlays are matched on the
+* DOM with script/style bodies removed; error copy on `renderedText` (the live
+* `innerText`, which also skips hidden elements), falling back to the stripped
+* DOM only when an artifact has no live text.
+*/
+const errorMarkerFinding = (dom, renderedText) => {
+	const markup = stripNonRendered(dom).toLowerCase();
+	const visible = (renderedText ?? markup).toLowerCase();
+	const marker = OVERLAY_MARKERS.find((m) => markup.includes(m)) ?? ERROR_TEXT_MARKERS.find((m) => visible.includes(m));
 	return marker === void 0 ? null : {
 		message: "Error boundary / error overlay rendered instead of the app",
 		severity: "critical",
@@ -990,7 +1024,7 @@ const runtimeHealthAxis = {
 			...consoleErrorFindings(artifact.console),
 			...networkFindings(artifact.network)
 		];
-		const errorMarker = errorMarkerFinding(artifact.dom);
+		const errorMarker = errorMarkerFinding(artifact.dom, artifact.renderedText);
 		if (errorMarker !== null) findings.push(errorMarker);
 		const whiteScreen = whiteScreenFinding(artifact.renderedText);
 		if (whiteScreen !== null) findings.push(whiteScreen);
@@ -1010,7 +1044,7 @@ 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). */
+/** Pixel mismatch ratio of two PNGs (0 = identical, 1 = every pixel differs). */
 const pngMismatchRatio = (a, b, pixelThreshold = DRIFT_PIXEL_THRESHOLD) => {
 	const imgA = pngjs.PNG.sync.read(Buffer.from(a));
 	const imgB = pngjs.PNG.sync.read(Buffer.from(b));
@@ -1044,16 +1078,9 @@ const baselineFinding = (screenshot, baseline) => {
 /**
 * 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.
+* - Most apps ignore `?brand=<id>`: brand is build configuration, not a runtime switch.
+* - `@keboola/design`'s ThemeProvider writes `data-brand`; its absence means "not assessed",
+*   not "did not re-skin".
 */
 const altBrandWasApplied = (altDom, brand) => altDom.includes(`data-brand="${brand}"`);
 const altBrandFinding = (screenshot, altScreenshot, brand, altDom) => {
@@ -1071,32 +1098,37 @@ const altBrandFinding = (screenshot, altScreenshot, brand, altDom) => {
 	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.
+* Non-fatal `moderate` findings for a brand's interactive pairings below WCAG-AA.
+*
+* - Surfaces `@keboola/brand-registry`'s check before axe would hit it at runtime.
 */
 const interactiveContrastFindings = (brand) => (0, _keboola_brand_registry.checkInteractiveContrast)(brand).map((warning) => ({
 	message: `brand '${brand.id}' ${warning.message}`,
 	severity: "moderate",
 	detail: `${warning.foreground} on ${warning.background} (${warning.palette})`
 }));
-const overflowFinding = async (page) => {
-	if (await page.evaluate(() => document.documentElement.scrollWidth > document.documentElement.clientWidth)) return {
+/**
+* Horizontal overflow, weighed by the width it was measured at.
+*
+* - Phone viewport: `critical` — blocking is what makes phone-first a rule.
+* - Desktop: `moderate`.
+*/
+const overflowFinding = async (page, viewport) => {
+	if (!await page.evaluate(() => document.documentElement.scrollWidth > document.documentElement.clientWidth)) return null;
+	return isPhoneViewport(viewport) ? {
+		message: `horizontal layout overflow at ${viewport.width}px`,
+		severity: "critical",
+		detail: "The page scrolls sideways on a phone — lay it out in one column instead."
+	} : {
 		message: "horizontal layout overflow",
 		severity: "moderate"
 	};
-	return null;
 };
 /**
-* A4 · Visual & brand-correctness verdict — UT-4495.
+* A4 · Visual & brand-correctness verdict.
 *
-* 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`.)
+* - Baseline pixel diff; alt brand must visibly re-skin the chrome; layout overflow.
+* - Each check yields no finding when its input is absent.
 */
 const visualBrandAxis = {
 	name: "visual-brand",
@@ -1115,7 +1147,7 @@ const visualBrandAxis = {
 			if (altBrand !== void 0) findings.push(...interactiveContrastFindings(altBrand));
 		}
 		if (page !== void 0) {
-			const finding = await overflowFinding(page);
+			const finding = await overflowFinding(page, artifact.viewport);
 			if (finding !== null) findings.push(finding);
 		}
 		return {
@@ -1370,6 +1402,18 @@ Object.defineProperty(exports, "MOBILE_VIEWPORT", {
 		return MOBILE_VIEWPORT;
 	}
 });
+Object.defineProperty(exports, "PHONE_MAX_WIDTH", {
+	enumerable: true,
+	get: function() {
+		return PHONE_MAX_WIDTH;
+	}
+});
+Object.defineProperty(exports, "PHONE_VIEWPORT", {
+	enumerable: true,
+	get: function() {
+		return PHONE_VIEWPORT;
+	}
+});
 Object.defineProperty(exports, "REGION_STATES", {
 	enumerable: true,
 	get: function() {
@@ -1382,6 +1426,12 @@ Object.defineProperty(exports, "Region", {
 		return Region;
 	}
 });
+Object.defineProperty(exports, "VIEWPORT_PRESETS", {
+	enumerable: true,
+	get: function() {
+		return VIEWPORT_PRESETS;
+	}
+});
 Object.defineProperty(exports, "__toESM", {
 	enumerable: true,
 	get: function() {
@@ -1460,12 +1510,24 @@ Object.defineProperty(exports, "extractRegions", {
 		return extractRegions;
 	}
 });
+Object.defineProperty(exports, "isPhoneViewport", {
+	enumerable: true,
+	get: function() {
+		return isPhoneViewport;
+	}
+});
 Object.defineProperty(exports, "loadSnapshot", {
 	enumerable: true,
 	get: function() {
 		return loadSnapshot;
 	}
 });
+Object.defineProperty(exports, "parseViewport", {
+	enumerable: true,
+	get: function() {
+		return parseViewport;
+	}
+});
 Object.defineProperty(exports, "prepareForScreenshot", {
 	enumerable: true,
 	get: function() {
@@ -1515,4 +1577,4 @@ Object.defineProperty(exports, "visualBrandAxis", {
 	}
 });
 
-//# sourceMappingURL=runner-CEdpbEON.cjs.map
+//# sourceMappingURL=runner-BwEjSueH.cjs.map