kerfjs 5.0.0-beta.56 → 5.0.0-beta.58

package/CHANGELOG.md

@@ -6,6 +6,338 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [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
@@ -2135,6 +2467,8 @@ font="monospace"` and Web Awesome code text match.
 - 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.
 
+- @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.

package/README.md

@@ -12,14 +12,14 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/kerfjs"><img src="https://img.shields.io/npm/v/kerfjs.svg" alt="npm version" /></a>
-  <img src="https://img.shields.io/badge/min%2Bgzip-~12%20KB-brightgreen.svg" alt="~12 KB minified and gzipped" />
+  <img src="https://img.shields.io/badge/min%2Bgzip-~13%20KB-brightgreen.svg" alt="~13 KB minified and gzipped" />
   <img src="https://img.shields.io/npm/l/kerfjs.svg" alt="MIT license" />
   <img src="https://img.shields.io/badge/types-included-3178c6.svg" alt="TypeScript types included" />
 </p>
 
 ---
 
-> ~12 KB. No virtual DOM. No compiler. No magic.
+> ~13 KB. No virtual DOM. No compiler. No magic.
 > Reactive UI that touches only the bytes that changed.
 
 ```ts
@@ -76,7 +76,7 @@ Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no ext
 
 ## Why Kerf
 
-1. **~12 KB, one dependency.** ~12 KB minified + gzipped including `@preact/signals-core` (~13 KB with `arraySignal`). No virtual DOM, no scheduler, no concurrent-mode machinery. On the official [krausest benchmark](https://krausest.github.io/js-framework-benchmark/current.html) kerf sits in the same cluster as Vue, Lit, and vanjs; Solid's compiler leads the update-path benchmarks, which kerf doesn't try to match by design — no compiler.
+1. **~13 KB in the browser.** ~13 KB minified + gzipped including `@preact/signals-core` (~13 KB with `arraySignal`). The optional setup CLI has its own npm dependencies; they stay out of the browser bundle. No virtual DOM, no scheduler, no concurrent-mode machinery. On the official [krausest benchmark](https://krausest.github.io/js-framework-benchmark/current.html) kerf sits in the same cluster as Vue, Lit, and vanjs; Solid's compiler leads the update-path benchmarks, which kerf doesn't try to match by design — no compiler.
 
 2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it _is_ the DOM.
 
@@ -88,7 +88,7 @@ Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no ext
 
 6. **Safe by default.** Text and attributes are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` dropped), and inline `on*` handlers are rejected outright — so untrusted data stays inert. `raw()` is the explicit, auditable opt-out.
 
-**Plus, nothing you don't ask for:** JSX typed against the HTML standard (not React's props) · a ~18-export API with no hooks, lifecycle, or per-instance state · **nine** tree-shakeable companion subpaths (`router`, `list`, `overlay`, `async`, …) that stay out of the core until imported · an [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) + opt-in dev warnings + `create-kerf-component` scaffold · plain TS/JSX/ESM that drops into esbuild / Vite / tsup — or **no** build at all via the `html` tagged template.
+**Plus, nothing you don't ask for:** JSX typed against the HTML standard (not React's props) · a small public API with no hooks, lifecycle, or per-instance state · tree-shakeable companion subpaths (`router`, `list`, `overlay`, `async`, …) that stay out of the core until imported · an [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) + opt-in dev warnings + `create-kerf-component` scaffold · plain TS/JSX/ESM that drops into esbuild / Vite / tsup — or **no** build at all via the `html` tagged template.
 
 ## When to use Kerf
 
@@ -223,8 +223,8 @@ Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip
 
 ```html
 <script type="module">
-  import { signal, mount, each } from "https://esm.sh/kerfjs@4";
-  import { html } from "https://esm.sh/kerfjs@4/html";
+  import { signal, mount, each } from "https://esm.sh/kerfjs@5";
+  import { html } from "https://esm.sh/kerfjs@5/html";
 
   const items = signal([{ id: 1, label: "no build step" }]);
 
@@ -239,7 +239,7 @@ Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip
 </script>
 ```
 
-Nothing is self-hosted — `kerfjs` is on npm, so every ESM CDN (esm.sh, jsDelivr, unpkg) mirrors it automatically. esm.sh works with a direct import as shown; jsDelivr / unpkg want an importmap so the internal `@preact/signals-core` import resolves. Pin to a major (`@4`, as shown — the latest `4.x`) rather than floating on `latest`, or an exact version (`@4.1.0`) for full reproducibility. Attribute names are written verbatim (`class`, not `className`), and holes are only legal in text positions or as a complete attribute value — anything ambiguous throws with an actionable message. See [`docs/6-jsx-runtime.md`](./docs/6-jsx-runtime.md) §6.11 (§6.11.1 for the full CDN / importmap recipes) — or the [live-poll example](https://brianwestphal.github.io/kerf/examples/complete/live-poll/), a complete app served exactly as authored: no bundler ever touches it.
+Nothing is self-hosted — `kerfjs` is on npm, so every ESM CDN (esm.sh, jsDelivr, unpkg) mirrors it automatically. esm.sh works with a direct import as shown; jsDelivr / unpkg want an importmap so the internal `@preact/signals-core` import resolves. Pin to a major (`@5`, as shown) rather than floating on `latest`, or an exact version (`@5.0.0`) for full reproducibility. Attribute names are written verbatim (`class`, not `className`), and holes are only legal in text positions or as a complete attribute value — anything ambiguous throws with an actionable message. See [`docs/6-jsx-runtime.md`](./docs/6-jsx-runtime.md) §6.11 (§6.11.1 for the full CDN / importmap recipes) — or the [live-poll example](https://brianwestphal.github.io/kerf/examples/complete/live-poll/), a complete app served exactly as authored: no bundler ever touches it.
 
 ### Batteries when you need them: the companion subpaths
 
@@ -322,7 +322,7 @@ Install and JSX setup are in [Quick start](#quick-start) above. These companion
 
 ### Optional: `eslint-plugin-kerfjs`
 
-A companion ESLint plugin enforces kerf's hard rules at edit time. Eight rules total: four `error`-level AST rules catch hard-rule violations — inline JSX event handlers, missing `data-key` in `each()`, nested `mount()`, and global `JSX.IntrinsicElements` augmentation — and four `warn`-level rules cover delegate-disposer capture, `attr()` selector rename-safety, `raw()` XSS audit trails, and AI-assistant config hygiene. The plugin is AST-only (no parser-services dependency), so it works with any TypeScript-ESLint setup.
+A companion ESLint plugin enforces kerf's hard rules at edit time. Its eight core rules cover inline JSX event handlers, missing `data-key` in `each()`, nested `mount()`, delegate-disposer capture, `attr()` selector rename-safety, `raw()` XSS audit trails, JSX augmentation, and AI-assistant config hygiene. Six additional UI rules check component ownership, composition, CSS values, application preferences, wiring, and public boundaries when you opt into the UI preset. The plugin requires no TypeScript parser service.
 
 ```bash
 npm install --save-dev eslint-plugin-kerfjs
@@ -334,7 +334,7 @@ import kerfjs from "eslint-plugin-kerfjs";
 export default [kerfjs.configs.recommended];
 ```
 
-Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — legacy `.eslintrc` config, per-rule examples, and the rationale for which violations get lint rules vs. dev-warns vs. strict TS.
+Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — flat config, per-rule examples, and the rationale for which violations get lint rules vs. dev-warns vs. strict TS.
 
 ### Optional: `create-kerf-component`
 
@@ -353,7 +353,7 @@ See [`docs/13-component-packages.md`](./docs/13-component-packages.md) for the f
 - **Migrating:** [coming from another framework?](https://brianwestphal.github.io/kerf/migrating/) — side-by-side TodoMVC translations + per-framework gotchas
 - **AI guide:** [`docs/ai/usage-guide.md`](./docs/ai/usage-guide.md) — reference for AI tools fetching kerf docs (linked from `llms.txt`)
 - **UI package:** [`@kerfjs/ui`](./ui/README.md) — accessible components, responsive app layouts, typed CSS values, Web Awesome adapters, and checked AI-facing component metadata
-- **ESLint plugin:** [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — `eslint-plugin-kerfjs`; eight rules (four hard-rule errors + four warns: `require-delegate-disposer`, `prefer-attr-selector`, `no-raw-with-dynamic-arg`, `ai-assistant-configs`) at edit time (source: [`eslint-plugin/`](./eslint-plugin/))
+- **ESLint plugin:** [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — `eslint-plugin-kerfjs`; eight core rules plus six opt-in UI rules at edit time (source: [`eslint-plugin/`](./eslint-plugin/))
 - **Component scaffold:** `npm create kerf-component@latest <dir>` — `create-kerf-component`; generates a publishable component package with packaging rules plus deterministic, drift-checked AI metadata pre-wired (source: [`create-kerf-component/`](./create-kerf-component/))
 - **Demo:** [live demo](https://brianwestphal.github.io/kerf/demo/) — nine sections exercising every primitive (counter, store-backed cart, focus survival, keyed list, morph-skip, SVG render, Tier-2 capture, `arraySignal` patches, fine-grained signal bindings)
 - **Repo:** [github.com/brianwestphal/kerf](https://github.com/brianwestphal/kerf)

package/ai/cursorrules

@@ -1,4 +1,4 @@
-<!-- kerf-skill-version: 1.22.0 -->
+<!-- kerf-skill-version: 1.23.0 -->
 
 # kerf.cursorrules — rules for building apps with kerf
 
@@ -10,7 +10,7 @@
 
 # These rules condense `docs/ai/usage-guide.md` into the form Cursor parses.
 
-You are writing a UI in kerf — a ~12 KB reactive framework (~13 KB with `arraySignal`): signals + DOM morphing + JSX → HTML strings. No virtual DOM, no compiler, no scheduler.
+You are writing a UI in kerf — a ~13 KB reactive framework (still ~13 KB with `arraySignal`): signals + DOM morphing + JSX → HTML strings. No virtual DOM, no compiler, no scheduler.
 
 ## Setup
 
@@ -33,13 +33,13 @@ the complete layer is intentional. Reuse these primitives before creating
 parallel local ones; keep domain state, commands, routing, and tab/menu policy
 in the app.
 
-Use MenuItem/MenuActionRow/MenuHeader `rootAttributes` only for application
-`data-*` metadata. MenuActionRow `trailingActionAttributes` and MenuHeader
+Use ListItem/ListActionRow/ListHeader `rootAttributes` only for application
+`data-*` metadata. ListActionRow `trailingActionAttributes` and ListHeader
 `triggerAttributes` additionally support native popover target/action and
 `aria-controls`/`aria-haspopup`. Do not use these slots to override action,
 item identity, selection, disclosure, naming, disabled, icon, or role
 semantics; one `role="menuitem"` does not make a complete menu widget.
-`MenuItem.trailing` is dormant. Use `MenuActionRow` for sibling primary and
+`ListItem.trailing` is dormant. Use `ListActionRow` for sibling primary and
 trailing native buttons, and keep its `label`, `icon`, and
 `trailingActionIcon` SafeHtml slots free of controls.
 
@@ -48,13 +48,22 @@ Wire emitted `data-action` hooks at the mount root and retain disposers.
 disposers. Compose `AppTab` inside controlled `TabBar`; `wireTabBars()` supplies
 horizontal edge autoscroll while dragging. Apply reorder reports
 with `reorderTabs()`, and keep order, selection, close policy, routing, panels,
-and persistence in the host. Icons/spinners are decorative unless
+and persistence in the host. Toolbars draw no divider by default; call
+`wireScrollDividers()` once at the app root so panes and tab bars show scroll
+dividers only while content is scrolled beneath or beyond them. Icons/spinners are decorative unless
 labeled, and assertive banners are only for urgent interruption.
 
-The opinionated semantic ramps match Hot Sheet 2 and Web Awesome. Override
-`--kui-color-*` globally or component properties such as
-`--kui-state-banner-background` at a tone or instance boundary; do not replace
-private descendant selectors.
+Components own their styles; configure, never override. Set how a component
+looks and sits through its typed props (size, density, inset, presentation,
+`dividerSides`, `ToolbarConfig`, `PaneConfig`, …); never write application
+CSS that selects a `.kui-*` class, a `[data-component]` root, a `wa-*` element
+a Kerf component renders, or its `::part()`s, and never add padding, margin,
+width, or height around a component to size or space it (it owns its 8px
+inset — adding more double-insets). A missing prop is a component gap to
+report upstream, not a reason to override. The opinionated semantic ramps
+match Hot Sheet 2 and Web Awesome: override `--kui-color-*` globally or
+component properties such as `--kui-state-banner-background` at a tone or
+instance boundary, for theming only.
 
 For Web Awesome's broader free component set, import the CSS-only
 `@kerfjs/ui/webawesome.css` theme once, then import only each Web Awesome

package/ai/manifest.json

@@ -1,13 +1,13 @@
 {
-  "kerfjsVersion": "5.0.0-beta.56",
+  "kerfjsVersion": "5.0.0-beta.58",
   "files": [
     {
       "name": "skill",
       "source": "kerf.claude-skill.md",
       "bundle": "ai/skill.md",
       "dest": ".claude/skills/kerf-app/SKILL.md",
-      "version": "1.24.0",
-      "sha256": "f74616ec20120fa97ec2ff7e92971f5721ee8dcb0b5b7da2dd2604bb87002b69",
+      "version": "1.25.0",
+      "sha256": "4bc2b292bd707639c13b8cafe3fb24f779bfea04ab38fd6a5d40c443eed89c9d",
       "history": {
         "1.0.0": "bef982cb743fd4c73e666ee5cf774112e57c93ebb13b24bbacbf08577db0930a",
         "1.1.0": "f2aadb21e33dd389028951ae1ecbd9f8ba68648b3c5beba43fb4dfa2ab29f195",
@@ -39,7 +39,8 @@
         "1.22.0": "dc99b0ca5e911be11cbfa2ae515c0e161a414a5185895069535c41ba56664e70",
         "1.23.0": "28b82b4d31b98814c8fbbe1cb0bcf716192deb494c020b9af41a30830e6a0007",
         "1.23.1": "e21d7db1097ad95c11af9248ad17d514716bebc5646becf57d19a7598d6e382c",
-        "1.24.0": "f74616ec20120fa97ec2ff7e92971f5721ee8dcb0b5b7da2dd2604bb87002b69"
+        "1.24.0": "f74616ec20120fa97ec2ff7e92971f5721ee8dcb0b5b7da2dd2604bb87002b69",
+        "1.25.0": "4bc2b292bd707639c13b8cafe3fb24f779bfea04ab38fd6a5d40c443eed89c9d"
       }
     },
     {
@@ -47,8 +48,8 @@
       "source": "kerf.cursorrules",
       "bundle": "ai/cursorrules",
       "dest": ".cursorrules",
-      "version": "1.22.0",
-      "sha256": "3515c663e908b2d6dc9a2a9cf42f2a5bf9a5b3a10c79d43e30cc8427e2ce209d",
+      "version": "1.23.0",
+      "sha256": "908e6622f597108ca696c8ff6f1081b3d83996dc46771a3515b184884dab4b25",
       "history": {
         "1.0.0": "98f7faff2b7585ef9cc511add42ea5d9bf0cbae8307b066af090e9281136d2ab",
         "1.1.0": "a2ec8c221dc694c98b81009cd2d99f9159a45fda94585de2f54471b227099eda",
@@ -78,7 +79,8 @@
         "1.20.0": "5e7b8d8ddc41f60220961417c9ae01c193fae045378a10a3e9c96a0e3cf10a03",
         "1.21.0": "a1b663b44650b1a04f89c60b26b002322fc6789650291477e14e13329c3ce25f",
         "1.21.1": "9b3eb825a7bec05bb6f0138f77b45fadf896b83020178c34c5a2f531c38f4dee",
-        "1.22.0": "3515c663e908b2d6dc9a2a9cf42f2a5bf9a5b3a10c79d43e30cc8427e2ce209d"
+        "1.22.0": "3515c663e908b2d6dc9a2a9cf42f2a5bf9a5b3a10c79d43e30cc8427e2ce209d",
+        "1.23.0": "908e6622f597108ca696c8ff6f1081b3d83996dc46771a3515b184884dab4b25"
       }
     }
   ]

package/ai/skill.md

@@ -1,7 +1,7 @@
 ---
 name: kerf-app
 description: Build UIs in the kerf reactive framework and its @kerfjs/ui component package (https://github.com/brianwestphal/kerf). Use this skill whenever the user is writing or modifying code that imports `kerfjs` or `@kerfjs/ui`, asks to add a feature to a kerf app, or asks "how do I do X in kerf?". Use it proactively the moment you spot a kerf import in the file you're editing.
-kerf-skill-version: 1.24.0
+kerf-skill-version: 1.25.0
 ---
 
 # Building apps with kerf
@@ -10,7 +10,7 @@ kerf-skill-version: 1.24.0
 > project's `.claude/skills/kerf-app/SKILL.md`) so Claude Code activates
 > it whenever you work on a kerf app.
 
-kerf is a ~12 KB reactive UI framework (~13 KB with `arraySignal`): signals + DOM morphing + JSX → HTML strings. No virtual DOM, no compiler, no scheduler. The whole public surface fits in 17 exports.
+kerf is a ~13 KB reactive UI framework (still ~13 KB with `arraySignal`): signals + DOM morphing + JSX → HTML strings. No virtual DOM, no compiler, no scheduler. The whole public surface fits in 17 exports.
 
 ## Setup
 
@@ -53,13 +53,23 @@ explicit behavioral helpers and return disposers. Compose `AppTab` inside a
 controlled `TabBar`; `wireTabBars()` supplies horizontal edge autoscroll during
 dragging. Apply reorder reports with `reorderTabs()`, and keep order,
 selection, close policy, routing, panels, and persistence in the host.
+Toolbars draw no divider by default: call `wireScrollDividers()` once at the
+app root so each `Pane` draws its header/footer divider, and each `TabBar` its
+overflow divider, only while content is scrolled beneath or beyond it.
 Icons and spinners are decorative unless labeled; use assertive banners only
 for urgent interruption.
 
-The opinionated semantic ramps match Hot Sheet 2 and Web Awesome. Override
-`--kui-color-*` globally or component properties such as
-`--kui-state-banner-background` at a tone or instance boundary; do not replace
-private descendant selectors.
+Components own their styles; configure, never override. Set how a component
+looks and sits through its typed props (size, density, inset, presentation,
+`dividerSides`, `ToolbarConfig`, `PaneConfig`, …); never write application
+CSS that selects a `.kui-*` class, a `[data-component]` root, a `wa-*` element
+a Kerf component renders, or its `::part()`s, and never add padding, margin,
+width, or height around a component to size or space it (it owns its 8px
+inset — adding more double-insets). A missing prop is a component gap to
+report upstream, not a reason to override. The opinionated semantic ramps
+match Hot Sheet 2 and Web Awesome: override `--kui-color-*` globally or
+component properties such as `--kui-state-banner-background` at a tone or
+instance boundary, for theming only.
 
 For Web Awesome's broader free component set, import the CSS-only
 `@kerfjs/ui/webawesome.css` theme once, then import only each Web Awesome

package/dist/actions.d.ts

@@ -1,5 +1,5 @@
 import { A as AttrSpec } from './attr-Cmu2ZoGO.js';
-import { D as DelegateOptions } from './delegate-CL9VTZFb.js';
+import { D as DelegateOptions } from './delegate--CrfgYtC.js';
 
 /**
  * `kerfjs/actions` — the delegated action-table helper.

package/dist/actions.js

@@ -1,5 +1,5 @@
 import { attr } from './chunk-MK42GLPV.js';
-import { delegate } from './chunk-X6OQ2HTR.js';
+import { _delegate, NON_BUBBLING } from './chunk-JN7EJM3B.js';
 
 
 // src/actions.ts
@@ -9,15 +9,19 @@ function action(value) {
 }
 function delegateActions(root, eventType, table, options) {
   const attrName = options?.attr ?? DEFAULT_ACTION_ATTR;
-  return delegate(
+  return _delegate(
     root,
     eventType,
     `[${attrName}]`,
     (event, el) => {
       const value = el.getAttribute(attrName);
-      if (Object.hasOwn(table, value)) table[value](event, el);
+      return () => {
+        if (Object.hasOwn(table, value)) table[value](event, el);
+      };
     },
-    options
+    options,
+    NON_BUBBLING.has(eventType),
+    "delegate"
   );
 }
 

package/dist/actions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/actions.ts"],"names":[],"mappings":";;;;;AAmCA,IAAM,mBAAA,GAAsB,aAAA;AAkBrB,SAAS,OAAyB,KAAA,EAAsC;AAC7E,EAAA,OAAO,IAAA,CAAK,qBAAqB,KAAK,CAAA;AACxC;AAwBO,SAAS,eAAA,CACd,IAAA,EACA,SAAA,EACA,KAAA,EACA,OAAA,EACY;AACZ,EAAA,MAAM,QAAA,GAAW,SAAS,IAAA,IAAQ,mBAAA;AAClC,EAAA,OAAO,QAAA;AAAA,IACL,IAAA;AAAA,IACA,SAAA;AAAA,IACA,IAAI,QAAQ,CAAA,CAAA,CAAA;AAAA,IACZ,CAAC,OAAO,EAAA,KAAO;AAEb,MAAA,MAAM,KAAA,GAAQ,EAAA,CAAG,YAAA,CAAa,QAAQ,CAAA;AAKtC,MAAA,IAAI,MAAA,CAAO,OAAO,KAAA,EAAO,KAAK,GAAG,KAAA,CAAM,KAAK,CAAA,CAAE,KAAA,EAAO,EAAE,CAAA;AAAA,IACzD,CAAA;AAAA,IACA;AAAA,GACF;AACF","file":"actions.js","sourcesContent":["/**\n * `kerfjs/actions` — the delegated action-table helper.\n *\n * The most-reinvented idiom across real kerf apps: one table of `data-action`\n * attribute specs used as the single source of truth for BOTH the JSX attribute\n * and the delegate selector, plus a hand-rolled `switch (dataset.action)`\n * dispatcher. This subpath blesses it as two thin helpers over the existing\n * `attr()` + `delegate()` — it does NOT replace them.\n *\n *   import { action, delegateActions } from 'kerfjs/actions';\n *\n *   const A = {\n *     select: action('select-file'),\n *     remove: action('remove-file'),\n *   };\n *\n *   // JSX — spread the attr (rename-safe; no hardcoded attribute name):\n *   //   <button {...A.select.attrs} data-id={id}>…</button>\n *\n *   // Wire the whole table with ONE delegated listener; returns a disposer:\n *   const dispose = delegateActions(root, 'click', {\n *     [A.select.value]: (_e, el) => selectFile(el.getAttribute('data-id')),\n *     [A.remove.value]: (_e, el) => removeFile(el.getAttribute('data-id')),\n *   });\n *\n * Contract: `delegateActions` returns a `() => void` disposer and holds no\n * per-instance state — the same shape as `delegate()`, which it builds on (so\n * it inherits the single-listener dispatch and the capture auto-promotion for\n * well-known non-bubbling event types). One event type per call, mirroring\n * `delegate()`; collect the disposers for a root that needs several.\n */\nimport { attr, type AttrSpec } from './attr.js';\nimport { delegate, type DelegateOptions } from './delegate.js';\n\n/** The attribute an action table keys on by default. */\nconst DEFAULT_ACTION_ATTR = 'data-action';\n\n/**\n * A handler in a {@link delegateActions} table. Receives the DOM event and the\n * matched element (walk-up `closest()` match by default) — the same shape as a\n * `delegate()` handler.\n */\nexport type ActionHandler<E extends Element = Element> = (\n  event: Event,\n  el: E,\n) => void;\n\n/**\n * `action(value)` — an {@link AttrSpec} on `data-action`. A thin specialization\n * of `attr('data-action', value)`: spread its `.attrs` in JSX and use its\n * `.value` as the handler-table key, so the action name lives in exactly one\n * place and can't drift between the markup and the dispatcher.\n */\nexport function action<V extends string>(value: V): AttrSpec<'data-action', V> {\n  return attr(DEFAULT_ACTION_ATTR, value);\n}\n\n/** Options for {@link delegateActions}. Extends {@link DelegateOptions}. */\nexport interface DelegateActionsOptions extends DelegateOptions {\n  /**\n   * The attribute the table keys on. Default `'data-action'`. Override it only\n   * if you also author the specs with `attr(yourName, …)` instead of `action()`.\n   */\n  attr?: string;\n}\n\n/**\n * Wire a whole table of action handlers with ONE delegated listener.\n *\n * On `eventType`, the nearest element carrying the action attribute (walk-up\n * `closest()` by default; pass `{ match: 'direct' }` for an exact-element match)\n * is looked up in `table` by its attribute value, and the matching handler\n * runs. An element whose action is absent from the table is ignored — the same\n * behavior as a `switch (dataset.action)` with no matching `case`.\n *\n * Returns a `() => void` disposer. One event type per call (the smallest\n * surface, mirroring `delegate()`); collect the disposers when a root needs\n * several event types.\n */\nexport function delegateActions<E extends Element = Element>(\n  root: HTMLElement,\n  eventType: string,\n  table: Readonly<Record<string, ActionHandler<E>>>,\n  options?: DelegateActionsOptions,\n): () => void {\n  const attrName = options?.attr ?? DEFAULT_ACTION_ATTR;\n  return delegate<E>(\n    root,\n    eventType,\n    `[${attrName}]`,\n    (event, el) => {\n      // `el` matched `[${attrName}]`, so the attribute is always present.\n      const value = el.getAttribute(attrName) as string;\n      // Own entries only: the table is an ordinary object, so a bare\n      // `table[value]` would resolve Object.prototype names (`__proto__`,\n      // `constructor`, `toString`, `hasOwnProperty`, …) and dispatch or throw\n      // on markup that names no action in the table.\n      if (Object.hasOwn(table, value)) table[value](event, el);\n    },\n    options,\n  );\n}\n"]}
+{"version":3,"sources":["../src/actions.ts"],"names":[],"mappings":";;;;;AAmCA,IAAM,mBAAA,GAAsB,aAAA;AAkBrB,SAAS,OAAyB,KAAA,EAAsC;AAC7E,EAAA,OAAO,IAAA,CAAK,qBAAqB,KAAK,CAAA;AACxC;AAwBO,SAAS,eAAA,CACd,IAAA,EACA,SAAA,EACA,KAAA,EACA,OAAA,EACY;AACZ,EAAA,MAAM,QAAA,GAAW,SAAS,IAAA,IAAQ,mBAAA;AAKlC,EAAA,OAAO,SAAA;AAAA,IACL,IAAA;AAAA,IACA,SAAA;AAAA,IACA,IAAI,QAAQ,CAAA,CAAA,CAAA;AAAA,IACZ,CAAC,OAAO,EAAA,KAAO;AAEb,MAAA,MAAM,KAAA,GAAQ,EAAA,CAAG,YAAA,CAAa,QAAQ,CAAA;AAKtC,MAAA,OAAO,MAAM;AACX,QAAA,IAAI,MAAA,CAAO,OAAO,KAAA,EAAO,KAAK,GAAG,KAAA,CAAM,KAAK,CAAA,CAAE,KAAA,EAAO,EAAO,CAAA;AAAA,MAC9D,CAAA;AAAA,IACF,CAAA;AAAA,IACA,OAAA;AAAA,IACA,YAAA,CAAa,IAAI,SAAS,CAAA;AAAA,IAC1B;AAAA,GACF;AACF","file":"actions.js","sourcesContent":["/**\n * `kerfjs/actions` — the delegated action-table helper.\n *\n * The most-reinvented idiom across real kerf apps: one table of `data-action`\n * attribute specs used as the single source of truth for BOTH the JSX attribute\n * and the delegate selector, plus a hand-rolled `switch (dataset.action)`\n * dispatcher. This subpath blesses it as two thin helpers over the existing\n * `attr()` + `delegate()` — it does NOT replace them.\n *\n *   import { action, delegateActions } from 'kerfjs/actions';\n *\n *   const A = {\n *     select: action('select-file'),\n *     remove: action('remove-file'),\n *   };\n *\n *   // JSX — spread the attr (rename-safe; no hardcoded attribute name):\n *   //   <button {...A.select.attrs} data-id={id}>…</button>\n *\n *   // Wire the whole table with ONE delegated listener; returns a disposer:\n *   const dispose = delegateActions(root, 'click', {\n *     [A.select.value]: (_e, el) => selectFile(el.getAttribute('data-id')),\n *     [A.remove.value]: (_e, el) => removeFile(el.getAttribute('data-id')),\n *   });\n *\n * Contract: `delegateActions` returns a `() => void` disposer and holds no\n * per-instance state — the same shape as `delegate()`, which it builds on (so\n * it inherits the single-listener dispatch and the capture auto-promotion for\n * well-known non-bubbling event types). One event type per call, mirroring\n * `delegate()`; collect the disposers for a root that needs several.\n */\nimport { attr, type AttrSpec } from './attr.js';\nimport { _delegate, type DelegateOptions, NON_BUBBLING } from './delegate.js';\n\n/** The attribute an action table keys on by default. */\nconst DEFAULT_ACTION_ATTR = 'data-action';\n\n/**\n * A handler in a {@link delegateActions} table. Receives the DOM event and the\n * matched element (walk-up `closest()` match by default) — the same shape as a\n * `delegate()` handler.\n */\nexport type ActionHandler<E extends Element = Element> = (\n  event: Event,\n  el: E,\n) => void;\n\n/**\n * `action(value)` — an {@link AttrSpec} on `data-action`. A thin specialization\n * of `attr('data-action', value)`: spread its `.attrs` in JSX and use its\n * `.value` as the handler-table key, so the action name lives in exactly one\n * place and can't drift between the markup and the dispatcher.\n */\nexport function action<V extends string>(value: V): AttrSpec<'data-action', V> {\n  return attr(DEFAULT_ACTION_ATTR, value);\n}\n\n/** Options for {@link delegateActions}. Extends {@link DelegateOptions}. */\nexport interface DelegateActionsOptions extends DelegateOptions {\n  /**\n   * The attribute the table keys on. Default `'data-action'`. Override it only\n   * if you also author the specs with `attr(yourName, …)` instead of `action()`.\n   */\n  attr?: string;\n}\n\n/**\n * Wire a whole table of action handlers with ONE delegated listener.\n *\n * On `eventType`, the nearest element carrying the action attribute (walk-up\n * `closest()` by default; pass `{ match: 'direct' }` for an exact-element match)\n * is looked up in `table` by its attribute value, and the matching handler\n * runs. An element whose action is absent from the table is ignored — the same\n * behavior as a `switch (dataset.action)` with no matching `case`.\n *\n * Returns a `() => void` disposer. One event type per call (the smallest\n * surface, mirroring `delegate()`); collect the disposers when a root needs\n * several event types.\n */\nexport function delegateActions<E extends Element = Element>(\n  root: HTMLElement,\n  eventType: string,\n  table: Readonly<Record<string, ActionHandler<E>>>,\n  options?: DelegateActionsOptions,\n): () => void {\n  const attrName = options?.attr ?? DEFAULT_ACTION_ATTR;\n  // The action value is read when the event STARTS dispatching (with the\n  // match itself — see `_delegate`), not from the live element when the\n  // handler runs: an earlier handler's synchronous re-render may have\n  // recycled the matched element into a different action by then.\n  return _delegate(\n    root,\n    eventType,\n    `[${attrName}]`,\n    (event, el) => {\n      // `el` matched `[${attrName}]`, so the attribute is always present.\n      const value = el.getAttribute(attrName) as string;\n      // Own entries only: the table is an ordinary object, so a bare\n      // `table[value]` would resolve Object.prototype names (`__proto__`,\n      // `constructor`, `toString`, `hasOwnProperty`, …) and dispatch or throw\n      // on markup that names no action in the table.\n      return () => {\n        if (Object.hasOwn(table, value)) table[value](event, el as E);\n      };\n    },\n    options,\n    NON_BUBBLING.has(eventType),\n    'delegate',\n  );\n}\n"]}

package/dist/chunk-JN7EJM3B.js

@@ -0,0 +1,86 @@
+import { devHooks } from './chunk-3C6F6NM4.js';
+
+// src/delegate.ts
+var NON_BUBBLING = /* @__PURE__ */ new Set([
+  "focus",
+  "blur",
+  "scroll",
+  "load",
+  "error",
+  "mouseenter",
+  "mouseleave"
+]);
+function assertValidSelector(selector, fn) {
+  try {
+    document.createElement("div").matches(selector);
+  } catch {
+    throw new Error(
+      `${fn}: invalid selector "${selector}". Pass a valid CSS selector (e.g. '[data-action="add"]', '.btn', 'input').`
+    );
+  }
+}
+var KEY = /* @__PURE__ */ Symbol();
+function _delegate(rootEl, type, selector, bind, options, capture, fn) {
+  assertValidSelector(selector, fn);
+  devHooks.delegateInEffect?.(fn);
+  const direct = options?.match === "direct";
+  const resolve = (event) => {
+    const target = event.target;
+    if (event.type === type && target instanceof Element) {
+      const matched = direct ? target.matches(selector) ? target : null : target.closest(selector);
+      if (matched !== null) {
+        const run = bind(event, matched);
+        return () => {
+          if (rootEl.contains(matched)) run();
+        };
+      }
+    }
+    return void 0;
+  };
+  const listener = (event) => {
+    let snap = event[KEY];
+    if (!snap?.has(resolve)) {
+      snap = event[KEY] = /* @__PURE__ */ new Map();
+      for (const node of event.composedPath()) {
+        for (const other of node[KEY] ?? []) {
+          snap.set(other, other(event));
+        }
+      }
+    }
+    const run = snap.get(resolve);
+    snap.delete(resolve);
+    run?.();
+  };
+  const registry = (rootEl[KEY] ??= /* @__PURE__ */ new Set()).add(resolve);
+  rootEl.addEventListener(type, listener, capture);
+  return () => {
+    registry.delete(resolve);
+    rootEl.removeEventListener(type, listener, capture);
+  };
+}
+function delegate(rootEl, type, selector, handler, options) {
+  return _delegate(
+    rootEl,
+    type,
+    selector,
+    (event, matched) => () => handler(event, matched),
+    options,
+    NON_BUBBLING.has(type),
+    "delegate"
+  );
+}
+function delegateCapture(rootEl, type, selector, handler, options) {
+  return _delegate(
+    rootEl,
+    type,
+    selector,
+    (event, matched) => () => handler(event, matched),
+    options,
+    true,
+    "delegateCapture"
+  );
+}
+
+export { NON_BUBBLING, _delegate, delegate, delegateCapture };
+
+//# sourceMappingURL=chunk-JN7EJM3B.js.map

package/dist/chunk-JN7EJM3B.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/delegate.ts"],"names":[],"mappings":";;;AA+CO,IAAM,YAAA,uBAAmB,GAAA,CAAY;AAAA,EAC1C,OAAA;AAAA,EACA,MAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EACA,YAAA;AAAA,EACA;AACF,CAAC;AAqBD,SAAS,mBAAA,CAAoB,UAAkB,EAAA,EAAkB;AAC/D,EAAA,IAAI;AACF,IAAA,QAAA,CAAS,aAAA,CAAc,KAAK,CAAA,CAAE,OAAA,CAAQ,QAAQ,CAAA;AAAA,EAChD,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,EAAG,EAAE,CAAA,oBAAA,EAAuB,QAAQ,CAAA,2EAAA;AAAA,KAEtC;AAAA,EACF;AACF;AASA,IAAM,sBAAM,MAAA,EAAO;AAiDZ,SAAS,UACd,MAAA,EACA,IAAA,EACA,UACA,IAAA,EACA,OAAA,EACA,SACA,EAAA,EACY;AACZ,EAAA,mBAAA,CAAoB,UAAU,EAAE,CAAA;AAChC,EAAA,QAAA,CAAS,mBAAmB,EAAE,CAAA;AAC9B,EAAA,MAAM,MAAA,GAAS,SAAS,KAAA,KAAU,QAAA;AAClC,EAAA,MAAM,OAAA,GAAmB,CAAC,KAAA,KAAU;AAClC,IAAA,MAAM,SAAS,KAAA,CAAM,MAAA;AACrB,IAAA,IAAI,KAAA,CAAM,IAAA,KAAS,IAAA,IAAQ,MAAA,YAAkB,OAAA,EAAS;AACpD,MAAA,MAAM,OAAA,GAAU,MAAA,GACZ,MAAA,CAAO,OAAA,CAAQ,QAAQ,IACrB,MAAA,GACA,IAAA,GACF,MAAA,CAAO,OAAA,CAAQ,QAAQ,CAAA;AAC3B,MAAA,IAAI,YAAY,IAAA,EAAM;AACpB,QAAA,MAAM,GAAA,GAAM,IAAA,CAAK,KAAA,EAAO,OAAO,CAAA;AAI/B,QAAA,OAAO,MAAM;AACX,UAAA,IAAI,MAAA,CAAO,QAAA,CAAS,OAAO,CAAA,EAAG,GAAA,EAAI;AAAA,QACpC,CAAA;AAAA,MACF;AAAA,IACF;AACA,IAAA,OAAO,MAAA;AAAA,EACT,CAAA;AACA,EAAA,MAAM,QAAA,GAAW,CAAC,KAAA,KAAuB;AACvC,IAAA,IAAI,IAAA,GAAQ,MAAsB,GAAG,CAAA;AACrC,IAAA,IAAI,CAAC,IAAA,EAAM,GAAA,CAAI,OAAO,CAAA,EAAG;AACvB,MAAA,IAAA,GAAQ,KAAA,CAAsB,GAAG,CAAA,mBAAI,IAAI,GAAA,EAAI;AAC7C,MAAA,KAAA,MAAW,IAAA,IAAQ,KAAA,CAAM,YAAA,EAAa,EAAG;AACvC,QAAA,KAAA,MAAW,KAAA,IAAU,IAAA,CAAoB,GAAG,CAAA,IAAK,EAAC,EAAG;AACnD,UAAA,IAAA,CAAK,GAAA,CAAI,KAAA,EAAO,KAAA,CAAM,KAAK,CAAC,CAAA;AAAA,QAC9B;AAAA,MACF;AAAA,IACF;AACA,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,GAAA,CAAI,OAAO,CAAA;AAC5B,IAAA,IAAA,CAAK,OAAO,OAAO,CAAA;AACnB,IAAA,GAAA,IAAM;AAAA,EACR,CAAA;AACA,EAAA,MAAM,QAAA,GAAA,CAAa,OAAsB,GAAG,CAAA,yBAAU,GAAA,EAAI,EAAG,IAAI,OAAO,CAAA;AACxE,EAAA,MAAA,CAAO,gBAAA,CAAiB,IAAA,EAAM,QAAA,EAAU,OAAO,CAAA;AAC/C,EAAA,OAAO,MAAM;AACX,IAAA,QAAA,CAAS,OAAO,OAAO,CAAA;AACvB,IAAA,MAAA,CAAO,mBAAA,CAAoB,IAAA,EAAM,QAAA,EAAU,OAAO,CAAA;AAAA,EACpD,CAAA;AACF;AAuBO,SAAS,QAAA,CACd,MAAA,EACA,IAAA,EACA,QAAA,EACA,SACA,OAAA,EACY;AACZ,EAAA,OAAO,SAAA;AAAA,IACL,MAAA;AAAA,IACA,IAAA;AAAA,IACA,QAAA;AAAA,IACA,CAAC,KAAA,EAAO,OAAA,KAAY,MAAM,OAAA,CAAQ,OAAO,OAAY,CAAA;AAAA,IACrD,OAAA;AAAA,IACA,YAAA,CAAa,IAAI,IAAI,CAAA;AAAA,IACrB;AAAA,GACF;AACF;AAuBO,SAAS,eAAA,CACd,MAAA,EACA,IAAA,EACA,QAAA,EACA,SACA,OAAA,EACY;AACZ,EAAA,OAAO,SAAA;AAAA,IACL,MAAA;AAAA,IACA,IAAA;AAAA,IACA,QAAA;AAAA,IACA,CAAC,KAAA,EAAO,OAAA,KAAY,MAAM,OAAA,CAAQ,OAAO,OAAY,CAAA;AAAA,IACrD,OAAA;AAAA,IACA,IAAA;AAAA,IACA;AAAA,GACF;AACF","file":"chunk-JN7EJM3B.js","sourcesContent":["/**\n * Tiny event-delegation helpers. Replace per-element `addEventListener` calls\n * (which don't survive morph re-renders for nodes the diff creates) with one\n * listener at the morph-root that dispatches via `closest()`.\n *\n * Three-tier listener model:\n *\n *   - Tier 1 (bubbling events) — use `delegate()`.\n *     click, input, change, submit, mousedown/up, keydown/up, pointerdown/up/move,\n *     drag*, drop, contextmenu, wheel, copy/paste/cut, focusin/focusout.\n *\n *     `delegate()` also auto-promotes the well-known non-bubbling event\n *     types (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`,\n *     `mouseleave`) to the capture phase under the hood, so the call site\n *     looks identical for \"interactive thing happens on a descendant\"\n *     regardless of whether that event bubbles. Selector matching stays\n *     `closest()`-style — the same as for bubbling events — so a wrapper\n *     selector like `'.field-row'` still matches when the event fires on\n *     a descendant `<input>`.\n *\n *   - Tier 2 (explicit capture) — use `delegateCapture()`.\n *     The escape hatch for cases the auto-promotion list doesn't cover\n *     (custom non-bubbling events) or when you want capture-phase\n *     interception. Selector matching is `closest()`-style by default —\n *     the same walk-up as `delegate()`, and it passes the matched ancestor\n *     (not the raw target) to the handler — so a click on any descendant of\n *     the selected element climbs to it. Pass `{ match: 'direct' }` to opt\n *     into strict `matches()`-style matching (fire only when the event lands\n *     on the exact element the selector identifies).\n *\n *   - Tier 3 (per-element instances / library-owned subtrees) — mark the\n *     host element with `data-morph-skip` and manage the library's\n *     lifecycle directly. No delegation helper applies.\n */\n\nimport { devHooks } from './dev-hooks.js';\n\n/**\n * Event types that don't bubble and so wouldn't reach a root-level\n * bubble-phase listener. `delegate()` flips to capture for these; the\n * caller doesn't need to know or care.\n *\n * Membership is conservative — it covers the cases that \"should obviously\n * work\" with delegate() but otherwise don't. For exotic non-bubbling events\n * (custom events, less-common DOM events) the explicit `delegateCapture()`\n * remains the escape hatch.\n */\nexport const NON_BUBBLING = new Set<string>([\n  'focus',\n  'blur',\n  'scroll',\n  'load',\n  'error',\n  'mouseenter',\n  'mouseleave',\n]);\n\n/**\n * How the selector is matched against the event's target:\n *\n *   - `'closest'` (the default for both helpers) — walk UP from `event.target`\n *     via `closest(selector)`, firing for the nearest matching ancestor inside\n *     `rootEl`. This is the delegation behavior you almost always want: a click\n *     on an icon inside a button fires the button's handler.\n *   - `'direct'` — strict `matches()` match: fire only when `event.target`\n *     itself matches the selector, with no walk-up.\n */\nexport interface DelegateOptions {\n  match?: 'closest' | 'direct';\n}\n\n/**\n * Validate a CSS selector at registration time, so a typo throws immediately\n * with the bad selector quoted instead of producing a cryptic DOMException\n * the first time a matching event fires.\n */\nfunction assertValidSelector(selector: string, fn: string): void {\n  try {\n    document.createElement('div').matches(selector);\n  } catch {\n    throw new Error(\n      `${fn}: invalid selector \"${selector}\". ` +\n        \"Pass a valid CSS selector (e.g. '[data-action=\\\"add\\\"]', '.btn', 'input').\",\n    );\n  }\n}\n\n/**\n * Per-root registry of the delegates installed on that root, and the per-event\n * dispatch snapshot. Both live ON the DOM objects, under one symbol key (a\n * root and an event are never the same object), rather than in module-level\n * maps — so they are collected with the root / event and add no module-level\n * mutable state (Design rule 5).\n */\nconst KEY = Symbol();\n\n/**\n * Resolves one delegate's selector against an event's target: the bound\n * handler call for a match, `undefined` otherwise.\n */\ntype Resolve = (event: Event) => (() => void) | undefined;\n\ninterface Registered {\n  [KEY]?: Set<Resolve>;\n}\n\ninterface Snapshotted {\n  [KEY]?: Map<Resolve, (() => void) | undefined>;\n}\n\n/**\n * Install one root-level delegate — the shared core of `delegate()`,\n * `delegateCapture()`, and `kerfjs/actions`' `delegateActions()`.\n *\n * The listener resolves the event's target to a matched element (walk-up\n * `closest()` or strict `matches()`, per `options.match`) that must lie inside\n * `rootEl`, then runs the call `bind(event, matched)` prepared. `bind` runs at\n * RESOLUTION time, so a caller can read matched-element state there (such as\n * `delegateActions`' action attribute) before any handler has mutated it.\n *\n * **Dispatch snapshot.** A handler that writes a signal makes `mount()` morph\n * synchronously, inside the same dispatch, and the morph can recycle the\n * clicked element in place into a control with a different selector identity\n * (same tag, same position, new `data-action`). Resolving later delegates\n * against that live DOM would fire one the user never clicked — typically one\n * that immediately undoes the first handler's state change. So the FIRST kerf\n * delegate listener to see an event resolves every kerf delegate on the\n * event's propagation path (fixed at dispatch start, per the DOM spec, and\n * listed by `composedPath()`) before any delegated handler runs, and stores\n * the results on the event; each listener then consumes its own entry. The\n * set of delegates an event reaches is fixed when it starts dispatching, like\n * per-element listeners. The matched element must also still be inside\n * `rootEl` when the listener runs: a handler that removed the target still\n * suppresses the later delegates, as before.\n *\n * A missing entry (a re-dispatch of the same event object, a delegate added\n * mid-dispatch, or a root hidden from the first listener by a closed shadow\n * boundary) takes a fresh snapshot. Accepted residuals: a same-path\n * re-dispatch after a stopped dispatch can reuse an unconsumed entry if all\n * earlier kerf listeners were disposed, and a closed shadow boundary can\n * hide delegates from the first listener's path view. See docs/5 §5.2.1.\n * Internal — exported for `kerfjs/actions`.\n */\nexport function _delegate(\n  rootEl: HTMLElement,\n  type: string,\n  selector: string,\n  bind: (event: Event, matched: Element) => () => void,\n  options: DelegateOptions | undefined,\n  capture: boolean,\n  fn: 'delegate' | 'delegateCapture',\n): () => void {\n  assertValidSelector(selector, fn);\n  devHooks.delegateInEffect?.(fn);\n  const direct = options?.match === 'direct';\n  const resolve: Resolve = (event) => {\n    const target = event.target;\n    if (event.type === type && target instanceof Element) {\n      const matched = direct\n        ? target.matches(selector)\n          ? target\n          : null\n        : target.closest(selector);\n      if (matched !== null) {\n        const run = bind(event, matched);\n        // Checked when the handler would run, not at resolution: a match\n        // outside `rootEl` never fires, and neither does one an earlier\n        // handler removed from `rootEl`.\n        return () => {\n          if (rootEl.contains(matched)) run();\n        };\n      }\n    }\n    return undefined;\n  };\n  const listener = (event: Event): void => {\n    let snap = (event as Snapshotted)[KEY];\n    if (!snap?.has(resolve)) {\n      snap = (event as Snapshotted)[KEY] = new Map();\n      for (const node of event.composedPath()) {\n        for (const other of (node as Registered)[KEY] ?? []) {\n          snap.set(other, other(event));\n        }\n      }\n    }\n    const run = snap.get(resolve);\n    snap.delete(resolve);\n    run?.();\n  };\n  const registry = ((rootEl as Registered)[KEY] ??= new Set()).add(resolve);\n  rootEl.addEventListener(type, listener, capture);\n  return () => {\n    registry.delete(resolve);\n    rootEl.removeEventListener(type, listener, capture);\n  };\n}\n\n/**\n * Delegation that \"just works\" for both bubbling and the common non-bubbling\n * events. Installs ONE listener on `rootEl`; for known non-bubblers (see\n * `NON_BUBBLING` above) the listener is registered on the capture phase so\n * it actually reaches the target, otherwise on the bubble phase. Either way,\n * matching walks up from `event.target` via `closest(selector)` and fires\n * `handler(event, matched)` if the match is inside `rootEl`.\n *\n * Pass `{ match: 'direct' }` to fire only when `event.target` itself matches\n * the selector (no walk-up); the default is `'closest'`.\n *\n * The generic `T` narrows the second handler argument to the expected element\n * type — `delegate<HTMLButtonElement>(root, 'click', 'button', (e, btn) => btn.value)`\n * — so consumers can avoid casts. Defaults to `Element` for untyped calls.\n *\n * Returns a disposer that removes the listener.\n *\n * Usage (pseudo-code — see examples for live ones):\n *   delegate(rootEl, 'click', '[data-action=\"add\"]', handlerFn);\n *   delegate(rootEl, 'focus', 'input',                handlerFn); // auto-capture\n */\nexport function delegate<T extends Element = Element>(\n  rootEl: HTMLElement,\n  type: string,\n  selector: string,\n  handler: (event: Event, target: T) => void,\n  options?: DelegateOptions,\n): () => void {\n  return _delegate(\n    rootEl,\n    type,\n    selector,\n    (event, matched) => () => handler(event, matched as T),\n    options,\n    NON_BUBBLING.has(type),\n    'delegate',\n  );\n}\n\n/**\n * Capture-phase delegation — the escape hatch for custom non-bubbling events\n * (ones `delegate()`'s auto-promotion list doesn't know about) and for\n * capture-phase interception (run before any descendant's bubble-phase\n * handler). Reaches descendants of `rootEl` that match `selector` regardless\n * of how many times the diff has rebuilt them.\n *\n * Selector matching is `closest()`-style by default — the same walk-up as\n * `delegate()`, and it passes the matched ancestor (not the raw target) to\n * the handler — so a click on any descendant of the selected element climbs\n * to it. Pass `{ match: 'direct' }` to opt into strict `matches()`-style\n * matching (fire only when the event lands on the exact element the selector\n * identifies, with no walk-up).\n *\n * The generic `T` narrows the second handler argument to the expected element\n * type, mirroring `delegate<T>()`. Defaults to `Element` for untyped calls.\n *\n * Usage (pseudo-code — see examples for live ones):\n *   delegateCapture(rootEl, 'focus', 'input, textarea', handlerFn);\n *   delegateCapture(rootEl, 'click', '.exact', handlerFn, { match: 'direct' });\n */\nexport function delegateCapture<T extends Element = Element>(\n  rootEl: HTMLElement,\n  type: string,\n  selector: string,\n  handler: (event: Event, target: T) => void,\n  options?: DelegateOptions,\n): () => void {\n  return _delegate(\n    rootEl,\n    type,\n    selector,\n    (event, matched) => () => handler(event, matched as T),\n    options,\n    true,\n    'delegateCapture',\n  );\n}\n"]}

