@kerfjs/ui 4.4.1 → 5.0.0-beta.10

package/docs/layout.md

@@ -0,0 +1,131 @@
+# Pane and content layout
+
+Import `@kerfjs/ui/layout.css` for the shared geometry used by sidebars, main
+areas, inspectors, and dialogs. The vocabulary deliberately describes structure
+rather than location: the same pane can be placed anywhere.
+
+## Anatomy
+
+```tsx
+<aside class="kui-pane">
+  <div class="kui-pane__toolbar"><Toolbar label="Workspace" ... /></div>
+  <div class="kui-pane__content kui-content">
+    <section>...</section>
+    <section>...</section>
+  </div>
+  <footer class="kui-pane__footer"><Toolbar label="Actions" ... /></footer>
+</aside>
+```
+
+`.kui-pane` has no padding. It reserves rows for an optional toolbar, one
+scrolling content area, and an optional footer. A main area or dialog often
+omits the footer; a navigation pane commonly uses all three. Fixed chrome stays
+outside `.kui-pane__content`, which is the pane's scroll owner.
+
+`.kui-content` is a vertical stack with a 24px gap between major children.
+Sections may contain adjacent `ListItem` rows without adding another major gap.
+Ordinary surface-like children use `.kui-content-item` and own their complete
+geometry:
+
+- 8px inline margin from the pane edge
+- 1px border, transparent by default
+- 8px internal padding and 8px internal gap
+- `calc(1px + remify(11px))`, or 12px, rounded corners
+
+Use `.kui-content-item--pill` for the 22px pill radius expressed as
+`calc(1px + remify(21px))`. Consumers can make a content item visible without
+changing its geometry by setting `--kui-content-item-border` and
+`--kui-content-item-background`.
+
+A visible parent surface does not make every child another visible card. The
+composer recipe keeps its form as the single surface, uses `PanelHeader` for
+its task hierarchy, and places field and action control edges on the shared 8px
+inline gutter instead of nesting them inside another padded content item. A
+conditional `StateBanner` remains visibly distinct because it communicates
+semantic status.
+
+## Public roles and tokens
+
+| Need | Class | Token / default |
+| --- | --- | --- |
+| Unpadded toolbar/content/footer structure | `.kui-pane` | — |
+| Scrolling pane content | `.kui-pane__content` | — |
+| Major vertical rhythm | `.kui-content` | `--kui-layout-content-gap: 24px` |
+| Self-contained child geometry | `.kui-content-item` | 8px margin + 1px border + 8px padding |
+| Pill child | `.kui-content-item--pill` | `--kui-layout-pill-radius: 22px` |
+| Related controls | `.kui-control-cluster` | `--kui-layout-control-gap: 8px` |
+| Inline metadata | `.kui-inline-metadata` | `--kui-layout-metadata-gap: 4px` |
+| Explicit scroll owner outside a pane | `.kui-scroll-owner` | `overflow: auto` |
+
+The component layer applies the same contract to `Toolbar`, `ListHeader`,
+`ListItem`, `PanelHeader`, `StateBanner`, `ValueTable`,
+`ValueTableRow`, tabs, and form controls. A value-table row separator starts at
+the row's 8px content inset, or at 40px when the row contains its 24px leading
+icon and 8px gap, and always ends 8px from the right edge. Each value-table row
+also keeps 8px of root-scaled block padding independently of its semantic inline
+inset. Most interactive rows and toolbar groups are 44px tall.
+Toolbar groups reserve a real 1px outer border around a 42px inner area, even
+when their border and background are transparent.
+`PanelHeader` is a plain top `Toolbar` used as a panel, dialog, or page heading
+and overrides no Toolbar styles. The leading zone holds the optional icon (a
+normal bordered `ToolbarControlGroup` given a brand fill with a matching border,
+a 22px glyph) and the title as extra-large `ToolbarText`; the app's trailing
+controls go straight into the trailing zone, and the icon group is omitted when
+no icon is passed. The optional subtitle is a separate row below the toolbar, its
+text left-aligned with the title text.
+
+## Spacing scale
+
+Spacing is not a free choice. The official scale is five canonical steps, each
+expressing exactly one relationship — pick the step by **how connected two
+elements are**, not by eye. Every scalable value is `remify`-authored against the
+fixed 16px baseline, so it delivers as `rem`.
+
+| Value | Token | Relationship — when to use |
+| --- | --- | --- |
+| 0px | `--kui-space-none` | No separation. The elements read as a single unit (a control and its own affordance, adjacent `ListItem` rows). |
+| 4px | `--kui-space-2xs` | Very minor. Still one connected cluster, but readability or aesthetics demand a hair of air (inline metadata, an icon beside its label). |
+| 8px | `--kui-space-xs` | Standard. Between elements **within a group** — the content-item padding/gutter, gaps between toolbar controls in a group. |
+| 16px | `--kui-space-m` | Minor. Between **homogeneous groups** — two lists, two sibling sections of the same kind. |
+| 24px | `--kui-space-l` | Major. Between **heterogeneous groups** — the `.kui-content` rhythm between major, differing regions. |
+
+The two relationships that get confused most are 8px vs 24px: 8px is *inside* a
+group, 24px is *between* major, differing regions. 16px sits between them for
+same-kind groups.
+
+`--kui-space-s` (12px) and `--kui-space-xl` (32px) exist but are **off the
+canonical rhythm** — reach for them only as a deliberate exception, never as a
+default step. Prefer the five canonical tokens so spacing stays legible and
+consistent across every surface.
+
+## Ownership rules
+
+1. Do not pad a sidebar, main area, dialog, or `.kui-pane` shell. Children own
+   their own margin, border, background, padding, and radius.
+2. Use 24px gaps for major vertical separation and 8px gaps inside an item or
+   between toolbar groups. Do not confuse the two relationships.
+3. Wrap toolbar content in `ToolbarControlGroup`, including dormant text. A
+   transparent group still reserves the same 44px geometry as a visible group.
+4. Keep one scrolling content owner per pane. Toolbar and footer siblings stay
+   fixed while the content scrolls.
+5. A split item keeps dormant and interactive regions separate. For example,
+   `ListHeader` renders its title/count-or-badge cluster separately from its optional
+   logical-end 44px action. The header fills the available inline width and its
+   action glyph defaults to 18px; disclosure mode makes the title cluster itself
+   the button and supplies the production `DisclosureArrow` unless `actionIcon`
+   replaces it.
+   `ListActionRow` uses a noninteractive row root around sibling 44px primary
+   and trailing buttons. `ListItem.trailing` remains dormant content.
+   In multiline `ListItem` and `ListActionRow` rows, the leading icon stays
+   centered on the label's first line rather than the full wrapped label.
+6. Reading width, column placement, and responsive relocation remain application
+   decisions. The shared classes define local geometry, not the whole shell.
+7. A visible collapsible pane owns its collapse control in that pane's toolbar.
+   When the pane is hidden, move the restore control into the adjacent main
+   toolbar on the same logical edge: an inline-start pane restores from the
+   main toolbar's leading group, and an inline-end pane restores from its
+   trailing group. Do not leave an otherwise empty icon-only rail behind.
+
+At narrow widths or 200% zoom, relocate or stack panes before shrinking targets.
+The 8/1/8 item contract and 44px controls remain stable, so screenshots and
+focus-order tests exercise the same model at every viewport.

