@kerfjs/ui 5.0.0-beta.3 → 5.0.0-beta.6

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.3` and `kerfjs@5.0.0-beta.3`. 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.6` and `kerfjs@5.0.0-beta.6`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/disclosure-arrow`
 
@@ -44,13 +44,15 @@ export { Toolbar, type ToolbarProps };
 ```ts
 import * as kerfjs from 'kerfjs';
 
-type ToolbarTextSize = 'large' | 'default' | 'small';
+type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small';
 interface ToolbarTextProps {
     text: string;
     size?: ToolbarTextSize;
     className?: string;
+    /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */
+    id?: string;
 }
-declare function ToolbarText({ text, size, className }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, className, id }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
 ```
@@ -212,26 +214,12 @@ declare function MenuItem({ label, icon, trailing, selected, action, itemId, cla
 export { MenuItem, type MenuItemProps };
 ```
 
-## `@kerfjs/ui/page-header`
+## `@kerfjs/ui/panel-header`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
 
-interface PageHeaderProps {
-    title: string | SafeHtml;
-    action?: SafeHtml;
-}
-declare function PageHeader({ title, action }: PageHeaderProps): SafeHtml;
-
-export { PageHeader, type PageHeaderProps };
-```
-
-## `@kerfjs/ui/dialog-header`
-
-```ts
-import { SafeHtml } from 'kerfjs';
-
-interface DialogHeaderProps {
+interface PanelHeaderProps {
     title: string;
     titleId: string;
     summary?: string;
@@ -239,11 +227,22 @@ interface DialogHeaderProps {
     icon?: SafeHtml;
     iconClassName?: string;
     actions?: SafeHtml;
-    actionsLabel?: string;
 }
-declare function DialogHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions, actionsLabel }: DialogHeaderProps): SafeHtml;
+/**
+ * The heading of a panel, dialog, or page: a plain `Toolbar` whose leading zone
+ * holds an optional icon control group and the title as extra-large `ToolbarText`,
+ * whose trailing zone holds the app's action controls, and with an optional
+ * subtitle on its own row, left-aligned with the title.
+ *
+ * PanelHeader overrides no Toolbar styles — it is just a Toolbar with an xl title.
+ * The only styling it adds is the icon group's fill/border color and the subtitle.
+ * When no icon is provided, the icon group is omitted entirely. The `actions` slot
+ * is passed straight into the toolbar's trailing zone; the app supplies whatever
+ * trailing controls it needs (typically a `ToolbarControlGroup`).
+ */
+declare function PanelHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions }: PanelHeaderProps): SafeHtml;
 