package/dist/{delegate-CL9VTZFb.d.ts → delegate--CrfgYtC.d.ts}

@@ -1,37 +1,3 @@
-/**
- * Tiny event-delegation helpers. Replace per-element `addEventListener` calls
- * (which don't survive morph re-renders for nodes the diff creates) with one
- * listener at the morph-root that dispatches via `closest()`.
- *
- * Three-tier listener model:
- *
- *   - Tier 1 (bubbling events) — use `delegate()`.
- *     click, input, change, submit, mousedown/up, keydown/up, pointerdown/up/move,
- *     drag*, drop, contextmenu, wheel, copy/paste/cut, focusin/focusout.
- *
- *     `delegate()` also auto-promotes the well-known non-bubbling event
- *     types (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`,
- *     `mouseleave`) to the capture phase under the hood, so the call site
- *     looks identical for "interactive thing happens on a descendant"
- *     regardless of whether that event bubbles. Selector matching stays
- *     `closest()`-style — the same as for bubbling events — so a wrapper
- *     selector like `'.field-row'` still matches when the event fires on
- *     a descendant `<input>`.
- *
- *   - Tier 2 (explicit capture) — use `delegateCapture()`.
- *     The escape hatch for cases the auto-promotion list doesn't cover
- *     (custom non-bubbling events) or when you want capture-phase
- *     interception. Selector matching is `closest()`-style by default —
- *     the same walk-up as `delegate()`, and it passes the matched ancestor
- *     (not the raw target) to the handler — so a click on any descendant of
- *     the selected element climbs to it. Pass `{ match: 'direct' }` to opt
- *     into strict `matches()`-style matching (fire only when the event lands
- *     on the exact element the selector identifies).
- *
- *   - Tier 3 (per-element instances / library-owned subtrees) — mark the
- *     host element with `data-morph-skip` and manage the library's
- *     lifecycle directly. No delegation helper applies.
- */
 /**
  * How the selector is matched against the event's target:
  *

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { A as AttrSpec, a as attr } from './attr-Cmu2ZoGO.js';
-export { D as DelegateOptions, d as delegate, a as delegateCapture } from './delegate-CL9VTZFb.js';
+export { D as DelegateOptions, d as delegate, a as delegateCapture } from './delegate--CrfgYtC.js';
 import { ArraySignal } from './array-signal.js';
 import { SafeHtml } from './jsx-runtime.js';
 export { Fragment, JSXChildren, isSafeHtml, raw } from './jsx-runtime.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 export { each, morph, mount } from './chunk-TLL3KXT6.js';
 export { defineStore, resetAllStores } from './chunk-BI4HGICV.js';
 export { attr } from './chunk-MK42GLPV.js';
-export { delegate, delegateCapture } from './chunk-X6OQ2HTR.js';
+export { delegate, delegateCapture } from './chunk-JN7EJM3B.js';
 
 
 export { Fragment, SafeHtml, isSafeHtml, raw } from './chunk-UGNPDLNI.js';

package/dist/jsx-runtime.d.ts

@@ -865,6 +865,7 @@ interface KerfBuiltinIntrinsicElements {
     p: KerfBaseAttrs;
     hr: KerfBaseAttrs;
     br: KerfBaseAttrs;
+    wbr: KerfBaseAttrs;
     pre: KerfBaseAttrs;
     blockquote: HTMLBlockquoteAttrs;
     q: HTMLQAttrs;

package/dist/overlay.js

@@ -1,6 +1,6 @@
 import { attach } from './chunk-FM6N2B4N.js';
 import { mount } from './chunk-TLL3KXT6.js';
-import { delegate } from './chunk-X6OQ2HTR.js';
+import { delegate } from './chunk-JN7EJM3B.js';
 
 
 import { jsx, escapeHtml } from './chunk-UGNPDLNI.js';

package/dist/router.js

@@ -1,4 +1,4 @@
-import { delegate } from './chunk-X6OQ2HTR.js';
+import { delegate } from './chunk-JN7EJM3B.js';
 import { jsx } from './chunk-UGNPDLNI.js';
 import { signal, computed } from './chunk-IHMDBBUJ.js';
 

package/dist/scope.d.ts

@@ -1,4 +1,4 @@
-import { D as DelegateOptions } from './delegate-CL9VTZFb.js';
+import { D as DelegateOptions } from './delegate--CrfgYtC.js';
 import { M as MountResult } from './mount-Bo2qOx25.js';
 import './jsx-runtime.js';
 import '@preact/signals-core';

package/dist/scope.js

@@ -1,5 +1,5 @@
 import { mount } from './chunk-TLL3KXT6.js';
-import { delegate } from './chunk-X6OQ2HTR.js';
+import { delegate } from './chunk-JN7EJM3B.js';
 
 
 

package/llms.txt

@@ -1,6 +1,6 @@
 # kerf
 
-> A tiny (~12 KB minified + gzipped including its one runtime dependency `@preact/signals-core`; ~13 KB with `arraySignal`) reactive UI framework — fine-grained signals + DOM morphing + JSX. No virtual DOM, no compiler. Apply the smallest possible cut to update your DOM.
+> A tiny (~13 KB minified + gzipped including its one runtime dependency `@preact/signals-core`; still ~13 KB with `arraySignal`) reactive UI framework — fine-grained signals + DOM morphing + JSX. No virtual DOM, no compiler. Apply the smallest possible cut to update your DOM.
 
 kerf renders JSX to a structured `SafeHtml` (string for static content; tagged "list"/"mixed" segments where `each(...)` was used) and reconciles it against the live tree with a custom segment-aware morph. Static surrounds go through a general-purpose tree-morph; list contents go through a keyed reconciler that operates directly on live children. Snapshot reconciliation scans O(rows) but limits rendering and DOM mutations to cache misses and structural changes; eligible `arraySignal` patch delivery runs in O(patches). Reactivity is provided by [@preact/signals-core](https://github.com/preactjs/signals). It pairs well with server-rendered HTML, embedded widgets, and any UI where preserving focus / selection across re-renders matters. Public API is one import: `signal`, `computed`, `effect`, `batch`, `defineStore`, `resetAllStores`, `mount`, `morph`, `each`, `attr`, `delegate`, `delegateCapture`, `toElement`, `renderDocument`, `SafeHtml`, `isSafeHtml`, `raw`, `Fragment`. (Two more subpaths: `kerfjs/testing` exposes `clearStoreRegistry` for unit-test isolation; `kerfjs/jsx-runtime` exposes the typed JSX building blocks for declaration-merging custom-element types.) An optional subpath at `kerfjs/array-signal` adds `arraySignal()` — a granular keyed-list signal whose patch events let `each()` reconcile in O(patches) instead of O(N). An optional subpath at `kerfjs/dev` installs the development diagnostics — kerf does NOT infer dev mode, so you import it behind your own build's dev flag (`if (import.meta.env.DEV) await import('kerfjs/dev');`); omitting it is production and sheds ~4.7 KB min+gzip. Another optional subpath at `kerfjs/html` adds the `html` tagged template — JSX-identical runtime semantics with no JSX transform, so CDN/importmap projects can author kerf UIs with literally no build step. A family of optional, tree-shakeable **companion-utility** subpaths cover patterns real apps hand-roll: `kerfjs/list` (`bindList` — a keyed list with per-row fine-grained mounts and fixed / declared / measured-height viewport virtualization, plus `observeRowHeights`), `kerfjs/router` (`createRouter` — the opt-in "postcard router": route matching + `navigate` + `<a>` link interception + a keyed outlet, core stays router-free), `kerfjs/overlay` (`overlay` / `confirm` / `prompt` / `form` / `choice` / `popover` / `tooltip` / `toast` + `positionAnchored` / `autoReposition`; `native: true` top-layer backing via `<dialog>` / the Popover API applies to the seven overlay/dialog/popover/tooltip surfaces), `kerfjs/scope` (`disposeScope` / `disposeSubtree` / `observeRemovals`), `kerfjs/async` (`resource` async-state with a stale-response guard + SWR cache), `kerfjs/timing` (`debounce` / `throttle` / `debouncedSignal`), `kerfjs/remount` (`remountOn` — key-driven wholesale subtree replacement), `kerfjs/attach` (`attach` — bind a non-kerf widget's lifecycle to one node), and `kerfjs/actions` (`action` / `delegateActions` — the delegated `data-action` table idiom).
 
@@ -19,8 +19,8 @@ kerf renders JSX to a structured `SafeHtml` (string for static content; tagged "
 - [Requirements summary](https://github.com/brianwestphal/kerf/blob/main/docs/ai/requirements-summary.md): synthesized view of the numbered design docs.
 - [`kerf.cursorrules`](https://github.com/brianwestphal/kerf/blob/main/kerf.cursorrules): drop-in [Cursor](https://cursor.sh) rules for projects that import `kerfjs`. Copy into your project as `.cursorrules` — or use the bundled mirror at `node_modules/kerfjs/ai/cursorrules` once you've `npm install`ed kerfjs.
 - [`kerf.claude-skill.md`](https://github.com/brianwestphal/kerf/blob/main/kerf.claude-skill.md): drop-in [Claude Code](https://claude.com/claude-code) skill. Copy into `~/.claude/skills/kerf-app/SKILL.md` (or your project's `.claude/skills/kerf-app/SKILL.md`) — or use the bundled mirror at `node_modules/kerfjs/ai/skill.md` once you've `npm install`ed kerfjs.
-- [`eslint-plugin-kerfjs`](https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/README.md): companion ESLint plugin enforcing the hard rules at edit time — eight AST-only core rules in `kerfjs.configs.recommended`: `no-inline-jsx-event-handlers`, `require-data-key-in-each`, `no-nested-mount`, `prefer-module-jsx-augmentation` (error) plus `require-delegate-disposer`, `prefer-attr-selector`, `no-raw-with-dynamic-arg`, `ai-assistant-configs` (warn), with no `parserServices` dependency; plus five `@kerfjs/ui` catalog-contract rules (`ui-composition`, `ui-css-values`, `ui-preferences`, `ui-public-boundaries`, `ui-wiring`) in the `recommended-ui` / `strict-ui` configs. Install with `npm install --save-dev eslint-plugin-kerfjs` and add `kerfjs.configs.recommended` to your eslint config. Recommended when authoring kerf code with an AI assistant — eslint feedback surfaces in the IDE before `tsc` or runtime warns ever run.
-- [`create-kerf-component`](https://github.com/brianwestphal/kerf/blob/main/create-kerf-component/README.md): companion initializer that scaffolds a publishable kerf component package with the hard packaging rules, an example component, and explicit `kerf.components.json` source metadata plus deterministic `component-catalog-v2.json` generation/checking. Run `npm create kerf-component@latest <dir>`.
+- [`eslint-plugin-kerfjs`](https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/README.md): companion ESLint plugin enforcing the hard rules at edit time — eight AST-only core rules in `kerfjs.configs.recommended`: `no-inline-jsx-event-handlers`, `require-data-key-in-each`, `no-nested-mount`, `prefer-module-jsx-augmentation` (error) plus `require-delegate-disposer`, `prefer-attr-selector`, `no-raw-with-dynamic-arg`, `ai-assistant-configs` (warn), with no `parserServices` dependency; plus six `@kerfjs/ui` catalog-contract rules (`ui-component-ownership`, `ui-composition`, `ui-css-values`, `ui-preferences`, `ui-public-boundaries`, `ui-wiring`) in the `recommended-ui` / `strict-ui` configs. Install with `npm install --save-dev eslint-plugin-kerfjs` and add `kerfjs.configs.recommended` to your eslint config. Recommended when authoring kerf code with an AI assistant — eslint feedback surfaces in the IDE before `tsc` or runtime warns ever run.
+- [`create-kerf-component`](https://github.com/brianwestphal/kerf/blob/main/create-kerf-component/README.md): companion initializer that scaffolds a publishable kerf component package with the hard packaging rules, an example component, and explicit `kerf.components.json` source metadata plus deterministic `component-composition.json` generation/checking. Run `npm create kerf-component@latest <dir>`.
 - [`@kerfjs/ui` AI guide](https://github.com/brianwestphal/kerf/blob/main/ui/ai/skill.md): component-selection, styling, accessibility, and event-wiring contract for the optional first-party UI package.
 
 ## Reference docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kerfjs",
-  "version": "5.0.0-beta.56",
+  "version": "5.0.0-beta.58",
   "description": "Tiny reactive UI framework — fine-grained signals + DOM morphing + JSX. Apply the smallest possible cut to update your DOM.",
   "type": "module",
   "sideEffects": [

package/setup/index.mjs

@@ -491,7 +491,7 @@ function profileTemplate(packageName, catalogPath) {
     catalogs: [
       {
         package: packageName,
-        composition: { path: catalogPath, schemaVersion: 2 },
+        composition: { path: catalogPath, schemaVersion: 1 },
       },
     ],
   };
@@ -502,7 +502,7 @@ function metadataTemplate() {
     $schema:
       './node_modules/create-kerf-component/component-metadata.schema.json',
     schemaVersion: 1,
-    v1Catalog: 'not-applicable',
+    componentCatalog: 'not-applicable',
     components: [],
   };
 }
@@ -820,7 +820,7 @@ export async function planKerfSetup({
       key: 'kerfComponentCatalog',
       value: {
         source: './kerf.components.json',
-        output: './component-catalog-v2.json',
+        output: './component-composition.json',
       },
       id: 'package.json#kerfComponentCatalog',
       ...context,
@@ -1011,7 +1011,7 @@ export async function planKerfSetup({
         : JSON.parse(currentProfileSource);
     const catalogRelative = portable(
       root,
-      resolve(selected.directory, 'component-catalog-v2.json'),
+      resolve(selected.directory, 'component-composition.json'),
     );
     const profile = mergeProfile(
       currentProfile,

package/dist/chunk-X6OQ2HTR.js

@@ -1,64 +0,0 @@
-import { devHooks } from './chunk-3C6F6NM4.js';
-
-// src/delegate.ts
-var NON_BUBBLING = /* @__PURE__ */ new Set([
-  "focus",
-  "blur",
-  "scroll",
-  "load",
-  "error",
-  "mouseenter",
-  "mouseleave"
-]);
-function assertValidSelector(selector, fn) {
-  try {
-    document.createElement("div").matches(selector);
-  } catch {
-    throw new Error(
-      `${fn}: invalid selector "${selector}". Pass a valid CSS selector (e.g. '[data-action="add"]', '.btn', 'input').`
-    );
-  }
-}
-function makeListener(rootEl, selector, handler, match) {
-  return (event) => {
-    const target = event.target;
-    if (!(target instanceof Element)) return;
-    const matched = match === "direct" ? target.matches(selector) ? target : null : target.closest(selector);
-    if (matched !== null && rootEl.contains(matched)) {
-      handler(event, matched);
-    }
-  };
-}
-function delegate(rootEl, type, selector, handler, options) {
-  assertValidSelector(selector, "delegate");
-  devHooks.delegateInEffect?.("delegate");
-  const listener = makeListener(
-    rootEl,
-    selector,
-    handler,
-    options?.match ?? "closest"
-  );
-  const capture = NON_BUBBLING.has(type);
-  rootEl.addEventListener(type, listener, capture);
-  return () => {
-    rootEl.removeEventListener(type, listener, capture);
-  };
-}
-function delegateCapture(rootEl, type, selector, handler, options) {
-  assertValidSelector(selector, "delegateCapture");
-  devHooks.delegateInEffect?.("delegateCapture");
-  const listener = makeListener(
-    rootEl,
-    selector,
-    handler,
-    options?.match ?? "closest"
-  );
-  rootEl.addEventListener(type, listener, true);
-  return () => {
-    rootEl.removeEventListener(type, listener, true);
-  };
-}
-
-export { delegate, delegateCapture };
-
-//# sourceMappingURL=chunk-X6OQ2HTR.js.map

