@kerfjs/ui 5.0.0-beta.3 → 5.0.0-beta.31

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

@@ -1,6 +1,86 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.3` and `kerfjs@5.0.0-beta.3`. 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.31` and `kerfjs@5.0.0-beta.31`. 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`
+
+```ts
+declare const cssValueBrand: unique symbol;
+declare const cssLengthBrand: unique symbol;
+declare const cssLengthExpressionBrand: unique symbol;
+declare const cssFlexBrand: unique symbol;
+declare const cssColorBrand: unique symbol;
+/**
+ * A complete typed CSS value minted by a property-specific Kerf UI builder.
+ *
+ * This brand is an authoring correctness aid, not a sanitizer or security
+ * boundary. Prefer the narrower property grammar, such as {@link CssLength},
+ * whenever one is available.
+ */
+type CssValue = string & {
+    readonly [cssValueBrand]: 'CssValue';
+};
+/**
+ * A complete CSS length-percentage value suitable for dimension-valued UI
+ * props. Despite the concise name, percentages are intentionally included.
+ */
+type CssLength = CssValue & {
+    readonly [cssLengthBrand]: 'CssLength';
+};
+/**
+ * An incomplete arithmetic expression. Wrap it with {@link calc} before
+ * passing it to a prop that accepts {@link CssLength}.
+ */
+type CssLengthExpression = string & {
+    readonly [cssLengthExpressionBrand]: 'CssLengthExpression';
+};
+/** A complete CSS `flex` shorthand. It is not interchangeable with a length. */
+type CssFlex = CssValue & {
+    readonly [cssFlexBrand]: 'CssFlex';
+};
+/** A complete CSS color value. It is not interchangeable with a length. */
+type CssColor = CssValue & {
+    readonly [cssColorBrand]: 'CssColor';
+};
+type CssFlexKeyword = 'none' | 'auto' | 'initial';
+type CssFlexBasis = CssLength | 'auto' | 'content' | 'min-content' | 'max-content' | 'fit-content';
+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-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"];
+/** Names of the public `--kui-color-*` semantic tokens. */
+type UiColorName = (typeof uiColorNames)[number];
+/** 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. */
+declare function px(value: number): CssLength;
+/** Create a complete root-font-relative length. */
+declare function rem(value: number): CssLength;
+/** Create a complete current-font-relative length. */
+declare function em(value: number): CssLength;
+/** Create a complete percentage length. */
+declare function pct(value: number): CssLength;
+/** Resolve a Kerf UI spacing step to its public custom property. */
+declare function space(name: UiSpaceName): CssLength;
+/**
+ * Reference an application-owned custom property whose contract is a CSS
+ * length-percentage. The deliberately narrow name grammar keeps this helper
+ * from becoming an arbitrary CSS-string constructor.
+ */
+declare function lengthVar(name: `--${string}`, fallback?: CssLength): CssLength;
+/** Combine two or more complete lengths into a non-standalone sum. */
+declare function plus(first: CssLength, second: CssLength, ...rest: readonly CssLength[]): CssLengthExpression;
+/** Turn a typed length expression into a complete CSS `calc()` value. */
+declare function calc(expression: CssLengthExpression): CssLength;
+/** Build a complete, structured CSS flex shorthand. */
+declare function flex(grow: number, shrink?: number, basis?: CssFlexBasis): CssFlex;
+/** Resolve a public Kerf UI semantic color token. */
+declare function uiColor(name: UiColorName): CssColor;
+/** Reference an application-owned custom property whose contract is a color. */
+declare function colorVar(name: `--${string}`, fallback?: CssColor): CssColor;
+
+export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColorName, type UiSpaceName, calc, colorVar, em, flex, lengthVar, pct, plus, px, rem, space, uiColor };
+```
 
 ## `@kerfjs/ui/disclosure-arrow`
 
@@ -24,19 +104,22 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 ## `@kerfjs/ui/toolbar`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { D as DividerSides } from './divider-sides-267FA7sY.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface ToolbarProps {
-    leading?: SafeHtml;
-    center?: SafeHtml;
-    trailing?: SafeHtml;
+    leading?: KerfUiContent;
+    center?: KerfUiContent;
+    trailing?: KerfUiContent;
     label?: string;
-    divider?: boolean;
+    /** Physical divider edges in canonical top/right/bottom/left order. Defaults to bottom. */
+    dividerSides?: DividerSides;
     className?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, divider, className }: ToolbarProps): SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, dividerSides, className, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { Toolbar, type ToolbarProps };
+export { DividerSides, Toolbar, type ToolbarProps };
 ```
 
 ## `@kerfjs/ui/toolbar-text`
@@ -44,99 +127,252 @@ export { Toolbar, type ToolbarProps };
 ```ts
 import * as kerfjs from 'kerfjs';
 
-type ToolbarTextSize = 'large' | 'default' | 'small';
-interface ToolbarTextProps {
+type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small';
+/** ARIA heading level for a title exposed as a heading landmark. */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+interface ToolbarTextBaseProps {
     text: string;
     size?: ToolbarTextSize;
     className?: string;
+    /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */
+    id?: string;
+    /**
+     * Expose heading semantics (`role="heading"` + `aria-level`) so the text acts as
+     * a heading landmark — e.g. a page's primary title. Omit to keep the plain span
+     * (the default), which suits a dialog title referenced via `aria-labelledby`.
+     */
+    headingLevel?: HeadingLevel;
+    /** Render the text as an unanimated loading skeleton instead of its value. */
+    placeholder?: boolean;
+    /**
+     * Show a trailing ellipsis (…) where the text is truncated — on the single line
+     * (default), or at the `maxLines` boundary when wrapping. Set false to hard-clip
+     * instead. Default true.
+     */
+    ellipsis?: boolean;
 }
-declare function ToolbarText({ text, size, className }: ToolbarTextProps): kerfjs.SafeHtml;
+type ToolbarTextWrappingProps = {
+    /** Wrap onto multiple lines; combine with `maxLines` to cap them. */
+    wrap: true;
+    maxLines?: number | null;
+} | {
+    wrap?: false;
+    maxLines?: never;
+};
+type ToolbarTextProps = ToolbarTextBaseProps & ToolbarTextWrappingProps;
+declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, }: ToolbarTextProps): kerfjs.SafeHtml;
 
-export { ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
+export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
 ```
 
 ## `@kerfjs/ui/toolbar-control-group`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
-
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+type ToolbarControlGroupAppearance = 'contained' | 'borderless';
+type ToolbarControlGroupTone = 'default' | 'dark';
+type ToolbarControlGroupButtonAppearance = 'plain' | 'push';
+type ToolbarControlGroupShape = 'pill' | 'rounded';
+type ToolbarControlGroupSize = 'default' | 'compact';
+type ToolbarControlGroupDensity = 'comfortable' | 'tight';
+type ToolbarControlGroupContent = 'icon' | 'text' | 'mixed' | 'avatar';
+type ToolbarControlGroupSelectedChrome = 'raised' | 'filled' | 'outline';
+type ToolbarControlGroupSelectedTone = 'brand' | 'neutral' | 'pop';
 interface ToolbarControlGroupProps {
-    children: SafeHtml | SafeHtml[];
+    children: KerfUiContent;
     label?: string;
     className?: string;
     expanded?: boolean;
     single?: boolean;
-    appearance?: 'contained' | 'borderless';
-    tone?: 'default' | 'dark';
-    buttonAppearance?: 'plain' | 'push';
+    appearance?: ToolbarControlGroupAppearance;
+    tone?: ToolbarControlGroupTone;
+    buttonAppearance?: ToolbarControlGroupButtonAppearance;
+    /** Corner shape: fully round `pill` (default) or a softer `rounded` rectangle. */
+    shape?: ToolbarControlGroupShape;
+    size?: ToolbarControlGroupSize;
+    density?: ToolbarControlGroupDensity;
+    content?: ToolbarControlGroupContent;
+    selectedChrome?: ToolbarControlGroupSelectedChrome;
+    selectedTone?: ToolbarControlGroupSelectedTone;
+    /** Size a nested Web Awesome dropdown trigger as part of this group. */
+    nestedDropdown?: boolean;
+    /** Add contrast behind photo-backed avatar content. */
+    scrim?: boolean;
+    /**
+     * Avatar image URL. A single-control group paints it on the group; a
+     * multi-control group paints it only on the pressed selection highlight.
+     */
+    avatarImage?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance }: ToolbarControlGroupProps): SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, selectedChrome, selectedTone, nestedDropdown, scrim, avatarImage, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
 
-export { ToolbarControlGroup, type ToolbarControlGroupProps };
+export { ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone };
 ```
 
-## `@kerfjs/ui/menu-header`
+## `@kerfjs/ui/floating-toolbar`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/** Where a {@link FloatingToolbar} floats within its positioned container. */
+type FloatingToolbarPosition = 'bottom' | 'bottom-start' | 'bottom-end' | 'top' | 'top-start' | 'top-end';
+interface FloatingToolbarProps {
+    /** Toolbar contents — normally one or more `ToolbarControlGroup`s. */
+    children: KerfUiContent;
+    /** Accessible name for the toolbar (required — it exposes `role="toolbar"`). */
+    label: string;
+    /**
+     * Corner or edge it floats to inside its nearest positioned ancestor.
+     * Default: `'bottom-end'`.
+     */
+    position?: FloatingToolbarPosition;
+    className?: string;
+}
+/**
+ * A toolbar that floats above the main content of its nearest positioned
+ * 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 to move it. The app owns the
+ * controls and their behavior — wire them with `delegate()` as usual.
+ */
+declare function FloatingToolbar({ children, label, position, className, }: FloatingToolbarProps): kerfjs.SafeHtml;
+
+export { FloatingToolbar, type FloatingToolbarPosition, type FloatingToolbarProps };
+```
+
+## `@kerfjs/ui/list-header`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
 
