@kerfjs/ui 5.0.0-beta.62 → 5.0.0-beta.64

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.62` and `kerfjs@5.0.0-beta.62`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.64` and `kerfjs@5.0.0-beta.64`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -146,11 +146,14 @@ import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
 
+type ToolbarPosition = 'header' | 'footer';
 interface ToolbarProps {
     leading?: KerfUiContent;
     center?: KerfUiContent;
     trailing?: KerfUiContent;
     label?: string;
+    /** Use footer semantics for a bottom toolbar; defaults to header. */
+    position?: ToolbarPosition;
     /**
      * Physical divider edges in canonical top/right/bottom/left order, drawn
      * always. Defaults to none: a toolbar pinned over or under scrolling content
@@ -200,9 +203,9 @@ interface ToolbarProps {
  * toolbar) forwards, so the app configures that toolbar instead of styling it.
  */
 type ToolbarConfig = Pick<ToolbarProps, 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
-declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, position, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { Sides, Toolbar, type ToolbarConfig, type ToolbarProps };
+export { Sides, Toolbar, type ToolbarConfig, type ToolbarPosition, type ToolbarProps };
 ```
 
 ## `@kerfjs/ui/toolbar-text`
@@ -321,6 +324,10 @@ interface ToolbarControlGroupProps {
     relocateOnCollapse?: boolean;
     /** Add contrast behind photo-backed avatar content. */
     scrim?: boolean;
+    /** Block the group's controls and show a spinner without changing its dimensions. */
+    busy?: boolean;
+    /** Announced status while busy; defaults to “Working”. */
+    busyLabel?: string;
     /**
      * Avatar image URL. A single-control group paints it on the group; a
      * multi-control group paints it only on the pressed selection highlight.
@@ -329,7 +336,7 @@ interface ToolbarControlGroupProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, busy, busyLabel, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
 
 export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };
 ```
@@ -413,9 +420,9 @@ interface PopupMenuItem {
     value?: string;
     /** Leading icon, typically a `LucideIcon`; it is placed in the item's icon slot. */
     icon?: SafeHtml;
-    /** A checked menu choice, including nested choices. */
+    /** A checkbox choice, including nested choices; omit for a plain command. */
     checked?: boolean;
-    /** Trailing safe content, such as a selected-choice tick. */
+    /** Trailing safe content, such as secondary status. */
     details?: SafeHtml;
     /** Destructive command styling. */
     tone?: 'default' | 'danger';
@@ -487,7 +494,8 @@ declare function closePopupMenu(menu: PopupMenuElement): void;
  * `nestedDropdown`) or a `PopupSurface` sizes and insets it as usual. Items
  * dispatch through delegated `data-action`s; the app owns the commands and any
  * open-state reaction. Import `@kerfjs/ui/popup-menu/register` once to register
- * the Web Awesome elements.
+ * the Web Awesome elements. At viewport widths up to 480px, submenus appear
+ * above or below their parent menu so their rows do not cover the parent list.
  */
 declare function PopupMenu({ text, label, icon, items, placement, caret, disabled, rootAttributes, slot, context, }: PopupMenuProps): SafeHtml;
 
@@ -870,10 +878,22 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 type ContentItemFrame = 'none' | 'framed';
 /** Corner shape: the 12px rounded rectangle or the 22px pill. */
 type ContentItemShape = 'rounded' | 'pill';
+/** `single` uses option selection; `toggle` uses a pressed button. */
+type ContentItemSelectionMode = 'none' | 'single' | 'toggle';
 type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
 }>;
