@kerfjs/ui 5.0.0-beta.95 → 5.0.0-beta.97

package/ai/skill.md

@@ -234,11 +234,11 @@ Quick routing:
 | Navigation row                        | `ListItem`                                                 | Use an ordinary link or button when sidebar/menu anatomy and state do not apply. Its rounded root clips overflowing descendants; set `multiline` when the primary label should wrap. Multiline leading icons stay aligned with the first text line.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | Horizontal flex layout                | `Row`                                                      | Use `hAlign`/`vAlign`, a typed `gap`, and opt-in `wrap`; use `List` when the main axis is vertical.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | Equal-width columns                   | `Grid`                                                     | Use fixed `columns` or typed `minColumnWidth` for automatic container-width collapse, plus typed `gap`/`flex`. Use CSS grid for asymmetric/intrinsic tracks and `ResizableRegion` for adjustable boundaries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| Navigation row with a trailing action | `ListActionRow`                                            | Use `ListItem` when the trailing region is dormant; never put controls inside either component's SafeHtml slots. Multiline leading icons stay aligned with the first text line.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Page, panel, or dialog heading        | `Toolbar` + `ToolbarText`                                  | Use a direct extra-large `ToolbarText`, optional grouped icon, grouped trailing controls, and app-owned supporting copy below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| Exclusive choice                      | `TabBar`, `SegmentedControl`, or `Select`                  | Tabs switch tabpanels; segments expose a few choices; Select handles a longer value list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Navigation row with a trailing action | `ListActionRow`                                            | Use `ListItem` when the trailing region is dormant; never put controls inside either component's SafeHtml slots. Multiline leading icons stay aligned with the first text line. A trailing "…" overflow menu is `trailingMenu` (a real `PopupMenu`), not a trailing button.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Page, panel, or dialog heading        | `Toolbar` + `ToolbarText`                                  | Use a direct extra-large `ToolbarText`, optional grouped icon, grouped trailing controls, and short supporting copy as the `ToolbarText` `description` (quiet, one line, aligned under the title, with `descriptionId` for `aria-describedby`; longer copy stays app-owned content below).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Exclusive choice                      | `TabBar`, `SegmentedControl`, or `Select`                  | Tabs switch tabpanels; segments expose a few choices; `ChoiceChips` keeps a larger visible set as wrapping pills; Select handles a longer value list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Status or absent content              | `StateBanner` or `EmptyState`                              | `StateBanner` accepts an optional terse, tone-tinted `badge` beside its title for a count or compact status; do not rely on color alone. Web Awesome callouts suit ecosystem content; toasts are transient and never the only record of important state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| Compact metadata                      | `Badge`                                                    | Configure status, count, category, or metadata presentation with tone, appearance, shape, and size props. For new content without a count use `size="dot"` (no children) with a `label` or `ariaHidden`. Do not build badges with application CSS or use them as interactive controls.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Compact metadata                      | `Badge`                                                    | Configure status, count, category, or metadata presentation with tone, appearance, shape, and size props. For new content without a count use `size="dot"` (no children) with a `label` or `ariaHidden`. Cap long app-supplied text with `maxWidth` (a `CssLength`); it truncates with an ellipsis and the full string becomes the `title`. Do not build badges with application CSS or use them as interactive controls.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Loading placeholder                   | a component's `placeholder` prop, or `Skeleton`            | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render its real chrome with value slots as subtle **unanimated** skeletons and interactivity disabled; only unknown values change, so a placeholder is never dimmed or styled as disabled (a control whose own `disabled` / `trailingActionDisabled` / choice `disabled` / `actionDisabled` prop is set keeps its live disabled tone via the reserved `data-kui-disabled` marker) — do not hand-rebuild an empty state. Component-drawn chrome stays live too: a `ListItem` or `ListActionRow` placeholder keeps its `busy` spinner while its `status` text (and a `ListItem`'s `trailing` content, always a value) becomes a skeleton. `Skeleton` is the standalone block for a custom slot. A known `AppTab` that is still opening takes `pending` instead: it keeps its name (quiet, and as its accessible name) and the same geometry, shows your `trailing` spinner, and stays selectable (close and drag disabled) so your panel can show placeholders until it loads. Use `LoadingSpinner` for known busy activity, not a skeleton; never animate a skeleton; prefer it over `wa-skeleton`. |
 | Adjustable or asymmetric columns      | `ResizableRegion` or CSS grid                              | Use `ResizableRegion` only for a user-operable controlled separator, CSS grid for asymmetric/intrinsic tracks, and `Grid` for static equal-width tracks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Structured or ordinary search         | `TokenSearchField` or an input                             | Use token search only when text and ordered filter chips form one editor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
@@ -307,16 +307,16 @@ Hard rules:
     An application helper can call `model.commit(value)` for the active `name:` prefix when it computes a valid value outside suggestions; invalid values and missing prefixes leave the query unchanged.
 12. Demo work uses public production component subpaths and their browser-selected CSS. Focused demos and recipes have no local stylesheet, inline style, or styling-only class; use public components and `CatalogExample.viewport` for unavoidable specimen constraints (a recipe declares its frame through its exported `presentation`). When a recipe needs a capability no component offers, report the component gap instead of adding CSS. Use exactly three demo kinds: a `component` is one component with variants/states, a `composition` is a focused container of components commonly used together, and a `recipe` is the recommended production approach to a task. Organize catalog routes into product-important functional groups; within each group put all components before compositions, order each kind by importance with display-name alphabetical tie-breaking, and put recipes after every component/composition group. Show `Composition` as an entry tag instead of repeating the word in its name. Give every public visual component its own category-grouped catalog route; list themed third-party components under a clearly labeled collapsible ecosystem section, with a focused route for each. For the complete taxonomy, focused/composition decision, `CatalogExample` / `CatalogExampleStack` row/group nesting, specimen structure and metadata ownership, follow the single [Catalog demo authoring contract](../docs/catalog.md#catalog-demo-authoring-contract), discovered machine-readably through [`catalog-authoring.json`](./catalog-authoring.json). Never infer structure from private `kui-catalog-*` classes. Project each component's deterministic repository-relative demo source and existing documentation path so the detail can expose `View demo source` and `Read guidance` links without a runtime export; also derive first-party component implementation paths from their canonical browser imports, and label Web Awesome documentation as Kerf integration guidance. Declare direct `uses` relationships so `Used by` stays derivable, and theme shell chrome through the same semantic tokens as the stage instead of drawing a substitute. Enable `wireCatalog({ revealSelection: true })` for long desktop sidebars so controlled selections remain visible without moving focus; keep its default compact media guard unless compact scrolling is an explicit product behavior, and use `revealCatalogEntry` for an initial deep link.
 13. The Web Awesome theme makes Tooltip and Popover arrowless by default. Keep that default unless a pointer materially clarifies the anchor; opt back in with `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or a popover's public `--arrow-size`, and use `without-arrow` when local no-arrow intent should survive theme changes. Its non-field chrome uses `--kui-wa-control-inset` (8px controls/items), `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside Accordion, Card, Details, Callout, and Include), and `--kui-wa-container-inset` (16px Tab Panel content and framed disclosure regions). Plain Details use the 8px surface inset on the trigger and keep the body flush; plain Accordion items use it on both trigger and body. Outlined and sunken Details use the 16px container inset on the trigger and 8px on the body; framed Accordion items use 16px on both. Dialog maps its body to the 8px surface tier and its footer to the 16px container tier independently of `--spacing`. Override those tiers instead of restyling individual parts. Filled badges use each variant's quiet fill with normal text so their compact copy stays WCAG-AA readable; override the pair with `--kui-wa-badge-filled-background` / `--kui-wa-badge-filled-foreground`, not host selectors. When a dialog provides another dismissal affordance, put `hide-actions` on the `wa-dialog` host to hide its directly exported `header-actions` part; never chain `::part()` selectors through internal parts. Checkbox and Radio Group option regions, the Color Picker trigger, and Slider's complete interactive region receive the shared 8px logical inline outer inset because those controls have no bordered field shell. Known Date field captions and bordered text-like field hints align with values at the 9px border-plus-padding inset. OTP Input's label uses the same uppercase xs/650 treatment as other field labels, and both its label and hint use that 9px inset.
