@kerfjs/ui 5.0.0-beta.53 → 5.0.0-beta.55

package/docs/ux-demo.md

@@ -10,7 +10,11 @@ launch Chromium, Firefox, and WebKit. The build emits
 `source-freshness.json`; browser coverage compares it with an independent hash
 of the current `src/` and `ux-demo/` inputs, so a stale `dist-demo` cannot pass
 after a route or component edit. `npm run demo:serve` remains a preview-only
-command for an already-built catalog.
+command for an already-built catalog. The demo-conformance preflight also
+rejects a component route that wraps its `CatalogExampleStack` in a card or
+other container (`catalog-demo/wrapped-example-stack`): single-component demos
+sit directly on the catalog grid, and only composition and recipe routes frame
+their content.
 
 Ten lazy production-composition routes live under the `Recipes` category.
 Each `?component=recipe-*` route uses public package primitives, real wiring,
@@ -18,14 +22,14 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 
 - 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` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, pending, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding, closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
+- The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, pending, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding (a new tab opens `pending` with a spinner and stays selectable while its panel shows a `Skeleton` heading until a simulated load completes), closing, keyboard/pointer reordering, and application-owned ordering. 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, and feedback scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component. The former aggregate Web Awesome theme specimen is intentionally omitted because its component families are covered by those focused routes.
 - `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, recommendation, 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. Functional groups follow their authored importance order; components precede compositions inside each group, equal-importance entries use alphabetical order, and the Recipes group comes last. Composition names stay concise and project a visible `Composition` sidebar tag. Non-supported Web Awesome recommendations project to a visible `Discouraged` tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
 - 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. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 15 discouraged choices. 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 supporting copy in its own aligned row; 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 preview scroll owner rather than a viewport-height stage or nested card, and one explicitly repeated SVG tile keeps the pattern continuous through below-fold content. 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 toolbar title/supporting-copy 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 composes `DialogSurface`, the dialog's own labeled header and close control, `SplitView`, and footer actions. Its `SplitView` sits flush in the dialog body, both panes open with a `ListHeader` on one shared line, the dialog title and header text share the 17px text edge, the value table keeps the 8px outer margin, and the trailing actions keep the 16px footer gutter. Compact devices get a full-screen sheet with a list-to-detail drill-down. Browser geometry coverage protects those relationships at wide and narrow widths.