-interface ContentItemProps {
+type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-action'?: never;
+    'data-item-id'?: never;
+    'data-interactive'?: never;
+    'data-selected'?: never;
+    'data-disabled'?: never;
+    'data-selection-mode'?: never;
+    'data-kui-pressed'?: never;
+}>;
+interface ContentItemBaseProps {
     /** Item content; a plain string is allowed for bare copy. */
     children?: KerfUiContent | string;
     /**
@@ -882,8 +902,12 @@ interface ContentItemProps {
      * marks a real distinction. Defaults to `none` (transparent border).
      */
     frame?: ContentItemFrame;
+    /** Remove block padding and block borders while retaining inline geometry. */
+    flush?: boolean;
     /** Corner shape. Defaults to `rounded`. */
     shape?: ContentItemShape;
+    /** Native hover tooltip. */
+    title?: string;
     /**
      * Names the item as a distinct region (`role="region"`). Omit it for an
      * ordinary item, which stays a non-landmark grouping.
@@ -896,19 +920,38 @@ interface ContentItemProps {
      */
     focusTarget?: boolean;
     className?: string;
-    /** Safe `data-*` metadata; component-owned structural attributes stay protected. */
-    rootAttributes?: ContentItemRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+type ContentItemProps = ContentItemBaseProps & ({
+    interactive?: false;
+    action?: never;
+    itemId?: never;
+    selectionMode?: never;
+    selected?: never;
+    disabled?: never;
+    /** Existing static `data-*` metadata remains available. */
+    rootAttributes?: ContentItemRootAttributes;
+} | {
+    /** Enable a keyboard reachable card; wire `wireContentItems` once on its containing root. */
+    interactive: true;
+    /** Delegated action dispatched by pointer, Enter, or Space. */
+    action: string;
+    itemId?: string;
+    selectionMode?: ContentItemSelectionMode;
+    selected?: boolean;
+    disabled?: boolean;
+    /** Safe app metadata; interaction attributes are component-owned. */
+    rootAttributes?: ContentItemInteractiveRootAttributes;
+});
 /**
  * One self-contained `.kui-content` child: an 8px inline margin, a real 1px
  * border (transparent unless `framed`), 8px padding, and a rounded or pill
  * radius. It owns that whole geometry, so wrappers must not add more.
  */
-declare function ContentItem({ children, frame, shape, ariaLabel, focusTarget, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
+declare function ContentItem({ children, frame, flush, shape, title, ariaLabel, focusTarget, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
 
-export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemShape };
+export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -1428,7 +1471,8 @@ interface PaneProps {
     chromePlacement?: PaneChromePlacement;
     /**
      * The divider under the header and over the footer, where they meet the
-     * scrolling content. `scroll` (default) shows the header's divider only
+     * scrolling content. Omitted defaults to `scroll` for a plain pane and
+     * `always` for `appearance="sunken"`. `scroll` shows the header's divider only
      * while the content is scrolled down, and the footer's only while more
      * content lies below — never when the content fits — once
      * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
@@ -1492,7 +1536,7 @@ import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { a as PanelToolbar, b as PanelToggle } from './panel-toolbar-DqwtBxQL.js';
+import { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
 import { ToolbarConfig } from './toolbar.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -1511,6 +1555,7 @@ type WorkbenchPanelToggle = PanelToggle;
  * `FloatingToolbar` in the work area's bottom-end corner.
  */
 type WorkbenchPanelToolbar = PanelToolbar;
+type WorkbenchPanelBottomToolbar = PanelBottomToolbar;
 /**
  * The work area's top toolbar; collapsed rails add their groups to it. Its
  * configuration forwards to its `Toolbar`. It draws no divider of its own by
@@ -1546,7 +1591,7 @@ interface WorkbenchMainBottomToolbar extends ToolbarConfig {
  * the Pane's `chromePlacement="auto"`; it applies to the pinned header and
  * footer together).
  */
-type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
+type WorkbenchChromePlacement = PanelChromePlacement;
 
 /**
  * The Workbench container breakpoint below which a panel presents as an
@@ -1554,7 +1599,7 @@ type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
  * breakpoints as `ResizableRegion`'s `responsiveFillAt` — or `never` to keep
  * it inline at every width.
  */
-type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never';
+type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never' | number;
 /**
  * How wide a rail's overlay is in a compact (448px or less) Workbench: `inset`
  * fills the Workbench less a dismiss margin on the side away from the rail's
@@ -1577,8 +1622,20 @@ interface WorkbenchPanel {
      * collapsed. With it, `content` renders in a `Pane` below the toolbar.
      */
     toolbar?: WorkbenchPanelToolbar;
-    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    /** Fixed content below a toolbar panel's top toolbar, above its scroll region. */
+    header?: KerfUiContent;
+    /** List layout for `header`; omitted fields keep List defaults. */
+    headerList?: ListConfig;
+    /** Placement of the top toolbar and header together; default `fixed`. */
+    headerPlacement?: WorkbenchChromePlacement;
+    /** Fixed content above a toolbar panel's bottom toolbar. */
     footer?: KerfUiContent;
+    /** List layout for `footer`; omitted fields keep List defaults. */
+    footerList?: ListConfig;
+    /** Fixed toolbar below `footer`, using footer semantics. */
+    bottomToolbar?: WorkbenchPanelBottomToolbar;
+    /** Placement of the footer and bottom toolbar together; default `fixed`. */
+    footerPlacement?: WorkbenchChromePlacement;
     /**
      * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
      * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
@@ -1610,8 +1667,9 @@ interface WorkbenchPanel {
     presentation?: ResizableRegionPresentation;
     /**
      * Present the panel as an overlay, without a separator, below a Workbench
-     * container breakpoint, and inline above it — the CSS decides, so the app
-     * needs no device-class check. A rail overlays from its side at full
+     * container breakpoint, and inline above it. `compact` and `narrow` use
+     * CSS container queries; a positive number is a pixel threshold measured
+     * by `wireWorkbench` and requires a `collapsed` signal. A rail overlays from its side at full
      * height, over the work area and an open drawer; the bottom drawer
      * overlays the bottom of the work-area column. Rails default to `narrow`
      * (pass `never` to keep one inline); the drawer defaults to inline.
@@ -1711,6 +1769,8 @@ interface WorkbenchProps {
      * shorter. Workbenches without a drawer ignore it.
      */
     mainMinHeight?: number;
+    /** Dim the work area below any open overlay and absorb outside presses; off by default. */
+    overlayBackdrop?: boolean;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -1728,9 +1788,9 @@ interface WorkbenchProps {
  * lives outside it and stays reachable). A panel may opt in to drag and keyboard resizing with
  * `resizable`, which `wireWorkbench` drives. See `docs/23-app-layouts.md` §3.3.
  */
-declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainPane, mainHeaderList, mainFooterList, mainMinSize, mainMinHeight, className, slot, }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainPane, mainHeaderList, mainFooterList, mainMinSize, mainMinHeight, overlayBackdrop, className, slot, }: WorkbenchProps): SafeHtml;
 
-export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
+export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelBottomToolbar, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
 ```
 
 ## `@kerfjs/ui/wire-workbench`
@@ -1770,6 +1830,13 @@ interface WireWorkbenchPanel {
      * keeps Tab inside it, and it closes on Escape or a press outside it.
      */
     collapsed?: Signal<boolean>;
+    /**
+     * Treat presses in a portal surface launched by this panel (for example a
+     * body-level menu or dialog) as inside it. The predicate receives each Node
+     * in the press's composed path; return true for the portal root. Ordinary
+     * presses outside the panel and its allowed surfaces still dismiss it.
+     */
+    keepOpenOn?: (target: Node) => boolean;
 }
 /** A resize the user made, after `wireWorkbench` wrote it to the size signal. */
 interface WorkbenchResize {
@@ -1851,16 +1918,18 @@ export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanel
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
-import { P as PanelSide, a as PanelToolbar, b as PanelToggle } from './panel-toolbar-DqwtBxQL.js';
-export { c as collapsiblePanelToggleIcon } from './panel-toolbar-DqwtBxQL.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
+export { e as collapsiblePanelToggleIcon } from './panel-toolbar-DDKh4uKd.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './sides-BPSWde0A.js';
 import './lucide-icon.js';
 import 'lucide';
 import './toolbar.js';
-import './sides-BPSWde0A.js';
-import './css-values.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
 type CollapsiblePanelSide = PanelSide;
@@ -1873,6 +1942,8 @@ type CollapsiblePanelToolbarToggle = PanelToggle;
  * {@link CollapsiblePanelRelocated} while it is collapsed.
  */
 type CollapsiblePanelToolbar = PanelToolbar;
+type CollapsiblePanelBottomToolbar = PanelBottomToolbar;
+type CollapsiblePanelChromePlacement = PanelChromePlacement;
 interface CollapsiblePanelToggleProps {
     /** The panel this toggle controls. */
     side: CollapsiblePanelSide;
@@ -1916,8 +1987,15 @@ interface CollapsiblePanelProps {
      * marked groups and toggle stay reachable while the panel is collapsed.
      */
     toolbar?: CollapsiblePanelToolbar;
-    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    /** Fixed content below a toolbar panel's top toolbar. */
+    header?: KerfUiContent;
+    headerList?: ListConfig;
+    headerPlacement?: CollapsiblePanelChromePlacement;
+    /** Fixed content above a toolbar panel's bottom toolbar. */
     footer?: KerfUiContent;
+    footerList?: ListConfig;
+    bottomToolbar?: CollapsiblePanelBottomToolbar;
+    footerPlacement?: CollapsiblePanelChromePlacement;
     /**
      * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
      * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
@@ -1951,7 +2029,7 @@ interface CollapsiblePanelProps {
  * and persistence semantics, and with `CollapsiblePanelToggle` for the standard
  * affordance. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.
  */
-declare function CollapsiblePanel({ id, side, collapsed, size, label, children, toolbar, footer, pane, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
+declare function CollapsiblePanel({ id, side, collapsed, size, label, children, toolbar, header, headerList, headerPlacement, footer, footerList, bottomToolbar, footerPlacement, pane, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
 interface CollapsiblePanelRelocatedProps {
     /** The panel's `id`. */
     panelId: string;
@@ -1971,7 +2049,7 @@ interface CollapsiblePanelRelocatedProps {
  */
 declare function CollapsiblePanelRelocated({ panelId, side, collapsed, toolbar, }: CollapsiblePanelRelocatedProps): SafeHtml;
 
-export { CollapsiblePanel, type CollapsiblePanelProps, CollapsiblePanelRelocated, type CollapsiblePanelRelocatedProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, type CollapsiblePanelToolbar, type CollapsiblePanelToolbarToggle };
+export { CollapsiblePanel, type CollapsiblePanelBottomToolbar, type CollapsiblePanelChromePlacement, type CollapsiblePanelProps, CollapsiblePanelRelocated, type CollapsiblePanelRelocatedProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, type CollapsiblePanelToolbar, type CollapsiblePanelToolbarToggle };
 ```
 
 ## `@kerfjs/ui/wire-sidebar`
@@ -2304,7 +2382,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-DqwtBxQL.js';
+import './panel-toolbar-DDKh4uKd.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2318,7 +2396,7 @@ import 'lucide';
 declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, sidebar, mainToolbar, footerToolbar, className, slot, }: CatalogProps): kerfjs.SafeHtml;
 
 /** How a specimen aligns its visible edge with its `ListHeader` label. */
