@zakkster/lite-signal 1.0.5 → 1.1.0

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,79 @@ 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.
+
+**167 of 177 tests pass (94.4%)**, placing lite-signal **fifth of sixteen**
+evaluated libraries — behind alien-signals (177), @preact/signals-core (174),
+@reatom/core (173), and @vue/reactivity (170), and ahead of anod, solid-js,
+tansu, @solidjs/signals, the TC39 signals polyfill, mobx, Angular signals,
+Svelte, S.js, and reactively.
+
+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,3 +165,78 @@ 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.
+ */
+export interface WatchOptions {
+    /** * If true, fires the callback immediately upon registration
+     * with `oldValue` set to `undefined`.
+     */
+    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;
+
+/**
+ * Promise-returning variant of {@link when}. The returned promise resolves
+ * when `predicate` first returns a truthy value.
+ *
+ * ⚠️ **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.
+ *
+ * **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 whenAsync(
+    predicate: () => unknown
+): Promise<void>;

package/Signal.js

@@ -68,6 +68,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;
@@ -244,10 +245,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 +274,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 +340,7 @@ export function createRegistry(config = {}) {
         node.tailDep = null;
         node.currentDep = null;
         node.headSub = null;
+        node.tailSub = null;
 
         node.gen = (node.gen + 1) | 0;
         node.nextFree = freeNodeHead;
@@ -382,6 +388,7 @@ 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;
@@ -391,10 +398,19 @@ export function createRegistry(config = {}) {
     /** 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;
         }
     }
 
@@ -541,6 +557,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;
@@ -910,6 +932,7 @@ 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;
@@ -1004,4 +1027,17 @@ export function onCleanup(fn) {
 /** @type {Registry["stats"]} */
 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, when, whenAsync} from "./Watch.js"

package/Watch.js

@@ -0,0 +1,192 @@
+import { effect, untrack } from "./Signal.js";
+
+/**
+ * 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 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).
+ *
+ * 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.
+ *
+ * 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(prev, "→", next));
+ *   count.set(1);  // logs: 0 → 1
+ *   stop();
+ *
+ * @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;
+
+    const stop = () => {
+        if (stopFn !== null) stopFn();
+        else wantsStopEarly = true;
+    };
+
+    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.5",
+  "version": "1.1.0",
   "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",
@@ -18,6 +18,7 @@
   "files": [
     "Signal.js",
     "Signal.d.ts",
+    "Watch.js",
     "README.md",
     "llms.txt",
     "LICENSE.txt"