@kerfjs/ui 5.0.0-beta.17 → 5.0.0-beta.21

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.17` and `kerfjs@5.0.0-beta.17`. 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.21` and `kerfjs@5.0.0-beta.21`. 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`
 
@@ -34,7 +34,7 @@ interface ToolbarProps {
     divider?: boolean;
     className?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, divider, className }: ToolbarProps): SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, divider, className, }: ToolbarProps): SafeHtml;
 
 export { Toolbar, type ToolbarProps };
 ```
@@ -47,7 +47,7 @@ import * as kerfjs from 'kerfjs';
 type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small';
 /** ARIA heading level for a title exposed as a heading landmark. */
 type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
-interface ToolbarTextProps {
+interface ToolbarTextBaseProps {
     text: string;
     size?: ToolbarTextSize;
     className?: string;
@@ -61,23 +61,22 @@ interface ToolbarTextProps {
     headingLevel?: HeadingLevel;
     /** Render the text as an unanimated loading skeleton instead of its value. */
     placeholder?: boolean;
-    /**
-     * Wrap onto multiple lines when the text does not fit, instead of the default
-     * single line. Combine with `maxLines` to cap the number of lines. Default false.
-     */
-    wrap?: boolean;
     /**
      * Show a trailing ellipsis (…) where the text is truncated — on the single line
      * (default), or at the `maxLines` boundary when wrapping. Set false to hard-clip
      * instead. Default true.
      */
     ellipsis?: boolean;
-    /**
-     * Cap wrapped text to this many lines, truncating past it. Only takes effect with
-     * `wrap`; ignored on a single line. `null`/omitted wraps without a line cap. Default null.
-     */
-    maxLines?: number | null;
 }
+type ToolbarTextWrappingProps = {
+    /** Wrap onto multiple lines; combine with `maxLines` to cap them. */
+    wrap: true;
+    maxLines?: number | null;
+} | {
+    wrap?: false;
+    maxLines?: never;
+};
+type ToolbarTextProps = ToolbarTextBaseProps & ToolbarTextWrappingProps;
 declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
@@ -88,21 +87,25 @@ export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarText
 ```ts
 import { SafeHtml } from 'kerfjs';
 
+type ToolbarControlGroupAppearance = 'contained' | 'borderless';
+type ToolbarControlGroupTone = 'default' | 'dark';
+type ToolbarControlGroupButtonAppearance = 'plain' | 'push';
+type ToolbarControlGroupShape = 'pill' | 'rounded';
 interface ToolbarControlGroupProps {
     children: SafeHtml | SafeHtml[];
     label?: string;
     className?: string;
     expanded?: boolean;
     single?: boolean;
-    appearance?: 'contained' | 'borderless';
-    tone?: 'default' | 'dark';
-    buttonAppearance?: 'plain' | 'push';
+    appearance?: ToolbarControlGroupAppearance;
+    tone?: ToolbarControlGroupTone;
+    buttonAppearance?: ToolbarControlGroupButtonAppearance;
     /** Corner shape: fully round `pill` (default) or a softer `rounded` rectangle. */
-    shape?: 'pill' | 'rounded';
+    shape?: ToolbarControlGroupShape;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape }: ToolbarControlGroupProps): SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, }: ToolbarControlGroupProps): SafeHtml;
 
-export { ToolbarControlGroup, type ToolbarControlGroupProps };
+export { ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupProps, type ToolbarControlGroupShape, type ToolbarControlGroupTone };
 ```
 
 ## `@kerfjs/ui/floating-toolbar`
@@ -133,7 +136,7 @@ interface FloatingToolbarProps {
  * top toolbar's own inset); override that token to move it. The app owns the
  * controls and their behavior — wire them with `delegate()` as usual.
  */
-declare function FloatingToolbar({ children, label, position, className }: FloatingToolbarProps): SafeHtml;
+declare function FloatingToolbar({ children, label, position, className, }: FloatingToolbarProps): SafeHtml;
 
 export { FloatingToolbar, type FloatingToolbarPosition, type FloatingToolbarProps };
 ```
@@ -159,18 +162,39 @@ type ListHeaderTriggerAttributes = Readonly<Record<`data-${string}`, string | un
 }>;
 interface ListHeaderBaseProps {
     label: string;
-    action?: string;
-    actionLabel?: string;
-    actionIcon?: SafeHtml;
-    actionDisabled?: boolean;
-    disabledReason?: string;
-    expanded?: boolean;
-    toggle?: boolean;
     /** Render as an unanimated loading skeleton: keep the label and action affordance, disable interaction. */
     placeholder?: boolean;
     rootAttributes?: ListHeaderRootAttributes;
     triggerAttributes?: ListHeaderTriggerAttributes;
 }
+type ListHeaderModeProps = {
+    /** Render the title as a controlled disclosure trigger. */
+    toggle: true;
+    action: string;
+    expanded: boolean;
+    actionIcon?: SafeHtml;
+    actionLabel?: never;
+    actionDisabled?: boolean;
+    disabledReason?: string;
+} | {
+    /** Render a separately named trailing action. */
+    toggle?: false;
+    action: string;
+    actionLabel: string;
+    actionIcon: SafeHtml;
+    expanded?: never;
+    actionDisabled?: boolean;
+    disabledReason?: string;
+} | {
+    /** Render a passive section heading. */
+    toggle?: false;
+    action?: never;
+    actionLabel?: never;
+    actionIcon?: never;
+    expanded?: never;
+    actionDisabled?: never;
+    disabledReason?: never;
+};
 type ListHeaderIndicatorProps = {
     count: number;
     countLabel: string;
@@ -180,8 +204,8 @@ type ListHeaderIndicatorProps = {
     countLabel?: never;
     badge?: SafeHtml;
 };
-type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps;
-declare function ListHeader({ label, count, countLabel, badge, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes }: ListHeaderProps): 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;
 
 export { ListHeader, type ListHeaderProps };
 ```
@@ -238,7 +262,7 @@ interface ListActionRowProps {
     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, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, className, style, rootAttributes, trailingActionAttributes, }: ListActionRowProps): SafeHtml;
 
 export { ListActionRow, type ListActionRowProps };
 ```
@@ -276,7 +300,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, icon, trailing, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes, }: ListItemProps): SafeHtml;
 
 export { ListItem, type ListItemProps };
 ```
@@ -297,7 +321,7 @@ interface ListInsetControlProps {
  * Use it for controls that carry their own border and padding but no outer margin
  * — the wrapper adds only the alignment margin and layout, not a second inset.
  */
-declare function ListInsetControl({ children, className }: ListInsetControlProps): SafeHtml;
+declare function ListInsetControl({ children, className, }: ListInsetControlProps): SafeHtml;
 
 export { ListInsetControl, type ListInsetControlProps };
 ```
@@ -327,7 +351,7 @@ interface ListInsetTextProps {
  * Pass `horizontalOnly` to keep the horizontal inset but drop the vertical box
  * space for tight text layout.
  */
-declare function ListInsetText({ children, horizontalOnly, className }: ListInsetTextProps): SafeHtml;
+declare function ListInsetText({ children, horizontalOnly, className, }: ListInsetTextProps): SafeHtml;
 
 export { ListInsetText, type ListInsetTextProps };
 ```
@@ -338,11 +362,9 @@ export { ListInsetText, type ListInsetTextProps };
 import { SafeHtml } from 'kerfjs';
 import { HeadingLevel } from './toolbar-text.js';
 
-interface PanelHeaderProps {
+interface PanelHeaderBaseProps {
     title: string;
     titleId: string;
-    summary?: string;
-    summaryId?: string;
     icon?: SafeHtml;
     iconClassName?: string;
     actions?: SafeHtml;
@@ -356,6 +378,14 @@ interface PanelHeaderProps {
     /** 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`,
@@ -368,7 +398,7 @@ interface PanelHeaderProps {
  * 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;
+declare function PanelHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions, headingLevel, placeholder, }: PanelHeaderProps): SafeHtml;
 
 export { PanelHeader, type PanelHeaderProps };
 ```
@@ -386,14 +416,14 @@ interface ValueTableRowProps {
     /** Render the value as an unanimated loading skeleton, keeping the field label. */
     placeholder?: boolean;
 }
-declare function ValueTableRow({ label, value, icon, className, placeholder }: ValueTableRowProps): SafeHtml;
+declare function ValueTableRow({ label, value, icon, className, placeholder, }: ValueTableRowProps): SafeHtml;
 
 interface ValueTableProps {
     label: string;
     className?: string;
     children: SafeHtml | readonly SafeHtml[];
 }
-declare function ValueTable({ label, className, children }: ValueTableProps): SafeHtml;
+declare function ValueTable({ label, className, children, }: ValueTableProps): SafeHtml;
 
 export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProps };
 ```
@@ -428,7 +458,7 @@ 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, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes, }: AppTabProps): SafeHtml;
 
 export { AppTab, type AppTabProps };
 ```
@@ -438,6 +468,7 @@ export { AppTab, type AppTabProps };
 ```ts
 import { SafeHtml } from 'kerfjs';
 
+type TabActivation = 'automatic' | 'manual';
 interface TabBarProps {
     id: string;
     label: string;
@@ -451,17 +482,20 @@ interface TabBarProps {
      * selects on arrow / Home / End; `'manual'` moves roving focus only and the user
      * selects with Enter / Space / click — use it when selecting a tab is a heavy action.
      */
-    activation?: 'automatic' | 'manual';
+    activation?: TabActivation;
 }
 /** 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, }: TabBarProps): SafeHtml;
 
-export { TabBar, type TabBarProps };
+export { type TabActivation, TabBar, type TabBarProps };
 ```
 
 ## `@kerfjs/ui/wire-tab-bars`
 
 ```ts
+import { TabActivation } from './tab-bar.js';
+import 'kerfjs';
+
 type TabReorderSource = 'pointer' | 'keyboard';
 type TabDropPosition = 'before' | 'after';
 interface TabReorder {
@@ -471,7 +505,7 @@ interface TabReorder {
     position: TabDropPosition;
     source: TabReorderSource;
 }
-type TabActivation = 'automatic' | 'manual';
+
 interface WireTabBarsOptions {
     onReorder: (change: TabReorder) => void;
     /**
@@ -491,7 +525,7 @@ declare function reorderTabs<T>(items: readonly T[], getId: (item: T) => string,
 /** Wire reordering and keyboard navigation while leaving controlled state in the application. */
 declare function wireTabBars(root: HTMLElement | Document, { onReorder, activation }: WireTabBarsOptions): () => void;
 
-export { type TabActivation, type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };
+export { TabActivation, type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };
 ```
 
 ## `@kerfjs/ui/nav-stack`
@@ -532,7 +566,7 @@ interface NavStackProps {
  * cross-fades the chrome across a change. A single-pane layout is a `NavStack`
  * with one entry. See `docs/23-app-layouts.md` §3.1.
  */
-declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className }: NavStackProps): SafeHtml;
+declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className, }: NavStackProps): SafeHtml;
 
 export { NavStack, type NavStackProps, type NavStackView };
 ```
@@ -599,11 +633,65 @@ interface SplitViewProps {
  * resizable wiring with `wireResizableRegions` and the compact back with
  * `wireNavStack`.
  */
-declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className }: SplitViewProps): SafeHtml;
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className, }: SplitViewProps): SafeHtml;
 
 export { SplitView, type SplitViewProps, type SplitViewResizable };
 ```
 
+## `@kerfjs/ui/pane`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+/** Logical sides that can show a {@link Pane} separator. */
+type PaneSeparatorSide = 'block-start' | 'block-end' | 'inline-start' | 'inline-end';
+/** Semantic root elements supported by {@link Pane}. */
+type PaneElement = 'article' | 'aside' | 'div' | 'main' | 'section';
+/** Semantic elements supported by the scrolling content slot. */
+type PaneContentElement = 'div' | 'main' | 'nav' | 'section';
+type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-separator-block-start'?: never;
+    'data-separator-block-end'?: never;
+    'data-separator-inline-start'?: never;
+    'data-separator-inline-end'?: never;
+}>;
+interface PaneProps {
+    /** Optional fixed chrome above the scrolling content, arranged vertically. */
+    header?: SafeHtml | readonly SafeHtml[];
+    /** The pane's primary vertical, scrolling content stack. */
+    children?: SafeHtml | readonly SafeHtml[];
+    /** Optional fixed chrome below the scrolling content. */
+    footer?: SafeHtml | readonly SafeHtml[];
+    /** Root semantics. Defaults to `div`. */
+    element?: PaneElement;
+    /** Scrolling content semantics. Defaults to `div`. */
+    contentElement?: PaneContentElement;
+    /** Independent logical-edge separator lines. Defaults to none. */
+    separators?: readonly PaneSeparatorSide[];
+    id?: string;
+    /** Accessible name for a landmark root such as `aside` or `main`. */
+    label?: string;
+    /** Accessible name for a landmark scrolling slot such as `nav`. */
+    contentLabel?: string;
+    className?: string;
+    headerClassName?: string;
+    contentClassName?: string;
+    footerClassName?: string;
+    /** Safe `data-*` metadata; Pane-owned structural attributes remain protected. */
+    rootAttributes?: PaneRootAttributes;
+}
+/**
+ * An unpadded application column with optional fixed header/footer slots and one
+ * scrolling vertical content owner. Separator lines are independently opt-in on
+ * each logical edge, so the same component works as a sidebar, main area,
+ * inspector, or dialog column.
+ */
+declare function Pane({ header, children, footer, element, contentElement, separators, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, }: PaneProps): SafeHtml;
+
+export { Pane, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
+```
+
 ## `@kerfjs/ui/workbench`
 
 ```ts
@@ -637,7 +725,7 @@ interface WorkbenchProps {
  * work area relayouts once, not per frame. The app owns each `collapsed` flag;
  * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.
  */
-declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className, }: WorkbenchProps): SafeHtml;
 
 export { Workbench, type WorkbenchPanel, type WorkbenchProps };
 ```
@@ -682,7 +770,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, }: CollapsiblePanelToggleProps): SafeHtml;
 interface CollapsiblePanelProps {
     /** A stable id for the panel — `wireSidebar` targets it and toggles reference it. */
     id: string;
@@ -708,7 +796,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, className, }: CollapsiblePanelProps): SafeHtml;
 
 export { CollapsiblePanel, type CollapsiblePanelProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, collapsiblePanelToggleIcon };
 ```
