@kerfjs/ui 5.0.0-beta.29 → 5.0.0-beta.30

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.29` and `kerfjs@5.0.0-beta.29`. 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.30` and `kerfjs@5.0.0-beta.30`. 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,20 @@ 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;
     /** Physical divider edges in canonical top/right/bottom/left order. Defaults to bottom. */
     dividerSides?: DividerSides;
     className?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, dividerSides, className, }: ToolbarProps): SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, dividerSides, className, }: ToolbarProps): kerfjs.SafeHtml;
 
 export { DividerSides, Toolbar, type ToolbarProps };
 ```
@@ -87,7 +168,8 @@ export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarText
 ## `@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';
@@ -97,9 +179,9 @@ type ToolbarControlGroupSize = 'default' | 'compact';
 type ToolbarControlGroupDensity = 'comfortable' | 'tight';
 type ToolbarControlGroupContent = 'icon' | 'text' | 'mixed' | 'avatar';
 type ToolbarControlGroupSelectedChrome = 'raised' | 'filled' | 'outline';
-type ToolbarControlGroupSelectedTone = 'brand' | 'neutral';
+type ToolbarControlGroupSelectedTone = 'brand' | 'neutral' | 'pop';
 interface ToolbarControlGroupProps {
-    children: SafeHtml | SafeHtml[];
+    children: KerfUiContent;
     label?: string;
     className?: string;
     expanded?: boolean;
@@ -118,8 +200,13 @@ interface ToolbarControlGroupProps {
     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, shape, size, density, content, selectedChrome, selectedTone, nestedDropdown, scrim, }: 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 ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone };
 ```
@@ -127,13 +214,14 @@ export { ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarCo
 ## `@kerfjs/ui/floating-toolbar`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+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: SafeHtml | SafeHtml[];
+    children: KerfUiContent;
     /** Accessible name for the toolbar (required — it exposes `role="toolbar"`). */
     label: string;
     /**
@@ -152,7 +240,7 @@ interface FloatingToolbarProps {
  * 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): SafeHtml;
+declare function FloatingToolbar({ children, label, position, className, }: FloatingToolbarProps): kerfjs.SafeHtml;
 
 export { FloatingToolbar, type FloatingToolbarPosition, type FloatingToolbarProps };
 ```
@@ -183,7 +271,7 @@ interface ListHeaderBaseProps {
     label: string;
     density?: 'standard' | 'compact';
     divider?: 'none' | 'before' | 'after' | 'both';
-    indicatorTone?: 'neutral' | 'accent' | 'danger';
+    indicatorTone?: 'neutral' | 'accent' | 'pop' | 'danger';
     /** Render as an unanimated loading skeleton: keep the label and action affordance, disable interaction. */
     placeholder?: boolean;
     rootAttributes?: ListHeaderRootAttributes;
@@ -239,6 +327,32 @@ declare function ListHeader({ label, count, countLabel, badge, status, density,
 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 { CssFlex, CssFlexKeyword, CssLength, DividerSides, List, type ListProps, UiSpaceName };
+```
+
 ## `@kerfjs/ui/list-action-row`
 
 ```ts
@@ -297,11 +411,10 @@ interface ListActionRowProps {
     trailingActionTitle?: string;
     trailingActionVisibility?: 'always' | 'interaction';
     className?: string;
-    style?: string;
     rootAttributes?: ListActionRowRootAttributes;
     trailingActionAttributes?: ListActionRowTrailingAttributes;
 }
-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, style, rootAttributes, trailingActionAttributes, }: ListActionRowProps): 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 { ListActionRow, type ListActionRowProps };
 ```
@@ -310,12 +423,14 @@ export { ListActionRow, type ListActionRowProps };
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 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;
@@ -327,7 +442,7 @@ interface ListItemProps {
     /** 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. */
@@ -338,7 +453,6 @@ interface ListItemProps {
     action: string;
     itemId?: string;
     className?: string;
-    style?: string;
     pressed?: boolean;
     accessibleLabel?: string;
     title?: string;
@@ -350,7 +464,7 @@ interface ListItemProps {
     placeholder?: boolean;
     rootAttributes?: ListItemRootAttributes;
 }
-declare function ListItem({ label, description, icon, trailing, status, busy, density, divider, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes, }: ListItemProps): 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 { ListItem, type ListItemProps };
 ```
@@ -358,11 +472,12 @@ export { ListItem, type ListItemProps };
 ## `@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 ListInsetControlProps {
     /** Control(s) that own their own border and padding (e.g. an input, a `wa-*`). */
-    children: SafeHtml | SafeHtml[];
+    children: KerfUiContent;
     className?: string;
 }
 /**
@@ -371,7 +486,7 @@ interface ListInsetControlProps {
  * 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): SafeHtml;
+declare function ListInsetControl({ children, className, }: ListInsetControlProps): kerfjs.SafeHtml;
 
 export { ListInsetControl, type ListInsetControlProps };
 ```
@@ -379,11 +494,12 @@ export { ListInsetControl, type ListInsetControlProps };
 ## `@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 ListInsetTextProps {
     /** Text (or inline content) that carries no margin, border, or padding of its own. */
