@kerfjs/ui 4.4.1 → 5.0.0-beta.3

package/docs/recipes.md

@@ -0,0 +1,116 @@
+# Production composition recipes
+
+These seven reference compositions sit between individual primitives and product
+code. Open each stable UX-catalog route to run it, then copy the linked TSX and
+CSS. The examples import public package subpaths, use semantic layout owners,
+and keep state in a per-instance application adapter. They are not new
+monolithic components.
+
+Copy the recipe source together with the catalog-independent
+[`mount-recipe.ts`](../ux-demo/recipes/mount-recipe.ts) adapter. It mounts the
+controller at one stable application root, uses `delegateActions()` for recipe
+commands, forwards form and dialog lifecycle events, wires resize commits with
+the public `onCommit` callback, retains every disposer, and returns one
+idempotent disposer:
+
+```ts
+import { createRecipe } from './navigation-sidebar.js';
+import { mountRecipe } from './mount-recipe.js';
+
+const root = document.querySelector<HTMLElement>('#navigation')!;
+const stopRecipe = mountRecipe(root, createRecipe(announce));
+window.addEventListener('pagehide', stopRecipe, { once: true });
+```
+
+The adapter is delivered as reference source, not a new package runtime export.
+`delegate()` remains a valid alternative when an application needs selector-
+specific dispatch; either way, wire once at a stable root and retain disposal.
+
+## Desktop application shell
+
+[Open the recipe](../ux-demo/?component=recipe-app-shell) · [TSX source](../ux-demo/recipes/app-shell.tsx) · [shared CSS](../ux-demo/recipes/recipes.css)
+
+Use `Toolbar`, controlled `ResizableRegion` panes, and one
+`.kui-pane__content` scroll owner per pane. The recipe owns the shell topology;
+the app owns routing, responsive pane visibility, sizes, persistence, and data.
+Adapt only public `--kui-layout-*` and component variables.
+
+## Navigation sidebar
+
+[Open the recipe](../ux-demo/?component=recipe-navigation-sidebar) · [TSX source](../ux-demo/recipes/navigation-sidebar.tsx)
+
+One unpadded `.kui-pane` owns toolbar/content/footer structure. Its
+`.kui-content` uses 24px major gaps; `MenuHeader`, `MenuItem`, and other
+`.kui-content-item` children own their 8px margin, 1px border, and 8px padding.
+Rows and footer toolbar groups remain 44px tall. The app owns routes,
+permissions, labels, selection, valid section counts and their localized
+`countLabel` phrases, non-count badge content, disclosure state, and revealed
+content. A toggled `MenuHeader` supplies the production `DisclosureArrow` when
+no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
+
+## Workspace header
+
+[Open the recipe](../ux-demo/?component=recipe-workspace-header) · [TSX source](../ux-demo/recipes/workspace-header.tsx)
+
+`PageHeader` 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.
+
+## Master-detail dialog
+
+[Open the recipe](../ux-demo/?component=recipe-master-detail-dialog) · [TSX source](../ux-demo/recipes/master-detail-dialog.tsx)
+
+The production Web Awesome dialog owns modal focus and Escape; the thin recipe
+adapter restores the invoking control consistently after the hide event.
+`DialogHeader`, `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`.
+Do not rebuild the dialog or reach into private shadow parts.
+
+## Composer form
+
+[Open the recipe](../ux-demo/?component=recipe-composer-form) · [TSX source](../ux-demo/recipes/composer-form.tsx)
+
+Production fields own labels, help, and native focus; semantic layout classes
+compose one visible form surface from exactly three transparent content items:
+introduction, fields, and a footer containing actions plus ownership guidance.
+The three sections retain 8px margin, 1px transparent border, and 8px padding,
+with 24px between major children and 8px inside each section. The app owns
+validation, drafts, permissions, and transport. Persistent error or success
+feedback is the only nested semantic surface and uses `StateBanner`, not a toast.
+Because upgraded Web Awesome fields retain live value properties, controlled
+resets synchronize both those properties and the rendered value attributes;
+the Reset action also announces `Draft reset` through the catalog live region.
+
+## List workspace states
+
+[Open the recipe](../ux-demo/?component=recipe-list-workspace-states) · [TSX source](../ux-demo/recipes/list-workspace-states.tsx)
+
+The same content region moves deterministically through loading, empty,
+populated, stale/background refresh, and error/retry states. The recipe owns
+feedback placement; the app owns fetching, cache age, retry policy, and domain
+rows.
+
+## Compact toolbar choices and actions
+
+[Open the recipe](../ux-demo/?component=recipe-compact-toolbar) · [TSX source](../ux-demo/recipes/compact-toolbar.tsx)
+
+Use `ToolbarControlGroup` for related commands, `SegmentedControl` for a few
+visible exclusive choices, `Select` for a longer value list, and an ordinary
+button for an independent command. The app owns values, actions, persistence,
+and responsive priority.
+
+## Rules shared by every recipe
+
+- Import `@kerfjs/ui/layout.css`; keep every pane unpadded and use exactly one
+  `.kui-pane__content` scroll owner for each real boundary.
+- For direct `wa-*` JSX, import types from `@kerfjs/ui/webawesome`. Import only
+  individual Web Awesome registration modules and theme them with
+  `@kerfjs/ui/webawesome.css`.
+- Prefer public props and variables at the composition boundary. When a recipe
+  needs responsive topology, join only classes listed in the catalog's
+  `publicClasses`; do not copy component markup or select descendants by tag,
+  id, attribute alone, or an unlisted implementation class.
+- Start from the copyable mount adapter, or reproduce its complete boundary:
+  wire stable `data-action` hooks once and retain every disposer.

