@esportsplus/reactivity 0.32.0 → 0.33.0

package/README.md

@@ -1,5 +1,7 @@
 # @esportsplus/reactivity
 
+Project doc bundle: [docs/index.md](./docs/index.md) — rejected dead-ends, skip reasons, completed-work index.
+
 A fine-grained reactivity system with compile-time transformations. Write reactive code with natural JavaScript syntax while the compiler generates optimized signal-based code.
 
 ## Installation
@@ -313,6 +315,34 @@ All standard array methods (`push`, `pop`, `shift`, `unshift`, `splice`, `sort`,
 | `splice` | `{ start, deleteCount, items }` | Array was spliced |
 | `unshift` | `{ items: T[] }` | Items were unshifted |
 
+## Architecture
+
+- `src/system.ts` — the core signal/computed/effect engine: height-bucketed heap scheduler,
+  generation-version dependency dedup (read-version dedup), and iterative (non-recursive)
+  notify/update/dispose walks. Also supports async (Promise/AsyncIterable) computeds and
+  per-key selector signals (`signal.selector`).
+- `src/constants.ts` — shared state bitmasks and symbol constants consumed by every other module.
+- `src/types.ts` — shared `Signal`/`Computed`/`Link`/`Reactive` types.
+- `src/reactive/index.ts`, `src/reactive/array.ts`, `src/reactive/object.ts` — the runtime
+  `reactive()` dispatch and the `ReactiveObject`/`ReactiveArray` classes it builds on.
+- `src/compiler/*` — the build-time transform pipeline (`constants.ts`, `primitives.ts`,
+  `object.ts`, `array.ts`, `index.ts`) plus the `plugins/tsc.ts` and `plugins/vite.ts`
+  entrypoints that wire it into a build (see Transformer Plugins above).
+
+## Development
+
+```bash
+pnpm install
+pnpm build   # tsc
+pnpm test    # vitest run
+pnpm bench   # vitest bench --run
+```
+
+`agent:test` (`tsc --noEmit && vitest run`) and `agent:bench` (`vitest bench --run`) are the
+CI-facing aliases of the same build/test/bench commands.
+
 ## License
 
 MIT
+
+<!-- claude-code:readme-source-hash: 189167a17e9be8c6 -->

package/build/reactive/array.d.ts

@@ -41,6 +41,9 @@ declare class ReactiveArray<T> extends Array<T> {
     private _length;
     listeners: Listeners<T>;
     constructor(...items: T[]);
+    static get [Symbol.species](): ArrayConstructor;
+    get $length(): number;
+    set $length(value: number);
     $set(i: number, value: T): void;
     clear(): void;
     concat(...items: ConcatArray<T>[]): ReactiveArray<T>;
@@ -56,7 +59,5 @@ declare class ReactiveArray<T> extends Array<T> {
     sort(fn?: (a: T, b: T) => number): this;
     splice(start: number, deleteCount?: number, ...items: T[]): T[];
     unshift(...items: T[]): number;
-    get $length(): number;
-    set $length(value: number);
 }
 export { ReactiveArray };

package/build/reactive/array.js

@@ -14,6 +14,18 @@ class ReactiveArray extends Array {
         super(...items);
         this._length = signal(items.length);
     }
+    static get [Symbol.species]() {
+        return Array;
+    }
+    get $length() {
+        return read(this._length);
+    }
+    set $length(value) {
+        if (value > this.length) {
+            throw Error(`@esportsplus/reactivity: cannot set length to a value larger than the current length, use splice instead.`);
+        }
+        this.splice(value, this.length);
+    }
     $set(i, value) {
         let prev = this[i];
         if (prev === value) {
@@ -146,29 +158,34 @@ class ReactiveArray extends Array {
         return item;
     }
     sort(fn) {
-        let n = this.length, before = new Array(n);
-        for (let i = 0; i < n; i++) {
-            before[i] = this[i];
-        }
-        super.sort(fn);
-        let buckets = new Map(), order = new Array(n);
-        for (let i = 0; i < n; i++) {
-            let value = before[i], list = buckets.get(value);
-            if (!list) {
-                buckets.set(value, [i]);
+        if (this.listeners.sort === undefined) {
+            super.sort(fn);
+        }
+        else {
+            let n = this.length, before = new Array(n);
+            for (let i = 0; i < n; i++) {
+                before[i] = this[i];
             }
-            else {
-                list.push(i);
+            super.sort(fn);
+            let buckets = new Map(), order = new Array(n);
+            for (let i = 0; i < n; i++) {
+                let value = before[i], list = buckets.get(value);
+                if (!list) {
+                    buckets.set(value, [i]);
+                }
+                else {
+                    list.push(i);
+                }
             }
-        }
-        for (let i = 0; i < n; i++) {
-            let list = buckets.get(this[i]);
-            order[i] = list.length === 1 ? list[0] : list[list.length - 1];
-            if (list.length > 1) {
-                list.pop();
+            for (let i = 0; i < n; i++) {
+                let list = buckets.get(this[i]);
+                order[i] = list.length === 1 ? list[0] : list[list.length - 1];
+                if (list.length > 1) {
+                    list.pop();
+                }
             }
+            this.dispatch('sort', { order });
         }
-        this.dispatch('sort', { order });
         return this;
     }
     splice(start, deleteCount = this.length, ...items) {
@@ -191,15 +208,6 @@ class ReactiveArray extends Array {
         this.dispatch('unshift', { items });
         return length;
     }
-    get $length() {
-        return read(this._length);
-    }
-    set $length(value) {
-        if (value > this.length) {
-            throw Error(`@esportsplus/reactivity: cannot set length to a value larger than the current length, use splice instead.`);
-        }
-        this.splice(value, this.length);
-    }
 }
 Object.defineProperty(ReactiveArray.prototype, REACTIVE_ARRAY, { value: true });
 export { ReactiveArray };

package/build/reactive/object.d.ts

@@ -4,7 +4,7 @@ import { ReactiveArray } from './array.js';
 declare class ReactiveObject<T extends Record<PropertyKey, unknown>> {
     protected disposers: VoidFunction[] | null;
     constructor(data: T | null);
-    protected [COMPUTED]<T extends Computed<ReturnType<T>>['fn']>(value: T): Computed<import("../types.js").Settled<ReturnType<T>>>;
+    protected [COMPUTED]<T extends Computed<ReturnType<T>>['fn']>(value: T): import("../types.js").ComputedResult<ReturnType<T>>;
     protected [REACTIVE_ARRAY]<U>(value: U[]): ReactiveArray<U>;
     protected [SIGNAL]<T>(value: T): import("../types.js").Signal<T>;
     dispose(): void;

package/build/system.d.ts

@@ -1,11 +1,11 @@
-import { Computed, Settled, Signal } from './types.js';
+import { Computed, ComputedResult, Settled, Signal } from './types.js';
 declare const batch: <T>(fn: () => T) => T;
 declare const computed: {
-    <T>(fn: Computed<T>["fn"], equals?: ((a: Settled<T>, b: Settled<T>) => boolean) | null): Computed<Settled<T>>;
+    <T>(fn: Computed<T>["fn"], equals?: ((a: Settled<T>, b: Settled<T>) => boolean) | null): ComputedResult<T>;
     invalidate<T>(c: Computed<T>): void;
 };
 declare const dispose: <T>(computed: Computed<T>) => void;
-declare const effect: <T>(fn: Computed<T>["fn"], onError?: (e: unknown) => void) => () => void;
+declare const effect: <T>(fn: Computed<T>["fn"], apply?: (value: T, prev: T | undefined) => void) => () => void;
 declare const flush: () => void;
 declare const isComputed: (value: unknown) => value is Computed<unknown>;
 declare const isSignal: (value: unknown) => value is Signal<unknown>;

package/build/system.js

@@ -412,18 +412,23 @@ function update(root) {
     }
 }
 function makeAsyncComputed(factory) {
-    let error = signal(undefined), node = signal(undefined), v = 0;
+    let error = signal(undefined), node = signal(undefined), pending = signal(false), v = 0;
     let stop = effect(() => {
         let fail = (e) => {
             if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
                 write(error, e === undefined ? new Error('reactivity: async computed rejected with undefined') : e);
+                write(pending, false);
             }
         }, id = ++v, result = read(factory);
         if (isPromise(result)) {
+            if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
+                write(pending, true);
+            }
             result.then((value) => {
                 if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
                     write(error, undefined);
                     write(node, value);
+                    write(pending, false);
                 }
             }, fail);
         }
@@ -439,14 +444,22 @@ function makeAsyncComputed(factory) {
                 if (!r.done) {
                     write(error, undefined);
                     write(node, r.value);
+                    write(pending, false);
                     it.next().then(step, fail);
                 }
+                else {
+                    write(pending, false);
+                }
             };
+            if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
+                write(pending, true);
+            }
             untrack(() => it.next()).then(step, fail);
         }
         else {
             write(error, undefined);
             write(node, result);
+            write(pending, false);
         }
     });
     let wrapper = makeComputed(() => {
@@ -456,6 +469,7 @@ function makeAsyncComputed(factory) {
         }
         return read(node);
     });
+    wrapper.pending = pending;
     asyncMeta.set(wrapper, { factory: factory });
     wrapper.disposal = stop;
     return wrapper;
@@ -574,15 +588,14 @@ const dispose = (computed) => {
         draining = false;
     }
 };
-const effect = (fn, onError) => {
-    let c = makeComputed(onError
+const effect = (fn, apply) => {
+    let prev;
+    let c = makeComputed(apply
         ? (o) => {
-            try {
-                return fn(o);
-            }
-            catch (e) {
-                onError(e);
-            }
+            let v = fn(o);
+            untrack(() => apply(v, prev));
+            prev = v;
+            return v;
         }
         : fn);
     c.state |= STATE_EFFECT;
@@ -681,9 +694,12 @@ root.disposables = 0;
 const signal = (value, equals = null) => {
     return {
         equals: equals,
+        key: undefined,
         keys: null,
         nextPending: null,
+        parent: undefined,
         rv: 0,
+        state: 0,
         subs: null,
         subsTail: null,
         type: SIGNAL,
@@ -703,6 +719,7 @@ signal.selector = (node, key) => {
             nextPending: null,
             parent: node,
             rv: 0,
+            state: 0,
             subs: null,
             subsTail: null,
             type: SIGNAL,

package/build/types.d.ts

@@ -19,6 +19,9 @@ interface Computed<T> {
     subsTail: Link | null;
     value: T;
 }
+type ComputedResult<T> = T extends Promise<any> | AsyncIterable<any> ? Computed<Settled<T>> & {
+    pending: Signal<boolean>;
+} : Computed<Settled<T>>;
 interface Link {
     dep: Signal<unknown> | Computed<unknown>;
     nextDep: Link | null;
@@ -42,9 +45,12 @@ type SelectorSignal<T> = Signal<boolean> & {
 type Settled<T> = T extends Promise<infer U> ? Awaited<U> | undefined : T extends AsyncIterable<infer U> ? U | undefined : T;
 type Signal<T> = {
     equals: ((a: unknown, b: unknown) => boolean) | null;
+    key: unknown;
     keys: Map<T, SelectorSignal<T>> | null;
     nextPending: Signal<unknown> | null;
+    parent: Signal<unknown> | undefined;
     rv: number;
+    state: number;
     subs: Link | null;
     subsTail: Link | null;
     type: typeof SIGNAL;
@@ -55,4 +61,4 @@ interface TransformResult {
     code: string;
     sourceFile: ts.SourceFile;
 }
-export type { Computed, Link, Reactive, SelectorSignal, Settled, Signal, TransformResult };
+export type { Computed, ComputedResult, Link, Reactive, SelectorSignal, Settled, Signal, TransformResult };

package/package.json

@@ -1,13 +1,13 @@
 {
   "author": "ICJR",
   "dependencies": {
-    "@esportsplus/utilities": "^0.27.3"
+    "@esportsplus/utilities": "^0.28.0"
   },
   "devDependencies": {
-    "@esportsplus/typescript": "^0.29.1",
-    "@types/node": "^25.6.0",
-    "vite": "^8.0.8",
-    "vitest": "^4.1.4"
+    "@esportsplus/typescript": "^0.29.5",
+    "@types/node": "^26.1.1",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
   },
   "exports": {
     ".": {
@@ -36,7 +36,7 @@
   },
   "type": "module",
   "types": "build/index.d.ts",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "scripts": {
     "agent:bench": "vitest bench --run",
     "agent:test": "tsc --noEmit && vitest run",

package/src/reactive/array.ts

@@ -54,7 +54,10 @@ function dispose(value: unknown) {
 }
 
 
+// Derived arrays (splice removals, map/filter/slice) must be plain Arrays: species-creating a
+// ReactiveArray runs the reactive constructor per call and seeds _length from the length argument.
 class ReactiveArray<T> extends Array<T> {
+
     private _length: Signal<number>;
 
     listeners: Listeners<T> = {};
@@ -66,6 +69,24 @@ class ReactiveArray<T> extends Array<T> {
     }
 
 
+    static get [Symbol.species]() {
+        return Array;
+    }
+
+
+    get $length() {
+        return read(this._length);
+    }
+
+    set $length(value: number) {
+        if (value > this.length) {
+            throw Error(`@esportsplus/reactivity: cannot set length to a value larger than the current length, use splice instead.`);
+        }
+
+        this.splice(value, this.length);
+    }
+
+
     $set(i: number, value: T) {
         let prev = this[i];
 
@@ -204,7 +225,6 @@ class ReactiveArray<T> extends Array<T> {
         if (item !== undefined) {
             dispose(item);
             write(this._length, this.length);
-
             this.dispatch('pop', { item });
         }
 
@@ -219,6 +239,7 @@ class ReactiveArray<T> extends Array<T> {
         let length = super.push(...items);
 
         write(this._length, length);
+
         this.dispatch('push', { items });
 
         return length;
@@ -237,7 +258,6 @@ class ReactiveArray<T> extends Array<T> {
         if (item !== undefined) {
             dispose(item);
             write(this._length, this.length);
-
             this.dispatch('shift', { item });
         }
 
@@ -245,41 +265,46 @@ class ReactiveArray<T> extends Array<T> {
     }
 
     sort(fn?: (a: T, b: T) => number) {
-        let n = this.length,
-            before = new Array(n) as T[];
-
-        for (let i = 0; i < n; i++) {
-            before[i] = this[i];
+        if (this.listeners.sort === undefined) {
+            super.sort(fn);
         }
+        else {
+            let n = this.length,
+                before = new Array(n) as T[];
 
-        super.sort(fn);
+            for (let i = 0; i < n; i++) {
+                before[i] = this[i];
+            }
 
-        let buckets = new Map<T, number[]>(),
-            order = new Array(n);
+            super.sort(fn);
 
-        for (let i = 0; i < n; i++) {
-            let value = before[i],
-                list = buckets.get(value);
+            let buckets = new Map<T, number[]>(),
+                order = new Array(n);
 
-            if (!list) {
-                buckets.set(value, [i]);
-            }
-            else {
-                list.push(i);
+            for (let i = 0; i < n; i++) {
+                let value = before[i],
+                    list = buckets.get(value);
+
+                if (!list) {
+                    buckets.set(value, [i]);
+                }
+                else {
+                    list.push(i);
+                }
             }
-        }
 
-        for (let i = 0; i < n; i++) {
-            let list = buckets.get(this[i])!;
+            for (let i = 0; i < n; i++) {
+                let list = buckets.get(this[i])!;
 
-            order[i] = list.length === 1 ? list[0] : list[list.length - 1];
+                order[i] = list.length === 1 ? list[0] : list[list.length - 1];
 
-            if (list.length > 1) {
-                list.pop();
+                if (list.length > 1) {
+                    list.pop();
+                }
             }
-        }
 
-        this.dispatch('sort', { order });
+            this.dispatch('sort', { order });
+        }
 
         return this;
     }
@@ -312,19 +337,6 @@ class ReactiveArray<T> extends Array<T> {
 
         return length;
     }
-
-
-    get $length() {
-        return read(this._length);
-    }
-
-    set $length(value: number) {
-        if (value > this.length) {
-            throw Error(`@esportsplus/reactivity: cannot set length to a value larger than the current length, use splice instead.`);
-        }
-
-        this.splice(value, this.length);
-    }
 }
 
 Object.defineProperty(ReactiveArray.prototype, REACTIVE_ARRAY, { value: true });

package/src/system.ts

@@ -4,7 +4,7 @@ import {
     STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED,
     STATE_CHECK, STATE_COMPUTED, STATE_DIRTY, STATE_EFFECT, STATE_ERROR, STATE_IN_HEAP, STATE_NOTIFY_MASK, STATE_RECOMPUTING
 } from './constants';
-import { Computed, Link, SelectorSignal, Settled, Signal } from './types';
+import { Computed, ComputedResult, Link, SelectorSignal, Settled, Signal } from './types';
 import { isObject, isPromise } from '@esportsplus/utilities';
 
 
@@ -613,12 +613,14 @@ function update<T>(root: Computed<T>): void {
 function makeAsyncComputed<T>(factory: Computed<Promise<T> | AsyncIterable<T> | T>): Computed<T | undefined> {
     let error = signal<unknown>(undefined),
         node = signal<T | undefined>(undefined),
+        pending = signal(false),
         v = 0;
 
     let stop = effect(() => {
         let fail = (e: unknown) => {
                 if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
                     write(error, e === undefined ? new Error('reactivity: async computed rejected with undefined') : e);
+                    write(pending, false);
                 }
             },
             id = ++v,
@@ -626,11 +628,16 @@ function makeAsyncComputed<T>(factory: Computed<Promise<T> | AsyncIterable<T> |
             result = read(factory);
 
         if (isPromise(result)) {
+            if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
+                write(pending, true);
+            }
+
             (result as Promise<T>).then(
                 (value) => {
                     if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
                         write(error, undefined);
                         write(node, value);
+                        write(pending, false);
                     }
                 },
                 fail
@@ -651,15 +658,24 @@ function makeAsyncComputed<T>(factory: Computed<Promise<T> | AsyncIterable<T> |
                 if (!r.done) {
                     write(error, undefined);
                     write(node, r.value);
+                    write(pending, false);
                     it.next().then(step, fail);
                 }
+                else {
+                    write(pending, false);
+                }
             };
 
+            if (id === v && !(factory.state & (STATE_IN_HEAP | STATE_NOTIFY_MASK))) {
+                write(pending, true);
+            }
+
             untrack(() => it.next()).then(step, fail);
         }
         else {
             write(error, undefined);
             write(node, result as T);
+            write(pending, false);
         }
     });
 
@@ -673,6 +689,8 @@ function makeAsyncComputed<T>(factory: Computed<Promise<T> | AsyncIterable<T> |
             return read(node);
         });
 
+    (wrapper as Computed<T | undefined> & { pending: Signal<boolean> }).pending = pending;
+
     asyncMeta.set(wrapper as Computed<unknown>, { factory: factory as Computed<unknown> });
     wrapper.disposal = stop;
 
@@ -753,7 +771,7 @@ const batch = <T>(fn: () => T): T => {
 
 // A fn returning a Promise or AsyncIterable transparently becomes an async computed: the first run is
 // the probe, reused as the factory (no duplicate dispatch). A plain fn returns the node directly.
-const computed = <T>(fn: Computed<T>['fn'], equals: ((a: Settled<T>, b: Settled<T>) => boolean) | null = null): Computed<Settled<T>> => {
+const computed = <T>(fn: Computed<T>['fn'], equals: ((a: Settled<T>, b: Settled<T>) => boolean) | null = null): ComputedResult<T> => {
     // eager probe so self.value carries fn's return even when this is a non-first tracked op — the
     // detection below cannot depend on the deferred branch, which never runs fn synchronously.
     let o = observer,
@@ -774,7 +792,7 @@ const computed = <T>(fn: Computed<T>['fn'], equals: ((a: Settled<T>, b: Settled<
 
     self.equals = equals as ((a: unknown, b: unknown) => boolean) | null;
 
-    return self as Computed<Settled<T>>;
+    return self as unknown as ComputedResult<T>;
 };
 
 // Forces a re-derivation without the dummy-signal-dependency hack. writes++ FIRST so a gv-stamped
@@ -803,7 +821,6 @@ const dispose = <T>(computed: Computed<T>): void => {
     // processed inline (no worklist node) and the pool is touched only for re-entrant deep cascades.
     if (draining) {
         disposeHead = walkPush(computed as Computed<unknown>, null, disposeHead);
-
         return;
     }
 
@@ -847,16 +864,18 @@ const dispose = <T>(computed: Computed<T>): void => {
     }
 };
 
-const effect = <T>(fn: Computed<T>['fn'], onError?: (e: unknown) => void) => {
+const effect = <T>(fn: Computed<T>['fn'], apply?: (value: T, prev: T | undefined) => void) => {
+    let prev: T | undefined;
+
     let c = makeComputed<T | undefined>(
-            onError
+            apply
                 ? (o) => {
-                    try {
-                        return fn(o);
-                    }
-                    catch (e) {
-                        onError(e);
-                    }
+                    let v = fn(o);
+
+                    untrack(() => apply(v, prev));
+                    prev = v;
+
+                    return v;
                 }
                 : fn
         );
@@ -1001,9 +1020,12 @@ root.disposables = 0;
 const signal = <T>(value: T, equals: ((a: T, b: T) => boolean) | null = null): Signal<T> => {
     return {
         equals: equals as ((a: unknown, b: unknown) => boolean) | null,
+        key: undefined,
         keys: null,
         nextPending: null,
+        parent: undefined,
         rv: 0,
+        state: 0,
         subs: null,
         subsTail: null,
         type: SIGNAL,
@@ -1029,6 +1051,7 @@ signal.selector = <T>(node: Signal<T>, key: T): boolean => {
             nextPending: null,
             parent: node,
             rv: 0,
+            state: 0,
             subs: null,
             subsTail: null,
             type: SIGNAL,

package/src/types.ts

@@ -22,6 +22,11 @@ interface Computed<T> {
     value: T;
 }
 
+type ComputedResult<T> =
+    T extends Promise<any> | AsyncIterable<any>
+        ? Computed<Settled<T>> & { pending: Signal<boolean> }
+        : Computed<Settled<T>>;
+
 interface Link {
     dep: Signal<unknown> | Computed<unknown>;
     nextDep: Link | null;
@@ -56,9 +61,12 @@ type Settled<T> =
 
 type Signal<T> = {
     equals: ((a: unknown, b: unknown) => boolean) | null;
+    key: unknown;
     keys: Map<T, SelectorSignal<T>> | null;
     nextPending: Signal<unknown> | null;
+    parent: Signal<unknown> | undefined;
     rv: number;
+    state: number;
     subs: Link | null;
     subsTail: Link | null;
     type: typeof SIGNAL;
@@ -74,6 +82,7 @@ interface TransformResult {
 
 export type {
     Computed,
+    ComputedResult,
     Link,
     Reactive,
     SelectorSignal,

package/test/async-computed.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { computed, dispose, effect, isComputed, isSignal, read, root, signal, write } from '~/system';
 import { tick, waitFor } from './lib/wait-for';
-import type { Computed } from '~/system';
+import type { Computed, Signal } from '~/system';
 
 
 describe('asyncComputed', () => {
@@ -295,6 +295,92 @@ describe('asyncComputed', () => {
         expect(read(node)).toBe(3);
     });
 
+    it('pending toggles true then false across a resolving promise', async () => {
+        let node!: Computed<number | undefined> & { pending: Signal<boolean> },
+            resolve!: (v: number) => void;
+
+        root(() => {
+            node = computed(() => new Promise<number>((r) => {
+                resolve = r;
+            }));
+        });
+
+        // The polling effect dispatches synchronously at creation — in flight now
+        expect(read(node.pending)).toBe(true);
+        expect(read(node)).toBeUndefined();
+
+        resolve(42);
+        await waitFor(() => read(node) === 42, 'node resolves to 42');
+
+        expect(read(node)).toBe(42);
+        expect(read(node.pending)).toBe(false);
+    });
+
+    it('pending rises on refetch while the value stays stale', async () => {
+        let node!: Computed<number | undefined> & { pending: Signal<boolean> },
+            resolvers: ((v: number) => void)[] = [],
+            s = signal(1);
+
+        root(() => {
+            node = computed(() => {
+                read(s);
+
+                return new Promise<number>((r) => {
+                    resolvers.push(r);
+                });
+            });
+        });
+
+        expect(read(node.pending)).toBe(true);
+
+        resolvers[0](10);
+        await waitFor(() => read(node) === 10, 'node settles to 10');
+
+        expect(read(node)).toBe(10);
+        expect(read(node.pending)).toBe(false);
+
+        // Refetch — dependency change re-dispatches the factory
+        write(s, 2);
+        await waitFor(() => resolvers.length === 2, 'refetch dispatched');
+
+        // stale-while-revalidate: value stays 10, but pending rises to signal the in-flight fetch
+        expect(read(node)).toBe(10);
+        expect(read(node.pending)).toBe(true);
+
+        resolvers[1](20);
+        await waitFor(() => read(node) === 20, 'node settles to 20');
+
+        expect(read(node)).toBe(20);
+        expect(read(node.pending)).toBe(false);
+    });
+
+    it('pending clears on rejection', async () => {
+        let node!: Computed<number | undefined> & { pending: Signal<boolean> },
+            reject!: (e: Error) => void;
+
+        root(() => {
+            node = computed(() => new Promise<number>((_, r) => {
+                reject = r;
+            }));
+        });
+
+        expect(read(node.pending)).toBe(true);
+
+        reject(new Error('boom'));
+        await waitFor(() => read(node.pending) === false, 'pending clears after rejection');
+
+        expect(read(node.pending)).toBe(false);
+        expect(() => read(node)).toThrow('boom');
+    });
+
+    it('sync computed has no pending', () => {
+        root(() => {
+            let node = computed(() => 42);
+
+            expect((node as { pending?: unknown }).pending).toBeUndefined();
+        });
+    });
+
     it('disposing the returned computed stops the polling effect and the factory', async () => {
         let calls = 0,
             s = signal(1);

package/test/effects.test.ts

@@ -269,3 +269,65 @@ describe('effect patterns', () => {
         });
     });
 });
+
+
+describe('effect apply phase', () => {
+    it('apply receives (value, prev) after each run', async () => {
+        let calls: [number, number | undefined][] = [],
+            s = signal(1);
+
+        effect(
+            () => read(s),
+            (value, prev) => {
+                calls.push([value, prev]);
+            }
+        );
+
+        expect(calls).toEqual([[1, undefined]]);
+
+        write(s, 2);
+        await Promise.resolve();
+
+        expect(calls).toEqual([[1, undefined], [2, 1]]);
+
+        write(s, 3);
+        await Promise.resolve();
+
+        expect(calls).toEqual([[1, undefined], [2, 1], [3, 2]]);
+    });
+
+    it('apply runs untracked — its reads do not subscribe', async () => {
+        let applied: number[] = [],
+            runs = 0,
+            s = signal(1),
+            t = signal(100);
+
+        effect(
+            () => {
+                runs++;
+
+                return read(s);
+            },
+            (value) => {
+                applied.push(value + read(t));
+            }
+        );
+
+        expect(runs).toBe(1);
+        expect(applied).toEqual([101]);
+
+        // apply read t untracked, so writing t must NOT re-run the effect
+        write(t, 200);
+        await Promise.resolve();
+
+        expect(runs).toBe(1);
+        expect(applied).toEqual([101]);
+
+        // writing s re-runs fn; apply then reads the current t (200)
+        write(s, 2);
+        await Promise.resolve();
+
+        expect(runs).toBe(2);
+        expect(applied).toEqual([101, 202]);
+    });
+});

package/test/errors.test.ts

@@ -174,19 +174,19 @@ describe('effect error contract', () => {
         stop();
     });
 
-    it('effect onError receives the error and nothing rethrows', async () => {
+    it('effect catching its own error internally rethrows nothing', async () => {
         let errors: unknown[] = [],
             s = signal(0),
-            stop = effect(
-                () => {
+            stop = effect(() => {
+                try {
                     if (read(s) === 1) {
                         throw new Error('handled');
                     }
-                },
-                (e) => {
+                }
+                catch (e) {
                     errors.push(e);
                 }
-            );
+            });
 
         let captured = await captureUncaught(() => {
             write(s, 1);

package/test/system.test.ts

@@ -1031,14 +1031,14 @@ describe('edge cases', () => {
                 return val * 10;
             });
 
-        effect(
-            () => {
+        effect(() => {
+            try {
                 effectValues.push(read(c));
-            },
-            (e) => {
+            }
+            catch (e) {
                 effectErrors.push(e);
             }
-        );
+        });
 
         expect(effectValues).toEqual([0]);
 
@@ -1072,14 +1072,14 @@ describe('edge cases', () => {
                 return val;
             });
 
-        effect(
-            () => {
+        effect(() => {
+            try {
                 effectValues.push(read(c));
-            },
-            (e) => {
+            }
+            catch (e) {
                 effectErrors.push(e);
             }
-        );
+        });
 
         expect(effectValues).toEqual([0]);
 

package/.claude/CHANGELOG.md

@@ -1,43 +0,0 @@
-# Changelog
-
-## Completed
-- [relocate-benchmarks] 567bd82. Relocate 7 benches to bench/ mirror + config, delete tests/ — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
-- [relocate-test-suites] 26fa1017. Relocate 23 suites to test/ mirror + config — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
-- [waitfor-test-helper] fa0a934a. waitFor/tick helper replacing 50 fixed-sleep sync sites — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
-- [compiler-import-order] 2610d50d. Normalize import order across compiler modules — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
-- [reactive-index-cleanup] 00b21810. reactive() facade unknown-bridges + import order — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
-- [reactive-array-cleanup] e0aa8b86. ReactiveArray listener typing, sort map, accessor order, imports — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
-- [system-any-casts] b890f047. Eliminate any casts in system.ts (unknown-bridged pool sentinels) — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
-- abandoned spend: ~$199.51 equivalent API cost across 7 terminal non-COMPLETED item(s) (system-any-casts, reactive-array-cleanup, reactive-index-cleanup, compiler-import-order, waitfor-test-helper, relocate-test-suites, relocate-benchmarks); recorded, not divided into per-item costs (run 36ee71d0)
-- run-level spend: ~$0.98 equivalent API cost (warm implementer runs + unit-scoped + boundary seats; never divided across items; blended rate = mean(input, output, cache_read, cache_creation) per million tokens) (run 36ee71d0)
-- [constants-export-order] 84f0b3613de0076e070ba4ddcd69c3e0d68a9f3a. Deviations: none; ladder: 3 attempts (critic → replanner completed → critic), completed. Cost: ~$20.03 equivalent API cost (blended-rate approximation). · spec: spec-coding-standards
-- [compiler-const-enum] 1b252cd2180063eefc04bf2b221ce4e9eff969a5. Deviations: none; ladder: 3 attempts (critic → replanner completed → critic), completed. Cost: ~$34.13 equivalent API cost (blended-rate approximation). · spec: spec-coding-standards
-- [types-variadic-any] da6b4873d4238db26d0d75f19a67f8c966a01b83. Deviations: none; ladder: 3 attempts (critic → replanner completed → critic), completed. Cost: ~$47.04 equivalent API cost (blended-rate approximation). · spec: spec-coding-standards
-- [reactive-object-cleanup] 769d007e46a9f6b0b299c2c3d48fa55dffe29628. Deviations: none; ladder: 3 attempts (critic → replanner completed → critic), completed. Cost: ~$32.61 equivalent API cost (blended-rate approximation). · spec: spec-coding-standards
-- cost source of truth: ccusage per-model breakdown (local transcripts carry the input/output/cache split the run journal does not) — figures above are a blended-rate approximation per contracts/models.json pricing (run 36ee71d0)
-- [recursion-free-walks] 143d5591. Recursion-free notify(), update(), and dispose()/unlink() walks — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next-2
-- [unobserved-hooks] b7a93aa4. onUnobserved() — last-subscriber lifecycle hook — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next-2
-- [invalidate] 60df87ae. invalidate() — standalone re-derivation of any computed — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next-2
-- [custom-equals] a4cb4e04. Custom equals on signal() and computed() — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next-2
-- follow-up discharged (completed) from spec-signals-next: pending-only-writes: complete full shape — selector recursive fan-out + nextPend… — evidence: 6a9b8e6
-- abandoned spend: ~$206.41 equivalent API cost across 4 terminal non-COMPLETED item(s) (custom-equals, invalidate, unobserved-hooks, recursion-free-walks); recorded, not divided into per-item costs (run 3306873d)
-- run-level spend: ~$2.11 equivalent API cost (warm implementer runs + unit-scoped + boundary seats; never divided across items; blended rate = mean(input, output, cache_read, cache_creation) per million tokens) (run 3306873d)
-- [async-iterable-resolve] 17b3878753d238869fdf6723dff468705d2795f8. Deviations: deviated — resolve()'s 'rejects when the tracked expression throws' was split into its own it() rather than combined into one test with the resolve-success case, matching the file's one-scenario-per-it convention from tests/async-hardening.ts; both scenarios from Design test 6 are covered.; added — Verified async generator .return() timing empirically (a queued return() on a generator suspended mid an unresolved internal await does not settle until that await resolves) via a throwaway Node script before writing tests 1-3, since the Design's prose doesn't spell out that an abandoned generator's pending gate must be released for its finally to run; tests 1-3 release the old generation's gate to observe closure, consistent with test 3's own description.; added — Added a gate()/tick() test-local helper pair (not in Design) to keep the generator-gating boilerplate readable across tests 1-5; mirrors async-hardening.ts's resolver-array convention.; ladder: 1 attempt (critic), completed. Cost: ~$16.19 equivalent API cost (blended-rate approximation). · spec: spec-signals-next-2
-- cost source of truth: ccusage per-model breakdown (local transcripts carry the input/output/cache split the run journal does not) — figures above are a blended-rate approximation per contracts/models.json pricing (run 3306873d)
-- abandoned spend: ~$229.74 equivalent API cost across 5 terminal non-COMPLETED item(s) (custom-equals, invalidate, unobserved-hooks, async-iterable-resolve, recursion-free-walks); recorded, not divided into per-item costs (run 2f191933)
-- run-level spend: ~$0.56 equivalent API cost (warm implementer runs + unit-scoped + boundary seats; never divided across items; blended rate = mean(input, output, cache_read, cache_creation) per million tokens) (run 2f191933)
-- [untrack-peek] 5d2a577c2b941bdc6fe869951c770ed3c12a82f8. Deviations: deviated — pull(node) extracted only the notified-broadcast + observer-nulled update() call (matching design's literal extraction target); drainPending() and the height>=heap_i||NOTIFY_MASK gate stay inline in read() exactly as before for byte-identical behavior.; deviated — peek() has no separate explicit NOTIFY_MASK pre-check before calling pull() — it always drains pending writes then calls pull(node) unconditionally for a STATE_COMPUTED node, relying on pull()'s internal notify-broadcast (which sets DIRTY/CHECK bits) plus update()'s own gv/CHECK/DIRTY branching to no-op cheaply when nothing changed. A literal external NOTIFY_MASK gate in peek() would check the bit *before* the broadcast that sets it, which never fires on a freshly-written-but-undrained dependency and would make peek() return stale values, contradicting Acceptance clause 3's 'up-to-date value for a dirty computed'. Verified via a dedicated test that peek() sees a fresh value synchronously right after write(), with 0 regressions across the full 343-test suite.; ladder: 1 attempt (critic), completed. Cost: ~$20.51 equivalent API cost (blended-rate approximation). · spec: spec-signals-next
-- [flush-batch] 3bc415d5568da53154f59a32069afaebfc381d04. Deviations: deviated — flush() implemented as `while (stabilizer === STABILIZER_SCHEDULED) stabilize();` instead of the Design's single `if`. Traced the RESCHEDULE path: a write() during an effect's recompute only flips stabilizer to RESCHEDULE and queues the *next* microtask when its subscriber's height is at or below the current heap_i already scanned in this pass (drain-before-scan only re-triggers on a later height iteration reached within the same for-loop) — a single stabilize() call leaves that tail unsettled until the next microtask, violating Acceptance clause 1's 'settles before flush() returns'. The while-loop drains it synchronously while still satisfying the no-op cases (RUNNING/RESCHEDULE/IDLE never equal SCHEDULED) and clause 4 (any stray queued microtask fires against an already-empty/IDLE state and no-ops).; ladder: 1 attempt (critic), completed. Cost: ~$11.27 equivalent API cost (blended-rate approximation). · spec: spec-signals-next
-- cost source of truth: ccusage per-model breakdown (local transcripts carry the input/output/cache split the run journal does not) — figures above are a blended-rate approximation per contracts/models.json pricing (run 2f191933)
-- follow-up discharged (completed) from spec-signals-next: read-version-dedup + pending-only-writes: stamp rv (+ nextPending on Signal entr… — evidence: 6a9b8e6
-- [cleanup-hardening] 14a40dd7. cleanup() hardening — run every disposer, never abort the batch — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
-- [async-computed-hardening] 033b205f. asyncComputed hardening — dirty-gap guard, isPending, leak test, ReactiveObject reuse — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
-- [async-error-propagation] bf8ad5c0. asyncComputed error propagation (rejections surface, ownership fixed) — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
-- [computed-error-caching] 79224d08. Computed error caching + propagation (errors never vanish) — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
-- [benchmark-harness] 9d6d7b2c. Canonical reactivity benchmark suite + glitch-freedom regression tests — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
-- [test-bench-scripts] 524d07bc. Add test/bench script aliases (agent:test, agent:bench) — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
-- [read-version-dedup] dcbaae90. O(1) interleaved repeat-read dedup (read-version stamp) — landed by hand (combined perf integration, bench-gated vs main: 0 regressions). Deviations: SelectorSignal entry-literal rv stamp deferred until signal-is-selector lands (superset-shape rule, follow-up); computed object-size assertion reconciled to 15. Cost: ~$UNMEASURED (manual integration, no journal)~ · spec: spec-signals-next
-- [global-version-fast-path] dcbaae90. globalVersion fast path for clean-graph reads — landed by hand (combined perf integration, bench-gated vs main: 0 regressions). Deviations: computed object-size assertion reconciled to 15 (shared bump with read-version-dedup + pending-only-writes). Cost: ~$UNMEASURED (manual integration, no journal)~ · spec: spec-signals-next
-- [pending-only-writes] dcbaae90. Pending-only writes — defer fan-out off the write hot path (reduced-shape core) — landed by hand (combined perf integration, bench-gated vs main: 0 regressions). Deviations: reduced-shape core only (intrusive nextPending queue, drainPending, per-height + read()-preamble drain); full shape (lazy mark-don't-schedule, selector recursive fan-out + nextPending on the SelectorSignal entry, tests/flush.ts invariant 2) deferred to follow-up pending flush-batch + lazy-computeds + signal-is-selector; SelectorSignal entry-literal nextPending/rv stamp deferred until signal-is-selector; computed object-size assertion reconciled to 15. Cost: ~$UNMEASURED (manual integration, no journal)~ · spec: spec-signals-next
-- [signal-is-selector] 6a9b8e63. signal.selector() per-key selector primitive — O(2) write-path fan-out, lazy per-key entries, eviction on last unsub — landed by hand off main (dcbaae9). Deviations: SelectorSignal entry literal pre-declares nextPending + rv (perf superset-shape, discharges follow-up #1); write-path bench informal (feature, not perf) — one predicted-not-taken keys null-check, write-neutral; suite 328→336 (+8 acceptance tests incl. SameValueZero NaN/object-ref caveats); glitch-freedom green. Cost: ~$UNMEASURED (manual, no journal)~ · spec: spec-signals-next
-- [lazy-computeds] REVERTED (no landing sha). Lazy computeds — compute on first read, sleep while unobserved — removed from scope by user decision 2026-07-19: lazy-by-default was implemented + A/B benchmarked and REGRESSED (full-suite ABBA geomean 1.04; read-class 0.77–0.88× eager; steady-read parity disproven by isolation bench). Do not re-attempt lazy-by-default naively; a non-regressing opt-in approach would be a fresh design. Patch preserved at ~/.claude/storage/lazy-bench/lazy-by-default-full.patch. Feature file removed from the spec per user request. Cost: ~$UNMEASURED (manual, no journal)~ · spec: spec-signals-next