kerfjs 5.0.0-beta.8 → 5.0.0-beta.81

package/README.md

@@ -12,14 +12,14 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/kerfjs"><img src="https://img.shields.io/npm/v/kerfjs.svg" alt="npm version" /></a>
-  <img src="https://img.shields.io/badge/min%2Bgzip-~12%20KB-brightgreen.svg" alt="~12 KB minified and gzipped" />
+  <img src="https://img.shields.io/badge/min%2Bgzip-~13%20KB-brightgreen.svg" alt="~13 KB minified and gzipped" />
   <img src="https://img.shields.io/npm/l/kerfjs.svg" alt="MIT license" />
   <img src="https://img.shields.io/badge/types-included-3178c6.svg" alt="TypeScript types included" />
 </p>
 
 ---
 
-> ~12 KB. No virtual DOM. No compiler. No magic.
+> ~13 KB. No virtual DOM. No compiler. No magic.
 > Reactive UI that touches only the bytes that changed.
 
 ```ts
@@ -31,14 +31,17 @@ const app = document.getElementById('app')!;
 mount(app, () => (
   <div>
     <button data-action="inc">+</button>
-    <span>{count.value}</span>
+    <span>{count}</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.
+That's it. Your JSX renders to HTML strings, and handing the signal itself to
+the text hole binds that one node directly. Structural reads still re-run the
+render, where kerf's native diff applies the minimum DOM mutations needed to
+make the live tree match.
 
 Here's the whole development loop — write a component, run the dev server, click around, edit, watch the browser pick it up:
 
@@ -51,25 +54,42 @@ 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.
+1. **~13 KB in the browser.** ~13 KB minified + gzipped including `@preact/signals-core` (~13 KB with `arraySignal`). The optional setup CLI has its own npm dependencies; they stay out of the browser bundle. No virtual DOM, no scheduler, no concurrent-mode machinery. On the official [krausest benchmark](https://krausest.github.io/js-framework-benchmark/current.html) kerf sits in the same cluster as Vue, Lit, and vanjs; Solid's compiler leads the update-path benchmarks, which kerf doesn't try to match by design — no compiler.
 
-2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it *is* the DOM.
+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. 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))
+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.
+5. **A first-party UI layer when you want one.** `@kerfjs/ui` adds accessible components, responsive application layouts, typed CSS values, and explicit wiring helpers without changing kerf's stateless component model. It is separately installable and tree-shakeable, so the core stays the core. ([tour →](#first-party-ui-separately-installable))
+
+6. **Safe by default.** Text and attributes are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` dropped), and inline `on*` handlers are rejected outright — so untrusted data stays inert. `raw()` is the explicit, auditable opt-out.
+
+**Plus, nothing you don't ask for:** JSX typed against the HTML standard (not React's props) · a small public API with no hooks, lifecycle, or per-instance state · tree-shakeable companion subpaths (`router`, `list`, `overlay`, `async`, …) that stay out of the core until imported · an [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) + opt-in dev warnings + `create-kerf-component` scaffold · plain TS/JSX/ESM that drops into esbuild / Vite / tsup — or **no** build at all via the `html` tagged template.
 
-**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.
@@ -82,9 +102,9 @@ Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no ext
 ### When to reach for something else
 
 - Need a full ecosystem (router + forms + data + SSR streaming) → **Next.js / Remix / SolidStart**.
-- Building a deeply componentised design-system app → **React / Solid / Svelte**.
+- Building a deeply componentized 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 +164,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');
@@ -160,7 +180,7 @@ status.value = 'saving';     // updates the class + the text node directly — n
 
 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,14 +207,15 @@ 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
+// `template` describes liveCard's CHILDREN; liveCard's own attributes are untouched
+morph(liveCard, freshlyBuiltCardEl); // Element template: its child nodes are used
+morph(liveCard, '<h2 class="card-title">…</h2><p>…</p>'); // 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.
+Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip-children`, `data-morph-preserve`, focused-input value + selection preservation, the user-agent-owned `open` rule (`<details>`, `<dialog>`, custom elements) all carry over. Only the live root's children are reconciled — the root's own attributes are never touched. 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.
 
 ### No build step at all: the `html` tagged template
 
@@ -202,22 +223,27 @@ 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@5";
+  import { html } from "https://esm.sh/kerfjs@5/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>
 ```
 
