kerfjs 4.4.1 → 4.5.0-beta.1

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.14.2
+description: Build UIs in the kerf reactive framework and its @kerfjs/ui component package (https://github.com/brianwestphal/kerf). Use this skill whenever the user is writing or modifying code that imports `kerfjs` or `@kerfjs/ui`, asks to add a feature to a kerf app, or asks "how do I do X in kerf?". Use it proactively the moment you spot a kerf import in the file you're editing.
+kerf-skill-version: 1.22.0
 ---
 
 # Building apps with kerf
@@ -22,45 +22,106 @@ kerf is a ~12 KB reactive UI framework (~13 KB with `arraySignal`): signals + DO
   - **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 companion: `npm install --save-dev eslint-plugin-kerfjs` and add `kerfjs.configs.recommended` to the project's eslint config. 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 — useful as a self-correction signal when authoring kerf code.
 
+## Optional first-party UI
+
+Install `@kerfjs/ui` when the app needs shared toolbars, menu rows, controlled tab bars,
+headers/value tables, resizable regions, selects, banners, empty states, or
+loading indicators. Import visual components from explicit subpaths so a
+CSS-aware browser bundler includes only their reachable styles. The root barrel
+and `@kerfjs/ui/unstyled` are CSS-free; pair the barrel with `styles.css` only
+when the complete layer is intentional. Prefer a component before inventing a
+parallel local primitive, but keep domain state, routing, commands, and tab/menu
+policy in the app.
+
+Use ListItem/ListActionRow/ListHeader/AppTab `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.
+`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.
+AppTab protects its component/action/identity/selection and transient drag/drop
+attributes at runtime. Keep `AppTab.closeIcon` and
+`ResizableRegion.handleIcon` decorative and free of controls; the existing
+named controls and wiring retain interaction and disposal ownership.
+
+Components emit stable `data-action` hooks; wire them at the mount root and
+retain every disposer. `wireResizableRegions()` and `wireTabBars()` are the
+explicit behavioral helpers and return disposers. Compose `AppTab` inside a
+controlled `TabBar`; `wireTabBars()` supplies horizontal edge autoscroll during
+dragging. Apply reorder reports with `reorderTabs()`, and keep order,
+selection, close policy, routing, panels, and persistence in the host.
+Icons and spinners are decorative unless labeled; use assertive banners only
+for urgent interruption.
+
+The opinionated semantic ramps match Hot Sheet 2 and Web Awesome. Override
+`--kui-color-*` globally or component properties such as
+`--kui-state-banner-background` at a tone or instance boundary; do not replace
+private descendant selectors.
+
+For Web Awesome's broader free component set, import the CSS-only
+`@kerfjs/ui/webawesome.css` theme once, then import only each Web Awesome
+component module the app renders. The theme registers no component JavaScript
+and remains overridable through later or scoped `--wa-*` values.
+
+`Select` renders pure Web Awesome markup. Import
+`@kerfjs/ui/select/register` once in an application entry that uses it; never
+hide that registration inside another component. Web Awesome is an optional
+peer and must remain absent from bundles that use neither Select nor the Web
+Awesome theme. The package's
+full AI contract is at `node_modules/@kerfjs/ui/ai/skill.md`.
+
 ## Public API — one import path
 
 ```ts
 import {
-  signal, computed, effect, batch,    // reactivity
-  defineStore, resetAllStores,        // stores
-  mount, morph, each,                 // render (reactive + one-shot) + keyed list
-  delegate, delegateCapture,          // events
-  toElement,                          // direct JSX → DOM Element (or DocumentFragment for multi-root)
-  SafeHtml, isSafeHtml, raw, Fragment,
-} from 'kerfjs';
+  signal,
+  computed,
+  effect,
+  batch, // reactivity
+  defineStore,
+  resetAllStores, // stores
+  mount,
+  morph,
+  each, // render (reactive + one-shot) + keyed list
+  delegate,
+  delegateCapture, // events
+  toElement, // direct JSX → DOM Element (or DocumentFragment for multi-root)
+  SafeHtml,
+  isSafeHtml,
+  raw,
+  Fragment,
+} from "kerfjs";
 
 // Optional, only when you need granular collection updates:
-import { arraySignal } from 'kerfjs/array-signal';
+import { arraySignal } from "kerfjs/array-signal";
 
 // Development diagnostics — gate with YOUR build's dev flag, in YOUR code.
-if (import.meta.env.DEV) await import('kerfjs/dev');
+if (import.meta.env.DEV) await import("kerfjs/dev");
 ```
 
-| Export | Use |
-| --- | --- |
-| `signal(initial)` | atomic reactive state; `.value` get/set |
-| `computed(fn)` | derived value, read-only |
-| `effect(fn)` | side effect on signal change; returns disposer |
-| `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 disposer |
-| `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 |
-| `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; `closest(selector)` walk 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 (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}"`) |
+| Export                                       | Use                                                                                                                                                                                                                                                                                                       |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `signal(initial)`                            | atomic reactive state; `.value` get/set                                                                                                                                                                                                                                                                   |
+| `computed(fn)`                               | derived value, read-only                                                                                                                                                                                                                                                                                  |
+| `effect(fn)`                                 | side effect on signal change; returns disposer                                                                                                                                                                                                                                                            |
+| `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 disposer                                                                                                                                                                                                                                                   |
+| `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                                                                                                                                   |
+| `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; `closest(selector)` walk 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 (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
 
@@ -74,7 +135,7 @@ if (import.meta.env.DEV) await import('kerfjs/dev');
 5. **Capture the `delegate()` / `delegateCapture()` disposer** whenever the registration's scope is shorter than the page. Both helpers return `() => void`; the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state). Discarding the disposer on a transient root (modal, route view, mount swap, dynamic widget) leaks the listener AND the app graph it captures; re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you. Safe to discard only when the registration is truly page-lifetime (root is `document.body` or equivalent, attached once at startup, never torn down).
 6. **One `mount()` per root.** Don't nest `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. **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.
+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.
@@ -87,22 +148,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.
 
@@ -117,20 +182,27 @@ When deciding which primitive to reach for, work down the axes:
 // 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;
+});
 
 // Pattern 2: keyed list with per-row 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>
 ));
 
