@kerfjs/ui 5.0.0-beta.18 → 5.0.0-beta.22

package/docs/sunken-panel.md

@@ -0,0 +1,43 @@
+# SunkenPanel
+
+`SunkenPanel` is a visually lowered application surface with one compact inset
+and a vertical content stack. Use it for a main work area or nested panel whose
+background should sit behind ordinary content, such as the primary stage in an
+issue tracker or component catalog.
+
+```tsx
+import { SunkenPanel } from '@kerfjs/ui/sunken-panel';
+
+<SunkenPanel ariaLabel="Release workspace">
+  <ReleaseSummary />
+  <ReleaseChecks />
+</SunkenPanel>;
+```
+
+## Ownership
+
+The root owns its lowered background, 8px padding, and 8px vertical gap.
+Children own their borders and internal geometry. The application owns child
+order, responsive placement, and scrolling; `SunkenPanel` deliberately does not
+create another scroll container.
+
+Use `ariaLabel` only when the surface is a distinct region people need to find
+by name. With a label, the root receives `role="region"`; without one it remains
+a non-landmark grouping.
+
+Do not use `SunkenPanel` merely to add padding, as a substitute for pane
+header/content/footer anatomy, or around a child that already owns the same
+outer surface.
+
+## Public styling boundary
+
+Override the public properties at the composition boundary:
+
+- `--kui-sunken-panel-background`
+- `--kui-sunken-panel-foreground`
+- `--kui-sunken-panel-padding`
+- `--kui-sunken-panel-gap`
+- `--kui-sunken-panel-radius`
+
+The public root class is `.kui-sunken-panel`. Prefer the properties above over
+styling descendants.

package/docs/type-contracts.md

