@cplieger/reactive 1.2.5 → 1.3.1

package/README.md

@@ -9,7 +9,19 @@
 
 > Signals + collections + DOM-reconciliation micro-framework for TypeScript
 
-A standalone reactive app-skeleton: fine-grained signals with automatic dependency tracking and synchronous batched effects, a typed per-key reactive store, a dynamic per-id signal registry (`SignalMap`), a reactive ordered keyed `Collection`, a two-tier list render binding (`bindList`), a CSP-safe element factory (`el`), keyed-list DOM reconciliation, structural tree-diffing, and a typed event bus (`createBus`). The store, `SignalMap`, and `Collection` are thin facades over the single signal engine — one reactive core, not several. The bus is the deliberate counterpart for discrete events (state lives in signals; events go on the bus). Zero dependencies beyond the DOM API.
+A standalone reactive app-skeleton:
+
+- fine-grained signals with automatic dependency tracking and synchronous batched effects
+- a typed per-key reactive store
+- a dynamic per-id signal registry (`SignalMap`)
+- a reactive ordered keyed `Collection`
+- a two-tier list render binding (`bindList`)
+- a CSP-safe element factory (`el`)
+- keyed-list DOM reconciliation
+- structural tree-diffing
+- a typed event bus (`createBus`)
+
+The store, `SignalMap`, and `Collection` are thin facades over a single signal engine: one reactive core, not several. Zero dependencies beyond the DOM API.
 
 Mirrors semantics from @preact/signals-core and solid-js reactivity.
 
@@ -69,86 +81,93 @@ isComputed(doubled); // true
 
 ### Signals
 
-- `signal<T>(initial, options?): Signal<T>` — reactive value with `.value` getter/setter and `.peek()`. Options: `{ equals?: false | ((prev, next) => boolean) }`
-- `computed<T>(fn, options?): ReadonlySignal<T>` — lazy cached derived signal (glitch-free, equality-deduped). Options: `{ equals?: false | ((prev, next) => boolean) }`
-- `effect(fn: () => Cleanup): () => void` — auto-tracking side-effect with cleanup support. `fn` must return `undefined` or a cleanup function.
-- `batch(fn)` — coalesce signal writes; effects flush synchronously at end of outermost batch
-- `flushSync()` — synchronously drain pending effects (no-op inside batch)
-- `untracked<T>(fn): T` — run fn without tracking signal reads (like Preact `untracked()` / Solid `untrack()`)
-- `on(deps, fn, options?): () => U` — explicit dependency declaration helper (like Solid `on()`). Returns `() => U`; with `{ defer: true }` the accessor returns `() => U | undefined` (the deferred first call yields `undefined`). A single accessor `() => T` types `value`/`prev` as `T`; an array of accessors types them as `unknown[]`. Pass into `effect()` or `computed()`.
-- `subscribe(signal, cb): () => void` — subscribe to a signal, calling cb immediately and on every change. The callback runs untracked: signals read inside it do not become dependencies of the subscription
-- `isSignal(value): boolean` — type guard for signals created by `signal()`
-- `isComputed(value): boolean` — type guard for computed signals
-- `setEffectErrorHandler(handler): EffectErrorHandler` — set global error handler for effects; returns the previous handler
+- `signal<T>(initial, options?): Signal<T>`: reactive value with `.value` getter/setter and `.peek()`. Options: `{ equals?: false | ((prev, next) => boolean) }`
+- `computed<T>(fn, options?): ReadonlySignal<T>`: lazy cached derived signal (glitch-free, equality-deduped). Options: `{ equals?: false | ((prev, next) => boolean) }`
+- `effect(fn: () => Cleanup): () => void`: auto-tracking side-effect with cleanup support. `fn` must return `undefined` or a cleanup function.
+- `batch(fn)`: coalesce signal writes; effects flush synchronously at end of outermost batch
+- `flushSync()`: synchronously drain pending effects (no-op inside batch)
+- `untracked<T>(fn): T`: run fn without tracking signal reads (like Preact `untracked()` / Solid `untrack()`)
+- `on(deps, fn, options?): () => U`: explicit dependency declaration helper (like Solid `on()`); pass into `effect()` or `computed()`. With `{ defer: true }` the accessor returns `() => U | undefined`: the deferred first call yields `undefined`.
+- `subscribe(signal, cb): () => void`: subscribe to a signal, calling cb immediately and on every change. The callback runs untracked: signals read inside it do not become dependencies of the subscription
+- `isSignal(value): boolean`: type guard for signals created by `signal()`
+- `isComputed(value): boolean`: type guard for computed signals
+- `setEffectErrorHandler(handler): EffectErrorHandler`: set global error handler for effects; returns the previous handler
 
 ### DOM building & reconciliation
 
