kerfjs 1.0.2 → 2.0.1

package/CHANGELOG.md

@@ -6,6 +6,42 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-07-23
+
+
+
+- Fixed a `morph()` bug where static text siblings of a fine-grained bound text hole were dropped after a structural re-render (e.g. `<div>{label} / static</div>` collapsing to just the label).
+
+
+- New animated coding-session demo on the getting-started page: watch the canonical counter get typed out, served, clicked in a browser, and live-edited into a todo list.
+- Added an animated architecture diagram and a link to the docs site from the README.
+
+## [2.0.0] - 2026-07-23
+
+
+
+- `delegateCapture()` now uses `closest()`-style walk-up matching like `delegate()`, passing the matched ancestor to the handler; pass `{ match: 'direct' }` (new `DelegateOptions`) to restore exact-element matching.
+- The dangerous-URL screen (`javascript:`, `vbscript:`, script-executing `data:` URLs) now throws an error in development instead of only warning. Production behavior is unchanged: warn and drop the attribute.
+
+
+- New `kerfjs/html` tagged template: author kerf UIs with no build step (CDN / importmap, no JSX transform) with runtime semantics identical to JSX — signal holes become fine-grained bindings, attributes and text are escaped and URL-screened the same way.
+- New no-build example app, **live-poll**, served exactly as authored — an importmap plus one `html`-templated module, with view-source showing the app.
+- Added `<filter>` to the typed JSX intrinsic elements, so SVG filters compile in JSX-authored code.
+- Fully-bound mounts are now a documented, test-pinned guarantee: a render that reads no signal `.value` runs exactly once, forever — every update is a direct per-node write.
+
+
+- Controlled form state now survives user interaction: `checked`, `value`, and `selected` DOM properties are synced when the reconciler mutates those attributes, so a clicked checkbox or typed-into input no longer ignores later updates.
+- Fixed stale fine-grained bindings after `arraySignal.update()`: in-place row updates now re-wire bindings whose signal instance changed, instead of leaving effects reading the old row object forever.
+
+
+- New runtime dev-mode override: set `globalThis.KERF_DEV = false` (or `true`) to control dev mode without a bundler — CDN/importmap apps are no longer stuck in dev mode in production.
+- Two new opt-in dev warnings: `KERF_DEV_WARN_STALE_BINDING` flags bindings that silently go stale on the byte-equal fast path, and `KERF_DEV_WARN_VALUE_ONLY_RERENDER` flags re-renders whose only changes could have been fine-grained bindings.
+- `defineStore`'s dev-mode `get()` snapshot now returns a deep read-only proxy instead of freezing the live state: nested mutations like `get().nested.x = 1` are caught too, and they throw a descriptive `TypeError` rather than failing silently.
+
+
+- Docs repositioned around the "values bind, structure re-renders" idiom as the primary way to render dynamic values, across the overview, reactivity guide, and AI assistant configs.
+- New guide covering the no-build authoring path and example app, plus a documentation-wide accuracy pass (delegate capture semantics, `effect()` cleanup returns, URL-screen behavior, and more).
+
 ## [1.0.2] - 2026-07-22
 
 

package/LICENSE

@@ -25,7 +25,7 @@ SOFTWARE.
 
 ## Acknowledgements
 