-14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Its UX sidebar marks superseded and exceptional entries `Discouraged`. Use `openAnchoredSurface` from `@kerfjs/ui/anchored-surface` for arbitrary interactive help or popup content beside a control, or `openAnchoredSurfaceAt` at pointer coordinates; pass an accessible label and let the app own content/actions. Consider Popup only when its lower-level behavior is specifically needed. Prefer Kerf `Select` over direct Dropdown/Dropdown Item/Select/Option composition, `SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over Split Panel. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame. Never render a `Discouraged` element directly in application, demo, or recipe markup; reach it only through the Kerf component that wraps it (`PopupMenu` renders `wa-dropdown`, `Select` renders `wa-select` / `wa-option`), and treat a Kerf component gap as a request to file, not a reason to drop to the raw element.
-15. Build sidebars, main areas, inspectors, and dialogs by rendering `Pane` (`@kerfjs/ui/pane`): an unpadded `.kui-pane` root, an optional `header`, one scrolling `.kui-pane__content`, and an optional `footer`; pick landmarks with `element` / `contentElement`. Never write a component's anatomy classes (`kui-pane`, `kui-toolbar`, `kui-list-item`, …) onto your own element to recreate it — render the component (`KUI-L103`). Only the catalog's `placeableClasses` (the `.kui-content` / `.kui-scroll-owner` / `.kui-control-cluster` / `.kui-inline-metadata` layout utilities, `.kui-app-root`, and `.kui-content-item` geometry on a non-div carrier) belong on elements you write. Use `Row` instead of a hand-written flex-row wrapper, `List` instead of a hand-written flex-column wrapper, and `Grid` instead of repeated equal-track CSS when children need a fixed positive count of evenly distributed columns. `Row` defaults to left/full with an `xs` gap and no wrapping; Grid defaults to an `xs` gap and keeps each track at `minmax(0, 1fr)`; List retains full/top and zero-gap defaults. The app owns Grid's responsive column-count changes. When a Row, List, or Grid is the layout root of a definite-height parent (an app root or a fixed-height frame), pass `fill` so it takes that full height, and put route/test/recipe `data-*` markers in its `rootAttributes`; never wrap a layout in a frame `Pane` just for height or a root attribute, because its content slot becomes a scroll owner that never scrolls. Inside a flex layout use `flex`, not `fill`. Use `List` when rows or sections also need flex growth, one vertical scroll owner, or physical-edge dividers. `dividerSides`, `textInsets`, and `controlInsets` use canonical physical `t`/`r`/`b`/`l` order; text geometry wins where text and control selections overlap. `ListInsetText` and `ListInsetControl` inset all four sides by default and accept the same `sides` grammar for selective edges. A dialog body is generally a `List`: set `DialogSurface bodyInset="none"` when its list children own geometry, and wrap bare dialog prose in `ListInsetText` so it aligns with bordered siblings without a second inset. Add `.kui-content` for 24px major vertical separation and render each ordinary surface-like child as `ContentItem` (`@kerfjs/ui/content-item`) for a child-owned 8px inline margin, 1px border, 8px padding, and 12px radius. Choose `frame="framed"` (neutral border in the always-reserved 1px, same geometry) only for a real distinction and `shape="pill"` for 22px; do not hand-write `<div class="kui-content-item">` or its modifier classes. There is no filled variant: a lowered filled surface is `SunkenPanel`. Do not pad pane shells, duplicate item geometry in wrappers, or create nested scroll owners. Align text to text and icons to icons across a pane — a title, a row label, and bare prose share the same text column (`ListInsetText` puts bare text on it); a border is decoration and never the alignment anchor, so a bordered surface extends to the pane gutter instead of being indented to line its border up with a heading's text.
+14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Its UX sidebar marks superseded and exceptional entries `Discouraged`. Use `openAnchoredSurface` from `@kerfjs/ui/anchored-surface` for arbitrary interactive help or popup content beside a control, or `openAnchoredSurfaceAt` at pointer coordinates; pass an accessible label and let the app own content/actions. It stays interactive inside a native `<dialog>`, `wa-dialog`, or `wa-drawer` (no host markup needed for the Web Awesome ones) and closes with that dialog. Consider Popup only when its lower-level behavior is specifically needed. Prefer Kerf `Select` over direct Dropdown/Dropdown Item/Select/Option composition, `SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over Split Panel. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame. Never render a `Discouraged` element directly in application, demo, or recipe markup; reach it only through the Kerf component that wraps it (`PopupMenu` renders `wa-dropdown`, `Select` renders `wa-select` / `wa-option`), and treat a Kerf component gap as a request to file, not a reason to drop to the raw element.
+15. Build sidebars, main areas, inspectors, and dialogs by rendering `Pane` (`@kerfjs/ui/pane`): an unpadded `.kui-pane` root, an optional `header`, one scrolling `.kui-pane__content`, and an optional `footer`; pick landmarks with `element` / `contentElement`. Never write a component's anatomy classes (`kui-pane`, `kui-toolbar`, `kui-list-item`, …) onto your own element to recreate it — render the component (`KUI-L103`). Only the catalog's `placeableClasses` (the `.kui-content` / `.kui-scroll-owner` / `.kui-control-cluster` / `.kui-inline-metadata` layout utilities, `.kui-app-root`, and `.kui-content-item` geometry on a non-div carrier) belong on elements you write. Use `Row` instead of a hand-written flex-row wrapper, `List` instead of a hand-written flex-column wrapper, and `Grid` instead of repeated equal-track CSS when children need a fixed positive count of evenly distributed columns. `Row` defaults to left/full with an `xs` gap and no wrapping; Grid defaults to an `xs` gap and keeps each track at `minmax(0, 1fr)`; List retains full/top and zero-gap defaults. The app owns Grid's responsive column-count changes. When a Row, List, or Grid is the layout root of a definite-height parent (an app root or a fixed-height frame), pass `fill` so it takes that full height, and put route/test/recipe `data-*` markers in its `rootAttributes`; never wrap a layout in a frame `Pane` just for height or a root attribute, because its content slot becomes a scroll owner that never scrolls. Inside a flex layout use `flex`, not `fill`. Use `List` when rows or sections also need flex growth, one vertical scroll owner, or physical-edge dividers. `dividerSides`, `textInsets`, and `controlInsets` use canonical physical `t`/`r`/`b`/`l` order; text geometry wins where text and control selections overlap. `ListInsetText` and `ListInsetControl` inset all four sides by default and accept the same `sides` grammar for selective edges. A dialog body is generally a `List`: set `DialogSurface bodyInset="none"` when its list children own geometry, and wrap bare dialog prose in `ListInsetText` so it aligns with bordered siblings without a second inset. Add `.kui-content` for 24px major vertical separation and render each ordinary surface-like child as `ContentItem` (`@kerfjs/ui/content-item`) for a child-owned 8px inline margin, 1px border, 8px padding, and 12px radius. For a chat transcript, set `bubble="start"` (other participants) or `bubble="end"` with `appearance="brand-loud"` (the person's own messages) instead of app width, alignment, or color CSS; the item fits its message up to 80% of the row. Choose `frame="framed"` (neutral border in the always-reserved 1px, same geometry) only for a real distinction and `shape="pill"` for 22px; do not hand-write `<div class="kui-content-item">` or its modifier classes. There is no filled variant: a lowered filled surface is `SunkenPanel`. Do not pad pane shells, duplicate item geometry in wrappers, or create nested scroll owners. Align text to text and icons to icons across a pane — a title, a row label, and bare prose share the same text column (`ListInsetText` puts bare text on it); a border is decoration and never the alignment anchor, so a bordered surface extends to the pane gutter instead of being indented to line its border up with a heading's text.
     15a. Use `Text` from `@kerfjs/ui/text` for ordinary headings, paragraphs, and inline secondary text outside toolbar title zones. Omit `variant` for the default `p`, pass `h1`–`h6` according to the document outline, or use `variant="span"` inside a row, label, or table cell; ordinary native attributes pass through. Express supporting, error, compact, or code text with the independent finite `tone="quiet|danger"`, `size="compact"`, and `font="monospace"` props instead of global utility classes or appearance-only heading choices. Block Text variants own a transparent 1px border and the standard item padding; `span` owns no box geometry. Keep toolbar identity/title content on `ToolbarText` and list-aligned bare prose on `ListInsetText`. `ToolbarText` below `xlarge` is intentionally quiet identity text in default tone; a normal-color subsection title is `Text` with an `h2`–`h6` variant (or `ListHeader` for a list or menu section), never a recolored `ToolbarText`. Use `controlMargins` with canonical physical Sides for an exterior 8px control gutter without a Row wrapper; avoid stacking parent insets, and remember spans retain native inline margin behavior.
 
 16. Keep a visible collapsible pane's collapse control in its own toolbar. When hidden, move its restore control into the adjacent main toolbar on the corresponding logical edge: leading for an inline-start sidebar and trailing for an inline-end inspector. Collapse the pane completely; do not preserve an empty icon-only rail.
     16a. Dividers between pinned chrome and scrolling content are component chrome: a `Toolbar` draws none by default (`dividerSides` is for a permanent edge only). Call `wireScrollDividers(appRoot)` from `@kerfjs/ui/wire-scroll-dividers` once and retain its disposer; a plain `Pane` with `chromeDividers="scroll"` draws the line under its header only while content is scrolled beneath it and over its footer only while more content lies below (never when the content fits), every `NavStack`'s top chrome and bottom toolbar and every `TabNavigator` bar do the same around the active view or scene (keyed on whatever actually scrolls there, including a sole `Pane`'s content), and every `TabBar` marks each side of its strip with tabs scrolled out of view. Configure a pane with `chromeDividers` (`scroll` by default for plain panes, `always` by default for sunken panes, or explicit `scroll`, `always`, `none`, also via `PaneConfig`); `always` draws both lines even when content fits. A `NavStack` or `TabNavigator` has its own `chromeDividers` (same values: `always` draws the chrome lines without the wiring, `none` never, even when wired; a `SplitView` forwards it through `compactStack`); a `toolbarConfig.dividerSides` edge stays the Toolbar's own. Name app-owned chrome by id in `targets`. The wiring writes only `data-scroll-overflow` / `data-scroll-divider` state; never write a border onto a component to show a divider.
