@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/README.md

@@ -4,11 +4,57 @@ Accessible, composable UI primitives for [kerf](https://github.com/brianwestphal
 
 Start interface work with the [need-first component selection matrix](./docs/component-selection.md). It distinguishes direct reuse, composition, thin application adapters, and genuinely custom semantics, with imports, required wiring, application ownership, alternatives, and recipes for every public primitive.
 
-For connective application patterns, use the seven [production composition
+When adding a first-party public component, follow the
+[component integration workflow](./docs/component-integration.md). The catalog
+entry drives one validator across package, build, barrel, CSS, demo, route, and
+AI signature projections, with a non-mutating dry-run report.
+
+### Shared semantic tones
+
+`SemanticTone` is the shared color-role type for `Badge`, `Chip`, `StateBanner`,
+and semantic `ContentItem` appearances: `neutral`, `info`, `pop`, `success`,
+`warning`, and `danger`. Import it as a type from `@kerfjs/ui`,
+`@kerfjs/ui/badge`, `@kerfjs/ui/state-banner`, or `@kerfjs/ui/content-item`.
+Use `info` for the role backed by the existing `--kui-color-brand-*` tokens.
+Migrate Badge/Chip `tone="brand"` to `tone="info"`; `BadgeTone` and
+`StateBannerTone` remain deprecated aliases of `SemanticTone`.
+
+## Source organization
+
+The flat files directly under `src/` are stable package entry facades. Keep
+component implementation and CSS together under
+`src/components/<family>/<component>/`. Put support code used by one component
+in its `internal/`, `model/`, `register/`, or `wiring/` folder. Shared types and
+utilities live under `src/shared/`; wiring that spans several components lives
+under `src/wiring/`; Web Awesome integration code lives under
+`src/integrations/`. Catalog-only implementation remains under `src/catalog/`.
+
+Choose an existing family by the component role, and add a family only when no
+current one fits. Public JavaScript and CSS subpaths remain flat through their
+root facades. `npm run check:source-organization` rejects implementation added
+back to the root or component-local support code placed in the wrong folder.
+
+Browser verification always builds current source: both `npm run test:e2e`
+and direct focused Playwright commands run the catalog/conformance preflights
+and production build before preview. See the [UX catalog contract](./docs/ux-demo.md).
+Failed Playwright tests retain traces and screenshots alongside an HTML report.
+CI runs the complete suite in concurrent Chromium, Firefox, and WebKit jobs,
+while the `ui` job checks the package. A failing browser job uploads its report
+and per-test evidence for 14 days as
+`ui-browser-failure-<browser>-<run>-<attempt>`.
+
+When authoring a component gallery, follow the single
+[Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)
+for focused-versus-composition modes, helper nesting, specimen selection,
+geometry inspection, and metadata ownership. AI tools can discover that
+contract and its public imports through the shipped
+[`catalog-authoring.json`](./ai/catalog-authoring.json) artifact.
+
+For connective application patterns, use the eleven [production composition
 recipes](./docs/recipes.md). Each has a stable catalog route, runnable state,
 public-subpath source, semantic layout ownership, and explicit application
 customization boundaries. The composer recipe demonstrates one coherent form
-surface with `PanelHeader` hierarchy and field/action controls aligned to the
+surface with a `Toolbar`/`ToolbarText` heading and field/action controls aligned to the
 shared 8px gutter; only persistent feedback adds a nested semantic
 `StateBanner` surface.
 
@@ -23,57 +69,90 @@ npm install kerfjs @kerfjs/ui
 ```
 
 ```tsx
-import { ListItem } from '@kerfjs/ui/list-item';
-import { ListHeader } from '@kerfjs/ui/list-header';
-import { ListActionRow } from '@kerfjs/ui/list-action-row';
-import { Toolbar } from '@kerfjs/ui/toolbar';
-import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
-import { ToolbarText } from '@kerfjs/ui/toolbar-text';
-
-mount(root, () => <>
-  <Toolbar label="Document" leading={<ToolbarControlGroup appearance="borderless" single><ToolbarText text="Notes" /></ToolbarControlGroup>} />
-  <section>
-    <ListHeader
-      label="Workspace"
-      action="show-workspace-actions"
-      actionLabel="Workspace actions"
-      rootAttributes={{ 'data-section-id': 'workspace' }}
-      triggerAttributes={{
-        popoverTarget: 'workspace-actions',
-        popoverTargetAction: 'toggle',
-        'aria-controls': 'workspace-actions',
-        'aria-haspopup': 'dialog',
-      }}
-    />
-    <ListItem
-      action="open-notes"
-      label="Notes"
-      selected
-      rootAttributes={{ 'data-command-color': 'blue', 'data-drop-status': 'ready' }}
+import { mount } from "kerfjs";
+import { ListItem } from "@kerfjs/ui/list-item";
+import { ListHeader } from "@kerfjs/ui/list-header";
+import { ListActionRow } from "@kerfjs/ui/list-action-row";
+import { Toolbar } from "@kerfjs/ui/toolbar";
+import { ToolbarText } from "@kerfjs/ui/toolbar-text";
+
+const root = document.getElementById("app")!;
+
+mount(root, () => (
+  <>
+    <Toolbar
+      label="Document"
+      leading={<ToolbarText text="Notes" />}
     />
-    <ListActionRow
-      action="open-file"
-      itemId="src/main.ts"
-      label="src/main.ts"
-      trailingAction="open-file-actions"
-      trailingActionLabel="Actions for src/main.ts"
-      trailingActionIcon={moreIcon}
-    />
-    <div id="workspace-actions" popover="auto">Application-owned actions</div>
-  </section>
-</>);
+    <section>
+      <ListHeader
+        label="Workspace"
+        action="show-workspace-actions"
+        actionLabel="Workspace actions"
+        rootAttributes={{ "data-section-id": "workspace" }}
+        triggerAttributes={{
+          popoverTarget: "workspace-actions",
+          popoverTargetAction: "toggle",
+          "aria-controls": "workspace-actions",
+          "aria-haspopup": "dialog",
+        }}
+      />
+      <ListItem
+        action="open-notes"
+        label="Notes"
+        selected
+        rootAttributes={{
+          "data-command-color": "blue",
+          "data-drop-status": "ready",
+        }}
+      />
+      <ListActionRow
+        action="open-file"
+        itemId="src/main.ts"
+        label="src/main.ts"
+        trailingAction="open-file-actions"
+        trailingActionLabel="Actions for src/main.ts"
+        trailingActionIcon={<span aria-hidden="true">⋯</span>}
+      />
+      <div id="workspace-actions" popover="auto">
+        Application-owned actions
+      </div>
+    </section>
+  </>
+));
 ```
 
 Components return Kerf `SafeHtml`. They do not own application state or attach transient listeners. Actions are stable `data-action` hooks; the application wires them once with `delegate()` or `delegateActions()` and retains the disposer.
 
+Component content positions use one convention: `children` is the homogeneous
+primary region, while semantic positions and replacement content use explicit
+named `SafeHtml` props such as `header`, `footer`, `leading`, `trailing`,
+`icon`, and `action`. These named `SafeHtml` prop slots are ordinary typed
+function-component props—not native `<slot>` elements, wrapper slot
+components, or a generic `slots` object. The composition catalog publishes
+sound prop bindings as `zone.jsx.prop`, allowing ESLint to validate statically
+visible content and cardinality without guessing from zone names.
+
+Stable single-root visual components also accept the explicit native
+`slot?: string` prop, so their returned root can participate directly in a web
+component's named slot and keep that assignment through Kerf rerenders. This is
+a narrow interop attribute, not general native-attribute spreading. The
+multi-root `ResizableRegion` and `CollapsiblePanel` intentionally omit it
+because neither has one unambiguous returned root; `CollapsiblePanelToggle`
+supports it as a normal single-root control.
+
 `ListItem.rootAttributes`, `ListHeader.rootAttributes`,
-`ListActionRow.rootAttributes`, and `AppTab.rootAttributes` carry typed
+`ListActionRow.rootAttributes`, `TabBarItem.rootAttributes`,
+`Catalog.stageRootAttributes`, `CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` carry typed
 application `data-*` metadata without
 teaching the package domain fields. `ListHeader.triggerAttributes` and
 `ListActionRow.trailingActionAttributes` additionally support native popover
 target and relationship attributes. Roles and component-owned action, selection,
-disclosure, naming, disabled, and icon semantics remain protected props; an
+disclosure, naming, disabled, icon, and catalog-structure semantics remain protected props; an
 isolated `role="menuitem"` is not an extension shortcut.
+`CatalogExample.viewport` owns the finite layout constraints needed by focused
+specimens, so catalog authors do not need route-local stylesheets, inline
+styles, or styling-only demo classes.
 The slots are also filtered at runtime, so structurally widened objects and
 JavaScript callers cannot bypass those protections with case-variant names.
 `ListItem.trailing` is dormant metadata. Use `ListActionRow` when a row needs
@@ -90,47 +169,186 @@ Do not concatenate a count into `label` or pass a numeric `badge`; the mutually
 exclusive legacy `badge` slot remains available for non-count `SafeHtml` such
 as a `New` marker.
 
+`Row.gap`, `Grid.gap`, `List.gap`, and `Spacer` dimensions accept a direct spacing name such as
+`gap="xs"` or `gap="m"`, or a branded `CssLength`. Import `space`, `rem`, `em`,
+`px`, `pct`, `lengthVar`, `plus`, and `calc` from the CSS-free
+`@kerfjs/ui/css-values` subpath when a named step is not enough. `plus` returns
+an incomplete expression, so wrap it with `calc` before passing it to a prop.
+Raw CSS strings are deliberately rejected; the opaque brands catch authoring
+mistakes but are not sanitizers.
+
+Use `Row` for horizontal flex composition and `List` for vertical composition.
+Both accept `hAlign` (`left`, `center`, `right`, `full`) and `vAlign` (`top`,
+`middle`, `bottom`, `full`), plus their documented short/CSS aliases. `Row`
+also accepts `vAlign="baseline"` for cross-axis text alignment; baseline is not
+available on `List`, whose vertical axis uses `justify-content`. `Row`
+defaults to left/full alignment, the `xs` gap, and `wrap={false}`; List keeps
+its existing full/top alignment and zero-gap defaults. Set `textInsets` or
+`controlInsets` with canonical physical sides in `t`/`r`/`b`/`l` order (for
+example, `textInsets="tbl"` or `controlInsets="r"`). Text geometry takes
+precedence where both select the same side. `ListInsetText` and
+`ListInsetControl` inset all four sides by default and accept the same `sides`
+grammar for selective insets. Nested Rows and Lists resolve their inset sides
+independently, so an unselected inner side does not inherit its parent's inset.
+
+Use `Grid` for a fixed positive number of evenly distributed columns. Its
+`minmax(0, 1fr)` tracks stay equal when children have different intrinsic
+widths; the application owns responsive count changes. Use application CSS grid
+for asymmetric or intrinsic tracks and `ResizableRegion` for adjustable ones.
+
+The same property-specific boundary applies beyond spacing: use `flex()` (or a
+finite keyword) for `Row.flex`, `Grid.flex`, and `List.flex`; length builders and intrinsic-size keywords for
+`Skeleton.width`/`height`; length builders for `Skeleton.radius`; and
+a foreground color for `SelectChoice.color` — `uiColor()` with a foreground
+token such as `success-on-quiet`, or `foregroundColorVar()` (fill tokens such
+as `uiColor('success-fill-quiet')` are rejected). These grammars are not
+interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
+`style` declarations; use `className`, public tokens, and component props.
+
 ## Component subpaths
 
-| Component | Browser import (includes reachable CSS) | Manual CSS export |
-| --- | --- | --- |
-| `LucideIcon` | `@kerfjs/ui/lucide-icon` | `@kerfjs/ui/lucide-icon.css` |
-| `DisclosureArrow` | `@kerfjs/ui/disclosure-arrow` | `@kerfjs/ui/disclosure-arrow.css` |
-| `Toolbar` | `@kerfjs/ui/toolbar` | `@kerfjs/ui/toolbar.css` |
-| `ToolbarControlGroup` | `@kerfjs/ui/toolbar-control-group` | `@kerfjs/ui/toolbar-control-group.css` |
-| `FloatingToolbar` | `@kerfjs/ui/floating-toolbar` | `@kerfjs/ui/floating-toolbar.css` |
-| `ToolbarText` | `@kerfjs/ui/toolbar-text` | `@kerfjs/ui/toolbar-text.css` |
-| `ListActionRow` | `@kerfjs/ui/list-action-row` | `@kerfjs/ui/list-action-row.css` |
-| `ListItem` | `@kerfjs/ui/list-item` | `@kerfjs/ui/list-item.css` |
-| `ListHeader` | `@kerfjs/ui/list-header` | `@kerfjs/ui/list-header.css` |
-| Pane, content, and navigation composition | — | `@kerfjs/ui/layout.css` |
-| `ResizableRegion` | `@kerfjs/ui/resizable-region` | `@kerfjs/ui/resizable-region.css` |
-| `wireResizableRegions` | `@kerfjs/ui/wire-resizable-regions` | — |
-| `AppTab` | `@kerfjs/ui/app-tab` | `@kerfjs/ui/app-tab.css` |
-| `TabBar` | `@kerfjs/ui/tab-bar` | `@kerfjs/ui/tab-bar.css` |
-| `wireTabBars`, `reorderTabs` | `@kerfjs/ui/wire-tab-bars` | — |
-| `LoadingSpinner` | `@kerfjs/ui/loading-spinner` | `@kerfjs/ui/loading-spinner.css` |
-| `Skeleton` | `@kerfjs/ui/skeleton` | `@kerfjs/ui/skeleton.css` |
-| `Select` | `@kerfjs/ui/select` | `@kerfjs/ui/select.css` |
-| `SegmentedControl` | `@kerfjs/ui/segmented-control` | `@kerfjs/ui/segmented-control.css` |
-| `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret` | `@kerfjs/ui/token-search-field` | `@kerfjs/ui/token-search-field.css` |
-| `wireTokenSearchFields` | `@kerfjs/ui/wire-token-search-fields` | — |
-| `StateBanner` | `@kerfjs/ui/state-banner` | `@kerfjs/ui/state-banner.css` |
-| `EmptyState` | `@kerfjs/ui/empty-state` | `@kerfjs/ui/empty-state.css` |
-| `PanelHeader` | `@kerfjs/ui/panel-header` | `@kerfjs/ui/panel-header.css` |
-| `ValueTable`, `ValueTableRow` | `@kerfjs/ui/value-table` | `@kerfjs/ui/value-table.css` |
-
-`PanelHeader` is a plain `Toolbar` used as a panel, dialog, or page heading: an
-optional icon control group (given a brand fill with a matching border), the
-title as extra-large `ToolbarText`, the app's trailing action controls, and an
-optional subtitle on a separate row below the title. It overrides no toolbar
-styles — the app passes its own trailing controls (typically a
-`ToolbarControlGroup`).
-
-`DisclosureArrow` defaults to an 18px root-scaled decorative visual. Override
-`--kui-disclosure-arrow-size` at the narrowest useful scope when a consumer
-needs another size; the owning control still supplies interaction, naming, and
-expanded state. Kerf `Select` retains its independent Web Awesome expand-glyph
+| Component                                                    | Browser import (includes reachable CSS) | Manual CSS export                        |
+| ------------------------------------------------------------ | --------------------------------------- | ---------------------------------------- |
+| `LucideIcon`                                                 | `@kerfjs/ui/lucide-icon`                | `@kerfjs/ui/lucide-icon.css`             |
+| `Badge`                                                      | `@kerfjs/ui/badge`                      | `@kerfjs/ui/badge.css`                   |
+| `Chip`                                                       | `@kerfjs/ui/chip`                       | `@kerfjs/ui/chip.css`                    |
+| `DisclosureArrow`                                            | `@kerfjs/ui/disclosure-arrow`           | `@kerfjs/ui/disclosure-arrow.css`        |
+| `Toolbar`                                                    | `@kerfjs/ui/toolbar`                    | `@kerfjs/ui/toolbar.css`                 |
+| `ToolbarControlGroup`, `ToolbarActionLink`                   | `@kerfjs/ui/toolbar-control-group`      | `@kerfjs/ui/toolbar-control-group.css`   |
+| `DialogSurface`, `PopupSurface`                              | `@kerfjs/ui/surface-scaffold`           | `@kerfjs/ui/surface-scaffold.css`        |
+| `ListDetailDialog`                                           | `@kerfjs/ui/list-detail-dialog`         | `@kerfjs/ui/list-detail-dialog.css`      |
+| `WorkbenchDialog`                                            | `@kerfjs/ui/workbench-dialog`           | `@kerfjs/ui/workbench-dialog.css`        |
+| `Disclosure`                                                 | `@kerfjs/ui/disclosure`                 | `@kerfjs/ui/disclosure.css`              |
+| `ProgressBar`                                                | `@kerfjs/ui/progress-bar`               | `@kerfjs/ui/progress-bar.css`            |
+| `ProgressRing`                                               | `@kerfjs/ui/progress-ring`              | `@kerfjs/ui/progress-ring.css`           |
+| `Slider`                                                     | `@kerfjs/ui/slider`                     | `@kerfjs/ui/slider.css`                  |
+| `wireSliders`, `syncSlider`                                  | `@kerfjs/ui/wire-sliders`               | —                                        |
+| `TagField`                                                   | `@kerfjs/ui/tag-field`                  | `@kerfjs/ui/tag-field.css`               |
+| `wireTagFields`                                              | `@kerfjs/ui/wire-tag-fields`            | —                                        |
+| `ColorSwatches`                                              | `@kerfjs/ui/color-swatches`             | `@kerfjs/ui/color-swatches.css`          |
+| `ColorPicker`                                                | `@kerfjs/ui/color-picker`               | `@kerfjs/ui/color-picker.css`            |
+| `wireColorPickers`                                           | `@kerfjs/ui/wire-color-pickers`         | —                                        |
+| `ColorField`                                                 | `@kerfjs/ui/color-field`                | `@kerfjs/ui/color-field.css`             |
+| `wireColorFields`                                            | `@kerfjs/ui/wire-color-fields`          | —                                        |
+| `FloatingToolbar`                                            | `@kerfjs/ui/floating-toolbar`           | `@kerfjs/ui/floating-toolbar.css`        |
+| `PopupMenu` (register with `@kerfjs/ui/popup-menu/register`) | `@kerfjs/ui/popup-menu`                 | `@kerfjs/ui/popup-menu.css`              |
+| `openAnchoredSurface`, `openAnchoredSurfaceAt`               | `@kerfjs/ui/anchored-surface`           | `@kerfjs/ui/anchored-surface.css`        |
+| `ToolbarText`                                                | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`            |
+| `Text`, `FieldLabel`                                         | `@kerfjs/ui/text`                       | `@kerfjs/ui/text.css`                    |
+| `List`                                                       | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                    |
+| `Row`                                                        | `@kerfjs/ui/row`                        | `@kerfjs/ui/row.css`                     |
+| `Grid`                                                       | `@kerfjs/ui/grid`                       | `@kerfjs/ui/grid.css`                    |
+| `Spacer`                                                     | `@kerfjs/ui/spacer`                     | `@kerfjs/ui/spacer.css`                  |
+| Typed CSS dimension builders                                 | `@kerfjs/ui/css-values`                 | —                                        |
+| `ListActionRow`                                              | `@kerfjs/ui/list-action-row`            | `@kerfjs/ui/list-action-row.css`         |
+| `ListItem`                                                   | `@kerfjs/ui/list-item`                  | `@kerfjs/ui/list-item.css`               |
+| `wireListReorder`, `reorderListItems`                        | `@kerfjs/ui/wire-list-reorder`          | —                                        |
+| `wireListFocusScroll`                                        | `@kerfjs/ui/wire-list-focus-scroll`     | —                                        |
+| `ListHeader`                                                 | `@kerfjs/ui/list-header`                | `@kerfjs/ui/list-header.css`             |
+| `ListInsetControl`                                           | `@kerfjs/ui/list-inset-control`         | `@kerfjs/ui/list-inset-control.css`      |
+| `ListInsetText`                                              | `@kerfjs/ui/list-inset-text`            | `@kerfjs/ui/list-inset-text.css`         |
+| `ContentItem`                                                | `@kerfjs/ui/content-item`               | `@kerfjs/ui/content-item.css`            |
+| `Pane`                                                       | `@kerfjs/ui/pane`                       | `@kerfjs/ui/pane.css`                    |
+| `NavStack`                                                   | `@kerfjs/ui/nav-stack`                  | `@kerfjs/ui/nav-stack.css`               |
+| `wireNavStack`                                               | `@kerfjs/ui/wire-nav-stack`             | —                                        |
+| `wirePaneChrome`                                             | `@kerfjs/ui/wire-pane-chrome`           | —                                        |
+| `SplitView`                                                  | `@kerfjs/ui/split-view`                 | `@kerfjs/ui/split-view.css`              |
+| `TabNavigator`                                               | `@kerfjs/ui/tab-navigator`              | `@kerfjs/ui/tab-navigator.css`           |
+| `wireTabNavigator`                                           | `@kerfjs/ui/wire-tab-navigator`         | —                                        |
+| `Workbench`                                                  | `@kerfjs/ui/workbench`                  | `@kerfjs/ui/workbench.css`               |
+| `wireWorkbench`                                              | `@kerfjs/ui/wire-workbench`             | —                                        |
+| `CollapsiblePanel`, `CollapsiblePanelToggle`                 | `@kerfjs/ui/collapsible-panel`          | `@kerfjs/ui/collapsible-panel.css`       |
+| `wireSidebar`                                                | `@kerfjs/ui/wire-sidebar`               | —                                        |
+| Content and navigation composition                           | —                                       | `@kerfjs/ui/layout.css`                  |
+| `ResizableRegion`                                            | `@kerfjs/ui/resizable-region`           | `@kerfjs/ui/resizable-region.css`        |
+| `wireResizableRegions`                                       | `@kerfjs/ui/wire-resizable-regions`     | —                                        |
+| `TabBarItem`                                                 | `@kerfjs/ui/tab-bar-item`               | `@kerfjs/ui/tab-bar-item.css`            |
+| `TabBar`                                                     | `@kerfjs/ui/tab-bar`                    | `@kerfjs/ui/tab-bar.css`                 |
+| `wireTabBars`, `reorderTabs`                                 | `@kerfjs/ui/wire-tab-bars`              | —                                        |
+| `wireScrollDividers`                                         | `@kerfjs/ui/wire-scroll-dividers`       | —                                        |
+| `wireToolbarVisibility`                                      | `@kerfjs/ui/wire-toolbar-visibility`    | —                                        |
+| `wireOverlaySheets`                                          | `@kerfjs/ui/wire-overlay-sheets`        | `@kerfjs/ui/overlay-sheet.css`           |
+| Toasts for `kerfjs/overlay` `toast()`                        | —                                       | `@kerfjs/ui/overlay-toast.css`           |
+| Tooltips for `kerfjs/overlay` `tooltip()`                    | —                                       | `@kerfjs/ui/overlay-tooltip.css`         |
+| `LoadingSpinner`                                             | `@kerfjs/ui/loading-spinner`            | `@kerfjs/ui/loading-spinner.css`         |
+| `Skeleton`                                                   | `@kerfjs/ui/skeleton`                   | `@kerfjs/ui/skeleton.css`                |
+| `SunkenPanel`                                                | `@kerfjs/ui/sunken-panel`               | `@kerfjs/ui/sunken-panel.css`            |
+| `BackdropImage`                                              | `@kerfjs/ui/backdrop-image`             | `@kerfjs/ui/backdrop-image.css`          |
+| `Select`                                                     | `@kerfjs/ui/select`                     | `@kerfjs/ui/select.css`                  |
+| `SegmentedControl`                                           | `@kerfjs/ui/segmented-control`          | `@kerfjs/ui/segmented-control.css`       |
+| `ChoiceChips`                                                | `@kerfjs/ui/choice-chips`               | `@kerfjs/ui/choice-chips.css`            |
+| `TextField`                                                  | `@kerfjs/ui/text-field`                 | `@kerfjs/ui/text-field.css`              |
+| `wireTextFields`                                             | `@kerfjs/ui/wire-text-fields`           | —                                        |
+| `Checkbox`                                                   | `@kerfjs/ui/checkbox`                   | `@kerfjs/ui/checkbox.css`                |
+| `CheckboxGroup`                                              | `@kerfjs/ui/checkbox-group`             | `@kerfjs/ui/checkbox-group.css`          |
+| `wireCheckboxes`                                             | `@kerfjs/ui/wire-checkboxes`            | —                                        |
+| `RadioGroup`                                                 | `@kerfjs/ui/radio-group`                | `@kerfjs/ui/radio-group.css`             |
+| `Switch`                                                     | `@kerfjs/ui/switch`                     | `@kerfjs/ui/switch.css`                  |
+| `MessageComposer`                                            | `@kerfjs/ui/message-composer`           | `@kerfjs/ui/message-composer.css`        |
+| `wireMessageComposers`                                       | `@kerfjs/ui/wire-message-composers`     | —                                        |
+| `SearchField`, `readSearchField`, `placeSearchFieldCaret`    | `@kerfjs/ui/search-field`               | `@kerfjs/ui/search-field.css`            |
+| `wireSearchFields`                                           | `@kerfjs/ui/wire-search-fields`         | —                                        |
+| `createSearchFieldModel`                                     | `@kerfjs/ui/search-field-model`         | —                                        |
+| `StateBanner`                                                | `@kerfjs/ui/state-banner`               | `@kerfjs/ui/state-banner.css`            |
+| `Button`                                                     | `@kerfjs/ui/button`                     | `@kerfjs/ui/button.css`                  |
+| `SplitButton`                                                | `@kerfjs/ui/split-button`               | `@kerfjs/ui/split-button.css`            |
+| `FramedList`, `FramedListRow`                                | `@kerfjs/ui/framed-list`                | `@kerfjs/ui/framed-list.css`             |
+| `SummaryRow`                                                 | `@kerfjs/ui/summary-row`                | `@kerfjs/ui/summary-row.css`             |
+| `ColumnTrack`                                                | `@kerfjs/ui/column-track`               | `@kerfjs/ui/column-track.css`            |
+| `ContentSwap`                                                | `@kerfjs/ui/content-swap`               | `@kerfjs/ui/content-swap.css`            |
+| `FilePickerTrigger`, `FileDropZone`                          | `@kerfjs/ui/file-picker`                | `@kerfjs/ui/file-picker.css`             |
+| `wireFilePickers`, `fileMatchesAccept`                       | `@kerfjs/ui/wire-file-pickers`          | —                                        |
+| `Combobox`                                                   | `@kerfjs/ui/combobox`                   | `@kerfjs/ui/combobox.css`                |
+| `wireComboboxes`                                             | `@kerfjs/ui/wire-comboboxes`            | —                                        |
+| `CornerStatus`                                               | `@kerfjs/ui/corner-status`              | `@kerfjs/ui/corner-status.css`           |
+| `EdgeActivityIndicator`                                      | `@kerfjs/ui/edge-activity-indicator`    | `@kerfjs/ui/edge-activity-indicator.css` |
+| `wireCornerStatus`                                           | `@kerfjs/ui/wire-corner-status`         | —                                        |
+| `EmptyState`                                                 | `@kerfjs/ui/empty-state`                | `@kerfjs/ui/empty-state.css`             |
+| `ValueTable`, `ValueTableRow`                                | `@kerfjs/ui/value-table`                | `@kerfjs/ui/value-table.css`             |
+
+Application layouts are separate component subpaths. Browser-condition imports
+include their reachable CSS; use the matching manual CSS export when your
+bundler does not select the browser condition. Add a wire subpath when the
+layout has interactive behavior. The catalog
+entries for `nav-stack`, `split-view`, `tab-navigator`, `workbench`, and
+`collapsible-panel` document their selection rules, ownership boundaries,
+public classes, tokens, and focused demos. See
+[`docs/app-layouts.md`](./docs/app-layouts.md) for the layout decision matrix.
+`NavStack` and `TabNavigator` expose `chromeDividers="scroll" | "always" |
+"none"` for their chrome lines; `SplitView` forwards the setting to its
+compact stack. A sole `Pane` in a view or scene fills it, keeping the Pane's
+header in place while its own content scrolls.
+
+For a `Workbench` or `CollapsiblePanel`, place panel toolbar groups in its
+`leading`, `center`, and `trailing` zones. Add `relocateOnCollapse` to each
+`ToolbarControlGroup` that should remain available in the work-area toolbar
+while the panel is closed. The panel collects marked groups in zone order;
+its toggle follows them. See [Workbench panel toolbars](./docs/workbench.md#panel-toolbars).
+
+Compose panel, dialog, and page headings directly with `Toolbar`: put an optional
+icon in a `ToolbarControlGroup`, use a direct extra-large `ToolbarText` for the
+title, and put actions in the trailing zone inside their own control group. Set
+`headingLevel` for page or section headings. Supporting copy is app-owned content
+below the toolbar and should be connected to its host with `aria-describedby`
+when it adds useful context. Set `responsive="wrap"` on a heading whose title
+must stay whole: it keeps one row while everything fits and otherwise moves the
+trailing actions below the title instead of truncating it.
+
+A toolbar with a single zone gives it the whole content box, so content set to
+fill the row reaches both insets; an absent zone leaves no empty track or gap.
+
+A toolbar never clips an action. Its trailing zone wraps whole control groups
+onto another trailing-aligned row under every `responsive` policy, and a
+`responsive="stack"` toolbar wraps its stacked center and trailing groups the
+same way. Wrapping keeps every command visible at its full 44px target without
+moving focus or DOM identity. When a product wants fewer visible commands at
+narrow widths, it chooses them: render a lower-priority command inside an
+app-owned "More" `PopupMenu` (in a `single` group with `nestedDropdown`).
+
+`DisclosureArrow` defaults to an 18px root-scaled decorative visual. Pass a
+typed `size` (for example `size={remify(24)}` from `@kerfjs/ui/css-values`)
+when a consumer needs another size; the owning control still supplies interaction, naming, and
+expanded state. Kerf `Select` keeps its own expand-glyph
 scale of `.5` through `--kui-disclosure-icon-scale`. Author replacement
 `DisclosureArrow` icon content facing right before its configured direction
 transform is applied. Direction changes take the shortest rotation path; a
@@ -141,20 +359,172 @@ transform is applied. Direction changes take the shortest rotation path; a
 real controlled content and preserve the button's stable label; ordinary
 navigation must not display a disclosure arrow. A custom `actionIcon` remains
 an escape hatch and replaces the default arrow entirely. The header fills its
-available inline width, keeping a separate action at the logical end in a 44px
-target. Its visible action glyph defaults to 18px through
+available inline width by default; set `inline` to shrink-wrap it beside other
+content and remove its root margin, border, and padding. It keeps a separate
+action at the logical end. Its visible action glyph defaults to 18px through
 `--kui-list-header-action-icon-size`.
 
 ## Machine-readable catalog
 
-AI tools can retrieve the shipped [`ai/component-catalog.json`](./ai/component-catalog.json)
+AI assistants should start from the generated markdown reference,
+[`ai/components/README.md`](./ai/components/README.md): a one-line index of
+every entry grouped like the catalog, plus one short page per entry
+(`ai/components/<id>.md`) covering when to use and avoid it, imports and
+CSS/registration side effects, where its exact props live, legal parents,
+zones with their JSX props and child counts, app- and wiring-owned state,
+geometry ownership, accessibility obligations, the styling boundary
+(configure through props; never override internals), and its composition
+diagnostics. The pages are projected from the two JSON catalogs by
+`scripts/sync-component-docs.mjs` (`npm run catalog:sync`), and
+`npm run check:catalog` fails when any page drifts.
+
+Tools can retrieve the shipped [`ai/component-catalog.json`](./ai/component-catalog.json)
 for the exhaustive component and composition inventory. It is the canonical
 source for ids, public exports, purpose and selection guidance, relationships,
 delivery and side effects, companion wiring, application-owned policy,
 variants, accessibility obligations, public CSS hooks, routes, and current
 documentation/recipe links. The adjacent
 [`component-catalog.schema.json`](./ai/component-catalog.schema.json) describes
-the versioned format.
+the versioned format. Every visual entry also declares who owns its margin,
+border, and padding, so a generator can fit it into Kerf's alignment model
+without guessing from a screenshot or private CSS.
+
+Catalog demo authoring is deliberately separate from the entry inventory. Load
+[`catalog-authoring.json`](./ai/catalog-authoring.json) to discover the
+authoritative [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract),
+the exact API-signature context, public imports/helpers, sanctioned metadata
+slot, three-kind taxonomy, and functional-group/importance ordering policy.
+Keeping this as a companion artifact prevents per-entry selection facts from
+duplicating presentation rules.
+
+Tools that evaluate composition may additionally load
+[`component-composition.json`](./ai/component-composition.json). It is a
+generated composition layer beside `component-catalog.json`, not a newer
+version of it: a deterministic, package-qualified projection of every
+component-catalog entry with formal parent/context, zone/cardinality, child,
+state ownership, wiring, responsive, layout, accessibility, public-boundary,
+and stable-diagnostic fields. `component-catalog.json` remains the selection
+and delivery surface. Composition defaults are
+deliberately permissive; only documented objective rules receive an
+authoritative override and enforceable diagnostic. The adjacent schema and
+[`component-composition.d.ts`](./ai/component-composition.d.ts) types describe
+the same contract.
+
+Applications and downstream design systems should publish the same facts for
+their own components. Start from the reusable
+[`component-catalog-extension.schema.json`](./ai/component-catalog-extension.schema.json)
+and the checked
+[`component-catalog-extension.json`](./docs/examples/component-catalog-extension.json)
+example. Give each app-owned component or composition a stable id, selection
+guidance, public hooks, and explicit geometry ownership; then concatenate its
+`entries` with Kerf's shipped `entries` in the AI context. Keep package/source
+identity alongside each input when ids could collide. This makes a combined
+tool reason about both sides of a composition using one vocabulary without
+pretending app-local components are `@kerfjs/ui` exports. A package that
+keeps a `kerf.components.json` generates this extension with
+`kerf-component-catalog` by setting `kerfComponentCatalog.selectionOutput`
+instead of maintaining a second JSON by hand.
+For a consumer UX demo, `@kerfjs/ui/catalog-projection` derives rows and
+relationships from that extension; `kerf-catalog-demo --write` emits a typed
+module and `--check` catches drift. See the [catalog guide](./docs/catalog.md)
+for repository base and source path configuration. To offer the catalog's
+**Capture region** link to UX Review on a local server, add the Node-only
+`uxReviewPlugin` from `@kerfjs/ui/vite-ux-review` to the Vite config (or, for a
+catalog your own backend serves, mount its `uxReviewProjectResponse` /
+`uxReviewMiddleware` on the development server) and pass `wireCatalog`'s
+`onUxReviewProject` result to `Catalog`'s `uxReview` (the
+[catalog guide](./docs/catalog.md#ux-review-capture) has the wiring).
+
+Composition-aware consumers use
+[`component-composition-extension.schema.json`](./ai/component-composition-extension.schema.json),
+its shipped TypeScript types, and the checked
+[`component-composition-extension.json`](./docs/examples/component-composition-extension.json)
+example. Preserve each catalog's package and qualify every identity and
+cross-catalog reference as `package:id`; never merge entries by bare id.
+
+[`compile-time-contracts-v1.json`](./ai/compile-time-contracts-v1.json) is the
+matching declaration contract: stable `KUI-T###` ids identify the invalid prop,
+state, identity, accessibility, and protected-attribute combinations TypeScript
+rejects. The package gate compiles one positive/negative consumer fixture against
+both source and declarations extracted from the real packed tarball. The
+[compile-time contract guide](./docs/type-contracts.md) documents migrations and
+the dynamic DOM/children relationships that remain runtime or catalog checks.
+Packages scaffolded by `create-kerf-component` maintain this composition input from
+`kerf.components.json`: `npm run catalog:generate` emits the catalog and
+`npm run catalog:check` verifies source files, named public exports, explicit
+author decisions, and byte-for-byte drift. Tools index the generated consumer
+entries and this catalog by full key, reject duplicate full keys, search the
+consumer package first, and retain package identity across every reference.
+They must not infer missing semantics or geometry from rendered appearance.
+
+### Application UI profile
+
+Applications can check in `.kerf-ui-profile.json` so tools do not have to infer
+project-wide UI policy. Start from the shipped
+[`application-ui-profile.defaults.json`](./ai/application-ui-profile.defaults.json)
+and the checked
+[`application-ui-profile.json`](./docs/examples/application-ui-profile.json)
+workspace example. The versioned
+[`application-ui-profile.schema.json`](./ai/application-ui-profile.schema.json)
+and [`application-ui-profile.d.ts`](./ai/application-ui-profile.d.ts) cover
+catalog locations, concept preferences, allowed theme/density choices, semantic
+token overrides, layout/responsive conventions, and narrow rule exceptions.
+Profiles contain policy only—never product records, user data, or broad styling
+waivers.
+
+Catalog declarations always provide a `composition` location. Consumer
+packages generated with composition-only metadata omit `selection`;
+`@kerfjs/ui` continues to require its `component-catalog.json` selection catalog.
+
+Node-based AI and static-analysis tools may import the shipped discovery API
+from `@kerfjs/ui/ai/application-ui-profile.mjs`. It discovers package defaults,
+then the workspace profile, then directory profiles from parent to child;
+`mergeApplicationUiProfiles()` applies later scalar/map values, replaces a
+catalog by package and an exception by id, and preserves source provenance.
+`loadApplicationUiProfile()` resolves catalogs and returns diagnostics with the
+originating file plus JSON path. Unknown/stale components, tokens, rules, and
+catalog locations are errors. Every layer is checked against its then-effective
+catalogs, including parent references and catalog paths later overridden by a
+child profile. Synchronous integrations can require the shipped
+`application-ui-profile-sync.cjs` projection and call
+`loadApplicationUiProfileSync()` with already-discovered layers. Consumers that define additional stable
+diagnostics pass their ids through the additive `knownRules` option; those ids
+are merged with catalog diagnostics before exception validation.
+
+### Static CSS and layout ownership analysis
+
+Run `kerf-ui-analyze --root . src` (or import
+`@kerfjs/ui/analyzer`) to evaluate cross-file integration facts against the
+composition catalogs and application profile. It catches provable private
+selector reach-through, unknown tokens, competing geometry owners, nested
+scroll owners, and cataloged CSS-value violations in JavaScript/TypeScript
+component calls and JSX, plus component-ownership overrides: CSS that makes
+another package's component its subject, touches its private variables,
+overrides a token its typed prop sets, or styles it through a hook class on
+its root (`KUI-L019`–`KUI-L022`; forcing a component's dimensions is one such
+restyle). It reports repeated insets, exceptional spacing shorthands, and
+dynamic classes separately as review findings. Text, versioned JSON,
+and SARIF outputs carry stable `KUI-L###` ids, repository-relative locations,
+evidence, and ownership chains. See the [analyzer guide](./docs/ui-analyzer.md).
+Opt into ownership between components in one package with Doctor's
+`"ownership": "component"` setting and catalog `styleSources` declarations;
+the default keeps package-level ownership.
+
+### Browser-backed integration evaluation
+
+Run `kerf-ui-evaluate --url <running-app>` (or import
+`@kerfjs/ui/evaluator`) after the static analyzer. Its Playwright-backed
+wide/intermediate/narrow/200%-zoom, light/dark, and reduced-motion matrix checks
+rendered overflow, clipping, reachability, focus/keyboard behavior, accessible
+names, contrast, hit targets, scrolling, alignment, and cataloged runtime
+geometry. The versioned report carries stable `KUI-B###` diagnostics, focused
+DOM/computed-style evidence, hashed screenshot artifacts, explicit timeout and
+retention policy, and a separate unscored human-visual rubric. See the
+[browser evaluator guide](./docs/ui-evaluator.md).
+
+### Unified repair-loop doctor
+
+Use `kerf-ui-doctor` for the supported application repair loop across profile/catalog validation, TypeScript, the Kerf UI ESLint preset, static layout analysis, and an optional explicitly authorized browser evaluation. Its isolated Kerf lint pass preserves each file's applicable core-rule and suppression settings without executing consumer plugin rules. It emits one portable versioned JSON report with deterministic exit codes, exact suppressions, monorepo package selection, changed/full modes, caching, and local-path redaction. See the [UI doctor guide](./docs/ui-doctor.md).
 
 For code generation, pair catalog selection guidance with the checked-in
 [`public-api-signatures-v1.md`](./ai/public-api-signatures-v1.md) declaration
@@ -184,40 +554,74 @@ roots therefore do not need a transitive stylesheet list, and removing the last
 component import also removes its reachable CSS. This is component-level CSS
 tree shaking; variants within an imported component remain together.
 
+When one public subpath groups several visual components, its source is a
+folder: one component per file and one owned stylesheet per visual component.
+The public JavaScript/TypeScript compatibility entrypoint only re-exports those
+modules, and its CSS compatibility entrypoint only imports the owner
+stylesheets. Do not accumulate multiple visual owners in either compatibility
+file.
+
+`npm run check:css-ownership` keeps that boundary honest: application CSS may
+style only application-owned structure, never package component classes or
+Web Awesome descendants, and a package component's stylesheet styles only
+itself (in a composing parent's context when needed) — never another kerf
+component's root, the `wa-*` tags it renders, its variables, or a hook class on
+its root. The UX catalog's `style.css` contains document-shell
+mechanics only, recipes ship no stylesheets (`npm run check:recipes` rejects
+route stylesheets, inline styles, and styling-only classes), and `catalog.css`
+remains a
+minimal compatibility entrypoint.
+
 The root `@kerfjs/ui` barrel stays JavaScript-only because making a side-effectful
 CSS barrel tree-shakable is not portable across bundlers. If an application uses
 that convenience import, also import `@kerfjs/ui/styles.css`, which deliberately
 contains the complete layer. Non-browser/SSR tools resolve the pure `import`
 condition automatically; `@kerfjs/ui/unstyled` is the explicit CSS-free root
 entry for a browser build with a custom styling pipeline. The exported
-`foundation.css` and component CSS paths remain available for fully manual
-delivery. Load application overrides after package styles, or scope `--kui-*`
-variables directly on a component instance.
+`@kerfjs/ui/foundation.css` and component CSS paths remain available for fully
+manual delivery. Its complete supported `--kui-*` token surface is cataloged
+under the `foundation` entry. Load application overrides after package styles,
+or scope variables directly on a component instance.
+
+Applications can separately opt into `@kerfjs/ui/document.css` for border-box
+sizing, token-backed body typography/colors, zero body margin, plain-link color,
+inherited native table-cell and form-control font metrics, and a definite
+full-height chain. Add `class="kui-app-root"` to the one direct
+mount container when a percentage-height application shell must fill the
+viewport. This global baseline is deliberately absent from `styles.css` and
+component browser imports. See [Document baseline](./docs/document-baseline.md).
 
 ## Pane and content geometry
 
-Import `@kerfjs/ui/layout.css` and use the same structural vocabulary for a
-sidebar, main area, inspector, or dialog. `.kui-pane` is unpadded and contains
-an optional toolbar, one scrolling `.kui-pane__content`, and an optional footer.
-Add `.kui-content` to make its major children a vertical stack with 24px gaps.
+Render `Pane` (`@kerfjs/ui/pane`) for a sidebar, main area, inspector, or
+dialog: the same structural vocabulary everywhere. Its `.kui-pane` root is
+unpadded and contains an optional header, one scrolling `.kui-pane__content`,
+and an optional footer; the content slot already carries `.kui-content`, which
+makes its major children a vertical stack with 24px gaps. Choose landmark
+semantics with `element` / `contentElement` rather than writing the pane
+classes onto your own elements — `eslint-plugin-kerfjs` reports a component's
+anatomy class on an application-owned element as `KUI-L103`.
 
 ```tsx
-<aside class="kui-pane">
-  <div class="kui-pane__toolbar"><Toolbar label="Workspace" ... /></div>
-  <nav class="kui-pane__content kui-content">
-    <section>
-      <ListHeader label="Workspace" count={3} countLabel="3 workspaces" />
-      <ListItem action="open" label="Inbox" icon={inboxIcon} />
-      <ListItem action="open" label="Drafts" />
-    </section>
-    <div class="kui-content-item">Workspace details</div>
-  </nav>
-</aside>
+<Pane
+  element="aside"
+  label="Workspace"
+  contentElement="nav"
+  header={<Toolbar label="Workspace" ... />}
+>
+  <section>
+    <ListHeader label="Workspace" count={3} countLabel="3 workspaces" />
+    <ListItem action="open" label="Inbox" icon={inboxIcon} />
+    <ListItem action="open" label="Drafts" />
+  </section>
+  <ContentItem>Workspace details</ContentItem>
+</Pane>
 ```
 
-Ordinary children use `.kui-content-item`: 8px inline margin, a real 1px border
-(transparent by default), 8px padding, and 12px rounded corners. The pill
-modifier uses a 22px radius. A component can expose a transparent border or
+Ordinary children use `ContentItem` (`@kerfjs/ui/content-item`): 8px inline
+margin, a real 1px border (transparent by default), 8px padding, and 12px
+rounded corners. `shape="pill"` uses a 22px radius, and `frame="framed"` paints
+the neutral border only when the item marks a real distinction. A component can expose a transparent border or
 background without changing layout. `ListHeader` follows the same rule while
 keeping its dormant title and count-or-badge cluster separate from its optional
 44px action.
@@ -234,14 +638,17 @@ the complete [layout contract](./docs/layout.md).
 
 ## Web Awesome theme
 
-Apps using Web Awesome's free components can opt into the same visual universe
-with one CSS import:
+Kerf components never need Web Awesome: every Kerf component draws native
+controls and reads only `--kui-*` tokens, which resolve to the same values with
+or without the Web Awesome theme. `@awesome.me/webawesome` is an optional peer
+for applications that also render Web Awesome's `wa-*` elements. Those apps opt
+into the same visual universe with one CSS import:
 
 ```ts
-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';
+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 `@kerfjs/ui/webawesome` import adds Kerf JSX intrinsic-element
@@ -252,7 +659,10 @@ Awesome modules the application renders.
 `webawesome.css` includes Web Awesome's native/base theme and then applies the
 Hot Sheet 2 palette, surfaces, status colors, focus treatment, form geometry,
 radii, tooltips, and shadows through Web Awesome's public `--wa-*` contract.
-Those tokens flow into all free component families. Every free Web Awesome 3.12
+On `wa-dialog`, the optional `hide-actions` class hides the exported
+`header-actions` shadow part for compositions that provide another dismissal
+affordance.
+Those tokens flow into all free component families. Every free Web Awesome 3.14
 component has an individual UX-catalog route under the collapsible ecosystem
 section, but the theme entry does not import or register component JavaScript,
 so each component module remains independently tree-shakeable in consuming apps.
@@ -260,37 +670,44 @@ Tooltip and Popover surfaces omit pointer arrows by default. Override
 `--wa-tooltip-arrow-size` and `--kui-wa-popover-arrow-size`, or a single
 popover's public `--arrow-size`, when an arrow communicates useful context.
 
-Load application CSS afterward to override semantic values globally, or scope
-them to a subtree. Use Web Awesome's `.wa-light`, `.wa-dark`, and `.wa-invert`
+Configure semantic values globally at the application root, or scope variables
+to a self-owned subtree. Use Web Awesome's `.wa-light`, `.wa-dark`, and `.wa-invert`
 classes for explicit appearance boundaries:
 
 ```css
 :root {
   --wa-color-brand-fill-loud: #7540a8;
-  --wa-form-control-border-radius: .5rem;
+  --wa-form-control-border-radius: 0.5rem;
 }
 ```
 
 `foundation.css` follows Hot Sheet 2's Web Awesome-compatible semantic palette.
-Brand, neutral, success, warning, and danger each expose fill, border, and
-foreground roles through `--kui-color-*`; stateful components also expose
+Brand, pop, neutral, success, warning, and danger each expose fill, border, and
+foreground roles through `--kui-color-*`. Pop is attractive, non-status emphasis
+for featured, novel, or celebratory content; it never substitutes for success,
+warning, or danger. Stateful components also expose
 component variables such as `--kui-state-banner-background`. Override the
 foundation for an application theme, a tone variable for one semantic state, or
 a component variable on one instance without replacing component selectors.
-Prefer an equivalent prop or token. When composition-specific layout still
-needs a selector, the component catalog's `publicClasses` arrays define the
-exact stable anatomy: public-class-to-public-class selectors are supported;
-descendant tag, id, attribute-only, and unlisted-class selectors are not.
-
-`StateBanner` has opinionated `neutral`, `info`, `success`, `warning`, and
-`danger` palettes. Override an individual banner with
+Prefer an equivalent prop or token. The component catalog's `publicClasses`
+arrays support diagnostics, tooling, browser assertions, and package-owned
+composition; they are not an application styling API. Application-owned CSS may
+style new structure rendered by its own component, but it must not select a
+nested Kerf or Web Awesome component. Add missing configuration to the owner.
+Markup follows the same rule: write only an entry's `placeableClasses` (layout
+utilities, `kui-app-root`, `kui-content-item` on a non-div carrier) onto your
+own elements; any other public class recreates a component by class, which
+`eslint-plugin-kerfjs` reports as `KUI-L103` with the component to render.
+
+`StateBanner` has opinionated `neutral`, `info`, `pop`, `success`, `warning`,
+and `danger` palettes. Override an individual banner with
 `--kui-state-banner-background`, `--kui-state-banner-border`,
 `--kui-state-banner-foreground`, `--kui-state-banner-detail`,
 `--kui-state-banner-action-background`, and
 `--kui-state-banner-action-hover-background`. To retheme one tone everywhere,
 override `--kui-state-banner-{tone}-{background|border|foreground}`. Other
 stateful components follow the same public-variable pattern, including
-`--kui-toolbar-control-*`, `--kui-segmented-*`, `--kui-app-tab-*`, and
+`--kui-toolbar-control-*`, `--kui-segmented-*`, `--kui-tab-bar-item-*`, and
 `--kui-tab-bar-*`.
 
 `SegmentedControl` is a controlled exclusive-choice component. Use
@@ -307,8 +724,8 @@ standalone `filled`/`outlined` appearance with `shape="rounded"` or
   appearance="toolbar"
   shape="pill"
   choices={[
-    { value: 'list', label: 'List' },
-    { value: 'columns', label: 'Columns' },
+    { value: "list", label: "List" },
+    { value: "columns", label: "Columns" },
   ]}
 />
 ```
@@ -318,18 +735,97 @@ value through `data-segment-value`. Override an instance through
 `--kui-segmented-{background|border|foreground|hover-background}` and
 `--kui-segmented-selected-{background|foreground|border|shadow}`.
 
-`TokenSearchField` is a token-controlled contenteditable searchbox that keeps
+`ChoiceChips` is the wrapping exclusive choice for a visible set too large for
+one segmented track, such as a labeled color palette. Each choice is a separate
+pill backed by a native radio, so the group is one Tab stop, arrow keys move
+the selection, and the checked radio submits the form value under `name`. A
+choice may lead with a `swatch` (a `CssColor`, or `'transparent'` for the
+struck-through no-color dot) or a decorative `icon`:
+
+```tsx
+<ChoiceChips
+  name="color"
+  label="Command color"
+  value={color.value}
+  action="select-command-color"
+  choices={[
+    { value: "transparent", label: "Transparent", swatch: "transparent" },
+    { value: "blue", label: "Blue", swatch: fillColor("#3b82f6") },
+  ]}
+/>
+```
+
+Listen for `change` on the supplied action (for example
+`delegateActions(root, "change", { "select-command-color": … })`), read the
+radio's `value`, and re-render.
+
+Set `multiple` when any number of the options may be on, such as label filters
+or annotation intents. `value` is then a `readonly Value[]`, the pills are
+native checkboxes in a `role="group"` (each a Tab stop that Space toggles), and
+every checked value submits under `name`. Read the checked boxes by name in the
+change handler. A multiple group takes no `required`. On dark inverse chrome,
+place the chips in a dark appearance scope (`.wa-dark`) instead of restyling
+them.
+
+`MessageComposer` is the chat or prompt composer: a raised frame (the standard
+border, large radius, and `shadow-l`) whose border turns brand while focus is
+within. Its borderless message field grows with its content between `minRows`
+(default 1) and `maxRows` (default 8) lines, then scrolls, above an action row
+with an optional quiet `hint` and the trailing `actions`:
+
+```tsx
+<MessageComposer
+  id="assistant-message"
+  name="message"
+  label="Message"
+  placeholder="Ask about this build"
+  hint="Answers use the latest nightly build."
+  trailing={<Button tone="brand" action="send-message">Send</Button>}
+/>
+```
+
+The app reads and clears the textarea from its send action. For
+Enter-to-send, set `submitOnEnter` and call `wireMessageComposers(root)` from
+`@kerfjs/ui/wire-message-composers` once: Enter or Cmd/Ctrl+Enter clicks the first
+trailing action, Shift+Enter inserts a newline, and an IME composition commit
+or an empty message never sends. Put it in a `DialogSurface` with
+`footerPresentation="floating"` (`slot="footer"`) to float it over a
+transcript, and give the transcript `scrollClearance="block-end"` so it
+scrolls beneath the composer while its last message still rests above it.
+Add `headerPresentation="floating"` with a `fill` body and
+`scrollClearance="both"` to let the transcript scroll beneath a translucent
+title bar as well.
+
+`SearchField` is a token-controlled contenteditable searchbox that keeps
 free text and ordered filter chips in one field. Its editable text stays
 DOM-owned between token changes so typing does not replace the caret. Tokens
 expose stable edit/remove actions and remain atomic during editing; the app owns
-parsing, suggestions, query execution, and state. Use `readTokenSearchField()`
+parsing, suggestions, query execution, and state in manual mode. For automatic
+handling, create a model with `createSearchFieldModel({ rules, evaluate })`,
+pass it as the field's `model`, and register it under the field id in
+`wireSearchFields(root, { models })`. Rules parse `name:value` expressions;
+their optional `suggest` function supplies selectable completions. The model
+commits valid expressions on whitespace or Enter, owns chips and clear/edit/
+remove actions, and exposes `state`, `suggestions`, and the latest `result` as
+signals. The field subscribes only to `model.structure`, which changes when a
+token is committed or removed, the text becomes empty or non-empty, or the
+editor revision changes, so typing plain text never re-runs the host render.
+Keep it that way in the host: read `model.state.peek()` in render, and bind
+`model.result` (or a `computed`) as a fine-grained signal hole rather than
+reading `model.state.value`. Omit the model to retain full manual control. Use `readSearchField()`
 after browser input to recover text plus token offsets, and
-`placeTokenSearchCaret()` when restoring focus after a controlled update.
-Call `wireTokenSearchFields()` once at a stable root to make Enter submit through
+`placeSearchFieldCaret()` when restoring focus after a controlled update.
+Call `wireSearchFields()` once at a stable root to make Enter submit through
 `onSubmit` without inserting a contenteditable line break and to preserve focus
 plus the text-relative caret when keyboard deletion of a chip causes controlled
-rendering to replace the editor. Text still wraps visually when it reaches the
-field edge.
+rendering to replace the editor. A select-all deletion is normalized to a truly
+empty editor even when the browser leaves an atomic chip or line break behind;
+replacement typing consumes that intent so a later Backspace/Delete remains an
+ordinary character edit.
+Managed deletion keeps a collapsible replacement editor open and focused before
+the next keystroke; applications must persist both query and tokens from the DOM
+read. Genuine outside focus and Escape still collapse an empty field.
+Text still wraps visually when it reaches the field edge.
 Clear actions should empty the editor's `textContent` before clearing app state.
 The leading icon, first text line, clear action, and trailing slot share one
 fixed alignment row; when text wraps, those controls stay pinned to that first
@@ -341,67 +837,118 @@ and respect reduced-motion preferences. The field works standalone or inside a
 `ToolbarControlGroup`; the application owns the transient focused/open signal,
 focus transfer, and focusout policy. The catalog's Toolbar route demonstrates
 that composition at wide and narrow sizes.
-Override its surface through `--kui-token-search-{background|border}` and its
-chips through `--kui-token-search-token-{background|foreground}`. Override
-`--kui-token-search-line-size` only when the complete first-line geometry must
+Override its surface through `--kui-search-field-{background|border}` and its
+chips through `--kui-search-field-token-{background|foreground}`. Override
+`--kui-search-field-line-size` only when the complete first-line geometry must
 change together.
 
-`TabBar` is controlled: pass ordered `AppTab` children, then wire its keyboard
+`TabBar` is controlled: pass ordered `TabBarItem` children, then wire its keyboard
 and same-bar drag behavior with `wireTabBars(root, { onReorder })`. During a
 drag, the scroll strip automatically moves toward either edge with speed based
 on pointer proximity, exposing earlier or later drop targets. Apply the reported
 change with `reorderTabs()` or application-specific state logic. The application
 still owns selection, closing, routing, and persistence.
-Use `AppTab.rootAttributes` for domain `data-*` metadata and `closeIcon` for a
+For a tab-local action immediately after the final tab plus a workspace action
+at the opposite edge, set `trailingPlacement="adjacent"`, pass the local action
+through `trailing`, and pass the workspace action through `end`. TabBar owns the
+flex geometry: the tab strip shrinks and scrolls while both action regions stay
+visible. Do not recreate that split with descendant CSS overrides.
+Use `TabBarItem.rootAttributes` for domain `data-*` metadata and `closeIcon` for a
 decorative replacement glyph. The runtime rejects roles and case variants of
 the component- or wiring-owned action, tab identity, selection, drag, drop, and
 component markers. Keep the icon free of interactive descendants; the named
 close button retains all close interaction.
 
-`Select` uses Web Awesome but does not register anything by itself. Install the optional peer, import the shared theme if desired, and explicitly import the registration entry in the application:
+`Select` and `PopupMenu` draw their own native controls and need no Web Awesome. Each renders inert markup until its registration entry is imported once in the application:
 
 ```ts
-import '@kerfjs/ui/webawesome.css';
-import '@kerfjs/ui/select/register';
+import "@kerfjs/ui/select/register";
+import "@kerfjs/ui/popup-menu/register";
 ```
 
-That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it.
-`Select` also owns the Kerf/Web Awesome reconciliation boundary: option icons
-keep stable slotted elements across rerenders, and `renderSelected` content is
-replaced when the controlled value changes. Consumers do not need to add
-`data-key` or `data-morph-skip` workarounds around choice icons.
-
-For application choices and panes, prefer Kerf's purpose-built primitives:
-`Select` over direct Web Awesome selection/dropdown composition,
-`SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web
-Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over
-Split Panel. `ResizableRegion` includes Hot Sheet 2's 1px separator and
+`select/register` defines the form-associated `kui-select` root and wires every `Select` in the document; `popup-menu/register` wires every `PopupMenu` (opening, keyboard navigation, submenus, the `kui-menu-select` event, and focus return). That boundary keeps custom-element and document-listener side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it, and also prove that no public entry except `@kerfjs/ui/webawesome.css` pulls in Web Awesome. Either registration also installs help tags: an icon-only Select, PopupMenu, or `aria-label`-named `<button>` in a `ToolbarControlGroup` shows its name in an `aria-hidden` tooltip on hover and keyboard focus. A toolbar with icon-only buttons but neither control imports `@kerfjs/ui/help-tags/register`, which registers only the tooltip.
+
+`PopupMenu` items may include `submenu` children, `checked` choices, a leading `icon`, trailing `details`, `disabledReason`, and a `danger` tone. The app owns choice state and dispatches each item's `action`. For a right-click menu, set `context: true`, a `label`, and `anchor={pointSignal.value}`; the app's `contextmenu` handler stores `{ x: event.clientX, y: event.clientY }` in that signal and calls `openPopupMenu(menu)`. The menu renders its own zero-footprint anchor host and keeps the point across re-renders, so it needs no wrapper or CSS (`openPopupMenuAt(menu, x, y, { placement? })` still opens a menu rendered without `anchor`); `closePopupMenu(menu)` closes it programmatically. See [component selection](docs/component-selection.md#popup-menu-migration) for examples.
+Use `label` for a visible label or `ariaLabel` for a visually hidden name. A
+nonempty visible label takes precedence when both are supplied. Kerf names the
+native trigger without adding visible label spacing; this also works with
+`renderSelected`. Use `hint`
+for persistent supporting text below the control and `placeholderText` for the
+empty value inside the closed control. Loading placeholders preserve the hint.
+
+`Select` also owns its reconciliation boundary: option icons keep stable
+elements across rerenders, and `renderSelected` content is replaced when the
+controlled value changes. Consumers do not need to add
+`data-key` or `data-morph-skip` workarounds around choice icons. Icon-bearing
+options retain the standard icon-to-label gap. When a compact Select is wrapped
+in a `ToolbarControlGroup`, use `focusRingOwner="group"`; the group paints the
+focus ring with its configured pill or rounded geometry.
+
+For application choices and panes, use Kerf's purpose-built primitives;
+Web Awesome is an optional integration, and the
+[migration guide](./docs/webawesome-migration.md) maps each Web Awesome
+element a Kerf component replaces (`Select`, `PopupMenu`, `SegmentedControl`,
+`TabBar`, `LucideIcon`, `ResizableRegion`, and the native form controls). `ResizableRegion` includes Hot Sheet 2's 1px separator and
 hover/focus grip. Its optional `handleIcon` replaces only the decorative glyph;
 the component and `wireResizableRegions()` retain separator semantics and
-pointer/keyboard behavior. Consider Web Awesome Popup when its anchored-positioning
-engine removes custom placement code; treat Tree, Animated Image, Comparison,
-Zoomable Frame, and the displaced alternatives above as exceptional rather
-than default patterns. The detailed rationale lives in the theme contract.
+pointer/keyboard behavior. Typed policies cover separator visibility,
+instant-track/composited-content collapse, popup-safe overflow,
+inline/overlay/hidden responsive presentation, `responsiveFillAt` single-track
+replacement, and safe-area restore controls;
+the same policies are available on `Workbench` and `CollapsiblePanel`. In an
+integration application, consider Web Awesome Popup when its anchored-positioning
+engine removes custom placement code, and treat Tree, Animated Image,
+Comparison, and Zoomable Frame as exceptional rather than default patterns.
+The detailed rationale lives in the theme contract.
 
 ## Design and tool guidance
 
 - [Component selection and composition](./docs/component-selection.md)
 - [Design philosophy](./docs/design-philosophy.md)
 - [Apple HIG translation](./docs/apple-hig.md)
+- [Writing interface copy](./docs/writing.md)
 - [Accessibility and keyboard contracts](./docs/accessibility.md)
 - [Component and integration contract](./docs/component-contract.md)
 - [Spacing and application layout](./docs/layout.md)
 - [Web Awesome theme contract](./docs/webawesome-theme.md)
+- [Moving an application off Web Awesome](./docs/webawesome-migration.md)
 - [UX catalog contract](./docs/ux-demo.md)
 - [AI guide](./ai/skill.md)
 
-Run `npm run dev` from this directory for the category-grouped master/detail catalog. Every public visual component has a focused route; all 70 free Web Awesome 3.12 components have focused routes under the collapsible ecosystem section. Every detail visibly links its first-party demo source and existing guidance while showing the repository-relative paths; first-party components also link their implementation source, and Web Awesome entries label local guidance as Kerf integration guidance. One grouped `Related components` selector contains derived `Uses` / `Used by` navigation across both sets. Run `npm run check` for static/unit/bundle gates and `npm run test:e2e` for the real-browser suite.
+Run `npm run dev` from this directory for the category-grouped master/detail catalog. Every public visual component has a focused route; all 73 free Web Awesome 3.14 components have focused routes under the collapsible Web Awesome Integration section. Every detail visibly links its first-party demo source and existing guidance while showing the repository-relative paths; first-party components also link their implementation source, and Web Awesome entries label local guidance as Kerf integration guidance. One grouped `Related components` selector contains derived `Uses` / `Used by` navigation across both sets. Run `npm run check` for static/unit/bundle gates and `npm run test:e2e` for the real-browser suite.
 
-Run `npm run format:css` after editing styles. The normal `npm run check` gate
-uses Prettier to reject unformatted CSS in `src/` and `ux-demo/`.
+Run `npm run format` after editing source or structured content. The narrower
+`npm run format:css` command remains available for style-only work. The normal
+`npm run lint` and `npm run check` gates use Prettier to reject formatting drift.
 
 For dimensions that should scale with the root font size, author pixels with
 `remify()`: `gap: remify(17px)` builds to `gap: 1.0625rem` using a fixed 16px
 baseline. Keep intentional 1px borders in pixels and contextual `em` values
 explicit. `npm run build` emits standard CSS to `dist/styles`; `npm run dev`
 applies the same transform directly to source styles and hot-reloads edits.
+
+Lowered surfaces and decorative neutral fills/borders use translucent shared theme colors. Nested surfaces compound naturally; demos compose public components without per-depth overrides. See [contextual transparency](docs/webawesome-theme.md#contextual-transparency).
+
+`ToolbarText` and `ToolbarControlGroup` accept typed `hideBelow`/`showBelow`
+lengths (for example `px(416)`). Wire `wireToolbarVisibility(root)` from
+`@kerfjs/ui/wire-toolbar-visibility` and dispose on unmount. Thresholds use the
+nearest Toolbar content-box width: hideBelow hides strictly below, showBelow
+shows strictly below, with complementary behavior at equality. Percentages use
+that content width; em and custom properties use the item's own context. Invalid,
+negative, unresolved, or contradictory values leave the item visible under this
+width policy. Keep primary actions visible and offer a complementary overflow
+group. See `docs/component-contract.md` "Toolbar width visibility" for lifecycle
+details.
+
+## License and third-party notices
+
+`@kerfjs/ui` is MIT licensed (see `LICENSE`).
+
+Web Awesome (`@awesome.me/webawesome`, copyright Fonticons, Inc., MIT) is an
+optional peer dependency. This package does not copy or bundle Web Awesome
+code: `@kerfjs/ui/webawesome.css` imports Web Awesome's stylesheet from the
+application's own installation, and `@kerfjs/ui/webawesome` contains only type
+declarations. An application that bundles Web Awesome components
+redistributes them, so it should retain Web Awesome's MIT notice; Font Awesome
+Free, whose icons Web Awesome embeds, asks that the attribution comments in
+those icons stay intact.