-type MenuHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-action'?: never;
     'data-has-badge'?: never;
     'data-has-count'?: never;
+    'data-density'?: never;
+    'data-divider'?: never;
+    'data-indicator-tone'?: never;
     'data-toggle'?: never;
 }>;
-type MenuHeaderTriggerAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListHeaderTriggerAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-action'?: never;
     popoverTarget?: string;
     popoverTargetAction?: 'toggle' | 'show' | 'hide';
     'aria-controls'?: string;
     'aria-haspopup'?: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | 'true';
 }>;
-interface MenuHeaderBaseProps {
+interface ListHeaderBaseProps {
     label: string;
-    action?: string;
-    actionLabel?: string;
+    density?: 'standard' | 'compact';
+    divider?: 'none' | 'before' | 'after' | 'both';
+    indicatorTone?: 'neutral' | 'accent' | 'pop' | 'danger';
+    /** Render as an unanimated loading skeleton: keep the label and action affordance, disable interaction. */
+    placeholder?: boolean;
+    rootAttributes?: ListHeaderRootAttributes;
+    triggerAttributes?: ListHeaderTriggerAttributes;
+}
+type ListHeaderModeProps = {
+    /** Render the title as a controlled disclosure trigger. */
+    toggle: true;
+    action: string;
+    expanded: boolean;
     actionIcon?: SafeHtml;
+    actionLabel?: never;
     actionDisabled?: boolean;
     disabledReason?: string;
-    expanded?: boolean;
-    toggle?: boolean;
-    rootAttributes?: MenuHeaderRootAttributes;
-    triggerAttributes?: MenuHeaderTriggerAttributes;
-}
-type MenuHeaderIndicatorProps = {
+} | {
+    /** Render a separately named trailing action. */
+    toggle?: false;
+    action: string;
+    actionLabel: string;
+    actionIcon: SafeHtml;
+    expanded?: never;
+    actionDisabled?: boolean;
+    disabledReason?: string;
+} | {
+    /** Render a passive section heading. */
+    toggle?: false;
+    action?: never;
+    actionLabel?: never;
+    actionIcon?: never;
+    expanded?: never;
+    actionDisabled?: never;
+    disabledReason?: never;
+};
+type ListHeaderIndicatorProps = {
     count: number;
     countLabel: string;
     badge?: never;
+    status?: never;
+} | {
+    count?: never;
+    countLabel?: never;
+    badge: SafeHtml;
+    status?: never;
 } | {
     count?: never;
     countLabel?: never;
-    badge?: SafeHtml;
+    badge?: never;
+    status?: SafeHtml;
 };
-type MenuHeaderProps = MenuHeaderBaseProps & MenuHeaderIndicatorProps;
-declare function MenuHeader({ label, count, countLabel, badge, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, rootAttributes, triggerAttributes }: MenuHeaderProps): SafeHtml;
+type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps & ListHeaderModeProps;
+declare function ListHeader({ label, count, countLabel, badge, status, density, divider, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, }: ListHeaderProps): SafeHtml;
+
+export { ListHeader, type ListHeaderProps };
+```
+
+## `@kerfjs/ui/list`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { D as DividerSides } from './divider-sides-267FA7sY.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+interface ListProps {
+    children?: KerfUiContent;
+    /** Use the standard item gap, a named UI spacing token, or a typed CSS length. Defaults to no gap. */
+    gap?: boolean | UiSpaceName | CssLength;
+    /** Allow this list to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
+    flex?: boolean | CssFlexKeyword | CssFlex;
+    /** Own vertical scrolling and overscroll containment. */
+    scrollable?: boolean;
+    /** Physical divider edges in canonical top/right/bottom/left order. */
+    dividerSides?: DividerSides;
+    className?: string;
+}
+/** A stretch-aligned vertical stack with optional gap, flex, scroll, and dividers. */
+declare function List({ children, gap, flex, scrollable, dividerSides, className, }: ListProps): kerfjs.SafeHtml;
 
-export { MenuHeader, type MenuHeaderProps };
+export { CssFlex, CssFlexKeyword, CssLength, DividerSides, List, type ListProps, UiSpaceName };
 ```
 
-## `@kerfjs/ui/menu-action-row`
+## `@kerfjs/ui/list-action-row`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
 
-type MenuActionRowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListActionRowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
     'data-has-icon'?: never;
     'data-multiline'?: never;
+    'data-density'?: never;
+    'data-divider'?: never;
+    'data-busy'?: never;
+    'data-trailing-visibility'?: never;
     'data-state'?: never;
     'data-selected'?: never;
     'data-pressed'?: never;
 }>;
-type MenuActionRowTrailingAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListActionRowTrailingAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
@@ -145,9 +381,14 @@ type MenuActionRowTrailingAttributes = Readonly<Record<`data-${string}`, string
     'aria-controls'?: string;
     'aria-haspopup'?: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | 'true';
 }>;