-17. Each `Toolbar` zone accepts `KerfUiContent` directly, including status content, native controls, and application markup. Put identity/title text directly in the zone as `ToolbarText`; use `ToolbarControlGroup` when related controls need shared toolbar chrome, sizing, hover treatment, or overflow behavior. Bare controls keep their own styling and accessibility responsibilities. A standalone primary `wa-button` in trailing keeps its own Web Awesome chrome. `SegmentedControl`, `Select`, and `TokenSearchField` can live inside a group when they need that shared presentation. Configure zone behavior with `Toolbar.centerAlign` and its `responsive` / `responsiveAt` policy instead of selecting toolbar zone classes. No policy clips an action: trailing (and stacked center) zones wrap whole groups onto another row, and the center zone never compresses below its content (a leading title too long for the row truncates with an ellipsis instead), so never hide or shrink a toolbar control to make it fit; use `responsive="wrap"` for a heading whose title must stay whole, and move genuinely lower-priority commands into an app-owned "More" popup menu. For an ordinary icon/action control inside a group, use a plain `<button>` (the group styles `> button` fully) — that is the default; reach for `wa-button` only when you need a Web Awesome feature. A popup menu in a toolbar is a `PopupMenu` (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`) in a `single` group with `nestedDropdown` and a `menuInset`: give it typed `items` (commands with `action`s, `heading`s, `divider`s) and a trigger `icon` plus visible `text` or an accessible `label`; never hand-write `wa-dropdown` / `wa-dropdown-item` markup for a menu. Let the group size that trigger from its icon, localized text, and caret; do not force a width on the menu or button. By default a group stays on one row: each icon sits beside its label, and the toolbar's `responsive` policy relocates whole groups when needed. Set `overflow="wrap"` only for independent links that should move as whole actions to another row within the group; use `overflow="scroll"` for a bounded one-row action strip. A `ToolbarText` is one line ending in an ellipsis by default; opt into `wrap` (capped by `maxLines`) or `ellipsis={false}` deliberately. Inside a group, a `Select` or `PopupMenu` trigger drops its focus ring while its popup is open (the open popup and its current row show where focus is) and the ring returns when the popup closes; a ring follows the control's shape (a pill for an icon-and-caret trigger, a circle for a compact icon button) — set `focusRingOwner="group"` on a Select whose group paints the composed ring, and never add CSS to show, hide, or reshape a ring. For a compact mixed group, keep the standard item padding and raised selected chrome; the selected item paints over the outer border without an internal separator. For an avatar control, set `content="avatar"` and `avatarImage` on the group instead of inserting an `img`: a lone control paints the contained image on the outer group and a multi-button group paints it only on the pressed selection highlight. Compose panel/dialog/page headings with a direct extra-large `ToolbarText`, optional grouped icon, grouped trailing controls, and app-owned supporting copy below. A non-interactive heading icon is an icon tile: put the `LucideIcon` directly in its `ToolbarControlGroup` (it takes an icon button's 40px slot and centers), never inside a `<button>` that does nothing. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Each zone item sits in the toolbar's top 44px control band, centered by its own size; a taller item (a wrapped title, a second trailing row) starts at the band's top and grows down without moving the others, so a wrapped `ToolbarText` keeps trailing controls beside its first line — do not add alignment CSS for this. Split dormant and interactive regions: `ListHeader` fills the available inline width by default; set `width="content"` to shrink-wrap while retaining its normal geometry, or `inline` when it belongs in surrounding text without outer margin, border, or padding. It keeps its label and either a semantic count or independent `badge` and `status` indicators together, with an independent logical-end action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size` inside a fitted 36px hover square whose transparent hit layer keeps the pointer target at least 44px (44px wide by the 36px row in `density="compact"`); never shrink the target to match the visual, and never force the button to 44px. Pass a sole non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a bare number in `badge`. For a contextual phrase such as "3 lines unpriced", `badge` can appear beside `status`, and either may be `undefined`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets. Dividers are chrome and earn their place: a `Toolbar` draws none by default, and the line between pinned chrome and scrolling content comes from scroll state (rule 16a), so never add a border, a permanent `dividerSides`, or a margin to fake or adjust one.
+17. Each `Toolbar` zone accepts `KerfUiContent` directly, including status content, native controls, and application markup. Put identity/title text directly in the zone as `ToolbarText`; use `ToolbarControlGroup` when related controls need shared toolbar chrome, sizing, hover treatment, or overflow behavior. Bare controls keep their own styling and accessibility responsibilities. A standalone primary `wa-button` in trailing keeps its own Web Awesome chrome. `SegmentedControl`, `Select`, and `TokenSearchField` can live inside a group when they need that shared presentation. Configure zone behavior with `Toolbar.centerAlign` and its `responsive` / `responsiveAt` policy instead of selecting toolbar zone classes. No policy clips an action: trailing (and stacked center) zones wrap whole groups onto another row, and the center zone never compresses below its content (a leading title too long for the row truncates with an ellipsis instead), so never hide or shrink a toolbar control to make it fit; use `responsive="wrap"` for a heading whose title must stay whole, and move genuinely lower-priority commands into an app-owned "More" popup menu. For an ordinary icon/action control inside a group, use a plain `<button>` (the group styles `> button` fully) — that is the default; reach for `wa-button` only when you need a Web Awesome feature. A popup menu in a toolbar is a `PopupMenu` (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`) in a `single` group with `nestedDropdown` and a `menuInset`: give it typed `items` (commands with `action`s, `heading`s, `divider`s) and a trigger `icon` plus visible `text` or an accessible `label`; never hand-write `wa-dropdown` / `wa-dropdown-item` markup for a menu. Let the group size that trigger from its icon, localized text, and caret; do not force a width on the menu or button. By default a group stays on one row: each icon sits beside its label, and the toolbar's `responsive` policy relocates whole groups when needed. Set `overflow="wrap"` only for independent links that should move as whole actions to another row within the group; use `overflow="scroll"` for a bounded one-row action strip. A `ToolbarText` is one line ending in an ellipsis by default; opt into `wrap` (capped by `maxLines`) or `ellipsis={false}` deliberately. Inside a group, a `Select` or `PopupMenu` trigger drops its focus ring while its popup is open (the open popup and its current row show where focus is) and the ring returns when the popup closes; a ring follows the control's shape (a pill for an icon-and-caret trigger, a circle for a compact icon button) — set `focusRingOwner="group"` on a Select whose group paints the composed ring, and never add CSS to show, hide, or reshape a ring. For a compact mixed group, keep the standard item padding and raised selected chrome; the selected item paints over the outer border without an internal separator. For an avatar control, set `content="avatar"` and `avatarImage` on the group instead of inserting an `img`: a lone control paints the contained image on the outer group and a multi-button group paints it only on the pressed selection highlight. Compose panel/dialog/page headings with a direct extra-large `ToolbarText`, optional grouped icon, grouped trailing controls, and short supporting copy as the `ToolbarText` `description` (quiet, one line, aligned under the title, with `descriptionId` for `aria-describedby`; longer copy stays app-owned content below). A non-interactive heading icon is an icon tile: put the `LucideIcon` directly in its `ToolbarControlGroup` (it takes an icon button's 40px slot and centers), never inside a `<button>` that does nothing. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Each zone item sits in the toolbar's top 44px control band, centered by its own size; a taller item (a wrapped title, a second trailing row) starts at the band's top and grows down without moving the others, so a wrapped `ToolbarText` keeps trailing controls beside its first line — do not add alignment CSS for this. Split dormant and interactive regions: `ListHeader` fills the available inline width by default; set `width="content"` to shrink-wrap while retaining its normal geometry, or `inline` when it belongs in surrounding text without outer margin, border, or padding. It keeps its label and either a semantic count or independent `badge` and `status` indicators together, with an independent logical-end action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size` inside a fitted 36px hover square whose transparent hit layer keeps the pointer target at least 44px (44px wide by the 36px row in `density="compact"`); never shrink the target to match the visual, and never force the button to 44px. Pass a sole non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a bare number in `badge`. For a contextual phrase such as "3 lines unpriced", `badge` can appear beside `status`, and either may be `undefined`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets. Dividers are chrome and earn their place: a `Toolbar` draws none by default, and the line between pinned chrome and scrolling content comes from scroll state (rule 16a), so never add a border, a permanent `dividerSides`, or a margin to fake or adjust one.
     For a toolbar heading that must remain at the 20px `--kui-font-l` step, use `ToolbarText size="xlarge-fixed"`; `xlarge` retains the responsive page-title clamp. Pass `headingLevel` when it is a section landmark.
 
-18. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, toolbar title/supporting-copy ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. For multi-line banner copy use `copyLayout="stacked"`; use `actionPlacement="below"` for an action on its own trailing row. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.
+18. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, toolbar title/supporting-copy ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. For multi-line banner copy use `copyLayout="stacked"`; use `actionPlacement="below"` for an action on its own trailing row. For a full-width status band at a layout edge (above a workspace), use `presentation="strip"` with optional `dividerSides` (bottom by default) instead of zeroing the card's margin, radius, and border tokens. For non-dismissible app-level progress with no home beside the affected work ("Loading…", "Updating… 3 of 12"), host the banner in `CornerStatus` and call `wireCornerStatus` once instead of fixed-position CSS or a toast with its close part hidden. For an icon-only `wa-button` with a `LucideIcon` (a Browse button beside a field), use `IconButton` (required `label`) rather than overriding `wa-button::part(base)` width, min-height, or padding. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.
 
 For compact `Select` triggers, set `triggerWidth` to `fit-content`, `max-content`,
 or `fill` and use `--kui-select-trigger-max-width` for a cap. Style custom
@@ -338,7 +338,7 @@ Set `pinned` on the first `AppTab` when it must stay visible while peers scroll.
 
 Use `--kui-resizable-region-background` for a region surface and `contentOverflow="visible"` while its anchored popup needs to escape. Choose a top or bottom `restorePosition`, typed `restoreInset`, or `restorePlacement="inline"` for its collapsed restore control. `FloatingToolbar placement="inline"` stays in normal flow; its per-edge inset tokens and `safeAreaInsets` configure floating placement.
 
-Use `ListItem density="spacious"` for larger option rows, `multiline` plus `multilineIconAlign="center"` when its icon should center on wrapped copy, `divider` for row separators, and `state="drag-target"` for the drop target treatment. Public `--kui-list-item-*` tokens adjust row, icon, label, and trailing geometry and color; ListHeader height, title padding, and border tokens adjust section density.
+Use `ListItem density="spacious"` for larger option rows, `multiline` plus `multilineIconAlign="center"` when its icon should center on wrapped copy, `divider` for row separators (for lines only between rows, every row but the last takes `divider="after"` and the last `"none"`; corners are flat wherever a divider line meets them, so the group rounds only its outer corners), and `state="drag-target"` for the drop target treatment. For a reorderable list, set `draggable` and `itemId` on each `ListItem`, `ListItemLink`, or `ListActionRow` and call `wireListReorder(root, { onReorder })` from `@kerfjs/ui/wire-list-reorder` once: it dims the dragged rows, draws the brand insertion line on the hovered row's `before`/`after` edge, supports Alt+Shift+ArrowUp/ArrowDown, and reports `{ listId, sourceIds, target: { id, position }, source }` (a selected or pressed row drags every selected row of its `List`; `data-list-id` on the `List` names it). Apply it with `reorderListItems` and re-render; the `dragging` and `dropPosition` props render the same states from app-owned drag state. Never hand-style drag rows. Public `--kui-list-item-*` tokens adjust row, icon, label, and trailing geometry and color; ListHeader height, title padding, and border tokens adjust section density.
 
 Set `ListHeader.size` to `xs`, `sm`, `m`, `l`, or `xl` for label scale. The default `sm` remains the small uppercase style shared with `FieldLabel`; `xs` is 2xs and capitalized, while `m`/`l`/`xl` match themed h5/h4/h3 typography. Choose `headingLevel` separately from the document outline.
 
@@ -346,10 +346,10 @@ For a filled command list, scope `--kui-list-item-background`, `--kui-list-item-
 
 Use `Toolbar responsive="trailing-priority"` when an expanded trailing search needs a full second row below its heading at `responsiveAt`. Configure a leading minimum width, trailing gap and justification, or zone inline padding with the public `--kui-toolbar-*` tokens rather than selectors into toolbar zones.
 
-Set `--kui-toolbar-inset: 0px` on an embedded Toolbar to remove its outer padding while retaining `--kui-toolbar-gap` between zones. The same inset token controls the minimum-height allowance; safe-area padding still applies at claimed edges.
+For a 40px header embedded in a panel or card, pass `Toolbar density="compact"` (a 34px control band with 3px block insets) and give its groups `size="compact"`; never shrink a Toolbar with CSS. Workbench, CollapsiblePanel, NavStack, and SplitView toolbars take `density` through their `ToolbarConfig` and size the groups they compose (panel toggles, the back button) to match; pass `density` to `CollapsiblePanelRelocated` when the destination toolbar is compact. Set `--kui-toolbar-inset: 0px` on an embedded Toolbar to remove its outer padding while retaining `--kui-toolbar-gap` between zones. The same inset token controls the minimum-height allowance; safe-area padding still applies at claimed edges.
 
-For compact dialog copy, use `Text flush lineHeight="tight"`; for compact metadata, use `ValueTable density="compact"` and its public row columns/padding/gap tokens. `ToolbarText size="xsmall"` fits a dense rail heading. A `TokenSearchField` editor shrinks inside a narrow group by default; set `--kui-token-search-editor-min-width` when a minimum is needed. A full-height shell uses the one `.kui-app-root` mount container documented in `docs/document-baseline.md`.
-When importing the opt-in `@kerfjs/ui/document.css` baseline, native `th`, `td`, `button`, `input`, `select`, and `textarea` inherit the surrounding font family, size, and line height; table headers retain their native emphasis. Load application typography overrides after the baseline.
+For compact dialog copy, use `Text flush lineHeight="tight"`; center short status copy with `Text align="center"` (or end-align a value with `align="end"`) rather than setting `text-align` on `.kui-text`; for compact metadata, use `ValueTable density="compact"` and its public row columns/padding/gap tokens. `ToolbarText size="xsmall"` fits a dense rail heading. A `TokenSearchField` editor shrinks inside a narrow group by default; set `--kui-token-search-editor-min-width` when a minimum is needed. A full-height shell uses the one `.kui-app-root` mount container documented in `docs/document-baseline.md`.
+When importing the opt-in `@kerfjs/ui/document.css` baseline, native `th`, `td`, `button`, `input`, `select`, and `textarea` inherit the surrounding font family, size, and line height; table headers retain their native emphasis. The baseline also gives native controls zero-specificity semantic cursors (pointer on enabled buttons, links, role=button, checkbox/radio inputs, and selects; not-allowed on disabled controls and a disabled `wa-button`; text on text inputs), so do not ship an app-wide cursor stylesheet. A full-viewport shell whose document must never scroll adds `data-viewport="locked"` to its body-child `.kui-app-root` (100dvh plus `overflow: clip` on `html`, `body`, and the root) instead of app CSS. Load application typography overrides after the baseline.
 
 For a read-only field preview that replaces a Web Awesome input, use `FieldLabel` from `@kerfjs/ui/text` above the preview. Put it in `ListInsetControl sides="trl"` beside a `ContentItem` value; give it an id and use `aria-labelledby` on the preview group. The app owns preview/edit state and hint copy.
 
@@ -357,46 +357,48 @@ For a read-only field preview that replaces a Web Awesome input, use `FieldLabel
 
 Common mistakes:
 
-| Mistake                                                                                                                           | Fix                                                                                                                                                                                                                                                                                           |
-| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Hard-coded project/transport action in a component                                                                                | Pass a semantic `data-action` string from an application adapter                                                                                                                                                                                                                              |
-| Per-instance signal at module scope                                                                                               | Create state in the application or a factory and pass it in                                                                                                                                                                                                                                   |
-| `role="menuitem"` on one button                                                                                                   | Use the native button, or implement the complete ARIA menu widget                                                                                                                                                                                                                             |
-| Put a button/link/interactive role in `ListItem.trailing` or a `ListActionRow` SafeHtml slot                                      | Use `ListActionRow` for the sibling controls and keep its label/icon slots dormant                                                                                                                                                                                                            |
-| Copy ListItem/ListHeader markup to add product data or a popover target                                                           | Use the typed `rootAttributes`/`triggerAttributes` slots and retain the component's protected semantics                                                                                                                                                                                       |
-| Concatenate a section count into a ListHeader label or numeric badge                                                              | Pass `count={value}` and a localized full phrase such as `countLabel="3 notes"`; reserve `badge` for non-count SafeHtml                                                                                                                                                                       |
-| Put a chevron on navigation that reveals nothing                                                                                  | Remove it, or model a real controlled `ListHeader` disclosure; omit `actionIcon` to use the production `DisclosureArrow`                                                                                                                                                                      |
-| Test only a custom-element attribute                                                                                              | Assert live property, emitted event, focus, and rendered output                                                                                                                                                                                                                               |
-| Import all Web Awesome components                                                                                                 | Import only `@kerfjs/ui/select/register` for `Select`, or individual Web Awesome modules for other controls; `webawesome.css` registers no JavaScript                                                                                                                                         |
-| Write `wa-*` JSX without activating its types                                                                                     | Add `import type {} from '@kerfjs/ui/webawesome'`; registration and theme imports remain separate                                                                                                                                                                                             |
-| Maintain a root list of component styles                                                                                          | Import each visual component from its JS subpath; its reachable CSS follows automatically                                                                                                                                                                                                     |
-| Add demo-only markup for a production state                                                                                       | Add the state to the production component, then render that export in the catalog                                                                                                                                                                                                             |
-| Choose a listed ecosystem component by default                                                                                    | Apply the component-selection guidance above; catalog coverage means supported and themed, not preferred                                                                                                                                                                                      |
-| Add sidebar-specific wrapper padding                                                                                              | Use the unpadded `.kui-pane`; let `ListHeader`, `ListItem`, and `ContentItem` own their 8/1/8 geometry                                                                                                                                                                                        |
-| Expect a bare toolbar control to receive group chrome automatically                                                               | Style and name the direct control itself, or use `ToolbarControlGroup` when controls need shared chrome                                                                                                                                                                                       |
-| Reach for `wa-button` for a plain control inside a `ToolbarControlGroup`                                                          | Use a plain `<button>` (the group styles it fully); for a popup menu use `PopupMenu`, which renders its own trigger                                                                                                                                                                           |
-| Render a `Discouraged` Web Awesome element (`wa-dropdown`, `wa-button-group`, `wa-select`, `wa-tab-group`, `wa-icon`, …) directly | Use the Kerf component that wraps or replaces it (`PopupMenu`, `SegmentedControl`, `Select`, `TabBar`, `LucideIcon`); file a component gap rather than dropping to the raw element. `KUI-L301` (`ui-preferences`, also run by `kerf-ui-doctor`) reports the raw tag and names the replacement |
-| Let a toolbar group wrap, or stack an icon above its label                                                                        | Keep icon and label on one row and let the group size to its content; relocate whole groups with the toolbar's `responsive` policy                                                                                                                                                            |
-| Add CSS to show, hide, or reshape a Select or PopupMenu trigger's focus ring                                                      | Nothing: the ring follows the control's shape and drops while the popup is open; set `focusRingOwner="group"` when the group paints the composed ring                                                                                                                                         |
-| Add a border or a permanent `dividerSides` under pinned chrome to separate it from scrolling content                              | Call `wireScrollDividers(appRoot)` once: a `Pane` draws the line only while content is scrolled beneath it, and never pad below a divider to adjust it                                                                                                                                        |
-| Add a `title` or `wa-tooltip` to an icon-only `Select` or `PopupMenu` trigger                                                     | Nothing: the register import already shows an `aria-hidden` help tag with the accessible name on hover and keyboard focus                                                                                                                                                                     |
-| Add a `title` or `wa-tooltip` to an icon-only toolbar `<button>`                                                                  | Name it with `aria-label` only; a registered Select/PopupMenu or `@kerfjs/ui/help-tags/register` shows the same help tag for it                                                                                                                                                               |
-| Hand-write `wa-dropdown` / `wa-dropdown-item` markup for an action menu                                                           | Use `PopupMenu` with typed `items` in a `single` `ToolbarControlGroup` with `nestedDropdown`                                                                                                                                                                                                  |
-| Let the document, pane, and list all scroll                                                                                       | Keep fixed chrome outside one `.kui-pane__content` scroll owner per pane                                                                                                                                                                                                                      |
-| Invent an `@kerfjs/ui` command-palette export                                                                                     | Keep the semantics application-local, reuse public layout vocabulary, and propose recurring behavior upstream                                                                                                                                                                                 |
-| Handwrite `ValueTable` row wrappers or compensate their padding or separators                                                     | Compose `ValueTableRow`; its root-scaled block padding, optional icon hook, and separator geometry are public contract                                                                                                                                                                        |
-| Rebuild a panel/dialog heading with bespoke CSS or a private wrapper                                                              | Compose a plain `Toolbar` with a direct xl `ToolbarText`, optional grouped icon, grouped trailing controls, and app-owned supporting copy below                                                                                                                                               |
-| Put an xl `ToolbarText` in a narrow rail or drawer header                                                                         | Use the default size there as pane identity; xl truncates at the minimum size ("Ins…" in a 160px rail)                                                                                                                                                                                        |
-| Force a `width`/`height`/`padding` on a component to size or space it                                                             | Let it size to its content and tokens; a forced box leaves a halo or a stretched oval — adjust an icon-size or spacing token, not the box                                                                                                                                                     |
-| Wrap a component or region in a card, border, backdrop, or outline to "contain" it                                                | Let it sit on the surface; add a `ContentItem frame="framed"` only for a real distinction — hierarchy comes from alignment, spacing, and type first                                                                                                                                           |
-| Override a component's `--kui-*` token to inset, size, or frame it                                                                | Use the typed prop: `FloatingToolbar inset`, `DisclosureArrow size`, `ListHeader headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"`                                                                                                                                    |
-| Add another container's padding on top of a content-item's own margin                                                             | Pick one owner of the inset; a pane has no padding and its `.kui-content` children own the 8/1/8 geometry — stacking them double-insets                                                                                                                                                       |
-| Put raw prose directly in a padded dialog body                                                                                    | Compose the body as `List`, set `bodyInset="none"` for list-owned geometry, and wrap bare prose in `ListInsetText`                                                                                                                                                                            |
-| Keep chrome, a label, or a readout that aids no decision                                                                          | Delete it; every element must help a person decide or act                                                                                                                                                                                                                                     |
-| Override a component's default size or color because it "looks off"                                                               | Trust the default (a LucideIcon is 24px) and fix the surrounding layout instead                                                                                                                                                                                                               |
+| Mistake                                                                                                                           | Fix                                                                                                                                                                                                                                                                                                         |
+| --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Hard-coded project/transport action in a component                                                                                | Pass a semantic `data-action` string from an application adapter                                                                                                                                                                                                                                            |
+| Per-instance signal at module scope                                                                                               | Create state in the application or a factory and pass it in                                                                                                                                                                                                                                                 |
+| `role="menuitem"` on one button                                                                                                   | Use the native button, or implement the complete ARIA menu widget                                                                                                                                                                                                                                           |
+| Put a button/link/interactive role in `ListItem.trailing` or a `ListActionRow` SafeHtml slot                                      | Use `ListActionRow` for the sibling controls and keep its label/icon slots dormant                                                                                                                                                                                                                          |
+| Copy ListItem/ListHeader markup to add product data or a popover target                                                           | Use the typed `rootAttributes`/`triggerAttributes` slots and retain the component's protected semantics                                                                                                                                                                                                     |
+| Concatenate a section count into a ListHeader label or numeric badge                                                              | Pass `count={value}` and a localized full phrase such as `countLabel="3 notes"`; reserve `badge` for non-count SafeHtml                                                                                                                                                                                     |
+| Put a chevron on navigation that reveals nothing                                                                                  | Remove it, or model a real controlled `ListHeader` disclosure; omit `actionIcon` to use the production `DisclosureArrow`                                                                                                                                                                                    |
+| Test only a custom-element attribute                                                                                              | Assert live property, emitted event, focus, and rendered output                                                                                                                                                                                                                                             |
+| Import all Web Awesome components                                                                                                 | Import only `@kerfjs/ui/select/register` for `Select`, or individual Web Awesome modules for other controls; `webawesome.css` registers no JavaScript                                                                                                                                                       |
+| Write `wa-*` JSX without activating its types                                                                                     | Add `import type {} from '@kerfjs/ui/webawesome'`; registration and theme imports remain separate                                                                                                                                                                                                           |
+| Maintain a root list of component styles                                                                                          | Import each visual component from its JS subpath; its reachable CSS follows automatically                                                                                                                                                                                                                   |
+| Add demo-only markup for a production state                                                                                       | Add the state to the production component, then render that export in the catalog                                                                                                                                                                                                                           |
+| Choose a listed ecosystem component by default                                                                                    | Apply the component-selection guidance above; catalog coverage means supported and themed, not preferred                                                                                                                                                                                                    |
+| Add sidebar-specific wrapper padding                                                                                              | Use the unpadded `.kui-pane`; let `ListHeader`, `ListItem`, and `ContentItem` own their 8/1/8 geometry                                                                                                                                                                                                      |
+| Expect a bare toolbar control to receive group chrome automatically                                                               | Style and name the direct control itself, or use `ToolbarControlGroup` when controls need shared chrome                                                                                                                                                                                                     |
+| Reach for `wa-button` for a plain control inside a `ToolbarControlGroup`                                                          | Use a plain `<button>` (the group styles it fully); for a popup menu use `PopupMenu`, which renders its own trigger                                                                                                                                                                                         |
+| Render a `Discouraged` Web Awesome element (`wa-dropdown`, `wa-button-group`, `wa-select`, `wa-tab-group`, `wa-icon`, …) directly | Use the Kerf component that wraps or replaces it (`PopupMenu`, `SegmentedControl`, `Select`, `TabBar`, `LucideIcon`); file a component gap rather than dropping to the raw element. `KUI-L301` (`ui-preferences`, also run by `kerf-ui-doctor`) reports the raw tag and names the replacement               |
+| Let a toolbar group wrap, or stack an icon above its label                                                                        | Keep icon and label on one row and let the group size to its content; relocate whole groups with the toolbar's `responsive` policy                                                                                                                                                                          |
+| Add CSS to show, hide, or reshape a Select or PopupMenu trigger's focus ring                                                      | Nothing: the ring follows the control's shape and drops while the popup is open; set `focusRingOwner="group"` when the group paints the composed ring                                                                                                                                                       |
+| Add a border or a permanent `dividerSides` under pinned chrome to separate it from scrolling content                              | Call `wireScrollDividers(appRoot)` once: a `Pane` draws the line only while content is scrolled beneath it, and never pad below a divider to adjust it                                                                                                                                                      |
+| Add a `title` or `wa-tooltip` to an icon-only `Select` or `PopupMenu` trigger                                                     | Nothing: the register import already shows an `aria-hidden` help tag with the accessible name on hover and keyboard focus                                                                                                                                                                                   |
+| Add a `title` or `wa-tooltip` to an icon-only toolbar `<button>`                                                                  | Name it with `aria-label` only; a registered Select/PopupMenu or `@kerfjs/ui/help-tags/register` shows the same help tag for it                                                                                                                                                                             |
+| Hand-write `wa-dropdown` / `wa-dropdown-item` markup for an action menu                                                           | Use `PopupMenu` with typed `items` in a `single` `ToolbarControlGroup` with `nestedDropdown`                                                                                                                                                                                                                |
+| Let the document, pane, and list all scroll                                                                                       | Keep fixed chrome outside one `.kui-pane__content` scroll owner per pane                                                                                                                                                                                                                                    |
+| Invent an `@kerfjs/ui` command-palette export                                                                                     | Keep the semantics application-local, reuse public layout vocabulary, and propose recurring behavior upstream                                                                                                                                                                                               |
+| Handwrite `ValueTable` row wrappers or compensate their padding or separators                                                     | Compose `ValueTableRow`; its root-scaled block padding, optional icon hook, and separator geometry are public contract                                                                                                                                                                                      |
+| Rebuild a panel/dialog heading with bespoke CSS or a private wrapper                                                              | Compose a plain `Toolbar` with a direct xl `ToolbarText`, optional grouped icon, grouped trailing controls, and short supporting copy as the `ToolbarText` `description` (quiet, one line, aligned under the title, with `descriptionId` for `aria-describedby`; longer copy stays app-owned content below) |
+| Put an xl `ToolbarText` in a narrow rail or drawer header                                                                         | Use the default size there as pane identity; xl truncates at the minimum size ("Ins…" in a 160px rail)                                                                                                                                                                                                      |
+| Force a `width`/`height`/`padding` on a component to size or space it                                                             | Let it size to its content and tokens; a forced box leaves a halo or a stretched oval — adjust an icon-size or spacing token, not the box                                                                                                                                                                   |
+| Wrap a component or region in a card, border, backdrop, or outline to "contain" it                                                | Let it sit on the surface; add a `ContentItem frame="framed"` only for a real distinction — hierarchy comes from alignment, spacing, and type first                                                                                                                                                         |
+| Override a component's `--kui-*` token to inset, size, or frame it                                                                | Use the typed prop: `FloatingToolbar inset`, `DisclosureArrow size`, `ListHeader headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"`                                                                                                                                                  |
+| Add another container's padding on top of a content-item's own margin                                                             | Pick one owner of the inset; a pane has no padding and its `.kui-content` children own the 8/1/8 geometry — stacking them double-insets                                                                                                                                                                     |
+| Put raw prose directly in a padded dialog body                                                                                    | Compose the body as `List`, set `bodyInset="none"` for list-owned geometry, and wrap bare prose in `ListInsetText`                                                                                                                                                                                          |
+| Keep chrome, a label, or a readout that aids no decision                                                                          | Delete it; every element must help a person decide or act                                                                                                                                                                                                                                                   |
+| Override a component's default size or color because it "looks off"                                                               | Trust the default (a LucideIcon is 24px) and fix the surrounding layout instead                                                                                                                                                                                                                             |
 
 For prominent content text, use `Text size="large"`; use `size="xlarge"` for display copy. Both sizes work with semantic `variant`, `tone`, and `font`, so keep heading levels based on the document outline.
 
+For an exclusive choice among several visible options that must wrap (a labeled color palette), use `ChoiceChips` from `@kerfjs/ui/choice-chips`: separate pills backed by native radios, so the group is one Tab stop, arrow keys select, and the checked radio submits under `name`. Name it with `label` or `labelledBy` (a visible `FieldLabel`), lead choices with `swatch` (a `CssColor`, or `'transparent'` for the struck-through no-color dot) or `icon`, and handle the delegated `action` on `change`. Never wrap a `SegmentedControl` or button-appearance `wa-radio` set instead.
+
 For removable tags use `Chip`, with `removeAction` for delegated handling and a specific `removeLabel` for the native button. `itemId` identifies the tag; the app owns removal. `size="compact"` and `disabled` replace app styling of raw `wa-tag` internals. Use `Badge` for non-interactive metadata.
 
 For an icon with a specific meaning, set `LucideIcon.color` using `uiColor('warning-on-quiet')` or another foreground token. Use `foregroundColorVar('--app-icon-color')` for an app-owned property or `foregroundColor('#8b5cf6')` for a direct custom CSS color. Omit the prop to inherit text color. Outline stroke and solid fill both follow the chosen color; size, appearance, label, and slot remain separate props. Avoid pale fill tokens as foregrounds.
@@ -404,7 +406,7 @@ Set `LucideIcon.inline` when an icon belongs within `Text` or another sentence;
 
 For `Select`, mark an unavailable choice with `disabled` and optionally `disabledReason`. In a multiple Select, `selectAllLabel` and `clearLabel` opt in to localized footer actions that select enabled choices or clear the selection through normal input/change events; the app still owns the controlled `value`.
 
-For nested action menus, use `PopupMenuItem.submenu` with item, heading, and divider entries; headings and dividers do not enter keyboard navigation. Items support `checked`, `icon`, `details`, `disabledReason`, and `tone`. The app owns choice state. For a right-click menu, use `PopupMenu` with `context: true` and call `openPopupMenuAt` from the app's `contextmenu` handler; the package positions and opens the menu. Call `closePopupMenu` for programmatic dismissal.
+For nested action menus, use `PopupMenuItem.submenu` with item, heading, and divider entries; headings and dividers do not enter keyboard navigation. Items support `checked`, `icon`, `details`, `disabledReason`, and `tone`. The app owns choice state. For a right-click menu, use `PopupMenu` with `context: true` and `anchor` (a signal holding the pointer's `{ x, y }` client coordinates); the `contextmenu` handler sets that signal and calls `openPopupMenu(menu)`. The menu owns its zero-footprint anchor host and keeps the point across re-renders, so never wrap it in a fixed/1px/z-index anchor element or re-apply the point after a render; `openPopupMenuAt(menu, x, y)` is only for a menu rendered without `anchor`. Call `closePopupMenu` for programmatic dismissal. `openPopupMenuAt` also opens a button-triggered `PopupMenu` (one without `context`) at the pointer for one opening; it returns to its trigger once closed, so a row's visible overflow menu doubles as its context menu. For a row's trailing "…" overflow menu, pass `ListActionRow` a `trailingMenu: { label, icon, items, placement?, disabled? }` instead of the `trailingAction*` props; never compose a `PopupMenu` next to or inside a `ListItem`.
 
 ## Select lifecycle ownership
 
@@ -427,7 +429,7 @@ For a tab scene with drill-down, place a `NavStack` directly in `TabNavigatorTab
 Use `Pane.deepInset` (also in `PaneConfig`) or `TabNavigatorTab.deepInset` for a plain scene when its scrolling content needs an extra 8px on all four sides, giving ordinary items a 16px inline gutter. The extra 8px is applied to the scroll surface, while nested Row/List/Grid item margins stay 8px. When a tab scene is a sole Pane or NavStack, configure deep inset on that child's Pane; the tab bar and top toolbar stay full width.
 An edge-to-edge table or similar Pane child can read `--kui-pane-content-inset-inline-start` and `--kui-pane-content-inset-inline-end`: negate them for the child's logical margins, then add them to the child's text padding. The inherited values include routed safe areas and `deepInset`; keep the child in the Pane's single scroll slot. See `docs/app-layouts.md` for the CSS recipe.
 
-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.
+Do not grow a collapsible search past the room beside its sibling groups: when it does not fit, the siblings wrap onto a new row while it opens. Size the expanded search to fit (`--kui-token-search-expanded-width`, or `sizing="grow"` with a fitting `growBasis`), and if a useful search still cannot fit, set aside the other controls while it is open, with `visibility="yield-to-expanded-sibling"` on those groups (they leave a 480px-or-narrower toolbar while a sibling is expanded) or behind a "…" `PopupMenu` overflow group; the app chooses which controls yield. 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.
 
 `ToolbarText` and `ToolbarControlGroup` accept typed `hideBelow`/`showBelow`
 lengths (for example `px(416)`). Wire `wireToolbarVisibility(root)` from
@@ -442,8 +444,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.
 
-Modal `DialogSurface` accepts a typed `preferredWidth` (`CssLength`) that overrides `size` while retaining the viewport width cap. Typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`) bound the modal; explicit height caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Side-sheet/fullscreen geometry, application responsive choices, and preview layout remain separately owned.
+Give sibling `DialogSurface`s that render conditionally a stable `rootAttributes={{ "data-key": "…" }}` so a re-render morphs each dialog into itself (structurally identical roots otherwise match by position and swap names and open state); never wrap one in a keyed app `div`. Modal `DialogSurface` accepts a typed `preferredWidth` (`CssLength`) that overrides `size` while retaining the viewport width cap. Typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`) bound the modal; explicit height caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Side-sheet/fullscreen geometry, application responsive choices, and preview layout remain separately owned. `height` (`CssLength` or `"viewport"`) gives the modal a definite bounded size, and `bodyLayout="fill"` hands the whole body to one child (a `SplitView` or `Pane`) that owns its scrolling. For a non-modal, light-dismiss dialog use `PopoverDialogSurface` from the same subpath (native `popover="auto"`, `role="dialog"`, Kerf chrome, the same size/gutter/height/fill props, and `presentation="embedded"` for an in-flow catalog or inline preview) instead of a hand-built popover with app CSS.
 
-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. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
+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.
 
 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.

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.95` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.97` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/dist/anchored-surface.d.ts

@@ -1,15 +1,26 @@
 import { PopoverOptions, OverlayContent, OverlayHandle } from 'kerfjs/overlay';
 
 /** App-facing options for a non-modal, arbitrary-content help surface. */
-interface AnchoredSurfaceOptions extends Pick<PopoverOptions, 'placement' | 'align' | 'gap' | 'dismiss' | 'initialFocus' | 'onDismiss' | 'outsideIgnore'> {
+interface AnchoredSurfaceOptions extends Pick<PopoverOptions, 'placement' | 'align' | 'gap' | 'dismiss' | 'initialFocus' | 'onDismiss' | 'outsideIgnore' | 'container'> {
     /** Accessible name for the non-modal dialog. */
     label: string;
+    /**
+     * Where to append the surface. Default: inside the anchor's open modal
+     * dialog — a native `<dialog>`'s host slot, or a slot kerf creates in a
+     * `wa-dialog` / `wa-drawer` — so the surface stays interactive there;
+     * otherwise `document.body`. Pass an element only for a modal context kerf
+     * cannot resolve; an element inside an open modal closes the surface with it.
+     */
+    container?: Element;
 }
 /** A viewport pointer location; `context` is the element under the pointer. */
 interface AnchoredSurfacePoint {
     x: number;
     y: number;
-    /** Pass the event target when opening from inside a modal dialog. */
+    /**
+     * Pass the event target when opening from inside a modal dialog, native or
+     * Web Awesome (`wa-dialog`, `wa-drawer`).
+     */
     context?: Element;
 }
 /**

package/dist/anchored-surface.js

@@ -1,3 +1,3 @@
-export { openAnchoredSurface, openAnchoredSurfaceAt } from './chunk-IOS2NXW7.js';
+export { openAnchoredSurface, openAnchoredSurfaceAt } from './chunk-76PWEN5Y.js';
 
 //# sourceMappingURL=anchored-surface.js.map

package/dist/app-tab.js

@@ -1,4 +1,4 @@
-export { AppTab } from './chunk-KAJVVN7Q.js';
+export { AppTab } from './chunk-6NOLL5KG.js';
 
 
 

package/dist/badge.d.ts

@@ -1,4 +1,5 @@
 import { SafeHtml } from 'kerfjs';
+import { CssLength } from './css-values.js';
 import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
 /** @deprecated Use SemanticTone. */
@@ -7,8 +8,22 @@ type BadgeAppearance = 'quiet' | 'solid' | 'outline';
 type BadgeShape = 'pill' | 'rounded';
 /** Size of a text badge. A text-free dot is the separate `size: 'dot'` form. */
 type BadgeSize = 'compact' | 'default';
+/** Application `data-*` identity on the badge root; Badge-owned markers stay protected. */
+type BadgeRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-tone'?: never;
+    'data-appearance'?: never;
+    'data-shape'?: never;
+    'data-size'?: never;
+    'data-has-icon'?: never;
+    'data-truncate'?: never;
+}>;
 interface BadgeCommonProps {
     tone?: SemanticTone;
+    /** Native tooltip text that explains the badge on hover. */
+    title?: string;
+    /** Safe `data-*` identity, such as a status band, on the badge root. */
+    rootAttributes?: BadgeRootAttributes;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -16,10 +31,23 @@ interface BadgeCommonProps {
 /** A badge that shows a short status, count, or category as visible text. */
 interface BadgeTextProps extends BadgeCommonProps {
     children: SafeHtml | string | number;
+    /** Decorative leading icon, normally an unsized LucideIcon, 4px before the text. */
+    icon?: SafeHtml;
     appearance?: BadgeAppearance;
     shape?: BadgeShape;
     size?: BadgeSize;
-    /** Optional accessible name when the visible content is abbreviated. */
+    /**
+     * Cap the badge's width and truncate longer text with an ellipsis, for
+     * app-supplied text such as a tag or category name. String and number
+     * content becomes the native `title` tooltip unless `title` is supplied, so
+     * the full text stays available on hover; SafeHtml content needs `title`.
+     */
+    maxWidth?: CssLength;
+    /**
+     * Accessible name that replaces the visible content when it is abbreviated
+     * or symbolic (`"82% confidence"` for `82`); the badge is then exposed as a
+     * labeled image.
+     */
     label?: string;
     /** Hide a repeated visual badge from assistive technology. */
     ariaHidden?: boolean;
@@ -46,9 +74,10 @@ type BadgeDotProps = BadgeCommonProps & {
     children?: never;
     appearance?: never;
     shape?: never;
+    maxWidth?: never;
 } & (BadgeDotLabeled | BadgeDotDecorative);
 type BadgeProps = BadgeTextProps | BadgeDotProps;
 /** Compact, non-interactive metadata whose tone, emphasis, and shape are configured by props. */
 declare function Badge(props: BadgeProps): SafeHtml;
 
-export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTextProps, type BadgeTone, SemanticTone };
+export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type BadgeRootAttributes, type BadgeShape, type BadgeSize, type BadgeTextProps, type BadgeTone, SemanticTone };

package/dist/badge.js

@@ -1,3 +1,4 @@
-export { Badge } from './chunk-J3AWE5I4.js';
+export { Badge } from './chunk-U6QYTMDB.js';
+
 
 //# sourceMappingURL=badge.js.map

package/dist/browser/choice-chips.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/choice-chips.css';
+export * from '../choice-chips.js';

package/dist/browser/column-track.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/column-track.css';
+export * from '../column-track.js';

package/dist/browser/combobox.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/combobox.css';
+export * from '../combobox.js';

package/dist/browser/content-swap.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/content-swap.css';
+export * from '../content-swap.js';

package/dist/browser/corner-status.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/corner-status.css';
+export * from '../corner-status.js';

package/dist/browser/edge-activity-indicator.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/edge-activity-indicator.css';
+export * from '../edge-activity-indicator.js';

package/dist/browser/file-picker.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/file-picker.css';
+export * from '../file-picker.js';

package/dist/browser/framed-list.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/framed-list.css';
+export * from '../framed-list.js';

package/dist/browser/icon-button.js

@@ -0,0 +1,4 @@
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/icon-button.css';
+export * from '../icon-button.js';

package/dist/browser/icon-toggle-button.js

@@ -0,0 +1,4 @@
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/icon-toggle-button.css';
+export * from '../icon-toggle-button.js';

package/dist/browser/list-action-row.js

@@ -1,4 +1,5 @@
 import '../styles/foundation.css';
+import '../styles/popup-menu.css';
 import '../styles/loading-spinner.css';
 import '../styles/skeleton.css';
 import '../styles/list-action-row.css';

package/dist/browser/split-button.js

@@ -0,0 +1,5 @@
+import '../styles/foundation.css';
+import '../styles/loading-spinner.css';
+import '../styles/lucide-icon.css';
+import '../styles/split-button.css';
+export * from '../split-button.js';

package/dist/browser/summary-row.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/summary-row.css';
+export * from '../summary-row.js';

package/dist/catalog-resources.d.ts

@@ -7,6 +7,7 @@ import './pane.js';
 import './workbench.js';
 import './nav-stack-BvSKY448.js';
 import './list.js';
+import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
 import './panel-toolbar-CL9tYOkh.js';

package/dist/catalog.d.ts

@@ -9,6 +9,7 @@ import './pane.js';
 import './workbench.js';
 import './nav-stack-BvSKY448.js';
 import './list.js';
+import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
 import './panel-toolbar-CL9tYOkh.js';