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.
- package/CHANGELOG.md +3384 -108
- package/README.md +101 -37
- package/ai/cursorrules +127 -68
- package/ai/manifest.json +36 -7
- package/ai/skill.md +167 -86
- package/ai/ui-skill.md +18 -0
- package/dist/actions.d.ts +1 -1
- package/dist/actions.js +10 -6
- package/dist/actions.js.map +1 -1
- package/dist/array-signal.js +1 -1
- package/dist/async.d.ts +7 -3
- package/dist/async.js +39 -22
- package/dist/async.js.map +1 -1
- package/dist/attach.js +1 -66
- package/dist/attach.js.map +1 -1
- package/dist/{chunk-GY4XV2UV.js → chunk-4TX6YJDM.js} +10 -3
- package/dist/chunk-4TX6YJDM.js.map +1 -0
- package/dist/{chunk-SVATPF5R.js → chunk-5QDM6HPD.js} +637 -277
- package/dist/chunk-5QDM6HPD.js.map +1 -0
- package/dist/{chunk-QIP723L4.js → chunk-5WRGJZV6.js} +3 -2
- package/dist/chunk-5WRGJZV6.js.map +1 -0
- package/dist/chunk-AP2FT33F.js +87 -0
- package/dist/chunk-AP2FT33F.js.map +1 -0
- package/dist/chunk-BTOKH5FA.js +70 -0
- package/dist/chunk-BTOKH5FA.js.map +1 -0
- package/dist/{chunk-ZDCJZCNO.js → chunk-GGADRIQO.js} +168 -97
- package/dist/chunk-GGADRIQO.js.map +1 -0
- package/dist/chunk-KOEGJCIS.js +65 -0
- package/dist/chunk-KOEGJCIS.js.map +1 -0
- package/dist/{chunk-HW7KSM2Y.js → chunk-KUHXPPJ4.js} +1 -1
- package/dist/chunk-KUHXPPJ4.js.map +1 -0
- package/dist/{chunk-UZJ6I4T6.js → chunk-MK42GLPV.js} +1 -1
- package/dist/chunk-MK42GLPV.js.map +1 -0
- package/dist/chunk-N4VHHOCM.js +27 -0
- package/dist/chunk-N4VHHOCM.js.map +1 -0
- package/dist/{chunk-V46JKE44.js → chunk-NRPLVJVR.js} +43 -14
- package/dist/chunk-NRPLVJVR.js.map +1 -0
- package/dist/{chunk-LVH3GC6B.js → chunk-QOAB2ESQ.js} +3 -3
- package/dist/chunk-QOAB2ESQ.js.map +1 -0
- package/dist/{chunk-KZJXHFIB.js → chunk-V322Z7FX.js} +5 -5
- package/dist/chunk-V322Z7FX.js.map +1 -0
- package/dist/{delegate-CL9VTZFb.d.ts → delegate--CrfgYtC.d.ts} +0 -34
- package/dist/dev.d.ts +46 -15
- package/dist/dev.js +185 -40
- package/dist/dev.js.map +1 -1
- package/dist/html.js +20 -8
- package/dist/html.js.map +1 -1
- package/dist/index.d.ts +98 -13
- package/dist/index.js +49 -21
- package/dist/index.js.map +1 -1
- package/dist/jsx-runtime.d.ts +25 -10
- package/dist/jsx-runtime.js +1 -1
- package/dist/list.d.ts +7 -3
- package/dist/list.js +236 -78
- package/dist/list.js.map +1 -1
- package/dist/overlay.d.ts +287 -142
- package/dist/overlay.js +1040 -369
- package/dist/overlay.js.map +1 -1
- package/dist/remount.js +2 -2
- package/dist/remount.js.map +1 -1
- package/dist/router.d.ts +22 -6
- package/dist/router.js +58 -19
- package/dist/router.js.map +1 -1
- package/dist/scope.d.ts +45 -8
- package/dist/scope.js +69 -30
- package/dist/scope.js.map +1 -1
- package/dist/testing.js +1 -1
- package/dist/timing.d.ts +17 -7
- package/dist/timing.js +8 -3
- package/dist/timing.js.map +1 -1
- package/llms.txt +17 -6
- package/package.json +48 -12
- package/setup/apply.mjs +202 -0
- package/setup/cli.mjs +95 -0
- package/setup/common.mjs +91 -0
- package/setup/detect.mjs +274 -0
- package/setup/index.d.mts +39 -0
- package/setup/index.mjs +1290 -0
- package/setup/jsonc.mjs +201 -0
- package/setup/state.schema.json +57 -0
- package/setup/ui-baseline.mjs +210 -0
- package/dist/chunk-GY4XV2UV.js.map +0 -1
- package/dist/chunk-HW7KSM2Y.js.map +0 -1
- package/dist/chunk-KPXIOG2C.js +0 -54
- package/dist/chunk-KPXIOG2C.js.map +0 -1
- package/dist/chunk-KZJXHFIB.js.map +0 -1
- package/dist/chunk-LVH3GC6B.js.map +0 -1
- package/dist/chunk-QIP723L4.js.map +0 -1
- package/dist/chunk-SVATPF5R.js.map +0 -1
- package/dist/chunk-U6FK33SG.js +0 -20
- package/dist/chunk-U6FK33SG.js.map +0 -1
- package/dist/chunk-UZJ6I4T6.js.map +0 -1
- package/dist/chunk-V46JKE44.js.map +0 -1
- package/dist/chunk-ZDCJZCNO.js.map +0 -1
package/dist/timing.d.ts
CHANGED
|
@@ -35,7 +35,7 @@ interface Throttled<A extends unknown[]> {
|
|
|
35
35
|
(...args: A): void;
|
|
36
36
|
/** Drop any pending trailing call and reset the rate window, including from inside `fn`. */
|
|
37
37
|
cancel(): void;
|
|
38
|
-
/** Invoke the pending trailing call now (if any). */
|
|
38
|
+
/** Invoke the pending trailing call now (if any); the current cooldown keeps running. */
|
|
39
39
|
flush(): void;
|
|
40
40
|
}
|
|
41
41
|
/**
|
|
@@ -49,18 +49,28 @@ declare function debounce<A extends unknown[]>(fn: (...args: A) => void, ms: num
|
|
|
49
49
|
* at most once per `ms`. Calls during a cooldown collapse to a single trailing
|
|
50
50
|
* call at the window's end (with the latest arguments). `cancel()` drops a
|
|
51
51
|
* pending trailing call and resets the window, even when called by a leading
|
|
52
|
-
* or trailing callback; `flush()` runs a pending trailing call now
|
|
52
|
+
* or trailing callback; `flush()` runs a pending trailing call now but leaves
|
|
53
|
+
* the current cooldown running (unlike `debounce`'s `flush()`).
|
|
53
54
|
*/
|
|
54
55
|
declare function throttle<A extends unknown[]>(fn: (...args: A) => void, ms: number): Throttled<A>;
|
|
56
|
+
/** The signal {@link debouncedSignal} returns: a read-only trailing signal plus `dispose()`. */
|
|
57
|
+
type DebouncedSignal<T> = ReadonlySignal<T> & {
|
|
58
|
+
/**
|
|
59
|
+
* Stop following `source`: unsubscribes from it and drops any pending
|
|
60
|
+
* trailing write. The signal keeps its last value. Idempotent.
|
|
61
|
+
*/
|
|
62
|
+
dispose(): void;
|
|
63
|
+
};
|
|
55
64
|
/**
|
|
56
65
|
* A read-only signal that trails `source` by `ms` (trailing-edge). Writes to
|
|
57
66
|
* `source` reschedule; the derived value updates once writes go quiet, so it
|
|
58
67
|
* composes with `computed()`/`effect()`/`mount()` like any signal.
|
|
59
68
|
*
|
|
60
|
-
* Holds a live subscription to `source`
|
|
61
|
-
*
|
|
62
|
-
*
|
|
69
|
+
* Holds a live subscription to `source` until `dispose()` is called. A
|
|
70
|
+
* module-scope (app-lifetime) signal never needs to dispose; a per-row or
|
|
71
|
+
* per-component one should, or it keeps `source` subscribed (and any pending
|
|
72
|
+
* timer alive) after its owner is gone.
|
|
63
73
|
*/
|
|
64
|
-
declare function debouncedSignal<T>(source: ReadonlySignal<T>, ms: number):
|
|
74
|
+
declare function debouncedSignal<T>(source: ReadonlySignal<T>, ms: number): DebouncedSignal<T>;
|
|
65
75
|
|
|
66
|
-
export { type Debounced, type Throttled, debounce, debouncedSignal, throttle };
|
|
76
|
+
export { type Debounced, type DebouncedSignal, type Throttled, debounce, debouncedSignal, throttle };
|
package/dist/timing.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { signal, effect } from './chunk-
|
|
1
|
+
import { signal, effect } from './chunk-N4VHHOCM.js';
|
|
2
2
|
|
|
3
3
|
|
|
4
4
|
// src/timing.ts
|
|
@@ -69,10 +69,15 @@ function debouncedSignal(source, ms) {
|
|
|
69
69
|
const write = debounce((value) => {
|
|
70
70
|
out.value = value;
|
|
71
71
|
}, ms);
|
|
72
|
-
effect(() => {
|
|
72
|
+
const stop = effect(() => {
|
|
73
73
|
write(source.value);
|
|
74
74
|
});
|
|
75
|
-
return out
|
|
75
|
+
return Object.assign(out, {
|
|
76
|
+
dispose() {
|
|
77
|
+
stop();
|
|
78
|
+
write.cancel();
|
|
79
|
+
}
|
|
80
|
+
});
|
|
76
81
|
}
|
|
77
82
|
|
|
78
83
|
export { debounce, debouncedSignal, throttle };
|
package/dist/timing.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/timing.ts"],"names":[],"mappings":";;;;AA8CO,SAAS,QAAA,
|
|
1
|
+
{"version":3,"sources":["../src/timing.ts"],"names":[],"mappings":";;;;AA8CO,SAAS,QAAA,CACd,IACA,EAAA,EACc;AACd,EAAA,IAAI,KAAA;AACJ,EAAA,IAAI,QAAA;AAEJ,EAAA,MAAM,SAAS,MAAY;AACzB,IAAA,KAAA,GAAQ,MAAA;AACR,IAAA,MAAM,IAAA,GAAO,QAAA;AACb,IAAA,QAAA,GAAW,MAAA;AACX,IAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,EACZ,CAAA;AAEA,EAAA,MAAM,SAAA,IAAa,IAAI,IAAA,KAAkB;AACvC,IAAA,QAAA,GAAW,IAAA;AACX,IAAA,IAAI,KAAA,KAAU,MAAA,EAAW,YAAA,CAAa,KAAK,CAAA;AAC3C,IAAA,KAAA,GAAQ,UAAA,CAAW,QAAQ,EAAE,CAAA;AAAA,EAC/B,CAAA,CAAA;AAEA,EAAA,SAAA,CAAU,SAAS,MAAY;AAC7B,IAAA,IAAI,KAAA,KAAU,MAAA,EAAW,YAAA,CAAa,KAAK,CAAA;AAC3C,IAAA,KAAA,GAAQ,MAAA;AACR,IAAA,QAAA,GAAW,MAAA;AAAA,EACb,CAAA;AAEA,EAAA,SAAA,CAAU,QAAQ,MAAY;AAC5B,IAAA,IAAI,UAAU,MAAA,EAAW;AACvB,MAAA,YAAA,CAAa,KAAK,CAAA;AAClB,MAAA,MAAA,EAAO;AAAA,IACT;AAAA,EACF,CAAA;AAEA,EAAA,OAAO,SAAA;AACT;AAUO,SAAS,QAAA,CACd,IACA,EAAA,EACc;AACd,EAAA,IAAI,KAAA;AACJ,EAAA,IAAI,YAAA;AAEJ,EAAA,MAAM,cAAc,MAAY;AAC9B,IAAA,MAAM,IAAA,GAAO,YAAA;AACb,IAAA,YAAA,GAAe,MAAA;AACf,IAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,EACZ,CAAA;AAEA,EAAA,MAAM,gBAAgB,MAAY;AAChC,IAAA,KAAA,GAAQ,WAAW,MAAM;AACvB,MAAA,KAAA,GAAQ,MAAA;AACR,MAAA,IAAI,iBAAiB,MAAA,EAAW;AAI9B,QAAA,aAAA,EAAc;AACd,QAAA,WAAA,EAAY;AAAA,MACd;AAAA,IACF,GAAG,EAAE,CAAA;AAAA,EACP,CAAA;AAEA,EAAA,MAAM,SAAA,IAAa,IAAI,IAAA,KAAkB;AACvC,IAAA,IAAI,UAAU,MAAA,EAAW;AAGvB,MAAA,aAAA,EAAc;AACd,MAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,IACZ,CAAA,MAAO;AACL,MAAA,YAAA,GAAe,IAAA;AAAA,IACjB;AAAA,EACF,CAAA,CAAA;AAEA,EAAA,SAAA,CAAU,SAAS,MAAY;AAC7B,IAAA,IAAI,KAAA,KAAU,MAAA,EAAW,YAAA,CAAa,KAAK,CAAA;AAC3C,IAAA,KAAA,GAAQ,MAAA;AACR,IAAA,YAAA,GAAe,MAAA;AAAA,EACjB,CAAA;AAEA,EAAA,SAAA,CAAU,QAAQ,MAAY;AAC5B,IAAA,IAAI,YAAA,KAAiB,QAAW,WAAA,EAAY;AAAA,EAC9C,CAAA;AAEA,EAAA,OAAO,SAAA;AACT;AAqBO,SAAS,eAAA,CACd,QACA,EAAA,EACoB;AACpB,EAAA,MAAM,GAAA,GAAM,MAAA,CAAO,MAAA,CAAO,KAAK,CAAA;AAC/B,EAAA,MAAM,KAAA,GAAQ,QAAA,CAAS,CAAC,KAAA,KAAa;AACnC,IAAA,GAAA,CAAI,KAAA,GAAQ,KAAA;AAAA,EACd,GAAG,EAAE,CAAA;AACL,EAAA,MAAM,IAAA,GAAO,OAAO,MAAM;AACxB,IAAA,KAAA,CAAM,OAAO,KAAK,CAAA;AAAA,EACpB,CAAC,CAAA;AACD,EAAA,OAAO,MAAA,CAAO,OAAO,GAAA,EAAK;AAAA,IACxB,OAAA,GAAgB;AACd,MAAA,IAAA,EAAK;AACL,MAAA,KAAA,CAAM,MAAA,EAAO;AAAA,IACf;AAAA,GACD,CAAA;AACH","file":"timing.js","sourcesContent":["/**\n * `kerfjs/timing` — the small timing primitives every app hand-rolls.\n *\n * kerf already replaced most imperative bookkeeping — `delegate` for listeners,\n * `mount`/`effect` for render, `defineStore` for state — but debouncing and\n * throttling still get written by hand as `let timer; clearTimeout(timer);\n * timer = setTimeout(fn, ms)`. This subpath blesses that with disposer-shaped\n * ergonomics (`.cancel()` / `.flush()`), plus `debouncedSignal` so a trailing\n * value composes inside the reactive graph instead of beside it.\n *\n * import { debounce, throttle, debouncedSignal } from 'kerfjs/timing';\n *\n * const save = debounce(() => persist(state), 300);\n * input.addEventListener('input', save); // save.cancel() on teardown\n *\n * const query = signal('');\n * const debouncedQuery = debouncedSignal(query, 250); // trails query by 250ms\n *\n * Tree-shakeable and tiny — `debounce`/`throttle` are dependency-free; only\n * `debouncedSignal` pulls in signals (no render core).\n */\nimport { effect, type ReadonlySignal, signal } from './reactive.js';\n\n/** A debounced function: call it like the original, plus `cancel()` / `flush()`. */\nexport interface Debounced<A extends unknown[]> {\n (...args: A): void;\n /** Drop any pending trailing call without invoking it. */\n cancel(): void;\n /** Invoke the pending trailing call now (if any) and clear the timer. */\n flush(): void;\n}\n\n/** A throttled function: call it like the original, plus `cancel()` / `flush()`. */\nexport interface Throttled<A extends unknown[]> {\n (...args: A): void;\n /** Drop any pending trailing call and reset the rate window, including from inside `fn`. */\n cancel(): void;\n /** Invoke the pending trailing call now (if any); the current cooldown keeps running. */\n flush(): void;\n}\n\n/**\n * Trailing-edge debounce: `fn` runs `ms` after calls STOP, with the most recent\n * arguments. Every call within the quiet window resets the timer. `cancel()`\n * drops a pending call; `flush()` runs it immediately.\n */\nexport function debounce<A extends unknown[]>(\n fn: (...args: A) => void,\n ms: number,\n): Debounced<A> {\n let timer: ReturnType<typeof setTimeout> | undefined;\n let lastArgs: A | undefined;\n\n const invoke = (): void => {\n timer = undefined;\n const args = lastArgs as A;\n lastArgs = undefined;\n fn(...args);\n };\n\n const debounced = ((...args: A): void => {\n lastArgs = args;\n if (timer !== undefined) clearTimeout(timer);\n timer = setTimeout(invoke, ms);\n }) as Debounced<A>;\n\n debounced.cancel = (): void => {\n if (timer !== undefined) clearTimeout(timer);\n timer = undefined;\n lastArgs = undefined;\n };\n\n debounced.flush = (): void => {\n if (timer !== undefined) {\n clearTimeout(timer);\n invoke();\n }\n };\n\n return debounced;\n}\n\n/**\n * Leading-plus-trailing throttle: `fn` runs immediately on the first call, then\n * at most once per `ms`. Calls during a cooldown collapse to a single trailing\n * call at the window's end (with the latest arguments). `cancel()` drops a\n * pending trailing call and resets the window, even when called by a leading\n * or trailing callback; `flush()` runs a pending trailing call now but leaves\n * the current cooldown running (unlike `debounce`'s `flush()`).\n */\nexport function throttle<A extends unknown[]>(\n fn: (...args: A) => void,\n ms: number,\n): Throttled<A> {\n let timer: ReturnType<typeof setTimeout> | undefined;\n let trailingArgs: A | undefined;\n\n const runTrailing = (): void => {\n const args = trailingArgs as A;\n trailingArgs = undefined;\n fn(...args);\n };\n\n const startCooldown = (): void => {\n timer = setTimeout(() => {\n timer = undefined;\n if (trailingArgs !== undefined) {\n // Install the next window before invoking user code. A trailing\n // callback can therefore cancel that window, and reentrant calls stay\n // throttled unless the callback explicitly resets it first.\n startCooldown();\n runTrailing();\n }\n }, ms);\n };\n\n const throttled = ((...args: A): void => {\n if (timer === undefined) {\n // Make the pending window visible before invoking user code so\n // `cancel()` from inside a leading callback remains effective.\n startCooldown();\n fn(...args); // leading edge\n } else {\n trailingArgs = args; // collapse into one trailing call\n }\n }) as Throttled<A>;\n\n throttled.cancel = (): void => {\n if (timer !== undefined) clearTimeout(timer);\n timer = undefined;\n trailingArgs = undefined;\n };\n\n throttled.flush = (): void => {\n if (trailingArgs !== undefined) runTrailing();\n };\n\n return throttled;\n}\n\n/** The signal {@link debouncedSignal} returns: a read-only trailing signal plus `dispose()`. */\nexport type DebouncedSignal<T> = ReadonlySignal<T> & {\n /**\n * Stop following `source`: unsubscribes from it and drops any pending\n * trailing write. The signal keeps its last value. Idempotent.\n */\n dispose(): void;\n};\n\n/**\n * A read-only signal that trails `source` by `ms` (trailing-edge). Writes to\n * `source` reschedule; the derived value updates once writes go quiet, so it\n * composes with `computed()`/`effect()`/`mount()` like any signal.\n *\n * Holds a live subscription to `source` until `dispose()` is called. A\n * module-scope (app-lifetime) signal never needs to dispose; a per-row or\n * per-component one should, or it keeps `source` subscribed (and any pending\n * timer alive) after its owner is gone.\n */\nexport function debouncedSignal<T>(\n source: ReadonlySignal<T>,\n ms: number,\n): DebouncedSignal<T> {\n const out = signal(source.value);\n const write = debounce((value: T) => {\n out.value = value;\n }, ms);\n const stop = effect(() => {\n write(source.value); // tracks source; reschedules on every change\n });\n return Object.assign(out, {\n dispose(): void {\n stop();\n write.cancel();\n },\n });\n}\n"]}
|
package/llms.txt
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# kerf
|
|
2
2
|
|
|
3
|
-
> A tiny (~
|
|
3
|
+
> A tiny (~15 KB minified + gzipped including its one runtime dependency `@preact/signals-core`; ~16 KB with `arraySignal`) reactive UI framework — fine-grained signals + DOM morphing + JSX. No virtual DOM, no compiler. Apply the smallest possible cut to update your DOM.
|
|
4
4
|
|
|
5
|
-
kerf renders JSX to a structured `SafeHtml` (string for static content; tagged "list"/"mixed" segments where `each(...)` was used) and reconciles it against the live tree with a custom segment-aware morph. Static surrounds go through a general-purpose tree-morph; list contents go through a keyed reconciler that operates directly on live children. Snapshot reconciliation scans O(rows) but limits rendering and DOM mutations to cache misses and structural changes; eligible `arraySignal` patch delivery runs in O(patches). Reactivity is provided by [@preact/signals-core](https://github.com/preactjs/signals). It pairs well with server-rendered HTML, embedded widgets, and any UI where preserving focus / selection across re-renders matters. Public API is one import: `signal`, `computed`, `effect`, `batch`, `defineStore`, `resetAllStores`, `mount`, `morph`, `each`, `attr`, `delegate`, `delegateCapture`, `toElement`, `renderDocument`, `SafeHtml`, `isSafeHtml`, `raw`, `Fragment`. (Two more subpaths: `kerfjs/testing` exposes `clearStoreRegistry` for unit-test isolation; `kerfjs/jsx-runtime` exposes the typed JSX building blocks for declaration-merging custom-element types.) An optional subpath at `kerfjs/array-signal` adds `arraySignal()` — a granular keyed-list signal whose patch events let `each()` reconcile in O(patches) instead of O(N). An optional subpath at `kerfjs/dev` installs the development diagnostics — kerf does NOT infer dev mode, so you import it behind your own build's dev flag (`if (import.meta.env.DEV) await import('kerfjs/dev');`); omitting it is production and sheds ~4.7 KB min+gzip. Another optional subpath at `kerfjs/html` adds the `html` tagged template — JSX-identical runtime semantics with no JSX transform, so CDN/importmap projects can author kerf UIs with literally no build step. A family of optional, tree-shakeable **companion-utility** subpaths cover patterns real apps hand-roll: `kerfjs/list` (`bindList` — a keyed list with per-row fine-grained mounts and fixed / declared / measured-height viewport virtualization, plus `observeRowHeights`), `kerfjs/router` (`createRouter` — the opt-in "postcard router": route matching + `navigate` + `<a>` link interception + a keyed outlet, core stays router-free), `kerfjs/overlay` (`overlay` / `confirm` / `prompt` / `form` / `choice` / `popover` / `tooltip` / `toast` + `positionAnchored` / `autoReposition`; `native: true` top-layer backing via `<dialog>` / the Popover API applies to the seven overlay/dialog/popover/tooltip surfaces), `kerfjs/scope` (`disposeScope` / `disposeSubtree` / `observeRemovals`), `kerfjs/async` (`resource` async-state with a stale-response guard + SWR cache), `kerfjs/timing` (`debounce` / `throttle` / `debouncedSignal`), `kerfjs/remount` (`remountOn` — key-driven wholesale subtree replacement), `kerfjs/attach` (`attach` — bind a non-kerf widget's lifecycle to one node), and `kerfjs/actions` (`action` / `delegateActions` — the delegated `data-action` table idiom).
|
|
5
|
+
kerf renders JSX to a structured `SafeHtml` (string for static content; tagged "list"/"mixed" segments where `each(...)` was used) and reconciles it against the live tree with a custom segment-aware morph. Static surrounds go through a general-purpose tree-morph; list contents go through a keyed reconciler that operates directly on live children. Snapshot reconciliation scans O(rows) but limits rendering and DOM mutations to cache misses and structural changes; eligible `arraySignal` patch delivery runs in O(patches). Reactivity is provided by [@preact/signals-core](https://github.com/preactjs/signals). It pairs well with server-rendered HTML, embedded widgets, and any UI where preserving focus / selection across re-renders matters. Public API is one import: `signal`, `computed`, `effect`, `batch`, `defineStore`, `resetAllStores`, `mount`, `morph`, `each`, `attr`, `delegate`, `delegateCapture`, `toElement`, `renderDocument`, `SafeHtml`, `isSafeHtml`, `raw`, `Fragment`. (Two more subpaths: `kerfjs/testing` exposes `clearStoreRegistry` for unit-test isolation; `kerfjs/jsx-runtime` exposes the typed JSX building blocks for declaration-merging custom-element types.) An optional subpath at `kerfjs/array-signal` adds `arraySignal()` — a granular keyed-list signal whose patch events let `each()` reconcile in O(patches) instead of O(N). An optional subpath at `kerfjs/dev` installs the development diagnostics — kerf does NOT infer dev mode, so you import it behind your own build's dev flag (`if (import.meta.env.DEV) await import('kerfjs/dev');`); omitting it is production and sheds ~4.7 KB min+gzip. Another optional subpath at `kerfjs/html` adds the `html` tagged template — JSX-identical runtime semantics with no JSX transform, so CDN/importmap projects can author kerf UIs with literally no build step. A family of optional, tree-shakeable **companion-utility** subpaths cover patterns real apps hand-roll: `kerfjs/list` (`bindList` — a keyed list with per-row fine-grained mounts and fixed / declared / measured-height viewport virtualization, plus `observeRowHeights`), `kerfjs/router` (`createRouter` — the opt-in "postcard router": route matching + `navigate` + `<a>` link interception + a keyed outlet, core stays router-free), `kerfjs/overlay` (`overlay` / `confirm` / `prompt` / `form` / `choice` / `popover` / `tooltip` / `toast` + `positionAnchored` / `autoReposition`; `native: true` top-layer backing via `<dialog>` / the Popover API applies to the seven overlay/dialog/popover/tooltip surfaces), `kerfjs/scope` (`createScope` / `disposeScope` / `disposeSubtree` / `observeRemovals`), `kerfjs/async` (`resource` async-state with a stale-response guard + SWR cache), `kerfjs/timing` (`debounce` / `throttle` / `debouncedSignal`), `kerfjs/remount` (`remountOn` — key-driven wholesale subtree replacement), `kerfjs/attach` (`attach` — bind a non-kerf widget's lifecycle to one node), and `kerfjs/actions` (`action` / `delegateActions` — the delegated `data-action` table idiom).
|
|
6
6
|
|
|
7
7
|
## For humans new to the codebase
|
|
8
8
|
|
|
@@ -10,14 +10,18 @@ kerf renders JSX to a structured `SafeHtml` (string for static content; tagged "
|
|
|
10
10
|
|
|
11
11
|
## For AI assistants
|
|
12
12
|
|
|
13
|
+
- One-step project setup: run `npx kerfjs setup` for a safe dry-run, then
|
|
14
|
+
`npx kerfjs setup --write --yes`; see
|
|
15
|
+
[AI-first setup](https://github.com/brianwestphal/kerf/blob/main/docs/24-ai-first-setup.md).
|
|
16
|
+
|
|
13
17
|
- [AI usage guide](https://github.com/brianwestphal/kerf/blob/main/docs/ai/usage-guide.md): when to recommend kerf, the full public API, the four core patterns, hard rules, and a common-errors table.
|
|
14
18
|
- [Code summary](https://github.com/brianwestphal/kerf/blob/main/docs/ai/code-summary.md): directory tree + reverse index of every public export.
|
|
15
19
|
- [Requirements summary](https://github.com/brianwestphal/kerf/blob/main/docs/ai/requirements-summary.md): synthesized view of the numbered design docs.
|
|
16
20
|
- [`kerf.cursorrules`](https://github.com/brianwestphal/kerf/blob/main/kerf.cursorrules): drop-in [Cursor](https://cursor.sh) rules for projects that import `kerfjs`. Copy into your project as `.cursorrules` — or use the bundled mirror at `node_modules/kerfjs/ai/cursorrules` once you've `npm install`ed kerfjs.
|
|
17
21
|
- [`kerf.claude-skill.md`](https://github.com/brianwestphal/kerf/blob/main/kerf.claude-skill.md): drop-in [Claude Code](https://claude.com/claude-code) skill. Copy into `~/.claude/skills/kerf-app/SKILL.md` (or your project's `.claude/skills/kerf-app/SKILL.md`) — or use the bundled mirror at `node_modules/kerfjs/ai/skill.md` once you've `npm install`ed kerfjs.
|
|
18
|
-
- [`eslint-plugin-kerfjs`](https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/README.md): companion ESLint plugin enforcing the hard rules at edit time —
|
|
19
|
-
- [`create-kerf-component`](https://github.com/brianwestphal/kerf/blob/main/create-kerf-component/README.md): companion initializer that scaffolds a publishable kerf component package with the hard packaging rules
|
|
20
|
-
- [`@kerfjs/ui` AI guide](https://github.com/brianwestphal/kerf/blob/main/ui/ai/skill.md): component-selection
|
|
22
|
+
- [`eslint-plugin-kerfjs`](https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/README.md): companion ESLint plugin enforcing the hard rules at edit time — nine core rules in `kerfjs.configs.recommended`: `no-inline-jsx-event-handlers`, `require-data-key-in-each`, `no-nested-mount`, `prefer-module-jsx-augmentation`, `no-generated-view-edits` (error) plus `require-delegate-disposer`, `prefer-attr-selector`, `no-raw-with-dynamic-arg`, `ai-assistant-configs` (warn), with no `parserServices` dependency; plus seven `@kerfjs/ui` catalog-contract rules (`ui-component-ownership`, `ui-composition`, `ui-css-values`, `ui-exceptional-shorthands`, `ui-preferences`, `ui-public-boundaries`, `ui-wiring`) in the `recommended-ui` / `strict-ui` configs. Install with `npm install --save-dev eslint-plugin-kerfjs` and add `kerfjs.configs.recommended` to your eslint config. Recommended when authoring kerf code with an AI assistant — eslint feedback surfaces in the IDE before `tsc` or runtime warns ever run.
|
|
23
|
+
- [`create-kerf-component`](https://github.com/brianwestphal/kerf/blob/main/create-kerf-component/README.md): companion initializer that scaffolds a publishable kerf component package with the hard packaging rules, an example component, and explicit `kerf.components.json` source metadata plus deterministic `component-composition.json` generation/checking. Run `npm create kerf-component@latest <dir>`.
|
|
24
|
+
- [`@kerfjs/ui` AI guide](https://github.com/brianwestphal/kerf/blob/main/ui/ai/skill.md) and [UI `llms.txt`](https://brianwestphal.github.io/kerf/ui/llms.txt) (also bundled at `node_modules/@kerfjs/ui/llms.txt`): start with the component-selection decision pass before writing JSX or CSS; use the package's layout and spacing ownership to avoid custom wrappers and styling.
|
|
21
25
|
|
|
22
26
|
## Reference docs
|
|
23
27
|
|
|
@@ -34,15 +38,22 @@ kerf renders JSX to a structured `SafeHtml` (string for static content; tagged "
|
|
|
34
38
|
- [Dev-mode warnings](https://github.com/brianwestphal/kerf/blob/main/docs/11-dev-warnings.md): the opt-in, switch-gated `KERF_DEV_WARN_*` family (environment variables in Node/CI or `enableWarnings()` in browser builds), plus the always-on dev guards and `KERF_DEV_INVARIANTS` structural checks; diagnostics are installed through `kerfjs/dev`, never inferred from the environment.
|
|
35
39
|
- [AI-assistant configs](https://github.com/brianwestphal/kerf/blob/main/docs/12-ai-assistant-configs.md): how the drop-in Claude Code skill + Cursor rules ship inside the `kerfjs` npm package at `ai/skill.md` / `ai/cursorrules` / `ai/manifest.json`, the version + marker contract for customization preservation, and the `kerfjs/ai-assistant-configs` ESLint rule that surfaces drift on every lint pass.
|
|
36
40
|
- [Component packages](https://github.com/brianwestphal/kerf/blob/main/docs/13-component-packages.md): building and publishing reusable kerf components as npm packages — the no-instance component model, per-instance state via factories, event/cleanup patterns, and `kerfjs`-as-peer-dependency packaging modeled on `eslint-plugin-kerfjs`. Scaffold one with `npm create kerf-component@latest <dir>` (the `create-kerf-component` initializer).
|
|
37
|
-
- [Feature coverage](https://github.com/brianwestphal/kerf/blob/main/docs/14-feature-coverage.md): the per-behavior coverage axis orthogonal to line coverage — an index mapping each behavior (especially list-reconciler
|
|
41
|
+
- [Feature coverage](https://github.com/brianwestphal/kerf/blob/main/docs/14-feature-coverage.md): the per-behavior coverage axis orthogonal to line coverage — an index mapping each behavior (especially list-reconciler _state transitions_) to its guarding test, enforced by `npm run check:features`.
|
|
38
42
|
- [No-build example](https://github.com/brianwestphal/kerf/blob/main/docs/15-no-build-example.md): the served-as-source `live-poll` example app — plain JS + importmap + the `html` tagged template, zero tooling — and the vendor-copy contract that ships it.
|
|
39
43
|
- [List identity](https://github.com/brianwestphal/kerf/blob/main/docs/16-list-identity.md): why an `each()` list's call-order identity is not stable, what the source guard fixes and what it doesn't, the five constraints any scheme must survive, and the explicit-key recommendation now shipped as `each(items, render, { key })`.
|
|
40
44
|
- [List virtualization](https://github.com/brianwestphal/kerf/blob/main/docs/17-list-virtualization.md): `bindList`'s virtualization — the `window` (default) height models (fixed `number`, app-declared `(item, index) => number`, and measured `{ estimate }` + `setHeight`) with kerf owning the cumulative-offset math and scroll anchoring while the app owns measurement (the `observeRowHeights` helper), the `minRows` render-all threshold and container/resize ergonomics, and the `content-visibility` mode that keeps every row in the DOM (full find-in-page / a11y) while the browser skips off-screen layout, plus the findability/a11y tradeoff of the default `window` mode.
|
|
41
45
|
- [State-preserving moves](https://github.com/brianwestphal/kerf/blob/main/docs/18-state-preserving-moves.md): connected-row reorders (every `each()` / `bindList` / `morph` move site) use `Node.prototype.moveBefore()` where the engine supports it — an atomic move that keeps focus, selection, `<iframe>` state, playing media, and running CSS animations across the reorder — falling back to `insertBefore()` otherwise. Transparent internal `moveNode` helper; no API change.
|
|
46
|
+
- [List View Transitions](https://github.com/brianwestphal/kerf/blob/main/docs/view-transitions.md): browser-verified, app-owned recipe for optional list reorder, insert, and remove motion with `each()` or `bindList()`; the [design decision](https://github.com/brianwestphal/kerf/blob/main/docs/view-transitions-design.md) explains the snapshot boundary.
|
|
42
47
|
- [Native overlay backing](https://github.com/brianwestphal/kerf/blob/main/docs/19-native-overlay-backing.md): opt-in `native: true` on the seven overlay/dialog/popover/tooltip surfaces hosts the overlay in the browser top layer — a `<dialog>.showModal()` for modal surfaces, the Popover API for non-modal — feature-detected, falling back to today's plain `<div>` where unsupported. Toasts and standalone positioning helpers do not create native top-layer hosts.
|
|
43
48
|
- [Router](https://github.com/brianwestphal/kerf/blob/main/docs/20-router.md): the opt-in, tree-shakeable `kerfjs/router` subpath — the "postcard router". `createRouter({ routes, mode?, base?, interceptLinks? })` → a reactive `route` signal, `navigate`/`back`/`forward`, `match`/`activeClass` active-link helpers, a keyed `outlet()` (a route change swaps the page wholesale, a same-route param change morphs in place), and `dispose()`. Route matching (`:param` / `*rest` / `*`), `delegate()`-based `<a href>` interception, history + hash modes, optional base. The core stays router-free (docs/1's "Not a router" is about the runtime); deliberately excludes nested layouts / loaders / lazy routes / guards / SSR.
|
|
44
49
|
- [`@kerfjs/ui`](https://github.com/brianwestphal/kerf/blob/main/docs/21-ui-package.md): the first-party component package, semantic CSS tokens, accessibility and keyboard contracts, explicit Web Awesome registration, UX catalog, AI surfaces, and lockstep release model.
|
|
45
50
|
- [UI CSS authoring](https://github.com/brianwestphal/kerf/blob/main/docs/22-ui-css-authoring.md): pixel-first `remify(<px>)` source syntax, fixed 16px conversion baseline, compiled `rem` package output, and Vite HMR behavior.
|
|
51
|
+
- [App and dialog layouts](https://github.com/brianwestphal/kerf/blob/main/docs/23-app-layouts.md): responsive whole-screen `@kerfjs/ui` layouts, the shared device-class foundation, controlled state model, and layout-selection guidance.
|
|
52
|
+
- [AI-first project setup](https://github.com/brianwestphal/kerf/blob/main/docs/24-ai-first-setup.md): dry-run-first `npx kerfjs setup`, deterministic workspace discovery, explicit conflict resolution, transactional writes, and the automation API.
|
|
53
|
+
- [Ticket phase timing](https://github.com/brianwestphal/kerf/blob/main/docs/25-ticket-timing.md): structured Hot Sheet phase intervals and process-review summaries without raw output, secrets, or machine-specific paths.
|
|
54
|
+
- [Kerf UI editor (design)](https://github.com/brianwestphal/kerf/blob/main/docs/26-ui-editor.md): JSON view documents as the source of truth, read-only generated view modules with a typed contract and digest, contract-diff re-export, and runtime interpretation.
|
|
55
|
+
- [Off-main-thread compute (decided: recipe, no subpath)](https://github.com/brianwestphal/kerf/blob/main/docs/27-worker.md): measured Worker crossover (send-every-call never pays; worker-resident data does once a call exceeds a few milliseconds; transfer binary data) and the recipe-vs-`kerfjs/worker`-subpath decision.
|
|
56
|
+
- [Editor Library previews (built)](https://github.com/brianwestphal/kerf/blob/main/docs/28-library-previews.md): one preview-registration mechanism for first-party, installed-package and application components (`defineLibraryPreviews`, keyed by full catalog key: sample props, a pure static renderer, an icon fallback, fit), literal-JSON composition samples with an optional preview module, and a fixed override precedence.
|
|
46
57
|
|
|
47
58
|
## Examples
|
|
48
59
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "kerfjs",
|
|
3
|
-
"version": "5.0.0-beta.
|
|
3
|
+
"version": "5.0.0-beta.131",
|
|
4
4
|
"description": "Tiny reactive UI framework — fine-grained signals + DOM morphing + JSX. Apply the smallest possible cut to update your DOM.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": [
|
|
@@ -35,6 +35,9 @@
|
|
|
35
35
|
},
|
|
36
36
|
"main": "./dist/index.js",
|
|
37
37
|
"types": "./dist/index.d.ts",
|
|
38
|
+
"bin": {
|
|
39
|
+
"kerfjs": "./setup/cli.mjs"
|
|
40
|
+
},
|
|
38
41
|
"exports": {
|
|
39
42
|
".": {
|
|
40
43
|
"types": "./dist/index.d.ts",
|
|
@@ -100,11 +103,17 @@
|
|
|
100
103
|
"types": "./dist/attach.d.ts",
|
|
101
104
|
"import": "./dist/attach.js"
|
|
102
105
|
},
|
|
103
|
-
"./ai/*": "./ai/*"
|
|
106
|
+
"./ai/*": "./ai/*",
|
|
107
|
+
"./setup": {
|
|
108
|
+
"types": "./setup/index.d.mts",
|
|
109
|
+
"import": "./setup/index.mjs"
|
|
110
|
+
},
|
|
111
|
+
"./setup/state.schema.json": "./setup/state.schema.json"
|
|
104
112
|
},
|
|
105
113
|
"files": [
|
|
106
114
|
"dist",
|
|
107
115
|
"ai",
|
|
116
|
+
"setup",
|
|
108
117
|
"llms.txt",
|
|
109
118
|
"README.md",
|
|
110
119
|
"CHANGELOG.md",
|
|
@@ -113,27 +122,37 @@
|
|
|
113
122
|
"scripts": {
|
|
114
123
|
"build": "tsup && node scripts/clean-dist-output.mjs dist",
|
|
115
124
|
"dev": "tsup --watch",
|
|
116
|
-
"
|
|
125
|
+
"dev:lan": "npm --prefix ui run dev:lan",
|
|
126
|
+
"test": "vitest run --coverage --maxWorkers=2",
|
|
117
127
|
"test:watch": "vitest",
|
|
118
128
|
"test:unit": "vitest run tests/unit --coverage",
|
|
119
129
|
"test:integration": "vitest run tests/integration --coverage",
|
|
120
130
|
"test:dist": "npm run build && vitest run --config vitest.config.dist.ts",
|
|
121
131
|
"test:dist:full": "npm run build && vitest run --config vitest.config.dist-full.ts",
|
|
122
132
|
"test:dist:jsx-typing": "npm run build && node node_modules/typescript7/bin/tsc -p tests/dist/jsx-typing/tsconfig.json",
|
|
133
|
+
"test:packed:jsx-typing": "npm run build && node scripts/check-packed-jsx-typing.mjs",
|
|
123
134
|
"test:dist:examples": "npm run build && node node_modules/typescript7/bin/tsc -p site/src/examples/complete/tsconfig.json",
|
|
124
135
|
"test:dist:scaffold-typing": "npm run build && node node_modules/typescript7/bin/tsc -p tests/dist/scaffold-typing/tsconfig.json",
|
|
125
136
|
"test:browser": "npm run build && playwright test",
|
|
126
137
|
"test:ui": "npm --prefix ui test",
|
|
127
138
|
"bench:micro": "vitest bench --run --config vitest.config.bench.ts",
|
|
128
139
|
"bench:serve": "bash bench/site.sh",
|
|
129
|
-
"
|
|
140
|
+
"format": "prettier --write . --ignore-unknown",
|
|
141
|
+
"format:check": "prettier --check . --ignore-unknown",
|
|
142
|
+
"lint:eslint": "eslint src tests scripts --max-warnings 0",
|
|
143
|
+
"lint:site": "npm --prefix site run lint",
|
|
144
|
+
"lint": "npm run lint:eslint && npm run lint:site && npm run format:check",
|
|
130
145
|
"typecheck": "node node_modules/typescript7/bin/tsc --noEmit",
|
|
131
|
-
"check": "
|
|
146
|
+
"check": "node scripts/check-guidance-integrity.mjs --record-pass -- node scripts/run-check-steps.mjs check:core",
|
|
147
|
+
"push": "node scripts/push.mjs",
|
|
148
|
+
"check:core": "npm run lint && npm run typecheck && node scripts/check-doc-test-inventory.mjs && node scripts/check-doc-api-coverage.mjs && node scripts/check-doc-ui-api-coverage.mjs && node scripts/check-doc-ui-subpaths.mjs && node scripts/check-doc-site-tickets.mjs && node scripts/check-cdn-versions.mjs && node scripts/check-dev-warn-docs.mjs && node scripts/check-skill-freshness.mjs && node scripts/check-design-rule-5.mjs && node scripts/check-feature-coverage.mjs && node scripts/sync-lockstep-versions.mjs --check && node scripts/sync-scaffold-catalog-schema.mjs --check && node scripts/check-ai-bundle.mjs && node --test scripts/verified-worktree-cleanup.test.mjs && npm test && npm run build && node scripts/check-bundle-size.mjs && node scripts/check-doc-api-signatures.mjs && vitest run --config vitest.config.dist.ts && vitest run --config vitest.config.dist-full.ts && node node_modules/typescript7/bin/tsc -p tests/dist/jsx-typing/tsconfig.json && node scripts/check-packed-jsx-typing.mjs && node node_modules/typescript7/bin/tsc -p site/src/examples/complete/tsconfig.json && node node_modules/typescript7/bin/tsc -p tests/dist/scaffold-typing/tsconfig.json && node scripts/check-docs-examples.mjs && node scripts/check-package-gates.mjs",
|
|
132
149
|
"check:docs:examples": "node scripts/check-docs-examples.mjs",
|
|
133
150
|
"check:full": "npm run check && npm run --silent check:audit && playwright test",
|
|
134
151
|
"check:ui": "npm --prefix ui run check",
|
|
135
152
|
"check:docs:test-inventory": "node scripts/check-doc-test-inventory.mjs",
|
|
136
153
|
"check:docs:api-coverage": "node scripts/check-doc-api-coverage.mjs",
|
|
154
|
+
"check:docs:ui-api-coverage": "node scripts/check-doc-ui-api-coverage.mjs",
|
|
155
|
+
"check:docs:ui-subpaths": "node scripts/check-doc-ui-subpaths.mjs",
|
|
137
156
|
"check:docs:site-tickets": "node scripts/check-doc-site-tickets.mjs",
|
|
138
157
|
"check:cdn-versions": "node scripts/check-cdn-versions.mjs",
|
|
139
158
|
"check:docs:api-signatures": "npm run build && node scripts/check-doc-api-signatures.mjs",
|
|
@@ -143,6 +162,8 @@
|
|
|
143
162
|
"ai-bundle:sync": "node scripts/sync-ai-bundle.mjs",
|
|
144
163
|
"check:lockstep-versions": "node scripts/sync-lockstep-versions.mjs --check",
|
|
145
164
|
"sync:lockstep-versions": "node scripts/sync-lockstep-versions.mjs --write",
|
|
165
|
+
"check:scaffold-catalog-schema": "node scripts/sync-scaffold-catalog-schema.mjs --check",
|
|
166
|
+
"sync:scaffold-catalog-schema": "node scripts/sync-scaffold-catalog-schema.mjs --write",
|
|
146
167
|
"clean": "rm -rf dist coverage node_modules/.cache",
|
|
147
168
|
"prepare": "husky",
|
|
148
169
|
"release": "bash scripts/release.sh",
|
|
@@ -159,10 +180,13 @@
|
|
|
159
180
|
"check:skills": "node scripts/check-skill-freshness.mjs",
|
|
160
181
|
"check:design-rule-5": "node scripts/check-design-rule-5.mjs",
|
|
161
182
|
"check:docs:dev-warns": "node scripts/check-dev-warn-docs.mjs",
|
|
162
|
-
"check:audit": "npm audit --omit=dev --audit-level=high"
|
|
183
|
+
"check:audit": "npm audit --omit=dev --audit-level=high",
|
|
184
|
+
"ticket:timing": "node scripts/ticket-timing.mjs"
|
|
163
185
|
},
|
|
164
186
|
"dependencies": {
|
|
165
|
-
"@preact/signals-core": "^1.14.1"
|
|
187
|
+
"@preact/signals-core": "^1.14.1",
|
|
188
|
+
"minimatch": "^6.2.3",
|
|
189
|
+
"yaml": "^2.9.1"
|
|
166
190
|
},
|
|
167
191
|
"devDependencies": {
|
|
168
192
|
"@eslint/js": "^10.0.1",
|
|
@@ -171,21 +195,33 @@
|
|
|
171
195
|
"@types/node": "^22.10.0",
|
|
172
196
|
"@typescript-eslint/eslint-plugin": "^8.65.0",
|
|
173
197
|
"@typescript-eslint/parser": "^8.65.0",
|
|
174
|
-
"@vitest/coverage-v8": "^4.1.
|
|
175
|
-
"domotion-svg": "^0.
|
|
198
|
+
"@vitest/coverage-v8": "^4.1.12",
|
|
199
|
+
"domotion-svg": "^0.35.0",
|
|
176
200
|
"eslint": "^10.8.0",
|
|
177
201
|
"eslint-plugin-simple-import-sort": "^12.1.1",
|
|
178
|
-
"gitgist": "
|
|
179
|
-
"happy-dom": "^
|
|
202
|
+
"gitgist": "1.2.0",
|
|
203
|
+
"happy-dom": "^21.0.4",
|
|
180
204
|
"http-server": "^14.1.1",
|
|
181
205
|
"husky": "^9.1.7",
|
|
182
206
|
"jsdom": "^29.1.1",
|
|
207
|
+
"prettier": "^3.9.8",
|
|
208
|
+
"prettier-plugin-astro": "^1.0.1",
|
|
209
|
+
"prettier-plugin-sh": "^0.19.0",
|
|
183
210
|
"tsup": "^8.3.0",
|
|
184
211
|
"typescript": "^6.0.3",
|
|
185
212
|
"typescript7": "npm:typescript@^7.0.2",
|
|
186
|
-
"
|
|
213
|
+
"vite": "^8.3.4",
|
|
214
|
+
"vitest": "^4.1.12"
|
|
215
|
+
},
|
|
216
|
+
"overrides": {
|
|
217
|
+
"esbuild": "0.28.2",
|
|
218
|
+
"minimatch@>=7 <11.0.1": "^11.0.5"
|
|
187
219
|
},
|
|
188
220
|
"gitgist": {
|
|
221
|
+
"provider": "claude-cli",
|
|
222
|
+
"fallbackProvider": "codex",
|
|
223
|
+
"maxDiffChars": 150000,
|
|
224
|
+
"linkCommits": true,
|
|
189
225
|
"exclude": [
|
|
190
226
|
"site/public/demos/*.svg",
|
|
191
227
|
"ai/*",
|
package/setup/apply.mjs
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
import { execFile } from 'node:child_process';
|
|
2
|
+
import { randomUUID } from 'node:crypto';
|
|
3
|
+
import {
|
|
4
|
+
lstat,
|
|
5
|
+
mkdir,
|
|
6
|
+
realpath,
|
|
7
|
+
rename,
|
|
8
|
+
rm,
|
|
9
|
+
rmdir,
|
|
10
|
+
writeFile,
|
|
11
|
+
} from 'node:fs/promises';
|
|
12
|
+
import { dirname, resolve } from 'node:path';
|
|
13
|
+
import process from 'node:process';
|
|
14
|
+
import { promisify } from 'node:util';
|
|
15
|
+
|
|
16
|
+
import { contained, exists, readText } from './common.mjs';
|
|
17
|
+
|
|
18
|
+
const execFileAsync = promisify(execFile);
|
|
19
|
+
|
|
20
|
+
export async function applyKerfSetup(
|
|
21
|
+
plan,
|
|
22
|
+
{ install = true, offline = false, runner = execFileAsync } = {},
|
|
23
|
+
) {
|
|
24
|
+
if (plan.conflicts.length)
|
|
25
|
+
throw new Error('Resolve setup conflicts before applying changes.');
|
|
26
|
+
const written = [];
|
|
27
|
+
const temporaryPaths = [];
|
|
28
|
+
const createdDirectories = [];
|
|
29
|
+
const lockPath = resolve(plan.root, '.kerf-ai-setup.lock');
|
|
30
|
+
try {
|
|
31
|
+
await mkdir(lockPath);
|
|
32
|
+
} catch {
|
|
33
|
+
throw new Error(
|
|
34
|
+
'Another Kerf setup is already applying in this workspace.',
|
|
35
|
+
);
|
|
36
|
+
}
|
|
37
|
+
const lockfiles = [
|
|
38
|
+
...new Set(
|
|
39
|
+
[plan.root, plan.packageRoot].flatMap((directory) => [
|
|
40
|
+
resolve(directory, 'package-lock.json'),
|
|
41
|
+
resolve(directory, 'pnpm-lock.yaml'),
|
|
42
|
+
resolve(directory, 'yarn.lock'),
|
|
43
|
+
]),
|
|
44
|
+
),
|
|
45
|
+
];
|
|
46
|
+
const lockfileSnapshots = new Map();
|
|
47
|
+
const generatedSnapshots = new Map();
|
|
48
|
+
let actualPackageRoot;
|
|
49
|
+
const isSymlink = async (path) => {
|
|
50
|
+
try {
|
|
51
|
+
return (await lstat(path)).isSymbolicLink();
|
|
52
|
+
} catch {
|
|
53
|
+
return false;
|
|
54
|
+
}
|
|
55
|
+
};
|
|
56
|
+
const validateGeneratedPath = async (
|
|
57
|
+
path,
|
|
58
|
+
{ allowLeafSymlink = false } = {},
|
|
59
|
+
) => {
|
|
60
|
+
if (!contained(plan.packageRoot, path))
|
|
61
|
+
throw new Error('A generated catalog path escapes the selected package.');
|
|
62
|
+
let ancestor = dirname(path);
|
|
63
|
+
while (!(await exists(ancestor))) ancestor = dirname(ancestor);
|
|
64
|
+
if (!contained(actualPackageRoot, await realpath(ancestor)))
|
|
65
|
+
throw new Error(
|
|
66
|
+
'A generated catalog path traverses a symlink outside the selected package.',
|
|
67
|
+
);
|
|
68
|
+
if (!allowLeafSymlink && (await isSymlink(path)))
|
|
69
|
+
throw new Error('Setup refuses a symlinked generated catalog output.');
|
|
70
|
+
};
|
|
71
|
+
try {
|
|
72
|
+
const actualRoot = await realpath(plan.root);
|
|
73
|
+
if (
|
|
74
|
+
!contained(plan.root, plan.packageRoot) ||
|
|
75
|
+
!contained(actualRoot, await realpath(plan.packageRoot))
|
|
76
|
+
)
|
|
77
|
+
throw new Error('Selected package escapes the setup workspace.');
|
|
78
|
+
actualPackageRoot = await realpath(plan.packageRoot);
|
|
79
|
+
for (const path of lockfiles) {
|
|
80
|
+
if (!contained(plan.root, path))
|
|
81
|
+
throw new Error('A lockfile path escapes the setup workspace.');
|
|
82
|
+
lockfileSnapshots.set(path, await readText(path));
|
|
83
|
+
}
|
|
84
|
+
for (const path of plan.generatedPaths ?? []) {
|
|
85
|
+
await validateGeneratedPath(path);
|
|
86
|
+
generatedSnapshots.set(path, await readText(path));
|
|
87
|
+
}
|
|
88
|
+
for (const action of plan.actions) {
|
|
89
|
+
const expectedPath = resolve(plan.root, action.path);
|
|
90
|
+
if (
|
|
91
|
+
action.absolutePath !== expectedPath ||
|
|
92
|
+
!contained(plan.root, action.absolutePath)
|
|
93
|
+
)
|
|
94
|
+
throw new Error(`Setup action escapes the workspace: ${action.path}.`);
|
|
95
|
+
let ancestor = dirname(action.absolutePath);
|
|
96
|
+
while (!(await exists(ancestor))) ancestor = dirname(ancestor);
|
|
97
|
+
if (!contained(actualRoot, await realpath(ancestor)))
|
|
98
|
+
throw new Error(
|
|
99
|
+
`Setup action traverses a symlink outside the workspace: ${action.path}.`,
|
|
100
|
+
);
|
|
101
|
+
if (
|
|
102
|
+
(await exists(action.absolutePath)) &&
|
|
103
|
+
(await lstat(action.absolutePath)).isSymbolicLink()
|
|
104
|
+
)
|
|
105
|
+
throw new Error(`Setup refuses to replace symlink ${action.path}.`);
|
|
106
|
+
if ((await readText(action.absolutePath)) !== action.before)
|
|
107
|
+
throw new Error(
|
|
108
|
+
`Setup plan is stale for ${action.path}; rerun the dry-run.`,
|
|
109
|
+
);
|
|
110
|
+
}
|
|
111
|
+
for (const action of plan.actions) {
|
|
112
|
+
let directory = dirname(action.absolutePath);
|
|
113
|
+
const missing = [];
|
|
114
|
+
while (!(await exists(directory))) {
|
|
115
|
+
missing.push(directory);
|
|
116
|
+
directory = dirname(directory);
|
|
117
|
+
}
|
|
118
|
+
await mkdir(dirname(action.absolutePath), { recursive: true });
|
|
119
|
+
createdDirectories.push(...missing);
|
|
120
|
+
if (!contained(actualRoot, await realpath(dirname(action.absolutePath))))
|
|
121
|
+
throw new Error(
|
|
122
|
+
`Setup action traverses a symlink outside the workspace: ${action.path}.`,
|
|
123
|
+
);
|
|
124
|
+
const temporary = `${action.absolutePath}.kerf-setup-${process.pid}-${randomUUID()}.tmp`;
|
|
125
|
+
temporaryPaths.push(temporary);
|
|
126
|
+
await writeFile(temporary, action.after);
|
|
127
|
+
if ((await readText(action.absolutePath)) !== action.before)
|
|
128
|
+
throw new Error(
|
|
129
|
+
`Setup plan became stale for ${action.path}; rerun the dry-run.`,
|
|
130
|
+
);
|
|
131
|
+
await rename(temporary, action.absolutePath);
|
|
132
|
+
written.push(action);
|
|
133
|
+
}
|
|
134
|
+
if (install) {
|
|
135
|
+
if (plan.packageManager === 'yarn' && !plan.packageManagerVariant)
|
|
136
|
+
throw new Error(
|
|
137
|
+
'Cannot install with Yarn until Classic or Berry is identified.',
|
|
138
|
+
);
|
|
139
|
+
const berry = plan.packageManagerVariant === 'berry';
|
|
140
|
+
const offlineArgs = offline
|
|
141
|
+
? berry
|
|
142
|
+
? ['--immutable-cache']
|
|
143
|
+
: ['--offline']
|
|
144
|
+
: [];
|
|
145
|
+
const workspace = plan.packageRoot !== plan.root;
|
|
146
|
+
let args;
|
|
147
|
+
let installCwd = plan.root;
|
|
148
|
+
if (!workspace || berry) args = ['install', ...offlineArgs];
|
|
149
|
+
else if (plan.packageManager === 'npm')
|
|
150
|
+
args = ['install', '--workspace', plan.packageName, ...offlineArgs];
|
|
151
|
+
else if (plan.packageManager === 'pnpm')
|
|
152
|
+
args = ['--filter', plan.packageName, 'install', ...offlineArgs];
|
|
153
|
+
else {
|
|
154
|
+
args = ['install', '--focus', ...offlineArgs];
|
|
155
|
+
installCwd = plan.packageRoot;
|
|
156
|
+
}
|
|
157
|
+
await runner(plan.packageManager, args, {
|
|
158
|
+
cwd: installCwd,
|
|
159
|
+
...(offline && berry
|
|
160
|
+
? { env: { ...process.env, YARN_ENABLE_NETWORK: '0' } }
|
|
161
|
+
: {}),
|
|
162
|
+
});
|
|
163
|
+
if (plan.mode === 'ui' && plan.generatedPaths?.length) {
|
|
164
|
+
for (const path of plan.generatedPaths ?? [])
|
|
165
|
+
await validateGeneratedPath(path);
|
|
166
|
+
await runner(plan.packageManager, ['run', 'catalog:generate'], {
|
|
167
|
+
cwd: plan.packageRoot,
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
} catch (error) {
|
|
172
|
+
for (const action of written.reverse()) {
|
|
173
|
+
if (action.before === null)
|
|
174
|
+
await rm(action.absolutePath, { force: true });
|
|
175
|
+
else await writeFile(action.absolutePath, action.before);
|
|
176
|
+
}
|
|
177
|
+
for (const [path, source] of lockfileSnapshots) {
|
|
178
|
+
if (source === null) await rm(path, { force: true });
|
|
179
|
+
else await writeFile(path, source);
|
|
180
|
+
}
|
|
181
|
+
for (const [path, source] of generatedSnapshots) {
|
|
182
|
+
await validateGeneratedPath(path, { allowLeafSymlink: true });
|
|
183
|
+
if (await isSymlink(path)) await rm(path, { force: true });
|
|
184
|
+
if (source === null) await rm(path, { force: true });
|
|
185
|
+
else await writeFile(path, source);
|
|
186
|
+
}
|
|
187
|
+
throw error;
|
|
188
|
+
} finally {
|
|
189
|
+
for (const path of temporaryPaths) await rm(path, { force: true });
|
|
190
|
+
for (const path of [...new Set(createdDirectories)].sort(
|
|
191
|
+
(left, right) => right.length - left.length,
|
|
192
|
+
)) {
|
|
193
|
+
try {
|
|
194
|
+
await rmdir(path);
|
|
195
|
+
} catch {
|
|
196
|
+
// Preserve non-empty directories, including directories used by other tools.
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
await rm(lockPath, { recursive: true, force: true });
|
|
200
|
+
}
|
|
201
|
+
return { changed: plan.actions.map(({ path }) => path) };
|
|
202
|
+
}
|
package/setup/cli.mjs
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import console from 'node:console';
|
|
4
|
+
import process from 'node:process';
|
|
5
|
+
|
|
6
|
+
import { applyKerfSetup, formatSetupPlan, planKerfSetup } from './index.mjs';
|
|
7
|
+
|
|
8
|
+
const args = process.argv.slice(2);
|
|
9
|
+
const command = args[0] && !args[0].startsWith('-') ? args.shift() : 'setup';
|
|
10
|
+
const take = (name) => {
|
|
11
|
+
const index = args.indexOf(name);
|
|
12
|
+
if (index < 0) return undefined;
|
|
13
|
+
const value = args[index + 1];
|
|
14
|
+
if (!value || value.startsWith('--'))
|
|
15
|
+
throw new Error(`${name} requires a value.`);
|
|
16
|
+
args.splice(index, 2);
|
|
17
|
+
return value;
|
|
18
|
+
};
|
|
19
|
+
const takeAll = (name) => {
|
|
20
|
+
const values = [];
|
|
21
|
+
while (args.includes(name)) values.push(take(name));
|
|
22
|
+
return values;
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
try {
|
|
26
|
+
if (args.includes('--help') || args.includes('-h')) {
|
|
27
|
+
console.log(`Usage: kerfjs setup [options]
|
|
28
|
+
|
|
29
|
+
Options:
|
|
30
|
+
--root <path> Workspace root (default: current directory)
|
|
31
|
+
--package <name> Select a workspace package by name or relative path
|
|
32
|
+
--guidance-source <path>
|
|
33
|
+
Use shared workspace guidance, e.g. AGENTS.md
|
|
34
|
+
--core | --ui Choose a mode when it cannot be detected
|
|
35
|
+
--resolve <id>=<choice>
|
|
36
|
+
Resolve a conflict with keep or kerf, or decline a
|
|
37
|
+
value proposal with skip (repeatable)
|
|
38
|
+
--write Apply the displayed plan (default is dry-run)
|
|
39
|
+
--yes Required with --write in non-interactive use
|
|
40
|
+
--offline Forbid registry access during dependency installation
|
|
41
|
+
--no-install Write configuration without running the package manager`);
|
|
42
|
+
process.exit(0);
|
|
43
|
+
}
|
|
44
|
+
if (command !== 'setup') throw new Error(`Unknown command ${command}.`);
|
|
45
|
+
const core = args.includes('--core');
|
|
46
|
+
const ui = args.includes('--ui');
|
|
47
|
+
if (core && ui) throw new Error('--core and --ui are mutually exclusive.');
|
|
48
|
+
const write = args.includes('--write');
|
|
49
|
+
const yes = args.includes('--yes');
|
|
50
|
+
const offline = args.includes('--offline');
|
|
51
|
+
const noInstall = args.includes('--no-install');
|
|
52
|
+
const root = take('--root');
|
|
53
|
+
const packageSelector = take('--package');
|
|
54
|
+
const guidanceSource = take('--guidance-source');
|
|
55
|
+
const resolutions = {};
|
|
56
|
+
for (const entry of takeAll('--resolve')) {
|
|
57
|
+
const index = entry.lastIndexOf('=');
|
|
58
|
+
if (index < 1) throw new Error('--resolve requires <id>=keep|kerf|skip.');
|
|
59
|
+
const id = entry.slice(0, index);
|
|
60
|
+
const choice = entry.slice(index + 1);
|
|
61
|
+
if (id in resolutions && resolutions[id] !== choice)
|
|
62
|
+
throw new Error(`Conflicting resolutions for ${id}.`);
|
|
63
|
+
resolutions[id] = choice;
|
|
64
|
+
}
|
|
65
|
+
const known = new Set([
|
|
66
|
+
'--core',
|
|
67
|
+
'--ui',
|
|
68
|
+
'--write',
|
|
69
|
+
'--yes',
|
|
70
|
+
'--offline',
|
|
71
|
+
'--no-install',
|
|
72
|
+
]);
|
|
73
|
+
const unknown = args.filter((arg) => !known.has(arg));
|
|
74
|
+
if (unknown.length)
|
|
75
|
+
throw new Error(`Unknown arguments: ${unknown.join(' ')}`);
|
|
76
|
+
const plan = await planKerfSetup({
|
|
77
|
+
root,
|
|
78
|
+
package: packageSelector,
|
|
79
|
+
mode: ui ? 'ui' : core ? 'core' : undefined,
|
|
80
|
+
resolutions,
|
|
81
|
+
guidanceSource,
|
|
82
|
+
});
|
|
83
|
+
console.log(formatSetupPlan(plan));
|
|
84
|
+
if (plan.conflicts.length) {
|
|
85
|
+
process.exitCode = 2;
|
|
86
|
+
} else if (write) {
|
|
87
|
+
if (!yes)
|
|
88
|
+
throw new Error('--write requires --yes after reviewing the plan.');
|
|
89
|
+
await applyKerfSetup(plan, { install: !noInstall, offline });
|
|
90
|
+
console.log(`Applied ${plan.actions.length} change(s).`);
|
|
91
|
+
}
|
|
92
|
+
} catch (error) {
|
|
93
|
+
console.error(`kerfjs setup: ${error.message}`);
|
|
94
|
+
process.exitCode = 2;
|
|
95
|
+
}
|