@godxjp/ui 16.9.4 → 17.0.0

package/dist/tokens/components/logo.css

@@ -0,0 +1,15 @@
+/* Logo component tokens — the product brand-mark box (a glyph on the primary fill), used in the
+ * app shell header, auth screens, and topbars. Size + radius + per-tier font-size are knobs so a
+ * service theme retunes the mark without forking CSS (rules #44/#45). Colours read the primary
+ * role tokens directly, so a re-themed --primary re-tints the mark automatically. */
+:root {
+  --logo-radius: var(--radius);
+  --logo-size-xs: 1.25rem;
+  --logo-size-sm: 1.5rem;
+  --logo-size-md: 1.75rem;
+  --logo-size-lg: 2.25rem;
+  --logo-font-size-xs: var(--font-size-2xs);
+  --logo-font-size-sm: var(--font-size-xs);
+  --logo-font-size-md: var(--font-size-sm);
+  --logo-font-size-lg: var(--font-size-base);
+}

package/dist/tokens/components/shell.css

@@ -32,4 +32,14 @@
    * Defaults = hsl(var(--accent)) fill · hsl(var(--foreground)) text. */
   --sidebar-item-active-background: initial;
   --sidebar-item-active-foreground: initial;
+
+  /* AuthShell — centred auth/login page shell. Comfortable control density (44px, WCAG touch floor)
+   * + a larger auth heading, scoped to the shell; a service re-tunes the auth card width, insets
+   * and heading size without forking. */
+  --auth-shell-control-height: var(--control-height-comfortable);
+  --auth-shell-heading-size: var(--font-size-2xl);
+  --auth-shell-card-max-width: 24rem;
+  --auth-shell-bar-padding: var(--space-5) var(--space-6);
+  --auth-shell-main-padding: var(--space-6);
+  --auth-shell-footer-padding: var(--space-3) var(--space-6) var(--space-4);
 }

package/dist/tokens/foundation.css

@@ -83,7 +83,8 @@
   --disabled-opacity: 0.5;
 
   /* Shape and elevation */
-  --radius: calc(0.375rem * var(--scaling)); /* 6px base × scaling; override to retheme every step */
+  /* 6px base × scaling; override to retheme every radius step */
+  --radius: calc(0.375rem * var(--scaling));
   --radius-ratio: 1.618; /* φ — radii scale by the golden ratio (steps derive in @theme) */
   --radius-pill: 9999px; /* fully-round: switch / radio / slider / pill badges (NOT --radius-derived) */
   --radius-sharp: 0; /* squared corners: table cells, flush inputs */
@@ -202,7 +203,9 @@
   --font-size-3xl: calc(
     var(--font-size-display) / var(--font-size-display-ratio) / var(--font-size-display-ratio)
   ); /* ≈ 33 → 28px feature heading */
-  --font-size-4xl: calc(var(--font-size-display) / var(--font-size-display-ratio)); /* ≈ 36px section */
+  --font-size-4xl: calc(
+    var(--font-size-display) / var(--font-size-display-ratio)
+  ); /* ≈ 36px section */
   --font-size-5xl: var(--font-size-display); /* 54px hero */
 
   /* Headings — also golden-derived. h1=ratio³, h2=ratio²; h3/h4 reuse body sizes (single source). */
@@ -332,6 +335,9 @@
   --ease-decelerate: cubic-bezier(0, 0, 0, 1);
   --ease-accelerate: cubic-bezier(0.3, 0, 1, 1);
   --reveal-distance: 10px;
+  /* One step of the Reveal stagger ladder — `<Reveal delay={n}>` waits n × this before entering,
+   * so a column of reveals cascades. Read instead of a literal `.04s`/`.09s` per-item delay. */
+  --reveal-stagger-step: 60ms;
 }
 
 .dark,

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "16.9.4",
+  "version": "17.0.0",
+  "godxUiMcp": "16.10.0",
   "type": "module",
   "packageManager": "pnpm@10.29.1",
   "sideEffects": false,
