kerfjs 5.0.0-beta.13 → 5.0.0-beta.131

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 +3384 -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 +1040 -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 +91 -0
  76. package/setup/detect.mjs +274 -0
  77. package/setup/index.d.mts +39 -0
  78. package/setup/index.mjs +1290 -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/README.md CHANGED
@@ -12,14 +12,14 @@
12
12
 
13
13
  <p align="center">
14
14
  <a href="https://www.npmjs.com/package/kerfjs"><img src="https://img.shields.io/npm/v/kerfjs.svg" alt="npm version" /></a>
15
- <img src="https://img.shields.io/badge/min%2Bgzip-~12%20KB-brightgreen.svg" alt="~12 KB minified and gzipped" />
15
+ <img src="https://img.shields.io/badge/min%2Bgzip-~15%20KB-brightgreen.svg" alt="~15 KB minified and gzipped" />
16
16
  <img src="https://img.shields.io/npm/l/kerfjs.svg" alt="MIT license" />
17
17
  <img src="https://img.shields.io/badge/types-included-3178c6.svg" alt="TypeScript types included" />
18
18
  </p>
19
19
 
20
20
  ---
21
21
 
22
- > ~12 KB. No virtual DOM. No compiler. No magic.
22
+ > ~15 KB. No virtual DOM. No compiler. No magic.
23
23
  > Reactive UI that touches only the bytes that changed.
24
24
 
25
25
  ```ts
@@ -31,14 +31,17 @@ const app = document.getElementById('app')!;
31
31
  mount(app, () => (
32
32
  <div>
33
33
  <button data-action="inc">+</button>
34
- <span>{count.value}</span>
34
+ <span>{count}</span>
35
35
  </div>
36
36
  ));
37
37
 
38
38
  delegate(app, 'click', '[data-action="inc"]', () => count.value++);
39
39
  ```
40
40
 
41
- That's it. Your JSX renders to HTML strings, kerf's native diff applies the minimum DOM mutations to make the live tree match, and signals re-run the render only when something they read actually changed.
41
+ That's it. Your JSX renders to HTML strings, and handing the signal itself to
42
+ the text hole binds that one node directly. Structural reads still re-run the
43
+ render, where kerf's native diff applies the minimum DOM mutations needed to
44
+ make the live tree match.
42
45
 
43
46
  Here's the whole development loop — write a component, run the dev server, click around, edit, watch the browser pick it up:
44
47
 
@@ -51,25 +54,47 @@ Here's the whole development loop — write a component, run the dev server, cli
51
54
  npm install kerfjs
52
55
  ```
53
56
 
57
+ Kerf runs in modern browsers (ES2022). The published package, including the
58
+ `kerfjs setup` CLI and server-side `toString()` rendering, needs Node.js 18 or
59
+ newer (`engines.node`); contributing to this repository (building, testing,
60
+ the documentation site) needs Node.js 22.12+.
61
+
62
+ For an existing project, install the AI guidance, strict TypeScript/ESLint
63
+ feedback, and package scripts with a reviewed dry run:
64
+
65
+ ```bash
66
+ npx kerfjs setup # inspect a value-level plan
67
+ npx kerfjs setup --write --yes # apply it
68
+ ```
69
+
70
+ The command detects core versus `@kerfjs/ui`, supports deterministic npm,
71
+ pnpm, and Yarn workspace selection plus manager-correct offline installs, and
72
+ never adds UI to a core-only project. See
73
+ [`docs/24-ai-first-setup.md`](./docs/24-ai-first-setup.md).
74
+
54
75
  ```jsonc
55
76
  // tsconfig.json — point JSX at kerf
56
77
  { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "kerfjs" } }