@@ -0,0 +1,99 @@
+# Compile-time contracts
+
+Kerf UI rejects invalid integrations at compile time only when TypeScript can
+prove the relationship from one call. The versioned
+[`compile-time-contracts-v1.json`](../ai/compile-time-contracts-v1.json)
+artifact names those guarantees with stable `KUI-T###` ids. Its source fixture
+is compiled twice: against `src/` and against declarations extracted from the
+actual `npm pack` tarball. `npm run check:catalog` also verifies that every
+contract still points to a real catalog entry/import and a symbol in the emitted
+public-signature artifact.
+
+## Strengthened contracts
+
+| ID         | Compile-time guarantee                                                                                                                                                                 |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KUI-T001` | `ListHeader` is a passive heading, a fully named/icon-bearing trailing action, or a controlled disclosure with `action` + `expanded`. Props ignored by the selected mode are rejected. |
+| `KUI-T002` | `Select` has a visible `label` or an `ariaLabel`.                                                                                                                                      |
+| `KUI-T003` | A literal `Select.value` belongs to its literal `choices`.                                                                                                                             |
+| `KUI-T004` | A literal `SegmentedControl.value` belongs to its literal `choices`.                                                                                                                   |
+| `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `TokenSearchField({ collapsible: true })`.                                                                                 |
+| `KUI-T006` | `TokenSearchEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                    |
+| `KUI-T007` | `PanelHeader.summaryId` cannot exist without rendered `summary` content.                                                                                                               |
+| `KUI-T008` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                              |
+| `KUI-T009` | A literal `TabScaffold.active` id belongs to its literal `tabs`.                                                                                                                       |
+| `KUI-T010` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                      |
+| `KUI-T011` | Finite public variants have named exported union types, including tab activation, banner urgency, and all ToolbarControlGroup presentation axes.                                       |
+
+Literal identity inference is intentionally additive for dynamic applications.
+When choices or ids arrive at runtime and the state signal is correctly typed as
+`string`, widen the component explicitly:
+
+```tsx
+<Select<string> value={loadedValue.value} choices={loadedChoices.value} ... />
+<SegmentedControl<string> value={mode.value} choices={loadedModes.value} ... />
+<TabScaffold<string> active={active.value} tabs={loadedTabs.value} ... />
+```
+
+The widening is an honest statement that TypeScript cannot know the runtime
+dataset. Do not cast a known literal typo merely to bypass the relationship.
+
+## Complete public-surface audit
+
+The following existing contracts were already exact and remain covered by the
+ordinary source/type gates:
+
+- required identity or accessible-name inputs on `AppTab`, `FloatingToolbar`,
+  `NavStack`, `SplitView`, `Workbench`, `TabBar`, `ResizableRegion`,
+  `SegmentedControl`, `TokenSearchField`, `PanelHeader`, and `ValueTable`;
+- finite variants exported or represented as literal props on `DisclosureArrow`,
+  `FloatingToolbar`, `Pane`, `ResizableRegion`, `SegmentedControl`, `StateBanner`,
+  `ToolbarText`, `CollapsiblePanel`, `Catalog`, and the wire helpers;
+- required controlled-state callbacks on `wireResizableRegions`, `wireTabBars`,
+  and `wireTabScaffold`;
+- mutually exclusive count/badge metadata on `ListHeader`; and
+- protected application metadata boundaries on `AppTab`, `ListItem`,
+  `ListActionRow`, `ListHeader`, `Pane`, `CatalogExample`, and
+  `CatalogExampleStack`.
+
+The remaining components (`LucideIcon`, `DisclosureArrow`, `Toolbar`,
+`ToolbarControlGroup`, `ListInsetControl`, `ListInsetText`, `LoadingSpinner`,
+`Skeleton`, `SunkenPanel`, `EmptyState`, `StateBanner`, `ValueTableRow`, and the
+pure helpers) have independent props with no further conditional invalid state
+that TypeScript can truthfully remove. Optional labels on decorative icons and
+unnamed non-landmark surfaces are intentional variants, not missing contracts.
+
+## Boundaries TypeScript cannot prove
+
+Types do not claim to validate:
+
+- the contents of `SafeHtml` slots (for example, “only AppTab children” or “no
+  interactive descendants”);
+- nonempty arrays, unique ids, numeric min/max ordering, or a controlled value
+  loaded from dynamic data;
+- equality between ids rendered in separate calls, elements discovered later in
+  the DOM, or an ARIA relationship's live target;
+- that a caller retained and invoked a wiring disposer; or
+- CSS class/token use inside arbitrary strings.
+
+Those remain catalog `KUI-C###` diagnostics, runtime filtering/guards, lint or
+browser assertions. Encoding them as permissive-looking TypeScript brands would
+move errors into casts without making the integration safer.
+
+## Migration from the earlier declarations
+
+- Add `actionLabel` and `actionIcon` to a non-toggle `ListHeader` action. For a
+  disclosure, set literal `toggle: true`, provide `action` and controlled
+  `expanded`, and remove trailing-action-only props.
+- Give every `Select` either `label` or `ariaLabel`. Use an explicit `<string>`
+  generic only for genuinely dynamic choice data.
+- Put `expanded`/expand-action props behind `collapsible: true`.
+- Replace `wireTokenSearchFields({ keyboard: true })` with either
+  `{ keyboard: { onRemoveToken } }` or
+  `{ keyboard: { removeAdjacentToken: false } }` when only caret navigation is
+  wanted.
+- Remove orphaned `summaryId`, or render the matching `summary`; add
+  `wrap: true` anywhere `ToolbarText.maxLines` is used.
+
+JavaScript runtime behavior remains defensive for previously emitted calls, but
+new TypeScript builds report these invalid or ignored combinations.

package/docs/ui-analyzer.md

