@zakkster/lite-signal 1.0.6 → 1.1.1

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@zakkster/lite-signal.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-signal)
 ![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
-[![bundle size](https://img.shields.io/badge/min%2Bgz-~3.2KB-blue?style=flat-square)](https://bundlephobia.com/package/@zakkster/lite-signal)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-signa?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-signal)
 [![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-signal?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-signal)
 [![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-signal?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-signal)
 ![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
@@ -40,6 +40,7 @@ Synchronous, glitch-free, push-pull. No microtask queue, no allocations after wa
 - [Architecture in one diagram](#architecture-in-one-diagram)
 - [How a write propagates](#how-a-write-propagates)
 - [API reference](#api-reference)
+- [Watchers](#watchers)
 - [Capacity, growth, and the link ceiling](#capacity-growth-and-the-link-ceiling)
 - [Edge cases pinned down](#edge-cases-pinned-down)
 - [Benchmarks](#benchmarks)
@@ -47,6 +48,7 @@ Synchronous, glitch-free, push-pull. No microtask queue, no allocations after wa
 - [What this is not](#what-this-is-not)
 - [Browser and runtime support](#browser-and-runtime-support)
 - [Integration recipes](#integration-recipes)
+- [Conformance](#conformance)
 - [FAQ](#faq)
 - [npm scripts](#npm-scripts)
 
@@ -347,6 +349,137 @@ Default sizing for a Twitch-extension-style budget:
 
 ---
 
+## Watchers
+
+`@zakkster/lite-signal` ships three composable watcher primitives, all built from `effect` + `untrack` — no engine extensions, no per-watcher flag in `ReactiveNode`. The core stays small; the surface stays useful.
+
+| API | Use case | Lifecycle | Hot-path safe? |
+|---|---|---|---|
+| `watch(source, cb)` | observe value changes over time | manual `stop()` | ✅ zero-GC per fire |
+| `watch(source, (v, p, stop) => …)` | observe until a condition | self-dispose via callback arg | ✅ zero-GC per fire |
+| `when(predicate, cb)` | one-shot trigger when condition first true | auto-dispose | ✅ zero-GC per check |
+| `whenAsync(predicate)` | await a condition | auto-dispose | ⚠️ allocates Promise — see below |
+
+### `watch(source, callback, options?)`
+
+Fires the callback whenever the source's projected value changes. The callback receives `(newValue, oldValue, stop)` — calling `stop()` from inside the callback disposes the watcher.
+
+```js
+import { signal, watch } from "@zakkster/lite-signal";
+
+const count = signal(0);
+
+// Basic — observe forever
+const stop = watch(count, (next, prev) => {
+    console.log(`${prev} → ${next}`);
+});
+
+count.set(1);  // logs: 0 → 1
+stop();        // manual dispose
+```
+
+**Self-disposing watcher** — declarative termination from inside the callback:
+
+```js
+watch(status, (next, prev, stop) => {
+    if (next === "ready") {
+        initialize();
+        stop();  // detach after first "ready"
+    }
+});
+```
+
+**Immediate option** — fires once on registration with `oldValue = undefined`:
+
+```js
+watch(theme, (v) => applyTheme(v), { immediate: true });
+```
+
+**Raw getter equality** — `watch` uses `Object.is` internally to avoid spurious fires when a dep mutation produces the same projected value:
+
+```js
+const health = signal(10);
+let deathLog = 0;
+watch(() => health() <= 0, (isDead) => { deathLog++; });
+
+health.set(9);  // isDead is still false — no fire
+health.set(8);  // same — no fire
+health.set(0);  // crossed — fires once with (true, false)
+```
+
+Without this guard, the callback would fire on every `health` mutation regardless of whether `isDead` changed. Wrapping the source in `computed()` would achieve the same via the computed's own equality check — the guard makes that wrapping optional.
+
+### `when(predicate, callback)`
+
+Fires `callback` exactly once when `predicate` first returns a truthy value, then auto-disposes. If the predicate is already truthy at registration, fires synchronously.
+
+```js
+import { when } from "@zakkster/lite-signal";
+
+when(() => user.isAuthenticated, () => {
+    navigate("/dashboard");
+});
+```
+
+The returned dispose function can cancel before the predicate fires:
+
+```js
+const cancel = when(() => slowApi.ready, () => start());
+if (userBacked) cancel();
+```
+
+### `whenAsync(predicate)`
+
+> ### ⚠️ Hot-path warning
+>
+> `whenAsync` calls `new Promise(...)` internally — **this is a heap allocation**. Every call allocates a Promise object, an executor closure, and Promise infrastructure (resolve function, microtask state). Promises require heap allocation by the language spec; this cost is unavoidable.
+>
+> **Use for:** high-level scene/UI orchestration, boot sequences, awaiting user input, level transitions. Anything that runs once or rarely.
+>
+> **NEVER use for:** per-frame entity updates, render-loop logic, animation tick handlers, anywhere that runs at 60/120 fps. The Promise allocations will be visible in GC traces and will cause frame-time spikes under sustained load.
+>
+> **For zero-GC hot-path logic, use `when` with a callback.**
+
+Promise-returning variant of `when`. Composes with `async/await` for declarative async control flow against reactive state:
+
+```js
+import { whenAsync } from "@zakkster/lite-signal";
+
+async function bootSequence() {
+    await whenAsync(() => config.loaded);
+    await whenAsync(() => auth.ready);
+    await whenAsync(() => db.connected);
+    render();
+}
+```
+
+The promise never rejects on its own — if the predicate never becomes truthy, the promise never settles. For timeout semantics use `Promise.race`:
+
+```js
+await Promise.race([
+    whenAsync(() => api.ready),
+    new Promise((_, rej) => setTimeout(() => rej(new Error("timeout")), 5000))
+]);
+```
+
+### Allocation profile
+
+Honest accounting of where memory is spent in each primitive:
+
+| Primitive | Allocations at registration | Allocations per fire / check |
+|---|---|---|
+| `watch(source, cb)` | 3 closures (stop, effect body, hoisted untrack body) | **0** |
+| `when(predicate, cb)` | 2 closures (stop, effect body) | **0** |
+| `whenAsync(predicate)` | 1 Promise + 1 executor closure + Promise internals + 2 closures from `when` | **0** (after registration) |
+
+The "0 per fire" property for `watch` is deliberate engineering — the inner `untrack` callback is hoisted to a single closure allocated once at registration, with `currentNewValue` as shared mutable state. If you read the source and wonder why we don't use a clean inline arrow function inside the effect body, this is the answer: doing it inline would allocate a fresh closure on every dep change, at 7,200 allocs per minute per watcher at 120 fps.
+
+### Tree-shaking
+
+All three primitives live in a separate module (`src/watch.js`) and are re-exported from the main entry. If your bundle doesn't import them, they won't appear in the output — modern ESM tree-shaking (Vite, Rollup, esbuild) handles this reliably.
+
+---
+
 ## Edge cases pinned down
 
 These are the questions you'd ask in a code review, with the answers:
@@ -412,6 +545,8 @@ Three tiers, all reproducible.
 - **`05-scheduler.test.mjs`** — scheduler-deferred effects, dispose-during-schedule races, microtask integration, 32-bit version wrap (simulated), `setDefaultRegistry`, `onCleanup` inside computeds.
 - **`06-nested-objects.test.mjs`** — array mutation patterns (push/splice/spread), deep nested paths, Map/Set/Date inside signals, custom structural equality, computed memoisation cutoffs over object slices, signal-of-signals composition, high-frequency object updates, batched immutable updates.
 - **`07-dispose.test.mjs`** — unified `dispose(api)` across signals, computeds and effect handles, idempotency, cross-registry isolation (per-registry Symbol prevents pool corruption), foreign-value safety, top-level helper routing, 500-cycle balanced churn leaving pool and stats stable.
+- **`08-watch.test.mjs`** — Validates the user-land observer utilities (watch, when, whenAsync). Covers lifecycle teardown, old/new value tracking, and Promise-based asynchronous state resolution.
+- **`09-conformance.test.mjs`** — Industry-standard conformance tests. Validates the engine against extreme edge cases from the johnsoncodehk reactive test suite, ensuring strict zero-GC invariants, correct cleanup isolation, and re-entrant stability.
 
 ```bash
 npm test
@@ -471,8 +606,8 @@ In highly chaotic graphs with branch switching, selective reads, and wide dense
 
 **The Takeaway:** "Zero-GC" and "topology scalability" are orthogonal dimensions. If you are building a DOM framework with massive dynamic `v-if` churn, use Alien Signals. If you are building a 120fps Canvas game with a stable scene graph where any GC pause is a dropped frame, use `lite-signal`.
 
-### Roadmap: v1.1
-We are actively working on a v1.1 architectural update to address this topology degradation while maintaining the zero-GC contract. By moving to a version-stamped dependency reconciliation pass (`lastSeenInEval`) with a pre-allocated scratch buffer, we expect to drop dynamic read costs to $O(1)$ unconditionally.
+### Roadmap: v1.2
+v1.2 (in benchmark validation) — Andrii Volynets (alien-signals#117) extended the benchmark matrix to dynamic-topology workloads and identified retracking-cost asymptotics, not allocation pressure, as the dominant cost in those scenarios. v1.2 replaces the cursor-based retracking with per-source version-stamped reconciliation: O(1) per read regardless of read order or dep-set churn. v1.2 will be validated against the alien-signals topology matrix and the before/after numbers published on release.
 
 ---
 
@@ -568,6 +703,76 @@ function spawnPlugin(pluginCode) {
 
 ---
 
+## Conformance
+
+lite-signal v1.1.0 was evaluated against the
+[reactive-framework-test-suite](https://github.com/johnsoncodehk/reactive-framework-test-suite),
+the most comprehensive behavioral test battery for JavaScript reactive
+libraries.
+
+**174 of 177 tests pass (98.3%)**, placing lite-signal **in a tie for second place of sixteen**
+evaluated libraries — just behind alien-signals (177).
+
+We publish both passing and failing tests, because honesty about behavior is
+more useful to library users than a green checkmark.
+
+### What lite-signal does that no other library does
+
+- **`batch()` returns the callback's value.** Every other library evaluated
+  returns `void`. `const total = batch(() => ...)` is a lite-signal idiom.
+- **Cycle detection** in effects (matches preact, reatom, svelte, solid).
+  Many libraries silently iterate to a 200-step bail; lite-signal throws so
+  the bug surfaces at development time.
+- **`Object.is` equality** throughout, including NaN — matches Vue,
+  Angular, Reatom, the TC39 polyfill, and tansu. The `===` camp returns
+  incorrect results on NaN flows.
+- **Single-pass propagation** through computed chains on inner writes —
+  matches alien-signals and Vue; faster than preact, solid, reatom, mobx,
+  and most others by one re-evaluation per write.
+- **Auto-unsubscribe** on first-run effect throws — matches preact, reatom,
+  solid. Half the field leaks the subscription.
+
+### What v1.1.0 doesn't do yet
+
+10 tests fail. We've categorized them by intent.
+
+**Targeted for v1.2** (6 tests):
+
+- **Revert detection inside batches** (#147, #132, #123): writes inside a
+  `batch()` that net to no change still mark dependents as dirty. Vue,
+  Solid, Mobx, and roughly half the field share this behavior. v1.2 will
+  capture pre-batch values per signal and skip propagation on revert.
+- **Throw isolation in batch flush** (#121): if an effect throws during
+  flush, lite-signal currently halts the flush. v1.2 will collect errors,
+  finish the flush, then re-throw as `AggregateError`.
+- **Inner-write propagation through computed chains** (#180, #213): two
+  specific propagation paths where lite-signal disagrees with the field.
+  Both are propagation-order bugs in the recursive computed resolver,
+  not zero-GC tradeoffs.
+
+**Design choices we will not change** (2 tests):
+
+- **Inner writes inside computeds** (#179): writing to a signal from inside
+  a computed is a side effect, not a derivation. Use an `effect` instead.
+  Most of the field also fails this test.
+- **Nested batch coalescing inside an effect body** (#235): explicit
+  `batch()` calls *inside* an executing effect do not coalesce beyond the
+  effect's own implicit batching. Most libraries behave this way. Wrap the
+  batch outside the effect for the intended semantics.
+
+**Opt-in feature, deferred** (2 tests):
+
+- **Solid-style cascading disposal of nested effects** (#209, #210):
+  lite-signal does not maintain an owner tree of parent-child effects.
+  This matches preact, vue, mobx, the TC39 polyfill, Angular, Svelte,
+  tansu, and Solid 1.x. Solid 2 / @solidjs/signals, reatom, and anod
+  implement it. If you need it, please open an issue.
+
+Per-test results, the runner adapter, and reproductions live in
+`/conformance/`.
+
+---
+
 ## FAQ
 
 **Why no microtask scheduler?**

package/Signal.d.ts

@@ -165,7 +165,7 @@ export function batch<T>(fn: () => T): T;
 export function untrack<T>(fn: () => T): T;
 export function onCleanup(fn: () => void): void;
 export function stats(): RegistryStats;
-
+export declare function destroy(): void;
 
 /**
  * Configuration options for the watch utility.
@@ -177,25 +177,66 @@ export interface WatchOptions {
     immediate?: boolean;
 }
 
+//**
+* Track a reactive source and run a callback whenever its projected value
+* changes. The callback receives `(newValue, oldValue, stop)` — the third
+* argument is a dispose function that can be called from inside the callback
+* to terminate the watcher.
+*
+* Internal reads inside the callback are untracked.
+*
+* Uses `Object.is` to guard against the raw-getter case where a dep mutation
+* fires the effect but the projected value is unchanged.
+*
+* @param source    Reactive read function.
+* @param callback  Called with the new and previous values plus a stop handle.
+* @param options   `immediate: true` runs the callback once on registration
+*                  with `oldValue = undefined`.
+* @returns Dispose function. Idempotent and safe to call at any time, including
+*          synchronously during the immediate callback.
+*/
+export function watch<T>(
+    source: () => T,
+    callback: (newValue: T, oldValue: T | undefined, stop: () => void) => void,
+    options?: { immediate?: boolean }
+): () => void;
+
+/**
+ * Fire `callback` exactly once when `predicate` first returns a truthy value,
+ * then auto-dispose. If `predicate` is already truthy at registration, fires
+ * synchronously.
+ *
+ * @param predicate  Reactive read function; callback fires when truthy.
+ * @param callback   Called once when predicate first truthy. Reads inside are untracked.
+ * @returns Dispose function. Call before predicate fires to cancel; idempotent.
+ */
+export function when(
+    predicate: () => unknown,
+    callback: () => void
+): () => void;
+
 /**
- * Track a reactive source and run a callback whenever its evaluated value changes.
+ * Promise-returning variant of {@link when}. The returned promise resolves
+ * when `predicate` first returns a truthy value.
  *
- * Models Vue's `watch(source, callback)` and MobX's `reaction(predicate, effect)`.
- * Internal reads inside the callback are untracked — they do not create reactive
- * dependencies.
+ * ⚠️ **HOT-PATH WARNING — DO NOT USE PER FRAME.** This function calls
+ * `new Promise(...)`, which is a heap allocation (one Promise object plus
+ * executor closure plus internal infrastructure per call). Promises require
+ * heap allocation by the language spec — this cost is unavoidable.
  *
- * @example
- * const count = signal(0);
- * const stop = watch(() => count() * 2, (next, prev) => {
- * console.log(`Doubled count changed: ${prev} -> ${next}`);
- * });
- * * @param source    A function that reads reactive values (e.g., a signal/computed getter).
- * @param callback  Fired when the source's value changes. Receives the new and previous values.
- * @param options   Optional configuration (e.g., `{ immediate: true }`).
- * @returns         Dispose function — call to stop watching and release the effect.
+ * **Use for:** high-level scene/UI orchestration, boot sequences, awaiting
+ * user input or network state, level transitions. Anything that runs once
+ * or rarely.
+ *
+ * **NEVER use for:** per-frame entity updates, render-loop logic, animation
+ * tick handlers. For zero-GC hot-path logic use {@link when} with a callback.
+ *
+ * Note: this promise never rejects. If the predicate never becomes truthy,
+ * the promise never settles. Wrap in `Promise.race` for timeout semantics.
+ *
+ * @param predicate  Reactive read function; resolves promise when truthy.
+ * @returns Promise that resolves when predicate first truthy.
  */
-export function watch<T>(
-    source: () => T,
-    callback: (newValue: T, oldValue: T | undefined) => void,
-    options?: WatchOptions
-): () => void;
+export function whenAsync(
+    predicate: () => unknown
+): Promise<void>;

package/Signal.js

@@ -61,6 +61,13 @@ class ReactiveNode {
         /** Recycle generation: bumped on dispose, used to invalidate stale scheduler closures. */
         this.gen = 0;
 
+        /** Captured value at first .set() inside the current batch (revert detection). */
+        this.preBatchValue = undefined;
+        /** Captured version at first .set() inside the current batch. */
+        this.preBatchVersion = 0;
+        /** batchEpoch that owns the capture; 0 = no capture. */
+        this.revertEpoch = 0;
+
         // Doubly-linked dependency list (this node depends on these sources).
         this.headDep = null;
         this.tailDep = null;
@@ -68,6 +75,7 @@ class ReactiveNode {
         this.currentDep = null;
         // Doubly-linked subscriber list (these targets depend on this node).
         this.headSub = null;
+        this.tailSub = null;
 
         // Pool free-list pointer.
         this.nextFree = null;
@@ -174,12 +182,17 @@ export function createRegistry(config = {}) {
 
     // --- GLOBAL STATE ---
     let globalVersion = 1 | 0; // Forced 32-bit SMI
+    let batchEpoch = 1 | 0;     // skip-zero sentinel; revertEpoch=0 means "no capture"
     let currentObserver = null;
     let activeObserverCurrentDep = null;
     let batchDepth = 0 | 0;
     let isTrackingDeps = false;
     let isFlushing = false;
 
+    // Reused buffer for throw isolation during flush
+    const flushErrorBuffer = [];
+    let flushErrorCount = 0 | 0;
+
     // --- ALLOCATORS ---
 
     /**
@@ -244,10 +257,13 @@ export function createRegistry(config = {}) {
             link.source = source;
             link.target = target;
 
-            link.prevSub = null;
-            link.nextSub = source.headSub;
-            if (source.headSub !== null) source.headSub.prevSub = link;
-            source.headSub = link;
+            link.nextSub = null;
+            link.prevSub = source.tailSub;
+
+            if (source.tailSub !== null) source.tailSub.nextSub = link;
+            else source.headSub = link;
+
+            source.tailSub = link;
         }
 
         link.nextDep = expected;
@@ -270,8 +286,9 @@ export function createRegistry(config = {}) {
     function freeLink(link, target, source) {
         const pSub = link.prevSub;
         const nSub = link.nextSub;
+
         if (pSub !== null) pSub.nextSub = nSub; else source.headSub = nSub;
-        if (nSub !== null) nSub.prevSub = pSub;
+        if (nSub !== null) nSub.prevSub = pSub; else source.tailSub = pSub;
 
         link.source = null;
         link.target = null;
@@ -335,6 +352,11 @@ export function createRegistry(config = {}) {
         node.tailDep = null;
         node.currentDep = null;
         node.headSub = null;
+        node.tailSub = null;
+
+        node.revertEpoch = 0;
+        node.preBatchValue = undefined;
+        node.preBatchVersion = 0;
 
         node.gen = (node.gen + 1) | 0;
         node.nextFree = freeNodeHead;
@@ -382,19 +404,32 @@ export function createRegistry(config = {}) {
         node.tailDep = null;
         node.currentDep = null;
         node.headSub = null;
+        node.tailSub = null;
         node.version = 0;
         node.evalVersion = 0;
         node.markEpoch = 0;
+        node.revertEpoch = 0;
+        node.preBatchValue = undefined;
+        node.preBatchVersion = 0;
         return node;
     }
 
     /** Invoke registered cleanup function(s) on `node` and clear. @private */
     function runCleanup(node) {
         const cleanup = node.cleanupFn;
-        if (cleanup) {
+        if (cleanup === undefined) return;
+
+        const prevObserver = currentObserver;
+        const prevTracking = isTrackingDeps;
+        currentObserver = null;
+        isTrackingDeps = false;
+        try {
             if (typeof cleanup === "function") cleanup();
             else for (let i = 0; i < cleanup.length; i++) cleanup[i]();
+        } finally {
             node.cleanupFn = undefined;
+            currentObserver = prevObserver;
+            isTrackingDeps = prevTracking;
         }
     }
 
@@ -421,7 +456,12 @@ export function createRegistry(config = {}) {
                     const flags = t.flags | 0;
 
                     if ((flags & FLAG_EFFECT) !== 0) {
-                        if ((flags & FLAG_QUEUED) === 0) {
+                        // "No re-run" semantics for self-cycles: an effect that is currently
+                        // executing on the call stack must not be re-queued by its own body's
+                        // writes (directly or through computed chains). The effect's evalVersion
+                        // is bumped to the post-write globalVersion in its executeEffect finally,
+                        // so subsequent unrelated writes still propagate normally.
+                        if ((flags & FLAG_QUEUED) === 0 && (flags & FLAG_COMPUTING) === 0) {
                             t.flags = flags | FLAG_QUEUED;
                             activeQueue[activeQueueLen] = t;
                             activeQueueLen = (activeQueueLen + 1) | 0;
@@ -449,40 +489,74 @@ export function createRegistry(config = {}) {
 
     /**
      * Drain the effect queue. Double-buffered so new effects scheduled mid-flush
-     * end up in the next pass.
+     * end up in the next pass. Individual effect throws are caught, buffered, and
+     * re-thrown at the end of the flush (or wrapped in AggregateError if multiple).
      * @private
      */
     function flushEffects() {
         if (isFlushing) return;
         isFlushing = true;
         let passes = 0 | 0;
+        let normalExit = false;
 
-        while (activeQueueLen > 0) {
-            passes = (passes + 1) | 0;
-            if (passes > maxFlushPasses) {
-                isFlushing = false;
-                throw new Error("CycleError: flush passes exceeded");
-            }
+        try {
+            while (activeQueueLen > 0) {
+                passes = (passes + 1) | 0;
+                if (passes > maxFlushPasses) {
+                    throw new Error("CycleError: flush passes exceeded");
+                }
 
-            const toRun = activeQueueLen | 0;
-            const currentQueue = activeQueue;
-
-            isQueueA = !isQueueA;
-            activeQueue = isQueueA ? effectQueueA : effectQueueB;
-            activeQueueLen = 0 | 0;
-
-            for (let i = 0; i < toRun; i++) {
-                const node = currentQueue[i];
-                const scheduler = node.scheduler;
-                if (scheduler) {
-                    const gen = node.gen | 0;
-                    scheduler(() => safeExecute(node, gen));
-                } else {
-                    executeEffect(node);
+                const toRun = activeQueueLen | 0;
+                const currentQueue = activeQueue;
+
+                isQueueA = !isQueueA;
+                activeQueue = isQueueA ? effectQueueA : effectQueueB;
+                activeQueueLen = 0 | 0;
+
+                for (let i = 0; i < toRun; i++) {
+                    const node = currentQueue[i];
+                    try {
+                        const scheduler = node.scheduler;
+                        if (scheduler) {
+                            const gen = node.gen | 0;
+                            scheduler(() => safeExecute(node, gen));
+                        } else {
+                            executeEffect(node);
+                        }
+                    } catch (err) {
+                        // Buffer and continue. Effect's own try/finally inside
+                        // executeEffect already restored observer state and
+                        // severed tail deps before the throw landed here.
+                        flushErrorBuffer[flushErrorCount] = err;
+                        flushErrorCount = (flushErrorCount + 1) | 0;
+                    }
                 }
             }
+            normalExit = true;
+        } finally {
+            isFlushing = false;
+            if (!normalExit) {
+                // Escaping via CycleError or any non-effect-body throw. Discard
+                // buffered effect errors — the structural failure supersedes them
+                // and prevents leaking stale errors to the next flush call.
+                for (let i = 0; i < flushErrorCount; i++) flushErrorBuffer[i] = null;
+                flushErrorCount = 0 | 0;
+            }
+        }
+
+        if (flushErrorCount > 0) {
+            if (flushErrorCount === 1) {
+                const err = flushErrorBuffer[0];
+                flushErrorBuffer[0] = null; // drop reference, retain backing store
+                flushErrorCount = 0 | 0;
+                throw err;
+            }
+            // 2+ errors: snapshot into a fresh array for AggregateError, then clear.
+            const errs = flushErrorBuffer.slice(0, flushErrorCount);
+            for (let i = 0; i < flushErrorCount; i++) flushErrorBuffer[i] = null;
+            flushErrorCount = 0 | 0;
+            throw new AggregateError(errs, "Effects threw during flush");
         }
-        isFlushing = false;
     }
 
     /**
@@ -541,6 +615,12 @@ export function createRegistry(config = {}) {
 
         runCleanup(node);
 
+        // Cleanup may have disposed us (e.g. via a synchronous dispose() call from
+        // within the user's cleanup body). disposeNode clears flags to 0 and nulls
+        // computeFn; bailing here prevents a TypeError on computeFn() below and
+        // avoids reinitialising observer state on a freed slot.
+        if ((node.flags & FLAG_EFFECT) === 0) return;
+
         const prevObserver = currentObserver;
         const prevActiveDep = activeObserverCurrentDep;
         const prevTracking = isTrackingDeps;
@@ -666,7 +746,26 @@ export function createRegistry(config = {}) {
         read.set = (value) => {
             const eq = node.equals;
             if (eq && eq(node.value, value)) return;
+
+            // Revert capture: first .set() of this signal inside the current batch.
+            // Guarded by batchDepth so out-of-batch writes pay zero added cost.
+            if (batchDepth > 0 && node.revertEpoch !== batchEpoch) {
+                node.preBatchValue = node.value;
+                node.preBatchVersion = node.version | 0;
+                node.revertEpoch = batchEpoch | 0;
+            }
+
             node.value = value;
+
+            // Revert detection: in-batch write whose value matches the pre-batch
+            // capture. Restore version (without bumping globalVersion) and skip
+            // propagation. Subscribers already queued by an earlier mid-batch set
+            // will dirty-check against this restored version at flush and bail.
+            if (batchDepth > 0 && node.revertEpoch === batchEpoch && eq && eq(node.preBatchValue, value)) {
+                node.version = node.preBatchVersion | 0;
+                return;
+            }
+
             globalVersion = (globalVersion + 1) | 0;
             node.version = globalVersion | 0;
             markDownstream(node);
@@ -832,6 +931,10 @@ export function createRegistry(config = {}) {
      * @returns {T}
      */
     function batch(fn) {
+        if (batchDepth === 0) {
+            batchEpoch = (batchEpoch + 1) | 0;
+            if (batchEpoch === 0) batchEpoch = 1 | 0;   // preserve the 0 sentinel
+        }
         batchDepth = (batchDepth + 1) | 0;
         try {
             return fn();
@@ -910,9 +1013,13 @@ export function createRegistry(config = {}) {
             n.tailDep = null;
             n.currentDep = null;
             n.headSub = null;
+            n.tailSub = null;
             n.version = 0;
             n.evalVersion = 0;
             n.markEpoch = 0;
+            n.revertEpoch = 0;
+            n.preBatchValue = undefined;
+            n.preBatchVersion = 0;
             // Bump gen so any scheduler trampolines holding a stale node ref bail.
             n.gen = (n.gen + 1) | 0;
             if (i < currentNodesCapacity - 1) n.nextFree = nodePool[i + 1];
@@ -942,9 +1049,15 @@ export function createRegistry(config = {}) {
         activeObserverCurrentDep = null;
         isTrackingDeps = false;
         globalVersion = 1 | 0;
+        batchEpoch = 1 | 0;
         statSignals = 0 | 0;
         statComputeds = 0 | 0;
         statEffects = 0 | 0;
+
+        for (let i = 0; i < flushErrorCount; i++) flushErrorBuffer[i] = null;
+
+        flushErrorCount = 0 | 0;
+        flushErrorBuffer.length = 0; // release the backing array
     }
 
     return {signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy};
@@ -1006,8 +1119,15 @@ export function stats() {
     return defaultRegistry.stats();
 }
 
+/** * Wipe the default registry. strictly for test-suite isolation.
+ * @private
+ */
+export function destroy() {
+    return defaultRegistry.destroy();
+}
+
 /**
  * Re-export of the user-land watch utility.
  * @see {@link watch} in Watch.js for full implementation details.
  */
-export {watch} from "./Watch.js"
+export {watch, when, whenAsync} from "./Watch.js"

package/Watch.js

@@ -1,72 +1,192 @@
 import { effect, untrack } from "./Signal.js";
 
 /**
- * Sentinel for "first run" — distinguishes a legitimate `undefined` source value
- * from the uninitialized state. Using `Symbol` instead of `undefined` ensures a
- * source like `signal(undefined)` correctly fires `callback(undefined, undefined)`
- * on first change rather than being treated as never-changed.
+ * Sentinel for "first run" in `watch`. Distinguishes a legitimate `undefined`
+ * source value from the uninitialized state — necessary because a naive
+ * `oldValue === undefined` check would conflate them.
  * @private
  */
 const UNINITIALIZED = Symbol("watch.uninitialized");
 
 /**
- * Track a reactive source and run a callback whenever its value changes.
+ * Track a reactive source and run a callback whenever its projected value
+ * changes. The callback receives `(newValue, oldValue, stop)` — the third
+ * argument is a dispose function that can be called from inside the callback
+ * to terminate the watcher (matching MobX's `reaction` ergonomics).
  *
- * Models Vue's `watch(source, callback)` and MobX's `reaction(predicate, effect)`.
- * The callback is invoked with `(newValue, oldValue)`. Internal reads inside the
- * callback are untracked — they don't create reactive dependencies — so a callback
- * that reads other signals to perform a side-effect won't re-fire when those
- * unrelated signals change.
+ * Internal reads inside the callback are untracked: a callback that reads
+ * other signals to perform side-effects won't re-fire when those unrelated
+ * signals change.
  *
- * Disposing the returned function detaches the underlying effect and stops the
- * watcher.
+ * Uses `Object.is` to guard against the raw-getter case where a dep mutation
+ * fires the effect but the projected value is unchanged (e.g.,
+ * `watch(() => health() <= 0, ...)` where many `health` changes produce the
+ * same boolean). Wrapping the source in a `computed` would achieve the same
+ * via the computed's own equality check — the guard makes that wrapping
+ * optional.
  *
  * @example
  *   const count = signal(0);
- *   const stop = watch(count, (next, prev) => {
- *       console.log(`count changed: ${prev} -> ${next}`);
- *   });
- *   count.set(1);  // logs: "count changed: 0 -> 1"
- *   count.set(2);  // logs: "count changed: 1 -> 2"
+ *   const stop = watch(count, (next, prev) => console.log(prev, "→", next));
+ *   count.set(1);  // logs: 0 → 1
  *   stop();
- *   count.set(3);  // no log
  *
- * @example
- *   // Immediate fires the callback once on registration with `oldValue = undefined`
- *   watch(count, (next, prev) => console.log(next), { immediate: true });
- *
- * @param {() => T} source        A function that reads reactive values (typically a
- *                                signal/computed getter, or a closure combining several).
- * @param {(newValue: T, oldValue: T | undefined) => void} callback
- *                                Called when the source's value changes. Receives the
- *                                new and previous values. Internal reads are untracked.
- * @param {{ immediate?: boolean }} [options]
- *                                `immediate: true` runs the callback once on registration
- *                                with `oldValue = undefined`. Defaults to false.
- * @returns {() => void}          Dispose function — call to stop watching.
+ * @example  // Self-disposing on a condition
+ *   const status = signal("loading");
+ *   watch(status, (next, prev, stop) => {
+ *       if (next === "ready") { initialize(); stop(); }
+ *   });
+ *
+ * @example  // Immediate fire
+ *   watch(count, (n, p) => render(n), { immediate: true });
+ *
+ * @param {() => T} source                    Reactive read function.
+ * @param {(newValue: T, oldValue: T | undefined, stop: () => void) => void} callback
+ * @param {{ immediate?: boolean }} [options] `immediate: true` runs callback
+ *                                            once on registration with
+ *                                            `oldValue = undefined`.
+ * @returns {() => void}                      Dispose function. Idempotent.
  * @template T
  */
 export function watch(source, callback, options) {
     const immediate = options !== undefined && options.immediate === true;
     let oldValue = UNINITIALIZED;
+    let currentNewValue;            // shared mutable state, read by untrackedFire
+    let stopFn = null;
+    let wantsStopEarly = false;
+
+    // Late-binding stop handle: safe to call before `stopFn` is assigned (e.g.,
+    // synchronously inside the immediate fire), and safe to call multiple times.
+    const stop = () => {
+        if (stopFn !== null) stopFn();
+        else wantsStopEarly = true;
+    };
+
+    // ZERO-GC HOT PATH: the untrack body is hoisted into a closure allocated
+    // ONCE at registration time. If this were declared inline as
+    // `untrack(() => { ... })` inside the effect body, V8 would allocate a
+    // fresh closure on every fire — at 120fps that's 7,200 allocations per
+    // minute per watcher. The shared `currentNewValue` variable is the price
+    // for keeping the per-fire cost at exactly zero allocations.
+    const untrackedFire = () => {
+        if (oldValue === UNINITIALIZED) {
+            if (immediate) callback(currentNewValue, undefined, stop);
+        } else if (!Object.is(currentNewValue, oldValue)) {
+            callback(currentNewValue, oldValue, stop);
+        }
+        oldValue = currentNewValue;
+    };
+
+    stopFn = effect(() => {
+        currentNewValue = source();
+        untrack(untrackedFire);
+    });
+
+    // If the immediate callback called stop() before stopFn was assigned,
+    // honor it now.
+    if (wantsStopEarly) stopFn();
+    return stop;
+}
+
+/**
+ * Fire `callback` exactly once when `predicate` first returns a truthy value,
+ * then auto-dispose. If `predicate` is already truthy at registration, fires
+ * synchronously and disposes immediately.
+ *
+ * Models MobX's `when(predicate, effect)` semantics. The returned dispose
+ * function can be called to cancel the watcher before it fires (useful for
+ * conditional registration that should be revocable).
+ *
+ * @example  // Trigger on state transition
+ *   when(() => user.isAuthenticated, () => redirect("/dashboard"));
+ *
+ * @example  // Cancellable
+ *   const cancel = when(() => slow.ready, () => start());
+ *   if (userBacked) cancel();
+ *
+ * @param {() => unknown} predicate Reactive read function; fired when truthy.
+ * @param {() => void} callback     Called once when predicate first truthy.
+ *                                  Internal reads are untracked.
+ * @returns {() => void}            Dispose function. Idempotent.
+ */
+export function when(predicate, callback) {
+    let stopFn = null;
+    let wantsStopEarly = false;
+    let fired = false;
 
-    return effect(() => {
-        // Track the source — this read registers the dependency.
-        const newValue = source();
+    const stop = () => {
+        if (stopFn !== null) stopFn();
+        else wantsStopEarly = true;
+    };
 
-        // Invoke the callback without registering further dependencies.
-        untrack(() => {
-            if (oldValue === UNINITIALIZED) {
-                if (immediate) callback(newValue, undefined);
-            } else if (!Object.is(newValue, oldValue)) {
-                // Guard for raw inline getters: the effect re-runs whenever any read
-                // dep changes, but the projected source value may be unchanged. Vue's
-                // `watch` and MobX's `reaction` both short-circuit here. Wrapping the
-                // source in a `computed` would also suppress this via the equality
-                // check inside computed itself; the guard makes that wrapping optional.
-                callback(newValue, oldValue);
-            }
-            oldValue = newValue;
-        });
+    stopFn = effect(() => {
+        // Defense-in-depth: even if dispose timing lets one more evaluation
+        // through (e.g., during sync propagation), don't fire twice.
+        if (fired) return;
+        if (predicate()) {
+            fired = true;
+            untrack(callback);
+            stop();
+        }
     });
-}
+
+    if (wantsStopEarly) stopFn();
+    return stop;
+}
+
+/**
+ * Promise-returning variant of {@link when}. The returned promise resolves
+ * when `predicate` first returns a truthy value. Composes with `await` for
+ * declarative async control flow against reactive state.
+ *
+ * ⚠️ **HOT-PATH WARNING — DO NOT USE PER FRAME.** This function calls
+ * `new Promise(...)`, which is a heap allocation. Every call allocates a
+ * Promise object plus its executor closure plus internal Promise infrastructure
+ * (resolve function, microtask state). This is unavoidable — Promises require
+ * heap allocation by the language spec.
+ *
+ * **Use `whenAsync` for:** high-level scene/UI orchestration, boot sequences,
+ * waiting for user input, awaiting network state, level transitions. Anything
+ * that runs once or rarely.
+ *
+ * **NEVER use `whenAsync` for:** per-frame entity updates, render-loop logic,
+ * animation tick handlers, anywhere that runs at 60/120 fps. The Promise
+ * allocations will be visible in GC traces and will cause frame-time spikes
+ * under sustained load.
+ *
+ * **Zero-GC alternative:** use {@link when} with a callback. `when` is
+ * allocation-free per evaluation in its hot path (two closures total at
+ * registration, zero per predicate check).
+ *
+ * Note: this promise never rejects. If the predicate never becomes truthy,
+ * the promise never settles. Wrap in `Promise.race` for timeout semantics.
+ *
+ * @example  // ✅ OK — high-level orchestration
+ *   await whenAsync(() => user.isAuthenticated);
+ *   navigate("/dashboard");
+ *
+ * @example  // ✅ OK — boot sequence
+ *   await whenAsync(() => assets.loaded);
+ *   startGame();
+ *
+ * @example  // ❌ NOT OK — per-frame, allocates a Promise every frame
+ *   function animate() {
+ *       whenAsync(() => physics.settled).then(render);  // GC pressure!
+ *       requestAnimationFrame(animate);
+ *   }
+ *
+ * @example  // ✅ Same use case, zero-GC
+ *   when(() => physics.settled, render);  // no Promise, no GC pressure
+ *
+ * @example  // With timeout
+ *   await Promise.race([
+ *     whenAsync(() => api.ready),
+ *     new Promise((_, rej) => setTimeout(() => rej(new Error("timeout")), 5000))
+ *   ]);
+ *
+ * @param {() => unknown} predicate Reactive read function; resolves promise when truthy.
+ * @returns {Promise<void>}         Resolves when predicate first truthy.
+ */
+export function whenAsync(predicate) {
+    return new Promise((resolve) => when(predicate, resolve));
+}

package/llms.txt

@@ -117,6 +117,59 @@ class CapacityError extends Error {
 }
 ```
 
+## Watchers (added in v1.1)
+
+Three composable watcher primitives, all built from `effect` + `untrack`. Tree-shakeable.
+
+### watch(source, callback, options?)
+
+Fires callback on every change of the projected source value.
+
+- **Signature**: `watch<T>(source: () => T, callback: (newValue: T, oldValue: T | undefined, stop: () => void) => void, options?: { immediate?: boolean }): () => void`
+- **Returns**: dispose function. Idempotent. Safe to call synchronously inside the callback.
+- **options.immediate**: when `true`, callback fires once on registration with `oldValue = undefined`. Default `false`.
+- **Equality guard**: uses `Object.is(newValue, oldValue)` internally to avoid firing when the projected value is unchanged across dep mutations. Critical for raw getter sources like `() => health() <= 0` — many dep changes can produce the same boolean. Wrapping the source in `computed()` would achieve the same via the computed's own equality check.
+- **UNINITIALIZED sentinel**: uses `Symbol("watch.uninitialized")` instead of `undefined` to detect first-run. This means `signal(undefined)` is correctly distinguished from "watcher hasn't fired yet".
+- **Callback reads are untracked**: the callback can read other signals without registering them as dependencies.
+- **Stop in callback**: third callback argument is a stop handle. Safe to call at any point including synchronously during the immediate fire (the `wantsStopEarly` flag defers dispose until after the effect is registered).
+- **Allocation profile**: 3 closures at registration (stop, effect body, hoisted untrack body). **Zero allocations per fire** — the untrack body is hoisted with `currentNewValue` as shared mutable state. Hot-path safe at 120fps.
+
+### when(predicate, callback)
+
+Fires callback exactly once when predicate first returns truthy, then auto-disposes.
+
+- **Signature**: `when(predicate: () => unknown, callback: () => void): () => void`
+- **Returns**: dispose function. Useful for cancelling before predicate fires; idempotent; no-op after callback has fired.
+- **Synchronous fire**: if predicate is already truthy at registration, callback fires synchronously and watcher disposes immediately (same `wantsStopEarly` pattern as `watch`).
+- **One-shot guarantee**: internal `fired` flag protects against double-fire even if dispose timing lets one more evaluation through.
+- **Callback reads are untracked.**
+- **Truthy/falsy semantics**: standard JS truthy check. `0`, `""`, `null`, `undefined`, `false`, `NaN` do not trigger; everything else does.
+- **Allocation profile**: 2 closures at registration (stop, effect body). **Zero allocations per check** — `untrack(callback)` passes the user's callback directly without wrapping. Hot-path safe at 120fps.
+
+### whenAsync(predicate)
+
+Promise variant of `when`.
+
+- **Signature**: `whenAsync(predicate: () => unknown): Promise<void>`
+- **Returns**: Promise that resolves when predicate first becomes truthy.
+- **Implementation**: `return new Promise((resolve) => when(predicate, resolve))`.
+- **Foot-gun**: promise never rejects. If predicate never becomes truthy, promise never settles. Use `Promise.race` for timeout: `Promise.race([whenAsync(p), timeoutPromise])`.
+- **⚠️ HOT-PATH WARNING**: `new Promise(...)` is a heap allocation. Each call allocates 1 Promise + 1 executor closure + Promise infrastructure (resolve fn, microtask state) + 2 closures from internal `when` call. This is unavoidable — Promises require heap allocation by spec. **Do NOT call per frame.** Use for high-level orchestration (boot sequences, scene transitions, awaiting user input). For 60/120fps logic, use `when(predicate, callback)` directly — it's zero-GC.
+
+### Architecture note
+
+None of these touch the reactive engine — no `FLAG_WATCHER` on `ReactiveNode`, no extension to the object pool, no new internal primitive. They compose entirely from public API. This is the test that the core engine is structurally complete: when a higher-level pattern can be built without extending the engine, the engine has enough.
+
+### Allocation profile summary
+
+| Primitive | At registration | Per fire / check |
+|---|---|---|
+| `watch` | 3 closures | 0 |
+| `when` | 2 closures | 0 |
+| `whenAsync` | 1 Promise + executor + Promise internals + 2 closures (from `when`) | 0 |
+
+The deliberate engineering for `watch`'s "0 per fire" is the hoisted `untrackedFire` closure with `currentNewValue` shared mutable state — see source comment in `watch.js`. Inline arrow function inside the effect body would allocate per fire and break the zero-GC contract.
+
 ## Benchmark snapshot (Node 22, 2016-era Intel MacBook Pro, 20K iter × 5 runs × 50+ invocations)
 
 | Scenario                                | lite-signal | alien-signals | preact   | solid    |
@@ -188,6 +241,8 @@ sandbox.destroy();   // entire reactive world reset
 - `test/05-scheduler.test.mjs` — scheduler races, dispose, gen counter, version wrap.
 - `test/06-nested-objects.test.mjs` — nested-object & reference-identity behaviours.
 - `test/07-dispose.test.mjs` — universal disposal: registry.dispose(api).
+- `test/08-watch.test.mjs` — new watch reactivity tests.
+- `test/09-conformance.test.mjs` — johnsoncodehk/reactive-framework-test-suite conformance fixes tests.
 - `bench/bench.mjs`           — comparative benchmark vs alien-signals, preact, solid.
 - `demo/index.html`           — interactive visualization of the reactive graph.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal",
-  "version": "1.0.6",
+  "version": "1.1.1",
   "description": "Zero-GC reactive graph. Monomorphic object pool, versioned push-pull propagation, 32-bit modular versioning. Built for hot paths and long-running processes.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",