57
78
  ```
58
79
 
59
80
  Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no extra plugin. New here? Read the [5-minute orientation](https://github.com/brianwestphal/kerf/blob/main/docs/orientation.md), or open a [complete example](https://brianwestphal.github.io/kerf/examples/complete/).
81
+
60
82
  ## Why Kerf
61
83
 
62
- 1. **~12 KB, one dependency.** ~12 KB minified + gzipped including `@preact/signals-core` (~13 KB with `arraySignal`). No virtual DOM, no scheduler, no concurrent-mode machinery. On the official [krausest benchmark](https://krausest.github.io/js-framework-benchmark/current.html) kerf sits in the same cluster as Vue, Lit, and vanjs; Solid's compiler leads the update-path benchmarks, which kerf doesn't try to match by design — no compiler.
84
+ 1. **~15 KB in the browser.** ~15 KB minified + gzipped including `@preact/signals-core` (~16 KB with `arraySignal`). The optional setup CLI has its own npm dependencies; they stay out of the browser bundle. No virtual DOM, no scheduler, no concurrent-mode machinery. On the official [krausest benchmark](https://krausest.github.io/js-framework-benchmark/current.html) kerf sits in the same cluster as Vue, Lit, and vanjs; Solid's compiler leads the update-path benchmarks, which kerf doesn't try to match by design — no compiler.
63
85
 
64
- 2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it *is* the DOM.
86
+ 2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it _is_ the DOM.
65
87
 
66
- 3. **Values bind, structure re-renders.** Hand a signal *itself* into a JSX hole — `class={selectedId}` — and kerf binds that one node: on change, only that attribute updates, with no render re-run and no list reconcile. Moving selection between rows in a 10,000-row table touches at most the old and new row classes. ([more →](#fine-grained-updates-bind-a-signal-into-a-hole))
88
+ 3. **Values bind, structure re-renders.** Hand a signal _itself_ into a JSX hole — `class={selectedId}` — and kerf binds that one node: on change, only that attribute updates, with no render re-run and no list reconcile. Moving selection between rows in a 10,000-row table touches at most the old and new row classes. ([more →](#fine-grained-updates-bind-a-signal-into-a-hole))
67
89
 
68
90
  4. **Focus, selection, and listeners survive re-renders — even mid-list.** The reconciler morphs instead of rebuilding, so caret position, IME composition, scroll, and delegated listeners survive every update; keyed rows are patched in place rather than recreated.
69
91
 
70
- 5. **Safe by default.** Text and attributes are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` dropped), and inline `on*` handlers are rejected outright — so untrusted data stays inert. `raw()` is the explicit, auditable opt-out.
92
+ 5. **A first-party UI layer when you want one.** `@kerfjs/ui` adds accessible components, responsive application layouts, typed CSS values, and explicit wiring helpers without changing kerf's stateless component model. It is separately installable and tree-shakeable, so the core stays the core. ([tour →](#first-party-ui-separately-installable))
93
+
94
+ 6. **Safe by default.** Text and attributes are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` dropped), and inline `on*` handlers are rejected outright — so untrusted data stays inert. `raw()` is the explicit, auditable opt-out.
95
+
96
+ **Plus, nothing you don't ask for:** JSX typed against the HTML standard (not React's props) · a small public API with no hooks, lifecycle, or per-instance state · tree-shakeable companion subpaths (`router`, `list`, `overlay`, `async`, …) that stay out of the core until imported · an [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) + opt-in dev warnings + `create-kerf-component` scaffold · plain TS/JSX/ESM that drops into esbuild / Vite / tsup — or **no** build at all via the `html` tagged template.
71
97
 
72
- **Plus, nothing you don't ask for:** JSX typed against the HTML standard (not React's props) · a ~18-export API with no hooks, lifecycle, or per-instance state · **nine** tree-shakeable companion subpaths (`router`, `list`, `overlay`, `async`, …) that stay out of the core until imported · an [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) + opt-in dev warnings + `create-kerf-component` scaffold · plain TS/JSX/ESM that drops into esbuild / Vite / tsup — or **no** build at all via the `html` tagged template.
73
98
  ## When to use Kerf
74
99
 
75
100
  - **Hybrid desktop apps (Tauri / Electron)** — small bundle, predictable diff, debuggable runtime; ideal for the embedded webview.
@@ -82,9 +107,9 @@ Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no ext
82
107
  ### When to reach for something else
83
108
 
84
109
  - Need a full ecosystem (router + forms + data + SSR streaming) → **Next.js / Remix / SolidStart**.
85
- - Building a deeply componentised design-system app → **React / Solid / Svelte**.
110
+ - Building a deeply componentized design-system app → **React / Solid / Svelte**.
86
111
  - Need React Native / cross-platform mobile → **React** (Kerf + Tauri/Electron also covers many of these cases).
87
- - Building a static site → **Astro** (we use it for *this* project's site).
112
+ - Building a static site → **Astro** (we use it for _this_ project's site).
88
113
  - Already invested in a framework where switching cost outweighs the bundle size gain.
89
114
 
90
115
  ## Quick tour
@@ -144,7 +169,7 @@ delegate(root, 'click', REMOVE.selector, (_e, btn) => { /* … */ }); // in dele
144
169
 
145
170
  ### Fine-grained updates: bind a signal into a hole
146
171
 
147
- Inside a `mount()`, hand a signal *itself* (not its `.value`) into an attribute or text position and kerf wires that hole straight to the signal — the render function never re-runs and the list reconciler never walks:
172
+ Inside a `mount()`, hand a signal _itself_ (not its `.value`) into an attribute or text position and kerf wires that hole straight to the signal — the render function never re-runs and the list reconciler never walks:
148
173
 
149
174
  ```ts
