kerfjs 5.0.0-beta.13 → 5.0.0-beta.130

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/CHANGELOG.md +3370 -108
  2. package/README.md +101 -37
  3. package/ai/cursorrules +127 -68
  4. package/ai/manifest.json +36 -7
  5. package/ai/skill.md +167 -86
  6. package/ai/ui-skill.md +18 -0
  7. package/dist/actions.d.ts +1 -1
  8. package/dist/actions.js +10 -6
  9. package/dist/actions.js.map +1 -1
  10. package/dist/array-signal.js +1 -1
  11. package/dist/async.d.ts +7 -3
  12. package/dist/async.js +39 -22
  13. package/dist/async.js.map +1 -1
  14. package/dist/attach.js +1 -66
  15. package/dist/attach.js.map +1 -1
  16. package/dist/{chunk-GY4XV2UV.js → chunk-4TX6YJDM.js} +10 -3
  17. package/dist/chunk-4TX6YJDM.js.map +1 -0
  18. package/dist/{chunk-SVATPF5R.js → chunk-5QDM6HPD.js} +637 -277
  19. package/dist/chunk-5QDM6HPD.js.map +1 -0
  20. package/dist/{chunk-QIP723L4.js → chunk-5WRGJZV6.js} +3 -2
  21. package/dist/chunk-5WRGJZV6.js.map +1 -0
  22. package/dist/chunk-AP2FT33F.js +87 -0
  23. package/dist/chunk-AP2FT33F.js.map +1 -0
  24. package/dist/chunk-BTOKH5FA.js +70 -0
  25. package/dist/chunk-BTOKH5FA.js.map +1 -0
  26. package/dist/{chunk-ZDCJZCNO.js → chunk-GGADRIQO.js} +168 -97
  27. package/dist/chunk-GGADRIQO.js.map +1 -0
  28. package/dist/chunk-KOEGJCIS.js +65 -0
  29. package/dist/chunk-KOEGJCIS.js.map +1 -0
  30. package/dist/{chunk-HW7KSM2Y.js → chunk-KUHXPPJ4.js} +1 -1
  31. package/dist/chunk-KUHXPPJ4.js.map +1 -0
  32. package/dist/{chunk-UZJ6I4T6.js → chunk-MK42GLPV.js} +1 -1
  33. package/dist/chunk-MK42GLPV.js.map +1 -0
  34. package/dist/chunk-N4VHHOCM.js +27 -0
  35. package/dist/chunk-N4VHHOCM.js.map +1 -0
  36. package/dist/{chunk-V46JKE44.js → chunk-NRPLVJVR.js} +43 -14
  37. package/dist/chunk-NRPLVJVR.js.map +1 -0
  38. package/dist/{chunk-LVH3GC6B.js → chunk-QOAB2ESQ.js} +3 -3
  39. package/dist/chunk-QOAB2ESQ.js.map +1 -0
  40. package/dist/{chunk-KZJXHFIB.js → chunk-V322Z7FX.js} +5 -5
  41. package/dist/chunk-V322Z7FX.js.map +1 -0
  42. package/dist/{delegate-CL9VTZFb.d.ts → delegate--CrfgYtC.d.ts} +0 -34
  43. package/dist/dev.d.ts +46 -15
  44. package/dist/dev.js +185 -40
  45. package/dist/dev.js.map +1 -1
  46. package/dist/html.js +20 -8
  47. package/dist/html.js.map +1 -1
  48. package/dist/index.d.ts +98 -13
  49. package/dist/index.js +49 -21
  50. package/dist/index.js.map +1 -1
  51. package/dist/jsx-runtime.d.ts +25 -10
  52. package/dist/jsx-runtime.js +1 -1
  53. package/dist/list.d.ts +7 -3
  54. package/dist/list.js +236 -78
  55. package/dist/list.js.map +1 -1
  56. package/dist/overlay.d.ts +287 -142
  57. package/dist/overlay.js +1039 -369
  58. package/dist/overlay.js.map +1 -1
  59. package/dist/remount.js +2 -2
  60. package/dist/remount.js.map +1 -1
  61. package/dist/router.d.ts +22 -6
  62. package/dist/router.js +58 -19
  63. package/dist/router.js.map +1 -1
  64. package/dist/scope.d.ts +45 -8
  65. package/dist/scope.js +69 -30
  66. package/dist/scope.js.map +1 -1
  67. package/dist/testing.js +1 -1
  68. package/dist/timing.d.ts +17 -7
  69. package/dist/timing.js +8 -3
  70. package/dist/timing.js.map +1 -1
  71. package/llms.txt +17 -6
  72. package/package.json +48 -12
  73. package/setup/apply.mjs +202 -0
  74. package/setup/cli.mjs +95 -0
  75. package/setup/common.mjs +77 -0
  76. package/setup/detect.mjs +274 -0
  77. package/setup/index.d.mts +39 -0
  78. package/setup/index.mjs +1226 -0
  79. package/setup/jsonc.mjs +201 -0
  80. package/setup/state.schema.json +57 -0
  81. package/setup/ui-baseline.mjs +210 -0
  82. package/dist/chunk-GY4XV2UV.js.map +0 -1
  83. package/dist/chunk-HW7KSM2Y.js.map +0 -1
  84. package/dist/chunk-KPXIOG2C.js +0 -54
  85. package/dist/chunk-KPXIOG2C.js.map +0 -1
  86. package/dist/chunk-KZJXHFIB.js.map +0 -1
  87. package/dist/chunk-LVH3GC6B.js.map +0 -1
  88. package/dist/chunk-QIP723L4.js.map +0 -1
  89. package/dist/chunk-SVATPF5R.js.map +0 -1
  90. package/dist/chunk-U6FK33SG.js +0 -20
  91. package/dist/chunk-U6FK33SG.js.map +0 -1
  92. package/dist/chunk-UZJ6I4T6.js.map +0 -1
  93. package/dist/chunk-V46JKE44.js.map +0 -1
  94. package/dist/chunk-ZDCJZCNO.js.map +0 -1
