@kerfjs/ui 5.0.0-beta.53 → 5.0.0-beta.55

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.53` and `kerfjs@5.0.0-beta.53`. 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.55` and `kerfjs@5.0.0-beta.55`. 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`
 
@@ -340,14 +340,93 @@ interface FloatingToolbarProps {
  * restore button) that sits over the content but NOT over dialogs or overlays
  * (it is not in the top layer). It is inset from the container edges by
  * `--kui-floating-toolbar-inset` (default `--kui-space-m`, i.e. 8px more than a
- * top toolbar's own inset); override that token to move it. The app owns the
- * controls and their behavior — wire them with `delegate()` as usual.
+ * top toolbar's own inset); override that token, on the toolbar or an
+ * ancestor, to move it. Inside a `Workbench`, `CollapsiblePanel`, or
+ * `ResizableRegion` restore corner the corner owns the inset, so the toolbar
+ * floats from the corner's own position. The app owns the controls and their
+ * behavior — wire them with `delegate()` as usual.
  */
 declare function FloatingToolbar({ children, label, position, className, slot, }: FloatingToolbarProps): kerfjs.SafeHtml;
 
 export { FloatingToolbar, type FloatingToolbarPosition, type FloatingToolbarProps };
 ```
 
+## `@kerfjs/ui/popup-menu`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+type PopupMenuPlacement = 'bottom-start' | 'bottom' | 'bottom-end' | 'top-start' | 'top' | 'top-end';
+type PopupMenuDataAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-action'?: never;
+    'data-component'?: never;
+    'data-key'?: never;
+    'data-morph-skip-children'?: never;
+}>;
+/** One command in the menu. */
+interface PopupMenuItem {
+    kind?: 'item';
+    label: string;
+    /** Delegated `data-action` the app handles when the item is chosen. */
+    action?: string;
+    /** Native `wa-dropdown-item` value, reported by its `wa-select` event. */
+    value?: string;
+    /** Leading icon, typically a `LucideIcon`; it is placed in the item's icon slot. */
+    icon?: SafeHtml;
+    disabled?: boolean;
+    /** Application `data-*` metadata such as a record id. */
+    attributes?: PopupMenuDataAttributes;
+}
+/** A labeled group heading; items that follow it belong to the group. */
+interface PopupMenuHeading {
+    kind: 'heading';
+    label: string;
+}
+/** A separator between groups of items. */
+interface PopupMenuDivider {
+    kind: 'divider';
+}
+type PopupMenuEntry = PopupMenuItem | PopupMenuHeading | PopupMenuDivider;
+type PopupMenuTriggerName = {
+    /** Visible trigger text, which is also its accessible name. */
+    text: string;
+    label?: never;
+} | {
+    text?: never;
+    /**
+     * Accessible name of an icon-only trigger, rendered as visually hidden
+     * slotted text (a Web Awesome button takes its name from its content).
+     */
+    label: string;
+};
+type PopupMenuProps = PopupMenuTriggerName & {
+    /** Trigger icon, typically a `LucideIcon`, before any visible text. */
+    icon?: KerfUiContent;
+    items: readonly PopupMenuEntry[];
+    /** Where the menu opens relative to its trigger. Defaults to `bottom-start`. */
+    placement?: PopupMenuPlacement;
+    /** Show the disclosure caret after the trigger content. Defaults to true. */
+    caret?: boolean;
+    disabled?: boolean;
+    /** Application `data-*` metadata on the menu root. */
+    rootAttributes?: PopupMenuDataAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+};
+/**
+ * An action menu: a trigger button that opens a list of commands. Renders the
+ * `wa-dropdown` root directly, so a `single` `ToolbarControlGroup` (with
+ * `nestedDropdown`) or a `PopupSurface` sizes and insets it as usual. Items
+ * dispatch through delegated `data-action`s; the app owns the commands and any
+ * open-state reaction. Import `@kerfjs/ui/popup-menu/register` once to register
+ * the Web Awesome elements.
+ */
+declare function PopupMenu({ text, label, icon, items, placement, caret, disabled, rootAttributes, slot, }: PopupMenuProps): SafeHtml;
+
+export { PopupMenu, type PopupMenuDivider, type PopupMenuEntry, type PopupMenuHeading, type PopupMenuItem, type PopupMenuPlacement, type PopupMenuProps };
+```
+
 ## `@kerfjs/ui/list-header`
 
 ```ts
