@kerfjs/ui 5.0.0-beta.4 → 5.0.0-beta.7

package/docs/ux-demo.md

@@ -13,15 +13,15 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Demo paths resolve to `ui/ux-demo/main.tsx`, the matching `ui/ux-demo/recipes/*.tsx` file, or `ui/ux-demo/webawesome-demos.tsx` according to the canonical entry. First-party component entries additionally derive `ui/src/<browser-subpath>.tsx` from their canonical `delivery.browserImport`.
 - Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
 - The master/detail shell groups first-party routes by category with production `MenuHeader` and `MenuItem` components. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
-- The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with the subtitle in its own aligned row like `DialogHeader`; the current-view heading is also a toolbar. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The checkerboard belongs to the complete scrollable preview region rather than a nested card. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
-- The composer-form recipe demonstrates one coherent visible form surface with `DialogHeader` title/summary hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
+- The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with the subtitle in its own aligned row like `PanelHeader`; the current-view heading is also a toolbar. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The checkerboard belongs to the complete scrollable preview region rather than a nested card. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
+- The composer-form recipe demonstrates one coherent visible form surface with `PanelHeader` title/summary hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
 - The master-detail dialog recipe places its header directly on the dialog edge while preserving the header's internal inset, gives the selected project title the complete outer-plus-inner content gutter, lets the value table fill the available detail column between the shared outer margins, and keeps record actions on one outer gutter without an extra content-item inset. Browser geometry coverage protects those relationships at wide and narrow widths.
 - Catalog-only brand marks, preview dimensions, checkerboard tiles, and the compound display-settings control retain local geometry because they are specimen chrome or intrinsic control anatomy rather than reusable application spacing roles.
 - The menu composition route demonstrates toolbar/content/footer anatomy, 24px major gaps, 8/1/8 child geometry, the full-width `MenuHeader` count-or-badge/action split, logical-end 44px action targets with 18px visuals, and 44px row/header/toolbar targets. Its one chevron is a production 18px `DisclosureArrow` inside a controlled Tools header that actually reveals and hides content; ordinary Projects navigation has no false disclosure affordance. Browser assertions cover stable naming, expanded/content transitions, visual rotation, node identity, reduced motion, RTL alignment and containment, and wide, narrow, dark, and 200% layouts. The focused MenuHeader route separately shows the shared neutral count pill for Attachments, Notes (including zero), and Duplicates plus a non-count legacy badge, full-width logical-end actions, and no disclosure without content.
 - The `DisclosureArrow` route renders the production 18px root-scaled default without a catalog-only size override. Its two native buttons independently control the default right-to-down chevron and a recognizable right-facing replacement arrow with left-to-up custom directions; both use shortest-path rotation and their names stay stable while `aria-expanded` communicates state. Browser coverage verifies the custom clockwise path, pointer and native keyboard activation, focus, narrow and 200%-zoom stacking with contained labels, consumer sizing, and the independent `.5` Web Awesome glyph scale retained by Kerf `Select`.
 - A detail with relationships renders one grouped footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
 - Demo-only CSS supplies only the catalog shell and stages; component appearance stays in package CSS. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
-- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. The Web Awesome theme route remains the broad system view, while individual action, form, layout, navigation, feedback, media, and helper routes provide focused specimens; MenuItem and MenuHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; DialogHeader demonstrates its top-toolbar identity/action groups, optional subtitle row, and 24px icon inside a 34px circle; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone plus a scoped override; TabBar demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
+- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. The Web Awesome theme route remains the broad system view, while individual action, form, layout, navigation, feedback, media, and helper routes provide focused specimens; MenuItem and MenuHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; PanelHeader demonstrates its plain top-toolbar identity, extra-large title, optional subtitle row, and bordered brand-filled icon group; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone plus a scoped override; TabBar demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
 - Recipe ownership notes are hidden by default. A page-toolbar toggle reveals them as floating warning-toned notes with a folded corner, keeping instructional copy visually distinct and removable from the specimen flow.
 - Settings exercise light/dark, increased contrast, and reduced motion without changing component code. The theme action starts from the operating system's effective color scheme, always names the appearance it will switch to, and installs an explicit light or dark override when activated; contrast and reduced motion expose their independent preferences through `aria-pressed`.
 - The footer action log is an `aria-live` region, making interactions visible to both people and browser tests.

package/docs/workbench.md

@@ -0,0 +1,47 @@
+# Workbench
+
+`@kerfjs/ui/workbench` is the Xcode-like multi-panel workspace: a collapsible
+left rail, right rail, and bottom drawer around a central work area (any absent).
+It generalizes the instant-width / sliding-content collapse used by the catalog
+sidebar. One of the opt-in app layouts (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)); best on
+desktop-class devices.
+
+```ts
+import { Workbench } from '@kerfjs/ui/workbench';
+import '@kerfjs/ui/workbench.css';
+```
+
+## State lives in the app
+
+`Workbench` is declarative and the collapse is **pure CSS** — no wire. The app
+owns each panel's `collapsed` flag (usually a signal) and toggles it; the panel
+animates itself.
+
+```tsx
+const navCollapsed = signal(false);
+
+<Workbench
+  id="studio"
+  label="Studio"
+  main={<Editor />}
+  leftRail={{ content: <Navigator />, label: 'Navigator', collapsed: navCollapsed.value, size: 280 }}
+  rightRail={{ content: <Inspector />, label: 'Inspector', collapsed: inspectorCollapsed.value }}
+  bottomDrawer={{ content: <Console />, label: 'Console', collapsed: consoleCollapsed.value }}
+/>;
+```
+
+Each `WorkbenchPanel` takes `content`, an optional `collapsed`, an optional
+`size` (rail width or drawer height in px, overriding the CSS default —
+`--kui-workbench-rail-width` 280px, `--kui-workbench-drawer-height` 220px), and
+an optional `label`.
+
+## How the collapse animates
+
+Collapsing snaps the panel's flex track to zero in a single reflow (so the work
+area relayouts once, not per frame) while the panel's fixed-size content slides
+out via a composited `transform` — a rail slides horizontally, the drawer
+vertically — clipped by the shell's overflow. It honors `prefers-reduced-motion`
+(the slide collapses to instant). On smaller device classes, present the rails'
+contents through a `NavStack` or overlay drawers rather than shrinking the
+three-panel shell.

