sprae 12.3.9 → 12.4.1

package/readme.md

@@ -1,82 +1,63 @@
-# [∴](https://dy.github.io/sprae) spræ [![tests](https://github.com/dy/sprae/actions/workflows/node.js.yml/badge.svg)](https://github.com/dy/sprae/actions/workflows/node.js.yml) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/sprae?color=white)](https://bundlephobia.com/package/sprae) [![npm](https://img.shields.io/npm/v/sprae?color=white)](https://www.npmjs.com/package/sprae) [![ॐ](https://img.shields.io/badge/MIT-%E0%A5%90-white)](https://krishnized.github.io/license)
+# [∴](https://dy.github.io/sprae) spræ [![tests](https://github.com/dy/sprae/actions/workflows/node.js.yml/badge.svg)](https://github.com/dy/sprae/actions/workflows/node.js.yml) ![size](https://img.shields.io/badge/size-~6kb-white) [![npm](https://img.shields.io/npm/v/sprae?color=white)](https://www.npmjs.com/package/sprae)
 
-Ræctive sprinkles for HTML/JSX tree
+Ræctive sprinkles for HTML/JSX
 
 ## usage
 
 ```html
-<div id="counter" :scope="{count: 1}">
-  <p :text="`Clicked ${count} times`"></p>
-  <button :onclick="count++">Click me</button>
-</div>
-
-<script type="module">
-  import sprae from '//unpkg.com/sprae?module'
-
-  const state = sprae(document.getElementById('counter'), { count: 0 })
-  state.count++
-</script>
+<!-- Tabs -->
+<nav :scope="{tab: 'A'}">
+  <button :class="{active: tab=='A'}" :onclick="tab='A'">A</button>
+  <button :class="{active: tab=='B'}" :onclick="tab='B'">B</button>
+  <section :if="tab=='A'">Content A</section>
+  <section :if="tab=='B'">Content B</section>
+</nav>
+
+<!-- Filter -->
+<input :scope="{q: ''}" :value="q" :oninput="q=e.target.value" placeholder="Search...">
+<ul :each="item in items.filter(i => i.includes(q))">
+  <li :text="item"></li>
+</ul>
+
+<script type="module" src="//unpkg.com/sprae"></script>
 ```
 
 ## [docs](docs.md)
 
 <!-- [start](docs.md#start)  [store](docs.md#store)  [signals](docs.md#signals)  [evaluator](docs.md#evaluator)  [jsx](docs.md#jsx)  [build](docs.md#custom-build)  [hints](docs.md#hints) -->
 
-[`:text`](docs.md#text) [`:class`](docs.md#class) [`:style`](docs.md#style) [`:value`](docs.md#value) [`:<attr>`](docs.md#attr-) [`:if :else`](docs.md#if-else) [`:each`](docs.md#each) [`:scope`](docs.md#scope) [`:fx`](docs.md#fx) [`:ref`](docs.md#ref) [`:on<event>`](docs.md#onevent)
+[`:text`](docs.md#text) [`:class`](docs.md#class) [`:style`](docs.md#style) [`:value`](docs.md#value) [`:<attr>`](docs.md#attr-) [`:if :else`](docs.md#if-else) [`:each`](docs.md#each) [`:scope`](docs.md#scope) [`:fx`](docs.md#fx) [`:ref`](docs.md#ref) [`:hidden`](docs.md#hidden) [`:portal`](docs.md#portal) [`:on<event>`](docs.md#onevent)
 
 [`.debounce`](docs.md#debounce-ms) [`.throttle`](docs.md#throttle-ms) [`.delay`](docs.md#tick) [`.once`](docs.md#once)<br>
-[`.window`](docs.md#window-document-body-root-parent-outside-self) [`.document`](docs.md#window-document-body-root-parent-outside-self) [`.root`](docs.md#window-document-body-root-parent-outside-self) [`.body`](docs.md#window-document-body-root-parent-outside-self) [`.parent`](docs.md#window-document-body-root-parent-outside-self) [`.self`](docs.md#window-document-body-root-parent-outside-self) [`.outside`](docs.md#window-document-body-root-parent-outside-self)<br>
+[`.window`](docs.md#window-document-body-root-parent-away-self) [`.document`](docs.md#window-document-body-root-parent-away-self) [`.root`](docs.md#window-document-body-root-parent-away-self) [`.body`](docs.md#window-document-body-root-parent-away-self) [`.parent`](docs.md#window-document-body-root-parent-away-self) [`.self`](docs.md#window-document-body-root-parent-away-self) [`.away`](docs.md#window-document-body-root-parent-away-self)<br>
 [`.passive`](docs.md#passive-captureevents-only) [`.capture`](docs.md#passive-captureevents-only) [`.prevent`](docs.md#prevent-stop-immediateevents-only) [`.stop`](docs.md#prevent-stop-immediateevents-only) [`.<key>`](docs.md#key-filters)
 
 
-<!--
-## Micro
-
-Micro sprae version is 2.5kb bundle with essentials:
+## vs alpine
 
-* no multieffects `:a:b`
-* no modifiers `:a.x.y`
-* no sequences `:ona..onb`
-* no `:each`, `:if`, `:value`
--->
+|                  | [alpine](alpine.md) | sprae |
+|------------------|--------|-------|
+| _size_           | ~16kb | ~6kb |
+| _performance_    | ~2× slower | 1.00× |
+| _CSP_            | limited | full |
+| _reactivity_     | custom | [signals](docs.md#signals) |
+| _sandboxing_     | no | yes |
+| _typescript_     | partial | full |
+| _JSX/SSR_        | no | [yes](docs.md#jsx) |
+| _prefix_         | `x-`, `:`, `@` | `:` or [custom](docs.md#custom-build) |
 
-<!-- ## used by
+<sup>[benchmark](https://krausest.github.io/js-framework-benchmark/current.html). CSP via [jessie](docs.md#evaluator).</sup>
 
-[wavearea](), [maetr](), [settings-panel]() -->
 
-## why
+## used by
 
-Wire UI in markup for cleaner app logic.<br>
-<!--Perfect for SPA, PWA, static sites, prototypes, micro-frontends, lightweight UI.<br> -->
-<!--Inspired by [preact-signals](https://github.com/preactjs/signals), [alpine](https://github.com/alpinejs/alpine), [lodash](https://lodash.com) and <span title="petite-vue, lucia, nuejs, hmpl, unpoly, dagger">others</span>. <!--[petite-vue](https://github.com/vuejs/petite-vue) and others. -->
-<!-- [lucia](https://github.com/aidenybai/lucia), [nuejs](https://github.com/nuejs/nuejs), [hmpl](https://github.com/hmpl-language/hmpl), [unpoly](https://unpoly.com/up.link), [dagger](https://github.com/dagger8224/dagger.js) -->
-
-<!-- Made with 🫰 for better DX. -->
-<!-- – for those who tired of complexity. -->
+[watr](https://dy.github.io/watr/play), [wavearea](https://dy.github.io/wavearea)
+<!-- , [maetr](), [settings-panel]() -->
 
 
 <!--
-|                       | [AlpineJS](https://github.com/alpinejs/alpine)          | [Petite-Vue](https://github.com/vuejs/petite-vue)        | Sprae            |
-|-----------------------|-------------------|-------------------|------------------|
-| _Size_              | ~10KB             | ~6KB              | ~5KB             |
-| _Memory_            | 5.05             | 3.16              | 2.78             |
-| _Performance_       | 2.64             | 2.43              | 1.76             |
-| _CSP_               | Limited                | No                | Yes              |
-| _SSR_ | No | No | No |
-| _Evaluation_        | [`new AsyncFunction`](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/evaluator.js#L81) | [`new Function`](https://github.com/vuejs/petite-vue/blob/main/src/eval.ts#L20) | [`new Function`]() / [justin](https://github.com/dy/subscript)           |
-| _Reactivity_        | `Alpine.store`    | _@vue/reactivity_   | _signals_ |
-| _Sandboxing_        | No                | No                | Yes              |
-| _Directives_ | `:`, `x-`, `{}` | `:`, `v-`, `@`, `{}` | `:` |
-| _Magic_               | `$data` | `$app`   | - |
-| _Fragments_ | Yes | No | Yes |
-| _Plugins_ | Yes | No | Yes |
-| _Modifiers_ | Yes | No | Yes |
-
-_Nested directives_ Yes
-_Inline directives_ Yes
--->
+[lucia](https://github.com/aidenybai/lucia), [nuejs](https://github.com/nuejs/nuejs), [hmpl](https://github.com/hmpl-language/hmpl), [unpoly](https://unpoly.com/up.link), [dagger](https://github.com/dagger8224/dagger.js), [petite-vue](https://github.com/vuejs/petite-vue)
 
-<!--
 ### Drops
 
 * ToDo MVC: [demo](https://dy.github.io/sprae/examples/todomvc), [code](https://github.com/dy/sprae/blob/main/examples/todomvc.html)
@@ -85,3 +66,7 @@ _Inline directives_ Yes
 * Carousel: [demo](https://rwdevelopment.github.io/sprae_js_carousel/), [code](https://github.com/RWDevelopment/sprae_js_carousel)
 * Tabs: [demo](https://rwdevelopment.github.io/sprae_js_tabs/), [code](https://github.com/RWDevelopment/sprae_js_tabs?tab=readme-ov-file)-->
 <!-- * Prostogreen [demo](https://web-being.org/prostogreen/), [code](https://github.com/web-being/prostogreen/) -->
+
+<p align='center'>
+<a href="https://krishnized.github.io/license">ॐ</a>
+</p>

package/signal.js

@@ -1,8 +1,22 @@
-// preact-signals minimal implementation
-let current, depth = 0, batched;
+/**
+ * @fileoverview Minimal signals implementation (preact-signals compatible)
+ * @module sprae/signal
+ */
 
-// default signals impl
+/** @type {import('./core.js').EffectFn | null} */
+let current
 
+let depth = 0
+
+/** @type {Set<import('./core.js').EffectFn> | null} */
+let batched;
+
+/**
+ * Creates a reactive signal.
+ * @template T
+ * @param {T} v - Initial value
+ * @returns {import('./core.js').Signal<T>}
+ */
 export const signal = (v, _s, _obs = new Set, _v = () => _s.value) => (
   _s = {
     get value() {
@@ -19,6 +33,11 @@ export const signal = (v, _s, _obs = new Set, _v = () => _s.value) => (
   }
 )
 
+/**
+ * Creates a reactive effect that re-runs when dependencies change.
+ * @param {() => void | (() => void)} fn - Effect function, may return cleanup
+ * @returns {() => void} Dispose function
+ */
 export const effect = (fn, _teardown, _fx, _deps) => (
   _fx = (prev) => {
     let tmp = _teardown;
@@ -35,6 +54,12 @@ export const effect = (fn, _teardown, _fx, _deps) => (
   (dep) => { _teardown?.call?.(); for (dep of _deps) dep.delete(_fx); _deps.clear() }
 )
 
+/**
+ * Creates a computed signal derived from other signals.
+ * @template T
+ * @param {() => T} fn - Computation function
+ * @returns {import('./core.js').Signal<T>}
+ */
 export const computed = (fn, _s = signal(), _c, _e, _v = () => _c.value) => (
   _c = {
     get value() {
@@ -46,10 +71,23 @@ export const computed = (fn, _s = signal(), _c, _e, _v = () => _c.value) => (
   }
 )
 
+/**
+ * Batches multiple signal updates into a single notification.
+ * @template T
+ * @param {() => T} fn - Function containing updates
+ * @returns {T}
+ */
 export const batch = (fn, _first = !batched, _list) => {
   batched ??= new Set;
   try { fn(); }
   finally { if (_first) { [batched, _list] = [null, batched]; for (const fx of _list) fx(); } }
 }
 
+/**
+ * Runs a function without tracking dependencies.
+ * @template T
+ * @param {() => T} fn - Function to run untracked
+ * @returns {T}
+ */
 export const untracked = (fn, _prev, _v) => (_prev = current, current = null, _v = fn(), current = _prev, _v)
+

package/sprae.js

@@ -1,3 +1,8 @@
+/**
+ * @fileoverview Sprae - lightweight reactive HTML templating library
+ * @module sprae
+ */
+
 import store from "./store.js";
 import { batch, computed, effect, signal, untracked } from './core.js';
 import * as signals from './signal.js';
@@ -17,6 +22,9 @@ import _default from "./directive/_.js";
 import _spread from "./directive/spread.js";
 import _event from "./directive/event.js";
 import _seq from "./directive/sequence.js";
+import _html from "./directive/html.js";
+import _portal from "./directive/portal.js";
+import _hidden from "./directive/hidden.js";
 
 
 Object.assign(directive, {
@@ -24,6 +32,7 @@ Object.assign(directive, {
   '': _spread,
   class: _class,
   text: _text,
+  html: _html,
   style: _style,
   fx: _fx,
   value: _value,
@@ -31,14 +40,20 @@ Object.assign(directive, {
   scope: _scope,
   if: _if,
   else: _else,
-  each: _each
+  each: _each,
+  portal: _portal,
+  hidden: _hidden
 })
 
 
 /**
- * Directive initializer (with modifiers support)
- * @type {(el: HTMLElement, name:string, value:string, state:Object) => Function}
- * */
+ * Directive initializer with modifiers support.
+ * @param {Element} target - Target element
+ * @param {string} name - Directive name with modifiers (e.g., 'onclick.throttle-500')
+ * @param {string} expr - Expression string
+ * @param {Object} state - Reactive state object
+ * @returns {() => (() => void) | void} Initializer function that returns a disposer
+ */
 const dir = (target, name, expr, state) => {
   let [dirName, ...mods] = name.split('.'), create = directive[dirName] || directive._
 
@@ -64,37 +79,68 @@ const dir = (target, name, expr, state) => {
   }
 }
 
-Object.assign(modifier, {
-  // timing (lodash-like)
-  // FIXME: add immediate param
-  debounce: (fn, _how) => debounce(fn, (_how ||= 0, !_how ? undefined : _how === 'raf' ? requestAnimationFrame : (fn) => setTimeout(fn, _how))),
-  throttle: (fn, _how) => throttle(fn, (_how ||= 0, !_how ? undefined : _how === 'raf' ? requestAnimationFrame : (fn) => setTimeout(fn, _how))),
-  delay: (fn, ms) => !ms ? (e) => (queueMicrotask(() => fn(e))) : (e) => setTimeout(() => fn(e), ms),
+// Parses time string to ms: 100, 100ms, 1s, 1m
+const parseTime = (t) => !t ? 0 : typeof t === 'number' ? t :
+  (([, n, u] = t.match(/^(\d+)(ms|s|m)?$/) || []) => (n = +n, u === 's' ? n * 1000 : u === 'm' ? n * 60000 : n))()
 
-  tick: (fn) => (console.warn('Deprecated'), (e) => (queueMicrotask(() => fn(e)))),
-  raf: (fn) => (console.warn('Deprecated'), (e) => requestAnimationFrame(() => fn(e))),
+// Creates scheduler from time/keyword (idle, raf, tick, or ms)
+const scheduler = (t) =>
+  t === 'idle' ? requestIdleCallback :
+  t === 'raf' ? requestAnimationFrame :
+  !t || t === 'tick' ? queueMicrotask :
+  (fn) => setTimeout(fn, parseTime(t))
 
+// Built-in modifiers for timing, targeting, and event handling
+Object.assign(modifier, {
+  /**
+   * Delays callback by interval since last call (trailing edge).
+   * Supports: tick (default), raf, idle, N, Nms, Ns, Nm. Add -immediate for leading edge.
+   * Examples: .debounce, .debounce-100, .debounce-1s, .debounce-raf, .debounce-idle, .debounce-100-immediate
+   */
+  debounce: (fn, a, b) => debounce(fn, scheduler(a === 'immediate' ? b : a), a === 'immediate' || b === 'immediate'),
+  /**
+   * Limits callback rate to interval (leading + trailing edges).
+   * Supports: tick (default), raf, idle, N, Nms, Ns, Nm.
+   * Examples: .throttle, .throttle-100, .throttle-1s, .throttle-raf, .throttle-idle
+   */
+  throttle: (fn, a) => throttle(fn, scheduler(a)),
+  /** Runs callback after delay. Supports: tick (default), raf, idle, N, Nms, Ns, Nm. */
+  delay: (fn, a) => ((sched = scheduler(a)) => (e) => sched(() => fn(e)))(),
+
+  /** Calls handler only once. */
   once: (fn, _done, _fn) => (_fn = (e) => !_done && (_done = 1, fn(e)), _fn.once = true, _fn),
 
-  // target
+  /** Attaches event listener to window. */
   window: fn => (fn.target = fn.target.ownerDocument.defaultView, fn),
+  /** Attaches event listener to document. */
   document: fn => (fn.target = fn.target.ownerDocument, fn),
+  /** Attaches event listener to document root element (<html>). */
   root: fn => (fn.target = fn.target.ownerDocument.documentElement, fn),
+  /** Attaches event listener to body. */
   body: fn => (fn.target = fn.target.ownerDocument.body, fn),
+  /** Attaches event listener to parent element. */
   parent: fn => (fn.target = fn.target.parentNode, fn),
+  /** Triggers only when event target is the element itself. */
   self: (fn) => (e) => (e.target === fn.target && fn(e)),
+  /** Triggers when click is outside the element. */
   away: (fn) => Object.assign((e) => (!fn.target.contains(e.target) && e.target.isConnected && fn(e)), {target: fn.target.ownerDocument}),
 
-  // events
+  /** Calls preventDefault() before handler. */
   prevent: (fn) => (e) => (e?.preventDefault(), fn(e)),
+  /** Calls stopPropagation() or stopImmediatePropagation() (with -immediate). */
   stop: (fn, _how) => (e) => (_how?.[0] === 'i' ? e?.stopImmediatePropagation() : e?.stopPropagation(), fn(e)),
-  immediate: (fn) => (console.warn('Deprecated'), (e) => (e?.stopImmediatePropagation(), fn(e))),
+  /** Sets passive option for event listener. */
   passive: fn => (fn.passive = true, fn),
+  /** Sets capture option for event listener. */
   capture: fn => (fn.capture = true, fn),
 })
+/** Alias for .away modifier */
 modifier.outside = modifier.away
 
-// key testers
+/**
+ * Key testers for keyboard event modifiers.
+ * @type {Record<string, (e: KeyboardEvent) => boolean>}
+ */
 const keys = {
   ctrl: e => e.ctrlKey || e.key === "Control" || e.key === "Ctrl",
   shift: e => e.shiftKey || e.key === "Shift",
@@ -112,12 +158,37 @@ const keys = {
   char: e => /^\S$/.test(e.key),
 };
 
-// augment modifiers with key testers
-for (let k in keys) modifier[k] = (fn, a, b) => (e) => keys[k](e) && (!a || keys[a]?.(e)) && (!b || keys[b]?.(e)) && fn(e)
+// match key by name, or by e.key (case-insensitive), or by keyCode (digits)
+const keyMatch = (k, e) => keys[k]?.(e) || e.key.toLowerCase() === k || e.keyCode == k
+
+// Augment modifiers with key testers (e.g., .enter, .ctrl, .ctrl-a, .ctrl-65)
+for (let k in keys) modifier[k] = (fn, a, b) => (e) => keys[k](e) && (!a || keyMatch(a, e)) && (!b || keyMatch(b, e)) && fn(e)
 
 
+// Checks for first-level semicolons (statement vs expression)
+const hasSemi = s => {
+  for (let d=0,i=0;i<s.length;i++) {
+    if (s[i]=='{') d++
+    else if (s[i]=='}') d--
+    else if (s[i]==';' && !d) return true
+  }
+  return false
+}
+
+// Configure sprae with default compiler and signals
 use({
-  compile: expr => sprae.constructor(`with(arguments[0]){${expr}}`),
+
+// Default compiler wraps expression for new Function
+  compile: expr => {
+    // if, const, let - no return
+    if (/^(if|let|const)\b/.test(expr));
+    // first-level semicolons - no return
+    else if (hasSemi(expr));
+    else expr = `return ${expr}`
+    // async expression
+    if (/\bawait\s/.test(expr)) expr = `return (async()=>{${expr}})()`
+    return sprae.constructor(`with(arguments[0]){${expr}}`)
+  },
   dir: (el, name, expr, state) => {
     // sequences shortcut
     if (name.includes('..')) return () => _seq(el, state, expr, name)[_dispose]
@@ -130,15 +201,32 @@ use({
 })
 
 
-// expose for runtime config
+// Expose for runtime configuration
 sprae.use = use
 sprae.store = store
 sprae.directive = directive
 sprae.modifier = modifier
 
+/**
+ * Disposes a spraed element, cleaning up all effects and state.
+ * @param {Element} el - Element to dispose
+ */
+sprae.dispose = (el) => el[_dispose]?.()
+
 
 /**
- * Lifecycle hanger: spraes automatically any new nodes
+ * Auto-initializes sprae on dynamically added elements.
+ * Uses MutationObserver to detect new DOM nodes and apply directives.
+ *
+ * @param {Element} [root=document.body] - Root element to observe
+ * @param {Object} [values] - Initial state values
+ * @returns {Object} The reactive state object
+ *
+ * @example
+ * ```js
+ * // Auto-init on page load
+ * sprae.start(document.body, { count: 0 })
+ * ```
  */
 const start = sprae.start = (root = document.body, values) => {
   const state = store(values)
@@ -150,10 +238,9 @@ const start = sprae.start = (root = document.body, values) => {
         if (el.nodeType === 1 && el[_state] === undefined && root.contains(el)) {
           // even if element has no spraeable attrs, some of its children can have
           root[_add](el)
-          // sprae(el, state, root);
         }
       }
-      // for (const el of m.removedNodes) el[Symbol.dispose]?.()
+      for (const el of m.removedNodes) el.nodeType === 1 && el[_dispose]?.()
     }
   });
   mo.observe(root, { childList: true, subtree: true });
@@ -161,8 +248,10 @@ const start = sprae.start = (root = document.body, values) => {
 }
 
 
-// version placeholder for bundler
+/** Package version (injected by bundler) */
 sprae.version = "[VI]{{inject}}[/VI]"
 
+const dispose = sprae.dispose
+
 export default sprae
-export { sprae, store, signal, effect, computed, batch, untracked, start, use }
+export { sprae, store, signal, effect, computed, batch, untracked, start, use, throttle, debounce, dispose }

package/store.js

@@ -1,19 +1,43 @@
-// signals-based proxy
+/**
+ * @fileoverview Signals-powered reactive proxy store
+ * @module sprae/store
+ */
+
 import { signal, computed, batch, untracked } from './core.js'
 
+/** Symbol for accessing the internal signals map */
+export const _signals = Symbol('signals')
+
+/** Symbol for the change signal that tracks object keys or array length */
+export const _change = Symbol('change')
 
-// _signals allows both storing signals and checking instance, which would be difficult with WeakMap
-export const _signals = Symbol('signals'),
-  // _change is a signal that tracks changes to the object keys or array length
-  _change = Symbol('change'),
-  // _set is stashed setter for computed values
-  _set = Symbol('set')
+/** Symbol for stashed setter on computed values */
+export const _set = Symbol('set')
 
 // a hack to simulate sandbox for `with` in evaluator
 let sandbox = true
 
-// object store is not lazy
-// parent defines parent scope or sandbox
+/**
+ * Reactive store with signals backing.
+ * @template T
+ * @typedef {T & { [_signals]: Record<string | symbol, import('./core.js').Signal<any>> }} ReactiveStore
+ */
+
+/**
+ * Creates a reactive proxy store from an object or array.
+ * Properties become signals for fine-grained reactivity.
+ * Supports nested objects, arrays, computed getters, and methods.
+ *
+ * @template {Object} T
+ * @param {T} values - Initial values object
+ * @param {Object} [parent] - Parent scope for inheritance
+ * @returns {ReactiveStore<T>} Reactive proxy store
+ *
+ * @example
+ * const state = store({ count: 0, get doubled() { return this.count * 2 } })
+ * state.count = 5  // triggers updates
+ * state.doubled    // 10 (computed)
+ */
 export const store = (values, parent) => {
   if (!values) return values
 
@@ -41,7 +65,7 @@ export const store = (values, parent) => {
       return parent ? parent[k] : (typeof globalThis[k] === 'function' && !globalThis[k].prototype ? globalThis[k].bind(globalThis) : globalThis[k])
     },
 
-    set: (_, k, v, _s) => {
+    set: (_, k, v) => {
       // console.group('SET', k, v)
       if (k in signals) return set(signals, k, v), 1
 
@@ -99,7 +123,13 @@ export const store = (values, parent) => {
   return state
 }
 
-// array store - signals are lazy since arrays can be very large & expensive
+/**
+ * Creates a reactive array store with lazy signal initialization.
+ * Arrays can be large, so signals are created on-demand.
+ * @param {any[]} values - Initial array values
+ * @param {Object} [parent=globalThis] - Parent scope
+ * @returns {ReactiveStore<any[]>} Reactive array proxy
+ */
 const list = (values, parent = globalThis) => {
 
   // gotta fill with null since proto methods like .reduce may fail
@@ -168,10 +198,21 @@ const list = (values, parent = globalThis) => {
   return state
 }
 
-// create signal value, skip untracked
+/**
+ * Creates a signal for a property value.
+ * Skips wrapping for untracked props (underscore prefix) and existing signals.
+ * @param {Object} signals - Signals storage object
+ * @param {string} k - Property key
+ * @param {any} v - Property value
+ */
 const create = (signals, k, v) => (signals[k] = (k[0] == '_' || v?.peek) ? v : signal(store(v)))
 
-// set/update signal value
+/**
+ * Updates a signal value, handling arrays specially for efficient patching.
+ * @param {Object} signals - Signals storage object
+ * @param {string} k - Property key
+ * @param {any} v - New value
+ */
 const set = (signals, k, v, _s, _v) => {
   // skip unchanged (although can be handled by last condition - we skip a few checks this way)
   return k[0] === '_' ? (signals[k] = v) :