@@ -275,8 +276,9 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "check:example-imports": "node scripts/check-example-imports.mjs",
-    "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm test",
-    "verify:release": "pnpm build && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm check:contrast && pnpm test",
+    "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm test",
+    "verify:release": "pnpm build && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm check:contrast && pnpm check:visual-audit && pnpm test",
+    "check:mcp-lockstep": "node scripts/check-release-lockstep.mjs",
     "check:mcp-sync": "node scripts/check-mcp-sync.mjs",
     "check:mcp-orphans": "node scripts/check-mcp-orphans.mjs",
     "check:mcp-prop-sync": "node scripts/check-mcp-prop-sync.mjs",
@@ -288,6 +290,7 @@
     "gen:component-tokens": "node scripts/gen-component-tokens.mjs",
     "check:mcp-token-sync": "node scripts/gen-component-tokens.mjs --check",
     "check:core-isolation": "node scripts/check-core-isolation.mjs",
+    "check:no-consumer-coupling": "node scripts/check-no-consumer-coupling.mjs",
     "release": "node scripts/release.mjs",
     "preview": "node preview/scripts/kill-port.mjs && vite --config preview/vite.config.ts --port 6008 --strictPort",
     "preview:build": "vite build --config preview/vite.config.ts",
@@ -300,6 +303,7 @@
     "check:audit-sync": "node scripts/check-audit-sync.mjs",
     "check:contrast": "node scripts/check-contrast.mjs",
     "visual-audit": "node scripts/visual-audit.mjs",
+    "check:visual-audit": "node scripts/visual-audit-smoke.mjs",
     "postinstall": "node scripts/postinstall.mjs",
     "init-agent": "node scripts/init-agent-kit.mjs",
     "check:use-client": "node scripts/check-use-client.mjs"

package/scripts/visual-audit.mjs

@@ -12,12 +12,27 @@
  * Playwright + @axe-core/playwright are OPTIONAL peer deps — installed only by apps that
  * run this audit, so the static audit and the library stay browser-free.
  *
+ * TESTED peer range (see TESTED_VERSIONS + README "Runtime visual audit"):
+ *   playwright               >=1.55 <2   (tested 1.61.1)
+ *   @axe-core/playwright     >=4.10 <5   (tested 4.12.1)
+ *   axe-core                 >=4.10 <5   (tested 4.12.1)
+ *
  * Usage (from the consuming app, against its running dev/preview server):
  *   node node_modules/@godxjp/ui/scripts/visual-audit.mjs http://localhost:5173 /invoices /settings
- *   node node_modules/@godxjp/ui/scripts/visual-audit.mjs --format json http://localhost:5173
+ *   node node_modules/@godxjp/ui/scripts/visual-audit.mjs http://localhost:5173 --format json
  *   node node_modules/@godxjp/ui/scripts/visual-audit.mjs --strict http://localhost:5173   # CI gate
  *   PLAYWRIGHT_CHROMIUM_EXECUTABLE=/usr/bin/chromium node …/visual-audit.mjs http://…       # system browser
+ *
+ * JSON contract (--format json ALWAYS emits valid JSON, even on bootstrap failure):
+ *   { status: "ok" | "partial" | "error",
+ *     tool: <TESTED_VERSIONS>,
+ *     summary: { errors, warnings, pages, infrastructureErrors } | null,
+ *     findings: [ … product findings … ],
+ *     errors:   [ … infrastructure errors (bootstrap / navigate / analyze) … ] }
+ *   `status: "ok"` ONLY when every page was audited with zero infrastructure errors —
+ *   so a tool/bootstrap failure can NEVER be misread as "zero violations".
  */
