@keboola/validate-ui 0.5.3 → 0.6.1

package/AGENTS.md

@@ -8,6 +8,7 @@ rendered result. Reach for it after generating/scaffolding a module, before a PR
 - **Five axes** live one-per-file in `src/axes/` (`runtime-health`, `a11y`, `visual-brand`, `brief-conformance`, `compare`), each implementing the `Axis` contract in `src/types.ts`. Add an axis: implement `{ name, run }`, register it in `src/axes/index.ts`.
 - **Contract boundary:** everything an axis needs is on `AxisContext` (`artifact`, live `page`, `brief`, `baseline`, `captureUnderBrand`, `comparison`, `compareConfig`). Don't reach outside it.
 - **Compare (old-vs-new)** is semantic, not a value multiset — `src/compare/`. Both sides reduce to a serializable `CompareSnapshot` (regions with key/state/values) via `extractRegions`; the pure `diffSnapshots` localizes every delta to a region, suppresses declared `expectedAbsent` deltas (recorded, not dropped), and reports an empty/error `region-degraded` instead of value loss. Multi-route: `validate-ui compare --new <url> (--old <url> | --old-snapshots <dir>) --routes a,b,c [--config f.json]` — `dedupeSharedChrome` collapses a delta seen on ≥2 routes into one finding so shared chrome isn't multiplied. The `compare` axis only activates when `context.comparison` is set, so single-page runs are unaffected.
+- **Viewport is a judgement, not just a size.** `validate({ viewport })` / `--viewport <WIDTHxHEIGHT | desktop | mobile | phone>` renders at that size, and `isPhoneViewport` (< 768px) is what makes horizontal overflow `critical` instead of `moderate`. An axis that cares how narrow the page is reads `context.artifact.viewport` and asks `isPhoneViewport`, never a literal width.
 - **Do not** depend on `@keboola/e2e-testing` (private) — the screenshot-prep helper is reimplemented in `src/prepare-screenshot.ts`.
 - **Want one pass/fail number + a gate exit code**, not raw findings? Use `@keboola/ui-gen-bench` — `ui-gen-bench eval --serve <dir> --route <path> --brief "…"` boots via this validator, scores the verdict, and exits 0/1. That's the per-generation gate; this package is the validator underneath it.
 - **VLM backend** for `brief-conformance` is chosen in `src/axes/vlm-provider.ts`: Keboola LLM proxy (base URL `VALIDATE_UI_LLM_BASE_URL` → `ANTHROPIC_BASE_URL`; token `VALIDATE_UI_LLM_TOKEN` → `KBC_TOKEN` → `ANTHROPIC_API_KEY` — so kai-agent's SDK-native `ANTHROPIC_BASE_URL` + `ANTHROPIC_API_KEY` pair works, preferred) → raw `ANTHROPIC_API_KEY` (no proxy base URL) → skip. Route new VLM calls through `resolveVlmProvider()`, never `new Anthropic()` directly.

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @keboola/validate-ui
 
+## 0.6.1
+
+### Patch Changes
+
+- Runtime health no longer fails a page because an error string such as "something went wrong" appears only inside an inline `<script>`, `<style>`, `<template>`, `<noscript>` or comment. Error-boundary copy is matched against the rendered text, and dev-server overlay names are matched against the DOM with those bodies removed.
+
+- Updated dependencies:
+  - @keboola/brand-registry@1.10.0
+
+## 0.6.0
+
+### Minor Changes
+
+- Horizontal overflow is blocking below 768px wide
+
+  `visual-brand` weighs the finding by the width it was measured at: `critical` on a phone-class
+  viewport, where the reader has to scroll sideways to finish a sentence, and `moderate` as before at
+  desktop widths. Nothing changes for an existing caller — `validate()` still renders at 1280x800
+  unless given a `viewport`.
+
+  `--viewport <WIDTHxHEIGHT | desktop | mobile | phone>` is now on the CLI, and `parseViewport`,
+  `PHONE_VIEWPORT`, `PHONE_MAX_WIDTH`, `VIEWPORT_PRESETS` and `isPhoneViewport` are exported.
+
 ## 0.5.3
 
 ### Patch Changes

package/README.md

@@ -8,8 +8,8 @@ human looks:
 - **runtime-health** — white-screens, console/page errors, failed requests
 - **a11y** — axe-core violations mapped to WCAG
 - **visual-brand** — baseline diff + the alt-brand fitness function (chrome must
-  re-skin under an alternate brand) + layout overflow (asserting categorical
-  colors stay fixed is future work)
+  re-skin under an alternate brand) + layout overflow, blocking below 768px wide
+  (asserting categorical colors stay fixed is future work)
 - **brief-conformance** — a VLM judge on "did it build what the brief asked,
   and are the empty/loading/error states present?"
 
@@ -33,10 +33,19 @@ validate-ui --url http://localhost:5173 --brief "Users list with empty state"
 
 # Serve a built SPA dir and validate a route
 validate-ui --serve apps/boilerplate/dist --route /tokens --json
+
+# Judge the page at a phone size instead of the 1280x800 default
+validate-ui --url http://localhost:5173 --viewport 375x812
 ```
 
 Exit code is `0` when every axis passes, `1` otherwise.
 
+`--viewport` takes `WIDTHxHEIGHT` or one of `desktop` | `mobile` | `phone`.
+Below 768px wide a horizontal layout overflow is a **critical** finding rather
+than a moderate one: the reader has to scroll sideways to finish a sentence, so
+the screen is broken and the verdict fails. Omitting the flag renders at
+1280x800 and is unchanged.
+
 ## Programmatic
 
 ```ts

