@pithyjs/signals 0.1.0-beta.0 → 0.1.0-beta.1

package/dist/signal.js

@@ -5,25 +5,529 @@
   "category": "feature"
 }
 */
+// The dependency graph (link, unlink, propagate, checkDirty) is adapted from alien-signals, MIT, Copyright (c) 2024-present Johnson Chu.
 import { SIGNAL_SYMBOL } from './types';
-/**
- * Tracks the current reactive effect being registered.
- * Used to record dependencies when a signal is read.
- */
-let currentEffect = null;
-/**
- * Internal cleanup registry to track cleanup functions for each registered effect.
- * Each effect can have multiple cleanups that are called before re-execution.
- */
+import { disposerCalled, effectWrappers, installIntrospection, nodesOf, rootOwners, } from './internals';
+const DEV = !!import.meta.env?.DEV;
+const MUTABLE = 1;
+const RUNNING = 2;
+const DIRTY = 8;
+const PENDING = 16;
+const QUEUED = 32;
+const DISPOSED = 64;
+const DRAINING = 128;
+const DEFERRED = 256;
+const FAILED = 512;
+const CHECKING = 1024;
+const OWNS = 2048;
+let activeSub = null;
+let currentOwner = null;
+let computing = null;
+let version = 0;
+let markEpoch = 0;
+let batchEpoch = 0;
+const effectNodes = new WeakSet();
+const noop = () => { };
 const cleanupMap = new WeakMap();
+const selfRegistered = new WeakMap();
+const warnedImpure = new WeakSet();
+function registerCleanup(owner, fn) {
+    if (!cleanupMap.has(owner))
+        return;
+    let stack = cleanupMap.get(owner);
+    if (!stack) {
+        stack = [];
+        cleanupMap.set(owner, stack);
+    }
+    stack.push(fn);
+}
 /**
- * Flag to indicate if we are currently inside a batched update.
+ * Runs every callback even if one throws, then rethrows the first failure.
+ * The caller has already dropped its reference to the stack, so a callback
+ * skipped here is unreachable forever — a throwing cleanup would otherwise
+ * leave the rest of an owner's children subscribed with no way to dispose them.
+ *
+ * Tracking and ownership are neutralised for the duration: a cleanup is
+ * teardown, not reactive work, so a signal it reads must not subscribe whatever
+ * effect happens to be mid-run, and an `onCleanup` it registers must not land
+ * on an owner that outlives it. Every disposal path shares this, not just the
+ * re-run one — a disposer called from inside another effect reaches here too.
  */