package/ai/cursorrules CHANGED
@@ -1,18 +1,23 @@
1
- <!-- kerf-skill-version: 1.20.0 -->
1
+ <!-- kerf-skill-version: 1.27.0 -->
2
+
2
3
  # kerf.cursorrules — rules for building apps with kerf
4
+
3
5
  #
6
+
4
7
  # Drop this file into your project as `.cursorrules` (Cursor will pick it
8
+
5
9
  # up automatically) when you're using kerf (https://github.com/brianwestphal/kerf).
10
+
6
11
  # These rules condense `docs/ai/usage-guide.md` into the form Cursor parses.
7
12
 
8
- You are writing a UI in kerf — a ~12 KB reactive framework (~13 KB with `arraySignal`): signals + DOM morphing + JSX → HTML strings. No virtual DOM, no compiler, no scheduler.
13
+ You are writing a UI in kerf — a ~15 KB reactive framework (still ~15 KB with `arraySignal`): signals + DOM morphing + JSX → HTML strings. No virtual DOM, no compiler, no scheduler.
9
14
 
10
15
  ## Setup
11
16
 
12
17
  - Install with `npm install kerfjs`.
13
18
  - `tsconfig.json`: `"jsx": "react-jsx"`, `"jsxImportSource": "kerfjs"`.
14
19
  - Vite / esbuild need no extra config.
15
- - **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it FIRST if relying on the untracked-signal warning — `signal()` picks its constructor at creation time.
20
+ - **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it (and any `enableWarnings()` call) FIRST if relying on the untracked-signal, delegate-in-effect, or rebuilt-listeners warnings — `signal()`, `effect()`, and `mount()` decide those at creation time, so anything created earlier stays uncovered.
16
21
  - **Switch individual warnings on with `enableWarnings()`**, which is the only switch that works in a browser (no `process` object there, and a bundler `define` cannot reach the read): `const dev = await import('kerfjs/dev'); dev.enableWarnings({ staleBinding: true, narrowSet: true, invariants: 'throw' });`. The `KERF_DEV_WARN_*` env vars do the same for Node/SSR/CI; an explicit call wins either way.
17
22
  - **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.
18
23
  - Recommended: also install `eslint-plugin-kerfjs` (`npm install --save-dev eslint-plugin-kerfjs`) and add `kerfjs.configs.recommended` to the project's eslint config. It enforces five of the hard rules below (no inline JSX event handlers, require `data-key` in `each()`, capture `delegate()` disposers, no nested `mount()`, prefer module JSX augmentation) at edit time so violations surface as IDE squiggles before any code runs.
@@ -28,79 +33,107 @@ the complete layer is intentional. Reuse these primitives before creating
28
33
  parallel local ones; keep domain state, commands, routing, and tab/menu policy
29
34
  in the app.
30
35
 