-interface MenuActionRowProps {
+interface ListActionRowProps {
     /** Visible dormant content for the primary button. Must not contain interactive descendants. */
     label: string | SafeHtml;
+    description?: string | SafeHtml;
+    status?: string | SafeHtml;
+    busy?: boolean;
+    density?: 'standard' | 'compact';
+    divider?: 'none' | 'before' | 'after' | 'both';
     /** Decorative dormant content for the primary button. Must not contain interactive descendants. */
     icon?: SafeHtml;
     action: string;
@@ -160,44 +401,58 @@ interface MenuActionRowProps {
     state?: string;
     disabled?: boolean;
     tabIndex?: number;
+    /** Render as an unanimated loading skeleton, disabling both actions. */
+    placeholder?: boolean;
     trailingAction: string;
     trailingActionLabel: string;
     /** Decorative dormant content for the trailing button. Must not contain interactive descendants. */
     trailingActionIcon: SafeHtml;
     trailingActionDisabled?: boolean;
     trailingActionTitle?: string;
+    trailingActionVisibility?: 'always' | 'interaction';
     className?: string;
-    style?: string;
-    rootAttributes?: MenuActionRowRootAttributes;
-    trailingActionAttributes?: MenuActionRowTrailingAttributes;
+    rootAttributes?: ListActionRowRootAttributes;
+    trailingActionAttributes?: ListActionRowTrailingAttributes;
 }
-declare function MenuActionRow({ label, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, className, style, rootAttributes, trailingActionAttributes }: MenuActionRowProps): SafeHtml;
+declare function ListActionRow({ label, description, status, busy, density, divider, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, trailingActionVisibility, className, rootAttributes, trailingActionAttributes, }: ListActionRowProps): SafeHtml;
 
-export { MenuActionRow, type MenuActionRowProps };
+export { ListActionRow, type ListActionRowProps };
 ```
 
-## `@kerfjs/ui/menu-item`
+## `@kerfjs/ui/list-item`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-type MenuItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
     'data-has-icon'?: never;
+    'data-has-description'?: never;
     'data-multiline'?: never;
+    'data-density'?: never;
+    'data-divider'?: never;
+    'data-busy'?: never;
     'data-state'?: never;
 }>;
-interface MenuItemProps {
+interface ListItemProps {
     label: string | SafeHtml;
+    /** App-owned supporting text rendered in the component's stable label stack. */
+    description?: string | SafeHtml;
     icon?: SafeHtml;
-    trailing?: SafeHtml;
+    trailing?: KerfUiContent;
+    /** Dormant status metadata rendered before trailing content. */
+    status?: string | SafeHtml;
+    /** Show a progress indicator and expose the row as busy without replacing its content. */
+    busy?: boolean;
+    density?: 'standard' | 'compact';
+    divider?: 'none' | 'before' | 'after' | 'both';
     selected?: boolean;
     action: string;
     itemId?: string;
     className?: string;
-    style?: string;
     pressed?: boolean;
     accessibleLabel?: string;
     title?: string;
@@ -205,66 +460,91 @@ interface MenuItemProps {
     state?: string;
     disabled?: boolean;
     tabIndex?: number;
-    rootAttributes?: MenuItemRootAttributes;
+    /** Render the row as an unanimated loading skeleton, disabling its action. */
+    placeholder?: boolean;
+    rootAttributes?: ListItemRootAttributes;
 }
-declare function MenuItem({ label, icon, trailing, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, rootAttributes }: MenuItemProps): SafeHtml;
+declare function ListItem({ label, description, icon, trailing, status, busy, density, divider, selected, action, itemId, className, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes, }: ListItemProps): SafeHtml;
 
-export { MenuItem, type MenuItemProps };
+export { ListItem, type ListItemProps };
 ```
 
-## `@kerfjs/ui/page-header`
+## `@kerfjs/ui/list-inset-control`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-interface PageHeaderProps {
-    title: string | SafeHtml;
-    action?: SafeHtml;
+interface ListInsetControlProps {
+    /** Control(s) that own their own border and padding (e.g. an input, a `wa-*`). */
+    children: KerfUiContent;
+    className?: string;
 }
-declare function PageHeader({ title, action }: PageHeaderProps): SafeHtml;
+/**
+ * Insets a control into a pane/list content region: an 8px inline margin (so its
+ * edges line up with `.kui-content` items) and a stretch flex row with an 8px gap.
+ * Use it for controls that carry their own border and padding but no outer margin
+ * — the wrapper adds only the alignment margin and layout, not a second inset.
+ */
+declare function ListInsetControl({ children, className, }: ListInsetControlProps): kerfjs.SafeHtml;
 
-export { PageHeader, type PageHeaderProps };
+export { ListInsetControl, type ListInsetControlProps };
 ```
 
-## `@kerfjs/ui/dialog-header`
+## `@kerfjs/ui/list-inset-text`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-interface DialogHeaderProps {
-    title: string;
-    titleId: string;
-    summary?: string;
-    summaryId?: string;
-    icon?: SafeHtml;
-    iconClassName?: string;
-    actions?: SafeHtml;
-    actionsLabel?: string;
+interface ListInsetTextProps {
+    /** Text (or inline content) that carries no margin, border, or padding of its own. */
+    children: KerfUiContent | string;
+    /**
+     * 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;
 }
-declare function DialogHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions, actionsLabel }: DialogHeaderProps): SafeHtml;
+/**
+ * Gives bare text the content-item geometry — an 8px inline margin, a 1px
+ * 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
+ * space for tight text layout.
+ */
+declare function ListInsetText({ children, horizontalOnly, className, }: ListInsetTextProps): kerfjs.SafeHtml;
 
-export { DialogHeader, type DialogHeaderProps };
+export { ListInsetText, type ListInsetTextProps };
 ```
 
 ## `@kerfjs/ui/value-table`
 
 ```ts
+import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface ValueTableRowProps {
     label: string | SafeHtml;
     value: string | SafeHtml;
     icon?: SafeHtml;
     className?: string;
+    /** Render the value as an unanimated loading skeleton, keeping the field label. */
+    placeholder?: boolean;
 }
-declare function ValueTableRow({ label, value, icon, className }: ValueTableRowProps): SafeHtml;
+declare function ValueTableRow({ label, value, icon, className, placeholder, }: ValueTableRowProps): SafeHtml;
 
 interface ValueTableProps {
     label: string;
     className?: string;
-    children: SafeHtml | readonly SafeHtml[];
+    children: KerfUiContent;
 }
-declare function ValueTable({ label, className, children }: ValueTableProps): SafeHtml;
+declare function ValueTable({ label, className, children, }: ValueTableProps): kerfjs.SafeHtml;
 
 export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProps };
 ```
@@ -273,6 +553,7 @@ export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProp
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type AppTabRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -282,48 +563,80 @@ type AppTabRootAttributes = Readonly<Record<`data-${string}`, string | undefined
     'data-tab-dragging'?: never;
     'data-tab-drop-position'?: never;
 }>;
+type AppTabPresentation = 'pill' | 'segmented' | 'icon-only';
+type AppTabSize = 'default' | 'compact';
 interface AppTabProps {
     id: string;
     name: string;
     selected?: boolean;
     closable?: boolean;
     draggable?: boolean;
-    leading?: SafeHtml;
-    trailing?: SafeHtml;
+    leading?: KerfUiContent;
+    trailing?: KerfUiContent;
+    /** Visual treatment within a TabBar. Icon-only tabs retain `name` as their accessible name. */
+    presentation?: AppTabPresentation;
+    /** Compact tabs use the 32px application-rail height. */
+    size?: AppTabSize;
+    /** Maximum visible label width in CSS pixels before ellipsis. */
+    labelMaxWidth?: number;
     /** Decorative dormant content for the close button. Must not contain interactive descendants. */
     closeIcon?: SafeHtml;
     selectAction?: string;
     closeAction?: string;
     className?: string;
+    /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
+    placeholder?: boolean;
     rootAttributes?: AppTabRootAttributes;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, rootAttributes }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, presentation, size, labelMaxWidth, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes, }: AppTabProps): SafeHtml;
 