package/docs/ux-demo.md

@@ -2,17 +2,29 @@
 
 Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation.
 
+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 `MenuActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, and an application-owned native popover relationship without nesting controls.
+- 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.
+- `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 header visibly pairs `View demo source` with `Read guidance`; first-party component details also expose `View component source`. Web Awesome details say `Read Kerf integration guidance` to distinguish the local integration contract from the upstream component implementation. All links show their repository-relative path and use deploy-safe absolute GitHub blob URLs with contextual new-tab names; the demo does not depend on a local source server or add a package runtime export.
+- 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. At narrow widths, the focused `ResizableRegion` specimen moves its committed-width status below the controlled pane while retaining local horizontal access when the pane is resized wider than the stage; its 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 exactly three transparent 8/1/8 content sections 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.
+- 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 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.
 - 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.
+- 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.
 - 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.
 - 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/llms.txt

@@ -4,6 +4,11 @@ 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)
@@ -13,9 +18,27 @@ Accessible, production-backed UI primitives for kerf applications.
 
 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.
 
-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.
+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.
 
-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.
+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.
+
+Composer form recipe: keep the form as one visible surface with exactly three transparent 8/1/8 content sections—introduction, fields, and actions-plus-ownership footer—separated by the 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. 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.
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@kerfjs/ui",
-  "version": "4.4.1",
+  "version": "5.0.0-beta.3",
   "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",
@@ -59,6 +64,11 @@
       "browser": "./dist/browser/toolbar-text.js",
       "import": "./dist/toolbar-text.js"
     },
