kerfjs 5.0.0-beta.53 → 5.0.0-beta.55

package/CHANGELOG.md

@@ -6,6 +6,537 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+- **New `@kerfjs/ui` `PopupMenu` (`@kerfjs/ui/popup-menu`).** It renders a
+  trigger and typed commands, headings, and dividers over the Web Awesome
+  dropdown. Put it in a `single` `ToolbarControlGroup` with `nestedDropdown`, or
+  wrap it in a `PopupSurface`. Register it once with
+  `@kerfjs/ui/popup-menu/register`. It replaces hand-written `wa-dropdown`
+  markup, which the catalog discourages: the guidance, the toolbar demos, and
+  the Catalog's "Components" menu now use it. It also fixes two defects that
+  hand-written menus had:
+  - Icon-only triggers were unnamed, because a Web Awesome button ignores an
+    `aria-label` on its host. PopupMenu renders `label` as visually hidden text
+    inside the button.
+  - A keyboard choice (Enter or Space) never reached click-delegated
+    `data-action` handlers. PopupMenu's registration routes it through the
+    item's click.
+- The UX catalog's application-layout demo no longer uses the discouraged
+  `wa-button-group`.
+
+- **`@kerfjs/ui`'s `TokenSearchField` takes a `revision` prop for programmatic
+  text replacement.** The editor's text is DOM-owned, so a new `query` with the
+  same tokens was silently ignored, for example when reseeding a persistent
+  dialog's field on reopen. Changing `revision` rebuilds the editor from `query`
+  and `tokens`, so consumers no longer need to re-key a wrapper element.
+
+- **`@kerfjs/ui`'s `TabBar` strip no longer scrolls vertically.** The strip set
+  only `overflow-x: auto`, so any vertical excess (consumer padding, focus-ring
+  insets, taller tabs under larger text) let it scroll up and down on touch. It
+  now scrolls only horizontally, and it takes a `min-height` so it grows to fit
+  taller tabs instead of clipping them.
+
+- **The `@kerfjs/ui` desktop app-shell recipe is a `Workbench`.** The old
+  pane switcher that showed one pane at a time below desktop sizes is gone. The
+  navigation and inspector are now resizable Workbench rails with their own
+  toolbars, and their show toggles relocate into the work-area toolbar. On a
+  narrow container the rails overlay the task list one at a time. The
+  collapsible-sidebar recipe composes each panel's `toolbar` and uses
+  `CollapsiblePanelRelocated` for its restore controls.
+
+- **`@kerfjs/ui`'s `CollapsiblePanel` composes a panel toolbar and relocates its
+  controls.** A panel takes the same `toolbar` roles as a `Workbench` panel
+  (`title`, `panelOnly`, `constant`, and a standard `toggle`) plus a `footer`,
+  and the new `CollapsiblePanelRelocated` renders a collapsed panel's constant
+  groups and toggle wherever the app's work-area toolbar holds them.
+  `wireSidebar` hands focus to that relocated toggle when the panel closes, even
+  when the app renders it a frame late. `collapsiblePanelToggleIcon` is
+  unchanged.
+
+- **`@kerfjs/ui`'s `Catalog` is built on `Workbench` and dogfoods the package's
+  components.** The sidebar is a Workbench left rail with the standard toggle
+  (labels "Show/Hide {brand} catalog"), which moves into the entry toolbar while
+  collapsed; on a small screen the sidebar overlays the stage instead of the
+  former stacked two-column navigation, which is gone. The sidebar, sections,
+  footer, and example notes are `List` / `ListHeader` / `ListInsetText` / `Text`
+  compositions, and most catalog CSS (and every viewport media query in the
+  shell) is removed. New: `Catalog`'s `id`, `headerPlacement`, and
+  `footerPlacement`; `wireCatalog`'s `collapsed` and `id` options (the sidebar is
+  wired like a Workbench rail and an open overlay closes on a selection);
+  `Workbench`'s `mainHeader`, `mainFooter`, `mainHeaderPlacement`,
+  `mainFooterPlacement`, and `mainToolbar.responsive` / `responsiveAt`;
+  `ListInsetText`'s `rootAttributes`. `wireWorkbench` now also re-checks panel
+  breakpoints when the root font size changes, and hands focus to a panel's
+  relocated toggle when an unfocused click on its own toggle closes it (WebKit).
+
+- **`@kerfjs/ui`'s `Workbench` rails overlay the work area on small screens by
+  default.** A rail's `responsiveOverlayAt` now defaults to `"narrow"` (704px
+  of Workbench width; the new `"never"` keeps it inline), so a sidebar covers
+  the work area and any open drawer instead of squeezing it, one at a time
+  with `wireWorkbench`. On a compact (448px) Workbench an open overlay rail
+  fills the width less a 44px dismiss strip
+  (`--kui-workbench-overlay-dismiss-margin`) on the side away from its edge;
+  the new per-rail `compactOverlay: "full"` fills it. The bottom drawer's
+  behavior is unchanged. `WorkbenchPanelToolbar` and the other panel-toolbar
+  types are now exported from `@kerfjs/ui/workbench`.
+
+- **`@kerfjs/ui`'s `Workbench` composes panel toolbars and moves a closed
+  panel's controls into the work area.** A panel takes an optional `toolbar`
+  (`title`, `panelOnly`, `constant`, and a standard `toggle: { action, name }`
+  the Workbench renders) and `footer`; the Workbench takes `mainToolbar` and
+  `mainBottomToolbar`. While a panel is closed its constant groups and toggle
+  move to the work area — a left rail's lead the main toolbar, a right rail's
+  end it, a drawer's trail the bottom toolbar or float in a corner
+  `FloatingToolbar` — and its panel-only groups stay behind. `wireWorkbench`
+  keeps focus with the toggle as it moves. Panels without a `toolbar` render
+  exactly as before, and a region's only-child `Pane` or layout now fills it.
+
+- **`@kerfjs/ui`'s list-detail dialog guidance is Workbench-shaped.** On roomy
+  devices the list is a full-height sidebar and the detail a full-height main
+  column, each a `Pane` with its own top `Toolbar`; the main column carries
+  the primary title, the close control (`data-dialog="close"` in a
+  `without-header` Web Awesome dialog), and the record actions, instead of a
+  dialog header spanning both columns. The recipe, `docs/recipes.md`, and the
+  shipped AI skill say so; compact devices keep the full-screen drill-down
+  sheet.
+
+- **`@kerfjs/ui`'s `ToolbarControlGroup` centers a direct icon tile.** A
+  non-interactive icon placed directly in a group — a heading's identity
+  glyph — now takes an icon button's 40px slot and 16px visual, so it centers
+  in the group. It previously sat at the group's start edge, which pushed
+  apps to wrap it in a focusable `<button>` that did nothing.
+
+- **`@kerfjs/ui`'s `Toolbar` keeps its controls in a top control band.** A
+  toolbar now reserves one 44px band at its top: each zone item no taller than
+  the band is centered in it by its own size, and a taller item — a wrapped
+  `ToolbarText` title, a multi-line search, a second trailing row — starts at
+  the band's top and grows down without moving the others. A wrapped title
+  centers its first line in the band, so trailing controls stay beside that
+  line instead of dropping to the middle of the whole title.
+
+- **`@kerfjs/ui`'s segmented `TabBar` ends its strip concentric with the pill
+  track.** The first tab's leading corners, and with `allocation="fill"` the
+  last tab's trailing corners, now follow the track's curve instead of keeping
+  the small segment radius, and compact tabs are inset from the track's ends
+  by the same distance as from its top and bottom. Corners between tabs are
+  unchanged.
+
+- **`@kerfjs/ui`'s `StateBanner` keeps its title, badge, and detail on one
+  baseline in Safari.** The truncating detail was a clipped `inline-block`,
+  which WebKit baselines at its bottom edge: the detail rose about 2px above
+  the title and pushed the title and badge down, so the banner's contents
+  looked vertically misaligned. The detail is now an inline flex wrapper
+  around a clipped inner `<span>`, which takes its text baseline in every
+  engine; truncation and the narrow-width detail line are unchanged.
+
+- **`@kerfjs/ui`'s `wireTabBars` reveals a tab the application selects.** A
+  tab added and selected by the app in an overflowing `TabBar` stayed
+  off-screen, because the wiring revealed a selection only at wire-up, on
+  focus, and after its own keyboard/drag changes. A change of a bar's selected
+  tab now scrolls that bar's strip (never the page) to show it; re-renders that
+  keep the selection leave a user-scrolled strip alone.
+
+- **`eslint-plugin-kerfjs`'s `ui-composition` rule resolves application
+  wrappers imported through a barrel.** A cataloged wrapper registered only by
+  its defining source file, so `import { DemandSegmentsControl } from
+'./components/index.js'` (where `index.ts` re-exports it) was an unknown
+  element and reported `KUI-L202` in a toolbar zone despite its `rendersAs`.
+  Relative re-exports — `export { X } from`, `export { X as Y } from`,
+  `export * from`, and chains of them — are now followed to the cataloged
+  source file. Type-only and namespace re-exports and non-cataloged components
+  stay unresolved.
+
+- **A collapsed `@kerfjs/ui` `Workbench` panel or `ResizableRegion` leaves
+  the accessibility tree.** Only its content was `inert`, so the labeled
+  `aside` / `section` stayed behind as an empty complementary or region
+  landmark that a screen-reader user could still land on. The collapsed
+  region itself now renders `inert` and `aria-hidden="true"`, like a
+  collapsed `CollapsiblePanel`; its separator was already hidden, and each
+  `restoreControl` renders outside it and stays reachable.
+
+- **An expanded `@kerfjs/ui` `CollapsiblePanel` holds its size in a flex
+  layout.** The panel shrank like any flex item beside a work area with wide
+  content, while its content kept the panel's fixed size for the slide-out, so
+  the panel's edge clipped the content — in the collapsible-sidebar recipe at
+  1280px, the rail showed 211 of its 232px and cut off the selected Inbox
+  row's count. The panel is now `flex-shrink: 0`; the sibling work area gives
+  way instead.
+
+- **`@kerfjs/ui` overlay panels span their host on the fixed axis.** The
+  85vw / 85vh overlay maximums (`--kui-resizable-region-overlay-max-*`,
+  `--kui-workbench-overlay-max-*`) applied to both axes, so an overlay bottom
+  drawer stopped about 15% short of its host's width and an overlay side rail
+  in a full-height layout stopped short of the bottom. Each maximum now caps
+  only the panel's resizable axis: side overlays cap their width, drawers
+  their height.
+
+- **An overlay `@kerfjs/ui` `ResizableRegion` paints the surface.** With
+  `presentation="overlay"` the region floated over the work area with a
+  shadow but no background, so the content beneath — and a collapsed rail's
+  restore control stacked under it — showed through. It now paints
+  `--kui-color-surface`, like an overlay `CollapsiblePanel`; an inline region
+  stays transparent over its host.
+
+- **A pinned `@kerfjs/ui` resize separator no longer overwrites the
+  remembered size.** When a container squeezes a `Workbench` rail, drawer, or
+  `ResizableRegion` below its `min` (or its reachable range collapses to one
+  size), the separator cannot move it, yet an arrow/Home/End key or a drag
+  still committed the configured `min` to the app's size signal and storage:
+  a rail remembered at 280px silently became 180px and came back at 180px
+  when the window widened. A pinned separator now commits nothing, so the
+  track returns at its remembered size once there is room.
+
+- **A `pending` `@kerfjs/ui` `AppTab` is selectable and no longer dimmed.**
+  A known tab that is still opening now keeps its select button enabled and
+  in the roving tab order, so a user can switch to it and the application can
+  show placeholder content in its panel until loading completes. With
+  `webawesome.css` loaded, Web Awesome's native `button:disabled` no longer
+  dims the pending pill to 50%; it shows only its quiet name color and
+  trailing spinner, as documented. Close and dragging stay disabled while
+  pending, and it stays `aria-busy`. An unknown `placeholder` tab is
+  unchanged: disabled and out of the tab order.
+
+- **Closing a `@kerfjs/ui` `Workbench` panel from its own control by mouse
+  returns focus in Safari.** Safari never focuses a clicked button, so
+  pressing an open panel's Hide control blurred the focused control to the
+  page before the click collapsed the panel, and `wireWorkbench` — which
+  returns focus only when it is inside the closing panel — left focus on the
+  page body instead of the toggle that opened it. A press that starts inside
+  the panel while focus is there now counts as focus inside, so the close
+  returns it; focus the user has moved to another element since is left
+  alone.
+- **A collapsed `@kerfjs/ui` `CollapsiblePanel` or `ResizableRegion` leaves
+  the Tab order.** Both kept collapsed content in the DOM, only slid out and
+  clipped, so Tab still reached its controls; focusing one scrolled the clipped
+  panel, and a `CollapsiblePanel`'s `aria-hidden` put those focusable controls
+  inside a hidden subtree. A collapsed `CollapsiblePanel` now renders `inert`
+  beside its `aria-hidden`, and a collapsed `ResizableRegion` renders its
+  content wrapper `inert`, with no wiring needed. The slide-out still animates,
+  each `restoreControl` stays outside the inert subtree and reachable, and
+  `wireSidebar` still hands focus to the panel's toggle when it collapses from
+  inside.
+
+- **A collapsed `@kerfjs/ui` `Workbench` rail's restore control no longer
+  covers an expanded bottom drawer.** A `leftRail` / `rightRail`
+  `restoreControl` floats in the Workbench's bottom corner, which the bottom
+  drawer's column reaches once the rail collapses, so with the drawer expanded
+  the control sat on the drawer's content. An expanded inline drawer now
+  publishes its top edge as a CSS anchor scoped to its Workbench, and the
+  rail's control floats the restore inset above it, returning to the corner
+  when the drawer collapses. An overlay drawer (static or `responsiveOverlayAt`)
+  still covers the control as every open overlay does, a nested Workbench's
+  drawer moves only its own rails' controls, and engines without anchor
+  positioning keep the corner.
+
+- **A collapsed `@kerfjs/ui` `Workbench` panel's content leaves the Tab order.**
+  A collapsed rail or bottom drawer kept its content in the DOM, only slid out
+  and clipped, so Tab still reached its controls; focusing one (at a narrow
+  width, the collapsed inspector's or output drawer's own Hide control)
+  scrolled the clipped panel and slid its hidden content back over the work
+  area. The panel's content wrapper now renders `inert` while `collapsed`, with
+  no wiring needed, so neither Tab nor assistive technology reaches it; the
+  slide-out still animates and the `restoreControl`, which lives outside the
+  content, stays reachable.
+
+- **A `kerfjs/overlay` popover or tooltip in a transformed or filtered modal
+  `<dialog>` now lands against its anchor.** A surface rendered into a
+  dialog's `[data-kerf-overlay-host][data-morph-skip]` slot is
+  `position: fixed`, and a dialog styled with `transform`, `filter`,
+  `perspective`, `contain`, or `will-change` becomes the containing block for
+  fixed descendants, so the surface used to land offset by the dialog's
+  position (and scale). `positionAnchored` (and so `autoReposition`,
+  `popover()`, and `tooltip()`) now measures the element's fixed-position
+  containing block with a transient 1px probe and maps its viewport
+  coordinates into it, compensating translation and scale. Rotated or skewed
+  containing blocks are not compensated.
+- **The `@kerfjs/ui` UX catalog demonstrates a standalone restore control.**
+  The CollapsiblePanel route gains a "Restore control" example: a bottom
+  drawer that collapses to a `FloatingToolbar` `restoreControl` in its frame's
+  corner, wired with `wireSidebar` so the control restores the drawer and
+  focus moves between it and the drawer's own hide toggle.
+
+- **A `@kerfjs/ui` collapsed rail's restore control no longer covers an open
+  bottom drawer beside it.** When a `CollapsiblePanel` or `ResizableRegion`
+  with a `restoreControl` shared its container with an expanded bottom
+  drawer — a bottom `CollapsiblePanel` or bottom `ResizableRegion` — as a
+  sibling or inside the app's work-area column, the control floated in the
+  container's bottom corner, on top of the drawer. It now floats the same
+  inset above the drawer's top edge, follows the drawer as it resizes, and
+  returns to the corner when the drawer collapses. A drawer nested deeper,
+  inside the work area's own content, does not move it. This uses CSS anchor
+  positioning; engines without it keep the container corner.
+
+- **An open `@kerfjs/ui` `CollapsiblePanel` or `ResizableRegion` overlay now
+  covers other panels' restore controls, as a `Workbench` overlay does.** A
+  collapsed panel's `restoreControl` stacked at z-index 42, above
+  `wireSidebar`'s compact overlay and its backdrop and above an overlay
+  `ResizableRegion`, so it floated over an open overlay and stayed clickable
+  behind the overlay's focus trap. `--kui-collapsible-panel-restore-z` now
+  defaults to two less than `--kui-collapsible-panel-overlay-z` (38),
+  `--kui-resizable-region-restore-z` to two less than
+  `--kui-resizable-region-overlay-z` (39), and the compact backdrop's
+  `--kui-collapsible-panel-backdrop-z` to one less than the overlay (still
+  39), so an app that moves the overlay z-index keeps the order. When the
+  overlay closes, the control shows and works again.
+- **An open `@kerfjs/ui` `Workbench` overlay now covers other panels'
+  restore controls.** Restore controls stacked above every overlay, so a
+  collapsed drawer's corner restore control floated over an open right-rail
+  overlay's content. An open overlay is now the top layer, like a sheet over
+  the view beneath it: `--kui-workbench-restore-z` defaults to two less than
+  `--kui-workbench-overlay-z` (39 by default, previously 42), below the
+  drawer and rail overlays. When the overlay closes, the control shows and
+  works again; a collapsed overlay passes pointer events through to it.
+- **`@kerfjs/ui` `wireWorkbench` overlay panels now take focus and keep Tab
+  inside them,** like `wireSidebar`'s compact overlay (the ARIA dialog
+  pattern). An open overlay covers the work area, yet focus stayed on the
+  control that opened it and Tab walked through the covered editor. A wired
+  panel that opens while it presents as an overlay now focuses its first
+  focusable control (usually the close control in its header); while it is
+  open, Tab and Shift+Tab cycle through its controls, and Escape, its own
+  close control, or an outside press leaves it, returning focus to the
+  opener. Panels opening inline never move focus. Focus returned on close
+  also skips an opener inside another panel that has closed since.
+  `dismissOverlays: false` leaves all of this to the app.
+- **`@kerfjs/ui` `Workbench` keeps its work-area minimum beside fixed rails
+  and above the bottom drawer.** `mainMinSize` used to apply only beside a
+  resizable rail, so two fixed 280px rails on a ~730px Workbench left the
+  editor 174px; now every inline rail, fixed or resizable, shrinks in
+  proportion (its content following the shown width) to keep the work area
+  `mainMinSize` px wide. A new `mainMinHeight` prop (default 120, `0` turns it
+  off) is the drawer's counterpart: an inline drawer, fixed or resizable,
+  shrinks when the Workbench gets shorter, and `wireWorkbench` stops a
+  resizable drawer where the work area would drop below that height (reported
+  in `aria-valuemax`) instead of only at the drawer's own `max`.
+- **A `@kerfjs/ui` Workbench rail squeezed below its minimum now reports the
+  width it shows.** When the Workbench was too narrow for a rail's `min`
+  beside the work-area minimum, the rail showed about 172px while its
+  separator still announced `aria-valuenow="180"`. The separator now reports
+  the shown width, with `aria-valuemin` and `aria-valuemax` pinned to it: the
+  WAI-ARIA window splitter's value is the separator's actual position and must
+  sit inside its range, and the separator cannot move a rail the container
+  holds there. Resizing still commits no less than `min`, and the configured
+  range returns once there is room. A `ResizableRegion` a parent clamps below
+  its `min` reports the same way.
+- **`KUI-L018` (`kerf-ui-analyze` / `kerf-ui-doctor`) now measures contrast and
+  follows the cascade.** When a `--wa-color-{tone}-fill-loud` override and its
+  `on-loud` are both literal colors (including `light-dark()`), a pair below
+  4.5:1 in either color scheme is reported with its ratio, and an unpaired
+  literal fill that still clears 4.5:1 against the theme's default `on-loud`
+  is no longer reported. An `on-loud` set in an ancestor scope (`:root`, or the
+  leading selector of a descendant chain) or in another stylesheet the same
+  entry loads now counts as the pair.
+- **`kerf-component-catalog` lets a private application declare components
+  without a fake `exports` map.** In a private package
+  (`"private": true`), a component's `publicExports` items may omit `subpath`; the generator
+  verifies each name against the component's `source` file instead of
+  requiring a `./dist/<path>.js` export the bundled app never emits. Publishable
+  packages still need every subpath in `exports`. The v2 catalog schema makes
+  `subpath` optional to match, and the `kerfjs/ui-composition` rule resolves a
+  subpath-less export only by its source file.
+- **`kerf-ui-doctor` and the `kerfjs/ui-public-boundaries` ESLint rule no
+  longer flag the documented `class="kui-app-root"` as KUI-L101 private
+  anatomy.** The `@kerfjs/ui` component catalog now has a `document-baseline`
+  composition entry for `@kerfjs/ui/document.css` that lists `kui-app-root`
+  as its public class, with a catalog demo route showing a `SplitView` filling
+  the root's definite height.
+- The `@kerfjs/ui` heading guidance (`ai/skill.md`, `llms.txt`,
+  `docs/component-selection.md`, `docs/layout.md`) now sizes a panel title to
+  its track: extra-large `ToolbarText` stays the title size for a page, view,
+  dialog, or pane that holds it, while a narrow peripheral rail or drawer
+  names itself with the default size, since extra-large truncated "Inspector"
+  to "Ins…" in a 160px Workbench rail.
+- **A `@kerfjs/ui` `Workbench` panel open when `wireWorkbench` wired up no
+  longer drops focus to the page when it closes from inside.** Such a panel
+  had no recorded opener, so without a restore control closing it from its
+  own header left focus on `<body>`. Focus now falls back to a control
+  outside the panel whose `aria-controls` names it (or an element inside it).
+  Each panel renders a stable `id` for that — `<id>-left-rail`,
+  `<id>-right-rail`, and `<id>-bottom-drawer` — so a toggle can name the
+  panel it controls.
+- **`@kerfjs/ui` `wireWorkbench` keeps overlay panels exclusive.** At a narrow
+  width two overlay rails could both be open and, together wider than the
+  Workbench, the right rail covered the left rail's own close control. Opening
+  a panel while it presents as an overlay now closes every other open overlay
+  panel, the bottom drawer included, like `wireSidebar`'s compact overlays;
+  panels presenting inline are never closed by it. New option
+  `exclusiveOverlays` (default `true`); pass `false` to let overlays stay open
+  together.
+- **A `@kerfjs/ui` `CollapsiblePanel` or `ResizableRegion` restore control
+  stays inside its container.** `restoreControl` was `position: fixed` to the
+  viewport, so a panel or region embedded in a page floated it over unrelated
+  page content. It now floats in the `restorePosition` corner of the element
+  that holds the panel (or region), scrolls with it, and is inset by the
+  component's restore inset plus the unsafe area of the edges that container
+  reaches, so a full-viewport shell still places it clear of them. While the
+  control is shown, that container isolates its stacking and becomes its
+  containing block; an app that positions the container itself keeps its own
+  `position`. As in `Workbench`, the corner owns the inset, so a
+  `FloatingToolbar` hosting the control no longer doubles it.
+- The `@kerfjs/ui` UX catalog's Workbench page gains a responsive overlay
+  drawer example: an output drawer with `responsiveOverlayAt: "narrow"` that
+  takes its own track beside a wide editor and becomes a transient overlay
+  over the editor's bottom once the Workbench is 704px or narrower, starting
+  hidden there and closing from its own header, on Escape, or on a press
+  outside it. The Workbench guide shows the pattern.
+- A `@kerfjs/ui` `Workbench` now stacks overlay rails above an overlay bottom
+  drawer. With the drawer and a rail both presented as overlays, their order
+  followed the markup, so the drawer covered the left rail while the right
+  rail covered the drawer. Both rails now stack above the drawer, mirroring
+  the inline layout where rails span the full height beside the drawer's
+  column, and the right rail stacks above the left; restore controls stay
+  above every overlay. The drawer's overlay z-index is now one less than
+  `--kui-workbench-overlay-z`.
+- **A `@kerfjs/ui` `Workbench` overlay rail can always be closed from inside
+  itself.** At a narrow width, the UX catalog's inspector overlay covered the
+  editor toolbar's "Hide inspector" toggle, leaving only Escape or an outside
+  press to close it. The catalog's resizable rails now carry their own close
+  control in their `Pane` header, and the Workbench guide recommends the same
+  for any panel that may present as an overlay. `wireWorkbench` now returns
+  focus stranded in a panel however the panel closed — including through the
+  app's own control inside it, and for inline panels — to the control that
+  opened it, else to its restore control; before, only an Escape, an outside
+  press, or a breakpoint collapse returned it.
+- **A `@kerfjs/ui` `Workbench` restore control stays inside its Workbench.**
+  `restoreControl` was `position: fixed` to the viewport, so an embedded
+  Workbench (the UX catalog's, for one) floated it over the page footer. It is
+  now anchored to a corner of the Workbench itself — the drawer's in the
+  corner of the work-area column, so it never covers an expanded rail — inset
+  by `--kui-workbench-restore-inset` plus the unsafe area of the edges that
+  corner reaches, and it scrolls with the Workbench. The Workbench now
+  isolates its own stacking, so its overlays and restore controls never stack
+  against the page around it. A `FloatingToolbar` can host the control
+  without doubling the inset: the corner owns it, and `FloatingToolbar` now
+  honors `--kui-floating-toolbar-inset` set on an ancestor as well as on
+  itself. The catalog's collapsed console restores from such a toolbar.
+- **`@kerfjs/ui` `wireWorkbench` makes overlay panels transient.** A rail
+  whose `responsiveOverlayAt` breakpoint applied stayed expanded over the
+  editor until the user found its toggle. Pass a panel's app-owned
+  `collapsed` signal (`panels: { leftRail: { collapsed } }`; `size` is now
+  optional, so a panel need not be resizable) and, like `wireSidebar`'s
+  compact overlay, the wiring collapses it when the breakpoint begins to
+  apply (without the collapse motion) and gives back its inline state when
+  the breakpoint stops applying or the wiring is disposed. An open overlay
+  panel, responsive or `presentation: "overlay"`, closes on Escape or on a
+  press that starts and ends outside it, and focus stranded inside returns to
+  the control that opened it, else to its restore control. It is on by
+  default for panels given `collapsed`; `dismissOverlays: false` turns it
+  off. The UX catalog's resizable example wires its rails this way.
+- A `@kerfjs/ui` `Workbench` rail with `presentation: "overlay"` now renders
+  exactly its size. Out of flow, it sized to its content plus its 1px
+  separator border, so a 280px rail measured 281px; it now takes its size
+  explicitly, as the responsive overlays do. Rails and the drawer are also
+  `border-box` now, so a panel's `size` is its whole track, border included,
+  even in an app without a global `box-sizing` reset, and overlay content
+  fills the panel inside its separator instead of painting over it.
+- **A `@kerfjs/ui` `Workbench` bottom drawer with `presentation: "overlay"`
+  is visible again.** Its content is positioned against the drawer's bottom
+  edge, so the out-of-flow overlay box had no height of its own and collapsed
+  to its 1px border. An overlay drawer now takes its configured height (220px
+  by default, or its `size`), covers the bottom of the work-area column, and
+  clamps its content to the overlay maximum height. The drawer also accepts
+  `responsiveOverlayAt: "narrow" | "compact"` like the rails: below that
+  Workbench width it presents as the same overlay, without a separator and
+  never resizable, while the work area takes the full height and keeps its
+  bottom safe-area inset beneath it.
+- The bundled AI assistant configs (`ai/skill.md`, `ai/cursorrules`) now
+  explain the `data-kerf-overlay-host` opt-in next to the one-`mount()`-per-root
+  rule: a modal `<dialog>` of your own that anchors kerf popovers or tooltips
+  needs `<div data-kerf-overlay-host data-morph-skip></div>`, the one allowed
+  nested-mount boundary. The `kerfjs/ai-assistant-configs` lint rule reports
+  installed copies as stale until they are refreshed.
+- The opt-in `rebuiltListeners` dev warning no longer reports a popover or
+  tooltip closing inside a modal dialog's host slot. Removals inside a
+  `[data-kerf-overlay-host][data-morph-skip]` slot belong to the surface's own
+  mount, so the enclosing mount now ignores them, as its re-renders already
+  did. A listener lost to a re-render inside the surface is still reported,
+  once.
+- **A popover or tooltip in a modal `<dialog>` no longer lingers after the
+  dialog is removed when its anchor was moved out first.** A surface rendered
+  into a dialog's host slot left with the dialog, but because its anchor was
+  still in the document, kerf kept it registered as open, and a tooltip on
+  that anchor never showed again. A slot-hosted surface now closes itself
+  (without calling `onDismiss`) when it leaves the document, and the tooltip
+  shows again on the next hover or focus.
+- **A popover inside a modal `<dialog>` is reachable by Tab in Safari on
+  macOS.** A popover or tooltip rendered into a dialog's host slot follows the
+  dialog's own Tab order, and WebKit on macOS skips buttons and links there
+  unless the system keyboard-navigation setting is on. kerf now gives each
+  implicitly tabbable control in a slot-hosted surface an explicit
+  `tabindex="0"` when it opens and again before each Tab keypress, the same
+  way its focus trap already did. Authored tabindexes, disabled controls, and
+  surfaces outside a slot are left alone.
+- `@kerfjs/ui` `Workbench` rails gain `responsiveOverlayAt: "narrow" |
+"compact"`, mirroring `ResizableRegion`'s `responsiveFillAt`: below the
+  Workbench's own 704px (`narrow`) or 448px (`compact`) width the rail
+  presents as an overlay over the work area, without a separator and never
+  resizable, and inline above it — the CSS decides, so apps no longer derive
+  `presentation` from a `deviceClass()` check. The bottom drawer ignores it.
+  A collapsed overlay rail (with `presentation: "overlay"` too) now drops its
+  surface and shadow instead of leaving an empty panel-sized box over the work
+  area. The UX catalog's resizable example uses it and now renders at phone
+  widths, and its collapsed console's restore control is a `ToolbarControlGroup`
+  toggle that actually restores the console.
+- `@kerfjs/ui` `Workbench` keeps a minimum work area beside resizable rails.
+  Two rails dragged near their 480px maximum on a ~1024px Workbench used to
+  leave the editor a sliver; now the work area keeps at least `mainMinSize`
+  px (a new `Workbench` prop, default 320, `0` turns it off). `wireWorkbench`
+  stops drag and keyboard resizing where the work area would drop below it
+  (and reports that reachable maximum in `aria-valuemax`), and when the
+  Workbench narrows, resizable rails shrink in proportion to their sizes, with
+  their content following the shown width, instead of squeezing the work
+  area. Workbenches without a resizable rail render exactly as before. The UX
+  catalog's resizable example adds a resizable inspector to show it.
+- `@kerfjs/ui`'s static analyzer (`kerf-ui-analyze`, and the analyzer stage of
+  `kerf-ui-doctor`) reports a new review finding, `KUI-L018`, when a
+  stylesheet overrides a loud tone fill (`--wa-color-{tone}-fill-loud` for
+  neutral, brand, success, warning, danger, or pop) without setting the
+  matching `--wa-color-{tone}-on-loud` in the same scope. The theme pairs each
+  loud fill with a foreground that clears WCAG AA, and an unpaired override
+  keeps that foreground on a fill it was never checked against. The pair must
+  share a selector (after resolving nesting and splitting selector lists) and
+  at-rule scope in the same stylesheet, in one rule or separate ones; another
+  tone's `on-loud` does not count. It is a review finding because it checks
+  the pairing, not the contrast; pass `--fail-on-review` to gate it. The
+  `webawesome-theme.md` customization example now sets both halves of each
+  pair.
+- **Tooltips and popovers also stay visible when your own code opens a modal
+  `<dialog>`.** `kerfjs/overlay` already moved every open tooltip and popover
+  above a modal dialog it opened itself, but a dialog opened with a bare
+  `dialog.showModal()` went unnoticed and left them inert beneath it. While
+  any kerf surface is open, one capture-phase listener on the document now
+  catches the dialog's `toggle` event and re-hosts them the same way, one task
+  after the `showModal()` call. The listener is removed once nothing is open.
+  An engine that fires no `toggle` event for `<dialog>` still misses such a
+  dialog; open it through `overlay()` there.
+- **A popover inside a modal `<dialog>` is clickable.** Browsers make
+  everything outside an open modal dialog inert, so a popover lifted above the
+  dialog was visible but its buttons could not be clicked or focused, and
+  kerf's one-mount-per-tree rule kept it from rendering inside a kerf-mounted
+  dialog. `popover()` and `tooltip()` whose anchor sits inside an open modal
+  `<dialog>` now render into the dialog's host slot, an element marked
+  `data-kerf-overlay-host data-morph-skip`, so they are part of the modal and
+  fully interactive: Tab reaches them, and Escape closes the popover before the
+  dialog. A dialog `kerfjs/overlay` opened gets the slot automatically (an
+  empty `display: contents` element added on first use). For your own
+  `<dialog>`, add `<div data-kerf-overlay-host data-morph-skip></div>` to its
+  markup, or pass `container`. The slot is the one place a second `mount()`
+  may live inside a mounted tree: the enclosing mount's morph, nesting guard,
+  and binding and `each()` marker scans all stop there. The `kerfjs/dev`
+  `inert` warning now fires only when no slot was used.
+- `@kerfjs/ui` `Workbench` rails and the bottom drawer can be drag-resized,
+  as an opt-in per panel. `WorkbenchPanel` gains `resizable: true | { min, max }`
+  (off by default, so existing Workbenches render unchanged); a resizable panel
+  gets a separator on its inner edge with the same focusable
+  `role="separator"` contract, grip, and 20px hit target as a
+  `ResizableRegion` handle. The new `@kerfjs/ui/wire-workbench` subpath's
+  `wireWorkbench(root, { id, panels, deviceClass?, storage?, onResize? })`
+  drives it: live pointer drags, arrow / Shift+arrow / Home / End keys,
+  clamping to the limits, and commits to the app-owned size signals, with
+  optional `storageKey` persistence. Collapsing keeps a panel's size, so it
+  expands back to the size it had, and resizing is suspended on compact device
+  classes and for overlay or hidden panels. The UX catalog's Workbench page
+  adds a resizable example. `wireResizableRegions` now drives only handles that
+  are direct children of a `ResizableRegion`, so it never double-drives a
+  Workbench separator under the same root.
 - `@kerfjs/ui` elevation shadows follow the color scheme, with or without the
   optional `@kerfjs/ui/webawesome.css` theme. Kerf's theme layer set
   `--wa-shadow-s` / `-m` / `-l` to fixed light-mode shadows (14%, 11%, and 9%

package/ai/cursorrules

@@ -1,4 +1,4 @@
-<!-- kerf-skill-version: 1.21.1 -->
+<!-- kerf-skill-version: 1.22.0 -->
 
 # kerf.cursorrules — rules for building apps with kerf
 
@@ -126,7 +126,7 @@ if (import.meta.env.DEV) await import("kerfjs/dev");
 3. **Escape hatches:** `data-morph-skip` (element + subtree preserved verbatim — for Monaco / xterm / D3); `data-morph-skip-children` (attrs morph, subtree preserved — for client-hydrated slots whose host classes change); `data-morph-preserve` (element survives the trailing-removal pass — for imperatively-injected nodes like autoplay videos).
 4. **Never `addEventListener` inside a `mount()`-managed tree** unless under `data-morph-skip`. A morph re-render may discard the node. Use `delegate` / `delegateCapture` instead.
 5. **Capture the `delegate()` / `delegateCapture()` disposer** whenever the registration's scope is shorter than the page. Both helpers return `() => void`; the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state). Discarding the disposer on a transient root (modal, route view, mount swap, dynamic widget) leaks the listener AND the app graph it captures; re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you. Safe to discard only when the registration is truly page-lifetime (root is `document.body` or equivalent, attached once at startup, never torn down).
-6. **One `mount()` per root.** Don't nest. Compose with plain functions that return JSX.
+6. **One `mount()` per root.** Don't nest. Compose with plain functions that return JSX. One exception: a modal `<dialog>` of your own that anchors kerf `popover()` / `tooltip()` surfaces must contain `<div data-kerf-overlay-host data-morph-skip></div>` — kerf renders those surfaces into it (inside the modal, so they are not inert) and that slot is the one allowed nested-mount boundary. Dialogs `kerfjs/overlay` opens get a slot automatically.
 7. **No `<MyComponent />` semantics with hooks.** Components are plain functions returning JSX. State lives in module-scope signals or stores, never in component closures.
 8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX _structure_ depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` will NOT re-render. Bind a STABLE signal/computed instance per hole (a `computed` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (`enableWarnings({ staleBinding: true })` (or `KERF_DEV_WARN_STALE_BINDING=1` under Node) detects it). Endpoint: a render reading NO `.value` runs exactly once — a fully bound mount never re-renders; `enableWarnings({ valueOnlyRerender: true })` (or `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` under Node) flags re-renders that could have been bindings.
 9. **Store actions receive `(set, get)`, not `(state)`.** `set(next)` replaces state; mutating `get()` does nothing.

package/ai/manifest.json

@@ -1,13 +1,13 @@
 {
-  "kerfjsVersion": "5.0.0-beta.53",
+  "kerfjsVersion": "5.0.0-beta.55",
   "files": [
     {
       "name": "skill",
       "source": "kerf.claude-skill.md",
       "bundle": "ai/skill.md",
       "dest": ".claude/skills/kerf-app/SKILL.md",
-      "version": "1.23.1",
-      "sha256": "e21d7db1097ad95c11af9248ad17d514716bebc5646becf57d19a7598d6e382c",
+      "version": "1.24.0",
+      "sha256": "f74616ec20120fa97ec2ff7e92971f5721ee8dcb0b5b7da2dd2604bb87002b69",
       "history": {
         "1.0.0": "bef982cb743fd4c73e666ee5cf774112e57c93ebb13b24bbacbf08577db0930a",
         "1.1.0": "f2aadb21e33dd389028951ae1ecbd9f8ba68648b3c5beba43fb4dfa2ab29f195",
@@ -38,7 +38,8 @@
         "1.21.0": "265b747eeb9c3d445c60d66a1109eec42705075b7cd154d107bd79d543c1e7e5",
         "1.22.0": "dc99b0ca5e911be11cbfa2ae515c0e161a414a5185895069535c41ba56664e70",
         "1.23.0": "28b82b4d31b98814c8fbbe1cb0bcf716192deb494c020b9af41a30830e6a0007",
-        "1.23.1": "e21d7db1097ad95c11af9248ad17d514716bebc5646becf57d19a7598d6e382c"
+        "1.23.1": "e21d7db1097ad95c11af9248ad17d514716bebc5646becf57d19a7598d6e382c",
+        "1.24.0": "f74616ec20120fa97ec2ff7e92971f5721ee8dcb0b5b7da2dd2604bb87002b69"
       }
     },
     {
@@ -46,8 +47,8 @@
       "source": "kerf.cursorrules",
       "bundle": "ai/cursorrules",
       "dest": ".cursorrules",
-      "version": "1.21.1",
-      "sha256": "9b3eb825a7bec05bb6f0138f77b45fadf896b83020178c34c5a2f531c38f4dee",
+      "version": "1.22.0",
+      "sha256": "3515c663e908b2d6dc9a2a9cf42f2a5bf9a5b3a10c79d43e30cc8427e2ce209d",
       "history": {
         "1.0.0": "98f7faff2b7585ef9cc511add42ea5d9bf0cbae8307b066af090e9281136d2ab",
         "1.1.0": "a2ec8c221dc694c98b81009cd2d99f9159a45fda94585de2f54471b227099eda",
@@ -76,7 +77,8 @@
         "1.19.0": "c5b91e449f6feccaa36a04cb7f8550d3e414eb2795ea6c5dccdf6071206b3261",
         "1.20.0": "5e7b8d8ddc41f60220961417c9ae01c193fae045378a10a3e9c96a0e3cf10a03",
         "1.21.0": "a1b663b44650b1a04f89c60b26b002322fc6789650291477e14e13329c3ce25f",
-        "1.21.1": "9b3eb825a7bec05bb6f0138f77b45fadf896b83020178c34c5a2f531c38f4dee"
+        "1.21.1": "9b3eb825a7bec05bb6f0138f77b45fadf896b83020178c34c5a2f531c38f4dee",
+        "1.22.0": "3515c663e908b2d6dc9a2a9cf42f2a5bf9a5b3a10c79d43e30cc8427e2ce209d"
       }
     }
   ]

package/ai/skill.md

@@ -1,7 +1,7 @@
 ---
 name: kerf-app
 description: Build UIs in the kerf reactive framework and its @kerfjs/ui component package (https://github.com/brianwestphal/kerf). Use this skill whenever the user is writing or modifying code that imports `kerfjs` or `@kerfjs/ui`, asks to add a feature to a kerf app, or asks "how do I do X in kerf?". Use it proactively the moment you spot a kerf import in the file you're editing.
-kerf-skill-version: 1.23.1
+kerf-skill-version: 1.24.0
 ---
 
 # Building apps with kerf
@@ -135,7 +135,7 @@ if (import.meta.env.DEV) await import("kerfjs/dev");
    - `data-morph-preserve` — element survives the trailing-removal pass even when the new template doesn't emit it. For imperatively-injected children (autoplay video, tooltip overlay, analytics pixel). Does NOT block a keyed-match move.
 4. **Never `addEventListener` inside a `mount()`-managed tree** unless under `data-morph-skip`. A morph re-render may discard the node. Use `delegate` / `delegateCapture` instead.
 5. **Capture the `delegate()` / `delegateCapture()` disposer** whenever the registration's scope is shorter than the page. Both helpers return `() => void`; the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state). Discarding the disposer on a transient root (modal, route view, mount swap, dynamic widget) leaks the listener AND the app graph it captures; re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you. Safe to discard only when the registration is truly page-lifetime (root is `document.body` or equivalent, attached once at startup, never torn down).
-6. **One `mount()` per root.** Don't nest `mount()` calls. Compose with plain functions returning JSX.
+6. **One `mount()` per root.** Don't nest `mount()` calls. Compose with plain functions returning JSX. One exception: a modal `<dialog>` of your own that anchors kerf `popover()` / `tooltip()` surfaces must contain `<div data-kerf-overlay-host data-morph-skip></div>` — kerf renders those surfaces into it (inside the modal, so they are not inert) and that slot is the one allowed nested-mount boundary. Dialogs `kerfjs/overlay` opens get a slot automatically.
 7. **Components are plain functions.** `<MyComponent props />` works — the JSX runtime calls `MyComponent(props)` and uses the returned JSX — but there's no hook system, no lifecycle, and no per-instance state. State lives in module-scope signals or stores, never in component closures.
 8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX _structure_ depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` does NOT re-render. One caveat on bound holes: bind a STABLE signal/computed instance per hole (`class={computed(() => …)}` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (detectable via `enableWarnings({ staleBinding: true })` (or `KERF_DEV_WARN_STALE_BINDING=1` under Node)). The idiom's endpoint: a render that reads NO `.value` runs exactly once — a fully bound mount never re-renders. To find `.value` holes worth migrating, `enableWarnings({ valueOnlyRerender: true })` (or `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` under Node) flags re-renders whose only differences were text/attribute values.
 9. **Store actions take `(set, get)`, not `(state)`.** `set(next)` replaces state; mutating `get()` does nothing.

package/dist/{chunk-BDX3R4OM.js → chunk-4TX6YJDM.js}

@@ -69,6 +69,12 @@ function wrapWithTags(child, openTag, closeTag) {
   };
 }
 
-export { LIST_MARKER_PREFIX, collectLists, flatten, flattenWithoutListItems, mergeChildSegments, wrapWithTags };
+// src/utils/overlay-host.ts
+var OVERLAY_HOST_SELECTOR = "[data-kerf-overlay-host][data-morph-skip]";
+function isOverlayHost(el) {
+  return el.matches(OVERLAY_HOST_SELECTOR);
+}
+
+export { LIST_MARKER_PREFIX, OVERLAY_HOST_SELECTOR, collectLists, flatten, flattenWithoutListItems, isOverlayHost, mergeChildSegments, wrapWithTags };
 
-//# sourceMappingURL=chunk-BDX3R4OM.js.map
+//# sourceMappingURL=chunk-4TX6YJDM.js.map