@kerfjs/ui 5.0.0-beta.23 → 5.0.0-beta.25

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.23` and `kerfjs@5.0.0-beta.23`. 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.25` and `kerfjs@5.0.0-beta.25`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/disclosure-arrow`
 
@@ -25,18 +25,20 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { D as DividerSides } from './divider-sides-267FA7sY.js';
 
 interface ToolbarProps {
     leading?: SafeHtml;
     center?: SafeHtml;
     trailing?: SafeHtml;
     label?: string;
-    divider?: boolean;
+    /** Physical divider edges in canonical top/right/bottom/left order. Defaults to bottom. */
+    dividerSides?: DividerSides;
     className?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, divider, className, }: ToolbarProps): SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, dividerSides, className, }: ToolbarProps): SafeHtml;
 
-export { Toolbar, type ToolbarProps };
+export { DividerSides, Toolbar, type ToolbarProps };
 ```
 
 ## `@kerfjs/ui/toolbar-text`
@@ -91,6 +93,11 @@ type ToolbarControlGroupAppearance = 'contained' | 'borderless';
 type ToolbarControlGroupTone = 'default' | 'dark';
 type ToolbarControlGroupButtonAppearance = 'plain' | 'push';
 type ToolbarControlGroupShape = 'pill' | 'rounded';
+type ToolbarControlGroupSize = 'default' | 'compact';
+type ToolbarControlGroupDensity = 'comfortable' | 'tight';
+type ToolbarControlGroupContent = 'icon' | 'text' | 'mixed' | 'avatar';
+type ToolbarControlGroupSelectedChrome = 'raised' | 'filled' | 'outline';
+type ToolbarControlGroupSelectedTone = 'brand' | 'neutral';
 interface ToolbarControlGroupProps {
     children: SafeHtml | SafeHtml[];
     label?: string;
@@ -102,10 +109,19 @@ interface ToolbarControlGroupProps {
     buttonAppearance?: ToolbarControlGroupButtonAppearance;
     /** Corner shape: fully round `pill` (default) or a softer `rounded` rectangle. */
     shape?: ToolbarControlGroupShape;
-}
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, }: ToolbarControlGroupProps): SafeHtml;
-
-export { ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupProps, type ToolbarControlGroupShape, type ToolbarControlGroupTone };
+    size?: ToolbarControlGroupSize;
+    density?: ToolbarControlGroupDensity;
+    content?: ToolbarControlGroupContent;
+    selectedChrome?: ToolbarControlGroupSelectedChrome;
+    selectedTone?: ToolbarControlGroupSelectedTone;
+    /** Size a nested Web Awesome dropdown trigger as part of this group. */
+    nestedDropdown?: boolean;
+    /** Add contrast behind photo-backed avatar content. */
+    scrim?: boolean;
+}
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, selectedChrome, selectedTone, nestedDropdown, scrim, }: ToolbarControlGroupProps): SafeHtml;
+
+export { ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone };
 ```
 
 ## `@kerfjs/ui/floating-toolbar`
@@ -151,6 +167,9 @@ type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undef
     'data-action'?: never;
     'data-has-badge'?: never;
     'data-has-count'?: never;
+    'data-density'?: never;
+    'data-divider'?: never;
+    'data-indicator-tone'?: never;
     'data-toggle'?: never;
 }>;
 type ListHeaderTriggerAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
@@ -162,6 +181,9 @@ type ListHeaderTriggerAttributes = Readonly<Record<`data-${string}`, string | un
 }>;
 interface ListHeaderBaseProps {
     label: string;
+    density?: 'standard' | 'compact';
+    divider?: 'none' | 'before' | 'after' | 'both';
+    indicatorTone?: 'neutral' | 'accent' | 'danger';
     /** Render as an unanimated loading skeleton: keep the label and action affordance, disable interaction. */
     placeholder?: boolean;
     rootAttributes?: ListHeaderRootAttributes;
@@ -199,13 +221,20 @@ type ListHeaderIndicatorProps = {
     count: number;
     countLabel: string;
     badge?: never;
+    status?: never;
+} | {
+    count?: never;
+    countLabel?: never;
+    badge: SafeHtml;
+    status?: never;
 } | {
     count?: never;
     countLabel?: never;
-    badge?: SafeHtml;
+    badge?: never;
+    status?: SafeHtml;
 };
 type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps & ListHeaderModeProps;
-declare function ListHeader({ label, count, countLabel, badge, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, }: ListHeaderProps): SafeHtml;
+declare function ListHeader({ label, count, countLabel, badge, status, density, divider, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, }: ListHeaderProps): SafeHtml;
 
 export { ListHeader, type ListHeaderProps };
 ```