31
- Use MenuItem/MenuActionRow/MenuHeader `rootAttributes` only for application
32
- `data-*` metadata. MenuActionRow `trailingActionAttributes` and MenuHeader
36
+ Use ListItem/ListActionRow/ListHeader `rootAttributes` only for application
37
+ `data-*` metadata. ListActionRow `trailingActionAttributes` and ListHeader
33
38
  `triggerAttributes` additionally support native popover target/action and
34
39
  `aria-controls`/`aria-haspopup`. Do not use these slots to override action,
35
40
  item identity, selection, disclosure, naming, disabled, icon, or role
36
41
  semantics; one `role="menuitem"` does not make a complete menu widget.
37
- `MenuItem.trailing` is dormant. Use `MenuActionRow` for sibling primary and
42
+ `ListItem.trailing` is dormant. Use `ListActionRow` for sibling primary and
38
43
  trailing native buttons, and keep its `label`, `icon`, and
39
44
  `trailingActionIcon` SafeHtml slots free of controls.
40
45
 
41
46
  Wire emitted `data-action` hooks at the mount root and retain disposers.
42
47
  `wireResizableRegions()` and `wireTabBars()` are eventful helpers and return
43
- disposers. Compose `AppTab` inside controlled `TabBar`; `wireTabBars()` supplies
48
+ disposers. Compose `TabBarItem` inside controlled `TabBar`; `wireTabBars()` supplies
44
49
  horizontal edge autoscroll while dragging. Apply reorder reports
45
50
  with `reorderTabs()`, and keep order, selection, close policy, routing, panels,
46
- and persistence in the host. Icons/spinners are decorative unless
51
+ and persistence in the host. Toolbars draw no divider by default; call
52
+ `wireScrollDividers()` once at the app root so panes and tab bars show scroll
53
+ dividers only while content is scrolled beneath or beyond them. Icons/spinners are decorative unless
47
54
  labeled, and assertive banners are only for urgent interruption.
48
55
 
49
- The opinionated semantic ramps match Hot Sheet 2 and Web Awesome. Override
50
- `--kui-color-*` globally or component properties such as
51
- `--kui-state-banner-background` at a tone or instance boundary; do not replace
52
- private descendant selectors.
53
-
54
- For Web Awesome's broader free component set, import the CSS-only
55
- `@kerfjs/ui/webawesome.css` theme once, then import only each Web Awesome
56
- component module the app renders. The theme registers no component JavaScript
57
- and remains overridable through later or scoped `--wa-*` values.
56
+ Components own their styles; configure, never override. Set how a component
57
+ looks and sits through its typed props (size, density, inset, presentation,
58
+ `dividerSides`, `ToolbarConfig`, `PaneConfig`, …); never write application
59
+ CSS that selects a `.kui-*` class, a `[data-component]` root, a `wa-*` element
60
+ a Kerf component renders, or its `::part()`s, and never add padding, margin,
61
+ width, or height around a component to size or space it (it owns its 8px
62
+ inset — adding more double-insets). A missing prop is a component gap to
63
+ report upstream, not a reason to override. The opinionated semantic ramps
64
+ match Hot Sheet 2 and Web Awesome: override `--kui-color-*` globally or
65
+ component properties such as `--kui-state-banner-background` at a tone or
66
+ instance boundary, for theming only.
67
+
68
+ Scope a subtree to the light or dark palette with a component's
69
+ `scheme="light" | "dark"` prop or Kerf's `.kui-light` / `.kui-dark` /
70
+ `.kui-invert` classes; they need no Web Awesome CSS. Only with the optional
71
+ Web Awesome integration: import the CSS-only `@kerfjs/ui/webawesome.css` theme
72
+ once, then only each Web Awesome component module the app renders. The theme
73
+ registers no component JavaScript and remains overridable through later or
74
+ scoped `--wa-*` values.
58
75
 
59
76
  `Select` is pure markup until the app explicitly imports
60
77
  `@kerfjs/ui/select/register`. Do that once in the application entry that uses
61
78
  Select; never hide registration inside a component. Web Awesome is an optional
62
- peer and stays out of bundles that use neither Select nor the Web Awesome theme. More detail ships at
79
+ peer that only the `@kerfjs/ui/webawesome.css` theme touches. More detail ships at
63
80
  `node_modules/@kerfjs/ui/ai/skill.md`.
64
81
 
65
82
  ## Public API — one import path
66
83
 