@@ -766,21 +854,21 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 ```ts
 import { SafeHtml } from 'kerfjs';
 
-interface TabScaffoldTab {
-    id: string;
+interface TabScaffoldTab<Id extends string = string> {
+    id: Id;
     label: string;
     /** Decorative icon shown above the label in the bottom bar. */
     icon?: SafeHtml;
     /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */
     content: SafeHtml;
 }
-interface TabScaffoldProps {
+interface TabScaffoldProps<Id extends string = string> {
     id: string;
     /** Accessible name for the tab bar. */
     label: string;
-    tabs: TabScaffoldTab[];
+    tabs: readonly TabScaffoldTab<Id>[];
     /** The controlled active tab id (the app owns selection). */
-    active: string;
+    active: NoInfer<Id>;
     className?: string;
 }
 /**
@@ -791,7 +879,7 @@ interface TabScaffoldProps {
  * 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, label, tabs, active, className }: TabScaffoldProps): SafeHtml;
+declare function TabScaffold<Id extends string>({ id, label, tabs, active, className, }: TabScaffoldProps<Id>): SafeHtml;
 
 export { TabScaffold, type TabScaffoldProps, type TabScaffoldTab };
 ```
@@ -835,7 +923,7 @@ interface ResizableRegionProps {
 }
 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, handleIcon, children, }: ResizableRegionProps): SafeHtml;
 
 export { ResizableRegion, type ResizableRegionAxis, type ResizableRegionEdge, type ResizableRegionProps, clampRegionSize, resizeRegionFromPointer };
 ```
@@ -855,7 +943,7 @@ interface WireResizableRegionsOptions {
     onCommit: (change: ResizeCommit) => void;
 }
 /** Wire pointer and separator-keyboard behavior for every ResizableRegion below root. */
-declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPreview, onCommit }: WireResizableRegionsOptions): () => void;
+declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPreview, onCommit, }: WireResizableRegionsOptions): () => void;
 
 export { type ResizeCommit, type WireResizableRegionsOptions, wireResizableRegions };
 ```