-Nothing is self-hosted — `kerfjs` is on npm, so every ESM CDN (esm.sh, jsDelivr, unpkg) mirrors it automatically. esm.sh works with a direct import as shown; jsDelivr / unpkg want an importmap so the internal `@preact/signals-core` import resolves. Pin to a major (`@4`, as shown — the latest `4.x`) rather than floating on `latest`, or an exact version (`@4.1.0`) for full reproducibility. Attribute names are written verbatim (`class`, not `className`), and holes are only legal in text positions or as a complete attribute value — anything ambiguous throws with an actionable message. See [`docs/6-jsx-runtime.md`](./docs/6-jsx-runtime.md) §6.11 (§6.11.1 for the full CDN / importmap recipes) — or the [live-poll example](https://brianwestphal.github.io/kerf/examples/complete/live-poll/), a complete app served exactly as authored: no bundler ever touches it.
+Nothing is self-hosted — `kerfjs` is on npm, so every ESM CDN (esm.sh, jsDelivr, unpkg) mirrors it automatically. esm.sh works with a direct import as shown; jsDelivr / unpkg want an importmap so the internal `@preact/signals-core` import resolves. Pin to a major (`@5`, as shown) rather than floating on `latest`, or an exact version (`@5.0.0`) for full reproducibility. Attribute names are written verbatim (`class`, not `className`), and holes are only legal in text positions or as a complete attribute value — anything ambiguous throws with an actionable message. See [`docs/6-jsx-runtime.md`](./docs/6-jsx-runtime.md) §6.11 (§6.11.1 for the full CDN / importmap recipes) — or the [live-poll example](https://brianwestphal.github.io/kerf/examples/complete/live-poll/), a complete app served exactly as authored: no bundler ever touches it.
 
 ### Batteries when you need them: the companion subpaths
 
-The core stays tiny because the patterns every real app rebuilds live in optional, tree-shakeable subpaths — a modal you'd otherwise hand-roll (`kerfjs/overlay`), an async-state container with the stale-response race already solved (`kerfjs/async`), a debounce that composes inside the reactive graph (`kerfjs/timing`), teardown tied to a DOM node's lifetime (`kerfjs/scope`). The largest is `kerfjs/list` — a keyed list that mounts each row individually (so a signal one row reads updates just that row) and virtualizes a long viewport, with fixed, app-declared, or measured row heights:
+The core stays tiny because the patterns every real app rebuilds live in optional, tree-shakeable subpaths — a modal you'd otherwise hand-roll (`kerfjs/overlay`), an async-state container with the stale-response race already solved (`kerfjs/async`), a debounce that composes inside the reactive graph (`kerfjs/timing`), and disposer groups with or without a DOM owner (`kerfjs/scope`). The largest is `kerfjs/list` — a keyed list that mounts each row individually (so a signal one row reads updates just that row) and virtualizes a long viewport, with fixed, app-declared, or measured row heights:
 
 ```ts
 import { bindList, observeRowHeights } from 'kerfjs/list';
@@ -238,7 +264,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';
@@ -258,13 +284,45 @@ 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`).
 
+### First-party UI, separately installable
+
+`@kerfjs/ui` is the optional component layer for applications that want a
+coherent interface vocabulary without switching frameworks. Components return
+Kerf `SafeHtml`; the application still owns state and wires behavior explicitly.
+Component subpaths pull in only their reachable CSS, while responsive app
+layouts, typed CSS-value builders, Web Awesome adapters, and the checked
+component catalog stay opt-in.
+
+```bash
+npm install kerfjs @kerfjs/ui
+```
+
+```tsx
+import { mount } from "kerfjs";
+import { ListItem } from "@kerfjs/ui/list-item";
+import { Toolbar } from "@kerfjs/ui/toolbar";
+import { ToolbarText } from "@kerfjs/ui/toolbar-text";
+
+const root = document.getElementById("app")!;
+
+mount(root, () => (
+  <>
+    <Toolbar label="Files" leading={<ToolbarText text="Workspace" />} />
+    <ListItem action="open-file" label="src/main.ts" selected />
+  </>
+));
+```
+
+Start with the [component selection matrix](./ui/docs/component-selection.md),
+or read the complete [`@kerfjs/ui` package guide](./ui/README.md).
+
 ## Optional tooling
 
 Install and JSX setup are in [Quick start](#quick-start) above. These companion packages are opt-in.
 
 ### Optional: `eslint-plugin-kerfjs`
 
-A companion ESLint plugin enforces kerf's hard rules at edit time. Eight rules total: four `error`-level AST rules catch hard-rule violations — inline JSX event handlers, missing `data-key` in `each()`, nested `mount()`, and global `JSX.IntrinsicElements` augmentation — and four `warn`-level rules cover delegate-disposer capture, `attr()` selector rename-safety, `raw()` XSS audit trails, and AI-assistant config hygiene. The plugin is AST-only (no parser-services dependency), so it works with any TypeScript-ESLint setup.
+A companion ESLint plugin enforces kerf's hard rules at edit time. Its eight core rules cover inline JSX event handlers, missing `data-key` in `each()`, nested `mount()`, delegate-disposer capture, `attr()` selector rename-safety, `raw()` XSS audit trails, JSX augmentation, and AI-assistant config hygiene. Six additional UI rules check component ownership, composition, CSS values, application preferences, wiring, and public boundaries when you opt into the UI preset. The plugin requires no TypeScript parser service.
 
 ```bash
 npm install --save-dev eslint-plugin-kerfjs
@@ -272,15 +330,15 @@ 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];
 ```
 
-Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — legacy `.eslintrc` config, per-rule examples, and the rationale for which violations get lint rules vs. dev-warns vs. strict TS.
+Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — flat config, per-rule examples, and the rationale for which violations get lint rules vs. dev-warns vs. strict TS.
 
 ### Optional: `create-kerf-component`
 
-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
@@ -294,16 +352,17 @@ See [`docs/13-component-packages.md`](./docs/13-component-packages.md) for the f
 - **Docs:** [`docs/`](./docs/) — overview · reactivity · stores · render · events · jsx · svg · [API reference](./docs/8-api-reference.md)
 - **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/))