-- `el(tag, attrs?, ...children)` — CSP-safe element factory (the build half; `reconcile`/`patch` are the commit half). `className` → class; `on*` → handler property + `trackHandler` (so `patch` reconciles handlers); boolean DOM props (`hidden`/`disabled`/`checked`/`selected`/…) and `value`/`colSpan`/`rowSpan`/`tabIndex`/`htmlFor` → properties; everything else (`data-*`, `aria-*`, `style`, `id`) → `setAttribute`. String children become text nodes (never parsed as HTML); null/undefined attrs and children are skipped.
-- `reconcile<T>(parent, items, spec)` — keyed-list DOM reconciliation with mount/update/onRemove lifecycle
-- `patch(parent, ...children)` — structural tree-diff, replacing a parent's children with reconciled new nodes. Element nodes are keyed by a `*-id` attribute (specific entity id — takes precedence) or, failing that, `data-col` (so reorders/re-patches reuse the matched node); duplicate-key siblings match in document order; unkeyed nodes match by position.
-- `reconcileChildren(parent, newChildren)` — low-level child reconciliation against existing DOM
-- `trackHandler(el, key)` — register an `on*` property for handler reconciliation during tree-diff
+- `el(tag, attrs?, ...children)`: CSP-safe element factory (the build half; `reconcile`/`patch` are the commit half). `className` → class; `on*` → handler property + `trackHandler` (so `patch` reconciles handlers); boolean DOM props (`hidden`/`disabled`/`checked`/`selected`/…) and `value`/`colSpan`/`rowSpan`/`tabIndex`/`htmlFor` → properties; everything else (`data-*`, `aria-*`, `style`, `id`) → `setAttribute`. String children become text nodes (never parsed as HTML); null/undefined attrs and children are skipped.
+- `reconcile<T>(parent, items, spec)`: keyed-list DOM reconciliation with mount/update/onRemove lifecycle
+- `patch(parent, ...children)`: structural tree-diff, replacing a parent's children with reconciled new nodes. Element nodes are keyed by a `*-id` attribute (a specific entity id, which takes precedence) or, failing that, `data-col`, so reorders and re-patches reuse the matched node; duplicate-key siblings match in document order; unkeyed nodes match by position. A reused element takes the new node's attributes, its tracked `on*` handlers, and the unreflected live properties the attribute pass cannot reach: `checked` (input), `selected` (option) and the `value` of an `input`/`textarea`. Those reflect to `defaultChecked`/`defaultSelected`/`defaultValue`, so without this a re-render could never turn a checkbox off or replace the text in a field. Syncing `value` overwrites what a user has typed and moves the caret to the end, which is correct only where a re-render cannot land mid-keystroke: a form re-rendered by a click is safe, one re-rendered by a timer or a server push is not, and that shape must drive the field from an effect instead (see [Unsupported by Design](#unsupported-by-design)).
+- `reconcileChildren(parent, newChildren)`: low-level child reconciliation against existing DOM
+- `trackHandler(el, key)`: register an `on*` property for handler reconciliation during tree-diff
 
 ### Store
 
-`createStore` and `SignalMap` are thin facades over the one signal engine — there is no second reactivity implementation. `createStore` lazily backs each key with a signal; `SignalMap` is a registry of signals keyed by a runtime string id.
+`createStore` and `SignalMap` are thin facades over the one signal engine. `createStore` lazily backs each key with a signal; `SignalMap` is a registry of signals keyed by a runtime string id.
 
-- `createStore<M>(): Store<M>` — typed, fixed-key reactive store with `get`, `set`, `subscribe`, `effect`, `computed`, and `batch`. `subscribe` notifies on change only (not immediately on subscribe), and its callback runs untracked. `computed(outputKey, fn)` is an EAGER effect that writes `outputKey` on every dependency change — not a lazy engine computed — so `fn` runs whether or not anyone reads the key, a throwing `fn` routes to the effect error handler instead of being cached and rethrown at the read site, and `set(outputKey, …)` still works between recomputes. A `computed` key whose fn reads its own output does not loop unbounded: a self-read that keeps yielding new values trips the engine's batch-iteration guard and surfaces `Error("Cycle detected")` through the effect error handler (effects isolate errors, so it is not rethrown to the caller), while a stable self-read settles via `Object.is` dedup.
-- `SignalMap<V>` — dynamic per-id signal registry: `get(id)`, `ensure(id, initial)`, `clear(id)`, `clearAll()`. For reactive state whose key set isn't known at the type level (per-message streaming text, per-row state, …); complements `createStore`'s fixed key set.
+- `createStore<M>(): Store<M>`: typed, fixed-key reactive store with `get`, `set`, `subscribe`, `effect`, `computed`, and `batch`. `subscribe` notifies on change only (not immediately on subscribe), and its callback runs untracked. `computed(outputKey, fn)` is an eager effect, not a lazy engine computed: it writes `outputKey` on every dependency change. So `fn` runs whether or not anyone reads the key; a throwing `fn` routes to the effect error handler instead of being cached and rethrown at the read site; `set(outputKey, …)` still works between recomputes. A `computed` key whose fn reads its own output does not loop unbounded: a self-read that keeps yielding new values surfaces `Error("Cycle detected")` through the effect error handler, while a stable self-read settles. The guard re-arms per write: a key that is still cyclic reports again on the next write to it rather than reporting once and going quiet, and effects merely queued alongside the cycle (a `subscribe` on the same key, say) stay reactive.
+- `SignalMap<V>`: dynamic per-id signal registry: `get(id)`, `ensure(id, initial)`, `clear(id)`, `clearAll()`. For reactive state whose key set isn't known at the type level (per-message streaming text, per-row state, …); complements `createStore`'s fixed key set.
 
 ### Collections
 
-A reactive ordered collection of keyed entities — the data half of the two-tier list pattern. A per-entity content update touches only that entity's subscribers; add/remove/reorder bumps the structure signal (`ids`). Built on `signal` + `SignalMap`.
+A reactive ordered collection of keyed entities: the data half of the two-tier list pattern. A per-entity content update touches only that entity's subscribers; add/remove/reorder bumps the structure signal (`ids`). Built on `signal` + `SignalMap`.
 
-- `createCollection<T>(keyOf: (item: T) => string): Collection<T>` — returns a collection with:
-  - `setAll(items)` — replace everything (same-order replacement does not bump `ids`; duplicate keys deduplicate — first occurrence keeps the position, last value wins)
-  - `upsert(item)` — add/replace one (appends new ids); `prepend(items)` — add to the front (scroll-up/load-older pagination)
+- `createCollection<T>(keyOf: (item: T) => string): Collection<T>`: returns a collection with:
+  - `setAll(items)`: replace everything (same-order replacement does not bump `ids`; duplicate keys deduplicate: first occurrence keeps the position, last value wins)
+  - `upsert(item)`: add/replace one (appends new ids); `prepend(items)`: add to the front (scroll-up/load-older pagination)
   - `update(id, next | updater)` / `remove(id)` / `clear()`
   - `get(id)` / `has(id)` (untracked), `signalFor(id)` (reactive per-entity), `size`
-  - `ids: ReadonlySignal<readonly string[]>` — structure tier (add/remove/reorder only)
-  - `items()` — ordered reactive snapshot (tracks order + every entity)
+  - `ids: ReadonlySignal<readonly string[]>`: structure tier (add/remove/reorder only)
+  - `items()`: ordered reactive snapshot (tracks order + every entity)
 
 ### List rendering
 
-- `bindList<T>(parent, source, spec): () => void` — two-tier render binding. `source` is a `ListSource<T>` = `{ ids, signalFor }`; a `Collection` satisfies it directly, and a filtered/sorted/paginated view is just `{ ids: computed(...), signalFor: collection.signalFor }` (pagination = a sliced view, not a separate primitive). One structural effect tracks `source.ids` and `reconcile`s the row list; each row owns a private effect tracking only its own entity signal, so a per-entity change repaints just that row with no structural reconcile. An id whose `signalFor` is `undefined` (an inconsistent source) is skipped rather than rendered. `spec`: `{ mount(item, id) => HTMLElement; update?(el, item, id); onRemove?(el, id) }` (`update` runs at mount and on every later change). Returns a dispose that tears down the structural effect and every row effect.
+- `bindList<T>(parent, source, spec): () => void`: two-tier render binding. `source` is a `ListSource<T>` = `{ ids, signalFor }`; a `Collection` satisfies it directly, and a filtered/sorted/paginated view is just `{ ids: computed(...), signalFor: collection.signalFor }` (pagination is a sliced view, not a separate primitive). A structural effect tracks `source.ids` and reconciles the row list; each row's own effect tracks only its entity signal, so a per-entity change repaints just that row with no structural reconcile. An id whose `signalFor` is `undefined` (an inconsistent source) is skipped rather than rendered. `spec`: `{ mount(item, id) => HTMLElement; update?(el, item, id); onRemove?(el, id) }` (`update` runs at mount and on every later change). Returns a dispose that tears down the structural effect and every row effect.
 
 ### Event bus
 
-State lives in signals; discrete events go on a bus. `createBus` is the typed event primitive (not reactive state — no retained value).
+State lives in signals; discrete events go on a bus. `createBus` is the typed event primitive (not reactive state; no retained value).
 
-- `createBus<EventMap>(options?): Bus<EventMap>` — `on`/`once`/`off`/`emit`/`clear`. Handlers are snapshot-cached (rebuilt only on mutation; a handler unsubscribed mid-emit still fires for that emit). Events whose payload type is `undefined` emit with no payload argument. A throwing handler is isolated via `options.onError` (default `console.error`).
+- `createBus<EventMap>(options?): Bus<EventMap>`: `on`/`once`/`off`/`emit`/`clear`. Handlers are snapshot-cached (rebuilt only on mutation; a handler unsubscribed mid-emit still fires for that emit). Events whose payload type is `undefined` emit with no payload argument. A throwing handler is isolated via `options.onError` (default `console.error`).
 
 ## Correctness guarantees
 
-- **Glitch-freedom**: Computed signals use equality dedup (`Object.is`) — downstream effects only fire when the computed value actually changes. Diamond dependency graphs are handled correctly.
+- **Glitch-freedom**: Computed signals use equality dedup (`Object.is`), so downstream effects only fire when the computed value actually changes. Diamond dependency graphs are handled correctly.
 - **Cycle detection**: Reading a computed that is currently being computed throws `Error("Cycle detected")`.
 - **Error caching**: If a computed's fn throws, the error is cached and rethrown on subsequent reads until dependencies change.
 - **Computed is read-only**: Setting `.value` on a computed throws `Error("Cannot set a computed signal")`.
 - **Synchronous batch**: `batch()` flushes effects synchronously at the end of the outermost batch (matching @preact/signals-core and solid-js).
 
-## Design Decisions — Unsupported by Design
+## Unsupported by Design
 
 The following features are intentionally NOT implemented:
 
-| Feature                                       | Reason                                                                                                             |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| **Effect ownership tree / `createRoot`**      | Consumers manage disposal explicitly. Adding ownership changes the mental model.                                   |
-| **Nested effect auto-disposal**               | Each effect is independent and returns its own dispose function. Compose with arrays or helper functions.          |
-| **Lazy activation / `onMount` lifecycle**     | Signals are always active. Resource management is the consumer's responsibility.                                   |
-| **`Signal.subtle.Watcher` / notify-on-dirty** | This library IS the framework layer. The Watcher pattern is for frameworks that sit on top of a signals primitive. |
-| **Introspection APIs**                        | Dev-tools concern. Not needed for production.                                                                      |
-| **Explicit computed disposal**                | Computed signals are GC'd when unreferenced. No explicit teardown needed.                                          |
-| **SSR / server-side isolation**               | Client-side library. Server usage should instantiate fresh signal graphs per request.                              |
-| **Async signals / resources**                 | Out of scope. Use effects + manual signal writes for async data loading.                                           |
-| **Transactions**                              | Framework-level concern. Not a signals primitive.                                                                  |
-| **Custom scheduler / `setScheduler()`**       | Batch is synchronous. No scheduler needed.                                                                         |
+| Feature                                           | Reason                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Effect ownership tree / `createRoot`**          | Consumers manage disposal explicitly. Adding ownership changes the mental model.                                                                                                                                                                                                                                               |
+| **Nested effect auto-disposal**                   | Each effect is independent and returns its own dispose function. Compose with arrays or helper functions.                                                                                                                                                                                                                      |
+| **Lazy activation / `onMount` lifecycle**         | Signals are always active. Resource management is the consumer's responsibility.                                                                                                                                                                                                                                               |
+| **`Signal.subtle.Watcher` / notify-on-dirty**     | This library IS the framework layer. The Watcher pattern is for frameworks that sit on top of a signals primitive.                                                                                                                                                                                                             |
+| **Introspection APIs**                            | Dev-tools concern. Not needed for production.                                                                                                                                                                                                                                                                                  |
+| **Explicit computed disposal**                    | Computed signals are GC'd when unreferenced. No explicit teardown needed.                                                                                                                                                                                                                                                      |
+| **SSR / server-side isolation**                   | Client-side library. Server usage should instantiate fresh signal graphs per request.                                                                                                                                                                                                                                          |
+| **Async signals / resources**                     | Out of scope. Use effects + manual signal writes for async data loading.                                                                                                                                                                                                                                                       |
+| **Transactions**                                  | Framework-level concern. Not a signals primitive.                                                                                                                                                                                                                                                                              |
+| **Custom scheduler / `setScheduler()`**           | Batch is synchronous. No scheduler needed.                                                                                                                                                                                                                                                                                     |
+| **Controlled form inputs**                        | `patch()` syncs `checked`, `selected` and `input`/`textarea` `value`, so the render owns them. It has no change routing or state ownership, so a surface re-rendered while a user types must own the field itself.                                                                                                             |
+| **Waking subscribers of a self-writing computed** | A computed that writes a signal it reads is re-read correctly (it is marked stale so the next read re-runs it), but its own subscribers are not woken, so an effect depending on it does not re-run until something else notifies it. Writing a source from a computed body is outside the intended shape; do it in an effect. |
+
+## Contributing
+
+Issues and PRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
+conventions and how to run the checks locally.
 
 ## Disclaimer
 
 This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.
 
-This project was built with AI-assisted tooling using [Claude Opus](https://www.anthropic.com/claude) and [Kiro](https://kiro.dev). The human maintainer defines architecture, supervises implementation, and makes all final decisions.
+This project was built with AI-assisted tooling using [Claude](https://claude.com), [GPT](https://openai.com), and [Kiro](https://kiro.dev). The human maintainer defines architecture, supervises implementation, and makes all final decisions.
 
 ## License
 
-GPL-3.0 — see [LICENSE](LICENSE).
+Apache-2.0. See [LICENSE](LICENSE).

package/jsr.json

@@ -1,6 +1,7 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.2.5",
+  "version": "1.3.1",
+  "license": "Apache-2.0",
   "exports": {
     ".": "./src/index.ts"
   },
@@ -11,8 +12,7 @@
       "src/**/*.ts"
     ],
     "exclude": [
-      "src/**/*.test.ts",
-      "src/**/__test-helpers__/**"
+      "src/**/*.test.ts"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.2.5",
+  "version": "1.3.1",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -13,21 +13,24 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@stryker-mutator/core": "9.6.1",
-    "@stryker-mutator/typescript-checker": "9.6.1",
-    "@stryker-mutator/vitest-runner": "9.6.1",
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/typescript-checker": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "4.1.10",
-    "eslint": "10.7.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "eslint": "10.8.1",
     "fast-check": "4.9.0",
-    "happy-dom": "20.10.6",
-    "prettier": "3.9.5",
+    "happy-dom": "20.11.6",
+    "prettier": "3.9.6",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.64.0",
-    "vitest": "4.1.10"
+    "typescript-eslint": "8.67.0",
+    "vitest": "4.1.11"
+  },
+  "overrides": {
+    "qs": "^6.15.2"
   },
   "description": "Signals + DOM-reconciliation reactive core for TypeScript (zero dependencies)",
-  "license": "GPL-3.0-or-later",
+  "license": "Apache-2.0",
   "types": "./src/index.ts",
   "publishConfig": {
     "access": "public"
@@ -36,11 +39,26 @@
     "type": "git",
     "url": "git+https://github.com/cplieger/reactive.git"
   },
+  "homepage": "https://github.com/cplieger/reactive",
+  "bugs": {
+    "url": "https://github.com/cplieger/reactive/issues"
+  },
+  "author": "cplieger <917744+cplieger@users.noreply.github.com>",
+  "keywords": [
+    "signals",
+    "reactivity",
+    "computed",
+    "effect",
+    "dom",
+    "reconciliation",
+    "store",
+    "event-bus",
+    "zero-dependency",
+    "typescript"
+  ],
   "files": [
     "src/",
-    "!src/**/*.test.ts",
-    "!src/**/__test-helpers__",
-    "!src/**/fc-strict-setup.ts",
-    "jsr.json"
+    "jsr.json",
+    "!src/**/*.test.ts"
   ]
 }

package/src/reconcile-tree.ts

@@ -57,6 +57,15 @@ export function reconcileChildren(parent: Node, newChildren: Node[]): void {
   }
 
   let oldIdx = 0;
+  // Old nodes already placed as the resolved child for an earlier index. The
+  // keyed path cannot hand one back — each key is consumed from its FIFO queue —
+  // but `oldChildren` is a SNAPSHOT taken before the loop, so a node still
+  // occupying its original slot there can be handed back by the positional scan
+  // after it has been placed. That happens when the caller re-renders a parent
+  // with its own current children reordered (drag-and-drop, sort): a match on an
+  // already-placed node either removes it as a tag mismatch or patches over it
+  // as a tag match, and either way a child the caller asked for is lost.
+  const placed = new Set<Node>();
   for (let i = 0; i < newChildren.length; i++) {
     const newChild = newChildren[i];
     if (newChild === undefined) {
@@ -82,7 +91,7 @@ export function reconcileChildren(parent: Node, newChildren: Node[]): void {
       // node would corrupt a node that key-matching also reuses in the same pass.
       while (oldIdx < oldChildren.length) {
         const oc = oldChildren[oldIdx];
-        if (oc !== undefined && !nodeKey(oc)) {
+        if (oc !== undefined && !nodeKey(oc) && !placed.has(oc)) {
           break;
         }
         oldIdx++;
@@ -110,6 +119,7 @@ export function reconcileChildren(parent: Node, newChildren: Node[]): void {
       // keyed node. The insert and patch branches already target index i.
       const ref = parent.childNodes.item(i);
       parent.insertBefore(newChild, ref);
+      placed.add(newChild);
       parent.removeChild(matched);
       continue;
     }
@@ -159,12 +169,18 @@ function nodeKey(node: Node): string {
   // precedence over the generic column key (`data-col`), so an element
   // carrying both keys by its entity identity — a generic first-in-attribute-
   // order `data-col` must not shadow it.
+  //
+  // The `data-col` scan is last-wins. The DOM keys attributes by (namespace,
+  // localName), so `setAttributeNS` with a foreign namespace and no prefix can
+  // put a second attribute whose `.name` is also "data-col" on the element;
+  // first-wins would key the node off the foreign one and refuse to match the
+  // author's own, destroying and recreating the node instead of reusing it.
   let colKey = "";
   for (const attr of (node as Element).attributes) {
     if (attr.name.endsWith("-id")) {
       return `${attr.name}=${attr.value}`;
     }
-    if (colKey === "" && attr.name === "data-col") {
+    if (attr.name === "data-col") {
       colKey = `${attr.name}=${attr.value}`;
     }
   }
@@ -182,8 +198,55 @@ function patchAttrs(oldEl: HTMLElement, newEl: HTMLElement): void {
       oldEl.removeAttribute(attr.name);
     }
   }
-  if (oldEl.hidden !== newEl.hidden) {
-    oldEl.hidden = newEl.hidden;
+
+  // Unreflected live state. `checked` (input), `selected` (option) and the
+  // `value` of an input/textarea are dirty-flag IDL properties: their content
+  // attributes are the DEFAULTS (`defaultChecked` / `defaultSelected` /
+  // `defaultValue`), so the two loops above equalise the default and never the
+  // live value. Without this, a keyed re-patch could not turn a checkbox off,
+  // move a selection, or replace the text in a field, ever.
+  //
+  // Syncing `value` overwrites whatever a user has typed, and it moves the caret
+  // to the end. That is correct only where a re-render cannot land mid-keystroke,
+  // which is a property of the CONSUMER, not of this function: a form re-rendered
+  // by a click (open, save, reset) is safe, one re-rendered by a timer or a server
+  // push is not. The README records the obligation; a consumer in the second shape
+  // must drive the field from an effect instead of re-rendering over it.
+  //
+  // Not covered here: `value` on an <option>/<progress>/<li> DOES reflect, so the
+  // loops above already carry it. A <select>'s value is derived from its options,
+  // which the OPTION branch below reconciles. `indeterminate` is unreflected too,
+  // but el() cannot set it, so it is outside patch()'s reach.
+  //
+  // canPatch has already established that both nodes share a nodeName, so one
+  // side decides the branch.
+  //
+  // Each `!==` guard is deliberate and no test here can pin it: assigning the
+  // same string to `.value` is a no-op through the DOM, but in a real browser it
+  // sets the dirty flag and moves the caret to the end, so an unconditional write
+  // would jump the caret on every re-render even when nothing changed. happy-dom
+  // exposes no caret, hence a permanently surviving `-> if (true)` mutant on each.
+  if (oldEl.nodeName === "INPUT") {
+    const oldInput = oldEl as HTMLInputElement;
+    const newInput = newEl as HTMLInputElement;
+    if (oldInput.checked !== newInput.checked) {
+      oldInput.checked = newInput.checked;
+    }
+    if (oldInput.value !== newInput.value) {
+      oldInput.value = newInput.value;
+    }
+  } else if (oldEl.nodeName === "TEXTAREA") {
+    const oldArea = oldEl as HTMLTextAreaElement;
+    const newArea = newEl as HTMLTextAreaElement;
+    if (oldArea.value !== newArea.value) {
+      oldArea.value = newArea.value;
+    }
+  } else if (oldEl.nodeName === "OPTION") {
+    const oldOption = oldEl as HTMLOptionElement;
+    const newOption = newEl as HTMLOptionElement;
+    if (oldOption.selected !== newOption.selected) {
+      oldOption.selected = newOption.selected;
+    }
   }
 
   // Reconcile on* event handler properties (not reflected as attributes).

package/src/signal.ts

@@ -1,18 +1,38 @@
 // Reactive signals: signal<T>, effect (with cleanup), batch, computed, untracked.
 // Preact-style doubly-linked source/target edges, pull-based glitch-free refresh,
-// global epoch + per-node version fast-skip, bitfield flags.
-// GPL-3.0-or-later.
+// per-node version fast-skip, bitfield flags.
+// Apache-2.0.
 //
 // Port provenance: graph/scheduler semantics verified against
 // @preact/signals-core@1.14.4 (drift audit 2026-07-17). Deliberate deltas
 // from upstream, pinned by tests: Object.is equality incl. NaN (upstream:
 // `!==`); custom `equals` / `equals: false` options (upstream has none);
 // isolate-and-continue effect error policy via setEffectErrorHandler
-// (upstream disposes-and-rethrows); cycle guard in endBatch (upstream also
-// guards in the signal setter). Upstream machinery NOT ported by design:
-// watched/unwatched hooks, createModel/action (1.13+), and the 1.14.x
-// batch-snapshot A->B->A revert optimization — the version-monotonicity bug
-// its first release carried (preactjs/signals#947) never existed here.
+// (upstream disposes-and-rethrows); the cycle guard lives in endBatch's drain
+// and un-notifies the chain it drops (upstream guards ONLY in the signal
+// setter, evaluated before the write, so it never drops a chain); and the drain
+// is re-entrant — `if (--batchDepth > 0) return` lets a write from an effect
+// body start a fresh drain, where upstream's `if (batchDepth > 1) return` plus
+// a post-drain `batchDepth--` keeps one drain per outermost batch.
+//
+// Upstream machinery NOT ported by design:
+//   - watched/unwatched hooks, createModel/action (1.13+);
+//   - the 1.14.x batch-snapshot A->B->A revert optimization — the
+//     version-monotonicity bug its first release carried
+//     (preactjs/signals#947) never existed here;
+//   - the `globalVersion` epoch fast-skip in refreshComputed. All three
+//     refresh call sites pre-check DIRTY, and because this port never
+//     unsubscribes a computed from its sources, notifyTargets always reaches
+//     every dependent computed — so DIRTY is a complete staleness signal.
+//     Upstream needs the epoch for computeds with no subscribers, which have
+//     no live edges. Do NOT try to revive it by deleting the DIRTY pre-checks:
+//     this refreshComputed has neither upstream's TRACKING shortcut nor its
+//     internal needsToRecompute gate, so an epoch miss recomputes
+//     unconditionally and six recompute-gating tests go red.
+//   - upstream's endBatch error capture and rethrow. Effect errors are
+//     isolated inside runEffect (see its contract below), so nothing can throw
+//     out of the drain and there was never anything to capture.
+//
 // Re-audit on upstream releases: diff src/index.ts against this file's
 // mechanisms and harvest engine-internal fixes (see CONTRIBUTING.md).
 
@@ -59,7 +79,6 @@ interface ComputedNode extends SourceNode, TargetNode {
   _isComputed: true;
   _fn: () => unknown;
   _equals: ((a: unknown, b: unknown) => boolean) | undefined;
-  _globalVersion: number;
 }
 
 interface EffectNode {
@@ -76,7 +95,6 @@ let evalContext: TargetNode | undefined;
 let batchDepth = 0;
 let batchedEffect: EffectNode | undefined;
 let batchIteration = 0;
-let globalVersion = 0;
 
 // Max effect-scheduling passes within one endBatch before assuming a cyclic
 // effect-write loop and bailing with "Cycle detected".
@@ -225,7 +243,22 @@ function notifyTargets(source: SourceNode): void {
     const target = node._target;
     if (target._isComputed) {
       // It's a ComputedNode
-      if (!(target._flags & (NOTIFIED | RUNNING))) {
+      if (target._flags & RUNNING) {
+        // A source written while this computed is mid-evaluation. Mark it stale
+        // so the next read re-runs it — every refresh call site pre-checks
+        // DIRTY, so without this the computed serves its pre-write value
+        // forever — but do NOT recurse: its own version has not moved yet, and
+        // recursing out of a RUNNING node is how a notify ping-pong is built.
+        //
+        // This repairs the PULL side only, deliberately. Two limits the next
+        // reader should not have to rediscover: (1) the computed's own
+        // subscribers are not woken here, so an effect that depends on it will
+        // not re-run until something else notifies it; (2) a computed that
+        // writes its own source unconditionally costs one extra recompute per
+        // read, and inside an effect it degrades into the documented
+        // MAX_BATCH_ITERATIONS "Cycle detected" path rather than hanging.
+        target._flags |= DIRTY;
+      } else if (!(target._flags & NOTIFIED)) {
         target._flags |= DIRTY | NOTIFIED;
         notifyTargets(target as unknown as SourceNode);
         target._flags &= ~NOTIFIED;
@@ -271,12 +304,6 @@ function refreshComputed(comp: ComputedNode): void {
     throw new Error("Cycle detected");
   }
 
-  // Fast-path: nothing changed globally since last check
-  if (comp._globalVersion === globalVersion && !(comp._flags & DIRTY)) {
-    return;
-  }
-  comp._globalVersion = globalVersion;
-
   const prevContext = evalContext;
   evalContext = comp;
   const prevFlags = comp._flags;
@@ -346,14 +373,31 @@ function endBatch(): void {
   if (--batchDepth > 0) {
     return;
   }
-  let error: unknown;
-  let hasError = false;
+  // The drain is re-entrant: a write, a batch() or a flushSync() from an effect
+  // body sees batchDepth back at 0 and starts a nested drain, and the cycle guard
+  // below counts on those nested passes — a two-effect ping-pong recurses one
+  // level per pass rather than looping here. So a nested drain must RESTORE the
+  // count it inherited instead of zeroing it: zeroing let any nested drain,
+  // including a flushSync() that found nothing to flush, wipe the passes the
+  // enclosing drain had accumulated and multiply the effective cap.
+  const enclosingIteration = batchIteration;
   while (batchedEffect !== undefined) {
     let eff: EffectNode | undefined = batchedEffect;
     batchedEffect = undefined;
     batchIteration++;
     if (batchIteration > MAX_BATCH_ITERATIONS) {
-      batchIteration = 0;
+      batchIteration = enclosingIteration;
+      // Un-notify the chain we are dropping: notifyTargets skips a NOTIFIED
+      // effect, so an effect left NOTIFIED here could never be queued again —
+      // bailing would silently deafen every effect in flight, including
+      // bystanders that merely share a signal with the cycling one.
+      let drop: EffectNode | undefined = eff;
+      while (drop !== undefined) {
+        const nextDrop: EffectNode | undefined = drop._nextBatchedEffect;
+        drop._nextBatchedEffect = undefined;
+        drop._flags &= ~NOTIFIED;
+        drop = nextDrop;
+      }
       throw new Error("Cycle detected");
     }
     while (eff !== undefined) {
@@ -361,22 +405,12 @@ function endBatch(): void {
       eff._nextBatchedEffect = undefined;
       eff._flags &= ~NOTIFIED;
       if (!(eff._flags & DISPOSED) && needsToRecompute(eff)) {
-        try {
-          runEffect(eff);
-        } catch (e) {
-          if (!hasError) {
-            error = e;
-            hasError = true;
-          }
-        }
+        runEffect(eff);
       }
       eff = next;
     }
   }
-  batchIteration = 0;
-  if (hasError) {
-    throw error;
-  }
+  batchIteration = enclosingIteration;
 }
 
 function runCleanup(eff: EffectNode): void {
@@ -395,6 +429,13 @@ function runCleanup(eff: EffectNode): void {
   }
 }
 
+// Contract: runEffect NEVER throws, and both callers depend on it.
+// Its body and its cleanup each route to safeCallHandler, which swallows even a
+// throwing handler; everything else here is a pointer walk over a well-formed
+// list. endBatch's drain and the effect() factory therefore call it bare. A
+// throw escaping this function would abandon the rest of the queued chain
+// mid-drain — the same shape of failure as the cycle bail's NOTIFIED leak. If
+// you add a statement here that can throw, wrap it HERE, not at the call sites.
 function runEffect(eff: EffectNode): void {
   // Run cleanup first (untracked)
   runCleanup(eff);
@@ -487,7 +528,6 @@ export function signal<T>(initial: T, options?: SignalOptions<T>): Signal<T> {
       }
       node._value = v;
       node._version++;
-      globalVersion++;
       startBatch();
       try {
         notifyTargets(node);
@@ -519,7 +559,6 @@ export function computed<T>(fn: () => T, options?: SignalOptions<T>): ReadonlySi
     _fn: fn,
     _equals:
       eq === false ? () => false : eq ? (a: unknown, b: unknown) => eq(a as T, b as T) : undefined,
-    _globalVersion: -1,
   };
 
   const c = {
@@ -577,11 +616,7 @@ export function effect(fn: () => Cleanup): () => void {
   };
 
   // Run immediately
-  try {
-    runEffect(eff);
-  } catch (e) {
-    safeCallHandler(e);
-  }
+  runEffect(eff);
 
   return () => {
     if (eff._flags & DISPOSED) {