@graphrefly/graphrefly 0.22.0 → 0.24.0

package/dist/patterns/reactive-layout/index.cjs

@@ -316,6 +316,109 @@ var ImageSizeAdapter = class {
   }
 };
 
+// src/core/clock.ts
+function monotonicNs() {
+  return Math.trunc(performance.now() * 1e6);
+}
+function wallClockNs() {
+  return Date.now() * 1e6;
+}
+
+// src/graph/codec.ts
+var JsonCodec = {
+  name: "json",
+  version: 1,
+  contentType: "application/json",
+  encode(snapshot) {
+    const json = JSON.stringify(snapshot);
+    return new TextEncoder().encode(json);
+  },
+  decode(buffer, _codecVersion) {
+    const json = new TextDecoder().decode(buffer);
+    return JSON.parse(json);
+  }
+};
+var ENVELOPE_VERSION = 1;
+var ENVELOPE_MIN_LEN = 4;
+function encodeEnvelope(codec, payload) {
+  const nameBytes = new TextEncoder().encode(codec.name);
+  if (nameBytes.length === 0 || nameBytes.length > 255) {
+    throw new Error(
+      `encodeEnvelope: codec name "${codec.name}" encodes to ${nameBytes.length} bytes (must be 1\u2013255)`
+    );
+  }
+  const cv = codec.version;
+  if (!Number.isInteger(cv) || cv < 0 || cv > 65535) {
+    throw new Error(
+      `encodeEnvelope: codec.version ${cv} out of u16 range (expected integer 0\u201365535)`
+    );
+  }
+  const totalLen = 1 + 1 + nameBytes.length + 2 + payload.length;
+  if (totalLen > 4294967295) {
+    throw new Error(
+      `encodeEnvelope: total envelope size ${totalLen} exceeds 2^32-1 bytes (payload ${payload.length} bytes)`
+    );
+  }
+  const out = new Uint8Array(totalLen);
+  let i = 0;
+  out[i++] = ENVELOPE_VERSION;
+  out[i++] = nameBytes.length;
+  out.set(nameBytes, i);
+  i += nameBytes.length;
+  out[i++] = cv >>> 8 & 255;
+  out[i++] = cv & 255;
+  out.set(payload, i);
+  return out;
+}
+function decodeEnvelope(bytes, config) {
+  if (bytes.length < ENVELOPE_MIN_LEN) {
+    throw new Error(`decodeEnvelope: bytes too short (${bytes.length} < ${ENVELOPE_MIN_LEN})`);
+  }
+  let i = 0;
+  const envVersion = bytes[i++];
+  if (envVersion !== ENVELOPE_VERSION) {
+    throw new Error(
+      `decodeEnvelope: unsupported envelope version ${envVersion} (expected ${ENVELOPE_VERSION})`
+    );
+  }
+  const nameLen = bytes[i++];
+  if (nameLen === 0) {
+    throw new Error("decodeEnvelope: name_len must be >= 1");
+  }
+  if (i + nameLen + 2 > bytes.length) {
+    throw new Error(
+      `decodeEnvelope: envelope truncated (need ${i + nameLen + 2} bytes, have ${bytes.length})`
+    );
+  }
+  const name = new TextDecoder().decode(bytes.subarray(i, i + nameLen));
+  i += nameLen;
+  const codecVersion = (bytes[i] << 8 | bytes[i + 1]) >>> 0;
+  i += 2;
+  const payload = bytes.subarray(i);
+  const codec = config.lookupCodec(name);
+  if (codec == null) {
+    throw new Error(
+      `decodeEnvelope: codec "${name}" not registered (envelope codec_v=${codecVersion})`
+    );
+  }
+  return { codec, codecVersion, payload };
+}
+function registerBuiltinCodecs(config) {
+  config.registerCodec(JsonCodec);
+}
+
+// src/core/actor.ts
+var DEFAULT_ACTOR = { type: "system", id: "" };
+function normalizeActor(actor) {
+  if (actor == null) return DEFAULT_ACTOR;
+  const { type, id, ...rest } = actor;
+  return {
+    type: type ?? "system",
+    id: id ?? "",
+    ...rest
+  };
+}
+
 // src/core/batch.ts
 var MAX_DRAIN_ITERATIONS = 1e3;
 var batchDepth = 0;