-export { AppTab, type AppTabProps };
+export { AppTab, type AppTabPresentation, type AppTabProps, type AppTabSize };
 ```
 
 ## `@kerfjs/ui/tab-bar`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
+type TabActivation = 'automatic' | 'manual';
+type TabBarAllocation = 'intrinsic' | 'fill';
+type TabBarPresentation = 'rail' | 'segmented' | 'inspector';
+type TabBarTrailingPlacement = 'separate' | 'adjacent';
 interface TabBarProps {
     id: string;
     label: string;
-    children: SafeHtml | readonly SafeHtml[];
-    leading?: SafeHtml;
-    trailing?: SafeHtml;
+    children: KerfUiContent;
+    leading?: KerfUiContent;
+    trailing?: KerfUiContent;
     className?: string;
+    /**
+     * Keyboard activation mode for this strip, emitted as `data-tab-activation` for
+     * `wireTabBars` to read (overrides its `activation` option). `'automatic'` (default)
+     * selects on arrow / Home / End; `'manual'` moves roving focus only and the user
+     * selects with Enter / Space / click — use it when selecting a tab is a heavy action.
+     */
+    activation?: TabActivation;
+    /** How available strip width is allocated across child AppTabs. */
+    allocation?: TabBarAllocation;
+    /** Named strip chrome for application rails, segmented tabs, or inspectors. */
+    presentation?: TabBarPresentation;
+    /** Keep a trailing action beside the final tab or at the far edge of the bar. */
+    trailingPlacement?: TabBarTrailingPlacement;
 }
 /** Render a controlled tab strip. The application owns selection, order, and persistence. */
-declare function TabBar({ id, label, children, leading, trailing, className }: TabBarProps): SafeHtml;
+declare function TabBar({ id, label, children, leading, trailing, className, activation, allocation, presentation, trailingPlacement, }: TabBarProps): kerfjs.SafeHtml;
 
-export { TabBar, type TabBarProps };
+export { type TabActivation, TabBar, type TabBarAllocation, type TabBarPresentation, type TabBarProps, type TabBarTrailingPlacement };
 ```
 
 ## `@kerfjs/ui/wire-tab-bars`
 
 ```ts
+import { TabActivation } from './tab-bar.js';
+import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';
+
 type TabReorderSource = 'pointer' | 'keyboard';
 type TabDropPosition = 'before' | 'after';
 interface TabReorder {
@@ -333,23 +646,450 @@ interface TabReorder {
     position: TabDropPosition;
     source: TabReorderSource;
 }
+
 interface WireTabBarsOptions {
     onReorder: (change: TabReorder) => void;
+    /**
+     * How arrow / Home / End keys activate tabs (default `'automatic'`):
+     * - `'automatic'` moves roving focus **and** selects the focused tab (clicks it).
+     * - `'manual'` moves roving focus only; the user selects with Enter / Space / click
+     *   (the ARIA Tabs manual-activation pattern). Use this when activation is a heavy or
+     *   side-effecting action (e.g. a tab that loads a project) so arrowing through the
+     *   strip doesn't trigger it on every tab.
+     *
+     * A per-bar `data-tab-activation="manual" | "automatic"` attribute (see the `TabBar`
+     * `activation` prop) overrides this option for that strip.
+     */
+    activation?: TabActivation;
 }
 declare function reorderTabs<T>(items: readonly T[], getId: (item: T) => string, sourceId: string, targetId: string, position: TabDropPosition): T[];
 /** Wire reordering and keyboard navigation while leaving controlled state in the application. */
-declare function wireTabBars(root: HTMLElement | Document, { onReorder }: WireTabBarsOptions): () => void;
+declare function wireTabBars(root: HTMLElement | Document, { onReorder, activation }: WireTabBarsOptions): () => void;
+
+export { TabActivation, type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };
+```
+
+## `@kerfjs/ui/nav-stack`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/**
+ * One entry in a {@link NavStack}. The app owns the stack as an array (usually a
+ * signal); `NavStack` renders it and `wireNavStack` animates the transitions.
+ */
+interface NavStackView {
+    /** Stable identity for keyed reconcile and transition direction. */
+    key: string;
+    content: KerfUiContent;
+    /** Title shown in the top toolbar for this view. */
+    title?: string;
+    /** 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;
+}
+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"). */
+    backLabel?: string;
+    /** 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. */
+    bottomToolbar?: KerfUiContent;
+    className?: string;
+}
+/**
+ * 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.
+ */
+declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className, }: NavStackProps): kerfjs.SafeHtml;
+
+export { NavStack, type NavStackProps, type NavStackView };
+```
+
+## `@kerfjs/ui/wire-nav-stack`
+
+```ts
+interface WireNavStackOptions {
+    /** Invoked when the back control is activated. The app pops its own stack. */
+    onBack?: () => void;
+    /** Transition duration in ms (default 200). Set 0 to disable animation. */
+    duration?: number;
+}
+/**
+ * Animate a `NavStack`'s push/pop transitions and wire its back control. The app
+ * owns the stack (a signal of `NavStackView[]`) and re-renders `NavStack` when it
+ * changes; this helper slides the content and settles the chrome across each
+ * change, moves focus into every new top view, restores that view's last focused
+ * descendant on pop, and calls `onBack` when the back control is used. Mark a
+ * preferred initial target with `data-nav-focus`; otherwise the first focusable
+ * descendant (or the view itself) receives focus. Returns a disposer.
+ */
+declare function wireNavStack(root: Element, options?: WireNavStackOptions): () => void;
+
+export { type WireNavStackOptions, wireNavStack };
+```
+
+## `@kerfjs/ui/split-view`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+interface SplitViewResizable {
+    size: number;
+    min: number;
+    max: number;
+}
+interface SplitViewProps {
+    id: string;
+    label: string;
+    /** The list (primary) pane. */
+    list: KerfUiContent;
+    /** The detail (secondary) pane. */
+    detail: KerfUiContent;
+    /**
+     * Compact ("one pane at a time") classes — a handset or portrait tablet.
+     * Derive from `deviceClass().value.compact`. When true the split collapses to
+     * a `NavStack`: the list is the root and the detail is pushed over it.
+     */
+    compact?: boolean;
+    /** In compact mode, whether the detail is currently pushed over the list. */
+    detailActive?: boolean;
+    /** Title/label for the list (compact NavStack root + region label). */
+    listTitle?: string;
+    /** Title/label for the detail (compact NavStack pushed view + region label). */
+    detailTitle?: string;
+    /** Back label for the compact NavStack (default "Back"). */
+    backLabel?: string;
+    /** A resizable separator on roomy classes (min/max px). Omit for a fixed split. */
+    resizable?: SplitViewResizable;
+    className?: string;
+}
+/**
+ * A list-detail split. On roomy classes it shows both panes side
+ * by side with an optional resizable separator; on compact classes it collapses
+ * to a `NavStack` (list → detail). See `docs/23-app-layouts.md` §3.2. Compose the
+ * resizable wiring with `wireResizableRegions` and the compact back with
+ * `wireNavStack`.
+ */
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className, }: SplitViewProps): kerfjs.SafeHtml;
+
+export { SplitView, type SplitViewProps, type SplitViewResizable };
+```
+
+## `@kerfjs/ui/pane`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/** Logical sides that can show a {@link Pane} separator. */
+type PaneSeparatorSide = 'block-start' | 'block-end' | 'inline-start' | 'inline-end';
+/** Semantic root elements supported by {@link Pane}. */
+type PaneElement = 'article' | 'aside' | 'div' | 'main' | 'section';
+/** Semantic elements supported by the scrolling content slot. */
+type PaneContentElement = 'div' | 'main' | 'nav' | 'section';
+type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-separator-block-start'?: never;
+    'data-separator-block-end'?: never;
+    'data-separator-inline-start'?: never;
+    'data-separator-inline-end'?: never;
+}>;
+interface PaneProps {
+    /** Optional fixed chrome above the scrolling content, arranged vertically. */
+    header?: KerfUiContent;
+    /** The pane's primary vertical, scrolling content stack. */
+    children?: KerfUiContent;
+    /** Optional fixed chrome below the scrolling content. */
+    footer?: KerfUiContent;
+    /** Root semantics. Defaults to `div`. */
+    element?: PaneElement;
+    /** Scrolling content semantics. Defaults to `div`. */
+    contentElement?: PaneContentElement;
+    /** Independent logical-edge separator lines. Defaults to none. */
+    separators?: readonly PaneSeparatorSide[];
+    id?: string;
+    /** Accessible name for a landmark root such as `aside` or `main`. */
+    label?: string;
+    /** Accessible name for a landmark scrolling slot such as `nav`. */
+    contentLabel?: string;
+    className?: string;
+    headerClassName?: string;
+    contentClassName?: string;
+    footerClassName?: string;
+    /** Safe `data-*` metadata; Pane-owned structural attributes remain protected. */
+    rootAttributes?: PaneRootAttributes;
+}
+/**
+ * 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, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, }: PaneProps): kerfjs.SafeHtml;
+
+export { Pane, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
+```
+
+## `@kerfjs/ui/workbench`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/** A collapsible Workbench panel — a side rail or the bottom drawer. */
+interface WorkbenchPanel {
+    content: KerfUiContent;
+    /** Whether the panel is currently collapsed (the app owns this). */
+    collapsed?: boolean;
+    /** Rail width, or drawer height, in px. Overrides the CSS default. */
+    size?: number;
+    /** Accessible name for the panel region. */
+    label?: string;
+    separator?: ResizableRegionSeparator;
+    collapseMotion?: ResizableRegionCollapseMotion;
+    contentOverflow?: ResizableRegionContentOverflow;
+    presentation?: ResizableRegionPresentation;
+    /** Control shown in a safe-area-aware viewport corner while collapsed. */
+    restoreControl?: SafeHtml;
+    restorePosition?: ResizableRegionRestorePosition;
+}
+interface WorkbenchProps {
+    id: string;
+    label: string;
+    /** The central work area. */
+    main: KerfUiContent;
+    leftRail?: WorkbenchPanel;
+    rightRail?: WorkbenchPanel;
+    bottomDrawer?: WorkbenchPanel;
+    className?: string;
+}
+/**
+ * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and
+ * bottom drawer around a central work area (any absent). Collapsing snaps the
+ * panel's track to zero in one reflow while its fixed-size content slides out via
+ * a composited transform — the instant-width / sliding-content technique, so the
+ * work area relayouts once, not per frame. Bottom-drawer content stays anchored
+ * to the shell's stable bottom edge throughout that transition. The app owns
+ * each `collapsed` flag; the collapse is pure CSS (no wire). See
+ * `docs/23-app-layouts.md` §3.3.
+ */
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className, }: WorkbenchProps): SafeHtml;
+
+export { Workbench, type WorkbenchPanel, type WorkbenchProps };
+```
+
+## `@kerfjs/ui/collapsible-panel`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { LucideIcon } from './lucide-icon.js';
+import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import 'lucide';
+
+/** Which edge a {@link CollapsiblePanel} docks to. */
+type CollapsiblePanelSide = 'left' | 'right' | 'bottom';
+/**
+ * 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.
+ */
+declare function collapsiblePanelToggleIcon(side: CollapsiblePanelSide, collapsed: boolean): {
+    icon: Parameters<typeof LucideIcon>[0]['icon'];
+    name: string;
+};
+interface CollapsiblePanelToggleProps {
+    /** The panel this toggle controls. */
+    side: CollapsiblePanelSide;
+    /** The panel's current collapsed state (drives the icon direction). */
+    collapsed: boolean;
+    /** `data-action` the button carries so `wireSidebar` can delegate its click. */
+    action: string;
+    /** The panel id the button targets (`data-tab-panel`-style: `data-collapsible-panel`). */
+    panelId?: string;
+    /** Accessible label; defaults to "Collapse"/"Expand". */
+    label?: string;
+    className?: string;
+}
+/**
+ * A standard collapse/expand toggle button for a {@link CollapsiblePanel}: the
+ * recognizable per-side icon (see {@link collapsiblePanelToggleIcon}) plus the
+ * `data-action` / `aria-expanded` `wireSidebar` reads. Placement is the app's —
+ * put it in the panel's own header (to collapse) and somewhere always-visible
+ * (to expand while collapsed).
+ */
+declare function CollapsiblePanelToggle({ side, collapsed, action, panelId, label, className, }: CollapsiblePanelToggleProps): SafeHtml;
+interface CollapsiblePanelProps {
+    /** A stable id for the panel — `wireSidebar` targets it and toggles reference it. */
+    id: string;
+    /** Which edge the panel docks to: a left/right rail or a bottom drawer. */
+    side: CollapsiblePanelSide;
+    /** Whether the panel is currently collapsed (the app owns this signal). */
+    collapsed?: boolean;
+    /** Rail width or drawer height in px. Overrides the CSS default. */
+    size?: number;
+    /** Accessible label for the panel region. */
+    label?: string;
+    /** Panel content. */
+    children?: KerfUiContent;
+    separator?: ResizableRegionSeparator;
+    collapseMotion?: ResizableRegionCollapseMotion;
+    contentOverflow?: ResizableRegionContentOverflow;
+    presentation?: ResizableRegionPresentation;
+    /** Control shown in a safe-area-aware viewport corner while collapsed. */
+    restoreControl?: SafeHtml;
+    restorePosition?: ResizableRegionRestorePosition;
+    className?: string;
+}
+/**
+ * A standalone collapsible side rail or bottom drawer, outside the full
+ * {@link Workbench} shell. It owns only the presentation: a fixed-size content
+ * area that stays laid out while the panel's track snaps to zero and the content
+ * slides out via `transform` (one reflow, composited — the same technique
+ * `Workbench` and the catalog sidebar use). Bottom-drawer content stays anchored
+ * to the panel's fixed bottom edge, so the track cannot move its layout origin
+ * underneath the transform transition. The app owns the `collapsed` signal;
+ * pair it with `wireSidebar` for the toggle, focus, compact-overlay, keyboard,
+ * and persistence semantics, and with `CollapsiblePanelToggle` for the standard
+ * affordance. See `docs/24-collapsible-panel.md`.
+ */
+declare function CollapsiblePanel({ id, side, collapsed, size, label, children, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
+
+export { CollapsiblePanel, type CollapsiblePanelProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, collapsiblePanelToggleIcon };
+```
+
+## `@kerfjs/ui/wire-sidebar`
+
+```ts
+import { Signal, ReadonlySignal } from 'kerfjs';
+import { DeviceClass } from './device-class.js';
+
+/** Minimal `localStorage`-shaped store, so the persistence hook is testable. */
+interface SidebarStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+interface WireSidebarPanel {
+    /** The panel id — matches `CollapsiblePanel`'s `id` and a toggle's `panelId`. */
+    id: string;
+    /** The app-owned collapsed signal. `wireSidebar` reads it (focus, overlay) and
+     *  writes it (toggle, Escape, backdrop, persistence). */
+    collapsed: Signal<boolean>;
+    /** `data-action` value the panel's toggle button(s) carry. */
+    toggleAction: string;
+    /** When set, the collapsed state is loaded from and saved to `storage` under
+     *  this key (a persistence hook), so the panel remembers its state. */
+    storageKey?: string;
+}
+interface WireSidebarOptions {
+    panels: readonly WireSidebarPanel[];
+    /**
+     * When provided, the sidebar adopts a compact **overlay** presentation while
+     * `deviceClass.compact` is true: an open panel floats over the content with a
+     * dismissable backdrop, Escape and backdrop-click collapse it, and focus is
+     * trapped within the open panel (the ARIA dialog pattern). Without it the panel
+     * is always inline.
+     */
+    deviceClass?: ReadonlySignal<DeviceClass>;
+    /** Compact devices either overlay the panels (default) or hide them in favor
+     *  of an application-owned responsive replacement. */
+    compactPresentation?: 'overlay' | 'hidden';
+    /** Collapse the other panels when one opens in compact overlay mode. */
+    exclusiveCompact?: boolean;
+    /** Persistence store (default `globalThis.localStorage`, if present). */
+    storage?: SidebarStorage;
+}
+/**
+ * The reusable sidebar-semantics layer for {@link CollapsiblePanel}s: toggle
+ * delegation with focus restore, focus-into on open, an optional compact overlay
+ * (backdrop + Escape + focus trap) driven by {@link deviceClass}, and an optional
+ * persistence hook. The app owns each `collapsed` signal and the layout; this wire
+ * owns the interaction. Returns a disposer. See `docs/24-collapsible-panel.md`.
+ */
+declare function wireSidebar(root: HTMLElement, { panels, deviceClass, compactPresentation, exclusiveCompact, storage, }: WireSidebarOptions): () => void;
 
-export { type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };
+export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wireSidebar };
+```
+
+## `@kerfjs/ui/tab-scaffold`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+interface TabScaffoldTab<Id extends string = string> {
+    id: Id;
+    label: string;
+    /** Decorative icon shown above the label in the bottom bar. */
+    icon?: SafeHtml;
+    /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */
+    content: KerfUiContent;
+}
+interface TabScaffoldProps<Id extends string = string> {
+    id: string;
+    /** Accessible name for the tab bar. */
+    label: string;
+    tabs: readonly TabScaffoldTab<Id>[];
+    /** The controlled active tab id (the app owns selection). */
+    active: NoInfer<Id>;
+    className?: string;
+}
+/**
+ * A mobile-first, iOS-like bottom tab scaffold: a bottom tab bar that switches
+ * between major sections, each tab keeping its own content (usually a `NavStack`)
+ * mounted so its stack and scroll survive a switch. Controlled — the app owns
+ * `active`; wire selection with `@kerfjs/ui/wire-tab-scaffold`'s `wireTabScaffold`.
+ * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of
+ * a bottom bar. See `docs/23-app-layouts.md` §3.4.
+ */
+declare function TabScaffold<Id extends string>({ id, label, tabs, active, className, }: TabScaffoldProps<Id>): SafeHtml;
+
+export { TabScaffold, type TabScaffoldProps, type TabScaffoldTab };
+```
+
+## `@kerfjs/ui/wire-tab-scaffold`
+
+```ts
+interface WireTabScaffoldOptions {
+    /** Invoked with the selected tab id when a bottom-bar tab is activated. */
+    onSelect: (tabId: string) => void;
+}
+/**
+ * Wire a `TabScaffold`'s bottom tab bar: clicking a tab calls `onSelect` with its
+ * id (the app then updates its controlled `active`). Returns a disposer.
+ */
+declare function wireTabScaffold(root: Element, options: WireTabScaffoldOptions): () => void;
+
+export { type WireTabScaffoldOptions, wireTabScaffold };
 ```
 
 ## `@kerfjs/ui/resizable-region`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type ResizableRegionAxis = 'horizontal' | 'vertical';
 type ResizableRegionEdge = 'start' | 'end';
+type ResizableRegionSeparator = 'auto' | 'hidden';
+type ResizableRegionCollapseMotion = 'none' | 'slide' | 'fade-slide';
+type ResizableRegionContentOverflow = 'clip' | 'auto' | 'visible';
+type ResizableRegionPresentation = 'inline' | 'overlay' | 'hidden';
+type ResizableRegionRestorePosition = 'bottom-start' | 'bottom-end';
 interface ResizableRegionProps {
     id: string;
     label: string;
@@ -360,15 +1100,27 @@ interface ResizableRegionProps {
     edge?: ResizableRegionEdge;
     collapsed?: boolean;
     transitioning?: boolean;
+    /** Whether the separator line is painted. The resize hit target remains available. */
+    separator?: ResizableRegionSeparator;
+    /** Keep the track change instant while optionally sliding the fixed-size content. */
+    collapseMotion?: ResizableRegionCollapseMotion;
+    /** Overflow policy for content such as an open popup inside a bottom drawer. */
+    contentOverflow?: ResizableRegionContentOverflow;
+    /** Inline layout, an edge overlay, or a responsive replacement that removes the region. */
+    presentation?: ResizableRegionPresentation;
+    /** Always-available control rendered while collapsed, outside the clipped region. */
+    restoreControl?: SafeHtml;
+    /** Safe-area-aware viewport corner for `restoreControl`. */
+    restorePosition?: ResizableRegionRestorePosition;
     /** Decorative dormant content for the separator handle. Must not contain interactive descendants. */
     handleIcon?: SafeHtml;
-    children: SafeHtml | SafeHtml[];
+    children: KerfUiContent;
 }
 declare const clampRegionSize: (size: number, min: number, max: number) => number;
 declare const resizeRegionFromPointer: (startSize: number, delta: number, edge: ResizableRegionEdge) => number;
-declare function ResizableRegion({ id, label, size, min, max, axis, edge, collapsed, transitioning, handleIcon, children }: ResizableRegionProps): SafeHtml;
+declare function ResizableRegion({ id, label, size, min, max, axis, edge, collapsed, transitioning, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, handleIcon, children, }: ResizableRegionProps): SafeHtml;
 
-export { ResizableRegion, type ResizableRegionAxis, type ResizableRegionEdge, type ResizableRegionProps, clampRegionSize, resizeRegionFromPointer };
+export { ResizableRegion, type ResizableRegionAxis, type ResizableRegionCollapseMotion, type ResizableRegionContentOverflow, type ResizableRegionEdge, type ResizableRegionPresentation, type ResizableRegionProps, type ResizableRegionRestorePosition, type ResizableRegionSeparator, clampRegionSize, resizeRegionFromPointer };
 ```
 
 ## `@kerfjs/ui/wire-resizable-regions`