67
84
  ```ts
68
85
  import {
69
- signal, computed, effect, batch, // reactivity
70
- defineStore, resetAllStores, // stores
71
- mount, morph, each, // render (reactive + one-shot) + keyed list
72
- delegate, delegateCapture, // events
73
- toElement, // direct JSX → DOM Element (or DocumentFragment for multi-root)
74
- SafeHtml, isSafeHtml, raw, Fragment,
75
- } from 'kerfjs';
86
+ signal,
87
+ computed,
88
+ effect,
89
+ batch,
90
+ selector,
91
+ setSelector, // reactivity
92
+ defineStore,
93
+ resetAllStores, // stores
94
+ mount,
95
+ morph,
96
+ each, // render (reactive + one-shot) + keyed list
97
+ delegate,
98
+ delegateCapture, // events
99
+ toElement, // direct JSX → DOM Element (or DocumentFragment for multi-root)
100
+ SafeHtml,
101
+ isSafeHtml,
102
+ raw,
103
+ Fragment,
104
+ type JSXChildren,
105
+ } from "kerfjs";
76
106
 
77
107
  // Optional, only when you need granular collection updates:
78
- import { arraySignal } from 'kerfjs/array-signal';
108
+ import { arraySignal } from "kerfjs/array-signal";
79
109
 
80
110
  // Development diagnostics — gate with YOUR build's dev flag, in YOUR code.
81
- if (import.meta.env.DEV) await import('kerfjs/dev');
111
+ if (import.meta.env.DEV) await import("kerfjs/dev");
82
112
  ```
83
113
 
84
- | Export | Use |
85
- | --- | --- |
86
- | `signal(initial)` | atomic reactive state; read/write via `.value` |
87
- | `computed(fn)` | derived value (read-only) |
88
- | `effect(fn)` | side effect that re-runs on signal change |
89
- | `batch(fn)` | coalesce multiple writes into one re-run |
90
- | `defineStore({initial, actions})` | named multi-consumer state |
91
- | `resetAllStores()` | reset every store (test teardown) |
92
- | `mount(el, render)` | bind reactive render to a DOM element; returns a disposer |
93
- | `morph(liveRoot, template)` | one-shot reconcile against an already-populated element (SSR hydration, page-refresh diffs). Template can be `Element`, `SafeHtml`, or HTML string |
94
- | `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 |
95
- | `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 |
96
- | `delegate(root, type, sel, h)` | one listener at the root, walks `closest(selector)` from target |
97
- | `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()` |
98
- | `attr(name, value)` | pre-computed `AttrSpec<N,V>` — `.selector` for `delegate()`, `.attrs` to spread into JSX (rename-safe) |
99
- | `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 |
100
- | `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. |
101
- | `raw(html)` | inject pre-escaped HTML |
102
- | `arraySignal(initial?)` | granular keyed-list signal at `kerfjs/array-signal` subpath; `each()` reconciles in O(patches) |
103
- | `` 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}"`) |
114
+ | Export | Use |
115
+ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
116
+ | `signal(initial)` | atomic reactive state; read/write via `.value` |
117
+ | `computed(fn)` | derived value (read-only) |
118
+ | `effect(fn)` | side effect that re-runs on signal change |
119
+ | `batch(fn)` | coalesce multiple writes into one re-run |
120
+ | `selector(source)` | keyed equality at O(1) per change: `selector(selectedId)(row.id).value` is true for the selected row; one subscription instead of one per row |
121
+ | `setSelector(source)` | membership in a `ReadonlySet` signal; a write notifies only the added/removed members (multi-select, expanded rows) |
122
+ | `defineStore({initial, actions})` | named multi-consumer state |
123
+ | `resetAllStores()` | reset every store (test teardown) |
124
+ | `mount(el, render)` | bind reactive render to a DOM element; returns a disposer |
125
+ | `morph(liveRoot, template)` | one-shot reconcile against an already-populated element (SSR hydration, page-refresh diffs). Template can be `Element`, `SafeHtml`, or HTML string |
126
+ | `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 |
127
+ | `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 |
128
+ | `delegate(root, type, sel, h)` | one listener at the root, walks `closest(selector)` from target |
129
+ | `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()` |
130
+ | `attr(name, value)` | pre-computed `AttrSpec<N,V>` — `.selector` for `delegate()`, `.attrs` to spread into JSX (rename-safe) |
131
+ | `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 |
132
+ | `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. |
133
+ | `raw(html)` | inject pre-escaped HTML |
134
+ | `JSXChildren` | recursive type for general-purpose component `children`: SafeHtml, primitives, read-only signals, nullish/boolean empty values, and readonly arrays at any depth. Use a narrower union for semantically restricted slots |
135
+ | `arraySignal(initial?)` | granular keyed-list signal at `kerfjs/array-signal` subpath; `each()` reconciles in O(patches) |
136
+ | `` 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}"`) |
104
137
 
