@fluixi/reactive 1.0.0-alpha.82 → 1.0.0-alpha.84

package/dist/lib/signal/graph/core.cjs

@@ -1 +1,295 @@
-"use strict";var l=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var T=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var S=(s,e)=>{for(var t in e)l(s,t,{get:e[t],enumerable:!0})},m=(s,e,t,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of T(e))!k.call(s,i)&&i!==t&&l(s,i,{get:()=>e[i],enumerable:!(o=b(e,i))||o.enumerable});return s};var g=s=>m(l({},"__esModule",{value:!0}),s);var D={};S(D,{Computed:()=>f,State:()=>d,Watcher:()=>p,currentComputed:()=>N,hasSinks:()=>E,untrack:()=>C});module.exports=g(D);var q="__fluixi_signal_next_state__",x=s=>{typeof queueMicrotask=="function"?queueMicrotask(s):Promise.resolve().then(s)},r=globalThis[q]??={consumer:null,untracked:!1,owner:null,queue:[],scheduled:!1,flushing:!1,batchDepth:0,hostSchedule:x,onSuspend:null,onError:null};var _=0,w=1,a=2,h=class{constructor(){this.observers=null;this.watchers=null;this.version=0}updateIfNecessary(){}track(){if(r.untracked)return;let e=r.consumer;e&&((this.observers??=new Set).add(e),(e.sources??=new Set).add(this))}},d=class extends h{constructor(e,t){super(),this._value=e,this._equals=t?.equals===!1?()=>!1:t?.equals??Object.is}get(){return this.track(),this._value}set(e){if(!this._equals(this._value,e)){if(this._value=e,this.version++,this.observers)for(let t of[...this.observers])t.markDirty(a);v(this)}}peek(){return this._value}},f=class extends h{constructor(t,o){super();this._threw=!1;this._initialized=!1;this.state=a;this.sources=null;this._fn=t,this._equals=o?.equals===!1?()=>!1:o?.equals??Object.is}get(){if(r.consumer===this)throw new Error("Signal.Computed cannot read itself");if(this.track(),this.updateIfNecessary(),this._threw)throw this._error;return this._value}updateIfNecessary(){if(this.state===w&&this.sources){for(let t of this.sources)if(t.updateIfNecessary(),this.state===a)break}(this.state===a||!this._initialized)&&this.recompute(),this.state=_}recompute(){if(this.sources){for(let n of this.sources)n.observers?.delete(this);this.sources.clear()}let t=r.consumer,o=r.untracked;r.consumer=this,r.untracked=!1;let i,u=!1,c;try{i=this._fn()}catch(n){u=!0,c=n,i=this._value}finally{r.consumer=t,r.untracked=o}let y=!this._initialized||this._threw!==u||(u?c!==this._error:!this._equals(this._value,i));if(this._initialized=!0,this._threw=u,this._error=c,this._value=i,y){if(this.version++,this.observers)for(let n of[...this.observers])n.markDirty(a);v(this)}}markDirty(t){if(this.state>=t)return;let o=this.state===_;if(this.state=t,o){if(this.observers)for(let i of[...this.observers])i.markDirty(w);v(this)}}peek(){if(this.updateIfNecessary(),this._threw)throw this._error;return this._value}};function v(s){if(s.watchers)for(let e of[...s.watchers])e._notify(s)}var p=class{constructor(e){this._watched=new Set;this._pending=new Set;this._notifyFn=e}watch(...e){for(let t of e)this._watched.add(t),(t.watchers??=new Set).add(this)}unwatch(...e){for(let t of e)this._watched.delete(t),t.watchers?.delete(this),this._pending.delete(t)}getPending(){let e=[...this._pending];return this._pending.clear(),e}_notify(e){if(!this._watched.has(e)||this._pending.has(e))return;let t=this._pending.size===0;this._pending.add(e),t&&this._notifyFn()}};function C(s){if(r.untracked)return s();r.untracked=!0;try{return s()}finally{r.untracked=!1}}function N(){return r.consumer}function E(s){return!!(s.observers&&s.observers.size)||!!(s.watchers&&s.watchers.size)}
+/*! @fluixi/reactive v1.0.0-alpha.84 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/signal/graph/core.ts
+var core_exports = {};
+__export(core_exports, {
+  Computed: () => Computed,
+  State: () => State,
+  Watcher: () => Watcher,
+  currentComputed: () => currentComputed,
+  hasSinks: () => hasSinks,
+  untrack: () => untrack
+});
+module.exports = __toCommonJS(core_exports);
+
+// src/version.generated.ts
+var VERSION = "1.0.0-alpha.84";
+
+// src/lib/signal/graph/state.ts
+var MAJOR = VERSION.split(".")[0];
+var KEY = `__fluixi_signal_state_v${MAJOR}__`;
+var VERSIONS_KEY = `__fluixi_signal_builds_v${MAJOR}__`;
+var defaultSchedule = (run) => {
+  if (typeof queueMicrotask === "function") queueMicrotask(run);
+  else void Promise.resolve().then(run);
+};
+function defaults() {
+  return {
+    consumer: null,
+    untracked: false,
+    owner: null,
+    queue: [],
+    scheduled: false,
+    flushing: false,
+    batchDepth: 0,
+    hostSchedule: defaultSchedule,
+    onSuspend: null,
+    onError: null,
+    observer: null
+  };
+}
+var realm = globalThis;
+function backfillState(existing) {
+  const fresh = defaults();
+  const target = existing;
+  for (const field of Object.keys(fresh)) {
+    if (!(field in existing)) target[field] = fresh[field];
+  }
+  return existing;
+}
+function claim() {
+  const existing = realm[KEY];
+  return existing ? backfillState(existing) : realm[KEY] = defaults();
+}
+var G = claim();
+(realm[VERSIONS_KEY] ??= []).push(VERSION);
+
+// src/lib/signal/graph/observe.ts
+function observeReactiveNodes(next) {
+  G.observer = next;
+  return () => {
+    if (G.observer === next) G.observer = null;
+  };
+}
+var running = [];
+function enterReactiveRun(node) {
+  if (!G.observer) return false;
+  running.push(node);
+  return true;
+}
+function exitReactiveRun() {
+  running.pop();
+}
+function reportReactiveRun(node) {
+  G.observer?.ran?.(node);
+}
+function reportReactiveWrite(node, by) {
+  G.observer?.wrote?.(node, by);
+}
+var HOOK = "__FLUIXI_DEVTOOLS_HOOK__";
+var hook = globalThis[HOOK];
+if (typeof hook?.inject === "function") {
+  try {
+    hook.inject({ observeReactiveNodes, version: VERSION });
+  } catch {
+  }
+}
+
+// src/lib/signal/graph/core.ts
+var CLEAN = 0;
+var CHECK = 1;
+var DIRTY = 2;
+var Source = class {
+  constructor() {
+    /** Computeds, and watched leaves, that read this node. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.observers = null;
+    /** Watchers eagerly observing this node, which is how `runtime.ts` schedules effects. */
+    this.watchers = null;
+    /** Bumped whenever this node's value actually changes (equality-gated). */
+    this.version = 0;
+  }
+  /** Settle this node so a reader sees a current value/version. Overridden by Computed. */
+  updateIfNecessary() {
+  }
+  /** Link the current consumer (if any) as an observer of this node. */
+  track() {
+    if (G.untracked) return;
+    const consumer = G.consumer;
+    if (!consumer) return;
+    (this.observers ??= /* @__PURE__ */ new Set()).add(consumer);
+    (consumer.sources ??= /* @__PURE__ */ new Set()).add(this);
+  }
+};
+var State = class extends Source {
+  constructor(value, options) {
+    super();
+    this._value = value;
+    this._equals = options?.equals === false ? () => false : options?.equals ?? Object.is;
+  }
+  get() {
+    this.track();
+    return this._value;
+  }
+  set(next) {
+    if (this._equals(this._value, next)) return;
+    this._value = next;
+    this.version++;
+    reportReactiveWrite(this, G.consumer);
+    if (this.observers) for (const o of [...this.observers]) o.markDirty(DIRTY);
+    notifyWatchers(this);
+  }
+  /** Read without subscribing (peek). */
+  peek() {
+    return this._value;
+  }
+};
+var Computed = class extends Source {
+  constructor(fn, options) {
+    super();
+    this._threw = false;
+    this._initialized = false;
+    this.state = DIRTY;
+    /** Nodes this computation read on its last run. Rebuilt on every run. */
+    this.sources = null;
+    this._fn = fn;
+    this._equals = options?.equals === false ? () => false : options?.equals ?? Object.is;
+  }
+  get() {
+    if (G.consumer === this) {
+      throw new Error("Signal.Computed cannot read itself");
+    }
+    this.track();
+    this.updateIfNecessary();
+    if (this._threw) throw this._error;
+    return this._value;
+  }
+  /** Settle, if CHECK, verify sources; if DIRTY (or never run), recompute. */
+  updateIfNecessary() {
+    if (this.state === CHECK) {
+      if (this.sources) {
+        for (const s of this.sources) {
+          s.updateIfNecessary();
+          if (this.state === DIRTY) break;
+        }
+      }
+    }
+    if (this.state === DIRTY || !this._initialized) this.recompute();
+    this.state = CLEAN;
+  }
+  recompute() {
+    if (this.sources) {
+      for (const s of this.sources) s.observers?.delete(this);
+      this.sources.clear();
+    }
+    const prevConsumer = G.consumer;
+    const prevUntracked = G.untracked;
+    const watched = enterReactiveRun(this);
+    G.consumer = this;
+    G.untracked = false;
+    let next;
+    let threw = false;
+    let err;
+    try {
+      next = this._fn();
+    } catch (e) {
+      threw = true;
+      err = e;
+      next = this._value;
+    } finally {
+      G.consumer = prevConsumer;
+      G.untracked = prevUntracked;
+      if (watched) exitReactiveRun();
+    }
+    const changed = !this._initialized || this._threw !== threw || (threw ? err !== this._error : !this._equals(this._value, next));
+    this._initialized = true;
+    this._threw = threw;
+    this._error = err;
+    this._value = next;
+    reportReactiveRun(this);
+    if (changed) {
+      this.version++;
+      if (this.observers) for (const o of [...this.observers]) o.markDirty(DIRTY);
+      notifyWatchers(this);
+    }
+  }
+  /**
+   * Push a maybe-dirty mark. A direct observer of a changed node gets DIRTY; its
+   * own observers get CHECK (recurse), stopping where already marked, so the
+   * push is O(newly-dirtied) and never recomputes.
+   */
+  markDirty(level) {
+    if (this.state >= level) return;
+    const wasClean = this.state === CLEAN;
+    this.state = level;
+    if (wasClean) {
+      if (this.observers) for (const o of [...this.observers]) o.markDirty(CHECK);
+      notifyWatchers(this);
+    }
+  }
+  peek() {
+    this.updateIfNecessary();
+    if (this._threw) throw this._error;
+    return this._value;
+  }
+};
+function notifyWatchers(node) {
+  if (!node.watchers) return;
+  for (const w of [...node.watchers]) w._notify(node);
+}
+var Watcher = class {
+  constructor(notify) {
+    this._watched = /* @__PURE__ */ new Set();
+    this._pending = /* @__PURE__ */ new Set();
+    this._notifyFn = notify;
+  }
+  watch(...nodes) {
+    for (const n of nodes) {
+      this._watched.add(n);
+      (n.watchers ??= /* @__PURE__ */ new Set()).add(this);
+    }
+  }
+  unwatch(...nodes) {
+    for (const n of nodes) {
+      this._watched.delete(n);
+      n.watchers?.delete(this);
+      this._pending.delete(n);
+    }
+  }
+  /** Watched nodes that may have changed since the last getPending(). */
+  getPending() {
+    const out = [...this._pending];
+    this._pending.clear();
+    return out;
+  }
+  /** @internal, a watched node became non-clean. Edge-triggered: notify once. */
+  _notify(node) {
+    if (!this._watched.has(node) || this._pending.has(node)) return;
+    const wasEmpty = this._pending.size === 0;
+    this._pending.add(node);
+    if (wasEmpty) this._notifyFn();
+  }
+};
+function untrack(fn) {
+  if (G.untracked) return fn();
+  G.untracked = true;
+  try {
+    return fn();
+  } finally {
+    G.untracked = false;
+  }
+}
+function currentComputed() {
+  return G.consumer;
+}
+function hasSinks(node) {
+  return !!(node.observers && node.observers.size) || !!(node.watchers && node.watchers.size);
+}

