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

package/docs/examples/component-catalog-extension-v2.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "../../ai/component-catalog-extension-v2.schema.json",
+  "schemaVersion": 2,
+  "package": "@acme/ui",
+  "compatibility": {
+    "v1Catalog": "./component-catalog-extension.json",
+    "identity": "package:id"
+  },
+  "entries": [
+    {
+      "key": "@acme/ui:inspector",
+      "package": "@acme/ui",
+      "id": "inspector",
+      "name": "Inspector",
+      "kind": "composition",
+      "source": "application",
+      "parents": { "mode": "listed", "entries": ["@kerfjs/ui:layout"] },
+      "contexts": ["record-detail"],
+      "zones": [
+        {
+          "id": "header",
+          "accepts": ["@kerfjs/ui:panel-header"],
+          "cardinality": { "min": 1, "max": 1 },
+          "exclusiveWith": []
+        },
+        {
+          "id": "facts",
+          "accepts": ["@kerfjs/ui:value-table"],
+          "cardinality": { "min": 1, "max": 1 },
+          "exclusiveWith": []
+        }
+      ],
+      "children": {
+        "mode": "listed",
+        "concepts": ["@kerfjs/ui:panel-header", "@kerfjs/ui:value-table"],
+        "requiredConcepts": [
+          "@kerfjs/ui:panel-header",
+          "@kerfjs/ui:value-table"
+        ]
+      },
+      "state": [
+        { "id": "selected-record", "owner": "application", "required": true }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": {
+        "owner": "application",
+        "behaviors": [
+          "May move between inline-end pane and dialog at the application breakpoint."
+        ]
+      },
+      "layout": {
+        "roles": ["inspector"],
+        "geometry": {
+          "margin": "parent",
+          "border": "child",
+          "padding": "child"
+        }
+      },
+      "accessibility": {
+        "obligations": ["The header names the inspector region."]
+      },
+      "boundaries": {
+        "rootClass": "acme-inspector",
+        "publicClasses": ["acme-inspector"],
+        "publicTokens": []
+      },
+      "diagnostics": [
+        {
+          "id": "KUI-C901",
+          "severity": "error",
+          "when": "the header or facts zone is absent",
+          "message": "Inspector requires exactly one header and one facts region."
+        }
+      ],
+      "provenance": {
+        "selection": "docs/inspector.md",
+        "composition": "docs/inspector.md#composition-contract"
+      }
+    }
+  ]
+}

package/docs/layout.md

@@ -1,26 +1,39 @@
 # Pane and content layout
 
-Import `@kerfjs/ui/layout.css` for the shared geometry used by sidebars, main
-areas, inspectors, and dialogs. The vocabulary deliberately describes structure
-rather than location: the same pane can be placed anywhere.
+Import `Pane` from `@kerfjs/ui/pane`. Browser-aware bundlers receive its CSS
+automatically; other consumers can import `@kerfjs/ui/pane.css`. Import
+`@kerfjs/ui/layout.css` as well when using the related content-item and control
+layout classes. The vocabulary deliberately describes structure rather than
+location: the same pane can be placed anywhere.
 
 ## Anatomy
 
 ```tsx
-<aside class="kui-pane">
-  <div class="kui-pane__toolbar"><Toolbar label="Workspace" ... /></div>
-  <div class="kui-pane__content kui-content">
+<Pane
+  element="aside"
+  label="Workspace"
+  contentElement="nav"
+  contentLabel="Workspace pages"
+  separators={["inline-end"]}
+  header={<Toolbar label="Workspace" ... />}
+  footer={<Toolbar label="Actions" ... />}
+>
     <section>...</section>
     <section>...</section>
-  </div>
-  <footer class="kui-pane__footer"><Toolbar label="Actions" ... /></footer>
-</aside>
+</Pane>
 ```
 
