@kerfjs/ui 5.0.0-beta.103 → 5.0.0-beta.105

package/llms.txt

@@ -231,18 +231,21 @@ title-style labels as `KUI-D040`. See
 
 ## Core rules (do the right thing)
 
-- **Prefer a Kerf UI component over a Web Awesome component over a raw HTML
-  tag**, using each for what it is good at. Never render a `Discouraged` Web
-  Awesome element (`wa-dropdown`, `wa-button-group`, `wa-select`, `wa-tab-group`,
-  `wa-icon`, …) directly; reach it only through the Kerf component that wraps or
-  replaces it (`PopupMenu`, `SegmentedControl`, `Select`, `TabBar`,
-  `LucideIcon`), and file a component gap rather than dropping to the raw tag.
+- **Prefer a Kerf UI component, then a native HTML element**, using each for
+  what it is good at. Kerf UI needs no Web Awesome; it is an optional
+  integration. Never render a `Discouraged` Web Awesome element (`wa-button`,
+  `wa-input`, `wa-checkbox`, `wa-select`, `wa-dropdown`, `wa-dialog`,
+  `wa-tab-group`, `wa-icon`, …); use the Kerf component that replaces it
+  (`Button`, `TextField`, `Checkbox`, `Select`, `PopupMenu`, `DialogSurface`,
+  `TabBar`, `LucideIcon`; see
+  [webawesome-migration.md](./docs/webawesome-migration.md)), and file a
+  component gap rather than dropping to the raw tag.
 - **Reach for the primitive, not for CSS.** The package is built to look right
   without an application customization layer. Before adding `padding`, `margin`,
   `width`, `height`, `border`, `background`, a wrapper card, or a decoration,
   check whether the component, pane, or content-item already owns it. Prefer a
   component prop — `FloatingToolbar inset`, `DisclosureArrow size`, `ListHeader
-headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
+headingLevel`, `SearchField clearIcon`, `ContentItem frame="framed"` for a
   visibly bounded content item — over overriding its `--kui-*` token. CSS for genuinely new structure
   belongs to the application-owned component that renders it and must not select
   nested Kerf or Web Awesome components.
@@ -270,8 +273,8 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   copy; `ValueTable density="compact"` reduces row spacing,
   with public row column, padding, and gap tokens for specific metadata layouts.
   `ToolbarText size="xsmall"` suits a dense rail heading. The
-  `TokenSearchField` editor shrinks in narrow groups; its minimum width can be
-  set with `--kui-token-search-editor-min-width`.
+  `SearchField` editor shrinks in narrow groups; its minimum width can be
+  set with `--kui-search-field-editor-min-width`.
 - **Label read-only field previews.** Use `FieldLabel` from `@kerfjs/ui/text`
   in `ListInsetControl sides="trl"` above a `ContentItem` value. Connect its
   id to the preview group's `aria-labelledby`; use the live control's own
@@ -367,7 +370,11 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   standard 17px text and 8px control inset; text wins on overlap.
   For selectable document tiles, use `selectionMode="multiple"` and a required
   `ariaLabel`, with `ContentItem selectionMode="multiple"` children. Wire
-  `wireContentItems` for spatial arrow navigation and Enter/Space activation.
+  `wireContentItems` for spatial arrow navigation, Enter/Space activation, and
+  one roving Tab stop per grid; a non-selectable row between them is a
+  `ContentItem gridRow` (row + gridcell, no selection).
+  Resolve each activation with `applySelection` and `selectionGesture` from
+  `@kerfjs/ui/selection` (plain replaces, Cmd/Ctrl toggles, Shift extends).
 - **Give a layout root `fill`, not a frame `Pane`.** A Row, List, or Grid that
   is the sole layout root of a definite-height parent takes its full height
   with `fill` and carries safe `data-*` markers through `rootAttributes`.
@@ -416,7 +423,7 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   or clear the value through ordinary change events. The app owns the updated
   controlled value and localized action labels.
   Icon-only Selects (single or multiple) and icon-only `PopupMenu`s show an
