@kerfjs/ui 5.0.0-beta.61 → 5.0.0-beta.63

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.61` and `kerfjs@5.0.0-beta.61`. 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.63` and `kerfjs@5.0.0-beta.63`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -146,11 +146,14 @@ import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
 
+type ToolbarPosition = 'header' | 'footer';
 interface ToolbarProps {
     leading?: KerfUiContent;
     center?: KerfUiContent;
     trailing?: KerfUiContent;
     label?: string;
+    /** Use footer semantics for a bottom toolbar; defaults to header. */
+    position?: ToolbarPosition;
     /**
      * Physical divider edges in canonical top/right/bottom/left order, drawn
      * always. Defaults to none: a toolbar pinned over or under scrolling content
@@ -160,8 +163,8 @@ interface ToolbarProps {
      * then draws its facing side the same way.
      */
     dividerSides?: Sides;
-    /** Horizontal treatment of the center zone. Defaults to centered content. */
-    centerAlign?: 'center' | 'stretch';
+    /** `balanced` gives both side zones equal tracks, centering the middle zone on the toolbar even if only one side has controls. */
+    centerAlign?: 'center' | 'stretch' | 'balanced';
     /**
      * Component-owned responsive layout; applications choose the policy rather
      * than restyling toolbar internals. Under every policy the trailing zone
@@ -200,9 +203,9 @@ interface ToolbarProps {
  * toolbar) forwards, so the app configures that toolbar instead of styling it.
  */
 type ToolbarConfig = Pick<ToolbarProps, 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
-declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, position, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { Sides, Toolbar, type ToolbarConfig, type ToolbarProps };
+export { Sides, Toolbar, type ToolbarConfig, type ToolbarPosition, type ToolbarProps };
 ```
 
 ## `@kerfjs/ui/toolbar-text`
@@ -210,7 +213,7 @@ export { Sides, Toolbar, type ToolbarConfig, type ToolbarProps };
 ```ts
 import * as kerfjs from 'kerfjs';
 
-type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small' | 'xsmall';
+type ToolbarTextSize = 'xlarge' | 'xlarge-fixed' | 'large' | 'default' | 'small' | 'xsmall';
 /** ARIA heading level for a title exposed as a heading landmark. */
 type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 interface ToolbarTextBaseProps {
@@ -321,6 +324,10 @@ interface ToolbarControlGroupProps {
     relocateOnCollapse?: boolean;
     /** Add contrast behind photo-backed avatar content. */
     scrim?: boolean;
+    /** Block the group's controls and show a spinner without changing its dimensions. */
+    busy?: boolean;
+    /** Announced status while busy; defaults to “Working”. */
+    busyLabel?: string;
     /**
      * Avatar image URL. A single-control group paints it on the group; a
      * multi-control group paints it only on the pressed selection highlight.
@@ -329,7 +336,7 @@ interface ToolbarControlGroupProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, busy, busyLabel, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
 
 export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };
 ```
@@ -413,9 +420,9 @@ interface PopupMenuItem {
     value?: string;
     /** Leading icon, typically a `LucideIcon`; it is placed in the item's icon slot. */
     icon?: SafeHtml;
-    /** A checked menu choice, including nested choices. */
+    /** A checkbox choice, including nested choices; omit for a plain command. */
     checked?: boolean;
-    /** Trailing safe content, such as a selected-choice tick. */
+    /** Trailing safe content, such as secondary status. */
     details?: SafeHtml;
     /** Destructive command styling. */
     tone?: 'default' | 'danger';
@@ -870,10 +877,22 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 type ContentItemFrame = 'none' | 'framed';
 /** Corner shape: the 12px rounded rectangle or the 22px pill. */
 type ContentItemShape = 'rounded' | 'pill';
+/** `single` uses option selection; `toggle` uses a pressed button. */
+type ContentItemSelectionMode = 'none' | 'single' | 'toggle';
 type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
 }>;
-interface ContentItemProps {
+type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-action'?: never;
+    'data-item-id'?: never;
+    'data-interactive'?: never;
+    'data-selected'?: never;
+    'data-disabled'?: never;
+    'data-selection-mode'?: never;
+    'data-kui-pressed'?: never;
+}>;
+interface ContentItemBaseProps {
     /** Item content; a plain string is allowed for bare copy. */
     children?: KerfUiContent | string;
     /**
@@ -896,19 +915,38 @@ interface ContentItemProps {
      */
     focusTarget?: boolean;
     className?: string;
-    /** Safe `data-*` metadata; component-owned structural attributes stay protected. */
-    rootAttributes?: ContentItemRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+type ContentItemProps = ContentItemBaseProps & ({
+    interactive?: false;
+    action?: never;
+    itemId?: never;
+    selectionMode?: never;
+    selected?: never;
+    disabled?: never;
+    /** Existing static `data-*` metadata remains available. */
+    rootAttributes?: ContentItemRootAttributes;
+} | {
+    /** Enable a keyboard reachable card; wire `wireContentItems` once on its containing root. */
+    interactive: true;
+    /** Delegated action dispatched by pointer, Enter, or Space. */
+    action: string;
+    itemId?: string;
+    selectionMode?: ContentItemSelectionMode;
+    selected?: boolean;
+    disabled?: boolean;
+    /** Safe app metadata; interaction attributes are component-owned. */
+    rootAttributes?: ContentItemInteractiveRootAttributes;
+});
 /**
  * One self-contained `.kui-content` child: an 8px inline margin, a real 1px
  * border (transparent unless `framed`), 8px padding, and a rounded or pill
  * radius. It owns that whole geometry, so wrappers must not add more.
  */
-declare function ContentItem({ children, frame, shape, ariaLabel, focusTarget, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
+declare function ContentItem({ children, frame, shape, ariaLabel, focusTarget, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
 
-export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemShape };
+export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -1024,6 +1062,8 @@ type TabActivation = 'automatic' | 'manual';
 type TabBarAllocation = 'intrinsic' | 'fill';
 type TabBarPresentation = 'rail' | 'segmented' | 'inspector';
 type TabBarTrailingPlacement = 'separate' | 'adjacent';
+/** Tablist width where segmented AppTabs switch to icon-only. */
+type TabBarIconOnlyAt = 'wide' | 'narrow' | 'compact';
 interface TabBarProps {
     id: string;
     label: string;
@@ -1047,15 +1087,17 @@ interface TabBarProps {
     allocation?: TabBarAllocation;
     /** Named strip chrome for application rails, segmented tabs, or inspectors. */
     presentation?: TabBarPresentation;
+    /** Switch segmented AppTabs to icon-only at tablist widths of 832, 704, or 448px. Each tab needs a leading icon. */
+    iconOnlyAt?: TabBarIconOnlyAt;
     /** Keep a trailing action beside the final tab or at the far edge of the bar. */
     trailingPlacement?: TabBarTrailingPlacement;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** Render a controlled tab strip. The application owns selection, order, and persistence. */
-declare function TabBar({ id, label, children, leading, trailing, end, className, activation, allocation, presentation, trailingPlacement, slot, }: TabBarProps): kerfjs.SafeHtml;
+declare function TabBar({ id, label, children, leading, trailing, end, className, activation, allocation, presentation, iconOnlyAt, trailingPlacement, slot, }: TabBarProps): kerfjs.SafeHtml;
 
-export { type TabActivation, TabBar, type TabBarAllocation, type TabBarPresentation, type TabBarProps, type TabBarTrailingPlacement };
+export { type TabActivation, TabBar, type TabBarAllocation, type TabBarIconOnlyAt, type TabBarPresentation, type TabBarProps, type TabBarTrailingPlacement };
 ```
 
 ## `@kerfjs/ui/wire-tab-bars`
@@ -1175,10 +1217,10 @@ export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDiv
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { PaneAppearance } from './pane.js';
 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';
 
 /**
@@ -1189,6 +1231,8 @@ interface NavStackView {
     /** Stable identity for keyed reconcile and transition direction. */
     key: string;
     content: KerfUiContent;
+    /** Background of this view's scrolling work surface. */
+    appearance?: PaneAppearance;
     /** 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. */
@@ -1294,8 +1338,8 @@ 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 './toolbar.js';
 import './sides-BPSWde0A.js';
 import './toolbar-text.js';
 import './css-values.js';
@@ -1393,6 +1437,7 @@ type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-safe-area-inline-end'?: never;
     'data-chrome-placement'?: never;
     'data-chrome-dividers'?: never;
+    'data-appearance'?: never;
 }>;
 /** How a Pane's header and footer relate to its scrolling content. */
 type PaneChromePlacement = 'fixed' | 'auto';
@@ -1402,6 +1447,8 @@ type PaneChromePlacement = 'fixed' | 'auto';
  * chrome, as `wireScrollDividers` reports; `always`; or `none`.
  */
 type PaneChromeDividers = 'scroll' | 'always' | 'none';
+/** Background treatment of the Pane's scrolling work surface. */
+type PaneAppearance = 'default' | 'sunken';
 interface PaneProps {
     /** Optional fixed chrome above the scrolling content, arranged vertically. */
     header?: KerfUiContent;
@@ -1419,7 +1466,8 @@ interface PaneProps {
     chromePlacement?: PaneChromePlacement;
     /**
      * The divider under the header and over the footer, where they meet the
-     * scrolling content. `scroll` (default) shows the header's divider only
+     * scrolling content. Omitted defaults to `scroll` for a plain pane and
+     * `always` for `appearance="sunken"`. `scroll` shows the header's divider only
      * while the content is scrolled down, and the footer's only while more
      * content lies below — never when the content fits — once
      * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
@@ -1427,6 +1475,8 @@ interface PaneProps {
      * The line is drawn inside the chrome, so no state moves the content.
      */
     chromeDividers?: PaneChromeDividers;
+    /** Paint the scrolling work surface with the shared lowered-surface color. */
+    appearance?: PaneAppearance;
     /** Root semantics. Defaults to `div`. */
     element?: PaneElement;
     /** Scrolling content semantics. Defaults to `div`. */
@@ -1461,16 +1511,16 @@ interface PaneProps {
  * 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' | 'chromeDividers'>;
+type PaneConfig = Pick<PaneProps, 'contentElement' | 'contentLabel' | 'separators' | 'safeAreaEdges' | 'chromeDividers' | 'appearance'>;
 /**
  * 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, chromePlacement, chromeDividers, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
+declare function Pane({ header, children, footer, chromePlacement, chromeDividers, appearance, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
 
-export { Pane, type PaneChromeDividers, type PaneChromePlacement, type PaneConfig, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
+export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlacement, type PaneConfig, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
 ```
 
 ## `@kerfjs/ui/workbench`
@@ -1481,7 +1531,7 @@ import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { a as PanelToolbar, b as PanelToggle } from './panel-toolbar-DqwtBxQL.js';
+import { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
 import { ToolbarConfig } from './toolbar.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -1500,6 +1550,7 @@ type WorkbenchPanelToggle = PanelToggle;
  * `FloatingToolbar` in the work area's bottom-end corner.
  */
 type WorkbenchPanelToolbar = PanelToolbar;
+type WorkbenchPanelBottomToolbar = PanelBottomToolbar;
 /**
  * The work area's top toolbar; collapsed rails add their groups to it. Its
  * configuration forwards to its `Toolbar`. It draws no divider of its own by
@@ -1535,7 +1586,7 @@ interface WorkbenchMainBottomToolbar extends ToolbarConfig {
  * the Pane's `chromePlacement="auto"`; it applies to the pinned header and
  * footer together).
  */
-type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
+type WorkbenchChromePlacement = PanelChromePlacement;
 
 /**
  * The Workbench container breakpoint below which a panel presents as an
@@ -1543,7 +1594,7 @@ type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
  * breakpoints as `ResizableRegion`'s `responsiveFillAt` — or `never` to keep
  * it inline at every width.
  */
-type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never';
+type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never' | number;
 /**
  * How wide a rail's overlay is in a compact (448px or less) Workbench: `inset`
  * fills the Workbench less a dismiss margin on the side away from the rail's
@@ -1566,8 +1617,20 @@ interface WorkbenchPanel {
      * collapsed. With it, `content` renders in a `Pane` below the toolbar.
      */
     toolbar?: WorkbenchPanelToolbar;
-    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    /** Fixed content below a toolbar panel's top toolbar, above its scroll region. */
+    header?: KerfUiContent;
+    /** List layout for `header`; omitted fields keep List defaults. */
+    headerList?: ListConfig;
+    /** Placement of the top toolbar and header together; default `fixed`. */
+    headerPlacement?: WorkbenchChromePlacement;
+    /** Fixed content above a toolbar panel's bottom toolbar. */
     footer?: KerfUiContent;
+    /** List layout for `footer`; omitted fields keep List defaults. */
+    footerList?: ListConfig;
+    /** Fixed toolbar below `footer`, using footer semantics. */
+    bottomToolbar?: WorkbenchPanelBottomToolbar;
+    /** Placement of the footer and bottom toolbar together; default `fixed`. */
+    footerPlacement?: WorkbenchChromePlacement;
     /**
      * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
      * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
@@ -1599,8 +1662,9 @@ interface WorkbenchPanel {
     presentation?: ResizableRegionPresentation;
     /**
      * Present the panel as an overlay, without a separator, below a Workbench
-     * container breakpoint, and inline above it — the CSS decides, so the app
-     * needs no device-class check. A rail overlays from its side at full
+     * container breakpoint, and inline above it. `compact` and `narrow` use
+     * CSS container queries; a positive number is a pixel threshold measured
+     * by `wireWorkbench` and requires a `collapsed` signal. A rail overlays from its side at full
      * height, over the work area and an open drawer; the bottom drawer
      * overlays the bottom of the work-area column. Rails default to `narrow`
      * (pass `never` to keep one inline); the drawer defaults to inline.
@@ -1700,6 +1764,8 @@ interface WorkbenchProps {
      * shorter. Workbenches without a drawer ignore it.
      */
     mainMinHeight?: number;
+    /** Dim the work area below any open overlay and absorb outside presses; off by default. */
+    overlayBackdrop?: boolean;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -1717,9 +1783,9 @@ interface WorkbenchProps {
  * lives outside it and stays reachable). A panel may opt in to drag and keyboard resizing with
  * `resizable`, which `wireWorkbench` drives. See `docs/23-app-layouts.md` §3.3.
  */
-declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainPane, mainHeaderList, mainFooterList, mainMinSize, mainMinHeight, className, slot, }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainPane, mainHeaderList, mainFooterList, mainMinSize, mainMinHeight, overlayBackdrop, className, slot, }: WorkbenchProps): SafeHtml;
 
-export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
+export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelBottomToolbar, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
 ```
 
 ## `@kerfjs/ui/wire-workbench`
@@ -1759,6 +1825,13 @@ interface WireWorkbenchPanel {
      * keeps Tab inside it, and it closes on Escape or a press outside it.
      */
     collapsed?: Signal<boolean>;
+    /**
+     * Treat presses in a portal surface launched by this panel (for example a
+     * body-level menu or dialog) as inside it. The predicate receives each Node
+     * in the press's composed path; return true for the portal root. Ordinary
+     * presses outside the panel and its allowed surfaces still dismiss it.
+     */
+    keepOpenOn?: (target: Node) => boolean;
 }
 /** A resize the user made, after `wireWorkbench` wrote it to the size signal. */
 interface WorkbenchResize {
@@ -1840,16 +1913,18 @@ export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanel
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
-import { P as PanelSide, a as PanelToolbar, b as PanelToggle } from './panel-toolbar-DqwtBxQL.js';
-export { c as collapsiblePanelToggleIcon } from './panel-toolbar-DqwtBxQL.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
+export { e as collapsiblePanelToggleIcon } from './panel-toolbar-DDKh4uKd.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './sides-BPSWde0A.js';
 import './lucide-icon.js';
 import 'lucide';
 import './toolbar.js';
-import './sides-BPSWde0A.js';
-import './css-values.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
 type CollapsiblePanelSide = PanelSide;
@@ -1862,6 +1937,8 @@ type CollapsiblePanelToolbarToggle = PanelToggle;
  * {@link CollapsiblePanelRelocated} while it is collapsed.
  */
 type CollapsiblePanelToolbar = PanelToolbar;
+type CollapsiblePanelBottomToolbar = PanelBottomToolbar;
+type CollapsiblePanelChromePlacement = PanelChromePlacement;
 interface CollapsiblePanelToggleProps {
     /** The panel this toggle controls. */
     side: CollapsiblePanelSide;
@@ -1905,8 +1982,15 @@ interface CollapsiblePanelProps {
      * marked groups and toggle stay reachable while the panel is collapsed.
      */
     toolbar?: CollapsiblePanelToolbar;
-    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    /** Fixed content below a toolbar panel's top toolbar. */
+    header?: KerfUiContent;
+    headerList?: ListConfig;
+    headerPlacement?: CollapsiblePanelChromePlacement;
+    /** Fixed content above a toolbar panel's bottom toolbar. */
     footer?: KerfUiContent;
+    footerList?: ListConfig;
+    bottomToolbar?: CollapsiblePanelBottomToolbar;
+    footerPlacement?: CollapsiblePanelChromePlacement;
     /**
      * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
      * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
@@ -1940,7 +2024,7 @@ interface CollapsiblePanelProps {
  * and persistence semantics, and with `CollapsiblePanelToggle` for the standard
  * affordance. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.
  */
-declare function CollapsiblePanel({ id, side, collapsed, size, label, children, toolbar, footer, pane, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
+declare function CollapsiblePanel({ id, side, collapsed, size, label, children, toolbar, header, headerList, headerPlacement, footer, footerList, bottomToolbar, footerPlacement, pane, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
 interface CollapsiblePanelRelocatedProps {
     /** The panel's `id`. */
     panelId: string;
@@ -1960,7 +2044,7 @@ interface CollapsiblePanelRelocatedProps {
  */
 declare function CollapsiblePanelRelocated({ panelId, side, collapsed, toolbar, }: CollapsiblePanelRelocatedProps): SafeHtml;
 
-export { CollapsiblePanel, type CollapsiblePanelProps, CollapsiblePanelRelocated, type CollapsiblePanelRelocatedProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, type CollapsiblePanelToolbar, type CollapsiblePanelToolbarToggle };
+export { CollapsiblePanel, type CollapsiblePanelBottomToolbar, type CollapsiblePanelChromePlacement, type CollapsiblePanelProps, CollapsiblePanelRelocated, type CollapsiblePanelRelocatedProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, type CollapsiblePanelToolbar, type CollapsiblePanelToolbarToggle };
 ```
 
 ## `@kerfjs/ui/wire-sidebar`
@@ -2035,6 +2119,7 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { PaneAppearance } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface TabScaffoldTabBase<Id extends string> {
@@ -2044,6 +2129,8 @@ interface TabScaffoldTabBase<Id extends string> {
     icon?: SafeHtml;
     /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */
     content: KerfUiContent;
+    /** Background of this scene's scrolling work surface. */
+    appearance?: PaneAppearance;
 }
 /** A tab with an optional count or short-status badge. */
 interface TabScaffoldTabCountBadge {
@@ -2290,7 +2377,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-DqwtBxQL.js';
+import './panel-toolbar-DDKh4uKd.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2383,7 +2470,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-DqwtBxQL.js';
+import './panel-toolbar-DDKh4uKd.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2608,6 +2695,8 @@ interface SelectBaseProps<Value extends string = string> {
     size?: SelectSize;
     /** Closed trigger width; omit to keep the presentation's default. */
     triggerWidth?: SelectTriggerWidth;
+    /** Show the disclosure caret (default); omit it for a compact icon-only trigger. */
+    caret?: boolean;
     /** Let an enclosing ToolbarControlGroup paint the composed focus ring. */
     focusRingOwner?: SelectFocusRingOwner;
     /** Maximum closed-control label width in CSS pixels before ellipsis. */
@@ -2783,6 +2872,7 @@ export { Skeleton, type SkeletonProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssFlexKeyword, CssFlex } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type SunkenPanelShape = 'rounded' | 'square';
@@ -2792,6 +2882,10 @@ interface SunkenPanelProps {
     ariaLabel?: string;
     /** Corner shape: a rounded rectangle (default) or square corners. */
     shape?: SunkenPanelShape;
+    /** Grow or shrink within a flex parent, using Grid's typed flex contract. */
+    flex?: boolean | CssFlexKeyword | CssFlex;
+    /** Fill a parent with a definite height; use flex inside a flex layout. */
+    fill?: boolean;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -2801,7 +2895,7 @@ interface SunkenPanelProps {
  * stack. The panel owns its background and padding; children own their own
  * borders and internal geometry.
  */
-declare function SunkenPanel({ children, ariaLabel, shape, className, slot, }: SunkenPanelProps): kerfjs.SafeHtml;
+declare function SunkenPanel({ children, ariaLabel, shape, flex, fill, className, slot, }: SunkenPanelProps): kerfjs.SafeHtml;
 
 export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ```
@@ -3075,8 +3169,8 @@ import { SafeHtml } from 'kerfjs';
 import { BadgeTone, BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
 
 interface ChipCommonProps {
-    /** Visible, non-interactive chip content. */
-    children: SafeHtml | string | number;
+    /** Decorative leading icon, normally an unsized LucideIcon. */
+    icon?: SafeHtml;
     tone?: BadgeTone;
     appearance?: BadgeAppearance;
     shape?: BadgeShape;
@@ -3090,6 +3184,12 @@ interface ChipCommonProps {
 }
 /** A removable chip needs both a delegated action and a specific accessible name. */
 type ChipProps = ChipCommonProps & ({
+    children: SafeHtml | string | number;
+    truncate?: false;
+} | {
+    children: string;
+    truncate: true;
+}) & ({
     removeAction: string;
     removeLabel: string;
 } | {
@@ -3097,7 +3197,7 @@ type ChipProps = ChipCommonProps & ({
     removeLabel?: never;
 });
 /** A short label with an optional native remove button. The application owns removal. */
-declare function Chip({ children, tone, appearance, shape, size, disabled, itemId, className, slot, ...remove }: ChipProps): SafeHtml;
+declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, ...remove }: ChipProps): SafeHtml;
 
 export { Chip, type ChipProps };
 ```
@@ -3109,18 +3209,21 @@ import * as kerfjs from 'kerfjs';
 import { IconNode } from 'lucide';
 
 type LucideNode = IconNode;
+type LucideIconSize = 'xs' | 's' | 'm' | 'l' | 'xl' | number;
 interface LucideIconProps {
     icon: LucideNode;
     name: string;
     className?: string;
     label?: string;
+    /** Named icon scale or positive pixel size, converted to rem. Omit for 1em. */
+    size?: LucideIconSize;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** Render a Lucide-compatible icon node without copying icon SVG strings. */
-declare function LucideIcon({ icon, name, className, label, slot, }: LucideIconProps): kerfjs.SafeHtml;
+declare function LucideIcon({ icon, name, className, label, size, slot, }: LucideIconProps): kerfjs.SafeHtml;
 
-export { LucideIcon, type LucideIconProps, type LucideNode };
+export { LucideIcon, type LucideIconProps, type LucideIconSize, type LucideNode };
 ```
 
 ## `@kerfjs/ui/surface-scaffold`
@@ -3171,8 +3274,9 @@ type TextSize = 'compact' | 'default' | 'large' | 'xlarge';
 type TextFont = 'default' | 'monospace';
 type TextBorder = 'transparent' | 'none';
 type TextLineHeight = 'default' | 'tight';
+type TextWrap = 'normal' | 'anywhere' | 'nowrap' | 'truncate';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
-type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
+type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
     variant?: TextVariant;
     /** Semantic foreground treatment. Defaults to the inherited foreground. */
@@ -3191,14 +3295,24 @@ type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     class?: string;
     className?: string;
 };
+type TextProps = TextCommonProps & ({
+    /** Wrap normally or break long unbroken strings. Defaults to normal. */
+    wrap?: 'normal' | 'anywhere';
+    /** Cap wrapped text to this positive number of lines. */
+    maxLines?: number;
+} | {
+    /** Keep one line, with or without an ellipsis. */
+    wrap: 'nowrap' | 'truncate';
+    maxLines?: never;
+});
 /**
  * Semantic heading, paragraph, or inline text. Block variants use the standard
  * content-item padding; `span` adds no box geometry.
  * All ordinary native heading/paragraph attributes pass through to the element.
  */
-declare function Text({ variant: Variant, tone, size, font, border, flush, lineHeight, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
+declare function Text({ variant: Variant, tone, size, font, border, flush, lineHeight, wrap, maxLines, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
 
-export { Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant };
+export { Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant, type TextWrap };
 ```
 
 ## `@kerfjs/ui/row`