-`src/diff.ts` re-implements the DOM-reconciliation algorithm of
+`src/morph.ts` re-implements the DOM-reconciliation algorithm of
 [morphdom](https://github.com/patrick-steele-idem/morphdom) by Patrick
 Steele-Idem, which is also distributed under the MIT License:
 
@@ -51,3 +51,31 @@ Steele-Idem, which is also distributed under the MIT License:
     CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
     TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
     SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+`src/attrSelector.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:
+
+    Copyright Mathias Bynens <https://mathiasbynens.be/>
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+    BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+    ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.

package/README.md

@@ -6,6 +6,10 @@
 
 <p align="center"><em>The smallest cut.</em></p>
 
+<p align="center">
+  <a href="https://brianwestphal.github.io/kerf/"><strong>brianwestphal.github.io/kerf</strong></a> — docs · examples · live demo
+</p>
+
 ---
 
 > Introducing Kerf.
@@ -29,23 +33,27 @@ mount(document.getElementById('app')!, () => (
 
 That's it. Your JSX renders to HTML strings, kerf's native diff applies the minimum DOM mutations to make the live tree match, and signals re-run the render only when something they read actually changed.
 
+Here's the whole development loop — write a component, run the dev server, click around, edit, watch the browser pick it up:
+
+[![Animated coding session: a counter component is typed line by line into an editor, npm run dev starts in a terminal and the localhost link is clicked, the running app is clicked in a browser, then back in the editor a computed class is added — selecting "btn" and typing a bound {cls} hole — and the browser shows the button change color at the fifth click](https://brianwestphal.github.io/kerf/demos/getting-started.svg)](https://brianwestphal.github.io/kerf/getting-started/)
+
 ## Why Kerf
 
 1. **Small bundle.** ~11 KB minified + gzipped including `@preact/signals-core` (~12 KB with `arraySignal`). One runtime dependency. No virtual DOM, no scheduler, no concurrent-mode machinery. On the official [krausest js-framework-benchmark](https://krausest.github.io/js-framework-benchmark/current.html) — where kerf is a listed entry, measured on the same reference machine as every competitor ([local mirror](./bench/results.md)) — kerf is in the same cluster as Vue, vanjs, and Lit on most operations; Solid's compiler leads the update-path benchmarks (notably `partial update`), which kerf doesn't try to match by design — no compiler.
 
 2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it *is* the DOM.
 
-3. **Fine-grained updates, opt-in.** Hand a signal *itself* into a JSX hole — `class={selectedId}` or `{status}` — and kerf binds that one node directly: when the signal changes, only that attribute or text node updates, with no render re-run and no list reconcile. It's a surgical tier beneath the coarse render effect, for the *external-state-drives-one-spot* pattern — a selection flip on a 10,000-row table touches exactly one class.
+3. **Values bind, structure re-renders.** Hand a signal *itself* into a JSX hole — `class={selectedId}` or `{status}` — and kerf binds that one node directly: when the signal changes, only that attribute or text node updates, with no render re-run and no list reconcile. A selection flip on a 10,000-row table touches exactly one class. Taken to its logical end: a mount whose render reads no `.value` at all runs **exactly once, forever** — every subsequent update flows through the per-hole bindings. Read `.value` in the render only when the *structure* depends on it (conditionals, list shape).
 
 4. **Focus, selection, listeners survive re-renders — even mid-list.** The reconciler morphs instead of rebuilding, so caret position, selection range, IME composition, and delegated listeners survive every re-render. Keyed lists get the same treatment: same-identity rows are updated *in place* rather than recreated, so a row reorder or a single-cell edit no longer blows away focus, scroll, or an in-flight animation the way node replacement does.
 
-5. **Safe by default.** Text and attribute values are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` / script-carrying `data:` dropped), inline `on*` handlers are rejected outright, and the same screening covers the fine-grained bound path — so untrusted data stays inert even when kerf is dropped into someone else's page. `raw()` is the explicit, auditable opt-out.
+5. **Safe by default.** Text and attribute values are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` / script-carrying `data:` dropped), inline `on*` handlers are rejected outright, and the same screening covers the fine-grained bound path — so untrusted data stays inert even when kerf is dropped into someone else's page. The URL screen fails loudly at your desk (throws in development) and degrades safely in the field (warns and drops in production). `raw()` is the explicit, auditable opt-out.
 
-6. **Small public API.** ~17 exports from the main barrel (plus `arraySignal` on its own subpath). No hooks, no lifecycle, no per-instance state. Components are plain functions that return JSX.
+6. **Small public API.** ~17 exports from the main barrel (plus `arraySignal` and the `html` tagged template on their own subpaths). No hooks, no lifecycle, no per-instance state. Components are plain functions that return JSX.
 
-7. **Plain TS, plain JSX, plain ESM.** Drops into anything using esbuild / Vite / tsup. No plugin chain.
+7. **Plain TS, plain JSX, plain ESM.** Drops into anything using esbuild / Vite / tsup. No plugin chain. And with the `html` tagged template (`import { html } from 'kerfjs/html'` — identical runtime semantics to JSX), a CDN / importmap project needs no build step at all.
 
-8. **Grown-up tooling around a tiny core.** An [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) that enforces the hard rules at edit time, a `create-kerf-component` scaffold for publishable component packages, drop-in AI-assistant configs, and side-by-side migration guides for a dozen-plus frameworks — none of which grows the core runtime past ~11 KB.
+8. **Grown-up tooling around a tiny core.** An [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) that enforces the hard rules at edit time, an opt-in family of `KERF_DEV_WARN_*` runtime warnings that catch the classic mistakes in development (with zero production cost), a `create-kerf-component` scaffold for publishable component packages, drop-in AI-assistant configs, and side-by-side migration guides for a dozen-plus frameworks — none of which grows the core runtime past ~11 KB.
 
 ## When to use Kerf
 
@@ -91,16 +99,12 @@ mount(root, () => (
   <div>
     <h1>Cart ({cart.state.value.items.length})</h1>
     <ul>
-      {each(
-        cart.state.value.items,
-        (item) => (
-          <li>
-            {item.name}
-            <button data-action="remove" data-id={item.id}>×</button>
-          </li>
-        ),
-        (item) => item.id,
-      )}
+      {each(cart.state.value.items, (item) => (
+        <li data-key={item.id}>
+          {item.name}
+          <button data-action="remove" data-id={item.id}>×</button>
+        </li>
+      ))}
     </ul>
     <p>Doubled count: {doubled.value}</p>
   </div>
@@ -112,6 +116,17 @@ delegate(root, 'click', '[data-action="remove"]', (_e, btn) => {
 });
 ```
 