package/docs/nav-stack.md

@@ -0,0 +1,47 @@
+# Navigation stack
+
+`@kerfjs/ui/nav-stack` is an iOS-style push/pop navigation stack: views slide in
+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:
+
+```ts
+import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
+import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
+import '@kerfjs/ui/nav-stack.css';
+```
+
+## State lives in the app
+
+Like every `@kerfjs/ui` component, `NavStack` is declarative: the app owns the
+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 /> }]);
+
+// 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); } });
+
+// push / pop by editing the signal:
+views.value = [...views.value, { key: id, 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.
+
+## 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.

package/docs/recipes.md

@@ -0,0 +1,167 @@
+# 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.
+
+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:
+
+```ts
+import { createRecipe } from './navigation-sidebar.js';
+import { mountRecipe } from './mount-recipe.js';
+
+const root = document.querySelector<HTMLElement>('#navigation')!;
+const stopRecipe = mountRecipe(root, createRecipe(announce));
+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
+
+[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.
+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
+
+[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,
+overflow, and primary actions. The app owns authorization and command policy;
+controls relocate without changing focus order.
+
+## List-detail dialog
+
+[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
+
+[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
+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
+
+[Open the recipe](../ux-demo/?component=recipe-list-workspace-states) · [TSX source](../ux-demo/recipes/list-workspace-states.tsx)
+
+The same content region moves deterministically through loading, empty,
+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
+
+[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.
+
+## 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
+[`app-layouts.md`](app-layouts.md) for choosing among `NavStack`, `SplitView`,
+`Workbench`, and `TabScaffold`.
+
+## 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`,
+`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
+which values are still unknown.
+
+## 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
+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`.
+
+## Rules shared by every recipe
+
+- Import `@kerfjs/ui/layout.css`; keep every pane unpadded and use exactly one
+  `.kui-pane__content` scroll owner for each real boundary.
+- 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.
+- Start from the copyable mount adapter, or reproduce its complete boundary:
+  wire stable `data-action` hooks once and retain every disposer.

package/docs/split-view.md

@@ -0,0 +1,49 @@
+# Split view (list-detail)
+
+`@kerfjs/ui/split-view` is a list-detail layout: a list and a
+detail side by side on roomy screens, collapsing to a `NavStack` (list → detail)
+on compact ones. One of the opt-in app layouts (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+
+```ts
+import { SplitView } from '@kerfjs/ui/split-view';
+import { deviceClass } from '@kerfjs/ui/device-class';
+import '@kerfjs/ui/split-view.css';
+// plus nav-stack.css when the compact path is reachable, and
+// wireResizableRegions / wireNavStack for the interactive behavior.
+```
+
+## Responsive by device class
+
+`SplitView` is declarative; the app derives `compact` from the device class and
+tracks its own selection:
+
+```tsx
+const device = deviceClass();
+const selected = signal<string | null>(null);
+
+<SplitView
+  id="mail"
+  label="Mail"
+  compact={device.value.compact}
+  detailActive={selected.value !== null}
+  list={<ThreadList />}
+  detail={<Message id={selected.value} />}
+  listTitle="Threads"
+  detailTitle="Message"
+  resizable={{ size: 320, min: 220, max: 480 }}
+/>;
+```
+
+- **Roomy** (`compact: false`): both panes show. With `resizable`, the list sits
+  in a `ResizableRegion` (wire it with `wireResizableRegions`); without it the
+  list takes a fixed `--kui-split-view-list-width` (default 320px) and the detail
+  fills the rest.
+- **Compact** (`compact: true`): the split collapses to a `NavStack`. The list is
+  the root; when `detailActive` is true the detail is pushed over it with an
+  automatic back control (wire it with `wireNavStack`, whose `onBack` clears the
+  app's selection). This is the portrait-tablet / handset presentation; as a
+  dialog the compact form is a full-screen or large partial-cover modal.
+
+Compose the interactive wiring from the existing helpers — `SplitView` adds no
+wire of its own.

package/docs/tab-scaffold.md

@@ -0,0 +1,41 @@
+# Tab scaffold
+
+`@kerfjs/ui/tab-scaffold` is a mobile-first, iOS-like bottom tab bar that switches
+between major app sections, where **each tab keeps its own content mounted** —
+usually a `NavStack`, so each tab's stack and scroll survive a switch. One of the
+opt-in app layouts (see [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+It is distinct from `TabBar` (document-oriented, reorderable strips).
+
+```ts
+import { TabScaffold } from '@kerfjs/ui/tab-scaffold';
+import { wireTabScaffold } from '@kerfjs/ui/wire-tab-scaffold';
+import '@kerfjs/ui/tab-scaffold.css';
+```
+
+## Controlled selection
+
+The app owns the active tab (a signal); `TabScaffold` renders every tab's scene
+(only the active one visible) plus the bottom bar, and `wireTabScaffold` reports
+clicks.
+
+```tsx
+const active = signal('home');
+
+<TabScaffold
+  id="app"
+  label="Sections"
+  active={active.value}
+  tabs={[
+    { id: 'home', label: 'Home', icon: <HomeIcon />, content: <HomeStack /> },
+    { id: 'search', label: 'Search', icon: <SearchIcon />, content: <SearchStack /> },
+  ]}
+/>;
+
+// once, after first render:
+const dispose = wireTabScaffold(root, { onSelect: (id) => { active.value = id; } });
+```
+
+Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, and `content`. The
+bottom bar respects the home-indicator safe area (`env(safe-area-inset-bottom)`)
+and keeps 44px targets. On larger device classes, promote the tab set to a
+`Workbench` rail or a persistent sidebar instead of a bottom bar.

package/docs/ux-demo.md

@@ -1,18 +1,32 @@
 # UX catalog contract
 
-Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation.
+Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
+
+Seven lazy production-composition routes live under the `Recipes` category.
+Each `?component=recipe-*` route uses public package primitives, real wiring,
+deterministic state, and semantic layout owners from the [recipe guide](./recipes.md).
 
 - It imports public component subpaths, exercising their browser-selected reachable CSS rather than a catalog-only style path.
+- The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
+- The `AppTab` route demonstrates a runtime-filtered domain metadata slot and a decorative replacement close icon without changing TabBar selection, close, reorder, or focus ownership. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
 - Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, feedback, and theme scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component.
-- Catalog metadata has a unique id, category, kind (`component` or `composition`), source (`kerf` or `webawesome`), name, description, and direct `uses` dependencies.
-- 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 constrain the expanded list to its own scroll region.
-- A detail with relationships renders one grouped selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Choosing either navigates to that component's demo. The footer is absent when both groups are empty; no duplicate relationship summary is rendered.
+- `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 `ListHeader` and `ListItem` 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 `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 list-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 `ListHeader` 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 ListHeader 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; 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; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; StateBanner exposes every built-in tone plus a scoped override; TabBar demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
-- Settings exercise light/dark, increased contrast, and reduced motion without changing component code, and expose each preference through `aria-pressed`.
-- The action log is an `aria-live` region, making interactions visible to both people and browser tests.
+- 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; ListItem and ListHeader 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.
 - The focused Toast route calls Web Awesome's documented programmatic stack API and notes that Hot Sheet 2 still uses its own app-level toast implementation; the catalog demonstrates ecosystem support without implying current product adoption.
-- Browser coverage walks every Kerf, composition, and Web Awesome route, checks every listed Web Awesome custom element is registered in its focused specimen, exercises the ecosystem disclosure and both relationship directions, and covers tab selection/reordering/overflow, semantic palettes and scoped overrides, light/dark rendering, toolbar popup behavior, menu alignment, banner urgency, keyboard resizing, live custom-element values, and representative wide/narrow captures.
-- The production build keeps the catalog shell and Kerf routes in the entry chunk, then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route (or the broad Web Awesome theme route) is selected. Directly addressed ecosystem URLs pass through the same loader. `npm run demo:build` enforces a 150 kB gzip ceiling for any JavaScript chunk and a 235 kB gzip ceiling for the complete JavaScript payload, so both accidental chunk collapse and aggregate growth fail the build.
+- Browser coverage walks every Kerf, composition, and Web Awesome route, checks every listed Web Awesome custom element is registered in its focused specimen, exercises the ecosystem disclosure and both relationship directions, validates offline source/guidance hrefs and accessible wide/narrow/200%-zoom wrapping, and covers tab selection/reordering/overflow, semantic palettes and scoped overrides, light/dark rendering, toolbar popup and responsive find behavior, single/multiline search alignment, menu alignment, banner urgency, keyboard resizing, live custom-element values, and representative wide/narrow captures.
+- The production build keeps the catalog shell and Kerf routes in the entry chunk, then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route, the broad Web Awesome theme route, or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
 
 Before handoff, inspect the actual captures for readability, context, alignment, clipping, spacing, responsiveness, focus, and obvious defects. Fix and recapture rather than treating the screenshot as proof by itself.

package/docs/webawesome-theme.md

@@ -4,11 +4,18 @@
 free components and the Kerf/Hot Sheet 2 design system.
 
 ```ts
+import type {} from '@kerfjs/ui/webawesome';
 import '@kerfjs/ui/webawesome.css';
 import '@awesome.me/webawesome/dist/components/button/button.js';
 import '@awesome.me/webawesome/dist/components/input/input.js';
 ```
 
+The type-only package import augments `kerfjs/jsx-runtime` with the 70
+catalog-supported `wa-*` elements. It has no runtime side effects. The catalog
+gate keeps the declaration tags aligned with Web Awesome's installed custom
+elements manifest, while individual component imports remain the only
+registration boundary.
+
 The CSS entry includes Web Awesome's native, utility, palette, and default-theme
 styles, then overrides the public semantic contract in
 `@layer wa-theme-overrides`. It does not import or register component
@@ -53,6 +60,11 @@ chevrons keep the same visual weight. The Accordion and Details components
 retain their own rotation behavior because scaling uses `transform` while
 their open state uses the independent `rotate` property.
 
+That scale applies to each Web Awesome component's intrinsic glyph and is
+independent of Kerf `DisclosureArrow`, whose default box is 18px relative to
+the root font size and whose consumer override is
+`--kui-disclosure-arrow-size`.
+
 Tooltip and Popover use arrowless floating surfaces by default, matching Hot
 Sheet 2. The theme sets Web Awesome's public `--wa-tooltip-arrow-size` token to
 `0px` and maps each popover's public `--arrow-size` property from
@@ -129,6 +141,9 @@ static content and labels that constraint next to the rendered output.
 
 The catalog lists every free Web Awesome component so support can be inspected;
 listing does not make each component the preferred Kerf application pattern.
+The [need-first decision matrix](./component-selection.md#web-awesome-overlap-policy)
+is the exhaustive Kerf/Web Awesome overlap index; the rules below explain the
+highest-risk choices.
 
 - Consider `wa-popup` for low-level anchored positioning when its flip, shift,
   or placement behavior avoids custom positioning code. Prefer the higher-level

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.