@kerfjs/ui 5.0.0-beta.54 → 5.0.0-beta.56

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.54` and `kerfjs@5.0.0-beta.54`. 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.56` and `kerfjs@5.0.0-beta.56`. 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`
 
@@ -48,9 +48,8 @@ type CssColor = CssValue & {
  * a surface. Mint it with {@link uiColor} and a foreground token name
  * ({@link UiForegroundColorName}) or with {@link foregroundColorVar}. It is a
  * {@link CssColor}, but a plain `CssColor` is not a foreground color: fill,
- * border, and surface tokens (including the `success` / `warning` / `danger` /
- * `pop` fill aliases) are pale backgrounds that leave a foreground nearly
- * invisible.
+ * border, and surface tokens are pale backgrounds that leave a foreground
+ * nearly invisible.
  */
 type CssForegroundColor = CssColor & {
     readonly [cssForegroundColorBrand]: 'CssForegroundColor';
@@ -60,16 +59,11 @@ type CssFlexBasis = CssLength | 'auto' | 'content' | 'min-content' | 'max-conten
 type CssSizeKeyword = 'auto' | 'min-content' | 'max-content' | 'fit-content';
 /** A complete width/height value accepted by dimension-valued UI props. */
 type CssSize = CssLength | CssSizeKeyword;
-declare const uiColorNames: readonly ["accent", "accent-text", "border", "border-quiet", "brand-border-loud", "brand-border-normal", "brand-border-quiet", "brand-fill-loud", "brand-fill-normal", "brand-fill-quiet", "brand-on-fill", "brand-on-loud", "brand-on-normal", "brand-on-quiet", "danger", "danger-border-loud", "danger-border-normal", "danger-border-quiet", "danger-fill-loud", "danger-fill-normal", "danger-fill-quiet", "danger-on-fill", "danger-on-loud", "danger-on-normal", "danger-on-quiet", "danger-text", "neutral-border-loud", "neutral-border-normal", "neutral-border-quiet", "neutral-fill-loud", "neutral-fill-normal", "neutral-fill-quiet", "neutral-on-loud", "neutral-on-normal", "neutral-on-quiet", "pop", "pop-border-loud", "pop-border-normal", "pop-border-quiet", "pop-fill-loud", "pop-fill-normal", "pop-fill-quiet", "pop-on-fill", "pop-on-loud", "pop-on-normal", "pop-on-quiet", "pop-text", "success", "success-border-loud", "success-border-normal", "success-border-quiet", "success-fill-loud", "success-fill-normal", "success-fill-quiet", "success-on-fill", "success-on-loud", "success-on-normal", "success-on-quiet", "success-text", "surface", "surface-lowered", "surface-raised", "text", "text-link", "text-quiet", "warning", "warning-border-loud", "warning-border-normal", "warning-border-quiet", "warning-fill-loud", "warning-fill-normal", "warning-fill-quiet", "warning-on-fill", "warning-on-loud", "warning-on-normal", "warning-on-quiet", "warning-text"];
+declare const uiColorNames: readonly ["brand-border-loud", "brand-border-normal", "brand-border-quiet", "brand-fill-loud", "brand-fill-normal", "brand-fill-quiet", "brand-on-fill", "brand-on-loud", "brand-on-normal", "brand-on-quiet", "danger-border-loud", "danger-border-normal", "danger-border-quiet", "danger-fill-loud", "danger-fill-normal", "danger-fill-quiet", "danger-on-fill", "danger-on-loud", "danger-on-normal", "danger-on-quiet", "neutral-border-loud", "neutral-border-normal", "neutral-border-quiet", "neutral-fill-loud", "neutral-fill-normal", "neutral-fill-quiet", "neutral-on-loud", "neutral-on-normal", "neutral-on-quiet", "pop-border-loud", "pop-border-normal", "pop-border-quiet", "pop-fill-loud", "pop-fill-normal", "pop-fill-quiet", "pop-on-fill", "pop-on-loud", "pop-on-normal", "pop-on-quiet", "success-border-loud", "success-border-normal", "success-border-quiet", "success-fill-loud", "success-fill-normal", "success-fill-quiet", "success-on-fill", "success-on-loud", "success-on-normal", "success-on-quiet", "surface", "surface-lowered", "surface-raised", "text", "text-link", "text-quiet", "warning-border-loud", "warning-border-normal", "warning-border-quiet", "warning-fill-loud", "warning-fill-normal", "warning-fill-quiet", "warning-on-fill", "warning-on-loud", "warning-on-normal", "warning-on-quiet"];
 /** Names of the public `--kui-color-*` semantic tokens. */
 type UiColorName = (typeof uiColorNames)[number];
-/**
- * The semantic tokens that paint a foreground: the `*-on-*` roles, the text
- * roles, and their `*-text` compatibility aliases. The bare `success`,
- * `warning`, `danger`, `pop`, and `accent` aliases are quiet fills, not
- * foregrounds.
- */
-type UiForegroundColorName = Extract<UiColorName, `${string}-on-${string}` | `${string}-text` | 'text' | 'text-quiet' | 'text-link'>;
+/** The semantic tokens that paint a foreground: the `*-on-*` and text roles. */
+type UiForegroundColorName = Extract<UiColorName, `${string}-on-${string}` | 'text' | 'text-quiet' | 'text-link'>;
 /** Kerf UI's complete spacing-token vocabulary. `s` and `xl` are exceptions. */
 type UiSpaceName = 'none' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl';
 /** Create a complete pixel length. */
@@ -124,6 +118,7 @@ export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, ty
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { CssLength } from './css-values.js';
 
 type DisclosureDirection = 'up' | 'down' | 'left' | 'right';
 interface DisclosureArrowProps {
@@ -132,11 +127,13 @@ interface DisclosureArrowProps {
     closedDirection?: DisclosureDirection;
     /** Replacement icons should use right as their unrotated orientation. */
     icon?: SafeHtml;
+    /** Typed box size for the square visual. Default: `remify(18px)`. */
+    size?: CssLength;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function DisclosureArrow({ open, openDirection, closedDirection, icon, className, slot, }: DisclosureArrowProps): SafeHtml;
+declare function DisclosureArrow({ open, openDirection, closedDirection, icon, size, className, slot, }: DisclosureArrowProps): SafeHtml;
 
 export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 ```