+The stringly-typed `'[data-action="remove"]'` pair above can be made rename-safe with the `attr()` helper — declare the attribute once and use it on both sides:
+
+```ts
+import { attr } from 'kerfjs';
+
+const REMOVE = attr('data-action', 'remove'); // pre-escaped name/value/selector
+
+<button {...REMOVE.attrs} data-id={item.id}>×</button>;          // in JSX
+delegate(root, 'click', REMOVE.selector, (_e, btn) => { /* … */ }); // in delegation
+```
+
 ### 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:
@@ -128,7 +143,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. See [`docs/2-reactivity.md`](./docs/2-reactivity.md) §2.9.
+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.
+
+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`
 
@@ -164,6 +181,25 @@ 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.
 
+### No build step at all: the `html` tagged template
+
+"No compiler" isn't just a JSX story. The `html` tagged template from `kerfjs/html` has **identical runtime semantics to JSX** — escaping, boolean/nullish attribute rules, URL screening, `on*` rejection, fine-grained signal bindings, `each()` composition — with no transform, so a plain `<script type="module">` on a CDN / importmap page is a complete kerf app:
+
+```html
+<script type="module">
+  import { signal, mount, each } from 'https://esm.sh/kerfjs';
+  import { html } from 'https://esm.sh/kerfjs/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>
+```
+
+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. Static template parts parse once per call site. See [`docs/6-jsx-runtime.md`](./docs/6-jsx-runtime.md) §6.11 — 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.
+
 ## Install
 
 ```bash
@@ -225,7 +261,7 @@ A *kerf* is the narrow strip of material a saw blade removes when cutting — th
 
 ## Status
 
-1.0 — the public API is stable and follows semver from here. See [CHANGELOG.md](./CHANGELOG.md) for the current version and what's shipped.
+Stable — the public API follows semver. See [CHANGELOG.md](./CHANGELOG.md) for the current version and what's shipped.
 
 ## Sponsor
 

package/ai/cursorrules

@@ -1,4 +1,4 @@
-<!-- kerf-skill-version: 1.3.0 -->
+<!-- kerf-skill-version: 1.8.0 -->
 # kerf.cursorrules — rules for building apps with kerf
 #
 # Drop this file into your project as `.cursorrules` (Cursor will pick it
@@ -42,12 +42,13 @@ import { arraySignal } from 'kerfjs/array-signal';
 | `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 |
 | `delegate(root, type, sel, h)` | one listener at the root, walks `closest(selector)` from target |
-| `delegateCapture(root, type, sel, h)` | capture-phase escape hatch, strict `target.matches()` |
+| `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
 
@@ -58,7 +59,7 @@ import { arraySignal } from 'kerfjs/array-signal';
 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. **Signal reads must happen INSIDE the render function** to be tracked. `const x = count.value; mount(el, () => <span>{x}</span>)` will NOT re-render. Move the read inside.