@@ -0,0 +1,81 @@
+# Static CSS and layout ownership analyzer
+
+`kerf-ui-analyze` checks integration facts that TypeScript and an individual
+ESLint file cannot see across component markup, stylesheets, the component
+catalog, and the application UI profile.
+
+```sh
+npx kerf-ui-analyze --root . --format text src
+npx kerf-ui-analyze --root . --format json --output artifacts/kerf-ui.json
+npx kerf-ui-analyze --root . --format sarif --output artifacts/kerf-ui.sarif
+```
+
+The analyzer is opt-in. Add a project script such as
+`"check:kerf-ui-layout": "kerf-ui-analyze --root . src"`; it never executes
+application code. It discovers `.kerf-ui-profile.json`, joins every declared
+composition catalog by `package:id`, parses literal TSX/JSX class usage and CSS,
+and reports portable repository-relative locations.
+
+Analysis is scoped per source file. Each TSX/JSX file resolves package,
+workspace, and parent-to-child directory profiles from its own location, then
+follows its relative CSS imports (including nested CSS `@import`s). Stylesheet
+facts are never pooled across unrelated files or sibling packages, and a shared
+stylesheet's diagnostics are evaluated against every importing source profile.
+A violation stays active when any consumer has not narrowly excepted it;
+duplicate source findings collapse to one result. Directly targeted or orphaned
+CSS uses its own directory profile. A direct changed-file target still brings
+its reachable project-local styles into the report, including quoted or
+unquoted `url()` imports; external package styles remain outside the consumer
+boundary.
+
+## Diagnostics and exit behavior
+
+| Rule       | Kind   | Meaning                                                           |
+| ---------- | ------ | ----------------------------------------------------------------- |
+| `KUI-L001` | error  | A stylesheet reaches into a private or unknown `.kui-*` selector. |
+| `KUI-L002` | error  | A stylesheet references an unknown or private `--kui-*` token.    |
+| `KUI-L003` | error  | One element combines public classes that claim the same geometry. |
+| `KUI-L004` | review | Nested literal classes both add a content inset.                  |
+| `KUI-L005` | review | Consumer CSS forces a public component's dimensions.              |
+| `KUI-L006` | review | Literal spacing falls outside Kerf's approved scale.              |
+| `KUI-L007` | error  | A declared scroll owner is nested inside another scroll owner.    |
+| `KUI-L008` | review | A dynamic class expression cannot be classified soundly.          |
+| `KUI-L009` | error  | A stylesheet cannot be parsed.                                    |
+
+Errors are provable contract violations and make the command exit 1. Review
+findings are deliberately heuristic and do not fail by default; pass
+`--fail-on-review` when a project has reviewed its baseline and wants them to
+gate CI. Text, versioned JSON, and SARIF carry the same stable rule ids,
+source locations, evidence, and ownership chain.
+
+The JSON report schema is exported as
+`@kerfjs/ui/analyzer/report.schema.json`.
+
+Profile discovery, parsing, catalog-loading, and validation diagnostics retain
+their stable `KUI-P###` ids in every output format and count as errors. The
+analyzer therefore cannot silently pass with stale or unreadable policy input.
+
+The analyzer is conservative about dynamic class expressions: it emits one
+review finding and does not guess which selectors, tokens, or owners the value
+might contain. CSS values expressed through public variables or `calc()` are
+also left to their owning token contract rather than reverse-engineered.
+
+## Narrow exceptions
+
+Use the application profile's `exceptions` only for an exact rule and exact
+repository-relative file. Every exception requires an id and rationale; broad
+directories, globs, absolute paths, and traversal are rejected by the profile
+validator.
+
+```json
+{
+  "id": "legacy-inspector-spacing",
+  "rules": ["KUI-L006"],
+  "target": "src/legacy/inspector.css",
+  "rationale": "The legacy inspector retains its measured spacing until migration."
+}
+```
+
+Review findings remain visible until explicitly suppressed. Avoid suppressing
+`KUI-L001`, `KUI-L002`, `KUI-L003`, `KUI-L007`, or `KUI-L009`: those indicate a
+definite boundary or parsing failure rather than an aesthetic judgment.

package/docs/ui-doctor.md

