kerfjs 4.4.1 → 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

@@ -51,25 +51,40 @@ Here's the whole development loop — write a component, run the dev server, cli
 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
+```
+
+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).
+
 ```jsonc
 // tsconfig.json — point JSX at kerf
 { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "kerfjs" } }
 ```
 
 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/).
+
 ## 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.
 
-2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it *is* the DOM.
+2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it _is_ the DOM.
 
-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. A selection flip on a 10,000-row table touches exactly one class. ([more →](#fine-grained-updates-bind-a-signal-into-a-hole))
+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))
 
 4. **Focus, selection, and listeners survive re-renders — even mid-list.** The reconciler morphs instead of rebuilding, so caret position, IME composition, scroll, and delegated listeners survive every update; keyed rows are patched in place rather than recreated.
 
 5. **Safe by default.** Text and attributes are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` dropped), and inline `on*` handlers are rejected outright — so untrusted data stays inert. `raw()` is the explicit, auditable opt-out.
 
-**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 + a `create-kerf-component` scaffold · plain TS/JSX/ESM that drops into esbuild / Vite / tsup — or **no** build at all via the `html` tagged template.
+**Plus, nothing you don't ask for:** JSX typed against the HTML standard (not React's props) · a ~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
 
 - **Hybrid desktop apps (Tauri / Electron)** — small bundle, predictable diff, debuggable runtime; ideal for the embedded webview.
@@ -84,7 +99,7 @@ Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no ext
 - 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
@@ -144,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');
@@ -158,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`
 
@@ -187,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.
@@ -202,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>
 ```
 
@@ -238,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';
@@ -272,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];
 ```
 
@@ -280,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
@@ -295,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`.

package/ai/manifest.json