+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.
@@ -73,7 +74,7 @@ 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 strict element-match → `delegateCapture()`.
+- 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)`.
@@ -89,18 +90,22 @@ When deciding which primitive to reach for, work down the axes:
 **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.
 
 ## Canonical patterns
 
 ```tsx
-// Signal + mount
+// Signal + mount. THE core idiom — values bind, structure re-renders:
+// pass the signal ITSELF into a value hole ({count}, class={sig}) so kerf
+// 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'>>;
 
 mount(document.getElementById('app')!, () => (
   <div>
     <button {...ACTIONS.inc.attrs}>+</button>
-    <span>{count.value}</span>
+    <span>{count}</span>
   </div>
 ));
 delegate(rootEl, 'click', ACTIONS.inc.selector, () => { count.value += 1; });
@@ -124,6 +129,15 @@ const cart = defineStore({
 // One-shot reconcile against existing DOM (no signals)
 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>
+`);
+
 // 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
 // hot spot driven by an external signal (selection class) — not everywhere.
@@ -150,6 +164,7 @@ mount(listEl, () => (
 - 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}`)}"`.
 
 ## Server / SSR
 

package/ai/manifest.json

@@ -1,21 +1,21 @@
 {
-  "kerfjsVersion": "1.0.2",
+  "kerfjsVersion": "2.0.1",
   "files": [
     {
       "name": "skill",
       "source": "kerf.claude-skill.md",
       "bundle": "ai/skill.md",
       "dest": ".claude/skills/kerf-app/SKILL.md",
-      "version": "1.3.0",
-      "sha256": "789cfd9bbe0fa8a01b779595912b7fef569b3c021be412d35f453476e576bac6"
+      "version": "1.8.0",
+      "sha256": "76b8a88bc7aaf9d50e6f3eee7b57a976b3279127f5d4970599aef1f839a06655"
     },
     {
       "name": "cursorrules",
       "source": "kerf.cursorrules",
       "bundle": "ai/cursorrules",
       "dest": ".cursorrules",
-      "version": "1.3.0",
-      "sha256": "2524a42cc3b488f8cc3cea736cf5b8d3e57d868c85260342ec50905243aa65f1"
+      "version": "1.8.0",
+      "sha256": "f91402df009941b4198ea659498f458d2433843d47a3b524b0ca5e2d3d2fc949"
     }
   ]
 }

package/ai/skill.md

