@ersbeth/picoflow 2.1.0 → 2.3.0

package/dist/picoflow.js

@@ -1,5 +1,310 @@
 import { createResource, onMount, createEffect, resetErrorBoundaries, onCleanup } from 'solid-js';
 
+class DependenciesRegistry {
+  _dependencies = /* @__PURE__ */ new Set();
+  register(dependency, dependent) {
+    this._dependencies.add(dependency);
+    dependency.registerDependent(dependent);
+  }
+  unregister(dependency, dependent) {
+    this._dependencies.delete(dependency);
+    dependency.unregisterDependent(dependent);
+  }
+  clear(dependent) {
+    this._dependencies.forEach((dependency) => {
+      dependency.unregisterDependent(dependent);
+    });
+    this._dependencies.clear();
+  }
+  forEach(fn) {
+    Array.from(this._dependencies).forEach(fn);
+  }
+}
+
+class DependentsRegistry {
+  _dependents = /* @__PURE__ */ new Set();
+  register(dependent) {
+    this._dependents.add(dependent);
+  }
+  unregister(dependent) {
+    this._dependents.delete(dependent);
+  }
+  notifyAll() {
+    this._dependents.forEach((dependent) => {
+      dependent.notify();
+    });
+  }
+  forEach(fn) {
+    Array.from(this._dependents).forEach(fn);
+  }
+}
+
+class PicoFlowError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PicoFlowError";
+  }
+}
+class PicoFlowDisposedError extends PicoFlowError {
+  constructor(message) {
+    super(message);
+    this.name = "PicoFlowDisposedError";
+  }
+}
+class PicoFlowCycleError extends PicoFlowError {
+  constructor(message) {
+    super(message);
+    this.name = "PicoFlowCycleError";
+  }
+}
+class PicoFlowInternalError extends PicoFlowError {
+  constructor(message) {
+    super(message);
+    this.name = "PicoFlowInternalError";
+  }
+}
+
+class Disposable {
+  _disposed = false;
+  _name;
+  constructor(name) {
+    this._name = name;
+  }
+  get disposed() {
+    return this._disposed;
+  }
+  /** Builds the disposed-primitive error, naming the primitive when a `name` was given at creation. */
+  _disposedError() {
+    return new PicoFlowDisposedError(
+      this._name ? `[PicoFlow] Primitive "${this._name}" is disposed` : "[PicoFlow] Primitive is disposed"
+    );
+  }
+}
+
+class ExecutionStack {
+  static _MAX_FLUSH_STEPS = 1e4;
+  static _pendingQueue = [];
+  static _effectQueue = [];
+  static _executionScheduled;
+  static _coalesceResetScheduled = false;
+  /** Per-effect resets accumulated for the microtask scheduled below, so notifying more than one
+   * effect in the same sync turn doesn't discard every reset after the first (A2-SEM-5). */
+  static _coalesceResets = /* @__PURE__ */ new Set();
+  /** Routes any error escaping the flush loop; defaults to logging rather than crashing (A2-SEM-2, A2-SEC-1). */
+  static _onFlushError = (error) => console.error(error);
+  /**
+   * True once the current synchronous call stack has finished and microtasks have started.
+   * EffectNode uses this to treat microtask notifications (e.g. async resolve) differently
+   * from coalesced sync-batch notifications.
+   */
+  static _pastSyncTurn = false;
+  /** @internal Used by EffectNode to distinguish sync-batch from microtask notifications. */
+  static get pastSyncTurn() {
+    return ExecutionStack._pastSyncTurn;
+  }
+  /**
+   * @internal Runs after the current sync turn ends (queueMicrotask).
+   * Marks pastSyncTurn so the next coalesced effect notify can bump its epoch,
+   * and resets per-effect coalesce flags via onReset.
+   */
+  static scheduleCoalesceReset(onReset) {
+    ExecutionStack._coalesceResets.add(onReset);
+    if (ExecutionStack._coalesceResetScheduled) return;
+    ExecutionStack._coalesceResetScheduled = true;
+    queueMicrotask(() => {
+      ExecutionStack._pastSyncTurn = true;
+      ExecutionStack._coalesceResetScheduled = false;
+      const resets = ExecutionStack._coalesceResets;
+      ExecutionStack._coalesceResets = /* @__PURE__ */ new Set();
+      resets.forEach((reset) => {
+        reset();
+      });
+    });
+  }
+  /** @internal Wired to the public `onFlushError()` API in `src/api/base/flowConfig.ts`. */
+  static setFlushErrorHandler(handler) {
+    ExecutionStack._onFlushError = handler;
+  }
+  static pushPending(node) {
+    ExecutionStack._beginSyncTurn();
+    ExecutionStack._scheduleExecution();
+    ExecutionStack._pendingQueue.push(node);
+  }
+  static pushEffect(effect) {
+    ExecutionStack._beginSyncTurn();
+    ExecutionStack._scheduleExecution();
+    ExecutionStack._effectQueue.push(effect);
+  }
+  static _beginSyncTurn() {
+    ExecutionStack._pastSyncTurn = false;
+  }
+  static _scheduleExecution() {
+    if (ExecutionStack._executionScheduled) return;
+    ExecutionStack._executionScheduled = new Promise((resolve) => {
+      setTimeout(() => {
+        ExecutionStack._executionScheduled = void 0;
+        ExecutionStack._execute();
+        resolve();
+      }, 0);
+    });
+  }
+  static _drain(queue) {
+    for (let i = 0; i < queue.length; i++) {
+      if (i >= ExecutionStack._MAX_FLUSH_STEPS) {
+        ExecutionStack._pendingQueue.length = 0;
+        ExecutionStack._effectQueue.length = 0;
+        ExecutionStack._onFlushError(
+          new PicoFlowCycleError("[PicoFlow] Reactive update cycle exceeded maximum depth")
+        );
+        return;
+      }
+      const node = queue[i];
+      try {
+        node?.execute();
+      } catch (error) {
+        ExecutionStack._onFlushError(error);
+      }
+    }
+    queue.length = 0;
+  }
+  static _execute() {
+    ExecutionStack._drain(ExecutionStack._pendingQueue);
+    ExecutionStack._drain(ExecutionStack._effectQueue);
+  }
+}
+
+class Node extends Disposable {
+  _dependenciesRegistry = new DependenciesRegistry();
+  _dependentsRegistry = new DependentsRegistry();
+  _status = "resolved";
+  get status() {
+    if (this.disposed) throw this._disposedError();
+    return this._status;
+  }
+  set status(status) {
+    if (this.disposed) throw this._disposedError();
+    this._status = status;
+  }
+  registerDependency(dependency) {
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.register(dependency, this);
+  }
+  unregisterDependency(dependency) {
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.unregister(dependency, this);
+  }
+  clearDependencies() {
+    if (this.disposed) throw this._disposedError();
+    this._dependenciesRegistry.clear(this);
+  }
+  registerDependent(dependent) {
+    if (this.disposed) throw this._disposedError();
+    this._dependentsRegistry.register(dependent);
+  }
+  unregisterDependent(dependent) {
+    if (this.disposed) throw this._disposedError();
+    this._dependentsRegistry.unregister(dependent);
+  }
+  markDependencyDisposed() {
+  }
+  notifyDependents() {
+    if (this.disposed) return;
+    this._dependentsRegistry.notifyAll();
+  }
+  watch(tracker) {
+    if (this.disposed) throw this._disposedError();
+    tracker.registerDependency(this);
+  }
+  trigger() {
+    if (this.disposed) throw this._disposedError();
+    this.notifyDependents();
+  }
+  dispose() {
+    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._dependentsRegistry.forEach((dependant) => {
+      dependant.markDependencyDisposed();
+      dependant.unregisterDependency(this);
+      this.unregisterDependent(dependant);
+    });
+    this._dependenciesRegistry.forEach((dependency) => {
+      this.unregisterDependency(dependency);
+    });
+    this._disposed = true;
+  }
+}
+
+class Observable extends Disposable {
+  _dependentsRegistry = new DependentsRegistry();
+  _status = "resolved";
+  get status() {
+    if (this.disposed) throw this._disposedError();
+    return this._status;
+  }
+  set status(status) {
+    if (this.disposed) throw this._disposedError();
+    this._status = status;
+  }
+  registerDependent(dependent) {
+    if (this.disposed) throw this._disposedError();
+    this._dependentsRegistry.register(dependent);
+  }
+  unregisterDependent(dependent) {
+    if (this.disposed) throw this._disposedError();
+    this._dependentsRegistry.unregister(dependent);
+  }
+  notifyDependents() {
+    if (this.disposed) return;
+    this._dependentsRegistry.notifyAll();
+  }
+  watch(tracker) {
+    if (this.disposed) throw this._disposedError();
+    tracker.registerDependency(this);
+  }
+  trigger() {
+    if (this.disposed) throw this._disposedError();
+    this.notifyDependents();
+  }
+  dispose() {
+    if (this._disposed) throw this._disposedError();
+    this._dependentsRegistry.forEach((dependant) => {
+      dependant.markDependencyDisposed();
+      dependant.unregisterDependency(this);
+      this.unregisterDependent(dependant);
+    });
+    this._disposed = true;
+  }
+}
+
+class Observer extends Disposable {
+  _dependenciesRegistry = new DependenciesRegistry();
+  /** Set when a dependency disposed while this observer was queued; consumed by the next execute(). */
+  _dependencyDisposed = false;
+  markDependencyDisposed() {
+    this._dependencyDisposed = true;
+  }
+  registerDependency(dependency) {
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.register(dependency, this);
+  }
+  unregisterDependency(dependency) {
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.unregister(dependency, this);
+  }
+  clearDependencies() {
+    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    this._dependenciesRegistry.clear(this);
+  }
+  dispose() {
+    if (this._disposed) throw this._disposedError();
+    this._dependenciesRegistry.clear(this);
+    this._disposed = true;
+  }
+}
+
+function onFlushError(handler) {
+  ExecutionStack.setFlushErrorHandler(handler);
+}
+
 function isDisposable(obj) {
   return obj !== null && obj !== void 0 && typeof obj.dispose === "function";
 }
