@graphrefly/ts 0.0.0 → 0.0.1

package/dist/sources/browser.cjs

@@ -33,6 +33,7 @@ __export(browser_exports, {
   fromIter: () => fromIter,
   fromPromise: () => fromPromise,
   fromPushNotification: () => fromPushNotification,
+  fromRaf: () => fromRaf,
   fromSSE: () => fromSSE,
   fromSSEWithOptions: () => fromSSEWithOptions,
   fromTimer: () => fromTimer,
@@ -70,6 +71,7 @@ var TIER = {
   START: TIER_START,
   PAUSE: TIER_CONTROL,
   RESUME: TIER_CONTROL,
+  PULL: TIER_CONTROL,
   DIRTY: TIER_NOTIFICATION,
   DATA: TIER_VALUE,
   RESOLVED: TIER_VALUE,
@@ -912,6 +914,17 @@ function notifyTopologyDepsChanged(node, prevDeps, deps) {
 function terminalView(t) {
   return t === void 0 ? false : t;
 }
+function normalizePullDemand(demand) {
+  if (typeof demand !== "object" || demand === null || Array.isArray(demand)) {
+    throw new Error("ctx.up: PULL requires { pullId, params? } demand payload (D269)");
+  }
+  const pullId = demand.pullId;
+  if (typeof pullId !== "string" && typeof pullId !== "symbol") {
+    throw new Error("ctx.up: PULL demand requires a string or symbol pullId (D269)");
+  }
+  const params = demand.params;
+  return params === void 0 ? { pullId } : { pullId, params };
+}
 function validateDownPayloads(msgs) {
   for (const m of msgs) {
     if (m[0] === "DATA" && m[1] === void 0) {
@@ -955,7 +968,7 @@ var Node = class {
     const pull = opts.pullId !== void 0;
     if (pull && pausable === false)
       throw new Error(
-        "node: pullId is incompatible with pausable:false \u2014 a pull node is demanded via RESUME, which pausable:false ignores (R-pull / R-pause-modes / D55,D59)"
+        "node: pullId is incompatible with pausable:false \u2014 a pull node uses the pausable delivery-content axis (R-pull / R-pause-modes / D55,D269)"
       );
     let handle;
     if (handleOrFn === null) handle = null;
@@ -978,7 +991,6 @@ var Node = class {
       value.status = "settled";
     }
     const pauseLockset = /* @__PURE__ */ new Set();
-    if (pull) pauseLockset.add(pullLock);
     this._core = core ?? new NodeCore();
     const created = this._core.createSlot(
       {
@@ -1019,7 +1031,9 @@ var Node = class {
           pauseLockset,
           pausedDepWaveOccurred: false,
           pauseBuffer: [],
-          demandOwed: false,
+          demandOwed: void 0,
+          activePull: void 0,
+          pullDirtyOwed: false,
           inDeliverDemand: false
         },
         privateState: { value: SENTINEL, persist: false },
@@ -1076,10 +1090,11 @@ var Node = class {
       this._wave.batchDirtyOwed = false;
       this._control.pauseBuffer = [];
       this._control.pausedDepWaveOccurred = false;
-      this._control.demandOwed = false;
+      this._control.demandOwed = void 0;
+      this._control.activePull = void 0;
+      this._control.pullDirtyOwed = false;
       this._control.inDeliverDemand = false;
       this._control.pauseLockset.clear();
-      if (this._slot.pull) this._control.pauseLockset.add(this._slot.pullLock);
       this._privateState.value = state.ctxState.value;
       this._privateState.persist = state.ctxState.persist;
       if (state.version === false) {
@@ -1118,17 +1133,16 @@ var Node = class {
     subscriberCountReaders.set(this, () => this._subscriberCount());
     activationReaders.set(this, () => this._lifecycle.activated);
   }
-  /** R-pull (D55): true while a pull node is quiet (holds its own pullId/demand lock). */
+  /** R-pull (D55/D272): true while a pull node is not serving a PULL demand pulse. */
   _isPullQuiet() {
-    return this._slot.pull && this._control.pauseLockset.has(this._slot.pullLock);
+    return this._slot.pull && this._control.activePull === void 0;
   }
   /**
-   * R-pull (D55/D59): this pull node's pullId (pure data, like {@link cache}/{@link handle} — never
-   * triggers computation). A consumer demands one delivery by cone-routing a RESUME of it (no node
-   * reference): `ctx.up([["RESUME", pullId]])` (immediate; loops back → D37 for a self-read dep) or
-   * `ctx.upNext([["RESUME", pullId]])` (boundary-deferred self-demand, R-up-routing/R-rewire-deferred).
-   * Undefined for a non-pull node. The author writes the pullId verbatim, so this getter is mainly
-   * for inspection/describe; routing matches by the pullId value carried in the RESUME, by identity.
+   * R-pull (D269/D272): this pull node's pullId (pure data, like {@link cache}/{@link handle} —
+   * never triggers computation). A consumer demands one delivery by cone-routing PULL of it (no
+   * node reference): `ctx.up([["PULL", { pullId }]])` (immediate; loops back → D37 for a self-read
+   * dep) or `ctx.upNext([["PULL", { pullId }]])` (boundary-deferred self-demand). Undefined for a
+   * non-pull node. The author writes the pullId verbatim; routing matches by identity.
    */
   get pullId() {
     return this._slot.pullLock;
@@ -1235,10 +1249,10 @@ var Node = class {
     });
   }
   /**
-   * Enqueue a deferred up-going control wave (R-up-routing / R-pull / D59): at the committed wave
+   * Enqueue a deferred up-going control/demand wave (R-up-routing / R-pull / D269): at the committed wave
    * boundary, route `msgs` up from THIS node (broadcast, or up the single `towardDep` edge). The
-   * deferred form of `ctx.up` — the SELF-demand path: a consumer issues `ctx.upNext([[RESUME,
-   * pullId]])` to demand a dep it ALSO reads; the demand applies at the boundary (not mid-fn), so
+   * deferred form of `ctx.up` — the SELF-demand path: a consumer issues `ctx.upNext([[PULL,
+   * { pullId }]])` to demand a dep it ALSO reads; the demand applies at the boundary (not mid-fn), so
    * the pull node's delivery loops back as a FRESH wave rather than re-entering the consumer (D37 /
    * R-reentrancy). Rides the same R-rewire-deferred (D47) drain as ctx.rewireNext.
    */
@@ -1453,7 +1467,6 @@ var Node = class {
     this._lifecycle.activated = true;
     const seedRestoredDeps = this._restoredActivationPending;
     this._restoredActivationPending = false;
-    if (this._slot.pull) this._control.pauseLockset.add(this._slot.pullLock);
     this._dep.unsubs = new Array(this._slot.deps.length);
     this._dep.idxBoxes = new Array(this._slot.deps.length);
     for (const dep of this._slot.deps)
@@ -1525,7 +1538,9 @@ var Node = class {
     this._control.pauseLockset.clear();
     this._control.pauseBuffer = [];
     this._control.pausedDepWaveOccurred = false;
-    this._control.demandOwed = false;
+    this._control.demandOwed = void 0;
+    this._control.activePull = void 0;
+    this._control.pullDirtyOwed = false;
     this._value.replayRing = [];
     if (!this._privateState.persist) this._privateState.value = SENTINEL;
   }
@@ -1537,8 +1552,7 @@ var Node = class {
     return this._lifecycle.subscribers.size;
   }
   _isRuntimeQuiescentForRelease() {
-    const allowedPullQuietLock = this._slot.pull && this._control.pauseLockset.size === 1 && this._control.pauseLockset.has(this._slot.pullLock);
-    return !this._released && this._value.status !== "dirty" && this._value.status !== "pending" && this._wave.pending === 0 && !this._wave.insideRunWave && !this._wave.inDepMutation && !this._wave.rewireRunPending && !this._wave.batchDirtyOwed && this._dep.dirty.every((dirty) => !dirty) && this._control.pauseBuffer.length === 0 && !this._control.pausedDepWaveOccurred && !this._control.demandOwed && !this._control.inDeliverDemand && (this._control.pauseLockset.size === 0 || allowedPullQuietLock);
+    return !this._released && this._value.status !== "dirty" && this._value.status !== "pending" && this._wave.pending === 0 && !this._wave.insideRunWave && !this._wave.inDepMutation && !this._wave.rewireRunPending && !this._wave.batchDirtyOwed && this._dep.dirty.every((dirty) => !dirty) && this._control.pauseBuffer.length === 0 && !this._control.pausedDepWaveOccurred && this._control.demandOwed === void 0 && this._control.activePull === void 0 && !this._control.inDeliverDemand && this._control.pauseLockset.size === 0;
   }
   _releaseRuntime() {
     if (this._released) return;
@@ -1594,7 +1608,9 @@ var Node = class {
     this._control.pauseLockset.clear();
     this._control.pauseBuffer = [];
     this._control.pausedDepWaveOccurred = false;
-    this._control.demandOwed = false;
+    this._control.demandOwed = void 0;
+    this._control.activePull = void 0;
+    this._control.pullDirtyOwed = false;
     this._restoredActivationPending = false;
     checkpointReaders.delete(this);
     restoreWriters.delete(this);
@@ -1776,7 +1792,7 @@ var Node = class {
       this._wave.rewireRunPending = true;
       return;
     }
-    if (this._slot.pausable === true && this._isPaused()) {
+    if (this._slot.pausable === true && (this._isPaused() || this._isPullQuiet())) {
       this._control.pausedDepWaveOccurred = true;
       return;
     }
@@ -1916,10 +1932,11 @@ var Node = class {
         unsubscribeDep: (dep, fn) => this._requestRewireNext({ kind: "remove", dep, fn }),
         replaceDeps: (deps, fn) => this._requestRewireNext({ kind: "set", deps, fn })
       },
-      // R-up-routing / R-pull (D59): deferred up — route a control wave (e.g. a RESUME pull
-      // DEMAND) up the declared cone at the committed boundary. The SELF-demand path: an
+      // R-up-routing / R-pull (D269): deferred up — route a control/demand wave (e.g. PULL)
+      // up the declared cone at the committed boundary. The SELF-demand path: an
       // immediate ctx.up whose delivery loops back re-enters this fn (D37 / R-reentrancy).
       upNext: (msgs, towardDep) => this._requestUpNext(msgs, towardDep),
+      ...this._control.activePull === void 0 ? {} : { pull: this._control.activePull },
       [CTX_DEP_CACHE]: { latest: snapshot?.latest ?? this._dep.prev },
       [CTX_NODE_BINDING]: {
         dispatcher: this._slot.dispatcher,
@@ -1934,6 +1951,11 @@ var Node = class {
   _refreshCtx(ctx) {
     ctx.waveData = this._dep.waveData;
     ctx.terminal = this._dep.terminalInput.map(terminalView);
+    if (this._control.activePull === void 0) {
+      delete ctx.pull;
+    } else {
+      ctx.pull = this._control.activePull;
+    }
     ctx[CTX_DEP_CACHE] = { latest: this._dep.prev };
   }
   _makeState() {
@@ -2026,7 +2048,7 @@ var Node = class {
         plannedVersions[i] = plannedVersion;
       }
     }
-    if (hasTier3 && !this._wave.insideRunWave && !this._wave.emittedDirtyThisWave) {
+    if (hasTier3 && (!this._wave.insideRunWave || this._control.pullDirtyOwed) && !this._wave.emittedDirtyThisWave) {
       this._wave.emittedDirtyThisWave = true;
       this._value.status = "dirty";
       this._emitToSubs(["DIRTY"], { wave: deliveryWave, last: false });
@@ -2106,13 +2128,18 @@ var Node = class {
       if (m[0] === "PAUSE") {
         this._pauseAcquire(m[1]);
       } else if (m[0] === "RESUME") {
-        if (this._slot.pull && m[1] === this._slot.pullLock) {
-          if (!this._markDemandRouted(m[1], routeState)) this._onDemand();
-        } else if (this._control.pauseLockset.has(m[1])) {
+        if (this._control.pauseLockset.has(m[1])) {
           this._pauseRelease(m[1]);
         } else {
           this._forwardUp(m, towardDep, routeState);
         }
+      } else if (m[0] === "PULL") {
+        const demand = normalizePullDemand(m[1]);
+        if (this._slot.pull && demand.pullId === this._slot.pullLock) {
+          if (!this._markDemandRouted(demand.pullId, routeState)) this._onDemand(demand);
+        } else {
+          this._forwardUp(["PULL", demand], towardDep, routeState);
+        }
       } else if (this._slot.deps.length === 0) {
         if (m[0] === "INVALIDATE") this._down([["INVALIDATE"]]);
       } else {
@@ -2134,7 +2161,7 @@ var Node = class {
    * Forward one up-going control message toward deps (R-up-routing): up the single declared edge
    * `towardDep` (directed — prunes other branches; only meaningful on the issuer's FIRST hop) or
    * broadcast up ALL deps. A depless source has no deps → the message DROPS here (the terminus —
-   * e.g. a cone-routed RESUME whose pullId no node up this cone holds, R-up-at-source). Recursive
+   * e.g. a cone-routed PULL whose pullId no node up this cone holds, R-up-at-source). Recursive
    * forwarding carries the same per-wave route state and no `towardDep` → broadcast beyond the
    * first hop.
    */
@@ -2153,9 +2180,7 @@ var Node = class {
   }
   _hasBoundaryPauseLock() {
     if (this._slot.pausable === false) return false;
-    let locks = this._control.pauseLockset.size;
-    if (this._slot.pull && this._control.pauseLockset.has(this._slot.pullLock)) locks--;
-    return locks > 0;
+    return this._control.pauseLockset.size > 0;
   }
   _isAsyncPool() {
     return this._slot.handle !== null && this._slot.dispatcher.poolKind(this._slot.handle.poolId) === "async";
@@ -2166,17 +2191,19 @@ var Node = class {
   _pauseRelease(lockId) {
     if (!this._control.pauseLockset.has(lockId)) return;
     this._control.pauseLockset.delete(lockId);
-    if (this._slot.pull && this._control.demandOwed) this._fireOwedDemandIfReady();
+    if (this._slot.pull && this._control.demandOwed !== void 0) this._fireOwedDemandIfReady();
     if (this._hasBoundaryPauseLock()) return;
     scheduleBoundaryDrain(this._core);
-    if (this._control.pauseLockset.size > 0) return;
+    if (this._slot.pull) return;
     this._onResume();
   }
   _onResume() {
     if (this._value.terminal !== void 0) {
       this._control.pauseBuffer = [];
       this._control.pausedDepWaveOccurred = false;
-      this._control.demandOwed = false;
+      this._control.demandOwed = void 0;
+      this._control.activePull = void 0;
+      this._control.pullDirtyOwed = false;
       return;
     }
     if (this._control.pauseBuffer.length > 0) {
@@ -2190,41 +2217,38 @@ var Node = class {
     }
   }
   /**
-   * R-pull (D59): can this pull node fire a demand NOW? — not terminal, settle-ready (_pending===0),
+   * R-pull (D269): can this pull node fire a demand NOW? — not terminal, settle-ready (_pending===0),
    * and no OTHER (non-pullId) lock holds it paused. The gate that decides fire-now vs OWE.
    */
   _canFireDemand() {
     if (this._value.terminal !== void 0 || this._wave.pending > 0) return false;
-    const own = this._control.pauseLockset.has(this._slot.pullLock) ? 1 : 0;
-    return this._control.pauseLockset.size <= own;
+    return this._control.pauseLockset.size === 0;
   }
   /**
-   * R-pull (D59): deliver ONE demand pulse — release the pullId so the demand wave RELAYS (not
-   * absorbed), fire it, then RE-QUIET (1:1). The pullId re-add + the re-entrancy flag are in a
-   * `finally` so a throwing pull fn (graph-less node, no D30 catch) cannot leave the node
-   * permanently non-quiet (the wedge-fix silently disabled) — QA-found robustness fix.
+   * R-pull (D269/D272): deliver ONE demand pulse — install activePull so the demand wave may
+   * emit, fire it, then clear activePull so the node is quiet again (1:1).
    */
-  _deliverPullDemand() {
-    this._control.demandOwed = false;
+  _deliverPullDemand(demand) {
+    this._control.demandOwed = void 0;
+    this._control.activePull = demand;
     this._control.inDeliverDemand = true;
-    this._control.pauseLockset.delete(this._slot.pullLock);
     try {
       this._firePullDemand();
     } finally {
-      this._control.pauseLockset.add(this._slot.pullLock);
+      this._control.activePull = void 0;
       this._control.inDeliverDemand = false;
     }
   }
   /**
-   * R-pull (D59): a cone-routed RESUME of THIS node's pullId arrived (R-up-routing) = a DEMAND.
+   * R-pull (D269): a cone-routed PULL of THIS node's pullId arrived (R-up-routing) = a DEMAND.
    * Fire immediately if able; else OWE it — pin-5 (a dep DIRTY in flight, _pending>0) or F4/F5 (an
    * external PAUSE lock co-holds the node) — and fire when the node next becomes able. A demand
    * arriving WHILE a delivery is in flight (synchronous re-entry) is DROPPED (1:1, QA guard).
    */
-  _onDemand() {
+  _onDemand(demand) {
     if (this._control.inDeliverDemand) return;
-    if (this._canFireDemand()) this._deliverPullDemand();
-    else this._control.demandOwed = true;
+    if (this._canFireDemand()) this._deliverPullDemand(demand);
+    else this._control.demandOwed = demand;
   }
   /**
    * R-pull (D55): service ONE demand. Delivery content = the orthogonal pausable mode:
@@ -2237,33 +2261,53 @@ var Node = class {
    * `_markDirty` relays the leading DIRTY (not absorbed).
    */
   _firePullDemand() {
+    let drainedBuffer = false;
     if (this._control.pauseBuffer.length > 0) {
       const buf = this._control.pauseBuffer;
       this._control.pauseBuffer = [];
       for (const wave of buf) this._down(wave);
+      drainedBuffer = true;
     }
+    if (drainedBuffer) return;
     if (this._control.pausedDepWaveOccurred) {
       const gated = this._slot.handle !== null && !this._wave.hasCalledFnOnce && !(this._slot.partial || this._allDepsSettled());
       if (this._wave.pending > 0 || gated) return;
       this._control.pausedDepWaveOccurred = false;
-      this._markDirty();
-      this._tryRun();
+      this._wave.emittedDirtyThisWave = false;
+      this._control.pullDirtyOwed = true;
+      try {
+        this._tryRun();
+      } finally {
+        this._control.pullDirtyOwed = false;
+      }
+      return;
+    }
+    if (this._slot.handle !== null) {
+      if (!this._wave.hasCalledFnOnce && !(this._slot.partial || this._allDepsSettled())) return;
+      this._wave.emittedDirtyThisWave = false;
+      this._control.pullDirtyOwed = true;
+      try {
+        this._runWave();
+      } finally {
+        this._control.pullDirtyOwed = false;
+      }
     }
   }
   /**
-   * R-pull (D55/D59): fire a demand that was OWED (deferred at demand time) once the node becomes
+   * R-pull (D269): fire a demand that was OWED (deferred at demand time) once the node becomes
    * able — called from the dep-settle arms (DATA/RESOLVED/INVALIDATE/terminal drain _pending, pin-5
    * + B1/F6) and from `_pauseRelease` (an external PAUSE lock releases, F4/F5).
    */
   _fireOwedDemandIfReady() {
     if (this._control.inDeliverDemand) return;
-    if (this._slot.pull && this._control.demandOwed && this._canFireDemand())
-      this._deliverPullDemand();
+    if (this._slot.pull && this._control.demandOwed !== void 0 && this._canFireDemand()) {
+      this._deliverPullDemand(this._control.demandOwed);
+    }
   }
   /** Should an outgoing settle slice be deferred into the pause buffer? */
   _shouldBufferOnPause() {
     if (this._slot.pausable === false) return false;
-    if (!this._isPaused()) return false;
+    if (!this._isPaused() && !this._isPullQuiet()) return false;
     if (this._slot.pausable === "resumeAll") return true;
     if (!this._wave.insideRunWave && this._isAsyncPool() && this._slot.deps.length > 0) return true;
     return false;
@@ -2303,7 +2347,9 @@ var Node = class {
     this._control.pauseLockset.clear();
     this._control.pauseBuffer = [];
     this._control.pausedDepWaveOccurred = false;
-    this._control.demandOwed = false;
+    this._control.demandOwed = void 0;
+    this._control.activePull = void 0;
+    this._control.pullDirtyOwed = false;
     this._value.replayRing = [];
     const isCompute = this._slot.handle !== null || this._slot.deps.length > 0;
     if (isCompute) {
@@ -3002,6 +3048,71 @@ function source2(factory, setup) {
     }
   };
 }
+function defaultAnimationFrameScheduler(fallbackMs) {
+  const host = globalThis;
+  if (typeof host.requestAnimationFrame === "function" && typeof host.cancelAnimationFrame === "function") {
+    return {
+      requestAnimationFrame: (callback) => host.requestAnimationFrame?.(callback) ?? 0,
+      cancelAnimationFrame: (handle) => {
+        if (typeof handle === "number") host.cancelAnimationFrame?.(handle);
+      }
+    };
+  }
+  return {
+    requestAnimationFrame(callback) {
+      return setTimeout(() => callback(Date.now()), fallbackMs);
+    },
+    cancelAnimationFrame(handle) {
+      clearTimeout(handle);
+    }
+  };
+}
+function defaultVisibilityDocument() {
+  return globalThis.document;
+}
+function fromRaf(opts = {}) {
+  const fallbackMsOpt = opts.fallbackMs;
+  const fallbackMs = Number.isFinite(fallbackMsOpt) && fallbackMsOpt !== void 0 && fallbackMsOpt > 0 ? fallbackMsOpt : 16;
+  const scheduler = opts.scheduler ?? defaultAnimationFrameScheduler(fallbackMs);
+  const visibilityDocument = opts.document ?? defaultVisibilityDocument();
+  return {
+    factory: "fromRaf",
+    opts: { pool: "sync", pausable: false },
+    body: (ctx) => {
+      let active2 = true;
+      let frame;
+      const cancelPending = () => {
+        if (frame === void 0) return;
+        scheduler.cancelAnimationFrame(frame);
+        frame = void 0;
+      };
+      const isHidden = () => opts.pauseWhenHidden === true && visibilityDocument?.visibilityState === "hidden";
+      const schedule = () => {
+        if (!active2 || frame !== void 0 || isHidden()) return;
+        frame = scheduler.requestAnimationFrame((time) => {
+          frame = void 0;
+          if (!active2 || isHidden()) return;
+          ctx.down([["DATA", Number.isFinite(time) ? time : Date.now()]]);
+          schedule();
+        });
+      };
+      const onVisibilityChange = () => {
+        if (!active2) return;
+        if (isHidden()) cancelPending();
+        else schedule();
+      };
+      if (opts.pauseWhenHidden === true && visibilityDocument?.addEventListener && visibilityDocument.removeEventListener) {
+        visibilityDocument.addEventListener("visibilitychange", onVisibilityChange);
+      }
+      ctx.onDeactivation(() => {
+        active2 = false;
+        cancelPending();
+        visibilityDocument?.removeEventListener?.("visibilitychange", onVisibilityChange);
+      });
+      schedule();
+    }
+  };
+}
 function fromIDBRequest(request) {
   return source2("fromIDBRequest", (ctx) => {
     let done = false;
@@ -3076,6 +3187,7 @@ function fromIDBTransaction(transaction) {
   fromIter,
   fromPromise,
   fromPushNotification,
+  fromRaf,
   fromSSE,
   fromSSEWithOptions,
   fromTimer,