150
175
  const status = signal('idle');
@@ -160,7 +185,7 @@ status.value = 'saving'; // updates the class + the text node directly — n
160
185
 
161
186
  The headline use is external state driving a hot spot: a `selectedId` moving between rows inside a 10,000-row `each()` list updates at most the old and new row class attributes, with no reconcile. Works in static content and inside `each()` rows (a row's binding is torn down with the row); outside a `mount()` (SSR / `SafeHtml.toString()`) a bound signal just snapshots its current value.
162
187
 
163
- This is kerf's guiding idiom — *values bind, structure re-renders*: pass the signal itself wherever a hole is just a value, and read `.value` in the render function only where the JSX structure depends on it. A render that reads no `.value` runs exactly once; from then on every update is a direct write to the node it concerns. See [`docs/2-reactivity.md`](./docs/2-reactivity.md) §2.9.
188
+ This is kerf's guiding idiom — _values bind, structure re-renders_: pass the signal itself wherever a hole is just a value, and read `.value` in the render function only where the JSX structure depends on it. A render that reads no `.value` runs exactly once; from then on every update is a direct write to the node it concerns. See [`docs/2-reactivity.md`](./docs/2-reactivity.md) §2.9.
164
189
 
165
190
  ### Long keyed lists: `arraySignal`
166
191
 
@@ -187,14 +212,15 @@ The class lives in its own subpath so apps that don't need it shed ~1 KB. Reads
187
212
  `mount()` wraps `effect()` so the render re-runs on signal changes. Sometimes you have a freshly-built template and an already-populated element and you just want to reconcile them once — no subscription, no re-render loop. That's `morph`:
188
213
 
189
214
  ```ts
190
- import { morph, raw } from 'kerfjs';
215
+ import { morph, raw } from "kerfjs";
191
216
 
192
- morph(liveCard, freshlyBuiltCardEl); // Element template
193
- morph(liveCard, '<article class="card">…</article>'); // raw HTML string
194
- morph(liveCard, raw(htmlFromServer)); // SafeHtml
217
+ // `template` describes liveCard's CHILDREN; liveCard's own attributes are untouched
218
+ morph(liveCard, freshlyBuiltCardEl); // Element template: its child nodes are used
219
+ morph(liveCard, '<h2 class="card-title">…</h2><p>…</p>'); // raw HTML string
220
+ morph(liveCard, raw(htmlFromServer)); // SafeHtml
195
221
  ```
196
222
 
197
- Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip-children`, `data-morph-preserve`, focused-input value + selection preservation, the `<details>` / `<dialog>` user-agent-owned `open` rule all carry over. Use it for SSR-fragment hydration, page-refresh diffs, third-party widget remounts. See [`docs/4-render.md`](./docs/4-render.md) §4.4.3.
223
+ Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip-children`, `data-morph-preserve`, focused-input value + selection preservation, the user-agent-owned `open` rule (`<details>`, `<dialog>`, custom elements) all carry over. Only the live root's children are reconciled — the root's own attributes are never touched. Use it for SSR-fragment hydration, page-refresh diffs, third-party widget remounts. See [`docs/4-render.md`](./docs/4-render.md) §4.4.3.
198
224
 
199
225
  ### No build step at all: the `html` tagged template
200
226
 
@@ -202,22 +228,27 @@ Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip
202
228
 
203
229
  ```html
204
230
  <script type="module">
205
- import { signal, mount, each } from 'https://esm.sh/kerfjs@4';
206
- import { html } from 'https://esm.sh/kerfjs@4/html';
207
-
208
- const items = signal([{ id: 1, label: 'no build step' }]);
209
-
210
- mount(document.getElementById('app'), () => html`
211
- <ul>${each(items.value, (i) => html`<li id="${i.id}">${i.label}</li>`)}</ul>
212
- `);
231
+ import { signal, mount, each } from "https://esm.sh/kerfjs@5";
232
+ import { html } from "https://esm.sh/kerfjs@5/html";
233
+
234
+ const items = signal([{ id: 1, label: "no build step" }]);
235
+
236
+ mount(
237
+ document.getElementById("app"),
238
+ () => html`
239
+ <ul>
240
+ ${each(items.value, (i) => html`<li id="${i.id}">${i.label}</li>`)}
241
+ </ul>
242
+ `,
243
+ );
213
244
  </script>
214
245
  ```
215
246
 
216
- Nothing is self-hosted — `kerfjs` is on npm, so every ESM CDN (esm.sh, jsDelivr, unpkg) mirrors it automatically. esm.sh works with a direct import as shown; jsDelivr / unpkg want an importmap so the internal `@preact/signals-core` import resolves. Pin to a major (`@4`, as shown — the latest `4.x`) rather than floating on `latest`, or an exact version (`@4.1.0`) for full reproducibility. Attribute names are written verbatim (`class`, not `className`), and holes are only legal in text positions or as a complete attribute value — anything ambiguous throws with an actionable message. See [`docs/6-jsx-runtime.md`](./docs/6-jsx-runtime.md) §6.11 (§6.11.1 for the full CDN / importmap recipes) — or the [live-poll example](https://brianwestphal.github.io/kerf/examples/complete/live-poll/), a complete app served exactly as authored: no bundler ever touches it.
247
+ Nothing is self-hosted — `kerfjs` is on npm, so every ESM CDN (esm.sh, jsDelivr, unpkg) mirrors it automatically. esm.sh works with a direct import as shown; jsDelivr / unpkg want an importmap so the internal `@preact/signals-core` import resolves. Pin to a major (`@5`, as shown) rather than floating on `latest`, or an exact version (`@5.0.0`) for full reproducibility. Attribute names are written verbatim (`class`, not `className`), and holes are only legal in text positions or as a complete attribute value — anything ambiguous throws with an actionable message. See [`docs/6-jsx-runtime.md`](./docs/6-jsx-runtime.md) §6.11 (§6.11.1 for the full CDN / importmap recipes) — or the [live-poll example](https://brianwestphal.github.io/kerf/examples/complete/live-poll/), a complete app served exactly as authored: no bundler ever touches it.
217
248
 
218
249
  ### Batteries when you need them: the companion subpaths
219
250
 
220
- The core stays tiny because the patterns every real app rebuilds live in optional, tree-shakeable subpaths — a modal you'd otherwise hand-roll (`kerfjs/overlay`), an async-state container with the stale-response race already solved (`kerfjs/async`), a debounce that composes inside the reactive graph (`kerfjs/timing`), teardown tied to a DOM node's lifetime (`kerfjs/scope`). The largest is `kerfjs/list` — a keyed list that mounts each row individually (so a signal one row reads updates just that row) and virtualizes a long viewport, with fixed, app-declared, or measured row heights:
251
+ The core stays tiny because the patterns every real app rebuilds live in optional, tree-shakeable subpaths — a modal you'd otherwise hand-roll (`kerfjs/overlay`), an async-state container with the stale-response race already solved (`kerfjs/async`), a debounce that composes inside the reactive graph (`kerfjs/timing`), and disposer groups with or without a DOM owner (`kerfjs/scope`). The largest is `kerfjs/list` — a keyed list that mounts each row individually (so a signal one row reads updates just that row) and virtualizes a long viewport, with fixed, app-declared, or measured row heights:
221
252
 
222
253
  ```ts
223
254
  import { bindList, observeRowHeights } from 'kerfjs/list';
@@ -238,7 +269,7 @@ const list = bindList(scrollEl, messages, {
238
269
  observeRowHeights(list); // one ResizeObserver → kerf anchor-corrects scroll
239
270
  ```
240
271
 
241
- And a whole client-side router in one call — `kerfjs/router`, the "postcard router." A route table, a keyed `outlet()`, and automatic `<a href>` interception; the *core* stays router-free (this is opt-in):
272
+ And a whole client-side router in one call — `kerfjs/router`, the "postcard router." A route table, a keyed `outlet()`, and automatic `<a href>` interception; the _core_ stays router-free (this is opt-in):
242
273
 
243
274
  ```ts
244
275
  import { createRouter } from 'kerfjs/router';
@@ -258,13 +289,45 @@ mount(app, () => <div><nav>{/* <a href> links, auto-intercepted */}</nav>{router
258
289
 
259
290
  Each subpath adds nothing to the main barrel until it's imported. See [`docs/8-api-reference.md`](./docs/8-api-reference.md) for the full list (`list`, `router`, `overlay`, `scope`, `async`, `timing`, `remount`, `attach`, `actions`).
260
291
 
292
+ ### First-party UI, separately installable
293
+
294
+ `@kerfjs/ui` is the optional component layer for applications that want a
295
+ coherent interface vocabulary without switching frameworks. Components return
296
+ Kerf `SafeHtml`; the application still owns state and wires behavior explicitly.
297
+ Component subpaths pull in only their reachable CSS, while responsive app
298
+ layouts, typed CSS-value builders, Web Awesome adapters, and the checked
299
+ component catalog stay opt-in.
300
+
301
+ ```bash
302
+ npm install kerfjs @kerfjs/ui
303
+ ```
304
+
305
+ ```tsx
306
+ import { mount } from "kerfjs";
307
+ import { ListItem } from "@kerfjs/ui/list-item";
308
+ import { Toolbar } from "@kerfjs/ui/toolbar";
309
+ import { ToolbarText } from "@kerfjs/ui/toolbar-text";
310
+
311
+ const root = document.getElementById("app")!;
312
+
313
+ mount(root, () => (
314
+ <>
315
+ <Toolbar label="Files" leading={<ToolbarText text="Workspace" />} />
316
+ <ListItem action="open-file" label="src/main.ts" selected />
317
+ </>
318
+ ));
319
+ ```
320
+
321
+ Start with the [component selection matrix](./ui/docs/component-selection.md),
322
+ or read the complete [`@kerfjs/ui` package guide](./ui/README.md).
323
+
261
324
  ## Optional tooling
262
325
 
263
326
  Install and JSX setup are in [Quick start](#quick-start) above. These companion packages are opt-in.
264
327
 
265
328
  ### Optional: `eslint-plugin-kerfjs`
266
329
 
267
- A companion ESLint plugin enforces kerf's hard rules at edit time. Eight rules total: four `error`-level AST rules catch hard-rule violations — inline JSX event handlers, missing `data-key` in `each()`, nested `mount()`, and global `JSX.IntrinsicElements` augmentation — and four `warn`-level rules cover delegate-disposer capture, `attr()` selector rename-safety, `raw()` XSS audit trails, and AI-assistant config hygiene. The plugin is AST-only (no parser-services dependency), so it works with any TypeScript-ESLint setup.
330
+ A companion ESLint plugin enforces kerf's hard rules at edit time. Its eight core rules cover inline JSX event handlers, missing `data-key` in `each()`, nested `mount()`, delegate-disposer capture, `attr()` selector rename-safety, `raw()` XSS audit trails, JSX augmentation, and AI-assistant config hygiene. Six additional UI rules check component ownership, composition, CSS values, application preferences, wiring, and public boundaries when you opt into the UI preset. The plugin requires no TypeScript parser service.
268
331
 
269
332
  ```bash
270
333
  npm install --save-dev eslint-plugin-kerfjs
@@ -272,15 +335,15 @@ npm install --save-dev eslint-plugin-kerfjs
272
335
 
273
336
  ```js
274
337
  // eslint.config.js (flat config, ESLint v9+)
275
- import kerfjs from 'eslint-plugin-kerfjs';
338
+ import kerfjs from "eslint-plugin-kerfjs";
276
339
  export default [kerfjs.configs.recommended];
277
340
  ```
278
341
 
279
- Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — legacy `.eslintrc` config, per-rule examples, and the rationale for which violations get lint rules vs. dev-warns vs. strict TS.
342
+ Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — flat config, per-rule examples, and the rationale for which violations get lint rules vs. dev-warns vs. strict TS.
280
343
 
281
344
  ### Optional: `create-kerf-component`
282
345
 
283
- Building a reusable component package? Scaffold one that already follows kerf's hard packaging rules (kerfjs as a peer dependency and `external` in the build, ESM + `.d.ts`, `jsxImportSource: "kerfjs"`, subpath exports) plus an example component showing per-instance state via a factory and a `wire(root)` delegation disposer:
346
+ Building a reusable component package? Scaffold one that already follows kerf's hard packaging rules (kerfjs as a peer dependency and `external` in the build, ESM + `.d.ts`, `jsxImportSource: "kerfjs"`, subpath exports), includes an example component showing per-instance state via a factory and a `wire(root)` delegation disposer, and generates checked package-qualified AI component metadata from explicit author decisions:
284
347
 
285
348
  ```bash
286
349
  npm create kerf-component@latest my-widgets
@@ -294,16 +357,17 @@ See [`docs/13-component-packages.md`](./docs/13-component-packages.md) for the f
294
357
  - **Docs:** [`docs/`](./docs/) — overview · reactivity · stores · render · events · jsx · svg · [API reference](./docs/8-api-reference.md)
295
358
  - **Migrating:** [coming from another framework?](https://brianwestphal.github.io/kerf/migrating/) — side-by-side TodoMVC translations + per-framework gotchas
296
359
  - **AI guide:** [`docs/ai/usage-guide.md`](./docs/ai/usage-guide.md) — reference for AI tools fetching kerf docs (linked from `llms.txt`)
297
- - **ESLint plugin:** [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — `eslint-plugin-kerfjs`; eight rules (four hard-rule errors + four warns: `require-delegate-disposer`, `prefer-attr-selector`, `no-raw-with-dynamic-arg`, `ai-assistant-configs`) at edit time (source: [`eslint-plugin/`](./eslint-plugin/))
298
- - **Component scaffold:** `npm create kerf-component@latest <dir>` — `create-kerf-component`; generates a publishable component package with the hard packaging rules pre-wired (source: [`create-kerf-component/`](./create-kerf-component/))
360
+ - **UI package:** [`@kerfjs/ui`](./ui/README.md) — accessible components, responsive app layouts, typed CSS values, Web Awesome adapters, and checked AI-facing component metadata
361
+ - **ESLint plugin:** [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — `eslint-plugin-kerfjs`; eight core rules plus six opt-in UI rules at edit time (source: [`eslint-plugin/`](./eslint-plugin/))
362
+ - **Component scaffold:** `npm create kerf-component@latest <dir>` — `create-kerf-component`; generates a publishable component package with packaging rules plus deterministic, drift-checked AI metadata pre-wired (source: [`create-kerf-component/`](./create-kerf-component/))
299
363
  - **Demo:** [live demo](https://brianwestphal.github.io/kerf/demo/) — nine sections exercising every primitive (counter, store-backed cart, focus survival, keyed list, morph-skip, SVG render, Tier-2 capture, `arraySignal` patches, fine-grained signal bindings)
300
364
  - **Repo:** [github.com/brianwestphal/kerf](https://github.com/brianwestphal/kerf)
301
365
 
302
366
  ## Why "kerf"?
303
367
 
304
- A *kerf* is the narrow strip of material a saw blade removes when cutting — the smallest possible cut. The framework's job is the same: apply the smallest possible mutation to update your DOM.
368
+ A _kerf_ is the narrow strip of material a saw blade removes when cutting — the smallest possible cut. The framework's job is the same: apply the smallest possible mutation to update your DOM.
305
369
 
306
- (And yes, ~~kerformance~~ → *performance* jokes were written. They were also rejected.)
370
+ (And yes, ~~kerformance~~ → _performance_ jokes were written. They were also rejected.)
307
371
 
308
372
  ## Status
309
373