-type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
+type CatalogExampleAlign = 'glyph' | 'inline-control' | 'text-trigger' | 'none';
 interface CatalogExampleViewport {
     layout?: 'grid' | 'flex' | 'flex-column';
     width?: 'full' | 'compact' | 'medium' | 'wide' | 'text' | 'control';
@@ -2397,7 +2475,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-DqwtBxQL.js';
+import './panel-toolbar-DDKh4uKd.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2799,6 +2877,7 @@ export { Skeleton, type SkeletonProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssFlexKeyword, CssFlex } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type SunkenPanelShape = 'rounded' | 'square';
@@ -2808,6 +2887,10 @@ interface SunkenPanelProps {
     ariaLabel?: string;
     /** Corner shape: a rounded rectangle (default) or square corners. */
     shape?: SunkenPanelShape;
+    /** Grow or shrink within a flex parent, using Grid's typed flex contract. */
+    flex?: boolean | CssFlexKeyword | CssFlex;
+    /** Fill a parent with a definite height; use flex inside a flex layout. */
+    fill?: boolean;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -2817,7 +2900,7 @@ interface SunkenPanelProps {
  * stack. The panel owns its background and padding; children own their own
  * borders and internal geometry.
  */
-declare function SunkenPanel({ children, ariaLabel, shape, className, slot, }: SunkenPanelProps): kerfjs.SafeHtml;
+declare function SunkenPanel({ children, ariaLabel, shape, flex, fill, className, slot, }: SunkenPanelProps): kerfjs.SafeHtml;
 
 export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ```
@@ -2827,14 +2910,14 @@ export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ```ts
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
-export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-DvgFLhLL.js';
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-Xk8jiw8Y.js';
 ```
 
 ## `@kerfjs/ui/wire-token-search-fields`
 
 ```ts
 import { Signal } from 'kerfjs';
-import { d as TokenSearchModel } from './token-search-field-DvgFLhLL.js';
+import { d as TokenSearchModel } from './token-search-field-Xk8jiw8Y.js';
 import './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchSubmit {
@@ -3091,8 +3174,8 @@ import { SafeHtml } from 'kerfjs';
 import { BadgeTone, BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
 
 interface ChipCommonProps {
-    /** Visible, non-interactive chip content. */
-    children: SafeHtml | string | number;
+    /** Decorative leading icon, normally an unsized LucideIcon. */
+    icon?: SafeHtml;
     tone?: BadgeTone;
     appearance?: BadgeAppearance;
     shape?: BadgeShape;
@@ -3106,6 +3189,12 @@ interface ChipCommonProps {
 }
 /** A removable chip needs both a delegated action and a specific accessible name. */
 type ChipProps = ChipCommonProps & ({
+    children: SafeHtml | string | number;
+    truncate?: false;
+} | {
+    children: string;
+    truncate: true;
+}) & ({
     removeAction: string;
     removeLabel: string;
 } | {
@@ -3113,7 +3202,7 @@ type ChipProps = ChipCommonProps & ({
     removeLabel?: never;
 });
 /** A short label with an optional native remove button. The application owns removal. */
-declare function Chip({ children, tone, appearance, shape, size, disabled, itemId, className, slot, ...remove }: ChipProps): SafeHtml;
+declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, ...remove }: ChipProps): SafeHtml;
 
 export { Chip, type ChipProps };
 ```
@@ -3125,18 +3214,21 @@ import * as kerfjs from 'kerfjs';
 import { IconNode } from 'lucide';
 
 type LucideNode = IconNode;
+type LucideIconSize = 'xs' | 's' | 'm' | 'l' | 'xl' | number;
 interface LucideIconProps {
     icon: LucideNode;
     name: string;
     className?: string;
     label?: string;
+    /** Named icon scale or positive pixel size, converted to rem. Omit for 1em. */
+    size?: LucideIconSize;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** Render a Lucide-compatible icon node without copying icon SVG strings. */
-declare function LucideIcon({ icon, name, className, label, slot, }: LucideIconProps): kerfjs.SafeHtml;
+declare function LucideIcon({ icon, name, className, label, size, slot, }: LucideIconProps): kerfjs.SafeHtml;
 
-export { LucideIcon, type LucideIconProps, type LucideNode };
+export { LucideIcon, type LucideIconProps, type LucideIconSize, type LucideNode };
 ```
 
 ## `@kerfjs/ui/surface-scaffold`
@@ -3187,8 +3279,9 @@ type TextSize = 'compact' | 'default' | 'large' | 'xlarge';
 type TextFont = 'default' | 'monospace';
 type TextBorder = 'transparent' | 'none';
 type TextLineHeight = 'default' | 'tight';
+type TextWrap = 'normal' | 'anywhere' | 'nowrap' | 'truncate';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
-type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
+type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
     variant?: TextVariant;
     /** Semantic foreground treatment. Defaults to the inherited foreground. */
@@ -3207,14 +3300,24 @@ type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     class?: string;
     className?: string;
 };
+type TextProps = TextCommonProps & ({
+    /** Wrap normally or break long unbroken strings. Defaults to normal. */
+    wrap?: 'normal' | 'anywhere';
+    /** Cap wrapped text to this positive number of lines. */
+    maxLines?: number;
+} | {
+    /** Keep one line, with or without an ellipsis. */
+    wrap: 'nowrap' | 'truncate';
+    maxLines?: never;
+});
 /**
  * Semantic heading, paragraph, or inline text. Block variants use the standard
  * content-item padding; `span` adds no box geometry.
  * All ordinary native heading/paragraph attributes pass through to the element.
  */
-declare function Text({ variant: Variant, tone, size, font, border, flush, lineHeight, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
+declare function Text({ variant: Variant, tone, size, font, border, flush, lineHeight, wrap, maxLines, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
 
-export { Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant };
+export { Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant, type TextWrap };
 ```
 
 ## `@kerfjs/ui/row`
@@ -3281,6 +3384,7 @@ type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-component'?: never;
     'data-columns'?: never;
     'data-min-column-width'?: never;
+    'data-auto-fill'?: never;
     'data-flex'?: never;
     'data-fill'?: never;
 }>;
@@ -3306,13 +3410,16 @@ type GridProps = GridCommonProps & ({
     /** Number of equal-width columns. Must be a positive safe integer. */
     columns: number;
     minColumnWidth?: never;
+    autoFill?: never;
 } | {
     columns?: never;
     /** Fit equal columns of at least this width; collapse as the container narrows. */
     minColumnWidth: CssLength;
+    /** Keep empty tracks instead of stretching a sparse row. Defaults to false. */
+    autoFill?: boolean;
 });
 /** Render equal tracks with a fixed count or a responsive minimum width. */
-declare function Grid({ children, columns, minColumnWidth, gap, flex, fill, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
+declare function Grid({ children, columns, minColumnWidth, autoFill, gap, flex, fill, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, UiSpaceName };
 ```
@@ -3344,6 +3451,6 @@ export { CssLength, Spacer, type SpacerProps, UiSpaceName };
 
 ```ts
 import 'kerfjs';
-export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, k as createTokenSearchModel } from './token-search-field-DvgFLhLL.js';
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, l as createTokenSearchModel } from './token-search-field-Xk8jiw8Y.js';
 import './semantic-content-BbzjvSu9.js';
 ```

package/ai/skill.md

@@ -70,8 +70,12 @@ Before choosing or aligning components, look for a consumer-owned catalog that
 conforms to `./component-catalog-extension.schema.json`. Treat its entries as a
 second, package-qualified input beside `./component-catalog.json`: search both,
 preserve their source identity, and use the shared `geometry` vocabulary across
-their composition boundary. When a consuming project has reusable visual
-components, prefer its generated `component-composition.json`. A package
+their composition boundary. An extension entry's optional `uses` ids resolve
+against both catalogs; its `source` and `demoSource` are repository-relative
+files for consumer catalog links. When a consuming project has reusable visual
+components, derive demo rows with `@kerfjs/ui/catalog-projection` or
+`kerf-catalog-demo --write`, then guard drift with `--check`; see
+`../docs/catalog.md`. Prefer its generated `component-composition.json`. A package
 scaffolded by `create-kerf-component` owns the decisions in
 `kerf.components.json`; run `npm run catalog:check` before using its output. If
 no generated extension exists, start from the checked examples and require the
@@ -195,7 +199,7 @@ Hard rules:
 4. Wire `data-action` hooks from one stable root with `delegate()` or `delegateActions()` and retain disposers.
 5. Configure components through their typed props; components own their own styles (see "Components own their styles; configure, never override" above). Use the opinionated `--kui-color-*` semantic ramps for theming, not to reshape a component. Use `pop` only for attractive non-status emphasis such as featured, novel, or celebratory content; never substitute it for info, success, warning, or danger. Set a theme token only at the narrowest useful scope, and never where an equivalent prop exists. `publicClasses` exist for diagnostics, tooling, tests, and package-owned composition, not application styling. Never target a Kerf or Web Awesome component from application CSS; add missing configuration to the owner.
 6. `Select` is pure until the app explicitly imports `@kerfjs/ui/select/register`; once registered, an icon-only `Select` (and, via `@kerfjs/ui/popup-menu/register`, an icon-only `PopupMenu`) shows an `aria-hidden` help tag repeating its accessible name (and a Select's current choice) on hover and keyboard focus, hidden while its popup is open — never add a `title` or your own tooltip to these triggers. The same installer tags an icon-only `<button>` or link in a `ToolbarControlGroup` named by `aria-label` (no visible text, no `title`); a toolbar with such buttons but no registered Select or PopupMenu imports `@kerfjs/ui/help-tags/register` once. Name those buttons with `aria-label`, not `title`: a `title` keeps the browser tooltip and skips the tag. Do not import Web Awesome's full registration bundle. When an app writes direct `wa-*` JSX, add `import type {} from '@kerfjs/ui/webawesome'` for the catalog-supported intrinsic-element declarations, import the CSS-only `@kerfjs/ui/webawesome.css` theme once, and keep importing individual Web Awesome component modules so their JavaScript remains tree-shakeable. The type boundary emits no code and registers nothing. Pass icon-bearing `choices` and `renderSelected` content normally: `Select` preserves its slotted option icons across Kerf rerenders and keys selected content by the controlled value, so app wrappers must not add competing morph-control attributes. Give it a visible `label` or an `ariaLabel` for a visually hidden name; the nonempty visible label takes precedence and the package names the actual shadow combobox, including `renderSelected`, without adding label geometry. Use `hint` for persistent supporting text below the control and `placeholderText` only for the empty value inside the closed control; loading placeholders retain the hint. For any number of choices set `multiple` with an array `value`: the popup stays open while choices toggle and closes on an outside press or Escape, the closed control summarizes the chosen labels, and `change` reports the value array; do not add app code to keep it open or to render tags. For a toolbar filter menu, add `selectedPresentation="icon-only"` plus a fixed `triggerIcon` (such as a funnel `LucideIcon`): the trigger shows that icon, a count badge while any choice is chosen, and ends its accessible name with the chosen labels ("Filter by label: Bug, Docs"); do not render your own count badge or rewrite the name. When testing name or description, target the element with the `combobox` role rather than the `wa-select` wrapper. Web Awesome's hint attribute and explicit hint slot both describe that shadow combobox across supported engines; do not add an `aria-description` mirror or application shadow-DOM patch.
-7. Decorative icons are hidden; controls are named; focus is visible; state never relies on color alone; reduced motion and increased contrast remain usable. `DisclosureArrow` defaults to an 18px root-scaled visual; size it with its typed `size` prop (`size={remify(24)}`); it never becomes the interaction or accessible-name owner. Put it in an owning native control with a stable accessible name and controlled `aria-expanded`. `ListHeader` toggle mode supplies it when `actionIcon` is omitted, but the app must reveal matching content; a custom icon replaces it. Author replacement icon content facing right before its configured direction transform is applied. Direction changes take the shortest rotation path, with counterclockwise chosen for a 180-degree closed-to-open tie. Kerf `Select` separately keeps its intrinsic Web Awesome expand glyph at `--kui-disclosure-icon-scale: .5`; an icon-only toolbar Select may set `caret={false}` for a round trigger while preserving its help tag and keyboard listbox.
+7. Decorative icons are hidden; controls are named; focus is visible; state never relies on color alone; reduced motion and increased contrast remain usable. `DisclosureArrow` defaults to an 18px root-scaled visual; size it with its typed `size` prop (`size={remify(24)}`); it never becomes the interaction or accessible-name owner. Put it in an owning native control with a stable accessible name and controlled `aria-expanded`. `ListHeader` toggle mode supplies it when `actionIcon` is omitted, but the app must reveal matching content; a custom icon replaces it. Author replacement icon content facing right before its configured direction transform is applied. Direction changes take the shortest rotation path, with counterclockwise chosen for a 180-degree closed-to-open tie. Kerf `Select` separately keeps its intrinsic Web Awesome expand glyph at `--kui-disclosure-icon-scale: .5`; an icon-only toolbar Select may set `caret={false}` for a round trigger while preserving its help tag and keyboard listbox, and a custom `renderSelected` icon stays centered.
 8. `ResizableRegion` uses `wireResizableRegions()` for Arrow, Shift+Arrow, Home/End, and pointer behavior. The app owns size persistence. `handleIcon` replaces decorative dormant glyph content only. Set `responsiveFillAt="narrow"` or `"compact"` when a responsive composition exposes the pane as its only inline track; the component fills that track and hides its dormant separator. For compact overlays, set `presentation="overlay"` and the overlay maximum variables. A lone child (normally a `Pane`) fills the region and owns scrolling; several children stack at natural height. Do not add descendant width/height overrides.
 9. Use controlled `SegmentedControl` for a small exclusive choice set. Select `appearance="toolbar"` when nesting it inside `ToolbarControlGroup`; use rounded or pill shapes for standalone contexts. The package derives inset hover/selection radii from the owning outer shape through `--kui-layout-highlight-inset`; do not restyle an inner highlight to an independent radius. Handle its action, update `value`, keep meaningful choice labels, and preserve every enabled native button in sequential Tab order.
 10. Compose `AppTab` inside controlled `TabBar`; call `wireTabBars()` once and retain its disposer. It owns same-bar drag mechanics, including proximity-based horizontal edge autoscroll, while the app applies `onReorder` and owns order, selection, panels, close policy, routing, and persistence. For a tab-local action followed by a separately pinned workspace action, set `trailingPlacement="adjacent"`, put the local action in `trailing`, and the workspace action in `end`; TabBar owns the shrinking/scrolling tabs and fixed action geometry, so do not add descendant flex overrides. Arrow/Home/End select on move by default and restore focus by bar/tab identity when controlled activation replaces the strip; pass `activation: 'manual'` (or `TabBar activation="manual"` per strip) so arrow keys move focus only and the user selects with Enter/Space/click — use it when selecting a tab is a heavy action. Use runtime-filtered `rootAttributes` for domain metadata and keep an optional `closeIcon` decorative and noninteractive.
@@ -207,7 +211,7 @@ Hard rules:
 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.
     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 with no tone option; a normal-color subsection title is `Text` with an `h2`–`h6` variant (or `ListHeader` for a list or menu section), never a recolored `ToolbarText`.
 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 scroll state, not decoration: 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; every `Pane` then 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 `TabScaffold` 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` default, `always`, `none`, also via `PaneConfig`), and a `NavStack` or `TabScaffold` with 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.
+    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 `TabScaffold` 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 `TabScaffold` 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. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. Put identity/title text directly in the zone as `ToolbarText`; wrap interactive controls and icon tiles in `ToolbarControlGroup`. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a group. 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. Nothing wraps inside a group: an icon sits beside its label on one row and a group's controls never break onto a second line — the group sizes to its content, so if it does not fit, the toolbar's `responsive` policy relocates whole groups. 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 mutually exclusive semantic count or non-count `badge` 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 every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `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.
 
@@ -230,7 +234,7 @@ Use `--kui-resizable-region-background` for a region surface and `contentOverflo
 
 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.
 
-For a filled command list, scope `--kui-list-item-background`, `--kui-list-item-border`, `--kui-list-item-hover-border`, and `--kui-list-item-selected-border` at the List or ListItem boundary. Keep global neutral and brand border colors semantic.
+For a filled command list, scope `--kui-list-item-background`, `--kui-list-item-color`, `--kui-list-item-border`, `--kui-list-item-hover-background`, `--kui-list-item-hover-border`, `--kui-list-item-selected-background`, `--kui-list-item-selected-color`, and `--kui-list-item-selected-border` at the List or ListItem boundary. Keep global neutral and brand border colors semantic.
 
 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.
 

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.62` 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.64` 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';