@@ -653,6 +732,10 @@ import * as kerfjs from 'kerfjs';
 import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
+type ListInsetTextRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-sides'?: never;
+}>;
 interface ListInsetTextProps {
     /** Text (or inline content) that carries no margin, border, or padding of its own. */
     children: KerfUiContent | string;
@@ -666,6 +749,8 @@ interface ListInsetTextProps {
      */
     horizontalOnly?: boolean;
     className?: string;
+    /** Safe `data-*` metadata; component-owned structural attributes stay protected. */
+    rootAttributes?: ListInsetTextRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
@@ -677,7 +762,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, slot, }: ListInsetTextProps): kerfjs.SafeHtml;
+declare function ListInsetText({ children, sides, horizontalOnly, className, rootAttributes, slot, }: ListInsetTextProps): kerfjs.SafeHtml;
 
 export { ListInsetText, type ListInsetTextProps, Sides };
 ```
@@ -751,11 +836,13 @@ interface AppTabProps {
     /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
     placeholder?: boolean;
     /**
-     * Dormant but named: the tab is known and still opening. Keeps `name`
-     * visible in the quiet text color and as the tab's accessible name, shows
-     * `trailing` (for example a `LoadingSpinner`), and disables select, close,
-     * and dragging with `aria-busy`, like `placeholder`. Same pill geometry as
-     * the live tab, so swapping it in place does not shift the bar.
+     * Named and still opening: the tab is known but its content is loading.
+     * Keeps `name` visible in the quiet text color and as the tab's accessible
+     * name, shows `trailing` (for example a `LoadingSpinner`), and marks the
+     * tab `aria-busy`. Unlike `placeholder` it stays selectable — the
+     * application shows placeholder content in its panel until loading
+     * completes — while close and dragging stay disabled. Same pill geometry
+     * as the live tab, so swapping it in place does not shift the bar.
      * `placeholder` wins when both are set.
      */
     pending?: boolean;
@@ -1050,32 +1137,189 @@ export { Pane, type PaneContentElement, type PaneElement, type PaneProps, type P
 import { SafeHtml } from 'kerfjs';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { a as PanelToolbar, b as PanelToggle } from './panel-toolbar-BFQxFITu.js';
+import { ToolbarProps } from './toolbar.js';
+import './lucide-icon.js';
+import 'lucide';
+import './divider-sides-BzB6rphT.js';
+import './pane.js';
 
+/** The standard toggle a Workbench renders for a panel (see {@link PanelToggle}). */
+type WorkbenchPanelToggle = PanelToggle;
+/**
+ * A Workbench panel's top toolbar, composed by the Workbench so its groups can
+ * follow the panel's open state (see {@link PanelToolbar} for the roles).
+ * A collapsed rail's `constant` groups and toggle go to the leading edge of
+ * `mainToolbar` (left rail) or its trailing edge (right rail); a collapsed
+ * drawer's go to the trailing edge of `mainBottomToolbar`, else to a
+ * `FloatingToolbar` in the work area's bottom-end corner.
+ */
+type WorkbenchPanelToolbar = PanelToolbar;
+/** The work area's top toolbar; collapsed rails add their groups to it. */
+interface WorkbenchMainToolbar {
+    label: string;
+    /** The work area's title, usually an extra-large `ToolbarText`. */
+    title?: KerfUiContent;
+    /** Groups after the title. */
+    leading?: KerfUiContent;
+    center?: KerfUiContent;
+    /** Groups at the trailing edge, before a collapsed right rail's groups. */
+    trailing?: KerfUiContent;
+    /** The toolbar's narrow-width policy (see `Toolbar.responsive`). */
+    responsive?: ToolbarProps['responsive'];
+    responsiveAt?: ToolbarProps['responsiveAt'];
+}
+/** The work area's bottom toolbar; a collapsed drawer adds its groups to it. */
+interface WorkbenchMainBottomToolbar {
+    label: string;
+    leading?: KerfUiContent;
+    trailing?: KerfUiContent;
+}
+/**
+ * The work area: the app's `main` under `mainToolbar` (and above
+ * `mainBottomToolbar`), with each collapsed panel's groups added to the
+ * toolbar on its side. Without either toolbar, `main` renders as given.
+ */
+/**
+ * Whether the work area's header or footer chrome stays pinned (`fixed`) or
+ * scrolls away with the content (`scroll`).
+ */
+type WorkbenchChromePlacement = 'fixed' | 'scroll';
+
+/**
+ * The Workbench container breakpoint below which a panel presents as an
+ * overlay: `narrow` (704px or less) or `compact` (448px or less) — the same
+ * breakpoints as `ResizableRegion`'s `responsiveFillAt` — or `never` to keep
+ * it inline at every width.
+ */
+type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never';
+/**
+ * How wide a rail's overlay is in a compact (448px or less) Workbench: `inset`
+ * fills the Workbench less a dismiss margin on the side away from the rail's
+ * edge, so a press beside it closes it; `full` fills the Workbench.
+ */
+type WorkbenchCompactOverlay = 'inset' | 'full';
+/** Drag-resize limits for a resizable Workbench panel, in px. */
+interface WorkbenchPanelResizable {
+    /** Smallest size (default 180 for a rail, 120 for the drawer). */
+    min?: number;
+    /** Largest size (default 480). */
+    max?: number;
+}
 /** A collapsible Workbench panel — a side rail or the bottom drawer. */
 interface WorkbenchPanel {
     content: KerfUiContent;
+    /**
+     * The panel's top toolbar, composed by the Workbench: its `constant` groups
+     * and standard `toggle` move to the work area's toolbar while the panel is
+     * collapsed. With it, `content` renders in a `Pane` below the toolbar.
+     */
+    toolbar?: WorkbenchPanelToolbar;
+    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    footer?: KerfUiContent;
     /** Whether the panel is currently collapsed (the app owns this). */
     collapsed?: boolean;
-    /** Rail width, or drawer height, in px. Overrides the CSS default. */
+    /**
+     * Rail width, or drawer height, in px. Overrides the CSS default. For a
+     * resizable panel it is the current size (default 280 for a rail, 220 for
+     * the drawer), clamped to the limits; the app owns it and `wireWorkbench`
+     * reports each resize.
+     */
     size?: number;
+    /**
+     * Opt in to drag and keyboard resizing on the panel's inner separator:
+     * `true` for the default limits, or `{ min, max }`. Off by default. Pair it
+     * with `wireWorkbench` from `@kerfjs/ui/wire-workbench`.
+     */
+    resizable?: boolean | WorkbenchPanelResizable;
     /** 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. */
+    /**
+     * Present the panel as an overlay, without a separator, below a Workbench
+     * container breakpoint, and inline above it — the CSS decides, so the app
+     * needs no device-class check. A rail overlays from its side at full
+     * height, over the work area and an open drawer; the bottom drawer
+     * overlays the bottom of the work-area column. Rails default to `narrow`
+     * (pass `never` to keep one inline); the drawer defaults to inline.
+     */
+    responsiveOverlayAt?: WorkbenchResponsiveOverlayAt;
+    /**
+     * A rail's overlay width in a compact Workbench (default `inset`: the
+     * Workbench less `--kui-workbench-overlay-dismiss-margin`, 44px). Ignored
+     * by the drawer.
+     */
+    compactOverlay?: WorkbenchCompactOverlay;
+    /**
+     * Control shown while collapsed, in a safe-area-aware corner of the
+     * Workbench (not the viewport); the bottom drawer's sits in the work-area
+     * column. Prefer `toolbar.toggle`, which the Workbench relocates into the
+     * work area's toolbar (or this corner when that toolbar is absent).
+     */
     restoreControl?: SafeHtml;
     restorePosition?: ResizableRegionRestorePosition;
 }
 interface WorkbenchProps {
+    /**
+     * The Workbench's `id`. Each panel's `id` derives from it —
+     * `<id>-left-rail`, `<id>-right-rail`, `<id>-bottom-drawer` — so a toggle
+     * can name the panel it shows and hides with `aria-controls`.
+     */
     id: string;
     label: string;
     /** The central work area. */
     main: KerfUiContent;
+    /**
+     * The work area's top toolbar. A collapsed left rail's `constant` groups
+     * and toggle lead it; a collapsed right rail's trail it. With it, `main`
+     * renders in a `Pane` below the toolbar.
+     */
+    mainToolbar?: WorkbenchMainToolbar;
+    /**
+     * Fixed content under `mainToolbar` — supporting copy such as a
+     * description — divided from the scrolling `main` below it.
+     */
+    mainHeader?: KerfUiContent;
+    /**
+     * Fixed content over `mainBottomToolbar` — a status line or a resource
+     * toolbar — divided from the scrolling `main` above it.
+     */
+    mainFooter?: KerfUiContent;
+    /**
+     * The work area's bottom toolbar. A collapsed drawer's `constant` groups and
+     * toggle trail it; without it they float in the work area's corner.
+     */
+    mainBottomToolbar?: WorkbenchMainBottomToolbar;
+    /**
+     * Whether `mainToolbar` and `mainHeader` stay pinned (`fixed`, default) or
+     * scroll away with `main` (`scroll`) — useful where large text would leave
+     * pinned chrome little room.
+     */
+    mainHeaderPlacement?: WorkbenchChromePlacement;
+    /** The same for `mainFooter` and `mainBottomToolbar` (default `fixed`). */
+    mainFooterPlacement?: WorkbenchChromePlacement;
     leftRail?: WorkbenchPanel;
     rightRail?: WorkbenchPanel;
     bottomDrawer?: WorkbenchPanel;
+    /**
+     * Minimum width, in px, the work area keeps beside the inline rails, fixed
+     * or `resizable` (default 320; `0` turns it off). Resizing a rail stops
+     * where the work area would drop below it, and inline rails shrink
+     * proportionally when the Workbench gets narrower. Workbenches without a
+     * rail ignore it.
+     */
+    mainMinSize?: number;
+    /**
+     * Minimum height, in px, the work area keeps above an inline bottom drawer,
+     * fixed or `resizable` (default 120; `0` turns it off) — the drawer's
+     * counterpart of `mainMinSize`. Resizing the drawer stops where the work
+     * area would drop below it, and the drawer shrinks when the Workbench gets
+     * shorter. Workbenches without a drawer ignore it.
+     */
+    mainMinHeight?: number;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -1087,36 +1331,153 @@ interface WorkbenchProps {
  * a composited transform — the instant-width / sliding-content technique, so the
  * work area relayouts once, not per frame. Bottom-drawer content stays anchored
  * to the shell's stable bottom edge throughout that transition. The app owns
- * each `collapsed` flag; the collapse is pure CSS (no wire). See
- * `docs/23-app-layouts.md` §3.3.
+ * each `collapsed` flag; the collapse is pure CSS. A collapsed panel renders
+ * `inert` and `aria-hidden`, so neither Tab nor assistive technology reaches
+ * controls that have slid out of view or an empty landmark (its restore control
+ * lives outside it and stays reachable). A panel may opt in to drag and keyboard resizing with
+ * `resizable`, which `wireWorkbench` drives. See `docs/23-app-layouts.md` §3.3.
  */
-declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className, slot, }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainMinSize, mainMinHeight, className, slot, }: WorkbenchProps): SafeHtml;
 
-export { Workbench, type WorkbenchPanel, type WorkbenchProps };
+export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
+```
+
+## `@kerfjs/ui/wire-workbench`
+
+```ts
+import { Signal, ReadonlySignal } from 'kerfjs';
+import { DeviceClass } from './device-class.js';
+
+/** A Workbench panel slot, named after its `WorkbenchProps` prop. */
+type WorkbenchPanelKey = 'leftRail' | 'rightRail' | 'bottomDrawer';
+
+/** Minimal `localStorage`-shaped store, so the persistence hook is testable. */
+interface WorkbenchStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/** One Workbench panel's app-owned state. */
+interface WireWorkbenchPanel {
+    /**
+     * The app-owned size signal a `resizable` panel renders as its `size`.
+     * `wireWorkbench` writes each committed resize here; collapsing never
+     * touches it, so an expanded panel returns at the size it had. Omit it for
+     * a panel that is not resizable.
+     */
+    size?: Signal<number>;
+    /**
+     * When set with `size`, the size is loaded from and saved to `storage`
+     * under this key, so the panel remembers the user's size.
+     */
+    storageKey?: string;
+    /**
+     * The app-owned signal the panel renders as its `collapsed`. With it (and
+     * `dismissOverlays`, on by default) `wireWorkbench` treats the panel as a
+     * transient overlay while it presents as one: it collapses when its
+     * `responsiveOverlayAt` breakpoint begins to apply and gets its inline state
+     * back when the breakpoint stops applying, an open overlay takes focus and
+     * keeps Tab inside it, and it closes on Escape or a press outside it.
+     */
+    collapsed?: Signal<boolean>;
+}
+/** A resize the user made, after `wireWorkbench` wrote it to the size signal. */
+interface WorkbenchResize {
+    panel: WorkbenchPanelKey;
+    size: number;
+    source: 'keyboard' | 'pointer';
+}
+interface WireWorkbenchOptions {
+    /** The `id` the `Workbench` was rendered with. */
+    id: string;
+    /**
+     * The wired panels, keyed like the `Workbench` props. Render a panel given
+     * a `size` with `resizable` and `size={panel.size.value}`, and one given a
+     * `collapsed` signal with `collapsed={panel.collapsed.value}`.
+     */
+    panels: Partial<Record<WorkbenchPanelKey, WireWorkbenchPanel>>;
+    /**
+     * When provided, resizing is suspended while `deviceClass.compact` is true —
+     * the classes where rails become overlay drawers or are replaced.
+     */
+    deviceClass?: ReadonlySignal<DeviceClass>;
+    /** Persistence store (default `globalThis.localStorage`, if present). */
+    storage?: WorkbenchStorage;
+    /** Keyboard step in px (default 16). */
+    step?: number;
+    /** Shift+arrow step in px (default 64). */
+    largeStep?: number;
+    /** Called after each committed resize. */
+    onResize?: (change: WorkbenchResize) => void;
+    /**
+     * Treat the panels given a `collapsed` signal as transient overlays while
+     * they present as overlays (default `true`), like `wireSidebar`'s compact
+     * overlay: a panel whose `responsiveOverlayAt` breakpoint begins to apply
+     * starts collapsed, with no collapse motion, and gets its inline collapsed
+     * state back when the breakpoint stops applying (and on disposal); an open
+     * overlay panel, responsive or `presentation: "overlay"`, closes on Escape
+     * or a press that starts and ends outside it. A panel that opens as an
+     * overlay takes focus on its first focusable control, and while it is open
+     * Tab and Shift+Tab cycle through its controls instead of reaching the
+     * work area it covers (the ARIA dialog pattern of `wireSidebar`'s compact
+     * overlay); inline panels never move focus. Focus stranded in a closing
+     * panel — however it closed, the app's own control inside it included —
+     * returns to the control that had it when the panel opened, else to the
+     * panel's restore control, else to a control outside the panel whose
+     * `aria-controls` names it (each panel's `id` is its region id, e.g.
+     * `studio-left-rail`) — the fallback for a panel already open at wire-up.
+     * An opener inside a panel that has closed since is skipped. `false` leaves
+     * every `collapsed` write and all focus handling to the app.
+     */
+    dismissOverlays?: boolean;
+    /**
+     * Keep overlays exclusive (default `true`), like `wireSidebar`'s
+     * `exclusiveCompact`: when a panel opens while it presents as an overlay,
+     * every other open overlay panel — rails and the bottom drawer alike —
+     * closes, so one overlay never covers another's controls. Panels presenting
+     * inline are never closed by it. Applies only with `dismissOverlays`.
+     */
+    exclusiveOverlays?: boolean;
+}
+/**
+ * Wire a `Workbench`'s panels. For `resizable` panels given a `size` signal:
+ * pointer drags and arrow / Shift+arrow / Home / End on each panel's
+ * separator, clamped to the panel's limits and to the room that leaves the
+ * work area its minimum width and height, committed to the app-owned size signals.
+ * Optional persistence loads and saves each size; optional `deviceClass`
+ * suspends resizing on compact classes. Collapse stays the app's `collapsed`
+ * flag and never changes a size. For panels given a `collapsed` signal,
+ * overlays are transient (`dismissOverlays`): a responsive overlay starts
+ * collapsed, an open overlay takes focus and keeps Tab inside it, it closes
+ * on Escape or an outside press, and
+ * opening one overlay closes the others (`exclusiveOverlays`). Returns a disposer. See `docs/23-app-layouts.md` §3.3.
+ */
+declare function wireWorkbench(root: HTMLElement, { id, panels, deviceClass, storage, step, largeStep, onResize, dismissOverlays, exclusiveOverlays, }: WireWorkbenchOptions): () => void;
+
+export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanelKey, type WorkbenchResize, type WorkbenchStorage, wireWorkbench };
 ```
 
 ## `@kerfjs/ui/collapsible-panel`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { LucideIcon } from './lucide-icon.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelToggle } from './panel-toolbar-BFQxFITu.js';
