@kerfjs/ui 5.0.0-beta.57 → 5.0.0-beta.59

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.57` and `kerfjs@5.0.0-beta.57`. 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.59` and `kerfjs@5.0.0-beta.59`. 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`
 
@@ -315,6 +315,8 @@ interface ToolbarControlGroupProps {
     overflow?: ToolbarControlGroupOverflow;
     /** Responsive visibility owned by the enclosing Toolbar container. */
     visibility?: ToolbarControlGroupVisibility;
+    /** Move this group into the work-area toolbar when its panel collapses. */
+    relocateOnCollapse?: boolean;
     /** Add contrast behind photo-backed avatar content. */
     scrim?: boolean;
     /**
@@ -325,7 +327,7 @@ interface ToolbarControlGroupProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, scrim, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
 
 export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };
 ```
@@ -403,9 +405,19 @@ interface PopupMenuItem {
     value?: string;
     /** Leading icon, typically a `LucideIcon`; it is placed in the item's icon slot. */
     icon?: SafeHtml;
+    /** A checked menu choice, including nested choices. */
+    checked?: boolean;
+    /** Trailing safe content, such as a selected-choice tick. */
+    details?: SafeHtml;
+    /** Destructive command styling. */
+    tone?: 'default' | 'danger';
     disabled?: boolean;
+    /** Native tooltip text for a disabled command. */
+    disabledReason?: string;
     /** Application `data-*` metadata such as a record id. */
     attributes?: PopupMenuDataAttributes;
+    /** Child commands opened by hover or keyboard navigation. */
+    submenu?: readonly PopupMenuItem[];
 }
 /** A labeled group heading; items that follow it belong to the group. */
 interface PopupMenuHeading {
@@ -429,7 +441,17 @@ type PopupMenuTriggerName = {
      */
     label: string;
 };
-type PopupMenuProps = PopupMenuTriggerName & {
+type PopupMenuTrigger = (PopupMenuTriggerName & {
+    context?: false;
+}) | {
+    context: true;
+    label: string;
+    text?: never;
+    icon?: never;
+    caret?: never;
+    disabled?: never;
+};
+type PopupMenuProps = PopupMenuTrigger & {
     /** Trigger icon, typically a `LucideIcon`, before any visible text. */
     icon?: KerfUiContent;
     items: readonly PopupMenuEntry[];
@@ -443,6 +465,14 @@ type PopupMenuProps = PopupMenuTriggerName & {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 };
+/** A rendered context PopupMenu with Web Awesome's controlled open state. */
+type PopupMenuElement = HTMLElement & {
+    open: boolean;
+};
+/** Open a context PopupMenu at viewport pointer coordinates. */
+declare function openPopupMenuAt(menu: PopupMenuElement, x: number, y: number): void;
+/** Close a programmatically opened PopupMenu. */
+declare function closePopupMenu(menu: PopupMenuElement): void;
 /**
  * An action menu: a trigger button that opens a list of commands. Renders the
  * `wa-dropdown` root directly, so a `single` `ToolbarControlGroup` (with
@@ -451,9 +481,9 @@ type PopupMenuProps = PopupMenuTriggerName & {
  * 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;
+declare function PopupMenu({ text, label, icon, items, placement, caret, disabled, rootAttributes, slot, context, }: PopupMenuProps): SafeHtml;
 
-export { PopupMenu, type PopupMenuDivider, type PopupMenuEntry, type PopupMenuHeading, type PopupMenuItem, type PopupMenuPlacement, type PopupMenuProps };
+export { PopupMenu, type PopupMenuDivider, type PopupMenuElement, type PopupMenuEntry, type PopupMenuHeading, type PopupMenuItem, type PopupMenuPlacement, type PopupMenuProps, closePopupMenu, openPopupMenuAt };
 ```
 
 ## `@kerfjs/ui/list-header`
@@ -1414,7 +1444,7 @@ import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
 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-BN4x0rth.js';
+import { a as PanelToolbar, b as PanelToggle } from './panel-toolbar-DqwtBxQL.js';
 import { ToolbarConfig } from './toolbar.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -1427,7 +1457,7 @@ 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
+ * A collapsed rail's marked 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.
@@ -1494,7 +1524,7 @@ interface WorkbenchPanelResizable {
 interface WorkbenchPanel {
     content: KerfUiContent;
     /**
-     * The panel's top toolbar, composed by the Workbench: its `constant` groups
+     * The panel's top toolbar, composed by the Workbench: its marked 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.
      */
@@ -1565,7 +1595,7 @@ interface WorkbenchProps {
     /** The central work area. */
     main: KerfUiContent;
     /**
-     * The work area's top toolbar. A collapsed left rail's `constant` groups
+     * The work area's top toolbar. A collapsed left rail's marked groups
      * and toggle lead it; a collapsed right rail's trail it. With it, `main`
      * renders in a `Pane` below the toolbar.
      */
@@ -1581,7 +1611,7 @@ interface WorkbenchProps {
      */
     mainFooter?: KerfUiContent;
     /**
-     * The work area's bottom toolbar. A collapsed drawer's `constant` groups and
+     * The work area's bottom toolbar. A collapsed drawer's marked groups and
      * toggle trail it; without it they float in the work area's corner.
      */
     mainBottomToolbar?: WorkbenchMainBottomToolbar;
@@ -1774,8 +1804,8 @@ export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanel
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { PaneConfig } from './pane.js';
-import { P as PanelSide, a as PanelToolbar, b as PanelToggle } from './panel-toolbar-BN4x0rth.js';
-export { c as collapsiblePanelToggleIcon } from './panel-toolbar-BN4x0rth.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelToggle } from './panel-toolbar-DqwtBxQL.js';
+export { c as collapsiblePanelToggleIcon } from './panel-toolbar-DqwtBxQL.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import './lucide-icon.js';
@@ -1788,10 +1818,10 @@ type CollapsiblePanelSide = PanelSide;
 /** The standard toggle a panel toolbar renders (see {@link CollapsiblePanelToolbar}). */
 type CollapsiblePanelToolbarToggle = PanelToggle;
 /**
- * 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.
+ * A panel's composed top toolbar. Its groups occupy `leading`, `center`, and
+ * `trailing` while open; groups marked `relocateOnCollapse` and the standard
+ * toggle move to the work-area toolbar through
+ * {@link CollapsiblePanelRelocated} while it is collapsed.
  */
 type CollapsiblePanelToolbar = PanelToolbar;
 interface CollapsiblePanelToggleProps {
@@ -1834,7 +1864,7 @@ interface CollapsiblePanelProps {
      * 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.
+     * marked groups and toggle stay reachable while the panel is collapsed.
      */
     toolbar?: CollapsiblePanelToolbar;
     /** Optional bottom toolbar under a `toolbar` panel's content. */
@@ -1883,7 +1913,7 @@ interface CollapsiblePanelRelocatedProps {
     toolbar: CollapsiblePanelToolbar;
 }
 /**
- * A collapsed {@link CollapsiblePanel}'s `constant` groups and standard
+ * A collapsed {@link CollapsiblePanel}'s marked 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`
@@ -2217,7 +2247,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-BN4x0rth.js';
+import './panel-toolbar-DqwtBxQL.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2310,7 +2340,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-BN4x0rth.js';
+import './panel-toolbar-DqwtBxQL.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2713,87 +2743,17 @@ export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
-import { SafeHtml } from 'kerfjs';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-
-interface TokenSearchToken {
-    value: string;
-    label: string;
-    offset?: number;
-    accessibleLabel?: string;
-}
-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;
-    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;
-    autofocus?: boolean;
-    leading?: KerfUiContent;
-    trailing?: KerfUiContent;
-    /** Standalone field chrome or the inset visual layer of a configured toolbar group. */
-    presentation?: 'standalone' | 'toolbar-group';
-    editAction?: string;
-    removeAction?: string;
-    clearAction?: string;
-    clearLabel?: string;
-    /** Icon for the clear button. Default: the Lucide `x` glyph token chips also use. */
-    clearIcon?: SafeHtml;
-    className?: string;
-    editorAttributes?: TokenSearchEditorAttributes;
-    /** Native named-slot assignment when composed inside a web component. */
-    slot?: string;
-}
-type TokenSearchCollapsibleProps = {
-    /** Allow an empty field to render as one iconic action. */
-    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[];
-}
-declare function TokenSearchField({ id, label, query, tokens, revision, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, presentation, editAction, removeAction, clearAction, clearLabel, clearIcon, className, editorAttributes, slot, }: TokenSearchFieldProps): 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. */
-declare function placeTokenSearchCaret(editor: HTMLElement, offset?: number): void;
-
-export { type TokenSearchEditorAttributes, TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValue, type TokenSearchToken, placeTokenSearchCaret, readTokenSearchField };
+import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-CCke1yvQ.js';
 ```
 
 ## `@kerfjs/ui/wire-token-search-fields`
 
 ```ts
 import { Signal } from 'kerfjs';
+import { d as TokenSearchModel } from './token-search-field-CCke1yvQ.js';
+import './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchSubmit {
     id: string;
@@ -2871,6 +2831,8 @@ interface TokenSearchCollapsibleOptions {
     signals?: Readonly<Record<string, Signal<boolean>>>;
 }
 interface WireTokenSearchFieldsOptions {
+    /** Optional automatic grammar/suggestion models, keyed by TokenSearchField id. */
+    models?: Readonly<Record<string, TokenSearchModel>>;
     onSubmit?: (submission: TokenSearchSubmit) => void;
     /** Fired on every editor `input`, after the browser mutates it, so a caller can drop its own `input` listener. */
     onEdit?: (edit: TokenSearchEdit) => void;
@@ -2901,7 +2863,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, { models, onSubmit, onEdit, collapsible, keyboard, }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
 
 export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
 ```
@@ -3105,7 +3067,7 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';
 type TextTone = 'default' | 'quiet' | 'danger';
-type TextSize = 'default' | 'compact';
+type TextSize = 'compact' | 'default' | 'large' | 'xlarge';
 type TextFont = 'default' | 'monospace';
 type TextBorder = 'transparent' | 'none';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
@@ -3248,3 +3210,11 @@ declare function Spacer({ flex, width, height, className, slot, }: SpacerProps):
 
 export { CssLength, Spacer, type SpacerProps, UiSpaceName };
 ```
+
+## `@kerfjs/ui/token-search-model`
+
+```ts
+import 'kerfjs';
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, k as createTokenSearchModel } from './token-search-field-CCke1yvQ.js';
+import './semantic-content-BbzjvSu9.js';
+```

package/ai/skill.md

@@ -194,7 +194,7 @@ Hard rules:
 8. `ResizableRegion` uses `wireResizableRegions()` for Arrow, Shift+Arrow, Home/End, and pointer behavior. The app owns size persistence. `handleIcon` replaces decorative dormant glyph content only. Set `responsiveFillAt="narrow"` or `"compact"` when a responsive composition exposes the pane as its only inline track; the component fills that track and hides its dormant separator. For compact overlays, set `presentation="overlay"` and the overlay maximum variables. A lone child (normally a `Pane`) fills the region and owns scrolling; several children stack at natural height. Do not add descendant width/height overrides.
 9. Use controlled `SegmentedControl` for a small exclusive choice set. Select `appearance="toolbar"` when nesting it inside `ToolbarControlGroup`; use rounded or pill shapes for standalone contexts. The package derives inset hover/selection radii from the owning outer shape through `--kui-layout-highlight-inset`; do not restyle an inner highlight to an independent radius. Handle its action, update `value`, keep meaningful choice labels, and preserve every enabled native button in sequential Tab order.
 10. Compose `AppTab` inside controlled `TabBar`; call `wireTabBars()` once and retain its disposer. It owns same-bar drag mechanics, including proximity-based horizontal edge autoscroll, while the app applies `onReorder` and owns order, selection, panels, close policy, routing, and persistence. For a tab-local action followed by a separately pinned workspace action, set `trailingPlacement="adjacent"`, put the local action in `trailing`, and the workspace action in `end`; TabBar owns the shrinking/scrolling tabs and fixed action geometry, so do not add descendant flex overrides. Arrow/Home/End select on move by default and restore focus by bar/tab identity when controlled activation replaces the strip; pass `activation: 'manual'` (or `TabBar activation="manual"` per strip) so arrow keys move focus only and the user selects with Enter/Space/click — use it when selecting a tab is a heavy action. Use runtime-filtered `rootAttributes` for domain metadata and keep an optional `closeIcon` decorative and noninteractive.
-11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes; to replace the text programmatically (reseeding a persistent dialog's field on reopen, applying a saved search) change the field's `revision` along with `query`, never re-key a wrapper. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. The app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. `clearIcon` replaces the clear action's glyph (its `clearLabel` still names it). Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded, and `wireTokenSearchFields()` manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse). Bind the field's `expanded` to the returned handle's `expanded(id)` signal or adopt your own via `collapsible.signals`; opt a behavior out only when the app must own it. Do not hand-roll the open handler, the focusout collapse, a clear-button mousedown guard, or reopening after controlled clear or Select All deletion — the helper keeps the replacement editor open and focused. Clear and deletion restoration finish at the replacement mutation checkpoint before the next input task, so shortcut-letter typing cannot escape to the page and delayed animation frames cannot overwrite a later selection. Persist both query and tokens returned by the DOM read. For real-app adoption it also provides a focusout keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn(target)`, so a sibling suggestions/date/help surface does not collapse an empty field), opt-in atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — reach for these instead of re-adding hand-rolled keydown/input handlers around the field.
+11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes; to replace the text programmatically (reseeding a persistent dialog's field on reopen, applying a saved search) change the field's `revision` along with `query`, never re-key a wrapper. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. For automatic parsing, chips, suggestions, and evaluation, use createTokenSearchModel with grammar rules, pass it as TokenSearchField.model, and register it in wireTokenSearchFields models; otherwise the app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. `clearIcon` replaces the clear action's glyph (its `clearLabel` still names it). Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded, and `wireTokenSearchFields()` manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse). Bind the field's `expanded` to the returned handle's `expanded(id)` signal or adopt your own via `collapsible.signals`; opt a behavior out only when the app must own it. Do not hand-roll the open handler, the focusout collapse, a clear-button mousedown guard, or reopening after controlled clear or Select All deletion — the helper keeps the replacement editor open and focused. Clear and deletion restoration finish at the replacement mutation checkpoint before the next input task, so shortcut-letter typing cannot escape to the page and delayed animation frames cannot overwrite a later selection. Persist both query and tokens returned by the DOM read. For real-app adoption it also provides a focusout keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn(target)`, so a sibling suggestions/date/help surface does not collapse an empty field), opt-in atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — reach for these instead of re-adding hand-rolled keydown/input handlers around the field.
 12. Demo work uses public production component subpaths and their browser-selected CSS. Focused demos and recipes have no local stylesheet, inline style, or styling-only class; use public components and `CatalogExample.viewport` for unavoidable specimen constraints (a recipe declares its frame through its exported `presentation`). When a recipe needs a capability no component offers, report the component gap instead of adding CSS. Use exactly three demo kinds: a `component` is one component with variants/states, a `composition` is a focused container of components commonly used together, and a `recipe` is the recommended production approach to a task. Organize catalog routes into product-important functional groups; within each group put all components before compositions, order each kind by importance with display-name alphabetical tie-breaking, and put recipes after every component/composition group. Show `Composition` as an entry tag instead of repeating the word in its name. Give every public visual component its own category-grouped catalog route; list themed third-party components under a clearly labeled collapsible ecosystem section, with a focused route for each. For the complete taxonomy, focused/composition decision, `CatalogExample` / `CatalogExampleStack` row/group nesting, exact specimen selection, geometry-overlay legend and exclusions, skip-marker behavior, and metadata ownership, follow the single [Catalog demo authoring contract](../docs/catalog.md#catalog-demo-authoring-contract), discovered machine-readably through [`catalog-authoring.json`](./catalog-authoring.json). Never infer structure from private `kui-catalog-*` classes. Project each component's deterministic repository-relative demo source and existing documentation path so the detail can expose `View demo source` and `Read guidance` links without a runtime export; also derive first-party component implementation paths from their canonical browser imports, and label Web Awesome documentation as Kerf integration guidance. Declare direct `uses` relationships so `Used by` stays derivable, and theme shell chrome through the same semantic tokens as the stage instead of drawing a substitute. Enable `wireCatalog({ revealSelection: true })` for long desktop sidebars so controlled selections remain visible without moving focus; keep its default compact media guard unless compact scrolling is an explicit product behavior, and use `revealCatalogEntry` for an initial deep link.
 13. The Web Awesome theme makes Tooltip and Popover arrowless by default. Keep that default unless a pointer materially clarifies the anchor; opt back in with `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or a popover's public `--arrow-size`, and use `without-arrow` when local no-arrow intent should survive theme changes. Its non-field chrome uses `--kui-wa-control-inset` (8px controls/items), `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside Accordion, Card, Details, Callout, and Include), and `--kui-wa-container-inset` (16px Tab Panel content and framed disclosure regions). Plain Details use the 8px surface inset on the trigger and keep the body flush; plain Accordion items use it on both trigger and body. Outlined and sunken Details use the 16px container inset on the trigger and 8px on the body; framed Accordion items use 16px on both. Dialog maps its body to the 8px surface tier and its footer to the 16px container tier independently of `--spacing`. Override those tiers instead of restyling individual parts. Filled badges use each variant's quiet fill with normal text so their compact copy stays WCAG-AA readable; override the pair with `--kui-wa-badge-filled-background` / `--kui-wa-badge-filled-foreground`, not host selectors. When a dialog provides another dismissal affordance, put `hide-actions` on the `wa-dialog` host to hide its directly exported `header-actions` part; never chain `::part()` selectors through internal parts. Checkbox and Radio Group option regions, the Color Picker trigger, and Slider's complete interactive region receive the shared 8px logical inline outer inset because those controls have no bordered field shell. Known Date field captions and bordered text-like field hints align with values at the 9px border-plus-padding inset. OTP Input's label uses the same uppercase xs/650 treatment as other field labels, and both its label and hint use that 9px inset.
 14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Its UX sidebar marks superseded and exceptional entries `Discouraged`. Consider Popup when it replaces custom anchored positioning. Prefer Kerf `Select` over direct Dropdown/Dropdown Item/Select/Option composition, `SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over Split Panel. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame. Never render a `Discouraged` element directly in application, demo, or recipe markup; reach it only through the Kerf component that wraps it (`PopupMenu` renders `wa-dropdown`, `Select` renders `wa-select` / `wa-option`), and treat a Kerf component gap as a request to file, not a reason to drop to the raw element.
@@ -207,7 +207,7 @@ Hard rules:
 19. Compose `ValueTable` from typed `ValueTableRow` entries instead of handwritten `dt`/`dd` wrappers. Pass `icon` for the optional 24px leading visual; the row owns 8px of root-scaled top and bottom padding, the 8px iconless or 40px icon-bearing separator start, and the common 8px right inset.
 20. Use the standard direct `Toolbar` composition for a panel, dialog, or page heading, not a private wrapper or custom heading row. Put an optional icon in a `ToolbarControlGroup`, the title directly in the leading zone as extra-large `ToolbarText`, and actions in a trailing group. Set `headingLevel` for page/section landmarks. Supporting copy stays below the toolbar as app-owned content. The app owns modal behavior, focus, dismissal, command policy, ids, and action handling.
 21. Space with the official five-step scale, picked by how connected two elements are — not by eye. `0` `--kui-space-none` = no separation (one unit); `4px` `--kui-space-2xs` = very minor air on a connected cluster; `8px` `--kui-space-xs` = standard, between elements within a group; `16px` `--kui-space-m` = minor, between homogeneous groups; `24px` `--kui-space-l` = major, between heterogeneous groups (the `.kui-content` rhythm). The 8px-vs-24px distinction is inside-a-group vs between-major-differing-regions. `--kui-space-s` (12px) and `--kui-space-xl` (32px) are off-scale exceptions. For `Row.gap`, `Grid.gap`, or `List.gap`, pass a finite shorthand such as `gap="xs"` or `gap="m"`; use `Spacer` for one intentional typed empty width/height or a flexible main-axis gap. When one token is insufficient, import typed builders from the CSS-free `@kerfjs/ui/css-values` subpath. Preserve property grammar: lengths for gap/Spacer/Skeleton geometry, `flex()` for Row/Grid/List flex, and a foreground color for choice icons: `uiColor()` with a `*-on-*` or text token (`success-on-quiet`, `text-quiet`) or `foregroundColorVar()`. Fill tokens (`*-fill-*`) are backgrounds, not foregrounds, and `SelectChoice.color` rejects them. Never cast between brands or emit raw row `style` declarations. `plus` is not standalone and must be wrapped in `calc`; `remify()` remains source-CSS syntax and is never a runtime prop value. See `docs/layout.md` "Spacing scale".
-22. Pick a whole-screen layout from the opt-in, tree-shakeable subpaths by data + interaction + device, and derive responsiveness from `@kerfjs/ui/device-class`'s `deviceClass()` (`compact` = handset or portrait tablet = one pane at a time). Simple/flat → `NavStack` with one entry (single pane), plus `TabScaffold` (`@kerfjs/ui/tab-scaffold`, iOS bottom tabs, each tab its own `NavStack`) for 2–5 co-equal sections on `compact`; show an unread count on a tab with its `badge` (a number or short string, rendered as the top-trailing danger `Badge` on the icon) plus a localized `badgeLabel` ("3 unread", folded into the tab's name as "Inbox, 3 unread"), never by concatenating the count into `label` or restyling the badge; for new content without a count pass `badge: true` (the text-free dot) with its required `badgeLabel` ("New activity"). Drill-down → `NavStack` (`@kerfjs/ui/nav-stack`), upgrading to `SplitView` (`@kerfjs/ui/split-view`, list-detail) once both panes fit (`atLeast('tablet')` landscape); `SplitView` collapses to a `NavStack` on `compact`. Keep each stack's ordered views controlled; put view-specific bottom chrome on `NavStackView.bottomToolbar` (or use the component-level persistent fallback), then call `wireNavStack` so content slides while the active view's top and bottom chrome cross-fade and focus moves into the new top view/restores on pop. Mark a preferred initial heading or control with `data-nav-focus` when DOM order is not sufficient. The stack's top chrome is a real `Toolbar`: put a view's groups on `NavStackView.leading` / `center` / `toolbar` (trailing), and configure the bar through `toolbarConfig` (`ToolbarConfig` plus `label`, `titleSize`, `headingLevel`) and `backIcon` / `backText`, never with CSS. `SplitView` forwards both of its inner components: `resizable` takes the list `ResizableRegion`'s `separator`, `handleIcon`, `contentOverflow`, and collapse props (`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`, `restorePosition`), and `compactStack` takes the compact stack's `toolbarConfig`, `backIcon`, `backText`, `hideToolbar`, `bottomToolbar`, plus `list` / `detail` view toolbars (`leading`, `center`, `toolbar`, `bottomToolbar`). Complex tool with peripheral panels → `Workbench` (`@kerfjs/ui/workbench`, collapsible rails + drawer) `atLeast('desktop')`, degrading to `NavStack`/overlays below. Workbench panels are fixed-size unless a panel opts in with `resizable` (`true` or `{ min, max }`); then render `size={sizeSignal.value}` and call `wireWorkbench(root, { id, panels: { leftRail: { size: sizeSignal, storageKey? } }, deviceClass })` from `@kerfjs/ui/wire-workbench` for pointer drags, arrow/Shift+arrow/Home/End on the separator, persistence, and no resizing on `compact` classes. Inline rails, fixed or resizable, leave the work area `mainMinSize` px of width (a `Workbench` prop, default 320, `0` off), and an inline bottom drawer leaves it `mainMinHeight` px of height (default 120, `0` off): resizable panels stop growing there, rails shrink in proportion when the Workbench narrows and the drawer when it gets shorter, so do not add your own main-area `min-width` / `min-height`. Rails present as overlays below the `narrow` Workbench container breakpoint (704px) by default — `responsiveOverlayAt: "compact"` moves that to 448px and `"never"` keeps a rail inline — and a bottom drawer opts in the same way; do not derive `presentation` from `deviceClass`, and overlays never resize. At compact widths an overlay rail fills the Workbench less a 44px dismiss strip (`--kui-workbench-overlay-dismiss-margin`) on the side away from its edge; `compactOverlay: "full"` makes one rail fill it. Pass each such panel's `collapsed` signal to `wireWorkbench` too (`panels: { leftRail: { collapsed: navCollapsed } }`, `size` optional) so the overlay is transient like `wireSidebar`'s compact overlay: it collapses when the breakpoint begins to apply (the inline state returns when it ends), takes focus on its first control and keeps Tab inside it while open, and closes on Escape or an outside press with focus returned to its toggle (give each toggle `aria-controls` naming its panel's derived id, `<workbench id>-left-rail` / `-right-rail` / `-bottom-drawer`, so a panel open at wire-up has a focus target too); opening one overlay closes the other open overlays, so they never cover each other's controls; do not hand-roll those listeners (`dismissOverlays: false` opts out of all of it, `exclusiveOverlays: false` of exclusivity only). Collapse stays the app's `collapsed` flag and keeps the size, so an expanded panel returns at its last size. Let the Workbench compose panel toolbars: give each panel `toolbar: { label, title?, panelOnly?, center?, constant?, toggle: { action, name, showLabel?, hideLabel? } }` and the work area `mainToolbar` (and `mainBottomToolbar` for a drawer). Each of these toolbars takes the `Toolbar`'s configuration (`ToolbarConfig`: `dividerSides`, `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`); configure a composed toolbar through those props (for example `dividerSides: ""` to drop its divider), never with CSS. Configure the composed panes and chrome lists the same way: a panel's `pane` (and `CollapsiblePanel`'s `pane`) and the Workbench's `mainPane` take `PaneConfig` (`contentElement`, `contentLabel`, `separators`, `safeAreaEdges` — for example `{ contentElement: "nav", contentLabel: "Files" }` for a navigator rail), and `mainHeaderList` / `mainFooterList` take `ListConfig` (`gap`, `hAlign`, `vAlign`, `dividerSides`, `textInsets`, `controlInsets`). Open, a panel's toolbar holds its title and panel-only groups, then its constant groups and its toggle last (the toggle is always the last control of the last group); closed, its constant groups and toggle move to the work area — a left rail's lead `mainToolbar`, a right rail's end it, a drawer's trail `mainBottomToolbar` or float in a corner `FloatingToolbar` — and panel-only groups stay behind. A control sits near where its effect appears: a collapsed drawer's restore belongs in the bottom toolbar or a `FloatingToolbar` beside the drawer, not in a distant top toolbar. Do not hand-place panel toggles in the work-area toolbar or render a second copy, and handle only the toggle's `data-action`. A collapsed panel renders `inert` and `aria-hidden` by itself, on the rail/drawer and its content (its `restoreControl` stays outside and reachable), so do not add your own `tabindex`, `aria-hidden`, or `inert` to hide it. These are declarative (the app owns the stack/selection/collapsed/active state as signals) with disposer-returning `wire…` helpers; each stays out of the barrel, and its CSS-aware browser import loads the layout's CSS plus that of every component it renders (`Pane`, `Toolbar`, `List`, …), so do not hand-import `pane.css` or the other internal stylesheets; the companion `.css` subpath is only for pipelines without the `browser` condition. For a standalone collapsible rail or bottom drawer outside a full shell, use `CollapsiblePanel` + `CollapsiblePanelToggle` (`@kerfjs/ui/collapsible-panel`) with `wireSidebar` (`@kerfjs/ui/wire-sidebar`): the standard collapse animation and per-side icon convention (`PanelLeft*`/`PanelRight*`/`PanelBottom*`) plus toggle, focus, compact overlay, and persistence semantics. Give a standalone panel the same `toolbar` roles and render `CollapsiblePanelRelocated` in your work-area toolbar (first in leading for a left rail, last in trailing for a right rail, a bottom toolbar or a `FloatingToolbar` restoreControl for a drawer) instead of hand-placing a second toggle. A collapsed `CollapsiblePanel`, `ResizableRegion`, or Workbench panel renders `inert` and `aria-hidden` by itself, so do not hide collapsed content yourself either. Likewise an open side overlay (a Workbench rail overlay, a `wireSidebar` compact overlay, an overlay `CollapsiblePanel` or horizontal `ResizableRegion`) hides the covered work area's `FloatingToolbar`s and restore corners by itself until it closes, so do not hide them from overlay state. A compact overlay opens only on a user action: wire-up on a compact device and a wide-to-compact crossing collapse every panel, and a wide crossing restores the inline state. Seed the signal with `signal(device.value.compact)` and pass the panel's `inlineCollapsed` default so the first compact render has no overlay. Dialogs pick the same inner layout, then present per device class (full-screen modal on `compact`, inline on desktop). A list-detail dialog is a Workbench-shaped layout on roomy devices: a full-height list sidebar and a full-height main column, each a `Pane` with its own top `Toolbar`; the main column holds the primary xl title, the close control (`data-dialog="close"` in a `without-header` Web Awesome dialog), and the record actions, never a header spanning both columns. A top-level percentage-height shell needs a definite containing height: opt into `@kerfjs/ui/document.css` and put `.kui-app-root` on the one direct mount container, or provide equivalent application-owned geometry. The global baseline is deliberately absent from `styles.css` and component imports. See `docs/app-layouts.md`, `docs/document-baseline.md`, and `docs/collapsible-panel.md`.
+22. Pick a whole-screen layout from the opt-in, tree-shakeable subpaths by data + interaction + device, and derive responsiveness from `@kerfjs/ui/device-class`'s `deviceClass()` (`compact` = handset or portrait tablet = one pane at a time). Simple/flat → `NavStack` with one entry (single pane), plus `TabScaffold` (`@kerfjs/ui/tab-scaffold`, iOS bottom tabs, each tab its own `NavStack`) for 2–5 co-equal sections on `compact`; show an unread count on a tab with its `badge` (a number or short string, rendered as the top-trailing danger `Badge` on the icon) plus a localized `badgeLabel` ("3 unread", folded into the tab's name as "Inbox, 3 unread"), never by concatenating the count into `label` or restyling the badge; for new content without a count pass `badge: true` (the text-free dot) with its required `badgeLabel` ("New activity"). Drill-down → `NavStack` (`@kerfjs/ui/nav-stack`), upgrading to `SplitView` (`@kerfjs/ui/split-view`, list-detail) once both panes fit (`atLeast('tablet')` landscape); `SplitView` collapses to a `NavStack` on `compact`. Keep each stack's ordered views controlled; put view-specific bottom chrome on `NavStackView.bottomToolbar` (or use the component-level persistent fallback), then call `wireNavStack` so content slides while the active view's top and bottom chrome cross-fade and focus moves into the new top view/restores on pop. Mark a preferred initial heading or control with `data-nav-focus` when DOM order is not sufficient. The stack's top chrome is a real `Toolbar`: put a view's groups on `NavStackView.leading` / `center` / `toolbar` (trailing), and configure the bar through `toolbarConfig` (`ToolbarConfig` plus `label`, `titleSize`, `headingLevel`) and `backIcon` / `backText`, never with CSS. `SplitView` forwards both of its inner components: `resizable` takes the list `ResizableRegion`'s `separator`, `handleIcon`, `contentOverflow`, and collapse props (`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`, `restorePosition`), and `compactStack` takes the compact stack's `toolbarConfig`, `backIcon`, `backText`, `hideToolbar`, `bottomToolbar`, plus `list` / `detail` view toolbars (`leading`, `center`, `toolbar`, `bottomToolbar`). Complex tool with peripheral panels → `Workbench` (`@kerfjs/ui/workbench`, collapsible rails + drawer) `atLeast('desktop')`, degrading to `NavStack`/overlays below. Workbench panels are fixed-size unless a panel opts in with `resizable` (`true` or `{ min, max }`); then render `size={sizeSignal.value}` and call `wireWorkbench(root, { id, panels: { leftRail: { size: sizeSignal, storageKey? } }, deviceClass })` from `@kerfjs/ui/wire-workbench` for pointer drags, arrow/Shift+arrow/Home/End on the separator, persistence, and no resizing on `compact` classes. Inline rails, fixed or resizable, leave the work area `mainMinSize` px of width (a `Workbench` prop, default 320, `0` off), and an inline bottom drawer leaves it `mainMinHeight` px of height (default 120, `0` off): resizable panels stop growing there, rails shrink in proportion when the Workbench narrows and the drawer when it gets shorter, so do not add your own main-area `min-width` / `min-height`. Rails present as overlays below the `narrow` Workbench container breakpoint (704px) by default — `responsiveOverlayAt: "compact"` moves that to 448px and `"never"` keeps a rail inline — and a bottom drawer opts in the same way; do not derive `presentation` from `deviceClass`, and overlays never resize. At compact widths an overlay rail fills the Workbench less a 44px dismiss strip (`--kui-workbench-overlay-dismiss-margin`) on the side away from its edge; `compactOverlay: "full"` makes one rail fill it. Pass each such panel's `collapsed` signal to `wireWorkbench` too (`panels: { leftRail: { collapsed: navCollapsed } }`, `size` optional) so the overlay is transient like `wireSidebar`'s compact overlay: it collapses when the breakpoint begins to apply (the inline state returns when it ends), takes focus on its first control and keeps Tab inside it while open, and closes on Escape or an outside press with focus returned to its toggle (give each toggle `aria-controls` naming its panel's derived id, `<workbench id>-left-rail` / `-right-rail` / `-bottom-drawer`, so a panel open at wire-up has a focus target too); opening one overlay closes the other open overlays, so they never cover each other's controls; do not hand-roll those listeners (`dismissOverlays: false` opts out of all of it, `exclusiveOverlays: false` of exclusivity only). Collapse stays the app's `collapsed` flag and keeps the size, so an expanded panel returns at its last size. Let the Workbench compose panel toolbars: give each panel `toolbar: { label, title?, leading?, center?, trailing?, toggle: { action, name, showLabel?, hideLabel? } }` and the work area `mainToolbar` (and `mainBottomToolbar` for a drawer). Each of these toolbars takes the `Toolbar`'s configuration (`ToolbarConfig`: `dividerSides`, `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`); configure a composed toolbar through those props (for example `dividerSides: ""` to drop its divider), never with CSS. Configure the composed panes and chrome lists the same way: a panel's `pane` (and `CollapsiblePanel`'s `pane`) and the Workbench's `mainPane` take `PaneConfig` (`contentElement`, `contentLabel`, `separators`, `safeAreaEdges` — for example `{ contentElement: "nav", contentLabel: "Files" }` for a navigator rail), and `mainHeaderList` / `mainFooterList` take `ListConfig` (`gap`, `hAlign`, `vAlign`, `dividerSides`, `textInsets`, `controlInsets`). Open, a panel's toolbar places groups in its leading, center, and trailing zones, with the toggle last; mark a ToolbarControlGroup relocateOnCollapse to keep it available when closed (pass marked groups directly or in arrays rather than JSX fragments); closed, marked groups follow zone order into the work area before the toggle — a left rail's lead `mainToolbar`, a right rail's end it, a drawer's trail `mainBottomToolbar` or float in a corner `FloatingToolbar` — and panel-only groups stay behind. A control sits near where its effect appears: a collapsed drawer's restore belongs in the bottom toolbar or a `FloatingToolbar` beside the drawer, not in a distant top toolbar. Do not hand-place panel toggles in the work-area toolbar or render a second copy, and handle only the toggle's `data-action`. A collapsed panel renders `inert` and `aria-hidden` by itself, on the rail/drawer and its content (its `restoreControl` stays outside and reachable), so do not add your own `tabindex`, `aria-hidden`, or `inert` to hide it. These are declarative (the app owns the stack/selection/collapsed/active state as signals) with disposer-returning `wire…` helpers; each stays out of the barrel, and its CSS-aware browser import loads the layout's CSS plus that of every component it renders (`Pane`, `Toolbar`, `List`, …), so do not hand-import `pane.css` or the other internal stylesheets; the companion `.css` subpath is only for pipelines without the `browser` condition. For a standalone collapsible rail or bottom drawer outside a full shell, use `CollapsiblePanel` + `CollapsiblePanelToggle` (`@kerfjs/ui/collapsible-panel`) with `wireSidebar` (`@kerfjs/ui/wire-sidebar`): the standard collapse animation and per-side icon convention (`PanelLeft*`/`PanelRight*`/`PanelBottom*`) plus toggle, focus, compact overlay, and persistence semantics. Give a standalone panel the same `toolbar` roles and render `CollapsiblePanelRelocated` in your work-area toolbar (first in leading for a left rail, last in trailing for a right rail, a bottom toolbar or a `FloatingToolbar` restoreControl for a drawer) instead of hand-placing a second toggle. A collapsed `CollapsiblePanel`, `ResizableRegion`, or Workbench panel renders `inert` and `aria-hidden` by itself, so do not hide collapsed content yourself either. Likewise an open side overlay (a Workbench rail overlay, a `wireSidebar` compact overlay, an overlay `CollapsiblePanel` or horizontal `ResizableRegion`) hides the covered work area's `FloatingToolbar`s and restore corners by itself until it closes, so do not hide them from overlay state. A compact overlay opens only on a user action: wire-up on a compact device and a wide-to-compact crossing collapse every panel, and a wide crossing restores the inline state. Seed the signal with `signal(device.value.compact)` and pass the panel's `inlineCollapsed` default so the first compact render has no overlay. Dialogs pick the same inner layout, then present per device class (full-screen modal on `compact`, inline on desktop). A list-detail dialog is a Workbench-shaped layout on roomy devices: a full-height list sidebar and a full-height main column, each a `Pane` with its own top `Toolbar`; the main column holds the primary xl title, the close control (`data-dialog="close"` in a `without-header` Web Awesome dialog), and the record actions, never a header spanning both columns. A top-level percentage-height shell needs a definite containing height: opt into `@kerfjs/ui/document.css` and put `.kui-app-root` on the one direct mount container, or provide equivalent application-owned geometry. The global baseline is deliberately absent from `styles.css` and component imports. See `docs/app-layouts.md`, `docs/document-baseline.md`, and `docs/collapsible-panel.md`.
 23. Layouts and `Pane` are safe-area aware without configuration: backgrounds, separators, and dividers paint through a device's unsafe areas (a collapsible rail or drawer grows by the inset it docks to), content is padded only on the sides a region actually reaches, and block insets are scroll padding inside the scroller so first/last content can always be scrolled clear. Interior edges get nothing, and a collapsed rail hands its edge back to the center. Never add your own `env(safe-area-inset-*)` padding around a kerf layout or pane — that double-insets. In an app-owned arrangement of panes, pass `Pane.safeAreaEdges` (the sides that pane reaches; `[]` opts out); give an app bar or bottom bar that sits at a screen edge outside a Pane header or footer `Toolbar.safeAreaEdges` for the sides it reaches (for example `['block-start', 'inline-start', 'inline-end']`); the Workbench `mainToolbar` / `mainBottomToolbar` and panel `toolbar` configurations forward the same `safeAreaEdges` to their `Toolbar`. Do not set the internal `--kui-edge-inset-*` context yourself. The device insets are `--kui-safe-area-*` (defaulting to `env()`), overridable on `:root`. See `docs/app-layouts.md` "Safe areas".
 
 Common mistakes:
@@ -250,6 +250,10 @@ Common mistakes:
 | Keep chrome, a label, or a readout that aids no decision                                                                          | Delete it; every element must help a person decide or act                                                                                                                                                                                                                                     |
 | Override a component's default size or color because it "looks off"                                                               | Trust the default (a LucideIcon is 24px) and fix the surrounding layout instead                                                                                                                                                                                                               |
 
+For prominent content text, use `Text size="large"`; use `size="xlarge"` for display copy. Both sizes work with semantic `variant`, `tone`, and `font`, so keep heading levels based on the document outline.
+
+For nested action menus, use `PopupMenuItem.submenu` and its `checked`, `icon`, `details`, `disabledReason`, and `tone` options. The app owns choice state. For a right-click menu, use `PopupMenu` with `context: true` and call `openPopupMenuAt` from the app's `contextmenu` handler; the package positions and opens the menu. Call `closePopupMenu` for programmatic dismissal.
+
 ## Select lifecycle ownership
 
 Import `@kerfjs/ui/select/register` once. It owns the canonical Select animation

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.57` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.59` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/dist/catalog-resources.d.ts

@@ -9,7 +9,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-BN4x0rth.js';
+import './panel-toolbar-DqwtBxQL.js';
 import './lucide-icon.js';
 import 'lucide';
 

package/dist/catalog.d.ts

@@ -11,7 +11,7 @@ import './list.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './resizable-region.js';
-import './panel-toolbar-BN4x0rth.js';
+import './panel-toolbar-DqwtBxQL.js';
 import './lucide-icon.js';
 import 'lucide';
 

package/dist/catalog.js

@@ -1,6 +1,6 @@
-import { Workbench } from './chunk-G2RKFVRB.js';
+import { Workbench } from './chunk-2CCMJTVY.js';
 
-import { PopupMenu } from './chunk-WLG6SSNT.js';
+import { PopupMenu } from './chunk-UWONG4QE.js';
 
 import { Row } from './chunk-VZOFZPSO.js';
 import { ListInsetText } from './chunk-DG6G5EPF.js';
@@ -11,13 +11,13 @@ import { ToolbarText } from './chunk-XDKAYSVD.js';
 
 
 
-import { ListHeader } from './chunk-553ASUK6.js';
-import { Text } from './chunk-24PHKUR3.js';
+import { ListHeader } from './chunk-UX2VVXZ3.js';
+import { Text } from './chunk-UXT7TE6B.js';
 
 
 
 
-import { ToolbarControlGroup, ToolbarActionLink } from './chunk-ZIYOJFZD.js';
+import { ToolbarControlGroup, ToolbarActionLink } from './chunk-7JUBXOIV.js';
 import { Toolbar } from './chunk-6YFHCLHG.js';
 
 import { LucideIcon } from './chunk-4R777DUZ.js';

package/dist/{chunk-G2RKFVRB.js → chunk-2CCMJTVY.js}

@@ -2,7 +2,7 @@ import { WORKBENCH_MAIN_MIN_SIZE, WORKBENCH_MAIN_MIN_HEIGHT, workbenchRegionId,
 import { clampRegionSize, ResizeGrip } from './chunk-VHADGP3B.js';
 import { List } from './chunk-NAPE7WUS.js';
 import { FloatingToolbar } from './chunk-M7QV3IHH.js';
-import { composedPanelBody, relocatedPanelGroups } from './chunk-XCO6YCYM.js';
+import { composedPanelBody, relocatedPanelGroups } from './chunk-QPUPLNNB.js';
 import { Toolbar } from './chunk-6YFHCLHG.js';
 import { Pane } from './chunk-EZVNC4J6.js';
 import { jsxs, jsx, Fragment } from 'kerfjs/jsx-runtime';
@@ -415,4 +415,4 @@ function Workbench({
 
 export { Workbench };
 
-//# sourceMappingURL=chunk-G2RKFVRB.js.map
+//# sourceMappingURL=chunk-2CCMJTVY.js.map

package/dist/chunk-2CCMJTVY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workbench-toolbars.tsx","../src/workbench.tsx"],"names":["jsx","jsxs"],"mappings":"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","file":"chunk-2CCMJTVY.js","sourcesContent":["import {\n  FloatingToolbar,\n  type FloatingToolbarPosition,\n} from './floating-toolbar.js';\nimport { List, type ListConfig } from './list.js';\nimport { Pane, type PaneConfig } from './pane.js';\nimport {\n  composedPanelBody,\n  type PanelSide,\n  type PanelToggle,\n  type PanelToggleAttributes,\n  type PanelToolbar,\n  relocatedPanelGroups,\n} from './panel-toolbar.js';\nimport type { KerfUiContent } from './semantic-content.js';\nimport { Toolbar, type ToolbarConfig } from './toolbar.js';\nimport {\n  type WorkbenchPanelKey,\n  workbenchRegionId,\n} from './workbench-resize.js';\n\n/** The standard toggle a Workbench renders for a panel (see {@link PanelToggle}). */\nexport type WorkbenchPanelToggle = PanelToggle;\n\n/**\n * A Workbench panel's top toolbar, composed by the Workbench so its groups can\n * follow the panel's open state (see {@link PanelToolbar} for the roles).\n * A collapsed rail's marked groups and toggle go to the leading edge of\n * `mainToolbar` (left rail) or its trailing edge (right rail); a collapsed\n * drawer's go to the trailing edge of `mainBottomToolbar`, else to a\n * `FloatingToolbar` in the work area's bottom-end corner.\n */\nexport type WorkbenchPanelToolbar = PanelToolbar;\n\n/**\n * The work area's top toolbar; collapsed rails add their groups to it. Its\n * configuration forwards to its `Toolbar`. It draws no divider of its own by\n * default: the work area's `Pane` draws one under its header chrome, wherever\n * that chrome ends, while `main` is scrolled (`mainPane.chromeDividers`).\n */\nexport interface WorkbenchMainToolbar extends ToolbarConfig {\n  label: string;\n  /** The work area's title, usually an extra-large `ToolbarText`. */\n  title?: KerfUiContent;\n  /** Groups after the title. */\n  leading?: KerfUiContent;\n  center?: KerfUiContent;\n  /** Groups at the trailing edge, before a collapsed right rail's groups. */\n  trailing?: KerfUiContent;\n}\n\n/**\n * The work area's bottom toolbar; a collapsed drawer adds its groups to it.\n * Its configuration forwards to its `Toolbar`. It draws no divider of its own\n * by default: the work area's `Pane` draws one over its footer chrome while\n * more of `main` lies below (`mainPane.chromeDividers`).\n */\nexport interface WorkbenchMainBottomToolbar extends ToolbarConfig {\n  label: string;\n  leading?: KerfUiContent;\n  center?: KerfUiContent;\n  trailing?: KerfUiContent;\n}\n\nconst SIDES: Record<WorkbenchPanelKey, PanelSide> = {\n  leftRail: 'left',\n  rightRail: 'right',\n  bottomDrawer: 'bottom',\n};\n\n/** A panel as far as its toolbar is concerned. */\nexport interface WorkbenchToolbarPanel {\n  toolbar?: WorkbenchPanelToolbar;\n  footer?: KerfUiContent;\n  /** Configuration for the `Pane` a `toolbar` panel's content renders in. */\n  pane?: PaneConfig;\n  content: KerfUiContent;\n  collapsed?: boolean;\n  /** The corner a collapsed panel's restore controls float in. */\n  restorePosition?: FloatingToolbarPosition;\n}\n\n/** A Workbench toggle's wiring hooks: its side, morph key, and panel. */\nconst toggleAttributes = (\n  workbenchId: string,\n  key: WorkbenchPanelKey,\n): PanelToggleAttributes => ({\n  'data-workbench-toggle': SIDES[key],\n  // Keyed, so the morph removes a toggle that leaves a toolbar instead of\n  // reusing its (possibly focused) button for a different control.\n  'data-key': `${workbenchRegionId(workbenchId, key)}-toggle`,\n  'aria-controls': workbenchRegionId(workbenchId, key),\n});\n\n/**\n * The groups a collapsed panel hands to the work area: its marked groups,\n * then its toggle. Empty while the panel is open or has no toolbar.\n */\nexport function relocatedGroups(\n  workbenchId: string,\n  key: WorkbenchPanelKey,\n  panel: WorkbenchToolbarPanel | undefined,\n): KerfUiContent[] {\n  return relocatedPanelGroups(\n    panel?.toolbar,\n    SIDES[key],\n    Boolean(panel?.collapsed),\n    toggleAttributes(workbenchId, key),\n  );\n}\n\n/**\n * A panel's content, wrapped in a `Pane` under its composed toolbar when it\n * has one (with its optional `footer` below). Without a toolbar the content\n * renders as given.\n */\nexport function panelBody(\n  workbenchId: string,\n  key: WorkbenchPanelKey,\n  panel: WorkbenchToolbarPanel,\n) {\n  const toolbar = panel.toolbar;\n  if (!toolbar) return panel.content;\n  return composedPanelBody({\n    toolbar,\n    side: SIDES[key],\n    collapsed: Boolean(panel.collapsed),\n    attributes: toggleAttributes(workbenchId, key),\n    pane: panel.pane,\n    footer: panel.footer,\n    content: panel.content,\n  });\n}\n\n/**\n * The work area's `mainHeader` / `mainFooter` chrome in a `List` carrying the\n * app's configuration; an omitted or `undefined` field keeps the `List`\n * default (no divider: the work area's `Pane` draws its chrome dividers).\n */\nfunction chromeList(content: KerfUiContent, config: ListConfig | undefined) {\n  return (\n    <List\n      dividerSides={config?.dividerSides}\n      gap={config?.gap}\n      hAlign={config?.hAlign}\n      vAlign={config?.vAlign}\n      textInsets={config?.textInsets}\n      controlInsets={config?.controlInsets}\n    >\n      {content}\n    </List>\n  );\n}\n\n/**\n * Whether the work area's header or footer chrome stays pinned (`fixed`),\n * scrolls away with the content (`scroll`), or stays pinned while the work\n * area is tall enough and scrolls with the content when it is short (`auto`,\n * the Pane's `chromePlacement=\"auto\"`; it applies to the pinned header and\n * footer together).\n */\nexport type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';\n\n/**\n * The work area: the app's `main` in a `Pane` (configured by `mainPane`)\n * under `mainToolbar` and any `mainHeader` list, and above any `mainFooter`\n * list and `mainBottomToolbar` (the header and footer lists configured by\n * `mainHeaderList` / `mainFooterList`), with each collapsed panel's groups\n * added to the toolbar on its side. Without any of that chrome, `main`\n * renders as given and `mainPane` is ignored.\n */\nexport function mainBody({\n  workbenchId,\n  main,\n  mainToolbar,\n  mainHeader,\n  mainFooter,\n  mainBottomToolbar,\n  mainHeaderPlacement = 'fixed',\n  mainFooterPlacement = 'fixed',\n  mainPane,\n  mainHeaderList,\n  mainFooterList,\n  leftRail,\n  rightRail,\n  bottomDrawer,\n}: {\n  workbenchId: string;\n  main: KerfUiContent;\n  mainToolbar?: WorkbenchMainToolbar;\n  mainHeader?: KerfUiContent;\n  mainFooter?: KerfUiContent;\n  mainBottomToolbar?: WorkbenchMainBottomToolbar;\n  mainHeaderPlacement?: WorkbenchChromePlacement;\n  mainFooterPlacement?: WorkbenchChromePlacement;\n  mainPane?: PaneConfig;\n  mainHeaderList?: ListConfig;\n  mainFooterList?: ListConfig;\n  leftRail?: WorkbenchToolbarPanel;\n  rightRail?: WorkbenchToolbarPanel;\n  bottomDrawer?: WorkbenchToolbarPanel;\n}) {\n  if (!mainToolbar && !mainBottomToolbar && !mainHeader && !mainFooter)\n    return main;\n  const left = relocatedGroups(workbenchId, 'leftRail', leftRail);\n  const right = relocatedGroups(workbenchId, 'rightRail', rightRail);\n  const drawer = mainBottomToolbar\n    ? relocatedGroups(workbenchId, 'bottomDrawer', bottomDrawer)\n    : [];\n  // The Pane draws one divider under the header chrome and one over the\n  // footer chrome, wherever that chrome ends, from the scroll state.\n  const header =\n    !mainToolbar && !mainHeader ? undefined : (\n      <>\n        {mainToolbar ? (\n          <Toolbar\n            label={mainToolbar.label}\n            dividerSides={mainToolbar.dividerSides}\n            centerAlign={mainToolbar.centerAlign}\n            responsive={mainToolbar.responsive}\n            responsiveAt={mainToolbar.responsiveAt}\n            safeAreaEdges={mainToolbar.safeAreaEdges}\n            leading={\n              <>\n                {left}\n                {mainToolbar.title}\n                {mainToolbar.leading}\n              </>\n            }\n            center={mainToolbar.center}\n            trailing={\n              <>\n                {mainToolbar.trailing}\n                {right}\n              </>\n            }\n          />\n        ) : null}\n        {mainHeader ? chromeList(mainHeader, mainHeaderList) : null}\n      </>\n    );\n  const footer =\n    !mainFooter && !mainBottomToolbar ? undefined : (\n      <>\n        {mainFooter ? chromeList(mainFooter, mainFooterList) : null}\n        {mainBottomToolbar ? (\n          <Toolbar\n            label={mainBottomToolbar.label}\n            dividerSides={mainBottomToolbar.dividerSides}\n            centerAlign={mainBottomToolbar.centerAlign}\n            responsive={mainBottomToolbar.responsive}\n            responsiveAt={mainBottomToolbar.responsiveAt}\n            safeAreaEdges={mainBottomToolbar.safeAreaEdges}\n            leading={mainBottomToolbar.leading}\n            center={mainBottomToolbar.center}\n            trailing={\n              <>\n                {mainBottomToolbar.trailing}\n                {drawer}\n              </>\n            }\n          />\n        ) : null}\n      </>\n    );\n  const scrollHeader = mainHeaderPlacement === 'scroll';\n  const scrollFooter = mainFooterPlacement === 'scroll';\n  return (\n    <Pane\n      header={scrollHeader ? undefined : header}\n      footer={scrollFooter ? undefined : footer}\n      chromePlacement={\n        mainHeaderPlacement === 'auto' || mainFooterPlacement === 'auto'\n          ? 'auto'\n          : 'fixed'\n      }\n      contentElement={mainPane?.contentElement}\n      contentLabel={mainPane?.contentLabel}\n      separators={mainPane?.separators}\n      safeAreaEdges={mainPane?.safeAreaEdges}\n      chromeDividers={mainPane?.chromeDividers}\n    >\n      {scrollHeader || scrollFooter ? (\n        // Chrome that scrolls joins the content in one gapless column that\n        // fills the scroller, so it scrolls away with the content.\n        <List flex>\n          {scrollHeader ? header : null}\n          {main}\n          {scrollFooter ? footer : null}\n        </List>\n      ) : (\n        main\n      )}\n    </Pane>\n  );\n}\n\n/**\n * A collapsed panel's groups when the work area has no toolbar on its side\n * to take them: a `FloatingToolbar` for the panel's restore corner, so the\n * panel can always be reopened.\n */\nexport function floatingRestore(\n  workbenchId: string,\n  key: WorkbenchPanelKey,\n  panel: WorkbenchToolbarPanel | undefined,\n  hasTargetToolbar: boolean,\n) {\n  if (hasTargetToolbar) return undefined;\n  const groups = relocatedGroups(workbenchId, key, panel);\n  if (groups.length === 0) return undefined;\n  return (\n    <FloatingToolbar\n      label={panel!.toolbar!.label}\n      position={\n        panel!.restorePosition ??\n        (key === 'leftRail' ? 'bottom-start' : 'bottom-end')\n      }\n    >\n      {groups}\n    </FloatingToolbar>\n  );\n}\n","import type { SafeHtml } from 'kerfjs';\n\nimport type { ListConfig } from './list.js';\nimport type { PaneConfig } from './pane.js';\nimport {\n  clampRegionSize,\n  type ResizableRegionAxis,\n  type ResizableRegionCollapseMotion,\n  type ResizableRegionContentOverflow,\n  type ResizableRegionEdge,\n  type ResizableRegionPresentation,\n  type ResizableRegionRestorePosition,\n  type ResizableRegionSeparator,\n} from './resizable-region.js';\nimport { ResizeGrip } from './resize-grip.js';\nimport type { KerfUiContent } from './semantic-content.js';\nimport {\n  WORKBENCH_MAIN_MIN_HEIGHT,\n  WORKBENCH_MAIN_MIN_SIZE,\n  WORKBENCH_RESIZE_DEFAULTS,\n  type WorkbenchPanelKey,\n  workbenchRegionId,\n} from './workbench-resize.js';\nimport {\n  floatingRestore,\n  mainBody,\n  panelBody,\n  type WorkbenchChromePlacement,\n  type WorkbenchMainBottomToolbar,\n  type WorkbenchMainToolbar,\n  type WorkbenchPanelToolbar,\n} from './workbench-toolbars.js';\n\nexport type {\n  WorkbenchChromePlacement,\n  WorkbenchMainBottomToolbar,\n  WorkbenchMainToolbar,\n  WorkbenchPanelToggle,\n  WorkbenchPanelToolbar,\n} from './workbench-toolbars.js';\n\n/**\n * The Workbench container breakpoint below which a panel presents as an\n * overlay: `narrow` (704px or less) or `compact` (448px or less) — the same\n * breakpoints as `ResizableRegion`'s `responsiveFillAt` — or `never` to keep\n * it inline at every width.\n */\nexport type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never';\n\n/**\n * How wide a rail's overlay is in a compact (448px or less) Workbench: `inset`\n * fills the Workbench less a dismiss margin on the side away from the rail's\n * edge, so a press beside it closes it; `full` fills the Workbench.\n */\nexport type WorkbenchCompactOverlay = 'inset' | 'full';\n\n/** Drag-resize limits for a resizable Workbench panel, in px. */\nexport interface WorkbenchPanelResizable {\n  /** Smallest size (default 180 for a rail, 120 for the drawer). */\n  min?: number;\n  /** Largest size (default 480). */\n  max?: number;\n}\n\n/** A collapsible Workbench panel — a side rail or the bottom drawer. */\nexport interface WorkbenchPanel {\n  content: KerfUiContent;\n  /**\n   * The panel's top toolbar, composed by the Workbench: its marked groups\n   * and standard `toggle` move to the work area's toolbar while the panel is\n   * collapsed. With it, `content` renders in a `Pane` below the toolbar.\n   */\n  toolbar?: WorkbenchPanelToolbar;\n  /** Optional bottom toolbar under a `toolbar` panel's content. */\n  footer?: KerfUiContent;\n  /**\n   * Configuration for a `toolbar` panel's `Pane` (`contentElement`,\n   * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example\n   * `{ contentElement: 'nav', contentLabel: 'Sections' }` for a navigation\n   * rail. Omitted or `undefined` fields keep the `Pane` defaults. Ignored\n   * without a `toolbar`, where `content` renders as given.\n   */\n  pane?: PaneConfig;\n  /** Whether the panel is currently collapsed (the app owns this). */\n  collapsed?: boolean;\n  /**\n   * Rail width, or drawer height, in px. Overrides the CSS default. For a\n   * resizable panel it is the current size (default 280 for a rail, 220 for\n   * the drawer), clamped to the limits; the app owns it and `wireWorkbench`\n   * reports each resize.\n   */\n  size?: number;\n  /**\n   * Opt in to drag and keyboard resizing on the panel's inner separator:\n   * `true` for the default limits, or `{ min, max }`. Off by default. Pair it\n   * with `wireWorkbench` from `@kerfjs/ui/wire-workbench`.\n   */\n  resizable?: boolean | WorkbenchPanelResizable;\n  /** Accessible name for the panel region. */\n  label?: string;\n  separator?: ResizableRegionSeparator;\n  collapseMotion?: ResizableRegionCollapseMotion;\n  contentOverflow?: ResizableRegionContentOverflow;\n  presentation?: ResizableRegionPresentation;\n  /**\n   * Present the panel as an overlay, without a separator, below a Workbench\n   * container breakpoint, and inline above it — the CSS decides, so the app\n   * needs no device-class check. A rail overlays from its side at full\n   * height, over the work area and an open drawer; the bottom drawer\n   * overlays the bottom of the work-area column. Rails default to `narrow`\n   * (pass `never` to keep one inline); the drawer defaults to inline.\n   */\n  responsiveOverlayAt?: WorkbenchResponsiveOverlayAt;\n  /**\n   * A rail's overlay width in a compact Workbench (default `inset`: the\n   * Workbench less `--kui-workbench-overlay-dismiss-margin`, 44px). Ignored\n   * by the drawer.\n   */\n  compactOverlay?: WorkbenchCompactOverlay;\n  /**\n   * Control shown while collapsed, in a safe-area-aware corner of the\n   * Workbench (not the viewport); the bottom drawer's sits in the work-area\n   * column. Prefer `toolbar.toggle`, which the Workbench relocates into the\n   * work area's toolbar (or this corner when that toolbar is absent).\n   */\n  restoreControl?: SafeHtml;\n  restorePosition?: ResizableRegionRestorePosition;\n}\n\nexport interface WorkbenchProps {\n  /**\n   * The Workbench's `id`. Each panel's `id` derives from it —\n   * `<id>-left-rail`, `<id>-right-rail`, `<id>-bottom-drawer` — so a toggle\n   * can name the panel it shows and hides with `aria-controls`.\n   */\n  id: string;\n  label: string;\n  /** The central work area. */\n  main: KerfUiContent;\n  /**\n   * The work area's top toolbar. A collapsed left rail's marked groups\n   * and toggle lead it; a collapsed right rail's trail it. With it, `main`\n   * renders in a `Pane` below the toolbar.\n   */\n  mainToolbar?: WorkbenchMainToolbar;\n  /**\n   * Fixed content under `mainToolbar` — supporting copy such as a\n   * description — divided from the scrolling `main` below it.\n   */\n  mainHeader?: KerfUiContent;\n  /**\n   * Fixed content over `mainBottomToolbar` — a status line or a resource\n   * toolbar — divided from the scrolling `main` above it.\n   */\n  mainFooter?: KerfUiContent;\n  /**\n   * The work area's bottom toolbar. A collapsed drawer's marked groups and\n   * toggle trail it; without it they float in the work area's corner.\n   */\n  mainBottomToolbar?: WorkbenchMainBottomToolbar;\n  /**\n   * Whether `mainToolbar` and `mainHeader` stay pinned (`fixed`, default),\n   * scroll away with `main` (`scroll`) — useful where large text would leave\n   * pinned chrome little room — or stay pinned while the work area is tall\n   * enough and scroll with `main` when it is short (`auto`).\n   */\n  mainHeaderPlacement?: WorkbenchChromePlacement;\n  /** The same for `mainFooter` and `mainBottomToolbar` (default `fixed`). */\n  mainFooterPlacement?: WorkbenchChromePlacement;\n  /**\n   * Configuration for the work area's `Pane` (`contentElement`,\n   * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`), which it has whenever it\n   * has a toolbar, `mainHeader`, or `mainFooter`; without that chrome, `main`\n   * renders as given and this is ignored. Omitted or `undefined` fields keep\n   * the `Pane` defaults.\n   */\n  mainPane?: PaneConfig;\n  /**\n   * Configuration for the `List` that holds `mainHeader` (`gap`, `hAlign`,\n   * `vAlign`, `dividerSides`, `textInsets`, `controlInsets`). Omitted or\n   * `undefined` fields keep the defaults (no divider: the work area's\n   * `Pane` draws the line under its header chrome).\n   */\n  mainHeaderList?: ListConfig;\n  /**\n   * The same for the `List` that holds `mainFooter` (no divider by default:\n   * the work area's `Pane` draws the line over its footer chrome).\n   */\n  mainFooterList?: ListConfig;\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  bottomDrawer?: WorkbenchPanel;\n  /**\n   * Minimum width, in px, the work area keeps beside the inline rails, fixed\n   * or `resizable` (default 320; `0` turns it off). Resizing a rail stops\n   * where the work area would drop below it, and inline rails shrink\n   * proportionally when the Workbench gets narrower. Workbenches without a\n   * rail ignore it.\n   */\n  mainMinSize?: number;\n  /**\n   * Minimum height, in px, the work area keeps above an inline bottom drawer,\n   * fixed or `resizable` (default 120; `0` turns it off) — the drawer's\n   * counterpart of `mainMinSize`. Resizing the drawer stops where the work\n   * area would drop below it, and the drawer shrinks when the Workbench gets\n   * shorter. Workbenches without a drawer ignore it.\n   */\n  mainMinHeight?: number;\n  className?: string;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\ninterface ResolvedResize {\n  regionId: string;\n  axis: ResizableRegionAxis;\n  edge: ResizableRegionEdge;\n  size: number;\n  min: number;\n  max: number;\n}\n\n/**\n * Each panel's separator is its inner edge. Growing the left rail moves that\n * edge toward the inline end; growing the right rail or the drawer moves it\n * toward the start — the same edge vocabulary `ResizableRegion` uses.\n */\nconst EDGES: Record<WorkbenchPanelKey, ResizableRegionEdge> = {\n  leftRail: 'end',\n  rightRail: 'start',\n  bottomDrawer: 'start',\n};\n\nconst DEFAULT_LABELS: Record<WorkbenchPanelKey, string> = {\n  leftRail: 'left rail',\n  rightRail: 'right rail',\n  bottomDrawer: 'bottom drawer',\n};\n\nfunction resolveResize(\n  id: string,\n  key: WorkbenchPanelKey,\n  panel: WorkbenchPanel,\n): ResolvedResize | undefined {\n  if (!panel.resizable) return undefined;\n  const defaults = WORKBENCH_RESIZE_DEFAULTS[key];\n  const limits = panel.resizable === true ? {} : panel.resizable;\n  const min = limits.min ?? defaults.min;\n  const max = Math.max(min, limits.max ?? defaults.max);\n  return {\n    regionId: workbenchRegionId(id, key),\n    axis: key === 'bottomDrawer' ? 'vertical' : 'horizontal',\n    edge: EDGES[key],\n    size: clampRegionSize(panel.size ?? defaults.size, min, max),\n    min,\n    max,\n  };\n}\n\n/** The attributes a resizable panel adds for the resize wiring to read. */\nconst resizeAttributes = (resize: ResolvedResize | undefined) =>\n  resize\n    ? {\n        'data-resizable': 'true',\n        'data-region-id': resize.regionId,\n        'data-axis': resize.axis,\n        'data-edge': resize.edge,\n      }\n    : {};\n\n/**\n * A resizable panel's size lives in the resize wiring's track property, so a\n * drag or key press resizes the panel before the app re-renders; the CSS maps\n * it onto the rail width or drawer height.\n */\nfunction panelStyle(\n  panel: WorkbenchPanel,\n  resize: ResolvedResize | undefined,\n  sizeProperty: string,\n) {\n  if (resize) return `--kui-resizable-region-size:${resize.size}px`;\n  return panel.size ? `${sizeProperty}: ${panel.size}px` : undefined;\n}\n\n/**\n * The separator a resizable panel owns: the same focusable `role=\"separator\"`\n * contract a `ResizableRegion` handle carries, so one resize wiring drives\n * both. It leaves the tab order while the panel is collapsed or not inline.\n */\nfunction PanelHandle({\n  panel,\n  resize,\n  label,\n}: {\n  panel: WorkbenchPanel;\n  resize: ResolvedResize;\n  label: string;\n}) {\n  const inert =\n    Boolean(panel.collapsed) || (panel.presentation ?? 'inline') !== 'inline';\n  return (\n    <div\n      class=\"kui-workbench__handle\"\n      role=\"separator\"\n      tabindex={inert ? '-1' : '0'}\n      aria-label={`Resize ${label}`}\n      aria-orientation={\n        resize.axis === 'horizontal' ? 'vertical' : 'horizontal'\n      }\n      aria-valuemin={resize.min}\n      aria-valuemax={resize.max}\n      aria-valuenow={resize.size}\n      aria-hidden={inert ? 'true' : undefined}\n      data-kui-resize-handle\n      data-region-id={resize.regionId}\n    >\n      <span class=\"kui-workbench__handle-icon\" aria-hidden=\"true\">\n        <ResizeGrip axis={resize.axis} />\n      </span>\n    </div>\n  );\n}\n\n/**\n * A collapsed panel leaves the accessibility tree as a whole, like a collapsed\n * `CollapsiblePanel`: its content and separator are already inert or hidden,\n * so the labeled landmark would otherwise stay behind, empty, for a screen\n * reader to land on. Its restore control renders outside it and stays\n * reachable.\n */\nfunction hiddenFromAccessibility(panel: WorkbenchPanel) {\n  return panel.collapsed || panel.presentation === 'hidden'\n    ? ('true' as const)\n    : undefined;\n}\n\n/** A breakpoint's attribute value; `never` (or none) renders no attribute. */\nconst responsiveAt = (at: WorkbenchResponsiveOverlayAt | undefined) =>\n  at === 'never' ? undefined : at;\n\nfunction Rail({\n  id,\n  side,\n  panel,\n}: {\n  id: string;\n  side: 'left' | 'right';\n  panel: WorkbenchPanel;\n}) {\n  const key: WorkbenchPanelKey = side === 'left' ? 'leftRail' : 'rightRail';\n  const resize = resolveResize(id, key, panel);\n  return (\n    <aside\n      id={workbenchRegionId(id, key)}\n      class={`kui-workbench__rail kui-workbench__rail--${side}`}\n      data-workbench-rail={side}\n      data-collapsed={String(panel.collapsed ?? false)}\n      data-separator={panel.separator ?? 'auto'}\n      data-collapse-motion={panel.collapseMotion ?? 'slide'}\n      data-content-overflow={panel.contentOverflow ?? 'clip'}\n      data-presentation={panel.presentation ?? 'inline'}\n      data-responsive-overlay-at={responsiveAt(\n        panel.responsiveOverlayAt ?? 'narrow',\n      )}\n      data-compact-overlay={panel.compactOverlay ?? 'inset'}\n      {...resizeAttributes(resize)}\n      aria-label={panel.label || undefined}\n      aria-hidden={hiddenFromAccessibility(panel)}\n      inert={Boolean(panel.collapsed)}\n      style={panelStyle(panel, resize, '--kui-workbench-rail-width')}\n    >\n      <div\n        class=\"kui-workbench__panel-content\"\n        data-workbench-panel-content\n        inert={Boolean(panel.collapsed)}\n      >\n        {panelBody(id, key, panel)}\n      </div>\n      {resize && (\n        <PanelHandle\n          panel={panel}\n          resize={resize}\n          label={panel.label || DEFAULT_LABELS[key]}\n        />\n      )}\n    </aside>\n  );\n}\n\nfunction Drawer({ id, panel }: { id: string; panel: WorkbenchPanel }) {\n  const resize = resolveResize(id, 'bottomDrawer', panel);\n  return (\n    <section\n      id={workbenchRegionId(id, 'bottomDrawer')}\n      class=\"kui-workbench__drawer\"\n      data-workbench-drawer\n      data-collapsed={String(panel.collapsed ?? false)}\n      data-separator={panel.separator ?? 'auto'}\n      data-collapse-motion={panel.collapseMotion ?? 'slide'}\n      data-content-overflow={panel.contentOverflow ?? 'clip'}\n      data-presentation={panel.presentation ?? 'inline'}\n      data-responsive-overlay-at={responsiveAt(panel.responsiveOverlayAt)}\n      {...resizeAttributes(resize)}\n      aria-label={panel.label || undefined}\n      aria-hidden={hiddenFromAccessibility(panel)}\n      inert={Boolean(panel.collapsed)}\n      style={panelStyle(panel, resize, '--kui-workbench-drawer-height')}\n    >\n      <div\n        class=\"kui-workbench__panel-content\"\n        data-workbench-panel-content\n        inert={Boolean(panel.collapsed)}\n      >\n        {panelBody(id, 'bottomDrawer', panel)}\n      </div>\n      {resize && (\n        <PanelHandle\n          panel={panel}\n          resize={resize}\n          label={panel.label || DEFAULT_LABELS.bottomDrawer}\n        />\n      )}\n    </section>\n  );\n}\n\n/** A collapsed panel's restore control, outside the clipped panel. */\nfunction restore(\n  panel: WorkbenchPanel | undefined,\n  side: 'left' | 'right' | 'bottom',\n  position: ResizableRegionRestorePosition,\n  generated: SafeHtml | undefined,\n) {\n  const control = panel?.restoreControl ?? generated;\n  if (!panel?.collapsed || !control || panel.presentation === 'hidden')\n    return '';\n  return (\n    <div\n      class=\"kui-workbench__restore\"\n      data-panel={side}\n      data-position={panel.restorePosition ?? position}\n    >\n      {control}\n    </div>\n  );\n}\n\n/**\n * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and\n * bottom drawer around a central work area (any absent). Collapsing snaps the\n * panel's track to zero in one reflow while its fixed-size content slides out via\n * a composited transform — the instant-width / sliding-content technique, so the\n * work area relayouts once, not per frame. Bottom-drawer content stays anchored\n * to the shell's stable bottom edge throughout that transition. The app owns\n * each `collapsed` flag; the collapse is pure CSS. A collapsed panel renders\n * `inert` and `aria-hidden`, so neither Tab nor assistive technology reaches\n * controls that have slid out of view or an empty landmark (its restore control\n * lives outside it and stays reachable). A panel may opt in to drag and keyboard resizing with\n * `resizable`, which `wireWorkbench` drives. See `docs/23-app-layouts.md` §3.3.\n */\nexport function Workbench({\n  id,\n  label,\n  main,\n  leftRail,\n  rightRail,\n  bottomDrawer,\n  mainToolbar,\n  mainHeader,\n  mainFooter,\n  mainBottomToolbar,\n  mainHeaderPlacement,\n  mainFooterPlacement,\n  mainPane,\n  mainHeaderList,\n  mainFooterList,\n  mainMinSize = WORKBENCH_MAIN_MIN_SIZE,\n  mainMinHeight = WORKBENCH_MAIN_MIN_HEIGHT,\n  className = '',\n  slot,\n}: WorkbenchProps) {\n  // Each work-area minimum applies only on an axis a panel shares with it:\n  // the width beside a rail, the height above the drawer.\n  const px = (value: number) => Math.max(0, Math.round(value));\n  const mainMin = leftRail || rightRail ? px(mainMinSize) : undefined;\n  const mainMinBlock = bottomDrawer ? px(mainMinHeight) : undefined;\n  const style = [\n    mainMin === undefined ? '' : `--_kui-workbench-main-min-width:${mainMin}px`,\n    mainMinBlock === undefined\n      ? ''\n      : `--_kui-workbench-main-min-height:${mainMinBlock}px`,\n  ]\n    .filter(Boolean)\n    .join(';');\n  return (\n    <section\n      class={`kui-workbench ${className}`.trim()}\n      id={id}\n      data-component=\"workbench\"\n      data-main-min-size={mainMin === undefined ? undefined : String(mainMin)}\n      data-main-min-height={\n        mainMinBlock === undefined ? undefined : String(mainMinBlock)\n      }\n      style={style || undefined}\n      aria-label={label}\n      slot={slot}\n    >\n      {leftRail && <Rail id={id} side=\"left\" panel={leftRail} />}\n      {restore(\n        leftRail,\n        'left',\n        'bottom-start',\n        floatingRestore(id, 'leftRail', leftRail, Boolean(mainToolbar)),\n      )}\n      <div class=\"kui-workbench__center\">\n        <div class=\"kui-workbench__main\" data-workbench-main>\n          {mainBody({\n            workbenchId: id,\n            main,\n            mainToolbar,\n            mainHeader,\n            mainFooter,\n            mainBottomToolbar,\n            mainHeaderPlacement,\n            mainFooterPlacement,\n            mainPane,\n            mainHeaderList,\n            mainFooterList,\n            leftRail,\n            rightRail,\n            bottomDrawer,\n          })}\n        </div>\n        {bottomDrawer && <Drawer id={id} panel={bottomDrawer} />}\n        {restore(\n          bottomDrawer,\n          'bottom',\n          'bottom-end',\n          floatingRestore(\n            id,\n            'bottomDrawer',\n            bottomDrawer,\n            Boolean(mainBottomToolbar),\n          ),\n        )}\n      </div>\n      {rightRail && <Rail id={id} side=\"right\" panel={rightRail} />}\n      {restore(\n        rightRail,\n        'right',\n        'bottom-end',\n        floatingRestore(id, 'rightRail', rightRail, Boolean(mainToolbar)),\n      )}\n    </section>\n  );\n}\n"]}