@keboola/validate-ui 0.5.3 → 0.6.0

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,19 @@
 # @keboola/validate-ui
 
+## 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-Dhb1FmeB.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-D5dD5L7c.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":"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"}

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-Dhb1FmeB.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.d.cts

@@ -203,6 +203,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
@@ -293,9 +330,10 @@ declare const runtimeHealthAxis: Axis;
  * 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`.)
+ * alternate brand. Flags layout overflow, blocking at phone widths. 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`.)
  */
 declare const visualBrandAxis: Axis;
 //#endregion
@@ -402,5 +440,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

package/dist/index.d.ts

@@ -203,6 +203,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
@@ -293,9 +330,10 @@ declare const runtimeHealthAxis: Axis;
  * 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`.)
+ * alternate brand. Flags layout overflow, blocking at phone widths. 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`.)
  */
 declare const visualBrandAxis: Axis;
 //#endregion
@@ -402,5 +440,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-D5dD5L7c.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/{runner-CLpaiCIG.js → runner-D5dD5L7c.js}

@@ -140,6 +140,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",
@@ -1056,12 +1115,24 @@ const interactiveContrastFindings = (brand) => checkInteractiveContrast(brand).m
 	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.
+*
+* - On a phone viewport it is `critical`: the reader scrolls sideways to finish a
+*   sentence, so the screen is broken rather than untidy. Blocking is the point — the
+*   phone-first rule is only a rule if a gate can go red on it.
+* - At desktop widths it stays `moderate`, unchanged.
+*/
+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.
@@ -1069,9 +1140,10 @@ const overflowFinding = async (page) => {
 * 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`.)
+* alternate brand. Flags layout overflow, blocking at phone widths. 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`.)
 */
 const visualBrandAxis = {
 	name: "visual-brand",
@@ -1090,7 +1162,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 {
@@ -1303,6 +1375,6 @@ const compareRoutes = async (options) => {
 	}
 };
 //#endregion
-export { prepareForScreenshot as A, accessibilityAxis as C, MOBILE_VIEWPORT as D, DESKTOP_VIEWPORT as E, capture as O, briefConformanceAxis as S, DEFAULT_VIEWPORTS as T, REGION_STATES as _, runAxes as a, comparePass as b, visualBrandAxis as c, captureSnapshot as d, loadSnapshot as f, ExpectedAbsentRule as g, CompareSnapshot as h, aggregatePass as i, capturePage as k, runtimeHealthAxis as l, CompareConfig as m, routeSnapshotFile as n, validate as o, saveSnapshot as p, dedupeSharedChrome as r, ALL_AXES as s, compareRoutes as t, compareAxis as u, Region as v, serveStatic as w, diffSnapshots as x, extractRegions as y };
+export { DEFAULT_VIEWPORTS as A, accessibilityAxis as C, VIEWPORT_PRESETS as D, PHONE_VIEWPORT as E, prepareForScreenshot as F, MOBILE_VIEWPORT as M, capture as N, isPhoneViewport as O, capturePage as P, briefConformanceAxis as S, PHONE_MAX_WIDTH as T, REGION_STATES as _, runAxes as a, comparePass as b, visualBrandAxis as c, captureSnapshot as d, loadSnapshot as f, ExpectedAbsentRule as g, CompareSnapshot as h, aggregatePass as i, DESKTOP_VIEWPORT as j, parseViewport as k, runtimeHealthAxis as l, CompareConfig as m, routeSnapshotFile as n, validate as o, saveSnapshot as p, dedupeSharedChrome as r, ALL_AXES as s, compareRoutes as t, compareAxis as u, Region as v, serveStatic as w, diffSnapshots as x, extractRegions as y };
 
-//# sourceMappingURL=runner-CLpaiCIG.js.map
+//# sourceMappingURL=runner-D5dD5L7c.js.map