package/llms.txt

@@ -1,45 +1,118 @@
 # @kerfjs/ui
 
-Accessible, production-backed UI primitives for kerf applications.
-
-- [Package guide](./README.md)
-- [AI skill](./ai/skill.md)
-- [Machine-readable component catalog](./ai/component-catalog.json)
-- [Public API signature snapshot](./ai/public-api-signatures-v1.md)
-- [Web Awesome JSX signature snapshot](./ai/webawesome-jsx-signatures-v1.md)
-- [Need-first component selection matrix](./docs/component-selection.md)
-- [Production composition recipes](./docs/recipes.md)
-- [Component contract](./docs/component-contract.md)
-- [Web Awesome theme contract](./docs/webawesome-theme.md)
-- [Accessibility and keyboard contracts](./docs/accessibility.md)
-- [Design philosophy](./docs/design-philosophy.md)
-- [Apple HIG translation](./docs/apple-hig.md)
-- [UX catalog](./docs/ux-demo.md)
-
-The UX catalog is a category-grouped master/detail review surface with a focused route for every public visual component plus composition demos. Its collapsible ecosystem section also lists all 70 free Web Awesome 3.12 components, each with a focused themed route. Related entries use one grouped `Uses` / `Used by` selector across both sets; the shell, display preferences, and selected component share one semantic theme.
-
-Choose from the interface need: search the catalog, reuse a semantic match, compose existing primitives, add a thin application adapter for product concerns, and use custom markup only for a genuinely different contract. The selection matrix covers every public visual/helper export and the supported-but-not-preferred Web Awesome overlaps, including required wiring, application ownership, import subpaths, alternatives, and recipe links.
-
-There is no `@kerfjs/ui` command-palette runtime export or production recipe. The typed application-local example at `docs/examples/command-palette-adapter.tsx` demonstrates how a missing concept can reuse public layout vocabulary without inventing a package API. Ranking, history, permissions, availability, focus policy, actions, and copy stay in the app; propose recurring behavior upstream.
-
-AI tools that need exhaustive retrieval should load `@kerfjs/ui/ai/component-catalog.json`. It is the canonical checked-in source for stable ids, exports, purpose, selection guidance, relationships, delivery and side effects, wiring, application ownership, variants, accessibility, public CSS hooks, catalog routes, and current documentation/recipe links. Its adjacent JSON Schema describes the format.
-
-Prefer an equivalent component prop or `--kui-*` token for customization. When composition-specific layout needs CSS, the catalog's `publicClasses` arrays are the exact supported anatomy boundary: selectors may join documented public classes, but must not reach into a component by tag, id, attribute alone, or an unlisted class.
-
-Before emitting code, load `@kerfjs/ui/ai/public-api-signatures-v1.md` for the exact declaration signatures used by the authoring corpus. It records accepted import paths, prop names, callback shapes, and disposer return types from emitted declarations rather than prose examples.
-
-Public components: `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `SegmentedControl`, `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`, `wireTokenSearchFields`, `MenuItem`, `MenuActionRow`, `MenuHeader`, `ResizableRegion`, `wireResizableRegions`, `AppTab`, `TabBar`, `wireTabBars`, `reorderTabs`, `PageHeader`, `LoadingSpinner`, `Select`, `StateBanner`, `EmptyState`, `DialogHeader`, `ValueTable`, and `ValueTableRow`. `MenuItem`, `MenuActionRow`, `MenuHeader`, and `AppTab` accept typed, runtime-filtered application `data-*` metadata through `rootAttributes`; MenuActionRow `trailingActionAttributes` and MenuHeader `triggerAttributes` additionally support native popover target/action and `aria-controls`/`aria-haspopup`, while component-owned action, identity, selection, disclosure, naming, disabled, icon, and role semantics stay protected. `MenuHeader` uses the mutually exclusive `count` plus required localized `countLabel` pair for non-negative safe-integer section quantities, including zero; it renders the shared neutral pill and joins the spoken phrase to the owning heading or disclosure button. Never concatenate a count into `label` or put numeric content in the legacy non-count `badge` SafeHtml slot. In real toggle mode, omitting `actionIcon` supplies one production 18px `DisclosureArrow` driven by `expanded`; a custom icon replaces it, and the app must reveal matching content. Ordinary navigation must not borrow a disclosure chevron. `AppTab.closeIcon` and `ResizableRegion.handleIcon` replace decorative dormant glyphs without taking control ownership. `MenuItem.trailing` is dormant; use `MenuActionRow` for sibling primary/trailing native buttons, keeping its `label`, `icon`, and `trailingActionIcon` SafeHtml dormant too. `ValueTableRow` owns semantic `dt`/`dd` markup, 8px of root-scaled top and bottom padding, and an optional 24px leading icon; its separator begins 8px from the left without an icon or 40px with one and ends 8px from the right. `DisclosureArrow` is a decorative, controlled open/closed indicator with configurable directions, shortest-path rotation (counterclockwise for a 180-degree closed-to-open tie), replaceable right-oriented icon content, an 18px root-scaled default, and a scoped `--kui-disclosure-arrow-size` override; the owning control retains interaction and expanded-state semantics. `SegmentedControl` is controlled and supports toolbar, rounded-rectangle, and pill presentations with native pressed buttons in sequential Tab order. `Select` preserves icon-bearing option slots across Kerf rerenders, keys custom selected content by the controlled value, and separately keeps its intrinsic Web Awesome expand glyph at `--kui-disclosure-icon-scale: .5`. `TokenSearchField` controls tokens while keeping editable text DOM-owned between token changes, combining free text with ordered atomic filter chips while leaving query parsing and results to the application; its leading icon, first text line, clear action, and trailing slot stay aligned to one fixed row when text wraps. Its optional `collapsible` mode animates between an empty iconic action and the complete field, works standalone or inside `ToolbarControlGroup`, and keeps populated searches expanded while the app controls transient focus/open state. Call `wireTokenSearchFields` once to make Enter submit without inserting a contenteditable line break and to preserve focus plus the text-relative caret across controlled keyboard chip deletion; visual wrapping remains available. Semantic state palettes are opinionated, Web Awesome-compatible, and overridable globally, by tone, or per instance.
-
-`DialogHeader` composes a real top `Toolbar`: its borderless identity group keeps the optional 24px icon in a 34px circular background and the first title line centered against an automatic action `ToolbarControlGroup`. Pass action children directly and add a localized `actionsLabel` when that group needs a name. The optional `summary`/`summaryId` row remains below the title; the application owns modal focus, dismissal, commands, and action handling.
-
-Pane and navigation composition: import `@kerfjs/ui/layout.css` and use an unpadded `.kui-pane` with optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Add `.kui-content` for 24px major vertical gaps. Use `.kui-content-item` for children that own 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px rounded corners; the pill modifier uses 22px. This vocabulary applies equally to sidebars, main areas, inspectors, and dialogs. A visible collapsible pane owns collapse in its own toolbar. When hidden, move restore into the adjacent main toolbar on the same logical edge—leading for an inline-start pane, trailing for inline-end—and remove the pane instead of leaving an icon-only rail.
-
-Composer form recipe: keep the form as one visible surface, use `DialogHeader` title/summary ids to label and describe it, and align field and action control edges on the shared 8px inline gutter without a second content-item padding inset. Retain 24px major rhythm. A conditional `StateBanner` is the only nested semantic surface. Do not make every form section another card. When resetting controlled upgraded Web Awesome fields, synchronize their live `value` properties as well as the rendered value attributes.
-
-Toolbar and split-item geometry: wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. Groups stay 44px outside (`calc(2px + remify(42px))`) even when their border and background are transparent, with 8px between groups and inside items. `MenuHeader` fills the available inline width and separates its dormant title/count-or-badge cluster from its optional logical-end 44px action; the visible action glyph defaults to 18px through `--kui-menu-header-action-icon-size`, while disclosure mode makes the title cluster the action. `MenuActionRow` keeps primary and trailing 44px actions as sibling native buttons inside a noninteractive row. Multiline `MenuItem` and `MenuActionRow` leading icons stay centered on the first text line while later lines extend below. Do not pad pane shells or add competing wrapper insets. See `docs/layout.md`.
-
-Import visual components from explicit JavaScript subpaths. A CSS-aware browser bundler selects generated wrappers that bring in the foundation, the component CSS, and styles for reachable UI subcomponents; unrelated CSS stays out. The root barrel and `@kerfjs/ui/unstyled` are CSS-free; use `styles.css` with the root barrel only when the complete layer is intentional. Manual CSS exports remain available for custom pipelines, and application overrides follow package styles in the cascade. Direct `wa-*` JSX uses `import type {} from '@kerfjs/ui/webawesome'`, the side-effect-free declaration boundary synchronized with all 70 catalog-supported elements. `@kerfjs/ui/webawesome.css` is the optional CSS-only theme; it includes Web Awesome's base stylesheet, registers no elements, and remains overridable through public `--wa-*` tokens. CSS, its generated browser wrappers, and `@kerfjs/ui/select/register` are the declared side effects. `kerfjs` is an external peer. The Web Awesome peer is optional and needed for its components. `wireTabBars` includes proximity-based horizontal edge autoscroll during same-bar drag reordering.
-
-The Web Awesome theme renders Tooltip and Popover without pointer arrows by default. Restore them only when the anchor relationship needs the pointer, using `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or one popover's public `--arrow-size`; `without-arrow` remains available for explicit local intent.
-
-Web Awesome catalog coverage means themed and inspectable, not preferred. 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. ResizableRegion carries Hot Sheet 2's 1px separator plus hover/focus grip. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame.
+> Accessible, production-backed UI primitives for [kerf](https://github.com/brianwestphal/kerf)
+> applications. Components are plain functions returning `SafeHtml`; the app owns
+> state and wires stable `data-action` hooks once. This file orients an LLM to
+> generate correct, good-looking kerf UI — it is not a catalog to browse.
+
+```bash
+npm install kerfjs @kerfjs/ui   # kerfjs is a peer; Web Awesome is an optional peer
+```
+
+Import each component from its own subpath (`@kerfjs/ui/menu-item`, `@kerfjs/ui/toolbar`,
+…); the browser build pulls that component's reachable CSS automatically, so do not
+maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
+
+## How to build a screen (retrieval order)
+
+1. **Pick the component from the interface need**, not by appearance — read
+   [component-selection.md](./docs/component-selection.md) (the problem→component
+   matrix, with imports, wiring, ownership, and alternatives).
+2. **Get exact signatures before emitting code** — read
+   [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) (real prop names,
+   callback shapes, disposer return types).
+3. **For exhaustive, structured facts** (ids, exports, variants, `publicClasses`,
+   relationships, side effects) load the
+   [Machine-readable component catalog](./ai/component-catalog.json) — the
+   canonical checked-in source; its schema is alongside it.
+4. **Apply the rules below and in** [skill.md](./ai/skill.md).
+
+## Core rules (do the right thing)
+
+- **Reach for the primitive, not for CSS.** The package is built to look right
+  *unstyled*. Before adding `padding`, `margin`, `width`, `height`, `border`,
+  `background`, a wrapper card, or a decoration, check whether the component, the
+  pane, or the content-item already owns it — it almost always does. Prefer a
+  component prop or a `--kui-*` token; write CSS only for genuinely new structure,
+  and then only join a component's documented `publicClasses` (never reach in by
+  tag/id/attribute or an unlisted class).
+- **Never double-inset.** A `.kui-pane` has no padding; its `.kui-content` children
+  own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
+  container padding on top of a content-item's own margin — pick one owner. Use
+  `.kui-content` for 24px major vertical rhythm.
+- **Trust the defaults.** Render a control at its natural size and color (a
+  `LucideIcon` is 24px); if it looks wrong, fix the surrounding layout, not the
+  control. Never force a component's width/height to size it — that leaves a halo
+  or a stretched oval.
+- **Toolbars hold only `ToolbarText` and `ToolbarControlGroup`.** Never put a bare
+  button, input, link, or loose markup in a `leading`/`center`/`trailing` zone.
+  Wrap every control — `SegmentedControl`, `Select`, a collapsible
+  `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. A
+  toolbar popup menu is a `single` `ToolbarControlGroup` around a `wa-dropdown`
+  (its `slot="trigger"` `wa-button` is the toolbar button, kept under
+  `data-morph-skip-children`).
+- **`PanelHeader` is *the* panel/dialog/page heading.** A plain toolbar with an
+  optional bordered icon group, an extra-large `ToolbarText` title, the trailing
+  controls you pass, and an optional subtitle below — do not hand-build a heading
+  row or restyle a toolbar into one.
+- **Space by the five-step scale, by relationship not by eye.** `0`
+  `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
+  group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing
+  regions). 12px/32px are off-scale exceptions.
+- **Panes share one child-owned geometry.** Sidebars, main areas, inspectors, and
+  dialogs all use an unpadded `.kui-pane` (optional `.kui-pane__toolbar`, one
+  scrolling `.kui-pane__content`, optional `.kui-pane__footer`). A visible pane owns
+  its collapse control; a hidden pane's restore moves to the adjacent main
+  toolbar's matching edge — no icon-only rail. Keep one scroll owner per region.
+- **State and behavior live in the app.** Components take semantic `data-action`
+  strings and controlled values; wire them once with `delegate()`/`delegateActions()`
+  or the disposer-returning `wire…` helpers, and own domain copy, transport, and
+  policy in a thin adapter. Every element must earn its place — cut chrome, labels,
+  and readouts that do not help a person decide or act.
+- **App state is domain/persisted; helpers own only ephemeral mechanics.** Keep
+  navigation stacks, tab selection and order, pane sizes, and `collapsed`/`expanded`
+  disclosure flags in the app — they are data or persisted layout, and the app reads
+  them to render. The `wire…` helpers own the *ephemeral* parts: `wireNavStack` the
+  push/pop animation, `wireTabBars` the overflow autoscroll and drag preview,
+  `wireResizableRegions` the live drag preview; they report committed changes via
+  callbacks. The one richer case is `wireTokenSearchFields`, which manages the
+  collapsible field's expand/collapse/focus by default (on, per-behavior opt-out) and
+  exposes the `expanded` signal on its handle — bind it in render or hand in your own
+  via `collapsible.signals`. Do not hand-roll open/collapse/focus that helper
+  provides; but do keep a plain disclosure toggle (a one-line boolean the app already
+  renders from) in the app.
+- **Placeholder loading state, don't rebuild it.** For a value or component that is
+  still loading, set `placeholder` on the component (`Select`, `MenuHeader`,
+  `MenuItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`,
+  `AppTab`, `ToolbarText`, `MenuActionRow`): it renders its real chrome with value
+  slots as subtle **unanimated** skeleton blocks and interactivity disabled, so a
+  parent composes a faithful loading view (e.g. an inspector) without hand-rebuilding
+  markup. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
+  (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
+  `LoadingSpinner` for known busy activity instead.
+
+## Public exports
+
+`LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarText`,
+`PanelHeader`, `MenuItem`, `MenuActionRow`, `MenuHeader`, `SegmentedControl`,
+`Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
+`wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
+`ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
+`LoadingSpinner`, `Skeleton`, `ValueTable`, `ValueTableRow`. Whole-screen layouts (opt-in,
+tree-shakeable, declarative with `wire…` helpers, each with a companion CSS import):
+`NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
+`@kerfjs/ui/device-class`. `@kerfjs/ui/webawesome` is a type-only boundary for
+`wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the declared side effects.
+
+## Reference
+
+- [skill.md](./ai/skill.md): the full rule set + a common-mistakes table (the shipped AI skill).
+- [design-philosophy.md](./docs/design-philosophy.md): why kerf UI is shaped this way — the decision principles behind the rules above.
+- [layout.md](./docs/layout.md): the pane/content-item geometry, public roles/tokens, and the spacing scale.
+- [component-contract.md](./docs/component-contract.md): what a component owns vs. what the app owns.
+- [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
+- [recipes.md](./docs/recipes.md): production compositions (app shell, master-detail dialog, composer form, …) as copyable references.
+- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
+- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists).
+- [component-catalog.json](./ai/component-catalog.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts and exact signatures.
+- [README.md](./README.md): package overview and the component subpath table.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.4",
+  "version": "5.0.0-beta.7",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -88,6 +88,10 @@
       "types": "./dist/wire-resizable-regions.d.ts",
       "import": "./dist/wire-resizable-regions.js"
     },
+    "./device-class": {
+      "types": "./dist/device-class.d.ts",
+      "import": "./dist/device-class.js"
+    },
     "./app-tab": {
       "types": "./dist/app-tab.d.ts",
       "browser": "./dist/browser/app-tab.js",
@@ -102,10 +106,29 @@
       "types": "./dist/wire-tab-bars.d.ts",
       "import": "./dist/wire-tab-bars.js"
     },
-    "./page-header": {
-      "types": "./dist/page-header.d.ts",
-      "browser": "./dist/browser/page-header.js",
-      "import": "./dist/page-header.js"
+    "./nav-stack": {
+      "types": "./dist/nav-stack.d.ts",
+      "import": "./dist/nav-stack.js"
+    },
+    "./wire-nav-stack": {
+      "types": "./dist/wire-nav-stack.d.ts",
+      "import": "./dist/wire-nav-stack.js"
+    },
+    "./split-view": {
+      "types": "./dist/split-view.d.ts",
+      "import": "./dist/split-view.js"
+    },
+    "./workbench": {
+      "types": "./dist/workbench.d.ts",
+      "import": "./dist/workbench.js"
+    },
+    "./tab-scaffold": {
+      "types": "./dist/tab-scaffold.d.ts",
+      "import": "./dist/tab-scaffold.js"
+    },
+    "./wire-tab-scaffold": {
+      "types": "./dist/wire-tab-scaffold.d.ts",
+      "import": "./dist/wire-tab-scaffold.js"
     },
     "./loading-spinner": {
       "types": "./dist/loading-spinner.d.ts",
@@ -117,6 +140,11 @@
       "browser": "./dist/browser/select.js",
       "import": "./dist/select.js"
     },
+    "./skeleton": {
+      "types": "./dist/skeleton.d.ts",
+      "browser": "./dist/browser/skeleton.js",
+      "import": "./dist/skeleton.js"
+    },
     "./segmented-control": {
       "types": "./dist/segmented-control.d.ts",
       "browser": "./dist/browser/segmented-control.js",
@@ -149,10 +177,10 @@
       "browser": "./dist/browser/empty-state.js",
       "import": "./dist/empty-state.js"
     },
-    "./dialog-header": {
-      "types": "./dist/dialog-header.d.ts",
-      "browser": "./dist/browser/dialog-header.js",
-      "import": "./dist/dialog-header.js"
+    "./panel-header": {
+      "types": "./dist/panel-header.d.ts",
+      "browser": "./dist/browser/panel-header.js",
+      "import": "./dist/panel-header.js"
     },
     "./value-table": {
       "types": "./dist/value-table.d.ts",
@@ -178,14 +206,18 @@
     "./resizable-region.css": "./dist/styles/resizable-region.css",
     "./app-tab.css": "./dist/styles/app-tab.css",
     "./tab-bar.css": "./dist/styles/tab-bar.css",
-    "./page-header.css": "./dist/styles/page-header.css",
+    "./nav-stack.css": "./dist/styles/nav-stack.css",
+    "./split-view.css": "./dist/styles/split-view.css",
+    "./workbench.css": "./dist/styles/workbench.css",
+    "./tab-scaffold.css": "./dist/styles/tab-scaffold.css",
     "./loading-spinner.css": "./dist/styles/loading-spinner.css",
     "./select.css": "./dist/styles/select.css",
+    "./skeleton.css": "./dist/styles/skeleton.css",
     "./segmented-control.css": "./dist/styles/segmented-control.css",
     "./token-search-field.css": "./dist/styles/token-search-field.css",
     "./state-banner.css": "./dist/styles/state-banner.css",
     "./empty-state.css": "./dist/styles/empty-state.css",
-    "./dialog-header.css": "./dist/styles/dialog-header.css",
+    "./panel-header.css": "./dist/styles/panel-header.css",
     "./value-table.css": "./dist/styles/value-table.css",
     "./ai/*": "./ai/*",
     "./docs/*": "./docs/*"

package/ux-demo/recipes/app-shell.tsx

@@ -4,7 +4,7 @@ import './recipes.css';
 import { LucideIcon } from '@kerfjs/ui/lucide-icon';
 import { MenuHeader } from '@kerfjs/ui/menu-header';
 import { MenuItem } from '@kerfjs/ui/menu-item';
-import { PageHeader } from '@kerfjs/ui/page-header';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
 import { ResizableRegion } from '@kerfjs/ui/resizable-region';
 import { Toolbar } from '@kerfjs/ui/toolbar';
 import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
@@ -24,8 +24,8 @@ export const createRecipe: RecipeFactory = (announce) => {
     <Toolbar label="Atlas workspace" leading={<ToolbarControlGroup appearance="borderless" single><ToolbarText text="Atlas" /></ToolbarControlGroup>} trailing={<div class="recipe-shell__toolbar-actions"><ToolbarControlGroup className="recipe-shell__responsive-controls" appearance="borderless" label="Workspace panes"><button type="button" aria-label="Show navigation" aria-controls="recipe-shell-navigation" aria-pressed={String(responsivePane.value === 'navigation')} data-action="recipe-action" data-recipe-command="show-navigation"><LucideIcon icon={Folder} name="folder" /></button><button type="button" aria-label="Show content" aria-controls="recipe-shell-content" aria-pressed={String(responsivePane.value === 'content')} data-action="recipe-action" data-recipe-command="show-content"><LucideIcon icon={Inbox} name="inbox" /></button><button type="button" aria-label="Show inspector" aria-controls="recipe-shell-inspector" aria-pressed={String(responsivePane.value === 'inspector')} data-action="recipe-action" data-recipe-command="show-inspector"><LucideIcon icon={Settings} name="settings" /></button></ToolbarControlGroup><ToolbarControlGroup appearance="borderless" label="Workspace controls"><button type="button" aria-label="Notifications" data-action="recipe-action" data-recipe-command="notify"><LucideIcon icon={Bell} name="bell" /></button><button type="button" aria-label="Settings" data-action="recipe-action" data-recipe-command="settings"><LucideIcon icon={Settings} name="settings" /></button></ToolbarControlGroup></div>} />
     <div class="recipe-shell__body">
       <div id="recipe-shell-navigation" class="recipe-shell__nav-region"><ResizableRegion id="recipe-navigation" label="Navigation" size={navigationSize.value} min={180} max={320}><aside class="recipe-shell__nav kui-pane"><MenuHeader label="Workspace" /><nav class="recipe-shell__nav-list kui-pane__content kui-content" aria-label="Workspace"><section><MenuItem action="recipe-action" itemId="inbox" label="Inbox" icon={<LucideIcon icon={Inbox} name="inbox" />} selected={selected.value === 'inbox'} /><MenuItem action="recipe-action" itemId="projects" label="Projects with a deliberately wrapping title" icon={<LucideIcon icon={Folder} name="folder" />} selected={selected.value === 'projects'} multiline /></section></nav></aside></ResizableRegion></div>
-      <main id="recipe-shell-content" class="recipe-shell__main kui-pane"><PageHeader title={selected.value === 'inbox' ? 'Inbox triage' : 'Active projects'} action={<button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="new">New task</button>} /><div class="recipe-shell__main-body kui-pane__content kui-content"><p class="kui-recipe__ownership kui-content-item">Recipe owns pane geometry and one scroll owner per pane. The app owns routing, data, pane visibility, sizes, and persistence.</p><div class="recipe-shell__cards">{['Release accessibility audit', 'Prepare tablet navigation', 'Review stale-data states', 'Confirm package boundaries'].map((title) => <article class="recipe-shell__card kui-content-item"><strong>{title}</strong><p class="kui-recipe__muted">Assigned to the interface systems team · due this week</p></article>)}</div></div></main>
-      <div id="recipe-shell-inspector" class="recipe-shell__inspector-region"><ResizableRegion id="recipe-inspector" label="Inspector" size={inspectorSize.value} min={200} max={360} edge="start"><aside class="recipe-shell__inspector kui-pane"><PageHeader title="Inspector" /><div class="recipe-shell__inspector-body kui-pane__content kui-content"><ValueTable label="Selected task"><ValueTableRow label="Status" value="In review" /><ValueTableRow label="Owner" value="Mara Chen" /><ValueTableRow label="Priority" value="High" /></ValueTable></div></aside></ResizableRegion></div>
+      <main id="recipe-shell-content" class="recipe-shell__main kui-pane"><PanelHeader title={selected.value === 'inbox' ? 'Inbox triage' : 'Active projects'} titleId="recipe-shell-main-title" actions={<button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="new">New task</button>} /><div class="recipe-shell__main-body kui-pane__content kui-content"><p class="kui-recipe__ownership kui-content-item">Recipe owns pane geometry and one scroll owner per pane. The app owns routing, data, pane visibility, sizes, and persistence.</p><div class="recipe-shell__cards">{['Release accessibility audit', 'Prepare tablet navigation', 'Review stale-data states', 'Confirm package boundaries'].map((title) => <article class="recipe-shell__card kui-content-item"><strong>{title}</strong><p class="kui-recipe__muted">Assigned to the interface systems team · due this week</p></article>)}</div></div></main>
+      <div id="recipe-shell-inspector" class="recipe-shell__inspector-region"><ResizableRegion id="recipe-inspector" label="Inspector" size={inspectorSize.value} min={200} max={360} edge="start"><aside class="recipe-shell__inspector kui-pane"><PanelHeader title="Inspector" titleId="recipe-shell-inspector-title" /><div class="recipe-shell__inspector-body kui-pane__content kui-content"><ValueTable label="Selected task"><ValueTableRow label="Status" value="In review" /><ValueTableRow label="Owner" value="Mara Chen" /><ValueTableRow label="Priority" value="High" /></ValueTable></div></aside></ResizableRegion></div>
     </div>
   </section>;
   return { render, action(command, element) { const pane = command.match(/^show-(navigation|content|inspector)$/)?.[1] as typeof responsivePane.value | undefined; if (pane) responsivePane.value = pane; const id = element.dataset.itemId; if (id) selected.value = id; announce(id ? `Opened ${id}` : pane ? `Showing ${pane}` : command === 'new' ? 'New task requested' : `${command} requested`); }, resize(id, size) { if (id === 'recipe-navigation') navigationSize.value = size; if (id === 'recipe-inspector') inspectorSize.value = size; announce(`${id} resized to ${size}px`); } };

package/ux-demo/recipes/composer-form.tsx

@@ -6,7 +6,7 @@ import '@awesome.me/webawesome/dist/components/input/input.js';
 import '@awesome.me/webawesome/dist/components/textarea/textarea.js';
 import './recipes.css';
 
-import { DialogHeader } from '@kerfjs/ui/dialog-header';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
 import { Select } from '@kerfjs/ui/select';
 import { StateBanner } from '@kerfjs/ui/state-banner';
 import { signal } from 'kerfjs';
@@ -30,7 +30,7 @@ export const createRecipe: RecipeFactory = (announce) => {
   const audience = signal('team');
   const status = signal<'idle' | 'error' | 'saved'>('idle');
   const render = () => <form class="kui-recipe recipe-form kui-recipe__surface kui-content" data-recipe="recipe-composer-form" aria-labelledby="recipe-composer-title" aria-describedby="recipe-composer-summary" noValidate>
-    <DialogHeader title="Publish workspace update" titleId="recipe-composer-title" summary="Share a concise, actionable update with collaborators." summaryId="recipe-composer-summary" />
+    <PanelHeader title="Publish workspace update" titleId="recipe-composer-title" summary="Share a concise, actionable update with collaborators." summaryId="recipe-composer-summary" />
     {status.value === 'error' && <StateBanner title="Add a title before publishing" detail="The update body and audience are preserved." tone="danger" urgency="alert" />}
     {status.value === 'saved' && <StateBanner title="Update published" detail="The team audience can now read it." tone="success" />}
     <div class="recipe-form__section recipe-form__fields">

package/ux-demo/recipes/list-workspace-states.tsx

@@ -3,7 +3,7 @@ import './recipes.css';
 
 import { EmptyState } from '@kerfjs/ui/empty-state';
 import { LoadingSpinner } from '@kerfjs/ui/loading-spinner';
-import { PageHeader } from '@kerfjs/ui/page-header';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
 import { StateBanner } from '@kerfjs/ui/state-banner';
 import { signal } from 'kerfjs';
 
@@ -21,6 +21,6 @@ export const createRecipe: RecipeFactory = (announce) => {
     if (state.value === 'error') return <StateBanner title="Release tasks could not be refreshed" detail="Existing filters are preserved. Try again when the connection recovers." tone="danger" urgency="alert" action={<button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="retry">Retry</button>} />;
     return <>{state.value === 'stale' && <StateBanner title="Showing saved results" detail="Refreshing in the background." tone="warning" action={<span class="kui-inline-metadata"><LoadingSpinner label="Refreshing release tasks" /><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="finish">Finish refresh</button></span>} />}{populated()}</>;
   };
-  const render = () => <section class="kui-recipe recipe-list kui-recipe__surface kui-pane" data-recipe="recipe-list-workspace-states" data-list-state={state.value}><PageHeader title="Release tasks" action={<div class="kui-control-cluster"><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="empty">Clear</button><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="fail">Simulate failure</button><button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="refresh">Refresh</button></div>} /><div class="recipe-list__body kui-pane__content kui-content">{renderBody()}<p class="kui-recipe__ownership kui-content-item">The recipe owns feedback placement and stable content. The app owns fetching, cache age, retry policy, and domain rows.</p></div></section>;
+  const render = () => <section class="kui-recipe recipe-list kui-recipe__surface kui-pane" data-recipe="recipe-list-workspace-states" data-list-state={state.value}><PanelHeader title="Release tasks" titleId="recipe-list-title" actions={<div class="kui-control-cluster"><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="empty">Clear</button><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="fail">Simulate failure</button><button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="refresh">Refresh</button></div>} /><div class="recipe-list__body kui-pane__content kui-content">{renderBody()}<p class="kui-recipe__ownership kui-content-item">The recipe owns feedback placement and stable content. The app owns fetching, cache age, retry policy, and domain rows.</p></div></section>;
   return { render, action(command) { const next: Record<string, ListState> = { load: 'populated', empty: 'empty', create: 'populated', fail: 'error', retry: 'populated', refresh: 'stale', finish: 'populated' }; if (command in next) state.value = next[command]!; announce(`List state: ${state.value}`); } };
 };

package/ux-demo/recipes/loaders.ts

@@ -8,6 +8,7 @@ export const recipeIds = [
   'recipe-composer-form',
   'recipe-list-workspace-states',
   'recipe-compact-toolbar',
+  'recipe-navigation-stack',
 ] as const;
 
 export type RecipeId = typeof recipeIds[number];
@@ -20,6 +21,7 @@ export const recipeLoaders: Record<RecipeId, () => Promise<{ createRecipe: Recip
   'recipe-composer-form': () => import('./composer-form.js'),
   'recipe-list-workspace-states': () => import('./list-workspace-states.js'),
   'recipe-compact-toolbar': () => import('./compact-toolbar.js'),
+  'recipe-navigation-stack': () => import('./navigation-stack.js'),
 };
 
 export function isRecipeId(value: string): value is RecipeId {

package/ux-demo/recipes/master-detail-dialog.tsx

@@ -4,10 +4,10 @@ import '@awesome.me/webawesome/dist/components/button/button.js';
 import '@awesome.me/webawesome/dist/components/dialog/dialog.js';
 import './recipes.css';
 
-import { DialogHeader } from '@kerfjs/ui/dialog-header';
 import { LucideIcon } from '@kerfjs/ui/lucide-icon';
 import { MenuHeader } from '@kerfjs/ui/menu-header';
 import { MenuItem } from '@kerfjs/ui/menu-item';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
 import { ValueTable, ValueTableRow } from '@kerfjs/ui/value-table';
 import { signal } from 'kerfjs';
 import { FileText } from 'lucide';
@@ -27,7 +27,7 @@ interface RecipeDialogElement extends HTMLElement {
 export const createRecipe: RecipeFactory = (announce) => {
   const selected = signal<keyof typeof records>('alpha');
   const open = { value: false };
-  const render = () => <section class="kui-recipe kui-content" data-recipe="recipe-master-detail-dialog"><button class="kui-recipe__button kui-content-item" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="open">Open project details</button><p class="kui-recipe__ownership kui-content-item">Web Awesome owns modal focus and dismissal. The recipe owns header/body/master-detail anatomy; the app owns open state, selection, and policy.</p><wa-dialog class="recipe-dialog" label="Project details" without-header open={open.value}><div class="recipe-dialog__pane kui-pane"><DialogHeader title="Project details" titleId="recipe-dialog-title" summary="Compare delivery state without leaving the workspace." summaryId="recipe-dialog-summary" icon={<LucideIcon icon={FileText} name="file-text" />} actions={<wa-button appearance="plain" data-action="recipe-action" data-recipe-command="close">Close</wa-button>} actionsLabel="Project detail actions" /><div class="recipe-master-detail kui-pane__content"><nav class="recipe-master-detail__master kui-pane" aria-label="Projects"><MenuHeader label="Recent projects" /><div class="kui-pane__content kui-content"><section>{Object.entries(records).map(([id, record]) => <MenuItem action="recipe-action" itemId={id} label={record.name} selected={selected.value === id} multiline />)}</section></div></nav><section class="recipe-master-detail__detail kui-content" aria-live="polite"><h3 class="recipe-master-detail__title kui-recipe__pane-title kui-content-item">{records[selected.value].name}</h3><ValueTable label="Project details"><ValueTableRow label="Owner" value={records[selected.value].owner} /><ValueTableRow label="Status" value={records[selected.value].state} /><ValueTableRow label="Updated" value={records[selected.value].updated} /></ValueTable><div class="recipe-master-detail__actions kui-control-cluster"><wa-button appearance="outlined" data-action="recipe-action" data-recipe-command="archive">Archive</wa-button><wa-button variant="brand" appearance="accent" data-action="recipe-action" data-recipe-command="open-record">Open project</wa-button></div></section></div></div></wa-dialog></section>;
+  const render = () => <section class="kui-recipe kui-content" data-recipe="recipe-master-detail-dialog"><button class="kui-recipe__button kui-content-item" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="open">Open project details</button><p class="kui-recipe__ownership kui-content-item">Web Awesome owns modal focus and dismissal. The recipe owns header/body/master-detail anatomy; the app owns open state, selection, and policy.</p><wa-dialog class="recipe-dialog" label="Project details" without-header open={open.value}><div class="recipe-dialog__pane kui-pane"><PanelHeader title="Project details" titleId="recipe-dialog-title" summary="Compare delivery state without leaving the workspace." summaryId="recipe-dialog-summary" icon={<LucideIcon icon={FileText} name="file-text" />} actions={<wa-button appearance="plain" data-action="recipe-action" data-recipe-command="close">Close</wa-button>} /><div class="recipe-master-detail kui-pane__content"><nav class="recipe-master-detail__master kui-pane" aria-label="Projects"><MenuHeader label="Recent projects" /><div class="kui-pane__content kui-content"><section>{Object.entries(records).map(([id, record]) => <MenuItem action="recipe-action" itemId={id} label={record.name} selected={selected.value === id} multiline />)}</section></div></nav><section class="recipe-master-detail__detail kui-content" aria-live="polite"><h3 class="recipe-master-detail__title kui-recipe__pane-title kui-content-item">{records[selected.value].name}</h3><ValueTable label="Project details"><ValueTableRow label="Owner" value={records[selected.value].owner} /><ValueTableRow label="Status" value={records[selected.value].state} /><ValueTableRow label="Updated" value={records[selected.value].updated} /></ValueTable><div class="recipe-master-detail__actions kui-control-cluster"><wa-button appearance="outlined" data-action="recipe-action" data-recipe-command="archive">Archive</wa-button><wa-button variant="brand" appearance="accent" data-action="recipe-action" data-recipe-command="open-record">Open project</wa-button></div></section></div></div></wa-dialog></section>;
   return {
     render,
     action(command, element) {

package/ux-demo/recipes/mount-recipe.ts

@@ -1,3 +1,4 @@
+import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
 import { wireResizableRegions } from '@kerfjs/ui/wire-resizable-regions';
 import { delegate, mount } from 'kerfjs';
 import { delegateActions } from 'kerfjs/actions';
@@ -23,11 +24,13 @@ export function mountRecipe(root: HTMLElement, controller: RecipeController): ()
   const stopResize = wireResizableRegions(root, {
     onCommit: ({ id, size }) => controller.resize?.(id, size),
   });
+  const stopNav = wireNavStack(root, { onBack: () => controller.action('nav-back', root) });
 
   let disposed = false;
   return () => {
     if (disposed) return;
     disposed = true;
+    stopNav();
     stopResize();
     stopDialogs();
     stopInputs();

package/ux-demo/recipes/navigation-stack.tsx

@@ -0,0 +1,76 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/nav-stack.css';
+import '@kerfjs/ui/toolbar-text.css';
+import './recipes.css';
+
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { MenuHeader } from '@kerfjs/ui/menu-header';
+import { MenuItem } from '@kerfjs/ui/menu-item';
+import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
+import { signal } from 'kerfjs';
+import { ChevronRight, FileText, Folder } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+interface LibraryItem {
+  id: string;
+  label: string;
+  detail: string;
+}
+
+const ITEMS: LibraryItem[] = [
+  { id: 'tokens', label: 'Design tokens', detail: 'Semantic color, spacing, and radius scales shared across every surface.' },
+  { id: 'controls', label: 'Toolbar controls', detail: 'Control groups and segmented controls with their hover and pressed contracts.' },
+  { id: 'layouts', label: 'App layouts', detail: 'Navigation stacks, split views, workbench, and bottom-tab scaffolds.' },
+];
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const listView = (): NavStackView => ({
+    key: 'library',
+    title: 'Library',
+    content: <div class="recipe-navstack__view kui-pane__content kui-content">
+      <section>
+        <MenuHeader label="Components" />
+        {ITEMS.map((item) => <MenuItem action="recipe-action" itemId={item.id} label={item.label} icon={<LucideIcon icon={Folder} name="folder" />} trailing={<LucideIcon icon={ChevronRight} name="chevron-right" />} />)}
+      </section>
+      <p class="kui-recipe__ownership kui-content-item">The recipe owns the stack as a signal of views and pushes/pops it; `NavStack` renders the stack and `wireNavStack` slides the content and settles the chrome. The app owns selection, data, and routing.</p>
+    </div>,
+  });
+
+  const detailView = (item: LibraryItem): NavStackView => ({
+    key: item.id,
+    title: item.label,
+    content: <div class="recipe-navstack__view kui-pane__content kui-content">
+      <div class="kui-content-item">
+        <LucideIcon icon={FileText} name="file-text" />
+        <strong>{item.label}</strong>
+        <p class="kui-recipe__muted">{item.detail}</p>
+      </div>
+    </div>,
+  });
+
+  const views = signal<NavStackView[]>([listView()]);
+
+  const render = () => <section class="kui-recipe recipe-navstack kui-recipe__surface" data-recipe="recipe-navigation-stack">
+    <div class="recipe-navstack__stage"><NavStack id="recipe-nav" label="Component library" views={views.value} /></div>
+  </section>;
+
+  return {
+    render,
+    action(command, element) {
+      if (command === 'nav-back') {
+        if (views.value.length > 1) {
+          views.value = views.value.slice(0, -1);
+          announce('Navigated back');
+        }
+        return;
+      }
+      const id = element.dataset.itemId;
+      const item = ITEMS.find((candidate) => candidate.id === id);
+      if (item) {
+        views.value = [...views.value, detailView(item)];
+        announce(`Opened ${item.label}`);
+      }
+    },
+  };
+};