@kerfjs/ui 4.4.1 → 5.0.0-beta.11

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.

package/llms.txt

@@ -1,22 +1,131 @@
 # @kerfjs/ui
 
-Accessible, production-backed UI primitives for kerf applications.
+> 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.
 
-- [Package guide](./README.md)
-- [AI skill](./ai/skill.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)
+```bash
+npm install kerfjs @kerfjs/ui   # kerfjs is a peer; Web Awesome is an optional peer
+```
 
-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.
+Import each component from its own subpath (`@kerfjs/ui/list-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"`.
 
-Public components: `LucideIcon`, `Toolbar`, `ToolbarControlGroup`, `ToolbarText`, `SegmentedControl`, `MenuItem`, `MenuHeader`, `ResizableRegion`, `wireResizableRegions`, `AppTab`, `TabBar`, `wireTabBars`, `reorderTabs`, `PageHeader`, `LoadingSpinner`, `Select`, `StateBanner`, `EmptyState`, `DialogHeader`, and `ValueTable`. `SegmentedControl` is controlled and supports toolbar, rounded-rectangle, and pill presentations with native pressed buttons in sequential Tab order. Semantic state palettes are opinionated, Web Awesome-compatible, and overridable globally, by tone, or per instance.
+## How to build a screen (retrieval order)
 
-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. `@kerfjs/ui/webawesome.css` is an optional CSS-only theme for Web Awesome's free components; 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.
+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).
 
-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.
+## Core rules (do the right thing)
 