@@ -386,78 +1138,472 @@ interface WireResizableRegionsOptions {
     onCommit: (change: ResizeCommit) => void;
 }
 /** Wire pointer and separator-keyboard behavior for every ResizableRegion below root. */
-declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPreview, onCommit }: WireResizableRegionsOptions): () => void;
+declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPreview, onCommit, }: WireResizableRegionsOptions): () => void;
 
 export { type ResizeCommit, type WireResizableRegionsOptions, wireResizableRegions };
 ```
 
-## `@kerfjs/ui/segmented-control`
+## `@kerfjs/ui/device-class`
+
+```ts
+import { ReadonlySignal } from 'kerfjs';
+
+/**
+ * Reactive device-class detection for `@kerfjs/ui` (see `docs/23-app-layouts.md`
+ * §2). `deviceClass()` returns a `ReadonlySignal<DeviceClass>` describing the
+ * current viewport as a size bucket × orientation × viewport-segment count, so a
+ * layout can pick its presentation reactively instead of hand-wiring `matchMedia`.
+ *
+ * One shared viewport source backs every reader; the pure `classifyViewport`
+ * core is DOM-free and directly unit-tested.
+ */
+type DeviceSize = 'xs-mobile' | 'mobile' | 'tablet' | 'desktop' | 'xl-desktop';
+type DeviceOrientation = 'portrait' | 'landscape';
+/** Minimum widths (px) at which each larger bucket begins. `xs-mobile` is 0. */
+interface DeviceBreakpoints {
+    mobile: number;
+    tablet: number;
+    desktop: number;
+    'xl-desktop': number;
+}
+interface DeviceClass {
+    size: DeviceSize;
+    orientation: DeviceOrientation;
+    /** Horizontal viewport segments (foldables / dual-screen); 1 on ordinary devices. */
+    segments: number;
+    /** Vertical viewport segments; 1 on ordinary devices. */
+    verticalSegments: number;
+    /** Small phones — `xs-mobile` or `mobile`. */
+    handset: boolean;
+    /** "One pane at a time" — a handset or a portrait tablet. */
+    compact: boolean;
+    /** True when the current size is `size` or larger, e.g. `atLeast('tablet')`. */
+    atLeast(size: DeviceSize): boolean;
+}
+/** A raw viewport snapshot, before breakpoints are applied. */
+interface Viewport {
+    width: number;
+    height: number;
+    segments: number;
+    verticalSegments: number;
+}
+interface DeviceClassOptions {
+    /** Override any of the default bucket thresholds. */
+    breakpoints?: Partial<DeviceBreakpoints>;
+    /** The viewport assumed when there is no DOM (SSR). Defaults to 1024×768, one segment. */
+    ssr?: Partial<Viewport>;
+}
+declare const DEFAULT_BREAKPOINTS: DeviceBreakpoints;
+/**
+ * Classify a raw viewport into a {@link DeviceClass}. Pure and DOM-free — the
+ * single source of truth for the bucketing rules.
+ */
+declare function classifyViewport(width: number, orientation: DeviceOrientation, segments?: number, verticalSegments?: number, breakpoints?: DeviceBreakpoints): DeviceClass;
+/**
+ * A reactive signal of the current {@link DeviceClass}. Reading it inside an
+ * `effect`/`computed` re-runs when the viewport crosses a breakpoint, rotates,
+ * or changes its segment count. Without a DOM it resolves to `options.ssr`
+ * (default 1024×768, landscape, one segment).
+ */
+declare function deviceClass(options?: DeviceClassOptions): ReadonlySignal<DeviceClass>;
+
+export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type DeviceClassOptions, type DeviceOrientation, type DeviceSize, type Viewport, classifyViewport, deviceClass };
+```
+
+## `@kerfjs/ui/catalog`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+/** A reference link shown in the detail footer for the active entry. */
+interface CatalogResource {
+    label: string;
+    href: string;
+    /** Optional monospace detail (e.g. a file path) shown after the label. */
+    detail?: string;
+}
+/** A related entry offered in the detail footer's "Related entries" popup menu. */
+interface CatalogRelated {
+    id: string;
+    name: string;
+    /** Group heading in the menu, e.g. "Uses" / "Used by". */
+    group: string;
+}
+interface CatalogEntry {
+    id: string;
+    name: string;
+    description?: string;
+    /** Short metadata tags shown at the trailing edge of the sidebar row. */
+    tags?: readonly string[];
+    resources?: readonly CatalogResource[];
+    related?: readonly CatalogRelated[];
+}
+interface CatalogSection {
+    category: string;
+    entries: readonly CatalogEntry[];
+}
+/**
+ * A secondary group of sections shown below the primary sidebar sections with a
+ * quieter "ecosystem" treatment (e.g. third-party components). Optionally
+ * collapsible — the app owns `expanded` and toggles it from `wireCatalog`'s
+ * `onToggleSecondary`.
+ */
+interface CatalogSecondaryGroup {
+    label: string;
+    sections: readonly CatalogSection[];
+    /** When true, the group's label is a disclosure toggle controlling `expanded`. */
+    collapsible?: boolean;
+    /** Whether the group is expanded (controlled). Ignored unless `collapsible`. */
+    expanded?: boolean;
+}
+interface CatalogBrand {
+    title: string;
+    subtitle?: string;
+    /** Logo image URL (rendered decorative). Omit for a text-only brand. */
+    logoUrl?: string;
+}
+interface CatalogProps {
+    brand: CatalogBrand;
+    sections: readonly CatalogSection[];
+    /** The controlled active entry id — the app owns this signal. */
+    active: string;
+    /** The rendered preview for the active entry; the app computes it from `active`. */
+    content: KerfUiContent;
+    /** Whether the sidebar is collapsed (controlled). */
+    collapsed?: boolean;
+    /** Current theme; when set, a theme toggle is shown that switches to the opposite. Omit to hide it. */
+    theme?: 'light' | 'dark';
+    /** Extra header controls placed before the theme toggle (each a `ToolbarControlGroup`). */
+    headerActions?: KerfUiContent;
+    /** A secondary "ecosystem" group of sections below the primary category groups. */
+    secondarySections?: CatalogSecondaryGroup;
+    /** Extra sidebar content below the category groups (and the secondary group). */
+    sidebarFooter?: KerfUiContent;
+    /** Status line content shown at the start of the detail footer. */
+    status?: KerfUiContent;
+    /**
+     * Whether to highlight specimens' computed borders (or transparent outer
+     * bounds) and non-zero margins. Pass a boolean (rather than omitting the
+     * prop) when the active entry can switch between component and composition
+     * previews; `wireCatalogGeometryOverlay` keeps the overlay synchronized.
+     */
+    geometryOverlay?: boolean;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    /** Action fired by the secondary group's disclosure toggle (when collapsible). */
+    toggleSecondaryAction?: string;
+    className?: string;
+}
+/**
+ * A reusable component-catalog shell: a collapsible category sidebar, a titled
+ * detail stage that renders the active entry's preview, and a footer with
+ * reference links and a related-entry popup menu. Built entirely from public
+ * `@kerfjs/ui` primitives. Controlled and stateless — the app owns the `active`,
+ * `collapsed`, and `theme` signals and computes `content` from `active` in its own
+ * render; wire the sidebar/collapse/theme actions with `wireCatalog`.
+ */
+declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, }: CatalogProps): SafeHtml;
+/**
+ * How a {@link CatalogExample}'s content aligns its visible left edge with the
+ * example's `ListHeader` label (which sits 16px in — 8px title + 8px label):
+ * - `'glyph'` — a bare glyph/text specimen with no inline geometry insets the full 16px.
+ * - `'inline-control'` — a control that already carries ~8px of its own inline padding insets 8px so its content lands on the same line.
+ * - `'none'` — a content-item / composition that owns its geometry and already aligns; no inset (default).
+ */
+type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
+type CatalogExampleRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-catalog-example'?: never;
+    'data-catalog-example-stack'?: never;
+    'data-catalog-example-label'?: never;
+    'data-catalog-example-note'?: never;
+    'data-align'?: never;
+}>;
+type CatalogExampleStackRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-catalog-example'?: never;
+    'data-catalog-example-stack'?: never;
+    'data-catalog-example-label'?: never;
+    'data-catalog-example-note'?: never;
+    'data-align'?: never;
+}>;
+interface CatalogExampleProps {
+    /** The example's label, shown as a `ListHeader` above the specimen. Omit for a bare specimen. */
+    label?: string;
+    /** Optional explanatory note between the label and the specimen. */
+    note?: SafeHtml | string;
+    /** Alignment inset for the specimen — see {@link CatalogExampleAlign}. Default `'none'`. */
+    align?: CatalogExampleAlign;
+    /** Safe authoring `data-*` metadata for the rendered section. Helper-owned structural attributes remain protected. */
+    rootAttributes?: CatalogExampleRootAttributes;
+    className?: string;
+    children?: KerfUiContent;
+}
+/**
+ * One labeled example in a catalog preview: a `ListHeader` label, an optional
+ * note, and the specimen. `align` insets the specimen so its visible left edge
+ * lines up with the label text, encoding the catalog's alignment rules as a
+ * first-class prop instead of per-demo CSS. The inset is published as the
+ * `--kui-catalog-example-align` custom property so a debug overlay can exclude it
+ * from a specimen's measured margin.
+ */
+declare function CatalogExample({ label, note, align, rootAttributes, className, children, }: CatalogExampleProps): SafeHtml;
+interface CatalogExampleStackProps {
+    /** Accessible label for the stack region. */
+    label?: string;
+    /** Safe authoring `data-*` metadata for the rendered stack. Helper-owned structural attributes remain protected. */
+    rootAttributes?: CatalogExampleStackRootAttributes;
+    className?: string;
+    children?: KerfUiContent;
+}
+/**
+ * A vertically-stacked group of {@link CatalogExample}s with the catalog's
+ * example rhythm. The semantic `section` becomes a named `region` when `label`
+ * is supplied; an unlabeled stack remains an ordinary grouping.
+ */
+declare function CatalogExampleStack({ label, rootAttributes, className, children, }: CatalogExampleStackProps): SafeHtml;
+
+export { Catalog, type CatalogBrand, type CatalogEntry, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, type CatalogProps, type CatalogRelated, type CatalogResource, type CatalogSecondaryGroup, type CatalogSection };
+```
+
+## `@kerfjs/ui/catalog-resources`
+
+```ts
+import { CatalogResource } from './catalog.js';
+import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';
+
+/**
+ * Standard resource labels for a Kerf catalog detail footer. Keep these labels
+ * stable across catalogs so people and AI-generated integrations see the same
+ * choices in the same vocabulary.
+ */
+type CatalogResourceKind = 'demoSource' | 'componentSource' | 'designTemplate' | 'guidance' | 'integrationGuidance';
+type CatalogGuidanceKind = 'guidance' | 'integrationGuidance';
+interface CatalogResourceTarget {
+    href: string;
+    /** Optional monospace detail, normally the repository-relative source path. */
+    detail?: string;
+}
+interface CatalogResourcesInput {
+    /** Required source for the runnable demonstration. */
+    demoSource: CatalogResourceTarget;
+    /** Source for the production component; omit for recipes and integrations. */
+    componentSource?: CatalogResourceTarget;
+    /** Optional design-tool template associated with the component. */
+    designTemplate?: CatalogResourceTarget;
+    /** Required UI or integration guidance. */
+    guidance: CatalogResourceTarget;
+    /** Use `integrationGuidance` when the component implementation is upstream. */
+    guidanceKind?: CatalogGuidanceKind;
+}
+/**
+ * Build the standard catalog resource group in its canonical order: demo,
+ * component, optional design template, then guidance.
+ */
+declare function catalogResources(input: CatalogResourcesInput): CatalogResource[];
+
+export { type CatalogGuidanceKind, type CatalogResourceKind, type CatalogResourceTarget, type CatalogResourcesInput, catalogResources };
+```
+
+## `@kerfjs/ui/wire-catalog`
+
+```ts
+interface WireCatalogOptions {
+    /** Invoked with the entry id when a sidebar item or a related-entry option is chosen. */
+    onSelect: (id: string) => void;
+    /** Invoked when the sidebar collapse/expand control is activated. */
+    onToggleSidebar?: () => void;
+    /** Invoked when the theme toggle is activated. */
+    onToggleTheme?: () => void;
+    /** Invoked when the secondary (ecosystem) group's disclosure toggle is activated. */
+    onToggleSecondary?: () => void;
+    /** When set, `?<urlParam>=<id>` is written on select via `history.replaceState`. */
+    urlParam?: string;
+    /**
+     * Reveal the chosen sidebar row after selection. `true` uses desktop-safe
+     * defaults; pass options to customize scroll alignment or the media guard.
+     */
+    revealSelection?: boolean | CatalogRevealOptions;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    toggleSecondaryAction?: string;
+}
+interface CatalogRevealOptions {
+    /** Scroll alignment within the sidebar. Default `'nearest'`. */
+    block?: ScrollLogicalPosition;
+    /** Cross-axis alignment. Default `'nearest'`. */
+    inline?: ScrollLogicalPosition;
+    /** Scroll behavior. Default `'auto'`. */
+    behavior?: ScrollBehavior;
+    /**
+     * Only reveal when this media query matches. Defaults to the Catalog's
+     * desktop layout; pass `false` to reveal at every viewport size.
+     */
+    media?: string | false;
+}
+/**
+ * Reveal one Catalog sidebar entry after the controlled render settles without
+ * moving focus. Returns a cancellation function for rapid selection changes.
+ */
+declare function revealCatalogEntry(root: HTMLElement, id: string, { block, inline, behavior, media, }?: CatalogRevealOptions): () => void;
+/**
+ * Keep a Catalog's opt-in geometry overlay synchronized with its preview.
+ * Specimens receive computed border highlights (or a dashed bound when they
+ * have no border and are transparent), while positive computed margins use
+ * devtools-style orange bands. CSS/stylesheet-only changes are observed too.
+ * Returns a disposer.
+ */
+declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
+/**
+ * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar
+ * item selection (and the related-entry popup menu), the sidebar collapse toggle, and
+ * the theme toggle. The app owns the `active`/`collapsed`/`theme` signals and updates
+ * 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;
+
+export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
+```
+
+## `@kerfjs/ui/segmented-control`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type SegmentedControlAppearance = 'filled' | 'outlined' | 'toolbar';
 type SegmentedControlShape = 'rounded' | 'pill';
 type SegmentedControlSize = 'small' | 'default';
 type SegmentedControlLayout = 'content' | 'equal';