@@ -998,6 +1086,13 @@ interface CatalogProps {
     sidebarFooter?: SafeHtml;
     /** 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.
+     */
+    geometryOverlay?: boolean;
     selectAction?: string;
     toggleSidebarAction?: string;
     toggleThemeAction?: string;
@@ -1013,7 +1108,7 @@ interface CatalogProps {
  * `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, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, }: CatalogProps): SafeHtml;
+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):
@@ -1022,6 +1117,16 @@ declare function Catalog({ brand, sections, active, content, collapsed, theme, h
  * - `'none'` — a content-item / composition that owns its geometry and already aligns; no inset (default).
  */
 type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
+type CatalogExampleRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-catalog-example'?: never;
+    'data-catalog-example-stack'?: never;
+    'data-align'?: never;
+}>;
+type CatalogExampleStackRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-catalog-example'?: never;
+    'data-catalog-example-stack'?: never;
+    'data-align'?: never;
+}>;
 interface CatalogExampleProps {
     /** The example's label, shown as a `ListHeader` above the specimen. Omit for a bare specimen. */
     label?: string;
@@ -1029,6 +1134,8 @@ interface CatalogExampleProps {
     note?: SafeHtml | string;
     /** Alignment inset for the specimen — see {@link CatalogExampleAlign}. Default `'none'`. */
     align?: CatalogExampleAlign;
+    /** Safe authoring `data-*` metadata for the rendered section. Helper-owned structural attributes remain protected. */
+    rootAttributes?: CatalogExampleRootAttributes;
     className?: string;
     children?: SafeHtml | readonly SafeHtml[];
 }
@@ -1040,19 +1147,64 @@ interface CatalogExampleProps {
  * `--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, className, children }: CatalogExampleProps): SafeHtml;