-  `aria-hidden` Web Awesome help tag repeating that name (and a Select's
+  `aria-hidden` help tag repeating that name (and a Select's
   choice) on hover and keyboard focus, hidden while the popup is open; the
   register import installs it, so do not add a `title` or tooltip of your own.
   The same installer tags an icon-only `<button>` or link inside a
@@ -437,7 +444,7 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
 - **Make room for an expanded search instead of growing it past what fits.** A
   collapsible search group grows into the space beside its sibling groups; if
   that space is too small, the siblings wrap onto a new row while it opens.
-  Size the expanded search to what fits (`--kui-token-search-expanded-width`,
+  Size the expanded search to what fits (`--kui-search-field-expanded-width`,
   or `sizing="grow"` with a `growBasis` that fits), and if a useful search
   cannot fit beside the other controls, set aside those controls while the
   search is open: mark them `visibility="yield-to-expanded-sibling"` (they
@@ -447,10 +454,10 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
 - **Toolbars hold only `ToolbarText` and `ToolbarControlGroup`.** Never put a bare
   button, input, link, or loose markup in a `leading`/`center`/`trailing` zone.
   Wrap every control — `SegmentedControl`, `Select`, a collapsible
-  `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. For an
+  `SearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. For an
   ordinary icon/action control inside the group use a **plain `<button>`** (the
-  group styles it fully) — that is the default; reach for `wa-button` only when you
-  need a Web Awesome feature. A toolbar popup menu is a `PopupMenu`
+  group styles it fully) — that is the default; a standalone `Button` belongs
+  outside a group. A toolbar popup menu is a `PopupMenu`
   (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`)
   in a `single` `ToolbarControlGroup` with `nestedDropdown`; never hand-write
   `wa-dropdown` markup for a menu. Let the group size the trigger from its icon,
@@ -459,6 +466,9 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   row, as in the catalog resource footer. `PopupMenu` items also support nested `submenu`
   actions, headings, dividers, checked or trailing choice marks, danger tone,
   and disabled reasons; nested headings/dividers stay out of keyboard choices;
+  a choice dispatches its `data-action` plus a bubbling `kui-menu-select` event whose
+  `detail.checked` is the state a checkbox choice asks for (the app owns and
+  renders that state);
   use `context` with `anchor` + `openPopupMenu` (or `openPopupMenuAt`) and
   `closePopupMenu` for pointer-anchored row menus; the menu owns its
   zero-footprint anchor host, so add no wrapper or CSS. `openPopupMenuAt`
@@ -503,7 +513,7 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   `ToolbarControlGroup` `material="glass"` paints a group that floats over imagery or a clear (transparent) toolbar on the translucent chrome material (`--kui-chrome-material` with the blur/saturate `--kui-chrome-material-filter`), with a specular edge in place of the gray border and a soft shadow. Its controls take `--kui-color-text`, so they stay at AA over any content; a raised or outline selection paints an opaque surface pill. The fill turns opaque under reduced transparency, increased contrast, static effects (`update: slow` or `:root[data-kui-effects="static"]`), or without backdrop-filter support, and paints Canvas/CanvasText in forced colors. A `tone="dark"` glass group keeps its loud fill and gains the blur and edge; a borderless group has no surface and ignores the material. Keep the solid default on an opaque toolbar, and never add your own `backdrop-filter` or translucent background to a group.
   `ListItem`, `ListItemLink`, and `ListActionRow` take `iconTile` to present their leading `icon` in a filled 32px rounded tile holding an 18px glyph, for settings or command rows that identify each entry by color. Pass a tone (`neutral`, `brand`, `success`, `warning`, or `danger`) for the same quiet fill, matching quiet border, and on-quiet foreground as `ToolbarControlGroup.tileTone`, or `{ color, foreground? }` for an application color: `color` is a `CssColor` (`uiColor()`, `colorVar()`, or `fillColor('#e5484d')`) and `foreground` a `CssForegroundColor`; without one, the glyph is black or white, whichever contrasts with the fill. The tile sits 6px clear of a standard 44px row (a compact row is at least 42px tall), moves the label to the tile's edge, and keeps its colors when the row is hovered or selected. Never wrap the icon in your own tile or resize the row's icon slot.
   Toolbar zones accept `KerfUiContent` directly. Use `ToolbarText` for identity and `ToolbarControlGroup` for related controls that need its shared chrome; a bare control keeps its own styling and accessibility responsibilities.
-  Expanded search groups accept `expandedOverflow="visible"` to anchor app-owned suggestion/date/help surfaces below their relative root; collapsed/default groups retain existing clipping. Apps own surface placement/dismissal and use `data-token-search-keep-open` or `collapsible.keepOpenOn` for focus.
+  Expanded search groups accept `expandedOverflow="visible"` to anchor app-owned suggestion/date/help surfaces below their relative root; collapsed/default groups retain existing clipping. Apps own surface placement/dismissal and use `data-search-field-keep-open` or `collapsible.keepOpenOn` for focus.
 
 - **Space by the five-step scale, by relationship not by eye.** `0`
   `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
@@ -596,9 +606,9 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   `TabBar trailingPlacement="adjacent"`, put the local action in `trailing`, and
   the workspace action in `end`; the component keeps both visible while its tab
   list shrinks and scrolls, without application descendant CSS. Each action
-  zone accepts one ToolbarControlGroup or a standalone `wa-button` for its own
-  Web Awesome chrome. Managed
-  TokenSearchField clear also preserves open state and replacement
+  zone accepts one ToolbarControlGroup or a standalone `Button` for its own
+  chrome. Managed
+  SearchField clear also preserves open state and replacement
   editor focus before the next input task, so shortcut-letter typing stays in search.
   Select All deletion does the same; deletion
   restoration finishes before the next keystroke rather than on a delayed frame.
@@ -610,13 +620,17 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   A sibling helper can call `model.commit(value)` for the active `name:` prefix
   even when that value is not suggested; invalid values and missing prefixes
   leave state unchanged.
-  The one richer case is `wireTokenSearchFields`, which manages the
+  A managed field subscribes the host render only to `model.structure`
+  (committed tokens, empty or non-empty text, editor revision), so typing plain
+  text never re-runs it; in the host's own render read `model.state.peek()` and
+  bind `model.result` as a signal hole instead of reading `model.state.value`.
+  The one richer case is `wireSearchFields`, which manages the
   collapsible field's expand/collapse/focus by default (on, per-behavior opt-out) and
   exposes the `expanded` signal on its handle — bind it in render or hand in your own
   via `collapsible.signals`. Do not hand-roll open/collapse/focus that helper
   provides; but do keep a plain disclosure toggle (a one-line boolean the app already
   renders from) in the app. For real-app composition it also offers a focusout
-  keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn`,
+  keep-open exception (`data-search-field-keep-open` regions or `collapsible.keepOpenOn`,
   so a sibling suggestions/date popover does not collapse an empty field), opt-in
   atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via
   `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an
@@ -629,15 +643,15 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
 - **Placeholder loading state, don't rebuild it.** For a value or component that is
   still loading, set `placeholder` on the component (`Select`, `ListHeader`,
   `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`,
-  `AppTab`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
+  `TabBarItem`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
   slots as subtle **unanimated** skeleton blocks and interactivity disabled. Only
   unknown values change: a placeholder is never dimmed or styled as disabled (a
   control you disabled keeps its live disabled tone), so a parent composes a
   faithful loading view (e.g. an inspector) without hand-rebuilding markup.
   Component-drawn chrome stays live: a `ListItem` or `ListActionRow` keeps its
   `busy` spinner while its `status` (and a `ListItem`'s `trailing`) content
-  become skeletons. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
-  (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
+  become skeletons. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`,
+  and never animate it — use
   `LoadingSpinner` for known busy activity instead. Set its `size` prop to a
   named icon step or positive pixel number when the inherited 1em is unsuitable.
 - **Keep ListItem content inside the row.** The rounded `ListItem` root clips
@@ -664,11 +678,11 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   fill with a native primary button and an options trigger (`aria-expanded`,
   `aria-haspopup`); `tone`, `fill`, `busy`, and `disabled` are props. Never
   build one from `wa-button-group` or app CSS on native buttons.
-- **Use `IconToggleButton` for an icon toggle outside a Toolbar.** In content or a
-  pane footer, `IconToggleButton({ icon, iconName, label, pressed, action })`
-  gives a native `aria-pressed` button the single contained toolbar group's
-  geometry; never wrap a `ToolbarControlGroup` outside a toolbar or restyle a
-  button to match it.
+- **Make any `Button` a toggle with `pressed`.** In content or a pane footer,
+  `<Button icon={…} ariaLabel="Show Conversation" emphasis="plain" pressed={open} action="toggle-chat" />`
+  renders a native `aria-pressed` button whose pressed look draws on top of
+  its tone and emphasis; the app flips the state. Never wrap a
+  `ToolbarControlGroup` outside a toolbar or restyle a button to fake it.
 - **Let an icon-state toggle skip selected chrome.** When a pressed toggle's
   glyph already shows its state (an empty or filled star), set
   `data-selected-chrome="none"` on that button, or `selectedChrome="none"` on
@@ -693,14 +707,31 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   that keeps the first and last rows' focus rings inside the clip, and the
   typed `CssLength` bounds need no flex-column ancestor. Never wrap a List in
   an app div with `max-height`, `overflow`, and a border.
-- **Square an icon-only button with `IconButton`.** Web Awesome squares a
-  `wa-button` only for a lone `wa-icon`; with a `LucideIcon` use
-  `IconButton({ icon, iconName, label })` (label required) instead of
-  overriding `wa-button::part(base)`. Inside a `ToolbarControlGroup` keep a
-  native `button`; the group owns its geometry.
+- **Use `Button` for every standalone action, icon-only included.**
+  `Button` (`@kerfjs/ui/button`) is a native button in a `tone` (`neutral`,
+  `brand`, `danger`) and an `emphasis` (`primary`, `secondary`, `plain`), at
+  the 44px control height or `size="compact"`, with an optional `icon`,
+  `loading`, `href`, form `type`, `shape` (`rounded` or `pill`), and `pressed`
+  for a toggle. With an `icon` and `ariaLabel` but no label it is an icon-only
+  square (a circle as a pill). Inside a `ToolbarControlGroup`
+  keep a native `button`; the group owns its geometry.
 - **Paint a strip's surface with `List surface`.** `surface="base"` or
   `"raised"` fills a List and its insets with a solid surface (a banner strip
   above a sunken work area); never wrap it in app CSS that sets a background.
+- **Use `TextField` for free text.** `@kerfjs/ui/text-field` is a native
+  input in one labeled box: `label` (or `ariaLabel`), `hint`, and `error` (its
+  description; an error marks it invalid), an optional `icon` and `clearable`
+  button, `multiline` with `rows` and a growing `maxRows`, and `maxLength` with
+  `showCount`, at the 44px height or `size="compact"`. Call
+  `wireTextFields(root)` (`@kerfjs/ui/wire-text-fields`) once for clearing and
+  counting. Never render `wa-input` or `wa-textarea` for a form field.
+- **Use `Checkbox`, `RadioGroup`, and `Switch` for native toggles.**
+  `@kerfjs/ui/checkbox` (with `indeterminate` and `wireCheckboxes(root)` from
+  `@kerfjs/ui/wire-checkboxes`), `@kerfjs/ui/radio-group` (`label`, `name`,
+  `choices`, `value`; one Tab stop, arrow keys), and `@kerfjs/ui/switch`
+  (`role="switch"`, only for a setting that applies immediately) draw Kerf
+  boxes over native inputs with hint and error text. Never render
+  `wa-checkbox`, `wa-radio-group`, or `wa-switch`.
 - **Use `Combobox` to pick or create a value by typing.** A themed native
   input on the ARIA combobox pattern with filtered suggestions and an optional
   create option; `wireComboboxes(root, { onCommit })` reports `{ id, value,
@@ -727,24 +758,59 @@ created, input }`. Never use a hand-styled `<input list>` + `<datalist>`.
   `wireCornerStatus` once: a top-layer manual popover at a safe-area-aware
   corner, with no close button, light dismiss, Escape, or focus change. Never
   position a banner with fixed-position CSS or hide a toast's close part.
+- **Style transient toasts with `@kerfjs/ui/overlay-toast.css`.** Import it
+  once and call `toast()` from `kerfjs/overlay` with `exitClass:
+'kui-toast-exit'` and `exitDuration: 200`: a bottom-edge, safe-area-aware
+  stack on the raised surface, `variant` tones, a `StateBanner` as the only
+  content, and reduced-motion-aware motion. Never use `wa-toast`.
+- **Style hover tooltips with `@kerfjs/ui/overlay-tooltip.css`.** Import it
+  once and call `tooltip(anchor, content)` from `kerfjs/overlay` with
+  `exitClass: 'kui-tooltip-exit'` and `exitDuration: 100`: the help tag's look,
+  wrapping at 40 characters. Icon-only Kerf controls already get help tags.
+  Never use `wa-tooltip`.
+- **Show and hide content with `Disclosure`** (`@kerfjs/ui/disclosure`): a
+  native details element with a DisclosureArrow on content-item geometry,
+  `plain` / `framed` / `sunken`; Disclosures sharing a `name` form an
+  accordion. Never use `wa-details` or `wa-accordion`.
+- **Show progress with `ProgressBar` or `ProgressRing`** (`@kerfjs/ui/progress-bar`,
+  `@kerfjs/ui/progress-ring`): `value` of `max` (omit `value` for
+  indeterminate), a `label`, `valueText`, tones. Never use `wa-progress-bar` or
+  `wa-progress-ring`.
+- **Pick a value on a range with `Slider`** (`@kerfjs/ui/slider`): a native
+  range input drawn as a track, fill, and thumb, with `showValue`/`unit`,
+  `ticks`, and `hint`; call `wireSliders(root)` once. Never use `wa-slider`.
+- **Collect tags with `TagField`** (`@kerfjs/ui/tag-field`): SearchField's
+  token editor as a form field, a hidden input per tag; call
+  `wireTagFields(root, { onChange })` and re-render. Never use `wa-tag-input`.
+- **Pick from a fixed palette with `ColorSwatches`** (`@kerfjs/ui/color-swatches`):
+  a native radio group of named round swatches, one Tab stop, a ring that
+  does not depend on hue, and a `'transparent'` no-color swatch.
+- **Choose any color with `ColorPicker`** (`@kerfjs/ui/color-picker`): an area,
+  hue and opacity sliders, RGB/HSL/HSB/Grayscale fields, hex, presets, and
+  samples; call `wireColorPickers(root, { onChange })` and re-render.
+- **Put a color in a form with `ColorField`** (`@kerfjs/ui/color-field`): a
+  swatch-and-hex trigger that opens a ColorPicker below it; call
+  `wireColorFields(root, { onChange, pickers })` and re-render. Never use
+  `wa-color-picker`.
 - **Size a Select through its API.** `triggerWidth` chooses `fit-content`,
-  `max-content`, or `fill`; `--kui-select-trigger-max-width` caps it. For custom
+  `max-content`, or `fill`; `maxTriggerWidth`/`minTriggerWidth` bound it under any
+  presentation, ellipsizing even `renderSelected` content. For custom
   selected text, use the public color, font-size, and font-weight tokens; the
   closed value ellipsizes when space runs out. `presentation="title"` gives a
   rail view heading a 36px bold, flush-start trigger and adjacent caret;
   `focusRingInset` keeps its ring inside clipping ancestors.
-- **Configure application tabs at their owners.** AppTab's `icon-only`
+- **Configure application tabs at their owners.** TabBarItem's `icon-only`
   presentation keeps `name` accessible, `labelMaxWidth` ellipsizes a long name,
   `nameOverflow="visible"` shows the full name during inline loading, and
   `dropTarget` highlights a drag-over without changing selection. `attention`
-  uses `--kui-app-tab-attention-color`. TabBar's public
+  uses `--kui-tab-bar-item-attention-color`. TabBar's public
   `--kui-tab-bar-strip-*` tokens set compact strip geometry.
   An inspector TabBar uses the shared rounded rectangle radius on its strip
   and inset segmented tabs; an ordinary segmented TabBar keeps pill ends and
   smaller interior tab corners. Configure the presentation instead of
-  restyling AppTab.
-  Set `pinned` on the first AppTab to keep it visible within a scrolling
-  tablist; it remains in keyboard order. Use `--kui-app-tab-pinned-background`
+  restyling TabBarItem.
+  Set `pinned` on the first TabBarItem to keep it visible within a scrolling
+  tablist; it remains in keyboard order. Use `--kui-tab-bar-item-pinned-background`
   for the surrounding surface and keep that backdrop opaque.
 - **Use `Badge` for compact non-interactive metadata.** Configure its semantic
   tone, appearance, shape, and size instead of creating badge CSS in an app or
@@ -782,10 +848,14 @@ created, input }`. Never use a hand-styled `<input list>` + `<datalist>`.
   the group with `label` or `labelledBy`, lead choices with a `swatch`
   (`CssColor` such as `fillColor('#3b82f6')`, or `'transparent'` for the struck-through no-color dot) or an
   `icon`, and handle the delegated `action` on `change`. Never wrap a
-  `SegmentedControl` or button-appearance `wa-radio` set instead. Set
-  `multiple` (with a `readonly Value[]` `value`) when any number may be on:
-  the same pills become native checkboxes in a `role="group"`, each a Tab stop
-  that Space toggles, and every checked value submits under `name`. On dark
+  `SegmentedControl` or a joined button group instead. Set
+  `multiple: 'toggle'` (with a `readonly Value[]` `value`) when any number may
+  be on and each pill toggles alone: native checkboxes in a `role="group"`,
+  each a Tab stop that Space toggles. Set `multiple: true` for the desktop
+  multi-select: a listbox where a click selects one, Cmd/Ctrl toggles, Shift
+  extends, and hidden inputs submit under `name`; wire it with
+  `wireChoiceChips` (`@kerfjs/ui/wire-choice-chips`) and read the set with
+  `readChoiceChips`. On dark
   inverse chrome, place the chips in a dark appearance scope (`.wa-dark`)
   instead of restyling them.
 
@@ -801,17 +871,18 @@ created, input }`. Never use a hand-styled `<input list>` + `<datalist>`.
   a hard edge (overlay on a solid `fadeTo` band) under reduced transparency. Never hand-roll scroll listeners or
   `background-attachment: fixed`.
 
-- **Use `Composer` for a chat or prompt composer.** `@kerfjs/ui/composer`
+- **Use `MessageComposer` for a chat or prompt composer.** `@kerfjs/ui/message-composer`
   renders a raised frame (standard border, large radius, `shadow-l`) whose
   border turns brand while focus is within, a borderless textarea that grows
   between `minRows` (default 1) and `maxRows` (default 8) lines and then
-  scrolls, and an action row with an optional quiet `hint` and the trailing
-  `actions` (a brand Send button). Name it with a title-style `label`; give it
-  an `id` so the hint describes the field. Slot it into a `DialogSurface`
-  floating footer (`footerInset="none"`) over a transcript. Never rebuild
+  scrolls, and a compact `Toolbar` action row: optional `leading` controls
+  (attach, a model `Select`), an optional quiet `hint`, and `trailing` actions
+  (a brand Send `Button`). Name it with a title-style `label`; give it
+  an `id` so the hint describes the field. Pass it as a `DialogSurface`'s
+  floating `footer` (`footerInset="none"`) over a transcript. Never rebuild
   composer chrome around a `wa-textarea` with app CSS. For Enter-to-send, set
-  `submitOnEnter` and call `wireComposers(root)` from
-  `@kerfjs/ui/wire-composers` once: Enter or Cmd/Ctrl+Enter clicks the first
+  `submitOnEnter` and call `wireMessageComposers(root)` from
+  `@kerfjs/ui/wire-message-composers` once: Enter or Cmd/Ctrl+Enter clicks the first
   trailing action, Shift+Enter inserts a newline, and an IME composition
   commit or an empty message never sends. Never hand-roll that handler.
 
@@ -819,9 +890,9 @@ created, input }`. Never use a hand-styled `<input list>` + `<datalist>`.
 
 `Badge`, `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarActionLink`, `FloatingToolbar`, `ToolbarText`, `Text`,
 `ListItem`, `ListActionRow` (+ `wireListReorder`, `reorderListItems`), `wireListFocusScroll`, `ListHeader`, `ListInsetControl`,
-`ListInsetText`, `SegmentedControl`, `ChoiceChips`, `Composer`,
-`Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
-`wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
+`ListInsetText`, `SegmentedControl`, `ChoiceChips`, `MessageComposer`,
+`Select`, `SearchField` (+ `readSearchField`, `placeSearchFieldCaret`,
+`wireSearchFields`), `TabBarItem`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
 `wireScrollDividers` (scroll-state dividers for every `Pane`, `NavStack`,
 `TabNavigator`, and `TabBar`),
 `ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
@@ -861,8 +932,11 @@ shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelTogg
 - [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
 - [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
 - [workbench.md](./docs/workbench.md): the `Workbench` multi-panel shell, its collapse policies, and opt-in `resizable` panels driven by `wireWorkbench` (`@kerfjs/ui/wire-workbench`: drag, keyboard, min/max, persistence, compact suspension), the `mainMinSize` / `mainMinHeight` work-area minimums (default 320px wide beside any inline rail, 120px tall above the drawer) that resizable panels stop at and inline panels shrink around, and a panel's `responsiveOverlayAt` (`narrow` / `compact`, rails and the bottom drawer) that presents it as an overlay below a Workbench container breakpoint without a device-class check; a panel given its `collapsed` signal is a transient overlay (collapsed on entering the breakpoint, takes focus and keeps Tab inside while open, closed by Escape or an outside press, focus returned; `dismissOverlays`), and overlays are exclusive by default (opening one closes the others; `exclusiveOverlays: false` opts out).
+- [workbench-dialog.md](./docs/workbench-dialog.md): `WorkbenchDialog`, the modal workbench dialog type: the title, actions, and close control in the work area's toolbar, full-height rails with their own toolbars, and overlay rails on compact devices.
+- [list-detail-dialog.md](./docs/list-detail-dialog.md): `ListDetailDialog`, the modal list-detail dialog type: full-height list and detail columns, the title and close control in the detail column, and a compact full-screen `NavStack` drill-down.
 - [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabNavigator` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
-- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
+- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome integration theme; catalog coverage means themed-and-supported for integration applications, not preferred. The UX sidebar tags every element a Kerf component replaces as `Discouraged`; Popup remains an available conditional positioning primitive.
+- [webawesome-migration.md](./docs/webawesome-migration.md): moving an application from Web Awesome elements to their Kerf replacements, then removing Web Awesome.
 - [ai/components/README.md](./ai/components/README.md): the generated per-component markdown reference — the assistant entry point over both JSON catalogs.
 - [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.
 - [compile-time-contracts-v1.json](./ai/compile-time-contracts-v1.json) + [type-contracts.md](./docs/type-contracts.md): stable compile diagnostics, packed-declaration proof, migrations, and explicit non-goals.
@@ -890,8 +964,8 @@ details.
 
 Select menus use native viewport shifting with 10px gutters: default menus grow to content (up to 20rem), while `fitMenu` matches trigger width and long labels wrap. Keep popup sizing and position repairs out of consumer CSS.
 
-Key sibling `DialogSurface`s that render conditionally with `rootAttributes={{ "data-key": "…" }}` so a re-render morphs each dialog into itself; never wrap one in a keyed app `div`. Modal `DialogSurface` bounds use typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`); explicit caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Application render state chooses responsive values, and preview layout remains application-owned. `height` sets a definite bounded modal size and `bodyLayout="fill"` lets one child fill the body; `bodyLayout="fill-last"` keeps leading rows at their height above one filling last child, and `footerPresentation="floating"` (with a typed `footerOffset`) floats a chat composer over the body while the body reserves its measured height; give the transcript `scrollClearance="block-end"` (a `scrollable` `List` or a `Pane`) to let it scroll beneath the composer, with the last message still resting above it, through the published `--kui-scroll-clearance-block-end` context (overlaying chrome publishes `--kui-scroll-clearance-block-start` / `-end`; one scroller per covered edge opts in; a composed Pane opts in through `PaneConfig.scrollClearance` on a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`). `headerPresentation="floating"` lays the title bar over the body on the translucent `--kui-chrome-material-raised` (opaque under reduced transparency, increased contrast, and forced colors); the register measures it and the body reserves it, and a `fill` body's only child with `scrollClearance="both"` scrolls beneath both the title bar and a floating composer through the published `--kui-scroll-clearance-block-start`. `presentation="bottom-sheet"` attaches the dialog to the bottom edge with square bottom corners, safe-area and virtual-keyboard clearance behind the panel, and a slide in/out (`enterMotion` / `exitMotion`); `resizable` adds a top grabber separator bounded by `minHeight` and `maxHeight`. `PopoverDialogSurface` is the non-modal, light-dismiss counterpart on the native Popover API, with the same size props and an `embedded` in-flow presentation; `describedBy` sets its `aria-describedby` (usually a title `ToolbarText`'s `descriptionId`).
+Key sibling `DialogSurface`s that render conditionally with `rootAttributes={{ "data-key": "…" }}` so a re-render morphs each dialog into itself; never wrap one in a keyed app `div`. Modal `DialogSurface` bounds use typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`); explicit caps stay within the dynamic viewport minus both gutters. Omitted props keep the default caps (20px clear of each edge, 80% of the viewport height at 420px wide or narrower). Application render state chooses responsive values, and preview layout remains application-owned. `height` sets a definite bounded modal size and `bodyLayout="fill"` lets one child fill the body; `bodyLayout="fill-last"` keeps leading rows at their height above one filling last child, and `footerPresentation="floating"` (with a typed `footerOffset`) floats a chat composer over the body while the body reserves its measured height; give the transcript `scrollClearance="block-end"` (a `scrollable` `List` or a `Pane`) to let it scroll beneath the composer, with the last message still resting above it, through the published `--kui-scroll-clearance-block-end` context (overlaying chrome publishes `--kui-scroll-clearance-block-start` / `-end`; one scroller per covered edge opts in; a composed Pane opts in through `PaneConfig.scrollClearance` on a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`). `headerPresentation="floating"` lays the title bar over the body on the translucent `--kui-chrome-material-raised` (opaque under reduced transparency, increased contrast, and forced colors); the register measures it and the body reserves it, and a `fill` body's only child with `scrollClearance="both"` scrolls beneath both the title bar and a floating composer through the published `--kui-scroll-clearance-block-start`. `presentation="bottom-sheet"` attaches the dialog to the bottom edge with square bottom corners, safe-area and virtual-keyboard clearance behind the panel, and a slide in/out (`enterMotion` / `exitMotion`); `resizable` adds a top grabber separator bounded by `minHeight` and `maxHeight`. `PopoverDialogSurface` is the non-modal, light-dismiss counterpart on the native Popover API, with the same size props and an `embedded` in-flow presentation; `describedBy` sets its `aria-describedby` (usually a title `ToolbarText`'s `descriptionId`).
 
-Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog` and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
+Render a modal dialog as `DialogSurface` itself, a native `<dialog>`: `label` (or `labelledBy` with a `heading`, such as an xl `ToolbarText` with a description) names it, `children` is its body, `footer` holds its buttons, and `headerActions` sit before its close button (`withoutHeader` drops the header for content that owns its heading and close control). Open it with `openDialog(dialog)` and close it with `closeDialog(dialog)` from `@kerfjs/ui/surface-scaffold`; never toggle its `open` attribute. The close button, any `data-dialog-close` element inside (a Cancel button), Escape, and, with `lightDismiss`, a backdrop press dispatch a cancelable `kui-request-close` (`detail.source`: `close-button`, `escape`, or `backdrop`); cancel it to keep the dialog open (the panel pulses). The native `close` event fires once it closes. `openDialog` installs the listeners and, while the dialog is open, measures its floating header/footer, follows a bottom sheet's keyboard and grabber, and keeps that state across re-renders; import `@kerfjs/ui/surface-scaffold/register` only when a dialog may open some other way. Do not write `wa-dialog` inside a `DialogSurface`.
 
 Toolbar visibility measurement probes and invisible state children are helper-owned and survive Kerf rerenders through `data-morph-preserve`. Actual CSS visibility stays stable while rendering removes transient parent markers, preventing geometry-driven render feedback and repeated probe recreation. Toolbar replacement, explicit internal-node removal and disposal retain their existing behavior.