@@ -0,0 +1,77 @@
+# Kerf UI doctor
+
+`kerf-ui-doctor` is the supported repair-loop entry point for a Kerf application. It produces one versioned report from application-profile and catalog validation, TypeScript, the Kerf UI ESLint preset, static layout analysis, and an explicitly enabled browser evaluation.
+
+```sh
+npx kerf-ui-doctor --full
+npx kerf-ui-doctor --changed
+npx kerf-ui-doctor --package @acme/admin --changed
+npx kerf-ui-doctor --full --browser-url http://127.0.0.1:4173
+```
+
+The default terminal output is short and repair-oriented. `--format json` emits the schema-version-1 report; `--output report.json` writes the same representation. The package exports its contract from `@kerfjs/ui/doctor`, its configuration schema from `@kerfjs/ui/doctor/config.schema.json`, and its report schema from `@kerfjs/ui/doctor/report.schema.json`.
+
+## Stages and trust boundary
+
+The catalog stage discovers the package-default application UI profile and workspace/root-to-leaf directory layers. It validates referenced selection/composition catalogs and, when a workspace declares `package.json#kerfComponentCatalog`, invokes the installed `create-kerf-component` catalog checker to validate metadata, source exports, schema conformance, and generated-output drift. This checker reads source text; it does not import application modules.
+
+TypeScript uses the compiler API with `noEmit`. ESLint loads the installed `eslint-plugin-kerfjs` `recommended-ui` preset (`--eslint strict-ui` opts into advisory rules as errors). Stable KUI identifiers come from the packaged `application-ui-diagnostic-ids-v1.json` registry; the doctor also reads installed ESLint message metadata for semantic conflict detection instead of duplicating rule definitions. The analyzer calls the public `@kerfjs/ui/analyzer` contract. None of these stages executes generated application code.
+
+The browser evaluator is different: it runs the application and is disabled by default. It only runs when configuration supplies `browser.url` or the command receives `--browser-url`. Start and authorize the target application separately.
+
+An unavailable or failed stage does not prevent independent stages from reporting. Its final exit is still a configuration failure, so a partial run cannot appear clean.
+
+## Full and changed modes
+
+`--full` is the default and analyzes the selected package. `--changed` reads tracked and untracked paths from Git unless one or more `--path` values are supplied. An empty changed set is a configuration error instead of a false-clean success. With `--package`, workspace-relative Git paths are converted to package-relative paths before TypeScript, ESLint, and analyzer selection; paths outside the selected package are ignored.
+
+TypeScript constructs the selected package's program so compiler options retain their real meaning, while its root inputs are narrowed to changed source files. Use `--full` for release gates.
+
+## Configuration and suppressions
+
+Place `.kerf-ui-doctor.json` at the workspace root:
+
+```json
+{
+  "$schema": "./node_modules/@kerfjs/ui/doctor/config.schema.json",
+  "schemaVersion": 1,
+  "mode": "full",
+  "stages": { "browser": false },
+  "cache": true,
+  "suppressions": [
+    {
+      "id": "legacy-toolbar",
+      "rules": ["KUI-L006"],
+      "target": "src/legacy-toolbar.css",
+      "rationale": "Removed with the toolbar migration in the next release."
+    }
+  ]
+}
+```
+
+A suppression requires a stable id, one or more exact diagnostic ids, an exact portable source path or browser selector, and a substantive rationale. Wildcards, absolute paths, and parent traversal are rejected. Suppressed diagnostics remain in `report.suppressions` with their rationale and do not affect the exit code.
+
+KUI suppression ids are checked against the analyzer, evaluator, doctor, installed ESLint-rule metadata, and diagnostics emitted by available tools. An unknown or stale id is a configuration error rather than a silent no-op. TypeScript `TS####` and namespaced `eslint:*` ids remain valid even when that particular run does not emit them.
+
+The content-addressed cache lives at `.kerf-cache/ui-doctor-v1.json`. Its key covers selected source/config/catalog JSON, package manifests, root and package lockfiles, mode, paths, and configuration. Browser results are never cached. Use `--no-cache` when investigating tool installation changes not yet reflected in a lockfile.
+
+Reports replace the workspace's absolute path with `<repo-root>` and express in-workspace files as portable relative paths. External paths are reduced to `<external>/<basename>`. URLs are excluded from the cache key. Tool messages and evidence receive the same root redaction before output or caching.
+
+## Report and exit contract
+
+Every diagnostic has a stable `id`, `severity`, `stage`, message, and—when applicable—an exact source location with JSON path or DOM context/selector. Analyzer evidence, catalog facts, documentation links, and safe next actions are preserved when the source tool provides them. Identical findings merge with their source stages; same identifiers with conflicting severities remain separate and add `KUI-D003`.
+
+Exit codes are deterministic:
+
+- `0`: no active error diagnostics;
+- `1`: repairable application findings;
+- `2`: malformed configuration, unavailable required tooling, or a failed stage;
+- `130`: cancellation.
+
+Warnings and review findings remain visible but do not fail unless their originating preset promotes them to errors. A cached report keeps its original exit code and labels previously run stages `cached`.
+
+## Monorepos and repair loops
+
+`--package` accepts either a workspace package name or a workspace-relative package path. The doctor uses the selected package for compiler, lint, profile-discovery start, and analyzer scope, while workspace profile precedence and root lockfiles remain authoritative.
+
+A repair agent should run JSON mode, apply only source-located safe changes, and rerun until exit `0`. Do not treat exit `2`, a skipped required stage, or an empty changed selection as clean. Browser evidence is objective input; the evaluator's named subjective rubric still requires human review.