+declare function CatalogExample({ label, note, align, rootAttributes, className, children, }: CatalogExampleProps): SafeHtml;
 interface CatalogExampleStackProps {
     /** Accessible label for the stack region. */
     label?: string;
+    /** Safe authoring `data-*` metadata for the rendered stack. Helper-owned structural attributes remain protected. */
+    rootAttributes?: CatalogExampleStackRootAttributes;
     className?: string;
     children?: SafeHtml | readonly SafeHtml[];
 }
-/** A vertically-stacked group of {@link CatalogExample}s with the catalog's example rhythm. */
-declare function CatalogExampleStack({ label, className, children }: CatalogExampleStackProps): SafeHtml;
+/**
+ * A vertically-stacked group of {@link CatalogExample}s with the catalog's
+ * example rhythm. The semantic `section` becomes a named `region` when `label`
+ * is supplied; an unlabeled stack remains an ordinary grouping.
+ */
+declare function CatalogExampleStack({ label, rootAttributes, className, children, }: CatalogExampleStackProps): SafeHtml;
 
 export { Catalog, type CatalogBrand, type CatalogEntry, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, type CatalogProps, type CatalogRelated, type CatalogResource, type CatalogSecondaryGroup, type CatalogSection };
 ```
 
+## `@kerfjs/ui/catalog-resources`
+
+```ts
+import { CatalogResource } from './catalog.js';
+import 'kerfjs';
+
+/**
+ * Standard resource labels for a Kerf catalog detail footer. Keep these labels
+ * stable across catalogs so people and AI-generated integrations see the same
+ * choices in the same vocabulary.
+ */
+type CatalogResourceKind = 'demoSource' | 'componentSource' | 'designTemplate' | 'guidance' | 'integrationGuidance';
+type CatalogGuidanceKind = 'guidance' | 'integrationGuidance';
+interface CatalogResourceTarget {
+    href: string;
+    /** Optional monospace detail, normally the repository-relative source path. */
+    detail?: string;
+}
+interface CatalogResourcesInput {
+    /** Required source for the runnable demonstration. */
+    demoSource: CatalogResourceTarget;
+    /** Source for the production component; omit for recipes and integrations. */
+    componentSource?: CatalogResourceTarget;
+    /** Optional design-tool template associated with the component. */
+    designTemplate?: CatalogResourceTarget;
+    /** Required UI or integration guidance. */
+    guidance: CatalogResourceTarget;
+    /** Use `integrationGuidance` when the component implementation is upstream. */
+    guidanceKind?: CatalogGuidanceKind;
+}
+/**
+ * Build the standard catalog resource group in its canonical order: demo,
+ * component, optional design template, then guidance.
+ */
+declare function catalogResources(input: CatalogResourcesInput): CatalogResource[];
+
+export { type CatalogGuidanceKind, type CatalogResourceKind, type CatalogResourceTarget, type CatalogResourcesInput, catalogResources };
+```
+
 ## `@kerfjs/ui/wire-catalog`
 
 ```ts
