@kerfjs/ui 4.4.1 → 4.5.0-beta.1

package/docs/ui-analyzer.md

@@ -0,0 +1,86 @@
+# 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.
+
+Recursive discovery excludes generated and tool-owned trees, including any
+nested `.claude/worktrees` checkout. Those checkouts are separate repositories,
+not application source, and cannot contribute files, diagnostics, profile
+policy, or analysis inputs to the containing application.
+
+## 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,84 @@
+# 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). This is deliberately an isolated Kerf lint pass rather than the consumer's complete ESLint configuration. Inline directives for consumer-owned 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.
+
+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.
+
+Full traversal treats generated/tool-owned directories (`dist`, `coverage`,
+`node_modules`, `.git`, `.kerf-cache`, `kerf-ui-evidence`, and nested
+`.claude/worktrees` checkouts) as outside application source. Their files are
+excluded consistently from TypeScript, the isolated ESLint pass, analyzer
+discovery, and cache inputs, even when one lives below another application
+directory.
+
+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/docs/ux-demo.md

@@ -1,18 +1,32 @@
 # UX catalog contract
 
-Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation.
+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.
+
+Seven 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 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.
-- Catalog metadata has a unique id, category, kind (`component` or `composition`), source (`kerf` or `webawesome`), name, description, and direct `uses` dependencies.
-- The master/detail shell groups first-party routes by category with production `MenuHeader` and `MenuItem` 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 constrain the expanded list to its own scroll region.
-- A detail with relationships renders one grouped selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Choosing either navigates to that component's demo. The footer is absent when both groups are empty; no duplicate relationship summary is rendered.
+- `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. Non-supported Web Awesome recommendations project to a visible `Discouraged` sidebar 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 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.
+- 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; 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; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; StateBanner exposes every built-in tone plus a scoped override; TabBar demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
-- Settings exercise light/dark, increased contrast, and reduced motion without changing component code, and expose each preference through `aria-pressed`.
-- The action log is an `aria-live` region, making interactions visible to both people and browser tests.
+- 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 with tone-tinted badges 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`.
+- 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, and covers tab selection/reordering/overflow, semantic palettes and scoped overrides, light/dark rendering, toolbar popup behavior, 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 (or the broad Web Awesome theme route) is selected. Directly addressed ecosystem URLs pass through the same loader. `npm run demo:build` enforces a 150 kB gzip ceiling for any JavaScript chunk and a 235 kB gzip ceiling for the complete JavaScript payload, so both accidental chunk collapse and aggregate growth fail the build.
+- 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.
 
 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.

package/docs/webawesome-theme.md

@@ -4,11 +4,18 @@
 free components and the Kerf/Hot Sheet 2 design system.
 
 ```ts
-import '@kerfjs/ui/webawesome.css';
-import '@awesome.me/webawesome/dist/components/button/button.js';
-import '@awesome.me/webawesome/dist/components/input/input.js';
+import type {} from "@kerfjs/ui/webawesome";
+import "@kerfjs/ui/webawesome.css";
+import "@awesome.me/webawesome/dist/components/button/button.js";
+import "@awesome.me/webawesome/dist/components/input/input.js";
 ```
 
+The type-only package import augments `kerfjs/jsx-runtime` with the 70
+catalog-supported `wa-*` elements. It has no runtime side effects. The catalog
+gate keeps the declaration tags aligned with Web Awesome's installed custom
+elements manifest, while individual component imports remain the only
+registration boundary.
+
 The CSS entry includes Web Awesome's native, utility, palette, and default-theme
 styles, then overrides the public semantic contract in
 `@layer wa-theme-overrides`. It does not import or register component
@@ -47,12 +54,82 @@ pointer targets. Override `--kui-wa-carousel-icon-size`,
 `--kui-wa-carousel-dot-hit-size` on a carousel or containing scope when a
 product needs different geometry.
 