@@ -221,6 +250,10 @@ type ListActionRowRootAttributes = Readonly<Record<`data-${string}`, string | un
     'data-item-id'?: never;
     'data-has-icon'?: never;
     'data-multiline'?: never;
+    'data-density'?: never;
+    'data-divider'?: never;
+    'data-busy'?: never;
+    'data-trailing-visibility'?: never;
     'data-state'?: never;
     'data-selected'?: never;
     'data-pressed'?: never;
@@ -237,6 +270,11 @@ type ListActionRowTrailingAttributes = Readonly<Record<`data-${string}`, string
 interface ListActionRowProps {
     /** Visible dormant content for the primary button. Must not contain interactive descendants. */
     label: string | SafeHtml;
+    description?: string | SafeHtml;
+    status?: string | SafeHtml;
+    busy?: boolean;
+    density?: 'standard' | 'compact';
+    divider?: 'none' | 'before' | 'after' | 'both';
     /** Decorative dormant content for the primary button. Must not contain interactive descendants. */
     icon?: SafeHtml;
     action: string;
@@ -257,12 +295,13 @@ interface ListActionRowProps {
     trailingActionIcon: SafeHtml;
     trailingActionDisabled?: boolean;
     trailingActionTitle?: string;
+    trailingActionVisibility?: 'always' | 'interaction';
     className?: string;
     style?: string;
     rootAttributes?: ListActionRowRootAttributes;
     trailingActionAttributes?: ListActionRowTrailingAttributes;
 }
-declare function ListActionRow({ label, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, 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, style, rootAttributes, trailingActionAttributes, }: ListActionRowProps): SafeHtml;
 
 export { ListActionRow, type ListActionRowProps };
 ```
@@ -278,12 +317,23 @@ type ListItemRootAttributes = Readonly<Record<`data-${string}`, string | undefin
     'data-item-id'?: never;
     'data-has-icon'?: never;
     'data-multiline'?: never;
+    'data-density'?: never;
+    'data-divider'?: never;
+    'data-busy'?: never;
     'data-state'?: never;
 }>;
 interface ListItemProps {
     label: string | SafeHtml;
+    /** App-owned supporting text rendered in the component's stable label stack. */
+    description?: string | SafeHtml;
     icon?: SafeHtml;
     trailing?: SafeHtml;
+    /** Dormant status metadata rendered before trailing content. */
+    status?: string | SafeHtml;
+    /** Show a progress indicator and expose the row as busy without replacing its content. */
+    busy?: boolean;
+    density?: 'standard' | 'compact';
+    divider?: 'none' | 'before' | 'after' | 'both';
     selected?: boolean;
     action: string;
     itemId?: string;
@@ -300,7 +350,7 @@ interface ListItemProps {
     placeholder?: boolean;
     rootAttributes?: ListItemRootAttributes;
 }
-declare function ListItem({ label, icon, trailing, 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, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes, }: ListItemProps): SafeHtml;
 
 export { ListItem, type ListItemProps };
 ```
@@ -356,53 +406,6 @@ declare function ListInsetText({ children, horizontalOnly, className, }: ListIns
 export { ListInsetText, type ListInsetTextProps };
 ```
 
-## `@kerfjs/ui/panel-header`
-
-```ts
-import { SafeHtml } from 'kerfjs';
-import { HeadingLevel } from './toolbar-text.js';
-
-interface PanelHeaderBaseProps {
-    title: string;
-    titleId: string;
-    icon?: SafeHtml;
-    iconClassName?: string;
-    actions?: SafeHtml;
-    /**
-     * Expose the title as a heading landmark (`role="heading"` + `aria-level`). Set it
-     * for a PAGE or view heading so screen-reader heading navigation works and the view
-     * has a primary heading; omit it (the default) for a dialog title, which is instead
-     * referenced via `aria-labelledby={titleId}` and needs no heading landmark.
-     */
-    headingLevel?: HeadingLevel;
-    /** Render the title and summary as unanimated loading skeletons, keeping the icon and actions. */
-    placeholder?: boolean;
-}
-type PanelHeaderSummaryProps = {
-    summary: string;
-    summaryId?: string;
-} | {
-    summary?: never;
-    summaryId?: never;
-};
-type PanelHeaderProps = PanelHeaderBaseProps & PanelHeaderSummaryProps;
-/**
- * The heading of a panel, dialog, or page: a plain `Toolbar` whose leading zone
- * holds an optional icon control group and the title as extra-large `ToolbarText`,
- * whose trailing zone holds the app's action controls, and with an optional
- * subtitle on its own row, left-aligned with the title.
- *
- * PanelHeader overrides no Toolbar styles — it is just a Toolbar with an xl title.
- * The only styling it adds is the icon group's fill/border color and the subtitle.
- * When no icon is provided, the icon group is omitted entirely. The `actions` slot
- * is passed straight into the toolbar's trailing zone; the app supplies whatever
- * trailing controls it needs (typically a `ToolbarControlGroup`).
- */
-declare function PanelHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions, headingLevel, placeholder, }: PanelHeaderProps): SafeHtml;
-
-export { PanelHeader, type PanelHeaderProps };
-```
-
 ## `@kerfjs/ui/value-table`
 
 ```ts