-interface SegmentedControlChoice {
-    value: string;
+interface SegmentedControlChoice<Value extends string = string> {
+    value: Value;
     label: string;
-    content?: SafeHtml;
+    content?: KerfUiContent;
     title?: string;
     disabled?: boolean;
 }
-interface SegmentedControlProps {
+interface SegmentedControlProps<Value extends string = string> {
     id: string;
     label: string;
-    value: string;
-    choices: readonly SegmentedControlChoice[];
+    value: NoInfer<Value>;
+    choices: readonly SegmentedControlChoice<Value>[];
     action?: string;
     appearance?: SegmentedControlAppearance;
     shape?: SegmentedControlShape;
     size?: SegmentedControlSize;
     layout?: SegmentedControlLayout;
     className?: string;
+    /** Render as an unanimated loading skeleton, disabling every segment. */
+    placeholder?: boolean;
 }
-declare function SegmentedControl({ id, label, value, choices, action, appearance, shape, size, layout, className, }: SegmentedControlProps): SafeHtml;
+declare function SegmentedControl<Value extends string>({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, }: SegmentedControlProps<Value>): kerfjs.SafeHtml;
 
 export { SegmentedControl, type SegmentedControlAppearance, type SegmentedControlChoice, type SegmentedControlLayout, type SegmentedControlProps, type SegmentedControlShape, type SegmentedControlSize };
 ```
 
+## `@kerfjs/ui/select`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { CssColor } from './css-values.js';
+import { LucideNode } from './lucide-icon.js';
+import 'lucide';
+
+interface SelectChoice<Value extends string = string> {
+    value: Value;
+    label: string;
+    icon?: LucideNode;
+    iconName?: string;
+    /** Typed semantic or application-owned color for the optional icon. */
+    color?: CssColor;
+    group?: string;
+    separatorBefore?: boolean;
+}
+type SelectAccessibleName = {
+    label: string;
+    ariaLabel?: string;
+} | {
+    label?: never;
+    ariaLabel: string;
+};
+type SelectPresentation = 'form' | 'toolbar-borderless' | 'navigation';
+type SelectSize = 'default' | 'compact';
+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). */
+    placeholderText?: string;
+    /** Supporting text shown below the control and associated with its combobox. */
+    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. */
+    labelMaxWidth?: number;
+}
+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, }: SelectProps<Value>): SafeHtml;
+
+export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectPresentation, type SelectProps, type SelectSelectedPresentation, type SelectSize };
+```
+
 ## `@kerfjs/ui/state-banner`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-type StateBannerTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+type StateBannerTone = 'neutral' | 'info' | 'pop' | 'success' | 'warning' | 'danger';
+type StateBannerUrgency = 'status' | 'alert';
 interface StateBannerProps {
     title: string;
     detail?: string;
+    /** Optional compact status or count shown beside the title. */
+    badge?: string;
     icon?: SafeHtml;
-    action?: SafeHtml;
+    action?: KerfUiContent;
     tone?: StateBannerTone;
-    urgency?: 'status' | 'alert';
+    urgency?: StateBannerUrgency;
     className?: string;
+    /** Render the title, badge, and detail as unanimated loading skeletons, keeping the icon and tone. */
+    placeholder?: boolean;
 }
-declare function StateBanner({ title, detail, icon, action, tone, urgency, className }: StateBannerProps): SafeHtml;
+declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, className, placeholder, }: StateBannerProps): SafeHtml;
 
