@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/README.md

@@ -4,6 +4,45 @@ 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.
 
+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,
@@ -11,11 +50,11 @@ 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 seven [production composition
+For connective application patterns, use the ten [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.
 
@@ -30,22 +69,20 @@ npm install kerfjs @kerfjs/ui
 ```
 
 ```tsx
+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 { ToolbarControlGroup } from "@kerfjs/ui/toolbar-control-group";
 import { ToolbarText } from "@kerfjs/ui/toolbar-text";
 
+const root = document.getElementById("app")!;
+
 mount(root, () => (
   <>
     <Toolbar
       label="Document"
-      leading={
-        <ToolbarControlGroup appearance="borderless" single>
-          <ToolbarText text="Notes" />
-        </ToolbarControlGroup>
-      }
+      leading={<ToolbarText text="Notes" />}
     />
     <section>
       <ListHeader
@@ -75,7 +112,7 @@ mount(root, () => (
         label="src/main.ts"
         trailingAction="open-file-actions"
         trailingActionLabel="Actions for src/main.ts"
-        trailingActionIcon={moreIcon}
+        trailingActionIcon={<span aria-hidden="true">⋯</span>}
       />
       <div id="workspace-actions" popover="auto">
         Application-owned actions
@@ -87,15 +124,35 @@ mount(root, () => (
 
 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`, `AppTab.rootAttributes`,
-`CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` carry typed
+`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, 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
@@ -112,58 +169,157 @@ 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`          |
-| `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.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`           |
-| `ListInsetControl`                                                  | `@kerfjs/ui/list-inset-control`         | `@kerfjs/ui/list-inset-control.css`    |
-| `ListInsetText`                                                     | `@kerfjs/ui/list-inset-text`            | `@kerfjs/ui/list-inset-text.css`       |
-| `Pane`                                                              | `@kerfjs/ui/pane`                       | `@kerfjs/ui/pane.css`                  |
-| 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`              |
-| `SunkenPanel`                                                       | `@kerfjs/ui/sunken-panel`               | `@kerfjs/ui/sunken-panel.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`           |
-
-Opt-in application layouts keep JavaScript and CSS explicit. For the
-desktop-class multi-panel shell, import `Workbench` from
-`@kerfjs/ui/workbench` and load `@kerfjs/ui/workbench.css`; its supported
-classes and size tokens are cataloged under the `workbench` entry. See
-[`docs/workbench.md`](./docs/workbench.md) for panel ownership and responsive
-replacement guidance.
-
-`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
+| 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`        |
+| `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`             | —                                        |
+| `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`     | —                                        |
+| `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`              | —                                        |
+| `wireScrollDividers`                                                | `@kerfjs/ui/wire-scroll-dividers`       | —                                        |
+| `wireToolbarVisibility`                                             | `@kerfjs/ui/wire-toolbar-visibility`    | —                                        |
+| `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`            |
+| `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`            |
+| `Composer`                                                          | `@kerfjs/ui/composer`                   | `@kerfjs/ui/composer.css`                |
+| `wireComposers`                                                     | `@kerfjs/ui/wire-composers`             | —                                        |
+| `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret` | `@kerfjs/ui/token-search-field`         | `@kerfjs/ui/token-search-field.css`      |
+| `wireTokenSearchFields`                                             | `@kerfjs/ui/wire-token-search-fields`   | —                                        |
+| `createTokenSearchModel`                                            | `@kerfjs/ui/token-search-model`         | —                                        |
+| `StateBanner`                                                       | `@kerfjs/ui/state-banner`               | `@kerfjs/ui/state-banner.css`            |
+| `IconButton`                                                        | `@kerfjs/ui/icon-button`                | `@kerfjs/ui/icon-button.css`             |
+| `IconToggleButton`                                                  | `@kerfjs/ui/icon-toggle-button`         | `@kerfjs/ui/icon-toggle-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 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` retains its independent Web Awesome expand-glyph
 scale of `.5` through `--kui-disclosure-icon-scale`. Author replacement
 `DisclosureArrow` icon content facing right before its configured direction
@@ -175,13 +331,26 @@ 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,
@@ -195,19 +364,22 @@ 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, and sanctioned metadata
-slot. Keeping this as a companion artifact prevents per-entry selection facts
-from duplicating presentation rules.
+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-catalog-v2.json`](./ai/component-catalog-v2.json). It is a
-deterministic, package-qualified projection of every v1 entry with formal
-parent/context, zone/cardinality, child, state ownership, wiring, responsive,
-layout, accessibility, public-boundary, and stable-diagnostic fields. V1
-remains the selection and delivery compatibility surface. V2 defaults are
+[`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-catalog-v2.d.ts`](./ai/component-catalog-v2.d.ts) types describe
+[`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
@@ -220,12 +392,25 @@ 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.
+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-catalog-extension-v2.schema.json`](./ai/component-catalog-extension-v2.schema.json),
+[`component-composition-extension.schema.json`](./ai/component-composition-extension.schema.json),
 its shipped TypeScript types, and the checked
-[`component-catalog-extension-v2.json`](./docs/examples/component-catalog-extension-v2.json)
+[`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.
 
@@ -236,7 +421,7 @@ rejects. The package gate compiles one positive/negative consumer fixture agains
 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 v2 input from
+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
@@ -259,9 +444,9 @@ 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 v2 `composition` location. Consumer
+Catalog declarations always provide a `composition` location. Consumer
 packages generated with composition-only metadata omit `selection`;
-`@kerfjs/ui` continues to require its v1 selection catalog.
+`@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,
@@ -283,11 +468,19 @@ are merged with catalog diagnostics before exception validation.
 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, and nested
-scroll owners; it reports forced dimensions, repeated insets, off-scale literal
-spacing, and dynamic classes separately as review findings. Text, versioned JSON,
+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
 
@@ -303,7 +496,7 @@ retention policy, and a separate unscored human-visual rubric. See the
 
 ### 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. 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).
+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
@@ -333,6 +526,24 @@ 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
@@ -344,30 +555,45 @@ 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.
@@ -402,6 +628,9 @@ 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.
+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.12
 component has an individual UX-catalog route under the collapsible ecosystem
 section, but the theme entry does not import or register component JavaScript,
@@ -410,8 +639,8 @@ 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
@@ -422,18 +651,25 @@ classes for explicit appearance boundaries:
 ```
 
 `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
@@ -468,18 +704,91 @@ value through `data-segment-value`. Override an instance through
 `--kui-segmented-{background|border|foreground|hover-background}` and
 `--kui-segmented-selected-{background|foreground|border|shadow}`.
 
+`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.
+
+`Composer` 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
+<Composer
+  id="assistant-message"
+  name="message"
+  label="Message"
+  placeholder="Ask about this build"
+  hint="Answers use the latest nightly build."
+  actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>}
+/>
+```
+
+The app reads and clears the textarea from its send action. For
+Enter-to-send, set `submitOnEnter` and call `wireComposers(root)` from
+`@kerfjs/ui/wire-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.
+
 `TokenSearchField` 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 `createTokenSearchModel({ rules, evaluate })`,
+pass it as the field's `model`, and register it under the field id in
+`wireTokenSearchFields(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. Omit the model to retain full manual control. Use `readTokenSearchField()`
 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
 `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. A select-all deletion is normalized to a truly
-empty editor even when the browser leaves an atomic chip or line break behind.
+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
@@ -503,6 +812,11 @@ 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.
+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 `AppTab.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
@@ -516,11 +830,23 @@ import "@kerfjs/ui/webawesome.css";
 import "@kerfjs/ui/select/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.
+That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it. `PopupMenu` follows the same rule: import `@kerfjs/ui/popup-menu/register` once to register the dropdown, item, button, and divider elements it renders. 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)` 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
+actual shadow combobox without adding visible label spacing; this also works
+with `renderSelected`, and needs no application shadow-DOM patch. 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 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.
+`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, prefer Kerf's purpose-built primitives:
 `Select` over direct Web Awesome selection/dropdown composition,
@@ -529,7 +855,12 @@ Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over
 Split Panel. `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
+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`. 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.
@@ -539,6 +870,7 @@ than default patterns. The detailed rationale lives in the theme contract.
 - [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)
@@ -557,3 +889,16 @@ For dimensions that should scale with the root font size, author pixels with
 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.