@@ -1067,11 +1219,40 @@ interface WireCatalogOptions {
     onToggleSecondary?: () => void;
     /** When set, `?<urlParam>=<id>` is written on select via `history.replaceState`. */
     urlParam?: string;
+    /**
+     * Reveal the chosen sidebar row after selection. `true` uses desktop-safe
+     * defaults; pass options to customize scroll alignment or the media guard.
+     */
+    revealSelection?: boolean | CatalogRevealOptions;
     selectAction?: string;
     toggleSidebarAction?: string;
     toggleThemeAction?: string;
     toggleSecondaryAction?: string;
 }
+interface CatalogRevealOptions {
+    /** Scroll alignment within the sidebar. Default `'nearest'`. */
+    block?: ScrollLogicalPosition;
+    /** Cross-axis alignment. Default `'nearest'`. */
+    inline?: ScrollLogicalPosition;
+    /** Scroll behavior. Default `'auto'`. */
+    behavior?: ScrollBehavior;
+    /**
+     * Only reveal when this media query matches. Defaults to the Catalog's
+     * desktop layout; pass `false` to reveal at every viewport size.
+     */
+    media?: string | false;
+}
+/**
+ * Reveal one Catalog sidebar entry after the controlled render settles without
+ * moving focus. Returns a cancellation function for rapid selection changes.
+ */
+declare function revealCatalogEntry(root: HTMLElement, id: string, { block, inline, behavior, media, }?: CatalogRevealOptions): () => void;
+/**
+ * Keep a Catalog's opt-in geometry overlay synchronized with its preview.
+ * Transparent specimens receive a dashed outer bound and positive margins use
+ * devtools-style orange bands. Returns a disposer.
+ */
+declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
 /**
  * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar
  * item selection (and the related-entry popup menu), the sidebar collapse toggle, and
@@ -1079,9 +1260,9 @@ interface WireCatalogOptions {
  * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.
  * Returns a disposer.
  */
-declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
 
-export { type WireCatalogOptions, wireCatalog };
+export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
 ```
 
 ## `@kerfjs/ui/segmented-control`
@@ -1093,18 +1274,18 @@ type SegmentedControlAppearance = 'filled' | 'outlined' | 'toolbar';
 type SegmentedControlShape = 'rounded' | 'pill';
 type SegmentedControlSize = 'small' | 'default';
 type SegmentedControlLayout = 'content' | 'equal';
-interface SegmentedControlChoice {
-    value: string;
+interface SegmentedControlChoice<Value extends string = string> {
+    value: Value;
     label: string;
     content?: SafeHtml;
     title?: string;
     disabled?: boolean;
 }
-interface SegmentedControlProps {
+interface SegmentedControlProps<Value extends string = string> {
     id: string;
     label: string;
-    value: string;
-    choices: readonly SegmentedControlChoice[];
+    value: NoInfer<Value>;
+    choices: readonly SegmentedControlChoice<Value>[];
     action?: string;
     appearance?: SegmentedControlAppearance;
     shape?: SegmentedControlShape;
@@ -1114,31 +1295,74 @@ interface SegmentedControlProps {
     /** Render as an unanimated loading skeleton, disabling every segment. */
     placeholder?: boolean;
 }
-declare function SegmentedControl({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, }: SegmentedControlProps): SafeHtml;
+declare function SegmentedControl<Value extends string>({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, }: SegmentedControlProps<Value>): SafeHtml;
 
 export { SegmentedControl, type SegmentedControlAppearance, type SegmentedControlChoice, type SegmentedControlLayout, type SegmentedControlProps, type SegmentedControlShape, type SegmentedControlSize };
 ```
 
