@kerfjs/ui 5.0.0-beta.49 → 5.0.0-beta.51

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

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.49` and `kerfjs@5.0.0-beta.49`. 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.51` and `kerfjs@5.0.0-beta.51`. 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`
 
@@ -10,6 +10,7 @@ declare const cssLengthBrand: unique symbol;
 declare const cssLengthExpressionBrand: unique symbol;
 declare const cssFlexBrand: unique symbol;
 declare const cssColorBrand: unique symbol;
+declare const cssForegroundColorBrand: unique symbol;
 /**
  * A complete typed CSS value minted by a property-specific Kerf UI builder.
  *
@@ -42,6 +43,18 @@ type CssFlex = CssValue & {
 type CssColor = CssValue & {
     readonly [cssColorBrand]: 'CssColor';
 };
+/**
+ * A complete CSS color meant to paint a foreground: text or an icon drawn over
+ * a surface. Mint it with {@link uiColor} and a foreground token name
+ * ({@link UiForegroundColorName}) or with {@link foregroundColorVar}. It is a
+ * {@link CssColor}, but a plain `CssColor` is not a foreground color: fill,
+ * border, and surface tokens (including the `success` / `warning` / `danger` /
+ * `pop` fill aliases) are pale backgrounds that leave a foreground nearly
+ * invisible.
+ */
+type CssForegroundColor = CssColor & {
+    readonly [cssForegroundColorBrand]: 'CssForegroundColor';
+};
 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';
@@ -50,6 +63,13 @@ 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];
+/**
+ * The semantic tokens that paint a foreground: the `*-on-*` roles, the text
+ * roles, and their `*-text` compatibility aliases. The bare `success`,
+ * `warning`, `danger`, `pop`, and `accent` aliases are quiet fills, not
+ * foregrounds.
+ */
+type UiForegroundColorName = Extract<UiColorName, `${string}-on-${string}` | `${string}-text` | 'text' | 'text-quiet' | 'text-link'>;
 /** 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. */
@@ -74,12 +94,28 @@ declare function plus(first: CssLength, second: CssLength, ...rest: readonly Css
 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;
+/**
+ * The brand {@link uiColor} returns for a token name: a
+ * {@link CssForegroundColor} for a foreground token, otherwise a plain
+ * {@link CssColor}.
+ */
+type UiColor<Name extends UiColorName> = Name extends UiForegroundColorName ? CssForegroundColor : CssColor;
+/**
+ * Resolve a public Kerf UI semantic color token. A foreground token name
+ * (`success-on-quiet`, `text-quiet`, …) returns a {@link CssForegroundColor};
+ * any other token returns a plain {@link CssColor}.
+ */
+declare function uiColor<Name extends UiColorName>(name: Name): UiColor<Name>;
 /** Reference an application-owned custom property whose contract is a color. */
 declare function colorVar(name: `--${string}`, fallback?: CssColor): CssColor;
+/**
+ * Reference an application-owned custom property whose contract is a
+ * foreground color (text or an icon over a surface). Use it where a prop
+ * accepts only {@link CssForegroundColor}, such as `SelectChoice.color`.
+ */
+declare function foregroundColorVar(name: `--${string}`, fallback?: CssForegroundColor): CssForegroundColor;
 
-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 };
+export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiSpaceName, calc, colorVar, em, flex, foregroundColorVar, lengthVar, pct, plus, px, rem, space, uiColor };
 ```
 
 ## `@kerfjs/ui/disclosure-arrow`