package/dist/lib/signal/graph/core.d.ts

@@ -1,19 +1,23 @@
 /**
- * L0 — the TC39-shaped reactive graph core.
+ * The TC39-shaped reactive graph core.
  *
- * Class-based primitives (`State`, `Computed`, `Watcher`) that own ONLY the
- * dependency graph: values, versions, source/observer edges, the lazy push-pull
- * state machine, and glitch-free pull evaluation. They know nothing about
- * ownership, scheduling, effects, suspense, or resources — those live in the L1
- * runtime that sits on top (see ../signal.ts). This is a re-shaping of the exact
- * algorithm the existing graph already runs (CLEAN/CHECK/DIRTY + version + the
- * `Listener`/observers edges), so behaviour is preserved; it's just relocated
- * onto classes whose shape matches the TC39 Signals proposal.
+ * `State`, `Computed` and `Watcher` own the dependency graph and nothing else:
+ * values, versions, source and observer edges, the lazy state machine, and
+ * glitch-free pull evaluation. Ownership, scheduling, effects, suspense and
+ * resources all live in `runtime.ts`, with the `create*` surface over them in
+ * `compat.ts`.
  *
- * The model is the "push the dirt, pull the value" scheme (Reactively / SolidJS /
- * the TC39 polyfill): a write PUSHES a maybe-dirty mark down to observers without
- * recomputing; a read PULLS, settling upstream lazily and recomputing only what
- * actually changed (equality-gated). Reads outside a tracking scope don't subscribe.
+ * `../signal.ts` also implements a graph and is not the one that runs. It is
+ * archive, reachable only through the `@fluixi/reactive/signal-legacy` entry, and
+ * editing it changes nothing here. Its `Computation` and `signalObservers` are the
+ * earlier spelling of what `Computed` and `Source.observers` do below, which is
+ * the only reason to open it.
+ *
+ * The scheme is push the dirt, pull the value, as in Reactively, SolidJS and the
+ * TC39 polyfill. A write pushes a maybe-dirty mark down to observers without
+ * recomputing anything. A read pulls: upstream settles lazily and only what
+ * actually changed recomputes, gated on equality. A read outside a tracking scope
+ * subscribes to nothing.
  */
 declare const CLEAN = 0;
 declare const CHECK = 1;