105
138
  ## Hard rules — get these right on the first try
106
139
 
@@ -109,9 +142,9 @@ if (import.meta.env.DEV) await import('kerfjs/dev');
109
142
  3. **Escape hatches:** `data-morph-skip` (element + subtree preserved verbatim — for Monaco / xterm / D3); `data-morph-skip-children` (attrs morph, subtree preserved — for client-hydrated slots whose host classes change); `data-morph-preserve` (element survives the trailing-removal pass — for imperatively-injected nodes like autoplay videos).
110
143
  4. **Never `addEventListener` inside a `mount()`-managed tree** unless under `data-morph-skip`. A morph re-render may discard the node. Use `delegate` / `delegateCapture` instead.
111
144
  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).
112
- 6. **One `mount()` per root.** Don't nest. Compose with plain functions that return JSX.
145
+ 6. **One `mount()` per root.** Don't nest. Compose with plain functions that return JSX. One exception: a modal `<dialog>` of your own that anchors kerf `popover()` / `tooltip()` surfaces must contain `<div data-kerf-overlay-host data-morph-skip></div>` — kerf renders those surfaces into it (inside the modal, so they are not inert) and that slot is the one allowed nested-mount boundary. Dialogs `kerfjs/overlay` opens get a slot automatically.
113
146
  7. **No `<MyComponent />` semantics with hooks.** Components are plain functions returning JSX. State lives in module-scope signals or stores, never in component closures.
