@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.101

package/docs/ui-doctor.md

@@ -0,0 +1,281 @@
+# 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
+npx kerf-ui-doctor --full --fail-on warning
+```
+
+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). This is deliberately an isolated Kerf lint pass rather than the consumer's complete ESLint configuration. For each file, the doctor projects the applicable core ESLint rules and `linterOptions` from the consumer configuration so core-rule suppression directives retain the same used/unused semantics as the application's normal lint command. Consumer plugin rules are not executed, and inline directives for plugins such as `@typescript-eslint` therefore do not produce false "rule definition not found" diagnostics; the consumer's normal ESLint command remains authoritative for those rules. Unknown `kerfjs/*` directives still fail the doctor pass. 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.
+
+Property-specific CSS values are evaluated from each first- or third-party
+catalog entry's `cssValueProps`. `KUI-L013`–`KUI-L016` are blocking grammar
+violations and name a preferred shorthand/helper; `KUI-L017` keeps an
+exceptional but valid spacing choice in the review queue. The ESLint and
+analyzer stages share these ids, messages, and severities, so each finding
+merges into one diagnostic and the normalized report can be consumed as one
+repair loop without tool-specific translations. ESLint has no `review`
+severity: the presets configure `ui-exceptional-shorthands` (`KUI-L017`) as
+`warn`, and the doctor reads an ESLint warning for a code the analyzer
+classifies as `review` as that review finding.
+
+The analyzer stage also reads consumer stylesheets for theme overrides:
+`KUI-L018` is a review finding for a `--wa-color-{tone}-fill-loud` override
+that lacks a governing `--wa-color-{tone}-on-loud` (in the same or an ancestor
+scope, in any stylesheet the same entry loads), or whose literal pair measures
+below 4.5:1 (see [the analyzer rule](./ui-analyzer.md#loud-fill--on-loud-pairing-kui-l018)).
+
+Component ownership is part of the same loop. The analyzer stage reports
+application or third-party CSS that restyles another package's component
+(`KUI-L019`), touches its private `--_*` variables (`KUI-L020`), overrides a
+token a typed prop sets (`KUI-L021`), or styles it through a hook class on its
+root (`KUI-L022`), including components nested in JSX prop values and hooks
+owned by the surrounding application. It also reports source modules that render another
+component's public classes as their own markup (`KUI-L023`), including raw HTML
+and DOM class writes. Raw HTML checks include complete static class tokens in
+interpolated template literals. `KUI-L023` skips `*.test.*`, `*.spec.*`, and `__tests__/`
+modules so output assertions are not mistaken for rendered markup. The ESLint
+stage's `ui-component-ownership` rule reports
+`KUI-L020` / `KUI-L021` in script. Each finding's `action` points at the
+component's configuration, and its message routes a need with no prop to a
+component-gap report instead of an override (see
+[the analyzer rule](./ui-analyzer.md#component-ownership-kui-l019kui-l023)).
+In component mode, `KUI-L019` also follows an owned wrapper to a composed
+child's cataloged root and descendant element types. For example, a wrapper
+around `LucideIcon` cannot size its `svg` or `path` with an element selector;
+use the icon's props or style an app-owned element. The same check follows
+local function components returned from the owner module and treats their
+intrinsic markup as app-owned.
+Unknown custom `IconNode` tags are identified when a selector explicitly
+passes through the icon's `svg[data-lucide]` root; unrelated HTML descendants
+without that marker remain app-owned.
+The analyzer resolves a cataloged application component imported through an
+exact or wildcard TypeScript `paths` alias from the nearest consumer tsconfig,
+so the same root hook-class check applies in those files.
+
+## Component style naming
+
+The analyzer stage also checks colocated JSX/TSX components and stylesheets.
+When a stylesheet has a same-basename component module, or exactly one
+component module imports it, Doctor checks that the stylesheet filename is
+the component's kebab-case name (`KUI-D031`). A component whose returned root
+is its own HTML element must put that kebab-case class on rendered markup
+(`KUI-D030`). Static base tokens in template, concatenated, and conditional
+class expressions count only when every path contains the token.
+An opaque class expression stays unclassified instead of producing a missing
+root-class error.
+For example, `WorkspaceHeader` pairs with `workspace-header.css` and renders
+`.workspace-header`. A local composition catalog can explicitly declare a
+different `boundaries.rootClass` or `publicClasses` and list its stylesheet
+under the selection entry's `styleSources`; Doctor honors that declared alias
+for both checks. The catalog stage remains responsible for validating the
+metadata. Thin components that return another component need no root class,
+even when they render nested HTML as children. Helpers declared in the same
+module share that module's CSS ownership; a module exporting several visual
+components can use a shared stylesheet name. Shared stylesheets declared in
+`ownershipGroups` are exempt from the naming check.
+
+Doctor reports `KUI-D032` when a paired stylesheet selects another module's
+local component class or its BEM descendants or modifiers. Move that
+rule to the owning component's stylesheet or use the component's public
+configuration. This check uses source declarations and CSS selectors; it does
+not execute component code. In changed mode, it reads other component sources
+to resolve ownership but reports only pairs containing a selected path. For
+broader cross-component ownership, including
+cataloged package components and hook classes, enable `ownership: "component"`
+with `implicitComponentOwnership: true` as described above.
+
+Set `"ownership": "component"` in `.kerf-ui-doctor.json` to enforce the same
+boundary between a consumer package's own cataloged components. The default is
+`"package"`. Selection-only entries participate too. A component owns its
+`styleSources` (relative to its package root), or its direct relative CSS
+imports when that list is absent, and its selection catalog `source` module.
+Literal rendered BEM classes are inferred when those stylesheets style their
+block. An owned root or styled literal owns its whole `block__*` and `block--*`
+family, including dynamic names and classes placed on imported components.
+Modules sharing one of those stylesheets co-own its classes, so their
+own markup does not borrow from one another. A class inferred by several
+co-owners has no arbitrary single owner for CSS subject diagnostics. A
+stylesheet foreign to all co-owners receives one `KUI-L019` per subject rule,
+including dynamic BEM modifiers; `evidence.components` names the co-owner set.
+Set `"implicitComponentOwnership": true` to include uncataloged modules
+that directly import CSS. Component mode reports sibling CSS and hook-class
+restyles while allowing a component's own stylesheet and module.
+For an application with reusable or app-level components, the recommended
+policy is `"ownership": "component"`, `"implicitComponentOwnership": true`,
+and `"ownershipContext": "any-package"`. This lets components style raw HTML
+and Web Awesome elements they own while blocking overrides of nested Kerf and
+application components. Thin glue compositions should normally omit CSS; when
+they own wrapper markup or layout, Doctor permits that own CSS and reports any
+selector that crosses into a child component.
+For an entry stylesheet shared by modules without direct CSS imports, configure
+`"ownershipGroups": [{ "styleSources": ["src/style.css"], "sources": ["src/main.tsx", "src/app/"] }]`.
+These package-relative paths define one owner: its stylesheet and every listed
+source file or directory prefix. Doctor reports sibling CSS restyles and markup
+class use as `KUI-L019` and `KUI-L023`. Source paths ending in `/` match a
+directory subtree; other paths match exactly. When implicit ownership is also
+enabled, the group takes precedence over listed source modules and any direct
+import of its stylesheet. An unrelated importer still borrows the group's
+classes; its other stylesheets can retain their own implicit ownership.
+
+Set `"ownershipContext": "any"` to also report a same-package sibling's class
+used as ancestor or sibling context or within `:has()`, `:is()`, `:where()`, or
+`:not()`. The default `"subject"` keeps subject-only context policy; classes
+from another package may still provide context. Set
+`"ownershipContext": "any-package"` to include cross-package component
+classes and `[data-component]` roots in the same selector-context checks.
+
+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.
+
+## Interface copy capitalization
+
+The analyzer stage also checks visible label copy against the package
+capitalization rule in [Writing interface copy](./writing.md#capitalization).
+Names of commands, controls, views, and fields use title style, following
+Apple's guidance. `KUI-D040` (warning) reports a string or template literal
+passed to a known title-style prop that leaves a word lowercase where title style
+capitalizes it. For example, `<wa-button>Save draft</wa-button>` should be
+"Save Draft", and `<ListHeader label="Needs attention" />` should be "Needs
+Attention". The action names the repaired label.
+
+The check reads `.tsx` and `.jsx` source text only and skips test modules.
+Fixture components that tests render (for example
+`tests/browser/fixtures/*.tsx`) are not test modules and are checked: they
+stand in for application screens, so their copy follows the same rule. It
+covers these string literals:
+
+- `ToolbarText` titles: text with `headingLevel`, a large size, or in a
+  toolbar or panel `title`, `header`, or (unless small) `leading` slot;
+- `ListHeader`, `ListActionRow`, `SplitButton`, and `Combobox` labels;
+- `CatalogExample` and `CatalogExampleStack` labels, which render as a
+  `ListHeader` heading (their `note` stays sentence style and is not read);
+- `EmptyState` and `StateBanner` titles;
+- `PopupMenu` trigger text and item and heading labels, including submenus
+  declared in the same file;
+- `SegmentedControl`, `Select`, and `TabNavigator` choice and tab labels;
+- `NavStack` view titles and `backText`, and `SplitView` `backLabel`;
+- `FieldLabel` text and the static text of a `button` or `wa-button`;
+- the `name` of a panel toolbar's `toggle: { action, name }` object literal
+  (Workbench panels, `CollapsiblePanel`), which names the toggle group and
+  completes its "Show …" / "Hide …" label;
+- region and landmark names: the `label` of `Pane`, `Workbench`, `Toolbar`,
+  `ToolbarControlGroup`, `TabBar`, `NavStack`, `CollapsiblePanel`,
+  `FloatingToolbar`, and `ResizableRegion`; the `ariaLabel` of `SunkenPanel`
+  and `List`; a `Pane`'s `contentLabel`; the panel, toolbar, and pane labels
+  in `Workbench` (`leftRail`, `rightRail`, `bottomDrawer`, `mainToolbar`,
+  `mainBottomToolbar`, `mainPane`), `CollapsiblePanel` (`toolbar`,
+  `bottomToolbar`, `pane`), and `NavStack` (`views`, `bottomToolbar`)
+  configuration declared in the same file; and the `aria-label` of a
+  `section`, `nav`, `aside`, `main`, `header`, `footer`, `form`, or `search`
+  element or an element with a landmark `role`;
+- the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or
+  `wa-radio-group`, which is a field or group label;
+- the accessible names of icon-only controls, which the rule also gives title
+  style: `IconButton` and `IconToggleButton` `label`, `PopupMenu` `label`,
+  `SplitButton` `optionsLabel`, `TokenSearchField` `clearLabel`, and the
+  `aria-label` of a `button` or `wa-button` whose only content is an icon. A
+  button with visible text is judged by that text, never by its `aria-label`.
+
+The check is deliberately one-directional, to keep false positives rare:
+
+- It reports only lowercase words. It never reports a capitalized short word,
+  because Apple capitalizes a phrasal verb's particle ("Log In to the
+  Server").
+- It leaves text ending in `.`, `!`, or `?` to sentence style.
+- It judges only a template literal's static words, so
+  `` `Edit ${name} shortcut` `` is reported and the interpolated value never
+  is. A word joined to an interpolation (`` `${count}s` ``) is skipped.
+- It ignores other dynamic values and every sentence-style surface: descriptions,
+  details, placeholders, tooltips, status text, and option text, including
+  `wa-checkbox`, `wa-switch`, and `wa-radio` labels. It does not read
+  `LoadingSpinner` or `Skeleton` labels, which announce a status.
+- It skips tokens containing digits, code, paths, or URLs, and lowercase-led
+  brands such as iOS and macOS.
+- It keeps a minor word inside a longer hyphenated compound lowercase, as
+  between separate words ("Edge-to-Edge", "Up-to-Date").
+- It does not read `ContentItem` `title`, which is a native tooltip.
+
+Suppress `KUI-D040` for a file whose copy is a lowercase brand or product
+name.
+
+## 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.
+
+Full traversal treats generated/tool-owned directories (`dist`, `coverage`,
+`node_modules`, `.git`, `.kerf-cache`, `kerf-ui-evidence`, Playwright's
+`playwright-report`, `test-results`, and `blob-report`, and nested
+`.claude/worktrees` checkouts) as outside application source. Inside a Git work
+tree it also skips every path the project's ignore rules (`.gitignore`,
+`.git/info/exclude`, and the global excludes file) ignore, so a local test run
+that writes gitignored reports or caches never changes the doctor result.
+These files are excluded consistently from TypeScript, the isolated ESLint
+pass, analyzer discovery, and cache inputs, even when one lives below another
+application directory; a `.gitignore` change invalidates the cache.
+
+TypeScript constructs the selected package's program so compiler options retain their real meaning. In changed mode, its root inputs are narrowed to changed source files plus the tsconfig's declaration roots, so ambient globals still participate; reported source diagnostics stay scoped to the changed 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",
+  "ownership": "component",
+  "ownershipContext": "any-package",
+  "implicitComponentOwnership": true,
+  "stages": { "browser": false },
+  "cache": true,
+  "failOn": "warning",
+  "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. `failOn` defaults to `error`; `--fail-on error|review|warning` overrides the config for a run. `review` fails on errors or review findings; `warning` also fails on warnings. Suppressed diagnostics never count. The effective threshold is part of the cache key.
+
+- `0`: no active diagnostics at or above the selected threshold;
+- `1`: repairable application findings;
+- `2`: malformed configuration, unavailable required tooling, or a failed stage;
+- `130`: cancellation.
+
+Warnings and review findings remain visible at every threshold. 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,139 @@
+# 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`.
+
+Target size (`KUI-B050`) measures the area the pointer can actually reach, not
+just the border box. When a control's box is under 44 × 44, the evaluator
+hit-tests outward from its center with `elementFromPoint`, so a transparent hit
+layer (a positioned `::before`/`::after` that receives pointer events, as on the
+`ListHeader` action) counts toward the target, while a pseudo-element with
+`pointer-events: none`, a clipping ancestor, or an overlapping neighbor does
+not. Where the probe reaches the viewport edge it mirrors the opposite side's
+reach; a control whose center is off-screen or covered keeps its border box.
+The diagnostic evidence reports the measured `width`/`height` and the border
+`box`.
+
+Compact density is a documented exception. Inside `[data-density="compact"]` —
+the compact `List`/`ListHeader` family, whose rows are 36px tall — a target
+still needs the full 44px width but only the 36px row height, because a taller
+hit layer would reach into the neighboring row. The evidence's `required` field
+names the floor that applied (`44×44`, or `44×36` in compact density).
+
+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/docs/ux-demo.md

@@ -1,32 +1,73 @@
 # UX catalog contract
 
-Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
+Run `npm run dev` from `ui/` (or `npm run dev:lan` from the repo root or `ui/`). The catalog is a development and review surface, not a second implementation. The development server reloads component source edits without a restart: component entries still load through their `dist/browser` wrappers, so each component's reachable CSS is exercised as consumers receive it, but the JavaScript those wrappers re-export (and every other `@kerfjs/ui` subpath) resolves to `src/`, and CSS resolves to `src/` as well. A component that gains a new CSS dependency needs a restart, because the wrapper listing its stylesheets is regenerated only by the build. Production demo builds, previews, and the browser tests use `dist/`. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
 
-Seven lazy production-composition routes live under the `Recipes` category.
+`npm run dev:lan` serves the same development catalog on every network
+interface, for checks only a real device can make: a phone's virtual keyboard
+and safe areas, touch dragging, and device rendering. It prints the catalog's
+LAN and Tailscale URLs (opening the bottom-sheet route) and accepts Tailscale
+MagicDNS (`*.ts.net`) and mDNS (`*.local`) host names; plain `npm run dev` stays
+on `127.0.0.1`. The catalog page sets `viewport-fit=cover`, so on a notched
+phone `env(safe-area-inset-*)` reports the real insets and the layouts' safe-area
+model is visible. See [`manual-test-plan.md`](manual-test-plan.md) for the
+device checks.
+
+Every Playwright entry point builds current source before the preview server
+starts. `npm run test:e2e -- tests/browser/row.spec.ts` and a direct focused
+`npx playwright test tests/browser/row.spec.ts` both run catalog generation and
+demo-conformance preflights, build the package and production catalog, then
+launch Chromium, Firefox, and WebKit. The build emits
+`source-freshness.json`; browser coverage compares it with an independent hash
+of the current `src/` and `ux-demo/` inputs, so a stale `dist-demo` cannot pass
+after a route or component edit. `npm run demo:serve` remains a preview-only
+command for an already-built catalog. The demo-conformance preflight also
+rejects a component route that wraps its `CatalogExampleStack` in a card or
+other container (`catalog-demo/wrapped-example-stack`): single-component demos
+sit directly on the catalog grid, and only composition and recipe routes frame
+their content.
+
+Ten lazy production-composition routes live under the `Recipes` category.
 Each `?component=recipe-*` route uses public package primitives, real wiring,
 deterministic state, and semantic layout owners from the [recipe guide](./recipes.md).
 
 - It imports public component subpaths, exercising their browser-selected reachable CSS rather than a catalog-only style path.
+- The `ListActionRow` route's Run Tests row composes a trailing `PopupMenu` (`trailingMenu`) with Edit and Delete commands, revealed on interaction, that also opens at the pointer when the row's primary button is right-clicked.
 - The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
-- The `AppTab` route demonstrates a runtime-filtered domain metadata slot and a decorative replacement close icon without changing TabBar selection, close, reorder, or focus ownership. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
-- Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, feedback, and theme scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component.
-- `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Demo paths resolve to `ui/ux-demo/main.tsx`, the matching `ui/ux-demo/recipes/*.tsx` file, or `ui/ux-demo/webawesome-demos.tsx` according to the canonical entry. First-party component entries additionally derive `ui/src/<browser-subpath>.tsx` from their canonical `delivery.browserImport`.
-- Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
-- The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
-- The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with the subtitle in its own aligned row like `PanelHeader`; the current-view heading is also a toolbar. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The checkerboard belongs to the complete scrollable preview region rather than a nested card. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
-- The composer-form recipe demonstrates one coherent visible form surface with `PanelHeader` title/summary hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
-- The list-detail dialog recipe places its header directly on the dialog edge while preserving the header's internal inset, gives the selected project title the complete outer-plus-inner content gutter, lets the value table fill the available detail column between the shared outer margins, and keeps record actions on one outer gutter without an extra content-item inset. Browser geometry coverage protects those relationships at wide and narrow widths.
+- The `PopupMenu` route's context example opens one app-owned menu either at the row's right-click point or below its adjacent, keyboard-operable Demand Actions button. The Nested Decisions example shows the automatic phone-width submenu placement above or below its parent list, with native ArrowLeft return, Escape dismissal, and child selection.
+- The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, pending, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The pinned leading-tab specimen uses native strip scrolling so momentum and the final tab's end position remain natural; `snapTabs` stays an opt-in for applications that want whole-tab settling. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding (a new tab opens `pending` with a spinner and stays selectable while its panel shows a `Skeleton` heading until a simulated load completes), closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
+- Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, and feedback scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component. The former aggregate Web Awesome theme specimen is intentionally omitted because its component families are covered by those focused routes.
+- `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Functional groups follow their authored importance order; components precede compositions inside each group, equal-importance entries use alphabetical order, and the Recipes group comes last. Composition names stay concise and project a visible `Composition` sidebar tag. Non-supported Web Awesome recommendations project to a visible `Discouraged` tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
+- Every detail footer groups compact `Demo Source` and `Guidance` actions; first-party component details also expose `Component Source`. Web Awesome details say `Integration Guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
+- The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 15 discouraged choices. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
+- The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with supporting copy in its own aligned row; the current-view heading is also a toolbar. The shared Catalog sidebar includes a filter for entry and heading names that works across first-party and ecosystem sections, including collapsed sections. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The preview stage sits directly in the sunken main Pane, with its canvas padded by the medium spacing token. The stage fills the preview scroller for short specimens and grows with taller ones; every background choice follows that same shared behavior in this demo and in consumers. The checkerboard belongs to that stage, rather than a viewport-height wrapper or nested card, and one explicitly repeated SVG tile keeps the pattern continuous through below-fold content. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
+- The composer-form recipe demonstrates one coherent visible form surface with toolbar title/supporting-copy hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
+- The list-detail dialog recipe is laid out like a `Workbench` on roomy devices: a headerless `DialogSurface` modal whose `SplitView` holds a full-height list sidebar `Pane` with its own toolbar beside a full-height detail `Pane` that carries the primary xl title, the `data-dialog="close"` control, and the record actions in its footer. Compact devices get a full-screen sheet with its own labeled header, footer actions, and a list-to-detail drill-down. Browser geometry coverage protects those relationships at wide and narrow widths.
 - Catalog-only brand marks, preview dimensions, checkerboard tiles, and the compound display-settings control retain local geometry because they are specimen chrome or intrinsic control anatomy rather than reusable application spacing roles.
 - The menu composition route demonstrates toolbar/content/footer anatomy, 24px major gaps, 8/1/8 child geometry, the full-width `ListHeader` count-or-badge/action split, logical-end 44px action targets with 18px visuals, and 44px row/header/toolbar targets. Its one chevron is a production 18px `DisclosureArrow` inside a controlled Tools header that actually reveals and hides content; ordinary Projects navigation has no false disclosure affordance. Browser assertions cover stable naming, expanded/content transitions, visual rotation, node identity, reduced motion, RTL alignment and containment, and wide, narrow, dark, and 200% layouts. The focused ListHeader route separately shows the shared neutral count pill for Attachments, Notes (including zero), and Duplicates plus a non-count legacy badge, full-width logical-end actions, and no disclosure without content.
 - The `DisclosureArrow` route renders the production 18px root-scaled default without a catalog-only size override. Its two native buttons independently control the default right-to-down chevron and a recognizable right-facing replacement arrow with left-to-up custom directions; both use shortest-path rotation and their names stay stable while `aria-expanded` communicates state. Browser coverage verifies the custom clockwise path, pointer and native keyboard activation, focus, narrow and 200%-zoom stacking with contained labels, consumer sizing, and the independent `.5` Web Awesome glyph scale retained by Kerf `Select`.
-- A detail with relationships renders one grouped footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
-- Demo-only CSS supplies only the catalog shell and stages; component appearance stays in package CSS. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
-- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. The Web Awesome theme route remains the broad system view, while individual action, form, layout, navigation, feedback, media, and helper routes provide focused specimens; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; PanelHeader demonstrates its plain top-toolbar identity, extra-large title, optional subtitle row, and bordered brand-filled icon group; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone plus a scoped override; TabBar demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
-- Recipe ownership notes are hidden by default. A page-toolbar toggle reveals them as floating warning-toned notes with a folded corner, keeping instructional copy visually distinct and removable from the specimen flow.
-- Settings exercise light/dark, increased contrast, and reduced motion without changing component code. The theme action starts from the operating system's effective color scheme, always names the appearance it will switch to, and installs an explicit light or dark override when activated; contrast and reduced motion expose their independent preferences through `aria-pressed`.
+- A detail with relationships renders one content-fitted `Components` footer selector: `Uses` links to direct dependencies and `Used By` links to reverse dependents. Its popup owns the standard surface inset so headings and even long component names stay clear of the menu border. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
+- Focused demos ship no local stylesheets, inline styles, or styling-only class names. They compose Kerf components first, Web Awesome surfaces where Kerf has no equivalent, and ordinary semantic HTML for the remainder. The catalog-owned `CatalogExample.viewport` contract supplies the few specimen constraints needed to demonstrate layout behavior. Recipes follow the same rule: they ship no stylesheets, inline styles, or styling-only classes, and the catalog frames each one in the `CatalogExample` viewport its exported `presentation` declares (full-width application arrangements span the canvas measure; narrower recipes sit in the left-aligned example column). Demo-only CSS is limited to the document-shell `style.css`, which carries no recipe rules. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
+- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. Individual Web Awesome action, form, layout, navigation, feedback, media, and helper routes provide focused theme specimens without a redundant aggregate route; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges, a scoped override, and a placeholder with and without a badge, the badged placeholder in every tone so captures cover the solid badge skeleton; the Application tabs composition uses a Web Awesome card with semantic header/footer slots and Kerf `Text` while demonstrating overflow, edge autoscroll, and controlled pointer/keyboard reordering.
+- The ToolbarControlGroup route also demonstrates the public compact/tight,
+  mixed-content, filled-selection, nested-dropdown, and avatar/scrim contracts
+  added for consumers that previously restyled group descendants. The compact
+  mixed specimen keeps its connected separator plus the standard 8px dropdown
+  trigger inset, label, and caret inside both pill and rounded group shapes.
+  Avatar images are chrome rather than nested `img`
+  elements: a lone avatar paints the group, while a multi-button avatar group
+  paints only the pressed selection, with contain fitting in both cases. Its
+  collapsible-search specimen follows the selected group shape with a
+  concentric inner radius in both collapsed and expanded states.
+- Recipe ownership notes are hidden by default. A page-toolbar toggle reveals each recipe's note as its `CatalogExample` note above the framed specimen, so instructional copy never covers the composition.
+- Settings exercise light/dark, increased contrast, and reduced motion without changing component code. The theme action starts from the operating system's effective color scheme, always names the appearance it will switch to, and installs an explicit light or dark override when activated; contrast and reduced motion expose their independent preferences through `aria-pressed`. The display-control group wraps whole independent controls at narrow widths so all stay reachable. The adjacent Background menu chooses an 8px-square checkerboard (default), 8px vertical stripes, a layout guide with single-pixel rules at 15px, 23px, and 32px, surface, or sunken for the preview stage. The demo saves all four display choices in browser storage and restores them across entries and reloads. A saved light or dark choice remains explicit when the operating-system appearance changes; without one, the theme follows the system. Invalid or unavailable storage falls back to defaults while the controls remain usable.
 - The footer action log is an `aria-live` region, making interactions visible to both people and browser tests.
 - The focused Toast route calls Web Awesome's documented programmatic stack API and notes that Hot Sheet 2 still uses its own app-level toast implementation; the catalog demonstrates ecosystem support without implying current product adoption.
 - Browser coverage walks every Kerf, composition, and Web Awesome route, checks every listed Web Awesome custom element is registered in its focused specimen, exercises the ecosystem disclosure and both relationship directions, validates offline source/guidance hrefs and accessible wide/narrow/200%-zoom wrapping, and covers tab selection/reordering/overflow, semantic palettes and scoped overrides, light/dark rendering, toolbar popup and responsive find behavior, single/multiline search alignment, menu alignment, banner urgency, keyboard resizing, live custom-element values, and representative wide/narrow captures.
-- The production build keeps the catalog shell and Kerf routes in the entry chunk, then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route, the broad Web Awesome theme route, or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
+- The production build splits the code loaded at startup into three eagerly preloaded chunks behind a tiny entry, so none nears the largest-chunk limit in `demo-bundle-budget.json`: `vendor` (the Web Awesome select and popup-menu registrations with their Lit and Floating UI runtime), `kerf` (the built `@kerfjs/ui` modules and the kerf core, plus every startup stylesheet), and `catalog` (the catalog shell and per-component demo modules). A chunk carries the CSS its modules import, so all startup CSS modules share the `kerf` chunk: the stylesheet stays one file with the cascade order a single-chunk build emits, and the chunk graph stays acyclic (`catalog` imports `kerf`, never the reverse). Only modules statically reachable from the entry qualify, so lazy-only dependencies stay in their lazy chunks. It then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
+
+The focused ListHeader route shows `xs`, `sm`, `m`, `l`, and `xl` labels at one
+semantic heading level. Its default `sm` style still matches `FieldLabel`.
+It also shows simultaneous badge and status indicators, with a conditional
+badge expression that may return `undefined`.
 
-Before handoff, inspect the actual captures for readability, context, alignment, clipping, spacing, responsiveness, focus, and obvious defects. Fix and recapture rather than treating the screenshot as proof by itself.
+Before handoff, inspect the actual captures for readability, context, alignment, clipping, spacing, responsiveness, focus, and obvious defects. Fix and recapture rather than treating the screenshot as proof by itself. Firefox and WebKit screenshots leave out `backdrop-filter`, so translucent chrome looks unblurred in them. Check the blur on a `recordVideo` frame instead (see [Accessibility › Chrome material](accessibility.md#chrome-material)).