-export { DialogHeader, type DialogHeaderProps };
+export { PanelHeader, type PanelHeaderProps };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -343,6 +342,205 @@ declare function wireTabBars(root: HTMLElement | Document, { onReorder }: WireTa
 export { type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };
 ```
 
+## `@kerfjs/ui/nav-stack`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+/**
+ * One entry in a {@link NavStack}. The app owns the stack as an array (usually a
+ * signal); `NavStack` renders it and `wireNavStack` animates the transitions.
+ */
+interface NavStackView {
+    /** Stable identity for keyed reconcile and transition direction. */
+    key: string;
+    content: SafeHtml;
+    /** Title shown in the top toolbar for this view. */
+    title?: string;
+    /** Trailing actions for this view's top toolbar. */
+    toolbar?: SafeHtml;
+}
+interface NavStackProps {
+    id: string;
+    /** Accessible name for the stack region. */
+    label: string;
+    /** The stack, root first; the last entry is the active top view. */
+    views: NavStackView[];
+    /** Accessible label for the back control (default "Back"). */
+    backLabel?: string;
+    /** Hide the top toolbar entirely (rare — a fully custom-chrome view). */
+    hideToolbar?: boolean;
+    /** Optional persistent bottom toolbar. */
+    bottomToolbar?: SafeHtml;
+    className?: string;
+}
+/**
+ * A navigation stack (iOS-style push/pop). Renders every entry stacked, the last
+ * one active; `@kerfjs/ui/wire-nav-stack`'s `wireNavStack` slides the content and
+ * cross-fades the chrome across a change. A single-pane layout is a `NavStack`
+ * with one entry. See `docs/23-app-layouts.md` §3.1.
+ */
+declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className }: NavStackProps): SafeHtml;
+
+export { NavStack, type NavStackProps, type NavStackView };
+```
+
+## `@kerfjs/ui/wire-nav-stack`
+
+```ts
+interface WireNavStackOptions {
+    /** Invoked when the back control is activated. The app pops its own stack. */
+    onBack?: () => void;
+    /** Transition duration in ms (default 200). Set 0 to disable animation. */
+    duration?: number;
+}
+/**
+ * Animate a `NavStack`'s push/pop transitions and wire its back control. The app
+ * owns the stack (a signal of `NavStackView[]`) and re-renders `NavStack` when it
+ * changes; this helper slides the content and settles the chrome across each
+ * change, and calls `onBack` when the back control is used. Returns a disposer.
+ */
+declare function wireNavStack(root: Element, options?: WireNavStackOptions): () => void;
+
+export { type WireNavStackOptions, wireNavStack };
+```
+
+## `@kerfjs/ui/split-view`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+interface SplitViewResizable {
+    size: number;
+    min: number;
+    max: number;
+}
+interface SplitViewProps {
+    id: string;
+    label: string;
+    /** The list (primary) pane. */
+    list: SafeHtml;
+    /** The detail (secondary) pane. */
+    detail: SafeHtml;
+    /**
+     * Compact ("one pane at a time") classes — a handset or portrait tablet.
+     * Derive from `deviceClass().value.compact`. When true the split collapses to
+     * a `NavStack`: the list is the root and the detail is pushed over it.
+     */
+    compact?: boolean;
+    /** In compact mode, whether the detail is currently pushed over the list. */
+    detailActive?: boolean;
+    /** Title/label for the list (compact NavStack root + region label). */
+    listTitle?: string;
+    /** Title/label for the detail (compact NavStack pushed view + region label). */
+    detailTitle?: string;
+    /** Back label for the compact NavStack (default "Back"). */
+    backLabel?: string;
+    /** A resizable separator on roomy classes (min/max px). Omit for a fixed split. */
+    resizable?: SplitViewResizable;
+    className?: string;
+}
+/**
+ * A list-detail (master-detail) split. On roomy classes it shows both panes side
+ * by side with an optional resizable separator; on compact classes it collapses
+ * to a `NavStack` (list → detail). See `docs/23-app-layouts.md` §3.2. Compose the
+ * resizable wiring with `wireResizableRegions` and the compact back with
+ * `wireNavStack`.
+ */
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className }: SplitViewProps): SafeHtml;
+
+export { SplitView, type SplitViewProps, type SplitViewResizable };
+```
+
+## `@kerfjs/ui/workbench`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+/** A collapsible Workbench panel — a side rail or the bottom drawer. */
+interface WorkbenchPanel {
+    content: SafeHtml;
+    /** Whether the panel is currently collapsed (the app owns this). */
+    collapsed?: boolean;
+    /** Rail width, or drawer height, in px. Overrides the CSS default. */
+    size?: number;
+    /** Accessible name for the panel region. */
+    label?: string;
+}
+interface WorkbenchProps {
+    id: string;
+    label: string;
+    /** The central work area. */
+    main: SafeHtml;
+    leftRail?: WorkbenchPanel;
+    rightRail?: WorkbenchPanel;
+    bottomDrawer?: WorkbenchPanel;
+    className?: string;
+}
+/**
+ * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and
+ * bottom drawer around a central work area (any absent). Collapsing snaps the
+ * panel's track to zero in one reflow while its fixed-size content slides out via
+ * a composited transform — the instant-width / sliding-content technique, so the
+ * work area relayouts once, not per frame. The app owns each `collapsed` flag;
+ * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.
+ */
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className }: WorkbenchProps): SafeHtml;
+
+export { Workbench, type WorkbenchPanel, type WorkbenchProps };
+```
+
+## `@kerfjs/ui/tab-scaffold`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+interface TabScaffoldTab {
+    id: string;
+    label: string;
+    /** Decorative icon shown above the label in the bottom bar. */
+    icon?: SafeHtml;
+    /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */
+    content: SafeHtml;
+}
+interface TabScaffoldProps {
+    id: string;
+    /** Accessible name for the tab bar. */
+    label: string;
+    tabs: TabScaffoldTab[];
+    /** The controlled active tab id (the app owns selection). */
+    active: string;
+    className?: string;
+}
+/**
+ * A mobile-first, iOS-like bottom tab scaffold: a bottom tab bar that switches
+ * between major sections, each tab keeping its own content (usually a `NavStack`)
+ * mounted so its stack and scroll survive a switch. Controlled — the app owns
+ * `active`; wire selection with `@kerfjs/ui/wire-tab-scaffold`'s `wireTabScaffold`.
+ * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of
+ * a bottom bar. See `docs/23-app-layouts.md` §3.4.
+ */
+declare function TabScaffold({ id, label, tabs, active, className }: TabScaffoldProps): SafeHtml;
+
+export { TabScaffold, type TabScaffoldProps, type TabScaffoldTab };
+```
+
+## `@kerfjs/ui/wire-tab-scaffold`
+
+```ts
+interface WireTabScaffoldOptions {
+    /** Invoked with the selected tab id when a bottom-bar tab is activated. */
+    onSelect: (tabId: string) => void;
+}
+/**
+ * Wire a `TabScaffold`'s bottom tab bar: clicking a tab calls `onSelect` with its
+ * id (the app then updates its controlled `active`). Returns a disposer.
+ */
+declare function wireTabScaffold(root: Element, options: WireTabScaffoldOptions): () => void;
+
+export { type WireTabScaffoldOptions, wireTabScaffold };
+```
+
 ## `@kerfjs/ui/resizable-region`
 
 ```ts
