kerfjs 5.0.0-beta.56 → 5.0.0-beta.57

package/CHANGELOG.md

@@ -6,6 +6,336 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+- **`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

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, one dependency.** ~13 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.
 
 2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it _is_ the DOM.
 

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.57",
   "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.57",
   "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"]}