@@ -138,8 +210,8 @@ mount(listEl, () => (
 const cart = defineStore({
   initial: () => ({ items: [] as string[] }),
   actions: (set, get) => ({
-    add:   (id: string) => set({ items: [...get().items, id] }),
-    clear: ()           => set({ items: [] }),
+    add: (id: string) => set({ items: [...get().items, id] }),
+    clear: () => set({ items: [] }),
   }),
 });
 // access: cart.state.value.items, cart.actions.add('x'), cart.reset()
@@ -154,9 +226,15 @@ morph(liveCard, '<article class="card">…</article>');
 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>
 ));
 // selectedId.value = 3  → only the ~2 affected <li> class attrs update.
@@ -164,34 +242,39 @@ mount(listEl, () => (
 // 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>
-`);
+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
 
-| Error / symptom | Root cause | Fix |
-| --- | --- | --- |
-| `JSX: DOM elements cannot be passed as children` | passed a `toElement()` result inside JSX | Build the whole tree in JSX; refs via `querySelector` after rendering |
-| `draggable={true}` / `spellCheck={false}` / `contentEditable={false}` / `writingsuggestions={false}` / `translate={false}` / `autocorrect={false}` won't typecheck | these are HTML **enumerated** attributes, not boolean ones — they take keyword strings (`"true"`/`"false"`; `"yes"`/`"no"` for `translate`; `"on"`/`"off"` for `autocorrect`), and omitting one selects a third state, so the boolean form rendered the opposite of what was meant | Write the keyword: `draggable="true"`, `spellCheck="false"`, `writingsuggestions="false"`, `translate="no"`, `autocorrect="off"`. Omit for the default state. Real boolean attrs (`hidden`, `checked`, `disabled`, `autofocus`, `required`, `inert`) are unaffected, as is `popover` (bare form = the spec's `auto` state); for a signal use `signal('true')` |
-| `<select value={x}>` / `<textarea value={x}>` won't typecheck | neither element has a `value` content attribute — the markup was inert | `<option value="b" selected>`; `<textarea>{draft}</textarea>` |
-| Focus / cursor lost on every keystroke | list items lack `data-key` | Add `data-key` (or `id`) to each list item |
-| Click handler stops firing after re-render | `el.addEventListener` was used | Replace with `delegate(rootEl, 'click', ACTIONS.foo.selector, ...)` (or a string literal for ad-hoc cases) |
-| Render fn never re-runs | signal was read outside the render fn | Move `signal.value` read inside the render fn |
-| SVG renders as broken / namespaceless markup | `innerHTML` used directly | Use `mount` or `toElement` (SVG-aware) |
-| Library widget destroyed on every render | host reachable by the morph | Wrap host in `data-morph-skip`; mount the library imperatively after first render |
-| `<my-tag>` fails to typecheck | declaration merging targeted global JSX | Use `declare module 'kerfjs/jsx-runtime' { namespace JSX { … } }` instead |
-| `each(): row render at index N produced K top-level elements` | row returned multiple sibling elements or zero | Wrap them in one parent so the row renders exactly one element |
-| 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 |
-| An `each()` list's rows lose focus / scroll / typing state when an unrelated conditional list above them appears or disappears (kerf warns about this in dev) | Lists without a key are identified by their 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 the HTML it rendered at its old index | Fold the index into the memo key so displaced rows re-render: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `KERF_DEV_WARN_STALE_INDEX=1` |
+| Error / symptom                                                                                                                                                    | Root cause                                                                                                                                                                                                                                                                                                                                                                              | Fix                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `JSX: DOM elements cannot be passed as children`                                                                                                                   | passed a `toElement()` result inside JSX                                                                                                                                                                                                                                                                                                                                                | Build the whole tree in JSX; refs via `querySelector` after rendering                                                                                                                                                                                                                                                                                         |
+| `draggable={true}` / `spellCheck={false}` / `contentEditable={false}` / `writingsuggestions={false}` / `translate={false}` / `autocorrect={false}` won't typecheck | these are HTML **enumerated** attributes, not boolean ones — they take keyword strings (`"true"`/`"false"`; `"yes"`/`"no"` for `translate`; `"on"`/`"off"` for `autocorrect`), and omitting one selects a third state, so the boolean form rendered the opposite of what was meant                                                                                                      | Write the keyword: `draggable="true"`, `spellCheck="false"`, `writingsuggestions="false"`, `translate="no"`, `autocorrect="off"`. Omit for the default state. Real boolean attrs (`hidden`, `checked`, `disabled`, `autofocus`, `required`, `inert`) are unaffected, as is `popover` (bare form = the spec's `auto` state); for a signal use `signal('true')` |
+| `<select value={x}>` / `<textarea value={x}>` won't typecheck                                                                                                      | neither element has a `value` content attribute — the markup was inert                                                                                                                                                                                                                                                                                                                  | `<option value="b" selected>`; `<textarea>{draft}</textarea>`                                                                                                                                                                                                                                                                                                 |
+| Focus / cursor lost on every keystroke                                                                                                                             | list items lack `data-key`                                                                                                                                                                                                                                                                                                                                                              | Add `data-key` (or `id`) to each list item                                                                                                                                                                                                                                                                                                                    |
+| Click handler stops firing after re-render                                                                                                                         | `el.addEventListener` was used                                                                                                                                                                                                                                                                                                                                                          | Replace with `delegate(rootEl, 'click', ACTIONS.foo.selector, ...)` (or a string literal for ad-hoc cases)                                                                                                                                                                                                                                                    |
+| Render fn never re-runs                                                                                                                                            | signal was read outside the render fn                                                                                                                                                                                                                                                                                                                                                   | Move `signal.value` read inside the render fn                                                                                                                                                                                                                                                                                                                 |
+| SVG renders as broken / namespaceless markup                                                                                                                       | `innerHTML` used directly                                                                                                                                                                                                                                                                                                                                                               | Use `mount` or `toElement` (SVG-aware)                                                                                                                                                                                                                                                                                                                        |
+| Library widget destroyed on every render                                                                                                                           | host reachable by the morph                                                                                                                                                                                                                                                                                                                                                             | Wrap host in `data-morph-skip`; mount the library imperatively after first render                                                                                                                                                                                                                                                                             |
+| `<my-tag>` fails to typecheck                                                                                                                                      | declaration merging targeted global JSX                                                                                                                                                                                                                                                                                                                                                 | Use `declare module 'kerfjs/jsx-runtime' { namespace JSX { … } }` instead                                                                                                                                                                                                                                                                                     |
+| `each(): row render at index N produced K top-level elements`                                                                                                      | row returned multiple sibling elements or zero                                                                                                                                                                                                                                                                                                                                          | Wrap them in one parent so the row renders exactly one element                                                                                                                                                                                                                                                                                                |
+| 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                                                                                                                                                                                                                                 |
+| An `each()` list's rows lose focus / scroll / typing state when an unrelated conditional list above them appears or disappears (kerf warns about this in dev)      | Lists without a key are identified by their 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 the HTML it rendered at its old index                                                                                                                                                                     | Fold the index into the memo key so displaced rows re-render: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `KERF_DEV_WARN_STALE_INDEX=1`                                                                                                                                                                      |
 
 ## Workflow guidance
 

package/dist/actions.d.ts

@@ -1,4 +1,4 @@
-import { A as AttrSpec } from './attrSelector-Cmu2ZoGO.js';
+import { A as AttrSpec } from './attr-Cmu2ZoGO.js';
 import { D as DelegateOptions } from './delegate-CL9VTZFb.js';
 
 /**

package/dist/actions.js

@@ -1,6 +1,6 @@
-import { attr } from './chunk-U32TFTGZ.js';
-import { delegate } from './chunk-KEZTD6H4.js';
-import './chunk-VVDJLWMP.js';
+import { attr } from './chunk-MK42GLPV.js';
+import { delegate } from './chunk-E5R5GNKE.js';
+
 
 // src/actions.ts
 var DEFAULT_ACTION_ATTR = "data-action";
@@ -22,5 +22,5 @@ function delegateActions(root, eventType, table, options) {
 }
 
 export { action, delegateActions };
-//# sourceMappingURL=actions.js.map
+
 //# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/actions.ts"],"names":[],"mappings":";;;;;AAmCA,IAAM,mBAAA,GAAsB,aAAA;AAerB,SAAS,OAAyB,KAAA,EAAsC;AAC7E,EAAA,OAAO,IAAA,CAAK,qBAAqB,KAAK,CAAA;AACxC;AAwBO,SAAS,eAAA,CACd,IAAA,EACA,SAAA,EACA,KAAA,EACA,OAAA,EACY;AACZ,EAAA,MAAM,QAAA,GAAW,SAAS,IAAA,IAAQ,mBAAA;AAClC,EAAA,OAAO,QAAA;AAAA,IACL,IAAA;AAAA,IACA,SAAA;AAAA,IACA,IAAI,QAAQ,CAAA,CAAA,CAAA;AAAA,IACZ,CAAC,OAAO,EAAA,KAAO;AAEb,MAAA,MAAM,OAAA,GAAU,KAAA,CAAM,EAAA,CAAG,YAAA,CAAa,QAAQ,CAAW,CAAA;AACzD,MAAA,IAAI,OAAA,KAAY,MAAA,EAAW,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAA;AAAA,IAC9C,CAAA;AAAA,IACA;AAAA,GACF;AACF","file":"actions.js","sourcesContent":["/**\n * `kerfjs/actions` — the delegated action-table helper.\n *\n * The most-reinvented idiom across real kerf apps: one table of `data-action`\n * attribute specs used as the single source of truth for BOTH the JSX attribute\n * and the delegate selector, plus a hand-rolled `switch (dataset.action)`\n * dispatcher. This subpath blesses it as two thin helpers over the existing\n * `attr()` + `delegate()` — it does NOT replace them.\n *\n *   import { action, delegateActions } from 'kerfjs/actions';\n *\n *   const A = {\n *     select: action('select-file'),\n *     remove: action('remove-file'),\n *   };\n *\n *   // JSX — spread the attr (rename-safe; no hardcoded attribute name):\n *   //   <button {...A.select.attrs} data-id={id}>…</button>\n *\n *   // Wire the whole table with ONE delegated listener; returns a disposer:\n *   const dispose = delegateActions(root, 'click', {\n *     [A.select.value]: (_e, el) => selectFile(el.getAttribute('data-id')),\n *     [A.remove.value]: (_e, el) => removeFile(el.getAttribute('data-id')),\n *   });\n *\n * Contract: `delegateActions` returns a `() => void` disposer and holds no\n * per-instance state — the same shape as `delegate()`, which it builds on (so\n * it inherits the single-listener dispatch and the capture auto-promotion for\n * well-known non-bubbling event types). One event type per call, mirroring\n * `delegate()`; collect the disposers for a root that needs several.\n */\nimport { attr, type AttrSpec } from './attrSelector.js';\nimport { delegate, type DelegateOptions } from './delegate.js';\n\n/** The attribute an action table keys on by default. */\nconst DEFAULT_ACTION_ATTR = 'data-action';\n\n/**\n * A handler in a {@link delegateActions} table. Receives the DOM event and the\n * matched element (walk-up `closest()` match by default) — the same shape as a\n * `delegate()` handler.\n */\nexport type ActionHandler<E extends Element = Element> = (event: Event, el: E) => void;\n\n/**\n * `action(value)` — an {@link AttrSpec} on `data-action`. A thin specialization\n * of `attr('data-action', value)`: spread its `.attrs` in JSX and use its\n * `.value` as the handler-table key, so the action name lives in exactly one\n * place and can't drift between the markup and the dispatcher.\n */\nexport function action<V extends string>(value: V): AttrSpec<'data-action', V> {\n  return attr(DEFAULT_ACTION_ATTR, value);\n}\n\n/** Options for {@link delegateActions}. Extends {@link DelegateOptions}. */\nexport interface DelegateActionsOptions extends DelegateOptions {\n  /**\n   * The attribute the table keys on. Default `'data-action'`. Override it only\n   * if you also author the specs with `attr(yourName, …)` instead of `action()`.\n   */\n  attr?: string;\n}\n\n/**\n * Wire a whole table of action handlers with ONE delegated listener.\n *\n * On `eventType`, the nearest element carrying the action attribute (walk-up\n * `closest()` by default; pass `{ match: 'direct' }` for an exact-element match)\n * is looked up in `table` by its attribute value, and the matching handler\n * runs. An element whose action is absent from the table is ignored — the same\n * behavior as a `switch (dataset.action)` with no matching `case`.\n *\n * Returns a `() => void` disposer. One event type per call (the smallest\n * surface, mirroring `delegate()`); collect the disposers when a root needs\n * several event types.\n */\nexport function delegateActions<E extends Element = Element>(\n  root: HTMLElement,\n  eventType: string,\n  table: Readonly<Record<string, ActionHandler<E>>>,\n  options?: DelegateActionsOptions,\n): () => void {\n  const attrName = options?.attr ?? DEFAULT_ACTION_ATTR;\n  return delegate<E>(\n    root,\n    eventType,\n    `[${attrName}]`,\n    (event, el) => {\n      // `el` matched `[${attrName}]`, so the attribute is always present.\n      const handler = table[el.getAttribute(attrName) as string];\n      if (handler !== undefined) handler(event, el);\n    },\n    options,\n  );\n}\n"]}
+{"version":3,"sources":["../src/actions.ts"],"names":[],"mappings":";;;;;AAmCA,IAAM,mBAAA,GAAsB,aAAA;AAkBrB,SAAS,OAAyB,KAAA,EAAsC;AAC7E,EAAA,OAAO,IAAA,CAAK,qBAAqB,KAAK,CAAA;AACxC;AAwBO,SAAS,eAAA,CACd,IAAA,EACA,SAAA,EACA,KAAA,EACA,OAAA,EACY;AACZ,EAAA,MAAM,QAAA,GAAW,SAAS,IAAA,IAAQ,mBAAA;AAClC,EAAA,OAAO,QAAA;AAAA,IACL,IAAA;AAAA,IACA,SAAA;AAAA,IACA,IAAI,QAAQ,CAAA,CAAA,CAAA;AAAA,IACZ,CAAC,OAAO,EAAA,KAAO;AAEb,MAAA,MAAM,OAAA,GAAU,KAAA,CAAM,EAAA,CAAG,YAAA,CAAa,QAAQ,CAAW,CAAA;AACzD,MAAA,IAAI,OAAA,KAAY,MAAA,EAAW,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAA;AAAA,IAC9C,CAAA;AAAA,IACA;AAAA,GACF;AACF","file":"actions.js","sourcesContent":["/**\n * `kerfjs/actions` — the delegated action-table helper.\n *\n * The most-reinvented idiom across real kerf apps: one table of `data-action`\n * attribute specs used as the single source of truth for BOTH the JSX attribute\n * and the delegate selector, plus a hand-rolled `switch (dataset.action)`\n * dispatcher. This subpath blesses it as two thin helpers over the existing\n * `attr()` + `delegate()` — it does NOT replace them.\n *\n *   import { action, delegateActions } from 'kerfjs/actions';\n *\n *   const A = {\n *     select: action('select-file'),\n *     remove: action('remove-file'),\n *   };\n *\n *   // JSX — spread the attr (rename-safe; no hardcoded attribute name):\n *   //   <button {...A.select.attrs} data-id={id}>…</button>\n *\n *   // Wire the whole table with ONE delegated listener; returns a disposer:\n *   const dispose = delegateActions(root, 'click', {\n *     [A.select.value]: (_e, el) => selectFile(el.getAttribute('data-id')),\n *     [A.remove.value]: (_e, el) => removeFile(el.getAttribute('data-id')),\n *   });\n *\n * Contract: `delegateActions` returns a `() => void` disposer and holds no\n * per-instance state — the same shape as `delegate()`, which it builds on (so\n * it inherits the single-listener dispatch and the capture auto-promotion for\n * well-known non-bubbling event types). One event type per call, mirroring\n * `delegate()`; collect the disposers for a root that needs several.\n */\nimport { attr, type AttrSpec } from './attr.js';\nimport { delegate, type DelegateOptions } from './delegate.js';\n\n/** The attribute an action table keys on by default. */\nconst DEFAULT_ACTION_ATTR = 'data-action';\n\n/**\n * A handler in a {@link delegateActions} table. Receives the DOM event and the\n * matched element (walk-up `closest()` match by default) — the same shape as a\n * `delegate()` handler.\n */\nexport type ActionHandler<E extends Element = Element> = (\n  event: Event,\n  el: E,\n) => void;\n\n/**\n * `action(value)` — an {@link AttrSpec} on `data-action`. A thin specialization\n * of `attr('data-action', value)`: spread its `.attrs` in JSX and use its\n * `.value` as the handler-table key, so the action name lives in exactly one\n * place and can't drift between the markup and the dispatcher.\n */\nexport function action<V extends string>(value: V): AttrSpec<'data-action', V> {\n  return attr(DEFAULT_ACTION_ATTR, value);\n}\n\n/** Options for {@link delegateActions}. Extends {@link DelegateOptions}. */\nexport interface DelegateActionsOptions extends DelegateOptions {\n  /**\n   * The attribute the table keys on. Default `'data-action'`. Override it only\n   * if you also author the specs with `attr(yourName, …)` instead of `action()`.\n   */\n  attr?: string;\n}\n\n/**\n * Wire a whole table of action handlers with ONE delegated listener.\n *\n * On `eventType`, the nearest element carrying the action attribute (walk-up\n * `closest()` by default; pass `{ match: 'direct' }` for an exact-element match)\n * is looked up in `table` by its attribute value, and the matching handler\n * runs. An element whose action is absent from the table is ignored — the same\n * behavior as a `switch (dataset.action)` with no matching `case`.\n *\n * Returns a `() => void` disposer. One event type per call (the smallest\n * surface, mirroring `delegate()`); collect the disposers when a root needs\n * several event types.\n */\nexport function delegateActions<E extends Element = Element>(\n  root: HTMLElement,\n  eventType: string,\n  table: Readonly<Record<string, ActionHandler<E>>>,\n  options?: DelegateActionsOptions,\n): () => void {\n  const attrName = options?.attr ?? DEFAULT_ACTION_ATTR;\n  return delegate<E>(\n    root,\n    eventType,\n    `[${attrName}]`,\n    (event, el) => {\n      // `el` matched `[${attrName}]`, so the attribute is always present.\n      const handler = table[el.getAttribute(attrName) as string];\n      if (handler !== undefined) handler(event, el);\n    },\n    options,\n  );\n}\n"]}

package/dist/array-signal.js

@@ -1,6 +1,6 @@
-export { ARRAY_SIGNAL_BRAND, ArraySignal, arraySignal } from './chunk-MRYM3O3V.js';
-import './chunk-QIP723L4.js';
-import './chunk-3APBEVHF.js';
-import './chunk-VVDJLWMP.js';
-//# sourceMappingURL=array-signal.js.map
+export { ARRAY_SIGNAL_BRAND, ArraySignal, arraySignal } from './chunk-ELXVRKY2.js';
+
+
+
+
 //# sourceMappingURL=array-signal.js.map

package/dist/async.js

@@ -1,5 +1,5 @@
-import { signal } from './chunk-3APBEVHF.js';
-import './chunk-VVDJLWMP.js';
+import { signal } from './chunk-Y2FOYPBV.js';
+
 
 // src/async.ts
 function resource(options = {}) {
@@ -47,28 +47,38 @@ function resource(options = {}) {
         state.value = { ...state.value, progress: { completed, total } };
       }
     };
-    return fetcher(report).then(
-      (data) => {
-        if (gen === generation) {
-          if (key !== void 0) cache.set(key, data);
-          state.value = {
-            status: "completed",
-            data,
-            error: void 0,
-            progress: void 0,
-            input,
-            revision: commit(data)
-          };
-        }
-        return data;
-      },
-      (error) => {
-        if (gen === generation) {
-          state.value = { ...state.value, status: "failed", error, progress: void 0, input };
-        }
-        return void 0;
+    const fail = (error) => {
+      if (gen === generation) {
+        state.value = {
+          ...state.value,
+          status: "failed",
+          error,
+          progress: void 0,
+          input
+        };
       }
-    );
+      return void 0;
+    };
+    let pending;
+    try {
+      pending = fetcher(report);
+    } catch (error) {
+      return Promise.resolve(fail(error));
+    }
+    return pending.then((data) => {
+      if (gen === generation) {
+        if (key !== void 0) cache.set(key, data);
+        state.value = {
+          status: "completed",
+          data,
+          error: void 0,
+          progress: void 0,
+          input,
+          revision: commit(data)
+        };
+      }
+      return data;
+    }, fail);
   }
   function reset() {
     generation++;
@@ -98,5 +108,5 @@ function resource(options = {}) {
 }
 
 export { resource };
-//# sourceMappingURL=async.js.map
+
 //# sourceMappingURL=async.js.map

package/dist/async.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/async.ts"],"names":[],"mappings":"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","file":"async.js","sourcesContent":["/**\n * `kerfjs/async` — model async state, with the stale-response guard built in.\n *\n * Every real kerf app reproduces the same shape — `{ status, data, error }` —\n * for loading/error UI, each paired with a hand-rolled generation counter so a\n * slow response can't overwrite a newer one. This subpath blesses exactly that,\n * and no more: you still write the fetch (Node `fetch` for SSR, browser `fetch`\n * client-side), and `.run()` owns the status transitions plus the stale guard.\n *\n *   import { resource } from 'kerfjs/async';\n *\n *   const users = resource<User[]>();\n *   users.run(() => fetch('/api/users').then((r) => r.json()));\n *   // render off users.value.status: 'idle' | 'running' | 'completed' | 'failed'\n *\n * Only the LATEST run may resolve the state, so out-of-order responses are\n * dropped automatically. Optional progress: declare the `report` parameter on\n * your fetcher and call it (e.g. from an upload's progress events).\n *\n * Pass an input — `run(input, fetcher)` — to carry which request a run is for\n * through to `value.input` (set for `running`/`completed`/`failed`), so a\n * failure handler can recover the id/params of the run that failed:\n *\n *   const diff = resource<Diff, { fileId: string }>();\n *   diff.run({ fileId }, (report) => fetchDiff(fileId, report));\n *   // on failure: diff.value.status === 'failed' && diff.value.input.fileId\n *\n * For a real SWR-with-cache section, pass `cacheKey` to keep the last value PER\n * input key (switching back to a loaded key paints its cached slice instantly\n * while it revalidates), and read `value.revision` — a counter that bumps only\n * when `data` actually CHANGES (by `equals`, default `Object.is`) — to skip a\n * redundant paint when a poll tick returns identical data:\n *\n *   const win = resource<Slice, string>({ cacheKey: (w) => w, equals: sameSlice });\n *   win.run(w, () => fetchSlice(w));  // instant cached paint for a revisited w\n */\nimport { signal } from './reactive.js';\n\n/** The lifecycle status of a {@link Resource}. */\nexport type ResourceStatus = 'idle' | 'running' | 'completed' | 'failed';\n\n/** Optional progress for a long-running fetch (uploads, chunked work). */\nexport interface ResourceProgress {\n  completed: number;\n  total: number;\n}\n\n/** The reactive state a {@link Resource} exposes. */\nexport interface ResourceState<T, I = void> {\n  status: ResourceStatus;\n  /** The last successful value. Kept across a re-run (stale-while-revalidate) and on failure. */\n  data: T | undefined;\n  /** The rejection from the most recent failed run. */\n  error: unknown;\n  /** Latest reported progress while running, or `undefined`. */\n  progress: ResourceProgress | undefined;\n  /**\n   * The input of the LATEST run — the value passed to {@link Resource.run} as\n   * `run(input, fetcher)`. Set for `running`, `completed`, AND `failed` (same\n   * stale-guard rule as the rest of the state), so an effect can branch on\n   * `status === 'failed'` and still know which request failed. `undefined` in\n   * `idle`, and for the no-input `run(fetcher)` form.\n   */\n  input: I | undefined;\n  /**\n   * A monotonic counter that increments only when `data` actually CHANGES (by\n   * the resource's `equals`, default `Object.is`). Compare it against the value\n   * you last painted to skip a redundant re-render — e.g. a 30s poll returning\n   * identical data leaves `revision` untouched, so you can bail before wiping\n   * scroll / sort / hover state. Starts at `0`.\n   */\n  revision: number;\n}\n\n/** Construction options for {@link resource}. */\nexport interface ResourceOptions<T, I = void> {\n  /**\n   * Derive a cache key from a run's `input`. When set, the resource keeps the\n   * last successful value PER key: starting a run for a key that was loaded\n   * before paints its cached slice immediately (still `running`) while the fetch\n   * revalidates in the background; a never-loaded key starts with no `data`.\n   * Without `cacheKey`, a run keeps the previous run's `data` (single-slot\n   * stale-while-revalidate), as before.\n   */\n  cacheKey?: (input: I) => string;\n  /**\n   * Equality used to decide whether `data` changed (drives `value.revision`).\n   * Default `Object.is`. Pass a structural comparison to dedup a poll that\n   * returns a fresh-but-equal object.\n   */\n  equals?: (a: T, b: T) => boolean;\n}\n\n/**\n * The fetcher passed to {@link Resource.run}. You own the transport. It receives\n * a `report(completed, total)` callback for optional progress — ignore it if you\n * don't need progress (a plain `() => Promise<T>` is assignable here).\n */\nexport type ResourceFetcher<T> = (report: (completed: number, total: number) => void) => Promise<T>;\n\n/**\n * An async-state container. Its `value` is a tracking read; drive UI off\n * `value.status`. `I` is the run-input type — parametrize it (`resource<T, I>()`)\n * to carry a typed `run(input, fetcher)` input through to `value.input`.\n */\nexport interface Resource<T, I = void> {\n  /** Tracking read of the current {@link ResourceState}. */\n  readonly value: ResourceState<T, I>;\n  /**\n   * Run `fetcher`, driving `idle`/`running` → `completed`/`failed` and guarding\n   * against stale responses (only the latest run resolves the state). Never\n   * rejects — a failure lands in `value.error`; resolves with the data (or\n   * `undefined` on failure) for callers who want to await it.\n   */\n  run(fetcher: ResourceFetcher<T>): Promise<T | undefined>;\n  /**\n   * Run `fetcher` for a given `input`, exposing it as `value.input` for the\n   * `running`/`completed`/`failed` states of THIS run — so a failure handler can\n   * recover which request failed. Same stale guard: only the latest run resolves.\n   */\n  run(input: I, fetcher: ResourceFetcher<T>): Promise<T | undefined>;\n  /** Reset to `idle` (clearing data/error/progress/input, and the per-key cache) and invalidate any in-flight run. */\n  reset(): void;\n  /**\n   * Read-only: the cached value for a `cacheKey` key, or `undefined` if that key\n   * isn't cached (or no `cacheKey` was given). Lets a consumer ask \"is this slice\n   * cached?\" without running it (which would mutate state).\n   */\n  cached(key: string): T | undefined;\n  /** Read-only: the keys currently in the per-input cache (`.length` is the cache size). */\n  cachedKeys(): string[];\n  /** Evict the per-input cache — one `key`, or the whole cache when called with no argument. Does NOT change `value`. */\n  clearCache(key?: string): void;\n}\n\n/** Create an async-state {@link Resource}. No per-instance framework state — it's a closure over a signal. */\nexport function resource<T, I = void>(options: ResourceOptions<T, I> = {}): Resource<T, I> {\n  const { cacheKey, equals } = options;\n  const eq: (a: T, b: T) => boolean = equals ?? Object.is;\n  const cache = new Map<string, T>(); // per-key SWR cache (GC-tied to the resource)\n\n  // Revision tracking: `revision` bumps only when `data` changes (by `eq`).\n  let revision = 0;\n  let lastData: T | undefined;\n  const changed = (next: T | undefined): boolean =>\n    // undefined transitions are handled by reference; two defined values by `eq`.\n    lastData === undefined || next === undefined ? lastData !== next : !eq(lastData, next);\n  const commit = (next: T | undefined): number => {\n    if (changed(next)) {\n      revision++;\n      lastData = next;\n    }\n    return revision;\n  };\n\n  const state = signal<ResourceState<T, I>>({\n    status: 'idle',\n    data: undefined,\n    error: undefined,\n    progress: undefined,\n    input: undefined,\n    revision: 0,\n  });\n  // Per-resource run counter (closure-local, not module state) — the stale guard.\n  let generation = 0;\n\n  function run(\n    inputOrFetcher: I | ResourceFetcher<T>,\n    maybeFetcher?: ResourceFetcher<T>,\n  ): Promise<T | undefined> {\n    // Two-arg form is (input, fetcher); one-arg form is (fetcher) with no input.\n    // A fetcher is always a function, so `maybeFetcher === undefined` uniquely\n    // identifies the one-arg call — even when the input value is itself undefined.\n    const fetcher = (maybeFetcher ?? inputOrFetcher) as ResourceFetcher<T>;\n    const input = (maybeFetcher === undefined ? undefined : inputOrFetcher) as I | undefined;\n    const key = cacheKey !== undefined && maybeFetcher !== undefined ? cacheKey(input as I) : undefined;\n\n    // What `data` shows while running: the cached slice for this key (per-key\n    // SWR), or the previous run's data (single-slot SWR) when no cacheKey.\n    const runningData = cacheKey !== undefined\n      ? (key !== undefined ? cache.get(key) : undefined)\n      : state.value.data;\n\n    const gen = ++generation;\n    state.value = {\n      status: 'running',\n      data: runningData,\n      error: undefined,\n      progress: undefined,\n      input,\n      revision: commit(runningData),\n    };\n\n    const report = (completed: number, total: number): void => {\n      if (gen === generation) {\n        state.value = { ...state.value, progress: { completed, total } };\n      }\n    };\n\n    return fetcher(report).then(\n      (data) => {\n        if (gen === generation) {\n          if (key !== undefined) cache.set(key, data);\n          state.value = {\n            status: 'completed',\n            data,\n            error: undefined,\n            progress: undefined,\n            input,\n            revision: commit(data),\n          };\n        }\n        return data;\n      },\n      (error: unknown) => {\n        if (gen === generation) {\n          // Keep `data` (and thus `revision`) on failure — stale-while-error.\n          state.value = { ...state.value, status: 'failed', error, progress: undefined, input };\n        }\n        return undefined;\n      },\n    );\n  }\n\n  function reset(): void {\n    generation++; // invalidate any in-flight run\n    cache.clear();\n    state.value = {\n      status: 'idle',\n      data: undefined,\n      error: undefined,\n      progress: undefined,\n      input: undefined,\n      revision: commit(undefined),\n    };\n  }\n\n  return {\n    get value() {\n      return state.value;\n    },\n    run,\n    reset,\n    cached: (k) => cache.get(k),\n    cachedKeys: () => Array.from(cache.keys()),\n    clearCache: (k) => {\n      if (k === undefined) cache.clear();\n      else cache.delete(k);\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../src/async.ts"],"names":[],"mappings":"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","file":"async.js","sourcesContent":["/**\n * `kerfjs/async` — model async state, with the stale-response guard built in.\n *\n * Every real kerf app reproduces the same shape — `{ status, data, error }` —\n * for loading/error UI, each paired with a hand-rolled generation counter so a\n * slow response can't overwrite a newer one. This subpath blesses exactly that,\n * and no more: you still write the fetch (Node `fetch` for SSR, browser `fetch`\n * client-side), and `.run()` owns the status transitions plus the stale guard.\n *\n *   import { resource } from 'kerfjs/async';\n *\n *   const users = resource<User[]>();\n *   users.run(() => fetch('/api/users').then((r) => r.json()));\n *   // render off users.value.status: 'idle' | 'running' | 'completed' | 'failed'\n *\n * Only the LATEST run may resolve the state, so out-of-order responses are\n * dropped automatically. Optional progress: declare the `report` parameter on\n * your fetcher and call it (e.g. from an upload's progress events).\n *\n * Pass an input — `run(input, fetcher)` — to carry which request a run is for\n * through to `value.input` (set for `running`/`completed`/`failed`), so a\n * failure handler can recover the id/params of the run that failed:\n *\n *   const diff = resource<Diff, { fileId: string }>();\n *   diff.run({ fileId }, (report) => fetchDiff(fileId, report));\n *   // on failure: diff.value.status === 'failed' && diff.value.input.fileId\n *\n * For a real SWR-with-cache section, pass `cacheKey` to keep the last value PER\n * input key (switching back to a loaded key paints its cached slice instantly\n * while it revalidates), and read `value.revision` — a counter that bumps only\n * when `data` actually CHANGES (by `equals`, default `Object.is`) — to skip a\n * redundant paint when a poll tick returns identical data:\n *\n *   const win = resource<Slice, string>({ cacheKey: (w) => w, equals: sameSlice });\n *   win.run(w, () => fetchSlice(w));  // instant cached paint for a revisited w\n */\nimport { signal } from './reactive.js';\n\n/** The lifecycle status of a {@link Resource}. */\nexport type ResourceStatus = 'idle' | 'running' | 'completed' | 'failed';\n\n/** Optional progress for a long-running fetch (uploads, chunked work). */\nexport interface ResourceProgress {\n  completed: number;\n  total: number;\n}\n\n/** The reactive state a {@link Resource} exposes. */\nexport interface ResourceState<T, I = void> {\n  status: ResourceStatus;\n  /** The last successful value. Kept across a re-run (stale-while-revalidate) and on failure. */\n  data: T | undefined;\n  /** The rejection from the most recent failed run. */\n  error: unknown;\n  /** Latest reported progress while running, or `undefined`. */\n  progress: ResourceProgress | undefined;\n  /**\n   * The input of the LATEST run — the value passed to {@link Resource.run} as\n   * `run(input, fetcher)`. Set for `running`, `completed`, AND `failed` (same\n   * stale-guard rule as the rest of the state), so an effect can branch on\n   * `status === 'failed'` and still know which request failed. `undefined` in\n   * `idle`, and for the no-input `run(fetcher)` form.\n   */\n  input: I | undefined;\n  /**\n   * A monotonic counter that increments only when `data` actually CHANGES (by\n   * the resource's `equals`, default `Object.is`). Compare it against the value\n   * you last painted to skip a redundant re-render — e.g. a 30s poll returning\n   * identical data leaves `revision` untouched, so you can bail before wiping\n   * scroll / sort / hover state. Starts at `0`.\n   */\n  revision: number;\n}\n\n/** Construction options for {@link resource}. */\nexport interface ResourceOptions<T, I = void> {\n  /**\n   * Derive a cache key from a run's `input`. When set, the resource keeps the\n   * last successful value PER key: starting a run for a key that was loaded\n   * before paints its cached slice immediately (still `running`) while the fetch\n   * revalidates in the background; a never-loaded key starts with no `data`.\n   * Without `cacheKey`, a run keeps the previous run's `data` (single-slot\n   * stale-while-revalidate), as before.\n   */\n  cacheKey?: (input: I) => string;\n  /**\n   * Equality used to decide whether `data` changed (drives `value.revision`).\n   * Default `Object.is`. Pass a structural comparison to dedup a poll that\n   * returns a fresh-but-equal object.\n   */\n  equals?: (a: T, b: T) => boolean;\n}\n\n/**\n * The fetcher passed to {@link Resource.run}. You own the transport. It receives\n * a `report(completed, total)` callback for optional progress — ignore it if you\n * don't need progress (a plain `() => Promise<T>` is assignable here).\n */\nexport type ResourceFetcher<T> = (\n  report: (completed: number, total: number) => void,\n) => Promise<T>;\n\n/**\n * An async-state container. Its `value` is a tracking read; drive UI off\n * `value.status`. `I` is the run-input type — parametrize it (`resource<T, I>()`)\n * to carry a typed `run(input, fetcher)` input through to `value.input`.\n */\nexport interface Resource<T, I = void> {\n  /** Tracking read of the current {@link ResourceState}. */\n  readonly value: ResourceState<T, I>;\n  /**\n   * Run `fetcher`, driving `idle`/`running` → `completed`/`failed` and guarding\n   * against stale responses (only the latest run resolves the state). Never\n   * rejects — a failure lands in `value.error`; resolves with the data (or\n   * `undefined` on failure) for callers who want to await it.\n   */\n  run(fetcher: ResourceFetcher<T>): Promise<T | undefined>;\n  /**\n   * Run `fetcher` for a given `input`, exposing it as `value.input` for the\n   * `running`/`completed`/`failed` states of THIS run — so a failure handler can\n   * recover which request failed. Same stale guard: only the latest run resolves.\n   */\n  run(input: I, fetcher: ResourceFetcher<T>): Promise<T | undefined>;\n  /** Reset to `idle` (clearing data/error/progress/input, and the per-key cache) and invalidate any in-flight run. */\n  reset(): void;\n  /**\n   * Read-only: the cached value for a `cacheKey` key, or `undefined` if that key\n   * isn't cached (or no `cacheKey` was given). Lets a consumer ask \"is this slice\n   * cached?\" without running it (which would mutate state).\n   */\n  cached(key: string): T | undefined;\n  /** Read-only: the keys currently in the per-input cache (`.length` is the cache size). */\n  cachedKeys(): string[];\n  /** Evict the per-input cache — one `key`, or the whole cache when called with no argument. Does NOT change `value`. */\n  clearCache(key?: string): void;\n}\n\n/** Create an async-state {@link Resource}. No per-instance framework state — it's a closure over a signal. */\nexport function resource<T, I = void>(\n  options: ResourceOptions<T, I> = {},\n): Resource<T, I> {\n  const { cacheKey, equals } = options;\n  const eq: (a: T, b: T) => boolean = equals ?? Object.is;\n  const cache = new Map<string, T>(); // per-key SWR cache (GC-tied to the resource)\n\n  // Revision tracking: `revision` bumps only when `data` changes (by `eq`).\n  let revision = 0;\n  let lastData: T | undefined;\n  const changed = (next: T | undefined): boolean =>\n    // undefined transitions are handled by reference; two defined values by `eq`.\n    lastData === undefined || next === undefined\n      ? lastData !== next\n      : !eq(lastData, next);\n  const commit = (next: T | undefined): number => {\n    if (changed(next)) {\n      revision++;\n      lastData = next;\n    }\n    return revision;\n  };\n\n  const state = signal<ResourceState<T, I>>({\n    status: 'idle',\n    data: undefined,\n    error: undefined,\n    progress: undefined,\n    input: undefined,\n    revision: 0,\n  });\n  // Per-resource run counter (closure-local, not module state) — the stale guard.\n  let generation = 0;\n\n  function run(\n    inputOrFetcher: I | ResourceFetcher<T>,\n    maybeFetcher?: ResourceFetcher<T>,\n  ): Promise<T | undefined> {\n    // Two-arg form is (input, fetcher); one-arg form is (fetcher) with no input.\n    // A fetcher is always a function, so `maybeFetcher === undefined` uniquely\n    // identifies the one-arg call — even when the input value is itself undefined.\n    const fetcher = (maybeFetcher ?? inputOrFetcher) as ResourceFetcher<T>;\n    const input = (maybeFetcher === undefined ? undefined : inputOrFetcher) as\n      I | undefined;\n    const key =\n      cacheKey !== undefined && maybeFetcher !== undefined\n        ? cacheKey(input as I)\n        : undefined;\n\n    // What `data` shows while running: the cached slice for this key (per-key\n    // SWR), or the previous run's data (single-slot SWR) when no cacheKey.\n    const runningData =\n      cacheKey !== undefined\n        ? key !== undefined\n          ? cache.get(key)\n          : undefined\n        : state.value.data;\n\n    const gen = ++generation;\n    state.value = {\n      status: 'running',\n      data: runningData,\n      error: undefined,\n      progress: undefined,\n      input,\n      revision: commit(runningData),\n    };\n\n    const report = (completed: number, total: number): void => {\n      if (gen === generation) {\n        state.value = { ...state.value, progress: { completed, total } };\n      }\n    };\n\n    const fail = (error: unknown): undefined => {\n      if (gen === generation) {\n        // Keep `data` (and thus `revision`) on failure — stale-while-error.\n        state.value = {\n          ...state.value,\n          status: 'failed',\n          error,\n          progress: undefined,\n          input,\n        };\n      }\n      return undefined;\n    };\n\n    let pending: Promise<T>;\n    try {\n      pending = fetcher(report);\n    } catch (error: unknown) {\n      return Promise.resolve(fail(error));\n    }\n\n    return pending.then((data) => {\n      if (gen === generation) {\n        if (key !== undefined) cache.set(key, data);\n        state.value = {\n          status: 'completed',\n          data,\n          error: undefined,\n          progress: undefined,\n          input,\n          revision: commit(data),\n        };\n      }\n      return data;\n    }, fail);\n  }\n\n  function reset(): void {\n    generation++; // invalidate any in-flight run\n    cache.clear();\n    state.value = {\n      status: 'idle',\n      data: undefined,\n      error: undefined,\n      progress: undefined,\n      input: undefined,\n      revision: commit(undefined),\n    };\n  }\n\n  return {\n    get value() {\n      return state.value;\n    },\n    run,\n    reset,\n    cached: (k) => cache.get(k),\n    cachedKeys: () => Array.from(cache.keys()),\n    clearCache: (k) => {\n      if (k === undefined) cache.clear();\n      else cache.delete(k);\n    },\n  };\n}\n"]}

package/dist/attach.d.ts

@@ -19,11 +19,13 @@
  * to wait for (this is NOT React's `useEffect`: no dependency array, no re-run,
  * no render-phase or hook-order scoping; it is closer to a Web Component's
  * `connectedCallback`/`disconnectedCallback` pair, Svelte's
- * `onMount(() => () => cleanup)`, or Solid's `onCleanup`). The returned teardown
- * runs once — whichever comes first — when the node leaves the document (detected
- * by a `MutationObserver`, so a morph swap, a `remountOn` replacement, or any
- * removal triggers it) or when the returned disposer is called. Re-creation is
- * NOT handled here: a fresh node is a fresh `attach()` call — pair it with
+ * `onMount(() => () => cleanup)`, or Solid's `onCleanup`). A node may start
+ * disconnected: setup still runs now, and teardown waits until it has first
+ * connected and subsequently leaves the document. The returned teardown runs
+ * once — whichever comes first — on that removal (detected by a
+ * `MutationObserver`, so a morph swap, a `remountOn` replacement, or any removal
+ * triggers it) or when the returned disposer is called. Re-creation is NOT
+ * handled here: a fresh node is a fresh `attach()` call — pair it with
  * `kerfjs/remount`, which replaces the node and re-runs your render (and thus
  * this call) on the new one.
  *
@@ -36,9 +38,10 @@
 /** The setup callback for {@link attach}: run against `node`, optionally return a teardown. */
 type AttachSetup = (node: Element) => (() => void) | void;
 /**
- * Run `setup(node)` now, and its returned teardown once — when `node` leaves the
- * document, or when the returned disposer is called, whichever is first. Returns
- * a disposer (idempotent) so a `mount()` / `Scope` can drive teardown explicitly.
+ * Run `setup(node)` now, and its returned teardown once — after `node` has been
+ * connected and then leaves the document, or when the returned disposer is
+ * called, whichever is first. Returns an idempotent disposer so a `mount()` /
+ * `Scope` can drive teardown explicitly.
  */
 declare function attach(node: Element, setup: AttachSetup): () => void;