package/docs/ui-evaluator.md

@@ -0,0 +1,122 @@
+# Browser UI quality evaluator
+
+`kerf-ui-evaluate` is the runtime half of Kerf's UI integration checks. The
+static [`kerf-ui-analyze`](./ui-analyzer.md) command finds source-level ownership
+mistakes; this Playwright-backed evaluator loads a running application and
+records what a browser can establish about the rendered result.
+
+Install Playwright beside `@kerfjs/ui` and install its browsers in CI:
+
+```bash
+npm install --save-dev playwright
+npx playwright install --with-deps chromium firefox webkit
+```
+
+Start the application separately, then evaluate its URL from the project root:
+
+```bash
+npx kerf-ui-evaluate \
+  --url http://127.0.0.1:4173 \
+  --root . \
+  --output artifacts/kerf-ui
+```
+
+The command discovers and resolves the same `.kerf-ui-profile.json` layers as
+the static analyzer. By default it runs Chromium, Firefox, and WebKit through
+six contexts: wide, intermediate, narrow, a half-width CSS viewport representing
+200% browser zoom, dark color scheme, and reduced motion. Use
+`--browser chromium` for a fast local loop; keep all three engines in CI.
+
+## Objective checks
+
+The versioned JSON report uses stable `KUI-B###` codes and includes the context,
+selector, measured evidence, and a repair-oriented message for each finding.
+
+| Code       | Browser fact                                                                     |
+| ---------- | -------------------------------------------------------------------------------- |
+| `KUI-B001` | Navigation, timeout, or browser-context failure                                  |
+| `KUI-B010` | Horizontal page overflow                                                         |
+| `KUI-B011` | Interactive content clipped by a hidden/clip owner or entirely off viewport      |
+| `KUI-B012` | An in-viewport action covered at its center point                                |
+| `KUI-B020` | Positive `tabindex` overriding DOM focus order                                   |
+| `KUI-B021` | Stable per-element focus reaches an invisible control or causes no visual change |
+| `KUI-B022` | Any ARIA widget role is absent from sequential keyboard order                    |
+| `KUI-B023` | A representative action does not activate with Enter                             |
+| `KUI-B030` | An interactive control has no text alternative                                   |
+| `KUI-B040` | Alpha-composited interactive text is below its WCAG AA contrast threshold        |
+| `KUI-B050` | A button-like target is smaller than 44 × 44 CSS pixels                          |
+| `KUI-B060` | A pane or declared scroll scope has multiple active scroll owners                |
+| `KUI-B070` | Elements in an explicitly declared alignment group drift by more than one pixel  |
+| `KUI-B080` | A cataloged root computes geometry assigned to `none`, `parent`, or `child`      |
+
+For a representative application action that must be operated in the generic
+evaluation, add `data-kui-evaluator-action` to its owning native control or
+keyboard-operable custom control. The evaluator focuses it, presses Enter, and
+accepts a click event or controlled `aria-expanded`, `aria-pressed`,
+`aria-checked`, or `value` transition as evidence. This attribute is test
+instrumentation, not an application event hook.
+
+Alignment checks are similarly explicit: put `data-kui-align-group` on the
+shared container and `data-kui-align-edge` on two or more elements whose logical
+start edges must align. Use `data-kui-scroll-scope` only for an application-owned
+scope that is not a `.kui-pane`.
+
+Accessible names follow ARIA/native naming inputs, including labels, referenced
+content with `aria-hidden` descendants removed, and native input values.
+Geometry checks use each catalog entry's explicit `boundaries.rootClass`; the
+order of `publicClasses` has no runtime meaning.
+
+Profile exceptions apply only when both the `KUI-B###` rule and `target` match
+exactly. For the browser evaluator, `target` is the evaluated `startDirectory`
+relative to `workspaceRoot` (for example `apps/settings`); wildcards and broad
+workspace targets remain invalid.
+
+## Report and artifacts
+
+The public Node API is available at `@kerfjs/ui/evaluator`:
+
+```js
+import { evaluateUi } from '@kerfjs/ui/evaluator';
+
+const abortController = new AbortController();
+const report = await evaluateUi({
+  url: 'http://127.0.0.1:4173',
+  workspaceRoot: process.cwd(),
+  retention: 'on-failure',
+  signal: abortController.signal,
+});
+if (!report.summary.passed) process.exitCode = 1;
+```
+
+The default output is `kerf-ui-evidence/report.json`; its schema ships at
+`@kerfjs/ui/evaluator/report.schema.json`. Every retained screenshot has a
+SHA-256 digest. Retention is deterministic:
+
+- `on-failure` (default) removes current and stale evaluator screenshots when
+  every objective check passes;
+- `always` retains one full-page PNG per browser/context;
+- `never` removes current and stale evaluator screenshots and writes only the
+  focused DOM/computed-style evidence in the report.
+
+`--timeout` bounds navigation and browser operations, while `--settle` provides
+one small explicit post-navigation delay for applications with asynchronous
+startup. A timeout becomes `KUI-B001` evidence rather than an unstructured crash.
+The Node API accepts an `AbortSignal`; cancellation closes the active browser,
+removes screenshots from the interrupted run, does not write a partial report,
+and rejects with `AbortError`.
+The CLI exits `1` for objective failures, `2` for invocation/profile errors, and
+`0` for a pass; `--no-fail` is available only for evidence-collection jobs.
+
+## Human visual review stays human
+
+Hierarchy, rhythm, density, aesthetic fit, and the perceived clarity of
+alignment or scroll ownership are not inferred from computed pixels. Every
+report carries the suite-v3 0–2 review rubric with `status: "not-recorded"` and
+an empty rating list. An AI agent may use the retained screenshots as review
+input, but it must record a named reviewer and rationale in the separate
+human-visual evidence workflow; it must not turn a subjective rating into a
+`KUI-B###` assertion.
+
+The deterministic good/bad downstream fixtures and three-engine integration
+suite live under `tests/fixtures/ui-evaluator/` and
+`tests/integration/ui-evaluator-downstream.test.ts`.