@@ -391,6 +589,73 @@ declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPr
 export { type ResizeCommit, type WireResizableRegionsOptions, wireResizableRegions };
 ```
 
+## `@kerfjs/ui/device-class`
+
+```ts
+import { ReadonlySignal } from 'kerfjs';
+
+/**
+ * Reactive device-class detection for `@kerfjs/ui` (see `docs/23-app-layouts.md`
+ * §2). `deviceClass()` returns a `ReadonlySignal<DeviceClass>` describing the
+ * current viewport as a size bucket × orientation × viewport-segment count, so a
+ * layout can pick its presentation reactively instead of hand-wiring `matchMedia`.
+ *
+ * One shared viewport source backs every reader; the pure `classifyViewport`
+ * core is DOM-free and directly unit-tested.
+ */
+type DeviceSize = 'xs-mobile' | 'mobile' | 'tablet' | 'desktop' | 'xl-desktop';
+type DeviceOrientation = 'portrait' | 'landscape';
+/** Minimum widths (px) at which each larger bucket begins. `xs-mobile` is 0. */
+interface DeviceBreakpoints {
+    mobile: number;
+    tablet: number;
+    desktop: number;
+    'xl-desktop': number;
+}
+interface DeviceClass {
+    size: DeviceSize;
+    orientation: DeviceOrientation;
+    /** Horizontal viewport segments (foldables / dual-screen); 1 on ordinary devices. */
+    segments: number;
+    /** Vertical viewport segments; 1 on ordinary devices. */
+    verticalSegments: number;
+    /** Small phones — `xs-mobile` or `mobile`. */
+    handset: boolean;
+    /** "One pane at a time" — a handset or a portrait tablet. */
+    compact: boolean;
+    /** True when the current size is `size` or larger, e.g. `atLeast('tablet')`. */
+    atLeast(size: DeviceSize): boolean;
+}
+/** A raw viewport snapshot, before breakpoints are applied. */
+interface Viewport {
+    width: number;
+    height: number;
+    segments: number;
+    verticalSegments: number;
+}
+interface DeviceClassOptions {
+    /** Override any of the default bucket thresholds. */
+    breakpoints?: Partial<DeviceBreakpoints>;
+    /** The viewport assumed when there is no DOM (SSR). Defaults to 1024×768, one segment. */
+    ssr?: Partial<Viewport>;
+}
+declare const DEFAULT_BREAKPOINTS: DeviceBreakpoints;
+/**
+ * Classify a raw viewport into a {@link DeviceClass}. Pure and DOM-free — the
+ * single source of truth for the bucketing rules.
+ */
+declare function classifyViewport(width: number, orientation: DeviceOrientation, segments?: number, verticalSegments?: number, breakpoints?: DeviceBreakpoints): DeviceClass;
+/**
+ * A reactive signal of the current {@link DeviceClass}. Reading it inside an
+ * `effect`/`computed` re-runs when the viewport crosses a breakpoint, rotates,
+ * or changes its segment count. Without a DOM it resolves to `options.ssr`
+ * (default 1024×768, landscape, one segment).
+ */
+declare function deviceClass(options?: DeviceClassOptions): ReadonlySignal<DeviceClass>;
+
+export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type DeviceClassOptions, type DeviceOrientation, type DeviceSize, type Viewport, classifyViewport, deviceClass };
+```
+
 ## `@kerfjs/ui/segmented-control`
 
 ```ts