+- The list-detail dialog recipe is laid out like a `Workbench` on roomy devices: a headerless `DialogSurface` modal whose `SplitView` holds a full-height list sidebar `Pane` with its own toolbar beside a full-height detail `Pane` that carries the primary xl title, the `data-dialog="close"` control, and the record actions in its footer. Compact devices get a full-screen sheet with its own labeled header, footer actions, and a list-to-detail drill-down. 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`.

package/docs/webawesome-theme.md

@@ -292,19 +292,28 @@ smallest subtree that needs a different identity:
 ```css
 :root {
   --wa-color-brand-fill-loud: #7540a8;
+  --wa-color-brand-on-loud: #ffffff;
   --wa-color-focus: #7540a8;
   --wa-form-control-border-radius: 0.5rem;
 }
 
 .billing-workspace {
   --wa-color-success-fill-loud: #10a86b;
+  --wa-color-success-on-loud: #1d1d1f;
 }
 ```
 
 The shipped theme pairs every `--wa-color-{variant}-fill-loud` with an
 `--wa-color-{variant}-on-loud` that clears WCAG AA (4.5:1) in both color
-schemes. When you override a loud fill, override its `on-loud` alongside it if
-the pair no longer clears 4.5:1 (for example, white text on a bright fill).
+schemes. When you override a loud fill, set its `on-loud` alongside it, in the
+same selector and at-rule scope, to a foreground that clears 4.5:1 on the new
+fill (white text on a bright fill usually does not: `#10a86b` above reaches
+only 3.1:1 with white, 5.5:1 with `#1d1d1f`). `kerf-ui-analyze` and
+`kerf-ui-doctor` report a loud fill override without a governing `on-loud`, or
+a literal pair that measures below 4.5:1, as review finding
+[`KUI-L018`](./ui-analyzer.md#loud-fill--on-loud-pairing-kui-l018); it cannot
+measure a `var()` or `color-mix()` value, so choosing a readable one is still
+yours.
 
 Use `.wa-light`, `.wa-dark`, and `.wa-invert` for explicit appearance scopes.
 Component-specific custom properties and documented `::part()` selectors from

package/docs/workbench.md

@@ -22,7 +22,22 @@ it can also be embedded. See [Document baseline](document-baseline.md).
 
 `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.
+animates itself. Panels are fixed-size by default; a panel can opt in to drag
+and keyboard resizing (see [Resizable panels](#resizable-panels)), and
+`wireWorkbench` can make overlay panels transient (see
+[Transient overlays](#transient-overlays)).
+
+A collapsed panel renders `inert` and `aria-hidden="true"` on the rail or
+drawer itself, and `inert` on its content, straight from `collapsed`, so
+neither Tab nor assistive technology reaches controls that have slid out of
+view, none of them can scroll back into view, and no empty labeled landmark
+stays behind. The slide-out still animates,
+and the panel's `restoreControl` lives outside the inert content, so it stays
+reachable. Expanding the panel makes its content reachable again in the same
+render. When the panel closes with focus inside it, `wireWorkbench` (given the
+panel's `collapsed` signal) moves focus back out (see
+[Transient overlays](#transient-overlays)); without it, that focus move is the
+app's.
 
 ```tsx
 const navCollapsed = signal(false);
@@ -50,7 +65,8 @@ const navCollapsed = signal(false);
 />;
 ```
 
-Each `WorkbenchPanel` takes `content`, an optional `collapsed`, an optional
+Each `WorkbenchPanel` takes `content`, an optional `toolbar` and `footer` (see
+[Panel toolbars](#panel-toolbars)), 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`. Common shell behavior is configured rather than restyled:
@@ -61,15 +77,372 @@ an optional `label`. Common shell behavior is configured rather than restyled:
 - `contentOverflow: "clip" | "auto" | "visible"` lets a drawer temporarily
   expose an open popup without a descendant override;
 - `presentation: "inline" | "overlay" | "hidden"` supports compact overlays
-  or a responsive replacement. Overlay panels clamp both their track and fixed-size
-  animated content to the configured viewport-relative maximum;
+  or a responsive replacement. An overlay rail spans the Workbench height at
+  its side and an overlay drawer spans the work-area column at the bottom,
+  each exactly at its configured size (its separator border included, as in
+  flow) up to the viewport-relative overlay maximum; the content fills the
+  panel inside its border, so it is clamped with it;
+- `responsiveOverlayAt: "narrow" | "compact" | "never"` presents a rail or the
+  bottom drawer as an overlay below a Workbench container breakpoint — 704px
+  or less for `narrow`, 448px or less for `compact`, the breakpoints of
+  `ResizableRegion`'s `responsiveFillAt` — and inline above it. **Rails
+  default to `narrow`**, so on a small screen a sidebar covers the work area
+  (and an open drawer) instead of squeezing it; pass `never` to keep a rail
+  inline. The drawer stays inline unless it opts in. On a compact (448px or
+  less) Workbench an overlay rail fills the Workbench less a dismiss strip on
+  the side away from its edge — `--kui-workbench-overlay-dismiss-margin`,
+  44px, one touch target — so a press beside it closes it;
+  `compactOverlay: "full"` (per rail) fills the Workbench instead, which
+  usually wants app-level handling of its own. Pass each rail's `collapsed`
+  signal to `wireWorkbench` so only one overlay is open at a time and a press
+  outside closes it. The CSS
+  decides, so the app needs no `deviceClass` check for presentation; a
+  collapsed overlay drops its surface and shadow so nothing covers the work
+  area, and the work area keeps the safe-area inset of the edge the overlay
+  covers. When overlays meet, the order is fixed rather than by which opened
+  last: both rails stack above the drawer, as inline rails span the
+  Workbench's full height beside the drawer's column, and the right rail
+  stacks above the left. Rails take `--kui-workbench-overlay-z` (41) and the
+  drawer one less. Restore controls take `--kui-workbench-restore-z`, which
+  defaults to two less than the overlay z-index (39), so they sit beneath
+  every overlay: an open overlay covers another panel's restore control as
+  it covers the rest of the work area, and a collapsed overlay, which drops
+  its pointer events, leaves the control beneath it usable;
 - `restoreControl` places an application-owned restore affordance in a
-  safe-area-aware viewport corner (`restorePosition` chooses the corner).
+  corner of the Workbench itself while the panel is collapsed. Prefer a
+  `toolbar.toggle`, which the Workbench relocates for you; keep
+  `restoreControl` for a custom affordance. `restorePosition` chooses the
+  corner, inset by
+  `--kui-workbench-restore-inset` (16px) plus the unsafe area of each edge the
+  corner reaches. A rail's control sits in the Workbench's corner; the
+  drawer's sits in the corner of the work-area column it restores into, so it
+  never lands on an expanded rail. A collapsed rail's control floats the
+  same inset above the top edge of an expanded inline bottom drawer, which
+  spans the column reaching that corner once the rail collapses, so it never
+  covers the drawer's content; it returns to the corner when the drawer
+  collapses (the drawer publishes its edge as a CSS anchor scoped to its own
+  Workbench; without anchor positioning the control keeps the corner). An
+  overlay drawer publishes no edge: an open one covers the control, as every
+  open overlay does. Because it is anchored to the Workbench
+  rather than the viewport, an embedded Workbench never floats it over page
+  chrome outside it, and it scrolls with the Workbench. Compose it from the
+  package controls — a `single` `ToolbarControlGroup` around one icon button
+  carrying `collapsiblePanelToggleIcon(side, true)` — rather than a bare
+  button. To give it `FloatingToolbar`'s toolbar role and floating look, wrap
+  that group in a `FloatingToolbar` whose `position` matches the corner: the
+  corner owns the inset (it sets `--kui-floating-toolbar-inset` to 0), so the
+  toolbar floats from the corner instead of doubling it.
+
+- `resizable: true | { min, max }` opts the panel in to drag and keyboard
+  resizing, driven by `wireWorkbench` (off by default).
 
 The same policy props are available on `ResizableRegion` and
 `CollapsiblePanel`, so a resizable application shell does not need to reach
 into `.kui-resizable-region__content`.
 
+## Panel toolbars
+
+A panel's controls follow it open and closed when the Workbench composes the
+toolbars. Give a panel a `toolbar` and the work area a `mainToolbar` (and, for
+a drawer, optionally a `mainBottomToolbar`); the Workbench renders each as a
+standard `Toolbar` over a `Pane`, and moves groups between them as panels open
+and close. A panel's `toolbar` has four parts:
+
+- `title` — the panel's `ToolbarText` (the quiet default size in a rail).
+- `panelOnly` — groups that make sense only while the panel is open. They lead
+  its toolbar, after the title, and are unavailable while it is closed.
+- `constant` — groups that stay available either way. They trail the panel's
+  toolbar while it is open and move to the work area's toolbar while it is
+  closed.
+- `toggle: { action, name }` — the standard collapse toggle, which the
+  Workbench renders: the per-side panel glyph, `aria-controls` naming the
+  panel, `aria-expanded`, a "Show …"/"Hide …" label, and the `data-action`
+  the app handles. It is always the last group.
+
+While a panel is closed, its `constant` groups and then its toggle go to:
+
+| Panel         | Where they go                                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------------------------- |
+| Left rail     | The leading edge of `mainToolbar`, before its `title`                                                           |
+| Right rail    | The trailing edge of `mainToolbar`, after its `trailing` groups, so the toggle is the toolbar's last group      |
+| Bottom drawer | The trailing edge of `mainBottomToolbar`; without one, a `FloatingToolbar` in the work area's bottom-end corner |
+
+A rail with no `mainToolbar` floats its groups in its corner the same way, so
+a closed panel can always be reopened. An open overlay panel carries its own
+toggle, so it never depends on a control it covers. An app's own
+`restoreControl` still wins over the floating fallback.
+
+```tsx
+<Workbench
+  id="studio"
+  label="Studio"
+  mainToolbar={{ label: "Editor", title: <ToolbarText text="Editor" size="xlarge" /> }}
+  main={<Editor />}
+  leftRail={{
+    label: "Navigator",
+    toolbar: {
+      label: "Navigator",
+      title: <ToolbarText text="Navigator" />,
+      panelOnly: <NewFileGroup />,
+      constant: <SearchGroup />,
+      toggle: { action: "toggle-navigator", name: "navigator" },
+    },
+    content: <Files />,
+    collapsed: navCollapsed.value,
+  }}
+/>
+```
+
+The work area's `Pane` can carry more fixed chrome: `mainHeader` renders under
+`mainToolbar` (supporting copy) and `mainFooter` over `mainBottomToolbar` (a status
+line or a resource toolbar), each divided from the scrolling `main`.
+`mainHeaderPlacement` and `mainFooterPlacement` (`"fixed"` by default, or
+`"scroll"`) let that header or footer chrome scroll away with `main` instead —
+useful where large text would leave pinned chrome little room. `mainToolbar` also
+takes the `Toolbar`'s `responsive` / `responsiveAt` policy; `responsive: "wrap"`
+keeps a long title whole and wraps its actions below it.
+
+Size a rail so its title and groups fit at its narrowest (a resizable rail's
+`min`); a toolbar that cannot hold them drops the title rather than
+truncating it. `constant` content renders in both places while the panel is
+closed (the panel's copy is inert), so give it no `id`s. With `wireWorkbench`
+given the panel's `collapsed` signal, focus follows the toggle: closing a
+panel from its own toggle focuses the relocated toggle in the work area, and
+opening it from there focuses the panel's own toggle. A panel's optional
+`footer` renders below its content, for a sidebar's bottom toolbar. Without a
+`toolbar` or `mainToolbar`, `content` and `main` render exactly as given.
+
+## Resizable panels
+
+Resizing is **opt-in per panel**. Give a panel `resizable` — `true` for the
+default limits (rails 180–480px, drawer 120–480px) or `{ min, max }` — and
+render its `size` from an app-owned signal. The panel then owns a separator on
+its inner edge (the left rail's end, the right rail's start, the drawer's top)
+with the same focusable `role="separator"` contract as a `ResizableRegion`
+handle. `wireWorkbench` drives it:
+
+```tsx
+import { wireWorkbench } from "@kerfjs/ui/wire-workbench";
+
+const navSize = signal(280);
+const consoleSize = signal(200);
+
+<Workbench
+  id="studio"
+  label="Studio"
+  main={<Editor />}
+  mainMinSize={320} // the default: the editor never drops below 320px wide
+  mainMinHeight={120} // the default: the drawer leaves it 120px of height
+  leftRail={{
+    content: <Navigator />,
+    label: "Navigator",
+    collapsed: navCollapsed.value,
+    size: navSize.value,
+    resizable: { min: 200, max: 420 },
+    responsiveOverlayAt: "narrow", // an overlay when the Workbench is 704px or narrower
+  }}
+  bottomDrawer={{
+    content: <Console />,
+    label: "Console",
+    size: consoleSize.value,
+    resizable: true,
+  }}
+/>;
+
+// once, after mount:
+const stop = wireWorkbench(root, {
+  id: "studio",
+  panels: {
+    leftRail: {
+      size: navSize,
+      storageKey: "studio.nav-width",
+      collapsed: navCollapsed, // a transient overlay: takes focus, closes on Escape / outside press
+    },
+    bottomDrawer: { size: consoleSize, storageKey: "studio.console-height" },
+  },
+});
+```
+
+- **Pointer:** dragging the separator resizes the panel live (the wire marks
+  it `data-resizing` and suppresses content motion) and commits the final
+  size to the signal on release.
+- **Keyboard:** focus the separator; arrow keys resize by `step` (16px),
+  Shift+arrow by `largeStep` (64px), Home/End jump to `min`/`max`. The
+  separator's `aria-valuenow`/`aria-valuemin`/`aria-valuemax` report the size
+  and limits.
+- **Limits:** every size — dragged, typed, restored from storage, or passed
+  by the app — is clamped to `min`/`max` when rendered.
+- **Work-area minimum:** beside its inline rails, fixed or resizable, the work
+  area keeps at least `mainMinSize` px of width (a `Workbench` prop, default
+  320; `0` turns it off), and above an inline bottom drawer at least
+  `mainMinHeight` px of height (default 120; `0` turns it off). A dragged or
+  keyed rail stops growing where the work area would drop below its width,
+  and the drawer where it would drop below its height, so wide rails or a tall
+  drawer cannot crowd out the editor; `aria-valuemax` reports that reachable
+  maximum. When the Workbench itself narrows, the rails shrink in proportion
+  to their sizes, and when it gets shorter the drawer shrinks (their content
+  follows the shown size) while the work area holds its minimum; a squeezed
+  panel can still be made smaller, never larger, and never below its own
+  `min`. Two fixed 280px rails in a 720px Workbench show 200px each rather
+  than leaving the editor 160px. Each minimum applies only to a Workbench with a
+  panel on its axis, and never exceeds the Workbench itself.
+- **Squeezed below `min`:** when the Workbench is too narrow for a rail's
+  `min` beside the work-area minimum, the rail shows less than its `min` (a
+  172px Navigator whose `min` is 180). Its separator then reports that shown
+  width in `aria-valuenow`, and `aria-valuemin`/`aria-valuemax` pin to the
+  same value: the WAI-ARIA window splitter's value is the separator's actual
+  position, and the range must contain it, so a screen reader hears the width
+  on screen rather than a configured limit the layout cannot honor — and a
+  range that does not move, because the separator cannot move a rail the
+  container holds. A pinned separator commits nothing: arrow keys, Home/End,
+  and drags leave the rail's remembered size (and its storage) alone, so a
+  rail remembered at 280px returns at 280px, with the configured range, once
+  there is room.
+- **Small Workbenches:** inline panels have no shrink floor of their own, by
+  design; the work area's minimums win, so in a very small Workbench a rail or
+  the drawer can become a sliver. Do not add your own `min-width` /
+  `min-height` to hold a panel open. Give the panel
+  `responsiveOverlayAt: "narrow"` (704px of Workbench width or less) or
+  `"compact"` (448px or less) instead: below that breakpoint it presents as a
+  full-size overlay over the work area rather than squeezing beside it (see
+  the catalog's resizable and responsive-drawer Workbench examples).
+- **Collapse:** `collapsed` never changes a size. A collapsed panel keeps its
+  size (its content slides out at that width), its separator leaves the tab
+  order, and expanding it returns it at the size it had.
+- **Persistence:** with a `storageKey`, the size is loaded from `storage`
+  (default `localStorage`) at wire-up and saved on every change, like
+  `wireSidebar`'s collapsed state.
+- **Overlays never resize:** an overlay or hidden panel — including a rail
+  whose `responsiveOverlayAt` breakpoint currently applies — hides its
+  separator and is never resizable, and it leaves the work-area minimum to the
+  rails still in flow. With `responsiveOverlayAt` no device check is needed;
+  otherwise pass `deviceClass` and resizing is suspended while `compact` is
+  true, where rails present as overlay drawers or are replaced.
+- `wireWorkbench` drives only the panels it is given, matched by the
+  Workbench `id`, so it never double-drives a `ResizableRegion` (or another
+  Workbench) under the same root. `onResize({ panel, size, source })` reports
+  each committed resize.
+
+## Transient overlays
+
+An overlay panel covers the work area, so it should open only when the user
+asks for it and close as easily as it opened. Give `wireWorkbench` a panel's
+app-owned `collapsed` signal (`size` is optional, so a panel need not be
+resizable) and it treats the panel as a transient overlay whenever it
+presents as one, mirroring `wireSidebar`'s compact overlay:
+
+- **Collapsed on entering the breakpoint:** when a panel's
+  `responsiveOverlayAt` breakpoint begins to apply — at wire-up, when the
+  Workbench first renders, or when it narrows across the breakpoint — the
+  wiring remembers the panel's inline `collapsed` state and collapses it, so
+  nothing covers the work area until the user opens it. When the breakpoint
+  stops applying (and on disposal) the remembered inline state comes back.
+  These presentation changes skip the collapse motion.
+- **Focus moves in, and Tab stays in:** a panel that opens while it presents
+  as an overlay takes focus on its first focusable control (typically the
+  close control in its header), because it covers the work area and the
+  control that opened it. While it is open, Tab and Shift+Tab cycle through
+  its controls and never reach the covered work area; Escape, its own close
+  control, or an outside press leaves it. This is the ARIA dialog pattern
+  `wireSidebar`'s compact overlay follows. A panel opening inline never moves
+  focus.
+- **Escape** closes the open overlay panel that holds focus, else the most
+  recently opened one. An Escape another handler already handled
+  (`defaultPrevented`) is left alone.
+- **Outside press:** a pointer press that starts and ends outside an open
+  overlay panel closes it. The app's own toggle still works: its click closes
+  the panel before the wiring looks, and the press that opens a panel never
+  closes it.
+- **Focus:** when a panel closes with focus inside it — whatever closed it,
+  including the app's own control inside the panel — focus returns to the
+  control that had it when the panel opened (typically its toggle; one inside
+  another panel that has closed since is skipped), else to
+  the first focusable control in the panel's `restoreControl`, else to a
+  focusable control outside the panel whose `aria-controls` names the panel
+  (or an element inside it). The last is what a panel already open at
+  wire-up relies on, since nothing opened it: give the app's toggle
+  `aria-controls` naming the panel. A pointer press inside the panel that
+  drops focus to the page counts as focus inside: Safari never focuses a
+  clicked button, so pressing the panel's own Hide control blurs the focused
+  control before the click closes it, and focus still returns. Focus the user
+  has moved to another element since is left alone. Each panel's `id` derives from the
+  Workbench's — `<id>-left-rail`, `<id>-right-rail`, `<id>-bottom-drawer`:
+
+  ```tsx
+  <button
+    data-action="toggle-navigator"
+    aria-controls="editor-left-rail"
+    aria-expanded={String(!navCollapsed.value)}
+    aria-label={navCollapsed.value ? "Show navigator" : "Hide navigator"}
+  >
+    <LucideIcon {...collapsiblePanelToggleIcon("left", navCollapsed.value)} />
+  </button>
+  ```
+
+An open overlay can cover the control that opened it: a narrow Workbench's
+right-rail overlay spans the full height at the end edge, over the trailing
+end of the work area's toolbar, where its toggle usually sits. Escape and an
+outside press still close it, but neither is a visible, pointer-reachable
+control. So give every panel that may present as an overlay its own close
+control, as a `CollapsiblePanel` puts its collapse toggle in its own header:
+render the panel content as a `Pane` whose header `Toolbar` holds the title
+and a `single`, borderless `ToolbarControlGroup` around one icon button
+carrying `collapsiblePanelToggleIcon(side, false)`. The work area's toggle
+stays the always-visible way to show the panel. The catalog's resizable
+example does this for both rails.
+
+The drawer works the same way. The catalog's responsive overlay drawer
+example is the whole pattern for a bottom drawer:
+
+```tsx
+const outputCollapsed = signal(false); // open inline by default
+
+<Workbench
+  id="editor"
+  label="Editor"
+  main={<Editor />} // its toolbar toggles `outputCollapsed`
+  bottomDrawer={{
+    label: "Output",
+    content: <OutputPane />, // a Pane whose header holds its close control
+    collapsed: outputCollapsed.value,
+    size: 180,
+    responsiveOverlayAt: "narrow",
+  }}
+/>;
+
+wireWorkbench(root, {
+  id: "editor",
+  panels: { bottomDrawer: { collapsed: outputCollapsed } },
+});
+```
+
+Above 704px of Workbench width the drawer takes its own track below the
+editor. At 704px or less it overlays the bottom of the full-height editor,
+starts hidden, and closes from its own header, on Escape, or on a press
+outside it; widening the Workbench again brings it back inline in the state
+it had before.
+
+Escape and outside-press dismissal apply to static `presentation: "overlay"`
+panels too; entering and leaving the collapsed state around a breakpoint is
+only for `responsiveOverlayAt`, because a static presentation is the app's
+choice. Inline panels are never touched. Pass `dismissOverlays: false` to
+leave every `collapsed` write, and all focus handling, to the app.
+
+Overlays are exclusive by default, like `wireSidebar`'s compact overlays:
+opening a panel while it presents as an overlay closes every other open
+overlay panel, the bottom drawer included. At a narrow width two rails are
+wider than the Workbench, so without this the right rail would cover the
+navigator's own close control. Panels presenting inline are never closed by
+it, so a wide Workbench keeps both rails open. Pass `exclusiveOverlays: false`
+to let overlays stay open together; they then stack in the fixed order above,
+and Tab stays in the one that holds focus (else the most recently opened
+one).
+
+Where the browser supports `overflow-clip-margin`, the 20px hit target
+straddles the panel's separator line like a `ResizableRegion` handle;
+elsewhere it sits just inside the panel's inner edge, because the panel clips
+its sliding content.
+
 ## Resizable application-shell migration
 
 An application such as Hot Sheet can replace its shell descendant overrides
@@ -89,7 +462,13 @@ with state-derived props:
   collapseMotion="fade-slide"
   contentOverflow={createMenuOpen.value ? "visible" : "clip"}
   presentation={mobile.value ? "overlay" : "inline"}
-  restoreControl={<button data-action="show-drawer">Show terminals</button>}
+  restoreControl={
+    <ToolbarControlGroup label="Terminals" single>
+      <button data-action="show-drawer" aria-label="Show terminals">
+        <LucideIcon {...collapsiblePanelToggleIcon("bottom", true)} />
+      </button>
+    </ToolbarControlGroup>
+  }
 >
   <TerminalDrawer />
 </ResizableRegion>
@@ -113,8 +492,9 @@ set `--kui-workbench-rail-width` and `--kui-workbench-drawer-height` on a
 Workbench instance. The supported composition classes are `.kui-workbench`,
 `.kui-workbench__rail`, `.kui-workbench__rail--left`,
 `.kui-workbench__rail--right`, `.kui-workbench__center`,
-`.kui-workbench__main`, `.kui-workbench__drawer`, and
-`.kui-workbench__panel-content`, and `.kui-workbench__restore`; these exact hooks are cataloged for tools that
+`.kui-workbench__main`, `.kui-workbench__drawer`,
+`.kui-workbench__panel-content`, `.kui-workbench__handle`,
+`.kui-workbench__handle-icon`, and `.kui-workbench__restore`; these exact hooks are cataloged for tools that
 must classify public application selectors. Prefer the component props and two
 size tokens before selecting internal anatomy, and do not target its data
 attributes or descendant tags as styling contracts.

package/llms.txt

@@ -80,8 +80,10 @@ the folder modules, and CSS only imports their owner stylesheets.
    [`kerf-ui-doctor`](./docs/ui-doctor.md). Its portable JSON report merges
    profile/catalog, TypeScript, Kerf ESLint, and static analyzer diagnostics;
    CSS-adjacent component props are checked from catalog `cssValueProps`, so
-   prefer its canonical shorthand or typed helper over raw CSS strings;
-   repair source-located errors until exit 0. Use full mode for release gates;
+   prefer its canonical shorthand or typed helper over raw CSS strings; a
+   `--wa-color-{tone}-fill-loud` override without a governing `on-loud` (same
+   or ancestor scope, possibly in a co-loaded stylesheet), or whose literal
+   pair measures below 4.5:1, is review finding `KUI-L018` (set both); repair source-located errors until exit 0. Use full mode for release gates;
    generated `dist`/`coverage`, dependency, cache, evidence, and nested-worktree
    directories are excluded consistently from every static stage.
    [`kerf-ui-analyze`](./docs/ui-analyzer.md) remains available when only static
@@ -185,10 +187,10 @@ the folder modules, and CSS only imports their owner stylesheets.
   `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. For an
   ordinary icon/action control inside the group use a **plain `<button>`** (the
   group styles it fully) — that is the default; reach for `wa-button` only when you
-  need a Web Awesome feature, chiefly the `slot="trigger"` button of a `wa-dropdown`
-  popup menu. 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`). Let the group size the trigger from its icon,
+  need a Web Awesome feature. A toolbar popup menu is a `PopupMenu`
+  (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`)
+  in a `single` `ToolbarControlGroup` with `nestedDropdown`; never hand-write
+  `wa-dropdown` markup for a menu. Let the group size the trigger from its icon,
   localized text, and caret; do not force a dropdown or button width. Compact
   mixed groups keep standard item padding and raised selected chrome without an
   internal separator; the selected item paints over the outer border. For an
@@ -199,7 +201,8 @@ the folder modules, and CSS only imports their owner stylesheets.
   optional icon in a `ToolbarControlGroup`, an extra-large `ToolbarText` directly
   in the leading zone, and actions in a trailing group. Supporting copy is
   app-owned content below. Do not create a private heading wrapper or restyle the
-  toolbar.
+  toolbar. A narrow peripheral rail or drawer, where extra-large would truncate
+  at its minimum size, names itself with the default `ToolbarText` size.
 - **Use `Text` for ordinary semantic headings, paragraphs, and inline secondary
   text outside toolbar title zones.** Omit `variant` for the default `p`, pass
   `h1`–`h6` based on the document outline, or use `variant="span"` inside a row,
@@ -246,7 +249,8 @@ the folder modules, and CSS only imports their owner stylesheets.
   editor focus before the next input task, so shortcut-letter typing stays in search.
   Select All deletion does the same; deletion
   restoration finishes before the next keystroke rather than on a delayed frame.
-  Persist both query and remaining tokens read from an edited field. The one richer case is `wireTokenSearchFields`, which manages the
+  Persist both query and remaining tokens read from an edited field; change
+  `revision` to replace its DOM-owned text programmatically. 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
@@ -322,6 +326,7 @@ shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelTogg
 - [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.
+- [workbench.md](./docs/workbench.md): the `Workbench` multi-panel shell, its collapse policies, and opt-in `resizable` panels driven by `wireWorkbench` (`@kerfjs/ui/wire-workbench`: drag, keyboard, min/max, persistence, compact suspension), the `mainMinSize` / `mainMinHeight` work-area minimums (default 320px wide beside any inline rail, 120px tall above the drawer) that resizable panels stop at and inline panels shrink around, and a panel's `responsiveOverlayAt` (`narrow` / `compact`, rails and the bottom drawer) that presents it as an overlay below a Workbench container breakpoint without a device-class check; a panel given its `collapsed` signal is a transient overlay (collapsed on entering the breakpoint, takes focus and keeps Tab inside while open, closed by Escape or an outside press, focus returned; `dismissOverlays`), and overlays are exclusive by default (opening one closes the others; `exclusiveOverlays: false` opts out).
 - [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
 - [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). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
 - [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.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 selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.53",
+  "version": "5.0.0-beta.55",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,8 @@
   "sideEffects": [
     "**/*.css",
     "./dist/browser/*.js",
-    "./dist/select-register.js"
+    "./dist/select-register.js",
+    "./dist/popup-menu-register.js"
   ],
   "exports": {
     ".": {
@@ -230,6 +231,10 @@
       "types": "./dist/wire-tab-scaffold.d.ts",
       "import": "./dist/wire-tab-scaffold.js"
     },
+    "./wire-workbench": {
+      "types": "./dist/wire-workbench.d.ts",
+      "import": "./dist/wire-workbench.js"
+    },
     "./loading-spinner": {
       "types": "./dist/loading-spinner.d.ts",
       "browser": "./dist/browser/loading-spinner.js",
@@ -264,6 +269,15 @@
       "types": "./dist/wire-token-search-fields.d.ts",
       "import": "./dist/wire-token-search-fields.js"
     },
+    "./popup-menu": {
+      "types": "./dist/popup-menu.d.ts",
+      "browser": "./dist/browser/popup-menu.js",
+      "import": "./dist/popup-menu.js"
+    },
+    "./popup-menu/register": {
+      "types": "./dist/popup-menu-register.d.ts",
+      "import": "./dist/popup-menu-register.js"
+    },
     "./select/register": {
       "types": "./dist/select-register.d.ts",
       "import": "./dist/select-register.js"
@@ -326,6 +340,7 @@
     "./tab-scaffold.css": "./dist/styles/tab-scaffold.css",
     "./loading-spinner.css": "./dist/styles/loading-spinner.css",
     "./select.css": "./dist/styles/select.css",
+    "./popup-menu.css": "./dist/styles/popup-menu.css",
     "./skeleton.css": "./dist/styles/skeleton.css",
     "./sunken-panel.css": "./dist/styles/sunken-panel.css",
     "./segmented-control.css": "./dist/styles/segmented-control.css",