-`.kui-pane` has no padding. It reserves rows for an optional toolbar, one
-scrolling content area, and an optional footer. A main area or dialog often
-omits the footer; a navigation pane commonly uses all three. Fixed chrome stays
-outside `.kui-pane__content`, which is the pane's scroll owner.
+`Pane` has no padding. It reserves rows for an optional vertical header, one
+scrolling vertical content area, and an optional footer. A header may contain a
+top toolbar followed by secondary toolbar or status rows. A main area or dialog
+often omits the footer; a navigation pane commonly uses all three. Fixed chrome
+stays outside `.kui-pane__content`, which is the pane's only scroll owner.
+
+Pass any combination of logical sides to `separators`: `block-start`,
+`block-end`, `inline-start`, and `inline-end`. Every line is off by default and
+each enabled side uses `--kui-pane-separator-width` (1px) and
+`--kui-pane-separator-color` (`--kui-color-border`). Logical sides keep pane
+boundaries correct in both left-to-right and right-to-left layouts.
 
 `.kui-content` is a vertical stack with a 24px gap between major children.
 Sections may contain adjacent `ListItem` rows without adding another major gap.
@@ -37,6 +50,11 @@ Use `.kui-content-item--pill` for the 22px pill radius expressed as
 changing its geometry by setting `--kui-content-item-border` and
 `--kui-content-item-background`.
 
+Nested rounded edges stay concentric by subtracting their full inset from the
+outer radius. For example, `SegmentedControl` places each item behind a 1px
+control border and 1px control padding, so its default rounded-rectangle radius
+is 10px inside the control's 12px radius.
+
 A visible parent surface does not make every child another visible card. The
 composer recipe keeps its form as the single surface, uses `PanelHeader` for
 its task hierarchy, and places field and action control edges on the shared 8px
@@ -46,16 +64,17 @@ semantic status.
 
 ## Public roles and tokens
 
-| Need                                      | Class                     | Token / default                       |
-| ----------------------------------------- | ------------------------- | ------------------------------------- |
-| Unpadded toolbar/content/footer structure | `.kui-pane`               | —                                     |
-| Scrolling pane content                    | `.kui-pane__content`      | —                                     |
-| Major vertical rhythm                     | `.kui-content`            | `--kui-layout-content-gap: 24px`      |
-| Self-contained child geometry             | `.kui-content-item`       | 8px margin + 1px border + 8px padding |
-| Pill child                                | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px`      |
-| Related controls                          | `.kui-control-cluster`    | `--kui-layout-control-gap: 8px`       |
-| Inline metadata                           | `.kui-inline-metadata`    | `--kui-layout-metadata-gap: 4px`      |
-| Explicit scroll owner outside a pane      | `.kui-scroll-owner`       | `overflow: auto`                      |
+| Need                                     | Class                     | Token / default                       |
+| ---------------------------------------- | ------------------------- | ------------------------------------- |
+| Unpadded header/content/footer structure | `Pane`, `.kui-pane`       | —                                     |
+| Scrolling pane content                   | `.kui-pane__content`      | —                                     |
+| Optional logical-edge separators         | `Pane.separators`         | `--kui-pane-separator-width: 1px`     |
+| Major vertical rhythm                    | `.kui-content`            | `--kui-layout-content-gap: 24px`      |
+| Self-contained child geometry            | `.kui-content-item`       | 8px margin + 1px border + 8px padding |
+| Pill child                               | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px`      |
+| Related controls                         | `.kui-control-cluster`    | `--kui-layout-control-gap: 8px`       |
+| Inline metadata                          | `.kui-inline-metadata`    | `--kui-layout-metadata-gap: 4px`      |
+| Explicit scroll owner outside a pane     | `.kui-scroll-owner`       | `overflow: auto`                      |
 
 The component layer applies the same contract to `Toolbar`, `ListHeader`,
 `ListItem`, `PanelHeader`, `StateBanner`, `ValueTable`,

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`.