@cplieger/reactive 1.3.1 → 2.1.0

package/README.md

@@ -25,6 +25,37 @@ The store, `SignalMap`, and `Collection` are thin facades over a single signal e
 
 Mirrors semantics from @preact/signals-core and solid-js reactivity.
 
+## Flush model
+
+One phase, and this is the whole of it.
+
+**A write flushes.** When `sig.value = x` returns, every effect that depends on
+`sig` has already re-run. The setter notifies and drains before it returns, so
+there is no pending-effect state a caller can observe and no queue to drain. Read
+the DOM on the next statement and you are reading what the effects wrote. Same
+contract as [@preact/signals-core](https://github.com/preactjs/signals/blob/main/packages/core/README.md),
+this engine's baseline.
+
+**`batch(fn)` is the only deferral.** Inside a batch, writes coalesce and effects
+are held; they run once, synchronously, when the _outermost_ batch returns. A
+nested batch defers to its outermost, and a throwing body still flushes.
+
+**Deferral beyond that is yours.** To get effects on a later task, write on a
+later task:
+
+```typescript
+queueMicrotask(() => {
+  count.value = next; // effects run inside this microtask
+});
+```
+
+There is deliberately **no flush barrier** — no `flushSync()`, no `nextTick()`.
+A barrier is the API a _deferred_ model owes its callers (Vue's `nextTick`,
+React's `flushSync`); an eager model never holds work, so it has nothing to
+report on and nothing to force. `flushSync()` existed through v1.x, could never
+find work pending, and refused to act when work was pending inside a batch; it
+was removed in v2.0.0. If you were calling it, delete the call — it was a no-op.
+
 ## Install
 
 ```sh
@@ -84,10 +115,10 @@ isComputed(doubled); // true
 - `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)
+- `batch(fn)`: coalesce signal writes; effects flush synchronously at end of outermost batch. The only deferral — see [Flush model](#flush-model)
 - `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`.
+- `touch(...signals): void`: read signals for their tracking effect alone, discarding the values — the complement of `peek()` (`peek` reads without subscribing, `touch` subscribes without keeping). `undefined` entries are skipped, so a per-key lookup that may miss (`Collection.signalFor(id)`, `SignalMap.get(id)`) can be passed straight in. Use it where a scope must re-run on a signal whose value it has no use for: most often a two-tier read, where a computed or effect takes per-entity values through `signalFor` and so must depend on the structure signal (`Collection.ids`) separately to re-derive when the id set changes. Unlike `on()` it ADDS a dependency and leaves every other read in the scope tracked
+- `on(deps, fn, options?): () => U`: explicit dependency declaration helper (like Solid `on()`); pass into `effect()` or `computed()`. Its body runs untracked, so the declared deps are the scope's ONLY dependencies — reach for `touch()` instead when the rest of the scope should stay tracked. Passed to `effect()`, the body owes an explicit `return undefined` (or a cleanup function) like any effect callback, since a body with no return statement infers `() => void`, which the `Cleanup` contract rejects. 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
@@ -97,15 +128,14 @@ isComputed(doubled); // true
 
 - `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
+- `patch(parent, ...children)`: structural tree-diff, replacing a parent's children with reconciled new nodes. Correspondence between a child the parent has and a child you asked for is decided strongest-first: the same **node** (you handed back a node that is already a child of `parent` — it is placed at the index you passed it at, unmodified, so handing a parent its own children reordered is supported), then the same **key** (a `*-id` attribute, a specific entity id which takes precedence, or failing that `data-col`; duplicate-key siblings match in document order), then the same **position**. Any node that is not already a child of `parent` is a TEMPLATE: its shape may be copied into a reused child and the node itself never inserted. 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)).
 - `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. `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, 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.
+- `createStore<M>(): Store<M>`: typed, fixed-key reactive store with `get`, `set`, `subscribe`, and `computed`. A member exists here only where it does something the engine's namesake does not, so `effect` and `batch` are **not** on the store (removed in v2.0.0) — import them from the package root; `store.batch(…)` read as "batch this store's writes" while batching the whole graph. `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
@@ -136,7 +166,7 @@ State lives in signals; discrete events go on a bus. `createBus` is the typed ev
 - **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).
+- **Synchronous batch**: `batch()` flushes effects synchronously at the end of the outermost batch (matching @preact/signals-core and solid-js). It is the only deferral the library has; a bare write flushes before it returns. See [Flush model](#flush-model).
 
 ## Unsupported by Design
 
@@ -153,7 +183,8 @@ The following features are intentionally NOT implemented:
 | **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.                                                                                                                                                                                                                                                                                     |
+| **Custom scheduler / `setScheduler()`**           | Batch is synchronous and a write flushes before it returns, so there is no queue to schedule. Deferral is the caller's: write on a later task. See [Flush model](#flush-model).                                                                                                                                                |
+| **A flush barrier (`flushSync`, `nextTick`)**     | A barrier is what a deferred model owes its callers; this model never holds work, so a barrier has nothing to report on. `flushSync()` shipped through v1.x and was a no-op from every position a caller could occupy; removed in v2.0.0.                                                                                      |
 | **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. |
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.3.1",
+  "version": "2.1.0",
   "license": "Apache-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.3.1",
+  "version": "2.1.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -17,13 +17,15 @@
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@typescript/native": "npm:typescript@7.0.2",
+    "@vitest/browser": "4.1.11",
+    "@vitest/browser-playwright": "4.1.11",
     "@vitest/coverage-v8": "4.1.11",
-    "eslint": "10.8.1",
+    "eslint": "10.9.1",
     "fast-check": "4.9.0",
-    "happy-dom": "20.11.6",
+    "playwright": "1.62.1",
     "prettier": "3.9.6",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.67.0",
+    "typescript-eslint": "8.69.0",
     "vitest": "4.1.11"
   },
   "overrides": {

package/src/index.ts

@@ -2,10 +2,10 @@ export {
   signal,
   effect,
   batch,
-  flushSync,
   setEffectErrorHandler,
   computed,
   untracked,
+  touch,
   subscribe,
   isSignal,
   isComputed,
@@ -31,4 +31,4 @@ export { el } from "./el.js";
 export type { AttrValue } from "./el.js";
 export { reconcile, KEY_ATTR } from "./reconcile.js";
 export type { ReconcileSpec } from "./reconcile.js";
-export { patch, reconcileChildren, trackHandler } from "./reconcile-tree.js";
+export { patch, trackHandler } from "./reconcile-tree.js";

package/src/reconcile-tree.ts

@@ -1,8 +1,19 @@
 // Structural tree-diff: reconcile a parent's children against new nodes.
 // Handles attribute patching, text node updates, element reordering,
-// and recursive child reconciliation. Keying: a specific `*-id` attribute
-// wins over the generic `data-col`; duplicate-key siblings match in
-// document order.
+// and recursive child reconciliation.
+//
+// Correspondence between a child the parent HAS and a child the caller ASKED
+// for is decided in one order, strongest notion of "the same child" first:
+//
+//   1. the same NODE   — the caller handed back a node already in this parent
+//   2. the same KEY    — a specific `*-id` attribute wins over the generic
+//                        `data-col`; siblings sharing a key queue in document
+//                        order, so they pair first-with-first
+//   3. the same POSITION — the next unclaimed unkeyed child
+//
+// Position is last because it is the only one that is not really identity. It
+// is the fallback for a caller that supplies no keys, and every child is
+// claimed at most once so the three tiers cannot disagree about a node.
 
 const handlerKeysMap = new WeakMap<HTMLElement, Set<string>>();
 
@@ -16,7 +27,25 @@ export function trackHandler(el: HTMLElement, key: string): void {
   keys.add(key);
 }
 
-/** Replace a parent's children with the given nodes/strings, reconciling against existing DOM. */
+/** Replace a parent's children with the given nodes/strings, reconciling against existing DOM.
+ *
+ * Strings become text nodes, a `DocumentFragment` contributes its children,
+ * and `null`/`undefined` are skipped. Afterwards `parent`'s children are
+ * exactly what was passed, in order, with existing children reused wherever
+ * one corresponds to a requested child — so focus, selection, scroll position
+ * and live input state survive a re-render.
+ *
+ * Two things a caller has to know:
+ *
+ * - **A node that is already a child of `parent` is placed at the index it was
+ *   passed at, unmodified.** Handing a parent its own children reordered is a
+ *   supported operation (a drag-and-drop, a sort).
+ * - **Any other node is a TEMPLATE.** Its tag, attributes and content may be
+ *   copied into a reused child and the node itself never inserted, so a
+ *   reference to a freshly built node is not a reference to something in the
+ *   DOM. This is what reuse costs, and it is why the point above is worth
+ *   stating separately.
+ */
 export function patch(
   parent: Node,
   ...children: (string | Node | DocumentFragment | null | undefined)[]
@@ -37,114 +66,125 @@ export function patch(
   reconcileChildren(parent, newChildren);
 }
 
-/** Reconcile a parent node's children against a new set of child nodes, patching in place. */
+/** Reconcile a parent node's children against a new set of child nodes, patching in place.
+ *
+ * @internal Not on the package's `exports` map. `patch(parent, ...nodes)` is
+ * the same call for a `Node[]`, with string, fragment and nullish handling on
+ * top.
+ */
 export function reconcileChildren(parent: Node, newChildren: Node[]): void {
-  const oldChildren = Array.from(parent.childNodes);
-  // Per-key FIFO queues: siblings sharing a key (e.g. two `data-col="meta"`
-  // cells in one row) match in document order (first↔first, second↔second)
-  // instead of a last-wins map entry mispairing them and churning nodes.
-  const oldByKey = new Map<string, Node[]>();
-  for (const child of oldChildren) {
-    const key = nodeKey(child);
+  // A node the caller NAMED is reserved for itself. This is the one fact that
+  // keeps the three tiers disjoint: a node already in this parent is seated as
+  // itself (tier 1), so tiers 2 and 3 must never hand it to a different child.
+  // Without the reservation a node can be claimed twice, and the second claim
+  // either removes it as a tag mismatch or patches another child's content into
+  // it — which also means reading out of a live sibling this loop has already
+  // mutated.
+  const named = new Set<Node>(newChildren);
+
+  // Partition the current children ONCE, before any mutation, by the tier
+  // allowed to claim them: a keyed child only ever through its key's FIFO queue,
+  // an unkeyed one only ever through the positional cursor. Nothing is in both,
+  // so tiers 2 and 3 cannot collide, and neither can yield a node twice — a
+  // queue consumes by shift, the cursor only moves forward.
+  const byKey = new Map<string, Node[]>();
+  const positional: Node[] = [];
+  for (let node = parent.firstChild; node !== null; node = node.nextSibling) {
+    const key = nodeKey(node);
     if (key) {
-      const queue = oldByKey.get(key);
+      const queue = byKey.get(key);
       if (queue === undefined) {
-        oldByKey.set(key, [child]);
+        byKey.set(key, [node]);
       } else {
-        queue.push(child);
+        queue.push(node);
       }
+    } else {
+      positional.push(node);
     }
   }
 
-  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) {
-      continue;
-    }
-    const newKey = nodeKey(newChild);
+  // The node currently at the index being resolved. Every branch below seats the
+  // resolved child at exactly that index, so the children before it are final
+  // and the next reference node is the seated child's next sibling — O(1), where
+  // a childNodes.item(i) lookup per step is not. That invariant is also what
+  // makes the sweep at the end of the loop exact.
+  let ref: Node | null = parent.firstChild;
+  let cursor = 0;
 
+  for (const newChild of newChildren) {
+    // Tier 1 — the same NODE. A child the caller handed back needs no lookup and
+    // no reconciliation: it already IS the requested child, so it falls straight
+    // through to being seated as itself below. Short-circuiting the other two
+    // tiers is what stops a sibling being claimed as its host — with duplicate
+    // keys, the key queue would otherwise skip the reserved node, reach the next
+    // one, find it patchable on the shared tag, and let the sweep delete the node
+    // the caller actually named.
     let matched: Node | null = null;
-    if (newKey) {
-      const queue = oldByKey.get(newKey);
-      if (queue !== undefined) {
-        matched = queue.shift() ?? null;
-        if (queue.length === 0) {
-          oldByKey.delete(newKey);
+    if (newChild.parentNode !== parent) {
+      const key = nodeKey(newChild);
+      if (key) {
+        // Tier 2 — the same KEY.
+        const queue = byKey.get(key);
+        while (queue !== undefined && queue.length > 0) {
+          const candidate = queue.shift();
+          if (candidate !== undefined && !named.has(candidate)) {
+            matched = candidate;
+            break;
+          }
         }
-      }
-    } else {
-      // Unkeyed new node: match the next UNKEYED old node by position, advancing
-      // past keyed old nodes (which are reserved for key-based matching) and any
-      // already-consumed slots. This mirrors the documented contract ("unkeyed
-      // nodes match by position, skipping keyed nodes") and React/Preact's
-      // keyed+positional reconciliation. Stopping at (and matching) a keyed old
-      // 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) && !placed.has(oc)) {
-          break;
+      } else {
+        // Tier 3 — the same POSITION.
+        while (cursor < positional.length) {
+          const candidate = positional[cursor++];
+          if (candidate !== undefined && !named.has(candidate)) {
+            matched = candidate;
+            break;
+          }
         }
-        oldIdx++;
-      }
-      if (oldIdx < oldChildren.length) {
-        matched = oldChildren[oldIdx] ?? null;
-        oldIdx++;
       }
     }
 
-    if (!matched) {
-      const ref = parent.childNodes.item(i);
-      parent.insertBefore(newChild, ref);
-      continue;
-    }
-
-    if (!canPatch(matched, newChild)) {
-      // Insert the replacement at the target index i, then drop the mismatched
-      // old node — which may NOT be at index i. The positional scan lets an
-      // unkeyed new node match a positionally-later unkeyed old node while an
-      // unconsumed keyed old node sits ahead of it, so `matched` can be at a
-      // position > i. replaceChild would leave newChild at matched's position;
-      // a later insert then pushes it past newChildren.length and the trailing
-      // removal loop deletes it, dropping the new node and leaving the stale
-      // 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;
-    }
-
-    const ref = parent.childNodes.item(i);
-    if (ref !== matched) {
-      parent.insertBefore(matched, ref);
-    }
-
-    if (matched.nodeType === 3) {
-      if (matched.textContent !== newChild.textContent) {
-        matched.textContent = newChild.textContent;
+    if (matched !== null && canPatch(matched, newChild)) {
+      // An existing child hosts this one: seat it, then patch it to match. The
+      // requested node is a template and is not inserted.
+      //
+      // Re-inserting a node that is already in place still detaches and
+      // reattaches it, which blurs a focused input, so move only when the
+      // position actually differs.
+      if (ref !== matched) {
+        parent.insertBefore(matched, ref);
       }
-    } else if (matched.nodeType === 1) {
-      patchAttrs(matched as HTMLElement, newChild as HTMLElement);
-      reconcileChildren(matched, Array.from(newChild.childNodes));
+      if (matched.nodeType === 3) {
+        if (matched.textContent !== newChild.textContent) {
+          matched.textContent = newChild.textContent;
+        }
+      } else if (matched.nodeType === 1) {
+        patchAttrs(matched as HTMLElement, newChild as HTMLElement);
+        reconcileChildren(matched, Array.from(newChild.childNodes));
+      }
+      ref = matched.nextSibling;
+    } else {
+      // Nothing to reconcile: either the caller handed back a node this parent
+      // already has, or nothing corresponds to it, or the tags disagree. Either
+      // way the requested node itself is seated here. A child that was matched
+      // but not patchable is NOT removed at this point — it now sits at or after
+      // `ref`, was consumed so no later index can claim it, and the sweep below
+      // takes it. One removal path, not two.
+      if (ref !== newChild) {
+        parent.insertBefore(newChild, ref);
+      }
+      ref = newChild.nextSibling;
     }
   }
 
-  while (parent.childNodes.length > newChildren.length) {
-    const last = parent.lastChild;
-    if (last === null) {
-      break;
-    }
-    last.remove();
+  // Everything from `ref` on is a child the caller did not ask for. The
+  // invariant above makes that exact where comparing counts cannot be: pass one
+  // node twice and the requested count exceeds what a tree can hold, leaving a
+  // stale sibling behind.
+  while (ref !== null) {
+    const next = ref.nextSibling;
+    parent.removeChild(ref);
+    ref = next;
   }
 }
 
@@ -206,12 +246,13 @@ function patchAttrs(oldEl: HTMLElement, newEl: HTMLElement): void {
   // 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.
+  // Syncing `value` overwrites whatever a user has typed, and a write that
+  // changes it also 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,
@@ -221,11 +262,17 @@ function patchAttrs(oldEl: HTMLElement, newEl: HTMLElement): void {
   // 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.
+  // Each `!==` guard is deliberate: assigning to `.value` sets the element's
+  // dirty-value flag unconditionally, which severs the property from its content
+  // attribute for the rest of the element's life, and on a field holding raw
+  // content the value getter cannot see (`type=date`, `number`, `time`, `month`,
+  // `week`, `datetime-local`) it destroys what the user is half-way through
+  // typing. The caret is NOT the reason: per the HTML spec the text entry cursor
+  // moves only when the value actually changes, so a same-value write leaves it
+  // where it was. The dirty-value, dirty-checkedness and dirtiness flags are what
+  // make "the re-patch did not write" observable as "the element still follows
+  // its content attribute" — all four guards are pinned behaviourally, with no
+  // spy and no caret.
   if (oldEl.nodeName === "INPUT") {
     const oldInput = oldEl as HTMLInputElement;
     const newInput = newEl as HTMLInputElement;

package/src/signal.ts

@@ -3,9 +3,34 @@
 // per-node version fast-skip, bitfield flags.
 // Apache-2.0.
 //
+// FLUSH MODEL — one phase, and the whole of it:
+//   1. A write flushes. When `sig.value = x` returns, every effect that depends
+//      on `sig` has already re-run. The setter opens an implicit batch, notifies,
+//      and drains before it returns, so there is no pending-effect state a caller
+//      can observe and no queue to drain.
+//   2. `batch(fn)` is the only deferral. Writes inside it coalesce; effects are
+//      held and run once, synchronously, when the OUTERMOST batch returns.
+//   3. Deferral beyond that is the caller's. To get effects on a later task,
+//      write on a later task (queueMicrotask, requestAnimationFrame). This module
+//      owns no scheduler and offers no flush barrier, because it never holds work.
+//
+// Clause 3 is why there is no `flushSync()`. A flush barrier is the API a
+// DEFERRED model owes its callers — Vue's `nextTick`, React's `flushSync` — and
+// an eager one owes none. The export existed until v2.0.0, could never find work
+// pending (endBatch drains the moment the depth reaches 0) and refused to act
+// when work WAS pending (it returned early above depth 0), so it was a no-op from
+// every position a caller could occupy; six mutants over its body were
+// permanently unkillable, and 71 consumer call sites had never done anything.
+// Anything reintroducing a barrier here is reintroducing that: the barrier is not
+// the missing piece, clause 1 is.
+//
 // 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:
+// @preact/signals-core@1.14.4 (drift audit 2026-07-17). The flush model above is
+// upstream's, including the absence of a barrier: upstream documents the write
+// contract in prose ("Changing a signal's value synchronously updates every
+// computed and effect that depends on that signal") and its surface is
+// signal/computed/effect/batch/untracked/createModel. 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); the cycle guard lives in endBatch's drain
@@ -373,13 +398,13 @@ function endBatch(): void {
   if (--batchDepth > 0) {
     return;
   }
-  // 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.
+  // The drain is re-entrant: a write or a batch() 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 an
+  // empty `batch(() => {})`, wipe the passes the enclosing drain had accumulated
+  // and multiply the effective cap.
   const enclosingIteration = batchIteration;
   while (batchedEffect !== undefined) {
     let eff: EffectNode | undefined = batchedEffect;
@@ -626,7 +651,8 @@ export function effect(fn: () => Cleanup): () => void {
   };
 }
 
-/** Coalesce signal writes; effects flush synchronously at end of outermost batch. */
+/** Coalesce signal writes; effects flush synchronously at end of outermost batch.
+ *  This is the library's ONLY deferral: see the flush model in the module header. */
 export function batch(fn: () => void): void {
   startBatch();
   try {
@@ -636,15 +662,6 @@ export function batch(fn: () => void): void {
   }
 }
 
-/** Flush all pending effects synchronously. No-op inside batch(). */
-export function flushSync(): void {
-  if (batchDepth > 0) {
-    return;
-  }
-  startBatch();
-  endBatch();
-}
-
 /** Run fn without tracking any signal reads. */
 export function untracked<T>(fn: () => T): T {
   const prev = evalContext;
@@ -656,6 +673,37 @@ export function untracked<T>(fn: () => T): T {
   }
 }
 
+/** Read a signal for its tracking effect alone, discarding the value.
+ *
+ *  The complement of `peek()`: `peek` reads without subscribing, `touch`
+ *  subscribes without keeping. Outside a reactive scope it does nothing
+ *  observable.
+ *
+ *  This exists because the two-tier shape `createCollection` and `bindList` are
+ *  built on produces it: a scope reads per-entity values through `signalFor`,
+ *  so it must depend on the structure signal separately to re-run when the id
+ *  set changes, and that dependency has no value the body wants. Spelling it as
+ *  a discarded expression left the intent to a comment, and `undefined` entries
+ *  are accepted so a per-key lookup that may miss (`signalFor(id)`,
+ *  `SignalMap.get(id)`) can be passed straight in.
+ *
+ *  Not a substitute for `on()`, which declares an exhaustive dependency list
+ *  and runs its body untracked. `touch` ADDS a dependency and leaves every
+ *  other read in the scope tracked as usual. */
+export function touch(
+  ...signals: readonly (Signal<unknown> | ReadonlySignal<unknown> | undefined)[]
+): void {
+  for (const sig of signals) {
+    readForDependency(sig);
+  }
+}
+
+// Named so the read is a call rather than a discarded expression: the value is
+// deliberately unused, and returning it is what keeps that legible.
+function readForDependency(sig: Signal<unknown> | ReadonlySignal<unknown> | undefined): unknown {
+  return sig?.value;
+}
+
 /** Subscribe to a signal, calling cb on every change. Returns dispose function.
  *  The callback runs untracked: reading other signals inside it does not add
  *  them as dependencies of the subscription (matches upstream

package/src/store.ts

@@ -3,22 +3,32 @@
 // Each key is backed by a lazily-created signal, so the store inherits the
 // engine's glitch-freedom, cycle detection, batching, and error handling.
 // There is NO separate reactivity implementation here: get/set read and
-// write signals, effect/batch are the engine's own, and auto-tracking falls
-// out of reading `signal.value` inside an effect.
+// write signals, and auto-tracking falls out of reading `signal.value` inside an
+// effect.
+//
+// The member set is decided by one rule: a Store member exists only where it
+// does something the engine's namesake does NOT. `subscribe` skips the initial
+// call and runs untracked; `computed` is an eager key-writing effect rather than
+// a lazy signal. `effect` and `batch` were the engine's own function objects
+// verbatim and are NOT re-exposed here (removed in v2.0.0) — `store.batch(…)`
+// read as "batch this store's writes" while batching the whole graph, which is a
+// scope the flush model does not have. Import `batch` and `effect` from the
+// package root beside `createStore`.
 //
 // Usage:
-//   import { createStore } from './store.js';
+//   import { createStore, batch, effect } from '@cplieger/reactive';
 //   interface MyMap { count: number; name: string }
-//   const { get, set, subscribe, effect, computed, batch } = createStore<MyMap>();
+//   const { get, set, subscribe, computed } = createStore<MyMap>();
 
-import { signal, effect, batch, untracked, type Signal, type Cleanup } from "./signal.js";
+import { signal, effect, untracked, type Signal } from "./signal.js";
 
-/** A typed per-key reactive store with auto-tracked effects, computed, and batching. */
+/** A typed per-key reactive store: lazily signal-backed keys, change-only
+ *  subscriptions, and eager derived keys. Effects and batching are the engine's
+ *  own `effect` / `batch`, imported from the package root. */
 export interface Store<M> {
   get<K extends keyof M & string>(key: K): M[K];
   set<K extends keyof M & string>(key: K, value: M[K]): void;
   subscribe<K extends keyof M & string>(key: K, cb: (value: M[K]) => void): () => void;
-  effect(fn: () => Cleanup): () => void;
   /** Derive `outputKey` from other keys. NOT a lazy engine `computed`: this is
    *  an EAGER effect that re-runs `fn` on dependency change and WRITES the
    *  result to `outputKey`. Consequences of that shape: `fn` runs whether or
@@ -28,7 +38,6 @@ export interface Store<M> {
    *  self-reading `fn` behaves as documented on the implementation below.
    *  Returns the effect's dispose function. */
   computed<K extends keyof M & string>(outputKey: K, fn: () => M[K]): () => void;
-  batch(fn: () => void): void;
 }
 
 /** Create a typed reactive store. Keys are lazily backed by signals; reading a
@@ -84,5 +93,5 @@ export function createStore<M>(): Store<M> {
     });
   }
 
-  return { get, set, subscribe, effect, computed, batch };
+  return { get, set, subscribe, computed };
 }