kerfjs 5.0.0-beta.50 → 5.0.0-beta.52

package/CHANGELOG.md

@@ -1,15 +1,491 @@
 # Changelog
 
-- Added `wa-dialog.hide-actions` support to `@kerfjs/ui/webawesome.css`, hiding
-  Web Awesome's directly exported `header-actions` shadow part for dialogs that
-  provide their own dismissal affordance.
-
 All notable changes to **kerf** are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+- `@kerfjs/ui`'s `AppTab` adds `pending` for a known tab that is still
+  opening. It keeps the name visible in the quiet text color and uses it as
+  the tab's accessible name, so a trailing spinner's label is not folded in.
+  Like `placeholder`, it disables select and close, turns off dragging, and
+  sets `aria-busy`, and it shows the consumer's `trailing` spinner. It keeps
+  the live tab's pill geometry, so it swaps in place without shifting the bar.
+  Dormant tabs (placeholder or pending) no longer reveal their disabled close
+  button on hover.
+- `@kerfjs/ui`'s `wireSidebar` moves focus into an opening panel without
+  scrolling it. A plain `focus()` scrolled the panel's clipped content to the
+  target while it was still sliding in, then the slide unwound that scroll:
+  a bottom drawer's content jumped up past its top and drifted back. The
+  collapsible-sidebar recipe also floats the drawer's expand toggle in a
+  `FloatingToolbar` at the bottom edge the drawer opens from, and drops the
+  divider under the drawer's toolbar.
+- `@kerfjs/ui`'s `Skeleton` takes `block` (default `false`). It lays the
+  placeholder out as `display: block` instead of `inline-block`, for a
+  skeleton that stands in for a box rather than text: no text line and no
+  baseline gap of its own. `ListItem`'s placeholder icon uses it.
+- `@kerfjs/ui/css-values` adds `remify(px)`, the runtime twin of source
+  CSS's `remify(<px>)`. It turns a pixel count into a rem `CssLength` against
+  the fixed 16px baseline, so `remify(18)` is `1.125rem`. `ListItem`'s
+  placeholder icon now uses it at 18px, and `Skeleton` no longer forces a
+  24px minimum width, so small placeholders keep the size they ask for.
+- `@kerfjs/ui/catalog`'s application-sized (`height: "app"`) example frame
+  no longer loses taps in Safari/WebKit. The frame became the containing block
+  for screen-fixed chrome through `contain: layout`. Combined with its clip,
+  that made WebKit mis-hit-test any transformed element inside an open compact
+  overlay. Every pressed `ListItem` scales, so taps on an overlay rail's items
+  went to their section instead. The frame now uses an identity transform,
+  which docks the same chrome without the bug and renders identically.
+- **Breaking (`@kerfjs/ui/catalog`):** `CatalogExample`'s viewport drops
+  `height: "fill"` and `fillChildren`. The catalog lays examples out at their
+  content height, so neither could give a specimen a definite height, and a
+  child sized with `height: 100%` (a horizontal `ResizableRegion`, say)
+  collapsed to its content. Use a fixed `height` (`short` through `app`) when
+  a specimen must fill its frame. `minHeight` remains, documented as a minimum
+  rather than a fill.
+- `create-kerf-component`'s `kerf.components.json` now accepts an optional
+  `composition.wiring.stateAttributes` declaration (the wiring-owned state
+  attributes `@kerfjs/ui`'s catalog now carries), so third-party
+  component authors can list the `data-*` attributes their wiring helpers write
+  (`{ name, on, helper, meaning }`). `kerf-component-catalog` passes them
+  through to the generated `component-catalog-v2.json` and reports a non-`data-*`
+  name, a duplicate name, an empty `on` or `meaning`, or a helper missing from
+  `wiring.helpers` at its exact path.
+- `@kerfjs/ui`'s component catalog now declares **wiring-owned state
+  attributes**. A new optional `wiring.stateAttributes` in
+  `component-catalog-v2` (and per wiring item in v1) lists each `data-*`
+  attribute a wiring helper writes at runtime, such as `data-handle-inset` and
+  `data-resizing` from `wireResizableRegions`. For each one it records the
+  element, the helper, and the meaning, so AI consumers and tools can tell
+  them apart from attributes the app writes. Every first-party wiring helper
+  is declared. `check:catalog` fails when a helper's declarations differ from
+  what its source writes.
+- `@kerfjs/ui`'s `wireSidebar` no longer leaves focus inside a panel it just
+  collapsed. When the collapse was triggered from a toggle inside the panel
+  (the documented placement), focus now moves to that panel's toggle outside
+  it, including one the app renders only once the panel is collapsed. The
+  collapsible-sidebar recipe now shows one control per action: each panel's
+  own collapse toggle while it is open, and the main header's expand toggle
+  only while it is collapsed. Wide widths no longer show two rail toggles.
+- `@kerfjs/ui`'s `wireSidebar` keeps a compact overlay intact when the app
+  re-renders the wired root without changing a panel. Previously, selecting a
+  destination in an open compact rail morphed the root, which removed the
+  overlay attributes and the backdrop, and the "overlay" rail fell back into
+  the layout. The wire now re-applies its host attributes and backdrop after
+  any such re-render, and the backdrop carries `data-morph-preserve`.
+- `@kerfjs/ui`'s `wireSidebar` now opens a compact overlay only on a user
+  action. Wiring on a compact device, or crossing from a wide device class to
+  a compact one, collapses every panel. The page is no longer covered by a
+  backdrop and focus trap until dismissed. Crossing back to a wide class, or
+  disposing the wire, restores each panel's remembered inline state.
+  Persistence now stores only that inline choice, never an overlay's
+  open/closed state. A new optional `WireSidebarPanel.inlineCollapsed`
+  declares the inline default when an app seeds its signal from the device
+  class, which avoids an open first frame on a compact device. The
+  collapsible-sidebar recipe no longer opens its rail as a blocking overlay
+  on load at compact widths.
+- `@kerfjs/ui`'s `ResizableRegion` handle keeps its hit target and focus ring
+  whole at a clipping edge. When a parent clamps the region to its own edge
+  (the catalog's 390px stage, an app shell with a `max-width` container),
+  `wireResizableRegions` marks the region `data-handle-inset` and the handle
+  moves inside it instead of overhanging the edge by 10px, where the frame cut
+  its focus ring in half. The ring is now drawn inside the handle's box
+  (`outline-offset: -3px`), so it is also no longer shaved where the region's
+  ends meet a clipping edge.
+- `@kerfjs/ui`'s `wireResizableRegions` keeps a clamped separator's
+  `aria-valuenow`/`aria-valuemax` current at rest. Previously, after a size was
+  saved at a wider width, narrowing the parent or any unrelated re-render left
+  the handle reporting the unclamped rendered size until it was next focused or
+  resized. A `ResizeObserver` on each region and its parent and a
+  `MutationObserver` for re-renders now re-clamp the report; the disposer
+  disconnects both.
+- The `@kerfjs/ui` catalog's `height: "app"` example frame is now the
+  containing block for screen-fixed chrome, so a compact `CollapsiblePanel`
+  overlay, its backdrop, and restore controls dock to the frame's edges. The
+  collapsible-sidebar recipe's compact rail was fixed to the page's left edge,
+  24px outside the inset frame, so its leading edge looked cut off at 390px.
+- The `CollapsiblePanel` compact-overlay backdrop now covers its whole
+  containing block. As a `<button>`, it did not stretch between its insets and
+  scrimmed only a 35px strip.
+- `@kerfjs/ui`'s `wireResizableRegions` now bounds a resize to the space the
+  region's parent actually leaves. When a parent clamps the track (a
+  `max-width` stage, a narrow container), pointer and keyboard resizing stop at
+  the visible size, and the separator reports that size in `aria-valuenow` and
+  its visible maximum in `aria-valuemax`. Previously a region resized to 420
+  inside a 340px stage announced 420 and needed several key presses before the
+  separator moved. Focusing the handle reports a stale larger committed size as
+  the shown size without committing it.
+- The UI evaluator's `KUI-B050` target-size rule now accepts a 44×36 target
+  inside compact density (`[data-density="compact"]`), matching the 36px
+  compact row height; standard density still requires 44×44, and the width
+  floor is unchanged.
+- Fixed `kerf-ui-analyze` and the `eslint-plugin-kerfjs` UI rules treating
+  every name in a catalog entry's `publicExports` as that entry's component,
+  so a helper such as `uiColor` or `flex` called with an object whose keys
+  matched a contract path (`uiColor({ choices: [...] })`) was checked as a
+  `Select` or `List` call. Only component exports, whose names start with an
+  uppercase letter as JSX component tags do, now resolve to an entry; the
+  `@kerfjs/ui` catalog check fails if a cataloged `SafeHtml` render function
+  is lowercase or any other runtime export is uppercase.
+- The `@kerfjs/ui` component catalog's `ToolbarText` entry now lists every
+  token its `xlarge` size reads (`--kui-color-text`, `--kui-font-l`,
+  `--kui-font-2xl`) in `publicTokens`; previously it named only the tokens of
+  the smaller sizes.
+- The `@kerfjs/ui` browser evaluator's target-size check (`KUI-B050`) now
+  measures the pointer-reachable area instead of only the border box: an
+  undersized control is hit-tested outward from its center, so a transparent
+  `::before`/`::after` hit layer (such as the `ListHeader` action's) counts,
+  while `pointer-events: none` decoration, clipping, and overlapping
+  neighbors do not. Diagnostic evidence now carries the measured size plus
+  the border `box`.
+- Fixed the `eslint-plugin-kerfjs` `ui-css-values` messages (`KUI-L013`,
+  `KUI-L014`, `KUI-L017`) listing suggested helpers with unbalanced backticks
+  (``use `uiColor() or `foregroundColorVar().``); each helper is now wrapped
+  as `` `uiColor()` ``.
+- Fixed `kerf-ui-analyze` skipping the CSS-value contracts of `@kerfjs/ui`
+  `Select` and `Skeleton`. Its component lookup was keyed by display name, so
+  the same-named Web Awesome catalog entries (`wa-select`, `wa-skeleton`) —
+  which carry no CSS-value props — shadowed them, and a wrong-grammar helper
+  such as `colorVar()` for `SelectChoice.color` went unreported although the
+  ESLint rule caught it. Entries now resolve by `package:id`, using the
+  selection catalog's public exports and import subpaths.
+- Fixed `@kerfjs/ui` monospace text rendering in the generic face (Courier on
+  macOS Chromium) whenever Web Awesome was loaded: `--kui-font-mono` deferred to
+  Web Awesome's `ui-monospace, monospace`, which Chromium does not resolve, and
+  the trailing generic `monospace` kept Kerf's named fallbacks from ever
+  applying. `--kui-font-mono` is now Kerf's own stack (`ui-monospace,
+SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace`),
+  and the Web Awesome theme points `--wa-font-family-code` at it so Kerf `Text
+font="monospace"` and Web Awesome code text match.
+- The `@kerfjs/ui` Web Awesome theme now gives default-size single-line
+  controls Kerf's 44px control height, so a plain `wa-input` or `wa-button`
+  sits flush beside a Kerf `Select` instead of about 9px shorter. It sets
+  `--wa-form-control-height` to `2.75em` (44px at the default size) on Button,
+  Color Picker, Input, Known Date, Number Input, Radio Group, Select, Textarea,
+  and Time Input; `size="large"` scales proportionally, `size="small"` keeps Web
+  Awesome's compact height, and buttons inside a `ToolbarControlGroup` keep the
+  group's 40px (32px compact) height. Tags, copy buttons, and toasts are
+  unchanged.
+- Fixed an `@kerfjs/ui` `Select` menu drawing two separators when a choice with
+  `separatorBefore` opened a separated group: the group's border plus a
+  `wa-divider` left an empty band between the group title and its first
+  choice. `separatorBefore` now only divides a choice from the previous choice
+  in the same list; a group boundary is already the single separator.
+- Fixed `@kerfjs/ui` compact `ToolbarControlGroup` end highlights not being
+  concentric with the group: controls sat 2px from the sides but 1px from the
+  top and bottom. A compact group now has no padding, so its 32px controls sit
+  on a 1px inset on every side with a radius of the group radius minus 1px
+  (pill and rounded). In compact mixed groups the raised selection still paints
+  over the border with the group's radius, neighboring controls still abut, and
+  the trailing dropdown trigger keeps the 1px end inset instead of running onto
+  the border. Compact groups are 2px narrower as a result.
+- Added `Toolbar.safeAreaEdges` to `@kerfjs/ui` so an app bar or bottom bar
+  that sits at a screen edge, outside any `Pane` header or footer, can claim
+  those edges for device safe areas. A toolbar there used to take only the
+  inline edges an owner handed it, so the app-shell recipe's top bar never
+  cleared the status area. Each claimed side pads by the routed
+  `--kui-edge-inset-*` context, or the full device inset when nothing routes
+  it, while the bar's surface and divider still paint through; the minimum
+  height grows with the claimed block insets so a shrinking flex column keeps a
+  whole control row clear. A claim inside a `Pane` header or footer adds
+  nothing, since the pane already owns those edges. The app-shell recipe's app
+  bar now claims the top edge and both sides.
+- Fixed `@kerfjs/ui` slide-motion `ResizableRegion` content overflowing its
+  separator when a parent clamps the region. The expanded content kept the
+  committed size even when a `max-width` or narrow container held the track
+  smaller, so in the catalog at 390px a region resized to 420px showed text
+  running past its handle. Expanded content now follows the region's actual
+  track on both axes; the fixed expanded size still applies while collapsing, so
+  the collapse keeps reading as a slide.
+- Fixed `@kerfjs/ui` `ResizableRegion` panes stopping at their content's
+  height. The region's content now spans the whole region, like its separator,
+  and a lone child (normally a `Pane`) fills it, so the app-shell recipe's
+  navigation and inspector panes reach the bottom edge and scroll long content
+  inside their own content slot instead of ending partway down the region.
+  Several children still stack at their natural height.
+- Fixed `@kerfjs/ui` `Toolbar responsive="center-priority"` leaving an
+  expanded center control at roughly half the row on narrow toolbars. The
+  policy set the toolbar's own grid template inside a container query on the
+  toolbar itself, which can never match, so the center kept only the first
+  column track once the leading and trailing zones left. The dead rule is gone
+  and the expanded center now spans every column track, filling the toolbar's
+  content width at phone widths.
+- Fixed a nested `@kerfjs/ui` `List`, `Row`, or `Grid` inheriting its
+  ancestor's `gap` and `flex`. Those props travel through private custom
+  properties, which inherit, so a nested `List` without its own `gap` took the
+  enclosing `List`'s gap (a heading unit inside a form got a 24px gap between
+  its title and supporting line) and any nested instance without `flex` took the
+  ancestor's flex growth. Every instance now resets its private values, so an
+  omitted prop means that component's own default. The workspace-header recipe's
+  breadcrumb now sits directly above its title and the List demo's section rows
+  sit flush under their header, as intended.
+- Fixed `@kerfjs/ui` slide-motion `ResizableRegion` content staying at its
+  previous width during a live resize until the app re-rendered the committed
+  size. `wireResizableRegions` now applies the live size to the sliding content
+  as well as the track, for pointer drags and key presses, so the content fills
+  the region (including a safe-area edge extent) throughout the drag and a later
+  collapse still slides it out at the resized width.
+- Fixed the `@kerfjs/ui` `ListHeader` action's pointer target being only its
+  fitted 36px square although the guidance promises 44px. A transparent hit
+  layer now extends the target to at least 44 × 44 around the square without
+  moving layout or enlarging the painted hover surface. Compact headers are
+  36px tall like the rest of the compact List family, so their action target is
+  44px wide and clamped to the header height, never reaching into a neighboring
+  row.
+- Fixed re-renders closing open Web Awesome popups: the morph (and the keyed-list
+  attribute fast path) no longer removes a live `open` attribute from custom
+  elements (`wa-select`, `wa-dropdown`, `wa-dialog`, …) when the template omits
+  it — the same user-agent-owned treatment `<details>` / `<dialog>` already
+  had. A template can still set `open`; closing stays imperative.
+- The `@kerfjs/ui` composer-form recipe's supporting line now sits directly
+  under its toolbar title instead of 24px lower, because a nested `List` no
+  longer inherits the form's section gap (see the nested `List`/`Row`/`Grid`
+  fix above). The guidance now
+  also states that `ToolbarText` below `xlarge` is intentionally quiet identity
+  text with no tone option. A normal-color subsection title is `Text` with an
+  `h2`–`h6` variant, or `ListHeader` for a list or menu section.
+- Fixed `@kerfjs/ui` `ToolbarText size="small"` labels rendering in a
+  monospace fallback face in Chromium. The small size used the code-font token,
+  which resolves through Web Awesome's `ui-monospace, monospace` stack; Chromium
+  does not recognize `ui-monospace`, so labels such as a pane's "Workspace" or
+  "Ready" fell back to the generic monospace font. Every `ToolbarText` size now
+  keeps the inherited UI sans stack.
+- Fixed `@kerfjs/ui` `ListInsetControl` not stretching its control as
+  documented. Its `justify-content: stretch` is a no-op on a flex row, so a
+  `Select`, `wa-input`, or `wa-button` inside stayed at its natural width. Each
+  direct child now grows to fill the inset row (several children share it with
+  the 8px gap) and may shrink below its intrinsic width instead of overflowing.
+- `@kerfjs/ui` `List`, `Row`, and `Grid` can now be the layout root of a
+  fixed-height parent. New `fill` takes the parent's full height (use `flex`
+  inside a flex layout as before), and new `rootAttributes` carries safe
+  `data-*` metadata while the component's structural attributes stay
+  protected. The app-shell and collapsible-sidebar recipes now use a filling
+  List or Row root instead of a frame `Pane` whose scroll owner never scrolled;
+  the collapsible sidebar's rail and drawer now reach the real frame edges, so
+  they paint through safe areas as the layout model intends. The UX catalog
+  adds an application-sized `height: "app"` (592px) specimen frame, and both
+  recipes use it instead of the cramped 360px `tall` frame.
+- Fixed a `@kerfjs/ui` stacked `Toolbar` clipping its last trailing action at
+  phone widths (the compact-toolbar recipe's "More" button at 390px). A
+  toolbar's trailing zone now wraps whole control groups onto another
+  trailing-aligned row under every `responsive` policy, and a
+  `responsive="stack"` toolbar wraps its stacked center and trailing groups the
+  same way, so no action is ever clipped or shrunk. Stacked zones also span the
+  full toolbar width; they previously lost 16px to empty column tracks. New:
+  `responsive="wrap"` keeps a heading on one row while everything fits and
+  otherwise moves the trailing zone below a whole title instead of truncating
+  it. The loading-inspector recipe uses it, so its narrow heading shows the
+  whole record title instead of an ellipsis.
+- `@kerfjs/ui` layouts and `Pane` now handle device safe areas as one model.
+  Pane and panel backgrounds, separators, and dividers paint through unsafe
+  areas; content is padded only on the edges a region actually reaches, and
+  block insets become scroll padding so content can scroll under the status bar
+  or home indicator but always scroll clear. `Workbench` rails and drawer,
+  `CollapsiblePanel`, and the `SplitView` list grow by the inset they dock to.
+  A center pane picks up the inset when an adjacent rail collapses, and
+  interior or nested edges are never double-inset. A header or footer `Toolbar`
+  keeps its dividers edge to edge. New: `Pane.safeAreaEdges` (default all
+  sides; `[]` opts out), the `--kui-safe-area-*` device-inset tokens (default
+  `env(safe-area-inset-*)`), the inherited `--kui-edge-inset-*` edge context for
+  app-owned layouts, and `--kui-resizable-region-edge-extent`. Nothing changes
+  on devices or pages without safe-area insets.
+- Fixed a `@kerfjs/ui` `ListHeader` action sitting about 4px outside the
+  trailing toolbar action of the Pane header above it. Its fitted action now
+  centers in the same 44px slot a toolbar control occupies at the 8px inline
+  margin, so trailing icon actions share one axis. The action's size, 18px
+  visual, and hover square are unchanged.
+- **Breaking (`@kerfjs/ui`, 5.0 beta):** `SelectChoice.color` now accepts only
+  a foreground color, the new `CssForegroundColor` brand from
+  `@kerfjs/ui/css-values`. `uiColor()` returns it for foreground token names
+  (the new `UiForegroundColorName`: the `*-on-*` roles, `text`, `text-quiet`,
+  `text-link`, and the `*-text` aliases), and the new
+  `foregroundColorVar('--app-icon-color', fallback?)` returns it for an
+  application-owned property. The `--kui-color-success` / `warning` / `danger`
+  / `pop` / `accent` compatibility aliases are quiet fills that read like
+  foreground colors; colored with one, an icon rendered at about 1.2:1
+  contrast. `uiColor('success')` and the other fill, border, and surface tokens
+  still return a plain `CssColor` and no longer type-check as an icon color,
+  and neither does a plain `colorVar()` value. Migrate
+  `color: uiColor('success')` to `uiColor('success-on-quiet')` and
+  `color: colorVar('--app-color')` to `foregroundColorVar('--app-color')`;
+  `uiColor('…-on-…')` calls keep compiling unchanged. The catalog's CSS-value
+  contract for `choices[].color` lists `uiColor` and `foregroundColorVar`, so
+  `eslint-plugin-kerfjs` also reports `colorVar()` there (`KUI-L014`), and
+  the source and packed consumer type contracts pin the rejected fills.
+
+- Fixed an `@kerfjs/ui` icon-only `Select` beside other controls in one
+  `ToolbarControlGroup`. A compact Select no longer eats 1px of the group's
+  4px gap on each side (the lone-trigger padding overlap now applies only when
+  it is the group's only child), a compact rounded Select uses its siblings'
+  item radius instead of the lone-slot radius, and the Select now shows the
+  same hover pill as its sibling buttons (a lone Select lifts the whole group,
+  like a popup-menu dropdown). In a group with per-control focus rings
+  (`focusRing="control"`, the default) the Select paints the same ring as its
+  siblings even when `focusRingOwner="group"` was set, which previously left it
+  with no visible focus. A compact icon-only `<button>` is now a 32px circle,
+  so a selected compact segment is no longer a 34x32 oval. The
+  ToolbarControlGroup catalog adds a "Select beside actions" example.
+
+- Changed the `@kerfjs/ui` icon-only `Select`
+  (`selectedPresentation="icon-only"`) to keep its disclosure caret. The
+  selected icon and caret now form one pill with the same geometry as a
+  `ToolbarControlGroup` popup-menu `wa-dropdown` trigger: 8px inline padding on
+  both sides, 12px from the icon to the caret, the same caret glyph size, and a
+  40px default or 32px compact control height, so the icon sits left of center
+  to balance the caret. In a single `ToolbarControlGroup` the group now sizes to
+  the trigger (a 70x44 default or 68x34 compact pill, wider than it is tall)
+  with an even inset on every side and a concentric radius, for pill and
+  rounded shapes, so the group-owned outline or halo ring follows the pill while
+  focused and while the listbox is open. Before, a default-size trigger was a
+  32px square left-aligned in its 44px group, and the caret was hidden. The
+  Select catalog adds a default-size "Toolbar icon" example beside the compact
+  one.
+
+- Fixed the `@kerfjs/ui` icon-only `Select` focus ring in a
+  `ToolbarControlGroup` not matching the control: the compact trigger grew its
+  group into a 36x34 oval and its disclosure caret overflowed the trailing edge.
+  The group-owned ring now stays concentric with the trigger while focused and
+  while the listbox is open. The Select demo's "Quiet" option icon also used the success fill alias
+  as its color and was nearly invisible; it now uses `success-on-quiet`, and the
+  `SelectChoice.color` guidance names foreground tokens.
+
+- `@kerfjs/ui` UX catalog: the ten production recipes now compose Kerf
+  components, layouts, and Web Awesome surfaces through their public
+  configuration alone, with no route stylesheets, inline styles, or
+  styling-only classes. The list-detail dialog is rebuilt from `DialogSurface`,
+  the dialog's own labeled header and close control, `SplitView` (a full-screen
+  list-to-detail drill-down on compact devices), aligned `ListHeader`s, a
+  `ValueTable`, and footer actions. The desktop application shell switches to one
+  pane at a time below desktop sizes through `deviceClass()`. Page and pane
+  headings stack instead of hiding their titles at narrow widths, and supporting
+  copy, content-item text, and loading skeletons sit on the shared 17px text
+  inset. The catalog frames each recipe in a `CatalogExample` viewport that the
+  recipe declares through an exported `presentation`, and recipe ownership notes
+  render as that example's note. `npm run check:recipes` now fails on a recipe
+  stylesheet, an inline style, a class outside the published layout and Web
+  Awesome vocabulary, a non-public stylesheet import, or recipe-specific rules in
+  the catalog shell stylesheet.
+- Fixed `@kerfjs/ui/webawesome.css` `wa-dialog` titles given as a plain-string
+  `label` sitting at the bare surface inset; they now inset by one bordered
+  item step (`--kui-layout-item-padding` + 1px) so the header label lines up
+  with body text and icons. Slotted label elements are unaffected.
+- Fixed icon + label `wa-button`s inside `ToolbarControlGroup` stacking the
+  icon above the label; their label part now lays out as a single nowrap row,
+  matching native mixed buttons.
+- `prompt()` / `form()` now reject with a `TypeError` when a validator returns
+  a promise (validators are synchronous), instead of resolving the value and
+  leaving an unhandled rejection. `prompt()` also re-reads its input on every
+  OK, so a reactive `render` that replaces the input no longer submits the
+  detached original's stale value, and a removed input rejects the promise.
+- A local `npm run check` run with `KERF_SKIP_PACKAGE_GATES=1` no longer
+  records a verified tree, so the pre-push hook cannot skip the sibling-package
+  gates that run left out.
+- `kerfjs/overlay`: a `prompt()` `validate` or `form()` `field.validate` that
+  throws now closes the dialog (full teardown, focus restored) and rejects the
+  returned promise with the original error. Previously the error escaped the
+  OK click or Enter handler, and the dialog stayed open with an OK button that
+  could never succeed. Validators are synchronous; this is the error channel
+  for a validator bug.
+- `kerfjs/overlay`: when a `form()` field input disappears after the dialog
+  opens (for example a reactive `render` re-render drops it), OK and Enter now
+  close the dialog and reject the promise with an error naming the missing
+  field. Previously `form()` resolved `null`, which
+  reads as a Cancel, and threw from the click handler.
+- `@kerfjs/ui`: a multiline `ListItem` whose label fits on one line now
+  centers its icon on that line. The row's 44px minimum used to stretch the
+  grid track, which centered the label but left the start-aligned icon about
+  1.4px above it.
+- `@kerfjs/ui`: a `ToolbarControlGroup` with `focusRing="outline"` or
+  `"halo"` keeps its group focus ring while a `Select` inside it has its
+  listbox open. Chromium and WebKit did not carry `:focus-within` from the
+  focused option to the group, so the ring disappeared.
+- UX catalog: the foundation palette's Brand swatch uses the brand on-fill
+  color again, the Spacer demo gives its flexible spacer room to grow again,
+  and the TokenSearchField adoption demo again wires its chip keyboard and
+  `onEdit` readout. The catalog demo rework had broken all three.
+- Documented and pinned how `tooltip()` surfaces a failed show from its delay
+  timer: the half-built tooltip is rolled back, the original error escapes the
+  timer for the host to report (a window `error` event in browsers, matching
+  kerf's other deferred callbacks), and the tooltip stays armed so the next
+  hover or focus tries again.
+- Fixed the dialog helpers (`confirm` / `prompt` / `form` / `choice`) leaving
+  wiring behind when a step after the overlay opened failed. Their post-open
+  wiring (required-slot checks, the click-table `delegate()`, the Enter-key
+  listener) is now part of construction: a failure removes the listeners
+  already wired, closes the overlay (including a `native` `<dialog>`), restores
+  focus, and rethrows the original error, so no pending promise is left
+  attached to an on-screen dialog.
+- Added `ticket:timing summary --all`, a read-only cross-ticket timing report
+  (median/p90 per phase, gate, and check step) that counts one push shared by
+  a batch of tickets once and detects and excludes fan-out backfill, such as
+  the first timed push that attached one check interval to 374 historical
+  tickets.
+- Ticket timing now records per-step durations of the root `npm run check`
+  chain (printed at the end of every run), interrupted gate attempts, active
+  time through `ticket:timing claim`/`release` wrappers around `hotsheet-cli`,
+  and CI/publication intervals imported idempotently from GitHub Actions with
+  `ticket:timing import-ci`.
+- The pre-push hook no longer reruns `npm run check` when a local run already
+  passed on the exact clean tree being pushed; the skip is recorded in ticket
+  timing, and any dirty worktree, different tree, Node.js change,
+  failed/interrupted rerun, or `KERF_FORCE_CHECK=1` runs the full gate.
+- The pre-push hook no longer fans its timing record out to every ticket in a
+  push that names more than 25 of them (a first push of a long history, a
+  force-push). It prints a notice and records only the explicit
+  `KERF_TICKET_TIMING_TICKETS` list, or nothing, so it can no longer write the
+  backfill shape the cross-ticket summary has to exclude.
+- The pre-push hook's "already verified" skip now also requires the same
+  platform, architecture, and installed dependencies as the passing run: a
+  fingerprint of every `package-lock.json` and `node_modules/.package-lock.json`
+  across the root, `ui/`, `eslint-plugin/`, `create-kerf-component/`, and
+  `site/`. A reinstall, a lockfile change, or a missing `node_modules` now runs
+  the full gate.
+- `ticket:timing record` accepts `--run-id <n>`, and `import-ci` no longer
+  imports a GitHub run a second time when it was already recorded by hand:
+  an interval with that run id, or one with no run id for the same phase and
+  gate whose span overlaps the run's (within 60 seconds), counts as imported.
+- `bindList()` now rolls back when its first render throws: rows that pass
+  already created are disposed (content mounts and element-mode `dispose`
+  callbacks) and removed before the original error is rethrown, instead of
+  leaking live row effects with no handle to release them.
+- `bindList()` virtualization now validates its dimensions: heights (fixed,
+  estimated, callback-returned, and `setHeight` reports) must be finite and
+  non-negative, a fixed window-mode `rowHeight` must be positive, and
+  `overscan` / `minRows` must be non-negative integers. Invalid values throw a
+  descriptive error instead of producing blank windows or a corrupted scroll
+  anchor.
+- `bindList()` now rejects a source that carries the `arraySignal` brand but
+  has no patch queue with a descriptive error at bind time, instead of failing
+  with a generic `TypeError` on its first render.
+- Added `wa-dialog.hide-actions` support to `@kerfjs/ui/webawesome.css`, hiding
+  Web Awesome's directly exported `header-actions` shadow part for dialogs that
+  provide their own dismissal affordance.
+- Fixed `mount()` leaving an element permanently "already mounted" when its
+  first render throws. The first render is now transactional: the original
+  error is rethrown, every binding effect and the dev listener observer
+  acquired so far are released, the element's pre-mount child nodes are
+  restored, and a retry on the same element succeeds.
+- Fixed `overlay()` construction leaking a live wrapper, mount, dismissal
+  listeners, and concurrent-overlay stack entry when setup failed partway. A
+  malformed `initialFocus` selector now throws a descriptive `overlay()` error
+  before anything is touched, and a throwing first render or `native`
+  `showModal()` / `showPopover()` call rolls back everything already installed
+  (restoring focus) before rethrowing. `popover()` and `tooltip()` roll back the
+  same way when positioning fails; the dialog helpers inherit the guarantee.
+- Added an opt-in `@kerfjs/ui/document.css` baseline for border-box sizing,
+  token-backed body and link presentation, and a `.kui-app-root` full-height
+  chain for application shells.
+- Added an inline `Text` span variant for secondary copy inside rows, labels,
+  and table cells, preserving tone, size, and font roles without box geometry.
+- Reworked every focused UX catalog demo to dogfood Kerf components, Web
+  Awesome surfaces, and semantic HTML without route-local stylesheets, inline
+  styles, styling-only classes, or shared icon/button render helpers. Added
+  catalog-owned specimen viewport constraints and a nonwaivable conformance
+  gate that prevents those styling shortcuts from returning.
+- Fixed `ToolbarControlGroup` dropdown triggers that were sized to fixed 48px/66px boxes,
+  which clipped popup icons and let compact mixed-control carets overflow in
+  Safari while distorting longer catalog controls.
 - Added a `TabBar.end` action zone for layouts that need a tab-local adjacent
   `trailing` action and a separate far-edge action; the tab strip now owns the
   shrink/scroll geometry while all action regions remain visible.

package/README.md

@@ -31,14 +31,17 @@ const app = document.getElementById('app')!;
 mount(app, () => (
   <div>
     <button data-action="inc">+</button>
-    <span>{count.value}</span>
+    <span>{count}</span>
   </div>
 ));
 
 delegate(app, 'click', '[data-action="inc"]', () => count.value++);
 ```
 
-That's it. Your JSX renders to HTML strings, kerf's native diff applies the minimum DOM mutations to make the live tree match, and signals re-run the render only when something they read actually changed.
+That's it. Your JSX renders to HTML strings, and handing the signal itself to
+the text hole binds that one node directly. Structural reads still re-run the
+render, where kerf's native diff applies the minimum DOM mutations needed to
+make the live tree match.
 
 Here's the whole development loop — write a component, run the dev server, click around, edit, watch the browser pick it up:
 
@@ -81,7 +84,9 @@ Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no ext
 
 4. **Focus, selection, and listeners survive re-renders — even mid-list.** The reconciler morphs instead of rebuilding, so caret position, IME composition, scroll, and delegated listeners survive every update; keyed rows are patched in place rather than recreated.
 
-5. **Safe by default.** Text and attributes are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` dropped), and inline `on*` handlers are rejected outright — so untrusted data stays inert. `raw()` is the explicit, auditable opt-out.
+5. **A first-party UI layer when you want one.** `@kerfjs/ui` adds accessible components, responsive application layouts, typed CSS values, and explicit wiring helpers without changing kerf's stateless component model. It is separately installable and tree-shakeable, so the core stays the core. ([tour →](#first-party-ui-separately-installable))
+
+6. **Safe by default.** Text and attributes are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` dropped), and inline `on*` handlers are rejected outright — so untrusted data stays inert. `raw()` is the explicit, auditable opt-out.
 
 **Plus, nothing you don't ask for:** JSX typed against the HTML standard (not React's props) · a ~18-export API with no hooks, lifecycle, or per-instance state · **nine** tree-shakeable companion subpaths (`router`, `list`, `overlay`, `async`, …) that stay out of the core until imported · an [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) + opt-in dev warnings + `create-kerf-component` scaffold · plain TS/JSX/ESM that drops into esbuild / Vite / tsup — or **no** build at all via the `html` tagged template.
 