114
- 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.
147
+ 8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX _structure_ depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` will NOT re-render. Bind a STABLE signal/computed instance per hole (a `computed` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (`enableWarnings({ staleBinding: true })` (or `KERF_DEV_WARN_STALE_BINDING=1` under Node) detects it). Endpoint: a render reading NO `.value` runs exactly once — a fully bound mount never re-renders; `enableWarnings({ valueOnlyRerender: true })` (or `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` under Node) flags re-renders that could have been bindings.
115
148
  9. **Store actions receive `(set, get)`, not `(state)`.** `set(next)` replaces state; mutating `get()` does nothing.
116
149
  10. **Use `data-action` attributes, not inline `onClick`.** Inline handlers are NOT supported by the JSX → string runtime; delegate from the root instead.
117
150
  11. **`arraySignal` is opt-in for long keyed lists** where most updates are pointwise (single-row edits, append-to-end). For short lists / filter+sort pipelines, plain `signal` + `each(items.value, ...)` is simpler and equally fast.
@@ -124,22 +157,26 @@ if (import.meta.env.DEV) await import('kerfjs/dev');
124
157
  When deciding which primitive to reach for, work down the axes:
125
158
 
126
159
  **Events.**
160
+
127
161
  - 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.
128
162
  - 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.
129
163
  - 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.
130
164
 
131
165
  **Lists.**
166
+
132
167
  - Items change across renders (todos, chat messages, table rows) → `each(items, render)`.
133
168
  - Static structural enumeration whose row render reads signals → `STATIC.map(item => <jsx/>)`. Inner `each(item.children, …)` still gets keyed reconcile.
134
169
  - Long list with point-wise mutations → `arraySignal` + `each(arraySig, render)` for O(patches) updates.
135
170
 
136
171
  **Side effects / imperative DOM.**
172
+
137
173
  - Library-owned subtree survives across renders → `data-morph-skip` on host.
138
174
  - Host attributes morph but subtree preserved → `data-morph-skip-children`.
139
175
  - Imperatively-injected element survives the trailing-removal pass → `data-morph-preserve`.
140
176
  - Focused input / contenteditable caret survives re-renders → automatic; no opt-in.
141
177
 
142
178
  **Raw HTML.**
179
+
143
180
  - User-controlled HTML → sanitize first (DOMPurify) then `raw(sanitized)`.
144
181
  - Author-controlled trusted HTML → `raw(html)` directly.
145
182
  - Dangerous URLs (`javascript:`/`vbscript:`/script-executing `data:`) on `href`/`src`/`xlink:href`/`formaction`/`action`/`data` are dropped — kerf THROWS in dev, WARNS + drops in prod. Sanitize user URLs upstream; wrap an intentional trusted one in `raw(url)` to bypass the screen in both modes. The `javascript:` no-op placeholders (`javascript:void(0)`, `javascript:;`, …) are allowed — they're the placeholder-link idiom, matched whole so nothing can ride along.
@@ -152,20 +189,27 @@ When deciding which primitive to reach for, work down the axes:
152
189
  // updates that one node directly with no render re-run; read `.value` only
153
190
  // when the JSX STRUCTURE depends on the signal (conditionals, list shape).
154
191
  const count = signal(0);
155
- const ACTIONS = { inc: attr('data-action', 'inc') } as const satisfies Record<string, AttrSpec<'data-action'>>;
192
+ const ACTIONS = { inc: attr("data-action", "inc") } as const satisfies Record<
193
+ string,
194
+ AttrSpec<"data-action">
195
+ >;
156
196
 
157
- mount(document.getElementById('app')!, () => (
197
+ mount(document.getElementById("app")!, () => (
158
198
  <div>
159
199
  <button {...ACTIONS.inc.attrs}>+</button>
160
200
  <span>{count}</span>
161
201
  </div>
162
202
  ));
163
- delegate(rootEl, 'click', ACTIONS.inc.selector, () => { count.value += 1; });
203
+ delegate(rootEl, "click", ACTIONS.inc.selector, () => {
204
+ count.value += 1;
205
+ });
164
206
 
165
207
  // Keyed list with per-item memoization
166
208
  mount(listEl, () => (
167
209
  <ul>
168
- {each(rows.value, (row) => <li data-key={row.id}>{row.label}</li>)}
210
+ {each(rows.value, (row) => (
211
+ <li data-key={row.id}>{row.label}</li>
212
+ ))}
169
213
  </ul>
170
214
  ));
171
215
 
@@ -173,22 +217,28 @@ mount(listEl, () => (
173
217
  const cart = defineStore({
174
218
  initial: () => ({ items: [] as string[] }),
175
219
  actions: (set, get) => ({
176
- add: (id: string) => set({ items: [...get().items, id] }),
177
- clear: () => set({ items: [] }),
220
+ add: (id: string) => set({ items: [...get().items, id] }),
221
+ clear: () => set({ items: [] }),
178
222
  }),
179
223
  });
180
224
 
181
225
  // One-shot reconcile against existing DOM (no signals)
182
- morph(liveCard, '<article class="card">…</article>');
226
+ // the template describes liveCard's CHILDREN; liveCard's own attributes are untouched
227
+ morph(liveCard, '<h2 class="card-title">…</h2><p>…</p>');
183
228
 
184
229
  // No build step (CDN / importmap): the html tagged template instead of JSX.
185
230
  // Same runtime semantics as JSX; write real HTML attribute names; a hole must
186
231
  // be a text position or a COMPLETE attribute value (partial values throw).
187
- import { html } from 'kerfjs/html';
188
- mount(rootEl, () => html`
189
- <div class="${cls}">Count: ${count}</div>
190
- <ul>${each(rows.value, (row) => html`<li data-key="${row.id}">${row.label}</li>`)}</ul>
191
- `);
232
+ import { html } from "kerfjs/html";
233
+ mount(
234
+ rootEl,
235
+ () => html`
236
+ <div class="${cls}">Count: ${count}</div>
237
+ <ul>
238
+ ${each(rows.value, (row) => html`<li data-key="${row.id}">${row.label}</li>`)}
239
+ </ul>
240
+ `,
241
+ );
192
242
 
193
243
  // Fine-grained binding (opt-in): pass the signal/computed ITSELF into a hole
194
244
  // so a change updates ONLY that node (no render re-run, no reconcile). For a
@@ -197,11 +247,20 @@ mount(rootEl, () => html`
197
247
  const selectedId = signal<number | null>(null);
198
248
  mount(listEl, () => (
199
249
  <ul>
200
- {each(rows.value, (row) => (
201
- <li class={computed(() => (row.id === selectedId.value ? 'sel' : ''))}>{row.label}</li>
202
- ), (row) => row.id)}
250
+ {each(
251
+ rows.value,
252
+ (row) => (
253
+ <li class={computed(() => (row.id === selectedId.value ? "sel" : ""))}>
254
+ {row.label}
255
+ </li>
256
+ ),
257
+ (row) => row.id,
258
+ )}
203
259
  </ul>
204
260
  ));
