kerfjs 4.4.0 → 4.5.0-beta.1

package/LICENSE

@@ -54,7 +54,7 @@ Steele-Idem, which is also distributed under the MIT License:
 
 ---
 
-`src/attrSelector.ts`'s `cssEscapeIdent` adapts the CSS identifier escaping of
+`src/attr.ts`'s `cssEscapeIdent` adapts the CSS identifier escaping of
 the [CSS.escape polyfill](https://github.com/mathiasbynens/CSS.escape) by
 Mathias Bynens, which is also distributed under the MIT License:
 

package/README.md

@@ -4,60 +4,86 @@
 
 <h1 align="center">Kerf</h1>
 
-<p align="center"><em>The smallest cut.</em></p>
+<p align="center"><em>A tiny reactive UI framework. The smallest cut.</em></p>
 
 <p align="center">
   <a href="https://brianwestphal.github.io/kerf/"><strong>brianwestphal.github.io/kerf</strong></a> — docs · examples · live demo
 </p>
 
+<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/npm/l/kerfjs.svg" alt="MIT license" />
+  <img src="https://img.shields.io/badge/types-included-3178c6.svg" alt="TypeScript types included" />
+</p>
+
 ---
 
-> Introducing Kerf.
-> The smallest cut.
->
 > ~12 KB. No virtual DOM. No compiler. No magic.
 > Reactive UI that touches only the bytes that changed.
 
 ```ts
-import { signal, mount } from 'kerfjs';
+import { signal, mount, delegate } from 'kerfjs';
 
 const count = signal(0);
+const app = document.getElementById('app')!;
 
-mount(document.getElementById('app')!, () => (
+mount(app, () => (
   <div>
     <button data-action="inc">+</button>
     <span>{count.value}</span>
   </div>
 ));
+
+delegate(app, 'click', '[data-action="inc"]', () => count.value++);
 ```
 
 That's it. Your JSX renders to HTML strings, kerf's native diff applies the minimum DOM mutations to make the live tree match, and signals re-run the render only when something they read actually changed.
 
 Here's the whole development loop — write a component, run the dev server, click around, edit, watch the browser pick it up:
 
-[![Animated coding session: a counter component is typed line by line into an editor, npm run dev starts in a terminal and the localhost link is clicked, the running app is clicked in a browser, then back in the editor a computed class is added — selecting "btn" and typing a bound {cls} hole — and the browser shows the button change color at the fifth click](https://brianwestphal.github.io/kerf/demos/getting-started.svg)](https://brianwestphal.github.io/kerf/getting-started/)
+[![Animated demo: coding a kerf counter in an editor, running the dev server, then hot-reloading a class change in the browser](https://brianwestphal.github.io/kerf/demos/getting-started.svg)](https://brianwestphal.github.io/kerf/getting-started/)
+**[Quick start](#quick-start) · [Why kerf](#why-kerf) · [Quick tour](#quick-tour) · [Docs & examples](https://brianwestphal.github.io/kerf/)**
 
-## Why Kerf
+## Quick start
+
+```bash
+npm install kerfjs
+```
+
+For an existing project, install the AI guidance, strict TypeScript/ESLint
+feedback, and package scripts with a reviewed dry run:
+
+```bash
+npx kerfjs setup                 # inspect a value-level plan
+npx kerfjs setup --write --yes   # apply it
+```
 
-1. **Small bundle.** ~12 KB minified + gzipped including `@preact/signals-core` (~13 KB with `arraySignal`). One runtime dependency. No virtual DOM, no scheduler, no concurrent-mode machinery. On the official [krausest js-framework-benchmark](https://krausest.github.io/js-framework-benchmark/current.html) — where kerf is a listed entry, measured on the same reference machine as every competitor ([local mirror](./bench/results.md)) — kerf is in the same cluster as Vue, vanjs, and Lit on most operations; Solid's compiler leads the update-path benchmarks (notably `partial update`), which kerf doesn't try to match by design — no compiler.
+The command detects core versus `@kerfjs/ui`, supports deterministic npm,
+pnpm, and Yarn workspace selection plus manager-correct offline installs, and
+never adds UI to a core-only project. See
+[`docs/24-ai-first-setup.md`](./docs/24-ai-first-setup.md).
 
-2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it *is* the DOM.
+```jsonc
+// tsconfig.json — point JSX at kerf
+{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "kerfjs" } }
+```
 
-3. **Values bind, structure re-renders.** Hand a signal *itself* into a JSX hole — `class={selectedId}` or `{status}` — and kerf binds that one node directly: when the signal changes, only that attribute or text node updates, with no render re-run and no list reconcile. A selection flip on a 10,000-row table touches exactly one class. Taken to its logical end: a mount whose render reads no `.value` at all runs **exactly once, forever** — every subsequent update flows through the per-hole bindings. Read `.value` in the render only when the *structure* depends on it (conditionals, list shape).
+Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no extra plugin. New here? Read the [5-minute orientation](https://github.com/brianwestphal/kerf/blob/main/docs/orientation.md), or open a [complete example](https://brianwestphal.github.io/kerf/examples/complete/).
 
-4. **Focus, selection, listeners survive re-renders — even mid-list.** The reconciler morphs instead of rebuilding, so caret position, selection range, IME composition, and delegated listeners survive every re-render. Keyed lists get the same treatment: same-identity rows are updated *in place* rather than recreated, so a row reorder or a single-cell edit no longer blows away focus, scroll, or an in-flight animation the way node replacement does.
+## Why Kerf
 
-5. **Safe by default.** Text and attribute values are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` / script-carrying `data:` dropped), inline `on*` handlers are rejected outright, and the same screening covers the fine-grained bound path — so untrusted data stays inert even when kerf is dropped into someone else's page. The URL screen fails loudly at your desk (throws in development) and degrades safely in the field (warns and drops in production). `raw()` is the explicit, auditable opt-out.
+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.
 
-6. **JSX typed against HTML, not against React.** Tags and attributes are checked at compile time — `<diiv>` and `<input typo />` don't build. The attribute types are derived from the HTML standard rather than another framework's property table, and that distinction has teeth: `draggable` and `spellcheck` are *enumerated* attributes that take the strings `"true"` / `"false"`, so kerf rejects `draggable={true}` rather than quietly emitting markup that means the opposite. Custom elements and web components slot in with one declaration merge.
+2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it _is_ the DOM.
 
-7. **Small public API.** ~18 exports from the main barrel (plus `arraySignal`, the `html` tagged template, and the companion-utility subpaths below — each opt-in, none in the core). No hooks, no lifecycle, no per-instance state. Components are plain functions that return JSX.
+3. **Values bind, structure re-renders.** Hand a signal _itself_ into a JSX hole — `class={selectedId}` — and kerf binds that one node: on change, only that attribute updates, with no render re-run and no list reconcile. Moving selection between rows in a 10,000-row table touches at most the old and new row classes. ([more →](#fine-grained-updates-bind-a-signal-into-a-hole))
 
-8. **Batteries on their own subpaths.** Nine optional, tree-shakeable subpaths cover the patterns every real app otherwise hand-rolls — **`kerfjs/list`** (a keyed list with per-row fine-grained mounts and fixed / app-declared / measured-height viewport **virtualization**, plus a `content-visibility` mode that keeps every row find-in-page-able), **`kerfjs/router`** (a "postcard **router**": route matching, `navigate`, auto `<a>` link interception, and a keyed outlet — the *core* stays router-free, this is opt-in), **`kerfjs/overlay`** (modals, `confirm` / `prompt` / `form` / `choice`, anchored popovers + tooltips, toasts — with opt-in native **top-layer** backing that stacks above any `z-index`), **`kerfjs/async`** (`resource` async-state with a built-in stale-response guard + SWR cache), **`kerfjs/scope`** (dispose-scopes that tie teardown to a DOM node's lifetime), plus `timing`, `remount`, `attach`, and `actions`. None of them grows the ~12 KB core until you import it.
+4. **Focus, selection, and listeners survive re-renders — even mid-list.** The reconciler morphs instead of rebuilding, so caret position, IME composition, scroll, and delegated listeners survive every update; keyed rows are patched in place rather than recreated.
 
-9. **Plain TS, plain JSX, plain ESM.** Drops into anything using esbuild / Vite / tsup. No plugin chain. And with the `html` tagged template (`import { html } from 'kerfjs/html'` — identical runtime semantics to JSX), a CDN / importmap project needs no build step at all.
+5. **Safe by default.** Text and attributes are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` dropped), and inline `on*` handlers are rejected outright — so untrusted data stays inert. `raw()` is the explicit, auditable opt-out.
 
-10. **Grown-up tooling around a tiny core.** An [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) that enforces the hard rules at edit time, an opt-in family of `KERF_DEV_WARN_*` runtime warnings that catch the classic mistakes in development (with zero production cost), a `create-kerf-component` scaffold for publishable component packages, drop-in AI-assistant configs, and side-by-side migration guides for a dozen-plus frameworks — none of which grows the core runtime past ~12 KB.
+**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.
 
 ## When to use Kerf
 
@@ -73,7 +99,7 @@ Here's the whole development loop — write a component, run the dev server, cli
 - Need a full ecosystem (router + forms + data + SSR streaming) → **Next.js / Remix / SolidStart**.
 - Building a deeply componentised design-system app → **React / Solid / Svelte**.
 - Need React Native / cross-platform mobile → **React** (Kerf + Tauri/Electron also covers many of these cases).
-- Building a static site → **Astro** (we use it for *this* project's site).
+- Building a static site → **Astro** (we use it for _this_ project's site).
 - Already invested in a framework where switching cost outweighs the bundle size gain.
 
 ## Quick tour
@@ -133,7 +159,7 @@ delegate(root, 'click', REMOVE.selector, (_e, btn) => { /* … */ }); // in dele
 
 ### Fine-grained updates: bind a signal into a hole
 
-Inside a `mount()`, hand a signal *itself* (not its `.value`) into an attribute or text position and kerf wires that hole straight to the signal — the render function never re-runs and the list reconciler never walks:
+Inside a `mount()`, hand a signal _itself_ (not its `.value`) into an attribute or text position and kerf wires that hole straight to the signal — the render function never re-runs and the list reconciler never walks:
 
 ```ts
 const status = signal('idle');
@@ -147,9 +173,9 @@ mount(root, () => (
 status.value = 'saving';     // updates the class + the text node directly — no re-render
 ```
 
-The headline use is external state driving one spot: a `selectedId` flipping a single row's class inside a 10,000-row `each()` list touches exactly that one node, no reconcile. Works in static content and inside `each()` rows (a row's binding is torn down with the row); outside a `mount()` (SSR / `SafeHtml.toString()`) a bound signal just snapshots its current value.
+The headline use is external state driving a hot spot: a `selectedId` moving between rows inside a 10,000-row `each()` list updates at most the old and new row class attributes, with no reconcile. Works in static content and inside `each()` rows (a row's binding is torn down with the row); outside a `mount()` (SSR / `SafeHtml.toString()`) a bound signal just snapshots its current value.
 
-This is kerf's guiding idiom — *values bind, structure re-renders*: pass the signal itself wherever a hole is just a value, and read `.value` in the render function only where the JSX structure depends on it. A render that reads no `.value` runs exactly once; from then on every update is a direct write to the node it concerns. See [`docs/2-reactivity.md`](./docs/2-reactivity.md) §2.9.
+This is kerf's guiding idiom — _values bind, structure re-renders_: pass the signal itself wherever a hole is just a value, and read `.value` in the render function only where the JSX structure depends on it. A render that reads no `.value` runs exactly once; from then on every update is a direct write to the node it concerns. See [`docs/2-reactivity.md`](./docs/2-reactivity.md) §2.9.
 
 ### Long keyed lists: `arraySignal`
 
@@ -176,11 +202,11 @@ The class lives in its own subpath so apps that don't need it shed ~1 KB. Reads
 `mount()` wraps `effect()` so the render re-runs on signal changes. Sometimes you have a freshly-built template and an already-populated element and you just want to reconcile them once — no subscription, no re-render loop. That's `morph`:
 
 ```ts
-import { morph, raw } from 'kerfjs';
+import { morph, raw } from "kerfjs";
 
-morph(liveCard, freshlyBuiltCardEl);                     // Element template
-morph(liveCard, '<article class="card">…</article>');    // raw HTML string
-morph(liveCard, raw(htmlFromServer));                    // SafeHtml
+morph(liveCard, freshlyBuiltCardEl); // Element template
+morph(liveCard, '<article class="card">…</article>'); // raw HTML string
+morph(liveCard, raw(htmlFromServer)); // SafeHtml
 ```
 
 Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip-children`, `data-morph-preserve`, focused-input value + selection preservation, the `<details>` / `<dialog>` user-agent-owned `open` rule all carry over. Use it for SSR-fragment hydration, page-refresh diffs, third-party widget remounts. See [`docs/4-render.md`](./docs/4-render.md) §4.4.3.
@@ -191,14 +217,19 @@ 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';
-
-  const items = signal([{ id: 1, label: 'no build step' }]);
-
-  mount(document.getElementById('app'), () => html`
-    <ul>${each(items.value, (i) => html`<li id="${i.id}">${i.label}</li>`)}</ul>
-  `);
+  import { signal, mount, each } from "https://esm.sh/kerfjs@4";
+  import { html } from "https://esm.sh/kerfjs@4/html";
+
+  const items = signal([{ id: 1, label: "no build step" }]);
+
+  mount(
+    document.getElementById("app"),
+    () => html`
+      <ul>
+        ${each(items.value, (i) => html`<li id="${i.id}">${i.label}</li>`)}
+      </ul>
+    `,
+  );
 </script>
 ```
 
@@ -227,7 +258,7 @@ const list = bindList(scrollEl, messages, {
 observeRowHeights(list); // one ResizeObserver → kerf anchor-corrects scroll
 ```
 
-And a whole client-side router in one call — `kerfjs/router`, the "postcard router." A route table, a keyed `outlet()`, and automatic `<a href>` interception; the *core* stays router-free (this is opt-in):
+And a whole client-side router in one call — `kerfjs/router`, the "postcard router." A route table, a keyed `outlet()`, and automatic `<a href>` interception; the _core_ stays router-free (this is opt-in):
 
 ```ts
 import { createRouter } from 'kerfjs/router';
@@ -247,21 +278,9 @@ mount(app, () => <div><nav>{/* <a href> links, auto-intercepted */}</nav>{router
 
 Each subpath adds nothing to the main barrel until it's imported. See [`docs/8-api-reference.md`](./docs/8-api-reference.md) for the full list (`list`, `router`, `overlay`, `scope`, `async`, `timing`, `remount`, `attach`, `actions`).
 
-## Install
+## Optional tooling
 
-```bash
-npm install kerfjs
-```
-
-```jsonc
-// tsconfig.json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "kerfjs"
-  }
-}
-```
+Install and JSX setup are in [Quick start](#quick-start) above. These companion packages are opt-in.
 
 ### Optional: `eslint-plugin-kerfjs`
 
@@ -273,7 +292,7 @@ npm install --save-dev eslint-plugin-kerfjs
 
 ```js
 // eslint.config.js (flat config, ESLint v9+)
-import kerfjs from 'eslint-plugin-kerfjs';
+import kerfjs from "eslint-plugin-kerfjs";
 export default [kerfjs.configs.recommended];
 ```
 
@@ -281,7 +300,7 @@ Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwes
 
 ### Optional: `create-kerf-component`
 
-Building a reusable component package? Scaffold one that already follows kerf's hard packaging rules (kerfjs as a peer dependency and `external` in the build, ESM + `.d.ts`, `jsxImportSource: "kerfjs"`, subpath exports) plus an example component showing per-instance state via a factory and a `wire(root)` delegation disposer:
+Building a reusable component package? Scaffold one that already follows kerf's hard packaging rules (kerfjs as a peer dependency and `external` in the build, ESM + `.d.ts`, `jsxImportSource: "kerfjs"`, subpath exports), includes an example component showing per-instance state via a factory and a `wire(root)` delegation disposer, and generates checked package-qualified AI component metadata from explicit author decisions:
 
 ```bash
 npm create kerf-component@latest my-widgets
@@ -296,15 +315,15 @@ 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`)
 - **ESLint plugin:** [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — `eslint-plugin-kerfjs`; eight rules (four hard-rule errors + four warns: `require-delegate-disposer`, `prefer-attr-selector`, `no-raw-with-dynamic-arg`, `ai-assistant-configs`) at edit time (source: [`eslint-plugin/`](./eslint-plugin/))
-- **Component scaffold:** `npm create kerf-component@latest <dir>` — `create-kerf-component`; generates a publishable component package with the hard packaging rules pre-wired (source: [`create-kerf-component/`](./create-kerf-component/))
+- **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)
 
 ## Why "kerf"?
 
-A *kerf* is the narrow strip of material a saw blade removes when cutting — the smallest possible cut. The framework's job is the same: apply the smallest possible mutation to update your DOM.
+A _kerf_ is the narrow strip of material a saw blade removes when cutting — the smallest possible cut. The framework's job is the same: apply the smallest possible mutation to update your DOM.
 
-(And yes, ~~kerformance~~ → *performance* jokes were written. They were also rejected.)
+(And yes, ~~kerformance~~ → _performance_ jokes were written. They were also rejected.)
 
 ## Status
 

package/ai/cursorrules

@@ -1,8 +1,13 @@
-<!-- kerf-skill-version: 1.14.2 -->
+<!-- kerf-skill-version: 1.20.0 -->
+
 # kerf.cursorrules — rules for building apps with kerf
+
 #
+
 # Drop this file into your project as `.cursorrules` (Cursor will pick it
+
 # up automatically) when you're using kerf (https://github.com/brianwestphal/kerf).
+
 # 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.
@@ -17,45 +22,100 @@ You are writing a UI in kerf — a ~12 KB reactive framework (~13 KB with `array
   - **A component package must NEVER import `kerfjs/dev`.** The hooks are process-global, so installing them is the consuming app's decision — a library that does it forces the diagnostics (and the chunk) on every consumer. Put the import in your demo page or test harness instead.
 - Recommended: also install `eslint-plugin-kerfjs` (`npm install --save-dev eslint-plugin-kerfjs`) and add `kerfjs.configs.recommended` to the project's eslint config. It enforces five of the hard rules below (no inline JSX event handlers, require `data-key` in `each()`, capture `delegate()` disposers, no nested `mount()`, prefer module JSX augmentation) at edit time so violations surface as IDE squiggles before any code runs.
 
+## Optional first-party UI
+
+Install `@kerfjs/ui` for shared toolbars, menu rows, controlled tab bars, headers/value tables,
+resizable regions, selects, banners, empty states, and loading indicators.
+Import visual components from explicit subpaths so a CSS-aware browser bundler
+includes only their reachable styles. The root barrel and
+`@kerfjs/ui/unstyled` are CSS-free; pair the barrel with `styles.css` only when
+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
+`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
+trailing native buttons, and keep its `label`, `icon`, and
+`trailingActionIcon` SafeHtml slots free of controls.
+
+Wire emitted `data-action` hooks at the mount root and retain disposers.
+`wireResizableRegions()` and `wireTabBars()` are eventful helpers and return
+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
+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.
+
+For Web Awesome's broader free component set, import the CSS-only
+`@kerfjs/ui/webawesome.css` theme once, then import only each Web Awesome
+component module the app renders. The theme registers no component JavaScript
+and remains overridable through later or scoped `--wa-*` values.
+
+`Select` is pure markup until the app explicitly imports
+`@kerfjs/ui/select/register`. Do that once in the application entry that uses
+Select; never hide registration inside a component. Web Awesome is an optional
+peer and stays out of bundles that use neither Select nor the Web Awesome theme. More detail ships at
+`node_modules/@kerfjs/ui/ai/skill.md`.
+
 ## Public API — one import path
 
 ```ts
 import {
-  signal, computed, effect, batch,    // reactivity
-  defineStore, resetAllStores,        // stores
-  mount, morph, each,                 // render (reactive + one-shot) + keyed list
-  delegate, delegateCapture,          // events
-  toElement,                          // direct JSX → DOM Element (or DocumentFragment for multi-root)
-  SafeHtml, isSafeHtml, raw, Fragment,
-} from 'kerfjs';
+  signal,
+  computed,
+  effect,
+  batch, // reactivity
+  defineStore,
+  resetAllStores, // stores
+  mount,
+  morph,
+  each, // render (reactive + one-shot) + keyed list
+  delegate,
+  delegateCapture, // events
+  toElement, // direct JSX → DOM Element (or DocumentFragment for multi-root)
+  SafeHtml,
+  isSafeHtml,
+  raw,
+  Fragment,
+} from "kerfjs";
 
 // Optional, only when you need granular collection updates:
-import { arraySignal } from 'kerfjs/array-signal';
+import { arraySignal } from "kerfjs/array-signal";
 
 // Development diagnostics — gate with YOUR build's dev flag, in YOUR code.
-if (import.meta.env.DEV) await import('kerfjs/dev');
+if (import.meta.env.DEV) await import("kerfjs/dev");
 ```
 
-| Export | Use |
-| --- | --- |
-| `signal(initial)` | atomic reactive state; read/write via `.value` |
-| `computed(fn)` | derived value (read-only) |
-| `effect(fn)` | side effect that re-runs on signal change |
-| `batch(fn)` | coalesce multiple writes into one re-run |
-| `defineStore({initial, actions})` | named multi-consumer state |
-| `resetAllStores()` | reset every store (test teardown) |
-| `mount(el, render)` | bind reactive render to a DOM element; returns a disposer |
-| `morph(liveRoot, template)` | one-shot reconcile against an already-populated element (SSR hydration, page-refresh diffs). Template can be `Element`, `SafeHtml`, or HTML string |
-| `each(items, render, cacheKey?)` | keyed list iteration; per-row memoization on object identity (+ optional cacheKey — a passive comparator for external state). Distinct from `data-key` on the rendered element |
-| `each(items, render, { cacheKey, key })` | same, options form. **`key` gives the list a stable identity** — required whenever a *conditional* list can render before this one, else kerf rebuilds this list and its rows lose focus/scroll/IME. A keyed list takes no positional slot, so keying the conditional list usually fixes its siblings too |
-| `delegate(root, type, sel, h)` | one listener at the root, walks `closest(selector)` from target |
-| `delegateCapture(root, type, sel, h, opts?)` | capture-phase escape hatch; `closest()` walk-up by default (same as `delegate`); pass `{ match: 'direct' }` for strict `target.matches()` |
-| `attr(name, value)` | pre-computed `AttrSpec<N,V>` — `.selector` for `delegate()`, `.attrs` to spread into JSX (rename-safe) |
-| `attr(name)` | dynamic factory — `attr<N,V=string>(name)` returns `(value: V) => { readonly [name]: V }`; both generics off → N inferred, V defaults to string; specify both to constrain values |
-| `toElement(jsx)` | parse JSX into a DOM node (SVG-aware). Single-root → `Element`; multi-root (`<><svg/> label</>`, two icons side by side) → `DocumentFragment` that `appendChild`/`replaceChildren`/`append` inlines into the parent. |
-| `raw(html)` | inject pre-escaped HTML |
-| `arraySignal(initial?)` | granular keyed-list signal at `kerfjs/array-signal` subpath; `each()` reconciles in O(patches) |
-| `` html`…` `` | tagged template at `kerfjs/html` subpath — JSX-identical runtime semantics with NO build step (CDN/importmap projects). Real HTML attribute names (`class`, not `className`); holes only in text positions or as a COMPLETE attribute value (`attr=${v}` / `attr="${v}"`) |
+| Export                                       | Use                                                                                                                                                                                                                                                                                                       |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `signal(initial)`                            | atomic reactive state; read/write via `.value`                                                                                                                                                                                                                                                            |
+| `computed(fn)`                               | derived value (read-only)                                                                                                                                                                                                                                                                                 |
+| `effect(fn)`                                 | side effect that re-runs on signal change                                                                                                                                                                                                                                                                 |
+| `batch(fn)`                                  | coalesce multiple writes into one re-run                                                                                                                                                                                                                                                                  |
+| `defineStore({initial, actions})`            | named multi-consumer state                                                                                                                                                                                                                                                                                |
+| `resetAllStores()`                           | reset every store (test teardown)                                                                                                                                                                                                                                                                         |
+| `mount(el, render)`                          | bind reactive render to a DOM element; returns a disposer                                                                                                                                                                                                                                                 |
+| `morph(liveRoot, template)`                  | one-shot reconcile against an already-populated element (SSR hydration, page-refresh diffs). Template can be `Element`, `SafeHtml`, or HTML string                                                                                                                                                        |
+| `each(items, render, cacheKey?)`             | keyed list iteration; per-row memoization on object identity (+ optional cacheKey — a passive comparator for external state). Distinct from `data-key` on the rendered element                                                                                                                            |
+| `each(items, render, { cacheKey, key })`     | same, options form. **`key` gives the list a stable identity** — required whenever a _conditional_ list can render before this one, else kerf rebuilds this list and its rows lose focus/scroll/IME. A keyed list takes no positional slot, so keying the conditional list usually fixes its siblings too |
+| `delegate(root, type, sel, h)`               | one listener at the root, walks `closest(selector)` from target                                                                                                                                                                                                                                           |
+| `delegateCapture(root, type, sel, h, opts?)` | capture-phase escape hatch; `closest()` walk-up by default (same as `delegate`); pass `{ match: 'direct' }` for strict `target.matches()`                                                                                                                                                                 |
+| `attr(name, value)`                          | pre-computed `AttrSpec<N,V>` — `.selector` for `delegate()`, `.attrs` to spread into JSX (rename-safe)                                                                                                                                                                                                    |
+| `attr(name)`                                 | dynamic factory — `attr<N,V=string>(name)` returns `(value: V) => { readonly [name]: V }`; both generics off → N inferred, V defaults to string; specify both to constrain values                                                                                                                         |
+| `toElement(jsx)`                             | parse JSX into a DOM node (SVG-aware). Single-root → `Element`; multi-root (`<><svg/> label</>`, two icons side by side) → `DocumentFragment` that `appendChild`/`replaceChildren`/`append` inlines into the parent.                                                                                      |
+| `raw(html)`                                  | inject pre-escaped HTML                                                                                                                                                                                                                                                                                   |
+| `arraySignal(initial?)`                      | granular keyed-list signal at `kerfjs/array-signal` subpath; `each()` reconciles in O(patches)                                                                                                                                                                                                            |
+| `` html`…` ``                                | tagged template at `kerfjs/html` subpath — JSX-identical runtime semantics with NO build step (CDN/importmap projects). Real HTML attribute names (`class`, not `className`); holes only in text positions or as a COMPLETE attribute value (`attr=${v}` / `attr="${v}"`)                                 |
 
 ## Hard rules — get these right on the first try
 
@@ -66,7 +126,7 @@ if (import.meta.env.DEV) await import('kerfjs/dev');
 5. **Capture the `delegate()` / `delegateCapture()` disposer** whenever the registration's scope is shorter than the page. Both helpers return `() => void`; the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state). Discarding the disposer on a transient root (modal, route view, mount swap, dynamic widget) leaks the listener AND the app graph it captures; re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you. Safe to discard only when the registration is truly page-lifetime (root is `document.body` or equivalent, attached once at startup, never torn down).
 6. **One `mount()` per root.** Don't nest. Compose with plain functions that return JSX.
 7. **No `<MyComponent />` semantics with hooks.** Components are plain functions returning JSX. State lives in module-scope signals or stores, never in component closures.
-8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX *structure* depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` will NOT re-render. Bind a STABLE signal/computed instance per hole (a `computed` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (`KERF_DEV_WARN_STALE_BINDING=1` detects it). Endpoint: a render reading NO `.value` runs exactly once — a fully bound mount never re-renders; `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` flags re-renders that could have been bindings.
+8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX _structure_ depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` will NOT re-render. Bind a STABLE signal/computed instance per hole (a `computed` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (`KERF_DEV_WARN_STALE_BINDING=1` detects it). Endpoint: a render reading NO `.value` runs exactly once — a fully bound mount never re-renders; `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` flags re-renders that could have been bindings.
 9. **Store actions receive `(set, get)`, not `(state)`.** `set(next)` replaces state; mutating `get()` does nothing.
 10. **Use `data-action` attributes, not inline `onClick`.** Inline handlers are NOT supported by the JSX → string runtime; delegate from the root instead.
 11. **`arraySignal` is opt-in for long keyed lists** where most updates are pointwise (single-row edits, append-to-end). For short lists / filter+sort pipelines, plain `signal` + `each(items.value, ...)` is simpler and equally fast.
@@ -79,22 +139,26 @@ if (import.meta.env.DEV) await import('kerfjs/dev');
 When deciding which primitive to reach for, work down the axes:
 
 **Events.**
+
 - Originates inside the mount tree → `delegate(rootEl, type, sel, handler)`. Originates outside (window-level keyboard, online/offline, beforeunload) → native `window.addEventListener` at module top-level.
 - Gesture that needs to follow an element after press (drag, draw, resize) → at the start event, `el.setPointerCapture(e.pointerId)`. Subsequent `pointermove` / `pointerup` redirect to the captured element and `delegate(rootEl, 'pointermove', '[data-card]', …)` still picks them up. Don't reach for `window.addEventListener` for in-mount-tree gestures.
 - Well-known non-bubbler (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`, `mouseleave`) → still `delegate()`; it auto-promotes to capture. Custom non-bubblers or capture-phase interception → `delegateCapture()` (also `closest()`-matched by default). Need strict element-match? Add `{ match: 'direct' }` on either helper.
 
 **Lists.**
+
 - Items change across renders (todos, chat messages, table rows) → `each(items, render)`.
 - Static structural enumeration whose row render reads signals → `STATIC.map(item => <jsx/>)`. Inner `each(item.children, …)` still gets keyed reconcile.
 - Long list with point-wise mutations → `arraySignal` + `each(arraySig, render)` for O(patches) updates.
 
 **Side effects / imperative DOM.**
+
 - Library-owned subtree survives across renders → `data-morph-skip` on host.
 - Host attributes morph but subtree preserved → `data-morph-skip-children`.
 - Imperatively-injected element survives the trailing-removal pass → `data-morph-preserve`.
 - Focused input / contenteditable caret survives re-renders → automatic; no opt-in.
 
 **Raw HTML.**
+
 - User-controlled HTML → sanitize first (DOMPurify) then `raw(sanitized)`.
 - Author-controlled trusted HTML → `raw(html)` directly.
 - Dangerous URLs (`javascript:`/`vbscript:`/script-executing `data:`) on `href`/`src`/`xlink:href`/`formaction`/`action`/`data` are dropped — kerf THROWS in dev, WARNS + drops in prod. Sanitize user URLs upstream; wrap an intentional trusted one in `raw(url)` to bypass the screen in both modes. The `javascript:` no-op placeholders (`javascript:void(0)`, `javascript:;`, …) are allowed — they're the placeholder-link idiom, matched whole so nothing can ride along.
@@ -107,20 +171,27 @@ When deciding which primitive to reach for, work down the axes:
 // updates that one node directly with no render re-run; read `.value` only
 // when the JSX STRUCTURE depends on the signal (conditionals, list shape).
 const count = signal(0);
-const ACTIONS = { inc: attr('data-action', 'inc') } as const satisfies Record<string, AttrSpec<'data-action'>>;
+const ACTIONS = { inc: attr("data-action", "inc") } as const satisfies Record<
+  string,
+  AttrSpec<"data-action">
+>;
 
-mount(document.getElementById('app')!, () => (
+mount(document.getElementById("app")!, () => (
   <div>
     <button {...ACTIONS.inc.attrs}>+</button>
     <span>{count}</span>
   </div>
 ));
-delegate(rootEl, 'click', ACTIONS.inc.selector, () => { count.value += 1; });
+delegate(rootEl, "click", ACTIONS.inc.selector, () => {
+  count.value += 1;
+});
 
 // Keyed list with per-item memoization
 mount(listEl, () => (
   <ul>
-    {each(rows.value, (row) => <li data-key={row.id}>{row.label}</li>)}
+    {each(rows.value, (row) => (
+      <li data-key={row.id}>{row.label}</li>
+    ))}
   </ul>
 ));
 
@@ -128,8 +199,8 @@ mount(listEl, () => (
 const cart = defineStore({
   initial: () => ({ items: [] as string[] }),
   actions: (set, get) => ({
-    add:   (id: string) => set({ items: [...get().items, id] }),
-    clear: ()           => set({ items: [] }),
+    add: (id: string) => set({ items: [...get().items, id] }),
+    clear: () => set({ items: [] }),
   }),
 });
 
@@ -139,11 +210,16 @@ morph(liveCard, '<article class="card">…</article>');
 // No build step (CDN / importmap): the html tagged template instead of JSX.
 // Same runtime semantics as JSX; write real HTML attribute names; a hole must
 // be a text position or a COMPLETE attribute value (partial values throw).
-import { html } from 'kerfjs/html';
-mount(rootEl, () => html`
-  <div class="${cls}">Count: ${count}</div>
-  <ul>${each(rows.value, (row) => html`<li data-key="${row.id}">${row.label}</li>`)}</ul>
-`);
+import { html } from "kerfjs/html";
+mount(
+  rootEl,
+  () => html`
+    <div class="${cls}">Count: ${count}</div>
+    <ul>
+      ${each(rows.value, (row) => html`<li data-key="${row.id}">${row.label}</li>`)}
+    </ul>
+  `,
+);
 
 // Fine-grained binding (opt-in): pass the signal/computed ITSELF into a hole
 // so a change updates ONLY that node (no render re-run, no reconcile). For a
@@ -152,9 +228,15 @@ mount(rootEl, () => html`
 const selectedId = signal<number | null>(null);
 mount(listEl, () => (
   <ul>
-    {each(rows.value, (row) => (
-      <li class={computed(() => (row.id === selectedId.value ? 'sel' : ''))}>{row.label}</li>
-    ), (row) => row.id)}
+    {each(
+      rows.value,
+      (row) => (
+        <li class={computed(() => (row.id === selectedId.value ? "sel" : ""))}>
+          {row.label}
+        </li>
+      ),
+      (row) => row.id,
+    )}
   </ul>
 ));
 ```
@@ -170,10 +252,10 @@ mount(listEl, () => (
 - SVG renders as broken / namespaceless markup → use `mount` (HTML path) or `toElement` (SVG-aware), not `innerHTML`.
 - Library widget destroyed on every render → wrap host in `data-morph-skip`; mount the library imperatively after first render.
 - `each(): row render at index N produced K top-level elements` → wrap multiple roots in one parent.
-- Drag/drop / state change has no visible effect, only stuff *outside* `each()` updates → you used `each(STATIC_ARRAY, …)` whose row render reads signals. Replace the outer with `STATIC_ARRAY.map(...)`; keep inner `each()` for the dynamic sub-list. See Hard Rule 14.
-- Row-enter CSS animation no longer replays when only a row's *content* changed (kerf ≥ 0.15.0) → 0.15.0+ morphs a same-identity, same-position row *in place* instead of recreating its node, so a mount-keyed `@keyframes` never re-triggers on a content-only update (≤ 0.14.x recreated the node, so it fired; the intentional flip side is that focus, scroll, IME, and in-progress transitions now survive). Key the animation on a state-class toggle, not element creation; to force a remount, churn the row's identity (new object ref / `data-key`).
+- Drag/drop / state change has no visible effect, only stuff _outside_ `each()` updates → you used `each(STATIC_ARRAY, …)` whose row render reads signals. Replace the outer with `STATIC_ARRAY.map(...)`; keep inner `each()` for the dynamic sub-list. See Hard Rule 14.
+- Row-enter CSS animation no longer replays when only a row's _content_ changed (kerf ≥ 0.15.0) → 0.15.0+ morphs a same-identity, same-position row _in place_ instead of recreating its node, so a mount-keyed `@keyframes` never re-triggers on a content-only update (≤ 0.14.x recreated the node, so it fired; the intentional flip side is that focus, scroll, IME, and in-progress transitions now survive). Key the animation on a state-class toggle, not element creation; to force a remount, churn the row's identity (new object ref / `data-key`).
 - Want a hot spot to update without re-running the whole render → fine-grained binding: pass the signal/`computed` ITSELF into the attr/text hole (`class={computed(() => …)}`), not `.value`. Use `computed()` not a bare `() => …` (memoization keeps a shared-signal flip to ~O(changed nodes)). Opt-in per hole. Limit: a bound hole depending on the row's OWN mutated data goes stale on a granular in-place update — use plain interpolation there.
-- `` html`` ``: partial attribute values are not supported → in `kerfjs/html` templates a hole must be the COMPLETE attribute value. Replace `class="a ${b}"` with a pre-built string (`` class="${`a ${b}`}" ``) or, for a bound attribute, `class="${computed(() => `a ${b.value}`)}"`.
+- ` html` ``: partial attribute values are not supported → in `kerfjs/html` templates a hole must be the COMPLETE attribute value. Replace `class="a ${b}"` with a pre-built string (`` class="${`a ${b}`}" ``) or, for a bound attribute, `class="${computed(() => `a ${b.value}`)}"`.
 - An `each()` list's rows lose focus / scroll / typing state when an unrelated conditional list above them appears or disappears (kerf warns in dev) → lists without a key are identified by position among the render's `each()` calls, so adding/removing one above shifts this list's identity and kerf rebuilds it. Give the lists stable keys: `each(items, render, { key: 'results' })`; keying just the conditional list is usually enough.
 - Keyed `each()` list suddenly renders zero rows — only its `<!--kf-list:N-->` marker — with no errors, and it never recovers (kerfjs ≤ 2.0.1) → a conditionally-rendered sibling BEFORE the list (possibly higher in the tree, e.g. an error banner) was removed that render; older kerfjs rebuilt the shifted list container from the template, permanently detaching the list's internal binding. Upgrade kerfjs (fixed after 2.0.1 — the morph now moves the shifted container up in place, keeping node identity). On older versions, keep the structure before the list stable: wrap the conditional in an always-present container (`<div class="banners">{cond ? <div/> : ''}</div>`).
 - A numbered / zebra-striped / "N of M" `each()` list shows the wrong number on rows that MOVED (reorder, or non-tail insert/remove), while unmoved rows look right → the render fn's `index` argument is NOT part of the memo key (only item identity + `cacheKey` + content version are), so a row that keeps identity but changes position keeps HTML rendered at its old index. Fold the index into the memo key: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `KERF_DEV_WARN_STALE_INDEX=1`.