@@ -1,21 +1,79 @@
 {
-  "kerfjsVersion": "4.4.1",
+  "kerfjsVersion": "4.5.0-beta.1",
   "files": [
     {
       "name": "skill",
       "source": "kerf.claude-skill.md",
       "bundle": "ai/skill.md",
       "dest": ".claude/skills/kerf-app/SKILL.md",
-      "version": "1.14.2",
-      "sha256": "3a9e4dd8d4ecfcf963e8d16f98ea98800a3c243f11bbb829134d8f7792a8d06d"
+      "version": "1.22.0",
+      "sha256": "dc99b0ca5e911be11cbfa2ae515c0e161a414a5185895069535c41ba56664e70",
+      "history": {
+        "1.0.0": "bef982cb743fd4c73e666ee5cf774112e57c93ebb13b24bbacbf08577db0930a",
+        "1.1.0": "f2aadb21e33dd389028951ae1ecbd9f8ba68648b3c5beba43fb4dfa2ab29f195",
+        "1.1.1": "f163d33ce1007dd24551503398160881377eedad1fb4f6d37d9d9b8c8100f143",
+        "1.2.0": "76550ec18da8e063123bfabc575d9ad3a43583d41a498c6e4b4be03c17dbd188",
+        "1.2.1": "290e57bfc9b4af0630c586770e61063742d5f5fac3d75406f5acbc2e5322440f",
+        "1.3.0": "789cfd9bbe0fa8a01b779595912b7fef569b3c021be412d35f453476e576bac6",
+        "1.4.0": "2c42d476174847cfca1aa941c1026195b6a1786074fa9c2bd0b5a287639543b7",
+        "1.5.0": "c4fae8806907e79507ac095a2e6fed1761ddf61e5c9bfa5ec28719897ea56613",
+        "1.6.0": "797b48ef0736b9113df9e300ab47109c83c5cdd582f110d0cde7f388a37f4a26",
+        "1.7.0": "033c6e538d3a48f36c52a1ba154c6c7782f6c7cca9399adee0fbd519cfaf5919",
+        "1.8.0": "76b8a88bc7aaf9d50e6f3eee7b57a976b3279127f5d4970599aef1f839a06655",
+        "1.8.1": "32b8239399d94b014927563c3ff4251df97c36dc31478d832dba5a4309c221fb",
+        "1.9.0": "3225206e0339a8f6e2f9c728b76cf22728983f5810d614eab6224f16c8f9c6d4",
+        "1.10.0": "4b8e73a44fba060cb2fc4c01ed87f3853ac13906ee759e982c5c140025dfd493",
+        "1.11.0": "4d7f6099cd47f76a9e85cfe953886eaeb650eeb11a540cbac45104362b32eda5",
+        "1.12.0": "7acf72fd1b2781054520cc5af66cd73ee2f44b43c643e981f1f7a92ead60f747",
+        "1.13.0": "6f9a7d00ff6ad4799c51b52da613dfc5c11f09abaf9b6a3b9ca960f05f30b927",
+        "1.14.0": "15786c4e2b5f5d51dcd17d973f29aef8348faaa1410e40d86259be599fb459c9",
+        "1.14.1": "15573973dabf6d53f67e51696c276732fb1d17a59bb843300e88200389305b1f",
+        "1.14.2": "3a9e4dd8d4ecfcf963e8d16f98ea98800a3c243f11bbb829134d8f7792a8d06d",
+        "1.15.0": "72db3f328ce4457bbecd31bfab6ee69b2d423d9bee7db8e2a01e7aa3ae369af9",
+        "1.16.0": "0fa5d8ef354059fe7e20843dcd0c6f38234f3018d47856503bf47ddff4541231",
+        "1.17.0": "e0e1f370a97bc94aa33ed7723ebcf0059a9c7613f1083e3b77f0c62aecc108a7",
+        "1.18.0": "d2d092b1e4d4d71012f9ec36921b3f5c1421f0a8b2ced50351d56daa9e35f79b",
+        "1.19.0": "bbbe87446cc4e1be250d27152adfd385431f4498cde320534f65f10f853ab7f9",
+        "1.20.0": "aa88ccdbf969624bbc6cefadba76ada1f090fae436597a7bab564e24c467287f",
+        "1.21.0": "265b747eeb9c3d445c60d66a1109eec42705075b7cd154d107bd79d543c1e7e5",
+        "1.22.0": "dc99b0ca5e911be11cbfa2ae515c0e161a414a5185895069535c41ba56664e70"
+      }
     },
     {
       "name": "cursorrules",
       "source": "kerf.cursorrules",
       "bundle": "ai/cursorrules",
       "dest": ".cursorrules",
-      "version": "1.14.2",
-      "sha256": "09d9f0290fe84d3244e1655c8284c8431b47cdbe220f7161f38bc96fc8ef8ba3"
+      "version": "1.20.0",
+      "sha256": "5e7b8d8ddc41f60220961417c9ae01c193fae045378a10a3e9c96a0e3cf10a03",
+      "history": {
+        "1.0.0": "98f7faff2b7585ef9cc511add42ea5d9bf0cbae8307b066af090e9281136d2ab",
+        "1.1.0": "a2ec8c221dc694c98b81009cd2d99f9159a45fda94585de2f54471b227099eda",
+        "1.1.1": "f28b963171b7c2cbc36823d7220080730cda85a41f105b90e81790c1188e6186",
+        "1.2.0": "dcf2fc03f5dfca3b9bfea8cfefc65ac8ce31e1c601c613e91af69b6195c5e267",
+        "1.2.1": "2fcd5e9e0fd889febdab19bcc7e415c342b10ae81e937852b8280014b8d374e0",
+        "1.3.0": "2524a42cc3b488f8cc3cea736cf5b8d3e57d868c85260342ec50905243aa65f1",
+        "1.4.0": "f2c0fb328d487cc4a64ccd0b671c3385f1a25074c8c5e502c507ee799cd65e80",
+        "1.5.0": "2c012cbffa2fd9f96a3b8cdca48b55e584530ee6e5be73c922d3bb49470b6c31",
+        "1.6.0": "9370876e58ac634936ca321bf5313bb339659cb7c7c1b38a9b10f2bf4b03836d",
+        "1.7.0": "8ce556caf8fa95f783f5423bf882a735fc3ce6b7eb83e823aaa0417b3272af15",
+        "1.8.0": "f91402df009941b4198ea659498f458d2433843d47a3b524b0ca5e2d3d2fc949",
+        "1.8.1": "eed385b8edf3b96e88d8f00ea45ee4146004a74d3f0e495b870a27c137d0ec44",
+        "1.9.0": "c3242e1aa8c5ca51fca3e2e3c3df8e55dffb5d6c7b5bc8d677949d48ff5563cc",
+        "1.10.0": "7adefcc5ab66fcc3e5ae10625d7c762e86ac02ca297648aa58b0b201b35b04f8",
+        "1.11.0": "506c3338ec1c2268912f5eb9530a6af04ad937061281b5ea84529fc8b10486ff",
+        "1.12.0": "48ff3d0f483a9fcd7f57ca20c17c0aadfce0e4a0b39d9e96e964ef9260f782d3",
+        "1.13.0": "3a6bf9b1c74e0be00053faddc2af3c979ba5bb26c11db93bfcb8b1ecbe66284d",
+        "1.14.0": "b83de9cff13789cdebf572f2e98d3d61fdd4f31c7eb237a0a4999b6a1dfe4d9b",
+        "1.14.1": "9d2cc9da69e974a56d79393ad3b3a9d76c068fbd46b392621790a82fc0772d00",
+        "1.14.2": "09d9f0290fe84d3244e1655c8284c8431b47cdbe220f7161f38bc96fc8ef8ba3",
+        "1.15.0": "eece0b3075ceeeec5f6a59393a82c105d28ad1a34374412fbf6a4e0c23d7e8b9",
+        "1.16.0": "49794d543ab1f9112f9f6a1dcdc7aad4347b8965e1b4003bb7884086a02411c3",
+        "1.17.0": "6ad51fb0eec468f584346d1d7b4d1c2eca2cb52b04891b38ba44e93b57eb9e1c",
+        "1.18.0": "de3eea1bc181da629694d19a0817d252a868e4704437fbdd9e923856b8a0890a",
+        "1.19.0": "c5b91e449f6feccaa36a04cb7f8550d3e414eb2795ea6c5dccdf6071206b3261",
+        "1.20.0": "5e7b8d8ddc41f60220961417c9ae01c193fae045378a10a3e9c96a0e3cf10a03"
+      }
     }
   ]
 }