@@ -528,17 +793,59 @@ export { TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValu
 ## `@kerfjs/ui/wire-token-search-fields`
 
 ```ts
+import { Signal } from 'kerfjs';
+
 interface TokenSearchSubmit {
     id: string;
     editor: HTMLElement;
 }
+/**
+ * Managed collapsible behavior for the iconic TokenSearchField. Every piece is on
+ * by default; disable a specific one to own it in the app. Provide `signals` to
+ * drive app-owned `expanded` signals per field id instead of helper-created ones.
+ */
+interface TokenSearchCollapsibleOptions {
+    /** Expand the field and focus its editor when the iconic trigger is activated. Default: true. */
+    expandOnActivate?: boolean;
+    /** Collapse the field when focus leaves it while it is empty. Default: true. */
+    collapseOnEmptyBlur?: boolean;
+    /** Collapse an empty field on Escape and restore focus to its trigger. Default: true. */
+    collapseOnEscape?: boolean;
+    /** Focus the editor on expand and the trigger on Escape-collapse. Default: true. */
+    manageFocus?: boolean;
+    /** App-owned `expanded` signals keyed by field id; adopted instead of helper-created. */
+    signals?: Readonly<Record<string, Signal<boolean>>>;
+}
 interface WireTokenSearchFieldsOptions {
-    onSubmit: (submission: TokenSearchSubmit) => void;
+    onSubmit?: (submission: TokenSearchSubmit) => void;
+    /** Managed collapsible transient behavior. `true`/omitted = on with defaults; `false` = fully off. */
+    collapsible?: boolean | TokenSearchCollapsibleOptions;
 }
-/** Keep TokenSearchField wrapping, submit Enter, and preserve its caret across controlled token deletion. */
-declare function wireTokenSearchFields(root: HTMLElement, { onSubmit }: WireTokenSearchFieldsOptions): () => void;
+/**
+ * The value returned from {@link wireTokenSearchFields}: call it (or `dispose()`) to
+ * tear down. When collapsible behavior is managed, it also exposes the transient
+ * `expanded` state per field id so the app can read it in render, hand in its own
+ * signal, or drive it imperatively.
+ */
+interface TokenSearchFieldsHandle {
+    (): void;
+    dispose(): void;
+    /** The managed `expanded` signal for a field id (adopted or helper-created); undefined when unmanaged. */
+    expanded(id: string): Signal<boolean> | undefined;
+    /** Expand the field (and, when focus is managed, focus its editor). */
+    open(id: string): void;
+    /** Collapse the field (and, when focus is managed, restore focus to its trigger). */
+    close(id: string): void;
+}
+/**
+ * Wire every TokenSearchField under `root`: submit on Enter, preserve the caret across
+ * controlled token deletion, and (by default) manage the collapsible field's transient
+ * 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, collapsible }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
 
-export { type TokenSearchSubmit, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
+export { type TokenSearchCollapsibleOptions, type TokenSearchFieldsHandle, type TokenSearchSubmit, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
 ```
 
 ## `kerfjs/actions`

package/ai/skill.md

@@ -1,7 +1,7 @@
 ---
 name: kerf-ui
 description: Build interfaces with kerfjs and the @kerfjs/ui production component package. Use whenever code imports @kerfjs/ui or a task asks for Kerf UI components.
-kerf-ui-skill-version: 1.32.0
+kerf-ui-skill-version: 1.34.0
 ---
 
 # Building with @kerfjs/ui
@@ -27,9 +27,9 @@ Quick routing:
 
 | Need | Choose | Nearest alternatives / boundary |
 | --- | --- | --- |
-| Navigation row | `MenuItem` | Use an ordinary link or button when sidebar/menu anatomy and state do not apply. |
-| Navigation row with a trailing action | `MenuActionRow` | Use `MenuItem` when the trailing region is dormant; never put controls inside either component's SafeHtml slots. |
-| Page chrome or heading | `Toolbar`, `PageHeader`, or `DialogHeader` | Toolbar is persistent chrome; page and dialog headers identify different scopes. |
+| Navigation row | `MenuItem` | Use an ordinary link or button when sidebar/menu anatomy and state do not apply. Multiline leading icons stay aligned with the first text line. |
+| Navigation row with a trailing action | `MenuActionRow` | Use `MenuItem` when the trailing region is dormant; never put controls inside either component's SafeHtml slots. Multiline leading icons stay aligned with the first text line. |
+| Page, panel, or dialog heading | `Toolbar` or `PanelHeader` | Toolbar is persistent chrome; `PanelHeader` heads a panel, dialog, or page. |
 | Exclusive choice | `TabBar`, `SegmentedControl`, or `Select` | Tabs switch tabpanels; segments expose a few choices; Select handles a longer value list. |
 | Status or absent content | `StateBanner` or `EmptyState` | Web Awesome callouts suit ecosystem content; toasts are transient and never the only record of important state. |
 | Adjustable or static columns | `ResizableRegion` or CSS grid | Use the component only for a user-operable controlled separator. |
@@ -56,15 +56,18 @@ 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.
 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. 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. 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. 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. Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded while the app controls transient `expanded` state, focus transfer, and focusout timing.
+11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes. 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. 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, or a clear-button mousedown guard — the helper owns them.
 12. Demo work uses public production component subpaths and their browser-selected CSS. 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. Project its 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.
 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.
 14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. 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.
 15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Add `.kui-content` for 24px major vertical separation and `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells or duplicate item geometry in wrappers.
-16. Wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `MenuHeader` fills the available inline width and keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end 44px action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-menu-header-action-icon-size`; never shrink the target to match it. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `MenuItem.trailing` is dormant; use `MenuActionRow` when primary and trailing actions need sibling 44px native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets.
-17. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, exactly three transparent 8/1/8 content sections, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.
+16. Keep a visible collapsible pane's collapse control in its own toolbar. When hidden, move its restore control into the adjacent main toolbar on the corresponding logical edge: leading for an inline-start sidebar and trailing for an inline-end inspector. Collapse the pane completely; do not preserve an empty icon-only rail.
+16. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a `ToolbarControlGroup`. A popup menu in a toolbar is a `single` `ToolbarControlGroup` wrapping a `wa-dropdown` whose `slot="trigger"` `wa-button` is the toolbar button and whose `wa-dropdown-item`s are the menu, with the dropdown kept under `data-morph-skip-children`. `PanelHeader` composes these for you as a panel/dialog/page heading. Wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `MenuHeader` fills the available inline width and keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end 44px action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-menu-header-action-icon-size`; never shrink the target to match it. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `MenuItem.trailing` is dormant; use `MenuActionRow` when primary and trailing actions need sibling 44px native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets.
+17. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, `PanelHeader` title/summary ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.
 18. 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.
-19. Use `DialogHeader` for dialog hierarchy, not a custom heading row. Its real top `Toolbar` puts the optional 24px icon in a 34px circular background and the first title line in a borderless `ToolbarControlGroup`, centered against the automatic action `ToolbarControlGroup`; pass action children directly and add a localized `actionsLabel` when that group needs a name. Its optional `summary`/`summaryId` row stays below the title. The app owns modal behavior, focus, dismissal, command policy, and action handling.
+19. Use `PanelHeader` for a panel, dialog, or page heading, not a custom heading row. It is a plain top `Toolbar` (overriding no Toolbar styles): the leading zone holds an optional icon (a normal bordered `ToolbarControlGroup` given a brand fill with a matching border) and the title as extra-large `ToolbarText`; the app's trailing controls (typically a `ToolbarControlGroup`) go straight in the trailing zone, and the icon group is omitted when no icon is passed. Its optional `summary`/`summaryId` row stays below the title. The app owns modal behavior, focus, dismissal, command policy, and action handling.
+20. 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; prefer the five canonical remify-authored tokens. See `docs/layout.md` "Spacing scale".
+21. 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`. 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`. Complex tool with peripheral panels → `Workbench` (`@kerfjs/ui/workbench`, collapsible rails + drawer) `atLeast('desktop')`, degrading to `NavStack`/overlays below. These are declarative (the app owns the stack/selection/collapsed/active state as signals) with disposer-returning `wire…` helpers; each ships a companion CSS import and stays out of the barrel. Dialogs pick the same inner layout, then present per device class (full-screen modal on `compact`, inline on desktop). See `docs/app-layouts.md`.
 
 Common mistakes:
 
@@ -88,4 +91,9 @@ Common mistakes:
 | Let the document, pane, and list all scroll | Keep fixed chrome outside one `.kui-pane__content` scroll owner per pane |
 | Invent an `@kerfjs/ui` command-palette export | Keep the semantics application-local, reuse public layout vocabulary, and propose recurring behavior upstream |
 | Handwrite `ValueTable` row wrappers or compensate their padding or separators | Compose `ValueTableRow`; its root-scaled block padding, optional icon hook, and separator geometry are public contract |
-| Rebuild a dialog heading or pre-wrap new `DialogHeader.actions` in groups | Pass action children directly; `DialogHeader` supplies aligned identity/action groups and keeps the optional subtitle below |
+| Rebuild a panel/dialog heading row by hand | Use `PanelHeader`: a plain toolbar with an optional bordered icon group, an xl title, trailing controls you pass, and the optional subtitle below |
+| Force a `width`/`height`/`padding` on a component to size or space it | Let it size to its content and tokens; a forced box leaves a halo or a stretched oval — adjust an icon-size or spacing token, not the box |
+| Wrap a component or region in a card, border, backdrop, or outline to "contain" it | Let it sit on the surface; add a `.kui-content-item` only for a real distinction — hierarchy comes from alignment, spacing, and type first |
+| Add another container's padding on top of a content-item's own margin | Pick one owner of the inset; a pane has no padding and its `.kui-content` children own the 8/1/8 geometry — stacking them double-insets |
+| 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 |

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.3` 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.6` 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/browser/{dialog-header.js → panel-header.js}

@@ -1,5 +1,6 @@
 import '../styles/foundation.css';
 import '../styles/toolbar.css';
 import '../styles/toolbar-control-group.css';
-import '../styles/dialog-header.css';
-export * from '../dialog-header.js';
+import '../styles/toolbar-text.css';
+import '../styles/panel-header.css';
+export * from '../panel-header.js';

package/dist/{chunk-GY5WH7TO.js → chunk-24Z2XE6C.js}

@@ -1,10 +1,10 @@
 import { jsx } from 'kerfjs/jsx-runtime';
 
 // src/toolbar-text.tsx
-function ToolbarText({ text, size = "default", className = "" }) {
-  return /* @__PURE__ */ jsx("span", { class: `kui-toolbar-text ${className}`.trim(), "data-component": "toolbar-text", "data-size": size, children: text });
+function ToolbarText({ text, size = "default", className = "", id }) {
+  return /* @__PURE__ */ jsx("span", { class: `kui-toolbar-text ${className}`.trim(), "data-component": "toolbar-text", "data-size": size, id, children: text });
 }
 
 export { ToolbarText };
 
-//# sourceMappingURL=chunk-GY5WH7TO.js.map
+//# sourceMappingURL=chunk-24Z2XE6C.js.map

package/dist/chunk-24Z2XE6C.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/toolbar-text.tsx"],"names":[],"mappings":";;;AAUO,SAAS,WAAA,CAAY,EAAE,IAAA,EAAM,IAAA,GAAO,WAAW,SAAA,GAAY,EAAA,EAAI,IAAG,EAAqB;AAC5F,EAAA,uBAAO,GAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAO,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK,EAAG,gBAAA,EAAe,cAAA,EAAe,WAAA,EAAW,IAAA,EAAM,IAAS,QAAA,EAAA,IAAA,EAAK,CAAA;AAC3H","file":"chunk-24Z2XE6C.js","sourcesContent":["export type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small';\n\nexport interface ToolbarTextProps {\n  text: string;\n  size?: ToolbarTextSize;\n  className?: string;\n  /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */\n  id?: string;\n}\n\nexport function ToolbarText({ text, size = 'default', className = '', id }: ToolbarTextProps) {\n  return <span class={`kui-toolbar-text ${className}`.trim()} data-component=\"toolbar-text\" data-size={size} id={id}>{text}</span>;\n}\n"]}