package/dist/cli.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_runner = require("./runner-CEdpbEON.cjs");
+const require_runner = require("./runner-BwEjSueH.cjs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 let node_process = require("node:process");
@@ -8,8 +8,8 @@ node_process = require_runner.__toESM(node_process, 1);
 const HELP = `@keboola/validate-ui — closed-loop validation for generated Keboola UI
 
 Usage:
-  validate-ui --url <url> [--brief <text>] [--json]
-  validate-ui --serve <dir> [--route <path>] [--brief <text>] [--json]
+  validate-ui --url <url> [--brief <text>] [--viewport <size>] [--json]
+  validate-ui --serve <dir> [--route <path>] [--brief <text>] [--viewport <size>] [--json]
   validate-ui compare --new <baseUrl> (--old <baseUrl> | --old-snapshots <dir>) --routes <a,b,c> [--config <file>] [--json]
 
 Options:
@@ -17,6 +17,8 @@ Options:
   --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)
+  --viewport <size>      WIDTHxHEIGHT, or desktop | mobile | phone (default: desktop).
+                         Horizontal overflow is blocking below 768px wide.
   --json                 Emit the verdict as JSON
   --help, -h             Show this help
 
@@ -114,6 +116,8 @@ const main = async () => {
 	}
 	const brief = flagValue(argv, "--brief");
 	const serveDir = flagValue(argv, "--serve");
+	const viewportSpec = flagValue(argv, "--viewport");
+	const viewport = viewportSpec === void 0 ? void 0 : require_runner.parseViewport(viewportSpec);
 	let url = flagValue(argv, "--url");
 	let server;
 	if (serveDir !== void 0) {
@@ -129,7 +133,8 @@ const main = async () => {
 	try {
 		const verdict = await require_runner.validate({
 			url,
-			brief
+			brief,
+			viewport
 		});
 		node_process.default.stdout.write((asJson ? JSON.stringify(verdict, null, 2) : formatText(verdict)) + "\n");
 		node_process.default.exitCode = verdict.pass ? 0 : 1;

package/dist/cli.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"cli.cjs","names":["CompareConfig","readFile","resolve","compareRoutes","process","serveStatic","validate"],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { readFile } from 'node:fs/promises';\nimport { resolve } from 'node:path';\nimport process from 'node:process';\n\nimport { compareRoutes, type CompareRoutesResult } from './compare/runner';\nimport { CompareConfig } from './compare/types';\nimport { validate } from './aggregate';\nimport { serveStatic } from './serve';\nimport type { AggregateVerdict } from './types';\n\nconst HELP = `@keboola/validate-ui — closed-loop validation for generated Keboola UI\n\nUsage:\n  validate-ui --url <url> [--brief <text>] [--json]\n  validate-ui --serve <dir> [--route <path>] [--brief <text>] [--json]\n  validate-ui compare --new <baseUrl> (--old <baseUrl> | --old-snapshots <dir>) --routes <a,b,c> [--config <file>] [--json]\n\nOptions:\n  --url <url>            Render and validate a running URL\n  --serve <dir>          Serve a built SPA dir (e.g. apps/boilerplate/dist) and validate it\n  --route <path>         Route to open when using --serve (default: /)\n  --brief <text>         The brief the UI was generated from (feeds brief-conformance)\n  --json                 Emit the verdict as JSON\n  --help, -h             Show this help\n\ncompare options:\n  --new <baseUrl>        Base URL of the new build\n  --old <baseUrl>        Base URL of the old build (booted live)\n  --old-snapshots <dir>  Directory of recorded old snapshots (alternative to --old)\n  --routes <a,b,c>       Comma-separated routes to compare\n  --config <file>        JSON compare config (expectedAbsent allowlist + state markers)\n\nExit code is 0 when every axis / route passes, 1 otherwise.\n`;\n\nconst flagValue = (argv: string[], name: string): string | undefined => {\n  const index = argv.indexOf(name);\n  if (index < 0) return undefined;\n  const value = argv[index + 1];\n  // A missing value, or the next token being another flag, means no value was\n  // given (e.g. `--url --json`) — reject it so callers fail fast.\n  return value === undefined || value.startsWith('-') ? undefined : value;\n};\n\nconst formatText = (verdict: AggregateVerdict): string => {\n  const lines = [`validate-ui ${verdict.pass ? 'PASS' : 'FAIL'} — ${verdict.url}`];\n  for (const axis of verdict.verdicts) {\n    lines.push(`  ${axis.pass ? '✓' : '✗'} ${axis.axis}`);\n    for (const finding of axis.findings) {\n      lines.push(`      [${finding.severity}] ${finding.message}`);\n    }\n  }\n  return lines.join('\\n');\n};\n\nconst formatCompareFinding = (finding: CompareRoutesResult['sharedChrome'][number]): string => {\n  const tag = finding.suppressed !== undefined ? ' (suppressed)' : '';\n  const detail = finding.detail !== undefined ? ` — ${finding.detail}` : '';\n  return `      [${finding.severity}] ${finding.message}${detail}${tag}`;\n};\n\nconst formatCompare = (result: CompareRoutesResult): string => {\n  const lines = [`validate-ui compare ${result.pass ? 'PASS' : 'FAIL'}`];\n  if (result.sharedChrome.length > 0) {\n    lines.push('  shared across routes:');\n    for (const finding of result.sharedChrome) lines.push(formatCompareFinding(finding));\n  }\n  for (const route of result.routes) {\n    lines.push(`  ${route.pass ? '✓' : '✗'} ${route.route}`);\n    for (const finding of route.findings) lines.push(formatCompareFinding(finding));\n  }\n  return lines.join('\\n');\n};\n\nconst loadCompareConfig = async (path: string | undefined): Promise<CompareConfig | undefined> => {\n  if (path === undefined) return undefined;\n  return CompareConfig.parse(JSON.parse(await readFile(resolve(path), 'utf8')));\n};\n\nconst runCompare = async (argv: string[], asJson: boolean): Promise<void> => {\n  const newBaseUrl = flagValue(argv, '--new');\n  const oldBaseUrl = flagValue(argv, '--old');\n  const oldSnapshotDir = flagValue(argv, '--old-snapshots');\n  const routes = flagValue(argv, '--routes')\n    ?.split(',')\n    .map((route) => route.trim())\n    .filter((route) => route !== '');\n\n  if (newBaseUrl === undefined || routes === undefined || routes.length === 0) {\n    process.stderr.write('validate-ui compare: --new and --routes are required\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n  if (oldBaseUrl !== undefined && oldSnapshotDir !== undefined) {\n    process.stderr.write(\n      'validate-ui compare: pass only one of --old or --old-snapshots\\n\\n' + HELP,\n    );\n    process.exitCode = 1;\n    return;\n  }\n\n  const config = await loadCompareConfig(flagValue(argv, '--config'));\n  const base = { newBaseUrl, routes, config };\n  // Branch so the XOR-typed options narrow without an assertion.\n  let result: CompareRoutesResult;\n  if (oldBaseUrl !== undefined) {\n    result = await compareRoutes({ ...base, oldBaseUrl });\n  } else if (oldSnapshotDir !== undefined) {\n    result = await compareRoutes({ ...base, oldSnapshotDir });\n  } else {\n    process.stderr.write('validate-ui compare: provide --old or --old-snapshots\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n  process.stdout.write((asJson ? JSON.stringify(result, null, 2) : formatCompare(result)) + '\\n');\n  process.exitCode = result.pass ? 0 : 1;\n};\n\nconst main = async (): Promise<void> => {\n  const argv = process.argv.slice(2);\n  if (argv.includes('--help') || argv.includes('-h') || argv.length === 0) {\n    process.stdout.write(HELP);\n    return;\n  }\n\n  const asJson = argv.includes('--json');\n  if (argv[0] === 'compare') {\n    await runCompare(argv.slice(1), asJson);\n    return;\n  }\n\n  const brief = flagValue(argv, '--brief');\n  const serveDir = flagValue(argv, '--serve');\n\n  let url = flagValue(argv, '--url');\n  let server: Awaited<ReturnType<typeof serveStatic>> | undefined;\n  if (serveDir !== undefined) {\n    server = await serveStatic(resolve(serveDir));\n    const route = flagValue(argv, '--route') ?? '/';\n    url = `${server.url}${route.startsWith('/') ? route : `/${route}`}`;\n  }\n\n  if (url === undefined) {\n    process.stderr.write('validate-ui: one of --url or --serve is required\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n\n  try {\n    const verdict = await validate({ url, brief });\n    process.stdout.write((asJson ? JSON.stringify(verdict, null, 2) : formatText(verdict)) + '\\n');\n    process.exitCode = verdict.pass ? 0 : 1;\n  } finally {\n    await server?.close();\n  }\n};\n\nmain().catch((error: unknown) => {\n  process.stderr.write(`validate-ui: ${error instanceof Error ? error.message : String(error)}\\n`);\n  process.exitCode = 1;\n});\n"],"mappings":"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"}
+{"version":3,"file":"cli.cjs","names":["CompareConfig","readFile","resolve","compareRoutes","process","parseViewport","serveStatic","validate"],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { readFile } from 'node:fs/promises';\nimport { resolve } from 'node:path';\nimport process from 'node:process';\n\nimport { compareRoutes, type CompareRoutesResult } from './compare/runner';\nimport { CompareConfig } from './compare/types';\nimport { validate } from './aggregate';\nimport { serveStatic } from './serve';\nimport type { AggregateVerdict } from './types';\nimport { parseViewport } from './viewport';\n\nconst HELP = `@keboola/validate-ui — closed-loop validation for generated Keboola UI\n\nUsage:\n  validate-ui --url <url> [--brief <text>] [--viewport <size>] [--json]\n  validate-ui --serve <dir> [--route <path>] [--brief <text>] [--viewport <size>] [--json]\n  validate-ui compare --new <baseUrl> (--old <baseUrl> | --old-snapshots <dir>) --routes <a,b,c> [--config <file>] [--json]\n\nOptions:\n  --url <url>            Render and validate a running URL\n  --serve <dir>          Serve a built SPA dir (e.g. apps/boilerplate/dist) and validate it\n  --route <path>         Route to open when using --serve (default: /)\n  --brief <text>         The brief the UI was generated from (feeds brief-conformance)\n  --viewport <size>      WIDTHxHEIGHT, or desktop | mobile | phone (default: desktop).\n                         Horizontal overflow is blocking below 768px wide.\n  --json                 Emit the verdict as JSON\n  --help, -h             Show this help\n\ncompare options:\n  --new <baseUrl>        Base URL of the new build\n  --old <baseUrl>        Base URL of the old build (booted live)\n  --old-snapshots <dir>  Directory of recorded old snapshots (alternative to --old)\n  --routes <a,b,c>       Comma-separated routes to compare\n  --config <file>        JSON compare config (expectedAbsent allowlist + state markers)\n\nExit code is 0 when every axis / route passes, 1 otherwise.\n`;\n\nconst flagValue = (argv: string[], name: string): string | undefined => {\n  const index = argv.indexOf(name);\n  if (index < 0) return undefined;\n  const value = argv[index + 1];\n  // A missing value, or the next token being another flag, means no value was\n  // given (e.g. `--url --json`) — reject it so callers fail fast.\n  return value === undefined || value.startsWith('-') ? undefined : value;\n};\n\nconst formatText = (verdict: AggregateVerdict): string => {\n  const lines = [`validate-ui ${verdict.pass ? 'PASS' : 'FAIL'} — ${verdict.url}`];\n  for (const axis of verdict.verdicts) {\n    lines.push(`  ${axis.pass ? '✓' : '✗'} ${axis.axis}`);\n    for (const finding of axis.findings) {\n      lines.push(`      [${finding.severity}] ${finding.message}`);\n    }\n  }\n  return lines.join('\\n');\n};\n\nconst formatCompareFinding = (finding: CompareRoutesResult['sharedChrome'][number]): string => {\n  const tag = finding.suppressed !== undefined ? ' (suppressed)' : '';\n  const detail = finding.detail !== undefined ? ` — ${finding.detail}` : '';\n  return `      [${finding.severity}] ${finding.message}${detail}${tag}`;\n};\n\nconst formatCompare = (result: CompareRoutesResult): string => {\n  const lines = [`validate-ui compare ${result.pass ? 'PASS' : 'FAIL'}`];\n  if (result.sharedChrome.length > 0) {\n    lines.push('  shared across routes:');\n    for (const finding of result.sharedChrome) lines.push(formatCompareFinding(finding));\n  }\n  for (const route of result.routes) {\n    lines.push(`  ${route.pass ? '✓' : '✗'} ${route.route}`);\n    for (const finding of route.findings) lines.push(formatCompareFinding(finding));\n  }\n  return lines.join('\\n');\n};\n\nconst loadCompareConfig = async (path: string | undefined): Promise<CompareConfig | undefined> => {\n  if (path === undefined) return undefined;\n  return CompareConfig.parse(JSON.parse(await readFile(resolve(path), 'utf8')));\n};\n\nconst runCompare = async (argv: string[], asJson: boolean): Promise<void> => {\n  const newBaseUrl = flagValue(argv, '--new');\n  const oldBaseUrl = flagValue(argv, '--old');\n  const oldSnapshotDir = flagValue(argv, '--old-snapshots');\n  const routes = flagValue(argv, '--routes')\n    ?.split(',')\n    .map((route) => route.trim())\n    .filter((route) => route !== '');\n\n  if (newBaseUrl === undefined || routes === undefined || routes.length === 0) {\n    process.stderr.write('validate-ui compare: --new and --routes are required\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n  if (oldBaseUrl !== undefined && oldSnapshotDir !== undefined) {\n    process.stderr.write(\n      'validate-ui compare: pass only one of --old or --old-snapshots\\n\\n' + HELP,\n    );\n    process.exitCode = 1;\n    return;\n  }\n\n  const config = await loadCompareConfig(flagValue(argv, '--config'));\n  const base = { newBaseUrl, routes, config };\n  // Branch so the XOR-typed options narrow without an assertion.\n  let result: CompareRoutesResult;\n  if (oldBaseUrl !== undefined) {\n    result = await compareRoutes({ ...base, oldBaseUrl });\n  } else if (oldSnapshotDir !== undefined) {\n    result = await compareRoutes({ ...base, oldSnapshotDir });\n  } else {\n    process.stderr.write('validate-ui compare: provide --old or --old-snapshots\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n  process.stdout.write((asJson ? JSON.stringify(result, null, 2) : formatCompare(result)) + '\\n');\n  process.exitCode = result.pass ? 0 : 1;\n};\n\nconst main = async (): Promise<void> => {\n  const argv = process.argv.slice(2);\n  if (argv.includes('--help') || argv.includes('-h') || argv.length === 0) {\n    process.stdout.write(HELP);\n    return;\n  }\n\n  const asJson = argv.includes('--json');\n  if (argv[0] === 'compare') {\n    await runCompare(argv.slice(1), asJson);\n    return;\n  }\n\n  const brief = flagValue(argv, '--brief');\n  const serveDir = flagValue(argv, '--serve');\n  const viewportSpec = flagValue(argv, '--viewport');\n  const viewport = viewportSpec === undefined ? undefined : parseViewport(viewportSpec);\n\n  let url = flagValue(argv, '--url');\n  let server: Awaited<ReturnType<typeof serveStatic>> | undefined;\n  if (serveDir !== undefined) {\n    server = await serveStatic(resolve(serveDir));\n    const route = flagValue(argv, '--route') ?? '/';\n    url = `${server.url}${route.startsWith('/') ? route : `/${route}`}`;\n  }\n\n  if (url === undefined) {\n    process.stderr.write('validate-ui: one of --url or --serve is required\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n\n  try {\n    const verdict = await validate({ url, brief, viewport });\n    process.stdout.write((asJson ? JSON.stringify(verdict, null, 2) : formatText(verdict)) + '\\n');\n    process.exitCode = verdict.pass ? 0 : 1;\n  } finally {\n    await server?.close();\n  }\n};\n\nmain().catch((error: unknown) => {\n  process.stderr.write(`validate-ui: ${error instanceof Error ? error.message : String(error)}\\n`);\n  process.exitCode = 1;\n});\n"],"mappings":"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"}

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { m as CompareConfig, o as validate, t as compareRoutes, w as serveStatic } from "./runner-CLpaiCIG.js";
+import { k as parseViewport, m as CompareConfig, o as validate, t as compareRoutes, w as serveStatic } from "./runner-DH04MitR.js";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import process from "node:process";
@@ -7,8 +7,8 @@ import process from "node:process";
 const HELP = `@keboola/validate-ui — closed-loop validation for generated Keboola UI
 
 Usage:
-  validate-ui --url <url> [--brief <text>] [--json]
-  validate-ui --serve <dir> [--route <path>] [--brief <text>] [--json]
+  validate-ui --url <url> [--brief <text>] [--viewport <size>] [--json]
+  validate-ui --serve <dir> [--route <path>] [--brief <text>] [--viewport <size>] [--json]
   validate-ui compare --new <baseUrl> (--old <baseUrl> | --old-snapshots <dir>) --routes <a,b,c> [--config <file>] [--json]
 
 Options:
@@ -16,6 +16,8 @@ Options:
   --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)