-export { StateBanner, type StateBannerProps, type StateBannerTone };
+export { StateBanner, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
 ```
 
 ## `@kerfjs/ui/empty-state`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface EmptyStateProps {
     title: string;
     detail?: string;
     icon?: SafeHtml;
-    action?: SafeHtml;
+    action?: KerfUiContent;
     busy?: boolean;
     className?: string;
 }
-declare function EmptyState({ title, detail, icon, action, busy, className }: EmptyStateProps): SafeHtml;
+declare function EmptyState({ title, detail, icon, action, busy, className, }: EmptyStateProps): SafeHtml;
 
 export { EmptyState, type EmptyStateProps };
 ```
@@ -477,10 +1623,66 @@ declare function LoadingSpinner({ className, label }: LoadingSpinnerProps): kerf
 export { LoadingSpinner, type LoadingSpinnerProps };
 ```
 
+## `@kerfjs/ui/skeleton`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { CssSize, CssLength } from './css-values.js';
+
+interface SkeletonProps {
+    /** Typed width or intrinsic sizing keyword. Defaults to filling its slot. */
+    width?: CssSize;
+    /** Typed height or intrinsic sizing keyword. Defaults to a single text line. */
+    height?: CssSize;
+    /** Typed corner-radius override. Defaults to the small radius token. */
+    radius?: CssLength;
+    /** Render this many stacked lines (the last one shorter), for multi-line text. */
+    lines?: number;
+    /** Accessible label. Omit to keep the block decorative (`aria-hidden`). */
+    label?: string;
+    className?: string;
+}
+/**
+ * A subtle, deliberately **unanimated** loading placeholder block. Use it for a
+ * value slot whose content is not yet known, on its own or via a component's
+ * `placeholder` prop. Decorative by default (`aria-hidden`); pass `label` to
+ * announce it. Sizes to its slot unless `width`/`height` are given.
+ */
+declare function Skeleton({ width, height, radius, lines, label, className, }: SkeletonProps): kerfjs.SafeHtml;
+
+export { Skeleton, type SkeletonProps };
+```
+
+## `@kerfjs/ui/sunken-panel`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+type SunkenPanelShape = 'rounded' | 'square';
+interface SunkenPanelProps {
+    children?: KerfUiContent;
+    /** Optional accessible landmark name for a distinct application region. */
+    ariaLabel?: string;
+    /** Corner shape: a rounded rectangle (default) or square corners. */
+    shape?: SunkenPanelShape;
+    className?: string;
+}
+/**
+ * A lowered application surface with one compact inset and a vertical content
+ * stack. The panel owns its background and padding; children own their own
+ * borders and internal geometry.
+ */
+declare function SunkenPanel({ children, ariaLabel, shape, className, }: SunkenPanelProps): kerfjs.SafeHtml;
+
+export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
+```
+
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchToken {
     value: string;
@@ -488,7 +1690,15 @@ interface TokenSearchToken {
     offset?: number;
     accessibleLabel?: string;
 }
-interface TokenSearchFieldProps {
+type TokenSearchEditorAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-key'?: never;
+    'data-morph-skip'?: never;
+    'data-token-search-editor'?: never;
+    'data-token-count'?: never;
+    'data-placeholder'?: never;
+}>;
+interface TokenSearchFieldBaseProps {
     id: string;
     label: string;
     query?: string;
@@ -497,48 +1707,156 @@ interface TokenSearchFieldProps {
     tokenPlaceholder?: string;
     disabled?: boolean;
     autofocus?: boolean;
-    /** Allow an empty field to render as one iconic action. */
-    collapsible?: boolean;
-    /** Keep an empty collapsible field open while the application owns focus. */
-    expanded?: boolean;
-    expandAction?: string;
-    expandLabel?: string;
-    leading?: SafeHtml;
-    trailing?: SafeHtml;
+    leading?: KerfUiContent;
+    trailing?: KerfUiContent;
     editAction?: string;
     removeAction?: string;
     clearAction?: string;
     clearLabel?: string;
     className?: string;
-    editorAttributes?: Readonly<Record<`data-${string}`, string>>;
+    editorAttributes?: TokenSearchEditorAttributes;
 }
+type TokenSearchCollapsibleProps = {
+    /** Allow an empty field to render as one iconic action. */
+    collapsible: true;
+    /** Keep an empty collapsible field open while the application owns focus. */
+    expanded?: boolean;
+    expandAction?: string;
+    expandLabel?: string;
+} | {
+    collapsible?: false;
+    expanded?: never;
+    expandAction?: never;
+    expandLabel?: never;
+};
+type TokenSearchFieldProps = TokenSearchFieldBaseProps & TokenSearchCollapsibleProps;
 interface TokenSearchFieldValue {
     query: string;
     tokens: TokenSearchToken[];
 }
-declare function TokenSearchField({ id, label, query, tokens, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, editAction, removeAction, clearAction, clearLabel, className, editorAttributes, }: TokenSearchFieldProps): SafeHtml;
+declare function TokenSearchField({ id, label, query, tokens, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, editAction, removeAction, clearAction, clearLabel, className, editorAttributes, }: TokenSearchFieldProps): kerfjs.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. */
 declare function placeTokenSearchCaret(editor: HTMLElement, offset?: number): void;
 
-export { TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValue, type TokenSearchToken, placeTokenSearchCaret, readTokenSearchField };
+export { type TokenSearchEditorAttributes, TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValue, type TokenSearchToken, placeTokenSearchCaret, readTokenSearchField };
 ```
 
 ## `@kerfjs/ui/wire-token-search-fields`
 
 ```ts
+import { Signal } from 'kerfjs';
+
 interface TokenSearchSubmit {
     id: string;
     editor: HTMLElement;
 }
+/** Reported to {@link WireTokenSearchFieldsOptions.onEdit} on every editor input. */
+interface TokenSearchEdit extends TokenSearchSubmit {
+    /**
+     * The `InputEvent` that mutated the editor — read `event.inputType` / `event.data`
+     * to gate commit behavior (e.g. only parse a chip on whitespace-terminated input)
+     * without keeping a separate `input` listener.
+     */
+    event: InputEvent;
+}
+/** Reported when adjacent-token keyboard deletion asks the app to drop a chip. */
+interface TokenSearchTokenRemoval {
+    id: string;
+    /** The `data-token-value` of the token the app should remove from its state. */
+    value: string;
+    editor: HTMLElement;
+    /** `'backward'` = the token before the caret (Backspace); `'forward'` = after (Delete). */
+    direction: 'backward' | 'forward';
+}
+/**
+ * Opt-in keyboard behavior for the atomic token chips. Off unless `keyboard` is
+ * set; each piece defaults on once opted in. The helper never mutates app state:
+ * a removal is reported through {@link TokenSearchKeyboardOptions.onRemoveToken}
+ * for the caller to apply, while caret movement past a chip is a pure ephemeral
+ * mechanic the helper performs itself.
+ */
+interface TokenSearchKeyboardBaseOptions {
+    /**
+     * From a collapsed caret with no selection, Backspace removes the token
+     * immediately before it and Delete the token immediately after — reported via
+     * `onRemoveToken` — instead of deleting a character. Default: true.
+     */
+    /**
+     * ArrowRight moves the caret past a trailing atomic token so text typed next
+     * lands after the chip. Default: true.
+     */
+    moveCaretPastToken?: boolean;
+}
+type TokenSearchKeyboardOptions = TokenSearchKeyboardBaseOptions & ({
+    removeAdjacentToken?: true;
+    /** Apply the reported removal to your controlled state, then re-render. */
+    onRemoveToken: (removal: TokenSearchTokenRemoval) => void;
+} | {
+    removeAdjacentToken: false;
+    onRemoveToken?: never;
+});
+/**
+ * Managed collapsible behavior for the iconic TokenSearchField. Every piece is on
+ * by default; disable a specific one to own it in the app. Provide `signals` to
+ * drive app-owned `expanded` signals per field id instead of helper-created ones.
+ */
+interface TokenSearchCollapsibleOptions {
+    /** Expand the field and focus its editor when the iconic trigger is activated. Default: true. */
+    expandOnActivate?: boolean;
+    /** Collapse the field when focus leaves it while it is empty. Default: true. */
+    collapseOnEmptyBlur?: boolean;
+    /** Collapse an empty field on Escape and restore focus to its trigger. Default: true. */
+    collapseOnEscape?: boolean;
+    /** Focus the editor on expand/controlled clear and the trigger on Escape-collapse. Default: true. */
+    manageFocus?: boolean;
+    /**
+     * Keep an empty field expanded when focus moves to a caller-owned surface
+     * rendered outside the field — a suggestions dropdown, date picker, or help
+     * popover shown beside it. Return true for any focus target that must NOT
+     * trigger collapse-on-empty-blur. An element carrying `data-token-search-keep-open`
+     * (or any node inside one) is always exempt, so this predicate is only needed
+     * for surfaces you cannot mark declaratively.
+     */
+    keepOpenOn?: (target: Node | null) => boolean;
+    /** App-owned `expanded` signals keyed by field id; adopted instead of helper-created. */
+    signals?: Readonly<Record<string, Signal<boolean>>>;
+}
 interface WireTokenSearchFieldsOptions {
-    onSubmit: (submission: TokenSearchSubmit) => void;
+    onSubmit?: (submission: TokenSearchSubmit) => void;
+    /** Fired on every editor `input`, after the browser mutates it, so a caller can drop its own `input` listener. */
+    onEdit?: (edit: TokenSearchEdit) => void;
+    /** Managed collapsible transient behavior. `true`/omitted = on with defaults; `false` = fully off. */
+    collapsible?: boolean | TokenSearchCollapsibleOptions;
+    /** Opt-in atomic-chip keyboard behavior (off by default). */
+    keyboard?: false | TokenSearchKeyboardOptions;
+}
+/**
+ * The value returned from {@link wireTokenSearchFields}: call it (or `dispose()`) to
+ * tear down. When collapsible behavior is managed, it also exposes the transient
+ * `expanded` state per field id so the app can read it in render, hand in its own
+ * signal, or drive it imperatively.
+ */
+interface TokenSearchFieldsHandle {
+    (): void;
+    dispose(): void;
+    /** The managed `expanded` signal for a field id (adopted or helper-created); undefined when unmanaged. */
+    expanded(id: string): Signal<boolean> | undefined;
+    /** Expand the field (and, when focus is managed, focus its editor). */
+    open(id: string): void;
+    /** Collapse the field (and, when focus is managed, restore focus to its trigger). */
+    close(id: string): void;
 }
-/** Keep TokenSearchField wrapping, submit Enter, and preserve its caret across controlled token deletion. */
-declare function wireTokenSearchFields(root: HTMLElement, { onSubmit }: WireTokenSearchFieldsOptions): () => void;
+/**
+ * Wire every TokenSearchField under `root`: submit on Enter, preserve the caret across
+ * controlled token deletion, and (by default) manage the collapsible field's transient
+ * expand/collapse/focus. Returns a {@link TokenSearchFieldsHandle} — a disposer that also
+ * exposes the managed `expanded` state per field id.
+ */
+declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard, }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
 
-export { type TokenSearchSubmit, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
+export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
 ```
 
 ## `kerfjs/actions`