@kerfjs/ui 5.0.0-beta.94 → 5.0.0-beta.96

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.94` and `kerfjs@5.0.0-beta.94`. 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.96` and `kerfjs@5.0.0-beta.96`. 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`
 
@@ -159,6 +159,8 @@ import { S as Sides } from './sides-BPSWde0A.js';
 import { PaneSeparatorSide } from './pane.js';
 
 type ToolbarPosition = 'header' | 'footer';
+/** Control-band density: `default` (60px with 44px groups) or `compact`. */
+type ToolbarDensity = 'default' | 'compact';
 interface ToolbarProps {
     leading?: KerfUiContent;
     center?: KerfUiContent;
@@ -166,6 +168,15 @@ interface ToolbarProps {
     label?: string;
     /** Use footer semantics for a bottom toolbar; defaults to header. */
     position?: ToolbarPosition;
+    /**
+     * `compact` sizes the toolbar to a 34px control band with 3px block
+     * insets — 40px tall — for a header embedded in a panel or card. Fill it
+     * with `ToolbarControlGroup size="compact"` groups; inline insets and the
+     * gap between zones are unchanged. Composites that render a Toolbar from a
+     * `ToolbarConfig` (Workbench, CollapsiblePanel, NavStack, SplitView) forward
+     * it and size the groups they compose to match. Defaults to `default`.
+     */
+    density?: ToolbarDensity;
     /**
      * Physical divider edges in canonical top/right/bottom/left order, drawn
      * always. Defaults to none: a toolbar pinned over or under scrolling content
@@ -214,10 +225,10 @@ interface ToolbarProps {
  * that renders a `Toolbar` for the app (a Workbench or CollapsiblePanel
  * 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, position, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
+type ToolbarConfig = Pick<ToolbarProps, 'density' | 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
+declare function Toolbar({ leading, center, trailing, label, position, density, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { Sides, Toolbar, type ToolbarConfig, type ToolbarPosition, type ToolbarProps };
+export { Sides, Toolbar, type ToolbarConfig, type ToolbarDensity, type ToolbarPosition, type ToolbarProps };
 ```
 
 ## `@kerfjs/ui/toolbar-text`