+- **UI package:** [`@kerfjs/ui`](./ui/README.md) — accessible components, responsive app layouts, typed CSS values, Web Awesome adapters, and checked AI-facing component metadata
+- **ESLint plugin:** [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — `eslint-plugin-kerfjs`; eight core rules plus six opt-in UI rules at edit time (source: [`eslint-plugin/`](./eslint-plugin/))
+- **Component scaffold:** `npm create kerf-component@latest <dir>` — `create-kerf-component`; generates a publishable component package with packaging rules plus deterministic, drift-checked AI metadata pre-wired (source: [`create-kerf-component/`](./create-kerf-component/))
 - **Demo:** [live demo](https://brianwestphal.github.io/kerf/demo/) — nine sections exercising every primitive (counter, store-backed cart, focus survival, keyed list, morph-skip, SVG render, Tier-2 capture, `arraySignal` patches, fine-grained signal bindings)
 - **Repo:** [github.com/brianwestphal/kerf](https://github.com/brianwestphal/kerf)
 
 ## 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,18 +1,23 @@
-<!-- kerf-skill-version: 1.20.0 -->
+<!-- kerf-skill-version: 1.23.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.
+You are writing a UI in kerf — a ~13 KB reactive framework (still ~13 KB with `arraySignal`): signals + DOM morphing + JSX → HTML strings. No virtual DOM, no compiler, no scheduler.
 
 ## Setup
 
 - Install with `npm install kerfjs`.
 - `tsconfig.json`: `"jsx": "react-jsx"`, `"jsxImportSource": "kerfjs"`.
 - Vite / esbuild need no extra config.
-- **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it FIRST if relying on the untracked-signal warning — `signal()` picks its constructor at creation time.
+- **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it (and any `enableWarnings()` call) FIRST if relying on the untracked-signal, delegate-in-effect, or rebuilt-listeners warnings — `signal()`, `effect()`, and `mount()` decide those at creation time, so anything created earlier stays uncovered.
   - **Switch individual warnings on with `enableWarnings()`**, which is the only switch that works in a browser (no `process` object there, and a bundler `define` cannot reach the read): `const dev = await import('kerfjs/dev'); dev.enableWarnings({ staleBinding: true, narrowSet: true, invariants: 'throw' });`. The `KERF_DEV_WARN_*` env vars do the same for Node/SSR/CI; an explicit call wins either way.
   - **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.
@@ -28,13 +33,13 @@ the complete layer is intentional. Reuse these primitives before creating
 parallel local ones; keep domain state, commands, routing, and tab/menu policy
 in the app.
 
-Use MenuItem/MenuActionRow/MenuHeader `rootAttributes` only for application
-`data-*` metadata. MenuActionRow `trailingActionAttributes` and MenuHeader
+Use ListItem/ListActionRow/ListHeader `rootAttributes` only for application
+`data-*` metadata. ListActionRow `trailingActionAttributes` and ListHeader
 `triggerAttributes` additionally support native popover target/action and
 `aria-controls`/`aria-haspopup`. Do not use these slots to override action,
 item identity, selection, disclosure, naming, disabled, icon, or role
 semantics; one `role="menuitem"` does not make a complete menu widget.
-`MenuItem.trailing` is dormant. Use `MenuActionRow` for sibling primary and
+`ListItem.trailing` is dormant. Use `ListActionRow` for sibling primary and
 trailing native buttons, and keep its `label`, `icon`, and
 `trailingActionIcon` SafeHtml slots free of controls.
 
@@ -43,13 +48,22 @@ Wire emitted `data-action` hooks at the mount root and retain disposers.
 disposers. Compose `AppTab` inside controlled `TabBar`; `wireTabBars()` supplies
 horizontal edge autoscroll while dragging. Apply reorder reports
 with `reorderTabs()`, and keep order, selection, close policy, routing, panels,
-and persistence in the host. Icons/spinners are decorative unless
+and persistence in the host. Toolbars draw no divider by default; call
+`wireScrollDividers()` once at the app root so panes and tab bars show scroll
+dividers only while content is scrolled beneath or beyond them. Icons/spinners are decorative unless
 labeled, and assertive banners are only for urgent interruption.
 
-The opinionated semantic ramps match Hot Sheet 2 and Web Awesome. Override
-`--kui-color-*` globally or component properties such as
-`--kui-state-banner-background` at a tone or instance boundary; do not replace
-private descendant selectors.
+Components own their styles; configure, never override. Set how a component
+looks and sits through its typed props (size, density, inset, presentation,
+`dividerSides`, `ToolbarConfig`, `PaneConfig`, …); never write application
+CSS that selects a `.kui-*` class, a `[data-component]` root, a `wa-*` element
+a Kerf component renders, or its `::part()`s, and never add padding, margin,
+width, or height around a component to size or space it (it owns its 8px
+inset — adding more double-insets). A missing prop is a component gap to
+report upstream, not a reason to override. The opinionated semantic ramps
+match Hot Sheet 2 and Web Awesome: override `--kui-color-*` globally or
+component properties such as `--kui-state-banner-background` at a tone or
+instance boundary, for theming only.
 
 For Web Awesome's broader free component set, import the CSS-only
 `@kerfjs/ui/webawesome.css` theme once, then import only each Web Awesome
@@ -66,41 +80,53 @@ peer and stays out of bundles that use neither Select nor the Web Awesome theme.
 
 ```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,
+  type JSXChildren,
+} 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                                                                                                                                                                                                                                                                                   |
+| `JSXChildren`                                | recursive type for general-purpose component `children`: SafeHtml, primitives, read-only signals, nullish/boolean empty values, and readonly arrays at any depth. Use a narrower union for semantically restricted slots                                                                                  |
+| `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
 
@@ -109,9 +135,9 @@ if (import.meta.env.DEV) await import('kerfjs/dev');
 3. **Escape hatches:** `data-morph-skip` (element + subtree preserved verbatim — for Monaco / xterm / D3); `data-morph-skip-children` (attrs morph, subtree preserved — for client-hydrated slots whose host classes change); `data-morph-preserve` (element survives the trailing-removal pass — for imperatively-injected nodes like autoplay videos).
 4. **Never `addEventListener` inside a `mount()`-managed tree** unless under `data-morph-skip`. A morph re-render may discard the node. Use `delegate` / `delegateCapture` instead.
 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.
+6. **One `mount()` per root.** Don't nest. Compose with plain functions that return JSX. One exception: a modal `<dialog>` of your own that anchors kerf `popover()` / `tooltip()` surfaces must contain `<div data-kerf-overlay-host data-morph-skip></div>` — kerf renders those surfaces into it (inside the modal, so they are not inert) and that slot is the one allowed nested-mount boundary. Dialogs `kerfjs/overlay` opens get a slot automatically.
 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 (`enableWarnings({ staleBinding: true })` (or `KERF_DEV_WARN_STALE_BINDING=1` under Node) detects it). Endpoint: a render reading NO `.value` runs exactly once — a fully bound mount never re-renders; `enableWarnings({ valueOnlyRerender: true })` (or `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` under Node) 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.
@@ -124,22 +150,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.
@@ -152,20 +182,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>
 ));
 
@@ -173,22 +210,28 @@ 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: [] }),
   }),
 });
 
 // One-shot reconcile against existing DOM (no signals)
-morph(liveCard, '<article class="card">…</article>');
+// the template describes liveCard's CHILDREN; liveCard's own attributes are untouched
+morph(liveCard, '<h2 class="card-title">…</h2><p>…</p>');
 
 // 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
@@ -197,9 +240,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>
 ));
 ```
@@ -215,13 +264,13 @@ 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`.
+- 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: `enableWarnings({ staleIndex: true })` (or `KERF_DEV_WARN_STALE_INDEX=1` under Node).
 
 ## Server / SSR