+    "./menu-action-row": {
+      "types": "./dist/menu-action-row.d.ts",
+      "browser": "./dist/browser/menu-action-row.js",
+      "import": "./dist/menu-action-row.js"
+    },
     "./menu-item": {
       "types": "./dist/menu-item.d.ts",
       "browser": "./dist/browser/menu-item.js",
@@ -112,10 +122,23 @@
       "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",
@@ -140,55 +163,73 @@
       "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",
+    "./toolbar-text.css": "./dist/styles/toolbar-text.css",
+    "./menu-action-row.css": "./dist/styles/menu-action-row.css",
+    "./menu-item.css": "./dist/styles/menu-item.css",
+    "./menu-header.css": "./dist/styles/menu-header.css",
+    "./resizable-region.css": "./dist/styles/resizable-region.css",
+    "./app-tab.css": "./dist/styles/app-tab.css",
+    "./tab-bar.css": "./dist/styles/tab-bar.css",
+    "./page-header.css": "./dist/styles/page-header.css",
+    "./loading-spinner.css": "./dist/styles/loading-spinner.css",
+    "./select.css": "./dist/styles/select.css",
+    "./segmented-control.css": "./dist/styles/segmented-control.css",
+    "./token-search-field.css": "./dist/styles/token-search-field.css",
+    "./state-banner.css": "./dist/styles/state-banner.css",
+    "./empty-state.css": "./dist/styles/empty-state.css",
+    "./dialog-header.css": "./dist/styles/dialog-header.css",
+    "./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",
+    "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 pack --dry-run",
     "prepublishOnly": "npm run check"
   },
   "peerDependencies": {
     "@awesome.me/webawesome": "^3.12.0",
-    "kerfjs": "^4.0.0",
+    "kerfjs": "^5.0.0-0",
     "lucide": "^1.43.0"
   },
   "peerDependenciesMeta": {
@@ -209,6 +250,8 @@
     "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",

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

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

package/ux-demo/recipes/compact-toolbar.tsx

@@ -0,0 +1,43 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/select/register';
+import './recipes.css';
+
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { SegmentedControl } from '@kerfjs/ui/segmented-control';
+import { Select } from '@kerfjs/ui/select';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
+import { ToolbarText } from '@kerfjs/ui/toolbar-text';
+import { signal } from 'kerfjs';
+import { Filter, MoreHorizontal, RefreshCw } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const view = signal('list');
+  const sort = signal('updated');
+  const filtered = signal(false);
+  const render = () => <section class="kui-recipe recipe-compact-toolbar kui-recipe__surface kui-layout" data-recipe="recipe-compact-toolbar">
+    <Toolbar
+      label="Task workspace controls"
+      leading={<ToolbarControlGroup appearance="borderless" single><ToolbarText text="Tasks" size="small" /></ToolbarControlGroup>}
+      center={<ToolbarControlGroup><SegmentedControl id="recipe-view" label="View" value={view.value} action="recipe-action" appearance="toolbar" shape="pill" size="small" choices={[{ value: 'list', label: 'List' }, { value: 'board', label: 'Board' }, { value: 'timeline', label: 'Timeline' }]} /></ToolbarControlGroup>}
+      trailing={<div class="kui-control-cluster"><Select name="recipe-sort" value={sort.value} ariaLabel="Sort tasks" fitMenu choices={[{ value: 'updated', label: 'Recently updated' }, { value: 'priority', label: 'Priority' }, { value: 'owner', label: 'Owner' }, { value: 'created', label: 'Created date' }]} /><ToolbarControlGroup label="Task actions" buttonAppearance="push"><button type="button" aria-label="Toggle filters" aria-pressed={String(filtered.value)} data-action="recipe-action" data-recipe-command="filter"><LucideIcon icon={Filter} name="filter" /></button><button type="button" aria-label="Refresh tasks" data-action="recipe-action" data-recipe-command="refresh"><LucideIcon icon={RefreshCw} name="refresh-cw" /></button></ToolbarControlGroup><button class="kui-recipe__button" type="button" aria-label="More task actions" data-action="recipe-action" data-recipe-command="more"><LucideIcon icon={MoreHorizontal} name="more-horizontal" /></button></div>}
+    />
+    <div class="recipe-compact-toolbar__guide kui-content-item"><div><strong>ToolbarControlGroup</strong><span class="kui-recipe__muted">Related commands or pressed tools.</span></div><div><strong>SegmentedControl</strong><span class="kui-recipe__muted">A few visible exclusive choices.</span></div><div><strong>Select</strong><span class="kui-recipe__muted">A longer controlled value list.</span></div><div><strong>Ordinary button</strong><span class="kui-recipe__muted">One independent command.</span></div></div>
+    <p class="kui-recipe__ownership kui-content-item">The recipe owns control semantics and wrapping. The app owns values, actions, persistence, and responsive priority.</p>
+  </section>;
+  return {
+    render,
+    action(command, element) {
+      const value = element.dataset.segmentValue;
+      if (value) view.value = value;
+      if (command === 'filter') filtered.value = !filtered.value;
+      announce(value ? `View: ${value}` : command === 'filter' ? `Filters ${filtered.value ? 'on' : 'off'}` : `${command} requested`);
+    },
+    change(element) {
+      const value = (element as HTMLElement & { value?: string }).value;
+      if (element.getAttribute('name') === 'recipe-sort' && value) { sort.value = value; announce(`Sort: ${value}`); }
+    },
+  };
+};

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