@@ -97,7 +102,7 @@ Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no ext
 ### When to reach for something else
 
 - Need a full ecosystem (router + forms + data + SSR streaming) → **Next.js / Remix / SolidStart**.
-- Building a deeply componentised design-system app → **React / Solid / Svelte**.
+- Building a deeply componentized design-system app → **React / Solid / Svelte**.
 - Need React Native / cross-platform mobile → **React** (Kerf + Tauri/Electron also covers many of these cases).
 - Building a static site → **Astro** (we use it for _this_ project's site).
 - Already invested in a framework where switching cost outweighs the bundle size gain.
@@ -278,6 +283,38 @@ mount(app, () => <div><nav>{/* <a href> links, auto-intercepted */}</nav>{router
 
 Each subpath adds nothing to the main barrel until it's imported. See [`docs/8-api-reference.md`](./docs/8-api-reference.md) for the full list (`list`, `router`, `overlay`, `scope`, `async`, `timing`, `remount`, `attach`, `actions`).
 
+### First-party UI, separately installable
+
+`@kerfjs/ui` is the optional component layer for applications that want a
+coherent interface vocabulary without switching frameworks. Components return
+Kerf `SafeHtml`; the application still owns state and wires behavior explicitly.
+Component subpaths pull in only their reachable CSS, while responsive app
+layouts, typed CSS-value builders, Web Awesome adapters, and the checked
+component catalog stay opt-in.
+
+```bash
+npm install kerfjs @kerfjs/ui
+```
+
+```tsx
+import { mount } from "kerfjs";
+import { ListItem } from "@kerfjs/ui/list-item";
+import { Toolbar } from "@kerfjs/ui/toolbar";
+import { ToolbarText } from "@kerfjs/ui/toolbar-text";
+
+const root = document.getElementById("app")!;
+
+mount(root, () => (
+  <>
+    <Toolbar label="Files" leading={<ToolbarText text="Workspace" />} />
+    <ListItem action="open-file" label="src/main.ts" selected />
+  </>
+));
+```
+
+Start with the [component selection matrix](./ui/docs/component-selection.md),
+or read the complete [`@kerfjs/ui` package guide](./ui/README.md).
+
 ## Optional tooling
 
 Install and JSX setup are in [Quick start](#quick-start) above. These companion packages are opt-in.
@@ -314,6 +351,7 @@ See [`docs/13-component-packages.md`](./docs/13-component-packages.md) for the f
 - **Docs:** [`docs/`](./docs/) — overview · reactivity · stores · render · events · jsx · svg · [API reference](./docs/8-api-reference.md)
 - **Migrating:** [coming from another framework?](https://brianwestphal.github.io/kerf/migrating/) — side-by-side TodoMVC translations + per-framework gotchas
 - **AI guide:** [`docs/ai/usage-guide.md`](./docs/ai/usage-guide.md) — reference for AI tools fetching kerf docs (linked from `llms.txt`)
+- **UI package:** [`@kerfjs/ui`](./ui/README.md) — accessible components, responsive app layouts, typed CSS values, Web Awesome adapters, and checked AI-facing component metadata
 - **ESLint plugin:** [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — `eslint-plugin-kerfjs`; eight rules (four hard-rule errors + four warns: `require-delegate-disposer`, `prefer-attr-selector`, `no-raw-with-dynamic-arg`, `ai-assistant-configs`) at edit time (source: [`eslint-plugin/`](./eslint-plugin/))
 - **Component scaffold:** `npm create kerf-component@latest <dir>` — `create-kerf-component`; generates a publishable component package with packaging rules plus deterministic, drift-checked AI metadata pre-wired (source: [`create-kerf-component/`](./create-kerf-component/))
 - **Demo:** [live demo](https://brianwestphal.github.io/kerf/demo/) — nine sections exercising every primitive (counter, store-backed cart, focus survival, keyed list, morph-skip, SVG render, Tier-2 capture, `arraySignal` patches, fine-grained signal bindings)

package/ai/manifest.json

@@ -1,5 +1,5 @@
 {
-  "kerfjsVersion": "5.0.0-beta.50",
+  "kerfjsVersion": "5.0.0-beta.52",
   "files": [
     {
       "name": "skill",