@@ -21,9 +25,9 @@ declare const DIRTY = 2;
 type NodeState = typeof CLEAN | typeof CHECK | typeof DIRTY;
 /** A thing that can be depended upon: holds observers + a monotonic version. */
 declare abstract class Source {
-    /** Computeds (and watched leaves) that read this node. (was the signalObservers entry) */
+    /** Computeds, and watched leaves, that read this node. */
     observers: Set<Computed<any>> | null;
-    /** Watchers eagerly observing this node, for effect scheduling (L1). */
+    /** Watchers eagerly observing this node, which is how `runtime.ts` schedules effects. */
     watchers: Set<Watcher> | null;
     /** Bumped whenever this node's value actually changes (equality-gated). */
     version: number;
@@ -49,7 +53,7 @@ export declare class Computed<T> extends Source {
     private _threw;
     private _initialized;
     state: NodeState;
-    /** Nodes this computation read on its last run. (was Computation.sources) */
+    /** Nodes this computation read on its last run. Rebuilt on every run. */
     sources: Set<Source> | null;
     private readonly _fn;
     private readonly _equals;
@@ -57,21 +61,21 @@ export declare class Computed<T> extends Source {
         equals?: ((a: T, b: T) => boolean) | false;
     });
     get(): T;
-    /** Settle: if CHECK, verify sources; if DIRTY (or never run), recompute. */
+    /** Settle, if CHECK, verify sources; if DIRTY (or never run), recompute. */
     updateIfNecessary(): void;
     private recompute;
     /**
      * Push a maybe-dirty mark. A direct observer of a changed node gets DIRTY; its
-     * own observers get CHECK (recurse) — stopping where already marked, so the
+     * own observers get CHECK (recurse), stopping where already marked, so the
      * push is O(newly-dirtied) and never recomputes.
      */
     markDirty(level: NodeState): void;
     peek(): T;
 }
 /**
- * Signal.subtle.Watcher — the only eager observation primitive. Its callback fires
- * when a watched signal MAY have changed; the callback MUST NOT read or write
- * signals. Effects (L1) are built on this + a scheduler.
+ * Signal.subtle.Watcher, the only eager observation primitive. Its callback fires
+ * when a watched signal MAY have changed; the callback must not read or write
+ * signals. Effects are built on this and a scheduler, in `runtime.ts`.
  */
 export declare class Watcher {
     private readonly _notifyFn;
@@ -82,12 +86,12 @@ export declare class Watcher {
     unwatch(...nodes: Source[]): void;
     /** Watched nodes that may have changed since the last getPending(). */
     getPending(): Source[];
-    /** @internal — a watched node became non-clean. Edge-triggered: notify once. */
+    /** @internal, a watched node became non-clean. Edge-triggered: notify once. */
     _notify(node: Source): void;
 }
-/** Signal.subtle.untrack — run `fn` without subscribing the current consumer. */
+/** Signal.subtle.untrack: run `fn` without subscribing the current consumer. */
 export declare function untrack<T>(fn: () => T): T;
-/** Signal.subtle.currentComputed — the computed currently evaluating, or null. */
+/** Signal.subtle.currentComputed, the computed currently evaluating, or null. */
 export declare function currentComputed(): Computed<unknown> | null;
 /** Whether a node currently has observers/watchers (Signal.subtle.hasSinks). */
 export declare function hasSinks(node: Source): boolean;

package/dist/lib/signal/graph/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/lib/signal/graph/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,QAAA,MAAM,KAAK,IAAI,CAAC;AAChB,QAAA,MAAM,KAAK,IAAI,CAAC;AAChB,QAAA,MAAM,KAAK,IAAI,CAAC;AAChB,KAAK,SAAS,GAAG,OAAO,KAAK,GAAG,OAAO,KAAK,GAAG,OAAO,KAAK,CAAC;AAK5D,gFAAgF;AAChF,uBAAe,MAAM;IACnB,0FAA0F;IAE1F,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAQ;IAC5C,wEAAwE;IACxE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,CAAQ;IACrC,2EAA2E;IAC3E,OAAO,SAAK;IAEZ,yFAAyF;IACzF,iBAAiB,IAAI,IAAI;IAEzB,sEAAsE;IACtE,SAAS,CAAC,KAAK,IAAI,IAAI;CAOxB;AAED,qBAAa,KAAK,CAAC,CAAC,CAAE,SAAQ,MAAM;IAClC,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAEtC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,KAAK,CAAA;KAAE;IAM9E,GAAG,IAAI,CAAC;IAKR,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAYlB,uCAAuC;IACvC,IAAI,IAAI,CAAC;CAGV;AAED,qBAAa,QAAQ,CAAC,CAAC,CAAE,SAAQ,MAAM;IACrC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAS;IAC7B,KAAK,EAAE,SAAS,CAAS;IACzB,6EAA6E;IAC7E,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAEtC,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,KAAK,CAAA;KAAE;IAMjF,GAAG,IAAI,CAAC;IAWR,4EAA4E;IACnE,iBAAiB,IAAI,IAAI;IAelC,OAAO,CAAC,SAAS;IA0CjB;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAUjC,IAAI,IAAI,CAAC;CAKV;AAOD;;;;GAIG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAqB;gBAEzB,MAAM,EAAE,MAAM,IAAI;IAI9B,KAAK,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAO/B,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAQjC,uEAAuE;IACvE,UAAU,IAAI,MAAM,EAAE;IAMtB,gFAAgF;IAChF,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAM5B;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAQzC;AAED,kFAAkF;AAClF,wBAAgB,eAAe,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAE1D;AAED,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9C"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/lib/signal/graph/core.ts"],"names":[],"mappings":"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"}

