@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.100

package/docs/nav-stack.md

@@ -5,14 +5,19 @@ and out over one another while the top chrome settles. A **single-pane layout is
 a `NavStack` with one entry**. It is one of the opt-in app layouts (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 
-Import the component and its companion stylesheet:
+Import the component and its wiring helper:
 
 ```ts
-import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
-import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
-import '@kerfjs/ui/nav-stack.css';
+import { NavStack, type NavStackView } from "@kerfjs/ui/nav-stack";
+import { wireNavStack } from "@kerfjs/ui/wire-nav-stack";
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads NavStack's stylesheet and those of the components it renders internally
+(`Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `Pane`, `List`, `LucideIcon`). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/nav-stack.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
 ## State lives in the app
 
 Like every `@kerfjs/ui` component, `NavStack` is declarative: the app owns the
@@ -20,28 +25,296 @@ stack as a `signal<NavStackView[]>`, `NavStack({ views })` renders it, and
 `wireNavStack` animates the transitions.
 
 ```tsx
-const views = signal<NavStackView[]>([{ key: 'inbox', title: 'Inbox', content: <InboxView /> }]);
+const views = signal<NavStackView[]>([
+  {
+    key: "inbox",
+    toolbar: { title: "Inbox" },
+    content: <InboxView />,
+    bottomToolbar: {
+      label: "Inbox status",
+      leading: <InboxStatus />,
+    },
+  },
+]);
 
 // render inside mount():
 <NavStack id="mail" label="Mail" views={views.value} />;
 
 // once, after first render:
-const dispose = wireNavStack(root, { onBack: () => { views.value = views.value.slice(0, -1); } });
+const dispose = wireNavStack(root, {
+  onBack: () => {
+    views.value = views.value.slice(0, -1);
+  },
+});
 
 // push / pop by editing the signal:
-views.value = [...views.value, { key: id, title: 'Message', content: <MessageView id={id} /> }];
+views.value = [
+  ...views.value,
+  { key: id, toolbar: { title: "Message" }, content: <MessageView id={id} /> },
+];
 ```
 
 `NavStack` renders every entry stacked, the last one active and the rest kept