-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.
+- **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. For real-app composition it also offers a focusout
+  keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn`,
+  so a sibling suggestions/date popover does not collapse an empty field), opt-in
+  atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via
+  `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an
+  `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — so the app can drop its own keydown/input
+  boilerplate while still owning parsing and controlled token state.
+- **Placeholder loading state, don't rebuild it.** For a value or component that is
+  still loading, set `placeholder` on the component (`Select`, `ListHeader`,
+  `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`,
+  `AppTab`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
+  slots as subtle **unanimated** skeleton blocks and interactivity disabled, so a
+  parent composes a faithful loading view (e.g. an inspector) without hand-rebuilding
+  markup. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
+  (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
+  `LoadingSpinner` for known busy activity instead.
+
+## Public exports
+
+`LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `FloatingToolbar`, `ToolbarText`,
+`PanelHeader`, `ListItem`, `ListActionRow`, `ListHeader`, `SegmentedControl`,
+`Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
+`wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
+`ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
+`LoadingSpinner`, `Skeleton`, `ValueTable`, `ValueTableRow`. Whole-screen layouts (opt-in,
+tree-shakeable, declarative with `wire…` helpers, each with a companion CSS import):
+`NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
+`@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
+shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
++ `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
+`@kerfjs/ui/catalog` is another opt-in shell — a
+`Catalog` component + `wireCatalog` helper for building a component-gallery catalog
+(collapsible category sidebar + preview stage + resources footer) from your own
+entries; controlled/stateless like the layouts. `@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, list-detail dialog, composer form, …) as copyable references.
+- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
+- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists).
+- [component-catalog.json](./ai/component-catalog.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts and exact signatures.
+- [README.md](./README.md): package overview and the component subpath table.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@kerfjs/ui",
-  "version": "4.4.1",
+  "version": "5.0.0-beta.11",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
   "author": "Brian Westphal <brian.westphal@bleugris.com>",
-  "homepage": "https://brianwestphal.github.io/kerf/docs/ui-package/",
+  "homepage": "https://brianwestphal.github.io/kerf/docs/component-packages/",
   "repository": {
     "type": "git",
     "url": "https://github.com/brianwestphal/kerf",
@@ -44,6 +44,11 @@
       "browser": "./dist/browser/lucide-icon.js",
       "import": "./dist/lucide-icon.js"
     },
+    "./disclosure-arrow": {
+      "types": "./dist/disclosure-arrow.d.ts",
+      "browser": "./dist/browser/disclosure-arrow.js",
+      "import": "./dist/disclosure-arrow.js"
+    },
     "./toolbar": {
       "types": "./dist/toolbar.d.ts",
       "browser": "./dist/browser/toolbar.js",
@@ -54,20 +59,30 @@
       "browser": "./dist/browser/toolbar-control-group.js",
       "import": "./dist/toolbar-control-group.js"
     },
+    "./floating-toolbar": {
+      "types": "./dist/floating-toolbar.d.ts",
+      "browser": "./dist/browser/floating-toolbar.js",
+      "import": "./dist/floating-toolbar.js"
+    },
     "./toolbar-text": {
       "types": "./dist/toolbar-text.d.ts",
       "browser": "./dist/browser/toolbar-text.js",
       "import": "./dist/toolbar-text.js"
     },
-    "./menu-item": {
-      "types": "./dist/menu-item.d.ts",
-      "browser": "./dist/browser/menu-item.js",
-      "import": "./dist/menu-item.js"
+    "./list-action-row": {
+      "types": "./dist/list-action-row.d.ts",
+      "browser": "./dist/browser/list-action-row.js",
+      "import": "./dist/list-action-row.js"
+    },
+    "./list-item": {
+      "types": "./dist/list-item.d.ts",
+      "browser": "./dist/browser/list-item.js",
+      "import": "./dist/list-item.js"
     },
-    "./menu-header": {
-      "types": "./dist/menu-header.d.ts",
-      "browser": "./dist/browser/menu-header.js",
-      "import": "./dist/menu-header.js"
+    "./list-header": {
+      "types": "./dist/list-header.d.ts",
+      "browser": "./dist/browser/list-header.js",
+      "import": "./dist/list-header.js"
     },
     "./resizable-region": {
       "types": "./dist/resizable-region.d.ts",
@@ -78,11 +93,23 @@
       "types": "./dist/wire-resizable-regions.d.ts",
       "import": "./dist/wire-resizable-regions.js"
     },
+    "./device-class": {
+      "types": "./dist/device-class.d.ts",
+      "import": "./dist/device-class.js"
+    },
     "./app-tab": {
       "types": "./dist/app-tab.d.ts",
       "browser": "./dist/browser/app-tab.js",
       "import": "./dist/app-tab.js"
     },
+    "./catalog": {
+      "types": "./dist/catalog.d.ts",
+      "import": "./dist/catalog.js"
+    },
+    "./wire-catalog": {
+      "types": "./dist/wire-catalog.d.ts",
+      "import": "./dist/wire-catalog.js"
+    },
     "./tab-bar": {
       "types": "./dist/tab-bar.d.ts",
       "browser": "./dist/browser/tab-bar.js",
@@ -92,10 +119,37 @@
       "types": "./dist/wire-tab-bars.d.ts",
       "import": "./dist/wire-tab-bars.js"
     },
-    "./page-header": {
-      "types": "./dist/page-header.d.ts",
-      "browser": "./dist/browser/page-header.js",
-      "import": "./dist/page-header.js"
+    "./nav-stack": {
+      "types": "./dist/nav-stack.d.ts",
+      "import": "./dist/nav-stack.js"
+    },
+    "./wire-nav-stack": {
+      "types": "./dist/wire-nav-stack.d.ts",
+      "import": "./dist/wire-nav-stack.js"
+    },
+    "./split-view": {
+      "types": "./dist/split-view.d.ts",
+      "import": "./dist/split-view.js"
+    },
+    "./workbench": {
+      "types": "./dist/workbench.d.ts",
+      "import": "./dist/workbench.js"
+    },
+    "./collapsible-panel": {
+      "types": "./dist/collapsible-panel.d.ts",
+      "import": "./dist/collapsible-panel.js"
+    },
+    "./wire-sidebar": {
+      "types": "./dist/wire-sidebar.d.ts",
+      "import": "./dist/wire-sidebar.js"
+    },
+    "./tab-scaffold": {
+      "types": "./dist/tab-scaffold.d.ts",
+      "import": "./dist/tab-scaffold.js"
+    },
+    "./wire-tab-scaffold": {
+      "types": "./dist/wire-tab-scaffold.d.ts",
+      "import": "./dist/wire-tab-scaffold.js"
     },
     "./loading-spinner": {
       "types": "./dist/loading-spinner.d.ts",
@@ -107,15 +161,33 @@
       "browser": "./dist/browser/select.js",
       "import": "./dist/select.js"
     },
+    "./skeleton": {
+      "types": "./dist/skeleton.d.ts",
+      "browser": "./dist/browser/skeleton.js",
+      "import": "./dist/skeleton.js"
+    },
     "./segmented-control": {
       "types": "./dist/segmented-control.d.ts",
       "browser": "./dist/browser/segmented-control.js",
       "import": "./dist/segmented-control.js"
     },
+    "./token-search-field": {
+      "types": "./dist/token-search-field.d.ts",
+      "browser": "./dist/browser/token-search-field.js",
+      "import": "./dist/token-search-field.js"
+    },
+    "./wire-token-search-fields": {
+      "types": "./dist/wire-token-search-fields.d.ts",
+      "import": "./dist/wire-token-search-fields.js"
+    },
     "./select/register": {
       "types": "./dist/select-register.d.ts",
       "import": "./dist/select-register.js"
     },
+    "./webawesome": {
+      "types": "./dist/webawesome.d.ts",
+      "import": "./dist/webawesome.js"
+    },
     "./state-banner": {
       "types": "./dist/state-banner.d.ts",
       "browser": "./dist/browser/state-banner.js",
@@ -126,10 +198,10 @@
       "browser": "./dist/browser/empty-state.js",
       "import": "./dist/empty-state.js"
     },
-    "./dialog-header": {
-      "types": "./dist/dialog-header.d.ts",
-      "browser": "./dist/browser/dialog-header.js",
-      "import": "./dist/dialog-header.js"
+    "./panel-header": {
+      "types": "./dist/panel-header.d.ts",
+      "browser": "./dist/browser/panel-header.js",
+      "import": "./dist/panel-header.js"
     },
     "./value-table": {
       "types": "./dist/value-table.d.ts",
@@ -140,55 +212,83 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./foundation.css": "./src/foundation.css",
-    "./webawesome.css": "./src/webawesome.css",
-    "./styles.css": "./src/styles.css",
-    "./lucide-icon.css": "./src/lucide-icon.css",
-    "./toolbar.css": "./src/toolbar.css",
-    "./toolbar-control-group.css": "./src/toolbar-control-group.css",
-    "./toolbar-text.css": "./src/toolbar-text.css",
-    "./menu-item.css": "./src/menu-item.css",
-    "./menu-header.css": "./src/menu-header.css",
-    "./resizable-region.css": "./src/resizable-region.css",
-    "./app-tab.css": "./src/app-tab.css",
-    "./tab-bar.css": "./src/tab-bar.css",
-    "./page-header.css": "./src/page-header.css",
-    "./loading-spinner.css": "./src/loading-spinner.css",
-    "./select.css": "./src/select.css",
-    "./segmented-control.css": "./src/segmented-control.css",
-    "./state-banner.css": "./src/state-banner.css",
-    "./empty-state.css": "./src/empty-state.css",
-    "./dialog-header.css": "./src/dialog-header.css",
-    "./value-table.css": "./src/value-table.css",
+    "./foundation.css": "./dist/styles/foundation.css",
+    "./layout.css": "./dist/styles/layout.css",
+    "./webawesome.css": "./dist/styles/webawesome.css",
+    "./styles.css": "./dist/styles/styles.css",
+    "./lucide-icon.css": "./dist/styles/lucide-icon.css",
+    "./disclosure-arrow.css": "./dist/styles/disclosure-arrow.css",
+    "./toolbar.css": "./dist/styles/toolbar.css",
+    "./toolbar-control-group.css": "./dist/styles/toolbar-control-group.css",
+    "./floating-toolbar.css": "./dist/styles/floating-toolbar.css",
+    "./toolbar-text.css": "./dist/styles/toolbar-text.css",
+    "./list-action-row.css": "./dist/styles/list-action-row.css",
+    "./list-item.css": "./dist/styles/list-item.css",
+    "./list-header.css": "./dist/styles/list-header.css",
+    "./resizable-region.css": "./dist/styles/resizable-region.css",
+    "./app-tab.css": "./dist/styles/app-tab.css",
+    "./catalog.css": "./dist/styles/catalog.css",
+    "./tab-bar.css": "./dist/styles/tab-bar.css",
+    "./nav-stack.css": "./dist/styles/nav-stack.css",
+    "./split-view.css": "./dist/styles/split-view.css",
+    "./workbench.css": "./dist/styles/workbench.css",
+    "./collapsible-panel.css": "./dist/styles/collapsible-panel.css",
+    "./tab-scaffold.css": "./dist/styles/tab-scaffold.css",
+    "./loading-spinner.css": "./dist/styles/loading-spinner.css",
+    "./select.css": "./dist/styles/select.css",
+    "./skeleton.css": "./dist/styles/skeleton.css",
+    "./segmented-control.css": "./dist/styles/segmented-control.css",
+    "./token-search-field.css": "./dist/styles/token-search-field.css",
+    "./state-banner.css": "./dist/styles/state-banner.css",
+    "./empty-state.css": "./dist/styles/empty-state.css",
+    "./panel-header.css": "./dist/styles/panel-header.css",
+    "./value-table.css": "./dist/styles/value-table.css",
     "./ai/*": "./ai/*",
     "./docs/*": "./docs/*"
   },
   "files": [
     "dist",
-    "src/*.css",
     "ai",
     "docs",
+    "ux-demo/recipes",
     "llms.txt",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup && node ../scripts/clean-dist-output.mjs dist && node scripts/build-browser-entries.mjs",
+    "build": "tsup && node ../scripts/clean-dist-output.mjs dist && node scripts/build-css.mjs && node scripts/build-browser-entries.mjs",
     "dev": "npm run build && vite --config ux-demo/vite.config.ts",
     "demo:build": "npm run build && vite build --config ux-demo/vite.config.ts && node scripts/check-demo-bundle.mjs",
     "demo:serve": "vite preview --config ux-demo/vite.config.ts",
-    "lint": "eslint src tests ux-demo --max-warnings 0",
+    "format:css": "prettier --write \"src/**/*.css\" \"ux-demo/**/*.css\"",
+    "check:format": "prettier --check \"src/**/*.css\" \"ux-demo/**/*.css\"",
+    "catalog:sync": "node scripts/sync-component-catalog.mjs",
+    "check:catalog": "node scripts/sync-component-catalog.mjs --check && node scripts/check-component-catalog.mjs",
+    "check:recipes": "node scripts/check-recipes.mjs",
+    "check:ai-regressions": "node scripts/check-ai-regressions.mjs && node scripts/audit-ai-regression-results.mjs",
+    "check:ai-signatures": "node scripts/sync-ai-public-signatures.mjs --check",
+    "ai:signatures:sync": "npm run build && node scripts/sync-ai-public-signatures.mjs",
+    "ai:regressions:compile": "node scripts/compile-ai-regression-response.mjs",
+    "ai:regressions:prepare": "node scripts/prepare-ai-regression.mjs",
+    "ai:regressions:record": "node scripts/record-ai-regression-run.mjs",
+    "ai:regressions:score": "node scripts/score-ai-regression.mjs",
+    "check:guidance": "node scripts/check-decision-guidance.mjs",
+    "lint": "eslint src tests ux-demo docs/examples --max-warnings 0",
     "typecheck": "node node_modules/typescript7/bin/tsc --noEmit",
     "test": "npm run test:unit && npm run test:bundle",
     "test:unit": "vitest run tests/unit --coverage",
     "test:bundle": "npm run build && vitest run tests/bundle",
+    "test:consumer-types": "npm run build && node node_modules/typescript7/bin/tsc -p tests/consumer-types/webawesome/tsconfig.json",
     "test:e2e": "npm run demo:build && playwright test",
-    "check": "npm run lint && npm run typecheck && npm test && npm run demo:build && npm pack --dry-run",
-    "prepublishOnly": "npm run check"
+    "check": "npm run check:format && npm run check:catalog && npm run check:recipes && npm run check:guidance && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm run check:design-templates && npm pack --dry-run",
+    "prepublishOnly": "npm run check",
+    "check:design-templates": "node scripts/check-design-templates.mjs",
+    "check:design-templates:drift": "node scripts/check-design-templates-drift.mjs",
+    "design-templates:build": "node scripts/build-design-templates.mjs"
   },
   "peerDependencies": {
     "@awesome.me/webawesome": "^3.12.0",
-    "kerfjs": "^4.0.0",
+    "kerfjs": "^5.0.0-0",
     "lucide": "^1.43.0"
   },
   "peerDependenciesMeta": {
@@ -204,11 +304,14 @@
     "@typescript-eslint/eslint-plugin": "^8.65.0",
     "@typescript-eslint/parser": "^8.65.0",
     "@vitest/coverage-v8": "4.1.11",
+    "domotion-svg": "^0.29.0",
     "esbuild": "^0.25.0",
     "eslint": "^10.8.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "happy-dom": "^20.9.0",
     "lucide": "1.43.0",
+    "postcss": "^8.5.28",
+    "prettier": "^3.9.6",
     "tsup": "^8.3.0",
     "typescript": "^6.0.3",
     "typescript7": "npm:typescript@^7.0.2",