261
+ // Large list: `const isSelected = selector(selectedId)` (from "kerfjs") and
262
+ // `computed(() => (isSelected(row.id).value ? "sel" : ""))` — one subscription
263
+ // to selectedId instead of one per row, so a selection flip is O(1).
205
264
  ```
206
265
 
207
266
  ## Common errors → fixes
@@ -215,13 +274,13 @@ mount(listEl, () => (
215
274
  - SVG renders as broken / namespaceless markup → use `mount` (HTML path) or `toElement` (SVG-aware), not `innerHTML`.
216
275
  - Library widget destroyed on every render → wrap host in `data-morph-skip`; mount the library imperatively after first render.
217
276
  - `each(): row render at index N produced K top-level elements` → wrap multiple roots in one parent.
218
- - 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.
219
- - 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`).
277
+ - 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.
278
+ - 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`).
220
279
  - 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.
221
- - `` 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}`)}"`.
280
+ - ` 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}`)}"`.
222
281
  - An `each()` list's rows lose focus / scroll / typing state when an unrelated conditional list above them appears or disappears (kerf warns in dev) → lists without a key are identified by position among the render's `each()` calls, so adding/removing one above shifts this list's identity and kerf rebuilds it. Give the lists stable keys: `each(items, render, { key: 'results' })`; keying just the conditional list is usually enough.