@@ -0,0 +1,62 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/select/register';
+import '@kerfjs/ui/webawesome.css';
+import '@awesome.me/webawesome/dist/components/button/button.js';
+import '@awesome.me/webawesome/dist/components/input/input.js';
+import '@awesome.me/webawesome/dist/components/textarea/textarea.js';
+import './recipes.css';
+
+import { Select } from '@kerfjs/ui/select';
+import { StateBanner } from '@kerfjs/ui/state-banner';
+import { signal } from 'kerfjs';
+
+import type { RecipeFactory } from './types.js';
+
+type ValueField = HTMLElement & { value: string };
+
+const syncControlledFieldValues = (action: HTMLElement, values: Record<string, string>) => {
+  const form = action.closest<HTMLElement>('[data-recipe="recipe-composer-form"]');
+  if (!form) return;
+  for (const [name, value] of Object.entries(values)) {
+    const field = form.querySelector<ValueField>(`[name="${name}"]`);
+    if (field && field.value !== value) field.value = value;
+  }
+};
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const title = signal('');
+  const body = signal('The tablet layout now keeps navigation, content, and inspector focus order aligned.');
+  const audience = signal('team');
+  const status = signal<'idle' | 'error' | 'saved'>('idle');
+  const render = () => <form class="kui-recipe recipe-form kui-recipe__surface kui-content" data-recipe="recipe-composer-form" noValidate>
+    <header class="recipe-form__section recipe-form__introduction kui-content-item"><h2>Publish workspace update</h2><p class="kui-recipe__muted">Share a concise, actionable update with collaborators.</p></header>
+    {status.value === 'error' && <StateBanner title="Add a title before publishing" detail="The update body and audience are preserved." tone="danger" urgency="alert" />}
+    {status.value === 'saved' && <StateBanner title="Update published" detail="The team audience can now read it." tone="success" />}
+    <div class="recipe-form__section recipe-form__fields kui-content-item">
+      <wa-input name="recipe-title" label="Update title" hint="Summarize the outcome in one line." required value={title.value}></wa-input>
+      <wa-textarea name="recipe-body" label="Details" hint="Include decisions, owners, and the next checkpoint." rows="5" maxlength="400" with-count value={body.value}></wa-textarea>
+      <Select name="recipe-audience" value={audience.value} label="Audience" choices={[{ value: 'team', label: 'Workspace team' }, { value: 'reviewers', label: 'Reviewers' }, { value: 'organization', label: 'Entire organization' }]} />
+    </div>
+    <footer class="recipe-form__section recipe-form__footer kui-content-item"><div class="recipe-form__actions kui-control-cluster"><wa-button appearance="outlined" data-action="recipe-action" data-recipe-command="reset">Reset</wa-button><wa-button variant="brand" appearance="accent" data-action="recipe-action" data-recipe-command="submit">Publish update</wa-button></div><p class="kui-recipe__ownership">The recipe owns field, message, and action rhythm. The app owns validation rules, draft persistence, permissions, and transport.</p></footer>
+  </form>;
+  return {
+    render,
+    action(command, element) {
+      if (command === 'reset') {
+        title.value = '';
+        body.value = '';
+        status.value = 'idle';
+        syncControlledFieldValues(element, { 'recipe-title': title.value, 'recipe-body': body.value });
+        announce('Draft reset');
+        return;
+      }
+      if (command === 'submit') { status.value = title.value.trim() ? 'saved' : 'error'; announce(status.value === 'saved' ? 'Update published' : 'Title required'); }
+    },
+    change(element) {
+      const value = (element as HTMLElement & { value?: string | null }).value ?? '';
+      if (element.getAttribute('name') === 'recipe-title') title.value = value;
+      if (element.getAttribute('name') === 'recipe-body') body.value = value;
+      if (element.getAttribute('name') === 'recipe-audience') audience.value = value;
+    },
+  };
+};