+## `@kerfjs/ui/select`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { LucideNode } from './lucide-icon.js';
+import 'lucide';
+
+interface SelectChoice<Value extends string = string> {
+    value: Value;
+    label: string;
+    icon?: LucideNode;
+    iconName?: string;
+    color?: string;
+    group?: string;
+    separatorBefore?: boolean;
+}
+type SelectAccessibleName = {
+    label: string;
+    ariaLabel?: string;
+} | {
+    label?: never;
+    ariaLabel: string;
+};
+interface SelectBaseProps<Value extends string = string> {
+    name: string;
+    value: NoInfer<Value>;
+    choices: readonly SelectChoice<Value>[];
+    className?: string;
+    /** Empty-value hint text shown in the closed control (the native select placeholder). */
+    placeholderText?: string;
+    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;
+}
+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;
+
+export { Select, type SelectChoice, type SelectProps };
+```
+
 ## `@kerfjs/ui/state-banner`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
 
 type StateBannerTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+type StateBannerUrgency = 'status' | 'alert';
 interface StateBannerProps {
     title: string;
     detail?: string;
     icon?: SafeHtml;
     action?: SafeHtml;
     tone?: StateBannerTone;
-    urgency?: 'status' | 'alert';
+    urgency?: StateBannerUrgency;
     className?: string;
     /** Render the title 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, icon, action, tone, urgency, className, placeholder, }: StateBannerProps): SafeHtml;
 
-export { StateBanner, type StateBannerProps, type StateBannerTone };
+export { StateBanner, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
 ```
 
 ## `@kerfjs/ui/empty-state`
@@ -1154,7 +1378,7 @@ interface EmptyStateProps {
     busy?: boolean;
     className?: string;
 }
-declare function EmptyState({ title, detail, icon, action, busy, className }: EmptyStateProps): SafeHtml;
+declare function EmptyState({ title, detail, icon, action, busy, className, }: EmptyStateProps): SafeHtml;
 
 export { EmptyState, type EmptyStateProps };
 ```
@@ -1198,11 +1422,32 @@ 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, }: SkeletonProps): kerfjs.SafeHtml;
 
 export { Skeleton, type SkeletonProps };
 ```
 