+export { c as collapsiblePanelToggleIcon } from './panel-toolbar-BFQxFITu.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import './lucide-icon.js';
 import 'lucide';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
-type CollapsiblePanelSide = 'left' | 'right' | 'bottom';
+type CollapsiblePanelSide = PanelSide;
+/** The standard toggle a panel toolbar renders (see {@link CollapsiblePanelToolbar}). */
+type CollapsiblePanelToolbarToggle = PanelToggle;
 /**
- * The standard collapse/expand icon for a panel `side` and `collapsed` state,
- * so every app's sidebars and drawers use one recognizable convention:
- * `PanelLeft*` for a left rail, `PanelRight*` for a right rail, `PanelBottom*`
- * for a bottom drawer — the `Close` glyph while open, the `Open` glyph while
- * collapsed. Exposed so an app can render its own toggle affordance.
+ * A panel's composed top toolbar. `title` and `panelOnly` groups lead it and
+ * are available only while the panel is open; `constant` groups and the
+ * standard `toggle` trail it while open and move to the app's work-area
+ * toolbar — through {@link CollapsiblePanelRelocated} — while it is collapsed.
  */
-declare function collapsiblePanelToggleIcon(side: CollapsiblePanelSide, collapsed: boolean): {
-    icon: Parameters<typeof LucideIcon>[0]['icon'];
-    name: string;
-};
+type CollapsiblePanelToolbar = PanelToolbar;
 interface CollapsiblePanelToggleProps {
     /** The panel this toggle controls. */
     side: CollapsiblePanelSide;
@@ -1153,11 +1514,20 @@ interface CollapsiblePanelProps {
     label?: string;
     /** Panel content. */
     children?: KerfUiContent;
+    /**
+     * The panel's top toolbar, composed so its groups follow the panel's open
+     * state. With it, `children` renders in a `Pane` below the toolbar; render
+     * {@link CollapsiblePanelRelocated} in the app's work-area toolbar so the
+     * `constant` groups and toggle stay reachable while the panel is collapsed.
+     */
+    toolbar?: CollapsiblePanelToolbar;
+    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    footer?: KerfUiContent;
     separator?: ResizableRegionSeparator;
     collapseMotion?: ResizableRegionCollapseMotion;
     contentOverflow?: ResizableRegionContentOverflow;
     presentation?: ResizableRegionPresentation;
-    /** Control shown in a safe-area-aware viewport corner while collapsed. */
+    /** Control shown while collapsed, in a safe-area-aware corner of the panel's container (not the viewport). */
     restoreControl?: SafeHtml;
     restorePosition?: ResizableRegionRestorePosition;
     className?: string;
@@ -1169,14 +1539,36 @@ interface CollapsiblePanelProps {
  * slides out via `transform` (one reflow, composited — the same technique
  * `Workbench` and the catalog sidebar use). Bottom-drawer content stays anchored
  * to the panel's fixed bottom edge, so the track cannot move its layout origin
- * underneath the transform transition. The app owns the `collapsed` signal;
+ * underneath the transform transition. A collapsed panel renders `inert` (with
+ * `aria-hidden`), so neither Tab, pointer, nor assistive technology reaches
+ * content that has slid out of view; its `restoreControl` renders outside the
+ * panel and stays reachable.
+ * 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 `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;
+declare function CollapsiblePanel({ id, side, collapsed, size, label, children, toolbar, footer, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
+interface CollapsiblePanelRelocatedProps {
+    /** The panel's `id`. */
+    panelId: string;
+    side: CollapsiblePanelSide;
+    /** The panel's current collapsed state. */
+    collapsed: boolean;
+    /** The same `toolbar` the panel receives. */
+    toolbar: CollapsiblePanelToolbar;
+}
+/**
+ * A collapsed {@link CollapsiblePanel}'s `constant` groups and standard
+ * toggle, for the app's work-area toolbar — nothing while the panel is open.
+ * Put it first in the leading zone for a left rail, last in the trailing zone
+ * for a right rail, and last in a bottom toolbar (or a `FloatingToolbar`
+ * `restoreControl`) for a bottom drawer. `wireSidebar` hands focus to it when
+ * the panel closes from its own toggle.
+ */
+declare function CollapsiblePanelRelocated({ panelId, side, collapsed, toolbar, }: CollapsiblePanelRelocatedProps): SafeHtml;
 
-export { CollapsiblePanel, type CollapsiblePanelProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, collapsiblePanelToggleIcon };
+export { CollapsiblePanel, type CollapsiblePanelProps, CollapsiblePanelRelocated, type CollapsiblePanelRelocatedProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, type CollapsiblePanelToolbar, type CollapsiblePanelToolbarToggle };
 ```
 
 ## `@kerfjs/ui/wire-sidebar`
@@ -1323,6 +1715,9 @@ interface ResizableRegionProps {
     max: number;
     axis?: ResizableRegionAxis;
     edge?: ResizableRegionEdge;
+    /** Snap the track to zero. The region renders `inert` and `aria-hidden`
+     * while collapsed, so neither Tab nor assistive technology reaches it or
+     * lands on an empty landmark; `restoreControl` renders outside the region. */
     collapsed?: boolean;
     transitioning?: boolean;
     /** Whether the separator line is painted. The resize hit target remains available. */
@@ -1335,7 +1730,7 @@ interface ResizableRegionProps {
     presentation?: ResizableRegionPresentation;
     /** Always-available control rendered while collapsed, outside the clipped region. */
     restoreControl?: SafeHtml;
-    /** Safe-area-aware viewport corner for `restoreControl`. */
+    /** Safe-area-aware corner of the region's container (not the viewport) for `restoreControl`. */
     restorePosition?: ResizableRegionRestorePosition;
     /** Fill the available inline track and hide the separator below a container breakpoint. */
     responsiveFillAt?: ResizableRegionResponsiveFillAt;
@@ -1364,8 +1759,9 @@ interface WireResizableRegionsOptions {
     onPreview?: (change: ResizeCommit) => void;
     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, options: WireResizableRegionsOptions): () => void;
 
 export { type ResizeCommit, type WireResizableRegionsOptions, wireResizableRegions };
 ```
@@ -1442,12 +1838,18 @@ export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type Dev
 ```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 { a as CatalogProps } from './types-D6vzj-VT.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-D6vzj-VT.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-/** 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;
+/**
+ * Controlled, stateless component-catalog shell: a `Workbench` whose left rail
+ * is the catalog navigation and whose work area is the active entry — its
+ * toolbar, description, preview stage, and resource footer. The sidebar's
+ * standard toggle moves into the entry toolbar while it is collapsed, and on
+ * a small screen the sidebar overlays the stage like any Workbench rail.
+ */
+declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, className, slot, }: CatalogProps): kerfjs.SafeHtml;
 
 /** How a specimen aligns its visible edge with its `ListHeader` label. */
 type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
@@ -1518,7 +1920,7 @@ export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleP
 ## `@kerfjs/ui/catalog-resources`
 
 ```ts
-import { C as CatalogResource } from './types-CEsieBZi.js';
+import { C as CatalogResource } from './types-D6vzj-VT.js';
 import './semantic-content-BbzjvSu9.js';
 import 'kerfjs';
 
@@ -1558,6 +1960,8 @@ export { type CatalogGuidanceKind, type CatalogResourceKind, type CatalogResourc
 ## `@kerfjs/ui/wire-catalog`
 
 ```ts
+import { Signal } from 'kerfjs';
+
 interface WireCatalogOptions {
     /** Invoked with the entry id when a sidebar item or a related-entry option is chosen. */
     onSelect: (id: string) => void;
@@ -1578,6 +1982,16 @@ interface WireCatalogOptions {
     toggleSidebarAction?: string;
     toggleThemeAction?: string;
     toggleSecondaryAction?: string;
+    /**
+     * The sidebar's app-owned collapsed flag. With it, the catalog's Workbench
+     * sidebar is wired like any Workbench rail: it becomes a transient overlay
+     * on a small screen (collapsed as the breakpoint applies, closed on Escape
+     * or a press outside, focus handed back), and choosing an entry from the
+     * open overlay closes it.
+     */
+    collapsed?: Signal<boolean>;
+    /** The Catalog's `id`, when it is not the default `kui-catalog`. */
+    id?: string;
 }
 interface CatalogRevealOptions {
     /** Scroll alignment within the sidebar. Default `'nearest'`. */
@@ -1612,7 +2026,7 @@ declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
  * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.
  * Returns a disposer.
  */
-declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, collapsed, id: catalogId, }: WireCatalogOptions): () => void;
 
 export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
 ```
@@ -1880,6 +2294,15 @@ interface TokenSearchFieldBaseProps {
     label: string;
     query?: string;
     tokens?: readonly TokenSearchToken[];
+    /**
+     * Editor identity for a programmatic text replacement. The editor's text is
+     * DOM-owned between token changes, so a new `query` with the same tokens
+     * does not re-render it (that would reset the caret on every keystroke).
+     * Change `revision` when the app replaces the text itself — reseeding a
+     * persistent dialog's field on reopen, applying a saved search — and the
+     * editor is rebuilt from `query` and `tokens`.
+     */
+    revision?: string | number;
     placeholder?: string;
     tokenPlaceholder?: string;
     disabled?: boolean;
@@ -1915,7 +2338,7 @@ interface TokenSearchFieldValue {
     query: string;
     tokens: TokenSearchToken[];
 }
-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;
+declare function TokenSearchField({ id, label, query, tokens, revision, 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. */