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

package/docs/design-philosophy.md

@@ -18,12 +18,27 @@ A reference image defines hierarchy, relationships, and intended feel. It does n
 
 ### Continuity is correctness
 
-Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
+Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. The default owner is the application: domain data and persisted layout preferences — a navigation stack, a selection, a tab order, a pane size, a `collapsed`/`expanded` disclosure flag — are the app's signals, which it reads to render. A `wire…` helper owns only the *ephemeral mechanics* around that state (a push/pop animation, overflow autoscroll, a live resize preview) and reports committed changes through callbacks. A helper takes over a piece of transient state itself only when hand-rolling that behavior is substantial and error-prone enough to cause real, inconsistent variation across apps — `wireTokenSearchFields`'s collapsible reveal/focus/Escape/blur-collapse is the bar; a one-line boolean toggle is not. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
 
 ### Hierarchy precedes decoration
 
 Establish one reading order and one dominant action per decision point. Group first with alignment, spacing, typography, and shared surfaces. A border, fill, badge, or nested card must communicate a real distinction.
 
+### Reach for the primitive, not for CSS
+
+The package is designed to look right *unstyled*. A screen built from the
+primitives, their props, and the semantic tokens should already read well, so
+custom CSS is the exception. Before adding any `padding`, `margin`, `width`,
+`height`, `border`, `background`, wrapper card, or decoration, check whether the
+component, the pane, or the content-item already owns it — it almost always does,
+and adding more usually **double-insets** or fights the component (the most common
+mistake). Trust component defaults: render a control at its natural size and color
+and fix the surrounding layout rather than overriding the control. Legitimate
+custom CSS is limited to genuinely new structure, and even then may only join a
+component's documented `publicClasses` or override documented `--kui-*` tokens at a
+real composition boundary — never size, space, or re-skin a primitive by hand, and
+never build a heading, toolbar, card, or pane geometry that a primitive provides.
+
 ### Panes share one child-owned geometry
 
 Sidebars, main areas, inspectors, and dialogs use the same unpadded pane. Their
@@ -80,6 +95,13 @@ foregrounds compatible with Hot Sheet 2 and Web Awesome. Consumers may replace
 the global palette, one semantic role, or one component instance through
 documented custom properties without rewriting component CSS.
 
+Spacing is likewise a finite, semantic scale, not a free measurement. Five
+canonical steps — 0, 4, 8, 16, and 24px, each a `--kui-space-*` token — map to a
+single relationship apiece, chosen by how connected two elements are: no
+separation, very minor air, standard within a group, between homogeneous groups,
+and major between heterogeneous groups. Off-scale values (12px, 32px) are
+deliberate exceptions. See [`layout.md`](layout.md) "Spacing scale".
+
 ### Responsive design reprioritizes
 
 Protect primary content, readable type, recognizable icons, and usable targets. Relocate secondary information before compressing it below a usable scale. Keep one clear scroll owner per region and test narrow, wide, zoomed, and intermediate layouts.

package/docs/device-class.md