+## `@kerfjs/ui/sunken-panel`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+interface SunkenPanelProps {
+    children?: SafeHtml | readonly SafeHtml[];
+    /** Optional accessible landmark name for a distinct application region. */
+    ariaLabel?: string;
+    className?: string;
+}
+/**
+ * A lowered application surface with one compact inset and a vertical content
+ * stack. The panel owns its background and padding; children own their own
+ * borders and internal geometry.
+ */
+declare function SunkenPanel({ children, ariaLabel, className, }: SunkenPanelProps): SafeHtml;
+
+export { SunkenPanel, type SunkenPanelProps };
+```
+
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
@@ -1214,7 +1459,15 @@ interface TokenSearchToken {
     offset?: number;
     accessibleLabel?: string;
 }
-interface TokenSearchFieldProps {
+type TokenSearchEditorAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-key'?: never;
+    'data-morph-skip'?: never;
+    'data-token-search-editor'?: never;
+    'data-token-count'?: never;
+    'data-placeholder'?: never;
+}>;
+interface TokenSearchFieldBaseProps {
     id: string;
     label: string;
     query?: string;
@@ -1223,12 +1476,6 @@ interface TokenSearchFieldProps {
     tokenPlaceholder?: string;
     disabled?: boolean;
     autofocus?: boolean;
-    /** Allow an empty field to render as one iconic action. */
-    collapsible?: boolean;
-    /** Keep an empty collapsible field open while the application owns focus. */
-    expanded?: boolean;
-    expandAction?: string;
-    expandLabel?: string;
     leading?: SafeHtml;
     trailing?: SafeHtml;
     editAction?: string;
@@ -1236,8 +1483,22 @@ interface TokenSearchFieldProps {
     clearAction?: string;
     clearLabel?: string;
     className?: string;
-    editorAttributes?: Readonly<Record<`data-${string}`, string>>;
+    editorAttributes?: TokenSearchEditorAttributes;
 }
+type TokenSearchCollapsibleProps = {
+    /** Allow an empty field to render as one iconic action. */
+    collapsible: true;
+    /** Keep an empty collapsible field open while the application owns focus. */
+    expanded?: boolean;
+    expandAction?: string;
+    expandLabel?: string;
+} | {
+    collapsible?: false;
+    expanded?: never;
+    expandAction?: never;
+    expandLabel?: never;
+};
+type TokenSearchFieldProps = TokenSearchFieldBaseProps & TokenSearchCollapsibleProps;
 interface TokenSearchFieldValue {
     query: string;
     tokens: TokenSearchToken[];
@@ -1248,7 +1509,7 @@ declare function readTokenSearchField(editor: HTMLElement, knownTokens?: readonl
 /** Focus an editor and place its caret at a text offset, skipping atomic token chips. */
 declare function placeTokenSearchCaret(editor: HTMLElement, offset?: number): void;
 
-export { TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValue, type TokenSearchToken, placeTokenSearchCaret, readTokenSearchField };
+export { type TokenSearchEditorAttributes, TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValue, type TokenSearchToken, placeTokenSearchCaret, readTokenSearchField };
 ```
 
 ## `@kerfjs/ui/wire-token-search-fields`
@@ -1285,21 +1546,26 @@ interface TokenSearchTokenRemoval {
  * for the caller to apply, while caret movement past a chip is a pure ephemeral
  * mechanic the helper performs itself.
  */
-interface TokenSearchKeyboardOptions {
+interface TokenSearchKeyboardBaseOptions {
     /**
      * From a collapsed caret with no selection, Backspace removes the token
      * immediately before it and Delete the token immediately after — reported via
      * `onRemoveToken` — instead of deleting a character. Default: true.
      */
-    removeAdjacentToken?: boolean;
     /**
      * ArrowRight moves the caret past a trailing atomic token so text typed next
      * lands after the chip. Default: true.
      */
     moveCaretPastToken?: boolean;
-    /** Apply the reported removal to your controlled state, then re-render. */
-    onRemoveToken?: (removal: TokenSearchTokenRemoval) => void;
 }
+type TokenSearchKeyboardOptions = TokenSearchKeyboardBaseOptions & ({
+    removeAdjacentToken?: true;
+    /** Apply the reported removal to your controlled state, then re-render. */
+    onRemoveToken: (removal: TokenSearchTokenRemoval) => void;
+} | {
+    removeAdjacentToken: false;
+    onRemoveToken?: never;
+});
 /**
  * Managed collapsible behavior for the iconic TokenSearchField. Every piece is on
  * by default; disable a specific one to own it in the app. Provide `signals` to
@@ -1332,8 +1598,8 @@ interface WireTokenSearchFieldsOptions {
     onEdit?: (edit: TokenSearchEdit) => void;
     /** Managed collapsible transient behavior. `true`/omitted = on with defaults; `false` = fully off. */
     collapsible?: boolean | TokenSearchCollapsibleOptions;
-    /** Opt-in atomic-chip keyboard behavior (off by default). `true` = on with defaults. */
-    keyboard?: boolean | TokenSearchKeyboardOptions;
+    /** Opt-in atomic-chip keyboard behavior (off by default). */
+    keyboard?: false | TokenSearchKeyboardOptions;
 }
 /**
  * The value returned from {@link wireTokenSearchFields}: call it (or `dispose()`) to
@@ -1357,7 +1623,7 @@ interface TokenSearchFieldsHandle {
  * expand/collapse/focus. Returns a {@link TokenSearchFieldsHandle} — a disposer that also
  * exposes the managed `expanded` state per field id.
  */
-declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
+declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard, }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
 
 export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
 ```