@kerfjs/ui 5.0.0-beta.8 → 5.0.0-beta.80

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 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.
 
@@ -23,60 +69,93 @@ npm install kerfjs @kerfjs/ui
 ```
 
 ```tsx
-import { MenuItem } from '@kerfjs/ui/menu-item';
-import { MenuHeader } from '@kerfjs/ui/menu-header';
-import { MenuActionRow } from '@kerfjs/ui/menu-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>
-    <MenuHeader
-      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',
-      }}
-    />
-    <MenuItem
-      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" />}
     />
-    <MenuActionRow
-      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.
 
-`MenuItem.rootAttributes`, `MenuHeader.rootAttributes`,
-`MenuActionRow.rootAttributes`, and `AppTab.rootAttributes` carry typed
+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`,
+`Catalog.stageRootAttributes`, `CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` carry typed
 application `data-*` metadata without
-teaching the package domain fields. `MenuHeader.triggerAttributes` and
-`MenuActionRow.trailingActionAttributes` additionally support native popover
+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.
-`MenuItem.trailing` is dormant metadata. Use `MenuActionRow` when a row needs
+`ListItem.trailing` is dormant metadata. Use `ListActionRow` when a row needs
 sibling primary and trailing native-button actions with independent names,
 disabled states, focus, and click ownership. Its `label`, `icon`, and
 `trailingActionIcon` slots are dormant content and must not contain controls.
@@ -90,70 +169,305 @@ 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` |
-| `ToolbarText` | `@kerfjs/ui/toolbar-text` | `@kerfjs/ui/toolbar-text.css` |
-| `MenuActionRow` | `@kerfjs/ui/menu-action-row` | `@kerfjs/ui/menu-action-row.css` |
-| `MenuItem` | `@kerfjs/ui/menu-item` | `@kerfjs/ui/menu-item.css` |
-| `MenuHeader` | `@kerfjs/ui/menu-header` | `@kerfjs/ui/menu-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
+| 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`            |
+| `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`             |
+| `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`     |
+| `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`          |
+| `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
 transform is applied. Direction changes take the shortest rotation path; a
 180-degree closed-to-open tie uses counterclockwise rotation.
 
-`MenuHeader` supplies that production `DisclosureArrow` automatically when
+`ListHeader` supplies that production `DisclosureArrow` automatically when
 `toggle` is true and `actionIcon` is omitted. Keep `expanded` synchronized with
 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
-`--kui-menu-header-action-icon-size`.
+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.
+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.
+
+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
@@ -183,41 +497,75 @@ 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>
-      <MenuHeader label="Workspace" count={3} countLabel="3 workspaces" />
-      <MenuItem action="open" label="Inbox" icon={inboxIcon} />
-      <MenuItem 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
-background without changing layout. `MenuHeader` follows the same rule while
+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.
 
@@ -237,10 +585,10 @@ Apps using Web Awesome's free components can 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
@@ -251,6 +599,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,
@@ -259,30 +610,37 @@ 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
@@ -306,8 +664,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" },
   ]}
 />
 ```
@@ -321,14 +679,27 @@ value through `data-segment-value`. Override an instance through
 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. 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
@@ -351,6 +722,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
@@ -360,15 +736,27 @@ 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:
 
 ```ts
-import '@kerfjs/ui/webawesome.css';
-import '@kerfjs/ui/select/register';
+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` and a `label`, then call `openPopupMenuAt(menu, event.clientX, event.clientY)` from the app's `contextmenu` handler; `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,
@@ -377,7 +765,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.
@@ -396,11 +789,25 @@ than default patterns. The detailed rationale lives in the theme contract.
 
 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 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.