@purityjs/signals 0.0.0-stage → 0.5.0

package/src/signals.ts

@@ -0,0 +1,1134 @@
+import {
+  type ComponentContext,
+  getCurrentComponent,
+  getCurrentContext,
+  popContext,
+  pushContext,
+  type Scope,
+} from './scope.ts';
+
+declare function queueMicrotask(callback: () => void): void;
+declare const console: {
+  error(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+};
+
+// ---------------------------------------------------------------------------
+// Reactivity core
+//
+// Push-pull, version-tracked graph. Plain-object nodes (no classes, no
+// private slots) so V8 can inline the shape — every State and Computed is a
+// fixed-shape literal, allocations land on the same hidden class.
+//
+// Status states:
+//   CLEAN  — value is current, all sources consistent
+//   CHECK  — an ancestor was DIRTY, so we MIGHT be dirty; resolve by walking
+//            sources and comparing versions before re-running
+//   DIRTY  — known stale; must re-run to refresh value
+//
+// Propagation runs in two phases (Solid-style):
+//  1. write() bumps version, marks direct observers DIRTY, transitive CHECK,
+//     and queues effect nodes onto the pending list.
+//  2. flush() pulls each pending effect: walks its sources, recursively
+//     updates dirty computeds top-down, then re-runs the effect only if a
+//     source's version actually changed. CHECK→CLEAN without a re-run is
+//     the glitch-freedom mechanism.
+// ---------------------------------------------------------------------------
+
+// const enum would inline these but Node's TS strip mode rejects them.
+const STATUS_CLEAN = 0;
+const STATUS_CHECK = 1;
+const STATUS_DIRTY = 2;
+type Status = 0 | 1 | 2;
+
+interface StateNode<T> {
+  /** Discriminator: state has no fn. */
+  fn: null;
+  value: T;
+  /** Bumps every time `value` actually changes. Consumers cache it to detect change without re-running fn. */
+  version: number;
+  observers: ComputedNode[] | null;
+}
+
+interface ComputedNode {
+  fn: () => unknown;
+  value: unknown;
+  version: number;
+  status: Status;
+  sources: AnyNode[] | null;
+  /** Interleaved source versions and observer back-pointers. */
+  sourceMeta: number[] | null;
+  observers: ComputedNode[] | null;
+  /** Effects: disposers of reactive work created during the last run (nested
+   *  watches, template bindings, computes), ending with the cleanup function
+   *  the body returned. An effect is the current scope while it runs, so this
+   *  is its `Scope.disposers`. Released before the next run and on dispose. */
+  disposers: (() => void)[] | null;
+  /** Effects: the component they were created under. An effect is the current
+   *  scope when it re-runs in a later flush, after that component rendered;
+   *  this keeps component-only APIs called from the body working. */
+  component: ComponentContext | null;
+  /** True for watch effects (must re-run for side effects); false for compute (lazy). */
+  isEffect: boolean;
+  disposed: boolean;
+  /** Set when the last fn() run threw (computes only; effects rethrow to flush).
+   *  Boxed so a thrown `undefined`/`null` is still distinguishable from "no error".
+   *  Checked on the read path only when set; cleared by the next successful run. */
+  error: { value: unknown } | null;
+  /** Effects: the flush that last counted a run of this node, and how many runs it has counted in that flush. */
+  flushId: number;
+  flushRuns: number;
+}
+
+type AnyNode = StateNode<unknown> | ComputedNode;
+
+let activeListener: ComputedNode | null = null;
+/** Position cursor while activeListener is running fn(); enables in-place source slot reuse. */
+let activeSourceIdx = 0;
+let batchDepth = 0;
+let microtaskScheduled = false;
+const pendingEffects: ComputedNode[] = [];
+
+// Re-runs allowed for one effect within one flush. A flush normally runs each
+// dirtied effect once; a second or third run comes from an upstream effect
+// writing again in the same cascade. 1000 is far beyond any such chain, and a
+// feedback loop reaches it in well under a millisecond per cycle, so it trips
+// quickly. Trade-off: one effect fed by more than 1000 separate writes inside a
+// single flush would trip; that is treated as a loop.
+const MAX_EFFECT_REPEATS = 1000;
+let flushSeq = 0;
+const MAX_EFFECT_DEPTH = 100;
+let effectDepth = 0;
+
+// ---------------------------------------------------------------------------
+// Inspection registry
+//
+// Powers the `globalThis.__purity_inspect__` hook (see `docs/debugging.md`
+// and ADR-0002) so consumers can debug live apps without rebuilding for
+// development. Gated on `__DEV__` (below) rather than always present: a
+// consuming app's own production build replaces `process.env.NODE_ENV` with
+// the literal "production" (standard behavior for Vite/esbuild/webpack app
+// builds — NOT this package's own library build, which leaves it
+// unresolved on purpose so the decision is the consumer's, at their build
+// time, not baked in here), which folds `__DEV__` to `false` and lets that
+// build's minifier drop every branch gated on it — this file's own
+// WeakRef/FinalizationRegistry bookkeeping and the whole inspector-hook
+// installation block at the end of this file.
+// ---------------------------------------------------------------------------
+
+// A minimal local ambient type for the one Node-style global this
+// browser-targeting package reads, so it doesn't need to depend on
+// @types/node (which would otherwise pull in a whole browser-irrelevant
+// global surface) just for this. Deliberately unguarded by a
+// `typeof process !== 'undefined'` check: that check can't itself be
+// constant-folded by a bundler, which would leave `__DEV__` unresolvable at
+// build time and defeat the dead-code elimination this exists for. Same
+// assumption every other library using this pattern (React included)
+// makes: something in the build pipeline replaces `process.env.NODE_ENV`
+// before this code reaches a real browser.
+declare const process: { env: { NODE_ENV?: string } };
+
+const __DEV__ = process.env.NODE_ENV !== 'production';
+
+const trackedNodes: Set<WeakRef<AnyNode>> | null = __DEV__ ? new Set() : null;
+
+// Without this, `trackedNodes` grows by one WeakRef per signal/effect ever
+// created and only sheds dead entries when the inspector hook is manually
+// invoked (`__purity_inspect__.liveNodes()`) — which most apps never do. A
+// long-running app with heavy each()/component churn would accumulate dead
+// WeakRef wrappers (and their Set slots) without bound even though the nodes
+// themselves are collected. The FinalizationRegistry drops each WeakRef from
+// the Set when its node is reclaimed, keeping the registry ~bounded to live
+// nodes. Feature-detected so non-supporting runtimes fall back to the lazy
+// prune in inspectorLiveNodes().
+const nodeFinalization: FinalizationRegistry<WeakRef<AnyNode>> | null =
+  __DEV__ && typeof FinalizationRegistry !== 'undefined'
+    ? new FinalizationRegistry<WeakRef<AnyNode>>((ref) => {
+        trackedNodes?.delete(ref);
+      })
+    : null;
+
+function trackNode(node: AnyNode): void {
+  if (trackedNodes === null) return;
+  const ref = new WeakRef(node);
+  trackedNodes.add(ref);
+  nodeFinalization?.register(node, ref);
+}
+
+// ---------------------------------------------------------------------------
+// read / write / track
+// ---------------------------------------------------------------------------
+
+function readState<T>(node: StateNode<T>): T {
+  if (activeListener !== null && !activeListener.disposed) track(node);
+  return node.value;
+}
+
+function readNode<T>(node: ComputedNode, trackReads = true): T {
+  if (node.status !== STATUS_CLEAN) updateValue(node);
+  // A disposed computed is a frozen snapshot, not a live reactive source: it
+  // can never become dirty again (its own sources were cut on dispose), so
+  // tracking it here would only create a dead observer edge.
+  if (trackReads && activeListener !== null && !activeListener.disposed && !node.disposed) {
+    track(node);
+  }
+  // Track before throwing so a consumer that catches the error still re-runs
+  // when a source of the failed compute changes.
+  if (node.error !== null) throw node.error.value;
+  return node.value as T;
+}
+
+function writeState<T>(node: StateNode<T>, value: T): void {
+  if (Object.is(node.value, value)) return;
+  node.value = value;
+  node.version++;
+  if (node.observers !== null) {
+    markDirty(node.observers);
+    if (batchDepth === 0) scheduleFlush();
+  }
+}
+
+function track(producer: AnyNode): void {
+  const consumer = activeListener!;
+  const idx = activeSourceIdx;
+  const sources = consumer.sources;
+
+  // Position-indexed reuse: if the slot at idx already points at the same
+  // producer, just refresh the version snapshot. Common case for stable
+  // dependency sets (most templates re-read the same signals each run).
+  if (sources !== null && idx < sources.length) {
+    const cur = sources[idx];
+    if (cur === producer) {
+      consumer.sourceMeta![idx * 2] = producer.version;
+      activeSourceIdx = idx + 1;
+      return;
+    }
+    // Slot occupied by a different producer — swap.
+    removeObserver(cur, consumer, idx);
+    sources[idx] = producer;
+    consumer.sourceMeta![idx * 2] = producer.version;
+    addObserver(producer, consumer, idx);
+  } else {
+    // Append fresh slot.
+    if (sources === null) {
+      consumer.sources = [producer];
+      consumer.sourceMeta = [producer.version, 0]; // slot overwritten below
+    } else {
+      sources.push(producer);
+      consumer.sourceMeta!.push(producer.version, 0);
+    }
+    addObserver(producer, consumer, idx);
+  }
+  activeSourceIdx = idx + 1;
+}
+
+function addObserver(producer: AnyNode, consumer: ComputedNode, sourceSlot: number): void {
+  const obs = producer.observers;
+  let pos: number;
+  if (obs === null) {
+    producer.observers = [consumer];
+    pos = 0;
+  } else {
+    pos = obs.length;
+    obs.push(consumer);
+  }
+  consumer.sourceMeta![sourceSlot * 2 + 1] = pos;
+}
+
+// `sourceSlot` is the consumer's position in its own sources[] for this producer.
+// Knowing it lets us look up the consumer's slot in producer.observers in O(1)
+// instead of scanning the (possibly thousands-long) observers list.
+//
+// Watchers may legitimately read the same signal twice in one fn body (e.g.
+// `${() => item().a * item().b}`), in which case sources[] contains the same
+// producer at multiple indices and producer.observers[] contains the consumer
+// multiple times. We disambiguate the moved consumer's source slot by matching
+// on (producer identity, currently-stored observer index) — that pair is
+// unique within a single consumer.
+function removeObserver(producer: AnyNode, consumer: ComputedNode, sourceSlot: number): void {
+  const obs = producer.observers;
+  if (obs === null) return;
+  const slot = consumer.sourceMeta![sourceSlot * 2 + 1];
+  // A removed source slot must no longer match a later swap's back-pointer.
+  // Repeated reads can be permuted by another consumer's removal; retaining
+  // the old index would then update an already detached slot instead of the
+  // moved live slot on this same consumer.
+  consumer.sourceMeta![sourceSlot * 2 + 1] = -1;
+  const last = obs.length - 1;
+  if (slot !== last) {
+    const moved = obs[last];
+    obs[slot] = moved;
+    const ms = moved.sources!;
+    const mslots = moved.sourceMeta!;
+    for (let k = 0; k < ms.length; k++) {
+      if (ms[k] === producer && mslots[k * 2 + 1] === last) {
+        mslots[k * 2 + 1] = slot;
+        break;
+      }
+    }
+  }
+  obs.pop();
+  if (obs.length === 0) producer.observers = null;
+}
+
+// Detach a node from every producer it currently observes.
+function disconnectFromSources(node: ComputedNode): void {
+  const sources = node.sources;
+  if (sources === null) return;
+  for (let i = 0; i < sources.length; i++) removeObserver(sources[i], node, i);
+  node.sources = null;
+  node.sourceMeta = null;
+}
+
+// ---------------------------------------------------------------------------
+// dirty propagation
+// ---------------------------------------------------------------------------
+
+// Computed-only graph traversal is installed when the first computed is
+// created, so state-and-effect-only applications can omit it entirely.
+let runDerived: ((node: ComputedNode) => void) | undefined;
+let propagateComputedCheck: ((observers: ComputedNode[]) => void) | undefined;
+let resolveComputedCheck: ((node: ComputedNode) => void) | undefined;
+let settleComputedLoop: ((from: number) => void) | undefined;
+
+function markDirty(observers: ComputedNode[]): void {
+  for (let i = 0; i < observers.length; i++) {
+    const o = observers[i];
+    if (o.status === STATUS_DIRTY) continue;
+    o.status = STATUS_DIRTY;
+    if (o.isEffect) pendingEffects.push(o);
+    if (o.observers !== null) propagateComputedCheck!(o.observers);
+  }
+}
+
+// Iterative (explicit stack) rather than recursive: a long-lived derived
+// chain grown one link at a time never trips a stack-depth limit while
+// building (each new link only touches its already-settled parent), but a
+// later write to the root still has to mark every link in one synchronous
+// pass. Pushing children in reverse index order preserves the same
+// pre-order visitation (and thus pendingEffects push order) the old
+// recursive version produced.
+function markCheck(observers: ComputedNode[]): void {
+  const stack: ComputedNode[] = [];
+  for (let i = observers.length - 1; i >= 0; i--) stack.push(observers[i]);
+  while (stack.length > 0) {
+    const o = stack.pop()!;
+    if (o.status !== STATUS_CLEAN) continue;
+    o.status = STATUS_CHECK;
+    if (o.isEffect) pendingEffects.push(o);
+    const kids = o.observers;
+    if (kids !== null) {
+      for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i]);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// updateValue — pull a node back to CLEAN
+// ---------------------------------------------------------------------------
+
+interface CheckFrame {
+  node: ComputedNode;
+  sources: AnyNode[];
+  versions: number[];
+  idx: number;
+}
+
+// Iterative (explicit heap-allocated stack of frames) equivalent of the
+// natural recursive formulation: to resolve a CHECK node, first resolve each
+// CHECK/DIRTY source (depth-first), then compare versions and either settle
+// CLEAN or recompute. A long incrementally-built chain can be arbitrarily
+// deep — see the sibling comment on markCheck — so this walk must not grow
+// the JS call stack by one frame per link. Behavior (including the
+// first-changed-source short-circuit) is unchanged; only the mechanism is.
+function updateValue(startNode: ComputedNode): void {
+  if (startNode.disposed) {
+    startNode.status = STATUS_CLEAN;
+    return;
+  }
+  if (startNode.status !== STATUS_CHECK) {
+    runComputed(startNode);
+    return;
+  }
+
+  resolveComputedCheck!(startNode);
+}
+
+function resolveCheck(startNode: ComputedNode): void {
+  const stack: CheckFrame[] = [
+    {
+      node: startNode,
+      sources: startNode.sources ?? [],
+      versions: startNode.sourceMeta ?? [],
+      idx: 0,
+    },
+  ];
+  // Nodes with a frame on the stack. A self-referential computed lists itself
+  // as a source; descending into it again would push frames forever. Created
+  // lazily at the first descent, when the stack holds only startNode.
+  let onStack: Set<ComputedNode> | null = null;
+
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    const { node, sources, versions } = frame;
+    let descended = false;
+
+    while (frame.idx < sources.length) {
+      const src = sources[frame.idx];
+      if (src.fn !== null) {
+        const sc = src as ComputedNode;
+        if (sc.disposed) {
+          sc.status = STATUS_CLEAN;
+        } else if (sc.status === STATUS_CHECK) {
+          // A source already being resolved (a cycle) cannot be resolved again;
+          // compare its version as it stands instead of descending.
+          const onPath = onStack !== null ? onStack.has(sc) : sc === node;
+          if (!onPath) {
+            // Resolve sc before we can know whether it actually changed —
+            // push a frame for it instead of recursing into updateValue(sc).
+            (onStack ??= new Set(stack.map((f) => f.node))).add(sc);
+            stack.push({
+              node: sc,
+              sources: sc.sources ?? [],
+              versions: sc.sourceMeta ?? [],
+              idx: 0,
+            });
+            descended = true;
+            break;
+          }
+        } else if (sc.status !== STATUS_CLEAN) {
+          runComputed(sc);
+        }
+      }
+      if (src.version !== versions[frame.idx * 2]) {
+        node.status = STATUS_DIRTY;
+        break;
+      }
+      frame.idx++;
+    }
+
+    if (descended) continue;
+
+    if (node.status === STATUS_CHECK) {
+      node.status = STATUS_CLEAN;
+    } else {
+      runComputed(node);
+    }
+    onStack?.delete(node);
+    stack.pop();
+  }
+}
+
+/** Run fn without subscribing the active listener to what it reads. @internal */
+export function untracked<T>(fn: () => T): T {
+  const prevListener = activeListener;
+  activeListener = null;
+  try {
+    return fn();
+  } finally {
+    activeListener = prevListener;
+  }
+}
+
+/** Run and clear a scope's disposers; one throwing disposer doesn't stop the rest. @internal */
+export function disposeScope(scope: Scope): void {
+  const disposers = scope.disposers;
+  if (!disposers) return;
+  scope.disposers = null;
+  // Cleanup reads must not subscribe whatever is running the disposal (an
+  // effect re-running, a match() switching cases, a list removing rows).
+  const prevListener = activeListener;
+  activeListener = null;
+  try {
+    for (let i = 0; i < disposers.length; i++) {
+      try {
+        disposers[i]();
+      } catch (err) {
+        console.error('[Purity] Error during disposal:', err);
+      }
+    }
+  } finally {
+    activeListener = prevListener;
+  }
+}
+
+function runComputedValue(node: ComputedNode): void {
+  // Release the previous run before fn re-evaluates; the user's cleanup
+  // closure still sees the values from the run that produced it.
+  if (node.disposers !== null) disposeScope(node);
+  if (node.disposed) {
+    node.status = STATUS_CLEAN;
+    return;
+  }
+
+  const prevListener = activeListener;
+  const prevIdx = activeSourceIdx;
+
+  let nextValue: unknown;
+  // Re-run-to-fixpoint loop. For a pure compute this runs exactly once.
+  //
+  // A compute that reads a source S and then writes S in the SAME fn body
+  // demotes itself: the write's markDirty() flips this node's status to DIRTY
+  // mid-run (the node is an observer of S). The old code then force-settled
+  // CLEAN, stranding the node with a source version snapshot that no longer
+  // matches S — permanently un-reactive (it never re-ran on a later pull, and
+  // returned a stale value). Instead we settle CLEAN optimistically before
+  // fn(), and if the body demoted us back to DIRTY we re-run to converge on a
+  // fixed point so the final snapshot is consistent with the value. Capped at
+  // MAX_EFFECT_DEPTH to bound a body that writes a strictly-changing source on
+  // every pass (a user bug — computes are meant to be pure).
+  let runGuard = 0;
+  // A compute whose fn throws caches the error (see ComputedNode.error) and
+  // settles CLEAN so it is not retried until a source changes.
+  let thrown = false;
+  let thrownValue: unknown;
+  // Suspend the cached error for the attempt: a self-read inside fn() sees the
+  // previous value (as it did before errors were cached) instead of rethrowing
+  // the old error, so a self-referential compute can recover. The outcome is
+  // reinstated below only if this attempt throws again.
+  const prevError = node.error;
+  node.error = null;
+  for (;;) {
+    activeListener = node;
+    activeSourceIdx = 0;
+    // Optimistically CLEAN before running. A re-entrant self-write's
+    // markDirty() then observes us as CLEAN and demotes us to DIRTY, which we
+    // detect after fn() returns.
+    node.status = STATUS_CLEAN;
+
+    try {
+      nextValue = node.fn();
+      thrown = false;
+    } catch (e) {
+      thrown = true;
+      thrownValue = e;
+    } finally {
+      // Truncate stale source slots. Anything past activeSourceIdx is no
+      // longer read by this fn — drop the producer→consumer link.
+      const consumed = activeSourceIdx;
+      const sources = node.sources;
+      if (sources !== null && sources.length > consumed) {
+        for (let i = consumed; i < sources.length; i++) {
+          removeObserver(sources[i], node, i);
+        }
+        sources.length = consumed;
+        node.sourceMeta!.length = consumed * 2;
+      }
+      activeListener = prevListener;
+      activeSourceIdx = prevIdx;
+    }
+
+    if (node.status === STATUS_CLEAN) break;
+    if (++runGuard > MAX_EFFECT_DEPTH) {
+      // Body keeps invalidating itself. Settle CLEAN to stop the loop and
+      // surface the misuse rather than hang.
+      node.status = STATUS_CLEAN;
+      console.error(
+        '[Purity] compute() did not stabilise.' +
+          (__DEV__ ? ' Its body keeps writing a source it reads; computes must be pure.' : ''),
+      );
+      break;
+    }
+  }
+
+  let changed: boolean;
+  if (thrown) {
+    changed = prevError === null || !Object.is(prevError.value, thrownValue);
+    node.error = changed ? { value: thrownValue } : prevError;
+  } else {
+    changed = prevError !== null || !Object.is(node.value, nextValue);
+    node.value = nextValue;
+  }
+  if (changed) {
+    node.version++;
+    // Direct observers reading us through the CHECK→CLEAN fast path were
+    // optimistic; force them DIRTY now that we know our value moved.
+    if (node.observers !== null) {
+      const obs = node.observers;
+      for (let i = 0; i < obs.length; i++) {
+        if (obs[i].status === STATUS_CHECK) obs[i].status = STATUS_DIRTY;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Scheduler
+// ---------------------------------------------------------------------------
+
+function runComputed(node: ComputedNode): void {
+  if (node.isEffect) runEffect(node);
+  else runDerived!(node);
+}
+
+// Effects never expose a value or act as a producer, so they do not need the
+// computed evaluator's value/error cache or fixpoint loop. Their cleanup and
+// ownership behavior must match that evaluator's effect path.
+function runEffect(node: ComputedNode): void {
+  if (node.disposers !== null) disposeScope(node);
+  if (node.disposed) {
+    node.status = STATUS_CLEAN;
+    return;
+  }
+  if (++effectDepth > MAX_EFFECT_DEPTH) {
+    effectDepth--;
+    throw new Error(
+      '[Purity] Maximum effect depth exceeded.' +
+        (__DEV__ ? ' A watch/effect callback is likely modifying the signal it depends on.' : ''),
+    );
+  }
+  const prevListener = activeListener;
+  const prevIdx = activeSourceIdx;
+  activeListener = node;
+  activeSourceIdx = 0;
+  node.status = STATUS_CLEAN;
+  pushContext(node);
+  let nextValue: unknown;
+  try {
+    nextValue = node.fn();
+  } finally {
+    popContext();
+    const consumed = activeSourceIdx;
+    const sources = node.sources;
+    if (sources !== null && sources.length > consumed) {
+      for (let i = consumed; i < sources.length; i++) removeObserver(sources[i], node, i);
+      sources.length = consumed;
+      node.sourceMeta!.length = consumed * 2;
+    }
+    activeListener = prevListener;
+    activeSourceIdx = prevIdx;
+    effectDepth--;
+  }
+  if (typeof nextValue === 'function') (node.disposers ??= []).push(nextValue as () => void);
+  if (node.disposed) disposeScope(node);
+  node.status = STATUS_CLEAN;
+}
+
+function scheduleFlush(): void {
+  if (microtaskScheduled) return;
+  microtaskScheduled = true;
+  queueMicrotask(flush);
+}
+
+function flush(): void {
+  microtaskScheduled = false;
+  // Process effects FIFO. New effects pushed during flushing are picked up
+  // in subsequent loop iterations of this same flush.
+  //
+  // Isolate each effect's throw: a user watch/effect callback that throws
+  // would otherwise (a) skip every sibling queued after it — their views
+  // stay stale until some unrelated write retriggers a flush — and (b)
+  // skip `pendingEffects.length = 0` below, leaving the queue polluted
+  // with stale entries the next flush would re-run. Catch + console.error
+  // reports unowned/unhandled failures, while component-owned effects use
+  // the existing onError chain. The outer try/finally guarantees the queue
+  // is cleared regardless.
+  const id = ++flushSeq;
+  try {
+    let i = 0;
+    while (i < pendingEffects.length) {
+      const e = pendingEffects[i++];
+      if (e.disposed || e.status === STATUS_CLEAN) continue;
+      if (e.flushId !== id) {
+        e.flushId = id;
+        e.flushRuns = 0;
+      }
+      if (++e.flushRuns > MAX_EFFECT_REPEATS) {
+        console.error(
+          '[Purity] effect feedback loop detected.' +
+            (__DEV__
+              ? ` An effect re-ran more than ${MAX_EFFECT_REPEATS} times in one flush: ` +
+                'effects write signals that other effects read in a cycle. ' +
+                'The remaining queued effects did not run.'
+              : ''),
+        );
+        settleAfterLoop(i - 1);
+        break;
+      }
+      // A callback can stop its own effect, which releases node.component.
+      // Retain the owner just for this attempt, and re-check its lifetime
+      // after releasing the failed run's work below.
+      const owner = e.component;
+      try {
+        updateValue(e);
+      } catch (err) {
+        // runComputed left the node DIRTY (it sets CLEAN only on the
+        // success path). Without resetting here, markDirty's
+        // already-DIRTY short-circuit would skip the effect on every
+        // subsequent write — the watcher would silently never run
+        // again. CLEAN restores the normal CLEAN→DIRTY transition that
+        // the next markDirty needs to re-queue. Release what the failed run
+        // created before throwing; no later run is guaranteed to.
+        e.status = STATUS_CLEAN;
+        disposeScope(e);
+        try {
+          if (!owner || owner._isDestroyed) throw err;
+          const prevListener = activeListener;
+          activeListener = null;
+          try {
+            owner._handleError(err);
+          } finally {
+            activeListener = prevListener;
+          }
+        } catch (unhandled) {
+          console.error('[Purity] watch/effect threw:', unhandled);
+        }
+      }
+    }
+  } finally {
+    pendingEffects.length = 0;
+  }
+}
+
+// Called when flush() cuts a feedback loop. Drops the queued effects from
+// `from` onward and makes their upstream computeds re-checkable. markDirty
+// skips nodes already DIRTY, so a computed left DIRTY would swallow the next
+// write to its source and its watcher would stay stale for good. Demoting the
+// DIRTY/CHECK ancestors to CHECK (not CLEAN) keeps them correct: a read
+// re-verifies their sources, and a write re-invalidates them.
+function settleAfterLoop(from: number): void {
+  if (settleComputedLoop) {
+    settleComputedLoop(from);
+    return;
+  }
+  for (let j = from; j < pendingEffects.length; j++) pendingEffects[j].status = STATUS_CLEAN;
+}
+
+function settleLoopWithComputeds(from: number): void {
+  const stack: ComputedNode[] = [];
+  for (let j = from; j < pendingEffects.length; j++) {
+    const e = pendingEffects[j];
+    e.status = STATUS_CLEAN;
+    if (e.sources !== null) {
+      for (const src of e.sources) if (src.fn !== null) stack.push(src);
+    }
+  }
+  const seen = new Set<ComputedNode>();
+  while (stack.length > 0) {
+    const c = stack.pop()!;
+    if (c.status === STATUS_CLEAN || seen.has(c)) continue;
+    seen.add(c);
+    c.status = STATUS_CHECK;
+    if (c.sources !== null) {
+      for (const src of c.sources) if (src.fn !== null) stack.push(src);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public types & API
+// ---------------------------------------------------------------------------
+
+/**
+ * Reactive state accessor. Call to read, call with value to write.
+ *
+ * @example
+ * ```ts
+ * const count = state(0);
+ * count()          // read → 0
+ * count(5)         // write → 5
+ * count(v => v+1)  // update → 6
+ * count.peek()     // read without tracking
+ * ```
+ */
+export interface StateAccessor<T> {
+  /** Read the current value (tracked by watch/compute). */
+  (): T;
+  /** Set a new value. */
+  (value: T): T;
+  /** Update via callback — receives current value, returns new value. */
+  (updater: (current: T) => T): T;
+  /** Read the current value (tracked). */
+  get(): T;
+  /** Set a new value. */
+  set(value: T): void;
+  /** Read without tracking — won't trigger watch/compute. */
+  peek(): T;
+}
+
+/**
+ * Reactive computed accessor. Read-only derived value.
+ *
+ * @example
+ * ```ts
+ * const doubled = compute(() => count() * 2);
+ * doubled()      // read derived value
+ * doubled.peek() // read without tracking
+ * ```
+ */
+export interface ComputedAccessor<T> {
+  /** Read the derived value (tracked). */
+  (): T;
+  /** Read the derived value (tracked). */
+  get(): T;
+  /** Read without tracking. */
+  peek(): T;
+}
+
+/** Cleanup function returned by watch(). Call to stop watching. */
+export type Dispose = () => void;
+
+// ---------------------------------------------------------------------------
+// state(initial)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create reactive state. Returns an accessor function.
+ *
+ * @example
+ * ```ts
+ * const count = state(0);
+ * count()              // read → 0
+ * count(5)             // write → 5
+ * count(v => v + 1)    // update with callback → 6
+ *
+ * // In templates — wrap in arrow for reactivity:
+ * html`<p>${() => count()}</p>`
+ *
+ * // Two-way binding on inputs:
+ * html`<input ::value=${count} />`
+ * ```
+ */
+export function state<T>(initial: T): StateAccessor<T> {
+  const node: StateNode<T> = {
+    fn: null,
+    value: initial,
+    version: 0,
+    observers: null,
+  };
+  if (__DEV__) trackNode(node);
+
+  const accessor = function (value?: T | ((current: T) => T)): T {
+    if (arguments.length === 0) return readState(node);
+    const next = typeof value === 'function' ? (value as (current: T) => T)(node.value) : value;
+    writeState(node, next as T);
+    return next as T;
+  } as StateAccessor<T>;
+
+  // Avoid `bind()` and per-call closures: we can attach the property API
+  // directly because every call routes through `node` already.
+  (accessor as unknown as { get: () => T }).get = () => readState(node);
+  (accessor as unknown as { set: (v: T) => void }).set = (v: T) => {
+    writeState(node, v);
+  };
+  (accessor as unknown as { peek: () => T }).peek = () => node.value;
+
+  return accessor;
+}
+
+// ---------------------------------------------------------------------------
+// compute(fn)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a computed (derived) value. Re-evaluates when dependencies change.
+ *
+ * @example
+ * ```ts
+ * const count = state(0);
+ * const doubled = compute(() => count() * 2);
+ * doubled()  // → 0
+ * count(5);
+ * doubled()  // → 10
+ *
+ * // In templates:
+ * html`<p>${() => doubled()}</p>`
+ * ```
+ */
+function createComputedNode(fn: () => unknown, isEffect: boolean): ComputedNode {
+  const node: ComputedNode = {
+    fn,
+    value: undefined,
+    version: 0,
+    status: STATUS_DIRTY,
+    sources: null,
+    sourceMeta: null,
+    observers: null,
+    disposers: null,
+    component: isEffect ? getCurrentComponent() : null,
+    isEffect,
+    disposed: false,
+    error: null,
+    flushId: 0,
+    flushRuns: 0,
+  };
+  if (__DEV__) trackNode(node);
+  return node;
+}
+
+export function compute<T>(fn: () => T): ComputedAccessor<T> {
+  runDerived = runComputedValue;
+  propagateComputedCheck = markCheck;
+  resolveComputedCheck = resolveCheck;
+  settleComputedLoop = settleLoopWithComputeds;
+  const node = createComputedNode(fn as () => unknown, false);
+  // Register with the current scope so a computed created inside a branch
+  // that unmounts is detached from its sources (no dangling observer links).
+  const dispose = (): void => {
+    if (node.disposed) return;
+    node.disposed = true;
+    disconnectFromSources(node);
+  };
+  const ctx = getCurrentContext();
+  if (ctx) (ctx.disposers ??= []).push(dispose);
+
+  const accessor = (() => readNode<T>(node)) as ComputedAccessor<T>;
+  (accessor as unknown as { get: () => T }).get = accessor;
+  (accessor as unknown as { peek: () => T }).peek = () => readNode<T>(node, false);
+
+  return accessor;
+}
+
+// ---------------------------------------------------------------------------
+// Internal effect runner
+// ---------------------------------------------------------------------------
+
+/** @internal Run a single auto-tracked effect for compiled templates. */
+export function watchEffectInternal(fn: () => undefined | Dispose): Dispose {
+  const node = createComputedNode(fn as () => unknown, true);
+
+  // Effects run their initial body eagerly (synchronous) — the templates
+  // and tests rely on this to set up DOM bindings before the user code
+  // continues.
+  // A throwing initial run never returns a disposer to the caller, so drop the
+  // sources it managed to read before the throw; otherwise the unreachable
+  // effect stays subscribed and re-runs on later writes.
+  try {
+    updateValue(node);
+  } catch (e) {
+    node.disposed = true;
+    disposeScope(node);
+    disconnectFromSources(node);
+    throw e;
+  }
+
+  const dispose = (): void => {
+    if (node.disposed) return;
+    node.disposed = true;
+    disposeScope(node);
+    disconnectFromSources(node);
+    // A retained stop handle must not keep an unmounted component alive.
+    node.component = null;
+  };
+
+  // Auto-register with the current component/render context so reactive
+  // bindings created inside a template (or inside an each() entry, a
+  // component, etc.) are torn down when that scope unmounts.
+  const ctx = getCurrentContext();
+  if (ctx) (ctx.disposers ??= []).push(dispose);
+
+  return dispose;
+}
+
+// ---------------------------------------------------------------------------
+// watch — unified reactive watcher
+// ---------------------------------------------------------------------------
+
+export type WatchSource<T> = StateAccessor<T> | ComputedAccessor<T> | (() => T);
+
+type InferSource<S> = S extends WatchSource<infer T> ? T : never;
+
+type InferSources<S extends readonly WatchSource<any>[]> = {
+  [K in keyof S]: InferSource<S[K]>;
+};
+
+/**
+ * Watch reactive values and run side effects.
+ *
+ * **Auto-track** — runs immediately, re-runs when any accessed signal changes:
+ * ```ts
+ * watch(() => console.log(count()));
+ * ```
+ *
+ * **Explicit source** — runs callback when source changes (skips initial):
+ * ```ts
+ * watch(count, (newVal, oldVal) => {
+ *   console.log(`changed from ${oldVal} to ${newVal}`);
+ * });
+ * ```
+ *
+ * **Multiple sources** — watches a tuple of signals:
+ * ```ts
+ * watch([count, name], ([c, n], [oldC, oldN]) => {
+ *   console.log(c, n);
+ * });
+ * ```
+ *
+ * **Cleanup** — return a function from the callback to clean up before re-run:
+ * ```ts
+ * const stop = watch(() => {
+ *   const id = setInterval(() => tick(), 1000);
+ *   return () => clearInterval(id);  // cleanup
+ * });
+ * stop(); // dispose the watcher
+ * ```
+ *
+ * @returns Dispose function — call to stop watching.
+ */
+export function watch(fn: () => undefined | Dispose): Dispose;
+export function watch<T>(
+  source: WatchSource<T>,
+  cb: (value: T, oldValue: T) => undefined | Dispose,
+): Dispose;
+export function watch<const S extends readonly WatchSource<any>[]>(
+  sources: [...S],
+  cb: (values: InferSources<S>, oldValues: InferSources<S>) => undefined | Dispose,
+): Dispose;
+
+export function watch(
+  sourceOrFn: WatchSource<any> | WatchSource<any>[] | (() => undefined | Dispose),
+  cb?: (value: any, oldValue: any) => undefined | Dispose,
+): Dispose {
+  if (!cb) {
+    return watchEffectInternal(sourceOrFn as () => undefined | Dispose);
+  }
+
+  const isArray = Array.isArray(sourceOrFn);
+  const sources: WatchSource<any>[] = isArray ? sourceOrFn : [sourceOrFn as WatchSource<any>];
+  const len = sources.length;
+
+  let oldValues = new Array(len);
+  let newValues = new Array(len);
+
+  // The eager first effect run samples and subscribes to every source; the
+  // buffer swap below keeps those values as the next callback's oldValues.
+  // Do not read source getters here as well: that evaluates user code twice.
+  let first = true;
+
+  return watchEffectInternal(() => {
+    // A callback may retain tuple arguments even if it throws. Recycle only
+    // the single-source buffers; each tuple run owns its own snapshot array.
+    if (isArray) newValues = [];
+    for (let i = 0; i < len; i++) newValues[i] = sources[i]();
+
+    // The first run only records the values; cb fires from the next change.
+    // Explicit sources alone control re-runs; callback reads are not dependencies.
+    const result = first
+      ? undefined
+      : untracked(() => {
+          return isArray ? cb(newValues, oldValues) : cb(newValues[0], oldValues[0]);
+        });
+    first = false;
+
+    const tmp = oldValues;
+    oldValues = newValues;
+    newValues = tmp;
+
+    return result;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// batch(fn)
+// ---------------------------------------------------------------------------
+
+/**
+ * Batch multiple signal writes into a single flush. Effects only run once
+ * after the batch.
+ *
+ * @example
+ * ```ts
+ * batch(() => {
+ *   firstName('Jane');
+ *   lastName('Doe');
+ *   age(30);
+ * });
+ * // Effects that depend on these signals fire once, not three times.
+ * ```
+ */
+export function batch(fn: () => void): void {
+  batchDepth++;
+  try {
+    fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0 && pendingEffects.length > 0) scheduleFlush();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// __purity_inspect__ — debugging hook on globalThis
+//
+// See `docs/debugging.md` for usage and ADR-0002 for the rationale.
+// ---------------------------------------------------------------------------
+
+type InspectorKind = 'state' | 'computed' | 'effect';
+type InspectorStatus = 'clean' | 'check' | 'dirty';
+
+interface InspectorNode {
+  kind: InspectorKind;
+  version: number;
+  status?: InspectorStatus;
+  value: unknown;
+  sources: InspectorNode[];
+  observers: InspectorNode[];
+}
+
+// Everything below is dev-only: see the __DEV__ comment above trackedNodes.
+// A production build that folds __DEV__ to false can drop this entire block
+// — the inspector hook, its node-graph conversion, and the labels array —
+// since nothing outside this block (or outside development tooling) calls
+// any of it.
+if (__DEV__) {
+  const INSPECTOR_STATUS_LABELS: readonly InspectorStatus[] = ['clean', 'check', 'dirty'];
+
+  const inspectorKindOf = (n: AnyNode): InspectorKind => {
+    if (n.fn === null) return 'state';
+    return (n as ComputedNode).isEffect ? 'effect' : 'computed';
+  };
+
+  const toInspectorNode = (n: AnyNode, seen: Map<AnyNode, InspectorNode>): InspectorNode => {
+    const cached = seen.get(n);
+    if (cached) return cached;
+    const out: InspectorNode = {
+      kind: inspectorKindOf(n),
+      version: n.version,
+      value: n.value,
+      sources: [],
+      observers: [],
+    };
+    if (n.fn !== null) out.status = INSPECTOR_STATUS_LABELS[(n as ComputedNode).status];
+    seen.set(n, out);
+    if (n.fn !== null) {
+      const sources = (n as ComputedNode).sources;
+      if (sources !== null) {
+        for (let i = 0; i < sources.length; i++) {
+          out.sources.push(toInspectorNode(sources[i], seen));
+        }
+      }
+    }
+    if (n.observers !== null) {
+      for (let i = 0; i < n.observers.length; i++) {
+        out.observers.push(toInspectorNode(n.observers[i], seen));
+      }
+    }
+    return out;
+  };
+
+  const inspectorLiveNodes = (): AnyNode[] => {
+    const live: AnyNode[] = [];
+    for (const ref of trackedNodes!) {
+      const n = ref.deref();
+      if (n) live.push(n);
+      else trackedNodes!.delete(ref);
+    }
+    return live;
+  };
+
+  // Install the hook eagerly at module load. The assignment is a side
+  // effect on globalThis that bundlers must preserve. `globalThis` works
+  // in workers, sandboxed iframes, jsdom, etc. — falls back to a no-op if
+  // somehow absent.
+  /* v8 ignore next 2 -- defensive; globalThis exists everywhere we run */
+  const inspectorTarget: { __purity_inspect__?: unknown } | null =
+    typeof globalThis !== 'undefined' ? (globalThis as { __purity_inspect__?: unknown }) : null;
+  if (inspectorTarget !== null) {
+    inspectorTarget.__purity_inspect__ = {
+      version: 1 as const,
+      nodes(): InspectorNode[] {
+        const seen = new Map<AnyNode, InspectorNode>();
+        return inspectorLiveNodes().map((n) => toInspectorNode(n, seen));
+      },
+    };
+  }
+}