-    children: SafeHtml | SafeHtml[] | string;
+    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
@@ -401,7 +517,7 @@ interface ListInsetTextProps {
  * Pass `horizontalOnly` to keep the horizontal inset but drop the vertical box
  * space for tight text layout.
  */
-declare function ListInsetText({ children, horizontalOnly, className, }: ListInsetTextProps): SafeHtml;
+declare function ListInsetText({ children, horizontalOnly, className, }: ListInsetTextProps): kerfjs.SafeHtml;
 
 export { ListInsetText, type ListInsetTextProps };
 ```
@@ -409,7 +525,9 @@ 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;
@@ -424,9 +542,9 @@ declare function ValueTableRow({ label, value, icon, className, placeholder, }:
 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 };
 ```
@@ -435,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;
@@ -452,8 +571,8 @@ interface AppTabProps {
     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. */
@@ -477,7 +596,8 @@ 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';
@@ -486,9 +606,9 @@ 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
@@ -505,7 +625,7 @@ interface TabBarProps {
     trailingPlacement?: TabBarTrailingPlacement;
 }
 /** Render a controlled tab strip. The application owns selection, order, and persistence. */
-declare function TabBar({ id, label, children, leading, trailing, className, activation, allocation, presentation, trailingPlacement, }: TabBarProps): SafeHtml;
+declare function TabBar({ id, label, children, leading, trailing, className, activation, allocation, presentation, trailingPlacement, }: TabBarProps): kerfjs.SafeHtml;
 
 export { type TabActivation, TabBar, type TabBarAllocation, type TabBarPresentation, type TabBarProps, type TabBarTrailingPlacement };
 ```
@@ -515,6 +635,7 @@ export { type TabActivation, TabBar, type TabBarAllocation, type TabBarPresentat
 ```ts
 import { TabActivation } from './tab-bar.js';
 import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';
 
 type TabReorderSource = 'pointer' | 'keyboard';
 type TabDropPosition = 'before' | 'after';
@@ -551,7 +672,8 @@ export { TabActivation, type TabDropPosition, type TabReorder, type TabReorderSo
 ## `@kerfjs/ui/nav-stack`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+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
@@ -560,11 +682,13 @@ import { SafeHtml } from 'kerfjs';
 interface NavStackView {
     /** Stable identity for keyed reconcile and transition direction. */
     key: string;
-    content: SafeHtml;
+    content: KerfUiContent;
     /** Title shown in the top toolbar for this view. */
     title?: string;
     /** Trailing actions for this view's top toolbar. */
-    toolbar?: SafeHtml;
+    toolbar?: KerfUiContent;
+    /** Bottom toolbar for this view. Cross-fades with the top chrome on navigation. */
+    bottomToolbar?: KerfUiContent;
 }
 interface NavStackProps {
     id: string;
@@ -576,8 +700,8 @@ interface NavStackProps {
     backLabel?: string;
     /** Hide the top toolbar entirely (rare — a fully custom-chrome view). */
     hideToolbar?: boolean;
-    /** Optional persistent bottom toolbar. */
-    bottomToolbar?: SafeHtml;
+    /** Optional persistent bottom toolbar used when the active view does not provide one. */
+    bottomToolbar?: KerfUiContent;
     className?: string;
 }
 /**
@@ -586,7 +710,7 @@ interface NavStackProps {
  * 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): SafeHtml;
+declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className, }: NavStackProps): kerfjs.SafeHtml;
 
 export { NavStack, type NavStackProps, type NavStackView };
 ```
@@ -604,7 +728,10 @@ interface WireNavStackOptions {
  * 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, and calls `onBack` when the back control is used. Returns a disposer.
+ * 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;
 
@@ -614,7 +741,8 @@ export { type WireNavStackOptions, wireNavStack };
 ## `@kerfjs/ui/split-view`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface SplitViewResizable {
     size: number;
@@ -625,9 +753,9 @@ interface SplitViewProps {
     id: string;
     label: string;
     /** The list (primary) pane. */
-    list: SafeHtml;
+    list: KerfUiContent;
     /** The detail (secondary) pane. */
-    detail: SafeHtml;
+    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
@@ -653,7 +781,7 @@ interface SplitViewProps {
  * resizable wiring with `wireResizableRegions` and the compact back with
  * `wireNavStack`.
  */
-declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className, }: SplitViewProps): SafeHtml;
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className, }: SplitViewProps): kerfjs.SafeHtml;
 
 export { SplitView, type SplitViewProps, type SplitViewResizable };
 ```
@@ -661,7 +789,8 @@ export { SplitView, type SplitViewProps, type SplitViewResizable };
 ## `@kerfjs/ui/pane`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+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';
@@ -678,11 +807,11 @@ type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
 }>;
 interface PaneProps {
     /** Optional fixed chrome above the scrolling content, arranged vertically. */
-    header?: SafeHtml | readonly SafeHtml[];
+    header?: KerfUiContent;
     /** The pane's primary vertical, scrolling content stack. */
-    children?: SafeHtml | readonly SafeHtml[];
+    children?: KerfUiContent;
     /** Optional fixed chrome below the scrolling content. */
-    footer?: SafeHtml | readonly SafeHtml[];
+    footer?: KerfUiContent;
     /** Root semantics. Defaults to `div`. */
     element?: PaneElement;
     /** Scrolling content semantics. Defaults to `div`. */
@@ -707,7 +836,7 @@ interface PaneProps {
  * 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): SafeHtml;
+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 };
 ```
@@ -717,10 +846,11 @@ export { Pane, type PaneContentElement, type PaneElement, type PaneProps, type P
 ```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: SafeHtml;
+    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. */
@@ -739,7 +869,7 @@ interface WorkbenchProps {
     id: string;
     label: string;
     /** The central work area. */
-    main: SafeHtml;
+    main: KerfUiContent;
     leftRail?: WorkbenchPanel;
     rightRail?: WorkbenchPanel;
     bottomDrawer?: WorkbenchPanel;
@@ -750,8 +880,10 @@ interface WorkbenchProps {
  * 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. The app owns each `collapsed` flag;
- * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.
+ * 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;
 
@@ -764,6 +896,7 @@ export { Workbench, type WorkbenchPanel, type WorkbenchProps };
 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. */
@@ -812,7 +945,7 @@ interface CollapsiblePanelProps {
     /** Accessible label for the panel region. */
     label?: string;
     /** Panel content. */
-    children?: SafeHtml | readonly SafeHtml[];
+    children?: KerfUiContent;
     separator?: ResizableRegionSeparator;
     collapseMotion?: ResizableRegionCollapseMotion;
     contentOverflow?: ResizableRegionContentOverflow;
@@ -827,7 +960,9 @@ interface CollapsiblePanelProps {
  * {@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). The app owns the `collapsed` signal;
+ * `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`.
@@ -894,6 +1029,7 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface TabScaffoldTab<Id extends string = string> {
     id: Id;
@@ -901,7 +1037,7 @@ interface TabScaffoldTab<Id extends string = 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: SafeHtml;
+    content: KerfUiContent;
 }
 interface TabScaffoldProps<Id extends string = string> {
     id: string;
@@ -945,6 +1081,7 @@ export { type WireTabScaffoldOptions, wireTabScaffold };
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type ResizableRegionAxis = 'horizontal' | 'vertical';
 type ResizableRegionEdge = 'start' | 'end';
@@ -977,7 +1114,7 @@ interface ResizableRegionProps {
     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;
@@ -1077,6 +1214,7 @@ export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type Dev
 
 ```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 {
@@ -1131,19 +1269,19 @@ interface CatalogProps {
     /** 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: SafeHtml;
+    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?: SafeHtml;
+    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?: SafeHtml;
+    sidebarFooter?: KerfUiContent;
     /** Status line content shown at the start of the detail footer. */
-    status?: SafeHtml;
+    status?: KerfUiContent;
     /**
      * Whether to highlight specimens' computed borders (or transparent outer
      * bounds) and non-zero margins. Pass a boolean (rather than omitting the
@@ -1199,7 +1337,7 @@ interface CatalogExampleProps {
     /** Safe authoring `data-*` metadata for the rendered section. Helper-owned structural attributes remain protected. */
     rootAttributes?: CatalogExampleRootAttributes;
     className?: string;
-    children?: SafeHtml | readonly SafeHtml[];
+    children?: KerfUiContent;
 }
 /**
  * One labeled example in a catalog preview: a `ListHeader` label, an optional
@@ -1216,7 +1354,7 @@ interface CatalogExampleStackProps {
     /** Safe authoring `data-*` metadata for the rendered stack. Helper-owned structural attributes remain protected. */
     rootAttributes?: CatalogExampleStackRootAttributes;
     className?: string;
-    children?: SafeHtml | readonly SafeHtml[];
+    children?: KerfUiContent;
 }
 /**
  * A vertically-stacked group of {@link CatalogExample}s with the catalog's
@@ -1233,6 +1371,7 @@ export { Catalog, type CatalogBrand, type CatalogEntry, CatalogExample, type Cat
 ```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
@@ -1332,7 +1471,8 @@ export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry,
 ## `@kerfjs/ui/segmented-control`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type SegmentedControlAppearance = 'filled' | 'outlined' | 'toolbar';
 type SegmentedControlShape = 'rounded' | 'pill';
@@ -1341,7 +1481,7 @@ type SegmentedControlLayout = 'content' | 'equal';
 interface SegmentedControlChoice<Value extends string = string> {
     value: Value;
     label: string;
-    content?: SafeHtml;
+    content?: KerfUiContent;
     title?: string;
     disabled?: boolean;
 }
@@ -1359,7 +1499,7 @@ interface SegmentedControlProps<Value extends string = string> {
     /** Render as an unanimated loading skeleton, disabling every segment. */
     placeholder?: boolean;
 }
-declare function SegmentedControl<Value extends string>({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, }: SegmentedControlProps<Value>): 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 };
 ```
@@ -1368,6 +1508,7 @@ export { SegmentedControl, type SegmentedControlAppearance, type SegmentedContro
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { CssColor } from './css-values.js';
 import { LucideNode } from './lucide-icon.js';
 import 'lucide';
 
@@ -1376,7 +1517,8 @@ interface SelectChoice<Value extends string = string> {
     label: string;
     icon?: LucideNode;
     iconName?: string;
-    color?: string;
+    /** Typed semantic or application-owned color for the optional icon. */
+    color?: CssColor;
     group?: string;
     separatorBefore?: boolean;
 }
@@ -1425,8 +1567,9 @@ export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectPresen
 
 ```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;