package/dist/lib/signal/graph/core.js

@@ -1,23 +1,31 @@
 /**
- * L0 — the TC39-shaped reactive graph core.
+ * The TC39-shaped reactive graph core.
  *
- * Class-based primitives (`State`, `Computed`, `Watcher`) that own ONLY the
- * dependency graph: values, versions, source/observer edges, the lazy push-pull
- * state machine, and glitch-free pull evaluation. They know nothing about
- * ownership, scheduling, effects, suspense, or resources — those live in the L1
- * runtime that sits on top (see ../signal.ts). This is a re-shaping of the exact
- * algorithm the existing graph already runs (CLEAN/CHECK/DIRTY + version + the
- * `Listener`/observers edges), so behaviour is preserved; it's just relocated
- * onto classes whose shape matches the TC39 Signals proposal.
+ * `State`, `Computed` and `Watcher` own the dependency graph and nothing else:
+ * values, versions, source and observer edges, the lazy state machine, and
+ * glitch-free pull evaluation. Ownership, scheduling, effects, suspense and
+ * resources all live in `runtime.ts`, with the `create*` surface over them in
+ * `compat.ts`.
  *
- * The model is the "push the dirt, pull the value" scheme (Reactively / SolidJS /
- * the TC39 polyfill): a write PUSHES a maybe-dirty mark down to observers without
- * recomputing; a read PULLS, settling upstream lazily and recomputing only what
- * actually changed (equality-gated). Reads outside a tracking scope don't subscribe.
+ * `../signal.ts` also implements a graph and is not the one that runs. It is
+ * archive, reachable only through the `@fluixi/reactive/signal-legacy` entry, and
+ * editing it changes nothing here. Its `Computation` and `signalObservers` are the
+ * earlier spelling of what `Computed` and `Source.observers` do below, which is
+ * the only reason to open it.
+ *
+ * The scheme is push the dirt, pull the value, as in Reactively, SolidJS and the
+ * TC39 polyfill. A write pushes a maybe-dirty mark down to observers without
+ * recomputing anything. A read pulls: upstream settles lazily and only what
+ * actually changed recomputes, gated on equality. A read outside a tracking scope
+ * subscribes to nothing.
  */
 import { G } from './state.js';