+Form fields carry the same content-item inset as the Kerf primitives: a 1px
+border with 8px inside it (`--wa-form-control-border-width`,
+`--wa-form-control-padding-block`, and `--wa-form-control-padding-inline` are set
+to the `--kui-layout-item-border-width` / `--kui-layout-item-padding` values), so
+a single-line control lands at the standard ~40px height and the value sits 9px
+in from the field edge. Each field's top label is inset by that same border +
+padding (9px) so it lines up with the value inside the field, and is styled
+exactly like a `ListHeader` label — uppercase, `--kui-font-xs`, weight 650, quiet
+foreground. This applies to every free field that exposes a top label
+(`::part(form-control-label)` plus the Slider's `::part(label)`). OTP Input
+exposes `label` instead of `form-control-label`; the theme gives it the same
+uppercase 12px/650 treatment. Inline control labels (Checkbox, Switch) keep
+their natural sentence case.
+
+Known Date's field captions and bordered text-like field hints use the same 9px
+inline inset, keeping secondary text aligned with the value rather than the
+field's outer border. This covers Input, Known Date, Number Input, OTP Input,
+Select, Textarea, and Time Input hints; unbordered group hints retain their own
+natural geometry. OTP Input's label and hint both use the 9px field-text inset.
+
+Checkbox Group and Radio Group option regions receive the shared 8px inline
+outer inset through `::part(form-control-input)`. Unlike bordered fields, these
+groups have no shell of their own, so the explicit margin places their controls
+on the same content-item geometry without adding padding to each option. The
+Color Picker trigger receives the same 8px inline outer inset because it also
+has no bordered field shell. Slider's complete interactive region receives the
+shared 8px logical inline outer inset through `::part(slider)`, keeping its
+track, markers, references, and hint together without moving the label.
+
+Non-field chrome follows explicit, overridable control, surface, and container
+tiers:
+
+- `--kui-wa-control-inset` defaults to the 8px content-item padding. It applies
+  to tabs, tree-item trailing content, tags, and dropdown items. Tree selection
+  also uses Kerf's 8px inline outer margin, so its background reads as an inset
+  list item instead of an edge-to-edge stripe. Buttons already consume the same
+  `--wa-form-control-padding-inline` 8px value at every size, so no extra part
+  override is needed.
+- `--kui-wa-surface-margin` and `--kui-wa-surface-inset` default to 8px.
+  Accordion, Card, Details, Callout, and Include use the margin around their
+  complete surface and the inset within it. Accordion applies the outer margin
+  once to the group rather than separating connected items; Card's header,
+  body, and footer all receive the full inset.
+- `--kui-wa-container-inset` defaults to the 16px homogeneous-group step. Tab
+  Panel retains this roomier tier for unframed panel content.
+
+Badge remains intentionally compact at Web Awesome's intrinsic `0.375em` block /
+`0.625em` inline padding (4.5px / 7.5px at its default 12px text size): it is a
+short status or count, not a content item. Breadcrumb has no bordered or filled
+container, and Scroller delegates item chrome to its slotted children, so both
+retain their upstream geometry. Web Awesome 3.12's free catalog has
+`wa-dropdown-item`, but no `wa-menu-item`; the theme therefore styles the
+supported dropdown item rather than carrying a dead selector.
+
+Override a tier for a product scope after importing the theme:
+
+```css
+.roomy-editor {
+  --kui-wa-control-inset: 0.75rem;
+  --kui-wa-surface-margin: 0.75rem;
+  --kui-wa-surface-inset: 0.75rem;
+  --kui-wa-container-inset: 1.5rem;
+}
+```
+
 Accordion, Details, Breadcrumb, and Kerf Select share
 `--kui-disclosure-icon-scale` (default `.5`) so disclosure and traversal
 chevrons keep the same visual weight. The Accordion and Details components
 retain their own rotation behavior because scaling uses `transform` while
 their open state uses the independent `rotate` property.
 
+That scale applies to each Web Awesome component's intrinsic glyph and is
+independent of Kerf `DisclosureArrow`, whose default box is 18px relative to
+the root font size and whose consumer override is
+`--kui-disclosure-arrow-size`.
+
 Tooltip and Popover use arrowless floating surfaces by default, matching Hot
 Sheet 2. The theme sets Web Awesome's public `--wa-tooltip-arrow-size` token to
 `0px` and maps each popover's public `--arrow-size` property from
@@ -61,12 +138,12 @@ subtree, or for one instance after the theme import:
 
 ```css
 :root {
-  --wa-tooltip-arrow-size: .375rem;
-  --kui-wa-popover-arrow-size: .375rem;
+  --wa-tooltip-arrow-size: 0.375rem;
+  --kui-wa-popover-arrow-size: 0.375rem;
 }
 
 .pointed-popover {
-  --arrow-size: .5rem;
+  --arrow-size: 0.5rem;
 }
 ```
 
@@ -129,6 +206,9 @@ static content and labels that constraint next to the rendered output.
 
 The catalog lists every free Web Awesome component so support can be inspected;
 listing does not make each component the preferred Kerf application pattern.
+The [need-first decision matrix](./component-selection.md#web-awesome-overlap-policy)
+is the exhaustive Kerf/Web Awesome overlap index; the rules below explain the
+highest-risk choices.
 
 - Consider `wa-popup` for low-level anchored positioning when its flip, shift,
   or placement behavior avoids custom positioning code. Prefer the higher-level
@@ -164,7 +244,7 @@ smallest subtree that needs a different identity:
 :root {
   --wa-color-brand-fill-loud: #7540a8;
   --wa-color-focus: #7540a8;
-  --wa-form-control-border-radius: .5rem;
+  --wa-form-control-border-radius: 0.5rem;
 }
 
 .billing-workspace {

package/docs/workbench.md

@@ -0,0 +1,73 @@
+# Workbench
+
+`@kerfjs/ui/workbench` is the Xcode-like multi-panel workspace: a collapsible
+left rail, right rail, and bottom drawer around a central work area (any absent).
+It generalizes the instant-width / sliding-content collapse used by the catalog
+sidebar. One of the opt-in app layouts (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)); best on
+desktop-class devices.
+
+```ts
+import { Workbench } from "@kerfjs/ui/workbench";
+import "@kerfjs/ui/workbench.css";
+```
+
+## State lives in the app
+
+`Workbench` is declarative and the collapse is **pure CSS** — no wire. The app
+owns each panel's `collapsed` flag (usually a signal) and toggles it; the panel
+animates itself.
+
+```tsx
+const navCollapsed = signal(false);
+
+<Workbench
+  id="studio"
+  label="Studio"
+  main={<Editor />}
+  leftRail={{
+    content: <Navigator />,
+    label: "Navigator",
+    collapsed: navCollapsed.value,
+    size: 280,
+  }}
+  rightRail={{
+    content: <Inspector />,
+    label: "Inspector",
+    collapsed: inspectorCollapsed.value,
+  }}
+  bottomDrawer={{
+    content: <Console />,
+    label: "Console",
+    collapsed: consoleCollapsed.value,
+  }}
+/>;
+```
+
+Each `WorkbenchPanel` takes `content`, an optional `collapsed`, an optional
+`size` (rail width or drawer height in px, overriding the CSS default —
+`--kui-workbench-rail-width` 280px, `--kui-workbench-drawer-height` 220px), and
+an optional `label`.
+
+## Public styling boundary
+
+Import `@kerfjs/ui/workbench.css` after the component subpath. Applications may
+set `--kui-workbench-rail-width` and `--kui-workbench-drawer-height` on a
+Workbench instance. The supported composition classes are `.kui-workbench`,
+`.kui-workbench__rail`, `.kui-workbench__rail--left`,
+`.kui-workbench__rail--right`, `.kui-workbench__center`,
+`.kui-workbench__main`, `.kui-workbench__drawer`, and
+`.kui-workbench__panel-content`; these exact hooks are cataloged for tools that
+must classify public application selectors. Prefer the component props and two
+size tokens before selecting internal anatomy, and do not target its data
+attributes or descendant tags as styling contracts.
+
+## How the collapse animates
+
+Collapsing snaps the panel's flex track to zero in a single reflow (so the work
+area relayouts once, not per frame) while the panel's fixed-size content slides
+out via a composited `transform` — a rail slides horizontally, the drawer
+vertically — clipped by the shell's overflow. It honors `prefers-reduced-motion`
+(the slide collapses to instant). On smaller device classes, present the rails'
+contents through a `NavStack` or overlay drawers rather than shrinking the
+three-panel shell.