kerfjs 5.0.0-beta.7 → 5.0.0-beta.71

package/CHANGELOG.md

@@ -6,7 +6,2457 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-- Added a first-class loading-placeholder mode to `@kerfjs/ui`: a new unanimated `Skeleton` block (`@kerfjs/ui/skeleton`) plus a `placeholder` boolean on every value-bearing component (`Select`, `MenuHeader`, `MenuItem`, `MenuActionRow`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`). In placeholder mode a component renders its real chrome with value slots as subtle skeleton blocks and its own controls disabled (`aria-busy`, dropped `data-action`), keeping sizes and shapes identical to the populated component, so a parent composes a faithful loading inspector/detail view without hand-rebuilding markup. Built on a Kerf-owned skeleton (not `wa-skeleton`) so the pure-Kerf primitives stay Web-Awesome-free. `Select`'s existing empty-hint string prop is renamed `placeholderText` to free `placeholder` for the loading boolean.
+- **LucideIcon supports filled glyphs.** Pass `appearance="solid"` to use the
+  icon's current text color as its fill; outline remains the default.
+
+- **Doctor detects borrowed component markup.** Source modules that place a
+  foreign public class in JSX, raw HTML, or DOM class writes now receive
+  `KUI-L023`; documented placeable classes remain allowed.
+
+- **Doctor offers strict same-package selector context checks.**
+  `ownershipContext: "any"` reports a sibling component's class even when it is
+  only used as selector context; cross-package composition stays available.
+
+- **Doctor catches classless descendants of composed components.** Component
+  mode uses JSX evidence to identify element selectors below component hooks,
+  sibling roots, and direct composed child roots.
+
+- **Doctor component ownership recognizes source evidence.** Selection-only
+  components and literal BEM classes rendered by a component are protected
+  when its stylesheet styles their block. CSS imports can supply the owned
+  stylesheet, and uncataloged modules can opt into the same inference.
+
+- **`createScope().dispose` is typed as a bound function property.** Consumers
+  can store or return it as a teardown without a wrapper or an unbound-method
+  lint suppression.
+
+- **ToolbarControlGroup grow sizing keeps its basis in wide toolbars.** An
+  expanded grow search now contributes its minimum width to the trailing zone's
+  intrinsic size, keeping sibling groups beside it instead of wrapping early.
+
+- **TabBar can settle overflowing peers at whole-tab starts.** Opt into
+  `snapTabs` beside a pinned leading AppTab; selection and scroll gestures
+  align peers after the pin in LTR and RTL, with enough end room for the final
+  tab instead of leaving a clipped sliver at rest.
+
+- **The pre-push check no longer adds timing metadata to Hot Sheet tickets.**
+  It still runs the repository gate or skips an identical verified clean tree;
+  historical timing notes remain readable through `ticket:timing summary`.
+
+- **Wrapping catalog resource groups align with the toolbar control band.** A
+  single row centers in the band, while multiple rows start at its top.
+
+- **UI browser checks cover the current catalog specimens.** Select, toolbar,
+  tab, and control group browser assertions now address the expanded demos;
+  a focused toolbar search field restores its default surface color when no
+  background override is set.
+
+- **Pinned tabs cover the full leading edge of their scroll strip.** The
+  backing now includes the strip border as well as its padding, preventing a
+  sliver of a scrolling tab label from showing beside the pinned tab.
+
+- **Catalog resource links remain readable at phone widths.** The resource
+  group wraps whole actions onto another row instead of clipping the Guidance
+  label at the right edge; `ToolbarControlGroup overflow="wrap"` is available
+  for the same independent-link pattern.
+
+- **The UI analyzer resolves application component imports through TypeScript
+  path aliases.** `KUI-L022` now catches a styled hook class when an imported
+  cataloged component uses an exact or wildcard `paths` mapping; Doctor uses
+  the same resolution.
+
+- **TabBar accepts standalone Web Awesome actions in `trailing` and `end`.**
+  A single `wa-button` can sit beside the scrolling tabs or at the far edge
+  without ToolbarControlGroup chrome; the composition rule recognizes the
+  cataloged custom element in these zones.
+
+- **FieldLabel matches form-control labels over field previews.** The
+  `@kerfjs/ui/text` export gives a read-only field the same label typography
+  and inset as a themed Web Awesome input, with an id for accessible grouping.
+
+- **TokenSearchField form fields match adjacent Web Awesome inputs.** The
+  control uses the form-control radius, and its required marker uses the
+  same neutral color and offset tokens as `wa-input`.
+
+- **Grid supports labeled multi-select ContentItem tiles.** Opt into
+  `selectionMode="multiple"` with `ariaLabel`; `wireContentItems` follows the
+  rendered columns with four arrow keys and keeps nested controls independent.
+
+- **Collapsible TokenSearchField can fill a stretched Toolbar center.** The
+  `fill` prop expands the field and its search group to the available width
+  while preserving the compact collapsed action.
+
+- **TokenSearchField has a typed trailing icon action.** `trailingAction`
+  renders an accessible button with Kerf owned chrome and a full 24px wide hit
+  target; the existing `trailing` content slot remains for passive content.
+
+- **PopupMenu and registered PopupSurface dropdowns preserve fast keyboard
+  navigation during opening.** Item focus gained while Web Awesome animates
+  the menu is restored after its initial focus handoff, so Enter acts on the
+  item the user reached.
+
+- **PopupMenu submenu checkmarks stay inside the menu surface.** Checked
+  submenu rows align their checkmark beside the label instead of letting the
+  Web Awesome negative check margin paint beyond the submenu border.
+
+- **Filled SegmentedControl labels keep contrast while switching themes.**
+  Web Awesome's native button color transition no longer interpolates the
+  label against the already-switched track fill.
+
+- **Workbench numeric overlays no longer restyle the full work area on unrelated changes.**
+  The overlay wiring mirrors active presentation and open state onto the Workbench
+  root for CSS, and avoids layout measurements when no wired panel uses a numeric
+  breakpoint.
+
+## [5.0.0] - 2026-09-29
+
+- **`ui-public-boundaries` inspects `kerfjs/html` tagged templates.** The
+  no-build `html` template writes the same markup as JSX, so its static
+  `class` attributes now carry `KUI-L101` (private `kui-*` anatomy) and
+  `KUI-L103` (a component's anatomy on your own element):
+  ``html`<aside class="kui-pane">` `` is reported with `Pane` to render, and a
+  plain ``html`<div class="kui-content-item">` `` with `ContentItem`, while a
+  `<ul>` carrier keeps the placeable class. The template's static parts are
+  read by the runtime's own rules; a class a hole supplies (`class=${cls}`)
+  is unknown and skipped.
+
+- **`KUI-L103`'s "render X instead" answer has one implementation.**
+  `@kerfjs/ui` ships `ai/component-class-owners.cjs`, the rule that decides
+  which cataloged classes are a component's anatomy and which export renders
+  each. `eslint-plugin-kerfjs`'s `ui-public-boundaries` loads it beside
+  `application-ui-profile-sync.cjs`, and the generated `ai/components/*.md`
+  pages use it too, so the lint message and the component reference can no
+  longer name different components (a test pins their agreement over the whole
+  shipped catalog). A vendored `profileContractPath` directory must now also
+  hold `component-class-owners.cjs`; an `@kerfjs/ui` without it reports
+  `KUI-L090`.
+
+- **A delegated click no longer re-fires on a target the re-render recycled.**
+  A delegated handler that writes a signal makes `mount()` re-render
+  synchronously, inside the same event dispatch; when the morph recycled the
+  clicked element in place into a control with a different `data-action`,
+  delegates registered later for the same event matched the recycled element
+  and fired too (a `request` click immediately ran `cancel` and undid itself).
+  `delegate()`, `delegateCapture()`, and `kerfjs/actions`' `delegateActions()`
+  now resolve every delegate's match against the DOM as it stood when the
+  event reached the first kerf delegate listener, like per-element listeners:
+  a delegate that matched at dispatch start still fires (unless an earlier
+  handler removed its element), one that matches only after a re-render does
+  not, and `delegateActions()` dispatches by the action value the element
+  carried at dispatch start. `mount()` stays synchronous. The
+  wrap-it-in-a-distinct-element workaround is no longer needed. Cost: about
+  0.11 KB min+gzip, which moves the advertised core size from ~12 KB to
+  ~13 KB.
+
+- **Component packages declare `placeableClasses`, and `KUI-L103` covers
+  their anatomy classes.** `create-kerf-component`'s `kerf.components.json`
+  accepts optional `boundaries.placeableClasses` (a subset of
+  `publicClasses`) and `boundaries.rootElement`, validates them, and copies
+  them into the generated `component-composition.json`.
+  `eslint-plugin-kerfjs`'s `ui-public-boundaries` now checks every class the
+  application or third-party catalogs in `.kerf-ui-profile.json` declare, not
+  only `kui-*` names: `<div class="acme-meter">` is reported with the
+  package's component to render (`Meter`), while its placeable classes stay
+  allowed. The scaffold template's README explains the field, and
+  `@kerfjs/ui/ai/skill.md` (1.50.0) applies the rule to package entries.
+
+- **`eslint-plugin-kerfjs` `ui-public-boundaries` reports a plain
+  `<div class="kui-content-item">` as `ContentItem` recreated (`KUI-L103`).**
+  The `kui-content-item` classes stay placeable on another carrier (a `<ul>`, a
+  `Text`, a control-cluster `<footer>`), but a plain `<div>` carrying them is
+  exactly what `ContentItem` renders; the diagnostic now says to render
+  `ContentItem`. The `@kerfjs/ui` catalogs gain an additive `rootElement`
+  field (selection entry and composition `boundaries.rootElement`) naming the
+  element a component renders around its own placeable classes, and
+  `check:guidance` derives its repository check from the same fields, so the
+  package check and the downstream diagnostic cannot drift. The rule also
+  inspects the static class names of a template-literal `class` /
+  `className` value.
+
+- **`eslint-plugin-kerfjs` `ui-public-boundaries` reports a component's
+  anatomy class written onto an application-owned element (`KUI-L103`).**
+  `<div class="kui-toolbar">`, `<aside class="kui-pane">`, or
+  `<wa-dropdown class="kui-popup-menu">` recreates a component by class and
+  inherits (and invites restyling of) its CSS; the diagnostic names the
+  component to render instead (`Toolbar`, `Pane`, `PopupMenu`). The
+  `@kerfjs/ui` catalogs gain `placeableClasses` (selection entry field and
+  composition `boundaries.placeableClasses`) naming the public classes an
+  application may place itself — the layout utilities, `kui-app-root`, the
+  `kui-content-item` geometry on a non-div carrier, and Web Awesome
+  `hide-actions` — and `check:catalog` requires every class-only entry to list
+  its classes there. A component's own element (`<Toolbar className="kui-toolbar">`)
+  is not reported. The README pane example and `@kerfjs/ui/ai/skill.md`
+  (1.47.0) now render `Pane` instead of writing its classes, and each generated
+  `ai/components/*.md` page states which classes are placeable and which
+  component renders the rest.
+
+- **`kerf-ui-analyze` retires `KUI-L005` ("forced component dimension").**
+  `KUI-L019` already reports any application rule whose subject is a cataloged
+  component, dimensions included, so `.kui-pane { width: 300px }` was reported
+  twice (an error and a review finding). L005's only other shape, a public
+  class as an ancestor (`.kui-pane .app-sidebar { width: 240px }`), sizes the
+  application's own element and is allowed. The analyzer no longer emits it;
+  the id stays in the diagnostic registry (now listing it under `retired`) so
+  existing profile exceptions that name it still load.
+
+- **`KUI-L301` now reports every `Discouraged` Web Awesome element rendered
+  directly.** The `@kerfjs/ui` package-default application profile avoids all
+  fifteen Discouraged entries (Dropdown/Dropdown Item → `PopupMenu`,
+  Select/Option → `Select`, Tab Group/Tab/Tab Panel → `TabBar`, Icon →
+  `LucideIcon`, Split Panel → `ResizableRegion`, Button Group →
+  `SegmentedControl`, Tree/Tree Item → `List`, and Animated Image, Comparison,
+  and Zoomable Frame → `ContentItem`), each with a rationale, and
+  `eslint-plugin-kerfjs` `ui-preferences` (and `kerf-ui-doctor`, which runs it)
+  now resolves a custom-element JSX tag such as `<wa-dropdown>` to its catalog
+  entry, not only an imported component. A declared component's own source
+  stays exempt because it is the wrapper that owns the element. A test keeps
+  the profile's avoid set equal to the catalog's Discouraged set in both
+  directions and lints the UX demo, recipes, and catalog shell clean;
+  `@kerfjs/ui/ai/skill.md` (1.46.0) names the diagnostic.
+
+- **New (`@kerfjs/ui`): `NavStack` and `TabScaffold` take `chromeDividers`
+  (`'scroll' | 'always' | 'none'`), like `Pane`.** `scroll` (the default) keeps
+  today's behavior: the stack's top-chrome and bottom-toolbar lines and the
+  scaffold's bar line follow the scroll once `wireScrollDividers` is installed.
+  `always` draws them permanently without the wiring; `none` never draws them,
+  even when wired. The top `Toolbar`'s own `toolbarConfig.dividerSides` is
+  unaffected. `SplitView` forwards it to its compact stack through
+  `compactStack.chromeDividers`.
+
+- **Fix (`@kerfjs/ui`): a `Pane` that is the only content of a `NavStack` view
+  or a `TabScaffold` scene fills it.** It used to size to its content, so the
+  view scrolled the whole Pane and its header scrolled away. Now the Pane's own
+  content scrolls under its pinned header and footer, the Pane's slots take the
+  safe-area edges the view or scene still reaches, and scroll dividers key on
+  the Pane's content. The rule lives in `pane.css`, as the Workbench-region fill
+  does.
+
+- **The `@kerfjs/ui` suite-v3 AI-regression protocol test runs in every gate
+  again.** `ui/tests/integration/ai-regressions-v3.test.ts` was selected by no
+  package script, so neither `npm --prefix ui run check` nor CI executed it. It
+  now runs as `test:ai-regressions` inside the package's `npm test`, and a new
+  unit guard fails when any file under `ui/tests` is selected by no script
+  reachable from `check` or `test:e2e`.
+
+- **Importing `@kerfjs/ui/catalog` or `@kerfjs/ui/workbench` now ships every
+  stylesheet those composites render.** `catalog`, `workbench`, `nav-stack`,
+  `split-view`, `tab-scaffold`, and `collapsible-panel` gain a CSS-aware
+  `browser` export condition whose generated wrapper imports the foundation, the
+  CSS of each internally rendered component (Pane, Toolbar, ToolbarText, List,
+  ListItem, ListInsetText, Row, PopupMenu, …) in dependency order, and the
+  composite's own CSS. Apps no longer hand-import `pane.css`, and a Catalog
+  sidebar's styling no longer depends on whether the app happens to import
+  `ListInsetText` elsewhere. The list is derived from the source import graph
+  (now following parent-relative imports), the `import` condition stays
+  CSS-free, and the companion `.css` subpaths remain for pipelines without the
+  `browser` condition. `@kerfjs/ui/ai/skill.md` is 1.46.0.
+
+- **The `@kerfjs/ui` AI guidance now states every maintainer design rule
+  explicitly.** An audit of the package's tickets folded the missing rules into
+  `@kerfjs/ui/ai/skill.md` (1.45.0), `llms.txt`, and the design docs: prefer a
+  Kerf UI component over a Web Awesome component over a raw tag and never render
+  a `Discouraged` Web Awesome element directly (only through the Kerf component
+  that wraps it); nothing wraps inside a `ToolbarControlGroup` and a
+  `ToolbarText` is one ellipsized line unless `wrap`/`maxLines` is set; a
+  `Select` or `PopupMenu` trigger drops its focus ring while its popup is open
+  and the ring follows the control's shape (never add ring CSS); dividers earn
+  their place (`dividerSides=""` over self-spacing content or between a pane's
+  header and its list, never padded around); a control sits near where its
+  effect appears; and text aligns to text and icons to icons — a border is
+  never the alignment anchor. The ToolbarControlGroup catalog entry no longer
+  points at a hand-written `wa-dropdown` trigger, and the bundled kerf app
+  configs (`ai/skill.md` 1.25.0, `ai/cursorrules` 1.23.0) name the List family
+  and carry the "components own their styles; configure, never override" rule.
+
+- **Applications and component packages are held to the component-ownership
+  rules `@kerfjs/ui` enforces internally: components own their styles and are
+  configured, never overridden.** `kerf-ui-analyze` and `kerf-ui-doctor` add
+  four error diagnostics (review findings under `--adoption`):
+  - `KUI-L019` — a CSS rule whose subject is another package's cataloged
+    component: a public class (`.kui-toolbar`, `.acme-meter`), its
+    `[data-component]` root, or a Web Awesome tag the package themes
+    (`wa-button`). Your own element in a component's context
+    (`.kui-toolbar > .my-widget`), keying on its state inside `:has()`, and
+    setting its public tokens stay allowed.
+  - `KUI-L020` — reading or writing another component's private `--_*`
+    variable (`--_kui-list-gap`).
+  - `KUI-L021` — overriding a token a typed prop sets (`--kui-list-gap` is
+    `<List gap>`); the message quotes the prop's example.
+  - `KUI-L022` — a class placed on a component's root (`<Toolbar
+className="header" />`) that the application then styles.
+
+  Each message names the component's configuration (typed props, public
+  tokens, variants) and ends by routing a need with no prop to a component-gap
+  report instead of an override. Ownership is per package, from the nearest
+  `package.json`, so a component package styling its own components — including
+  in a Kerf UI parent's context — passes, and third-party catalogs declared in
+  `.kerf-ui-profile.json` get the same protection. `eslint-plugin-kerfjs` adds
+  `ui-component-ownership` (in `recommended-ui` and `strict-ui`, `error`),
+  reporting `KUI-L020` / `KUI-L021` in style strings, style objects, and
+  `style.setProperty()`. The `create-kerf-component` scaffold now ships a
+  `counter.css` that styles only Counter (configured by a typed `size` prop and
+  a `--kerf-counter-gap` token, with context named after Counter and a
+  Toolbar-context rule in its own stylesheet), plus `npm run check:styles`
+  (`kerf-ui-analyze`, from a new `@kerfjs/ui` dev dependency) in
+  `prepublishOnly`.
+
+- **Behavior change (`@kerfjs/ui`): `NavStack` and `TabScaffold` chrome
+  dividers follow the scroll.** The `NavStack` bottom toolbar's and the
+  `TabScaffold` bar's top borders are no longer permanent. With `wireScrollDividers`
+  installed, a `NavStack`'s top chrome draws a line along its bottom edge only
+  while the active view's content is scrolled beneath it, its bottom toolbar a
+  line along its top edge only while more content lies below, and a
+  `TabScaffold` bar a line along its top edge only while the active scene's
+  content continues below it — none when the content fits. The line follows
+  the active view across a push or pop and the active scene across a tab
+  switch, and keys on whichever element actually scrolls: the view or scene
+  itself, or, through a sole child with no chrome of its own on that edge, a
+  `Pane`'s content or a nested `NavStack`'s active view (a sole `Pane`'s own
+  header or footer draws that boundary instead). Each layout draws the line
+  from its own stylesheet (an overlaid pseudo-element on the stack's chrome; the
+  bottom toolbar and bar keep their 1px top border, transparent until shown),
+  so nothing moves; the wiring
+  writes only its `data-scroll-overflow` / `data-scroll-divider` state. Without
+  the wiring those edges draw no line.
+
+- **Behavior change (`@kerfjs/ui`): toolbars no longer draw a divider by
+  default; dividers between pinned chrome and scrolling content follow the
+  scroll.** `Toolbar`'s `dividerSides` now defaults to `''` (was `'b'`), and
+  the `Workbench` (`mainToolbar`, `mainBottomToolbar`, panel toolbars, and the
+  `mainHeader` / `mainFooter` lists), `CollapsiblePanel`, and `Catalog`
+  toolbars no longer place dividers of their own. Instead a `Pane` draws one
+  line under its header and one over its footer, wherever that chrome ends:
+  the header's only while content is scrolled beneath it, the footer's only
+  while more content lies below, and neither when the content fits. The new
+  `@kerfjs/ui/wire-scroll-dividers` subpath's `wireScrollDividers(root, {
+targets? })` reports that state — call it once at the app root and keep its
+  disposer (`wireCatalog` installs it for its own root). It also marks each
+  side of a `TabBar` strip with tabs scrolled out of view, and lets a
+  `Toolbar` or `List` named as chrome in `targets` draw the divider facing an
+  app-owned scroller. The wiring only writes the `data-scroll-overflow` /
+  `data-scroll-divider` state attributes; each component draws its own line,
+  and no state moves the chrome, the content, or a tab. `Pane` gains
+  `chromeDividers` (`scroll` default, `always`, `none`; also in `PaneConfig`,
+  so `mainPane` and a panel's `pane` forward it) and TabBar the
+  `--kui-tab-bar-divider-color` token. To keep a permanent line, set
+  `chromeDividers: "always"` on the pane or an explicit `dividerSides`.
+
+- **`@kerfjs/ui`: `Pane`, `NavStack`, `SplitView`, and `TabScaffold` fill a
+  Workbench region from their own stylesheets.** As a Workbench main area's
+  or panel's only child, each sets its own `height: 100%` in that context,
+  which the Workbench marks on its regions (`data-workbench-main`, and the new
+  `data-workbench-panel-content` on each panel's content); `workbench.css` no
+  longer sizes another component's root (it still fills a nested Workbench).
+  Rendering is unchanged.
+
+- **`@kerfjs/ui`: layouts name the covered-floating-controls context after
+  themselves, and no longer write `FloatingToolbar`'s inset token.** Workbench,
+  CollapsiblePanel, and ResizableRegion each provide their own private
+  `--_kui-<layout>-covered` context in place of the shared
+  `--_kui-floating-covered` flag; `FloatingToolbar` and every restore corner
+  read all three. A restore corner no longer sets
+  `--kui-floating-toolbar-inset: 0px`; `FloatingToolbar` zeroes its own inset
+  inside a restore corner (a toolbar's own `inset` still wins). Rendering is
+  unchanged. One edge case changes: a floating control inside an open overlay
+  of one layout type that is itself covered by another layout type's open
+  overlay (for example, a ResizableRegion overlay in a Workbench work area
+  under an open rail overlay) now stays hidden.
+
+- **`@kerfjs/ui`: `ListHeader`, `NavStack`, `Select`, and `StateBanner` no
+  longer restyle a composed child through a class on its root.** Each child
+  now styles itself: `Text` sets a `ListHeader` label from `text.css`, `Badge`
+  spaces a `Select` count and a `StateBanner` badge from `badge.css`, and a
+  `NavStack` title uses `ToolbarText`'s new `fill` option. Rendering is
+  unchanged. `ToolbarText` gains `fill` (grow into the free space of its
+  toolbar zone and truncate there). The `kui-list-header__label`,
+  `kui-nav-stack__title`, `kui-select__count`, and `kui-state-banner__badge`
+  classes are removed; select a ListHeader label with
+  `.kui-list-header__title > .kui-text` and a NavStack title with
+  `.kui-toolbar-text[data-fill="true"]` if a test needs to find them.
+
+- **`@kerfjs/ui` ships a markdown component reference for AI assistants.**
+  `@kerfjs/ui/ai/components/README.md` indexes every catalog entry in one line,
+  and `@kerfjs/ui/ai/components/<id>.md` gives each entry a short page: when to
+  use and avoid it, imports and CSS/registration side effects, a link to its
+  exact props, legal parents and zones (JSX prop and child count), app- and
+  wiring-owned state, geometry, accessibility obligations, its styling boundary
+  (configure through props; do not override internals), and its diagnostics.
+  `llms.txt` and the shipped skill now send assistants there instead of to the
+  263 KB `component-catalog.json` and 221 KB `component-composition.json`,
+  which remain the canonical sources for tools. The pages are generated from
+  those two files and a package check fails when they drift.
+
+- **Breaking (`@kerfjs/ui` and `create-kerf-component`): the composition
+  catalog files are renamed so they no longer read as a "v2" of the component
+  catalog.** The composition catalog is a generated composition layer beside
+  `component-catalog.json`, not a newer version of it. Update any import,
+  `$schema`, `$ref`, or `.kerf-ui-profile.json` catalog location that names an
+  old path:
+
+  | Old path                                                       | New path                                                        |
+  | -------------------------------------------------------------- | --------------------------------------------------------------- |
+  | `@kerfjs/ui/ai/component-catalog-v2.json`                      | `@kerfjs/ui/ai/component-composition.json`                      |
+  | `@kerfjs/ui/ai/component-catalog-v2.schema.json`               | `@kerfjs/ui/ai/component-composition.schema.json`               |
+  | `@kerfjs/ui/ai/component-catalog-v2.d.ts`                      | `@kerfjs/ui/ai/component-composition.d.ts`                      |
+  | `@kerfjs/ui/ai/component-catalog-v2-overrides.json`            | `@kerfjs/ui/ai/component-composition-rules.json`                |
+  | `@kerfjs/ui/ai/component-catalog-extension-v2.schema.json`     | `@kerfjs/ui/ai/component-composition-extension.schema.json`     |
+  | `@kerfjs/ui/ai/component-catalog-extension-v2.d.ts`            | `@kerfjs/ui/ai/component-composition-extension.d.ts`            |
+  | `@kerfjs/ui/docs/examples/component-catalog-extension-v2.json` | `@kerfjs/ui/docs/examples/component-composition-extension.json` |
+  | scaffolded package `component-catalog-v2.json`                 | scaffolded package `component-composition.json`                 |
+
+  The exported types follow: `ComponentCatalogV2` → `ComponentComposition`,
+  `CatalogCompositionEntryV2` → `CatalogCompositionEntry`,
+  `ConsumerComponentCatalogV2` → `ConsumerComponentComposition`, and
+  `ConsumerCatalogEntryV2` → `ConsumerCompositionEntry`. In the repository,
+  `npm run catalog:v2:sync` is now `npm run composition:sync`
+  (`catalog:sync` still runs both generators). The file contents and their
+  `schemaVersion` are unchanged.
+
+- **Breaking (`@kerfjs/ui`, `create-kerf-component`, and `kerfjs setup`): the
+  composition catalog's own fields no longer read as a "v2" of the component
+  catalog.** In `component-composition.json` (and any consumer composition
+  catalog), `"schemaVersion": 2` is now `"schemaVersion": 1` — the composition
+  format's own first version, independent of `component-catalog.json`'s — and
+  `compatibility.v1Catalog` is now `compatibility.componentCatalog`. A
+  scaffolded package's `kerf.components.json` renames its `v1Catalog` field to
+  `componentCatalog` the same way. Regenerate scaffolded catalogs
+  (`npm run catalog:generate`), and change any `.kerf-ui-profile.json` `composition`
+  location from `"schemaVersion": 2` to `"schemaVersion": 1`; a catalog still
+  carrying the old fields fails validation with a message naming the rename.
+  The `ComponentComposition` type follows (`schemaVersion: 1`,
+  `compatibility.componentCatalog`).
+
+- **`@kerfjs/ui` `NavStack` bars use the standard `Toolbar` padding.** The
+  navigation bar dropped its toolbar's block padding to stay 44px tall, so its
+  title and controls touched the bar's edges. It now keeps the 8px above and
+  below that every other toolbar has (60px plus any top safe-area inset).
+
+- **`@kerfjs/ui` multiline list rows break long camelCase names at word
+  boundaries.** A string label in a `multiline` `ListItem` or `ListActionRow`
+  (such as a Catalog sidebar entry) gets `<wbr>` break opportunities at its
+  camelCase and acronym boundaries, so `QuickTicketComposer` wraps as
+  `QuickTicket` / `Composer` instead of `QuickTicketComp` / `oser`. Breaking
+  mid-word remains the fallback for a single word that is still too wide.
+- **`wbr` is a typed JSX intrinsic element.** The runtime already rendered it
+  as a void element; `JSX.IntrinsicElements` now declares it.
+
+- **`@kerfjs/ui` `Badge` has a text-free dot, and `TabScaffold` tabs can show
+  it.** `Badge` takes `size="dot"`: an 8px solid circle in the badge's tone,
+  with no children, appearance, or shape. Because a dot has no text, its props
+  require either a `label` (announced as an image, for example
+  `label="New activity"`) or `ariaHidden` when the owning component already
+  announces it. `TabScaffoldTab` accepts `badge: true` for the iOS tab-bar dot
+  (new content without a count), centered on the icon's top-trailing corner;
+  its `badgeLabel` is required and joins the tab's accessible name
+  ("Settings, Update available"). `BadgeTextProps` and `BadgeDotProps` are
+  exported from the root barrel.
+
+- **`@kerfjs/ui` `Toolbar` truncates the leading title instead of letting the
+  center zone cover it.** When a leading identity, a `center` group, and
+  trailing actions no longer fit one row, the center zone keeps its whole
+  content width and the leading title ends in an ellipsis. Previously the
+  center track could shrink below its group, which then painted over the
+  title — a pushed `NavStack` view with a center group did this at 390px. The
+  fix holds under every `responsive` policy and both `centerAlign` values, and
+  a toolbar that fits lays out exactly as before.
+
+- **`@kerfjs/ui` `ValueTableRow` keeps its value readable beside a long
+  label.** A long single-word label (such as `ConnectionStateBanner` in a
+  390px-wide table) no longer squeezes the value to 0px wide, where it wrapped
+  one character per line while the label ran underneath it. The label and value
+  now share the row as two content-sized columns: a short value stays whole on
+  one line, the label wraps at its spaces and ends an over-long word in an
+  ellipsis before the value, and when both are long they split the row.
+
+- **`@kerfjs/ui` pinned chrome can give way in a short pane.** `Pane` takes
+  `chromePlacement="auto"`: its header and footer stay pinned while the pane is
+  at least 480px (30rem) tall, and below that the whole pane scrolls as one
+  column so tall chrome never squeezes the content to nothing.
+  `WorkbenchChromePlacement` gains `"auto"` for `mainHeaderPlacement` /
+  `mainFooterPlacement`, and `Catalog` now defaults `headerPlacement` /
+  `footerPlacement` to `"auto"`. Its entry description is pinned under the
+  toolbar, which at 200% text size on a short window had left the preview 0px
+  tall.
+
+- **`@kerfjs/ui` `TabScaffold` tabs can show a badge.** Give a
+  `TabScaffoldTab` a `badge` (a count or short string) to show the iOS tab-bar
+  badge — a compact, solid danger `Badge` at the top-trailing corner of the
+  tab's icon. The badge is hidden from assistive technology; the tab's
+  accessible name becomes `"<label>, <badgeLabel>"` (for example
+  "Inbox, 3 unread"), with `badgeLabel` defaulting to the badge text. Tabs
+  without a badge are unchanged.
+
+- **`@kerfjs/ui` `ListItem` and `ListActionRow` labels stay out of the
+  trailing slot.** A long single-word primary label (such as a Catalog sidebar
+  entry named `ConnectionStateBanner` in a narrow rail) no longer runs
+  underneath trailing status text. Single-line rows now end the primary label
+  and description with a real ellipsis (previously the text was cut mid-glyph
+  with no "…"), and `multiline` rows break a word wider than the label column
+  onto the next line.
+
+- **Custom elements keep the `role` and `aria-*` they set on themselves across
+  re-renders.** Web components conventionally own their host's ARIA (Web
+  Awesome's `wa-option` sets `role="option"` / `aria-selected`, `wa-divider`
+  sets `role="separator"`; Shoelace and FAST do the same), but a template never
+  mentions them, so the morph and the keyed-list attribute fast path stripped
+  them on the next re-render. On any custom element (hyphenated tag), `role`
+  and `aria-*` are now element-owned like `open`: never removed just because
+  the template omits them. The template can still set or change them, a signal
+  binding set to `null` / `false` still removes them, and plain elements are
+  unchanged. Trade-off: omitting one from a static template no longer removes
+  it from a custom element — render an explicit value (`aria-pressed="false"`)
+  instead.
+
+- **`@kerfjs/ui` layout regions no longer slow edits to long lists inside
+  them.** The rule that clears the safe-area context for the children of a
+  Workbench main area or panel, SplitView list or detail, NavStack view,
+  TabScaffold scene, or CollapsiblePanel content made each child re-check the
+  region in Chromium on every DOM change. A 1000-row list placed directly in
+  one of these regions took about 46ms per style recalculation (2ms with the
+  list one level down), and now takes about 0.2ms. Layout and insets are
+  unchanged.
+
+- **`@kerfjs/ui` `CollapsiblePanel` no longer slows insertions into long
+  lists.** An expanded inline panel clears its screen edge for its siblings;
+  the rules that did so selected the siblings themselves
+  (`:has(~ panel)` and `panel ~ *`), which in Chromium made each row inserted
+  into or removed from a long list restyle the list's other rows — about
+  14.6ms instead of 0.2ms per insertion beside a 1000-row list. The panel's
+  container now carries a flag that a CSS style query reads, so a list pays
+  nothing. The edge still clears for the panel's siblings and returns when it
+  collapses; the one difference is that a sibling placed before a left panel
+  or after a right or bottom panel now loses the edge too.
+
+- **`@kerfjs/ui` restore corners and covered floating controls no longer slow
+  every style recalculation.** The `CollapsiblePanel` / `ResizableRegion`
+  restore-corner anchor scope (`:has(> restore) > * > * > *`) and the static
+  side-overlay covered flag (`:has(> open overlay) > :not(overlay)`) put a
+  universal selector after a `:has()` container, which in Chromium restyled
+  the children of every ancestor of each DOM change — about 85ms instead of
+  1ms per edit beside a 1000-row list. The drawer now publishes its anchor
+  only beside a restore control's container (or its work-area column), and
+  the covered flag is set on the overlay's container and cleared on its
+  overlay children. Restore-corner placement and covered-control hiding are
+  unchanged; a new CSS unit test rejects the costly `:has()` shapes.
+
+- **`@kerfjs/ui` adds `ContentItem`.** Import it from
+  `@kerfjs/ui/content-item` to render one self-contained pane child with the
+  shared 8px margin, 1px border, and 8px padding. Framing and shape are typed
+  props instead of hand-written modifier classes:
+  - `frame="framed"` paints the neutral border in the 1px the item always
+    reserves, so its geometry does not change (replacing
+    `class="kui-content-item kui-content-item--framed"`);
+  - `shape="pill"` selects the 22px radius.
+  - `ariaLabel` names a distinct region, and `focusTarget` makes the item a
+    programmatic focus target (`tabindex="-1"`), such as a NavStack view's
+    `data-nav-focus` target.
+
+  The `.kui-content-item` classes stay public for elements that must carry the
+  geometry themselves; their CSS now lives in `content-item.css`, which
+  `layout.css` still imports. There is no filled variant — use `SunkenPanel`
+  for a lowered surface. The catalog, demos, and recipes use the component.
+
+- **`@kerfjs/ui` icon-only toolbar buttons show the same help tag.** An
+  icon-only `<button>` or link inside a `ToolbarControlGroup`, named by
+  `aria-label` with no visible text, now shows the help tag icon-only Selects
+  and PopupMenus show, with the same 500ms hover delay, keyboard-focus-only
+  display, press/Escape dismissal, and quick scanning along a toolbar. The tag
+  is `aria-hidden` and never renames the button. A button with a native
+  `title`, or with its own Web Awesome tooltip, keeps that and gets no second
+  tag. The `select/register` and `popup-menu/register` imports install it; a
+  toolbar with icon-only buttons but neither control imports the new
+  `@kerfjs/ui/help-tags/register` subpath, which registers only the tooltip.
+
+- **`@kerfjs/ui` icon-only Select and PopupMenu triggers show a help tag.**
+  An icon-only `Select` (single or `multiple` with `triggerIcon`) and an
+  icon-only `PopupMenu` now show a Web Awesome tooltip naming the control on
+  hover (after 500ms) and on keyboard focus: a filter reads "Filter by label:
+  Bug, Docs", a single Select its name and current choice, a menu its `label`.
+  It hides while the popup is open, on a press, and on Escape. The tag repeats
+  the accessible name, so it is `aria-hidden` and never joins
+  `aria-labelledby`; screen readers still hear the name once. It is installed
+  by the existing `select/register` and `popup-menu/register` imports, needs no
+  props, and never appears for labeled Selects or text menu triggers.
+
+- **`@kerfjs/ui` toolbar groups drop their focus ring while a popup is open.**
+  A `ToolbarControlGroup` that owns the ring (`focusRing="outline"` or
+  `"halo"`) no longer paints it while a Select listbox or `PopupMenu` inside it
+  is open; the open popup shows focus, and the ring returns when the popup
+  closes with focus still in the group. This matches the per-control Select
+  and PopupMenu triggers.
+
+- **`@kerfjs/ui` multiple `Select` can be an icon-only toolbar filter menu.**
+  Set `selectedPresentation: 'icon-only'` on a `multiple` Select together with
+  a fixed `triggerIcon` (for example a funnel `LucideIcon`); the types require
+  `triggerIcon` there and reject it everywhere else. The trigger keeps the
+  icon-only caret pill used in a `ToolbarControlGroup`, and:
+  - shows the fixed icon whatever is chosen;
+  - adds a compact count `Badge` while any choice is chosen;
+  - ends the combobox's accessible name with the chosen labels in choice order
+    ("Filter by label: Bug, Docs"), leaving the hidden value text empty so the
+    list is not announced twice.
+
+  The popup still stays open while choices toggle.
+
+- **`@kerfjs/ui` `Select` options keep their accessibility semantics across
+  re-renders.** Re-rendering a Select (for example after its `change` handler
+  updates the controlling signal) removed the `role="option"` and
+  `aria-selected` Web Awesome sets on each option, so screen readers lost every
+  option's role and selected state. They now survive in single and `multiple`
+  Selects through the core rule below (custom elements own their `role` /
+  `aria-*`), with no Select-specific restore.
+
+- **`@kerfjs/ui` `Select` dividers keep their separator role across
+  re-renders.** The `wa-divider` a `separatorBefore` choice adds lost the
+  `role="separator"` and `aria-orientation` Web Awesome sets on it the first
+  time the enclosing mount re-rendered, and never got them back, so assistive
+  technology stopped announcing the break between option runs. The Select now
+  renders both attributes itself.
+
+- **`@kerfjs/ui` `Select` and `PopupMenu` re-renders no longer force Web
+  Awesome updates.** Web Awesome reflects its default `size`, `appearance`,
+  `placement`, and `orientation` onto `wa-select`, `wa-dropdown`, and
+  `wa-divider`; the templates omitted them, so every re-render of the enclosing
+  mount stripped them and each host ran a full Lit update to put them back. The
+  templates now render those defaults (`wa-select size="m"
+appearance="outlined" placement="bottom"`, `wa-dropdown size="m"`, divider
+  `orientation="horizontal"`), so an unchanged re-render leaves the hosts
+  alone. No visual change. The `@kerfjs/ui/webawesome` JSX declarations type
+  these attributes.
+
+- **`@kerfjs/ui` Workbench and CollapsiblePanel panes and chrome lists are
+  configurable.** The `Pane`s these layouts compose around app content now
+  take the new `PaneConfig` type (`contentElement`, `contentLabel`,
+  `separators`, `safeAreaEdges`): a Workbench panel's or `CollapsiblePanel`'s
+  `pane`, and the Workbench's `mainPane`. The `List`s holding `mainHeader` /
+  `mainFooter` take the new `ListConfig` type (`gap`, `hAlign`, `vAlign`,
+  `dividerSides`, `textInsets`, `controlInsets`) through `mainHeaderList` /
+  `mainFooterList`. Previously this configuration was hard-coded, so, for
+  example, a navigator rail could not render its content as a `nav` landmark
+  without restyling. Omitted or `undefined` fields keep today's defaults, and
+  the default markup is unchanged.
+
+- **`@kerfjs/ui` `SplitView` forwards its `ResizableRegion` and compact
+  `NavStack` configuration.** `resizable` now also takes the list region's
+  `separator`, `handleIcon`, `contentOverflow`, and collapse options
+  (`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`,
+  `restorePosition`), so an app can hide the list and float a restore control
+  without leaving `SplitView`. The new `compactStack` prop forwards the compact
+  stack's `toolbarConfig`, `backIcon`, `backText`, `hideToolbar`, and
+  persistent `bottomToolbar`, and gives the list and detail views their own
+  toolbar groups (`list` / `detail`: `leading`, `center`, `toolbar`,
+  `bottomToolbar`). Omitted options keep today's defaults.
+
+- **`@kerfjs/ui` `NavStack` renders its top chrome as a real `Toolbar`.** The
+  back control is a borderless `ToolbarControlGroup` and the title a
+  `ToolbarText` in the leading zone, and the stack now forwards:
+  - `toolbarConfig` — the `Toolbar` configuration (`dividerSides`,
+    `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) plus `label`,
+    `titleSize` (default `large`), and `headingLevel`;
+  - per-view `leading` and `center` groups beside the existing trailing
+    `toolbar`;
+  - `backIcon` and visible `backText` for the back control.
+
+  The defaults keep today's bar: no divider, one 44px band, and the top and
+  side safe-area edges claimed. The hand-rolled `kui-nav-stack__lead` and
+  `kui-nav-stack__actions` wrappers are gone (their content now sits in the
+  toolbar's zones), and `kui-nav-stack__back` / `kui-nav-stack__back-icon`
+  are no longer styled by the stack.
+
+- **`@kerfjs/ui` configures with props instead of token overrides.** Five
+  settings apps previously reached through raw `--kui-*` overrides now have a
+  typed prop or modifier; each defaults to today's rendering, and the
+  underlying tokens keep working:
+  - `FloatingToolbar` `inset` (a `CssLength`, default `--kui-space-m`) moves
+    it from the container edges. Omit it inside a restore corner, which owns
+    the inset.
+  - `DisclosureArrow` `size` (a `CssLength`, default 18px root-scaled).
+  - `ListHeader` `headingLevel` (1–6, default 2) sets the label's native
+    heading element for passive and trailing-action headers; a toggle header
+    has no heading and rejects it at compile time.
+  - `TokenSearchField` `clearIcon` replaces the clear action's glyph.
+  - `.kui-content-item--framed` paints the standard neutral border on a
+    content item that marks a real distinction, with no geometry change.
+
+  The docs and AI guidance also stop recommending `--kui-edge-inset-*`
+  overrides: an app-owned arrangement passes `safeAreaEdges` to its panes and
+  edge-claiming toolbars (including the layout toolbar configurations, which
+  forward it).
+
+- **`@kerfjs/ui` hides a work area's floating controls under an open side
+  overlay.** While a side overlay is open — a Workbench rail (static
+  `presentation: "overlay"`, or a responsive overlay whose breakpoint applies),
+  a `wireSidebar` compact overlay or `presentation="overlay"`
+  `CollapsiblePanel`, or a horizontal `presentation="overlay"`
+  `ResizableRegion` — the covered work area's `FloatingToolbar`s and the
+  layouts' restore corners are now hidden (`visibility: hidden`, so they also
+  leave the tab order and the accessibility tree) instead of relying on
+  stacking order alone. A phone-width app could otherwise paint the main
+  column's floating drawer toggle over its open inspector. They come back as
+  the overlay closes; the overlay's own floating controls and a bottom
+  drawer's overlay are unaffected.
+
+- **`@kerfjs/ui` `Select` supports multiple selection.** Set `multiple: true`
+  and pass the chosen values as an array `value`; the props are typed so an
+  array value requires `multiple`. Behavior:
+  - The popup stays open while the person toggles choices with the pointer,
+    Enter, or Space, and closes only on an outside press, Escape, or focus
+    leaving.
+  - Each chosen option shows a check.
+  - The closed control summarizes the chosen labels in choice order as a short
+    localized list, or shows `placeholderText` when none are chosen.
+  - `change` / `input` report the value array, and a form submits every chosen
+    value under `name`.
+  - Re-rendering with a different `value` updates the selection even after the
+    person has interacted.
+
+  `renderSelected` and `selectedPresentation="icon-only"` stay single-value
+  only.
+
+- **`@kerfjs/ui` `PopupMenu` now looks exactly like `Select`.** Both read one
+  shared popup contract, so a command menu beside a value list in a toolbar
+  draws the same popup. `PopupMenu` changes:
+  - its caret turns to face the open menu;
+  - its menu fades in without scaling;
+  - it takes the Select listbox's 4px inset (also under the default
+    `menuInset="standard"`);
+  - its rows use the Select option's height, padding, and reserved check
+    column, and its icons use the same 16px size and 8px gap;
+  - a keyboard-focused item takes the Select's current-option fill instead of
+    a focus ring;
+  - headings render as the Select's uppercase group titles rather than slotted
+    `h3` elements.
+
+  An open `Select` also no longer paints its trigger focus ring. The open
+  listbox shows focus, and the ring returns when it closes.
+
+- **`@kerfjs/ui` `Catalog` exposes its sidebar and toolbar configuration.** New
+  `sidebar` prop (size, `resizable`, `separator`, `collapseMotion`,
+  `presentation`, `responsiveOverlayAt`, `compactOverlay`, and the header
+  `toolbar`'s `ToolbarConfig`) forwarded to its Workbench rail, plus
+  `mainToolbar` / `footerToolbar` `ToolbarConfig` props. `wireCatalog` takes
+  `sidebarSize` / `sidebarStorageKey` to wire a resizable sidebar. Today's
+  288px fixed sidebar and toolbar policies remain the defaults.
+
+- **`@kerfjs/ui` composed toolbars are configurable.** `WorkbenchMainToolbar`,
+  `WorkbenchMainBottomToolbar`, and the panel `toolbar` of a Workbench panel or
+  `CollapsiblePanel` now take the `Toolbar`'s configuration: the new
+  `ToolbarConfig` type, covering `dividerSides`, `centerAlign`, `responsive`,
+  `responsiveAt`, and `safeAreaEdges`. Previously their dividers were
+  hard-coded, so for example dropping the line between a toolbar and its
+  content took CSS. Today's dividers remain the defaults. Also:
+  - `mainBottomToolbar` and panel toolbars take a `center`;
+  - panel toggles take localized `showLabel` / `hideLabel`;
+  - a Workbench panel's floating restore controls follow its
+    `restorePosition`.
+
+- **Breaking (`@kerfjs/ui`): removed the pre-release compatibility surface.**
+  - The `DividerSides` type is gone; use `Sides`, from the renamed `sides`
+    module.
+  - `ListInsetText.horizontalOnly` and its `kui-list-inset-text--horizontal`
+    class are gone; pass `sides="rl"` instead.
+  - The legacy color tokens are gone, both as `--kui-color-*` properties and
+    as `uiColor()` names. Replace them with their canonical tokens:
+
+    | Removed                                       | Use instead             |
+    | --------------------------------------------- | ----------------------- |
+    | `border`                                      | `neutral-border-normal` |
+    | `border-quiet`                                | `neutral-border-quiet`  |
+    | `accent`                                      | `brand-fill-normal`     |
+    | `accent-text`                                 | `brand-on-quiet`        |
+    | `pop`                                         | `pop-fill-quiet`        |
+    | `pop-text`                                    | `pop-on-fill`           |
+    | `success`, `warning`, `danger`                | `*-fill-quiet`          |
+    | `success-text`, `warning-text`, `danger-text` | `*-on-quiet`            |
+
+- **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%
+  black), which all but vanished against the dark page, and the
+  `--kui-shadow-s` / `--kui-shadow-l` foundation fallbacks copied those fixed
+  values. The theme now pairs each light alpha with a stronger dark one (50%,
+  40%, 32%) through `light-dark()`, and the foundation fallbacks mirror them, so
+  selected segments and app tabs, compact overlay panels, and Web Awesome
+  surfaces that read `--wa-shadow-*` keep their elevation in dark mode. Light mode is unchanged. The browser parity test
+  now compares every `--kui-shadow-*` token with and without the theme in both
+  schemes.
+- `@kerfjs/ui` text on loud tone fills clears WCAG AA in both color schemes,
+  with or without the optional `@kerfjs/ui/webawesome.css` theme. White
+  `on-loud` text reached about 2.2:1 on the success fill, 3.5:1 on the light
+  brand fill (`#0088ff`), and 3.6:1 on the danger fill (`#ff383c`) in both
+  schemes. Kerf's theme layer and the foundation fallbacks now pair each
+  fill with a foreground chosen to keep the tone's look: success keeps its
+  bright green with dark text (`#1d1d1f`, 7.6:1), as warning already did; light
+  brand and danger keep white text on a slightly deeper fill of the same hue
+  (`#0075db`, 4.6:1; `#eb0005`, 4.6:1); dark danger keeps its fill with dark
+  text (`#111113`, 5.3:1), as dark brand already did. Web Awesome accent
+  buttons, badges, and checked controls pick this up, and accent `wa-badge`s now
+  use their variant's `on-loud` foreground by default instead of a fixed dark
+  color (`--kui-wa-badge-accent-foreground` still overrides it). The browser
+  contrast test asserts every tone's `on-loud` over `fill-loud` pair, including
+  pop and neutral, in both schemes with and without the theme.
+- `@kerfjs/ui` brand, success, and warning text clears WCAG AA on the lowered
+  page background in light mode, with or without the optional
+  `@kerfjs/ui/webawesome.css` theme. Their light `on-quiet` values (`#1e6ef4`,
+  `#008932`, `#a16a00`) passed on the white surface but reached only about
+  4.1:1 on `#f2f2f7`. Kerf's theme layer and the foundation fallbacks now use
+  the same hues a step darker: `#0c62f3` (4.64:1), `#007f2e` (4.62:1), and
+  `#966200` (4.65:1) on the page, about 5.2:1 on white. Links, selected tabs,
+  segmented and toolbar selections, and token-search accents that read
+  `brand-on-quiet` darken with it. Dark mode is unchanged. The browser contrast
+  test no longer skips light text over the page background.
+- `@kerfjs/ui` surfaces, links, and focus rings match the optional
+  `@kerfjs/ui/webawesome.css` theme without it. Three foundation fallbacks
+  pointed at a different token than the theme: `--kui-color-surface-raised`
+  fell back to the surface color (the theme's dark raised surface is
+  `#2c2c2e`), `--kui-color-text-link` fell back to the brand fill (`#0088ff`,
+  about 3.5:1 on white) instead of the brand on-quiet text color, and the focus
+  ring used the brand fill instead of the theme's focus color (`#007aff`). Each
+  now falls back to the theme's value. The browser parity test now covers every
+  `--kui-color-*` token the foundation declares, plus the focus ring, instead of
+  only the tone tokens.
+- The `@kerfjs/ui` UX catalog's `StateBanner` route adds a placeholder with a
+  badge for every tone, next to the existing badge-less placeholder, so visual
+  review and captures show the solid badge's loading skeleton on each tone's
+  fill. A browser test checks that each tone's badged placeholder is present.
+- `@kerfjs/ui` toned text stays readable in dark mode without the optional
+  `@kerfjs/ui/webawesome.css` theme. The foundation's fallbacks for the
+  success, warning, and danger `on-quiet` and `on-normal` tokens were single
+  light-mode colors, so dark danger `Text` rendered dark red on a dark surface
+  (under 3:1). Every tone token now falls back to the same light and dark
+  pair the theme assigns, including `brand-on-loud` (dark text on the pale dark
+  brand fill instead of white) and `neutral-border-quiet`. Light-mode colors
+  are unchanged. A browser test bundles the package with and without the theme
+  and asserts that every tone token resolves identically in both color schemes
+  and that toned text clears WCAG AA in dark mode.
+- `@kerfjs/ui` danger text and badges are readable in dark mode, and every
+  tone's `StateBanner` detail and quiet or outline `Badge` text now clears
+  WCAG AA. The danger tone was the only one without an on-fill foreground: its
+  solid badge fill and `StateBanner` text reused `danger-on-quiet`, a mid red
+  in dark mode (banner detail 4.0:1, badge placeholder skeleton 2.25:1). A new
+  `--kui-color-danger-on-fill` token (also accepted by `uiColor()`) matches the
+  other tones' pale dark values, lifting the dark danger banner text to 8.2:1.
+  The banner detail no longer dims to 78% opacity, which left the light info,
+  success, warning, and danger details at 3.4 to 4.3:1; it reads as secondary
+  through its smaller type, and the neutral detail uses the quiet text color.
+  Quiet and outline badges use their tone's on-fill text, lifting light brand,
+  success, and warning from about 4.1:1 to at least 5:1.
+
+- A `@kerfjs/ui` placeholder skeleton inside a solid `Badge`, such as the
+  badge of a `StateBanner` placeholder, is now clearly visible. The generic
+  skeleton tint, 12% of the text color, almost disappeared on the badge's
+  saturated fill in every tone. A solid badge now tints its skeleton from its
+  own foreground color, which contrasts with the fill in every tone in light
+  and dark mode. Quiet and outline badges keep the generic tint, which already
+  reads on their pale fills. Geometry is unchanged.
+- The `@kerfjs/ui` SVG design templates render badges as filled pills: the
+  `StateBanner` badge and the `ListHeader` and `List` count pills used to show
+  as plain text, because the template build loaded only a hand-written list of
+  stylesheets that omitted `badge.css`. The build now loads each component's
+  full stylesheet set from its generated browser entry, the same set a
+  consumer's browser import loads, so a nested component's CSS can no longer be
+  missed. The `ListHeader` and `List` templates also pick up the label inset
+  from `text.css`, so a header label now lines up with the list items below it,
+  as it does in the live component.
+- A `@kerfjs/ui` `StateBanner` placeholder's badge sits at the live badge's
+  height on every platform. With a skeleton instead of text, the badge took a
+  baseline from the skeleton's bottom edge and sat about a pixel higher, by an
+  amount that depended on the platform's font metrics.
+- A `@kerfjs/ui` `StateBanner` with a long, wrapping title keeps its badge
+  one item gap after the title's last word, and its detail uses the full copy
+  width. The wide flex layout shrank the title and detail together, which left
+  a large gap before the badge and truncated the detail early. The title,
+  badge, and detail now flow as inline text: the detail stays beside the title
+  while it fits whole, and otherwise moves to its own line, truncating only at
+  the full width. A wrapped title's lines stay evenly spaced.
+- A `@kerfjs/ui` `ListHeader` disclosure toggle disabled with `actionDisabled`
+  is dimmed by the component itself, at the same tone as a disabled action
+  button, and shows the `not-allowed` cursor. It used to rely on Web Awesome's
+  native `button:disabled` dimming, so without `webawesome.css` it looked
+  enabled. Disabled toggles and action buttons also no longer show hover
+  feedback without `webawesome.css`.
+- A `@kerfjs/ui` `ListActionRow` placeholder keeps its `busy` spinner. The
+  whole status line used to collapse into one skeleton, dropping the spinner
+  the component draws from a known prop. Now only the `status` text becomes a
+  skeleton, matching `ListItem`.
+- **A tooltip or popover already showing stays visible when a modal opens.**
+  Lifting a surface above an open modal `<dialog>` was decided only when the
+  surface opened, so a tooltip or popover already on screen when a modal
+  dialog opened was left inert beneath it. Whenever `kerfjs/overlay` opens a
+  modal `<dialog>` (a `native: true` modal, or one it lifted), it now moves
+  every open tooltip and popover into the top layer above the new dialog. One
+  that is already a `[popover]` is re-shown so it stacks on top. The existing
+  `kerfjs/dev` warnings still report an engine without the Popover API, and a
+  surface with controls the modal keeps inert. A modal `<dialog>` the app
+  opens itself, outside kerf, is not observed.
+- Moved `mount()`'s list-binding lifecycle (turning list markers into
+  bindings, first-render row-contract validation, orphan pruning) into its own
+  internal module, so `mount.ts` holds only the render orchestration. No
+  behavior or public API change.
+- A narrow (576px and below) `@kerfjs/ui` `StateBanner` keeps its badge
+  sized to its content, one item gap after the title and on the title's
+  baseline, as in the wide layout. The narrow grid stretched the badge across
+  the free column into a wide pill that sat less than 1px from the title.
+- Hovering a `@kerfjs/ui` `ListActionRow` placeholder with
+  `trailingActionVisibility="interaction"` no longer reveals its disabled
+  trailing button. A placeholder is inert, so it keeps the live row's resting
+  state, with the trailing action hidden until an interaction it cannot take.
+- A `@kerfjs/ui` `ListItem` placeholder keeps its `busy` spinner. The whole
+  trailing slot used to collapse into one skeleton, dropping the spinner the
+  component draws from a known prop and shifting the label's width. Now only
+  the values in that slot become skeletons: `status` text in its status line
+  and author-supplied `trailing` content (always a value, since the component
+  cannot tell a chevron from a count) each get their own.
+- `@kerfjs/ui` placeholders keep the live disabled tone of a control the
+  author disabled. A disabled `ListItem` or `ListActionRow`, a
+  `trailingActionDisabled` button, a disabled `SegmentedControl` choice, or a
+  `ListHeader` with `actionDisabled` rendered at full opacity as a
+  placeholder, because the placeholder reset could not tell its own
+  `disabled` attribute from the author's. Those controls now carry a
+  component-owned `data-kui-disabled="true"` marker whenever their disabled
+  prop is set; the disabled tone keys on it and the placeholder reset skips
+  it. The marker is reserved: the extension-attribute props cannot set it.
+- `@kerfjs/ui` adds a browser test that renders every placeholder-capable
+  component live and as a placeholder from identical props and diffs each
+  element's geometry and computed chrome, so any future drift outside a value
+  slot fails. It caught one more: a `ListActionRow` placeholder's `status`
+  line was 3.5px shorter than the live line; the status line now always
+  keeps a full line height.
+- `@kerfjs/ui`'s `Select` placeholder hint now matches the live hint: 14px
+  text at a 1.6 line height, 7px below the box. It was 12px / 1.4 with a 4px
+  gap, so a placeholder with a `hint` was 8.6px shorter than the loaded
+  control and the content below it jumped when loading finished.
+- `@kerfjs/ui`'s `StateBanner` placeholder adds a detail skeleton only when
+  `detail` is set, matching the live banner. Previously every placeholder
+  showed a detail line, so a banner without one changed shape when loading
+  finished. Pass the banner's real `title` and `detail` with `placeholder`;
+  an empty `detail` now means no detail line.
+- `@kerfjs/ui`'s `AppTab` placeholder pill is no longer dimmed to 50% with a
+  `not-allowed` cursor when `webawesome.css` is loaded; it keeps the live
+  tab's tone, and only its name is a skeleton.
+- `@kerfjs/ui`'s `ListHeader` placeholder no longer dims its action button
+  (48%) or, in `toggle` mode, the whole title and label (Web Awesome's native
+  50%), and its inert action and toggle give no hover feedback. A live
+  `actionDisabled` header still dims its action.
+- `@kerfjs/ui`'s `SegmentedControl` placeholder now keeps its choices. The
+  choices are known; only the selection is unknown, so a placeholder renders
+  every choice's live label or icon at its live size, selects none, and stays
+  inert. Previously every segment became a 4em text skeleton (widening icon
+  segments from 40px to 60px) and was dimmed to 45%.
+- `@kerfjs/ui`'s `ListItem` and `ListActionRow` placeholders now match the
+  live row. They are no longer dimmed (the rows' own `:disabled` tone and
+  hover highlight skip placeholders), and a row with a `description` (or a
+  `ListActionRow` `status`) keeps that line as a second, smaller skeleton, so
+  the row keeps its live height instead of collapsing to one line. The
+  `ListActionRow` icon placeholder is an 18px block centered in its icon slot,
+  like `ListItem`'s.
+- `@kerfjs/ui` placeholders no longer look disabled. A component's
+  `placeholder` keeps its controls `disabled` (inert and out of the keyboard
+  order), but `skeleton.css` now neutralizes generic disabled chrome under
+  `[data-placeholder="true"]`: full opacity and the default cursor instead of
+  Web Awesome's native `button:disabled` dimming to 50% with a `not-allowed`
+  cursor. A component's own opacity (a control hidden until interaction) still
+  applies.
+- `toElement('<image href="…" />')` now returns an SVG `<image>`. The HTML
+  parser rewrites an orphan `<image>` to an HTML `<img>` before kerf sees the
+  tag, so it previously came back as an XHTML `img` that no `<svg>` would
+  render. kerf now recognizes a leading `<image` tag in the raw input
+  (case-insensitive, after leading whitespace) and parses it through the SVG
+  wrapper. A genuine `<img>` is unchanged.
+- `delegateActions()` (`kerfjs/actions`) dispatches only the table's own
+  entries. It used to look the action up with a plain property read, so a
+  `data-action` naming an inherited `Object.prototype` member resolved:
+  `"__proto__"` or `"hasOwnProperty"` threw a `TypeError` from the listener,
+  and `"toString"` or `"constructor"` silently ran the inherited function.
+  Those values are now ignored like any other action absent from the table.
+  An own entry with such a name (`{ toString: … }`) still dispatches.
+- `toElement()` now puts orphan camelCase SVG fragments in the SVG namespace.
+  `toElement('<linearGradient>…</linearGradient>')`, and likewise `clipPath`,
+  `radialGradient`, and `foreignObject`, previously returned an XHTML
+  `LINEARGRADIENT` element that no `<svg>` would render, because the lookup
+  compared the HTML parser's lowercased tag against camelCase names. The
+  fragment is now wrapped in `<svg>` and XML-parsed like `<path>` or `<g>`,
+  and the returned element keeps its camelCase `localName`.
+- **A tooltip or popover no longer outlives its anchor.** When the anchor left
+  the document, most commonly because the modal containing it closed, the
+  `tooltip()` or `popover()` stayed on screen: a removed element fires no
+  `pointerleave` or `blur`. Both now watch their anchor with the same removal
+  tracking as `kerfjs/attach`. The tooltip hides, and the popover closes
+  without calling `onDismiss`, as soon as the anchor leaves the document.
+  Moving the anchor within the document keeps them open. A tooltip show still
+  pending when its anchor is removed never appears.
+- **Overlays opened over a modal `<dialog>` are visible and usable.** A browser
+  makes everything outside an open modal dialog inert and paints a plain
+  element beneath it, so a `tooltip()`, `popover()`, or `confirm()` opened
+  from inside a `native: true` dialog without `native` itself was invisible and
+  could not be used. While a modal `<dialog>` is open, `kerfjs/overlay` now
+  hosts such a surface in the top layer anyway: a tooltip or popover becomes a
+  `[popover]`, and a nested modal becomes its own `<dialog>`. The browser's
+  default `[popover]` / `<dialog>` styles then apply, as they do with `native:
+true`. Browsers keep a popover outside the modal dialog inert even in the top
+  layer, so a lifted popover with buttons is visible but not clickable. A new
+  always-on `kerfjs/dev` warning reports that case, and an engine without the
+  needed API.
+- **A tooltip shown inside a modal no longer disables the modal.** `kerfjs/overlay`
+  used to treat the most recently opened overlay as the only one that could
+  react to input, so a `tooltip()` (which handles no input) inside an open
+  modal left Escape doing nothing and let Tab leave the dialog. Every overlay,
+  native or fallback, now joins one open-order stack, and each Escape, backdrop
+  click, outside click, or trapped Tab goes to the topmost surface that handles
+  it. A modal still blocks everything beneath it, and a surface that handles
+  nothing never intercepts. A popover that dismisses on Escape gets it before
+  the modal beneath. One click that is both outside a popover and on a modal's
+  backdrop now closes only the popover. A native `<dialog>` is arbitrated with
+  the fallback surfaces: one Escape closes one surface, and a fallback modal
+  beneath an open dialog no longer takes the dialog's Tab. Closing a lower
+  overlay first leaves focus in the overlay that holds it. An overlay opened
+  from inside it then restores focus to the closed overlay's opener, not a
+  detached node.
+- `kerfjs` now exports the `EachOptions<T>` type (`{ cacheKey?, key? }`), the
+  options-object form of `each()`'s third argument, so a helper that builds or
+  forwards those options can import the shape instead of restating it:
+  `import { type EachOptions } from "kerfjs"`. Type-only; no runtime or bundle
+  change.
+- Documentation: the companion-utility reference now matches the code. The
+  router's `match()` / `activeClass()` compare a literal path prefix, so
+  `match('/users/:id')` is never true. Link interception still applies to
+  `target="_self"`, the no-match `outlet()` is `null` with `params` `{}`,
+  components receive `(params, route)`, and hash mode keeps `route.hash` at
+  `''`. Invalid `bindList` configuration throws only `RangeError`. `popover()`
+  defaults `className` to `'kerf-popover'`, and the toast region is a reused
+  `.kerf-toasts` element when one exists. A `resource()` `cacheKey` applies
+  only to `run(input, fetcher)`, and throttle's `flush()` leaves the cooldown
+  running. `delegate()` / `delegateCapture()` throw on an invalid selector at
+  registration. The reference also now lists the `kerfjs/jsx-dev-runtime`
+  alias, the `DEV_HOOKS` export of `kerfjs/dev`, and `Signal#peek()`.
+- Documentation: `morph(liveRoot, template)` is now described as it behaves.
+  It reconciles only the root's children and never touches the root's own
+  attributes, so `template` describes the content inside the root (an
+  `Element` template contributes its child nodes). The examples no longer
+  nest a duplicate `<article>` inside the live one. An `each()` list parent is
+  not a children-only short-circuit: the diff still walks it and skips only
+  the owned rows. The user-agent-owned `open` exception covers custom elements
+  as well as `<details>` / `<dialog>`, and a content-only row change inside an
+  `each()` list keeps its DOM node (and focus) unless the row's top-level tag
+  changes or the same render also inserts, removes, or moves rows.
+- Every opt-in `kerfjs/dev` warning now ends with a silence hint that leads
+  with the browser-reachable switch, for example "Silence it with
+  enableWarnings({ narrowSet: false }) from kerfjs/dev, or set
+  KERF_DEV_WARN_NARROW_SET=0 (or unset it) under Node." Previously the
+  messages named only the environment variable, which a browser cannot reach.
+  The docs now teach `enableWarnings()` wherever they showed an env-only
+  switch, and name all three creation-time boundaries: `signal()`
+  (`untrackedSignals`), `effect()` (`delegateInEffect`), and `mount()`
+  (`rebuiltListeners`) decide once when created, so anything created before
+  the install or the opt-in stays uncovered.
+- The `kerfjs/dev` rebuilt-listeners warning (`rebuiltListeners` /
+  `KERF_DEV_WARN_REBUILT_LISTENERS`) now dedups once per `mount()`, as
+  documented. Previously the first warning silenced every other mount for
+  the life of the process, so a second mount with the same bug stayed quiet.
+- `kerfjs/router`: a second router on the same document no longer diverges
+  from the URL after a link click. The first router's interceptor navigates
+  with `pushState`, which fires no `popstate`, so the second router ignored
+  the already-handled click and kept the old route. An already-handled click
+  now re-syncs the route from the URL; when nothing navigated, it is a no-op.
+  One router per document remains the supported shape: a second router does
+  not follow another router's programmatic `navigate()` (no `popstate` fires
+  and routers do not broadcast to each other) until the next `popstate` or
+  link click. This is now documented and pinned by a test.
+- `kerfjs/scope`: a disposed `Scope` handle no longer leaks registrations.
+  Previously `add` / `mount` / `effect` / `delegate` on a handle after its
+  `dispose()` (or from a disposer while `dispose()` ran) pushed into a list
+  nothing would ever run, leaving the effect subscribed or the listener
+  attached. Such a registration now tears down at once: `add(fn)` calls `fn`
+  immediately, and the wrappers create and immediately dispose.
+- `bindList` measured-height virtualization no longer applies a stale
+  scroll-anchor correction. A `setHeight()` report for a row above the viewport
+  is now resolved when the animation frame runs: if the source removed the key,
+  moved it below the fold, or the user scrolled the row into view first,
+  `scrollTop` is left alone, and several reports for one key in a frame net
+  out. Fixed-height windows also clamp to the source length, so a list that
+  shrinks while scrolled deep no longer pads far past its content.
+- `create-kerf-component` accepts an explicit `boundaries.rootClass: null` as
+  an author decision, as its schema always allowed. A wrapper whose root
+  element belongs to another catalog (a `rendersAs` wrapper) no longer has to
+  invent a class to satisfy the generator. An absent `rootClass` still fails
+  as undecided.
+- `@kerfjs/ui`'s `Select` placeholder now matches the live control. The label
+  uses the field-label style (uppercase, extra-small, quiet, inset to line up
+  with the value), and the chevron is the same glyph at the same size.
+  Previously the placeholder drew a larger, regular-weight label at a
+  different inset and a different, smaller chevron. Only the value is a
+  skeleton; the chrome no longer changes when loading finishes.
+- **Wrapper components can declare the cataloged root they render.** A
+  `kerf.components.json` component may set `composition.rendersAs`, for
+  example `["@kerfjs/ui:toolbar-control-group"]`: a list of the roots it
+  renders, any one of them, or nothing. `kerf-component-catalog` copies it
+  into the generated v2 entry and fails unless every key resolves to a
+  cataloged entry. `eslint-plugin-kerfjs`'s `ui-composition` rule, and so
+  `kerf-ui-doctor`, now loads the application and third-party catalogs a
+  `.kerf-ui-profile.json` declares. It resolves their components by package
+  subpath or source file and checks a wrapper as each declared root: a zone
+  must accept every root, each root's parent contract applies where the
+  wrapper is placed, and a wrapper counts as zero or one child. Undeclared
+  wrappers keep reporting `KUI-L202`.
+- `@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.
+- Moved the UX catalog checkerboard to the preview scroll owner and replaced
+  its four gradients with one repeated SVG tile, so the pattern continues
+  through below-fold content.
+- Added explicit native `slot` support to every stable single-root
+  `@kerfjs/ui` visual component, including alternate render branches, while
+  keeping multi-root `ResizableRegion` and `CollapsiblePanel` excluded.
+- Fixed the UX catalog's desktop grid sizing so both the sidebar and component
+  detail can scroll all the way to their final content while narrow layouts
+  retain normal document scrolling.
+- Fixed single-line `ToolbarText` clipping glyph descenders while retaining its
+  horizontal ellipsis behavior.
+- Formalized UX catalog demos as components, compositions, or recipes; catalogs
+  now group and order those kinds consistently and label compositions with a
+  visible tag instead of title suffixes.
+- Removed stale Web Awesome guidance that still advertised the deleted
+  aggregate theme route; focused component routes remain the supported catalog
+  surface.
+- Aligned Web Awesome Accordion and Details disclosure geometry: plain Details
+  keep a flush body, plain Accordion items use the 8px surface inset throughout,
+  framed Details use 16px on the trigger and 8px on the body, and framed
+  Accordion items use 16px throughout.
+- Added a first-class `@kerfjs/ui/grid` layout primitive for any positive
+  equal-width column count, with typed gap and flex values and zero-minimum
+  fractional tracks that stay equal when child content has different intrinsic
+  widths.
+- Made accent and filled-outlined Web Awesome badge variants meet WCAG AA at
+  their compact text size while preserving loud accent fills and outlined
+  borders.
+- Added independent typed `tone`, `size`, and `font` presentation roles to
+  `@kerfjs/ui/text`, covering quiet/danger copy, compact metadata, and monospace
+  identifiers without global utility classes or appearance-only heading levels.
+- Made filled Web Awesome badges use a quiet semantic fill with normal text by
+  default, preserving variant tint while meeting WCAG AA for their compact text.
+- Fixed nested Rows and Lists inheriting inset values for sides that were not
+  selected on the inner layout component.
+- Fixed migrated `Text` instances in Catalog and passive `ListHeader` labels
+  retaining nested padding or border geometry that offset their visible content.
+- Added `Row.vAlign="baseline"` for native flex cross-axis baseline alignment;
+  `List.vAlign` remains limited to values supported by vertical main-axis
+  distribution.
+- Added a first-class `@kerfjs/ui/text` component for native `h1`–`h6` and
+  paragraph semantics with standard transparent-border and content-padding
+  geometry and margin-neutral defaults; it renders `p` when `variant` is omitted,
+  and Kerf UI's headings and prose now use it.
+- Added the shared physical `Sides` contract to `List` and `Row` text/control
+  insets and to `ListInsetText` / `ListInsetControl`; inset wrappers now default
+  to all four sides, while `ListInsetText.horizontalOnly` remains a deprecated
+  compatibility alias for `sides="rl"`.
+- Added `ListHeader.inline` for shrink-wrapped section labels that remove the
+  component root's outer margin, border, and padding while preserving title,
+  count, action, and disclosure behavior.
+- Added a catalog-driven public-component integration validator for
+  `@kerfjs/ui`, including an all-at-once dry-run report across package, build,
+  barrel, CSS, demo, route, signature, and compatibility surfaces.
+- Added one change-local `@kerfjs/ui` verification command that synchronizes
+  generated projections, runs component/bundle/type coverage, builds the demo,
+  reports exact gzip deltas, and records reviewed budget updates with reasons.
+- Made every `@kerfjs/ui` Playwright invocation build current catalog source
+  after fast preflights, with a served source digest that rejects stale preview
+  output during focused browser runs.
+- Added durable Hot Sheet phase timing for active work, local verification,
+  push hooks, CI, and publication, including safe failure aggregation and
+  per-ticket summaries.
+- Added typed flex participation to `Row`, matching `List`'s boolean, finite
+  keyword, and branded `CssFlex` contract.
+- Added a first-class horizontal `Row` with typed spacing, physical-axis
+  alignment, and opt-in wrapping; `List` now supports the same alignment
+  vocabulary while retaining its existing defaults.
+- Refined compact mixed `ToolbarControlGroup` selections to retain standard
+  horizontal padding, remove the internal separator, and raise the selected
+  surface over the outer border; avatar group hover now preserves image fitting.
+- Moved the comprehensive local `npm run check` gate from pre-commit to
+  pre-push so coherent commit batches pay its cost once; pre-commit now performs
+  only Git's staged whitespace check, and multi-source AI guidance files are
+  excluded from repository-wide Prettier enforcement.
+- Fixed `create-kerf-component` releases carrying a stale composition-catalog
+  schema by generating the bundled copy from `@kerfjs/ui`'s canonical schema
+  and gating both the root check and interactive release flow against drift.
+- Added catalog-driven CSS value diagnostics across `eslint-plugin-kerfjs`,
+  `kerf-ui-analyze`, and `kerf-ui-doctor`. Stable `KUI-L013`–`KUI-L017`
+  findings now identify raw or unknown values, wrong-dimension helpers,
+  incomplete expressions, declaration-list escapes, and review-worthy
+  off-scale spacing from first- or third-party component catalogs.
+- Extended the property-specific `@kerfjs/ui/css-values` contracts: `List.flex`
+  now uses finite keywords or `flex()`, `Skeleton` dimensions use `CssSize` and
+  `CssLength`, and `SelectChoice.color` uses `uiColor()` or `colorVar()`.
+  Removed the unrestricted `style` escape hatches from `ListItem` and
+  `ListActionRow` before the 5.0 stable release; use `className`, public tokens,
+  and cataloged props instead.
+- Added typed, CSS-free `@kerfjs/ui/css-values` builders and branded complete
+  versus expression length types. `List.gap` now accepts direct spacing-token
+  shorthands or complete `CssLength` values and rejects unrestricted CSS strings.
+- Added the public recursive `JSXChildren` type from both `kerfjs` and
+  `kerfjs/jsx-runtime`, giving third-party function components a canonical
+  declaration for nullable, signal-backed, and arbitrarily nested readonly
+  child content that matches the runtime.
+- Added the public recursive `KerfUiContent` type across semantic UI content
+  zones, so nullable conditionals and mutable or readonly nested component
+  arrays compose directly without a `Fragment` while raw strings, numbers, and
+  signals remain rejected outside explicit text positions.
+- Fixed bottom `Workbench` drawers overshooting and snapping during collapse
+  transitions by anchoring fixed-height content to the shell's stable bottom
+  edge.
+- Fixed bottom `CollapsiblePanel` drawers overshooting their open position and
+  snapping back by anchoring fixed-height content to the panel's stable bottom
+  edge throughout the transform transition.
+- Formalized named `SafeHtml` prop slots as explicit `zone.jsx.prop` bindings
+  in the UI composition catalog and generalized `ui-composition` linting beyond
+  Toolbar, including statically visible `children`, cardinality, aliases,
+  namespaces, arrays, fragments, and branches.
+- Added `ToolbarControlGroup.avatarImage`, painting contained avatar imagery on
+  a lone group or on the pressed highlight when the group has multiple buttons.
+- Split the AppTab and TabBar catalog routes into focused component specimens,
+  and moved their controlled selection, tabpanel, overflow, add/close, and
+  reorder lifecycle into a separate application-tabs composition demo.
+- Fixed `wireNavStack` focus ownership across controlled navigation: pushes
+  focus the new top view, pops restore its remembered descendant, and removed
+  targets fall back through `data-nav-focus`, the first enabled control, and
+  the view container.
+- Fixed compact mixed-content `ToolbarControlGroup` dropdown triggers being
+  forced into an icon-only width, which painted the label across its separator
+  and the Web Awesome caret outside the group.
+- Made `ListItem` clip label, status, and dormant trailing painting to its
+  rounded row boundary so compact and constrained rows cannot visibly overflow;
+  described rows now grow enough to keep their owned two-line label readable.
+- Fixed compact toolbar `Select` focus to follow its owning group's pill or
+  rounded geometry and restored consistent spacing between popup icons and labels.
+- Fixed the compact-toolbar recipe's independent overflow action to use the
+  same full-height pill geometry as its adjacent toolbar controls.
+- Fixed the catalog footer's `Components` relationship selector to fit its icon
+  and plural label and give popup headings/items consistent border clearance.
+- Fixed a collapsible `TokenSearchField` inside a rounded
+  `ToolbarControlGroup` retaining its independent pill radius instead of using
+  the group's shared concentric highlight radius.
+- Updated the header-composition catalog demo's supporting copy to use the
+  horizontal `ListInsetText` geometry, aligning it with the value-table content
+  edge across responsive, RTL, and zoomed layouts.
+- Updated the `Pane` catalog demo's secondary header copy to use
+  `ListInsetText`, aligning it with the standard pane content gutter at wide and
+  narrow sizes instead of maintaining demo-only padding.
+- Completed `NavStack` navigation transitions by cross-fading top and bottom
+  chrome alongside content slides, added per-view bottom toolbars with a
+  persistent fallback, and replaced the static focused demo with a working
+  push/pop flow.
+- Replaced the static compact `SplitView` detail specimen with a controlled,
+  interactive list-to-detail drill-down whose Back action restores the list;
+  the roomy example now demonstrates controlled selection as well.
+- Documented and demonstrated list-first dialog bodies: use `List` with
+  `bodyInset="none"`, and wrap bare dialog copy in `ListInsetText` so content
+  shares the standard list gutter without double-insetting.
+- Fixed `@kerfjs/ui`'s collapsible `TokenSearchField` keep-open ownership in
+  WebKit: when `focusout.relatedTarget` is missing during pointer activation of
+  an external `data-token-search-keep-open` surface, the helper now uses the
+  actual pointer target instead of collapsing and removing the target before
+  its click handler runs.
+- Added a first-class vibrant `pop` semantic color for attractive non-status
+  emphasis, with complete light/dark/increased-contrast token roles and typed
+  StateBanner, ListHeader indicator, and ToolbarControlGroup selected tones.
+- Fixed canonical `Select` popup animation reversals so an earlier close cannot
+  hide a reopened menu after resizing. Canceled transitions retain the accepted
+  state, and removed controls cannot receive stale completion or deferred focus.
+- Fixed managed `TokenSearchField` Clear focus before the next input task, so
+  immediate typing stays in the replacement editor instead of triggering page
+  shortcuts; genuine later focus handoffs and selections remain untouched.
+- Fixed `@kerfjs/ui/tab-scaffold` bottom-tab labels being vertically clipped by
+  flex shrinkage while retaining horizontal ellipsis for long labels.
+- Made inset selection and hover highlights follow their owning control's pill
+  or rounded shape, with concentric inner radii derived from the full inset.
+- Fixed animated `ResizableRegion` overlays so remembered desktop dimensions
+  cannot make their content overflow the responsive panel cap on narrow screens.
+- Added configuration-first application-panel policies across `ResizableRegion`,
+  `Workbench`, and `CollapsiblePanel`: separator visibility, instant-track
+  collapse with optional composited content motion, popup-safe overflow,
+  inline/overlay/hidden responsive presentations, and safe-area restore-control
+  placement. `wireResizableRegions` now suppresses motion during pointer drags
+  and ignores unavailable regions; `wireSidebar` supports hidden compact
+  replacements and exclusive overlays.
+- Added typed `TabBar` allocation/presentation/action-placement and `AppTab`
+  presentation/size/label-width variants for segmented inspector strips,
+  compact drawer tabs, icon-only accessible tabs, and truncating labels.
+- Added typed `ToolbarControlGroup` size, density, content anatomy, selected
+  chrome/tone, nested-dropdown, and avatar scrim variants.
+- Added typed `Select` form, borderless-toolbar, intrinsic-navigation, compact,
+  icon-only-selected, truncation, and composed focus-ring variants.
+- Added `DialogSurface` and `PopupSurface` composition APIs for standard dialog
+  sizes/presentations, independent body/footer insets, and list-compatible popup
+  menu insets without consumer `::part()` overrides.
+- **Breaking (`@kerfjs/ui`):** removed `PanelHeader` and its subpath/CSS export.
+  Compose page, panel, and dialog headings directly with `Toolbar`, a direct
+  extra-large `ToolbarText`, and optional `ToolbarControlGroup` icon/action zones;
+  keep supporting copy as app-owned content below the toolbar.
+- Fixed controlled TokenSearchField Select All + Backspace/Delete collapsing the
+  editor: managed deletion keeps the adopted open signal and restores replacement
+  focus before another keystroke, without a stale animation-frame caret reset.
+  The adoption demo now persists both edited text and remaining tokens.
+- Fixed `Select` controls using only `ariaLabel` being unnamed to assistive
+  technology. Ordinary and custom selected content retain their geometry while
+  the actual shadow combobox receives its accessible name.
+- Added first-class `Select` hint text below interactive and loading-placeholder
+  controls while keeping empty-value `placeholderText` semantically distinct.
+
+- Changed the Web Awesome Dialog theme to use 8px body padding and 16px footer
+  padding, independently of the component's shared `--spacing` value.
+
+- Fixed `kerf-ui-doctor` so its isolated Kerf ESLint pass preserves applicable
+  consumer core rules and suppression reporting options. Playwright's required
+  `no-empty-pattern` fixture suppression no longer becomes a false unused
+  directive while consumer plugin rules remain outside the doctor boundary.
+
+- Cataloged `SplitView` and its documented
+  `--kui-split-view-list-width` override so `kerf-ui-doctor --full` accepts the
+  public token in downstream application stylesheets.
+
+- Added the first-class `List` vertical-layout component with gap, flex, scroll,
+  and multi-edge divider options; `Toolbar` now uses the same typed
+  `dividerSides` contract instead of a boolean divider.
+
+- Added an optional tone-tinted pill badge beside `StateBanner` titles, including
+  loading skeleton behavior and per-instance badge color overrides.
+
+- Fixed pending `wireTabBars` and `wireTokenSearchFields` controlled-render
+  callbacks moving focus after their owning wiring had been disposed.
+
+- Changed the default `ListItem` leading icon visual from 24px to a root-scaled
+  18px while retaining the row's 44px minimum target and first-line alignment.
+
+- Fixed managed `TokenSearchField` clear losing focus or collapsing when an
+  application replaces its controlled editor; continued typing now works without
+  an application reopen callback.
+
+- Fixed `@kerfjs/ui` automatic TabBar keyboard activation losing focus when a
+  controlled selection replaces the strip; navigation restores the same logical tab.
+
+- Updated the published setup runtime to patched `minimatch` 9.0.9 and `yaml`
+  2.9.1 releases, resolving the known regular-expression denial-of-service and
+  deeply nested YAML denial-of-service advisories without narrowing Kerf's
+  supported Node.js range.
+- Fixed `kerf-ui-doctor --full` so its isolated ESLint stage shares the same
+  generated-directory exclusions as TypeScript, static analysis, and cache
+  hashing; populated `dist`, `coverage`, dependency, cache, evidence, and nested
+  worktree directories no longer produce application diagnostics.
+- Changed `@kerfjs/ui` component-library design templates to compose their
+  individual variant SVGs through HTML and `domotion capture
+--flatten-nested-svg`, eliminating the hand-built nested-SVG compositor and
+  making top-level template sheets reliable in Sketch.
+- Added a typed `shape` option to `SunkenPanel`: `rounded` remains the default,
+  while `square` produces a lowered surface with `border-radius: 0` for flush or
+  edge-to-edge application areas. Both shapes now appear in the UX catalog.
+- Made the Catalog geometry overlay derive both margin bands and border
+  edges/radii from each live specimen's computed CSS. Public example helpers now
+  mark their generated labels and notes for automatic exclusion, and stylesheet,
+  theme, DOM, and resize changes refresh the overlay without duplicated demo
+  measurements.
+- Updated the `@kerfjs/ui` SVG design-template generator to `domotion-svg`
+  0.30.1 and enabled `--flatten-nested-svg`, so inline component icons are
+  emitted as Sketch-compatible groups without changing their browser rendering.
+  The offline template gate now rejects variant captures that reintroduce nested
+  `<svg>` elements.
+- Fixed `kerf-ui-doctor` and `kerf-ui-analyze` recursive discovery so nested
+  `.claude/worktrees` checkouts are excluded from source diagnostics, doctor
+  cache inputs, TypeScript, and ESLint.
+- Added `npx kerfjs setup` and the `kerfjs/setup` automation API for safe,
+  AI-first initialization and migration of core and UI projects. The command
+  provides bounded dry-run diffs, explicit per-conflict keep/Kerf choices,
+  package-scoped hash-backed upgrades, monorepo selection, transactional
+  rollback, shipped guidance, strict TypeScript/ESLint, and UI catalog/profile
+  and doctor discovery. Empty application component metadata now emits a valid
+  empty v2 catalog. Existing JSONC TypeScript configuration is structurally
+  merged without discarding comments, trailing commas, authored fields, or line
+  endings; malformed roots and compiler-option containers require an explicit
+  keep/Kerf decision. Workspace selection now evaluates ordered globstar,
+  brace, exclusion, and re-inclusion patterns deterministically across npm,
+  Yarn, and pnpm declarations, rejects path/symlink/name ambiguity, and uses
+  manager-correct offline commands with explicit Yarn Classic/Berry detection
+  and network-disabled Berry installs.
+- Added `@kerfjs/ui/doctor` and the `kerf-ui-doctor` command: a versioned, redacted repair-loop report that merges catalog/profile validation, TypeScript, Kerf UI ESLint, static analysis, and opt-in browser evaluation with changed/full modes, monorepo selection, reasoned suppressions, caching, and deterministic exits.
+- Added the public Playwright-backed `kerf-ui-evaluate` CLI and `@kerfjs/ui/evaluator` Node API. It resolves application profiles and composition catalogs, exercises wide/intermediate/narrow/200%-zoom, light/dark, and reduced-motion contexts across Chromium, Firefox, and WebKit, and emits versioned repair-oriented `KUI-B###` diagnostics plus focused DOM/style evidence and hashed screenshots. Subjective visual quality remains an explicitly separate unrecorded reviewer rubric.
+- Added `kerf-ui-analyze`, a profile- and catalog-aware static evaluator for Kerf UI integrations. It resolves directory policy per source, follows project-local CSS import graphs without cross-package class leakage, and evaluates shared stylesheets against every consuming source policy before deduplicating findings. Stable portable text, JSON, or SARIF diagnostics cover private selectors, unknown tokens, competing geometry/scroll owners, repeated insets, forced dimensions, off-scale spacing, and dynamic-class review, with exact scoped profile exceptions, a public report schema, and configurable CI review failure.
+- Added catalog/profile-aware `recommended-ui` and `strict-ui` flat presets to `eslint-plugin-kerfjs`. Toolbar zone acceptance/cardinality and valid wiring imports come from the shipped catalogs; intrinsic or unknown zone children, root/subpath/namespace wiring, and the non-colliding `KUI-L090` load diagnostic are covered by real packed downstream installs on every supported ESLint major.
+- **Breaking (`@kerfjs/ui` TypeScript declarations):** strengthened invalid-integration contracts for ListHeader modes, Select naming and literal choice identity, SegmentedControl/TabScaffold literal identity, collapsible TokenSearchField props, protected editor metadata, PanelHeader summary ids, ToolbarText line caps, and token-removal callbacks. Added named public unions for previously anonymous finite variants plus source and packed-tarball positive/negative compilation gates. See `ui/docs/type-contracts.md` for the compatibility review and dynamic-data widening syntax.
+- `create-kerf-component` now scaffolds explicit `kerf.components.json` AI metadata and a deterministic `kerf-component-catalog` generator/checker. Generated v2 entries carry package identity, purpose, verified named exports, composition and geometry ownership, tokens, accessibility, and source links; publishing rejects missing author decisions, schema-invalid source/output fields, deleted sources, renamed exports, duplicate ids, or output drift, including multi-package workspaces. Syntax-aware TypeScript/TSX export discovery prevents JSX text, nested scopes, comments, and literals from impersonating public exports.
+- Added a versioned application UI profile for AI tools and static evaluators. Shipped package defaults, schema, TypeScript types, Node discovery/merge/validation APIs, and a workspace example now make catalog locations, preferred components/recipes, theme/density policy, semantic token overrides, responsive/layout conventions, and narrow source-located exceptions explicit. Composition-only generated consumer catalogs load without a fabricated v1 selection artifact, while Kerf retains its required v1 selection catalog. Deterministic package → workspace → parent-to-child directory precedence validates every raw layer before merge, attributes resolved diagnostics through field provenance, and rejects stale catalogs, unknown components/tokens/rules, conflicts, malformed value shapes, and broad exemptions.
+- Fixed `CatalogExampleStack` accessible labels: the helper now renders a semantic `section`, so a supplied `label` exposes the documented named region to assistive technology while an unlabeled stack remains an ordinary grouping.
+- Added first-class `Pane` and `SunkenPanel` primitives to `@kerfjs/ui`. `Pane` standardizes semantic header/content/footer columns, explicit logical-edge separators, and one content scroll owner; `SunkenPanel` supplies one lowered surface with an 8px inset and vertical rhythm. The Catalog shell now dogfoods `Pane`, and both components ship focused demos, catalog metadata, documentation, and three-engine browser coverage.
+- Added the package-qualified component catalog v2 alongside the compatible v1 artifact. Its schema and generated metadata formalize child zones, cardinality, exclusivity, wiring, state, responsive behavior, layout and accessibility boundaries, stable validation diagnostics, provenance, and consumer extension catalogs, so AI tools can join Kerf and application components without guessing composition contracts.
+- Added an AST-based Catalog demo conformance gate. It checks every first-party demo for public helper usage, package imports, focused specimen structure, geometry-overlay metadata, and reviewed schema-checked exceptions, with adversarial fixtures and authoring guidance that makes the same contract available to downstream AI tools.
+- Made `ui/docs/catalog.md` the authoritative Catalog demo authoring contract, covering focused versus composition previews, public row/group nesting, exact specimen selection, conditional geometry overlays, skip-marker behavior, metadata ownership, and an explicit overlay legend. A shipped `ai/catalog-authoring.json` discovery artifact now routes AI tools to that contract and exact signatures, with schema, link-integrity, and browser-consumer fixture coverage.
+- Extended `CatalogExample` and `CatalogExampleStack` with typed, runtime-filtered `rootAttributes` for catalog-authoring `data-*` metadata such as `data-demo` and `data-catalog-geometry-overlay-skip`, while preserving helper-owned structural and alignment markers. The UX catalog now composes its example stacks through these public helpers instead of copying private `kui-catalog-*` markup.
+- Added `revealCatalogEntry` and opt-in `wireCatalog({ revealSelection })` support to the exported Catalog tool. Sidebar or related-entry selection can now reveal the matching row after the controlled render settles, using a desktop-safe media guard, exact id matching, configurable scroll alignment/behavior, focus-preserving scrolling, and cancellation of stale rapid selections; the Kerf UX demo now uses the public behavior.
+- Added a reusable consumer component-catalog extension schema and checked app-component example. Downstream packages can now publish the same selection facts and margin/border/padding ownership vocabulary as Kerf, and the README, component contract, Catalog guide, `llms.txt`, and AI skill explain how to combine package-qualified app entries with Kerf's shipped catalog for alignment decisions.
+- Added an opt-in geometry inspector to the exported `@kerfjs/ui/catalog` tool. `geometryOverlay` plus `wireCatalogGeometryOverlay` now marks transparent component bounds with a dashed outline and positive intrinsic margins with devtools-style bands, excludes example labels/alignment scaffolding, stays synchronized across preview changes, and replaces the Kerf UX demo's private implementation.
+- Added machine-readable margin, border, and padding ownership to every visual entry in the `@kerfjs/ui` component catalog. The additive schema distinguishes self-, parent-, child-, conditional-, and unowned geometry, and enforces complete metadata plus explanatory notes for conditional cases.
+- Refreshed the standalone reactivity demo lockfile to Vite 6.4.3, PostCSS 8.5.28, and nanoid 3.3.19, clearing its development-toolchain audit advisories.
+- Overrode the development toolchain's transitive esbuild dependency to 0.28.2, resolving GHSA-g7r4-m6w7-qqqr while current tsup still constrains its declared range to 0.27.x.
+- Added repository-wide Prettier formatting for TypeScript, JavaScript, Astro, shell, CSS, HTML, Markdown, YAML, and JSON source and structured-content files. Root and `@kerfjs/ui` lint gates now reject formatting drift, while generated, binary, and parser-incompatible fixtures remain explicitly excluded.
+- Added reusable sidebar tags to `@kerfjs/ui` Catalog entries and marked the 15 Web Awesome components superseded by preferred Kerf patterns or reserved for exceptional cases as `Discouraged` in the UX catalog. The tag is deterministically projected from the canonical recommendation metadata; Popup remains an available conditional positioning primitive.
+- Aligned Web Awesome Accordion, Card, Details, Callout, and Include surfaces with Kerf content-item geometry: each complete surface now has an overridable 8px logical inline margin and 8px inner padding, Accordion keeps connected items under one group margin, and Card's header/body/footer share the full inset. Tab Panel intentionally retains the roomier 16px container inset.
+- Fixed `@kerfjs/ui` Web Awesome Slider geometry: its complete interactive region now receives the shared 8px logical inline outer inset without shifting the already-aligned label.
+- Styled `@kerfjs/ui` Web Awesome OTP Input like a bordered text field: its label now uses the shared uppercase xs/650 field-label treatment, and both label and hint align at the 9px border-plus-padding inset.
+- Aligned `@kerfjs/ui` Web Awesome Known Date's Month/Day/Year captions and bordered text-like field hints with their values using the shared 9px border-plus-padding inline inset.
+- Fixed `@kerfjs/ui` Web Awesome Color Picker geometry: its unbordered trigger now receives the shared 8px inline outer inset, aligning it with Kerf content-item spacing.
+- Fixed `@kerfjs/ui` Web Awesome Checkbox Group and Radio Group option geometry: each group's unbordered option region now receives the shared 8px inline outer inset, aligning it with Kerf content-item spacing without padding the individual controls.
+- Aligned the remaining bordered/padded Web Awesome chrome in `@kerfjs/ui/webawesome.css` to explicit Kerf spacing tiers: `--kui-wa-control-inset` (8px) drives tabs, inset tree selection, tags, and dropdown items; `--kui-wa-surface-margin` / `--kui-wa-surface-inset` drive bordered surface geometry; and `--kui-wa-container-inset` (16px) retains roomier Tab Panel content. Buttons already inherit the 8px form-control inset; compact badges, unframed Breadcrumb, and slotted Scroller item chrome deliberately retain their native geometry. The tiers are overridable by scope and pinned by three-engine computed-style coverage plus light/dark wide and narrow visual QA.
+- Tightened the `@kerfjs/ui` Web Awesome theme's form fields to the Kerf content-item inset — a 1px border with 8px inside it (`--wa-form-control-border-width` / `--wa-form-control-padding-block` / `--wa-form-control-padding-inline` now follow `--kui-layout-item-border-width` / `--kui-layout-item-padding`), replacing Web Awesome's larger default pad, so fields land at the standard ~40px height and 9px value inset. Each field's top label is now inset by that same border + padding (9px) so it aligns with the value inside the field, and is styled exactly like a `ListHeader` label — uppercase, xs, weight 650, quiet foreground (`::part(form-control-label)` across Input/Number Input/Textarea/Select/Checkbox Group/Radio Group/Color Picker/Known Date/Time Input, plus the Slider's `::part(label)`). Inline Checkbox/Switch labels keep their sentence case.
+- Added overflow controls to `@kerfjs/ui`'s `ToolbarText`: `wrap` (flow onto multiple lines instead of a single line), `ellipsis` (show the trailing … at the truncation, or hard-clip when false), and `maxLines` (cap wrapped text to N lines, ellipsizing past it). The default is unchanged — one line, ellipsized when it does not fit. `maxLines` takes effect only with `wrap`. Driven by `data-wrap` / `data-ellipsis` / `data-max-lines` attributes plus a `--kui-toolbar-text-max-lines` var; no new public classes. The UX catalog gains ellipsis/wrap/capped examples.
+- Fixed a `@kerfjs/ui` `TokenSearchField` bug where selecting all content and pressing Delete (or Backspace) left a stray newline in the field. A `contenteditable` host inserts a bogus `<br>` when emptied that way in every engine — it renders as a newline and `readTokenSearchField` read it back as a space. `wireTokenSearchFields` now strips that line break after any delete input and, when the field is otherwise empty, restores the canonical empty text span and places the caret in it so typing resumes cleanly. Also clears any leftover chips in the select-all case. Regression-tested in unit (happy-dom) and across all three browser engines.
+- Hardened that full `TokenSearchField` deletion for platform-specific selection
+  ranges whose endpoints sit inside the first and last text spans instead of at
+  the editor boundary—or whose cloned Linux range omits an atomic chip entirely.
+  Full logical text-and-token selection is recognized from its value, while an
+  explicit Ctrl/Cmd+A intent survives only until the next delete and is
+  consumed by that delete even when the browser omits `beforeinput`, and is
+  retained across a controlled editor replacement before or after
+  `beforeinput`. It is captured before propagation can be stopped and
+  invalidated by selection-moving keys, pointer input, blur, or another edit.
+  The explicit shortcut-to-delete transition is handled deterministically:
+  the helper prevents the unreliable mixed-contenteditable native mutation,
+  canonicalizes the empty editor, and emits the corresponding bubbling input
+  event so controlled application state clears before it can restore a chip.
+  A browser can no longer preserve a controlled chip merely because its range
+  shape or native deletion timing differs.
+- Added a `horizontalOnly` prop to `@kerfjs/ui`'s `ListInsetText`. When true it keeps the horizontal geometry (8px inline margin, 1px left/right border, 8px left/right padding — so the text edge still lands at the 17px inset) but drops the vertical margin, border, and padding, for tight text layout that still aligns with bordered items. It applies a `kui-list-inset-text--horizontal` modifier class; the default (vertical box space intact) is unchanged. The UX catalog gains a horizontal-only example.
+- Fixed a WCAG AA color-contrast failure on `@kerfjs/ui`'s selected list rows. The selected `ListItem` and `ListActionRow` used the brand accent (`brand-on-quiet`, `#1e6ef4`) for their text, which resolved to only **3.77:1** over the selected `brand-fill-normal` background (`#d6ecff`) — below the 4.5:1 minimum for normal text (flagged by axe downstream). Both now use the normal neutral foreground over the brand-tinted fill, so selection is carried by the fill and border while the text stays readable in light and dark themes. Computed-ratio browser tests pin both selected rows at ≥4.5:1 in both themes across all three engines.
+- Fixed the same brand-accent contrast failure on `@kerfjs/ui`'s info `StateBanner` tone and `Select`'s current option, where the blue is a semantic (not a selection cue), so the text stays blue rather than going neutral: a new darker `--kui-color-brand-on-fill` token (`#1a5dcf` light; the compliant `#8acbff` in dark) replaces `brand-on-quiet` for brand text placed directly on a brand fill. The info banner (was 4.15:1) now clears ~5.4:1 and the current Select option (was 3.77:1) ~4.9:1. Computed-ratio browser assertions guard both.
+- Completed the `@kerfjs/ui` `StateBanner` contrast pass: the `success` (was 4.05:1) and `warning` (was 4.39:1) tones failed WCAG AA the same way via their own `*-on-quiet` tokens over the tinted banner fills. New darker `--kui-color-success-on-fill` (`#00792c`) and `--kui-color-warning-on-fill` (`#8f5e00`) tokens (each keeping its semantic hue, dark values unchanged and already compliant) now back the success/warning banner text, clearing ~5.0:1 and ~5.3:1. Every `StateBanner` tone now clears 4.5:1 in both themes, guarded by an all-tone computed-ratio browser assertion.
+- Added two structure primitives to `@kerfjs/ui` for aligning bare content inside a `.kui-content` list: `ListInsetControl` (`@kerfjs/ui/list-inset-control` + `.css`) wraps a control that owns its own border and padding but no outer margin (a search input, a `SegmentedControl`) with the standard 8px inline margin plus a stretch flex row and an 8px gap, so it lines up with the bordered items around it without double-insetting; `ListInsetText` (`@kerfjs/ui/list-inset-text` + `.css`) gives a bare string or inline content the content-item geometry (8px inline margin, 1px transparent border, 8px padding) so its text edge lands at the same 17px inset as bordered rows. Both are additive, take an optional `className`, and appear in the UX catalog and the component-selection guidance.
+- `@kerfjs/ui`'s `wireTokenSearchFields` `onEdit` callback now also receives the originating `InputEvent` (`onEdit({ id, editor, event })`), so a consumer can gate token-commit behavior on `event.inputType` / `event.data` (e.g. commit a chip only on whitespace-terminated input) and drop its own `input` listener entirely — completing the goal `onEdit` was added for. Additive; existing `{ id, editor }` destructuring is unaffected.
+- Added a CI-only visual-drift gate for the `@kerfjs/ui` SVG design templates (`check:design-templates:drift`): it re-renders every template in a browser and fails if any regenerated SVG differs from the committed one (normalizing run-to-run noise — XML comments and auto-minted ids/font names). It closes the gap the offline `check:design-templates` cannot cover and runs in CI's browser-capable job, not the offline pre-commit `check`.
+- Added `FloatingToolbar` to `@kerfjs/ui` (`@kerfjs/ui/floating-toolbar` + `.css`): a transparent, forced-dark toolbar that floats over the content of its nearest positioned ancestor — a drawer-restore / floating-controls pattern — without covering dialogs or overlays (it is not top-layer). It exposes `role="toolbar"` with a required `label`, floats to a customizable `position` (`bottom-end` default, plus the other corners/edges), and is inset by `--kui-floating-toolbar-inset` (default 8px past a top toolbar's own inset). The app owns the controls and their visibility. Includes a UX-catalog demo with a show/hide toggle that auto-hides on leaving the demo.
+- Added a `shape` prop to `@kerfjs/ui`'s `ToolbarControlGroup`: `'pill'` (default, unchanged) or `'rounded'` for a softer rounded-rectangle corner on the group and its items (using the design system's rounded radius). The UX catalog's ToolbarControlGroup section gains a Pill/Rounded toggle that switches every example.
+- Added a **Design template** link to the UX catalog's detail-footer resources (beside demo source / component source / guidance) for every component that has a committed SVG design template, pointing at its per-component library under `docs/design/templates/`. The link is generated from the design-template manifest during `catalog:sync`, so it appears only where a template exists and stays in step as the template set grows.
+- Gave the `@kerfjs/ui` `Catalog` detail footer's related-entries popup trigger a visible **"Component"** text label beside its glyph (it was icon-only), so the affordance reads as a labeled control rather than a bare icon. The trigger grows to fit the label instead of the single-group's fixed icon-button width, and the glyph stays beside the label.
+- Fixed the `@kerfjs/ui` `Catalog` component's `secondarySections` ("ecosystem" group) indentation: the subsection heading sat further left than everything else while its list items sat further right, so the group read as awkwardly stair-stepped. The subsection heading now takes the same 8px content inset the list items and the group's `ListHeader` self-apply, so the group heading, its subsection headings, and their items all share one left edge — matching the primary sidebar.
+- Extended the `@kerfjs/ui` SVG **design templates** (`ui/docs/design/templates/`) from the initial two components to fourteen — adding `Toolbar`, `ToolbarText`, `ListItem`, `ListHeader`, `ListActionRow`, `ValueTable`, `StateBanner`, `EmptyState`, `Skeleton`, `SegmentedControl`, `TabBar`/`AppTab`, and `TokenSearchField`, each captured (light + dark, system-font text, self-contained inlined libraries) in its common presentation combinations with realistic sample data. Added an offline sync-check gate (`check:design-templates`, part of `npm run check`) that verifies every manifest component/variant has its committed output and flags stray files. `Select` (Web Awesome runtime), the decorative icon primitives, `ResizableRegion`, the whole-screen layouts, and the `Catalog` shell are deliberately not templated (see `ui/docs/design/templates.md`).
+- Extended `@kerfjs/ui`'s `wireTokenSearchFields` with three opt-in knobs for dropping a real app's hand-rolled token-search plumbing: a **focusout keep-open exception** (`collapsible.keepOpenOn(target)` or a `data-token-search-keep-open` region) so focus moving to a sibling suggestions/date/help surface no longer collapses an empty collapsible field; **opt-in atomic-chip keyboard** (`keyboard`) where, from a collapsed caret with no selection, Backspace/Delete remove the adjacent chip (reported via `onRemoveToken` for the app to apply to its controlled state) and ArrowRight moves the caret past a trailing chip; and an **`onEdit({ id, editor })`** callback fired on every editor `input` so callers can drop their own `input` listener. All are additive and off/unchanged by default (the keyboard block is opt-in; the full `collapsible: false` opt-out and per-behavior opt-outs are unchanged).
+- Fixed a collapsible `@kerfjs/ui` `TokenSearchField` stretching to its full expanded width **in height** when placed directly in a flex column: the expanded size was carried on the flex `basis`, which a column reads as the cross-axis height (a ~480px-tall field). The field and its enclosing toolbar group now size their inline axis through `width` alone (`flex: 0 1 auto`), so the field stays a single line tall in any container while a toolbar row still shrinks it as before.
+- Added SVG **design templates** for `@kerfjs/ui` components (`ui/docs/design/templates/`): each component captured from its real rendered HTML/CSS in its common presentation combinations via `domotion-svg`, with a per-component library file that references the individual variant SVGs. A `design-templates:build` script + `ui/docs/design/templates.md` cover regeneration, maintenance, and templating your own app-level components. Initial coverage: PanelHeader and ToolbarControlGroup.
+- Fixed two `@kerfjs/ui/catalog` presentation bugs: header-action buttons that carry a text label (the built-in theme toggle) now render icon-beside-label instead of the toolbar group's icon-over-label grid, and the detail footer's related-entry selector is a single-bordered popup (a borderless `single` group around a label-less `fitMenu` select) rather than a bordered select nested inside a bordered group.
+- Dogfooded the UX demo's own shell onto `@kerfjs/ui/catalog` (`Catalog` + `wireCatalog`), which surfaced and fixed three `Catalog` bugs: an active entry inside a `secondarySections` group is now found for the detail header/footer; the brand subtitle's alignment override outranks the toolbar group's default gap (it lost specificity before, dropping the logo→title gap); and the detail footer's resource links stack above the related selector at narrow widths.
+- Extended `@kerfjs/ui/catalog`: `Catalog` gained a `secondarySections` prop — an optional, quieter "ecosystem" group of sections below the primary sidebar categories, with an optional disclosure toggle (`wireCatalog` gains `onToggleSecondary`) — and the subpath now also exports `CatalogExample` / `CatalogExampleStack`, labeled-example primitives that carry a first-class `align` prop (`'glyph'` = 16px, `'inline-control'` = 8px, `'none'`) to line a specimen's left edge up with its label, publishing the inset as `--kui-catalog-example-align` so a debug overlay can exclude it. This lets a gallery compose its previews from the shipped shell instead of hand-rolled example markup and CSS.
+- Reworked the `@kerfjs/ui` list-detail dialog recipe so its `PanelHeader` sits at the top of the detail column rather than spanning both columns; the master list and detail pane now each run full height top-to-bottom within the dialog.
+- **Breaking (`@kerfjs/ui`):** renamed the three menu primitives to their list names — `MenuHeader` → `ListHeader`, `MenuItem` → `ListItem`, `MenuActionRow` → `ListActionRow` — across every surface: the exported components, their subpaths (`@kerfjs/ui/list-header`, `/list-item`, `/list-action-row` and the matching `.css` subpaths), their `kui-menu-*` CSS classes (now `kui-list-*`), their `data-component` values, and the catalog. The sidebar navigation composition demo is likewise renamed from `menu` to `list`. There are no deprecated aliases; update imports, class references, and any `?component=menu` links. The names better reflect that these primitives compose any list or navigation surface, not only menus.
+- Added a reusable component-catalog shell to `@kerfjs/ui`: an opt-in, subpath-only `Catalog` component (`@kerfjs/ui/catalog`) plus a `wireCatalog` helper (`@kerfjs/ui/wire-catalog`) that render the collapsible category sidebar + titled preview stage + resources/related footer the kerf UI catalog uses, driven by your own `sections`, per-entry preview `content`, and `brand`. Controlled and stateless like the app layouts (the app owns `active`/`collapsed`/`theme`); `wireCatalog` wires selection, the related-entry selector, and the collapse/theme toggles, and can mirror the active id into the URL. See `ui/docs/catalog.md`.
+- Gave `@kerfjs/ui`'s `PanelHeader` (and `ToolbarText`) an optional `headingLevel` prop: when set, the title exposes `role="heading"` with a matching `aria-level`, so a page or view heading is a real heading landmark for screen-reader navigation. The default is unchanged — a plain span referenced via `aria-labelledby` for dialog titles — so existing usage is backward-compatible. Restores the page-heading semantics lost when `PageHeader` was consolidated into `PanelHeader`.
+- Added a first-class loading-placeholder mode to `@kerfjs/ui`: a new unanimated `Skeleton` block (`@kerfjs/ui/skeleton`) plus a `placeholder` boolean on every value-bearing component (`Select`, `ListHeader`, `ListItem`, `ListActionRow`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`). In placeholder mode a component renders its real chrome with value slots as subtle skeleton blocks and its own controls disabled (`aria-busy`, dropped `data-action`), keeping sizes and shapes identical to the populated component, so a parent composes a faithful loading inspector/detail view without hand-rebuilding markup. Built on a Kerf-owned skeleton (not `wa-skeleton`) so the pure-Kerf primitives stay Web-Awesome-free. `Select`'s existing empty-hint string prop is renamed `placeholderText` to free `placeholder` for the loading boolean.
 - Made `@kerfjs/ui`'s `wireTokenSearchFields` manage the collapsible `TokenSearchField`'s transient expand/collapse/focus by default (activate to reveal and focus, Escape or empty blur to collapse), holding that state in a signal exposed on the returned handle so an app can bind it in render, adopt its own via `collapsible.signals`, drive it through `open`/`close`, or opt any behavior out individually — removing the per-app boilerplate that had caused inconsistent transient-UI variation. `onSubmit` is now optional and the helper returns a `TokenSearchFieldsHandle` (a disposer that also exposes `expanded(id)`/`open`/`close`).
 - Made the UX catalog's theme action follow the operating system's initial light/dark appearance, label itself with the appearance it will switch to, and explicitly override either direction when activated.
 - Corrected the UX catalog's project-details dialog gutters so its header uses less side inset, its selected title uses the full content gutter, its value table fills the available detail width between the usual margins, and its record actions avoid a doubled left inset.
@@ -18,7 +2468,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Aligned the UX catalog's StateBanner tone labels with each banner's leading icon by deriving the shared 8px margin, 1px border, and 8px content inset in demo-only specimen chrome.
 - Let the UX catalog's resizable-panel specimen fill its available preview height and moved its committed-width readout into the shared status footer.
 - Reworked the UI catalog into collapsible pane chrome with toolbar headers, a full-stage checkerboard preview, compact resource footer, hidden-by-default floating recipe notes, and edge-aligned `PageHeader` actions.
-- Aligned multiline `MenuItem` and `MenuActionRow` leading icons with the first text line instead of centering them against the full wrapped label.
+- Aligned multiline `ListItem` and `ListActionRow` leading icons with the first text line instead of centering them against the full wrapped label.
 - Fixed packages generated by `create-kerf-component` failing declaration builds under TypeScript 6 when tsup injects its deprecated `baseUrl` option.
 - Fixed the complete kanban example's mobile layout by stacking its columns and header controls without horizontal overflow while preserving the wider board layout.
 - Fixed the complete dashboard example's mobile layout so its status header, chart, and table fit the viewport without horizontal overflow.
@@ -66,28 +2516,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Removed the unsolicited command-palette catalog demo and production recipe while retaining the earlier, independent application-local adapter example for missing-concept guidance.
 - Kept the `ResizableRegion` UX specimen readable by moving committed-width status below the controlled pane at narrow widths, preserving its 200% root-scaled split, and retaining local scroll access to the handle at its maximum size.
 - Reworked the composer-form recipe into one coherent visible form surface with exactly three transparent 8/1/8 content sections, 24px major rhythm, and a conditional `StateBanner` as its only nested semantic surface.
-- Made `MenuHeader` fill its available inline width, align separate actions at the logical end in both LTR and RTL, and use an overridable 18px visible action glyph without shrinking the 44px target.
-- Added first-class `MenuHeader` count semantics with a required localized `countLabel`, zero-safe neutral pill presentation, accessible heading/disclosure naming, legacy non-count badge exclusivity, and runtime filtering for invalid counts and protected presence flags.
-- Made `MenuHeader` toggle mode supply the production 18px `DisclosureArrow` by default while retaining custom `actionIcon` replacement, removed competing raw SVG sizing/rotation, and made the menu-composition Tools disclosure control real content instead of showing a false Projects chevron.
+- Made `ListHeader` fill its available inline width, align separate actions at the logical end in both LTR and RTL, and use an overridable 18px visible action glyph without shrinking the 44px target.
+- Added first-class `ListHeader` count semantics with a required localized `countLabel`, zero-safe neutral pill presentation, accessible heading/disclosure naming, legacy non-count badge exclusivity, and runtime filtering for invalid counts and protected presence flags.
+- Made `ListHeader` toggle mode supply the production 18px `DisclosureArrow` by default while retaining custom `actionIcon` replacement, removed competing raw SVG sizing/rotation, and made the menu-composition Tools disclosure control real content instead of showing a false Projects chevron.
 - Repaired the `DisclosureArrow` UX specimen by replacing its ambiguous sorting glyph with a right-facing arrow, putting both examples in independently controlled native buttons with stable names and `aria-expanded`, and demonstrating custom directions through delegated pointer and keyboard activation across narrow and 200%-zoom layouts.
 - Set `DisclosureArrow` to an 18px root-scaled default, removed the catalog-only 24px enlargement, retained `--kui-disclosure-arrow-size` for scoped consumer overrides, and kept Kerf `Select` on its independent `.5` Web Awesome expand-glyph scale.
 - Added a site-scoped CI dependency audit that includes the complete static-site build tree and fails on high or critical advisories while keeping low/moderate development-tool findings informational.
 - Aligned the UX catalog's header-composition dialog with the shared 8px inline layout gutter while preserving its 16px vertical separation.
 - Added visible `View demo source` and `Read guidance` affordances to every UI catalog detail, plus `View component source` for first-party components, backed by deterministic repository-relative paths for the main renderer, individual recipe files, Web Awesome specimens, and canonical browser-import implementations. Web Awesome entries explicitly label local documentation as Kerf integration guidance; all links use deploy-safe GitHub URLs and a responsive accessible layout.
 - Added runtime-safe `AppTab.rootAttributes` for domain `data-*` metadata plus decorative `AppTab.closeIcon` and `ResizableRegion.handleIcon` slots, preserving existing tab and resize wiring ownership while blocking case-folded component/action/drag/drop collisions.
-- Added `MenuActionRow`, a full-width navigation row with sibling primary and trailing native-button actions, independent names and disabled states, controlled selection semantics, safe metadata/popover extension slots, and responsive 44px targets. `MenuItem.trailing` is now explicitly documented as dormant content.
-- Added safe typed MenuItem/MenuHeader extension slots for application `data-*` metadata and native popover trigger relationships while protecting component-owned action, selection, disclosure, accessible-name, disabled, icon, and native-button semantics.
+- Added `ListActionRow`, a full-width navigation row with sibling primary and trailing native-button actions, independent names and disabled states, controlled selection semantics, safe metadata/popover extension slots, and responsive 44px targets. `ListItem.trailing` is now explicitly documented as dormant content.
+- Added safe typed ListItem/ListHeader extension slots for application `data-*` metadata and native popover trigger relationships while protecting component-owned action, selection, disclosure, accessible-name, disabled, icon, and native-button semantics.
 - Fixed keyboard deletion of a controlled `TokenSearchField` chip so `wireTokenSearchFields` restores focus and the text-relative caret after the application rerenders the editor.
 - Aligned `@kerfjs/ui` CSS guidance and AI regression scoring with the catalog's exact public anatomy: documented public-class composition selectors are supported, private tag/id/attribute/unlisted-class descendants remain rejected, and historical measured runs replay under their recorded stricter oracle.
 - Added typed `ValueTableRow` composition with a first-class optional icon hook. Value-table separators now align 8px from both edges for iconless rows and 40px from the left plus 8px from the right for rows with a 24px leading icon.
 - Added first-class collapsible `TokenSearchField` support: an empty closed field becomes one iconic search action, controlled activation animates to the complete searchbox, and text or tokens keep it expanded after blur. It works standalone or when composed inside `ToolbarControlGroup`; the UX demo demonstrates that common toolbar composition at wide and narrow sizes.
 - Restored the public documentation site to its Astro + Starlight implementation while the Kerf UI redesign is reconsidered, and removed the in-progress `@kerfjs/ui` page and promotional links from public navigation.
 - Fixed `TokenSearchField` first-line alignment so the leading icon, editable text, clear action, and trailing content share the field's vertical center while remaining pinned when text wraps.
-- Replaced sidebar-specific and wrapper-inset UI geometry with one shared pane/content model across sidebars, main areas, inspectors, and dialogs. Unpadded panes now compose optional toolbars, one scrolling content stack, and optional footers; content children own consistent 8px margin, 1px transparent-or-visible border, 8px padding, 12px or 22px radii, and 24px major separation. Toolbar groups retain 44px geometry even with transparent chrome, and `MenuHeader` now supports a badge while separating dormant title content from its action.
+- Replaced sidebar-specific and wrapper-inset UI geometry with one shared pane/content model across sidebars, main areas, inspectors, and dialogs. Unpadded panes now compose optional toolbars, one scrolling content stack, and optional footers; content children own consistent 8px margin, 1px transparent-or-visible border, 8px padding, 12px or 22px radii, and 24px major separation. Toolbar groups retain 44px geometry even with transparent chrome, and `ListHeader` now supports a badge while separating dormant title content from its action.
 - Added pixel-first `remify(<px>)` authoring for `@kerfjs/ui` styles. The build converts values exactly against a 16px baseline into ordinary `rem`, package CSS exports now deliver compiled `dist/styles/` files, and the UX catalog applies the same transform during Vite development so CSS edits remain hot-reloaded.
 - Added a side-effect-free `@kerfjs/ui/webawesome` TypeScript declaration subpath for all 70 catalog-supported Web Awesome elements, synchronized against the installed custom-elements manifest and covered by a downstream package-export compile fixture.
 - Added a deterministic internal `@kerfjs/ui` AI-regression foundation with seven task-shaped prompts, frozen versioned context conditions, AST-aware structural scoring, generated public declaration signatures, equivalent supported import scoring in suite v2, and an opt-in non-executing TypeScript compile-evidence sidecar with exact response/config/package/declaration hashes. Adversarial fixtures catch component substitution, duplicated primitives, and spacing/layout ownership regressions without invoking a live model in CI.
-- Added seven lazy, production-backed `@kerfjs/ui` composition recipes for application shells, sidebars, workspace headers, master-detail dialogs, composer forms, list-state lifecycles, and mixed-control toolbars, with stable catalog routes, canonical AI metadata, drift gates, responsive/keyboard/state coverage, and a copyable stable-root adapter that wires delegated actions, form/dialog events, resize commits, and idempotent disposal outside the catalog.
+- Added seven lazy, production-backed `@kerfjs/ui` composition recipes for application shells, sidebars, workspace headers, list-detail dialogs, composer forms, list-state lifecycles, and mixed-control toolbars, with stable catalog routes, canonical AI metadata, drift gates, responsive/keyboard/state coverage, and a copyable stable-root adapter that wires delegated actions, form/dialog events, resize commits, and idempotent disposal outside the catalog.
 - Added a shipped, schema-described `@kerfjs/ui` machine-readable component catalog with deterministic typed UX projection and drift gates for public exports, package/CSS/registration paths, relationships, Web Awesome manifest coverage, AI guidance, routes, CSS hooks, and documentation links.
 - Added a canonical `@kerfjs/ui/layout.css` vocabulary for responsive page, pane, section, control, metadata, surface, dialog, and scroll ownership, with semantic variables, compact/narrow behavior, consumer and AI guidance, normalized catalog compositions, and wide/intermediate/narrow/200%-zoom geometry coverage.
 - Added a need-first `@kerfjs/ui` component-selection matrix and automated drift gate so AI tools choose among reuse, composition, thin application adapters, custom semantics, and overlapping Web Awesome components without inferring contracts from implementation CSS. A typed application-local command-palette example now shows how a missing package concept still uses canonical layout, one inset owner, and related-control grouping while keeping semantics honest and proposing recurring behavior upstream.
@@ -110,7 +2560,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Made the Web Awesome intersection, mutation, and resize observer UX specimens interactive, with deliberate triggers, visible live-event results, and browser coverage.
 - Updated the UI package's Vitest toolchain to 4.1.11 and resolved the remaining development-only npm audit advisories without changing its runtime dependency surface.
 - Added a first-class controlled `SegmentedControl` to `@kerfjs/ui`, with Hot Sheet 2-aligned toolbar, rounded-rectangle, pill, equal-width, small, and disabled presentations; native pressed-button semantics; scoped palette overrides; tree-shakeable component CSS; and a complete UX-catalog route.
-- Aligned `@kerfjs/ui` defaults with Hot Sheet 2, added overridable semantic state palettes, completed ToolbarControlGroup and StateBanner catalog variants, simplified related-component navigation, corrected MenuHeader action alignment, and added a controlled horizontally scrolling TabBar with pointer and keyboard reordering plus proximity-based edge autoscroll.
+- Aligned `@kerfjs/ui` defaults with Hot Sheet 2, added overridable semantic state palettes, completed ToolbarControlGroup and StateBanner catalog variants, simplified related-component navigation, corrected ListHeader action alignment, and added a controlled horizontally scrolling TabBar with pointer and keyboard reordering plus proximity-based edge autoscroll.
 - Updated `@kerfjs/ui` to develop and test against Lucide 1.43.0 and Web Awesome 3.12.0, with matching peer baselines.
 - Added an opt-in `@kerfjs/ui/webawesome.css` theme for Web Awesome's free components. It carries the Hot Sheet 2-aligned semantic palette, form and panel geometry, focus, tooltip, radius, and shadow choices without registering component JavaScript; the UX catalog now lists all 70 free Web Awesome 3.12 components under a collapsible ecosystem section, gives each a focused themed route and dependency links, and retains the aggregate light, dark, narrow, and scoped-override gallery.
 - Fixed trapped overlays losing sequential focus in WebKit after the second control. Implicitly focusable descendants now receive `tabindex="0"` inside the trap, while authored tabindex values (including `-1`) remain intact.
@@ -119,9 +2569,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Added the lockstep `@kerfjs/ui` package: accessible toolbar, menu, tab, header, resize, select, and feedback primitives; semantic CSS tokens and browser component subpaths that automatically include only reachable component styles; CSS-free root/SSR entries and an optional complete stylesheet; opt-in Web Awesome registration; AI-oriented docs; a production-backed UX catalog; bundle/unit/three-engine browser gates; and a least-privilege release workflow.
 - The virtual-list demo animation opens on the full app again (header, the "N in the DOM" badge, and the list) before the scroll; the list now scrolls inside its own box while the header stays put (previously the whole frame was a full-bleed list strip), holds at row 0 before gliding instead of starting a few rows down, and the loop stays in phase on every pass. Captured with domotion-svg 0.28.2.
 
-## [4.4.1] - 2026-08-26
-
+- @kerfjs/ui panel toolbars now place groups in leading, center, and trailing zones; relocateOnCollapse keeps chosen groups available when a panel closes.
 
+## [4.4.1] - 2026-08-26
 
 - Overhauled the README landing page: new one-line tagline, npm/size/license/TypeScript-types badges, a hoisted "Quick start" (install + `tsconfig`) right under the hook, and a jump nav (Quick start · Why kerf · Quick tour · Docs). The counter example now shows `delegate()` wiring the click handler.
 - Reworked the homepage hero to lead with the value proposition ("Reactive UI that touches only the bytes that changed"), with "Introducing Kerf" demoted to an eyebrow, a right-sized logo, tighter vertical spacing, and "Get started" as the single filled primary action ("View examples" now a secondary/outline button).
@@ -130,7 +2580,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Rewrote the site's docs pages as hand-authored consumer content (cleaner headings, no internal section numbers) rather than verbatim copies of the internal design docs.
 - Renamed the migration guides' "Side-by-side code" heading to "Section by section" (the sections stack code blocks rather than showing true columns), across all framework pages.
 
-
 - The getting-started and Markdown-editor demo animations now open on a non-blank frame — real code and a rendered heading are visible immediately instead of an empty pane.
 - Added a horizontal-scroll shadow affordance to wide tables so off-screen columns are discoverable on narrow viewports.
 - Shortened the longest demo alt text on the router and virtual-list pages for more concise screen-reader output.
@@ -138,29 +2587,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [4.4.0] - 2026-08-23
 
-
-
 - Reworked the router example app to run inside a fake browser window — traffic-light chrome, working Back/Forward buttons wired to `router.back()`/`forward()` via one delegated listener, and a live address bar bound to `router.route` that updates as you navigate — making the URL-driven, no-reload story clearer.
 
 - **New `kerfjs/router` subpath — a client-side router (the "postcard router").** `createRouter({ routes, mode?, base?, interceptLinks? })` returns a handle over three things kerf already has: a reactive `route` signal (`{ path, params, query, hash }`), `delegate()`-based `<a href>` link interception, and a keyed **outlet** — `router.outlet()` renders the matched route in a `data-key`ed wrapper, so kerf's keyed morph **replaces the page wholesale on a route change** (fresh DOM) and **reconciles in place on a same-route param change** (preserving scroll / focus). Route patterns are static, `:param`, a trailing `*rest` wildcard, and `*` catch-all; the handle also gives `navigate(path, { replace?, state? })`, `back()`/`forward()`, `match(pattern)` / `activeClass(pattern, className)` reactive active-link helpers, hash **or** history mode, an optional base path, and `dispose()`. Link interception is automatic (same-origin, left-click, no modifier/`target`/`download`, opt out per-link with `data-router-ignore` / `rel="external"` or globally with `interceptLinks: false`). **Deliberately scoped** — no nested layouts, data loaders, lazy routes, guards, or SSR matching; compose those with kerf primitives (`resource` for loading, an `effect` on `route` for guards). The kerf **core stays router-free** — this is opt-in and tree-shakeable, adding nothing to the main barrel until imported, and docs/1's "Not a router" is about the runtime. See [`docs/20-router.md`](docs/20-router.md).
 
 ## [4.3.0] - 2026-08-22
 
-
-
 - KF-529: refresh README for the 4.3 cycle (prep-major-release) (`909c82a`)
 - KF-530: extract promise-dialog helpers into overlay-dialogs.ts (`5d4ac38`)
 - KF-528: sync llms.txt with docs/19 + 4.3 features (`1d9c004`)
 
 - **`kerfjs/overlay` gains opt-in native top-layer backing (`native: true`).** Every overlay surface (`overlay`, `confirm`, `prompt`, `form`, `choice`, `popover`, `tooltip`) now takes `native?: boolean` (default `false`). When `true` and the engine supports it, a **modal** surface (`trap: true`) is hosted in a `<dialog>` opened with `.showModal()` — real document inerting (pointer + focus + AT) and guaranteed stacking above any `z-index` — and a **non-modal** surface (`trap: false`) uses the **Popover API** (`[popover]` + `showPopover()`). Feature-detected (`HTMLDialogElement.prototype.showModal`, `HTMLElement.prototype.showPopover`), falling back to today's plain `<div>` where unsupported, so `native: true` is always safe to pass. The `render` slot + promise API are unchanged — kerf just hosts your markup in a `<dialog>` / `[popover]`. **Opt-in on purpose:** the native elements carry UA default styles (a `::backdrop`, centering, border, padding) that kerf does **not** reset (a reset would violate the zero-CSS contract) — style the element and its `::backdrop` via `className` (`.kerf-overlay::backdrop { … }`, the stable contract); and `container` becomes a visual no-op in native mode (the top layer ignores DOM position). See [`docs/19-native-overlay-backing.md`](docs/19-native-overlay-backing.md).
-- **`bindList` virtualization gains a `content-visibility` mode.** `virtualize: { rowHeight, mode: 'content-visibility' }` is a second virtualization strategy alongside the default `mode: 'window'` (today's JS windowing). It keeps **every** row in the DOM and sets `content-visibility: auto` + `contain-intrinsic-size: 0 <rowHeight>px` on each row, so a supporting engine (Chromium, Safari 18) skips the *layout/paint* of off-screen rows while **all rows stay findable** — find-in-page (Cmd/Ctrl+F), the accessibility tree, and anchor links / `scrollIntoView` all work on any row (the exact guarantee `mode: 'window'` can't give, since it removes off-window rows from the DOM). The `mode` choice is the app's and it's about list size: pick `'content-visibility'` for medium lists where findability beats the node ceiling, keep `'window'` for very large (100k-row) lists. In this mode `rowHeight` is only the `contain-intrinsic-size` placeholder (no windowing math), `setHeight` / `observeRowHeights` are no-ops (the browser owns measurement), `minRows` is ignored (all rows already render), and no scroll listener / `ResizeObserver` is installed — while `handle.container` / `containerClass` / `containerId` still work. There is deliberately **no feature detection**: on an engine without `content-visibility` the CSS is inert, so all rows still render (correct, still findable) — only the off-screen-skip optimization is absent. See [`docs/17-list-virtualization.md`](docs/17-list-virtualization.md) §17.11.
+- **`bindList` virtualization gains a `content-visibility` mode.** `virtualize: { rowHeight, mode: 'content-visibility' }` is a second virtualization strategy alongside the default `mode: 'window'` (today's JS windowing). It keeps **every** row in the DOM and sets `content-visibility: auto` + `contain-intrinsic-size: 0 <rowHeight>px` on each row, so a supporting engine (Chromium, Safari 18) skips the _layout/paint_ of off-screen rows while **all rows stay findable** — find-in-page (Cmd/Ctrl+F), the accessibility tree, and anchor links / `scrollIntoView` all work on any row (the exact guarantee `mode: 'window'` can't give, since it removes off-window rows from the DOM). The `mode` choice is the app's and it's about list size: pick `'content-visibility'` for medium lists where findability beats the node ceiling, keep `'window'` for very large (100k-row) lists. In this mode `rowHeight` is only the `contain-intrinsic-size` placeholder (no windowing math), `setHeight` / `observeRowHeights` are no-ops (the browser owns measurement), `minRows` is ignored (all rows already render), and no scroll listener / `ResizeObserver` is installed — while `handle.container` / `containerClass` / `containerId` still work. There is deliberately **no feature detection**: on an engine without `content-visibility` the CSS is inert, so all rows still render (correct, still findable) — only the off-screen-skip optimization is absent. See [`docs/17-list-virtualization.md`](docs/17-list-virtualization.md) §17.11.
 - **Docs: `bindList` virtualization findability/a11y tradeoff is now a first-class caveat.** Off-window rows are removed from the DOM (not just hidden), so with `virtualize` set, find-in-page (Cmd/Ctrl+F), screen readers / the accessibility tree, and anchor links / `scrollIntoView` reach only the visible window. New `docs/17-list-virtualization.md` §17.10 spells out the consequences and the guidance (don't virtualize, or use `minRows` above the list length, when full findability matters more than the DOM node ceiling), and the `bindList` JSDoc + `docs/8-api-reference.md` §8.11 carry the same note. Behavior unchanged — documentation only.
 - **State-preserving row moves via `moveBefore()` (transparent optimization).** When a keyed list reorders — `each()` (snapshot and granular paths), `bindList`, and `morph()`'s keyed / positional / list-marker moves — kerf now relocates an already-connected row with `Node.prototype.moveBefore()` where the engine supports it (Chromium 133+, spreading to other engines), falling back to `insertBefore()` everywhere else. `moveBefore()` is an atomic move: the node is never disconnected, so a moved row keeps its focus, text selection, `<iframe>` document state, playing media, running CSS transitions/animations, and open `popover`/`dialog` state across the reorder — richer state than the existing focus snapshot in the reconciler could ever restore, and it needs no snapshot at all where it runs. No API change and no behavior change on engines without `moveBefore()`; the focus-preservation snapshot stays in place for them. Fresh (not-yet-connected) rows still use `insertBefore()` — only genuine moves of connected rows take the new path. See [`docs/18-state-preserving-moves.md`](docs/18-state-preserving-moves.md).
 
 ## [4.2.0] - 2026-08-20
 
-
-
 - Added a **Virtual list** example app — a 10,000-row virtualized list showcasing the companion subpaths together: `kerfjs/list` viewport virtualization (only a screenful in the DOM), `kerfjs/timing` debounced search, and `kerfjs/overlay` confirm-to-delete with a toast. Includes a live "in the DOM" counter that stays flat as you scroll all 10,000 rows.
 - Expanded the README with a companion-subpaths spotlight covering `list`, `overlay`, `async`, `scope`, `timing`, `remount`, `attach`, and `actions`, with `bindList` fixed and measured-height virtualization examples.
 - Corrected the complete-apps index to accurately describe the eight standalone showcase apps and note that the cart and counter-store apps live in the migration guides.
@@ -174,86 +2617,70 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - **New `kerfjs/remount` subpath** — `remountOn(parent, key, render)`, the opposite of kerf's morph-by-default: **replace** a subtree wholesale when `key` changes instead of morphing it. Names the hand-rolled `data-key={`gen-${n}`}` + `data-morph-skip` counter trick, for library-owned subtrees (a highlighted diff, a chart, an editor) that must tear down and re-initialize on fresh DOM. `key` is a signal or a thunk `() => K`; an unchanged key (including a thunk whose inputs moved but whose value stayed equal) leaves the subtree alone, so per-row reactivity inside `render` still updates in place. An optional `onMount(root)` callback runs after each (re)mount with the live subtree — the place to bind an imperative widget (`kerfjs/attach`) to the fresh DOM; returning `attach`'s disposer from it makes teardown synchronous. `remountOn` owns `parent`'s children and returns a disposer. Optional and tree-shakeable.
 - **New `kerfjs/timing` subpath** — the `let timer; clearTimeout(timer); timer = setTimeout(…)` pattern every app hand-rolls, blessed with disposer-shaped ergonomics. `debounce(fn, ms)` is trailing-edge (runs once `ms` after calls stop, latest args); `throttle(fn, ms)` is leading-plus-trailing (fires immediately, then at most once per `ms`, collapsing a burst to one trailing call). Both return a callable with `cancel()` / `flush()`. `debouncedSignal(source, ms)` is a read-only signal that trails `source` by `ms` so it composes inside the reactive graph (`computed`/`effect`/`mount`) instead of beside it. `debounce`/`throttle` are dependency-free; `debouncedSignal` pulls in signals only (no render core). Optional and tree-shakeable; tiny.
 - **New `kerfjs/scope` subpath** — tie disposers to a DOM element's lifetime, so append-heavy UIs stop leaking detached-but-subscribed effects/listeners. `disposeScope(el)` returns a WeakMap-keyed, accumulating scope whose `add(disposer)` (plus convenience `mount` / `effect` / `delegate` wrappers that register their own disposer) collects teardown; `dispose()` runs it all best-effort and idempotently. `disposeSubtree(root)` sweeps a subtree before removal; `observeRemovals(root)` installs one `MutationObserver` that auto-disposes on removal. No module-level mutable state. Optional and tree-shakeable.
-- **New `kerfjs/overlay` subpath** — the blessed modal/overlay + dismiss manager that every real kerf app hand-rolls. `overlay(content, options?)` appends a wrapper, `mount()`s content inside it (owning the disposal), wires dismissals (Escape / backdrop / outside-click, with `outsideIgnore`), a focus trap (`role="dialog"` / `aria-modal`, Tab wrap-around, restore-focus-on-close), and returns `{ el, close(result?), result }`. `confirm(message, options?)` is a promise-based `window.confirm` replacement, and `prompt(message, options?)` → `Promise<string | null>` its `window.prompt` counterpart (both globals are no-ops in Tauri webviews); `form(fields, options?)` → `Promise<Record<string, string> | null>` collects a two-or-three-field dialog. `choice<R>(message, actions, options?)` → `Promise<R | null>` is the **N-way** sibling of `confirm` — one button per action resolves that action's `value` (or `null` on dismissal), and `options.defaultValue` makes **Enter** (anywhere in the dialog) resolve a default action (the "global Enter-to-confirm" model) without holding the overlay handle. `prompt`/`form` submit on Enter and take an inline `validate`; all auto-escape their content. `confirm` / `prompt` / `form` also accept a **`render` slot option** for design-system teams — return your own markup and spread the provided `ok`/`cancel` (+ `input`/`error`) wiring onto it; kerf keeps owning the promise, `validate`, Enter-submit, dismiss, focus-trap, and focus-restore, so you adopt the batteries-included dialogs without a CSS rewrite. `popover(anchor, content, options?)` → `OverlayHandle` is a non-modal **anchored** overlay: it positions the content relative to `anchor` (below by default, flipping above on viewport overflow, clamped horizontally), defaults to dismiss-on-outside with the anchor exempt, and repositions on scroll / resize. `popover`'s placement core is also exported standalone: **`positionAnchored(el, anchor, options?)`** (one-shot) and **`autoReposition(el, anchor, options?)`** (keeps an element positioned on scroll/resize, returns a disposer) position *your own* element with no overlay lifecycle. **`tooltip(anchor, content, options?)`** is a hover/focus-triggered, non-modal, auto-hiding tooltip built on them. `toast(content, options?)` now returns a **`ToastHandle` (`{ el, dismiss }`)** instead of a bare dismiss function, so callers can inspect the node, wire an action button, or run entrance/exit transitions; new options: `mode: 'replace'` (collapse a rapid sequence to the latest) with `collapse: 'fade'` (default — run the prior toast's exit transition, good for a stacking region) or `'instant'` (remove it synchronously, what a single centered slot wants so messages never cross-fade in place), `variant` (`'info'`/`'success'`/`'warning'` → a `${className}--${variant}` accent class), `enterClass` (added on the next animation frame for a CSS entrance) and `exitClass` + `exitDuration` (CSS owns the exit — on dismiss the `enterClass` is **removed** so `exitClass` needn't out-specify it, and a symmetric single-class fade works with just `enterClass` + `exitDuration`; the node is removed after the delay). `dismiss({ instant: true })` removes the toast **synchronously** (skipping the exit transition), and `mode: 'replace'` `collapse: 'instant'` also force-removes a toast that is already mid-fade — so an action button that dismisses itself and shows a replacement in a single centered slot doesn't cross-fade the two. **Breaking (beta):** `toast()`'s return type changed from `() => void` to `{ el, dismiss }` — call `toast(...).dismiss()` or destructure `{ dismiss }`. Structural only — kerf ships no CSS. Optional and tree-shakeable; shares the core with the main barrel via code-splitting.
+- **New `kerfjs/overlay` subpath** — the blessed modal/overlay + dismiss manager that every real kerf app hand-rolls. `overlay(content, options?)` appends a wrapper, `mount()`s content inside it (owning the disposal), wires dismissals (Escape / backdrop / outside-click, with `outsideIgnore`), a focus trap (`role="dialog"` / `aria-modal`, Tab wrap-around, restore-focus-on-close), and returns `{ el, close(result?), result }`. `confirm(message, options?)` is a promise-based `window.confirm` replacement, and `prompt(message, options?)` → `Promise<string | null>` its `window.prompt` counterpart (both globals are no-ops in Tauri webviews); `form(fields, options?)` → `Promise<Record<string, string> | null>` collects a two-or-three-field dialog. `choice<R>(message, actions, options?)` → `Promise<R | null>` is the **N-way** sibling of `confirm` — one button per action resolves that action's `value` (or `null` on dismissal), and `options.defaultValue` makes **Enter** (anywhere in the dialog) resolve a default action (the "global Enter-to-confirm" model) without holding the overlay handle. `prompt`/`form` submit on Enter and take an inline `validate`; all auto-escape their content. `confirm` / `prompt` / `form` also accept a **`render` slot option** for design-system teams — return your own markup and spread the provided `ok`/`cancel` (+ `input`/`error`) wiring onto it; kerf keeps owning the promise, `validate`, Enter-submit, dismiss, focus-trap, and focus-restore, so you adopt the batteries-included dialogs without a CSS rewrite. `popover(anchor, content, options?)` → `OverlayHandle` is a non-modal **anchored** overlay: it positions the content relative to `anchor` (below by default, flipping above on viewport overflow, clamped horizontally), defaults to dismiss-on-outside with the anchor exempt, and repositions on scroll / resize. `popover`'s placement core is also exported standalone: **`positionAnchored(el, anchor, options?)`** (one-shot) and **`autoReposition(el, anchor, options?)`** (keeps an element positioned on scroll/resize, returns a disposer) position _your own_ element with no overlay lifecycle. **`tooltip(anchor, content, options?)`** is a hover/focus-triggered, non-modal, auto-hiding tooltip built on them. `toast(content, options?)` now returns a **`ToastHandle` (`{ el, dismiss }`)** instead of a bare dismiss function, so callers can inspect the node, wire an action button, or run entrance/exit transitions; new options: `mode: 'replace'` (collapse a rapid sequence to the latest) with `collapse: 'fade'` (default — run the prior toast's exit transition, good for a stacking region) or `'instant'` (remove it synchronously, what a single centered slot wants so messages never cross-fade in place), `variant` (`'info'`/`'success'`/`'warning'` → a `${className}--${variant}` accent class), `enterClass` (added on the next animation frame for a CSS entrance) and `exitClass` + `exitDuration` (CSS owns the exit — on dismiss the `enterClass` is **removed** so `exitClass` needn't out-specify it, and a symmetric single-class fade works with just `enterClass` + `exitDuration`; the node is removed after the delay). `dismiss({ instant: true })` removes the toast **synchronously** (skipping the exit transition), and `mode: 'replace'` `collapse: 'instant'` also force-removes a toast that is already mid-fade — so an action button that dismisses itself and shows a replacement in a single centered slot doesn't cross-fade the two. **Breaking (beta):** `toast()`'s return type changed from `() => void` to `{ el, dismiss }` — call `toast(...).dismiss()` or destructure `{ dismiss }`. Structural only — kerf ships no CSS. Optional and tree-shakeable; shares the core with the main barrel via code-splitting.
 - **New `kerfjs/actions` subpath** — the blessed delegated action-table helper. `action(value)` returns a `data-action` `AttrSpec` (a thin specialization of `attr()`); `delegateActions(root, eventType, table, options?)` wires a whole table of `data-action` handlers with one delegated listener (built on `delegate()`) and returns a disposer. Formalizes the most-reinvented idiom in real kerf apps — one `attr('data-action', …)` table as the single source of truth for both the JSX attribute and the delegate dispatch. Optional and tree-shakeable; adds nothing to the main barrel.
 
 ## [4.1.1] - 2026-08-14
 
-
-
 - Added a CDN / importmap quickstart (`docs/6-jsx-runtime.md` §6.11.1) covering three no-install ways to load kerf from an ESM CDN: a direct `esm.sh` import, and jsDelivr / unpkg behind an importmap that also maps `@preact/signals-core`. Explains why a raw `dist/*.js` path fails (its unrewritten bare `@preact/signals-core` import won't resolve in the browser) and recommends pinning to a major version.
 - Updated the README no-build example to use version-pinned CDN URLs (`kerfjs@4`) and noted that jsDelivr / unpkg need an importmap while esm.sh works with a direct import.
 
 ## [4.1.0] - 2026-07-31
 
-
-
 - ESLint 10 is now supported: `eslint-plugin-kerfjs` declares `peerDependencies.eslint` as `^9.0.0 || ^10.0.0`, and every named major is exercised by the rule suite in CI.
 - The plugin now runs its rule suite against each supported ESLint major via `npm run test:eslint-matrix`, which also fails if the declared peer range, the tested set, and the CI matrix disagree — or if the range is left open-ended.
 
-
 - **ESLint 8 is no longer supported by `eslint-plugin-kerfjs`.** The package is ESM-only and ESLint 8 resolves `.eslintrc` plugins with `require()`, so `extends: ["plugin:kerfjs/…"]` could never load it.
 - **Legacy `.eslintrc` configuration is documented as unsupported.** Use flat config (`eslint.config.js`); the `legacy-recommended` export remains in the package but is unreachable through any config system and should be treated as deprecated.
 
-
 - Generated Hot Sheet skill and rule files no longer hardcode a machine's local API port or shared secret. The curl fallbacks read `$HOTSHEET_PORT` / `$HOTSHEET_SECRET` from `.hotsheet/settings.local.json` and `.hotsheet/secret.json` instead, with `.hotsheet/settings.json` as the fallback for older projects.
 - A new `npm run check:audit` gate runs `npm audit --omit=dev --audit-level=high` against the published dependency tree and is wired into the pre-push `check:full` gate.
 
-
 - Test tooling moved to vitest 4 and ESLint 10; coverage thresholds were recalibrated to 98.5% branches / 99.5% statements (lines and functions stay at 100%) after vitest 4's sharper AST-based coverage mapping resolved seventeen previously-miscredited defensive branches.
 - Removed the `hs-m` marketing-ticket skill and Cursor rule.
 
 ## [4.0.0] - 2026-07-28
 
-
-
 - `draggable`, `spellCheck`, and `contentEditable` no longer accept booleans — they are enumerated HTML attributes, so write the keyword string (`draggable="true"`, `spellCheck="false"`). The boolean forms rendered markup that meant the opposite of what was written; real boolean attributes like `hidden`/`checked`/`disabled` are unchanged.
 - `<select value>` / `<textarea value>` (and their `defaultValue` forms) no longer typecheck — neither element has a `value` content attribute, so kerf was emitting markup no browser reads. Use `<option selected>` and `<textarea>{draft}</textarea>`.
-- Lowercase `autofocus` no longer accepts `"true"` / `"false"` — it is a real boolean attribute, so `autofocus="false"` turned autofocus *on*. Use `autofocus={false}` or omit it.
-
+- Lowercase `autofocus` no longer accepts `"true"` / `"false"` — it is a real boolean attribute, so `autofocus="false"` turned autofocus _on_. Use `autofocus={false}` or omit it.
 
 - `href="javascript:void(0)"` and its five sibling spellings are no longer dropped by the URL screen. Dropping the `href` unmade the anchor — it lost `:link` styling, keyboard focus, and its pointer cursor. Matching is against the whole normalized value, so nothing can ride along after an inert body.
 - `defaultSelected` rendered as `defaultselected`, an attribute no browser reads, so the option it named was never pre-selected. It now correctly emits `selected`.
 
-
 - Typed JSX gained a wide set of modern attributes: globals `inert`, `popover`, `nonce`, `part`/`exportparts`, `enterKeyHint`, `translate`, `autocorrect`, and the full microdata family; per-element `<button popoverTarget/popoverTargetAction/command>`, `<input popoverTarget/popoverTargetAction>`, `<form rel>`, `<source width/height>`, and `writingsuggestions`.
 - `<button command>` is now typed to the spec keywords (`show-modal`, `close`, `request-close`, `toggle-popover`, `show-popover`, `hide-popover`) plus any `--custom` command, catching a custom command written without its required `--` prefix.
 - `<a download>` and `<area download>` accept the bare boolean form as well as a string filename, so `<a href="/report.pdf" download>` compiles.
 
-
 - The advertised bundle size is corrected everywhere: ~12 KB min+gzip for a realistic import, ~13 KB with `arraySignal` (previously stated as ~11/~12 KB, and ~6.1 KB in the Cursor rules). Every migration page's delta row was recomputed against the new figure.
 - The JSX runtime doc gained a section on enumerated vs. boolean attributes, and the API reference now records where the JSX types come from (WHATWG HTML Living Standard + SVG 2, not another framework's property table).
 - The dev-warning sections in the dev-warnings doc were renumbered by family so the `11.2.N` headings run in document order; cross-references elsewhere in the docs were updated to match.
 
-
-- The bundle-size check now gates the *prose* as well as the build: every place the docs advertise a size is matched against the measured figure, and a reworded claim that stops matching fails rather than going silently unchecked.
+- The bundle-size check now gates the _prose_ as well as the build: every place the docs advertise a size is matched against the measured figure, and a reworded claim that stops matching fails rather than going silently unchecked.
 - New repo checks wired into `npm run check`: `check:docs:dev-warns` (the dev-warning doc and `ENV_NAME` must name the same set, with monotonic section numbers), `check:design-rule-5` (every top-level `let` in `src/` must be accounted for by the documented rule), and `check:skills` (a skill file restating a threshold its owner disagrees with fails).
 
 ## [3.0.0] - 2026-07-27
 
-
-
 - **kerf no longer infers development mode — add one line to your entry to keep the dev diagnostics.**
 
   ```js
-  if (import.meta.env.DEV) await import('kerfjs/dev');                   // Vite
-  if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev'); // webpack / Node
+  if (import.meta.env.DEV) await import("kerfjs/dev"); // Vite
+  if (process.env.NODE_ENV !== "production") await import("kerfjs/dev"); // webpack / Node
   ```
 
   Without it you get production shape: no dev warnings, no read-only `defineStore` `get()`
   snapshot, and a screened dangerous URL warns-and-drops instead of throwing. Nothing else
   changes, and if you never used the dev warnings you get a smaller bundle for free.
 
-  **Why it changed.** kerf inferred its own dev/prod mode by reading `globalThis.process?.env?.NODE_ENV`. Bundlers substitute the *bare* `process.env.NODE_ENV` token and never create a `globalThis.process` object for browser targets, so that read was `undefined`, `undefined !== 'production'` was `true`, and every production browser build silently took the development path. Consequences that were shipping: every `defineStore` `get()` returned a deep read-only `Proxy` (an allocation on every store read), a screened `javascript:`/`data:` URL **threw** instead of the documented warn-and-drop, and the always-on list-key warnings printed to production consoles. Server/Node builds, where `process` exists, were unaffected.
+  **Why it changed.** kerf inferred its own dev/prod mode by reading `globalThis.process?.env?.NODE_ENV`. Bundlers substitute the _bare_ `process.env.NODE_ENV` token and never create a `globalThis.process` object for browser targets, so that read was `undefined`, `undefined !== 'production'` was `true`, and every production browser build silently took the development path. Consequences that were shipping: every `defineStore` `get()` returned a deep read-only `Proxy` (an allocation on every store read), a screened `javascript:`/`data:` URL **threw** instead of the documented warn-and-drop, and the always-on list-key warnings printed to production consoles. Server/Node builds, where `process` exists, were unaffected.
 
   Removing the inference also shrinks production bundles by **~4.7 KB min+gzip (27%)** — a realistic import (`signal`/`computed`/`effect`/`batch`/`mount`/`each`/`delegate`) goes from 16.91 KB to **12.24 KB**. Previously the dev-warning modules were imported unconditionally by `mount()`/`each()` and gated at runtime, so they shipped to production regardless of build mode and no amount of tree-shaking could reclaim them. With the dev entry absent they are unreachable, and the `import()` statement itself is eliminated — the chunk is never emitted, let alone fetched.
 
   `globalThis.KERF_DEV` is no longer consulted — not importing the dev entry is now the (compile-time) way to opt out. One ordering note: `signal()` picks its constructor at creation time, so put the import first if you rely on the untracked-signal warning.
 
-- The `KERF_DEV_WARN_*` diagnostics no longer consult `NODE_ENV` or `globalThis.KERF_DEV` at all. Whether they run is decided in exactly one place: whether you imported `kerfjs/dev`. The previous release stopped kerf's core from inferring dev mode but left a second, inherited gate inside each warner, so a Node/SSR consumer who *deliberately* installed the diagnostics under `NODE_ENV=production` got silence — and `globalThis.KERF_DEV = false` still silenced warnings the consumer had explicitly opted into. Both are gone; each warning is now gated only by its own env var. If you were using `globalThis.KERF_DEV` to turn diagnostics off, remove the dev import instead (which is also what sheds the ~4.7 KB from your bundle).
+- The `KERF_DEV_WARN_*` diagnostics no longer consult `NODE_ENV` or `globalThis.KERF_DEV` at all. Whether they run is decided in exactly one place: whether you imported `kerfjs/dev`. The previous release stopped kerf's core from inferring dev mode but left a second, inherited gate inside each warner, so a Node/SSR consumer who _deliberately_ installed the diagnostics under `NODE_ENV=production` got silence — and `globalThis.KERF_DEV = false` still silenced warnings the consumer had explicitly opted into. Both are gone; each warning is now gated only by its own env var. If you were using `globalThis.KERF_DEV` to turn diagnostics off, remove the dev import instead (which is also what sheds the ~4.7 KB from your bundle).
 
-
-- **New:** `each()` accepts an options object — `each(items, render, { cacheKey, key })` — and `key` gives a list a **stable identity**. Without one a list is identified by its position among the `each()` calls in a render, so adding or removing a conditional list above it made kerf rebuild it from scratch: rows lost their DOM nodes, and with them focus, scroll position and in-progress IME composition. Keying a list removes that dependency; because a keyed list doesn't occupy a positional slot, keying just the *conditional* list usually stabilizes its siblings too. The existing three-argument `each(items, render, cacheKey)` form is unchanged. In development kerf now warns once per list when it detects such a shift and names the fix.
+- **New:** `each()` accepts an options object — `each(items, render, { cacheKey, key })` — and `key` gives a list a **stable identity**. Without one a list is identified by its position among the `each()` calls in a render, so adding or removing a conditional list above it made kerf rebuild it from scratch: rows lost their DOM nodes, and with them focus, scroll position and in-progress IME composition. Keying a list removes that dependency; because a keyed list doesn't occupy a positional slot, keying just the _conditional_ list usually stabilizes its siblings too. The existing three-argument `each(items, render, cacheKey)` form is unchanged. In development kerf now warns once per list when it detects such a shift and names the fix.
 
 - **`kerfjs/dev` now exports `enableWarnings()`** — and it fixes a defect: until now, none of the
   `KERF_DEV_WARN_*` diagnostics could be switched on in a browser at all. Every one of them read `globalThis.process.env`, which does not exist in a browser realm — and a bundler `define` cannot reach it either, because the read goes through `globalThis.process` into a local binding rather than the substitutable `process.env.X` token. So in a Vite/webpack dev server, the environment where these warnings are most wanted, the entire opt-in family was permanently and silently off. Only Node/SSR (and kerf's own vitest suite, which is why nothing caught it) could turn any of them on.
@@ -262,8 +2689,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
   ```js
   if (import.meta.env.DEV) {
-    const dev = await import('kerfjs/dev');
-    dev.enableWarnings({ staleBinding: true, narrowSet: true, invariants: 'throw' });
+    const dev = await import("kerfjs/dev");
+    dev.enableWarnings({
+      staleBinding: true,
+      narrowSet: true,
+      invariants: "throw",
+    });
   }
   ```
 
@@ -277,8 +2708,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - New opt-in dev warning `KERF_DEV_WARN_LIST_REBIND=1`: fires (once per list) when an `each()` list's container is rebuilt by the morph — an ancestor's tag changed across renders, so the subtree was replaced and the list self-healed by re-binding and repopulating. The recovery is correct but discards row DOM state (focus, scroll, IME, imperative listeners); the warning names the list and points at keeping ancestor tags stable. Follows the standard `KERF_DEV_WARN_*` family rules: off by default, dev-mode only, zero production cost.
 
-
-- `KERF_DEV_WARN_UNTRACKED_SIGNALS=1` now tells you what it can and cannot see. The warning picks its machinery when a signal is *created*, so it only covers signals created after `kerfjs/dev` is installed — and because static imports are hoisted above a top-level `await import('kerfjs/dev')`, the module-scope signals it most wants to catch are usually created first. Previously that failed silently: you set the env var, saw nothing, and concluded your code was clean. Opting in now prints the coverage boundary once, along with the fix (make `import 'kerfjs/dev'` the first static import of a dev-only entry file). The boundary itself can't be removed — `Signal.prototype`'s `value` accessor is non-configurable, so already-created signals can't be retro-fitted without kerf keeping a registry of every signal, which production would pay for.
+- `KERF_DEV_WARN_UNTRACKED_SIGNALS=1` now tells you what it can and cannot see. The warning picks its machinery when a signal is _created_, so it only covers signals created after `kerfjs/dev` is installed — and because static imports are hoisted above a top-level `await import('kerfjs/dev')`, the module-scope signals it most wants to catch are usually created first. Previously that failed silently: you set the env var, saw nothing, and concluded your code was clean. Opting in now prints the coverage boundary once, along with the fix (make `import 'kerfjs/dev'` the first static import of a dev-only entry file). The boundary itself can't be removed — `Signal.prototype`'s `value` accessor is non-configurable, so already-created signals can't be retro-fitted without kerf keeping a registry of every signal, which production would pay for.
 
 - An `each()` of `<tr>` written directly inside `<table>` now fails with a clear error instead of silently duplicating rows: the HTML parser inserts a `<tbody>` around the rows, which kerf cannot bind through. The message names both tags and shows the supported shape (`<table><tbody>{each(...)}</tbody></table>`). Previously this also mis-reported the rows as missing `data-key`.
 
@@ -286,8 +2716,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - Toolchain: the repo now type-checks with the native **TypeScript 7** compiler across every gate (`typecheck`, the dist `.d.ts` typing gates, the docs code-block compile — a full-repo `tsc --noEmit` now takes ~0.3 s), with `typescript@6` (the JS-API bridge release) retained for tsup's `.d.ts` emit and typescript-eslint, which still require the JS compiler API. `@typescript-eslint/*` bumped to 8.65. No shipped-code changes — `dist/` output is unaffected.
 
-
-- Fixed: passing a **function** as an `each()` item through an `arraySignal` insert/update (an unusual mistake, but functions are valid `WeakMap` keys so the per-item cache silently accepted them) rendered the row and then threw `each(): items must be objects…` on a *later, unrelated* re-render — far from the cause. The granular path now enforces the same objects-only item contract the snapshot path does, so the error is thrown on the render the offending mutation triggered, naming the type and index. Primitive items already behaved this way; functions now match.
+- Fixed: passing a **function** as an `each()` item through an `arraySignal` insert/update (an unusual mistake, but functions are valid `WeakMap` keys so the per-item cache silently accepted them) rendered the row and then threw `each(): items must be objects…` on a _later, unrelated_ re-render — far from the cause. The granular path now enforces the same objects-only item contract the snapshot path does, so the error is thrown on the render the offending mutation triggered, naming the type and index. Primitive items already behaved this way; functions now match.
 
 - `arraySignal.update(i, fn)` now works when `fn` mutates the row object and returns it (not only when it returns a fresh object). Previously such a same-ref update rendered correctly in one list but left every other view of the same signal — a second list, a second `mount()`, a `filter()`ed plain-array view — permanently stale, and was lost outright when the update was batched with a selection change or a `replace()`. kerf now tracks a per-item content version so the change reaches every consumer. Returning a fresh object remains the idiomatic style; both are supported. (Fixed in the same line of work: the per-item version tracking briefly made `arraySignal.update()` throw on a signal of primitives — `arraySignal<number>` used as a plain signal — because a primitive can't key the internal version map; primitive items are now simply skipped, since only object rows are ever memoized.)
 
@@ -299,13 +2728,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - Fixed: an `arraySignal.update()` that mutated a row object in place (returning the same reference) could be silently reverted to its old content by the next unrelated re-render. The granular update path now keeps kerf's per-row HTML cache in sync with what it rendered, so the two never disagree. (Immutable updates — returning a fresh object — were unaffected, and remain the recommendation.)
 
-- Fixed: showing an empty conditionally-rendered `each()` list in the same batch as an update to a *sibling* list could empty the sibling entirely — it rendered zero rows. When the conditional list reappeared, its list-marker comment landed next to the sibling's, and the diff overwrote the sibling marker's internal id with the reappearing one's, so the sibling's binding could no longer find its own marker. Marker comments (kerf's internal list and binding anchors) now pair only with the identical marker, never with a different one that happens to be the same kind. Ordinary comments in your markup are unaffected.
+- Fixed: showing an empty conditionally-rendered `each()` list in the same batch as an update to a _sibling_ list could empty the sibling entirely — it rendered zero rows. When the conditional list reappeared, its list-marker comment landed next to the sibling's, and the diff overwrote the sibling marker's internal id with the reappearing one's, so the sibling's binding could no longer find its own marker. Marker comments (kerf's internal list and binding anchors) now pair only with the identical marker, never with a different one that happens to be the same kind. Ordinary comments in your markup are unaffected.
 
 - Fixed: when an element rendered by a condition came back, the diff could pair it with an unrelated sibling that happened to have the same tag, and then whatever protects that sibling's contents kept the wrong contents alive inside it. A `data-morph-skip` widget **swallowed** the reappearing element — its content never rendered — and the widget was duplicated, which for a library-owned subtree (an editor, a chart, a terminal) means a second live instance attached to a node the library has no reference to. A `data-morph-preserve` child ended up under the foreign host and appeared twice. A bound hole's text leaked into the reappearing element and rendered twice. Three rules now gate that pairing: an element with an `id`/`data-key` is only ever matched to a live element with the same key; a `data-morph-skip` element only ever matches another one (so a library-owned subtree is never adopted as a stand-in, whether or not you use keys); and a comment anchoring kerf's own state only matches an anchor of the same kind. Ordinary elements without a key still match positionally exactly as before.
 
-- Fixed: when the number of `each()` calls in a render changed — a conditional list appearing or disappearing — a *surviving* list could render the departed list's rows, or render its own rows inside the wrong container. Lists without a `key` are identified by their position among the `each()` calls, and both the per-item HTML cache and the live list binding were being read as belonging to whichever list now held that position. Two lists over the same collection hit each other's cache exactly, so nothing could detect it from the data. A shift now discards that state and re-renders, which is what the documentation already described it as costing: a rebuild, never wrong output. Lists given a `key` are unaffected, and a render that doesn't change the call count is unaffected. One related improvement falls out: an unrelated list no longer loses its row nodes when a nested `each()` shifts the count.
+- Fixed: when the number of `each()` calls in a render changed — a conditional list appearing or disappearing — a _surviving_ list could render the departed list's rows, or render its own rows inside the wrong container. Lists without a `key` are identified by their position among the `each()` calls, and both the per-item HTML cache and the live list binding were being read as belonging to whichever list now held that position. Two lists over the same collection hit each other's cache exactly, so nothing could detect it from the data. A shift now discards that state and re-renders, which is what the documentation already described it as costing: a rebuild, never wrong output. Lists given a `key` are unaffected, and a render that doesn't change the call count is unaffected. One related improvement falls out: an unrelated list no longer loses its row nodes when a nested `each()` shifts the count.
 
-- Fixed: a row added to an `each()` list could land in the wrong place whenever the list wasn't the last thing inside its parent. A list ends at its last row, but kerf was looking for the next *element* after it and skipping everything else on the way — so static content following the list (a footer row, a totals line, an "add item" control) got jumped, and a new row appeared after it instead of before. The same skip crossed a neighboring list's internal anchor: with two `each()` lists in one parent, rows from the first could be placed inside the second's region, and when both lists started empty their rows came out **in the wrong order** — the second list's rows rendered first. Both were correct on the initial paint and only went wrong on a later update, which made them read as intermittent. Lists now anchor on the next node of any kind, so a list's rows always stay within its own region.
+- Fixed: a row added to an `each()` list could land in the wrong place whenever the list wasn't the last thing inside its parent. A list ends at its last row, but kerf was looking for the next _element_ after it and skipping everything else on the way — so static content following the list (a footer row, a totals line, an "add item" control) got jumped, and a new row appeared after it instead of before. The same skip crossed a neighboring list's internal anchor: with two `each()` lists in one parent, rows from the first could be placed inside the second's region, and when both lists started empty their rows came out **in the wrong order** — the second list's rows rendered first. Both were correct on the initial paint and only went wrong on a later update, which made them read as intermittent. Lists now anchor on the next node of any kind, so a list's rows always stay within its own region.
 
 - Fixed: an `each()` list inside an `<svg>` whose row markup contained an apostrophe (or anything else the serializer writes back differently) failed to mount at all, with a self-contradictory error. Also fixed: `each({ key })` now validates the key, so a key containing an HTML comment terminator can no longer break out of the list's internal marker and put markup in the page.
 
@@ -317,7 +2746,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - Fixed: a controlled `checked` / `value` on an `each()` row's own top-level element could stay visibly stale after the user had interacted with it — the row reconciler's attribute-only fast path wrote the attribute without syncing the live property, so whether the control obeyed your data depended on which internal route the update happened to take.
 
-- Fixed: when a conditionally-rendered `each()` list is added or removed, a sibling list could render the *other* list's rows — a batched "hide one list and push to another" applied the queued update to the wrong list's DOM. Lists now verify which data a pending update belongs to before applying it, and rebuild from their own items when it doesn't match.
+- Fixed: when a conditionally-rendered `each()` list is added or removed, a sibling list could render the _other_ list's rows — a batched "hide one list and push to another" applied the queued update to the wrong list's DOM. Lists now verify which data a pending update belongs to before applying it, and rebuild from their own items when it doesn't match.
 
 - Fixed: `each()` rows inside an `<svg>` root were re-parsed in the HTML namespace on every update, so rows added or structurally changed after the first render were invisible in the browser — the initial picture looked right, which made it read as a rendering flake. Row parsing now follows the list parent's namespace (rows under `<foreignObject>` correctly stay HTML).
 
@@ -325,92 +2754,72 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - Fixed: anything sitting between a keyed `each()` list's anchor and its rows — a node injected imperatively into the list region — could make a conditional sibling's removal reorder the list, landing a trailing sibling ahead of the rows. A list's row region (anchor through last row) is now treated as one unit by the diff: it moves whole, the diff's cursor steps over it whole, and injected nodes inside it travel along keeping their position relative to the rows.
 
-- A conditional sibling *inside* a keyed `each()` list's parent — a header row that comes and goes above the list — no longer costs the list's rows their DOM identity. The morph now recognizes the list's marker when a sibling shifts it, moving the marker and its rows up as a single unit instead of rebuilding the list, so row nodes, focus, and the caret survive the toggle. (An ancestor tag change, or a same-tag sibling that positionally takes the container's place, still rebuilds the list — give the list's own container a stable `id`/`data-key` if its rows need to survive that.)
+- A conditional sibling _inside_ a keyed `each()` list's parent — a header row that comes and goes above the list — no longer costs the list's rows their DOM identity. The morph now recognizes the list's marker when a sibling shifts it, moving the marker and its rows up as a single unit instead of rebuilding the list, so row nodes, focus, and the caret survive the toggle. (An ancestor tag change, or a same-tag sibling that positionally takes the container's place, still rebuilds the list — give the list's own container a stable `id`/`data-key` if its rows need to survive that.)
 
 - Fixed: a conditional sibling that shared or positionally shadowed a keyed `each()` list's container could strand the list's rows and then render a duplicate copy of them (e.g. a header `<li>` toggled inside the list's `<ul>`, or a same-tag banner `<ul>` before the list container). The morph can separate the list's marker comment from its still-attached rows; the self-heal now removes any such still-live stranded rows before repopulating, so recovery replaces the rows rather than duplicating them.
 
 ## [2.0.1] - 2026-07-23
 
-
-
 - Fixed a `morph()` bug where static text siblings of a fine-grained bound text hole were dropped after a structural re-render (e.g. `<div>{label} / static</div>` collapsing to just the label).
 
-
 - New animated coding-session demo on the getting-started page: watch the canonical counter get typed out, served, clicked in a browser, and live-edited into a todo list.
 - Added an animated architecture diagram and a link to the docs site from the README.
 
 ## [2.0.0] - 2026-07-23
 
-
-
 - `delegateCapture()` now uses `closest()`-style walk-up matching like `delegate()`, passing the matched ancestor to the handler; pass `{ match: 'direct' }` (new `DelegateOptions`) to restore exact-element matching.
 - The dangerous-URL screen (`javascript:`, `vbscript:`, script-executing `data:` URLs) now throws an error in development instead of only warning. Production behavior is unchanged: warn and drop the attribute.
 
-
 - New `kerfjs/html` tagged template: author kerf UIs with no build step (CDN / importmap, no JSX transform) with runtime semantics identical to JSX — signal holes become fine-grained bindings, attributes and text are escaped and URL-screened the same way.
 - New no-build example app, **live-poll**, served exactly as authored — an importmap plus one `html`-templated module, with view-source showing the app.
 - Added `<filter>` to the typed JSX intrinsic elements, so SVG filters compile in JSX-authored code.
 - Fully-bound mounts are now a documented, test-pinned guarantee: a render that reads no signal `.value` runs exactly once, forever — every update is a direct per-node write.
 
-
 - Controlled form state now survives user interaction: `checked`, `value`, and `selected` DOM properties are synced when the reconciler mutates those attributes, so a clicked checkbox or typed-into input no longer ignores later updates.
 - Fixed stale fine-grained bindings after `arraySignal.update()`: in-place row updates now re-wire bindings whose signal instance changed, instead of leaving effects reading the old row object forever.
 
-
 - New runtime dev-mode override: set `globalThis.KERF_DEV = false` (or `true`) to control dev mode without a bundler — CDN/importmap apps are no longer stuck in dev mode in production.
 - Two new opt-in dev warnings: `KERF_DEV_WARN_STALE_BINDING` flags bindings that silently go stale on the byte-equal fast path, and `KERF_DEV_WARN_VALUE_ONLY_RERENDER` flags re-renders whose only changes could have been fine-grained bindings.
 - `defineStore`'s dev-mode `get()` snapshot now returns a deep read-only proxy instead of freezing the live state: nested mutations like `get().nested.x = 1` are caught too, and they throw a descriptive `TypeError` rather than failing silently.
 
-
 - Docs repositioned around the "values bind, structure re-renders" idiom as the primary way to render dynamic values, across the overview, reactivity guide, and AI assistant configs.
 - New guide covering the no-build authoring path and example app, plus a documentation-wide accuracy pass (delegate capture semantics, `effect()` cleanup returns, URL-screen behavior, and more).
 
 ## [1.0.2] - 2026-07-22
 
-
-
 - Fixed the row-selector demo animation 404ing on the published site — the missing SVG capture is now generated and committed.
 
 ## [1.0.1] - 2026-07-22
 
-
-
 - KF-329: pin release-workflow npm upgrade to npm@11 — npm@12 needs Node ≥ 22.22.2, above the 22.21.0 pin (`c54559f`)
 
 ## [1.0.0] - 2026-07-22
 
-
-
 - **Fine-grained signal bindings** — pass a signal or `computed` directly into a JSX attribute or text hole (e.g. `class={computed(...)}` or `{sig}`) inside `mount()`, and that one node updates on signal change without re-running `render()` or walking the list reconciler. Opt-in per hole and non-breaking; works in static content and inside `each()` rows on both the snapshot and `arraySignal` reconcile paths, with binding effects correctly wired, carried, and disposed across row insert/update/remove/move.
 - Bound values get the same safety treatment as static ones: URL screening and `SafeHtml`/`raw()` unwrapping now apply to fine-grained bound attributes.
 - New interactive benchmark playground (`npm run bench:serve`) to explore kerf by hand in the standard 1k-rows benchmark app.
 - New **row-selector** example app and a "Fine-grained bindings" section in the reactivity demo, both showing select-row updates with zero render re-runs and zero list reconciles.
 
-
 - Hardened the dangerous-URL screen: scheme detection now normalizes away C0 control characters, DEL, and leading whitespace, so obfuscations like `java	script:` or a NUL before the colon can no longer slip `javascript:`/`vbscript:` URLs past the check.
 - Attribute names are now validated — malformed names (e.g. from spreading attacker-controlled keys into JSX) throw instead of breaking out of the open tag, and inline `on*` event handlers are rejected on both the static and signal-bound attribute paths, closing an XSS vector where a bound `onclick` would have installed a live handler.
 - Documented kerf's reserved marker namespace (`data-kfb`, `data-kfbrow`, `kfb:`/`kfbr:`/`kf-list:` comments) — consumer content using these can collide with binding wiring, so they're now explicitly reserved.
 - Documented the trusted-input bridges (`toElement()`, `morph()` with string/Element templates, `<iframe srcdoc>`) that bypass escaping by design, and the `raw()`/`SafeHtml` trust boundary.
 - Hardened the release pipeline: least-privilege OIDC scoping per job, SHA-pinned GitHub Actions with automated Dependabot bumps, and a token-holding publish job that runs with `--ignore-scripts` and no build tools.
 
-
 - Reduced the per-row create cost of fine-grained row bindings from ~1.65× to ~1.15× via lazy row wiring — the common single-root-binding case now needs no subtree walk or extra allocations.
 - Published cross-framework benchmark numbers now come from the official upstream krausest js-framework-benchmark run (kerf is a merged upstream entry), replacing stale local-machine measurements.
 
-
 - README refreshed for the 1.0 release: fine-grained updates and safe-by-default escaping promoted to headline features, and the status line flipped from "Pre-1.0 — API may evolve" to stable 1.0.
 - Fine-grained bindings documented across all consumer and AI-assistant surfaces (reactivity docs, API reference, usage guide, Cursor rules, Claude skill).
 
-- **Signposted the raw HTML/SVG → DOM bridges as trusted-input only.** `toElement()`, `morph()` (with a string/Element template), and the `<iframe srcdoc>` attribute bypass kerf's escaping/URL-screening by design — they're the same trust model as `innerHTML` / `raw()`. The docs now call this out loudly, including that the SVG path is *more* dangerous than the HTML path (a top-level `<svg><script>`, SVG event attributes, and `xlink:href="javascript:"` execute once inserted, whereas an HTML-string `<script>` is inert), and that `srcdoc` is HTML a browser re-parses as a document (so `srcdoc={userString}` executes even though the value is escaped as an attribute). No behavior change — these are documentation + regression tests: a real-browser spec (`tests/browser/trusted-html-bridges.spec.ts`) pins the execution boundary across Chromium/Firefox/WebKit, a unit test pins that the granular list fast path keeps the URL screen's guarantee end-to-end, and another pins that SVG input isn't sanitized. See [`docs/7-svg.md`](docs/7-svg.md) § Security, [`docs/8-api-reference.md`](docs/8-api-reference.md), and [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.3.
-- **Documented kerf's reserved marker namespace.** Fine-grained bindings and `each()` lists coordinate through in-band markers that the wiring pass finds by scanning the mounted subtree and matching by id. A consumer element that carries one of those names can collide with a real binding's id and silently steal its update, so the names are now documented as reserved: the `data-kfb` / `data-kfbrow` attributes and HTML comments beginning `kfb:` / `kfbr:` / `kf-list:`. Don't emit them from your own markup or via `raw()`. (kerf's escaping already prevents a plain text/attribute *value* from forging one — the only ways in are hand-written markup or `raw()`.) See [`docs/2-reactivity.md`](docs/2-reactivity.md) § "Reserved marker names".
-- **Attribute names are now validated, and inline event handlers are rejected outright.** The JSX runtime already escaped attribute *values*; it now also validates each attribute *name* against a safe shape (a letter/underscore/colon followed by letters, digits, or `_ . : -`) and **throws** on anything else. This closes a markup-injection vector when an object with attacker-controlled keys is spread into JSX (`<div {...untrustedObj}>`) — previously a key like `'x><img onerror=…>'` broke out of the open tag even though the value was escaped. Separately, any `on*` attribute (a function *or* a string value, in any case — e.g. `onClick={fn}` or `onclick="…"`) now throws and points at `delegate()`; previously only function-valued keys matching `/^on[A-Z]/` were caught, so a string `onclick="alert(1)"` slipped through and became a live inline handler when parsed. Both checks now cover the **fine-grained bound path** too: a signal bound straight into an attribute (`onclick={signal}`) is written with `setAttribute`, and `setAttribute('onclick', …)` installs a live inline handler just as a parsed string would — so an `on*` (or malformed) name bound as a signal is rejected at binding time, closing the same vector on the signal path. See [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.2.
+- **Signposted the raw HTML/SVG → DOM bridges as trusted-input only.** `toElement()`, `morph()` (with a string/Element template), and the `<iframe srcdoc>` attribute bypass kerf's escaping/URL-screening by design — they're the same trust model as `innerHTML` / `raw()`. The docs now call this out loudly, including that the SVG path is _more_ dangerous than the HTML path (a top-level `<svg><script>`, SVG event attributes, and `xlink:href="javascript:"` execute once inserted, whereas an HTML-string `<script>` is inert), and that `srcdoc` is HTML a browser re-parses as a document (so `srcdoc={userString}` executes even though the value is escaped as an attribute). No behavior change — these are documentation + regression tests: a real-browser spec (`tests/browser/trusted-html-bridges.spec.ts`) pins the execution boundary across Chromium/Firefox/WebKit, a unit test pins that the granular list fast path keeps the URL screen's guarantee end-to-end, and another pins that SVG input isn't sanitized. See [`docs/7-svg.md`](docs/7-svg.md) § Security, [`docs/8-api-reference.md`](docs/8-api-reference.md), and [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.3.
+- **Documented kerf's reserved marker namespace.** Fine-grained bindings and `each()` lists coordinate through in-band markers that the wiring pass finds by scanning the mounted subtree and matching by id. A consumer element that carries one of those names can collide with a real binding's id and silently steal its update, so the names are now documented as reserved: the `data-kfb` / `data-kfbrow` attributes and HTML comments beginning `kfb:` / `kfbr:` / `kf-list:`. Don't emit them from your own markup or via `raw()`. (kerf's escaping already prevents a plain text/attribute _value_ from forging one — the only ways in are hand-written markup or `raw()`.) See [`docs/2-reactivity.md`](docs/2-reactivity.md) § "Reserved marker names".
+- **Attribute names are now validated, and inline event handlers are rejected outright.** The JSX runtime already escaped attribute _values_; it now also validates each attribute _name_ against a safe shape (a letter/underscore/colon followed by letters, digits, or `_ . : -`) and **throws** on anything else. This closes a markup-injection vector when an object with attacker-controlled keys is spread into JSX (`<div {...untrustedObj}>`) — previously a key like `'x><img onerror=…>'` broke out of the open tag even though the value was escaped. Separately, any `on*` attribute (a function _or_ a string value, in any case — e.g. `onClick={fn}` or `onclick="…"`) now throws and points at `delegate()`; previously only function-valued keys matching `/^on[A-Z]/` were caught, so a string `onclick="alert(1)"` slipped through and became a live inline handler when parsed. Both checks now cover the **fine-grained bound path** too: a signal bound straight into an attribute (`onclick={signal}`) is written with `setAttribute`, and `setAttribute('onclick', …)` installs a live inline handler just as a parsed string would — so an `on*` (or malformed) name bound as a signal is rejected at binding time, closing the same vector on the signal path. See [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.2.
 - **Hardened the dangerous-URL screen.** The URL-attribute filter (on `href`/`src`/`xlink:href`/`formaction`/`action`) now: (1) sees through control-character and whitespace obfuscation of the scheme — a leading `
`, an in-scheme `TAB`/`LF`/`CR` (`java	script:`), or a `NUL` before the colon are all normalized away before the scheme is read, matching how a browser resolves the URL, so they can no longer slip a `javascript:` past the screen; (2) treats `data:` by subtype instead of only blocking `data:text/html` — script-executing document types (`data:text/html`, `data:image/svg+xml`, XHTML/XML) are dropped while inert media (raster images, fonts, audio, video, plain text/CSS) still pass, and any unknown subtype fails closed; and (3) also screens the `data` attribute on `<object>` (which loads its target as a document). `raw()` remains the opt-out. Both the static serializer and the fine-grained bound-attribute writer share the screen, so both paths are covered.
-- **Fine-grained signal bindings.** Hand a `Signal`/`computed` *itself* (not its `.value`) into a JSX attribute (`class={someSignal}`) or a text hole (`{someSignal}`) inside a `mount()`, and kerf binds that hole directly to the signal: when the signal changes, only that attribute/text node updates — the render function does **not** re-run and the list reconciler does **not** walk. This is kerf's fine-grained update tier, sitting below the coarse `mount()` effect, for the "external state drives one spot" pattern (a `selectedId` flipping a row's class, a live status attribute, etc.). Works in static content and inside `each()` rows on both the snapshot and `arraySignal` (granular) paths, and row bindings' lifetimes track their row node (a row reorder is free; a removed row's binding is torn down). Opt-in and non-breaking: passing a raw signal into JSX previously threw, so existing apps are unchanged, and any hole that isn't a signal stringifies exactly as before. Bound URL attributes (`href`/`src`/`formaction`/`action`/`xlink:href`) get the same `javascript:`/`vbscript:`/`data:text/html` screening as static attributes (`raw()` opts out). Outside a `mount()` (SSR / `SafeHtml.toString()`) a bound signal snapshots its current value and emits no markers. See [`docs/2-reactivity.md`](docs/2-reactivity.md) §2.9.
+- **Fine-grained signal bindings.** Hand a `Signal`/`computed` _itself_ (not its `.value`) into a JSX attribute (`class={someSignal}`) or a text hole (`{someSignal}`) inside a `mount()`, and kerf binds that hole directly to the signal: when the signal changes, only that attribute/text node updates — the render function does **not** re-run and the list reconciler does **not** walk. This is kerf's fine-grained update tier, sitting below the coarse `mount()` effect, for the "external state drives one spot" pattern (a `selectedId` flipping a row's class, a live status attribute, etc.). Works in static content and inside `each()` rows on both the snapshot and `arraySignal` (granular) paths, and row bindings' lifetimes track their row node (a row reorder is free; a removed row's binding is torn down). Opt-in and non-breaking: passing a raw signal into JSX previously threw, so existing apps are unchanged, and any hole that isn't a signal stringifies exactly as before. Bound URL attributes (`href`/`src`/`formaction`/`action`/`xlink:href`) get the same `javascript:`/`vbscript:`/`data:text/html` screening as static attributes (`raw()` opts out). Outside a `mount()` (SSR / `SafeHtml.toString()`) a bound signal snapshots its current value and emits no markers. See [`docs/2-reactivity.md`](docs/2-reactivity.md) §2.9.
 
 ## [0.16.0] - 2026-07-01
 
-
-
 - Fixed keyed-list selection breaking after a row was removed: a signal read only inside `each()`'s `cacheKey` (such as a `selectedId` toggling a row's class) no longer drops out of the reactive dependency set, so later changes re-render correctly.
 - Fixed appending items to a list after clearing it rendering nothing.
 
@@ -419,115 +2828,90 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [0.15.5] - 2026-06-30
 
-
-
 - Corrected the advertised bundle size in `llms.txt` to ~11 KB minified + gzipped (including the `@preact/signals-core` runtime dependency; ~12 KB with `arraySignal`), matching the README.
 
 ## [0.15.4] - 2026-06-30
 
-
-
 - `llms.txt` is now published at a public docs-site URL and bundled in the npm package, making kerf's AI-assistant documentation index discoverable to llms.txt directories and tooling.
 
 - The `kerfjs` package now bundles `llms.txt` (the AI-discovery index) at the package root, and the docs site serves it at `https://brianwestphal.github.io/kerf/llms.txt`. Its links are now absolute GitHub URLs so the file is portable across GitHub, the site, and the installed package.
 
 ## [0.15.3] - 2026-06-30
 
-
-
 - `npm create kerf-component` with no directory argument now prompts for the target directory (defaulting to `my-kerf-component`, with a `.` hint for the current directory) instead of printing usage text and exiting with an error.
 
 ## [0.15.2] - 2026-06-30
 
-
-
 - Added the `create-kerf-component` initializer — scaffold a ready-to-publish kerf component package with `npm create kerf-component@latest <dir>`, no need to reverse-engineer the packaging rules.
 
 ## [0.15.1] - 2026-06-30
 
-
-
 - README refresh + eslint rule-count fixes + CHANGELOG hygiene (`cfbaef3`)
 
 ## [0.15.0] - 2026-06-30
 
-
-
 - List updates now morph same-identity rows in place instead of recreating their DOM nodes, avoiding full-table relayout on large lists and preserving DOM identity, focus, and IME composition across re-renders.
 
-
 - New guide on incremental migration: kerf can own a single DOM subtree and coexist with React (or any framework), letting you migrate one island at a time.
 - New guide on building and publishing reusable kerf components as npm packages.
 - Example app documentation pages now open with an animated SVG preview of the real app in action, plus a gallery on the complete-examples index.
 
 ## [0.14.0] - 2026-05-27
 
-
 - Fix `toElement()` first-paint divergence in WebKit by adopting its result into the live document
 - Fix `mount()` first render in WebKit by adopting an inert `rootEl` into the live document
 
 ## [0.13.0] - 2026-05-23
 
-
 - Add `KERF_DEV_WARN_DELEGATE_IN_EFFECT` dev warning to catch `delegate()` calls inside reactive effects
 - New `require-delegate-disposer` ESLint rule flags `delegate()` calls whose disposer is discarded
 - Document `delegate()` disposer gotchas and canonical cleanup patterns
 
 ## [0.12.1] - 2026-05-22
 
-
 - Add GitHub Sponsors link to README, homepage, and npm `funding` field
 
 ## [0.12.0] - 2026-05-22
 
-
 - `toElement` now returns `Element | DocumentFragment` to support multi-root inputs
 
 ## [0.11.1] - 2026-05-21
 
-
 - `attr()` redesign: typed `AttrSpec<N, V>` exposes `.attrs` with dual overloads for cleaner attribute handling
 
 ## [0.11.0] - 2026-05-21
 
-
 - `attr()` redesigned with `AttrSpec<N,V>` shape, `.attrs` accessor, and dual overloads
 - Hardened defensive programming across the runtime for safer edge-case handling
 - Refreshed published performance numbers from a fresh cross-framework benchmark run
 
 ## [0.10.0] - 2026-05-20
 
-
 - Expose `kerfjs/ai/*` subpaths via package `exports` so the bundled skill/cursorrules files are resolvable
 - Add a defensive fallback in `kerfjs/ai-assistant-configs` ESLint rule so it fires against installed kerfjs versions whose `exports` block subpath resolution
 
 ## [0.9.1] - 2026-05-20
 
-
 - Bundle the kerf-app Claude Code skill and Cursor rules inside the npm package at `ai/skill.md`, `ai/cursorrules`, and `ai/manifest.json`
 - Add `kerfjs/ai-assistant-configs` rule to `eslint-plugin-kerfjs` (warn in recommended) to flag drift in installed AI assistant configs
 - `eslint --fix` now replaces only the canonical section above the `KERF-APP-CANONICAL-END` marker, preserving consumer customizations below it
 
 ## [0.9.0] - 2026-05-20
 
-
 - Bundle the kerf-app Claude Code skill and Cursor rules inside the npm package at `ai/skill.md`, `ai/cursorrules`, and `ai/manifest.json`
 - Add `kerfjs/ai-assistant-configs` rule (warn in recommended) to `eslint-plugin-kerfjs` v0.9.0 to surface AI-config drift on every lint pass
 - Canonical-file contract (`kerf-skill-version` + `KERF-APP-CANONICAL-END` marker) lets `eslint --fix` refresh the canonical section while preserving consumer customizations below the marker
 
 ## [0.8.2] - 2026-05-19
 
-
 - Package `homepage` fields now point to the published docs site, with prominent links in both READMEs
 
 ## [0.8.1] - 2026-05-19
 
-
 - New `eslint-plugin-kerfjs` with four AST rules enforcing kerf Hard Rules
 
 ## [0.8.0] - 2026-05-18
 
-
 - Add opt-in dev warning `KERF_DEV_WARN_NARROW_SET=1` that fires when `set()` is called with a partial-state object (replace semantics would silently drop missing keys); names the missing keys and points at the `set({ ...get(), ...next })` merge fix
 - Widen `KerfBaseAttrs.contentEditable` to accept `'plaintext-only'` and add the lowercase `contenteditable` alias
 - Expand the `/kerf/migrating/` hub to 13 frameworks — adds Vue 3, Svelte 5, Solid, Preact, htmx, Angular, jQuery, Redux, and Astro pages alongside a refreshed 8-framework comparison matrix
@@ -538,7 +2922,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [0.7.0] - 2026-05-18
 
-
 - Granular list updates now preserve DOM identity, focus, scroll, IME state, `<details open>`/`<dialog open>`, and `data-morph-skip` subtrees across in-place row updates
 - Two new fast paths in the granular reconciler cut krausest select-row by 71% (27.8 → 8.2 ms) and partial-update by 28% (46.8 → 33.8 ms)
 - `each()`'s third parameter renamed from `key` to `cacheKey` to clarify it's a passive cache-invalidation comparator, not a React-style reconciliation identity; positional callers unaffected
@@ -554,7 +2937,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [0.6.0] - 2026-05-11
 
-
 - Public `morph(liveRoot, template)` export for standalone DOM reconciliation
 - New `data-morph-preserve` attribute to opt elements out of morphing
 - New `data-morph-skip-children` attribute — morph host attrs but leave subtree intact
@@ -563,12 +2945,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [0.5.1] - 2026-05-11
 
-
 - Fix `dist/jsx-runtime.d.ts` IntrinsicElements self-shadow that broke JSX typing in consumer apps
 
 ## [0.5.0] - 2026-05-10
 
-
 - Add `arraySignal` (`kerfjs/array-signal` subpath) — granular collection signal that drives O(patches) DOM updates for keyed lists
 - Faster keyed-list updates: bulk-parse contiguous insert runs and consecutive update patches in the granular reconcile path
 - Perf optimizations on the `each()` / `mount()` update path; benchmarks now competitive with Solid/Vue on swap/remove/clear
@@ -582,17 +2962,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [0.4.2] - 2026-05-09
 
-
 - No user-facing changes in this release.
 
 ## [0.4.1] - 2026-05-09
 
-
 - Just fixing the build
 
 ## [0.4.0] - 2026-05-09
 
-
 - `delegate()` now auto-promotes the seven well-known non-bubbling events (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`, `mouseleave`) to capture phase, with `closest()`-style selector matching preserved
 - Fixed focus and caret position loss when reordering keyed `each()` rows on engines that drop focus on `insertBefore` (older Safari, happy-dom)
 - `mount()` now throws a descriptive error when the root element is null/undefined instead of a generic "Cannot set properties of null"
@@ -603,12 +2980,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [0.3.1] - 2026-05-08
 
-
 - Removed stale `morphdom` references; the bundled native diff is now the only reconciler
 
 ## [0.3.0] - 2026-05-08
 
-
 - Rebuilt render pipeline with structured segments and a native keyed-list diff, replacing the morphdom dependency
 - Added `each()` for keyed list iteration with per-item HTML memoization by object identity
 - Renamed the npm package from `kerf` to `kerfjs` (the `kerf` name tripped npm's typo-squatting heuristic); the brand, GitHub repo, and Pages URL are unchanged
@@ -619,24 +2994,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [0.2.1] - 2026-05-07
 
-
 - Add `Fragment` export to the `kerfjs` barrel for explicit JSX fragment usage
 
 ## [0.2.0] - 2026-05-07
 
-
 - Fix focused contenteditable losing focus/caret during morph
 - Fix `SafeHtml` identity mismatch across entry points caused by dist bundling
 - Fix `clearStoreRegistry` no-op in built output, restoring test isolation
 
 ## [0.1.2] - 2026-05-07
 
-
 - No user-facing changes; release tooling fixes only.
 
 ## [0.1.1] - 2026-05-07
 
-
 - This is just a publication script test
 
 ## [0.1.0] - 2026-05-07