-// Node states. CHECK = "a source may have changed — verify on read" (your STALE);
-// DIRTY = "definitely recompute"; CLEAN = "cached value is current".
+import { enterReactiveRun, exitReactiveRun, reportReactiveRun, reportReactiveWrite } from './observe.js';
+// CLEAN, the cached value is current. CHECK, a source may have changed, so verify on
+// read. DIRTY, recompute without checking.
+// CHECK is what keeps a diamond from recomputing twice: a write marks direct observers
+// DIRTY and everything downstream of them CHECK, so a transitive reader asks its
+// sources whether their versions moved before it runs its own function.
 const CLEAN = 0;
 const CHECK = 1;
 const DIRTY = 2;
@@ -25,10 +33,10 @@ const DIRTY = 2;
 // so duplicate module copies share one graph. `consumer`/`untracked` proxy them.
 /** A thing that can be depended upon: holds observers + a monotonic version. */
 class Source {
-    /** Computeds (and watched leaves) that read this node. (was the signalObservers entry) */
+    /** Computeds, and watched leaves, that read this node. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     observers = null;
-    /** Watchers eagerly observing this node, for effect scheduling (L1). */
+    /** Watchers eagerly observing this node, which is how `runtime.ts` schedules effects. */
     watchers = null;
     /** Bumped whenever this node's value actually changes (equality-gated). */
     version = 0;
@@ -62,10 +70,12 @@ export class State extends Source {
             return;
         this._value = next;
         this.version++;
-        // Push: direct observers are DIRTY, their transitive observers are CHECK.
-        // Snapshot first — a synchronous scheduler can re-run an effect mid-propagation,
-        // which re-subscribes (mutates `observers`); iterating the live Set would then
-        // re-visit the re-added node forever. (Matches the legacy Array.from(observers).)
+        // Who wrote it: once a write has propagated, nothing else records what caused it.
+        reportReactiveWrite(this, G.consumer);
+        // Push: direct observers go DIRTY, their transitive observers CHECK.
+        // Snapshot first. The scheduler is synchronous, so an effect can re-run part way
+        // through this loop, and re-running re-subscribes it, which mutates `observers`.
+        // Iterating the live Set would then reach the re-added node again, and again.
         if (this.observers)
             for (const o of [...this.observers])
                 o.markDirty(DIRTY);
@@ -82,7 +92,7 @@ export class Computed extends Source {
     _threw = false;
     _initialized = false;
     state = DIRTY;
-    /** Nodes this computation read on its last run. (was Computation.sources) */
+    /** Nodes this computation read on its last run. Rebuilt on every run. */
     sources = null;
     _fn;
     _equals;
@@ -102,7 +112,7 @@ export class Computed extends Source {
             throw this._error;
         return this._value;
     }
-    /** Settle: if CHECK, verify sources; if DIRTY (or never run), recompute. */
+    /** Settle, if CHECK, verify sources; if DIRTY (or never run), recompute. */
     updateIfNecessary() {
         if (this.state === CHECK) {
             // Pull each source; if one recomputes to a new value it will have flipped
@@ -128,6 +138,7 @@ export class Computed extends Source {
         }
         const prevConsumer = G.consumer;
         const prevUntracked = G.untracked;
+        const watched = enterReactiveRun(this);
         G.consumer = this;
         G.untracked = false;
         let next;
@@ -144,6 +155,8 @@ export class Computed extends Source {
         finally {
             G.consumer = prevConsumer;
             G.untracked = prevUntracked;
+            if (watched)
+                exitReactiveRun();
         }
         const changed = !this._initialized ||
             this._threw !== threw ||
@@ -152,9 +165,10 @@ export class Computed extends Source {
         this._threw = threw;
         this._error = err;
         this._value = next;
+        reportReactiveRun(this);
         if (changed) {
             this.version++;
-            // Our value moved → observers that were merely CHECK must now recompute.
+            // Our value moved -> observers that were merely CHECK must now recompute.
             if (this.observers)
                 for (const o of [...this.observers])
                     o.markDirty(DIRTY);
@@ -163,7 +177,7 @@ export class Computed extends Source {
     }
     /**
      * Push a maybe-dirty mark. A direct observer of a changed node gets DIRTY; its
-     * own observers get CHECK (recurse) — stopping where already marked, so the
+     * own observers get CHECK (recurse), stopping where already marked, so the
      * push is O(newly-dirtied) and never recomputes.
      */
     markDirty(level) {
@@ -192,9 +206,9 @@ function notifyWatchers(node) {
         w._notify(node);
 }
 /**
- * Signal.subtle.Watcher — the only eager observation primitive. Its callback fires
- * when a watched signal MAY have changed; the callback MUST NOT read or write
- * signals. Effects (L1) are built on this + a scheduler.
+ * Signal.subtle.Watcher, the only eager observation primitive. Its callback fires
+ * when a watched signal MAY have changed; the callback must not read or write
+ * signals. Effects are built on this and a scheduler, in `runtime.ts`.
  */
 export class Watcher {
     _notifyFn;
@@ -222,7 +236,7 @@ export class Watcher {
         this._pending.clear();
         return out;
     }
-    /** @internal — a watched node became non-clean. Edge-triggered: notify once. */
+    /** @internal, a watched node became non-clean. Edge-triggered: notify once. */
     _notify(node) {
         if (!this._watched.has(node) || this._pending.has(node))
             return;
@@ -232,7 +246,7 @@ export class Watcher {
             this._notifyFn();
     }
 }
-/** Signal.subtle.untrack — run `fn` without subscribing the current consumer. */
+/** Signal.subtle.untrack: run `fn` without subscribing the current consumer. */
 export function untrack(fn) {
     if (G.untracked)
         return fn();
@@ -244,7 +258,7 @@ export function untrack(fn) {
         G.untracked = false;
     }
 }
-/** Signal.subtle.currentComputed — the computed currently evaluating, or null. */
+/** Signal.subtle.currentComputed, the computed currently evaluating, or null. */
 export function currentComputed() {
     return G.consumer;
 }