223
282
  - 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>`).
224
- - A numbered / zebra-striped / "N of M" `each()` list shows the wrong number on rows that MOVED (reorder, or non-tail insert/remove), while unmoved rows look right → the render fn's `index` argument is NOT part of the memo key (only item identity + `cacheKey` + content version are), so a row that keeps identity but changes position keeps HTML rendered at its old index. Fold the index into the memo key: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `KERF_DEV_WARN_STALE_INDEX=1`.
283
+ - A numbered / zebra-striped / "N of M" `each()` list shows the wrong number on rows that MOVED (reorder, or non-tail insert/remove), while unmoved rows look right → the render fn's `index` argument is NOT part of the memo key (only item identity + `cacheKey` + content version are), so a row that keeps identity but changes position keeps HTML rendered at its old index. Fold the index into the memo key: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `enableWarnings({ staleIndex: true })` (or `KERF_DEV_WARN_STALE_INDEX=1` under Node).
225
284
 
226
285
  ## Server / SSR
227
286
 
package/ai/manifest.json CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
- "kerfjsVersion": "5.0.0-beta.13",
2
+ "kerfjsVersion": "5.0.0-beta.130",
3
3
  "files": [
4
4
  {
5
5
  "name": "skill",
6
6
  "source": "kerf.claude-skill.md",
7
7
  "bundle": "ai/skill.md",
8
8
  "dest": ".claude/skills/kerf-app/SKILL.md",
9
- "version": "1.22.0",
10
- "sha256": "5eb6631671faefeb273c93dee492eecf35dfc567fecba799374ac8af6c9a0dc3",
9
+ "version": "1.31.0",
10
+ "sha256": "9880f36aa1994da1b02c35fed72079d2484c0f384f68e22ae47d0634b233a1cb",
11
11
  "history": {
12
12
  "1.0.0": "bef982cb743fd4c73e666ee5cf774112e57c93ebb13b24bbacbf08577db0930a",
13
13
  "1.1.0": "f2aadb21e33dd389028951ae1ecbd9f8ba68648b3c5beba43fb4dfa2ab29f195",
@@ -36,7 +36,28 @@
36
36
  "1.19.0": "bbbe87446cc4e1be250d27152adfd385431f4498cde320534f65f10f853ab7f9",
37
37
  "1.20.0": "aa88ccdbf969624bbc6cefadba76ada1f090fae436597a7bab564e24c467287f",
38
38
  "1.21.0": "265b747eeb9c3d445c60d66a1109eec42705075b7cd154d107bd79d543c1e7e5",
39
- "1.22.0": "5eb6631671faefeb273c93dee492eecf35dfc567fecba799374ac8af6c9a0dc3"
39
+ "1.22.0": "dc99b0ca5e911be11cbfa2ae515c0e161a414a5185895069535c41ba56664e70",
40
+ "1.23.0": "28b82b4d31b98814c8fbbe1cb0bcf716192deb494c020b9af41a30830e6a0007",
41
+ "1.23.1": "e21d7db1097ad95c11af9248ad17d514716bebc5646becf57d19a7598d6e382c",
42
+ "1.24.0": "f74616ec20120fa97ec2ff7e92971f5721ee8dcb0b5b7da2dd2604bb87002b69",
43
+ "1.25.0": "bc2622cb12b382118e44aa50d1afb058252e0caf85b7c0ced4433bc0ca76f7c1",
44
+ "1.26.0": "64a86a36399d12e5803a050c116d32d8762608d91ec9222670592ff471bc64b8",
45
+ "1.27.0": "7cc6a566cbe08023079731b98166e3c5e49160a8844358f928acf3ee0654092c",
46
+ "1.28.0": "95a803e82a234dda363f468511bf64247c89798c1af8a1c62d082b40627f41aa",
47
+ "1.29.0": "1816494efdc7e3b15d9c5213988477f68f82c5c2a2e4a685956500845ae5cc90",
48
+ "1.30.0": "2e78139920bbb6e6fd1e396cd6ed3edf772cfdbd2f0eb84d0c3077f9cd2035c6",
49
+ "1.31.0": "9880f36aa1994da1b02c35fed72079d2484c0f384f68e22ae47d0634b233a1cb"
50
+ }
51
+ },
52
+ {
53
+ "name": "ui-skill",
54
+ "source": "kerf.ui-skill.md",
55
+ "bundle": "ai/ui-skill.md",
56
+ "dest": ".claude/skills/kerf-ui/SKILL.md",
57
+ "version": "1.0.0",
58
+ "sha256": "ee6e0e1d4028c37c3cc868ec12459e23cfa42c9dcaac791011c656984ae19310",
59
+ "history": {
60
+ "1.0.0": "ee6e0e1d4028c37c3cc868ec12459e23cfa42c9dcaac791011c656984ae19310"
40
61
  }
41
62
  },
42
63
  {
@@ -44,8 +65,8 @@
44
65
  "source": "kerf.cursorrules",
45
66
  "bundle": "ai/cursorrules",
46
67
  "dest": ".cursorrules",
47
- "version": "1.20.0",
48
- "sha256": "c4dac40630fc456c6c7e6ba9d1b75215bc76bd76e6f31ba36d3bc9ab867d46e0",
68
+ "version": "1.27.0",
69
+ "sha256": "e8d8a56ed88ee427c2edc9ddfb4358780e19ea70c0feeae4e052d8b7c4520aae",
49
70
  "history": {
50
71
  "1.0.0": "98f7faff2b7585ef9cc511add42ea5d9bf0cbae8307b066af090e9281136d2ab",
51
72
  "1.1.0": "a2ec8c221dc694c98b81009cd2d99f9159a45fda94585de2f54471b227099eda",
@@ -72,7 +93,15 @@
72
93
  "1.17.0": "6ad51fb0eec468f584346d1d7b4d1c2eca2cb52b04891b38ba44e93b57eb9e1c",
73
94
  "1.18.0": "de3eea1bc181da629694d19a0817d252a868e4704437fbdd9e923856b8a0890a",
74
95
  "1.19.0": "c5b91e449f6feccaa36a04cb7f8550d3e414eb2795ea6c5dccdf6071206b3261",
75
- "1.20.0": "c4dac40630fc456c6c7e6ba9d1b75215bc76bd76e6f31ba36d3bc9ab867d46e0"
96
+ "1.20.0": "5e7b8d8ddc41f60220961417c9ae01c193fae045378a10a3e9c96a0e3cf10a03",
97
+ "1.21.0": "a1b663b44650b1a04f89c60b26b002322fc6789650291477e14e13329c3ce25f",
98
+ "1.21.1": "9b3eb825a7bec05bb6f0138f77b45fadf896b83020178c34c5a2f531c38f4dee",
99
+ "1.22.0": "3515c663e908b2d6dc9a2a9cf42f2a5bf9a5b3a10c79d43e30cc8427e2ce209d",
100
+ "1.23.0": "dad6f677c85bf01760da6694afb7ead1439f0e1f0298ba8dac65de44ba031848",
101
+ "1.24.0": "9578b5141b417b10560a426086c0f8dad3bd6a302f2856bea4808be7d02ef0d3",
102
+ "1.25.0": "c52120502cc76fa5c6588a551b1d7f8097e2f6cd8a496d30a8bad0e103ea37db",
103
+ "1.26.0": "a583bad7217181229f7bc7047a472f87867738d9514f926dc9805b7e2443d8c2",
104
+ "1.27.0": "e8d8a56ed88ee427c2edc9ddfb4358780e19ea70c0feeae4e052d8b7c4520aae"
76
105
  }
77
106
  }
78
107
  ]