@@ -145,9 +142,9 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { D as DividerSides } from './divider-sides-BzB6rphT.js';
 import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 interface ToolbarProps {
     leading?: KerfUiContent;
@@ -155,13 +152,15 @@ interface ToolbarProps {
     trailing?: KerfUiContent;
     label?: string;
     /** Physical divider edges in canonical top/right/bottom/left order. Defaults to bottom. */
-    dividerSides?: DividerSides;
+    dividerSides?: Sides;
     /** Horizontal treatment of the center zone. Defaults to centered content. */
     centerAlign?: 'center' | 'stretch';
     /**
      * Component-owned responsive layout; applications choose the policy rather
      * than restyling toolbar internals. Under every policy the trailing zone
-     * wraps its groups instead of clipping an action.
+     * wraps its groups instead of clipping an action, and the center zone keeps
+     * its whole content width: when the zones do not fit one row, the leading
+     * title truncates with an ellipsis rather than the center overlapping it.
      * - `none` keeps one row; the leading identity truncates first.
      * - `stack` stacks the zones at `responsiveAt`, wrapping stacked control
      *   groups onto further rows.
@@ -186,9 +185,15 @@ interface ToolbarProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+/**
+ * A toolbar's configuration, apart from its content: the props a composite
+ * 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, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { DividerSides, Toolbar, type ToolbarProps };
+export { Sides, Toolbar, type ToolbarConfig, type ToolbarProps };
 ```
 
 ## `@kerfjs/ui/toolbar-text`
@@ -316,6 +321,7 @@ export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, ty
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssLength } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 /** Where a {@link FloatingToolbar} floats within its positioned container. */
@@ -330,6 +336,13 @@ interface FloatingToolbarProps {
      * Default: `'bottom-end'`.
      */
     position?: FloatingToolbarPosition;
+    /**
+     * Distance from the container edges named by `position`. Default:
+     * `space('m')` (16px, 8px past a top toolbar's own inset). Omit it inside a
+     * `Workbench`, `CollapsiblePanel`, or `ResizableRegion` restore corner: the
+     * corner owns the inset there and sets it to zero.
+     */
+    inset?: CssLength;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -339,22 +352,102 @@ interface FloatingToolbarProps {
  * ancestor — a transparent, forced-dark cluster of controls (e.g. a drawer
  * restore button) that sits over the content but NOT over dialogs or overlays
  * (it is not in the top layer). It is inset from the container edges by
- * `--kui-floating-toolbar-inset` (default `--kui-space-m`, i.e. 8px more than a
- * top toolbar's own inset); override that token, on the toolbar or an
- * ancestor, to move it. Inside a `Workbench`, `CollapsiblePanel`, or
+ * `inset` (default `--kui-space-m`, i.e. 8px more than a top toolbar's own
+ * inset); pass a typed length to move it. Inside a `Workbench`, `CollapsiblePanel`, or
  * `ResizableRegion` restore corner the corner owns the inset, so the toolbar
- * floats from the corner's own position. The app owns the controls and their
- * behavior — wire them with `delegate()` as usual.
+ * floats from the corner's own position. While one of those layouts has a
+ * side overlay open over the toolbar's region (a Workbench rail overlay, a
+ * `wireSidebar` compact overlay, an overlay `CollapsiblePanel` or horizontal
+ * `ResizableRegion`), the toolbar is hidden — unfocusable and out of the
+ * accessibility tree — until the overlay closes. The app owns the controls
+ * and their behavior — wire them with `delegate()` as usual.
  */
-declare function FloatingToolbar({ children, label, position, className, slot, }: FloatingToolbarProps): kerfjs.SafeHtml;
+declare function FloatingToolbar({ children, label, position, inset, className, slot, }: FloatingToolbarProps): kerfjs.SafeHtml;
 
 export { FloatingToolbar, type FloatingToolbarPosition, type FloatingToolbarProps };
 ```
 
+## `@kerfjs/ui/popup-menu`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+type PopupMenuPlacement = 'bottom-start' | 'bottom' | 'bottom-end' | 'top-start' | 'top' | 'top-end';
+type PopupMenuDataAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-action'?: never;
+    'data-component'?: never;
+    'data-key'?: never;
+    'data-morph-skip-children'?: never;
+}>;
+/** One command in the menu. */
+interface PopupMenuItem {
+    kind?: 'item';
+    label: string;
+    /** Delegated `data-action` the app handles when the item is chosen. */
+    action?: string;
+    /** Native `wa-dropdown-item` value, reported by its `wa-select` event. */
+    value?: string;
+    /** Leading icon, typically a `LucideIcon`; it is placed in the item's icon slot. */
+    icon?: SafeHtml;
+    disabled?: boolean;
+    /** Application `data-*` metadata such as a record id. */
+    attributes?: PopupMenuDataAttributes;
+}
+/** A labeled group heading; items that follow it belong to the group. */
+interface PopupMenuHeading {
+    kind: 'heading';
+    label: string;
+}
+/** A separator between groups of items. */
+interface PopupMenuDivider {
+    kind: 'divider';
+}
+type PopupMenuEntry = PopupMenuItem | PopupMenuHeading | PopupMenuDivider;
+type PopupMenuTriggerName = {
+    /** Visible trigger text, which is also its accessible name. */
+    text: string;
+    label?: never;
+} | {
+    text?: never;
+    /**
+     * Accessible name of an icon-only trigger, rendered as visually hidden
+     * slotted text (a Web Awesome button takes its name from its content).
+     */
+    label: string;
+};
+type PopupMenuProps = PopupMenuTriggerName & {
+    /** Trigger icon, typically a `LucideIcon`, before any visible text. */
+    icon?: KerfUiContent;
+    items: readonly PopupMenuEntry[];
+    /** Where the menu opens relative to its trigger. Defaults to `bottom-start`. */
+    placement?: PopupMenuPlacement;
+    /** Show the disclosure caret after the trigger content. Defaults to true. */
+    caret?: boolean;
+    disabled?: boolean;
+    /** Application `data-*` metadata on the menu root. */
+    rootAttributes?: PopupMenuDataAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+};
+/**
+ * An action menu: a trigger button that opens a list of commands. Renders the
+ * `wa-dropdown` root directly, so a `single` `ToolbarControlGroup` (with
+ * `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.
+ */
+declare function PopupMenu({ text, label, icon, items, placement, caret, disabled, rootAttributes, slot, }: PopupMenuProps): SafeHtml;
+
+export { PopupMenu, type PopupMenuDivider, type PopupMenuEntry, type PopupMenuHeading, type PopupMenuItem, type PopupMenuPlacement, type PopupMenuProps };
+```
+
 ## `@kerfjs/ui/list-header`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { HeadingLevel } from './toolbar-text.js';
 
 type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -395,6 +488,8 @@ interface ListHeaderBaseProps {
 type ListHeaderModeProps = {
     /** Render the title as a controlled disclosure trigger. */
     toggle: true;
+    /** A toggle's label is its button text, not a heading. */
+    headingLevel?: never;
     action: string;
     expanded: boolean;
     actionIcon?: SafeHtml;
@@ -404,6 +499,11 @@ type ListHeaderModeProps = {
 } | {
     /** Render a separately named trailing action. */
     toggle?: false;
+    /**
+     * Native heading level (`h1`–`h6`) of the label. Default `2`. Match the
+     * document outline; the visual treatment does not change.
+     */
+    headingLevel?: HeadingLevel;
     action: string;
     actionLabel: string;
     actionIcon: SafeHtml;
@@ -413,6 +513,11 @@ type ListHeaderModeProps = {
 } | {
     /** Render a passive section heading. */
     toggle?: false;
+    /**
+     * Native heading level (`h1`–`h6`) of the label. Default `2`. Match the
+     * document outline; the visual treatment does not change.
+     */
+    headingLevel?: HeadingLevel;
     action?: never;
     actionLabel?: never;
     actionIcon?: never;
@@ -437,7 +542,7 @@ type ListHeaderIndicatorProps = {
     status?: SafeHtml;
 };
 type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps & ListHeaderModeProps;
-declare function ListHeader({ label, count, countLabel, badge, status, density, divider, inline, width, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, slot, }: ListHeaderProps): SafeHtml;
+declare function ListHeader({ label, headingLevel, count, countLabel, badge, status, density, divider, inline, width, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, slot, }: ListHeaderProps): SafeHtml;
 
 export { ListHeader, type ListHeaderProps };
 ```
@@ -447,10 +552,10 @@ export { ListHeader, type ListHeaderProps };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
-import { D as DividerSides, S as Sides } from './divider-sides-BzB6rphT.js';
 import { H as HorizontalAlignment, L as ListVerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 export { V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -482,7 +587,7 @@ interface ListProps {
     /** Own vertical scrolling and overscroll containment. */
     scrollable?: boolean;
     /** Physical divider edges in canonical top/right/bottom/left order. */
-    dividerSides?: DividerSides;
+    dividerSides?: Sides;
     /** 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. */
@@ -493,10 +598,17 @@ interface ListProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+/**
+ * A list's configuration, apart from its content and styling hooks: the props a
+ * composite that renders a `List` for the app (the Workbench's `mainHeader` /
+ * `mainFooter` chrome) forwards, so the app configures that list instead of
+ * styling it. An omitted or `undefined` field keeps the composite's default.
+ */
+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, gap, flex, fill, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, DividerSides, HorizontalAlignment, List, type ListProps, ListVerticalAlignment, Sides, UiSpaceName };
+export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, List, type ListConfig, type ListProps, ListVerticalAlignment, Sides, UiSpaceName };
 ```
 
 ## `@kerfjs/ui/list-action-row`
@@ -626,8 +738,8 @@ export { ListItem, type ListItemProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 interface ListInsetControlProps {
     /** Control(s) that own their own border and padding (e.g. an input, a `wa-*`). */
@@ -653,22 +765,21 @@ export { ListInsetControl, type ListInsetControlProps, Sides };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
+type ListInsetTextRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-sides'?: never;
+}>;
 interface ListInsetTextProps {
     /** Text (or inline content) that carries no margin, border, or padding of its own. */
     children: KerfUiContent | string;
     /** Physical inset sides in canonical top/right/bottom/left order. Defaults to all sides. */
     sides?: Sides;
-    /**
-     * @deprecated Pass `sides="rl"` instead. Keep only the horizontal geometry (inline margin, left/right border, and
-     * left/right padding) and drop the vertical margin, border, and padding. Use it
-     * when the text edge must still align with bordered items but the line should not
-     * add its own vertical box space — tight text layout inside a content region.
-     */
-    horizontalOnly?: boolean;
     className?: string;
+    /** Safe `data-*` metadata; component-owned structural attributes stay protected. */
+    rootAttributes?: ListInsetTextRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
@@ -677,14 +788,65 @@ interface ListInsetTextProps {
  * transparent border, and 8px padding — so a plain string lines up with
  * bordered `.kui-content` items (its text edge lands at the same 17px inset).
  * Use it for text elements that have no margin, border, or padding of their own.
- * Pass `horizontalOnly` to keep the horizontal inset but drop the vertical box
+ * Pass `sides="rl"` to keep the horizontal inset but drop the vertical box
  * space for tight text layout.
  */
-declare function ListInsetText({ children, sides, horizontalOnly, className, slot, }: ListInsetTextProps): kerfjs.SafeHtml;
+declare function ListInsetText({ children, sides, className, rootAttributes, slot, }: ListInsetTextProps): kerfjs.SafeHtml;
 
 export { ListInsetText, type ListInsetTextProps, Sides };
 ```
 
+## `@kerfjs/ui/content-item`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/** 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. */
+type ContentItemShape = 'rounded' | 'pill';
+type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+}>;
+interface ContentItemProps {
+    /** Item content; a plain string is allowed for bare copy. */
+    children?: KerfUiContent | string;
+    /**
+     * `framed` paints the standard neutral border in the 1px the item always
+     * reserves, so framing never changes geometry. Frame only an item that
+     * marks a real distinction. Defaults to `none` (transparent border).
+     */
+    frame?: ContentItemFrame;
+    /** Corner shape. Defaults to `rounded`. */
+    shape?: ContentItemShape;
+    /**
+     * Names the item as a distinct region (`role="region"`). Omit it for an
+     * ordinary item, which stays a non-landmark grouping.
+     */
+    ariaLabel?: string;
+    /**
+     * Makes the item a programmatic focus target (`tabindex="-1"`, never a tab
+     * stop), for example the preferred initial focus of a NavStack view when
+     * combined with `data-nav-focus` in `rootAttributes`.
+     */
+    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;
+}
+/**
+ * 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;
+
+export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemShape };
+```
+
 ## `@kerfjs/ui/value-table`
 
 ```ts
@@ -861,6 +1023,10 @@ export { TabActivation, type TabDropPosition, type TabReorder, type TabReorderSo
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { ToolbarConfig } from './toolbar.js';
+import { ToolbarTextSize, HeadingLevel } from './toolbar-text.js';
+import './pane.js';
+import './sides-BPSWde0A.js';
 
 /**
  * One entry in a {@link NavStack}. The app owns the stack as an array (usually a
@@ -872,19 +1038,46 @@ interface NavStackView {
     content: KerfUiContent;
     /** Title shown in the top toolbar for this view. */
     title?: string;
+    /** Leading groups for this view's top toolbar, after the back control and before the title. */
+    leading?: KerfUiContent;
+    /** Center content for this view's top toolbar (placed per `toolbarConfig.centerAlign`). */
+    center?: KerfUiContent;
     /** Trailing actions for this view's top toolbar. */
     toolbar?: KerfUiContent;
     /** Bottom toolbar for this view. Cross-fades with the top chrome on navigation. */
     bottomToolbar?: KerfUiContent;
 }
+/**
+ * The top toolbar's configuration. Its `ToolbarConfig` forwards to the real
+ * `Toolbar` the stack renders; by default that toolbar draws no divider and
+ * claims the top and side safe-area edges the stack still touches.
+ */
+interface NavStackToolbarConfig extends ToolbarConfig {
+    /** Accessible name of the top toolbar (default: none). */
+    label?: string;
+    /** Size of the view title's `ToolbarText` (default `large`). */
+    titleSize?: ToolbarTextSize;
+    /** Expose the view title as a heading at this level (default: a plain span). */
+    headingLevel?: HeadingLevel;
+}
 interface NavStackProps {
     id: string;
     /** Accessible name for the stack region. */
     label: string;
     /** The stack, root first; the last entry is the active top view. */
     views: NavStackView[];
-    /** Accessible label for the back control (default "Back"). */
+    /** Accessible label for the icon-only back control (default "Back"). */
     backLabel?: string;
+    /** The back control's icon (default a chevron-left `LucideIcon`). */
+    backIcon?: KerfUiContent;
+    /**
+     * Visible text beside the back icon, such as the previous view's title
+     * (default: icon only). When set, the text names the control and
+     * `backLabel` is not used.
+     */
+    backText?: string;
+    /** The top toolbar's configuration, forwarded to its `Toolbar`. */
+    toolbarConfig?: NavStackToolbarConfig;
     /** Hide the top toolbar entirely (rare — a fully custom-chrome view). */
     hideToolbar?: boolean;
     /** Optional persistent bottom toolbar used when the active view does not provide one. */
@@ -896,12 +1089,14 @@ interface NavStackProps {
 /**
  * A navigation stack (iOS-style push/pop). Renders every entry stacked, the last
  * one active; `@kerfjs/ui/wire-nav-stack`'s `wireNavStack` slides the content and
- * cross-fades the chrome across a change. A single-pane layout is a `NavStack`
- * with one entry. See `docs/23-app-layouts.md` §3.1.
+ * cross-fades the chrome across a change. Its top chrome is a real `Toolbar`: the
+ * back control and title lead, the active view's `leading` / `center` / `toolbar`
+ * content fills the zones, and `toolbarConfig` configures it. A single-pane
+ * layout is a `NavStack` with one entry. See `docs/23-app-layouts.md` §3.1.
  */
-declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className, slot, }: NavStackProps): kerfjs.SafeHtml;
+declare function NavStack({ id, label, views, backLabel, backIcon, backText, toolbarConfig, hideToolbar, bottomToolbar, className, slot, }: NavStackProps): kerfjs.SafeHtml;
 
-export { NavStack, type NavStackProps, type NavStackView };
+export { NavStack, type NavStackProps, type NavStackToolbarConfig, type NavStackView };
 ```
 
 ## `@kerfjs/ui/wire-nav-stack`
@@ -931,13 +1126,39 @@ export { type WireNavStackOptions, wireNavStack };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { NavStackProps, NavStackView } from './nav-stack.js';
+import { ResizableRegionProps } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './toolbar.js';
+import './pane.js';
+import './sides-BPSWde0A.js';
+import './toolbar-text.js';
 
-interface SplitViewResizable {
+/**
+ * The roomy list pane's `ResizableRegion`: its committed `size` and `min` /
+ * `max` limits, plus the region configuration that forwards unchanged
+ * (`separator`, `handleIcon`, `contentOverflow`, and collapse:
+ * `collapsed`, `transitioning`, `collapseMotion`, `restoreControl`,
+ * `restorePosition`). Omitted options keep the region's defaults.
+ */
+interface SplitViewResizable extends Pick<ResizableRegionProps, 'separator' | 'handleIcon' | 'contentOverflow' | 'collapsed' | 'transitioning' | 'collapseMotion' | 'restoreControl' | 'restorePosition'> {
     size: number;
     min: number;
     max: number;
 }
+/** One compact view's top- and bottom-toolbar content (see `NavStackView`). */
+type SplitViewCompactViewToolbars = Pick<NavStackView, 'leading' | 'center' | 'toolbar' | 'bottomToolbar'>;
+/**
+ * The compact `NavStack`'s configuration: its toolbar configuration, back
+ * control, and persistent bottom toolbar forward to the stack, and `list` /
+ * `detail` give each view its own toolbar groups.
+ */
+interface SplitViewCompactStack extends Pick<NavStackProps, 'toolbarConfig' | 'backIcon' | 'backText' | 'hideToolbar' | 'bottomToolbar'> {
+    /** Toolbar content for the list (root) view. */
+    list?: SplitViewCompactViewToolbars;
+    /** Toolbar content for the pushed detail view. */
+    detail?: SplitViewCompactViewToolbars;
+}
 interface SplitViewProps {
     id: string;
     label: string;
@@ -959,6 +1180,8 @@ interface SplitViewProps {
     detailTitle?: string;
     /** Back label for the compact NavStack (default "Back"). */
     backLabel?: string;
+    /** Compact NavStack configuration and per-view toolbars. */
+    compactStack?: SplitViewCompactStack;
     /** A resizable separator on roomy classes (min/max px). Omit for a fixed split. */
     resizable?: SplitViewResizable;
     className?: string;
@@ -972,9 +1195,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, resizable, className, slot, }: SplitViewProps): kerfjs.SafeHtml;
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, compactStack, resizable, className, slot, }: SplitViewProps): kerfjs.SafeHtml;
 
-export { SplitView, type SplitViewProps, type SplitViewResizable };
+export { SplitView, type SplitViewCompactStack, type SplitViewCompactViewToolbars, type SplitViewProps, type SplitViewResizable };
 ```
 
 ## `@kerfjs/ui/pane`
@@ -1002,7 +1225,10 @@ type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-safe-area-block-end'?: never;
     'data-safe-area-inline-start'?: never;
     'data-safe-area-inline-end'?: never;
+    'data-chrome-placement'?: never;
 }>;
+/** How a Pane's header and footer relate to its scrolling content. */
+type PaneChromePlacement = 'fixed' | 'auto';
 interface PaneProps {
     /** Optional fixed chrome above the scrolling content, arranged vertically. */
     header?: KerfUiContent;
@@ -1010,6 +1236,14 @@ interface PaneProps {
     children?: KerfUiContent;
     /** Optional fixed chrome below the scrolling content. */
     footer?: KerfUiContent;
+    /**
+     * Whether the header and footer stay pinned around the scrolling content.
+     * `fixed` (default) always pins them. `auto` pins them while the pane is
+     * tall enough, and below 480px of height (30rem, so it scales with the text
+     * size) lets the whole pane scroll as one column, so tall chrome can never
+     * squeeze the content to nothing.
+     */
+    chromePlacement?: PaneChromePlacement;
     /** Root semantics. Defaults to `div`. */
     element?: PaneElement;
     /** Scrolling content semantics. Defaults to `div`. */
@@ -1038,30 +1272,101 @@ interface PaneProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+/**
+ * A pane's configuration, apart from its content and styling hooks: the props a
+ * composite that renders a `Pane` for the app (a Workbench panel or work area,
+ * or a CollapsiblePanel) forwards, so the app configures that pane instead of
+ * styling it. An omitted or `undefined` field keeps the composite's default.
+ */
+type PaneConfig = Pick<PaneProps, 'contentElement' | 'contentLabel' | 'separators' | 'safeAreaEdges'>;
 /**
  * An unpadded application column with optional fixed header/footer slots and one
  * scrolling vertical content owner. Separator lines are independently opt-in on
  * each logical edge, so the same component works as a sidebar, main area,
  * inspector, or dialog column.
  */
-declare function Pane({ header, children, footer, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
+declare function Pane({ header, children, footer, chromePlacement, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
 
-export { Pane, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
+export { Pane, type PaneChromePlacement, type PaneConfig, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
 ```
 
 ## `@kerfjs/ui/workbench`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+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-C8sF-YZC.js';
+import { ToolbarConfig } from './toolbar.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './sides-BPSWde0A.js';
+import './lucide-icon.js';
+import 'lucide';
+
+/** The standard toggle a Workbench renders for a panel (see {@link PanelToggle}). */
+type WorkbenchPanelToggle = PanelToggle;
+/**
+ * A Workbench panel's top toolbar, composed by the Workbench so its groups can
+ * follow the panel's open state (see {@link PanelToolbar} for the roles).
+ * A collapsed rail's `constant` groups and toggle go to the leading edge of
+ * `mainToolbar` (left rail) or its trailing edge (right rail); a collapsed
+ * drawer's go to the trailing edge of `mainBottomToolbar`, else to a
+ * `FloatingToolbar` in the work area's bottom-end corner.
+ */
+type WorkbenchPanelToolbar = PanelToolbar;
+/**
+ * The work area's top toolbar; collapsed rails add their groups to it. Its
+ * configuration forwards to its `Toolbar`. By default it draws the divider
+ * under the work area's header chrome: its own bottom edge, or none when a
+ * `mainHeader` follows (which then carries the divider).
+ */
+interface WorkbenchMainToolbar extends ToolbarConfig {
+    label: string;
+    /** The work area's title, usually an extra-large `ToolbarText`. */
+    title?: KerfUiContent;
+    /** Groups after the title. */
+    leading?: KerfUiContent;
+    center?: KerfUiContent;
+    /** Groups at the trailing edge, before a collapsed right rail's groups. */
+    trailing?: KerfUiContent;
+}
+/**
+ * The work area's bottom toolbar; a collapsed drawer adds its groups to it.
+ * Its configuration forwards to its `Toolbar`. By default it draws the divider
+ * over the work area's footer chrome: its own top edge, or none when a
+ * `mainFooter` precedes it.
+ */
+interface WorkbenchMainBottomToolbar extends ToolbarConfig {
+    label: string;
+    leading?: KerfUiContent;
+    center?: KerfUiContent;
+    trailing?: KerfUiContent;
+}
+/**
+ * Whether the work area's header or footer chrome stays pinned (`fixed`),
+ * scrolls away with the content (`scroll`), or stays pinned while the work
+ * area is tall enough and scrolls with the content when it is short (`auto`,
+ * the Pane's `chromePlacement="auto"`; it applies to the pinned header and
+ * footer together).
+ */
+type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
 
 /**
  * The Workbench container breakpoint below which a panel presents as an
  * overlay: `narrow` (704px or less) or `compact` (448px or less) — the same
- * breakpoints as `ResizableRegion`'s `responsiveFillAt`.
+ * breakpoints as `ResizableRegion`'s `responsiveFillAt` — or `never` to keep
+ * it inline at every width.
  */
-type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow';
+type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never';
+/**
+ * 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
+ * edge, so a press beside it closes it; `full` fills the Workbench.
+ */
+type WorkbenchCompactOverlay = 'inset' | 'full';
 /** Drag-resize limits for a resizable Workbench panel, in px. */
 interface WorkbenchPanelResizable {
     /** Smallest size (default 180 for a rail, 120 for the drawer). */
@@ -1072,6 +1377,22 @@ interface WorkbenchPanelResizable {
 /** A collapsible Workbench panel — a side rail or the bottom drawer. */
 interface WorkbenchPanel {
     content: KerfUiContent;
+    /**
+     * The panel's top toolbar, composed by the Workbench: its `constant` groups
+     * and standard `toggle` move to the work area's toolbar while the panel is
+     * collapsed. With it, `content` renders in a `Pane` below the toolbar.
+     */
+    toolbar?: WorkbenchPanelToolbar;
+    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    footer?: KerfUiContent;
+    /**
+     * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`) — for example
+     * `{ contentElement: 'nav', contentLabel: 'Sections' }` for a navigation
+     * rail. Omitted or `undefined` fields keep the `Pane` defaults. Ignored
+     * without a `toolbar`, where `content` renders as given.
+     */
+    pane?: PaneConfig;
     /** Whether the panel is currently collapsed (the app owns this). */
     collapsed?: boolean;
     /**
@@ -1097,13 +1418,22 @@ interface WorkbenchPanel {
      * 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
-     * height; the bottom drawer overlays the bottom of the work-area column.
+     * 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.
      */
     responsiveOverlayAt?: WorkbenchResponsiveOverlayAt;
+    /**
+     * A rail's overlay width in a compact Workbench (default `inset`: the
+     * Workbench less `--kui-workbench-overlay-dismiss-margin`, 44px). Ignored
+     * by the drawer.
+     */
+    compactOverlay?: WorkbenchCompactOverlay;
     /**
      * Control shown while collapsed, in a safe-area-aware corner of the
      * Workbench (not the viewport); the bottom drawer's sits in the work-area
-     * column.
+     * column. Prefer `toolbar.toggle`, which the Workbench relocates into the
+     * work area's toolbar (or this corner when that toolbar is absent).
      */
     restoreControl?: SafeHtml;
     restorePosition?: ResizableRegionRestorePosition;
@@ -1118,6 +1448,55 @@ interface WorkbenchProps {
     label: string;
     /** The central work area. */
     main: KerfUiContent;
+    /**
+     * The work area's top toolbar. A collapsed left rail's `constant` groups
+     * and toggle lead it; a collapsed right rail's trail it. With it, `main`
+     * renders in a `Pane` below the toolbar.
+     */
+    mainToolbar?: WorkbenchMainToolbar;
+    /**
+     * Fixed content under `mainToolbar` — supporting copy such as a
+     * description — divided from the scrolling `main` below it.
+     */
+    mainHeader?: KerfUiContent;
+    /**
+     * Fixed content over `mainBottomToolbar` — a status line or a resource
+     * toolbar — divided from the scrolling `main` above it.
+     */
+    mainFooter?: KerfUiContent;
+    /**
+     * The work area's bottom toolbar. A collapsed drawer's `constant` groups and
+     * toggle trail it; without it they float in the work area's corner.
+     */
+    mainBottomToolbar?: WorkbenchMainBottomToolbar;
+    /**
+     * Whether `mainToolbar` and `mainHeader` stay pinned (`fixed`, default),
+     * scroll away with `main` (`scroll`) — useful where large text would leave
+     * pinned chrome little room — or stay pinned while the work area is tall
+     * enough and scroll with `main` when it is short (`auto`).
+     */
+    mainHeaderPlacement?: WorkbenchChromePlacement;
+    /** The same for `mainFooter` and `mainBottomToolbar` (default `fixed`). */
+    mainFooterPlacement?: WorkbenchChromePlacement;
+    /**
+     * Configuration for the work area's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`), which it has whenever it
+     * has a toolbar, `mainHeader`, or `mainFooter`; without that chrome, `main`
+     * renders as given and this is ignored. Omitted or `undefined` fields keep
+     * the `Pane` defaults.
+     */
+    mainPane?: PaneConfig;
+    /**
+     * Configuration for the `List` that holds `mainHeader` (`gap`, `hAlign`,
+     * `vAlign`, `dividerSides`, `textInsets`, `controlInsets`). Omitted or
+     * `undefined` fields keep the defaults, including its bottom divider.
+     */
+    mainHeaderList?: ListConfig;
+    /**
+     * The same for the `List` that holds `mainFooter`; by default it draws a
+     * top divider, or none when a `mainBottomToolbar` follows it.
+     */
+    mainFooterList?: ListConfig;
     leftRail?: WorkbenchPanel;
     rightRail?: WorkbenchPanel;
     bottomDrawer?: WorkbenchPanel;
@@ -1154,9 +1533,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, 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, className, slot, }: WorkbenchProps): SafeHtml;
 
-export { Workbench, type WorkbenchPanel, type WorkbenchPanelResizable, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
+export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
 ```
 
 ## `@kerfjs/ui/wire-workbench`
@@ -1277,24 +1656,27 @@ export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanel
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { LucideIcon } from './lucide-icon.js';
+import { PaneConfig } from './pane.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelToggle } from './panel-toolbar-C8sF-YZC.js';
+export { c as collapsiblePanelToggleIcon } from './panel-toolbar-C8sF-YZC.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './lucide-icon.js';
 import 'lucide';
+import './toolbar.js';
+import './sides-BPSWde0A.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
-type CollapsiblePanelSide = 'left' | 'right' | 'bottom';
+type CollapsiblePanelSide = PanelSide;
+/** The standard toggle a panel toolbar renders (see {@link CollapsiblePanelToolbar}). */
+type CollapsiblePanelToolbarToggle = PanelToggle;
 /**
- * The standard collapse/expand icon for a panel `side` and `collapsed` state,
- * so every app's sidebars and drawers use one recognizable convention:
- * `PanelLeft*` for a left rail, `PanelRight*` for a right rail, `PanelBottom*`
- * for a bottom drawer — the `Close` glyph while open, the `Open` glyph while
- * collapsed. Exposed so an app can render its own toggle affordance.
+ * A panel's composed top toolbar. `title` and `panelOnly` groups lead it and
+ * are available only while the panel is open; `constant` groups and the
+ * standard `toggle` trail it while open and move to the app's work-area
+ * toolbar — through {@link CollapsiblePanelRelocated} — while it is collapsed.
  */
-declare function collapsiblePanelToggleIcon(side: CollapsiblePanelSide, collapsed: boolean): {
-    icon: Parameters<typeof LucideIcon>[0]['icon'];
-    name: string;
-};
+type CollapsiblePanelToolbar = PanelToolbar;
 interface CollapsiblePanelToggleProps {
     /** The panel this toggle controls. */
     side: CollapsiblePanelSide;
@@ -1331,6 +1713,23 @@ interface CollapsiblePanelProps {
     label?: string;
     /** Panel content. */
     children?: KerfUiContent;
+    /**
+     * The panel's top toolbar, composed so its groups follow the panel's open
+     * state. With it, `children` renders in a `Pane` below the toolbar; render
+     * {@link CollapsiblePanelRelocated} in the app's work-area toolbar so the
+     * `constant` groups and toggle stay reachable while the panel is collapsed.
+     */
+    toolbar?: CollapsiblePanelToolbar;
+    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    footer?: KerfUiContent;
+    /**
+     * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`) — for example
+     * `{ contentElement: 'nav', contentLabel: 'Sections' }` for a navigation
+     * rail. Omitted or `undefined` fields keep the `Pane` defaults. Ignored
+     * without a `toolbar`, where `children` renders as given.
+     */
+    pane?: PaneConfig;
     separator?: ResizableRegionSeparator;
     collapseMotion?: ResizableRegionCollapseMotion;
     contentOverflow?: ResizableRegionContentOverflow;
@@ -1356,9 +1755,27 @@ 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, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
+declare function CollapsiblePanel({ id, side, collapsed, size, label, children, toolbar, footer, pane, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
+interface CollapsiblePanelRelocatedProps {
+    /** The panel's `id`. */
+    panelId: string;
+    side: CollapsiblePanelSide;
+    /** The panel's current collapsed state. */
+    collapsed: boolean;
+    /** The same `toolbar` the panel receives. */
+    toolbar: CollapsiblePanelToolbar;
+}
+/**
+ * A collapsed {@link CollapsiblePanel}'s `constant` groups and standard
+ * toggle, for the app's work-area toolbar — nothing while the panel is open.
+ * Put it first in the leading zone for a left rail, last in the trailing zone
+ * for a right rail, and last in a bottom toolbar (or a `FloatingToolbar`
+ * `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;
 
-export { CollapsiblePanel, type CollapsiblePanelProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, collapsiblePanelToggleIcon };
+export { CollapsiblePanel, type CollapsiblePanelProps, CollapsiblePanelRelocated, type CollapsiblePanelRelocatedProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, type CollapsiblePanelToolbar, type CollapsiblePanelToolbarToggle };
 ```
 
 ## `@kerfjs/ui/wire-sidebar`
@@ -1435,7 +1852,7 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-interface TabScaffoldTab<Id extends string = string> {
+interface TabScaffoldTabBase<Id extends string> {
     id: Id;
     label: string;
     /** Decorative icon shown above the label in the bottom bar. */
@@ -1443,6 +1860,40 @@ interface TabScaffoldTab<Id extends string = string> {
     /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */
     content: KerfUiContent;
 }
+/** A tab with an optional count or short-status badge. */
+interface TabScaffoldTabCountBadge {
+    /**
+     * Optional count or short status shown as a solid danger `Badge` at the
+     * top-trailing corner of the tab icon (the iOS tab-bar badge). Omitted, `''`,
+     * or non-finite numbers render no badge. The visual badge is `aria-hidden`;
+     * its meaning reaches assistive technology through `badgeLabel`.
+     *
+     * Pass `true` instead for the text-free dot (new content without a count).
+     */
+    badge?: string | number;
+    /**
+     * Localized phrase folded into the tab's accessible name as
+     * `"<label>, <badgeLabel>"` (for example `"3 unread"` → `"Inbox, 3 unread"`).
+     * Defaults to the badge text itself. Ignored when no badge renders.
+     */
+    badgeLabel?: string;
+}
+/** A tab with the text-free dot badge (new content without a count). */
+interface TabScaffoldTabDotBadge {
+    /**
+     * `true` shows a solid danger dot `Badge` at the top-trailing corner of the
+     * tab icon — the iOS tab-bar dot for new content without a count.
+     */
+    badge: true;
+    /**
+     * Required localized phrase folded into the tab's accessible name as
+     * `"<label>, <badgeLabel>"` (for example `"New activity"` →
+     * `"Feed, New activity"`). A dot has no text, so this is its only meaning.
+     */
+    badgeLabel: string;
+}
+/** One bottom-bar destination: its label, optional icon and badge, and content. */
+type TabScaffoldTab<Id extends string = string> = TabScaffoldTabBase<Id> & (TabScaffoldTabCountBadge | TabScaffoldTabDotBadge);
 interface TabScaffoldProps<Id extends string = string> {
     id: string;
     /** Accessible name for the tab bar. */
@@ -1628,12 +2079,29 @@ export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type Dev
 ```ts
 import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
-import { a as CatalogProps } from './types-CEsieBZi.js';
-export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-CEsieBZi.js';
+import { a as CatalogProps } from './types-DXAGogOS.js';
+export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-DXAGogOS.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './toolbar.js';
+import './pane.js';
+import './sides-BPSWde0A.js';
+import './workbench.js';
+import './list.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './resizable-region.js';
+import './panel-toolbar-C8sF-YZC.js';
+import './lucide-icon.js';
+import 'lucide';
 
-/** Controlled, stateless component-catalog shell. */
-declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, slot, }: CatalogProps): kerfjs.SafeHtml;
+/**
+ * Controlled, stateless component-catalog shell: a `Workbench` whose left rail
+ * is the catalog navigation and whose work area is the active entry — its
+ * toolbar, description, preview stage, and resource footer. The sidebar's
+ * standard toggle moves into the entry toolbar while it is collapsed, and on
+ * a small screen the sidebar overlays the stage like any Workbench rail.
+ */
+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';
@@ -1704,9 +2172,20 @@ export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleP
 ## `@kerfjs/ui/catalog-resources`
 
 ```ts
-import { C as CatalogResource } from './types-CEsieBZi.js';
+import { C as CatalogResource } from './types-DXAGogOS.js';
 import './semantic-content-BbzjvSu9.js';
 import 'kerfjs';
+import './toolbar.js';
+import './pane.js';
+import './sides-BPSWde0A.js';
+import './workbench.js';
+import './list.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './resizable-region.js';
+import './panel-toolbar-C8sF-YZC.js';
+import './lucide-icon.js';
+import 'lucide';
 
 /**
  * Standard resource labels for a Kerf catalog detail footer. Keep these labels
@@ -1744,6 +2223,8 @@ export { type CatalogGuidanceKind, type CatalogResourceKind, type CatalogResourc
 ## `@kerfjs/ui/wire-catalog`
 
 ```ts
+import { Signal } from 'kerfjs';
+
 interface WireCatalogOptions {
     /** Invoked with the entry id when a sidebar item or a related-entry option is chosen. */
     onSelect: (id: string) => void;
@@ -1764,6 +2245,27 @@ interface WireCatalogOptions {
     toggleSidebarAction?: string;
     toggleThemeAction?: string;
     toggleSecondaryAction?: string;
+    /**
+     * The sidebar's app-owned collapsed flag. With it, the catalog's Workbench
+     * sidebar is wired like any Workbench rail: it becomes a transient overlay
+     * on a small screen (collapsed as the breakpoint applies, closed on Escape
+     * or a press outside, focus handed back), and choosing an entry from the
+     * open overlay closes it.
+     */
+    collapsed?: Signal<boolean>;
+    /**
+     * The app-owned sidebar width signal for a Catalog rendered with
+     * `sidebar={{ resizable: true, size: sidebarSize.value }}`. Each committed
+     * drag or keyboard resize is written to it.
+     */
+    sidebarSize?: Signal<number>;
+    /**
+     * With `sidebarSize`, load and save the width under this storage key so the
+     * catalog remembers the user's sidebar width.
+     */
+    sidebarStorageKey?: string;
+    /** The Catalog's `id`, when it is not the default `kui-catalog`. */
+    id?: string;
 }
 interface CatalogRevealOptions {
     /** Scroll alignment within the sidebar. Default `'nearest'`. */
@@ -1798,7 +2300,7 @@ declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
  * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.
  * Returns a disposer.
  */
-declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, collapsed, sidebarSize, sidebarStorageKey, id: catalogId, }: WireCatalogOptions): () => void;
 
 export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
 ```
@@ -1847,6 +2349,7 @@ export { SegmentedControl, type SegmentedControlAppearance, type SegmentedContro
 import { SafeHtml } from 'kerfjs';
 import { CssForegroundColor } from './css-values.js';
 import { LucideNode } from './lucide-icon.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import 'lucide';
 
 interface SelectChoice<Value extends string = string> {
@@ -1858,7 +2361,8 @@ interface SelectChoice<Value extends string = string> {
      * Foreground color for the optional icon: a semantic foreground token such
      * as `uiColor('success-on-quiet')`, or an application-owned
      * `foregroundColorVar('--app-icon-color')`. Fill tokens such as
-     * `uiColor('success')` are pale background tints and do not type-check.
+     * `uiColor('success-fill-quiet')` are pale background tints and do not
+     * type-check.
      */
     color?: CssForegroundColor;
     group?: string;
@@ -1882,7 +2386,6 @@ type SelectSelectedPresentation = 'label' | 'icon-only';
 type SelectFocusRingOwner = 'select' | 'group';
 interface SelectBaseProps<Value extends string = string> {
     name: string;
-    value: NoInfer<Value>;
     choices: readonly SelectChoice<Value>[];
     className?: string;
     /** Empty-value hint text shown in the closed control (the native select placeholder). */
@@ -1891,14 +2394,11 @@ interface SelectBaseProps<Value extends string = string> {
     hint?: string;
     disabled?: boolean;
     fitMenu?: boolean;
-    renderSelected?: (choice: SelectChoice<Value>) => SafeHtml;
     /** Render as an unanimated loading skeleton: the label above a static, empty control box. */
     placeholder?: boolean;
     /** Form (default), borderless toolbar, or intrinsic navigation chrome. */
     presentation?: SelectPresentation;
     size?: SelectSize;
-    /** Show only the selected choice icon while retaining the Select's accessible name. */
-    selectedPresentation?: SelectSelectedPresentation;
     /** Let an enclosing ToolbarControlGroup paint the composed focus ring. */
     focusRingOwner?: SelectFocusRingOwner;
     /** Maximum closed-control label width in CSS pixels before ellipsis. */
@@ -1906,10 +2406,50 @@ interface SelectBaseProps<Value extends string = string> {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-type SelectProps<Value extends string = string> = SelectBaseProps<Value> & SelectAccessibleName;
-declare function Select<Value extends string>({ name, value, label, ariaLabel, choices, className, placeholderText, hint, disabled, fitMenu, renderSelected, placeholder, presentation, size, selectedPresentation, focusRingOwner, labelMaxWidth, slot, }: SelectProps<Value>): SafeHtml;
+/** One chosen value (the default). */
+interface SelectSingleValueProps<Value extends string = string> {
+    multiple?: false;
+    value: NoInfer<Value>;
+    renderSelected?: (choice: SelectChoice<Value>) => SafeHtml;
+    /** Show only the selected choice icon while retaining the Select's accessible name. */
+    selectedPresentation?: SelectSelectedPresentation;
+    triggerIcon?: never;
+}
+/**
+ * Any number of chosen values. The popup stays open while the person toggles
+ * choices and closes on an outside click, Escape, or focus leaving; the closed
+ * control summarizes the chosen labels in choice order.
+ */
+interface SelectMultipleLabelProps<Value extends string = string> {
+    multiple: true;
+    value: readonly NoInfer<Value>[];
+    renderSelected?: never;
+    selectedPresentation?: 'label';
+    triggerIcon?: never;
+}
+/**
+ * A multiple Select drawn as an icon-only toolbar trigger, such as a
+ * "Filter by label" funnel. No single choice is selected, so the trigger shows
+ * a fixed `triggerIcon` naming the menu's purpose; while any choice is chosen
+ * a count badge sits beside it, and the combobox's accessible name ends with
+ * the chosen labels in choice order.
+ */
+interface SelectMultipleIconProps<Value extends string = string> {
+    multiple: true;
+    value: readonly NoInfer<Value>[];
+    renderSelected?: never;
+    selectedPresentation: 'icon-only';
+    /**
+     * The trigger's fixed icon, typically a `LucideIcon` naming the menu's
+     * purpose (a funnel for a filter), independent of the selection.
+     */
+    triggerIcon: KerfUiContent;
+}
+type SelectMultipleValueProps<Value extends string = string> = SelectMultipleLabelProps<Value> | SelectMultipleIconProps<Value>;
+type SelectProps<Value extends string = string> = SelectBaseProps<Value> & SelectAccessibleName & (SelectSingleValueProps<Value> | SelectMultipleValueProps<Value>);
+declare function Select<Value extends string>(props: SelectProps<Value>): SafeHtml;
 
-export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectPresentation, type SelectProps, type SelectSelectedPresentation, type SelectSize };
+export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectMultipleIconProps, type SelectMultipleLabelProps, type SelectMultipleValueProps, type SelectPresentation, type SelectProps, type SelectSelectedPresentation, type SelectSingleValueProps, type SelectSize };
 ```
 
 ## `@kerfjs/ui/state-banner`
@@ -2044,7 +2584,7 @@ export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
-import * as kerfjs from 'kerfjs';
+import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchToken {
@@ -2066,6 +2606,15 @@ interface TokenSearchFieldBaseProps {
     label: string;
     query?: string;
     tokens?: readonly TokenSearchToken[];
+    /**
+     * Editor identity for a programmatic text replacement. The editor's text is
+     * DOM-owned between token changes, so a new `query` with the same tokens
+     * does not re-render it (that would reset the caret on every keystroke).
+     * Change `revision` when the app replaces the text itself — reseeding a
+     * persistent dialog's field on reopen, applying a saved search — and the
+     * editor is rebuilt from `query` and `tokens`.
+     */
+    revision?: string | number;
     placeholder?: string;
     tokenPlaceholder?: string;
     disabled?: boolean;
@@ -2078,6 +2627,8 @@ interface TokenSearchFieldBaseProps {
     removeAction?: string;
     clearAction?: string;
     clearLabel?: string;
+    /** Icon for the clear button. Default: the Lucide `x` glyph token chips also use. */
+    clearIcon?: SafeHtml;
     className?: string;
     editorAttributes?: TokenSearchEditorAttributes;
     /** Native named-slot assignment when composed inside a web component. */
@@ -2101,7 +2652,7 @@ interface TokenSearchFieldValue {
     query: string;
     tokens: TokenSearchToken[];
 }
-declare function TokenSearchField({ id, label, query, tokens, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, presentation, editAction, removeAction, clearAction, clearLabel, className, editorAttributes, slot, }: TokenSearchFieldProps): kerfjs.SafeHtml;
+declare function TokenSearchField({ id, label, query, tokens, revision, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, presentation, editAction, removeAction, clearAction, clearLabel, clearIcon, className, editorAttributes, slot, }: TokenSearchFieldProps): SafeHtml;
 /** Read editable text and ordered token offsets from a rendered TokenSearchField editor. */
 declare function readTokenSearchField(editor: HTMLElement, knownTokens?: readonly TokenSearchToken[]): TokenSearchFieldValue;
 /** Focus an editor and place its caret at a text offset, skipping atomic token chips. */
@@ -2311,10 +2862,17 @@ import { SafeHtml } from 'kerfjs';
 type BadgeTone = 'neutral' | 'brand' | 'pop' | 'success' | 'warning' | 'danger';
 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';
-interface BadgeProps {
-    children: SafeHtml | string | number;
+interface BadgeCommonProps {
     tone?: BadgeTone;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/** A badge that shows a short status, count, or category as visible text. */
+interface BadgeTextProps extends BadgeCommonProps {
+    children: SafeHtml | string | number;
     appearance?: BadgeAppearance;
     shape?: BadgeShape;
     size?: BadgeSize;
@@ -2322,14 +2880,35 @@ interface BadgeProps {
     label?: string;
     /** Hide a repeated visual badge from assistive technology. */
     ariaHidden?: boolean;
-    className?: string;
-    /** Native named-slot assignment when composed inside a web component. */
-    slot?: string;
 }
+/** A labeled dot, announced as an image with its own accessible name. */
+interface BadgeDotLabeled {
+    /** Accessible name for the dot, for example `"New activity"`. */
+    label: string;
+    ariaHidden?: false;
+}
+/** A decorative dot whose meaning the owning component already announces. */
+interface BadgeDotDecorative {
+    label?: never;
+    ariaHidden: true;
+}
+/**
+ * A text-free status dot (the iOS "new content" dot): a small solid circle in
+ * the badge's tone. It has no visible text, so it must either carry its own
+ * accessible `label` (exposed as an image) or be `ariaHidden` because the
+ * surrounding component already folds its meaning into an accessible name.
+ */
+type BadgeDotProps = BadgeCommonProps & {
+    size: 'dot';
+    children?: never;
+    appearance?: never;
+    shape?: never;
+} & (BadgeDotLabeled | BadgeDotDecorative);
+type BadgeProps = BadgeTextProps | BadgeDotProps;
 /** Compact, non-interactive metadata whose tone, emphasis, and shape are configured by props. */
-declare function Badge({ children, tone, appearance, shape, size, label, ariaHidden, className, slot, }: BadgeProps): SafeHtml;
+declare function Badge(props: BadgeProps): SafeHtml;
 
-export { Badge, type BadgeAppearance, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTone };
+export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTextProps, type BadgeTone };
 ```
 
 ## `@kerfjs/ui/lucide-icon`
@@ -2431,9 +3010,9 @@ export { Text, type TextBorder, type TextContent, type TextFont, type TextProps,
 ```ts
 import * as kerfjs from 'kerfjs';
 import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
-import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 type RowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;