-let isBatching = false;
+function drain(stack) {
+    const callerSub = activeSub;
+    const callerOwner = currentOwner;
+    activeSub = null;
+    currentOwner = null;
+    let failure;
+    let failed = false;
+    try {
+        for (const cleanup of stack) {
+            try {
+                cleanup();
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+    }
+    finally {
+        activeSub = callerSub;
+        currentOwner = callerOwner;
+    }
+    if (failed)
+        throw failure;
+}
+function link(dep, sub) {
+    const prevDep = sub.depsTail;
+    if (prevDep !== undefined && prevDep.dep === dep)
+        return;
+    const nextDep = prevDep !== undefined ? prevDep.nextDep : sub.deps;
+    if (nextDep !== undefined && nextDep.dep === dep) {
+        nextDep.version = sub.version;
+        sub.depsTail = nextDep;
+        return;
+    }
+    const prevSub = dep.subsTail;
+    if (prevSub !== undefined &&
+        prevSub.version === sub.version &&
+        prevSub.sub === sub) {
+        return;
+    }
+    const newLink = {
+        version: sub.version,
+        dep,
+        sub,
+        prevDep,
+        nextDep,
+        prevSub,
+        nextSub: undefined,
+    };
+    sub.depsTail = newLink;
+    dep.subsTail = newLink;
+    if (nextDep !== undefined)
+        nextDep.prevDep = newLink;
+    if (prevDep !== undefined)
+        prevDep.nextDep = newLink;
+    else
+        sub.deps = newLink;
+    if (prevSub !== undefined)
+        prevSub.nextSub = newLink;
+    else
+        dep.subs = newLink;
+}
+function unlink(target, sub) {
+    const { dep, prevDep, nextDep, nextSub, prevSub } = target;
+    if (nextDep !== undefined)
+        nextDep.prevDep = prevDep;
+    else
+        sub.depsTail = prevDep;
+    if (prevDep !== undefined)
+        prevDep.nextDep = nextDep;
+    else
+        sub.deps = nextDep;
+    if (nextSub !== undefined)
+        nextSub.prevSub = prevSub;
+    else
+        dep.subsTail = prevSub;
+    if (prevSub !== undefined)
+        prevSub.nextSub = nextSub;
+    else
+        dep.subs = nextSub;
+    return nextDep;
+}
+function unlinkAll(sub) {
+    let dep = sub.deps;
+    while (dep !== undefined)
+        dep = unlink(dep, sub);
+}
+function purgeDeps(sub) {
+    const tail = sub.depsTail;
+    let dep = tail !== undefined ? tail.nextDep : sub.deps;
+    while (dep !== undefined)
+        dep = unlink(dep, sub);
+}
+function settleDeps(sub, kept) {
+    if (sub.flags & DISPOSED) {
+        unlinkAll(sub);
+    }
+    else if (kept || sub.depsTail === undefined) {
+        let tail = sub.deps;
+        while (tail?.nextDep !== undefined)
+            tail = tail.nextDep;
+        sub.depsTail = tail;
+    }
+    else {
+        purgeDeps(sub);
+    }
+}
+function isValidLink(check, sub) {
+    let candidate = sub.depsTail;
+    while (candidate !== undefined) {
+        if (candidate === check)
+            return true;
+        candidate = candidate.prevDep;
+    }
+    return false;
+}
+function isComputed(node) {
+    return (node.flags & MUTABLE) !== 0 && 'getter' in node;
+}
+let queue = [];
+let queuedLength = 0;
+let flushLevel = 0;
+let segment = 0;
+function isQueuedHere(node) {
+    return (node.flags & QUEUED) !== 0 && node.slot >= segment;
+}
+let ownersQueued = false;
+function enqueue(node) {
+    node.flags |= QUEUED;
+    node.slot = queuedLength;
+    queue[queuedLength++] = node;
+    if (node.flags & OWNS)
+        ownersQueued = true;
+}
+function runQueuedAncestors(node) {
+    const chain = [];
+    for (let ancestor = node.parent; ancestor !== null; ancestor = ancestor.parent) {
+        if ((ancestor.flags & (QUEUED | DISPOSED)) === QUEUED)
+            chain.push(ancestor);
+    }
+    for (let at = chain.length - 1; at >= 0; at--)
+        run(chain[at]);
+}
+function notify(effectNode, direct) {
+    const flags = effectNode.flags;
+    if (flags & DISPOSED)
+        return;
+    effectNode.flags = flags | (direct ? DIRTY : PENDING);
+    if (!isQueuedHere(effectNode))
+        enqueue(effectNode);
+}
+function propagate(first) {
+    const epoch = ++markEpoch;
+    const stack = [];
+    let current = first;
+    do {
+        while (current !== undefined) {
+            const sub = current.sub;
+            const next = current.nextSub;
+            const flags = sub.flags;
+            const direct = stack.length === 0;
+            if (flags & DISPOSED) {
+                current = next;
+                continue;
+            }
+            if (!isComputed(sub)) {
+                notify(sub, direct);
+                current = next;
+                continue;
+            }
+            const node = sub;
+            if (flags & DRAINING) {
+                current = next;
+                continue;
+            }
+            if (flags & RUNNING) {
+                if (isValidLink(current, node)) {
+                    node.flags = flags | (direct ? DIRTY : PENDING);
+                }
+                current = next;
+                continue;
+            }
+            node.flags = flags | (direct ? DIRTY : PENDING);
+            const settled = batchDepth > 0 && node.marked > batchEpoch && flags & (DIRTY | PENDING);
+            if (node.marked !== epoch && !settled) {
+                node.marked = epoch;
+                if (node.subs !== undefined) {
+                    stack.push(next);
+                    current = node.subs;
+                    continue;
+                }
+            }
+            current = next;
+        }
+        current = stack.pop();
+    } while (current !== undefined || stack.length > 0);
+}
+function shallowPropagate(first) {
+    let current = first;
+    while (current !== undefined) {
+        const sub = current.sub;
+        const flags = sub.flags;
+        if ((flags & (PENDING | DIRTY)) === PENDING)
+            sub.flags = flags | DIRTY;
+        current = current.nextSub;
+    }
+}
+function checkDirty(start, origin) {
+    const stack = [];
+    origin.flags |= CHECKING;
+    try {
+        return walkDirty(start, origin, stack);
+    }
+    finally {
+        origin.flags &= ~CHECKING;
+        for (const link of stack)
+            link.dep.flags &= ~CHECKING;
+    }
+}
+function walkDirty(start, origin, stack) {
+    let current = start;
+    let sub = origin;
+    let dirty = false;
+    for (;;) {
+        const dep = current.dep;
+        const flags = dep.flags;
+        if (sub.flags & DIRTY) {
+            dirty = true;
+        }
+        else if (isComputed(dep) && !(flags & (DISPOSED | RUNNING | CHECKING))) {
+            if (flags & DIRTY) {
+                if (updateComputed(dep)) {
+                    if (dep.subs?.nextSub !== undefined)
+                        shallowPropagate(dep.subs);
+                    dirty = true;
+                }
+                else if (dep.flags & DIRTY) {
+                    dirty = true;
+                }
+            }
+            else if (flags & PENDING && dep.deps !== undefined) {
+                dep.flags |= CHECKING;
+                stack.push(current);
+                current = dep.deps;
+                sub = dep;
+                continue;
+            }
+        }
+        if (!dirty && current.nextDep !== undefined) {
+            current = current.nextDep;
+            continue;
+        }
+        let resumed = false;
+        let parent;
+        while ((parent = stack.pop()) !== undefined) {
+            const node = sub;
+            node.flags &= ~CHECKING;
+            if (dirty) {
+                const changed = updateComputed(node);
+                if (changed && node.subs?.nextSub !== undefined) {
+                    shallowPropagate(node.subs);
+                }
+                if (changed || node.flags & DIRTY) {
+                    sub = parent.sub;
+                    current = parent;
+                    continue;
+                }
+                dirty = false;
+            }
+            else {
+                node.flags &= ~PENDING;
+            }
+            sub = parent.sub;
+            if (parent.nextDep !== undefined) {
+                current = parent.nextDep;
+                resumed = true;
+                break;
+            }
+            current = parent;
+        }
+        if (resumed)
+            continue;
+        return dirty && !(sub.flags & DISPOSED);
+    }
+}
+let errorScopes = 0;
+let recordedError;
+let inBatchBody = false;
+function record(error, node, compute) {
+    if (errorScopes === 0) {
+        node.flags |= DIRTY;
+        throw error;
+    }
+    if (compute && inBatchBody) {
+        node.flags |= DIRTY;
+        return;
+    }
+    recordedError ?? (recordedError = [error]);
+}
+function warnImpure(what) {
+    const node = computing;
+    if (!node || warnedImpure.has(node))
+        return;
+    warnedImpure.add(node);
+    console.warn(`[PithyJS] A computed ${what} while computing. A computed must be pure: move the work into an effect() that reads the computed.`);
+}
+function updateComputed(node) {
+    const getter = node.getter;
+    if (!getter)
+        return false;
+    const previousComputing = computing;
+    const stale = cleanupMap.get(node);
+    cleanupMap.set(node, null);
+    node.flags = (node.flags & ~(DIRTY | PENDING)) | RUNNING;
+    computing = node;
+    if (stale && stale.length > 0) {
+        node.flags |= DRAINING;
+        try {
+            drain(stale);
+        }
+        catch (error) {
+            node.flags &= ~(RUNNING | DRAINING);
+            computing = previousComputing;
+            record(error, node, false);
+            return false;
+        }
+        finally {
+            node.flags &= ~DRAINING;
+        }
+    }
+    if (node.flags & DISPOSED) {
+        node.flags &= ~RUNNING;
+        computing = previousComputing;
+        unlinkAll(node);
+        return false;
+    }
+    const previousSub = activeSub;
+    const previousOwner = currentOwner;
+    const previousTracking = isTrackingContext;
+    node.depsTail = undefined;
+    node.version = ++version;
+    activeSub = node;
+    currentOwner = node;
+    isTrackingContext = true;
+    let next;
+    let ok = false;
+    try {
+        next = getter();
+        ok = true;
+    }
+    catch (error) {
+        record(error, node, true);
+        return false;
+    }
+    finally {
+        activeSub = previousSub;
+        currentOwner = previousOwner;
+        isTrackingContext = previousTracking;
+        computing = previousComputing;
+        node.flags &= ~RUNNING;
+        settleDeps(node, !ok);
+    }
+    const changed = node.value !== next;
+    node.value = next;
+    return changed;
+}
+function refresh(node) {
+    const flags = node.flags;
+    if (flags & (DISPOSED | RUNNING | CHECKING) || !(flags & (DIRTY | PENDING))) {
+        return;
+    }
+    if (flags & DIRTY ||
+        (node.deps !== undefined && checkDirty(node.deps, node))) {
+        if (updateComputed(node))
+            shallowPropagate(node.subs);
+    }
+    else {
+        node.flags &= ~PENDING;
+    }
+}
+function readComputed(node) {
+    refresh(node);
+    const sub = activeSub;
+    if (sub !== null &&
+        sub !== node &&
+        isComputed(sub) &&
+        (node.flags & (DIRTY | RUNNING | CHECKING | DISPOSED)) === DIRTY) {
+        sub.flags |= DIRTY;
+    }
+    if (sub !== null &&
+        sub !== node &&
+        !(node.flags & DISPOSED) &&
+        !(sub.flags & DISPOSED)) {
+        link(node, sub);
+    }
+    return node.value;
+}
+let notifyDepth = 0;
+let batchFlushes = 0;
+let reentries = 0;
+function flushFrom(start, depth, reentered) {
+    let failure;
+    const outermost = flushLevel++ === 0;
+    let index = start;
+    try {
+        while (index < queuedLength) {
+            const node = queue[index];
+            queue[index++] = undefined;
+            if (node === undefined)
+                continue;
+            const stale = node.slot !== index - 1;
+            if (stale && node.flags & DISPOSED)
+                continue;
+            if (!stale &&
+                (node.flags & (RUNNING | DEFERRED)) === RUNNING &&
+                index < queuedLength) {
+                node.flags |= DEFERRED;
+                node.slot = queuedLength;
+                queue[queuedLength++] = node;
+                continue;
+            }
+            node.flags &= ~DEFERRED;
+            const prior = reentries;
+            try {
+                if (ownersQueued && node.parent !== null)
+                    runQueuedAncestors(node);
+                if (stale && node.flags & FAILED)
+                    runEffect(node);
+                else
+                    run(node);
+            }
+            catch (error) {
+                failure ?? (failure = [error]);
+                if (depth && (reentered || reentries !== prior))
+                    throw failure[0];
+            }
+        }
+    }
+    finally {
+        flushLevel--;
+        while (index < queuedLength) {
+            const node = queue[index];
+            queue[index++] = undefined;
+            if (node !== undefined)
+                node.flags &= ~QUEUED;
+        }
+        queuedLength = outermost ? 0 : start;
+        if (outermost) {
+            ownersQueued = false;
+            if (queue.length > 1024)
+                queue = [];
+        }
+    }
+    return failure;
+}
+function run(node) {
+    const flags = node.flags;
+    node.flags = flags & ~QUEUED;
+    if (flags & DISPOSED)
+        return;
+    if (flags & DIRTY ||
+        (flags & PENDING && node.deps !== undefined && checkDirty(node.deps, node))) {
+        runEffect(node);
+    }
+    else {
+        node.flags &= ~PENDING;
+    }
+}
 /**
- * Set of effect wrappers scheduled to run after a batch ends.
+ * How many `batch()` bodies are running; only the outermost one flushes.
  */
-const pendingEffects = new Set();
+let batchDepth = 0;
 /**
  * Indicates whether we are currently inside a tracking context (effect or computed).
  * Used to suppress signal read warnings in appropriate scopes.
@@ -34,11 +538,11 @@ let isTrackingContext = false;
  */
 let suppressionDepth = 0;
 /**
- * Checks if a value is a Signal at runtime.
+ * Checks if a value is a signal or a computed at runtime.
  * @param value - The value to check.
- * @returns True if the value is a Signal.
+ * @returns True if the value is a signal or a computed.
  */
-/** @codexApi {"parent":"pithy.feature.signals","name":"isSignal","stability":"stable","signature":"(value: unknown) => value is Signal<any>"} */
+/** @codexApi {"parent":"pithy.feature.signals","name":"isSignal","stability":"stable","signature":"(value: unknown) => value is ReadableSignal<unknown>"} */
 export function isSignal(value) {
     return (typeof value === 'function' &&
         value[SIGNAL_SYMBOL] === true);
@@ -59,18 +563,21 @@ function suppressWarnings(fn) {
     }
 }
 /**
- * Registers a cleanup callback that will be executed
- * before the current effect is re-run.
+ * Registers a cleanup callback, executed once — before the current effect's
+ * next re-run, or when it is disposed, whichever comes first. Effects and
+ * computeds created during a run are
+ * owned by that run and torn down on the same schedule; use `createRoot` for
+ * work that must outlive the run that built it.
  *
  * @param fn - The cleanup function.
  */
 /** @codexApi {"parent":"pithy.feature.signals","name":"onCleanup","stability":"stable","signature":"(fn: () => void) => void"} */
 export function onCleanup(fn) {
-    if (currentEffect) {
-        const stack = cleanupMap.get(currentEffect);
-        if (stack)
-            stack.push(fn);
-    }
+    if (!currentOwner)
+        return;
+    if (selfRegistered.get(fn) === currentOwner)
+        return;
+    registerCleanup(currentOwner, fn);
 }
 /**
  * Creates a reactive effect that automatically tracks
@@ -81,36 +588,297 @@ export function onCleanup(fn) {
  */
 /** @codexApi {"parent":"pithy.feature.signals","name":"effect","stability":"stable","signature":"(fn: () => void) => () => void"} */
 export function effect(fn) {
-    const wrapped = () => runEffect(wrapped, fn);
-    // Run immediately to establish dependencies
-    wrapped();
-    // Return disposer to manually stop the effect
+    if (DEV && computing)
+        warnImpure('created an effect');
+    const owner = currentOwner;
+    const node = {
+        fn,
+        deps: undefined,
+        depsTail: undefined,
+        flags: DIRTY,
+        version: 0,
+        parent: owner !== null && effectNodes.has(owner) ? owner : null,
+        slot: 0,
+    };
+    if (node.parent !== null) {
+        node.parent.flags |= OWNS;
+        if (node.parent.flags & QUEUED)
+            ownersQueued = true;
+    }
+    effectNodes.add(node);
+    cleanupMap.set(node, null);
     const disposer = () => {
-        cleanupMap.get(wrapped)?.forEach(fn => fn());
-        cleanupMap.delete(wrapped);
+        const flags = node.flags;
+        if (typeof __PITHY_TEST__ !== 'undefined' && __PITHY_TEST__)
+            disposerCalled.add(node);
+        if (flags & DISPOSED)
+            return;
+        node.flags |= DISPOSED;
+        node.parent = null;
+        try {
+            const stack = cleanupMap.get(node);
+            if (stack)
+                drain(stack);
+        }
+        finally {
+            cleanupMap.delete(node);
+            selfRegistered.delete(disposer);
+            node.fn = noop;
+            if (!(node.flags & RUNNING))
+                unlinkAll(node);
+        }
     };
+    if (typeof __PITHY_TEST__ !== 'undefined' && __PITHY_TEST__)
+        effectWrappers.set(disposer, node);
+    if (owner) {
+        selfRegistered.set(disposer, owner);
+        registerCleanup(owner, disposer);
+    }
+    if (batchDepth > 0) {
+        enqueue(node);
+        return disposer;
+    }
+    const owns = errorScopes === 0;
+    const outer = recordedError;
+    let recorded;
+    if (owns) {
+        recordedError = undefined;
+        errorScopes++;
+    }
+    let thrown;
+    try {
+        runEffect(node);
+    }
+    catch (error) {
+        thrown = [error];
+    }
+    finally {
+        if (owns) {
+            errorScopes--;
+            recorded = recordedError;
+            recordedError = outer;
+        }
+    }
+    const failure = recorded ?? thrown;
+    if (failure) {
+        if (!owner) {
+            try {
+                disposer();
+            }
+            catch {
+                // The run's error is the one worth reporting.
+            }
+        }
+        throw failure[0];
+    }
     return disposer;
 }
+function runEffect(node) {
+    if (node.flags & (DISPOSED | DRAINING))
+        return;
+    const stale = cleanupMap.get(node);
+    cleanupMap.set(node, null);
+    if (stale && stale.length > 0) {
+        node.flags |= DRAINING;
+        try {
+            drain(stale);
+        }
+        finally {
+            node.flags &= ~DRAINING;
+        }
+    }
+    if (node.flags & DISPOSED)
+        return;
+    const running = node.flags & RUNNING;
+    node.flags = (node.flags & ~(DIRTY | PENDING | FAILED)) | RUNNING;
+    node.depsTail = undefined;
+    node.version = ++version;
+    const parentSub = activeSub;
+    const parentOwner = currentOwner;
+    const parentTracking = isTrackingContext;
+    const parentComputing = computing;
+    activeSub = node;
+    currentOwner = node;
+    isTrackingContext = true;
+    computing = null;
+    let ok = false;
+    try {
+        node.fn();
+        ok = true;
+    }
+    finally {
+        activeSub = parentSub;
+        currentOwner = parentOwner;
+        isTrackingContext = parentTracking;
+        computing = parentComputing;
+        if (!running)
+            node.flags &= ~RUNNING;
+        if (!ok)
+            node.flags |= FAILED;
+        settleDeps(node, !ok);
+    }
+}
 /**
  * Batches multiple signal updates together.
- * Effects triggered during the batch are deferred and executed once after the batch.
+ * Batches nest: effects triggered inside are deferred and run once, after the outermost batch.
  *
  * @param fn - The function performing multiple signal updates.
  */
 /** @codexApi {"parent":"pithy.feature.signals","name":"batch","stability":"stable","signature":"(fn: () => void) => void"} */
 export function batch(fn) {
-    isBatching = true;
+    let failure;
+    const outermost = batchDepth === 0;
+    const start = queuedLength;
+    const outerEpoch = batchEpoch;
+    const outerSegment = segment;
+    const outer = recordedError;
+    const outerBody = inBatchBody;
+    if (outermost) {
+        batchEpoch = markEpoch;
+        segment = start;
+        recordedError = undefined;
+        inBatchBody = true;
+        errorScopes++;
+    }
+    batchDepth++;
     try {
         fn();
     }
     finally {
-        isBatching = false;
-        // Execute all pending effects once
-        const effects = Array.from(pendingEffects);
-        pendingEffects.clear();
-        effects.forEach(run => run());
+        if (--batchDepth === 0) {
+            batchEpoch = outerEpoch;
+            segment = outerSegment;
+            inBatchBody = outerBody;
+            failure = recordedError;
+            recordedError = undefined;
+            const depth = notifyDepth++;
+            const nested = batchFlushes++ > 0;
+            if (nested)
+                reentries++;
+            try {
+                const flushed = flushFrom(start, depth, nested);
+                failure ?? (failure = flushed);
+            }
+            catch (error) {
+                failure ?? (failure = [error]);
+                while (queuedLength > start) {
+                    const node = queue[--queuedLength];
+                    queue[queuedLength] = undefined;
+                    if (node !== undefined)
+                        node.flags &= ~QUEUED;
+                }
+            }
+            finally {
+                notifyDepth = depth;
+                batchFlushes--;
+                inBatchBody = outerBody;
+                errorScopes--;
+                failure ?? (failure = recordedError);
+                recordedError = outer;
+            }
+        }
+    }
+    if (failure)
+        throw failure[0];
+}
+/**
+ * Reads signals without subscribing the enclosing effect to them.
+ *
+ * @param fn - The function to run untracked.
+ * @returns Whatever `fn` returns.
+ */
+/** @codexApi {"parent":"pithy.feature.signals","name":"untrack","stability":"stable","signature":"<T>(fn: () => T) => T"} */
+export function untrack(fn) {
+    const previous = activeSub;
+    activeSub = null;
+    try {
+        return suppressWarnings(fn);
+    }
+    finally {
+        activeSub = previous;
+    }
+}
+/**
+ * Creates an ownership root: effects and computeds created inside `fn` are owned
+ * by the root rather than by any enclosing effect, so an enclosing re-run does
+ * not dispose them. Disposing the root disposes everything it owns — but a root
+ * created inside another root is independent: hold its disposer, because the
+ * outer root will not reach it.
+ *
+ * Tracking is untouched — a signal read inside `fn` still subscribes whatever
+ * effect is current.
+ *
+ * @param fn - Receives the root's disposer.
+ * @returns Whatever `fn` returns.
+ */
+/** @codexApi {"parent":"pithy.feature.signals","name":"createRoot","stability":"stable","signature":"<T>(fn: (dispose: () => void) => T) => T"} */
+export function createRoot(fn) {
+    const owner = {};
+    cleanupMap.set(owner, null);
+    const dispose = () => {
+        const stack = cleanupMap.get(owner);
+        cleanupMap.delete(owner);
+        if (stack)
+            drain(stack);
+    };
+    if (typeof __PITHY_TEST__ !== 'undefined' && __PITHY_TEST__)
+        rootOwners.set(dispose, owner);
+    const parentOwner = currentOwner;
+    currentOwner = owner;
+    try {
+        return fn(dispose);
+    }
+    catch (error) {
+        try {
+            dispose();
+        }
+        catch {
+            // `fn`'s error is the one worth reporting.
+        }
+        throw error;
+    }
+    finally {
+        currentOwner = parentOwner;
     }
 }
+function callListeners(listeners, value, depth, reentered, failure) {
+    const previousSub = activeSub;
+    const previousComputing = computing;
+    activeSub = null;
+    computing = null;
+    try {
+        for (const fn of listeners) {
+            const prior = reentries;
+            try {
+                fn(value);
+            }
+            catch (error) {
+                failure ?? (failure = [error]);
+                if (depth && (reentered || reentries !== prior))
+                    throw failure[0];
+            }
+        }
+    }
+    finally {
+        activeSub = previousSub;
+        computing = previousComputing;
+    }
+    return failure;
+}
+function subscribeWith(listeners, fn, current) {
+    const added = !listeners.has(fn);
+    listeners.add(fn);
+    let called = false;
+    try {
+        fn(current());
+        called = true;
+    }
+    finally {
+        if (!called && added)
+            listeners.delete(fn);
+    }
+    return called;
+}
 /**
  * Creates a signal: a reactive function holding a value and supporting subscriptions.
  *
@@ -119,112 +887,254 @@ export function batch(fn) {
  */
 /** @codexApi {"parent":"pithy.feature.signals","name":"signal","stability":"stable","signature":"<T>(initial: T) => Signal<T>"} */
 export function signal(initial) {
-    let value = initial;
-    const subscribers = new Set();
+    const node = {
+        value: initial,
+        subs: undefined,
+        subsTail: undefined,
+        flags: 0,
+    };
+    let active = 0;
     const listeners = new Set();
-    const read = () => suppressWarnings(() => {
-        if (currentEffect) {
-            // Register currentEffect as a subscriber
-            subscribers.add(currentEffect);
-            // IMPORTANT: Capture currentEffect NOW, not when cleanup runs!
-            // Otherwise, if cleanup runs while a different effect is active,
-            // we'd delete the wrong effect from subscribers.
-            const effectToRemove = currentEffect;
-            onCleanup(() => {
-                subscribers.delete(effectToRemove);
-            });
-        }
-        else {
-            // Warn if a signal is read outside of reactive context (in dev mode)
-            if (!isTrackingContext &&
-                suppressionDepth === 0 &&
-                import.meta.env?.DEV &&
-                !import.meta.env?.TEST) {
-                const error = new Error();
-                const stack = error.stack ?? '';
-                console.warn(`[PithyJS] ❗ Signal (value: ${value}) was read outside of a reactive context.\n` +
-                    `  • This might lead to missed updates in the UI.\n\n` +
-                    `🔎 Where it happened:\n${stack.split('\n').slice(2).join('\n')}`);
-            }
-        }
-        return value;
-    });
+    const read = () => {
+        const sub = activeSub;
+        if (sub !== null && !(sub.flags & DISPOSED))
+            link(node, sub);
+        return node.value;
+    };
     read.set = (next) => {
-        const newValue = suppressWarnings(() => typeof next === 'function' ? next(value) : next);
-        if (value !== newValue) {
-            value = newValue;
-            // Notify all reactive subscribers
-            subscribers.forEach(fn => {
-                if (isBatching) {
-                    pendingEffects.add(fn);
-                }
-                else {
-                    fn();
-                }
-            });
-            // Notify all external listeners (subscriptions)
-            listeners.forEach(fn => fn(value));
+        const newValue = suppressWarnings(() => typeof next === 'function' ? next(node.value) : next);
+        if (DEV && computing)
+            warnImpure('wrote a signal');
+        if (node.value === newValue)
+            return;
+        node.value = newValue;
+        let failure;
+        const start = queuedLength;
+        const outerSegment = segment;
+        const outer = recordedError;
+        const outerBody = inBatchBody;
+        const depth = notifyDepth++;
+        const entered = active++ > 0;
+        if (entered)
+            reentries++;
+        if (batchDepth === 0)
+            segment = start;
+        recordedError = undefined;
+        inBatchBody = false;
+        errorScopes++;
+        try {
+            if (node.subs !== undefined)
+                propagate(node.subs);
+            if (batchDepth === 0)
+                failure = flushFrom(start, depth, entered);
+            if (listeners.size > 0) {
+                failure = callListeners(listeners, node.value, depth, entered, failure);
+            }
+            failure ?? (failure = recordedError);
+        }
+        finally {
+            notifyDepth = depth;
+            active--;
+            segment = outerSegment;
+            errorScopes--;
+            recordedError = outer;
+            inBatchBody = outerBody;
         }
+        if (failure)
+            throw failure[0];
     };
     read.subscribe = (fn) => {
-        listeners.add(fn);
-        fn(value); // Immediately call with current value
+        subscribeWith(listeners, fn, () => node.value);
         return () => listeners.delete(fn);
     };
     read[SIGNAL_SYMBOL] =
         true;
+    if (typeof __PITHY_TEST__ !== 'undefined' && __PITHY_TEST__)
+        nodesOf.set(read, node);
     return read;
 }
 /**
- * Creates a derived signal (computed value) that automatically
- * recalculates when its dependencies change.
+ * Creates a derived signal (computed value). It computes once when created,
+ * then recomputes when it is read after one of its sources changed.
  *
- * @param compute - A function returning the computed value.
- * @returns A readonly function returning the latest computed value.
+ * @param compute - A function returning the computed value. It must not write signals or create effects.
+ * @returns A read-only signal returning the latest computed value.
  */
-/** @codexApi {"parent":"pithy.feature.signals","name":"computed","stability":"stable","signature":"<T>(compute: () => T) => () => T"} */
+/** @codexApi {"parent":"pithy.feature.signals","name":"computed","stability":"stable","signature":"<T>(compute: () => T) => ReadableSignal<T>"} */
 export function computed(compute) {
-    isTrackingContext = true; // Allow first compute() call to access signals without warnings
-    let initial;
+    const node = {
+        value: undefined,
+        getter: compute,
+        subs: undefined,
+        subsTail: undefined,
+        deps: undefined,
+        depsTail: undefined,
+        flags: MUTABLE,
+        version: 0,
+        marked: 0,
+        watcher: null,
+    };
+    const listeners = new Set();
+    cleanupMap.set(node, null);
+    const dispose = () => {
+        if (node.flags & DISPOSED)
+            return;
+        node.flags |= DISPOSED;
+        const watcher = node.watcher;
+        node.watcher = null;
+        try {
+            watcher?.();
+            const stack = cleanupMap.get(node);
+            if (stack)
+                drain(stack);
+        }
+        finally {
+            cleanupMap.delete(node);
+            if (!(node.flags & RUNNING))
+                unlinkAll(node);
+            node.getter = null;
+        }
+    };
+    const owner = currentOwner;
+    if (owner)
+        registerCleanup(owner, dispose);
+    const previousSub = activeSub;
+    const previousOwner = currentOwner;
+    const previousTracking = isTrackingContext;
+    const previousComputing = computing;
+    node.flags |= RUNNING;
+    node.version = ++version;
+    activeSub = node;
+    currentOwner = node;
+    isTrackingContext = true;
+    computing = node;
+    let recorded;
+    let failed;
+    const owns = errorScopes === 0;
+    const outer = recordedError;
+    if (owns) {
+        recordedError = undefined;
+        errorScopes++;
+    }
     try {
-        initial = compute();
+        node.value = compute();
+    }
+    catch (error) {
+        failed = [error];
     }
     finally {
-        isTrackingContext = false;
+        if (owns) {
+            errorScopes--;
+            recorded = recordedError;
+            recordedError = outer;
+        }
+        activeSub = previousSub;
+        currentOwner = previousOwner;
+        isTrackingContext = previousTracking;
+        computing = previousComputing;
+        node.flags &= ~RUNNING;
     }
-    const result = signal(initial);
-    const owner = currentEffect;
-    const dispose = effect(() => {
-        result.set(compute());
-    });
-    if (owner) {
-        cleanupMap.get(owner)?.push(dispose);
+    failed ?? (failed = recorded);
+    if (failed) {
+        dispose();
+        throw failed[0];
     }
-    return result;
+    if (node.flags & DISPOSED)
+        unlinkAll(node);
+    const read = () => readComputed(node);
+    read.subscribe = (fn) => {
+        let delivered = untrack(read);
+        if (!subscribeWith(listeners, fn, () => delivered))
+            return () => { };
+        if (!node.watcher && !(node.flags & DISPOSED)) {
+            const outerOwner = currentOwner;
+            const outerComputing = computing;
+            currentOwner = null;
+            computing = null;
+            try {
+                node.watcher = effect(() => {
+                    const value = read();
+                    if (value === delivered)
+                        return;
+                    delivered = value;
+                    const failure = callListeners(listeners, value, 0, false, undefined);
+                    if (failure)
+                        throw failure[0];
+                });
+            }
+            finally {
+                currentOwner = outerOwner;
+                computing = outerComputing;
+            }
+        }
+        return () => {
+            listeners.delete(fn);
+            if (listeners.size === 0 && node.watcher) {
+                const stop = node.watcher;
+                node.watcher = null;
+                stop();
+            }
+        };
+    };
+    read[SIGNAL_SYMBOL] =
+        true;
+    if (typeof __PITHY_TEST__ !== 'undefined' && __PITHY_TEST__)
+        nodesOf.set(read, node);
+    return read;
 }
-/**
- * Runs the provided effect function, setting up the current tracking context,
- * managing cleanups, and allowing signal dependencies to be re-collected.
- *
- * @param wrapped - The wrapper function associated with the effect.
- * @param fn - The effect body function.
- */
-function runEffect(wrapped, fn) {
-    isTrackingContext = true;
-    if (isBatching) {
-        // Defer running effect until after batch completes
-        pendingEffects.add(() => runEffect(wrapped, fn));
-        return;
+function subscribersOfNode(node) {
+    const result = [];
+    let current = node.subs;
+    while (current !== undefined) {
+        if (!result.includes(current.sub))
+            result.push(current.sub);
+        current = current.nextSub;
     }
-    // Prepare new cleanup stack
-    cleanupMap.set(wrapped, []);
-    currentEffect = wrapped;
-    try {
-        fn(); // Run the effect
-    }
-    finally {
-        currentEffect = null;
-        isTrackingContext = false;
+    return result;
+}
+function dependenciesOfNode(node) {
+    const result = [];
+    let current = node.deps;
+    while (current !== undefined) {
+        if (!result.includes(current.dep))
+            result.push(current.dep);
+        current = current.nextDep;
     }
+    return result;
+}
+if (typeof __PITHY_TEST__ !== 'undefined' && __PITHY_TEST__) {
+    installIntrospection({
+        context: () => {
+            let pending = 0;
+            for (let index = 0; index < queuedLength; index++) {
+                const node = queue[index];
+                if (node !== undefined && !(node.flags & DISPOSED))
+                    pending++;
+            }
+            return {
+                effect: activeSub,
+                owner: currentOwner,
+                tracking: isTrackingContext,
+                suppression: suppressionDepth,
+                batching: batchDepth > 0,
+                pending,
+                notifying: notifyDepth,
+                flushing: flushLevel,
+            };
+        },
+        cleanupStack: owner => cleanupMap.get(owner),
+        subscribers: subscribersOfNode,
+        links: node => {
+            let count = 0;
+            let current = node.subs;
+            while (current !== undefined) {
+                count++;
+                current = current.nextSub;
+            }
+            return count;
+        },
+        dependencies: dependenciesOfNode,
+        disposed: node => (node.flags & DISPOSED) !== 0,
+    });
 }
 //# sourceMappingURL=signal.js.map