package/dist/chunk-X6OQ2HTR.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/delegate.ts"],"names":[],"mappings":";;;AA+CA,IAAM,YAAA,uBAAmB,GAAA,CAAY;AAAA,EACnC,OAAA;AAAA,EACA,MAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EACA,YAAA;AAAA,EACA;AACF,CAAC,CAAA;AAqBD,SAAS,mBAAA,CAAoB,UAAkB,EAAA,EAAkB;AAC/D,EAAA,IAAI;AACF,IAAA,QAAA,CAAS,aAAA,CAAc,KAAK,CAAA,CAAE,OAAA,CAAQ,QAAQ,CAAA;AAAA,EAChD,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,EAAG,EAAE,CAAA,oBAAA,EAAuB,QAAQ,CAAA,2EAAA;AAAA,KAEtC;AAAA,EACF;AACF;AAQA,SAAS,YAAA,CACP,MAAA,EACA,QAAA,EACA,OAAA,EACA,KAAA,EACwB;AACxB,EAAA,OAAO,CAAC,KAAA,KAAuB;AAC7B,IAAA,MAAM,SAAS,KAAA,CAAM,MAAA;AACrB,IAAA,IAAI,EAAE,kBAAkB,OAAA,CAAA,EAAU;AAClC,IAAA,MAAM,OAAA,GACJ,KAAA,KAAU,QAAA,GACN,MAAA,CAAO,OAAA,CAAQ,QAAQ,CAAA,GACrB,MAAA,GACA,IAAA,GACF,MAAA,CAAO,OAAA,CAAQ,QAAQ,CAAA;AAC7B,IAAA,IAAI,OAAA,KAAY,IAAA,IAAQ,MAAA,CAAO,QAAA,CAAS,OAAO,CAAA,EAAG;AAChD,MAAA,OAAA,CAAQ,OAAO,OAAY,CAAA;AAAA,IAC7B;AAAA,EACF,CAAA;AACF;AAuBO,SAAS,QAAA,CACd,MAAA,EACA,IAAA,EACA,QAAA,EACA,SACA,OAAA,EACY;AACZ,EAAA,mBAAA,CAAoB,UAAU,UAAU,CAAA;AACxC,EAAA,QAAA,CAAS,mBAAmB,UAAU,CAAA;AACtC,EAAA,MAAM,QAAA,GAAW,YAAA;AAAA,IACf,MAAA;AAAA,IACA,QAAA;AAAA,IACA,OAAA;AAAA,IACA,SAAS,KAAA,IAAS;AAAA,GACpB;AACA,EAAA,MAAM,OAAA,GAAU,YAAA,CAAa,GAAA,CAAI,IAAI,CAAA;AACrC,EAAA,MAAA,CAAO,gBAAA,CAAiB,IAAA,EAAM,QAAA,EAAU,OAAO,CAAA;AAC/C,EAAA,OAAO,MAAM;AACX,IAAA,MAAA,CAAO,mBAAA,CAAoB,IAAA,EAAM,QAAA,EAAU,OAAO,CAAA;AAAA,EACpD,CAAA;AACF;AAuBO,SAAS,eAAA,CACd,MAAA,EACA,IAAA,EACA,QAAA,EACA,SACA,OAAA,EACY;AACZ,EAAA,mBAAA,CAAoB,UAAU,iBAAiB,CAAA;AAC/C,EAAA,QAAA,CAAS,mBAAmB,iBAAiB,CAAA;AAC7C,EAAA,MAAM,QAAA,GAAW,YAAA;AAAA,IACf,MAAA;AAAA,IACA,QAAA;AAAA,IACA,OAAA;AAAA,IACA,SAAS,KAAA,IAAS;AAAA,GACpB;AACA,EAAA,MAAA,CAAO,gBAAA,CAAiB,IAAA,EAAM,QAAA,EAAU,IAAI,CAAA;AAC5C,EAAA,OAAO,MAAM;AACX,IAAA,MAAA,CAAO,mBAAA,CAAoB,IAAA,EAAM,QAAA,EAAU,IAAI,CAAA;AAAA,EACjD,CAAA;AACF","file":"chunk-X6OQ2HTR.js","sourcesContent":["/**\n * Tiny event-delegation helpers. Replace per-element `addEventListener` calls\n * (which don't survive morph re-renders for nodes the diff creates) with one\n * listener at the morph-root that dispatches via `closest()`.\n *\n * Three-tier listener model:\n *\n *   - Tier 1 (bubbling events) — use `delegate()`.\n *     click, input, change, submit, mousedown/up, keydown/up, pointerdown/up/move,\n *     drag*, drop, contextmenu, wheel, copy/paste/cut, focusin/focusout.\n *\n *     `delegate()` also auto-promotes the well-known non-bubbling event\n *     types (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`,\n *     `mouseleave`) to the capture phase under the hood, so the call site\n *     looks identical for \"interactive thing happens on a descendant\"\n *     regardless of whether that event bubbles. Selector matching stays\n *     `closest()`-style — the same as for bubbling events — so a wrapper\n *     selector like `'.field-row'` still matches when the event fires on\n *     a descendant `<input>`.\n *\n *   - Tier 2 (explicit capture) — use `delegateCapture()`.\n *     The escape hatch for cases the auto-promotion list doesn't cover\n *     (custom non-bubbling events) or when you want capture-phase\n *     interception. Selector matching is `closest()`-style by default —\n *     the same walk-up as `delegate()`, and it passes the matched ancestor\n *     (not the raw target) to the handler — so a click on any descendant of\n *     the selected element climbs to it. Pass `{ match: 'direct' }` to opt\n *     into strict `matches()`-style matching (fire only when the event lands\n *     on the exact element the selector identifies).\n *\n *   - Tier 3 (per-element instances / library-owned subtrees) — mark the\n *     host element with `data-morph-skip` and manage the library's\n *     lifecycle directly. No delegation helper applies.\n */\n\nimport { devHooks } from './dev-hooks.js';\n\n/**\n * Event types that don't bubble and so wouldn't reach a root-level\n * bubble-phase listener. `delegate()` flips to capture for these; the\n * caller doesn't need to know or care.\n *\n * Membership is conservative — it covers the cases that \"should obviously\n * work\" with delegate() but otherwise don't. For exotic non-bubbling events\n * (custom events, less-common DOM events) the explicit `delegateCapture()`\n * remains the escape hatch.\n */\nconst NON_BUBBLING = new Set<string>([\n  'focus',\n  'blur',\n  'scroll',\n  'load',\n  'error',\n  'mouseenter',\n  'mouseleave',\n]);\n\n/**\n * How the selector is matched against the event's target:\n *\n *   - `'closest'` (the default for both helpers) — walk UP from `event.target`\n *     via `closest(selector)`, firing for the nearest matching ancestor inside\n *     `rootEl`. This is the delegation behavior you almost always want: a click\n *     on an icon inside a button fires the button's handler.\n *   - `'direct'` — strict `matches()` match: fire only when `event.target`\n *     itself matches the selector, with no walk-up.\n */\nexport interface DelegateOptions {\n  match?: 'closest' | 'direct';\n}\n\n/**\n * Validate a CSS selector at registration time, so a typo throws immediately\n * with the bad selector quoted instead of producing a cryptic DOMException\n * the first time a matching event fires.\n */\nfunction assertValidSelector(selector: string, fn: string): void {\n  try {\n    document.createElement('div').matches(selector);\n  } catch {\n    throw new Error(\n      `${fn}: invalid selector \"${selector}\". ` +\n        \"Pass a valid CSS selector (e.g. '[data-action=\\\"add\\\"]', '.btn', 'input').\",\n    );\n  }\n}\n\n/**\n * Build the shared root-level listener used by both helpers. Resolves the\n * event's target to a matched element (walk-up `closest()` or strict\n * `matches()`, per `match`), requires the match to be inside `rootEl`, then\n * fires `handler(event, matched)`.\n */\nfunction makeListener<T extends Element>(\n  rootEl: HTMLElement,\n  selector: string,\n  handler: (event: Event, target: T) => void,\n  match: 'closest' | 'direct',\n): (event: Event) => void {\n  return (event: Event): void => {\n    const target = event.target;\n    if (!(target instanceof Element)) return;\n    const matched =\n      match === 'direct'\n        ? target.matches(selector)\n          ? target\n          : null\n        : target.closest(selector);\n    if (matched !== null && rootEl.contains(matched)) {\n      handler(event, matched as T);\n    }\n  };\n}\n\n/**\n * Delegation that \"just works\" for both bubbling and the common non-bubbling\n * events. Installs ONE listener on `rootEl`; for known non-bubblers (see\n * `NON_BUBBLING` above) the listener is registered on the capture phase so\n * it actually reaches the target, otherwise on the bubble phase. Either way,\n * matching walks up from `event.target` via `closest(selector)` and fires\n * `handler(event, matched)` if the match is inside `rootEl`.\n *\n * Pass `{ match: 'direct' }` to fire only when `event.target` itself matches\n * the selector (no walk-up); the default is `'closest'`.\n *\n * The generic `T` narrows the second handler argument to the expected element\n * type — `delegate<HTMLButtonElement>(root, 'click', 'button', (e, btn) => btn.value)`\n * — so consumers can avoid casts. Defaults to `Element` for untyped calls.\n *\n * Returns a disposer that removes the listener.\n *\n * Usage (pseudo-code — see examples for live ones):\n *   delegate(rootEl, 'click', '[data-action=\"add\"]', handlerFn);\n *   delegate(rootEl, 'focus', 'input',                handlerFn); // auto-capture\n */\nexport function delegate<T extends Element = Element>(\n  rootEl: HTMLElement,\n  type: string,\n  selector: string,\n  handler: (event: Event, target: T) => void,\n  options?: DelegateOptions,\n): () => void {\n  assertValidSelector(selector, 'delegate');\n  devHooks.delegateInEffect?.('delegate');\n  const listener = makeListener(\n    rootEl,\n    selector,\n    handler,\n    options?.match ?? 'closest',\n  );\n  const capture = NON_BUBBLING.has(type);\n  rootEl.addEventListener(type, listener, capture);\n  return () => {\n    rootEl.removeEventListener(type, listener, capture);\n  };\n}\n\n/**\n * Capture-phase delegation — the escape hatch for custom non-bubbling events\n * (ones `delegate()`'s auto-promotion list doesn't know about) and for\n * capture-phase interception (run before any descendant's bubble-phase\n * handler). Reaches descendants of `rootEl` that match `selector` regardless\n * of how many times the diff has rebuilt them.\n *\n * Selector matching is `closest()`-style by default — the same walk-up as\n * `delegate()`, and it passes the matched ancestor (not the raw target) to\n * the handler — so a click on any descendant of the selected element climbs\n * to it. Pass `{ match: 'direct' }` to opt into strict `matches()`-style\n * matching (fire only when the event lands on the exact element the selector\n * identifies, with no walk-up).\n *\n * The generic `T` narrows the second handler argument to the expected element\n * type, mirroring `delegate<T>()`. Defaults to `Element` for untyped calls.\n *\n * Usage (pseudo-code — see examples for live ones):\n *   delegateCapture(rootEl, 'focus', 'input, textarea', handlerFn);\n *   delegateCapture(rootEl, 'click', '.exact', handlerFn, { match: 'direct' });\n */\nexport function delegateCapture<T extends Element = Element>(\n  rootEl: HTMLElement,\n  type: string,\n  selector: string,\n  handler: (event: Event, target: T) => void,\n  options?: DelegateOptions,\n): () => void {\n  assertValidSelector(selector, 'delegateCapture');\n  devHooks.delegateInEffect?.('delegateCapture');\n  const listener = makeListener(\n    rootEl,\n    selector,\n    handler,\n    options?.match ?? 'closest',\n  );\n  rootEl.addEventListener(type, listener, true);\n  return () => {\n    rootEl.removeEventListener(type, listener, true);\n  };\n}\n"]}