+import { pathToFileURL } from "node:url";
 import {
   VISUAL_RULES,
   isOversaturated,
@@ -27,55 +42,79 @@ import {
   alertControlIssues,
 } from "./visual-audit-rules.mjs";
 
-const args = process.argv.slice(2);
-const asJson = args.includes("--format") && args[args.indexOf("--format") + 1] === "json";
-const strict = args.includes("--strict");
-const listRules = args.includes("--rules");
+/**
+ * Peer versions this audit is tested against. Surfaced in the JSON `tool` field, the
+ * README, and the MCP `list_visual_checks` command so agents pin a compatible range.
+ * Playwright 1.55+ is required for the `browser.newContext()` / `context.newPage()`
+ * flow that @axe-core/playwright 4.10+ expects (older `browser.newPage()` throws
+ * "Please use browser.newContext()").
+ */
+export const TESTED_VERSIONS = {
+  playwright: { range: ">=1.55 <2", tested: "1.61.1" },
+  "@axe-core/playwright": { range: ">=4.10 <5", tested: "4.12.1" },
+  "axe-core": { range: ">=4.10 <5", tested: "4.12.1" },
+};
 
-if (listRules) {
-  process.stdout.write(JSON.stringify(VISUAL_RULES, null, 2) + "\n");
-  process.exit(0);
+/** Shape one product finding from a rule id (pure — unit-tested without a browser). */
+export function buildFinding(ruleId, url, message) {
+  const rule = VISUAL_RULES.find((r) => r.id === ruleId);
+  return {
+    url,
+    rule: ruleId,
+    severity: rule?.severity ?? "warn",
+    standard: rule?.standard,
+    message,
+  };
 }
 
-const C = {
-  red: "\x1b[31m",
-  yellow: "\x1b[33m",
-  dim: "\x1b[2m",
-  bold: "\x1b[1m",
-  reset: "\x1b[0m",
-};
+/**
+ * Assemble the machine-readable result (pure). `findings` are PRODUCT results; `errors`
+ * are INFRASTRUCTURE failures (a page that would not load, axe that would not inject).
+ * `status` is "ok" only when no infra error occurred, "error" when nothing could be
+ * audited, "partial" when some pages ran and some failed.
+ */
+export function buildResult({ findings = [], errors = [], pages = 0 } = {}) {
+  const productErrors = findings.filter((f) => f.severity === "error");
+  const warnings = findings.filter((f) => f.severity === "warn");
+  const failedToLoad = errors.filter((e) => e.stage === "navigate").length;
+  const audited = pages - failedToLoad;
+  const status = errors.length === 0 ? "ok" : audited > 0 ? "partial" : "error";
+  return {
+    status,
+    tool: TESTED_VERSIONS,
+    summary: {
+      errors: productErrors.length,
+      warnings: warnings.length,
+      pages,
+      infrastructureErrors: errors.length,
+    },
+    findings,
+    errors,
+  };
+}
 
-const urls = args.filter((a, i) => !a.startsWith("--") && args[i - 1] !== "--format");
-if (urls.length === 0) {
-  console.error(
-    "usage: visual-audit.mjs [--format json] [--strict] <baseUrl> [route …]\n" +
-      "       (baseUrl is the running app; extra args are routes appended to it)",
-  );
-  process.exit(2);
+/**
+ * Assemble a BOOTSTRAP failure result (pure) — missing peers, no browser, bad args.
+ * `summary` is null (never `{ warnings: 0 }`) so a consumer cannot read a bootstrap
+ * failure as a clean pass.
+ */
+export function buildBootstrapError(message, hint) {
+  return {
+    status: "error",
+    tool: TESTED_VERSIONS,
+    summary: null,
+    findings: [],
+    errors: [{ stage: "bootstrap", message, ...(hint ? { hint } : {}) }],
+  };
 }
-const base = urls[0].replace(/\/$/, "");
-const routes = urls.length > 1 ? urls.slice(1) : ["/"];
-const targets = routes.map((r) =>
-  r.startsWith("http") ? r : `${base}${r.startsWith("/") ? r : `/${r}`}`,
-);
 
-/** Optional-peer loader — print a clear install hint instead of a stack trace. */
-async function loadDeps() {
-  try {
-    const [{ chromium }, axe] = await Promise.all([
-      import("playwright"),
-      import("@axe-core/playwright"),
-    ]);
-    return { chromium, AxeBuilder: axe.default ?? axe.AxeBuilder };
-  } catch {
-    console.error(
-      "visual-audit needs the optional peers `playwright` and `@axe-core/playwright`:\n" +
-        "  pnpm add -D playwright @axe-core/playwright\n" +
-        "  pnpm exec playwright install chromium\n" +
-        "(or set PLAYWRIGHT_CHROMIUM_EXECUTABLE to a system Chromium).",
-    );
-    process.exit(2);
-  }
+/** Exit code for a result: 2 = could not audit, 1 = findings/partial gate, 0 = clean. */
+export function exitCodeFor(result, { strict = false } = {}) {
+  if (result.status === "error") return 2;
+  if (result.status === "partial") return 1;
+  if (strict && result.findings.length > 0) return 1;
+  if (result.summary && result.summary.errors > 0) return 1;
+  return 0;
 }
 
 /** Collect raw measurements from the rendered page; the PURE rules run back in node. */
@@ -160,102 +199,230 @@ function collectInPage() {
 }
 /* c8 ignore stop */
 
-async function run() {
-  const { chromium, AxeBuilder } = await loadDeps();
-  const browser = await chromium.launch({
-    executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE || undefined,
-  });
-  const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
-  const findings = [];
-  const add = (ruleId, url, message) => {
-    const rule = VISUAL_RULES.find((r) => r.id === ruleId);
-    findings.push({
-      url,
-      rule: ruleId,
-      severity: rule?.severity ?? "warn",
-      standard: rule?.standard,
-      message,
-    });
-  };
+/** Optional-peer loader — throws a tagged bootstrap error instead of a raw stack. */
+async function loadDeps() {
+  try {
+    const [{ chromium }, axe] = await Promise.all([
+      import("playwright"),
+      import("@axe-core/playwright"),
+    ]);
+    return { chromium, AxeBuilder: axe.default ?? axe.AxeBuilder };
+  } catch (cause) {
+    const err = new Error(
+      "visual-audit needs the optional peers `playwright` and `@axe-core/playwright`",
+    );
+    err.bootstrap = true;
+    err.hint =
+      "pnpm add -D playwright @axe-core/playwright && pnpm exec playwright install chromium " +
+      "(or set PLAYWRIGHT_CHROMIUM_EXECUTABLE to a system Chromium).";
+    err.cause = cause;
+    throw err;
+  }
+}
 
-  for (const url of targets) {
+/**
+ * Drive the browser over every target and gather findings + infra errors. Cleanup
+ * (page/context/browser) is guaranteed via finally on BOTH success and failure.
+ * A launch failure is re-tagged as a bootstrap error so it surfaces as `status:error`.
+ */
+/* c8 ignore start — the browser-driving glue; exercised by scripts/visual-audit-smoke.mjs in CI. */
+async function audit(targets, { chromium, AxeBuilder }) {
+  const findings = [];
+  const errors = [];
+  let browser;
+  let context;
+  try {
     try {
-      await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
-    } catch (e) {
-      add("axe-violations", url, `could not load page: ${e.message}`);
-      continue;
+      browser = await chromium.launch({
+        executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE || undefined,
+      });
+    } catch (cause) {
+      const err = new Error(`could not launch Chromium: ${cause.message}`);
+      err.bootstrap = true;
+      err.hint =
+        "install a browser: pnpm exec playwright install chromium " +
+        "(or set PLAYWRIGHT_CHROMIUM_EXECUTABLE to a system Chromium).";
+      throw err;
     }
+    context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+    const page = await context.newPage();
 
-    // 1) axe-core — real WCAG/ARIA engine.
-    const { violations } = await new AxeBuilder({ page }).analyze();
-    for (const v of violations) {
-      add(
-        "axe-violations",
-        url,
-        `${v.id} (${v.impact}) — ${v.help} [${v.nodes.length} node(s)] ${v.helpUrl}`,
-      );
-    }
+    for (const url of targets) {
+      try {
+        await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
+      } catch (e) {
+        errors.push({ url, stage: "navigate", message: `could not load page: ${e.message}` });
+        continue;
+      }
 
-    // 2) computed-style / layout heuristics via the PURE rules.
-    const m = await page.evaluate(collectInPage);
-    for (const a of m.accents) {
-      if (isOversaturated(a.rgb))
-        add(
-          "oversaturated-accent",
-          url,
-          `<${a.tag}> background OKLCH chroma ${oklchChroma(a.rgb).toFixed(3)} > 0.18 (rgb ${a.rgb.r},${a.rgb.g},${a.rgb.b})`,
-        );
-    }
-    for (const t of m.targets) {
-      if (isUndersizedTarget(t))
-        add(
-          "target-size-min",
-          url,
-          `target "${t.name || "(unnamed)"}" is ${t.width}×${t.height}px (< 24×24)`,
-        );
-    }
-    if (hasEmoji(m.text)) {
-      const found = (m.text.match(/\p{Extended_Pictographic}/gu) || []).slice(0, 8).join(" ");
-      add("emoji-rendered", url, `emoji rendered in product text: ${found}`);
+      try {
+        // 1) axe-core — real WCAG/ARIA engine.
+        const { violations } = await new AxeBuilder({ page }).analyze();
+        for (const v of violations) {
+          findings.push(
+            buildFinding(
+              "axe-violations",
+              url,
+              `${v.id} (${v.impact}) — ${v.help} [${v.nodes.length} node(s)] ${v.helpUrl}`,
+            ),
+          );
+        }
+
+        // 2) computed-style / layout heuristics via the PURE rules.
+        const m = await page.evaluate(collectInPage);
+        for (const a of m.accents) {
+          if (isOversaturated(a.rgb))
+            findings.push(
+              buildFinding(
+                "oversaturated-accent",
+                url,
+                `<${a.tag}> background OKLCH chroma ${oklchChroma(a.rgb).toFixed(3)} > 0.18 (rgb ${a.rgb.r},${a.rgb.g},${a.rgb.b})`,
+              ),
+            );
+        }
+        for (const t of m.targets) {
+          if (isUndersizedTarget(t))
+            findings.push(
+              buildFinding(
+                "target-size-min",
+                url,
+                `target "${t.name || "(unnamed)"}" is ${t.width}×${t.height}px (< 24×24)`,
+              ),
+            );
+        }
+        if (hasEmoji(m.text)) {
+          const found = (m.text.match(/\p{Extended_Pictographic}/gu) || []).slice(0, 8).join(" ");
+          findings.push(
+            buildFinding("emoji-rendered", url, `emoji rendered in product text: ${found}`),
+          );
+        }
+        m.alerts.forEach((al, i) => {
+          for (const issue of alertControlIssues(al))
+            findings.push(
+              buildFinding("alert-controls-misplaced", url, `banner #${i + 1}: ${issue}`),
+            );
+        });
+      } catch (e) {
+        errors.push({ url, stage: "analyze", message: `audit engine failed: ${e.message}` });
+      }
     }
-    m.alerts.forEach((al, i) => {
-      for (const issue of alertControlIssues(al))
-        add("alert-controls-misplaced", url, `banner #${i + 1}: ${issue}`);
-    });
+  } finally {
+    await context?.close().catch(() => {});
+    await browser?.close().catch(() => {});
   }
 
-  await browser.close();
-  report(findings);
+  return buildResult({ findings, errors, pages: targets.length });
 }
+/* c8 ignore stop */
 
-function report(findings) {
-  const errors = findings.filter((f) => f.severity === "error");
-  const warnings = findings.filter((f) => f.severity === "warn");
+const C = {
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  reset: "\x1b[0m",
+};
+
+/** Render a result to stdout in the requested format, then exit with the right code. */
+/* c8 ignore start — thin process-exit glue, driven by the smoke/CLI paths. */
+function finish(result, { asJson, strict, pages }) {
+  const code = exitCodeFor(result, { strict });
   if (asJson) {
-    process.stdout.write(
-      JSON.stringify(
-        { summary: { errors: errors.length, warnings: warnings.length }, findings },
-        null,
-        2,
-      ) + "\n",
-    );
-  } else {
-    for (const f of findings) {
-      const tag = f.severity === "error" ? `${C.red}error${C.reset}` : `${C.yellow}warn ${C.reset}`;
-      console.log(`${tag} ${C.bold}${f.url}${C.reset}  ${C.dim}[${f.rule}]${C.reset}`);
-      console.log(`      ${f.message}`);
-      if (f.standard) console.log(`      ${C.dim}standard: ${f.standard}${C.reset}`);
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    process.exit(code);
+  }
+
+  // Bootstrap failure — no page was audited.
+  if (result.summary === null) {
+    for (const e of result.errors) {
+      process.stderr.write(`visual-audit failed: ${e.message}\n`);
+      if (e.hint) process.stderr.write(`  ${e.hint}\n`);
     }
+    process.exit(code);
+  }
+
+  for (const f of result.findings) {
+    const tag = f.severity === "error" ? `${C.red}error${C.reset}` : `${C.yellow}warn ${C.reset}`;
+    console.log(`${tag} ${C.bold}${f.url}${C.reset}  ${C.dim}[${f.rule}]${C.reset}`);
+    console.log(`      ${f.message}`);
+    if (f.standard) console.log(`      ${C.dim}standard: ${f.standard}${C.reset}`);
+  }
+  for (const e of result.errors) {
     console.log(
-      `\ngodxjp-ui visual-audit: ${C.red}${errors.length} error(s)${C.reset}, ${C.yellow}${warnings.length} warning(s)${C.reset} across ${targets.length} page(s).`,
+      `${C.red}infra${C.reset} ${C.bold}${e.url ?? "(bootstrap)"}${C.reset}  ${C.dim}[${e.stage}]${C.reset}`,
     );
-    if (findings.length === 0) console.log("✓ No visual/runtime a11y violations found.");
+    console.log(`      ${e.message}`);
   }
-  // Warnings never block; --strict turns any finding into a non-zero exit (CI gate).
-  process.exit(strict && findings.length > 0 ? 1 : errors.length > 0 ? 1 : 0);
+  const { errors, warnings } = result.summary;
+  console.log(
+    `\ngodxjp-ui visual-audit [${result.status}]: ${C.red}${errors} error(s)${C.reset}, ` +
+      `${C.yellow}${warnings} warning(s)${C.reset}` +
+      (result.errors.length ? `, ${C.red}${result.errors.length} infra error(s)${C.reset}` : "") +
+      ` across ${pages} page(s).`,
+  );
+  if (result.status === "ok" && result.findings.length === 0)
+    console.log("✓ No visual/runtime a11y violations found.");
+  process.exit(code);
 }
+/* c8 ignore stop */
+
+/** CLI entry — parse args, run the audit, print, exit. */
+/* c8 ignore start — CLI driver, exercised via subprocess by the smoke test. */
+async function main() {
+  const args = process.argv.slice(2);
+  const fmtIdx = args.indexOf("--format");
+  const asJson = fmtIdx !== -1 && args[fmtIdx + 1] === "json";
+  const strict = args.includes("--strict");
+
+  if (args.includes("--rules")) {
+    process.stdout.write(JSON.stringify(VISUAL_RULES, null, 2) + "\n");
+    process.exit(0);
+  }
+
+  const urls = args.filter((a, i) => !a.startsWith("--") && args[i - 1] !== "--format");
+  if (urls.length === 0) {
+    const msg =
+      "no baseUrl given — usage: visual-audit.mjs [--format json] [--strict] <baseUrl> [route …] " +
+      "(baseUrl is the running app; extra args are routes appended to it)";
+    finish(buildBootstrapError(msg), { asJson, strict, pages: 0 });
+    return;
+  }
 
-run().catch((e) => {
-  console.error(`visual-audit failed: ${e.message}`);
-  process.exit(2);
-});
+  const base = urls[0].replace(/\/$/, "");
+  const routes = urls.length > 1 ? urls.slice(1) : ["/"];
+  const targets = routes.map((r) =>
+    r.startsWith("http") ? r : `${base}${r.startsWith("/") ? r : `/${r}`}`,
+  );
+
+  let deps;
+  try {
+    deps = await loadDeps();
+  } catch (e) {
+    finish(buildBootstrapError(e.message, e.hint), { asJson, strict, pages: targets.length });
+    return;
+  }
+
+  try {
+    const result = await audit(targets, deps);
+    finish(result, { asJson, strict, pages: targets.length });
+  } catch (e) {
+    // A launch/setup failure = infrastructure error (never "zero violations").
+    finish(buildBootstrapError(e.message, e.hint), { asJson, strict, pages: targets.length });
+  }
+}
+/* c8 ignore stop */
+
+// Run only as a CLI — importing this module (for unit tests) must NOT execute.
+/* c8 ignore start */
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((e) => {
+    const asJson =
+      process.argv.indexOf("--format") !== -1 &&
+      process.argv[process.argv.indexOf("--format") + 1] === "json";
+    if (asJson) {
+      process.stdout.write(JSON.stringify(buildBootstrapError(e.message, e.hint)) + "\n");
+    } else console.error(`visual-audit failed: ${e.message}`);
+    process.exit(2);
+  });
+}
+/* c8 ignore stop */