-mounted (so their DOM state and focus survive) but hidden. Each entry carries a
-`key` (stable identity), `content`, an optional `title`, and optional per-view
-`toolbar` actions. The back control appears automatically once the stack has more
-than one entry; `wireNavStack`'s `onBack` is where the app pops its own signal.
+mounted (so their DOM state survives) but hidden. Each entry carries a
+`key` (stable identity), `content`, an optional `toolbar` object with `title`,
+`leading`, `center`, and `trailing` groups, and an optional structured
+`bottomToolbar`. The component-level structured
+`bottomToolbar` remains a persistent fallback for views that do not provide one.
+Each view can also provide `header`, `footer`, `headerList`, `footerList`, and
+`pane` configuration, as a `WorkbenchStaticPanel` does. With any of these,
+the view renders a `Pane`: its header and footer stay pinned around the view's
+scrolling content, and slide with that view during navigation. The header and
+footer list configuration forwards to their `List`s; `pane` forwards
+`contentElement`, `contentLabel`, `separators`, `safeAreaEdges`,
+`chromeDividers`, `appearance`, `deepInset`, `scrollClearance`, `headerPresentation`, `tabIndex`,
+and `outlined` to the Pane. Without those fields, the view
+keeps its simple direct scroll area. Use `pane: { appearance: "sunken" }` for a
+lowered scrolling work surface.
+The back control appears automatically once the stack has more than one entry;
+`wireNavStack`'s `onBack` is where the app pops its own signal.
+
+See [Lowered work surfaces](layout.md#lowered-work-surfaces) for nested Pane
+and layout content.
+
+## The top toolbar
+
+The top chrome is a real `Toolbar`, so it follows the same zone,
+group, and responsive rules as every other toolbar. Its leading zone holds the
+back control (a contained, bordered `ToolbarControlGroup`, shown once the stack has
+depth), then `toolbar.leading`. `toolbar.trailing` fills the trailing zone.
+Give each zone `ToolbarControlGroup`s or `ToolbarText`, as in any toolbar.
+
+Where `toolbar.title` goes depends on the back control:
+
+- **At the root** (no back control) the title is a filling `ToolbarText` at
+  the end of the leading zone, so it reads left-aligned.
+- **Once the stack has depth**, the title is the center zone's only child and
+  the toolbar is `centerAlign="balanced"`, like a platform navigation bar. The
+  title sits on the bar's midpoint while the sides leave room, moves away from
+  a wider side when they do not, and truncates with an ellipsis before it
+  reaches the back control or a trailing group. It keeps the root title's
+  full-strength text color at its smaller size. This overrides a configured
+  `centerAlign`, which applies to view-owned center content.
+- **A view that sets `toolbar.center`** owns the center zone, so its title
+  stays left-aligned in the leading zone at any depth.
+
+Configure the toolbar with `toolbarConfig` instead of styling it:
+
+```tsx
+<NavStack
+  id="mail"
+  label="Mail"
+  views={views.value}
+  backText={previousTitle}
+  toolbarConfig={{
+    headingLevel: 1,
+    titleSize: "xlarge",
+    dividerSides: "b",
+    responsive: "wrap",
+  }}
+/>
+```
+
+- Each view's `toolbar` can forward the `Toolbar` configuration (`dividerSides`,
+  `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) and its `label`,
+  `titleSize`, and `headingLevel`. A view value overrides the corresponding
+  `toolbarConfig` default. Its `bottomToolbar` forwards the same `Toolbar`
+  configuration and has a required accessible `label`.
+- `toolbarConfig` supplies stack-wide defaults (`dividerSides`,
+  `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) and adds
+  `label` (the toolbar's accessible name), `titleSize` (the title's
+  `ToolbarText` size; default `xlarge` at the root, where the title is the page
+  heading, and `large` once a back control shares the bar; a Workbench panel's
+  stack keeps `large` at every depth), and `headingLevel` (expose the title as
+  a heading; default a plain span). The defaults keep the stack's own chrome:
+  no divider, the standard Toolbar height (a 44px control band with 8px above and below), and the top and side safe-area edges
+  claimed.
+- `backIcon` replaces the default chevron-left icon. `backText` adds visible
+  text beside it (for example, the previous view's title); visible text names
+  the control, so `backLabel` applies only to the icon-only control.
+
+`panelToggle` supplies a persistent final group in the trailing zone of every
+view's top toolbar. `Workbench` uses it for a navigation panel's standard
+collapse toggle; the active view still owns the preceding toolbar groups.
+
+The catalog's **Configured Toolbar** example shows these together: a level-2
+heading title over a bottom divider, leading and center groups on the root
+view, a trailing group on the pushed view, and `backText` set to the previous
+view's title.
+
+Focus follows the controlled stack automatically. On push, `wireNavStack`
+remembers the focused descendant of the departing view and moves focus into the
+new top view. On pop it restores that exact descendant when it still exists. A
+new view prefers a descendant marked `data-nav-focus`, then its first enabled
+focusable descendant, and finally the view container itself. Use
+`data-nav-focus` for a heading or primary control when DOM order is not the best
+initial reading position; it may use `tabindex="-1"` for programmatic focus.
+When a remembered control was removed during the controlled rerender, the same
+fallback order applies. Disposing the helper stops future transitions and
+cleans up any temporary fallback `tabindex` it added.
+
+## Separators and scroll dividers
+
+`separator="auto"` (the default) draws a line under the top chrome and above
+the optional bottom toolbar when the active view's Pane has
+`appearance="sunken"`, even if its content fits and no scroll wiring runs. The
+line follows the active view on push and pop. Set `separator="hidden"` to hide
+both stack-owned edges, including lines requested by `chromeDividers`. The
+existing 1px edges change color without moving the content. A view's own Pane
+header and footer separators remain controlled by that Pane.
+
+For a flat active view, the stack draws no permanent line. With
+`wireScrollDividers(appRoot)` installed (see
+[Layout › Scroll dividers](layout.md#scroll-dividers)), the top chrome shows a
+line along its bottom edge only while the active view's content is scrolled
+beneath it, and the bottom toolbar a line along its top edge only while more
+content lies below it — neither when the content fits. The line follows the
+active view across a push or pop. The chrome's line is overlaid on its bottom
+edge and the bottom toolbar's is its always-present 1px top border, colored
+only while shown, so neither ever moves the chrome or the content. When the view's only child is a `Pane`,
+the line keys on whichever actually scrolls — the view, or the Pane's content —
+and a Pane header or footer draws its own boundary instead. An explicit
+`toolbarConfig.dividerSides` still draws a permanent Toolbar edge.
+
+`chromeDividers` configures both lines for flat views, with the same values as a `Pane`'s:
+`scroll` (the default) follows the scroll state above and draws nothing until
+the wiring runs; `always` keeps both lines, with or without the wiring; `none`
+drops them even when the wiring reports scroll state. A sunken active Pane still
+shows the separator unless `separator="hidden"`. This option does not change the
+top Toolbar's own `dividerSides`.
+
+```tsx
+<NavStack id="settings" label="Settings" views={views.value} chromeDividers="always" />
+```
+
+## Overlay chrome
+
+`chromePresentation="overlay"` lays the top chrome over the active view's top
+edge, like an iOS navigation bar, instead of docking it above the view
+(`"docked"`, the default). The chrome paints the shared chrome material,
+`--kui-chrome-material` behind `--kui-chrome-material-filter`, so content
+scrolls visibly, blurred, beneath it.
+
+```tsx
+<NavStack id="mail" label="Mail" views={views.value} chromePresentation="overlay" />
+```
+
+- **`wireNavStack` measures it.** The helper you already call for transitions
+  reads the live chrome's border-box height with a `ResizeObserver`, publishes
+  it on the stack root, and marks the root `data-chrome-overlay="measured"`.
+  Only then does the chrome leave its band. Unwired, or with `hideToolbar`, the
+  chrome stays docked, so it never covers content it has not measured. The
+  measurement follows the chrome as its title wraps, text grows, or a pushed
+  view changes its toolbar. A re-render that strips the measurement gets it
+  back before paint.
+- **Every view clears it automatically.** The measured height becomes the
+  viewport's block-start edge context (`--kui-edge-inset-block-start`), the
+  same context that carries safe areas. A plain view pads and scroll-pads by
+  it, a sole `Pane` adds it to its content's (or its header's) block-start
+  inset, and a nested layout hands it on. The first item rests just below the
+  chrome, and anything focused or scrolled into view stops clear of it. No
+  `scrollClearance` prop is involved, so a Pane that also opts into
+  `scrollClearance` does not clear the chrome twice.
+- **Safe area.** The chrome keeps claiming the top safe area: its toolbar pads
+  for it while the material paints through it. The measured height already
+  includes that padding, so views clear the chrome and the safe area exactly
+  once.
+- **Transitions.** Only the live chrome is measured, never a cross-fading
+  copy. The copy keeps painting over the top edge with the same material while
+  it fades, and the incoming view settles at the incoming chrome's clearance.
+- **Classic scrollbars.** Where the active view's scroller (the view, or a
+  sole header-less Pane's content) shows a classic, space-taking scrollbar,
+  `wireNavStack` measures it and the chrome ends where its track begins, so
+  the thumb and arrows stay visible and usable. An overlay scrollbar takes no
+  space and passes beneath the material like the content.
+- **Dividers.** With `wireScrollDividers`, the line under the chrome still
+  appears only while content is scrolled beneath it.
+- **Contrast.** The material keeps normal text at AA over any content. An
+  untoned `ToolbarText` in the chrome lifts itself: its title takes the normal
+  text color at every size and its `description` mixes the quiet color halfway
+  toward it, and a default-tone `ToolbarControlGroup` takes the normal text
+  color for its controls. Other quiet copy you place in the chrome has no such
+  lift, so keep it in the view (see
+  [Accessibility › Chrome material](accessibility.md#chrome-material)). The
+  material turns opaque under `prefers-reduced-transparency`,
+  `prefers-contrast: more`, or without `backdrop-filter`, and forced colors
+  paint `Canvas` with a `CanvasText` bottom edge.
+
+`SplitView`'s `compactStack.chromePresentation` and a Workbench navigation
+panel's `navStack.chromePresentation` forward the same option.
+`chromePresentation` governs only the top chrome; the bottom toolbar has its
+own option below.
+
+### Overlay bottom toolbar
+
+`bottomToolbarPresentation="overlay"` does the same for the bottom toolbar,
+like an iOS toolbar: it lies over the active view's bottom edge on the same
+chrome material instead of docking below the view (`"docked"`, the default).
+It is a separate prop, so either bar can be overlaid alone, and it mirrors
+`Pane.headerPresentation` and `DialogSurface.footerPresentation` in naming one
+edge.
+
+```tsx
+<NavStack
+  id="mail"
+  label="Mail"
+  views={views.value}
+  chromePresentation="overlay"
+  bottomToolbarPresentation="overlay"
+  bottomToolbar={{ label: 'Mail Actions', trailing: composeGroup }}
+/>
+```
+
+- **`wireNavStack` measures it.** It reads the live bottom toolbar's
+  border-box height (never a cross-fading copy's), publishes it on the stack
+  root, and marks the root `data-bottom-toolbar-overlay="measured"`. Only then
+  does the toolbar leave its band. Unwired, or while no bottom toolbar is
+  shown (a view without one and no stack-level fallback), it stays docked. The
+  measurement follows a view-owned toolbar as views push and pop, and a
+  re-render that strips it gets it back before paint.
+- **Every view clears it automatically.** The measured height becomes the
+  viewport's block-end edge context (`--kui-edge-inset-block-end`). A plain
+  view pads and scroll-pads by it, a sole `Pane` adds it to its content's
+  block-end inset (or its footer's, so the footer rests just above the
+  toolbar), and a nested layout hands it on. The last item rests just above
+  the toolbar, and anything focused or scrolled into view stops clear of it.
+- **Safe area.** The toolbar keeps claiming the bottom safe area (the home
+  indicator), and the measured height includes it, so views clear both exactly
+  once. Inside a `TabNavigator` scene the tab bar owns that edge, so the
+  stack's toolbar sits just above the tab bar and counts no safe area.
+- **Classic scrollbars and dividers.** The toolbar ends where a classic
+  scrollbar's track begins (a sole Pane with a footer ends its scroller above
+  the toolbar, so nothing needs leaving there). With `wireScrollDividers`, the
+  toolbar's top line still appears only while more content lies below.
+- **Contrast.** An untoned `ToolbarText` lifts itself as in the top chrome,
+  and a default-tone `ToolbarControlGroup` in either overlaid bar takes the
+  normal text color for its controls, so labels and icons keep AA over the
+  content beneath. The material has the same opaque fallbacks; in forced
+  colors the toolbar paints `Canvas` and its always-present 1px top border
+  becomes a `CanvasText` edge, which the measurement includes.
+
+`SplitView`'s `compactStack.bottomToolbarPresentation` and a Workbench
+navigation panel's `navStack.bottomToolbarPresentation` forward it too.
+
+## Safe areas
+
+The stack paints through a device's unsafe areas. Its chrome pads for the top
+and side insets, its bottom toolbar for the bottom and side insets, and each
+view pads the remaining edges inside its scroller, so content scrolls under the
+unsafe area but can always be scrolled clear. A view whose only child is a
+`Pane` or layout lets that child own the insets. See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
 
 ## Transitions
 
 `wireNavStack(root, { onBack, duration? })` observes the rendered stack and
 animates each change: a pushed view slides in from the trailing edge; a popped
-view slides back off it over the revealed view. It returns a disposer. The
-animation honors `prefers-reduced-motion` (transitions collapse to instant) and
-`duration: 0` disables it. Applicable at every device size and inside dialogs.
+view slides back off it over the revealed view; and snapshots of the previous
+top and bottom chrome cross-fade into the active view's chrome. The preserved
+underlying view remains visible during a push, while remaining inaccessible.
+Starting transforms and opacity apply instantly before the transition begins.
+A new navigation settles the previous transition and cancels its pending frames
+and cleanup timers; disposal removes temporary copies and exiting views. Focus moves to
+the new top view independently of animation duration. It returns a disposer.
+The animation honors `prefers-reduced-motion` (transitions collapse to instant)
+and `duration: 0` disables it. Applicable at every device size and inside
+dialogs.

package/docs/recipes.md

@@ -1,62 +1,75 @@
 # Production composition recipes
 
-These seven reference compositions sit between individual primitives and product
-code. Open each stable UX-catalog route to run it, then copy the linked TSX and
-CSS. The examples import public package subpaths, use semantic layout owners,
-and keep state in a per-instance application adapter. They are not new
-monolithic components.
+These ten reference compositions sit between individual primitives and product
+code. Open each stable UX-catalog route to run it, then copy the linked TSX. The
+examples import public package subpaths, compose components through their
+props and tokens, and keep state in a per-instance application adapter. They
+ship no stylesheet of their own and are not new monolithic components.
 
 Copy the recipe source together with the catalog-independent
 [`mount-recipe.ts`](../ux-demo/recipes/mount-recipe.ts) adapter. It mounts the
 controller at one stable application root, uses `delegateActions()` for recipe
-commands, forwards form and dialog lifecycle events, wires resize commits with
-the public `onCommit` callback, retains every disposer, and returns one
-idempotent disposer:
+commands, forwards form and dialog lifecycle events, runs the recipe's own
+`wire()` (for example `wireWorkbench` or `wireSidebar`), retains every
+disposer, and returns one idempotent disposer:
 
 ```ts
-import { createRecipe } from './navigation-sidebar.js';
-import { mountRecipe } from './mount-recipe.js';
+import { createRecipe } from "./navigation-sidebar.js";
+import { mountRecipe } from "./mount-recipe.js";
 
-const root = document.querySelector<HTMLElement>('#navigation')!;
+const root = document.querySelector<HTMLElement>("#navigation")!;
 const stopRecipe = mountRecipe(root, createRecipe(announce));
-window.addEventListener('pagehide', stopRecipe, { once: true });
+window.addEventListener("pagehide", stopRecipe, { once: true });
 ```
 
 The adapter is delivered as reference source, not a new package runtime export.
 `delegate()` remains a valid alternative when an application needs selector-
 specific dispatch; either way, wire once at a stable root and retain disposal.
 
-## Desktop application shell
-
-[Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx) · [shared CSS](../ux-demo/recipes/recipes.css)
-
-Use `Toolbar`, controlled `ResizableRegion` panes, and one
-`.kui-pane__content` scroll owner per pane. The recipe owns the shell topology;
-the app owns routing, responsive pane visibility, sizes, persistence, and data.
-Keep each visible pane's collapse action in its own toolbar. Once hidden, put
-its restore action in the adjacent main toolbar on the same logical edge:
-leading for an inline-start sidebar and trailing for an inline-end inspector.
-Collapse the pane completely rather than preserving an empty icon rail.
-Adapt only public `--kui-layout-*` and component variables.
-
-## Navigation sidebar
+## Desktop Application Shell
+
+[Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx)
+
+A filling `List` (`fill`, with the recipe's `data-*` markers through
+`rootAttributes`) stacks the app-bar `Toolbar` above a `Workbench`
+(`@kerfjs/ui/workbench`): resizable navigation and inspector rails around the
+task list. Each rail composes its own panel toolbar — a default-size title and
+the standard hide toggle — and the work area's `mainToolbar` carries the xl
+view title. While a rail is hidden, `Workbench` relocates its show toggle into
+the work-area toolbar on the same logical edge (leading for the navigation
+rail, trailing for the inspector), and `wireWorkbench` hands focus between the
+two positions. Collapse a rail completely rather than preserving an empty icon
+rail. Only the three real panes own a `.kui-pane__content` scroll owner; no
+frame `Pane` wraps the layout in a scroll owner that never scrolls, and the
+app-bar `Toolbar` claims the top edge and both sides with its own
+`safeAreaEdges`.
+
+On a narrow container the rails overlay the task list one at a time instead of
+squeezing it, leaving a 44px strip on the far side that dismisses the overlay
+(`responsiveOverlayAt`, on by default; `compactOverlay: 'full'` covers the
+whole width). The app owns each rail's collapsed and size signals — which
+`wireWorkbench` keeps in sync with resizing and overlay dismissal — plus
+routing, persistence, and data. Adapt only public `--kui-layout-*` and
+component variables.
+
+## Navigation Sidebar
 
 [Open the recipe](../ux-demo/?component=recipe-navigation-sidebar) · [TSX source](../ux-demo/recipes/navigation-sidebar.tsx)
 
 One unpadded `.kui-pane` owns toolbar/content/footer structure. Its
-`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and other
-`.kui-content-item` children own their 8px margin, 1px border, and 8px padding.
+`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and
+`ContentItem` children own their 8px margin, 1px border, and 8px padding.
 Rows and footer toolbar groups remain 44px tall. The app owns routes,
 permissions, labels, selection, valid section counts and their localized
 `countLabel` phrases, non-count badge content, disclosure state, and revealed
 content. A toggled `ListHeader` supplies the production `DisclosureArrow` when
 no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
 
-## Workspace header
+## Workspace Header
 
 [Open the recipe](../ux-demo/?component=recipe-workspace-header) · [TSX source](../ux-demo/recipes/workspace-header.tsx)
 
-`PanelHeader` owns the page heading while one control cluster holds secondary,
+The page heading is a direct `Toolbar`/`ToolbarText` composition while one control cluster holds secondary,
 overflow, and primary actions. The app owns authorization and command policy;
 controls relocate without changing focus order.
 
@@ -64,34 +77,48 @@ controls relocate without changing focus order.
 
 [Open the recipe](../ux-demo/?component=recipe-list-detail-dialog) · [TSX source](../ux-demo/recipes/list-detail-dialog.tsx)
 
-The production Web Awesome dialog owns modal focus and Escape; the thin recipe
-adapter restores the invoking control consistently after the hide event.
-`PanelHeader`, `ListHeader`, `ListItem`, and `ValueTable` own their included
-anatomy. The application owns open state, selection, dismissal policy, and
-record actions. `PanelHeader` places the trailing controls the app passes
-directly into its top toolbar's trailing zone.
-The header sits on the dialog edge while retaining its internal control inset;
-the selected title receives the full content gutter, the metadata table fills
-the available detail width between the usual outer margins, and the action
-cluster uses one outer gutter without a second content-item inset.
-Do not rebuild the dialog or reach into private shadow parts.
-
-## Composer form
+A list-detail dialog is laid out like a `Workbench` with a left sidebar: on
+roomy devices the list is a full-height sidebar and the detail is a full-height
+main column, each a `Pane` with its own top `Toolbar`. The sidebar's toolbar
+carries its quiet default-size title (and it may add a bottom toolbar for
+sidebar-only actions); the main column's toolbar carries the dialog's primary
+extra-large title and the close control, and its footer carries the record
+actions. The Web Awesome dialog therefore renders `without-header` there —
+its label still names the modal — and the close button uses
+`data-dialog="close"`. Web Awesome keeps modal focus and Escape, and the thin
+recipe adapter restores the invoking control after the hide event.
+`DialogSurface` chooses the large modal with no body inset, because the panes
+own their geometry. Its explicit 16px `viewportGutter` and `maxHeight="viewport"`
+bound the roomy modal to the dynamic viewport; the compact fullscreen
+presentation retains its existing geometry. Application render state chooses
+the presentation and can likewise choose gutter/cap values for a compact modal.
+On compact devices the dialog becomes a full-screen sheet
+with its own labeled header and footer actions, and `SplitView` becomes a
+`NavStack` drill-down whose back control the application pops. The
+application owns open state, selection, the pushed detail, dismissal policy,
+and record actions. Do not put the primary title in a header spanning both
+columns, rebuild the dialog, or reach into private shadow parts.
+
+## Composer Form
 
 [Open the recipe](../ux-demo/?component=recipe-composer-form) · [TSX source](../ux-demo/recipes/composer-form.tsx)
 
-`PanelHeader` supplies the task title and summary, with their ids referenced
-by the form. Production fields own labels, help, and native focus. The field
-and footer control edges sit directly on the shared 8px inline gutter rather
-than acquiring a second content-item padding inset; major children remain 24px
-apart and related controls use 8px gaps. The app owns
+A direct `ToolbarText` supplies the task title, with app-owned supporting copy
+below; their ids are referenced by the form. `ListInsetText` gives that bare
+supporting copy the same content-item text inset as the fields. The title and
+supporting line share a nested heading `List` with `gap="none"`, so the heading
+unit stays together instead of taking the form's 24px section gap. Production
+fields own labels, help, and native focus. One `List` owns the 24px major
+rhythm; the field `List` and the action `Row` use `controlInsets` to sit on the
+shared 8px inline gutter with 8px gaps between related controls, rather than
+acquiring a second content-item padding inset. The app owns
 validation, drafts, permissions, and transport. Persistent error or success
 feedback is the only nested semantic surface and uses `StateBanner`, not a toast.
 Because upgraded Web Awesome fields retain live value properties, controlled
 resets synchronize both those properties and the rendered value attributes;
 the Reset action also announces `Draft reset` through the catalog live region.
 
-## List workspace states
+## List Workspace States
 
 [Open the recipe](../ux-demo/?component=recipe-list-workspace-states) · [TSX source](../ux-demo/recipes/list-workspace-states.tsx)
 
@@ -100,54 +127,75 @@ populated, stale/background refresh, and error/retry states. The recipe owns
 feedback placement; the app owns fetching, cache age, retry policy, and domain
 rows.
 
-## Compact toolbar choices and actions
+## Compact Toolbar Choices and Actions
 
 [Open the recipe](../ux-demo/?component=recipe-compact-toolbar) · [TSX source](../ux-demo/recipes/compact-toolbar.tsx)
 
 Use `ToolbarControlGroup` for related commands, `SegmentedControl` for a few
 visible exclusive choices, `Select` for a longer value list, and an ordinary
-button for an independent command. The app owns values, actions, persistence,
-and responsive priority.
+button for an independent command. Even that independent button sits in a
+single-control `ToolbarControlGroup`, which keeps its height, pill shape, focus,
+and hover treatment aligned with the adjacent toolbar controls. At compact
+widths the toolbar stacks its zones and wraps whole trailing groups onto another
+row, so the last action is never clipped. The app owns values, actions,
+persistence, and responsive priority.
 
-## Navigation stack
+## Navigation Stack
 
 [Open the recipe](../ux-demo/?component=recipe-navigation-stack) · [TSX source](../ux-demo/recipes/navigation-stack.tsx)
 
 Drill from a library list into a detail and back with `NavStack`
 (`@kerfjs/ui/nav-stack`): the app owns the stack as a signal of views and
 pushes/pops it, `NavStack` renders it, and `wireNavStack` slides the content and
-settles the chrome (reduced motion collapses the slide to instant). A live
-`deviceClass()` badge shows the current size/orientation. See the layout guide
+settles the chrome (reduced motion collapses the slide to instant). See the
+layout guide
 [`app-layouts.md`](app-layouts.md) for choosing among `NavStack`, `SplitView`,
-`Workbench`, and `TabScaffold`.
+`Workbench`, and `TabNavigator`.
 
-## Loading inspector
+## Loading Inspector
 
 [Open the recipe](../ux-demo/?component=recipe-loading-inspector) · [TSX source](../ux-demo/recipes/loading-inspector.tsx)
 
 A record inspector whose per-record values load asynchronously. Every
-value-bearing component (`PanelHeader`, `ValueTable`/`ValueTableRow`, `Select`,
+value-bearing component (`ToolbarText`, `ValueTable`/`ValueTableRow`, `Select`,
 `SegmentedControl`, `ListItem`, `StateBanner`) takes its `placeholder` from one
 loading flag, so the same real chrome renders a faithful loading state and then
 the populated record — no separate skeleton markup. The composition is the point;
-`Skeleton` is the primitive it builds on. The app owns the loading lifecycle and
+`Skeleton` is the primitive it builds on. Its heading `Toolbar` uses
+`responsive="wrap"`, so on a narrow inspector the toggle moves below a whole
+record title instead of truncating it. The app owns the loading lifecycle and
 which values are still unknown.
 
-## Collapsible sidebar
+## Collapsible Sidebar
 
 [Open the recipe](../ux-demo/?component=recipe-collapsible-sidebar) · [TSX source](../ux-demo/recipes/collapsible-sidebar.tsx)
 
 A mini app frame whose left navigation rail and bottom activity drawer are
 standalone `CollapsiblePanel`s (`@kerfjs/ui/collapsible-panel`) driven by
-`wireSidebar` (`@kerfjs/ui/wire-sidebar`). `CollapsiblePanelToggle` supplies the
-standard per-side glyph: a collapse toggle lives inside each panel and an expand
-toggle lives in the always-visible main header, so a collapsed panel is still
-reachable. `wireSidebar` owns the toggle delegation, moves focus into a panel on
-open and restores it to the trigger on close, and — when a `deviceClass()` reports
-`compact` — switches the open panel to a dismissable **overlay** (backdrop, Escape
-and backdrop-click collapse, and a trapped Tab ring, the ARIA dialog pattern). It
-also persists each panel's collapsed state through a supplied storage hook. The app
-owns each `collapsed` signal, the panel sizes, and the content; the wire owns the
+`wireSidebar` (`@kerfjs/ui/wire-sidebar`). Each panel takes a `toolbar` — a
+title plus the standard per-side toggle — so the hide control lives in the
+panel's own header, and `CollapsiblePanelRelocated` renders the matching show
+control only while the panel is collapsed, so exactly one control owns each
+action and a collapsed panel is still reachable. The rail's relocated toggle
+leads the always-visible main header; the drawer's sits in a
+`FloatingToolbar` passed as the drawer's own `restoreControl`, which the panel
+floats in its column's safe-area-aware bottom-end corner, next to where the
+drawer opens — do not hand-roll a conditional floating control beside the
+panel. `wireSidebar` owns the toggle delegation, moves focus into a
+panel on open, restores it on close (to the trigger, or to the panel's expand toggle when
+the trigger sits inside the collapsed panel), and — when a `deviceClass()` reports
+`compact` — presents the panels as a dismissable **overlay** (backdrop, Escape
+and backdrop-click collapse, and a trapped Tab ring, the ARIA dialog pattern).
+The overlay starts closed and opens only from a toggle; the rail's signal is
+seeded from the device class with `inlineCollapsed: false`, so the first compact
+render has no overlay and a wide crossing restores the open inline rail. It
+also persists each panel's inline collapsed state through a supplied storage hook. A
+filling `Row` (`fill` plus `rootAttributes`) is the root: it takes the frame's
+definite height and places the rail beside a `List` column, and a one-column
+`Grid` grows the main pane above the drawer. Because the panels sit at the real
+frame edges, each grows through its edge's safe area and hands that edge back to
+its siblings when it collapses; the drawer's activity log is a `ValueTable`. The app owns each
+`collapsed` signal, the panel sizes, and the content; the wire owns the
 ephemeral interaction. For a full three-pane shell use `Workbench` instead — see
 [`app-layouts.md`](app-layouts.md). This recipe is covered end-to-end across
 Chromium, Firefox, and WebKit by `tests/browser/collapsible-sidebar-recipe.spec.ts`.
@@ -159,9 +207,17 @@ Chromium, Firefox, and WebKit by `tests/browser/collapsible-sidebar-recipe.spec.
 - For direct `wa-*` JSX, import types from `@kerfjs/ui/webawesome`. Import only
   individual Web Awesome registration modules and theme them with
   `@kerfjs/ui/webawesome.css`.
-- Prefer public props and variables at the composition boundary. When a recipe
-  needs responsive topology, join only classes listed in the catalog's
-  `publicClasses`; do not copy component markup or select descendants by tag,
-  id, attribute alone, or an unlisted implementation class.
+- Compose, don't style. A recipe ships no stylesheet, sets no inline style, and
+  names no class outside the published layout vocabulary (`.kui-content`,
+  `.kui-control-cluster`, …) and themed Web Awesome classes — a content item is
+  a `ContentItem`, not a hand-written `.kui-content-item`; it configures
+  components through props, `rootAttributes`, and tokens. When a recipe needs a
+  capability no component offers, record it as a component gap rather than
+  papering over it with CSS. `npm run check:recipes` enforces these rules on
+  every file in `ux-demo/recipes/`.
+- Each recipe also exports a catalog-only `presentation`: the `CatalogExample`
+  viewport that frames it in the UX catalog and its ownership note. An
+  application that copies the recipe ignores that export and mounts the
+  controller into its own container.
 - Start from the copyable mount adapter, or reproduce its complete boundary:
   wire stable `data-action` hooks once and retain every disposer.