package/doctor/cli.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import console from 'node:console';
+import { execFile } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { promisify } from 'node:util';
+
+import { formatUiDoctorText, runUiDoctor, UI_DOCTOR_EXIT } from './index.mjs';
+
+const execFileAsync = promisify(execFile);
+const args = process.argv.slice(2);
+const take = (name, repeat = false) => {
+  const values = [];
+  while (args.includes(name)) {
+    const index = args.indexOf(name);
+    const value = args[index + 1];
+    if (!value || value.startsWith('--'))
+      throw new Error(`${name} requires a value.`);
+    args.splice(index, 2);
+    values.push(value);
+    if (!repeat) break;
+  }
+  return repeat ? values : values[0];
+};
+
+async function changedPaths(root) {
+  const { stdout: tracked } = await execFileAsync(
+    'git',
+    ['diff', '--name-only', '--diff-filter=ACMR', 'HEAD', '--'],
+    { cwd: root },
+  );
+  const { stdout: untracked } = await execFileAsync(
+    'git',
+    ['ls-files', '--others', '--exclude-standard'],
+    { cwd: root },
+  );
+  return [
+    ...new Set(`${tracked}\n${untracked}`.split(/\r?\n/).filter(Boolean)),
+  ].sort();
+}
+
+try {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: kerf-ui-doctor [--full | --changed] [options]
+
+Options:
+  --root <path>          Workspace root (default: current directory)
+  --package <name|path>  Select one workspace package
+  --path <path>          Restrict changed mode (repeatable)
+  --config <path>        Doctor config (default: .kerf-ui-doctor.json)
+  --browser-url <url>    Explicitly enable browser evaluation
+  --browser <list>       Comma-separated chromium,firefox,webkit
+  --eslint <preset>      recommended-ui or strict-ui
+  --format <format>      text or json (default: text)
+  --output <path>        Also write the merged report
+  --no-cache             Disable the content-addressed cache
+
+Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
+    process.exit(0);
+  }
+  const root = resolve(take('--root') ?? process.cwd());
+  const packageSelector = take('--package');
+  const explicitPaths = take('--path', true);
+  const configPath = take('--config');
+  const url = take('--browser-url');
+  const browserList = take('--browser');
+  const eslintConfig = take('--eslint') ?? 'recommended-ui';
+  const format = take('--format') ?? 'text';
+  const output = take('--output');
+  const full = args.includes('--full');
+  const changed = args.includes('--changed');
+  const noCache = args.includes('--no-cache');
+  const known = new Set(['--full', '--changed', '--no-cache']);
+  const unknown = args.filter((item) => !known.has(item));
+  if (unknown.length)
+    throw new Error(`Unknown arguments: ${unknown.join(' ')}`);
+  if (full && changed)
+    throw new Error('--full and --changed are mutually exclusive.');
+  if (!['text', 'json'].includes(format))
+    throw new Error('--format must be text or json.');
+  if (!['recommended-ui', 'strict-ui'].includes(eslintConfig))
+    throw new Error('--eslint must be recommended-ui or strict-ui.');
+  const abort = new globalThis.AbortController();
+  process.once('SIGINT', () => abort.abort());
+  const paths =
+    changed && !explicitPaths.length ? await changedPaths(root) : explicitPaths;
+  const report = await runUiDoctor({
+    root,
+    package: packageSelector,
+    mode: changed ? 'changed' : full ? 'full' : undefined,
+    paths,
+    configPath,
+    cache: !noCache,
+    signal: abort.signal,
+    eslintConfig,
+    browser: url
+      ? { url, browsers: browserList?.split(',').map((item) => item.trim()) }
+      : undefined,
+  });
+  const rendered =
+    format === 'json'
+      ? JSON.stringify(report, null, 2)
+      : formatUiDoctorText(report);
+  if (output) await writeFile(resolve(root, output), `${rendered}\n`);
+  else console.log(rendered);
+  process.exitCode = report.exitCode;
+} catch (error) {
+  console.error(`kerf-ui-doctor: ${error.message}`);
+  process.exitCode =
+    process.exitCode === UI_DOCTOR_EXIT.cancelled
+      ? process.exitCode
+      : UI_DOCTOR_EXIT.configuration;
+}