@@ -323,9 +426,20 @@ var flushInProgress = false;
 var drainPhase2 = [];
 var drainPhase3 = [];
 var drainPhase4 = [];
+var flushHooks = [];
 function isBatching() {
   return batchDepth > 0 || flushInProgress;
 }
+function isExplicitlyBatching() {
+  return batchDepth > 0;
+}
+function registerBatchFlushHook(hook) {
+  if (batchDepth > 0) {
+    flushHooks.push(hook);
+  } else {
+    hook();
+  }
+}
 function batch(fn) {
   batchDepth += 1;
   let threw = false;
@@ -339,6 +453,13 @@ function batch(fn) {
     if (batchDepth === 0) {
       if (threw) {
         if (!flushInProgress) {
+          const hooks = flushHooks.splice(0);
+          for (const h of hooks) {
+            try {
+              h();
+            } catch {
+            }
+          }
           drainPhase2.length = 0;
           drainPhase3.length = 0;
           drainPhase4.length = 0;
@@ -355,7 +476,18 @@ function drainPending() {
   const errors = [];
   let iterations = 0;
   try {
-    while (drainPhase2.length > 0 || drainPhase3.length > 0 || drainPhase4.length > 0) {
+    while (drainPhase2.length > 0 || drainPhase3.length > 0 || drainPhase4.length > 0 || ownsFlush && flushHooks.length > 0) {
+      if (ownsFlush && flushHooks.length > 0) {
+        const hooks = flushHooks.splice(0);
+        for (const h of hooks) {
+          try {
+            h();
+          } catch (e) {
+            errors.push(e);
+          }
+        }
+        continue;
+      }
       iterations += 1;
       if (iterations > MAX_DRAIN_ITERATIONS) {
         drainPhase2.length = 0;
@@ -428,14 +560,6 @@ function downWithBatch(sink, messages, tierOf) {
   }
 }
 
-// src/core/clock.ts
-function monotonicNs() {
-  return Math.trunc(performance.now() * 1e6);
-}
-function wallClockNs() {
-  return Date.now() * 1e6;
-}
-
 // src/core/messages.ts
 var START = /* @__PURE__ */ Symbol.for("graphrefly/START");
 var DATA = /* @__PURE__ */ Symbol.for("graphrefly/DATA");
@@ -459,101 +583,6 @@ var INVALIDATE_ONLY_BATCH = Object.freeze([INVALIDATE_MSG]);
 var COMPLETE_ONLY_BATCH = Object.freeze([COMPLETE_MSG]);
 var TEARDOWN_ONLY_BATCH = Object.freeze([TEARDOWN_MSG]);
 
-// src/graph/codec.ts
-var JsonCodec = {
-  name: "json",
-  version: 1,
-  contentType: "application/json",
-  encode(snapshot) {
-    const json = JSON.stringify(snapshot);
-    return new TextEncoder().encode(json);
-  },
-  decode(buffer, _codecVersion) {
-    const json = new TextDecoder().decode(buffer);
-    return JSON.parse(json);
-  }
-};
-var ENVELOPE_VERSION = 1;
-var ENVELOPE_MIN_LEN = 4;
-function encodeEnvelope(codec, payload) {
-  const nameBytes = new TextEncoder().encode(codec.name);
-  if (nameBytes.length === 0 || nameBytes.length > 255) {
-    throw new Error(
-      `encodeEnvelope: codec name "${codec.name}" encodes to ${nameBytes.length} bytes (must be 1\u2013255)`
-    );
-  }
-  const cv = codec.version;
-  if (!Number.isInteger(cv) || cv < 0 || cv > 65535) {
-    throw new Error(
-      `encodeEnvelope: codec.version ${cv} out of u16 range (expected integer 0\u201365535)`
-    );
-  }
-  const totalLen = 1 + 1 + nameBytes.length + 2 + payload.length;
-  if (totalLen > 4294967295) {
-    throw new Error(
-      `encodeEnvelope: total envelope size ${totalLen} exceeds 2^32-1 bytes (payload ${payload.length} bytes)`
-    );
-  }
-  const out = new Uint8Array(totalLen);
-  let i = 0;
-  out[i++] = ENVELOPE_VERSION;
-  out[i++] = nameBytes.length;
-  out.set(nameBytes, i);
-  i += nameBytes.length;
-  out[i++] = cv >>> 8 & 255;
-  out[i++] = cv & 255;
-  out.set(payload, i);
-  return out;
-}
-function decodeEnvelope(bytes, config) {
-  if (bytes.length < ENVELOPE_MIN_LEN) {
-    throw new Error(`decodeEnvelope: bytes too short (${bytes.length} < ${ENVELOPE_MIN_LEN})`);
-  }
-  let i = 0;
-  const envVersion = bytes[i++];
-  if (envVersion !== ENVELOPE_VERSION) {
-    throw new Error(
-      `decodeEnvelope: unsupported envelope version ${envVersion} (expected ${ENVELOPE_VERSION})`
-    );
-  }
-  const nameLen = bytes[i++];
-  if (nameLen === 0) {
-    throw new Error("decodeEnvelope: name_len must be >= 1");
-  }
-  if (i + nameLen + 2 > bytes.length) {
-    throw new Error(
-      `decodeEnvelope: envelope truncated (need ${i + nameLen + 2} bytes, have ${bytes.length})`
-    );
-  }
-  const name = new TextDecoder().decode(bytes.subarray(i, i + nameLen));
-  i += nameLen;
-  const codecVersion = (bytes[i] << 8 | bytes[i + 1]) >>> 0;
-  i += 2;
-  const payload = bytes.subarray(i);
-  const codec = config.lookupCodec(name);
-  if (codec == null) {
-    throw new Error(
-      `decodeEnvelope: codec "${name}" not registered (envelope codec_v=${codecVersion})`
-    );
-  }
-  return { codec, codecVersion, payload };
-}
-function registerBuiltinCodecs(config) {
-  config.registerCodec(JsonCodec);
-}
-
-// src/core/actor.ts
-var DEFAULT_ACTOR = { type: "system", id: "" };
-function normalizeActor(actor) {
-  if (actor == null) return DEFAULT_ACTOR;
-  const { type, id, ...rest } = actor;
-  return {
-    type: type ?? "system",
-    id: id ?? "",
-    ...rest
-  };
-}
-
 // src/core/config.ts
 var GraphReFlyConfig = class {
   _messageTypes = /* @__PURE__ */ new Map();
@@ -1088,6 +1117,22 @@ var NodeImpl = class _NodeImpl {
    * treats `0` as "wave settled" — O(1) check for full dep settlement.
    */
   _dirtyDepCount = 0;
+  // --- Per-batch emit accumulator (Bug 2: K+1 fan-in fix) ---
+  /**
+   * Inside an explicit `batch(() => ...)` scope, every `_emit` accumulates
+   * its already-framed messages here instead of dispatching synchronously.
+   * At batch end, `_flushBatchPending` runs (registered via
+   * `registerBatchFlushHook`) and delivers the whole accumulated batch as
+   * one `downWithBatch` call — collapsing what would otherwise be K
+   * separate sink invocations into one. This is the fix for the diamond
+   * fan-in K+1 over-fire.
+   *
+   * `null` outside batch (or after flush). Only ever appended to within
+   * a single explicit batch lifetime; reset to `null` on flush. State
+   * updates (cache, version, status) still happen per-emit via
+   * `_updateState` — only the downstream delivery is coalesced.
+   */
+  _batchPendingMessages = null;
   // --- PAUSE/RESUME lock tracking (C0) ---
   /**
    * Set of active pause locks held against this node. Every `[PAUSE, lockId]`
@@ -1465,7 +1510,10 @@ var NodeImpl = class _NodeImpl {
         dep.unsub = noopUnsub;
         dep.unsub = dep.node.subscribe((msgs) => {
           if (dep.unsub === null) return;
+          const tierOf = this._config.tierOf;
+          let sawSettlement = false;
           for (const m of msgs) {
+            if (tierOf(m[0]) >= 3) sawSettlement = true;
             this._config.onMessage(
               this,
               m,
@@ -1473,6 +1521,7 @@ var NodeImpl = class _NodeImpl {
               this._actions
             );
           }
+          if (sawSettlement) this._maybeRunFnOnSettlement();
         });
         subscribedCount++;
       }
@@ -1527,7 +1576,10 @@ var NodeImpl = class _NodeImpl {
     try {
       record.unsub = depNode.subscribe((msgs) => {
         if (record.unsub === null) return;
+        const tierOf = this._config.tierOf;
+        let sawSettlement = false;
         for (const m of msgs) {
+          if (tierOf(m[0]) >= 3) sawSettlement = true;
           this._config.onMessage(
             this,
             m,
@@ -1535,6 +1587,7 @@ var NodeImpl = class _NodeImpl {
             this._actions
           );
         }
+        if (sawSettlement) this._maybeRunFnOnSettlement();
       });
     } catch (err) {
       record.unsub = null;
@@ -1656,7 +1709,6 @@ var NodeImpl = class _NodeImpl {
       }
       return;
     }
-    this._maybeRunFnOnSettlement();
   }
   // --- Centralized dep-state transitions (A3 settlement counters) ---
   //
@@ -1902,37 +1954,35 @@ var NodeImpl = class _NodeImpl {
   // --- Emit pipeline ---
   /**
    * @internal The unified dispatch waist — one call = one wave.
+   * See `GRAPHREFLY-SPEC.md` §1.3.1 for protocol context — the stages
+   * below are the implementation order.
    *
    * Pipeline stages, in order:
    *
-   *   1. Early-return on empty batch.
-   *   2. Terminal filter — post-COMPLETE/ERROR only TEARDOWN/INVALIDATE
+   *   1. Terminal filter — post-COMPLETE/ERROR only TEARDOWN/INVALIDATE
    *      still propagate so graph teardown and cache-clear still work.
-   *   3. Tier sort (stable) — the batch can be in any order when it
+   *   2. Tier sort (stable) — the batch can be in any order when it
    *      arrives; the walker downstream (`downWithBatch`) assumes
    *      ascending tier monotone, and so does `_updateState`'s tier-3
    *      slice walk. This is the single source of truth for ordering.
-   *   4. Synthetic DIRTY prefix — if a tier-3 payload is present, no
+   *   3. Synthetic DIRTY prefix — if a tier-3 payload is present, no
    *      DIRTY is already in the batch, and the node isn't already in
    *      `"dirty"` status, prepend `[DIRTY]` after any tier-0 START
    *      entries. Guarantees spec §1.3.1 (DIRTY precedes DATA within
    *      the same batch) uniformly across every entry point.
-   *   5. PAUSE/RESUME lock bookkeeping (C0) — update `_pauseLocks`,
+   *   4. PAUSE/RESUME lock bookkeeping (C0) — update `_pauseLocks`,
    *      derive `_paused`, filter unknown-lockId RESUME, replay
    *      bufferAll buffer on final lock release.
-   *   6. Meta TEARDOWN fan-out — notify meta children before
+   *   5. Meta TEARDOWN fan-out — notify meta children before
    *      `_updateState`'s TEARDOWN branch calls `_deactivate`. Hoisted
    *      out of the walk to keep `_updateState` re-entrance-free.
-   *   7. `_updateState` — walk the batch in tier order, advancing
+   *   6. `_updateState` — walk the batch in tier order, advancing
    *      `_cached` / `_status` / `_versioning` and running equals
    *      substitution on tier-3 DATA (§3.5.1). Returns
    *      `{finalMessages, equalsError?}`.
-   *   8. `downWithBatch` dispatch (or bufferAll capture if paused with
+   *   7. `downWithBatch` dispatch (or bufferAll capture if paused with
    *      `pausable: "resumeAll"`).
-   *   9. Recursive ERROR emission if equals threw mid-walk.
-   *
-   * `node.down` / `node.emit` / `actions.down` / `actions.emit` all
-   * converge here — the unified `_emit` waist (spec §1.3.1).
+   *   8. Recursive ERROR emission if equals threw mid-walk.
    */
   _emit(messages) {
     if (messages.length === 0) return;
@@ -2028,10 +2078,10 @@ var NodeImpl = class _NodeImpl {
           }
         }
         if (immediate.length > 0) {
-          downWithBatch(this._deliverToSinks, immediate, tierOf);
+          this._dispatchOrAccumulate(immediate);
         }
       } else {
-        downWithBatch(this._deliverToSinks, finalMessages, this._config.tierOf);
+        this._dispatchOrAccumulate(finalMessages);
       }
     }
     if (equalsError != null) {
@@ -2154,6 +2204,50 @@ var NodeImpl = class _NodeImpl {
     const snapshot = [...this._sinks];
     for (const sink of snapshot) sink(messages);
   };
+  /**
+   * @internal Dispatch entry point that respects the per-batch emit
+   * accumulator (Bug 2). Inside an explicit `batch()` scope, append to
+   * `_batchPendingMessages` and register a flush hook on first append.
+   * Outside batch — or during a drain (where `flushInProgress` is true
+   * but `batchDepth` is 0) — dispatch synchronously through `downWithBatch`.
+   *
+   * Per-emit state updates (`_frameBatch`, `_updateState`) have already
+   * happened by the time we reach here; only the **downstream delivery**
+   * is coalesced. Cache, version, and status are visible mid-batch on
+   * the emitting node itself.
+   */
+  _dispatchOrAccumulate(messages) {
+    if (isExplicitlyBatching()) {
+      if (this._batchPendingMessages === null) {
+        this._batchPendingMessages = [];
+        registerBatchFlushHook(() => this._flushBatchPending());
+      }
+      for (const m of messages) this._batchPendingMessages.push(m);
+      return;
+    }
+    downWithBatch(this._deliverToSinks, messages, this._config.tierOf);
+  }
+  /**
+   * @internal Flushes the accumulated batch through `downWithBatch` and
+   * clears the pending state. Idempotent — safe to call when pending is
+   * already null or empty (e.g. on a `batch()` throw, where the hook
+   * fires for cleanup but the drainPhase queues are wiped after).
+   *
+   * Critical: the accumulated batch is interleaved per-emit framings like
+   * `[DIRTY, DATA(1), DIRTY, DATA(2)]` — non-monotone tier order. We must
+   * re-frame to sort by tier before handing to `downWithBatch`, which
+   * assumes pre-sorted input. `_frameBatch` also handles the synthetic
+   * DIRTY prepend rule (no-op here — `hasDirty` is true since each
+   * accumulated emit already carries its own DIRTY prefix).
+   */
+  _flushBatchPending() {
+    const pending = this._batchPendingMessages;
+    if (pending === null) return;
+    this._batchPendingMessages = null;
+    if (pending.length === 0) return;
+    const framed = this._frameBatch(pending);
+    downWithBatch(this._deliverToSinks, framed, this._config.tierOf);
+  }
 };
 var isNodeArray = (value) => Array.isArray(value);
 var isNodeOptionsObject = (value) => typeof value === "object" && value != null && !Array.isArray(value);
@@ -4760,6 +4854,12 @@ function reachable(described, from, direction, options = {}) {
   return paths;
 }
 
+// src/patterns/_internal.ts
+function emitToMeta(metaNode, value) {
+  if (metaNode == null) return;
+  downWithBatch((msgs) => metaNode.down(msgs), [[DATA, value]], defaultConfig.tierOf);
+}
+
 // src/patterns/reactive-layout/reactive-layout.ts
 function isCJK(s) {
   for (const ch of s) {
@@ -5216,13 +5316,9 @@ function reactiveLayout(opts) {
       const hitRate = lookups === 0 ? 1 : measureStats.hits / lookups;
       const meta = segmentsNode.meta;
       if (meta) {
-        const hr = hitRate;
-        const len = result.length;
-        const el = elapsed;
-        const tierOf = defaultConfig.tierOf;
-        downWithBatch((msgs) => meta["cache-hit-rate"]?.down(msgs), [[DATA, hr]], tierOf);
-        downWithBatch((msgs) => meta["segment-count"]?.down(msgs), [[DATA, len]], tierOf);
-        downWithBatch((msgs) => meta["layout-time-ns"]?.down(msgs), [[DATA, el]], tierOf);
+        emitToMeta(meta["cache-hit-rate"], hitRate);
+        emitToMeta(meta["segment-count"], result.length);
+        emitToMeta(meta["layout-time-ns"], elapsed);
       }
       actions.emit(result);
       return () => {
@@ -5442,9 +5538,8 @@ function reactiveBlockLayout(opts) {
       const elapsed = monotonicNs() - t0;
       const meta = measuredBlocksNode.meta;
       if (meta) {
-        const tierOf = defaultConfig.tierOf;
-        downWithBatch((msgs) => meta["block-count"]?.down(msgs), [[DATA, result.length]], tierOf);
-        downWithBatch((msgs) => meta["layout-time-ns"]?.down(msgs), [[DATA, elapsed]], tierOf);
+        emitToMeta(meta["block-count"], result.length);
+        emitToMeta(meta["layout-time-ns"], elapsed);
       }
       actions.emit(result);
       return () => {