@@ -1,7 +1,7 @@
 ---
 name: kerf-app
 description: Build UIs in the kerf reactive framework (https://github.com/brianwestphal/kerf). Use this skill whenever the user is writing or modifying code that imports `kerfjs`, asks to add a feature to a kerf app, or asks "how do I do X in kerf?". Use it proactively the moment you spot a kerf import in the file you're editing.
-kerf-skill-version: 1.3.0
+kerf-skill-version: 1.8.0
 ---
 
 # Building apps with kerf
@@ -47,12 +47,13 @@ import { arraySignal } from 'kerfjs/array-signal';
 | `morph(liveRoot, template)` | one-shot reconcile against a populated element (SSR hydration, page-refresh diffs). Template = `Element`, `SafeHtml`, or HTML string |
 | `each(items, render, cacheKey?)` | keyed list iteration; per-row memoization on identity (+ optional cacheKey — a passive comparator for external state). Distinct from `data-key` on the rendered element |
 | `delegate(root, type, sel, h)` | one listener at the root; `closest(selector)` walk from target |
-| `delegateCapture(root, type, sel, h)` | capture-phase escape hatch; `target.matches()` strict match |
+| `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 (subpath `kerfjs/array-signal`); `each()` reconciles in O(patches) |
+| `` html`…` `` | tagged template (subpath `kerfjs/html`) — JSX-identical runtime semantics with NO build step, for 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 — every AI assistant gets these wrong at least once
 
@@ -66,7 +67,7 @@ import { arraySignal } from 'kerfjs/array-signal';
 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 `mount()` calls. Compose with plain functions returning JSX.
 7. **Components are plain functions.** `<MyComponent props />` works — the JSX runtime calls `MyComponent(props)` and uses the returned JSX — but there's no hook system, no lifecycle, and no per-instance state. State lives in module-scope signals or stores, never in component closures.
-8. **Signal reads must happen INSIDE the render function** to be tracked. `const x = count.value; mount(el, () => <span>{x}</span>)` does NOT re-render. Move the read inside.
+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>)` does NOT re-render. One caveat on bound holes: bind a STABLE signal/computed instance per hole (`class={computed(() => …)}` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (detectable via `KERF_DEV_WARN_STALE_BINDING=1`). The idiom's endpoint: a render that reads NO `.value` runs exactly once — a fully bound mount never re-renders. To find `.value` holes worth migrating, `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` flags re-renders whose only differences were text/attribute values.
 9. **Store actions take `(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.
 11. **`arraySignal` is opt-in for long keyed lists** where most updates are pointwise. For short lists / filter+sort pipelines, plain `signal` + `each(items.value, ...)` is simpler and equally fast.
@@ -81,7 +82,7 @@ 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 strict element-match → `delegateCapture()`.
+- 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)`.
@@ -98,17 +99,23 @@ When deciding which primitive to reach for, work down the axes:
 - User-controlled HTML → sanitize first (DOMPurify) then `raw(sanitized)`.
 - Author-controlled trusted HTML → `raw(html)` directly.
 
+**Dangerous URLs.** `javascript:`/`vbscript:`/script-executing `data:` values 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)` (bypasses the screen in both modes).
+
 ## Canonical patterns
 
 ```tsx
-// Pattern 1: signal + mount + delegate
+// Pattern 1: signal + mount + delegate.
+// THE core idiom — values bind, structure re-renders: pass the signal ITSELF
+// into a value hole ({count}, class={sig}) so kerf 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'>>;
 
 mount(document.getElementById('app')!, () => (
   <div>
     <button {...ACTIONS.inc.attrs}>+</button>
-    <span>{count.value}</span>
+    <span>{count}</span>
   </div>
 ));
 delegate(rootEl, 'click', ACTIONS.inc.selector, () => { count.value += 1; });
@@ -146,6 +153,15 @@ mount(listEl, () => (
   </ul>
 ));
 // selectedId.value = 3  → only the ~2 affected <li> class attrs update.
+
+// Pattern 6: no build step (CDN / importmap) — the html tagged template
+// instead of JSX. Same runtime semantics; real HTML attribute names; a hole
+// must be a text position or a COMPLETE attribute value (partials 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>
+`);
 ```
 
 ## Diagnosing common errors
@@ -163,6 +179,7 @@ mount(listEl, () => (
 | Drag/drop / state change has no visible effect; only elements *outside* `each()` update | Used `each(STATIC_ARRAY, …)` whose row render reads signals. Items never change identity → cache hits forever → row render never re-invoked → signal reads stop tracking | Replace 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). Intentional flip side: 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`) so the reconciler replaces the node |
 | 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 | Build the full string first (`` class="${`a ${b}`}" ``), or bind `class="${computed(() => `a ${b.value}`)}"` for a reactive one |
 
 ## Workflow guidance
 

package/dist/array-signal.js

@@ -1,4 +1,4 @@
-import { signal } from './chunk-4E26PO2C.js';
+import { signal } from './chunk-NU7YHYEV.js';
 
 // src/array-signal.ts
 var ARRAY_SIGNAL_BRAND = /* @__PURE__ */ Symbol.for("kerfjs.ArraySignal");

package/dist/{chunk-QNYOMGI4.js → chunk-GYRZQCSY.js}

@@ -1,4 +1,18 @@
-import { effect, isSignal } from './chunk-4E26PO2C.js';
+import { effect, isSignal, isDevMode } from './chunk-NU7YHYEV.js';
+
+// src/utils/syncFormProp.ts
+function syncFormProp(el, name, value, present) {
+  const tag = el.tagName;
+  if (name === "checked") {
+    if (tag === "INPUT") el.checked = present;
+  } else if (name === "value") {
+    if (tag === "INPUT" && el !== document.activeElement) {
+      el.value = present ? value : "";
+    }
+  } else if (name === "selected") {
+    if (tag === "OPTION") el.selected = present;
+  }
+}
 
 // src/utils/urlScreen.ts
 var URL_ATTRS = /* @__PURE__ */ new Set(["href", "src", "xlink:href", "formaction", "action", "data"]);
@@ -30,6 +44,11 @@ function isDangerousUrlValue(name, value) {
 function dangerousUrlWarning(name, value) {
   return `dropped dangerous URL value for ${name}=${JSON.stringify(value.slice(0, 80))}. kerf blocks javascript:, vbscript:, and script-executing data: URLs (text/html, image/svg+xml, xml) in href/src/data/formaction/action/xlink:href by default. Wrap in raw() if this is intentional (e.g. bookmarklets), or sanitize upstream.`;
 }
+function reportDangerousUrl(context2, name, value) {
+  const message = `${context2}: ${dangerousUrlWarning(name, value)}`;
+  if (isDevMode()) throw new Error(message);
+  console.warn(message);
+}
 
 // src/bindings.ts
 var BIND_ATTR = "data-kfb";
@@ -39,7 +58,7 @@ var ROW_TEXT_PREFIX = "kfbr:";
 var context = null;
 var rowSink = null;
 var rowCounter = 0;
-var NO_DISPOSERS = [];
+var NO_DISPOSERS = Object.freeze([]);
 function newBindingContext() {
   return { counter: 0, list: [] };
 }
@@ -92,7 +111,7 @@ function wireBindings(rootEl, ctx, prevDisposers) {
   for (const d of prevDisposers) d();
   if (ctx.list.length === 0) return NO_DISPOSERS;
   const disposers = [];
-  wireInto(rootEl, BIND_ATTR, TEXT_MARKER_PREFIX, ctx.list, disposers);
+  wireInto(rootEl, ctx.list, disposers);
   return disposers;
 }
 function wireRowBindings(rowNode, bindings) {
@@ -138,10 +157,29 @@ function disposeRowBindings(disposers) {
   if (disposers === void 0) return;
   for (const d of disposers) d();
 }
-function wireInto(scope, attrName, textPrefix, bindings, disposers) {
-  const attrEls = indexAttrEls(scope, attrName);
+function carryOrRewireRowBindings(node, oldBindings, oldDisposers, newBindings) {
+  const oldLen = oldBindings === void 0 ? 0 : oldBindings.length;
+  const newLen = newBindings === void 0 ? 0 : newBindings.length;
+  if (oldLen === newLen) {
+    let same = true;
+    for (let i = 0; i < newLen; i++) {
+      if (oldBindings[i].signal !== newBindings[i].signal) {
+        same = false;
+        break;
+      }
+    }
+    if (same) return { bindings: oldBindings, bindingDisposers: oldDisposers };
+  }
+  disposeRowBindings(oldDisposers);
+  return {
+    bindings: newBindings,
+    bindingDisposers: newLen > 0 ? wireRowBindings(node, newBindings) : void 0
+  };
+}
+function wireInto(scope, bindings, disposers) {
+  const attrEls = indexAttrEls(scope, BIND_ATTR);
   const textMarkers = /* @__PURE__ */ new Map();
-  collectComments(scope, textPrefix, textMarkers);
+  collectComments(scope, TEXT_MARKER_PREFIX, textMarkers);
   for (const b of bindings) {
     if (b.kind === "attr") {
       const el = attrEls.get(b.id);
@@ -164,33 +202,47 @@ function indexAttrEls(scope, attrName) {
 function attachAttrEffect(el, attr, signal) {
   return effect(() => setBoundAttr(el, attr, signal.value));
 }
+var insertedTextNodes = /* @__PURE__ */ new WeakMap();
+function boundTextNodeOf(marker) {
+  const t = insertedTextNodes.get(marker);
+  return t !== void 0 && marker.nextSibling === t ? t : null;
+}
 function attachTextEffect(marker, signal) {
-  const text = marker.ownerDocument.createTextNode("");
-  marker.parentNode.insertBefore(text, marker.nextSibling);
+  let text = insertedTextNodes.get(marker);
+  if (text === void 0 || marker.nextSibling !== text) {
+    text = marker.ownerDocument.createTextNode("");
+    marker.parentNode.insertBefore(text, marker.nextSibling);
+    insertedTextNodes.set(marker, text);
+  }
+  const node = text;
   return effect(() => {
-    text.data = coerceText(signal.value);
+    node.data = coerceText(signal.value);
   });
 }
 function setBoundAttr(el, name, value) {
   if (value == null || value === false) {
     el.removeAttribute(name);
+    syncFormProp(el, name, "", false);
     return;
   }
   if (value === true) {
     el.setAttribute(name, "");
+    syncFormProp(el, name, "", true);
     return;
   }
   if (isSafeHtmlValue(value)) {
     el.setAttribute(name, value.__html);
+    syncFormProp(el, name, value.__html, true);
     return;
   }
   const str = String(value);
   if (isDangerousUrlValue(name, str)) {
-    console.warn(`kerf binding: ${dangerousUrlWarning(name, str)}`);
+    reportDangerousUrl("kerf binding", name, str);
     el.removeAttribute(name);
     return;
   }
   el.setAttribute(name, str);
+  syncFormProp(el, name, str, true);
 }
 var SAFE_HTML_BRAND = /* @__PURE__ */ Symbol.for("kerfjs.SafeHtml");
 function isSafeHtmlValue(v) {
@@ -212,17 +264,18 @@ function collectComments(node, prefix, out) {
 }
 
 // src/segment.ts
+var LIST_MARKER_PREFIX = "kf-list:";
 function flatten(segment, withMarkers) {
   if (segment.kind === "static") return segment.html;
   if (segment.kind === "list") {
     const items = segment.items.map((i) => i.html).join("");
-    return withMarkers ? `<!--kf-list:${segment.id}-->${items}` : items;
+    return withMarkers ? `<!--${LIST_MARKER_PREFIX}${segment.id}-->${items}` : items;
   }
   return segment.parts.map((p) => flatten(p, withMarkers)).join("");
 }
 function flattenWithoutListItems(segment) {
   if (segment.kind === "static") return segment.html;
-  if (segment.kind === "list") return `<!--kf-list:${segment.id}-->`;
+  if (segment.kind === "list") return `<!--${LIST_MARKER_PREFIX}${segment.id}-->`;
   return segment.parts.map(flattenWithoutListItems).join("");
 }
 function collectLists(segment, out = /* @__PURE__ */ new Map()) {
@@ -488,7 +541,9 @@ See docs/5-event-delegation.md for the tier-1/tier-2/tier-3 model.`
   }
 }
 function renderAttr(key, value) {
-  const name = ATTR_ALIASES[key] ?? key;
+  return renderAttrNamed(key, ATTR_ALIASES[key] ?? key, value);
+}
+function renderAttrNamed(key, name, value) {
   if (value == null || value === false) return "";
   assertEmittableAttrName(key, name, typeof value === "function");
   if (value === true) return ` ${name}`;
@@ -499,7 +554,7 @@ function renderAttr(key, value) {
     strValue = String(value);
   } else if (typeof value === "string") {
     if (isDangerousUrlValue(name, value)) {
-      console.warn(`JSX: ${dangerousUrlWarning(name, value)}`);
+      reportDangerousUrl("JSX", name, value);
       return "";
     }
     strValue = escapeAttr(value);
@@ -537,7 +592,13 @@ function jsx(tag, props) {
 function Fragment({ children }) {
   return new SafeHtml(children != null ? toSegment(children) : { kind: "static", html: "" });
 }
+function _toSegment(child) {
+  return toSegment(child);
+}
+function _renderAttrVerbatim(name, value) {
+  return renderAttrNamed(name, name, value);
+}
 
-export { Fragment, SafeHtml, _setBindingContext, captureRowBindings, collectLists, disposeRowBindings, flatten, flattenWithoutListItems, granularListSafeHtml, isSafeHtml, jsx, listSafeHtml, newBindingContext, raw, wireBindings, wireRowBindings };
-//# sourceMappingURL=chunk-QNYOMGI4.js.map
-//# sourceMappingURL=chunk-QNYOMGI4.js.map
+export { Fragment, LIST_MARKER_PREFIX, SafeHtml, _renderAttrVerbatim, _setBindingContext, _toSegment, assertEmittableAttrName, bindAttr, bindMarkerAttr, boundTextNodeOf, captureRowBindings, carryOrRewireRowBindings, collectLists, disposeRowBindings, flatten, flattenWithoutListItems, granularListSafeHtml, isSafeHtml, jsx, listSafeHtml, mergeChildSegments, newBindingContext, raw, syncFormProp, wireBindings, wireRowBindings };
+//# sourceMappingURL=chunk-GYRZQCSY.js.map
+//# sourceMappingURL=chunk-GYRZQCSY.js.map