@@ -441,6 +444,8 @@ type AppTabRootAttributes = Readonly<Record<`data-${string}`, string | undefined
     'data-tab-dragging'?: never;
     'data-tab-drop-position'?: never;
 }>;
+type AppTabPresentation = 'pill' | 'segmented' | 'icon-only';
+type AppTabSize = 'default' | 'compact';
 interface AppTabProps {
     id: string;
     name: string;
@@ -449,6 +454,12 @@ interface AppTabProps {
     draggable?: boolean;
     leading?: SafeHtml;
     trailing?: SafeHtml;
+    /** Visual treatment within a TabBar. Icon-only tabs retain `name` as their accessible name. */
+    presentation?: AppTabPresentation;
+    /** Compact tabs use the 32px application-rail height. */
+    size?: AppTabSize;
+    /** Maximum visible label width in CSS pixels before ellipsis. */
+    labelMaxWidth?: number;
     /** Decorative dormant content for the close button. Must not contain interactive descendants. */
     closeIcon?: SafeHtml;
     selectAction?: string;
@@ -458,9 +469,9 @@ interface AppTabProps {
     placeholder?: boolean;
     rootAttributes?: AppTabRootAttributes;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, 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, }: AppTabProps): SafeHtml;
 
-export { AppTab, type AppTabProps };
+export { AppTab, type AppTabPresentation, type AppTabProps, type AppTabSize };
 ```
 
 ## `@kerfjs/ui/tab-bar`
@@ -469,6 +480,9 @@ export { AppTab, type AppTabProps };
 import { SafeHtml } from 'kerfjs';
 
 type TabActivation = 'automatic' | 'manual';
+type TabBarAllocation = 'intrinsic' | 'fill';
+type TabBarPresentation = 'rail' | 'segmented' | 'inspector';
+type TabBarTrailingPlacement = 'separate' | 'adjacent';
 interface TabBarProps {
     id: string;
     label: string;
@@ -483,11 +497,17 @@ interface TabBarProps {
      * selects with Enter / Space / click — use it when selecting a tab is a heavy action.
      */
     activation?: TabActivation;
+    /** How available strip width is allocated across child AppTabs. */
+    allocation?: TabBarAllocation;
+    /** Named strip chrome for application rails, segmented tabs, or inspectors. */
+    presentation?: TabBarPresentation;
+    /** Keep a trailing action beside the final tab or at the far edge of the bar. */
+    trailingPlacement?: TabBarTrailingPlacement;
 }
 /** Render a controlled tab strip. The application owns selection, order, and persistence. */
-declare function TabBar({ id, label, children, leading, trailing, className, activation, }: TabBarProps): SafeHtml;
+declare function TabBar({ id, label, children, leading, trailing, className, activation, allocation, presentation, trailingPlacement, }: TabBarProps): SafeHtml;
 
-export { type TabActivation, TabBar, type TabBarProps };
+export { type TabActivation, TabBar, type TabBarAllocation, type TabBarPresentation, type TabBarProps, type TabBarTrailingPlacement };
 ```
 
 ## `@kerfjs/ui/wire-tab-bars`
@@ -696,6 +716,7 @@ 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';
 
 /** A collapsible Workbench panel — a side rail or the bottom drawer. */
 interface WorkbenchPanel {
@@ -706,6 +727,13 @@ interface WorkbenchPanel {
     size?: number;
     /** Accessible name for the panel region. */
     label?: string;
+    separator?: ResizableRegionSeparator;
+    collapseMotion?: ResizableRegionCollapseMotion;
+    contentOverflow?: ResizableRegionContentOverflow;
+    presentation?: ResizableRegionPresentation;
+    /** Control shown in a safe-area-aware viewport corner while collapsed. */
+    restoreControl?: SafeHtml;
+    restorePosition?: ResizableRegionRestorePosition;
 }
 interface WorkbenchProps {
     id: string;
@@ -735,6 +763,7 @@ export { Workbench, type WorkbenchPanel, type WorkbenchProps };
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { LucideIcon } from './lucide-icon.js';
+import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import 'lucide';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
@@ -784,6 +813,13 @@ interface CollapsiblePanelProps {
     label?: string;
     /** Panel content. */
     children?: SafeHtml | readonly SafeHtml[];
+    separator?: ResizableRegionSeparator;
+    collapseMotion?: ResizableRegionCollapseMotion;
+    contentOverflow?: ResizableRegionContentOverflow;
+    presentation?: ResizableRegionPresentation;
+    /** Control shown in a safe-area-aware viewport corner while collapsed. */
+    restoreControl?: SafeHtml;
+    restorePosition?: ResizableRegionRestorePosition;
     className?: string;
 }
 /**
@@ -796,7 +832,7 @@ interface CollapsiblePanelProps {
  * and persistence semantics, and with `CollapsiblePanelToggle` for the standard
  * affordance. See `docs/24-collapsible-panel.md`.
  */
-declare function CollapsiblePanel({ id, side, collapsed, size, label, children, className, }: CollapsiblePanelProps): SafeHtml;
+declare function CollapsiblePanel({ id, side, collapsed, size, label, children, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
 
 export { CollapsiblePanel, type CollapsiblePanelProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, collapsiblePanelToggleIcon };
 ```
@@ -834,6 +870,11 @@ interface WireSidebarOptions {
      * is always inline.
      */
     deviceClass?: ReadonlySignal<DeviceClass>;
+    /** Compact devices either overlay the panels (default) or hide them in favor
+     *  of an application-owned responsive replacement. */
+    compactPresentation?: 'overlay' | 'hidden';
+    /** Collapse the other panels when one opens in compact overlay mode. */
+    exclusiveCompact?: boolean;
     /** Persistence store (default `globalThis.localStorage`, if present). */
     storage?: SidebarStorage;
 }
@@ -844,7 +885,7 @@ interface WireSidebarOptions {
  * persistence hook. The app owns each `collapsed` signal and the layout; this wire
  * owns the interaction. Returns a disposer. See `docs/24-collapsible-panel.md`.
  */
-declare function wireSidebar(root: HTMLElement, { panels, deviceClass, storage }: WireSidebarOptions): () => void;
+declare function wireSidebar(root: HTMLElement, { panels, deviceClass, compactPresentation, exclusiveCompact, storage, }: WireSidebarOptions): () => void;
 
 export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wireSidebar };
 ```
@@ -907,6 +948,11 @@ import { SafeHtml } from 'kerfjs';
 
 type ResizableRegionAxis = 'horizontal' | 'vertical';
 type ResizableRegionEdge = 'start' | 'end';
+type ResizableRegionSeparator = 'auto' | 'hidden';
+type ResizableRegionCollapseMotion = 'none' | 'slide' | 'fade-slide';
+type ResizableRegionContentOverflow = 'clip' | 'auto' | 'visible';
+type ResizableRegionPresentation = 'inline' | 'overlay' | 'hidden';
+type ResizableRegionRestorePosition = 'bottom-start' | 'bottom-end';
 interface ResizableRegionProps {
     id: string;
     label: string;
@@ -917,15 +963,27 @@ interface ResizableRegionProps {
     edge?: ResizableRegionEdge;
     collapsed?: boolean;
     transitioning?: boolean;
+    /** Whether the separator line is painted. The resize hit target remains available. */
+    separator?: ResizableRegionSeparator;
+    /** Keep the track change instant while optionally sliding the fixed-size content. */
+    collapseMotion?: ResizableRegionCollapseMotion;
+    /** Overflow policy for content such as an open popup inside a bottom drawer. */
+    contentOverflow?: ResizableRegionContentOverflow;
+    /** Inline layout, an edge overlay, or a responsive replacement that removes the region. */
+    presentation?: ResizableRegionPresentation;
+    /** Always-available control rendered while collapsed, outside the clipped region. */
+    restoreControl?: SafeHtml;
+    /** Safe-area-aware viewport corner for `restoreControl`. */
+    restorePosition?: ResizableRegionRestorePosition;
     /** Decorative dormant content for the separator handle. Must not contain interactive descendants. */
     handleIcon?: SafeHtml;
     children: SafeHtml | SafeHtml[];
 }
 declare const clampRegionSize: (size: number, min: number, max: number) => number;
 declare const resizeRegionFromPointer: (startSize: number, delta: number, edge: ResizableRegionEdge) => number;
-declare function ResizableRegion({ id, label, size, min, max, axis, edge, collapsed, transitioning, handleIcon, children, }: ResizableRegionProps): SafeHtml;
+declare function ResizableRegion({ id, label, size, min, max, axis, edge, collapsed, transitioning, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, handleIcon, children, }: ResizableRegionProps): SafeHtml;
 
-export { ResizableRegion, type ResizableRegionAxis, type ResizableRegionEdge, type ResizableRegionProps, clampRegionSize, resizeRegionFromPointer };
+export { ResizableRegion, type ResizableRegionAxis, type ResizableRegionCollapseMotion, type ResizableRegionContentOverflow, type ResizableRegionEdge, type ResizableRegionPresentation, type ResizableRegionProps, type ResizableRegionRestorePosition, type ResizableRegionSeparator, clampRegionSize, resizeRegionFromPointer };
 ```
 
 ## `@kerfjs/ui/wire-resizable-regions`
@@ -1087,10 +1145,10 @@ interface CatalogProps {
     /** Status line content shown at the start of the detail footer. */
     status?: SafeHtml;
     /**
-     * Whether to highlight transparent specimens' 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.
+     * 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;
@@ -1120,11 +1178,15 @@ type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
 type CatalogExampleRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-catalog-example'?: never;
     'data-catalog-example-stack'?: never;
+    'data-catalog-example-label'?: never;
+    'data-catalog-example-note'?: never;
     'data-align'?: never;
 }>;
 type CatalogExampleStackRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-catalog-example'?: never;
     'data-catalog-example-stack'?: never;
+    'data-catalog-example-label'?: never;
+    'data-catalog-example-note'?: never;
     'data-align'?: never;
 }>;
 interface CatalogExampleProps {
@@ -1249,8 +1311,10 @@ interface CatalogRevealOptions {
 declare function revealCatalogEntry(root: HTMLElement, id: string, { block, inline, behavior, media, }?: CatalogRevealOptions): () => void;
 /**
  * Keep a Catalog's opt-in geometry overlay synchronized with its preview.
- * Transparent specimens receive a dashed outer bound and positive margins use
- * devtools-style orange bands. Returns a disposer.
+ * Specimens receive computed border highlights (or a dashed bound when they
+ * have no border and are transparent), while positive computed margins use
+ * devtools-style orange bands. CSS/stylesheet-only changes are observed too.
+ * Returns a disposer.
  */
 declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
 /**
@@ -1330,14 +1394,25 @@ interface SelectBaseProps<Value extends string = string> {
     className?: string;
     /** Empty-value hint text shown in the closed control (the native select placeholder). */
     placeholderText?: string;
+    /** Supporting text shown below the control and associated with its combobox. */
+    hint?: string;
     disabled?: boolean;
     fitMenu?: boolean;
     renderSelected?: (choice: SelectChoice<Value>) => SafeHtml;
     /** Render as an unanimated loading skeleton: the label above a static, empty control box. */
     placeholder?: boolean;
+    /** Form (default), borderless toolbar, or intrinsic navigation chrome. */
+    presentation?: 'form' | 'toolbar-borderless' | 'navigation';
+    size?: 'default' | 'compact';
+    /** Show only the selected choice icon while retaining the Select's accessible name. */
+    selectedPresentation?: 'label' | 'icon-only';
+    /** Let an enclosing ToolbarControlGroup paint the composed focus ring. */
+    focusRingOwner?: 'select' | 'group';
+    /** Maximum closed-control label width in CSS pixels before ellipsis. */
+    labelMaxWidth?: number;
 }
 type SelectProps<Value extends string = string> = SelectBaseProps<Value> & SelectAccessibleName;
-declare function Select<Value extends string>({ name, value, label, ariaLabel, choices, className, placeholderText, disabled, fitMenu, renderSelected, placeholder, }: 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, }: SelectProps<Value>): SafeHtml;
 
 export { Select, type SelectChoice, type SelectProps };
 ```
@@ -1352,15 +1427,17 @@ type StateBannerUrgency = 'status' | 'alert';
 interface StateBannerProps {
     title: string;
     detail?: string;
+    /** Optional compact status or count shown beside the title. */
+    badge?: string;
     icon?: SafeHtml;
     action?: SafeHtml;
     tone?: StateBannerTone;
     urgency?: StateBannerUrgency;
     className?: string;
-    /** Render the title and detail as unanimated loading skeletons, keeping the icon and tone. */
+    /** Render the title, badge, and detail as unanimated loading skeletons, keeping the icon and tone. */
     placeholder?: boolean;
 }
-declare function StateBanner({ title, detail, icon, action, tone, urgency, className, placeholder, }: StateBannerProps): SafeHtml;
+declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, className, placeholder, }: StateBannerProps): SafeHtml;
 
 export { StateBanner, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
 ```
@@ -1404,7 +1481,7 @@ export { LoadingSpinner, type LoadingSpinnerProps };
 import * as kerfjs from 'kerfjs';
 
 interface SkeletonProps {
-    /** Width as any CSS length (e.g. `remify(120px)`, `60%`). Defaults to filling its slot. */
+    /** 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;
@@ -1432,10 +1509,13 @@ export { Skeleton, type SkeletonProps };
 ```ts
 import { SafeHtml } from 'kerfjs';
 
+type SunkenPanelShape = 'rounded' | 'square';
 interface SunkenPanelProps {
     children?: SafeHtml | readonly SafeHtml[];
     /** Optional accessible landmark name for a distinct application region. */
     ariaLabel?: string;
+    /** Corner shape: a rounded rectangle (default) or square corners. */
+    shape?: SunkenPanelShape;
     className?: string;
 }
 /**
@@ -1443,9 +1523,9 @@ interface SunkenPanelProps {
  * stack. The panel owns its background and padding; children own their own
  * borders and internal geometry.
  */
-declare function SunkenPanel({ children, ariaLabel, className, }: SunkenPanelProps): SafeHtml;
+declare function SunkenPanel({ children, ariaLabel, shape, className, }: SunkenPanelProps): SafeHtml;
 
-export { SunkenPanel, type SunkenPanelProps };
+export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ```
 
 ## `@kerfjs/ui/token-search-field`
@@ -1578,7 +1658,7 @@ interface TokenSearchCollapsibleOptions {
     collapseOnEmptyBlur?: boolean;
     /** Collapse an empty field on Escape and restore focus to its trigger. Default: true. */
     collapseOnEscape?: boolean;
-    /** Focus the editor on expand and the trigger on Escape-collapse. Default: true. */
+    /** Focus the editor on expand/controlled clear and the trigger on Escape-collapse. Default: true. */
     manageFocus?: boolean;
     /**
      * Keep an empty field expanded when focus moves to a caller-owned surface