+  --viewport <size>      WIDTHxHEIGHT, or desktop | mobile | phone (default: desktop).
+                         Horizontal overflow is blocking below 768px wide.
   --json                 Emit the verdict as JSON
   --help, -h             Show this help
 
@@ -113,6 +115,8 @@ const main = async () => {
 	}
 	const brief = flagValue(argv, "--brief");
 	const serveDir = flagValue(argv, "--serve");
+	const viewportSpec = flagValue(argv, "--viewport");
+	const viewport = viewportSpec === void 0 ? void 0 : parseViewport(viewportSpec);
 	let url = flagValue(argv, "--url");
 	let server;
 	if (serveDir !== void 0) {
@@ -128,7 +132,8 @@ const main = async () => {
 	try {
 		const verdict = await validate({
 			url,
-			brief
+			brief,
+			viewport
 		});
 		process.stdout.write((asJson ? JSON.stringify(verdict, null, 2) : formatText(verdict)) + "\n");
 		process.exitCode = verdict.pass ? 0 : 1;

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { readFile } from 'node:fs/promises';\nimport { resolve } from 'node:path';\nimport process from 'node:process';\n\nimport { compareRoutes, type CompareRoutesResult } from './compare/runner';\nimport { CompareConfig } from './compare/types';\nimport { validate } from './aggregate';\nimport { serveStatic } from './serve';\nimport type { AggregateVerdict } from './types';\n\nconst HELP = `@keboola/validate-ui — closed-loop validation for generated Keboola UI\n\nUsage:\n  validate-ui --url <url> [--brief <text>] [--json]\n  validate-ui --serve <dir> [--route <path>] [--brief <text>] [--json]\n  validate-ui compare --new <baseUrl> (--old <baseUrl> | --old-snapshots <dir>) --routes <a,b,c> [--config <file>] [--json]\n\nOptions:\n  --url <url>            Render and validate a running URL\n  --serve <dir>          Serve a built SPA dir (e.g. apps/boilerplate/dist) and validate it\n  --route <path>         Route to open when using --serve (default: /)\n  --brief <text>         The brief the UI was generated from (feeds brief-conformance)\n  --json                 Emit the verdict as JSON\n  --help, -h             Show this help\n\ncompare options:\n  --new <baseUrl>        Base URL of the new build\n  --old <baseUrl>        Base URL of the old build (booted live)\n  --old-snapshots <dir>  Directory of recorded old snapshots (alternative to --old)\n  --routes <a,b,c>       Comma-separated routes to compare\n  --config <file>        JSON compare config (expectedAbsent allowlist + state markers)\n\nExit code is 0 when every axis / route passes, 1 otherwise.\n`;\n\nconst flagValue = (argv: string[], name: string): string | undefined => {\n  const index = argv.indexOf(name);\n  if (index < 0) return undefined;\n  const value = argv[index + 1];\n  // A missing value, or the next token being another flag, means no value was\n  // given (e.g. `--url --json`) — reject it so callers fail fast.\n  return value === undefined || value.startsWith('-') ? undefined : value;\n};\n\nconst formatText = (verdict: AggregateVerdict): string => {\n  const lines = [`validate-ui ${verdict.pass ? 'PASS' : 'FAIL'} — ${verdict.url}`];\n  for (const axis of verdict.verdicts) {\n    lines.push(`  ${axis.pass ? '✓' : '✗'} ${axis.axis}`);\n    for (const finding of axis.findings) {\n      lines.push(`      [${finding.severity}] ${finding.message}`);\n    }\n  }\n  return lines.join('\\n');\n};\n\nconst formatCompareFinding = (finding: CompareRoutesResult['sharedChrome'][number]): string => {\n  const tag = finding.suppressed !== undefined ? ' (suppressed)' : '';\n  const detail = finding.detail !== undefined ? ` — ${finding.detail}` : '';\n  return `      [${finding.severity}] ${finding.message}${detail}${tag}`;\n};\n\nconst formatCompare = (result: CompareRoutesResult): string => {\n  const lines = [`validate-ui compare ${result.pass ? 'PASS' : 'FAIL'}`];\n  if (result.sharedChrome.length > 0) {\n    lines.push('  shared across routes:');\n    for (const finding of result.sharedChrome) lines.push(formatCompareFinding(finding));\n  }\n  for (const route of result.routes) {\n    lines.push(`  ${route.pass ? '✓' : '✗'} ${route.route}`);\n    for (const finding of route.findings) lines.push(formatCompareFinding(finding));\n  }\n  return lines.join('\\n');\n};\n\nconst loadCompareConfig = async (path: string | undefined): Promise<CompareConfig | undefined> => {\n  if (path === undefined) return undefined;\n  return CompareConfig.parse(JSON.parse(await readFile(resolve(path), 'utf8')));\n};\n\nconst runCompare = async (argv: string[], asJson: boolean): Promise<void> => {\n  const newBaseUrl = flagValue(argv, '--new');\n  const oldBaseUrl = flagValue(argv, '--old');\n  const oldSnapshotDir = flagValue(argv, '--old-snapshots');\n  const routes = flagValue(argv, '--routes')\n    ?.split(',')\n    .map((route) => route.trim())\n    .filter((route) => route !== '');\n\n  if (newBaseUrl === undefined || routes === undefined || routes.length === 0) {\n    process.stderr.write('validate-ui compare: --new and --routes are required\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n  if (oldBaseUrl !== undefined && oldSnapshotDir !== undefined) {\n    process.stderr.write(\n      'validate-ui compare: pass only one of --old or --old-snapshots\\n\\n' + HELP,\n    );\n    process.exitCode = 1;\n    return;\n  }\n\n  const config = await loadCompareConfig(flagValue(argv, '--config'));\n  const base = { newBaseUrl, routes, config };\n  // Branch so the XOR-typed options narrow without an assertion.\n  let result: CompareRoutesResult;\n  if (oldBaseUrl !== undefined) {\n    result = await compareRoutes({ ...base, oldBaseUrl });\n  } else if (oldSnapshotDir !== undefined) {\n    result = await compareRoutes({ ...base, oldSnapshotDir });\n  } else {\n    process.stderr.write('validate-ui compare: provide --old or --old-snapshots\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n  process.stdout.write((asJson ? JSON.stringify(result, null, 2) : formatCompare(result)) + '\\n');\n  process.exitCode = result.pass ? 0 : 1;\n};\n\nconst main = async (): Promise<void> => {\n  const argv = process.argv.slice(2);\n  if (argv.includes('--help') || argv.includes('-h') || argv.length === 0) {\n    process.stdout.write(HELP);\n    return;\n  }\n\n  const asJson = argv.includes('--json');\n  if (argv[0] === 'compare') {\n    await runCompare(argv.slice(1), asJson);\n    return;\n  }\n\n  const brief = flagValue(argv, '--brief');\n  const serveDir = flagValue(argv, '--serve');\n\n  let url = flagValue(argv, '--url');\n  let server: Awaited<ReturnType<typeof serveStatic>> | undefined;\n  if (serveDir !== undefined) {\n    server = await serveStatic(resolve(serveDir));\n    const route = flagValue(argv, '--route') ?? '/';\n    url = `${server.url}${route.startsWith('/') ? route : `/${route}`}`;\n  }\n\n  if (url === undefined) {\n    process.stderr.write('validate-ui: one of --url or --serve is required\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n\n  try {\n    const verdict = await validate({ url, brief });\n    process.stdout.write((asJson ? JSON.stringify(verdict, null, 2) : formatText(verdict)) + '\\n');\n    process.exitCode = verdict.pass ? 0 : 1;\n  } finally {\n    await server?.close();\n  }\n};\n\nmain().catch((error: unknown) => {\n  process.stderr.write(`validate-ui: ${error instanceof Error ? error.message : String(error)}\\n`);\n  process.exitCode = 1;\n});\n"],"mappings":"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"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { readFile } from 'node:fs/promises';\nimport { resolve } from 'node:path';\nimport process from 'node:process';\n\nimport { compareRoutes, type CompareRoutesResult } from './compare/runner';\nimport { CompareConfig } from './compare/types';\nimport { validate } from './aggregate';\nimport { serveStatic } from './serve';\nimport type { AggregateVerdict } from './types';\nimport { parseViewport } from './viewport';\n\nconst HELP = `@keboola/validate-ui — closed-loop validation for generated Keboola UI\n\nUsage:\n  validate-ui --url <url> [--brief <text>] [--viewport <size>] [--json]\n  validate-ui --serve <dir> [--route <path>] [--brief <text>] [--viewport <size>] [--json]\n  validate-ui compare --new <baseUrl> (--old <baseUrl> | --old-snapshots <dir>) --routes <a,b,c> [--config <file>] [--json]\n\nOptions:\n  --url <url>            Render and validate a running URL\n  --serve <dir>          Serve a built SPA dir (e.g. apps/boilerplate/dist) and validate it\n  --route <path>         Route to open when using --serve (default: /)\n  --brief <text>         The brief the UI was generated from (feeds brief-conformance)\n  --viewport <size>      WIDTHxHEIGHT, or desktop | mobile | phone (default: desktop).\n                         Horizontal overflow is blocking below 768px wide.\n  --json                 Emit the verdict as JSON\n  --help, -h             Show this help\n\ncompare options:\n  --new <baseUrl>        Base URL of the new build\n  --old <baseUrl>        Base URL of the old build (booted live)\n  --old-snapshots <dir>  Directory of recorded old snapshots (alternative to --old)\n  --routes <a,b,c>       Comma-separated routes to compare\n  --config <file>        JSON compare config (expectedAbsent allowlist + state markers)\n\nExit code is 0 when every axis / route passes, 1 otherwise.\n`;\n\nconst flagValue = (argv: string[], name: string): string | undefined => {\n  const index = argv.indexOf(name);\n  if (index < 0) return undefined;\n  const value = argv[index + 1];\n  // A missing value, or the next token being another flag, means no value was\n  // given (e.g. `--url --json`) — reject it so callers fail fast.\n  return value === undefined || value.startsWith('-') ? undefined : value;\n};\n\nconst formatText = (verdict: AggregateVerdict): string => {\n  const lines = [`validate-ui ${verdict.pass ? 'PASS' : 'FAIL'} — ${verdict.url}`];\n  for (const axis of verdict.verdicts) {\n    lines.push(`  ${axis.pass ? '✓' : '✗'} ${axis.axis}`);\n    for (const finding of axis.findings) {\n      lines.push(`      [${finding.severity}] ${finding.message}`);\n    }\n  }\n  return lines.join('\\n');\n};\n\nconst formatCompareFinding = (finding: CompareRoutesResult['sharedChrome'][number]): string => {\n  const tag = finding.suppressed !== undefined ? ' (suppressed)' : '';\n  const detail = finding.detail !== undefined ? ` — ${finding.detail}` : '';\n  return `      [${finding.severity}] ${finding.message}${detail}${tag}`;\n};\n\nconst formatCompare = (result: CompareRoutesResult): string => {\n  const lines = [`validate-ui compare ${result.pass ? 'PASS' : 'FAIL'}`];\n  if (result.sharedChrome.length > 0) {\n    lines.push('  shared across routes:');\n    for (const finding of result.sharedChrome) lines.push(formatCompareFinding(finding));\n  }\n  for (const route of result.routes) {\n    lines.push(`  ${route.pass ? '✓' : '✗'} ${route.route}`);\n    for (const finding of route.findings) lines.push(formatCompareFinding(finding));\n  }\n  return lines.join('\\n');\n};\n\nconst loadCompareConfig = async (path: string | undefined): Promise<CompareConfig | undefined> => {\n  if (path === undefined) return undefined;\n  return CompareConfig.parse(JSON.parse(await readFile(resolve(path), 'utf8')));\n};\n\nconst runCompare = async (argv: string[], asJson: boolean): Promise<void> => {\n  const newBaseUrl = flagValue(argv, '--new');\n  const oldBaseUrl = flagValue(argv, '--old');\n  const oldSnapshotDir = flagValue(argv, '--old-snapshots');\n  const routes = flagValue(argv, '--routes')\n    ?.split(',')\n    .map((route) => route.trim())\n    .filter((route) => route !== '');\n\n  if (newBaseUrl === undefined || routes === undefined || routes.length === 0) {\n    process.stderr.write('validate-ui compare: --new and --routes are required\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n  if (oldBaseUrl !== undefined && oldSnapshotDir !== undefined) {\n    process.stderr.write(\n      'validate-ui compare: pass only one of --old or --old-snapshots\\n\\n' + HELP,\n    );\n    process.exitCode = 1;\n    return;\n  }\n\n  const config = await loadCompareConfig(flagValue(argv, '--config'));\n  const base = { newBaseUrl, routes, config };\n  // Branch so the XOR-typed options narrow without an assertion.\n  let result: CompareRoutesResult;\n  if (oldBaseUrl !== undefined) {\n    result = await compareRoutes({ ...base, oldBaseUrl });\n  } else if (oldSnapshotDir !== undefined) {\n    result = await compareRoutes({ ...base, oldSnapshotDir });\n  } else {\n    process.stderr.write('validate-ui compare: provide --old or --old-snapshots\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n  process.stdout.write((asJson ? JSON.stringify(result, null, 2) : formatCompare(result)) + '\\n');\n  process.exitCode = result.pass ? 0 : 1;\n};\n\nconst main = async (): Promise<void> => {\n  const argv = process.argv.slice(2);\n  if (argv.includes('--help') || argv.includes('-h') || argv.length === 0) {\n    process.stdout.write(HELP);\n    return;\n  }\n\n  const asJson = argv.includes('--json');\n  if (argv[0] === 'compare') {\n    await runCompare(argv.slice(1), asJson);\n    return;\n  }\n\n  const brief = flagValue(argv, '--brief');\n  const serveDir = flagValue(argv, '--serve');\n  const viewportSpec = flagValue(argv, '--viewport');\n  const viewport = viewportSpec === undefined ? undefined : parseViewport(viewportSpec);\n\n  let url = flagValue(argv, '--url');\n  let server: Awaited<ReturnType<typeof serveStatic>> | undefined;\n  if (serveDir !== undefined) {\n    server = await serveStatic(resolve(serveDir));\n    const route = flagValue(argv, '--route') ?? '/';\n    url = `${server.url}${route.startsWith('/') ? route : `/${route}`}`;\n  }\n\n  if (url === undefined) {\n    process.stderr.write('validate-ui: one of --url or --serve is required\\n\\n' + HELP);\n    process.exitCode = 1;\n    return;\n  }\n\n  try {\n    const verdict = await validate({ url, brief, viewport });\n    process.stdout.write((asJson ? JSON.stringify(verdict, null, 2) : formatText(verdict)) + '\\n');\n    process.exitCode = verdict.pass ? 0 : 1;\n  } finally {\n    await server?.close();\n  }\n};\n\nmain().catch((error: unknown) => {\n  process.stderr.write(`validate-ui: ${error instanceof Error ? error.message : String(error)}\\n`);\n  process.exitCode = 1;\n});\n"],"mappings":";;;;;;AAYA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;AA2Bb,MAAM,aAAa,MAAgB,SAAqC;CACtE,MAAM,QAAQ,KAAK,QAAQ,IAAI;CAC/B,IAAI,QAAQ,GAAG,OAAO,KAAA;CACtB,MAAM,QAAQ,KAAK,QAAQ;CAG3B,OAAO,UAAU,KAAA,KAAa,MAAM,WAAW,GAAG,IAAI,KAAA,IAAY;AACpE;AAEA,MAAM,cAAc,YAAsC;CACxD,MAAM,QAAQ,CAAC,eAAe,QAAQ,OAAO,SAAS,OAAO,KAAK,QAAQ,KAAK;CAC/E,KAAK,MAAM,QAAQ,QAAQ,UAAU;EACnC,MAAM,KAAK,KAAK,KAAK,OAAO,MAAM,IAAI,GAAG,KAAK,MAAM;EACpD,KAAK,MAAM,WAAW,KAAK,UACzB,MAAM,KAAK,UAAU,QAAQ,SAAS,IAAI,QAAQ,SAAS;CAE/D;CACA,OAAO,MAAM,KAAK,IAAI;AACxB;AAEA,MAAM,wBAAwB,YAAiE;CAC7F,MAAM,MAAM,QAAQ,eAAe,KAAA,IAAY,kBAAkB;CACjE,MAAM,SAAS,QAAQ,WAAW,KAAA,IAAY,MAAM,QAAQ,WAAW;CACvE,OAAO,UAAU,QAAQ,SAAS,IAAI,QAAQ,UAAU,SAAS;AACnE;AAEA,MAAM,iBAAiB,WAAwC;CAC7D,MAAM,QAAQ,CAAC,uBAAuB,OAAO,OAAO,SAAS,QAAQ;CACrE,IAAI,OAAO,aAAa,SAAS,GAAG;EAClC,MAAM,KAAK,yBAAyB;EACpC,KAAK,MAAM,WAAW,OAAO,cAAc,MAAM,KAAK,qBAAqB,OAAO,CAAC;CACrF;CACA,KAAK,MAAM,SAAS,OAAO,QAAQ;EACjC,MAAM,KAAK,KAAK,MAAM,OAAO,MAAM,IAAI,GAAG,MAAM,OAAO;EACvD,KAAK,MAAM,WAAW,MAAM,UAAU,MAAM,KAAK,qBAAqB,OAAO,CAAC;CAChF;CACA,OAAO,MAAM,KAAK,IAAI;AACxB;AAEA,MAAM,oBAAoB,OAAO,SAAiE;CAChG,IAAI,SAAS,KAAA,GAAW,OAAO,KAAA;CAC/B,OAAO,cAAc,MAAM,KAAK,MAAM,MAAM,SAAS,QAAQ,IAAI,GAAG,MAAM,CAAC,CAAC;AAC9E;AAEA,MAAM,aAAa,OAAO,MAAgB,WAAmC;CAC3E,MAAM,aAAa,UAAU,MAAM,OAAO;CAC1C,MAAM,aAAa,UAAU,MAAM,OAAO;CAC1C,MAAM,iBAAiB,UAAU,MAAM,iBAAiB;CACxD,MAAM,SAAS,UAAU,MAAM,UAAU,CAAC,EACtC,MAAM,GAAG,CAAC,CACX,KAAK,UAAU,MAAM,KAAK,CAAC,CAAC,CAC5B,QAAQ,UAAU,UAAU,EAAE;CAEjC,IAAI,eAAe,KAAA,KAAa,WAAW,KAAA,KAAa,OAAO,WAAW,GAAG;EAC3E,QAAQ,OAAO,MAAM,6DAA6D,IAAI;EACtF,QAAQ,WAAW;EACnB;CACF;CACA,IAAI,eAAe,KAAA,KAAa,mBAAmB,KAAA,GAAW;EAC5D,QAAQ,OAAO,MACb,uEAAuE,IACzE;EACA,QAAQ,WAAW;EACnB;CACF;CAGA,MAAM,OAAO;EAAE;EAAY;EAAQ,QAAA,MADd,kBAAkB,UAAU,MAAM,UAAU,CAAC;CACxB;CAE1C,IAAI;CACJ,IAAI,eAAe,KAAA,GACjB,SAAS,MAAM,cAAc;EAAE,GAAG;EAAM;CAAW,CAAC;MAC/C,IAAI,mBAAmB,KAAA,GAC5B,SAAS,MAAM,cAAc;EAAE,GAAG;EAAM;CAAe,CAAC;MACnD;EACL,QAAQ,OAAO,MAAM,8DAA8D,IAAI;EACvF,QAAQ,WAAW;EACnB;CACF;CACA,QAAQ,OAAO,OAAO,SAAS,KAAK,UAAU,QAAQ,MAAM,CAAC,IAAI,cAAc,MAAM,KAAK,IAAI;CAC9F,QAAQ,WAAW,OAAO,OAAO,IAAI;AACvC;AAEA,MAAM,OAAO,YAA2B;CACtC,MAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;CACjC,IAAI,KAAK,SAAS,QAAQ,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,WAAW,GAAG;EACvE,QAAQ,OAAO,MAAM,IAAI;EACzB;CACF;CAEA,MAAM,SAAS,KAAK,SAAS,QAAQ;CACrC,IAAI,KAAK,OAAO,WAAW;EACzB,MAAM,WAAW,KAAK,MAAM,CAAC,GAAG,MAAM;EACtC;CACF;CAEA,MAAM,QAAQ,UAAU,MAAM,SAAS;CACvC,MAAM,WAAW,UAAU,MAAM,SAAS;CAC1C,MAAM,eAAe,UAAU,MAAM,YAAY;CACjD,MAAM,WAAW,iBAAiB,KAAA,IAAY,KAAA,IAAY,cAAc,YAAY;CAEpF,IAAI,MAAM,UAAU,MAAM,OAAO;CACjC,IAAI;CACJ,IAAI,aAAa,KAAA,GAAW;EAC1B,SAAS,MAAM,YAAY,QAAQ,QAAQ,CAAC;EAC5C,MAAM,QAAQ,UAAU,MAAM,SAAS,KAAK;EAC5C,MAAM,GAAG,OAAO,MAAM,MAAM,WAAW,GAAG,IAAI,QAAQ,IAAI;CAC5D;CAEA,IAAI,QAAQ,KAAA,GAAW;EACrB,QAAQ,OAAO,MAAM,yDAAyD,IAAI;EAClF,QAAQ,WAAW;EACnB;CACF;CAEA,IAAI;EACF,MAAM,UAAU,MAAM,SAAS;GAAE;GAAK;GAAO;EAAS,CAAC;EACvD,QAAQ,OAAO,OAAO,SAAS,KAAK,UAAU,SAAS,MAAM,CAAC,IAAI,WAAW,OAAO,KAAK,IAAI;EAC7F,QAAQ,WAAW,QAAQ,OAAO,IAAI;CACxC,UAAU;EACR,MAAM,QAAQ,MAAM;CACtB;AACF;AAEA,KAAK,CAAC,CAAC,OAAO,UAAmB;CAC/B,QAAQ,OAAO,MAAM,gBAAgB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE,GAAG;CAC/F,QAAQ,WAAW;AACrB,CAAC"}

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_runner = require("./runner-CEdpbEON.cjs");
+const require_runner = require("./runner-BwEjSueH.cjs");
 //#region src/types.ts
 const SEVERITIES = [
 	"critical",
@@ -15,9 +15,12 @@ exports.DEFAULT_VIEWPORTS = require_runner.DEFAULT_VIEWPORTS;
 exports.DESKTOP_VIEWPORT = require_runner.DESKTOP_VIEWPORT;
 exports.ExpectedAbsentRule = require_runner.ExpectedAbsentRule;
 exports.MOBILE_VIEWPORT = require_runner.MOBILE_VIEWPORT;
+exports.PHONE_MAX_WIDTH = require_runner.PHONE_MAX_WIDTH;
+exports.PHONE_VIEWPORT = require_runner.PHONE_VIEWPORT;
 exports.REGION_STATES = require_runner.REGION_STATES;
 exports.Region = require_runner.Region;
 exports.SEVERITIES = SEVERITIES;
+exports.VIEWPORT_PRESETS = require_runner.VIEWPORT_PRESETS;
 exports.accessibilityAxis = require_runner.accessibilityAxis;
 exports.aggregatePass = require_runner.aggregatePass;
 exports.briefConformanceAxis = require_runner.briefConformanceAxis;
@@ -30,7 +33,9 @@ exports.compareRoutes = require_runner.compareRoutes;
 exports.dedupeSharedChrome = require_runner.dedupeSharedChrome;
 exports.diffSnapshots = require_runner.diffSnapshots;
 exports.extractRegions = require_runner.extractRegions;
+exports.isPhoneViewport = require_runner.isPhoneViewport;
 exports.loadSnapshot = require_runner.loadSnapshot;
+exports.parseViewport = require_runner.parseViewport;
 exports.prepareForScreenshot = require_runner.prepareForScreenshot;
 exports.routeSnapshotFile = require_runner.routeSnapshotFile;
 exports.runAxes = require_runner.runAxes;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","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.cjs","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/index.d.cts

@@ -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.cts.map