@@ -271,6 +282,17 @@ type ToolbarTextProps = ToolbarTextBaseProps & (({
     headingLevel?: HeadingLevel;
     /** Render an unanimated loading skeleton instead of the text. */
     placeholder?: boolean;
+    /**
+     * Quiet, single-line supporting copy under the title ("Changes save
+     * automatically."), truncating with an ellipsis. Title and description
+     * share the toolbar's control band and the same text start, with or
+     * without a leading icon group. With a description, `id` and
+     * `headingLevel` apply to the title alone, so a dialog's
+     * `aria-labelledby` names only the title.
+     */
+    description?: string;
+    /** Id for the description, for a dialog's `aria-describedby`. */
+    descriptionId?: string;
 } & ToolbarTextWrappingProps) | {
     /** Render a native button with this delegated action; the app owns editing. */
     action: string;
@@ -278,8 +300,10 @@ type ToolbarTextProps = ToolbarTextBaseProps & (({
     placeholder?: never;
     wrap?: never;
     maxLines?: never;
+    description?: never;
+    descriptionId?: never;
 });
-declare function ToolbarText({ text, size, tone, hideBelow, showBelow, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, action, }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, tone, hideBelow, showBelow, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, action, description, descriptionId, }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize, type ToolbarTextTone };
 ```
@@ -301,7 +325,7 @@ type ToolbarControlGroupSize = 'default' | 'compact';
 type ToolbarControlGroupDensity = 'comfortable' | 'tight';
 type ToolbarControlGroupContent = 'icon' | 'text' | 'mixed' | 'avatar' | 'search';
 type ToolbarControlGroupFocusRing = 'control' | 'outline' | 'halo';
-type ToolbarControlGroupSelectedChrome = 'raised' | 'filled' | 'outline';
+type ToolbarControlGroupSelectedChrome = 'raised' | 'filled' | 'outline' | 'none';
 type ToolbarControlGroupSelectedTone = 'brand' | 'neutral' | 'pop';
 type ToolbarControlGroupOverflow = 'visible' | 'scroll' | 'wrap';
 type ToolbarControlGroupExpandedOverflow = 'clip' | 'visible';
@@ -343,6 +367,13 @@ interface ToolbarControlGroupProps {
     content?: ToolbarControlGroupContent;
     /** Whether controls paint focus individually or the group paints an outline/halo on focus-within. */
     focusRing?: ToolbarControlGroupFocusRing;
+    /**
+     * Chrome a pressed (`aria-pressed="true"`) control paints. `none` keeps a
+     * pressed control looking like its neighbors, for an icon-state toggle whose
+     * glyph already shows the state (an empty or filled star); hover and the
+     * focus ring are unchanged. One control can opt out alone with
+     * `data-selected-chrome="none"` on its own button.
+     */
     selectedChrome?: ToolbarControlGroupSelectedChrome;
     selectedTone?: ToolbarControlGroupSelectedTone;
     /** Size a nested Web Awesome dropdown trigger as part of this group. */
@@ -501,11 +532,23 @@ type PopupMenuTriggerName = {
      */
     label: string;
 };
+/** A context PopupMenu's viewport anchor point. */
+interface PopupMenuAnchor {
+    x: number;
+    y: number;
+}
 type PopupMenuTrigger = (PopupMenuTriggerName & {
     context?: false;
+    anchor?: never;
 }) | {
     context: true;
     label: string;
+    /**
+     * The viewport point (CSS pixels, as in `MouseEvent.clientX/Y`) the
+     * menu opens from. Rendered into the menu itself, so it survives
+     * re-renders and replacement; open it with `openPopupMenu`.
+     */
+    anchor?: PopupMenuAnchor;
     text?: never;
     icon?: never;
     caret?: never;
@@ -529,8 +572,21 @@ type PopupMenuProps = PopupMenuTrigger & {
 type PopupMenuElement = HTMLElement & {
     open: boolean;
 };
-/** Open a context PopupMenu at viewport pointer coordinates. */
+/**
+ * Open a PopupMenu at viewport pointer coordinates. A `context` menu rendered
+ * without `anchor` moves its invisible anchor there (a menu rendered with
+ * `anchor` opens with `openPopupMenu` instead). A button-triggered menu (such as a `ListActionRow`
+ * trailing menu) anchors its popup at the point, opening `bottom-start` like a
+ * context menu, for this opening only; once the menu has closed it returns to
+ * its trigger and placement. Before Web Awesome upgrades it, the menu opens at
+ * its trigger.
+ */
 declare function openPopupMenuAt(menu: PopupMenuElement, x: number, y: number): void;
+/**
+ * Open a context PopupMenu at the `anchor` it was rendered with (or the
+ * point a previous `openPopupMenuAt` set).
+ */
+declare function openPopupMenu(menu: PopupMenuElement): void;
 /** Close a programmatically opened PopupMenu. */
 declare function closePopupMenu(menu: PopupMenuElement): void;
 /**
@@ -542,9 +598,9 @@ declare function closePopupMenu(menu: PopupMenuElement): void;
  * 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;
+declare function PopupMenu({ text, label, icon, items, placement, caret, disabled, rootAttributes, slot, context, anchor, }: PopupMenuProps): SafeHtml;
 
-export { PopupMenu, type PopupMenuDivider, type PopupMenuElement, type PopupMenuEntry, type PopupMenuHeading, type PopupMenuItem, type PopupMenuPlacement, type PopupMenuProps, closePopupMenu, openPopupMenuAt };
+export { PopupMenu, type PopupMenuAnchor, type PopupMenuDivider, type PopupMenuElement, type PopupMenuEntry, type PopupMenuHeading, type PopupMenuItem, type PopupMenuPlacement, type PopupMenuProps, closePopupMenu, openPopupMenu, openPopupMenuAt };
 ```
 
 ## `@kerfjs/ui/list-header`
@@ -655,13 +711,14 @@ export { ListHeader, type ListHeaderProps };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as StructuralRootAttributes } from './extension-attributes-mu8MFUl0.js';
 import { H as HorizontalAlignment, L as ListVerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 export { V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { S as Sides } from './sides-BPSWde0A.js';
 import { UiGap, CssFlexKeyword, CssFlex } from './css-values.js';
 export { CssLength, UiGapValue, UiSpaceName } from './css-values.js';
 
-type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListRootAttributes = StructuralRootAttributes & Readonly<{
     'data-component'?: never;
     'data-gap'?: never;
     'data-flex'?: never;
@@ -669,9 +726,23 @@ type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-h-align'?: never;
     'data-v-align'?: never;
     'data-scrollable'?: never;
+    'data-surface'?: never;
+    'data-inset'?: never;
     'data-text-insets'?: never;
     'data-control-insets'?: never;
 }>;
+/**
+ * A solid surface painted behind a List: `base` is the page surface
+ * (`--kui-color-surface`), `raised` the raised surface
+ * (`--kui-color-surface-raised`). A lowered region is a `SunkenPanel`.
+ */
+type ListSurface = 'base' | 'raised';
+/**
+ * A preset inset on all four sides. `document` is the reading inset for long
+ * content such as a reader view: 24px block and 32px inline, narrowing to
+ * 16px inline below 576px. It replaces any `textInsets`/`controlInsets`.
+ */
+type ListInset = 'document';
 interface ListProps {
     children?: KerfUiContent;
     /** Make this list a labeled multi-select grid for `ContentItem selectionMode="multiple"` rows. */
@@ -692,16 +763,33 @@ interface ListProps {
     hAlign?: HorizontalAlignment;
     /** Vertical distribution. Defaults to top. */
     vAlign?: ListVerticalAlignment;
-    /** Own vertical scrolling and overscroll containment. */
+    /**
+     * Own vertical scrolling and overscroll containment. Children keep their
+     * natural height and scroll instead of shrinking. To bound the list by a
+     * `max-height` ancestor (no definite height), give that ancestor a flex
+     * column and use `flex`; `fill` needs a definite-height parent.
+     */
     scrollable?: boolean;
+    /**
+     * Paint a solid surface behind the stack, including its insets: for a strip
+     * of chrome (a banner above a sunken work area) that must not show the
+     * lowered tint around its content. Omitted, the List is transparent.
+     */
+    surface?: ListSurface;
     /** Physical divider edges in canonical top/right/bottom/left order. */
     dividerSides?: Sides;
+    /** A preset four-sided inset; see `ListInset`. */
+    inset?: ListInset;
     /** Physical sides that receive the standard 17px text inset. */
     textInsets?: Sides;
     /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
     controlInsets?: Sides;
     className?: string;
-    /** Safe `data-*` metadata; List-owned structural attributes remain protected. */
+    /**
+     * Safe `data-*`, `aria-*`, and structural `role` metadata (a named drop
+     * `region`, `aria-busy`); List-owned structural attributes remain
+     * protected, and a multi-select List owns its grid role and name.
+     */
     rootAttributes?: ListRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -714,15 +802,17 @@ interface ListProps {
  */
 type ListConfig = Pick<ListProps, 'gap' | 'hAlign' | 'vAlign' | 'dividerSides' | 'textInsets' | 'controlInsets'>;
 /** A stretch-aligned vertical stack with optional gap, flex, fill, scroll, and dividers. */
-declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
+declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, surface, inset, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, HorizontalAlignment, List, type ListConfig, type ListProps, ListVerticalAlignment, Sides, UiGap };
+export { CssFlex, CssFlexKeyword, HorizontalAlignment, List, type ListConfig, type ListInset, type ListProps, type ListSurface, ListVerticalAlignment, Sides, UiGap };
 ```
 
 ## `@kerfjs/ui/list-action-row`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { PopupMenuEntry, PopupMenuPlacement } from './popup-menu.js';
+import './semantic-content-BbzjvSu9.js';
 
 type ListActionRowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -737,6 +827,8 @@ type ListActionRowRootAttributes = Readonly<Record<`data-${string}`, string | un
     'data-state'?: never;
     'data-selected'?: never;
     'data-pressed'?: never;
+    'data-dragging'?: never;
+    'data-drop-position'?: never;
 }>;
 type ListActionRowTrailingAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -748,7 +840,39 @@ type ListActionRowTrailingAttributes = Readonly<Record<`data-${string}`, string
     'aria-controls'?: string;
     'aria-haspopup'?: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | 'true';
 }>;
-interface ListActionRowProps {
+/** A trailing overflow `PopupMenu` rendered as the row's sibling trailing control. */
+interface ListActionRowTrailingMenu {
+    /** Accessible name of the icon-only menu trigger, such as `Actions for report.json`. */
+    label: string;
+    /** Decorative trigger icon, typically a `MoreHorizontal` `LucideIcon`. */
+    icon: SafeHtml;
+    /** The menu's commands, headings, and dividers; items dispatch their own `data-action`s. */
+    items: readonly PopupMenuEntry[];
+    /** Where the menu opens relative to its trigger. Defaults to `bottom-end`. */
+    placement?: PopupMenuPlacement;
+    disabled?: boolean;
+}
+interface ListActionRowTrailingButtonProps {
+    trailingAction: string;
+    trailingActionLabel: string;
+    /** Decorative dormant content for the trailing button. Must not contain interactive descendants. */
+    trailingActionIcon: SafeHtml;
+    trailingActionDisabled?: boolean;
+    trailingActionTitle?: string;
+    trailingActionAttributes?: ListActionRowTrailingAttributes;
+    trailingMenu?: never;
+}
+interface ListActionRowTrailingMenuProps {
+    /** A trailing overflow menu in place of the trailing button. Import `@kerfjs/ui/popup-menu/register` once. */
+    trailingMenu: ListActionRowTrailingMenu;
+    trailingAction?: never;
+    trailingActionLabel?: never;
+    trailingActionIcon?: never;
+    trailingActionDisabled?: never;
+    trailingActionTitle?: never;
+    trailingActionAttributes?: never;
+}
+interface ListActionRowCommonProps {
     /** Visible dormant content for the primary button. Must not contain interactive descendants. */
     label: string | SafeHtml;
     description?: string | SafeHtml;
@@ -770,22 +894,23 @@ interface ListActionRowProps {
     tabIndex?: number;
     /** Render as an unanimated loading skeleton, disabling both actions: label, description, icon, and status text become skeletons; the `busy` indicator stays live. */
     placeholder?: boolean;
-    trailingAction: string;
-    trailingActionLabel: string;
-    /** Decorative dormant content for the trailing button. Must not contain interactive descendants. */
-    trailingActionIcon: SafeHtml;
-    trailingActionDisabled?: boolean;
-    trailingActionTitle?: string;
+    /** Native HTML drag source (`draggable="true"` on the row root); a placeholder is never draggable. Pair with `wireListReorder` for pointer and keyboard reordering. */
+    draggable?: boolean;
+    /** Dim this row as one of the rows being dragged. */
+    dragging?: boolean;
+    /** Draw the insertion line at this row's leading (`before`) or trailing (`after`) block edge. */
+    dropPosition?: 'before' | 'after';
     trailingActionVisibility?: 'always' | 'interaction';
     className?: string;
     rootAttributes?: ListActionRowRootAttributes;
-    trailingActionAttributes?: ListActionRowTrailingAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ListActionRow({ label, description, status, busy, density, divider, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, trailingActionVisibility, className, rootAttributes, trailingActionAttributes, slot, }: ListActionRowProps): SafeHtml;
+/** Exactly one trailing control: a native button (`trailingAction*`) or an overflow menu (`trailingMenu`). */
+type ListActionRowProps = ListActionRowCommonProps & (ListActionRowTrailingButtonProps | ListActionRowTrailingMenuProps);
+declare function ListActionRow({ label, description, status, busy, density, divider, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, draggable, dragging, dropPosition, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, trailingActionVisibility, trailingMenu, className, rootAttributes, trailingActionAttributes, slot, }: ListActionRowProps): SafeHtml;
 
-export { ListActionRow, type ListActionRowProps };
+export { ListActionRow, type ListActionRowProps, type ListActionRowTrailingMenu };
 ```
 
 ## `@kerfjs/ui/list-item`
@@ -807,6 +932,8 @@ type ListItemRootAttributes = Readonly<Record<`data-${string}`, string | undefin
     'data-state'?: never;
     'data-kui-disabled'?: never;
     'data-icon-align'?: never;
+    'data-dragging'?: never;
+    'data-drop-position'?: never;
 }>;
 interface ListItemProps {
     label: string | SafeHtml;
@@ -836,6 +963,12 @@ interface ListItemProps {
     tabIndex?: number;
     /** Render the row as an unanimated loading skeleton, disabling its action: label, description, icon, status, and trailing content become skeletons; the `busy` indicator stays live. */
     placeholder?: boolean;
+    /** Native HTML drag source (`draggable="true"`); a placeholder is never draggable. Pair with `wireListReorder` for pointer and keyboard reordering. */
+    draggable?: boolean;
+    /** Dim this row as one of the rows being dragged. */
+    dragging?: boolean;
+    /** Draw the insertion line at this row's leading (`before`) or trailing (`after`) block edge. */
+    dropPosition?: 'before' | 'after';
     rootAttributes?: ListItemRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -848,9 +981,9 @@ interface ListItemLinkProps extends Omit<ListItemProps, 'action' | 'pressed'> {
     action?: never;
     pressed?: never;
 }
-declare function ListItem({ label, description, icon, trailing, status, busy, density, divider, selected, action, itemId, className, pressed, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, rootAttributes, slot, }: ListItemProps): SafeHtml;
+declare function ListItem({ label, description, icon, trailing, status, busy, density, divider, selected, action, itemId, className, pressed, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, draggable, dragging, dropPosition, rootAttributes, slot, }: ListItemProps): SafeHtml;
 /** A navigation row with native link activation and ListItem geometry. */
-declare function ListItemLink({ href, external, label, description, icon, trailing, status, busy, density, divider, selected, itemId, className, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, rootAttributes, slot, }: ListItemLinkProps): SafeHtml;
+declare function ListItemLink({ href, external, label, description, icon, trailing, status, busy, density, divider, selected, itemId, className, accessibleLabel, title, multiline, multilineIconAlign, state, disabled, tabIndex, placeholder, draggable, dragging, dropPosition, rootAttributes, slot, }: ListItemLinkProps): SafeHtml;
 
 export { ListItem, ListItemLink, type ListItemLinkProps, type ListItemProps };
 ```
@@ -924,8 +1057,17 @@ import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
-/** Base surface treatment or semantic status colors. */
-type ContentItemAppearance = 'transparent' | 'surface' | SemanticTone;
+/**
+ * Base surface treatment, semantic status colors, or `brand-loud`: the solid
+ * brand fill with its on-loud foreground (a transcript's own messages).
+ */
+type ContentItemAppearance = 'transparent' | 'surface' | 'brand-loud' | SemanticTone;
+/**
+ * A chat-bubble layout for transcripts: the item fits its content up to 80%
+ * of the row and sits at the `start` (other participants) or `end` (the
+ * person's own messages) of the line.
+ */
+type ContentItemBubble = 'start' | 'end';
 /** Whether the item's always-reserved 1px border is transparent or visible. */
 type ContentItemFrame = 'none' | 'framed';
 /** Corner shape: the 12px rounded rectangle or the 22px pill. */
@@ -936,11 +1078,13 @@ type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | unde
     'data-component'?: never;
     'data-appearance'?: never;
     'data-outlined'?: never;
+    'data-bubble'?: never;
 }>;
 type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-appearance'?: never;
     'data-outlined'?: never;
+    'data-bubble'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
     'data-interactive'?: never;
@@ -968,6 +1112,12 @@ interface ContentItemBaseProps {
     flush?: boolean;
     /** Corner shape. Defaults to `rounded`. */
     shape?: ContentItemShape;
+    /**
+     * Lay the item out as a chat bubble: content width up to 80% of the row,
+     * at the `start` or `end` of the line. Pair `end` with `brand-loud` for the
+     * person's own messages. Omit for an ordinary full-width item.
+     */
+    bubble?: ContentItemBubble;
     /** Native hover tooltip. */
     title?: string;
     /**
@@ -1016,9 +1166,9 @@ type ContentItemProps = ContentItemBaseProps & ({
  * 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({ appearance, children, frame, flush, shape, title, ariaLabel, focusTarget, outlined, tabIndex, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
+declare function ContentItem({ appearance, children, frame, flush, shape, bubble, title, ariaLabel, focusTarget, outlined, tabIndex, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
 
-export { ContentItem, type ContentItemAppearance, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape, SemanticTone };
+export { ContentItem, type ContentItemAppearance, type ContentItemBubble, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape, SemanticTone };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -1027,6 +1177,7 @@ export { ContentItem, type ContentItemAppearance, type ContentItemFrame, type Co
 import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 interface ValueTableRowProps {
     label: string | SafeHtml;
@@ -1040,18 +1191,35 @@ interface ValueTableRowProps {
 }
 declare function ValueTableRow({ label, value, icon, className, placeholder, slot, }: ValueTableRowProps): SafeHtml;
 
+/** `columns` keeps label and value side by side; `stacked` puts each value under its label. */
+type ValueTablePresentation = 'columns' | 'stacked';
+/** Table width below which columns stack: `compact` is 512px, `narrow` 576px. */
+type ValueTableStackBelow = 'compact' | 'narrow';
 interface ValueTableProps {
     label: string;
     /** Compact row spacing for metadata-dense surfaces. */
     density?: 'default' | 'compact';
+    /**
+     * Minimum width of the label column (for example `px(160)`); the value then
+     * takes the rest of the row. Omitted, label and value share the row by
+     * content.
+     */
+    labelWidth?: CssLength;
+    /** Side-by-side columns (default) or values stacked under their labels. */
+    presentation?: ValueTablePresentation;
+    /**
+     * Stack the rows only while the table itself is narrower than the preset,
+     * so one table reads as columns in a wide dialog and stacks on a phone.
+     */
+    stackBelow?: ValueTableStackBelow;
     className?: string;
     children: KerfUiContent;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ValueTable({ label, density, className, children, slot, }: ValueTableProps): kerfjs.SafeHtml;
+declare function ValueTable({ label, density, labelWidth, presentation, stackBelow, className, children, slot, }: ValueTableProps): kerfjs.SafeHtml;
 
-export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProps };
+export { ValueTable, type ValueTablePresentation, type ValueTableProps, ValueTableRow, type ValueTableRowProps, type ValueTableStackBelow };
 ```
 
 ## `@kerfjs/ui/app-tab`
@@ -1298,6 +1466,52 @@ declare function wireScrollDividers(root: Root, { targets }?: WireScrollDividers
 export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDividers };
 ```
 
+## `@kerfjs/ui/wire-list-reorder`
+
+```ts
+/** Which edge of the target row the moved rows land beside. */
+type ListDropPosition = 'before' | 'after';
+/** How the person asked for the move. */
+type ListReorderSource = 'pointer' | 'keyboard';
+/** The row the moved rows land beside, and on which side of it. */
+interface ListReorderTarget {
+    id: string;
+    position: ListDropPosition;
+}
+/** One requested reorder. The application applies it to its own ordered state. */
+interface ListReorder {
+    /** The containing list's `data-list-id`, when it has one. */
+    listId?: string;
+    /** The moved rows' `itemId`s, in their current order. */
+    sourceIds: string[];
+    target: ListReorderTarget;
+    source: ListReorderSource;
+}
+interface WireListReorderOptions {
+    /** Apply the change synchronously (for example with `reorderListItems`) and re-render. */
+    onReorder: (change: ListReorder) => void;
+}
+/**
+ * Move `sourceIds` (kept in their current relative order) to `target`'s side
+ * of the target row. Returns a new array; an unknown target, a target that is
+ * itself being moved, or no known sources leave the order unchanged.
+ */
+declare function reorderListItems<T>(items: readonly T[], getId: (item: T) => string, sourceIds: readonly string[], target: ListReorderTarget): T[];
+/**
+ * Wire native drag-and-drop and Alt+Shift+ArrowUp/ArrowDown reordering for
+ * draggable `ListItem`, `ListItemLink`, and `ListActionRow` rows below `root`.
+ * Rows reorder within their `List` (or parent element) and are identified by
+ * `itemId`. Dragging a selected or pressed row moves every selected row of
+ * its list. While a pointer drag is in progress the wiring paints the same
+ * `data-dragging` / `data-drop-position` attributes the rows' `dragging` and
+ * `dropPosition` props render. Order stays application state: `onReorder`
+ * reports the change and the application re-renders. Returns a disposer.
+ */
+declare function wireListReorder(root: HTMLElement | Document, { onReorder }: WireListReorderOptions): () => void;
+
+export { type ListDropPosition, type ListReorder, type ListReorderSource, type ListReorderTarget, type WireListReorderOptions, reorderListItems, wireListReorder };
+```
+
 ## `@kerfjs/ui/nav-stack`
 
 ```ts
@@ -1305,6 +1519,7 @@ export { c as NavStack, N as NavStackProps, d as NavStackToolbarConfig, a as Nav
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 import './list.js';
+import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './sides-BPSWde0A.js';
 import './css-values.js';
@@ -1347,6 +1562,7 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { N as NavStackProps, a as NavStackView } from './nav-stack-BvSKY448.js';
 import { ResizableRegionProps } from './resizable-region.js';
 import './list.js';
+import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './sides-BPSWde0A.js';
 import './css-values.js';
@@ -1382,6 +1598,17 @@ interface SplitViewCompactStack extends Pick<NavStackProps, 'toolbarConfig' | 'b
     /** Toolbar content for the pushed detail view. */
     detail?: SplitViewCompactViewToolbars;
 }
+/**
+ * The fixed list column's width: a size in CSS pixels, or that size capped
+ * at a fraction of the SplitView's own width so a narrow container (a
+ * dialog, a small window) always leaves the detail in view.
+ */
+type SplitViewListWidth = number | {
+    /** Preferred width in CSS pixels. */
+    size: number;
+    /** Largest share of the SplitView's width, greater than 0 and at most 1. */
+    maxFraction?: number;
+};
 interface SplitViewProps {
     id: string;
     label: string;
@@ -1407,6 +1634,12 @@ interface SplitViewProps {
     compactStack?: SplitViewCompactStack;
     /** A resizable separator on roomy classes (min/max px). Omit for a fixed split. */
     resizable?: SplitViewResizable;
+    /**
+     * The fixed split's list column width (default 320px). A number is CSS
+     * pixels; `{ size, maxFraction }` caps it at that share of the SplitView's
+     * width. A resizable split sizes its list with `resizable` instead.
+     */
+    listWidth?: SplitViewListWidth;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -1418,9 +1651,9 @@ interface SplitViewProps {
  * resizable wiring with `wireResizableRegions` and the compact back with
  * `wireNavStack`.
  */
-declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, compactStack, resizable, className, slot, }: SplitViewProps): kerfjs.SafeHtml;
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, compactStack, resizable, listWidth, className, slot, }: SplitViewProps): kerfjs.SafeHtml;
 
-export { SplitView, type SplitViewCompactStack, type SplitViewCompactViewToolbars, type SplitViewProps, type SplitViewResizable };
+export { SplitView, type SplitViewCompactStack, type SplitViewCompactViewToolbars, type SplitViewListWidth, type SplitViewProps, type SplitViewResizable };
 ```
 
 ## `@kerfjs/ui/pane`
@@ -1557,6 +1790,7 @@ import { a as PanelToolbar, c as PanelBottomToolbar, b as PanelChromePlacement,
 import { ToolbarConfig } from './toolbar.js';
 import './toolbar-text.js';
 import './css-values.js';
+import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './sides-BPSWde0A.js';
 import './lucide-icon.js';
@@ -1947,14 +2181,15 @@ import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
 export { e as collapsiblePanelToggleIcon } from './panel-toolbar-CL9tYOkh.js';
+import { ToolbarConfig } from './toolbar.js';
 import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
-import './toolbar.js';
-import './sides-BPSWde0A.js';
 import './lucide-icon.js';
 import 'lucide';
 import './css-values.js';
+import './sides-BPSWde0A.js';
+import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
@@ -2068,6 +2303,12 @@ interface CollapsiblePanelRelocatedProps {
     collapsed: boolean;
     /** The same `toolbar` the panel receives. */
     toolbar: CollapsiblePanelToolbar;
+    /**
+     * Density of the toolbar the groups are placed in, so the standard toggle
+     * fits it (`compact` in a `density="compact"` toolbar). Defaults to
+     * `default`.
+     */
+    density?: ToolbarConfig['density'];
 }
 /**
  * A collapsed {@link CollapsiblePanel}'s marked groups and standard
@@ -2077,7 +2318,7 @@ interface CollapsiblePanelRelocatedProps {
  * `restoreControl`) for a bottom drawer. `wireSidebar` hands focus to it when
  * the panel closes from its own toggle.
  */
-declare function CollapsiblePanelRelocated({ panelId, side, collapsed, toolbar, }: CollapsiblePanelRelocatedProps): SafeHtml;
+declare function CollapsiblePanelRelocated({ panelId, side, collapsed, toolbar, density, }: CollapsiblePanelRelocatedProps): SafeHtml;
 
 export { CollapsiblePanel, type CollapsiblePanelBottomToolbar, type CollapsiblePanelChromePlacement, type CollapsiblePanelProps, CollapsiblePanelRelocated, type CollapsiblePanelRelocatedProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, type CollapsiblePanelToolbar, type CollapsiblePanelToolbarToggle };
 ```
@@ -2423,6 +2664,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';
@@ -2546,6 +2788,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';
@@ -2599,6 +2842,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';
@@ -2760,6 +3004,69 @@ declare function SegmentedControl<Value extends string>({ id, label, value, choi
 export { SegmentedControl, type SegmentedControlAppearance, type SegmentedControlChoice, type SegmentedControlLayout, type SegmentedControlProps, type SegmentedControlShape, type SegmentedControlSize };
 ```
 
+## `@kerfjs/ui/choice-chips`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { CssColor } from './css-values.js';
+
+type ChoiceChipsSize = 'default' | 'compact';
+/**
+ * A leading color dot: a {@link CssColor} from `uiColor()`, `colorVar()`, or
+ * `foregroundColor()`, or `'transparent'` for the no-color swatch (an outlined
+ * dot struck through by a diagonal line).
+ */
+type ChoiceChipsSwatch = CssColor | 'transparent';
+interface ChoiceChipsChoice<Value extends string = string> {
+    value: Value;
+    /** Visible label; it is also the radio's accessible name. */
+    label: string;
+    /** Leading color dot. Mutually exclusive with `icon`. */
+    swatch?: ChoiceChipsSwatch;
+    /** Decorative leading icon, normally an unsized LucideIcon. */
+    icon?: SafeHtml;
+    /** Supplementary tooltip; never the only place a choice is described. */
+    title?: string;
+    disabled?: boolean;
+}
+interface ChoiceChipsCommonProps<Value extends string> {
+    /** Native radio `name`: the form field the selected value submits under. */
+    name: string;
+    /** The selected value. Omit (or pass `undefined`) for no selection. */
+    value?: NoInfer<Value>;
+    choices: readonly ChoiceChipsChoice<Value>[];
+    /** Delegated `data-action` on every radio; listen for `change`. */
+    action?: string;
+    size?: ChoiceChipsSize;
+    /** Disable the whole group. */
+    disabled?: boolean;
+    /** Require a selection for native form validation. */
+    required?: boolean;
+    /** Associate the radios with a form outside their ancestor chain. */
+    form?: string;
+    id?: string;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/** A radio group is named either by a string or by a visible heading's id. */
+type ChoiceChipsProps<Value extends string = string> = ChoiceChipsCommonProps<Value> & ({
+    label: string;
+    labelledBy?: never;
+} | {
+    labelledBy: string;
+    label?: never;
+});
+/**
+ * An exclusive, wrapping set of pill chips backed by native radios: one Tab
+ * stop, arrow-key selection, and a real form value. Each choice may lead with
+ * a color swatch (including a struck-through transparent swatch) or an icon.
+ */
+declare function ChoiceChips<Value extends string>({ name, value, choices, action, size, disabled, required, form, id, className, slot, label, labelledBy, }: ChoiceChipsProps<Value>): SafeHtml;
+
+export { ChoiceChips, type ChoiceChipsChoice, type ChoiceChipsProps, type ChoiceChipsSize, type ChoiceChipsSwatch };
+```
+
 ## `@kerfjs/ui/select`
 
 ```ts
@@ -2896,6 +3203,7 @@ export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectMultip
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
 /** @deprecated Use SemanticTone. */
@@ -2903,6 +3211,7 @@ type StateBannerTone = SemanticTone;
 type StateBannerUrgency = 'status' | 'alert';
 type StateBannerCopyLayout = 'inline' | 'stacked';
 type StateBannerActionPlacement = 'trailing' | 'below';
+type StateBannerPresentation = 'card' | 'strip';
 interface StateBannerProps {
     title: string;
     detail?: string;
@@ -2916,15 +3225,28 @@ interface StateBannerProps {
     copyLayout?: StateBannerCopyLayout;
     /** Place the action beside the copy or on a separate trailing row. */
     actionPlacement?: StateBannerActionPlacement;
+    /**
+     * `card` (the default) is an inset, rounded, fully bordered banner beside
+     * the affected work. `strip` is a full-width band at a layout edge, such as
+     * above a workspace: square corners, no inline margin, inline padding on the
+     * shared content-text column, and only the tone-colored `dividerSides` edges.
+     */
+    presentation?: StateBannerPresentation;
+    /**
+     * Physical tone-colored divider edges of a `strip`, in canonical
+     * top/right/bottom/left order. Defaults to the bottom edge; `''` draws none.
+     * A `card` keeps its full border and ignores this.
+     */
+    dividerSides?: Sides;
     className?: string;
     /** Render the title, badge, and detail as unanimated loading skeletons, keeping the icon and tone. The detail line appears only when `detail` is set, as in the live banner. */
     placeholder?: boolean;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, copyLayout, actionPlacement, className, placeholder, slot, }: StateBannerProps): SafeHtml;
+declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, copyLayout, actionPlacement, presentation, dividerSides, className, placeholder, slot, }: StateBannerProps): SafeHtml;
 
-export { SemanticTone, StateBanner, type StateBannerActionPlacement, type StateBannerCopyLayout, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
+export { SemanticTone, StateBanner, type StateBannerActionPlacement, type StateBannerCopyLayout, type StateBannerPresentation, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
 ```
 
 ## `@kerfjs/ui/empty-state`
@@ -3016,6 +3338,13 @@ import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { CssFlexKeyword, CssFlex } from './css-values.js';
 
+/**
+ * Generate the sunken texture once for a document. Sunken surfaces call this
+ * as they render; it is idempotent, and on a server (no document) or without
+ * a 2D canvas it does nothing, leaving the flat lowered surface.
+ */
+declare function ensureSunkenTexture(doc?: Document | undefined): void;
+
 type SunkenPanelShape = 'rounded' | 'square';
 interface SunkenPanelProps {
     children?: KerfUiContent;
@@ -3042,7 +3371,7 @@ interface SunkenPanelProps {
  */
 declare function SunkenPanel({ children, ariaLabel, shape, flex, fill, tabIndex, outlined, className, slot, }: SunkenPanelProps): kerfjs.SafeHtml;
 
-export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
+export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape, ensureSunkenTexture };
 ```
 
 ## `@kerfjs/ui/token-search-field`
@@ -3254,6 +3583,7 @@ export { type ActionHandler, type DelegateActionsOptions, action, delegateAction
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { CssLength } from './css-values.js';
 import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
 /** @deprecated Use SemanticTone. */
@@ -3262,8 +3592,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;
@@ -3271,10 +3615,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;
@@ -3301,12 +3658,13 @@ 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 };
 ```
 
 ## `@kerfjs/ui/chip`
@@ -3315,6 +3673,7 @@ export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type
 import { SafeHtml } from 'kerfjs';
 import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 import { BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
+import './css-values.js';
 
 interface ChipCommonProps {
     /** Decorative leading icon, normally an unsized LucideIcon. */
@@ -3410,6 +3769,19 @@ type DialogSurfaceSize = 'small' | 'medium' | 'large';
 type DialogSurfacePresentation = 'modal' | 'side-sheet' | 'fullscreen';
 type SurfaceInset = 'none' | 'compact' | 'comfortable';
 type DialogSurfaceMaxHeight = CssLength | 'viewport';
+/** A definite modal height: a length or the full viewport, minus both gutters. */
+type DialogSurfaceHeight = CssLength | 'viewport';
+/**
+ * How the dialog body lays out its children: `flow` (default) scrolls ordinary
+ * content in the body; `fill` gives one child the body's whole height and
+ * lets it own scrolling (a SplitView, a Pane, an editor).
+ */
+type DialogSurfaceBodyLayout = 'flow' | 'fill';
+/**
+ * Application `data-*` identity on the DialogSurface root, such as
+ * `data-key`; the surface's own configuration attributes stay protected.
+ */
+type DialogSurfaceRootAttributes = Readonly<Record<`data-${string}`, string | undefined>>;
 interface DialogSurfaceProps {
     children: KerfUiContent;
     size?: DialogSurfaceSize;
@@ -3422,12 +3794,72 @@ interface DialogSurfaceProps {
     viewportGutter?: CssLength;
     /** Modal height cap, bounded by the dynamic viewport minus both gutters. */
     maxHeight?: DialogSurfaceMaxHeight;
+    /**
+     * Modal definite height, bounded the same way, so a filling child has a
+     * height to fill. Takes precedence over `maxHeight`.
+     */
+    height?: DialogSurfaceHeight;
+    /** Body layout (default `flow`); `fill` lets one child own the body. */
+    bodyLayout?: DialogSurfaceBodyLayout;
+    /**
+     * Safe `data-*` identity on the root. Give sibling dialogs distinct
+     * `data-key`s so a re-render morphs each surface into itself instead of
+     * reusing one dialog's element for another (structurally identical roots
+     * are otherwise matched by position).
+     */
+    rootAttributes?: DialogSurfaceRootAttributes;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** Configure recurring Web Awesome dialog geometry without consumer ::part() CSS. */
-declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, bodyLayout, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+/** Where a PopoverDialogSurface appears: the top layer, or in flow. */
+type PopoverDialogSurfacePresentation = 'overlay' | 'embedded';
+/** Application `data-*` metadata on the surface root. */
+type PopoverDialogSurfaceDataAttributes = Readonly<Record<`data-${string}`, string>>;
+type PopoverDialogSurfaceName = {
+    label: string;
+    labelledBy?: never;
+} | {
+    label?: never;
+    labelledBy: string;
+};
+type PopoverDialogSurfaceProps = PopoverDialogSurfaceName & {
+    /** The root id: what an opening control's `popovertarget` names. */
+    id?: string;
+    children: KerfUiContent;
+    /**
+     * `overlay` (default) is a native `popover="auto"` in the top layer:
+     * non-modal, light dismiss (Escape or a press outside), nothing inert.
+     * `embedded` renders the same surface in flow for a catalog or inline use.
+     */
+    presentation?: PopoverDialogSurfacePresentation;
+    /** Preferred width preset: 400px, 560px (default), or 800px. */
+    size?: DialogSurfaceSize;
+    /** Preferred width; takes precedence over `size`, within the viewport cap. */
+    preferredWidth?: CssLength;
+    /** Definite height, bounded by the dynamic viewport minus both gutters. */
+    height?: DialogSurfaceHeight;
+    /** Height cap, bounded the same way, for a surface that sizes to content. */
+    maxHeight?: DialogSurfaceMaxHeight;
+    /** Edge clearance on each side of the viewport (default 16px). */
+    viewportGutter?: CssLength;
+    /** Body layout (default `flow`); `fill` lets one child own the surface. */
+    bodyLayout?: DialogSurfaceBodyLayout;
+    rootAttributes?: PopoverDialogSurfaceDataAttributes;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+};
+/**
+ * A non-modal dialog surface on the native Popover API: Kerf's dialog chrome,
+ * viewport-bounded size, and single-child fill without application CSS.
+ * Open it with a `popovertarget` control or `showPopover()`; it light
+ * dismisses and leaves the page interactive. Use `DialogSurface` with
+ * `wa-dialog` when the task must block the page.
+ */
+declare function PopoverDialogSurface({ id, children, label, labelledBy, presentation, size, preferredWidth, height, maxHeight, viewportGutter, bodyLayout, rootAttributes, className, slot, }: PopoverDialogSurfaceProps): kerfjs.SafeHtml;
 type PopupSurfaceInset = 'standard' | 'compact' | 'list-zero';
 interface PopupSurfaceProps {
     children: KerfUiContent;
@@ -3439,7 +3871,7 @@ interface PopupSurfaceProps {
 /** Configure recurring Web Awesome dropdown-menu geometry without consumer ::part() CSS. */
 declare function PopupSurface({ children, inset, className, slot, }: PopupSurfaceProps): kerfjs.SafeHtml;
 
-export { DialogSurface, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceSize, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
+export { DialogSurface, type DialogSurfaceBodyLayout, type DialogSurfaceHeight, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceRootAttributes, type DialogSurfaceSize, PopoverDialogSurface, type PopoverDialogSurfaceDataAttributes, type PopoverDialogSurfacePresentation, type PopoverDialogSurfaceProps, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
 ```
 
 ## `@kerfjs/ui/text`
@@ -3466,6 +3898,19 @@ type TextFont = 'default' | 'monospace';
 type TextBorder = 'transparent' | 'none';
 type TextLineHeight = 'default' | 'tight';
 type TextWrap = 'normal' | 'anywhere' | 'nowrap' | 'truncate';
+/** Inline alignment of the text's lines, in logical (writing-direction) terms. */
+type TextAlign = 'start' | 'center' | 'end';
+/**
+ * Where `wrap="truncate"` places its ellipsis: `end` (default) keeps the
+ * start, `start` keeps the tail (branch names, the end of an identifier), and
+ * `middle` keeps both the start and a suffix (file paths).
+ */
+type TextTruncate = 'end' | 'middle' | 'start';
+/**
+ * The suffix `truncate="middle"` always keeps: a number of trailing
+ * characters, or `segment` for the last path segment with its separator.
+ */
+type TextTruncateKeep = number | 'segment';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
 type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
@@ -3486,6 +3931,8 @@ type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> &
     flush?: boolean;
     /** Use compact leading for short dialog or metadata copy. */
     lineHeight?: TextLineHeight;
+    /** Inline alignment of the lines (default `start`), for centered status copy. */
+    align?: TextAlign;
     children: TextContent;
     class?: string;
     className?: string;
@@ -3495,19 +3942,152 @@ type TextProps = TextCommonProps & ({
     wrap?: 'normal' | 'anywhere';
     /** Cap wrapped text to this positive number of lines. */
     maxLines?: number;
+    truncate?: never;
+    truncateKeep?: never;
 } | {
-    /** Keep one line, with or without an ellipsis. */
-    wrap: 'nowrap' | 'truncate';
+    /** Keep one line without an ellipsis. */
+    wrap: 'nowrap';
     maxLines?: never;
+    truncate?: never;
+    truncateKeep?: never;
+} | {
+    /** Keep one line with an ellipsis. */
+    wrap: 'truncate';
+    maxLines?: never;
+    /**
+     * Where the ellipsis goes (default `end`). `start` and `middle` are
+     * for left-to-right identifiers and paths, and `middle` requires
+     * string or number children so it can split them.
+     */
+    truncate?: TextTruncate;
+    /**
+     * The suffix `truncate="middle"` keeps (default `segment`: the last
+     * path segment, or the last 10 characters when there is no `/` or
+     * `\\` separator).
+     */
+    truncateKeep?: TextTruncateKeep;
 });
 /**
  * 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, color, size, font, border, flush, controlMargins, lineHeight, wrap, maxLines, children, class: classValue, className, style, ...attributes }: TextProps): kerfjs.SafeHtml;
+declare function Text({ variant: Variant, tone, color, size, font, border, flush, controlMargins, lineHeight, align, wrap, maxLines, truncate, truncateKeep, children, class: classValue, className, style, ...attributes }: TextProps): kerfjs.SafeHtml;
 
-export { FieldLabel, type FieldLabelProps, Sides, Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant, type TextWrap };
+export { FieldLabel, type FieldLabelProps, Sides, Text, type TextAlign, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextTruncate, type TextTruncateKeep, type TextVariant, type TextWrap };
+```
+
+## `@kerfjs/ui/framed-list`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/** The frame's fill: the lowered surface (as `ValueTable`), or the page surface. */
+type FramedListSurface = 'lowered' | 'base';
+type FramedListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-surface'?: never;
+}>;
+type FramedListRowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-highlighted'?: never;
+}>;
+interface FramedListProps {
+    /** `FramedListRow` children. */
+    children: KerfUiContent;
+    /** Accessible name for the list, when no heading names it. */
+    label?: string;
+    /** Frame fill; defaults to `lowered`, matching `ValueTable`. */
+    surface?: FramedListSurface;
+    id?: string;
+    className?: string;
+    /** Safe `data-*` metadata; FramedList-owned markers stay protected. */
+    rootAttributes?: FramedListRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+interface FramedListRowProps {
+    /** Arbitrary row content: a `Row` of copy and controls, a keycap, … */
+    children: KerfUiContent;
+    /** Tint the row (the row being edited or the current item). */
+    highlighted?: boolean;
+    id?: string;
+    className?: string;
+    /** Safe `data-*` metadata; FramedListRow-owned markers stay protected. */
+    rootAttributes?: FramedListRowRootAttributes;
+}
+/**
+ * An inset-grouped list (the settings-list pattern): one rounded, bordered
+ * frame with 1px dividers between rows of arbitrary content. `ValueTable` is
+ * the same frame for label/value facts; this one takes any row content.
+ */
+declare function FramedList({ children, label, surface, id, className, rootAttributes, slot, }: FramedListProps): kerfjs.SafeHtml;
+/** One row of a `FramedList`; it owns the row inset and the divider above it. */
+declare function FramedListRow({ children, highlighted, id, className, rootAttributes, }: FramedListRowProps): kerfjs.SafeHtml;
+
+export { FramedList, type FramedListProps, FramedListRow, type FramedListRowProps, type FramedListSurface };
+```
+
+## `@kerfjs/ui/summary-row`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
+
+/** `row` for a list section; `card` for a board column. */
+type SummaryRowPresentation = 'row' | 'card';
+/** A row's place in a rounded list section, so its corners match. */
+type SummaryRowListEdge = 'start' | 'end' | 'only';
+type SummaryRowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-presentation'?: never;
+    'data-list-edge'?: never;
+    'data-rail'?: never;
+    'data-selected'?: never;
+    'data-dimmed'?: never;
+}>;
+interface SummaryRowProps {
+    /** The identity line: an identifier, inline status glyphs, and the title. */
+    title: KerfUiContent;
+    /** Optional leading glyph, such as a category icon. */
+    leading?: SafeHtml;
+    /** Quiet text at the end of the title line, such as a relative time. */
+    trailingMeta?: string | SafeHtml;
+    /** A wrapping line of badges, chips, and quiet text below the title. */
+    metadata?: KerfUiContent;
+    /** `row` (default) or `card`. */
+    presentation?: SummaryRowPresentation;
+    /** Title lines before clipping; default 2 for a row and 4 for a card. */
+    titleLines?: number;
+    /** A leading state rail in a semantic tone (Up Next, blocked, …). */
+    rail?: SemanticTone;
+    /** Selected state, exposed as `aria-selected`. */
+    selected?: boolean;
+    /** Dim a finished or cut item; hover and selection restore it. */
+    dimmed?: boolean;
+    /** Round the corners that meet a rounded list section's edge. */
+    listEdge?: SummaryRowListEdge;
+    /** Skip rendering while off screen in long lists (`content-visibility`). */
+    deferRendering?: boolean;
+    /** Accessible name when the visible content is not a good one. */
+    ariaLabel?: string;
+    id?: string;
+    className?: string;
+    /** Safe `data-*` identity (an item id or delegated action) on the option. */
+    rootAttributes?: SummaryRowRootAttributes;
+}
+/**
+ * A selectable, keyboard-focusable summary of one item, as a list row or a
+ * board card: an optional leading glyph and state rail, a clamped identity line
+ * with trailing quiet metadata, and a wrapping metadata line. It is a
+ * `role="option"`; place rows in a labeled `role="listbox"` and own selection
+ * and keyboard movement in the application.
+ */
+declare function SummaryRow({ title, leading, trailingMeta, metadata, presentation, titleLines, rail, selected, dimmed, listEdge, deferRendering, ariaLabel, id, className, rootAttributes, }: SummaryRowProps): SafeHtml;
+
+export { SummaryRow, type SummaryRowListEdge, type SummaryRowPresentation, type SummaryRowProps };
 ```
 
 ## `@kerfjs/ui/row`
@@ -3515,12 +4095,13 @@ export { FieldLabel, type FieldLabelProps, Sides, Text, type TextBorder, type Te
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as StructuralRootAttributes } from './extension-attributes-mu8MFUl0.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { S as Sides } from './sides-BPSWde0A.js';
 import { UiGap, CssFlexKeyword, CssFlex } from './css-values.js';
 export { CssLength, UiGapValue, UiSpaceName } from './css-values.js';
 
-type RowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type RowRootAttributes = StructuralRootAttributes & Readonly<{
     'data-component'?: never;
     'data-h-align'?: never;
     'data-v-align'?: never;
@@ -3553,7 +4134,10 @@ interface RowProps {
     /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
     controlInsets?: Sides;
     className?: string;
-    /** Safe `data-*` metadata; Row-owned structural attributes remain protected. */
+    /**
+     * Safe `data-*`, `aria-*`, and structural `role` metadata (a named
+     * `region`, a `group`); Row-owned structural attributes remain protected.
+     */
     rootAttributes?: RowRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -3627,6 +4211,91 @@ declare function Grid({ children, selectionMode, ariaLabel, columns, minColumnWi
 export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, Sides, UiGap };
 ```
 
+## `@kerfjs/ui/column-track`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as StructuralRootAttributes } from './extension-attributes-mu8MFUl0.js';
+import { CssLength } from './css-values.js';
+
+/** `scroll` keeps equal min-width columns; `paged` shows one near-full-width column per page. */
+type ColumnTrackLayout = 'scroll' | 'paged';
+type ColumnTrackRootAttributes = StructuralRootAttributes & Readonly<{
+    'data-component'?: never;
+    'data-layout'?: never;
+}>;
+interface ColumnTrackProps {
+    /** The columns, in order; each owns its own inset and scrolling. */
+    children: KerfUiContent;
+    /**
+     * `scroll` (default): equal columns that never shrink below
+     * `minColumnWidth`, so a narrow track scrolls sideways instead of crushing
+     * them. `paged`: each column is nearly the visible width, the next one peeks
+     * in, and scrolling snaps to column starts.
+     */
+    layout?: ColumnTrackLayout;
+    /** Narrowest a `scroll` column gets before the track scrolls; default 250px. */
+    minColumnWidth?: CssLength;
+    /** How much of the next column a `paged` track shows; default 24px. */
+    peek?: CssLength;
+    id?: string;
+    className?: string;
+    /** Safe `data-*`, `aria-*`, and structural `role` metadata on the scroller. */
+    rootAttributes?: ColumnTrackRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/**
+ * A horizontal track of columns (a kanban board): the track is the sideways
+ * scroll owner and fills its parent's height; columns sit flush and own their
+ * insets and vertical scrolling. Kerf owns the overflow, the paged snapping,
+ * and reduced motion.
+ */
+declare function ColumnTrack({ children, layout, minColumnWidth, peek, id, className, rootAttributes, slot, }: ColumnTrackProps): kerfjs.SafeHtml;
+
+export { ColumnTrack, type ColumnTrackLayout, type ColumnTrackProps };
+```
+
+## `@kerfjs/ui/content-swap`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+type ContentSwapSide = 'a' | 'b';
+type ContentSwapTransition = 'none' | 'crossfade' | 'push';
+/** `forward` pushes the incoming side in from the inline end; `backward` from the start. */
+type ContentSwapDirection = 'forward' | 'backward';
+interface ContentSwapProps {
+    /** Which side is shown. Changing it runs the transition. */
+    active: ContentSwapSide;
+    a: KerfUiContent;
+    b: KerfUiContent;
+    /** `push` (default) slides the sides, `crossfade` fades them, `none` swaps instantly. */
+    transition?: ContentSwapTransition;
+    /** Push direction; mirrors in right-to-left documents. Default `forward`. */
+    direction?: ContentSwapDirection;
+    /** Accessible name; when set, the swap is a named region. */
+    label?: string;
+    /** Span the full width of its slot (a dialog label or footer) instead of its content. */
+    fill?: boolean;
+    className?: string;
+    /** Native named-slot assignment, such as a dialog's `label` or `footer`. */
+    slot?: string;
+}
+/**
+ * Two content sides sharing one cell (a dialog body that steps to a second
+ * page, a footer whose actions change), with the swap animated in place.
+ * Kerf owns the motion, the reduced-motion fallback, and the inactive side's
+ * `inert`/`aria-hidden`. Use `NavStack` for full views with their own
+ * toolbars.
+ */
+declare function ContentSwap({ active, a, b, transition, direction, label, fill, className, slot, }: ContentSwapProps): kerfjs.SafeHtml;
+
+export { ContentSwap, type ContentSwapDirection, type ContentSwapProps, type ContentSwapSide, type ContentSwapTransition };
+```
+
 ## `@kerfjs/ui/spacer`
 
 ```ts
@@ -3658,21 +4327,77 @@ import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 ```
 
+## `@kerfjs/ui/combobox`
+
+```ts
+import * as kerfjs from 'kerfjs';
+
+/** A suggestion: a plain string, or a value with a distinct visible label. */
+type ComboboxSuggestion = string | {
+    value: string;
+    label: string;
+};
+interface ComboboxProps {
+    /** Unique id; it also identifies the field in `wireComboboxes` reports. */
+    id: string;
+    /** Visible field label. */
+    label: string;
+    /** Suggestions to filter as the person types. */
+    suggestions: readonly ComboboxSuggestion[];
+    /** Initial text; the field owns its text while the person types. */
+    value?: string;
+    placeholder?: string;
+    /** Optional hint below the field, such as "Press Enter to add". */
+    hint?: string;
+    /** Form field name. */
+    name?: string;
+    /**
+     * Offer to create the typed text when it matches no suggestion; the option
+     * reads `createLabel` with `{value}` replaced. Omit to only allow
+     * suggestions. Default `Create “{value}”`.
+     */
+    createLabel?: string | false;
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * A free-text field with a filtered suggestion list that can also create a new
+ * value: the ARIA combobox pattern on a native input with the themed Web
+ * Awesome field chrome. `wireComboboxes` filters, moves the active option,
+ * and reports commits (Enter, comma, or a click). Use `Select` when only
+ * existing values are allowed and nothing is typed.
+ */
+declare function Combobox({ id, label, suggestions, value, placeholder, hint, name, createLabel, disabled, className, }: ComboboxProps): kerfjs.SafeHtml;
+
+export { Combobox, type ComboboxProps, type ComboboxSuggestion };
+```
+
 ## `@kerfjs/ui/anchored-surface`
 
 ```ts
 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;
 }
 /**
@@ -3692,3 +4417,289 @@ declare function openAnchoredSurfaceAt(point: AnchoredSurfacePoint, content: Ove
 
 export { type AnchoredSurfaceOptions, type AnchoredSurfacePoint, openAnchoredSurface, openAnchoredSurfaceAt };
 ```
+
+## `@kerfjs/ui/icon-button`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { LucideNode } from './lucide-icon.js';
+import 'lucide';
+import './css-values.js';
+
+type IconButtonAppearance = 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain';
+type IconButtonVariant = 'neutral' | 'brand' | 'success' | 'warning' | 'danger';
+type IconButtonSize = 'xs' | 's' | 'm' | 'l' | 'xl';
+type IconButtonRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-action'?: never;
+}>;
+interface IconButtonProps {
+    /** The Lucide-compatible icon node shown alone in the button. */
+    icon: LucideNode;
+    /** The icon's stable name, as `LucideIcon` takes it. */
+    iconName: string;
+    /** Accessible name; the button has no visible text, so it is required. */
+    label: string;
+    /** Delegated `data-action` the application handles. */
+    action?: string;
+    /** Web Awesome appearance; defaults to Web Awesome's own. */
+    appearance?: IconButtonAppearance;
+    /** Web Awesome semantic variant; defaults to Web Awesome's own. */
+    variant?: IconButtonVariant;
+    /** Web Awesome control size; the square follows its control height. */
+    size?: IconButtonSize;
+    type?: 'button' | 'submit' | 'reset';
+    disabled?: boolean;
+    id?: string;
+    className?: string;
+    /** Safe `data-*` metadata; `data-component` and `data-action` stay owned. */
+    rootAttributes?: IconButtonRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/**
+ * An icon-only Web Awesome button with a `LucideIcon`: square, one form
+ * control height on each side, so it matches an adjacent `wa-input` or
+ * `Select`. Web Awesome squares a button only for a lone `wa-icon`; this is
+ * the Kerf form for Lucide icons. Register `wa-button` once
+ * (`@awesome.me/webawesome/dist/components/button/button.js`).
+ */
+declare function IconButton({ icon, iconName, label, action, appearance, variant, size, type, disabled, id, className, rootAttributes, slot, }: IconButtonProps): kerfjs.SafeHtml;
+
+export { IconButton, type IconButtonAppearance, type IconButtonProps, type IconButtonSize, type IconButtonVariant };
+```
+
+## `@kerfjs/ui/icon-toggle-button`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { LucideNode } from './lucide-icon.js';
+import 'lucide';
+import './css-values.js';
+
+/** Corner shape: fully round `pill` (default) or a softer `rounded` square. */
+type IconToggleButtonShape = 'pill' | 'rounded';
+type IconToggleButtonRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-action'?: never;
+    'data-shape'?: never;
+}>;
+interface IconToggleButtonProps {
+    /** The Lucide-compatible icon node. */
+    icon: LucideNode;
+    /** The icon's stable name, as `LucideIcon` takes it. */
+    iconName: string;
+    /** Accessible name and hover help tag; required because no text is shown. */
+    label: string;
+    /** Pressed state, exposed as `aria-pressed`; the application owns it. */
+    pressed: boolean;
+    /** Delegated `data-action` the application handles to flip `pressed`. */
+    action?: string;
+    shape?: IconToggleButtonShape;
+    disabled?: boolean;
+    id?: string;
+    className?: string;
+    /** Safe `data-*` metadata; IconToggleButton-owned markers stay protected. */
+    rootAttributes?: IconToggleButtonRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/**
+ * A standalone, icon-only toggle: a native `<button aria-pressed>` with the
+ * geometry and pressed chrome of a single contained `ToolbarControlGroup`
+ * (44px, a 2px-inset face that rises when pressed), for content and pane
+ * footers where no `Toolbar` belongs. Inside a toolbar, use a
+ * `ToolbarControlGroup` instead.
+ */
+declare function IconToggleButton({ icon, iconName, label, pressed, action, shape, disabled, id, className, rootAttributes, slot, }: IconToggleButtonProps): kerfjs.SafeHtml;
+
+export { IconToggleButton, type IconToggleButtonProps, type IconToggleButtonShape };
+```
+
+## `@kerfjs/ui/split-button`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+/** The loud fill the whole split button paints. */
+type SplitButtonTone = 'brand' | 'neutral' | 'success' | 'warning' | 'danger';
+type SplitButtonRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-tone'?: never;
+    'data-fill'?: never;
+    'data-busy'?: never;
+}>;
+interface SplitButtonProps {
+    /** Visible primary label. */
+    label: string;
+    /** Delegated `data-action` of the primary half. */
+    action: string;
+    /** Optional decorative leading icon of the primary half. */
+    icon?: SafeHtml;
+    /** Primary accessible name when it should say more than `label`. */
+    accessibleLabel?: string;
+    /** Accessible name (and tooltip) of the options trigger. */
+    optionsLabel: string;
+    /** Delegated `data-action` of the options trigger, which opens the app's menu. */
+    optionsAction: string;
+    /** Whether the options menu is open, exposed as `aria-expanded`. */
+    optionsExpanded?: boolean;
+    /** What the options trigger opens, exposed as `aria-haspopup`; defaults to `menu`. */
+    optionsPopup?: 'menu' | 'dialog' | 'listbox';
+    /** Element id the options trigger controls, exposed as `aria-controls`. */
+    optionsControls?: string;
+    /** The loud fill; defaults to `brand`. Switch it (for example to `neutral`) while running. */
+    tone?: SplitButtonTone;
+    /** Span the full width of the parent instead of sizing to the label. */
+    fill?: boolean;
+    /** Show work in progress: a spinner replaces the icon and the primary is `aria-busy`. */
+    busy?: boolean;
+    /** Disable the primary half. */
+    disabled?: boolean;
+    /** Disable the options trigger. */
+    optionsDisabled?: boolean;
+    /** Native tooltip of the primary half, for example why it is disabled. */
+    title?: string;
+    className?: string;
+    /** Safe `data-*` metadata; SplitButton-owned markers stay protected. */
+    rootAttributes?: SplitButtonRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/**
+ * A primary action with an attached options trigger on one loud, semantic
+ * fill (a "Drive" button with a provider menu). Both halves are native
+ * buttons, so `aria-expanded` and the accessible names reach assistive
+ * technology directly; the application opens its own menu from the options
+ * action and owns the running state.
+ */
+declare function SplitButton({ label, action, icon, accessibleLabel, optionsLabel, optionsAction, optionsExpanded, optionsPopup, optionsControls, tone, fill, busy, disabled, optionsDisabled, title, className, rootAttributes, slot, }: SplitButtonProps): SafeHtml;
+
+export { SplitButton, type SplitButtonProps, type SplitButtonTone };
+```
+
+## `@kerfjs/ui/file-picker`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+interface FileInputProps {
+    /** Accepted types, as the native `accept` attribute (`.png,image/*`). */
+    accept?: string;
+    /** Allow several files at once. */
+    multiple?: boolean;
+    /** Form field name of the native file input. */
+    name?: string;
+    /** Identifies this picker in `wireFilePickers` reports. */
+    pickerId?: string;
+    disabled?: boolean;
+    className?: string;
+}
+interface FilePickerTriggerProps extends FileInputProps {
+    /** Visible trigger text, such as "Add". */
+    label: string;
+    /** Accessible name of the file input when it should say more than `label`. */
+    accessibleLabel?: string;
+    /** Optional decorative leading icon, normally an unsized LucideIcon. */
+    icon?: SafeHtml;
+}
+interface FileDropZoneProps extends FileInputProps {
+    /** Primary copy, such as "Drop attachments here or browse". */
+    title: string;
+    /** Optional secondary copy, such as accepted types or a size limit. */
+    detail?: string;
+    /** Optional decorative icon above the copy, normally an unsized LucideIcon. */
+    icon?: SafeHtml;
+    /** Accessible name of the file input when it should say more than `title`. */
+    accessibleLabel?: string;
+}
+/**
+ * A compact, link-toned trigger that opens the native file chooser: a label
+ * around a visually hidden `<input type="file">`, so a click or keyboard
+ * activation reaches the input without script. Report choices with
+ * `wireFilePickers`.
+ */
+declare function FilePickerTrigger(props: FilePickerTriggerProps): SafeHtml;
+/**
+ * A dashed drop target that also opens the file chooser when clicked. While
+ * files are dragged over it, `wireFilePickers` sets `data-dragging` and Kerf
+ * highlights it; dropped and chosen files are reported the same way.
+ */
+declare function FileDropZone(props: FileDropZoneProps): SafeHtml;
+
+export { FileDropZone, type FileDropZoneProps, FilePickerTrigger, type FilePickerTriggerProps };
+```
+
+## `@kerfjs/ui/corner-status`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/** The viewport corner a CornerStatus occupies, in logical (RTL-aware) terms. */
+type CornerStatusPlacement = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+/** Where a CornerStatus appears: the top layer, or in flow. */
+type CornerStatusPresentation = 'overlay' | 'embedded';
+interface CornerStatusProps {
+    /** The root id: what a `popovertarget` control or `getElementById` names. */
+    id?: string;
+    /** One or more `StateBanner`s, typically `urgency="status"`; they stack. */
+    children: KerfUiContent;
+    /** Viewport corner; defaults to `bottom-end`. */
+    placement?: CornerStatusPlacement;
+    /**
+     * `overlay` (default) is a native `popover="manual"` host in the top layer,
+     * opened by `wireCornerStatus`: above fixed and z-indexed page chrome,
+     * never focused, and with no close button, light dismiss, or Escape.
+     * `embedded` renders the same stack in flow for a catalog or inline use.
+     */
+    presentation?: CornerStatusPresentation;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/**
+ * A non-dismissible status surface pinned to a viewport corner — "Loading…",
+ * "Updating tickets… 3 of 12" — for app-level progress that has no better
+ * home beside the affected work. The application owns its lifetime: render it
+ * while the work runs and remove it when the work ends. It carries no role of
+ * its own; the composed `StateBanner` is the polite live region. Use a toast
+ * for transient, dismissible confirmation instead.
+ */
+declare function CornerStatus({ id, children, placement, presentation, className, slot, }: CornerStatusProps): kerfjs.SafeHtml;
+
+export { CornerStatus, type CornerStatusPlacement, type CornerStatusPresentation, type CornerStatusProps };
+```
+
+## `@kerfjs/ui/edge-activity-indicator`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
+
+interface EdgeActivityIndicatorProps {
+    /** Whether work is in progress; shows the strip and runs its wave. */
+    busy: boolean;
+    /**
+     * Optional status shown in a small pill hanging from the edge while busy.
+     * The pill is a polite live region; omit it for a purely decorative strip.
+     */
+    message?: string;
+    /** Strip and pill color; defaults to `info`. */
+    tone?: SemanticTone;
+    /** Clear the device's top safe area (default) or sit at the very edge. */
+    inset?: 'safe-area' | 'none';
+    className?: string;
+}
+/**
+ * A layout-free activity strip pinned to the top edge of the viewport: a row
+ * of thin bars that ripple in a traveling wave while `busy`, plus an optional
+ * hanging status pill. It allocates no layout, ignores the pointer, and its
+ * bars are hidden from assistive technology; only the pill announces.
+ * Kerf owns the motion: it scales in from the edge and, under reduced motion,
+ * only fades.
+ */
+declare function EdgeActivityIndicator({ busy, message, tone, inset, className, }: EdgeActivityIndicatorProps): kerfjs.SafeHtml;
+
+export { EdgeActivityIndicator, type EdgeActivityIndicatorProps };
+```