@@ -1434,7 +1577,7 @@ interface StateBannerProps {
     /** Optional compact status or count shown beside the title. */
     badge?: string;
     icon?: SafeHtml;
-    action?: SafeHtml;
+    action?: KerfUiContent;
     tone?: StateBannerTone;
     urgency?: StateBannerUrgency;
     className?: string;
@@ -1450,12 +1593,13 @@ export { StateBanner, type StateBannerProps, type StateBannerTone, type StateBan
 
 ```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;
 }
@@ -1483,14 +1627,15 @@ export { LoadingSpinner, type LoadingSpinnerProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssSize, CssLength } from './css-values.js';
 
 interface SkeletonProps {
-    /** Width as any browser CSS length (e.g. `7.5rem`, `60%`). Defaults to filling its slot. */
-    width?: string;
-    /** Height as any CSS length. Defaults to a single text line. */
-    height?: string;
-    /** Corner radius override (a CSS length). Defaults to the small radius token. */
-    radius?: string;
+    /** 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`). */
@@ -1511,11 +1656,12 @@ export { Skeleton, type SkeletonProps };
 ## `@kerfjs/ui/sunken-panel`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type SunkenPanelShape = 'rounded' | 'square';
 interface SunkenPanelProps {
-    children?: SafeHtml | readonly SafeHtml[];
+    children?: KerfUiContent;
     /** Optional accessible landmark name for a distinct application region. */
     ariaLabel?: string;
     /** Corner shape: a rounded rectangle (default) or square corners. */
@@ -1527,7 +1673,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, }: SunkenPanelProps): SafeHtml;
+declare function SunkenPanel({ children, ariaLabel, shape, className, }: SunkenPanelProps): kerfjs.SafeHtml;
 
 export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ```
@@ -1535,7 +1681,8 @@ 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;
@@ -1560,8 +1707,8 @@ interface TokenSearchFieldBaseProps {
     tokenPlaceholder?: string;
     disabled?: boolean;
     autofocus?: boolean;
-    leading?: SafeHtml;
-    trailing?: SafeHtml;
+    leading?: KerfUiContent;
+    trailing?: KerfUiContent;
     editAction?: string;
     removeAction?: string;
     clearAction?: string;
@@ -1587,7 +1734,7 @@ 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. */