@@ -95,8 +131,10 @@ interface DisclosureArrowProps {
     /** Replacement icons should use right as their unrotated orientation. */
     icon?: SafeHtml;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function DisclosureArrow({ open, openDirection, closedDirection, icon, className, }: DisclosureArrowProps): SafeHtml;
+declare function DisclosureArrow({ open, openDirection, closedDirection, icon, className, slot, }: DisclosureArrowProps): SafeHtml;
 
 export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 ```
@@ -106,6 +144,7 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { D as DividerSides } from './divider-sides-BzB6rphT.js';
+import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface ToolbarProps {
@@ -115,9 +154,37 @@ interface ToolbarProps {
     label?: string;
     /** Physical divider edges in canonical top/right/bottom/left order. Defaults to bottom. */
     dividerSides?: DividerSides;
+    /** Horizontal treatment of the center zone. Defaults to centered content. */
+    centerAlign?: 'center' | 'stretch';
+    /**
+     * Component-owned responsive layout; applications choose the policy rather
+     * than restyling toolbar internals. Under every policy the trailing zone
+     * wraps its groups instead of clipping an action.
+     * - `none` keeps one row; the leading identity truncates first.
+     * - `stack` stacks the zones at `responsiveAt`, wrapping stacked control
+     *   groups onto further rows.
+     * - `wrap` keeps one row while every zone fits at its natural width, and
+     *   otherwise moves the trailing zone below a whole leading identity.
+     * - `center-priority` gives an expanded center control the full row.
+     */
+    responsive?: 'none' | 'stack' | 'wrap' | 'center-priority';
+    /** Container width at which `responsive="stack"` activates. */
+    responsiveAt?: 'compact' | 'narrow';
+    /**
+     * Screen edges this toolbar claims for device safe-area compensation, for an
+     * app bar or bottom bar that sits directly at a screen edge rather than in a
+     * Pane header or footer. Each listed side pads by the inset its surrounding
+     * layout reports through `--kui-edge-inset-*`, or the full device inset when
+     * nothing routes that edge, while the toolbar's box and dividers paint
+     * through. Omitted, the toolbar pads only the inline edges an owner such as
+     * a Pane header hands it, and never a block edge.
+     */
+    safeAreaEdges?: readonly PaneSeparatorSide[];
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, dividerSides, className, }: ToolbarProps): kerfjs.SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
 export { DividerSides, Toolbar, type ToolbarProps };
 ```
@@ -150,6 +217,8 @@ interface ToolbarTextBaseProps {
      * instead. Default true.
      */
     ellipsis?: boolean;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 type ToolbarTextWrappingProps = {
     /** Wrap onto multiple lines; combine with `maxLines` to cap them. */
@@ -160,7 +229,7 @@ type ToolbarTextWrappingProps = {
     maxLines?: never;
 };
 type ToolbarTextProps = ToolbarTextBaseProps & ToolbarTextWrappingProps;
-declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, slot, }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
 ```
@@ -177,9 +246,29 @@ type ToolbarControlGroupButtonAppearance = 'plain' | 'push';
 type ToolbarControlGroupShape = 'pill' | 'rounded';
 type ToolbarControlGroupSize = 'default' | 'compact';
 type ToolbarControlGroupDensity = 'comfortable' | 'tight';
-type ToolbarControlGroupContent = 'icon' | 'text' | 'mixed' | 'avatar';
+type ToolbarControlGroupContent = 'icon' | 'text' | 'mixed' | 'avatar' | 'search';
+type ToolbarControlGroupFocusRing = 'control' | 'outline' | 'halo';
 type ToolbarControlGroupSelectedChrome = 'raised' | 'filled' | 'outline';
 type ToolbarControlGroupSelectedTone = 'brand' | 'neutral' | 'pop';
+type ToolbarControlGroupOverflow = 'visible' | 'scroll';
+type ToolbarControlGroupMenuInset = 'standard' | 'compact' | 'list-zero';
+type ToolbarControlGroupVisibility = 'always' | 'compact-only';
+interface ToolbarActionLinkProps {
+    href: string;
+    label: string;
+    icon?: KerfUiContent;
+    /** Optional machine-readable detail hidden visually but included in the default accessible name. */
+    detail?: string;
+    /** Override the accessible name when surrounding context is needed. */
+    ariaLabel?: string;
+    /** Open in a new tab with a safe rel and announce that behavior. */
+    external?: boolean;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/** A semantic anchor with ToolbarControlGroup-owned action geometry. */
+declare function ToolbarActionLink({ href, label, icon, detail, ariaLabel, external, className, slot, }: ToolbarActionLinkProps): kerfjs.SafeHtml;
 interface ToolbarControlGroupProps {
     children: KerfUiContent;
     label?: string;
@@ -194,10 +283,18 @@ interface ToolbarControlGroupProps {
     size?: ToolbarControlGroupSize;
     density?: ToolbarControlGroupDensity;
     content?: ToolbarControlGroupContent;
+    /** Whether controls paint focus individually or the group paints an outline/halo on focus-within. */
+    focusRing?: ToolbarControlGroupFocusRing;
     selectedChrome?: ToolbarControlGroupSelectedChrome;
     selectedTone?: ToolbarControlGroupSelectedTone;
     /** Size a nested Web Awesome dropdown trigger as part of this group. */
     nestedDropdown?: boolean;
+    /** Configure the nested dropdown menu inset without consumer ::part() CSS. */
+    menuInset?: ToolbarControlGroupMenuInset;
+    /** Keep an overlong row of actions inside the available width with horizontal scrolling. */
+    overflow?: ToolbarControlGroupOverflow;
+    /** Responsive visibility owned by the enclosing Toolbar container. */
+    visibility?: ToolbarControlGroupVisibility;
     /** Add contrast behind photo-backed avatar content. */
     scrim?: boolean;
     /**
@@ -205,10 +302,12 @@ interface ToolbarControlGroupProps {
      * multi-control group paints it only on the pressed selection highlight.
      */
     avatarImage?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, selectedChrome, selectedTone, nestedDropdown, scrim, avatarImage, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, scrim, avatarImage, slot, }: 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 };
+export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };
 ```
 
 ## `@kerfjs/ui/floating-toolbar`
@@ -230,6 +329,8 @@ interface FloatingToolbarProps {
      */
     position?: FloatingToolbarPosition;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * A toolbar that floats above the main content of its nearest positioned
@@ -240,7 +341,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): kerfjs.SafeHtml;
+declare function FloatingToolbar({ children, label, position, className, slot, }: FloatingToolbarProps): kerfjs.SafeHtml;
 
 export { FloatingToolbar, type FloatingToolbarPosition, type FloatingToolbarProps };
 ```
@@ -258,6 +359,7 @@ type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undef
     'data-density'?: never;
     'data-divider'?: never;
     'data-inline'?: never;
+    'data-width'?: never;
     'data-indicator-tone'?: never;
     'data-toggle'?: never;
 }>;
@@ -274,11 +376,15 @@ interface ListHeaderBaseProps {
     divider?: 'none' | 'before' | 'after' | 'both';
     /** Shrink-wrap the header without its default outer margin, border, or padding. */
     inline?: boolean;
+    /** Fill the available row or shrink-wrap while retaining normal header geometry. */
+    width?: 'fill' | 'content';
     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;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 type ListHeaderModeProps = {
     /** Render the title as a controlled disclosure trigger. */
@@ -325,7 +431,7 @@ type ListHeaderIndicatorProps = {
     status?: SafeHtml;
 };
 type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps & ListHeaderModeProps;
-declare function ListHeader({ label, count, countLabel, badge, status, density, divider, inline, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, }: ListHeaderProps): SafeHtml;
+declare function ListHeader({ label, count, countLabel, badge, status, density, divider, inline, width, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, slot, }: ListHeaderProps): SafeHtml;
 
 export { ListHeader, type ListHeaderProps };
 ```
@@ -340,12 +446,29 @@ import { H as HorizontalAlignment, L as ListVerticalAlignment } from './flex-ali
 export { V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
+type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-gap'?: never;
+    'data-flex'?: never;
+    'data-fill'?: never;
+    'data-h-align'?: never;
+    'data-v-align'?: never;
+    'data-scrollable'?: never;
+    'data-text-insets'?: never;
+    'data-control-insets'?: never;
+}>;
 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;
+    /**
+     * Fill the height of a parent with a definite height, such as an app root or
+     * a fixed-height frame, when this list is that parent's layout root. Inside a
+     * flex layout use `flex` instead. Defaults to false.
+     */
+    fill?: boolean;
     /** Horizontal alignment. Defaults to full to preserve stretch-aligned list children. */
     hAlign?: HorizontalAlignment;
     /** Vertical distribution. Defaults to top. */
@@ -359,9 +482,13 @@ interface ListProps {
     /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
     controlInsets?: Sides;
     className?: string;
+    /** Safe `data-*` metadata; List-owned structural attributes remain protected. */
+    rootAttributes?: ListRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-/** A stretch-aligned vertical stack with optional gap, flex, scroll, and dividers. */
-declare function List({ children, gap, flex, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, }: ListProps): kerfjs.SafeHtml;
+/** A stretch-aligned vertical stack with optional gap, flex, fill, scroll, and dividers. */
+declare function List({ children, gap, flex, fill, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, DividerSides, HorizontalAlignment, List, type ListProps, ListVerticalAlignment, Sides, UiSpaceName };
 ```
@@ -426,8 +553,10 @@ interface ListActionRowProps {
     className?: string;
     rootAttributes?: ListActionRowRootAttributes;
     trailingActionAttributes?: ListActionRowTrailingAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function ListActionRow({ label, description, status, busy, density, divider, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, trailingActionVisibility, className, rootAttributes, trailingActionAttributes, }: 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, slot, }: ListActionRowProps): SafeHtml;
 
 export { ListActionRow, type ListActionRowProps };
 ```
@@ -476,8 +605,10 @@ interface ListItemProps {
     /** Render the row as an unanimated loading skeleton, disabling its action. */
     placeholder?: boolean;
     rootAttributes?: ListItemRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-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;
+declare function ListItem({ label, description, icon, trailing, status, busy, density, divider, selected, action, itemId, className, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes, slot, }: ListItemProps): SafeHtml;
 
 export { ListItem, type ListItemProps };
 ```
@@ -495,6 +626,8 @@ interface ListInsetControlProps {
     /** Physical inset sides in canonical top/right/bottom/left order. Defaults to all sides. */
     sides?: Sides;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * Insets a control into a pane/list content region: an 8px inline margin (so its
@@ -502,7 +635,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, sides, className, }: ListInsetControlProps): kerfjs.SafeHtml;
+declare function ListInsetControl({ children, sides, className, slot, }: ListInsetControlProps): kerfjs.SafeHtml;
 
 export { ListInsetControl, type ListInsetControlProps, Sides };
 ```
@@ -527,6 +660,8 @@ interface ListInsetTextProps {
      */
     horizontalOnly?: boolean;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * Gives bare text the content-item geometry — an 8px inline margin, a 1px
@@ -536,7 +671,7 @@ interface ListInsetTextProps {
  * Pass `horizontalOnly` to keep the horizontal inset but drop the vertical box
  * space for tight text layout.
  */
-declare function ListInsetText({ children, sides, horizontalOnly, className, }: ListInsetTextProps): kerfjs.SafeHtml;
+declare function ListInsetText({ children, sides, horizontalOnly, className, slot, }: ListInsetTextProps): kerfjs.SafeHtml;
 
 export { ListInsetText, type ListInsetTextProps, Sides };
 ```
@@ -555,15 +690,19 @@ interface ValueTableRowProps {
     className?: string;
     /** Render the value as an unanimated loading skeleton, keeping the field label. */
     placeholder?: boolean;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function ValueTableRow({ label, value, icon, className, placeholder, }: ValueTableRowProps): SafeHtml;
+declare function ValueTableRow({ label, value, icon, className, placeholder, slot, }: ValueTableRowProps): SafeHtml;
 
 interface ValueTableProps {
     label: string;
     className?: string;
     children: KerfUiContent;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function ValueTable({ label, className, children, }: ValueTableProps): kerfjs.SafeHtml;
+declare function ValueTable({ label, className, children, slot, }: ValueTableProps): kerfjs.SafeHtml;
 
 export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProps };
 ```
@@ -606,8 +745,10 @@ interface AppTabProps {
     /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
     placeholder?: boolean;
     rootAttributes?: AppTabRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, presentation, size, labelMaxWidth, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes, }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, presentation, size, labelMaxWidth, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes, slot, }: AppTabProps): SafeHtml;
 
 export { AppTab, type AppTabPresentation, type AppTabProps, type AppTabSize };
 ```
@@ -628,6 +769,11 @@ interface TabBarProps {
     children: KerfUiContent;
     leading?: KerfUiContent;
     trailing?: KerfUiContent;
+    /**
+     * Action pinned to the far edge of the bar. Combine with an adjacent `trailing`
+     * action when the tab-local and workspace-level actions must remain distinct.
+     */
+    end?: KerfUiContent;
     className?: string;
     /**
      * Keyboard activation mode for this strip, emitted as `data-tab-activation` for
@@ -642,9 +788,11 @@ interface TabBarProps {
     presentation?: TabBarPresentation;
     /** Keep a trailing action beside the final tab or at the far edge of the bar. */
     trailingPlacement?: TabBarTrailingPlacement;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /** Render a controlled tab strip. The application owns selection, order, and persistence. */
-declare function TabBar({ id, label, children, leading, trailing, className, activation, allocation, presentation, trailingPlacement, }: TabBarProps): kerfjs.SafeHtml;
+declare function TabBar({ id, label, children, leading, trailing, end, className, activation, allocation, presentation, trailingPlacement, slot, }: TabBarProps): kerfjs.SafeHtml;
 
 export { type TabActivation, TabBar, type TabBarAllocation, type TabBarPresentation, type TabBarProps, type TabBarTrailingPlacement };
 ```
@@ -722,6 +870,8 @@ interface NavStackProps {
     /** Optional persistent bottom toolbar used when the active view does not provide one. */
     bottomToolbar?: KerfUiContent;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * A navigation stack (iOS-style push/pop). Renders every entry stacked, the last
@@ -729,7 +879,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): kerfjs.SafeHtml;
+declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className, slot, }: NavStackProps): kerfjs.SafeHtml;
 
 export { NavStack, type NavStackProps, type NavStackView };
 ```
@@ -792,6 +942,8 @@ interface SplitViewProps {
     /** A resizable separator on roomy classes (min/max px). Omit for a fixed split. */
     resizable?: SplitViewResizable;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * A list-detail split. On roomy classes it shows both panes side
@@ -800,7 +952,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): kerfjs.SafeHtml;
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className, slot, }: SplitViewProps): kerfjs.SafeHtml;
 
 export { SplitView, type SplitViewProps, type SplitViewResizable };
 ```
@@ -811,7 +963,10 @@ export { SplitView, type SplitViewProps, type SplitViewResizable };
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-/** Logical sides that can show a {@link Pane} separator. */
+/**
+ * Logical pane sides: where a {@link Pane} can show a separator and where it can
+ * compensate for a device safe-area inset.
+ */
 type PaneSeparatorSide = 'block-start' | 'block-end' | 'inline-start' | 'inline-end';
 /** Semantic root elements supported by {@link Pane}. */
 type PaneElement = 'article' | 'aside' | 'div' | 'main' | 'section';
@@ -823,6 +978,10 @@ type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-separator-block-end'?: never;
     'data-separator-inline-start'?: never;
     'data-separator-inline-end'?: never;
+    'data-safe-area-block-start'?: never;
+    'data-safe-area-block-end'?: never;
+    'data-safe-area-inline-start'?: never;
+    'data-safe-area-inline-end'?: never;
 }>;
 interface PaneProps {
     /** Optional fixed chrome above the scrolling content, arranged vertically. */
@@ -837,6 +996,14 @@ interface PaneProps {
     contentElement?: PaneContentElement;
     /** Independent logical-edge separator lines. Defaults to none. */
     separators?: readonly PaneSeparatorSide[];
+    /**
+     * Sides on which the pane may compensate for a device safe-area inset.
+     * Defaults to every side: the pane pads its slots for each side that still
+     * reaches an unsafe screen edge, as its surrounding layout reports, while its
+     * background and separators paint through. List only the sides an app-owned
+     * layout places at a screen edge, or pass `[]` to opt out.
+     */
+    safeAreaEdges?: readonly PaneSeparatorSide[];
     id?: string;
     /** Accessible name for a landmark root such as `aside` or `main`. */
     label?: string;
@@ -848,6 +1015,8 @@ interface PaneProps {
     footerClassName?: string;
     /** Safe `data-*` metadata; Pane-owned structural attributes remain protected. */
     rootAttributes?: PaneRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * An unpadded application column with optional fixed header/footer slots and one
@@ -855,7 +1024,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): kerfjs.SafeHtml;
+declare function Pane({ header, children, footer, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
 
 export { Pane, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
 ```
@@ -893,6 +1062,8 @@ interface WorkbenchProps {
     rightRail?: WorkbenchPanel;
     bottomDrawer?: WorkbenchPanel;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and
@@ -904,7 +1075,7 @@ interface WorkbenchProps {
  * 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;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className, slot, }: WorkbenchProps): SafeHtml;
 
 export { Workbench, type WorkbenchPanel, type WorkbenchProps };
 ```
@@ -943,6 +1114,8 @@ interface CollapsiblePanelToggleProps {
     /** Accessible label; defaults to "Collapse"/"Expand". */
     label?: string;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * A standard collapse/expand toggle button for a {@link CollapsiblePanel}: the
@@ -951,7 +1124,7 @@ interface CollapsiblePanelToggleProps {
  * 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;
+declare function CollapsiblePanelToggle({ side, collapsed, action, panelId, label, className, slot, }: CollapsiblePanelToggleProps): SafeHtml;
 interface CollapsiblePanelProps {
     /** A stable id for the panel — `wireSidebar` targets it and toggles reference it. */
     id: string;
@@ -984,7 +1157,7 @@ interface CollapsiblePanelProps {
  * 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`.
+ * affordance. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.
  */
 declare function CollapsiblePanel({ id, side, collapsed, size, label, children, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
 
@@ -1010,9 +1183,18 @@ interface WireSidebarPanel {
     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. */
+    /** When set, the panel's inline collapsed state is loaded from and saved to
+     *  `storage` under this key (a persistence hook), so the panel remembers the
+     *  user's inline choice. A compact overlay's open/closed state is transient
+     *  and is never persisted. */
     storageKey?: string;
+    /** The panel's inline (non-compact) collapsed state when `storage` holds no
+     *  choice for it; wire-up seeds the signal with it. Defaults to the signal's
+     *  own value. Set it when the app seeds the signal from the device class
+     *  (`signal(device.value.compact)`) so a compact first render already starts
+     *  collapsed while a later crossing to a wide class still restores this
+     *  inline default. */
+    inlineCollapsed?: boolean;
 }
 interface WireSidebarOptions {
     panels: readonly WireSidebarPanel[];
@@ -1022,6 +1204,12 @@ interface WireSidebarOptions {
      * 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.
+     *
+     * An overlay is transient and user-initiated: whenever the compact overlay
+     * presentation begins (wire-up on a compact device, or a crossing from a wide
+     * class), every panel starts collapsed so nothing blocks the page until the
+     * user opens it. The inline state is remembered and restored when the device
+     * crosses back to a wide class (and on disposal).
      */
     deviceClass?: ReadonlySignal<DeviceClass>;
     /** Compact devices either overlay the panels (default) or hide them in favor
@@ -1037,7 +1225,7 @@ interface WireSidebarOptions {
  * 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`.
+ * owns the interaction. Returns a disposer. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.
  */
 declare function wireSidebar(root: HTMLElement, { panels, deviceClass, compactPresentation, exclusiveCompact, storage, }: WireSidebarOptions): () => void;
 
@@ -1066,6 +1254,8 @@ interface TabScaffoldProps<Id extends string = string> {
     /** The controlled active tab id (the app owns selection). */
     active: NoInfer<Id>;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * A mobile-first, iOS-like bottom tab scaffold: a bottom tab bar that switches
@@ -1075,7 +1265,7 @@ interface TabScaffoldProps<Id extends string = string> {
  * 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;
+declare function TabScaffold<Id extends string>({ id, label, tabs, active, className, slot, }: TabScaffoldProps<Id>): SafeHtml;
 
 export { TabScaffold, type TabScaffoldProps, type TabScaffoldTab };
 ```
@@ -1109,6 +1299,7 @@ type ResizableRegionCollapseMotion = 'none' | 'slide' | 'fade-slide';
 type ResizableRegionContentOverflow = 'clip' | 'auto' | 'visible';
 type ResizableRegionPresentation = 'inline' | 'overlay' | 'hidden';
 type ResizableRegionRestorePosition = 'bottom-start' | 'bottom-end';
+type ResizableRegionResponsiveFillAt = 'compact' | 'narrow';
 interface ResizableRegionProps {
     id: string;
     label: string;
@@ -1131,15 +1322,17 @@ interface ResizableRegionProps {
     restoreControl?: SafeHtml;
     /** Safe-area-aware viewport corner for `restoreControl`. */
     restorePosition?: ResizableRegionRestorePosition;
+    /** Fill the available inline track and hide the separator below a container breakpoint. */
+    responsiveFillAt?: ResizableRegionResponsiveFillAt;
     /** Decorative dormant content for the separator handle. Must not contain interactive descendants. */
     handleIcon?: 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, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, handleIcon, children, }: ResizableRegionProps): SafeHtml;
+declare function ResizableRegion({ id, label, size, min, max, axis, edge, collapsed, transitioning, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, responsiveFillAt, handleIcon, children, }: ResizableRegionProps): SafeHtml;
 
-export { ResizableRegion, type ResizableRegionAxis, type ResizableRegionCollapseMotion, type ResizableRegionContentOverflow, type ResizableRegionEdge, type ResizableRegionPresentation, type ResizableRegionProps, type ResizableRegionRestorePosition, type ResizableRegionSeparator, clampRegionSize, resizeRegionFromPointer };
+export { ResizableRegion, type ResizableRegionAxis, type ResizableRegionCollapseMotion, type ResizableRegionContentOverflow, type ResizableRegionEdge, type ResizableRegionPresentation, type ResizableRegionProps, type ResizableRegionResponsiveFillAt, type ResizableRegionRestorePosition, type ResizableRegionSeparator, clampRegionSize, resizeRegionFromPointer };
 ```
 
 ## `@kerfjs/ui/wire-resizable-regions`
@@ -1232,106 +1425,36 @@ export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type Dev
 ## `@kerfjs/ui/catalog`
 
 ```ts
+import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
+import { a as CatalogProps } from './types-CEsieBZi.js';
+export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-CEsieBZi.js';
 import { 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).
- */
+/** Controlled, stateless component-catalog shell. */
+declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, slot, }: CatalogProps): kerfjs.SafeHtml;
+
+/** How a specimen aligns its visible edge with its `ListHeader` label. */
 type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
+interface CatalogExampleViewport {
+    layout?: 'grid' | 'flex' | 'flex-column';
+    width?: 'full' | 'compact' | 'medium' | 'wide' | 'text' | 'control';
+    /** Fixed specimen height; `app` frames an application-sized recipe or layout.
+     *  A fixed height is definite, so a child that fills with `height: 100%`
+     *  (a horizontal `ResizableRegion`, say) spans the whole frame. */
+    height?: 'short' | 'reduced' | 'medium' | 'tall' | 'app';
+    /** A minimum the frame may grow past. It is not a definite height: a child
+     *  sized with `height: 100%` falls back to its content height, so use
+     *  `height` when the specimen must fill the frame. */
+    minHeight?: 'short' | 'medium';
+    frame?: 'solid' | 'dashed';
+    surface?: 'default' | 'lowered';
+    overflow?: 'hidden' | 'auto-x';
+    responsive?: 'roomy-only';
+    shadow?: boolean;
+    /** Public component custom properties applied to the specimen viewport. */
+    tokens?: Readonly<Record<`--${string}`, string>>;
+}
 type CatalogExampleRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-catalog-example'?: never;
     'data-catalog-example-stack'?: never;
@@ -1339,58 +1462,50 @@ type CatalogExampleRootAttributes = Readonly<Record<`data-${string}`, string | u
     '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. */
+    /** Optional catalog-owned constraints for demonstrating layout components. */
+    viewport?: CatalogExampleViewport;
+    /** Replacement guidance shown when a roomy-only viewport is hidden. */
+    compactFallback?: SafeHtml | string;
     rootAttributes?: CatalogExampleRootAttributes;
     className?: string;
     children?: KerfUiContent;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-/**
- * 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;
+/** A labeled catalog specimen with optional explanatory text and alignment. */
+declare function CatalogExample({ label, note, align, viewport, compactFallback, rootAttributes, className, children, slot, }: CatalogExampleProps): SafeHtml;
+
+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 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;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-/**
- * 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;
+/** A vertically stacked group of catalog examples. */
+declare function CatalogExampleStack({ label, rootAttributes, className, children, slot, }: CatalogExampleStackProps): kerfjs.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 };
+export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, type CatalogExampleViewport, CatalogProps };
 ```
 
 ## `@kerfjs/ui/catalog-resources`
 
 ```ts
-import { CatalogResource } from './catalog.js';
-import 'kerfjs';
+import { C as CatalogResource } from './types-CEsieBZi.js';
 import './semantic-content-BbzjvSu9.js';
+import 'kerfjs';
 
 /**
  * Standard resource labels for a Kerf catalog detail footer. Keep these labels
@@ -1517,8 +1632,10 @@ interface SegmentedControlProps<Value extends string = string> {
     className?: string;
     /** Render as an unanimated loading skeleton, disabling every segment. */
     placeholder?: boolean;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function SegmentedControl<Value extends string>({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, }: SegmentedControlProps<Value>): kerfjs.SafeHtml;
+declare function SegmentedControl<Value extends string>({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, slot, }: SegmentedControlProps<Value>): kerfjs.SafeHtml;
 
 export { SegmentedControl, type SegmentedControlAppearance, type SegmentedControlChoice, type SegmentedControlLayout, type SegmentedControlProps, type SegmentedControlShape, type SegmentedControlSize };
 ```
@@ -1527,7 +1644,7 @@ export { SegmentedControl, type SegmentedControlAppearance, type SegmentedContro
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { CssColor } from './css-values.js';
+import { CssForegroundColor } from './css-values.js';
 import { LucideNode } from './lucide-icon.js';
 import 'lucide';
 
@@ -1536,9 +1653,19 @@ interface SelectChoice<Value extends string = string> {
     label: string;
     icon?: LucideNode;
     iconName?: string;
-    /** Typed semantic or application-owned color for the optional icon. */
-    color?: CssColor;
+    /**
+     * Foreground color for the optional icon: a semantic foreground token such
+     * as `uiColor('success-on-quiet')`, or an application-owned
+     * `foregroundColorVar('--app-icon-color')`. Fill tokens such as
+     * `uiColor('success')` are pale background tints and do not type-check.
+     */
+    color?: CssForegroundColor;
     group?: string;
+    /**
+     * Draw a divider between this choice and the previous choice in the same
+     * list. A group boundary is already a separator, so the first choice of a
+     * group (or of the whole menu) never draws a second one.
+     */
     separatorBefore?: boolean;
 }
 type SelectAccessibleName = {
@@ -1575,9 +1702,11 @@ interface SelectBaseProps<Value extends string = string> {
     focusRingOwner?: SelectFocusRingOwner;
     /** Maximum closed-control label width in CSS pixels before ellipsis. */
     labelMaxWidth?: number;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 type SelectProps<Value extends string = string> = SelectBaseProps<Value> & SelectAccessibleName;
-declare function Select<Value extends string>({ name, value, label, ariaLabel, choices, className, placeholderText, hint, disabled, fitMenu, renderSelected, placeholder, presentation, size, selectedPresentation, focusRingOwner, labelMaxWidth, }: SelectProps<Value>): SafeHtml;
+declare function Select<Value extends string>({ name, value, label, ariaLabel, choices, className, placeholderText, hint, disabled, fitMenu, renderSelected, placeholder, presentation, size, selectedPresentation, focusRingOwner, labelMaxWidth, slot, }: SelectProps<Value>): SafeHtml;
 
 export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectPresentation, type SelectProps, type SelectSelectedPresentation, type SelectSize };
 ```
@@ -1602,8 +1731,10 @@ interface StateBannerProps {
     className?: string;
     /** Render the title, badge, and detail as unanimated loading skeletons, keeping the icon and tone. */
     placeholder?: boolean;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, className, placeholder, }: StateBannerProps): SafeHtml;
+declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, className, placeholder, slot, }: StateBannerProps): SafeHtml;
 
 export { StateBanner, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
 ```
@@ -1621,8 +1752,10 @@ interface EmptyStateProps {
     action?: KerfUiContent;
     busy?: boolean;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function EmptyState({ title, detail, icon, action, busy, className, }: EmptyStateProps): SafeHtml;
+declare function EmptyState({ title, detail, icon, action, busy, className, slot, }: EmptyStateProps): SafeHtml;
 
 export { EmptyState, type EmptyStateProps };
 ```
@@ -1635,9 +1768,11 @@ import * as kerfjs from 'kerfjs';
 interface LoadingSpinnerProps {
     className?: string;
     label?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /** Stable viewBox-centered progress ring based on svg-spinners' MIT-licensed 180-ring. */
-declare function LoadingSpinner({ className, label }: LoadingSpinnerProps): kerfjs.SafeHtml;
+declare function LoadingSpinner({ className, label, slot, }: LoadingSpinnerProps): kerfjs.SafeHtml;
 
 export { LoadingSpinner, type LoadingSpinnerProps };
 ```
@@ -1660,6 +1795,8 @@ interface SkeletonProps {
     /** Accessible label. Omit to keep the block decorative (`aria-hidden`). */
     label?: string;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /**
  * A subtle, deliberately **unanimated** loading placeholder block. Use it for a
@@ -1667,7 +1804,7 @@ interface SkeletonProps {
  * `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;
+declare function Skeleton({ width, height, radius, lines, label, className, slot, }: SkeletonProps): kerfjs.SafeHtml;
 
 export { Skeleton, type SkeletonProps };
 ```
@@ -1686,13 +1823,15 @@ interface SunkenPanelProps {
     /** Corner shape: a rounded rectangle (default) or square corners. */
     shape?: SunkenPanelShape;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: 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;
+declare function SunkenPanel({ children, ariaLabel, shape, className, slot, }: SunkenPanelProps): kerfjs.SafeHtml;
 
 export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ```
@@ -1728,12 +1867,16 @@ interface TokenSearchFieldBaseProps {
     autofocus?: boolean;
     leading?: KerfUiContent;
     trailing?: KerfUiContent;
+    /** Standalone field chrome or the inset visual layer of a configured toolbar group. */
+    presentation?: 'standalone' | 'toolbar-group';
     editAction?: string;
     removeAction?: string;
     clearAction?: string;
     clearLabel?: string;
     className?: string;
     editorAttributes?: TokenSearchEditorAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 type TokenSearchCollapsibleProps = {
     /** Allow an empty field to render as one iconic action. */
@@ -1753,7 +1896,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): kerfjs.SafeHtml;
+declare function TokenSearchField({ id, label, query, tokens, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, presentation, editAction, removeAction, clearAction, clearLabel, className, editorAttributes, slot, }: TokenSearchFieldProps): kerfjs.SafeHtml;
 /** 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. */
@@ -1955,6 +2098,35 @@ declare function delegateActions<E extends Element = Element>(root: HTMLElement,
 export { type ActionHandler, type DelegateActionsOptions, action, delegateActions };
 ```
 
+## `@kerfjs/ui/badge`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+type BadgeTone = 'neutral' | 'brand' | 'pop' | 'success' | 'warning' | 'danger';
+type BadgeAppearance = 'quiet' | 'solid' | 'outline';
+type BadgeShape = 'pill' | 'rounded';
+type BadgeSize = 'compact' | 'default';
+interface BadgeProps {
+    children: SafeHtml | string | number;
+    tone?: BadgeTone;
+    appearance?: BadgeAppearance;
+    shape?: BadgeShape;
+    size?: BadgeSize;
+    /** Optional accessible name when the visible content is abbreviated. */
+    label?: string;
+    /** Hide a repeated visual badge from assistive technology. */
+    ariaHidden?: boolean;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/** Compact, non-interactive metadata whose tone, emphasis, and shape are configured by props. */
+declare function Badge({ children, tone, appearance, shape, size, label, ariaHidden, className, slot, }: BadgeProps): SafeHtml;
+
+export { Badge, type BadgeAppearance, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTone };
+```
+
 ## `@kerfjs/ui/lucide-icon`
 
 ```ts
@@ -1967,9 +2139,11 @@ interface LucideIconProps {
     name: string;
     className?: string;
     label?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /** Render a Lucide-compatible icon node without copying icon SVG strings. */
-declare function LucideIcon({ icon, name, className, label }: LucideIconProps): kerfjs.SafeHtml;
+declare function LucideIcon({ icon, name, className, label, slot, }: LucideIconProps): kerfjs.SafeHtml;
 
 export { LucideIcon, type LucideIconProps, type LucideNode };
 ```
@@ -1990,17 +2164,21 @@ interface DialogSurfaceProps {
     bodyInset?: SurfaceInset;
     footerInset?: SurfaceInset;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /** Configure recurring Web Awesome dialog geometry without consumer ::part() CSS. */
-declare function DialogSurface({ children, size, presentation, bodyInset, footerInset, className, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ children, size, presentation, bodyInset, footerInset, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
 type PopupSurfaceInset = 'standard' | 'compact' | 'list-zero';
 interface PopupSurfaceProps {
     children: KerfUiContent;
     inset?: PopupSurfaceInset;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /** Configure recurring Web Awesome dropdown-menu geometry without consumer ::part() CSS. */
-declare function PopupSurface({ children, inset, className, }: PopupSurfaceProps): kerfjs.SafeHtml;
+declare function PopupSurface({ children, inset, className, slot, }: PopupSurfaceProps): kerfjs.SafeHtml;
 
 export { DialogSurface, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceSize, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
 ```
@@ -2012,13 +2190,14 @@ import * as kerfjs from 'kerfjs';
 import { KerfBaseAttrs } from 'kerfjs/jsx-runtime';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
+type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';
 type TextTone = 'default' | 'quiet' | 'danger';
 type TextSize = 'default' | 'compact';
 type TextFont = 'default' | 'monospace';
+type TextBorder = 'transparent' | 'none';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
 type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
-    /** Native heading or paragraph element to render. Defaults to `p`. */
+    /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
     variant?: TextVariant;
     /** Semantic foreground treatment. Defaults to the inherited foreground. */
     tone?: TextTone;
@@ -2026,17 +2205,20 @@ type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     size?: TextSize;
     /** Font family independent of the native semantic element. */
     font?: TextFont;
+    /** Transparent alignment border or no border when embedded in owner chrome. */
+    border?: TextBorder;
     children: TextContent;
     class?: string;
     className?: string;
 };
 /**
- * Semantic heading or paragraph text with the standard content-item padding.
+ * Semantic heading, paragraph, or inline text. Block variants use the standard
+ * content-item padding; `span` adds no box geometry.
  * All ordinary native heading/paragraph attributes pass through to the element.
  */
-declare function Text({ variant: Variant, tone, size, font, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
+declare function Text({ variant: Variant, tone, size, font, border, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
 
-export { Text, type TextContent, type TextFont, type TextProps, type TextSize, type TextTone, type TextVariant };
+export { Text, type TextBorder, type TextContent, type TextFont, type TextProps, type TextSize, type TextTone, type TextVariant };
 ```
 
 ## `@kerfjs/ui/row`
@@ -2048,6 +2230,16 @@ import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
+type RowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-h-align'?: never;
+    'data-v-align'?: never;
+    'data-flex'?: never;
+    'data-fill'?: never;
+    'data-wrap'?: never;
+    'data-text-insets'?: never;
+    'data-control-insets'?: never;
+}>;
 interface RowProps {
     children?: KerfUiContent;
     /** Horizontal distribution. Defaults to left. */
@@ -2058,6 +2250,12 @@ interface RowProps {
     gap?: UiSpaceName | CssLength;
     /** Allow this row to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
+    /**
+     * Fill the height of a parent with a definite height, such as an app root or
+     * a fixed-height frame, when this row is that parent's layout root. Inside a
+     * flex layout use `flex` instead. Defaults to false.
+     */
+    fill?: boolean;
     /** Allow children to wrap onto additional lines. */
     wrap?: boolean;
     /** Physical sides that receive the standard 17px text inset. */
@@ -2065,9 +2263,13 @@ interface RowProps {
     /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
     controlInsets?: Sides;
     className?: string;
+    /** Safe `data-*` metadata; Row-owned structural attributes remain protected. */
+    rootAttributes?: RowRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /** A horizontal flex row with explicit physical-axis alignment and spacing. */
-declare function Row({ children, hAlign, vAlign, gap, flex, wrap, textInsets, controlInsets, className, }: RowProps): kerfjs.SafeHtml;
+declare function Row({ children, hAlign, vAlign, gap, flex, fill, wrap, textInsets, controlInsets, className, rootAttributes, slot, }: RowProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowProps, Sides, UiSpaceName, VerticalAlignment };
 ```
@@ -2079,6 +2281,12 @@ import * as kerfjs from 'kerfjs';
 import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
+type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-columns'?: never;
+    'data-flex'?: never;
+    'data-fill'?: never;
+}>;
 interface GridProps {
     children?: KerfUiContent;
     /** Number of equal-width columns. Must be a positive safe integer. */
@@ -2087,10 +2295,20 @@ interface GridProps {
     gap?: UiSpaceName | CssLength;
     /** Allow this grid to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
+    /**
+     * Fill the height of a parent with a definite height, such as an app root or
+     * a fixed-height frame, when this grid is that parent's layout root. Inside a
+     * flex layout use `flex` instead. Defaults to false.
+     */
+    fill?: boolean;
     className?: string;
+    /** Safe `data-*` metadata; Grid-owned structural attributes remain protected. */
+    rootAttributes?: GridRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /** A fixed-count grid whose columns share the available width equally. */
-declare function Grid({ children, columns, gap, flex, className, }: GridProps): kerfjs.SafeHtml;
+declare function Grid({ children, columns, gap, flex, fill, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, UiSpaceName };
 ```
@@ -2109,9 +2327,11 @@ interface SpacerProps {
     /** A named UI spacing token or typed physical height. */
     height?: UiSpaceName | CssLength;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
 /** A decorative fixed-size or flexible gap for Row, List, and other flex layouts. */
-declare function Spacer({ flex, width, height, className, }: SpacerProps): kerfjs.SafeHtml;
+declare function Spacer({ flex, width, height, className, slot, }: SpacerProps): kerfjs.SafeHtml;
 
 export { CssLength, Spacer, type SpacerProps, UiSpaceName };
 ```