@@ -84,14 +389,14 @@ class AsyncScheduler {
     this._attachHandlers(this._resolver);
   }
   get settled() {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     return this._settled.promise;
   }
   get disposed() {
     return this._disposed;
   }
   overwrite(promise) {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     if (this._resolver.finished) {
       this._resolver = new AsyncResolver(this._compute);
       this._settled = Promise.withResolvers();
@@ -100,7 +405,7 @@ class AsyncScheduler {
     this._resolver.overwrite(promise);
   }
   compute() {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     if (this._resolver.finished) {
       this._resolver = new AsyncResolver(this._compute);
       this._settled = Promise.withResolvers();
@@ -192,7 +497,7 @@ class SyncScheduler {
     return this._settled.promise;
   }
   overwrite(value) {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     if (this._resolver.finished) {
       this._settled = Promise.withResolvers();
       this._resolver = new SyncResolver(this._compute, this._onResolve, this._onReject);
@@ -200,7 +505,7 @@ class SyncScheduler {
     this._resolver.overwrite(value);
   }
   compute() {
-    if (this._disposed) throw new Error("[PicoFlow] ComputationScheduler is disposed");
+    if (this._disposed) throw new PicoFlowDisposedError("[PicoFlow] ComputationScheduler is disposed");
     if (this._resolver.finished) {
       this._settled = Promise.withResolvers();
       this._resolver = new SyncResolver(this._compute, this._onResolve, this._onReject);
@@ -213,229 +518,6 @@ class SyncScheduler {
   }
 }
 
-class Disposable {
-  _disposed = false;
-  get disposed() {
-    return this._disposed;
-  }
-  dispose() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._disposed = true;
-  }
-}
-
-class ExecutionStack {
-  static _MAX_FLUSH_STEPS = 1e4;
-  static _pendingQueue = [];
-  static _effectQueue = [];
-  static _executionScheduled;
-  static _coalesceResetScheduled = false;
-  /**
-   * True once the current synchronous call stack has finished and microtasks have started.
-   * EffectNode uses this to treat microtask notifications (e.g. async resolve) differently
-   * from coalesced sync-batch notifications.
-   */
-  static _pastSyncTurn = false;
-  /** @internal Used by EffectNode to distinguish sync-batch from microtask notifications. */
-  static get pastSyncTurn() {
-    return ExecutionStack._pastSyncTurn;
-  }
-  /**
-   * @internal Runs after the current sync turn ends (queueMicrotask).
-   * Marks pastSyncTurn so the next coalesced effect notify can bump its epoch,
-   * and resets per-effect coalesce flags via onReset.
-   */
-  static scheduleCoalesceReset(onReset) {
-    if (ExecutionStack._coalesceResetScheduled) return;
-    ExecutionStack._coalesceResetScheduled = true;
-    queueMicrotask(() => {
-      ExecutionStack._pastSyncTurn = true;
-      ExecutionStack._coalesceResetScheduled = false;
-      onReset();
-    });
-  }
-  static pushPending(node) {
-    ExecutionStack._beginSyncTurn();
-    ExecutionStack._scheduleExecution();
-    ExecutionStack._pendingQueue.push(node);
-  }
-  static pushEffect(effect) {
-    ExecutionStack._beginSyncTurn();
-    ExecutionStack._scheduleExecution();
-    ExecutionStack._effectQueue.push(effect);
-  }
-  static _beginSyncTurn() {
-    ExecutionStack._pastSyncTurn = false;
-  }
-  static _scheduleExecution() {
-    if (ExecutionStack._executionScheduled) return;
-    ExecutionStack._executionScheduled = new Promise((resolve) => {
-      setTimeout(() => {
-        ExecutionStack._executionScheduled = void 0;
-        ExecutionStack._execute();
-        resolve();
-      }, 0);
-    });
-  }
-  static _drain(queue) {
-    for (let i = 0; i < queue.length; i++) {
-      if (i >= ExecutionStack._MAX_FLUSH_STEPS) {
-        ExecutionStack._pendingQueue.length = 0;
-        ExecutionStack._effectQueue.length = 0;
-        throw new Error("[PicoFlow] Reactive update cycle exceeded maximum depth");
-      }
-      const node = queue[i];
-      node?.execute();
-    }
-    queue.length = 0;
-  }
-  static _execute() {
-    ExecutionStack._drain(ExecutionStack._pendingQueue);
-    ExecutionStack._drain(ExecutionStack._effectQueue);
-  }
-}
-
-class Node extends Disposable {
-  _dependencies = /* @__PURE__ */ new Set();
-  _dependents = /* @__PURE__ */ new Set();
-  _status = "resolved";
-  get status() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    return this._status;
-  }
-  set status(status) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._status = status;
-  }
-  registerDependency(dependency) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.add(dependency);
-    dependency.registerDependent(this);
-  }
-  unregisterDependency(dependency) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.delete(dependency);
-    dependency.unregisterDependent(this);
-  }
-  clearDependencies() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.forEach((dependency) => {
-      dependency.unregisterDependent(this);
-    });
-    this._dependencies.clear();
-  }
-  registerDependent(dependent) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependents.add(dependent);
-  }
-  unregisterDependent(dependent) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependents.delete(dependent);
-  }
-  notifyDependents() {
-    if (this.disposed) return;
-    this._dependents.forEach((dependent) => {
-      dependent.notify();
-    });
-  }
-  watch(tracker) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    tracker.registerDependency(this);
-  }
-  trigger() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this.notifyDependents();
-  }
-  notify() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    if (this.status === "dirty") return;
-    this.status = "dirty";
-    this.notifyDependents();
-  }
-  dispose() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    Array.from(this._dependents).forEach((dependant) => {
-      dependant.unregisterDependency(this);
-      this.unregisterDependent(dependant);
-    });
-    Array.from(this._dependencies).forEach((dependency) => {
-      this.unregisterDependency(dependency);
-    });
-    this._disposed = true;
-  }
-}
-
-class Observable extends Disposable {
-  _dependents = /* @__PURE__ */ new Set();
-  _status = "resolved";
-  get status() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    return this._status;
-  }
-  set status(status) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._status = status;
-  }
-  registerDependent(dependent) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependents.add(dependent);
-  }
-  unregisterDependent(dependent) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependents.delete(dependent);
-  }
-  notifyDependents() {
-    if (this.disposed) return;
-    this._dependents.forEach((dependent) => {
-      dependent.notify();
-    });
-  }
-  watch(tracker) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    tracker.registerDependency(this);
-  }
-  trigger() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this.notifyDependents();
-  }
-  dispose() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    Array.from(this._dependents).forEach((dependant) => {
-      dependant.unregisterDependency(this);
-      this.unregisterDependent(dependant);
-    });
-    this._disposed = true;
-  }
-}
-
-class Observer extends Disposable {
-  _dependencies = /* @__PURE__ */ new Set();
-  registerDependency(dependency) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.add(dependency);
-    dependency.registerDependent(this);
-  }
-  unregisterDependency(dependency) {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.delete(dependency);
-    dependency.unregisterDependent(this);
-  }
-  clearDependencies() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    this._dependencies.forEach((dependency) => {
-      dependency.unregisterDependent(this);
-    });
-    this._dependencies.clear();
-  }
-  dispose() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    Array.from(this._dependencies).forEach((dependency) => {
-      this.unregisterDependency(dependency);
-    });
-    this._disposed = true;
-  }
-}
-
 class EffectNode extends Observer {
   _data;
   _onData;
@@ -449,6 +531,8 @@ class EffectNode extends Observer {
   _notifyEpoch = 0;
   /** How many notification epochs have been executed so far. */
   _executedEpoch = 0;
+  /** Callbacks registered via {@link onDispose}, run once after dispose() tears down the graph edges. */
+  _disposeListeners = [];
   constructor(data, onData, onError, onPending) {
     super();
     this._data = data;
@@ -458,8 +542,23 @@ class EffectNode extends Observer {
     this._notifyEpoch = 1;
     this.execute();
   }
+  /**
+   * Registers a callback to run once this effect is disposed, after the graph edges are torn
+   * down. Lets a caller that wraps an effect (e.g. {@link ActionNode.subscribe}) attach its own
+   * teardown without patching `dispose` on the returned instance (A2-ARCH-8).
+   * @internal
+   */
+  onDispose(fn) {
+    this._disposeListeners.push(fn);
+  }
+  dispose() {
+    super.dispose();
+    this._disposeListeners.forEach((fn) => {
+      fn();
+    });
+  }
   notify() {
-    if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this._disposed) throw this._disposedError();
     if (this._queued) {
       if (!this._coalescedWhileQueued) {
         this._coalescedWhileQueued = true;
@@ -482,6 +581,11 @@ class EffectNode extends Observer {
       this._executedEpoch = this._notifyEpoch;
       return;
     }
+    if (this._dependencyDisposed) {
+      this._dependencyDisposed = false;
+      this._executedEpoch = this._notifyEpoch;
+      return;
+    }
     const targetEpoch = this._notifyEpoch;
     while (this._executedEpoch < targetEpoch) {
       this._executedEpoch++;
@@ -489,6 +593,11 @@ class EffectNode extends Observer {
         this._executedEpoch = this._notifyEpoch;
         return;
       }
+      if (this._dependencyDisposed) {
+        this._dependencyDisposed = false;
+        this._executedEpoch = this._notifyEpoch;
+        return;
+      }
       try {
         this.clearDependencies();
         const data = this._data(this);
@@ -508,11 +617,27 @@ class EffectNode extends Observer {
   }
 }
 
+const PICOFLOW_VALUE_NODE = /* @__PURE__ */ Symbol.for("picoflow.node");
 class ValueNode extends Node {
+  [PICOFLOW_VALUE_NODE] = true;
   _value;
   _error;
+  /** Builds the "unreachable state" error, naming the primitive when a `name` was given at creation. */
+  _internalError() {
+    return new PicoFlowInternalError(
+      this._name ? `[PicoFlow] Internal error (${this._name})` : "[PicoFlow] Internal error"
+    );
+  }
+  /**
+   * Hook called just before a tracked read throws `PendingError`, i.e. a dependent registered while
+   * this node is mid-flight and has no other way to learn the computation later settled (A2-PERF-4).
+   * No-op by default; overridden by {@link ValueAsyncNode} to know when its own post-resolve
+   * `notifyDependents()` call cannot be skipped even if the resolved value is unchanged.
+   */
+  _markPendingRead() {
+  }
   watch(tracker) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     super.watch(tracker);
     switch (this.status) {
       case "resolved":
@@ -520,26 +645,28 @@ class ValueNode extends Node {
       case "error":
         throw this._error;
       case "pending": {
+        this._markPendingRead();
         throw new PendingError(this._scheduler.settled);
       }
       case "dirty": {
         this.execute();
         switch (this.status) {
           case "pending":
+            this._markPendingRead();
             throw new PendingError(this._scheduler.settled);
           case "resolved":
             return;
           case "error":
             throw this._error;
           case "dirty": {
-            throw new Error("[PicoFlow] Internal error");
+            throw this._internalError();
           }
         }
       }
     }
   }
   notify() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (this.status === "dirty") return;
     if (this.status === "pending") {
       ExecutionStack.pushPending(this);
@@ -552,7 +679,7 @@ class ValueNode extends Node {
     this._scheduler.dispose();
   }
   get(tracker) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     super.watch(tracker);
     switch (this.status) {
       case "resolved":
@@ -560,6 +687,7 @@ class ValueNode extends Node {
       case "error":
         throw this._error;
       case "pending": {
+        this._markPendingRead();
         throw new PendingError(this._scheduler.settled);
       }
       case "dirty": {
@@ -570,17 +698,18 @@ class ValueNode extends Node {
           case "error":
             throw this._error;
           case "pending": {
+            this._markPendingRead();
             throw new PendingError(this._scheduler.settled);
           }
           case "dirty": {
-            throw new Error("[PicoFlow] Internal error");
+            throw this._internalError();
           }
         }
       }
     }
   }
   async pick() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     switch (this.status) {
       case "resolved":
         return this._value;
@@ -588,7 +717,7 @@ class ValueNode extends Node {
         await this._scheduler.settled;
         if (this.status === "resolved") return this._value;
         if (this.status === "error") throw this._error;
-        throw new Error("[PicoFlow] Internal error");
+        throw this._internalError();
       }
       case "error":
         throw this._error;
@@ -601,12 +730,12 @@ class ValueNode extends Node {
             await this._scheduler.settled;
             if (this.status === "resolved") return this._value;
             if (this.status === "error") throw this._error;
-            throw new Error("[PicoFlow] Internal error");
+            throw this._internalError();
           }
           case "error":
             throw this._error;
           case "dirty": {
-            throw new Error("[PicoFlow] Internal error");
+            throw this._internalError();
           }
         }
       }
@@ -619,7 +748,7 @@ class ValueNode extends Node {
     this._scheduler.compute();
   }
   subscribe(onValue, onError, onPending) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const effect = new EffectNode((t) => this.get(t), onValue, onError, onPending);
     return effect;
   }
@@ -628,8 +757,17 @@ class ValueNode extends Node {
 class ValueAsyncNode extends ValueNode {
   _scheduler;
   _compute;
-  constructor(promiseOrCompute) {
-    super();
+  /** Set by {@link ValueNode._markPendingRead} when a dependent registers while this node is mid-flight. */
+  _hasPendingReader = false;
+  /**
+   * True only while the in-flight computation was started by `set()`, which already ran its own
+   * eager `notifyDependents()` cascade before this resolution. `refresh()` and a recompute pulled
+   * lazily after an upstream `notify()` have no such pre-cascade — for them, `_onResolve`'s own
+   * `notifyDependents()` call is the only notification, so it must never be skipped (A2-PERF-4).
+   */
+  _pendingFromSet = false;
+  constructor(promiseOrCompute, name) {
+    super(name);
     if (typeof promiseOrCompute === "function") {
       this._compute = () => promiseOrCompute(this, this._value);
     } else {
@@ -644,10 +782,18 @@ class ValueAsyncNode extends ValueNode {
   }
   _onResolve(value) {
     if (this.disposed) return;
+    const changed = value !== this._value;
+    const hadPendingReader = this._hasPendingReader;
+    const pendingFromSet = this._pendingFromSet;
+    this._hasPendingReader = false;
+    this._pendingFromSet = false;
     this.status = "resolved";
     this._value = value;
     this._error = void 0;
-    this.notifyDependents();
+    if (changed || hadPendingReader || !pendingFromSet) this.notifyDependents();
+  }
+  _markPendingRead() {
+    this._hasPendingReader = true;
   }
   _onReject(error) {
     if (this.disposed) return;
@@ -656,12 +802,13 @@ class ValueAsyncNode extends ValueNode {
     this.notifyDependents();
   }
   set(promiseOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (typeof promiseOrUpdater === "function") {
       const updater = promiseOrUpdater;
       switch (this.status) {
         case "resolved": {
           this.status = "pending";
+          this._pendingFromSet = true;
           this._scheduler.overwrite(updater(this._value));
           this.notifyDependents();
           return;
@@ -670,6 +817,7 @@ class ValueAsyncNode extends ValueNode {
         case "error":
         case "dirty": {
           this.status = "pending";
+          this._pendingFromSet = true;
           this._scheduler.overwrite(updater(this._value));
           this.notifyDependents();
           return;
@@ -677,38 +825,39 @@ class ValueAsyncNode extends ValueNode {
       }
     } else {
       this.status = "pending";
+      this._pendingFromSet = true;
       const promise = promiseOrUpdater;
       this._scheduler.overwrite(promise);
       this.notifyDependents();
     }
   }
   refresh() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this.execute();
   }
 }
 
-function constantAsync(valueOrInitializer) {
-  return new ValueAsyncNode(valueOrInitializer);
+function constantAsync(valueOrInitializer, options) {
+  return new ValueAsyncNode(valueOrInitializer, options?.name);
 }
 
-function derivationAsync(compute) {
-  return new ValueAsyncNode(compute);
+function derivationAsync(compute, options) {
+  return new ValueAsyncNode(compute, options?.name);
 }
 
-function stateAsync(valueOrInitializer) {
-  return new ValueAsyncNode(valueOrInitializer);
+function stateAsync(valueOrInitializer, options) {
+  return new ValueAsyncNode(valueOrInitializer, options?.name);
 }
 
-function writableDerivationAsync(compute) {
-  return new ValueAsyncNode(compute);
+function writableDerivationAsync(compute, options) {
+  return new ValueAsyncNode(compute, options?.name);
 }
 
 class ValueSyncNode extends ValueNode {
   _scheduler;
   _compute;
-  constructor(valueOrCompute) {
-    super();
+  constructor(valueOrCompute, name) {
+    super(name);
     if (typeof valueOrCompute === "function") {
       this._compute = () => valueOrCompute(this, this._value);
     } else {
@@ -734,7 +883,7 @@ class ValueSyncNode extends ValueNode {
     this._error = error;
   }
   set(valueOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (typeof valueOrUpdater === "function") {
       const updater = valueOrUpdater;
       switch (this.status) {
@@ -778,7 +927,7 @@ class ValueSyncNode extends ValueNode {
     }
   }
   refresh() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const currentValue = this._value;
     const currentStatus = this.status;
     this.execute();
@@ -807,7 +956,7 @@ class ActionNode extends ValueSyncNode {
     }
   }
   set(valueOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (typeof valueOrUpdater === "function") {
       const updater = valueOrUpdater;
       const nextValue2 = updater(this._value);
@@ -822,7 +971,7 @@ class ActionNode extends ValueSyncNode {
     super.set(nextValue);
   }
   subscribe(onValue, onError, onPending) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const slot = { queue: [] };
     this._slots.add(slot);
     const effect = new EffectNode(
@@ -841,11 +990,9 @@ class ActionNode extends ValueSyncNode {
       onError,
       onPending
     );
-    const originalDispose = effect.dispose.bind(effect);
-    effect.dispose = () => {
+    effect.onDispose(() => {
       this._slots.delete(slot);
-      originalDispose();
-    };
+    });
     return effect;
   }
   dispose() {
@@ -856,8 +1003,8 @@ class ActionNode extends ValueSyncNode {
 
 class ArrayNode extends ValueSyncNode {
   $lastAction;
-  constructor(value = []) {
-    super(value);
+  constructor(value = [], name) {
+    super(value, name);
     this.$lastAction = new ActionNode({
       type: "set",
       setItems: value,
@@ -873,11 +1020,11 @@ class ArrayNode extends ValueSyncNode {
     return [...values];
   }
   get length() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     return this._value.length;
   }
   set(itemsOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const previousValue = this._value;
     super.set(itemsOrUpdater);
     this.$lastAction.set({
@@ -888,8 +1035,8 @@ class ArrayNode extends ValueSyncNode {
     return previousValue;
   }
   update(index, item) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
-    if (index < 0 || index >= this._value.length) {
+    if (this.disposed) throw this._disposedError();
+    if (index < 0 || index >= this._value.length || !Number.isInteger(index)) {
       throw new Error("[PicoFlow] Index out of bounds");
     }
     const previousValue = this._value[index];
@@ -904,13 +1051,13 @@ class ArrayNode extends ValueSyncNode {
     return previousValue;
   }
   push(item) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this._value.push(item);
     this.notifyDependents();
     this.$lastAction.set({ type: "push", addedItem: item });
   }
   pop() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (this._value.length === 0) return void 0;
     const item = this._value.pop();
     this.notifyDependents();
@@ -918,13 +1065,13 @@ class ArrayNode extends ValueSyncNode {
     return item;
   }
   unshift(item) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     this._value.unshift(item);
     this.notifyDependents();
     this.$lastAction.set({ type: "unshift", addedItem: item });
   }
   shift() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (this._value.length === 0) return void 0;
     const item = this._value.shift();
     this.notifyDependents();
@@ -932,7 +1079,7 @@ class ArrayNode extends ValueSyncNode {
     return item;
   }
   splice(start, deleteCount, ...newItems) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const items = this._value.splice(start, deleteCount, ...newItems);
     this.notifyDependents();
     this.$lastAction.set({
@@ -945,7 +1092,7 @@ class ArrayNode extends ValueSyncNode {
     return items;
   }
   clear() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const previousValue = [...this._value];
     this._value = [];
     this.notifyDependents();
@@ -961,14 +1108,14 @@ class ArrayNode extends ValueSyncNode {
   }
 }
 
-function array(initial) {
-  return new ArrayNode(initial);
+function array(initial, options) {
+  return new ArrayNode(initial, options?.name);
 }
 
 class MapNode extends ValueSyncNode {
   $lastAction;
-  constructor(value = /* @__PURE__ */ new Map()) {
-    super(value);
+  constructor(value = /* @__PURE__ */ new Map(), name) {
+    super(value, name);
     this.$lastAction = new ActionNode({
       type: "set",
       setMap: value,
@@ -976,7 +1123,7 @@ class MapNode extends ValueSyncNode {
     });
   }
   add(key, value) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (this._value.has(key)) {
       throw new Error("[PicoFlow] Key already exists");
     }
@@ -985,7 +1132,7 @@ class MapNode extends ValueSyncNode {
     this.$lastAction.set({ type: "add", key, addedValue: value });
   }
   update(key, value) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (!this._value.has(key)) throw new Error("[PicoFlow] Key does not exist");
     const previousValue = this._value.get(key);
     this._value.set(key, value);
@@ -999,7 +1146,7 @@ class MapNode extends ValueSyncNode {
     return previousValue;
   }
   delete(key) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     if (!this._value.has(key)) throw new Error("[PicoFlow] Key does not exist");
     const value = this._value.get(key);
     this._value.delete(key);
@@ -1008,7 +1155,7 @@ class MapNode extends ValueSyncNode {
     return value;
   }
   set(mapOrUpdater) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const previousValue = this._value;
     super.set(mapOrUpdater);
     this.$lastAction.set({
@@ -1019,7 +1166,7 @@ class MapNode extends ValueSyncNode {
     return previousValue;
   }
   clear() {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const previousValue = this._value;
     this._value = /* @__PURE__ */ new Map();
     this.notifyDependents();
@@ -1035,11 +1182,11 @@ class MapNode extends ValueSyncNode {
   }
 }
 
-function map(initial) {
+function map(initial, options) {
   if (initial instanceof Map) {
-    return new MapNode(initial);
+    return new MapNode(initial, options?.name);
   }
-  return new MapNode(new Map(initial ? Object.entries(initial) : []));
+  return new MapNode(new Map(initial ? Object.entries(initial) : []), options?.name);
 }
 
 function subscribe(data, onData, onError, onPending) {
@@ -1048,30 +1195,30 @@ function subscribe(data, onData, onError, onPending) {
 
 class SignalNode extends Observable {
   subscribe(onTrigger, onError, onPending) {
-    if (this.disposed) throw new Error("[PicoFlow] Primitive is disposed");
+    if (this.disposed) throw this._disposedError();
     const effect = new EffectNode((t) => this.watch(t), onTrigger, onError, onPending);
     return effect;
   }
 }
 
-function signal() {
-  return new SignalNode();
+function signal(options) {
+  return new SignalNode(options?.name);
 }
 
-function constant(initializer) {
-  return new ValueSyncNode(initializer);
+function constant(initializer, options) {
+  return new ValueSyncNode(initializer, options?.name);
 }
 
-function derivation(compute) {
-  return new ValueSyncNode(compute);
+function derivation(compute, options) {
+  return new ValueSyncNode(compute, options?.name);
 }
 
-function state(valueOrInitializer) {
-  return new ValueSyncNode(valueOrInitializer);
+function state(valueOrInitializer, options) {
+  return new ValueSyncNode(valueOrInitializer, options?.name);
 }
 
-function writableDerivation(compute) {
-  return new ValueSyncNode(compute);
+function writableDerivation(compute, options) {
+  return new ValueSyncNode(compute, options?.name);
 }
 
 function describeFlowInput(value) {
@@ -1082,6 +1229,9 @@ function describeFlowInput(value) {
   }
   return typeof value;
 }
+function isValueNode(flow) {
+  return typeof flow === "object" && flow !== null && PICOFLOW_VALUE_NODE in flow;
+}
 function fromNode(node, options) {
   const [resource, { refetch }] = createResource(() => node.pick());
   let fx;
@@ -1122,7 +1272,7 @@ function fromGetter(getter) {
   return fromNode(derivation, { disposeNode: true });
 }
 function from(flow) {
-  if (flow instanceof ValueAsyncNode || flow instanceof ValueSyncNode) {
+  if (isValueNode(flow)) {
     return fromNode(flow);
   }
   if (typeof flow === "function") {
@@ -1131,4 +1281,4 @@ function from(flow) {
   throw new Error(`[PicoFlow] from(): expected a FlowValue or getter function, received ${describeFlowInput(flow)}`);
 }
 
-export { array, constant, constantAsync, derivation, derivationAsync, from, isDisposable, map, signal, state, stateAsync, subscribe, writableDerivation, writableDerivationAsync };
+export { PicoFlowCycleError, PicoFlowDisposedError, PicoFlowError, PicoFlowInternalError, array, constant, constantAsync, derivation, derivationAsync, from, isDisposable, map, onFlushError, signal, state, stateAsync, subscribe, writableDerivation, writableDerivationAsync };