package/doctor/config.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/doctor/config.schema.json",
+  "title": "Kerf UI doctor configuration",
+  "type": "object",
+  "required": ["schemaVersion"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "mode": { "enum": ["full", "changed"] },
+    "package": { "type": "string", "minLength": 1 },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "catalog": { "type": "boolean" },
+        "typescript": { "type": "boolean" },
+        "eslint": { "type": "boolean" },
+        "analyzer": { "type": "boolean" },
+        "browser": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "browser": {
+      "type": "object",
+      "required": ["url"],
+      "properties": {
+        "url": { "type": "string", "pattern": "^https?://" },
+        "browsers": {
+          "type": "array",
+          "items": { "enum": ["chromium", "firefox", "webkit"] },
+          "uniqueItems": true
+        },
+        "retention": { "enum": ["always", "on-failure", "never"] },
+        "outputDirectory": { "$ref": "#/$defs/path" },
+        "reportPath": { "$ref": "#/$defs/path" }
+      },
+      "additionalProperties": false
+    },
+    "cache": { "type": "boolean" },
+    "suppressions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "rules", "target", "rationale"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "rules": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "target": { "$ref": "#/$defs/path" },
+          "rationale": { "type": "string", "minLength": 12 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "path": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))(?!.*[?*]).+"
+    }
+  }
+}