@@ -0,0 +1,54 @@
+# Device class
+
+`@kerfjs/ui/device-class` reports the current viewport as a reactive **device
+class** — a size bucket × orientation × viewport-segment count — so a layout can
+pick its presentation from one signal instead of hand-wiring `matchMedia`. It is
+the foundation the app/dialog layouts build on (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+
+```ts
+import { deviceClass } from '@kerfjs/ui/device-class';
+
+const device = deviceClass(); // ReadonlySignal<DeviceClass>
+
+effect(() => {
+  if (device.value.compact) showStack();
+  else showSplit();
+});
+```
+
+## `DeviceClass`
+
+| Field | Meaning |
+| --- | --- |
+| `size` | `xs-mobile` \| `mobile` \| `tablet` \| `desktop` \| `xl-desktop` |
+| `orientation` | `portrait` \| `landscape` |
+| `segments` / `verticalSegments` | viewport segment counts (foldables / dual-screen); `1` on ordinary devices |
+| `handset` | `xs-mobile` or `mobile` |
+| `compact` | "one pane at a time" — a handset or a portrait tablet |
+| `atLeast(size)` | true when the current size is `size` or larger |
+
+Reading `device.value` inside an `effect`/`computed` re-runs when the viewport
+crosses a breakpoint, rotates, or changes its segment count. One shared viewport
+source backs every reader.
+
+## Breakpoints
+
+Default minimum widths (px): `mobile` 360, `tablet` 720, `desktop` 1024,
+`xl-desktop` 1440. Override per reader:
+
+```ts
+const device = deviceClass({ breakpoints: { tablet: 900 } });
+```
+
+The same numbers are mirrored as CSS custom properties in the foundation
+(`--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`)
+so CSS media queries and the JS signal read one source. `classifyViewport(width,
+orientation, segments?, verticalSegments?, breakpoints?)` is exported as the
+pure, DOM-free bucketing core.
+
+## Server rendering
+
+Without a DOM, `deviceClass()` resolves to an SSR default (1024×768, landscape,
+one segment) and hydrates to the real class on the client. Override the assumed
+viewport with `deviceClass({ ssr: { width, height } })`.

package/docs/layout.md

@@ -38,7 +38,7 @@ 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 `DialogHeader` for
+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
@@ -58,7 +58,7 @@ semantic status.
 | Explicit scroll owner outside a pane | `.kui-scroll-owner` | `overflow: auto` |
 
 The component layer applies the same contract to `Toolbar`, `MenuHeader`,
-`MenuItem`, `PageHeader`, `DialogHeader`, `StateBanner`, `ValueTable`,
+`MenuItem`, `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
@@ -66,12 +66,37 @@ 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.
-`PageHeader` keeps its title on the shared inset while its action border aligns
-with the logical edge of the following `.kui-content-item` border.
-`DialogHeader` applies the same rule internally: its icon/title identity is a
-borderless group in a top toolbar, its direct action children are wrapped in a
-contained group, and its optional subtitle is a separate row aligned below the
-title. The icon visual is 24px inside a 34px circular background.
+`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 `MenuItem` 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
 

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

@@ -56,7 +56,7 @@ no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
 
 [Open the recipe](../ux-demo/?component=recipe-workspace-header) · [TSX source](../ux-demo/recipes/workspace-header.tsx)
 
-`PageHeader` owns the page heading while one control cluster holds secondary,
+`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.
 
@@ -66,10 +66,10 @@ controls relocate without changing focus order.
 
 The production Web Awesome dialog owns modal focus and Escape; the thin recipe
 adapter restores the invoking control consistently after the hide event.
-`DialogHeader`, `MenuHeader`, `MenuItem`, and `ValueTable` own their included
+`PanelHeader`, `MenuHeader`, `MenuItem`, and `ValueTable` own their included
 anatomy. The application owns open state, selection, dismissal policy, and
-record actions. Pass the dialog action children directly; `DialogHeader` places
-them in its top toolbar's action group and uses the localized `actionsLabel`.
+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
@@ -80,7 +80,7 @@ Do not rebuild the dialog or reach into private shadow parts.
 
 [Open the recipe](../ux-demo/?component=recipe-composer-form) · [TSX source](../ux-demo/recipes/composer-form.tsx)
 
-`DialogHeader` supplies the task title and summary, with their ids referenced
+`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
@@ -109,6 +109,18 @@ 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`.
+
 ## Rules shared by every recipe
 
 - Import `@kerfjs/ui/layout.css`; keep every pane unpadded and use exactly one

package/docs/split-view.md

@@ -0,0 +1,49 @@
+# Split view (list-detail)
+
+`@kerfjs/ui/split-view` is a list-detail (master-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

@@ -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,109 @@
 # @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.
+
+## 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`, `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.