@modernrelay/orbit-core 0.14.0 → 0.16.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { DIAGNOSTIC_SAMPLE_CAP, encodeStringTable, collectTransfers, deriveClusters, resolveClusterCenters, clusterCentroids, EnvelopeSequencer, RequestLedger } from './chunk-KRCG2JFN.js';
-export { DEFAULT_CLUSTER_CENTER_RADIUS, DEFAULT_LAYOUT_SEED, DIAGNOSTIC_SAMPLE_CAP, acceptColumnar, clusterCentroids, collectTransfers, decodeStringTable, deriveClusters, encodeStringTable, generateClusterCenters, judgeEpoch, resolveClusterCenters } from './chunk-KRCG2JFN.js';
+import { DIAGNOSTIC_SAMPLE_CAP, resolveSimulation, encodeStringTable, collectTransfers, deriveClusters, resolveClusterCenters, clusterCentroids, EnvelopeSequencer, RequestLedger } from './chunk-DCY66QZS.js';
+export { DEFAULT_CLUSTER_CENTER_RADIUS, DEFAULT_LAYOUT_SEED, DIAGNOSTIC_SAMPLE_CAP, SIMULATION_PRESETS, acceptColumnar, clusterCentroids, collectTransfers, decodeStringTable, deriveClusters, encodeStringTable, generateClusterCenters, judgeEpoch, resolveClusterCenters, resolveSimulation } from './chunk-DCY66QZS.js';
 import { createStore } from 'zustand/vanilla';
 
 // src/errors.ts
@@ -123,6 +123,10 @@ function validateSnapshot(snapshot) {
       record(invalidEdge, typeof edge.id === "string" ? edge.id : `[${i}]`);
       continue;
     }
+    if (typeof edge.id === "string" && edge.id.includes("\0")) {
+      record(invalidEdge, `[${i}]`);
+      continue;
+    }
     if (!nodeIndex.has(source)) {
       record(danglingEdge, source);
       continue;
@@ -172,7 +176,7 @@ function validateSnapshot(snapshot) {
     "invalid-edge",
     "error",
     invalidEdge,
-    `${invalidEdge.count} edge row(s) dropped: missing or non-string source/target`
+    `${invalidEdge.count} edge row(s) dropped: missing or non-string source/target, or NUL-containing explicit id`
   );
   pushDiagnostic(
     diagnostics,
@@ -1239,7 +1243,7 @@ function stageBatch(contribution, batch, tallies, nextOrder) {
   for (let i = 0; i < rawNodes.length; i++) {
     const row = rawNodes[i];
     const id = typeof row === "object" && row !== null ? row.id : void 0;
-    if (typeof id !== "string") {
+    if (typeof id !== "string" || id.includes("\0")) {
       recordRow(tallies.invalidNodes, `[${batch.sequence}:${i}]`);
       continue;
     }
@@ -1263,6 +1267,10 @@ function stageBatch(contribution, batch, tallies, nextOrder) {
       recordRow(tallies.invalidEdges, typeof edge.id === "string" ? edge.id : `[${batch.sequence}:${i}]`);
       continue;
     }
+    if (typeof edge.id === "string" && edge.id.includes("\0")) {
+      recordRow(tallies.invalidEdges, `[${batch.sequence}:${i}]`);
+      continue;
+    }
     const hasExplicitId = typeof edge.id === "string";
     let id;
     if (hasExplicitId) {
@@ -1415,7 +1423,7 @@ function sessionCommitDiagnostics(tallies, danglingCount, danglingSamples = [])
     "invalid-node",
     "error",
     tallies.invalidNodes,
-    `${tallies.invalidNodes.count} ingested node row(s) dropped: missing or non-string id`
+    `${tallies.invalidNodes.count} ingested node row(s) dropped: missing, non-string, or NUL-containing id`
   );
   push(
     "duplicate-node-id",
@@ -1427,7 +1435,7 @@ function sessionCommitDiagnostics(tallies, danglingCount, danglingSamples = [])
     "invalid-edge",
     "error",
     tallies.invalidEdges,
-    `${tallies.invalidEdges.count} ingested edge row(s) dropped: missing or non-string source/target`
+    `${tallies.invalidEdges.count} ingested edge row(s) dropped: missing or non-string source/target, or NUL-containing explicit id`
   );
   push(
     "duplicate-edge-id",
@@ -2982,6 +2990,16 @@ function checkStringColumn(col, rows, where, isIds, out) {
     out.push({ where, problem: "not-a-string-column", detail: 'expected {kind:"string", dictionary, codes}' });
     return;
   }
+  for (let d = 0; d < col.dictionary.length; d++) {
+    if (typeof col.dictionary[d] !== "string") {
+      out.push({
+        where,
+        problem: "not-a-string-column",
+        detail: `dictionary entry ${d} is not a string`
+      });
+      return;
+    }
+  }
   if (col.codes.length !== rows) {
     const detached = col.codes.length === 0 && col.codes.buffer.byteLength === 0;
     out.push({
@@ -3230,10 +3248,12 @@ function detachColumnarBuffers(snapshot) {
   return detached;
 }
 
-// src/worker/lane.ts
-function defaultWorkerUrl() {
-  return new URL("./worker/entry.js", import.meta.url);
+// src/workerAsset.ts
+function createDefaultWorker() {
+  return new Worker(new URL("./worker/entry.js", import.meta.url), { type: "module" });
 }
+
+// src/worker/lane.ts
 function transportFromWorker(worker) {
   return {
     post: (envelope, transfers) => worker.postMessage(envelope, [...transfers]),
@@ -3275,10 +3295,7 @@ var WorkerLane = class {
       let transport = this.options.transport ?? null;
       if (transport === null) {
         const factory = this.options.factory;
-        const worker = factory !== void 0 && "create" in factory ? factory.create() : new Worker(
-          factory !== void 0 && "url" in factory ? factory.url : defaultWorkerUrl(),
-          { type: "module" }
-        );
+        const worker = factory !== void 0 && "create" in factory ? factory.create() : factory !== void 0 && "url" in factory ? new Worker(factory.url, { type: "module" }) : createDefaultWorker();
         transport = transportFromWorker(worker);
       }
       transport.onReply((reply) => this.settle(reply));
@@ -5026,6 +5043,7 @@ var isNum = (v) => typeof v === "number" && Number.isFinite(v);
 var isBool = (v) => typeof v === "boolean";
 var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isStrArray = (v) => Array.isArray(v) && v.every(isStr);
+var isNumArray = (v) => Array.isArray(v) && v.every(isNum);
 function validateBrush(v, at, problems) {
   if (!isObj(v)) {
     problems.push(`${at}: not an object`);
@@ -5044,18 +5062,43 @@ function validateBrush(v, at, problems) {
   }
   problems.push(`${at}: unknown brush kind`);
 }
-function validateScale(v, at, problems) {
+function validateScale(v, at, valueKind, problems) {
   if (!isObj(v)) {
     problems.push(`${at}: not an object`);
     return;
   }
-  if (v["kind"] === "sequential" || v["kind"] === "diverging") {
+  const isValueArray = valueKind === "string" ? isStrArray : isNumArray;
+  const valueLabel = valueKind === "string" ? "string" : "finite number";
+  if (v["kind"] === "sequential") {
     if (!isStr(v["metric"])) problems.push(`${at}: metric must be a string`);
-    if (!Array.isArray(v["range"])) problems.push(`${at}: range must be an array`);
+    if (!isValueArray(v["range"]) || v["range"].length !== 2) {
+      problems.push(`${at}: sequential range must be a [${valueLabel}, ${valueLabel}] tuple`);
+    }
+    if (v["domain"] !== void 0 && (!isNumArray(v["domain"]) || v["domain"].length !== 2)) {
+      problems.push(`${at}: sequential domain must be a [min, max] finite-number tuple`);
+    }
+    return;
+  }
+  if (v["kind"] === "diverging") {
+    if (!isStr(v["metric"])) problems.push(`${at}: metric must be a string`);
+    if (!isValueArray(v["range"]) || v["range"].length !== 3) {
+      problems.push(
+        `${at}: diverging range must be a [${valueLabel}, ${valueLabel}, ${valueLabel}] tuple`
+      );
+    }
+    if (!isNum(v["mid"])) {
+      problems.push(`${at}: diverging mid must be a finite number`);
+    }
     return;
   }
   if (v["kind"] === "categorical") {
     if (!isStr(v["by"])) problems.push(`${at}: categorical 'by' must be a field string`);
+    if (v["domain"] !== void 0 && !isStrArray(v["domain"])) {
+      problems.push(`${at}: categorical domain must be a string[]`);
+    }
+    if (v["palette"] !== void 0 && !isValueArray(v["palette"])) {
+      problems.push(`${at}: categorical palette must be a ${valueLabel}[]`);
+    }
     return;
   }
   problems.push(`${at}: unknown scale kind`);
@@ -5180,10 +5223,10 @@ function validateViewState(raw) {
       problems.push("styling: must be an object");
     } else {
       if (styling["nodeColor"] !== void 0) {
-        validateScale(styling["nodeColor"], "styling.nodeColor", problems);
+        validateScale(styling["nodeColor"], "styling.nodeColor", "string", problems);
       }
       if (styling["nodeSize"] !== void 0) {
-        validateScale(styling["nodeSize"], "styling.nodeSize", problems);
+        validateScale(styling["nodeSize"], "styling.nodeSize", "number", problems);
       }
       for (const flag of ["showLinks", "edgeArrows"]) {
         if (styling[flag] !== void 0 && !isBool(styling[flag])) {
@@ -6339,6 +6382,9 @@ function pruneIds(ids, base) {
 function createGraphInstance(opts) {
   const engineFactory = opts.engine;
   const fitViewOnFirstData = opts.fitViewOnFirstData ?? true;
+  const fitViewOnSettle = opts.fitViewOnSettle ?? "follow";
+  const fitViewMaxZoom = opts.fitViewMaxZoom === void 0 ? 1.5 : opts.fitViewMaxZoom;
+  const clampFit = (o) => fitViewMaxZoom === null ? o : { ...o, maxZoom: fitViewMaxZoom };
   const store = createStore(() => ({
     status: "idle",
     revisions: { source: null, model: 0, scope: 0, render: 0, appliedRender: null },
@@ -6507,7 +6553,7 @@ function createGraphInstance(opts) {
   let linkColor;
   let linkWidth;
   let layout = "force";
-  let simulation;
+  let simulation = resolveSimulation(void 0);
   let theme = resolveTheme(void 0);
   let edgeArrows = false;
   let showLinks = true;
@@ -8193,7 +8239,7 @@ function createGraphInstance(opts) {
             simRestarted = true;
           }
         }
-        eng.commit(commit);
+        commitToEngine(eng, commit);
         revisions.appliedRender = eng.appliedRevision();
         const facade = session !== null ? session.edgePicking : null;
         if (facade !== null) {
@@ -9078,12 +9124,41 @@ function createGraphInstance(opts) {
       if (idx !== void 0) applyEmphasis(eng, idx);
     }
   }
+  const SETTLE_FOLLOW_INTERVAL_FRAMES = 55;
+  const SETTLE_FOLLOW_CAP_FRAMES = 480;
+  let settleFollowFrames = null;
+  let settleFollowContainer = null;
+  const settleFollowCancelListener = () => {
+    cancelSettleFollow();
+  };
+  function cancelSettleFollow() {
+    if (settleFollowContainer !== null) {
+      settleFollowContainer.removeEventListener?.("pointerdown", settleFollowCancelListener);
+      settleFollowContainer.removeEventListener?.("wheel", settleFollowCancelListener);
+      settleFollowContainer = null;
+    }
+    settleFollowFrames = null;
+  }
+  function armSettleFollow(s) {
+    if (fitViewOnSettle === false || layout !== "force") return;
+    settleFollowFrames = 0;
+    if (typeof s.container.addEventListener === "function") {
+      settleFollowContainer = s.container;
+      s.container.addEventListener("pointerdown", settleFollowCancelListener);
+      s.container.addEventListener("wheel", settleFollowCancelListener);
+    }
+  }
+  function settleFollowFit(eng, durationMs) {
+    if (effectiveReducedMotion()) eng.fitView(clampFit({ durationMs: 0 }));
+    else eng.fitView(clampFit({ durationMs }));
+  }
   function maybeFitView(eng) {
     if (!fitViewOnFirstData || session === null || session.fitDone) return;
     if (accepted === null) return;
     session.fitDone = true;
-    if (effectiveReducedMotion()) eng.fitView({ durationMs: 0 });
-    else eng.fitView();
+    if (effectiveReducedMotion()) eng.fitView(clampFit({ durationMs: 0 }));
+    else eng.fitView(clampFit({}));
+    armSettleFollow(session);
   }
   function nodeIndexBase() {
     return accepted === null ? EMPTY_INDEX2 : accepted.nodeIndex;
@@ -11498,10 +11573,13 @@ function createGraphInstance(opts) {
     {
       const c = {};
       let any = false;
-      if (update.simulation !== void 0 && !Object.is(update.simulation, simulation)) {
-        simulation = update.simulation;
-        c.simulation = update.simulation;
-        any = true;
+      if (update.simulation !== void 0) {
+        const nextSimulation = resolveSimulation(update.simulation);
+        if (!Object.is(nextSimulation, simulation)) {
+          simulation = nextSimulation;
+          c.simulation = nextSimulation;
+          any = true;
+        }
       }
       if (update.theme !== void 0) {
         const nextTheme = resolveTheme(update.theme);
@@ -12082,6 +12160,14 @@ function createGraphInstance(opts) {
       onFrame(timeMs) {
         if (!active()) return;
         frameCadence += 1;
+        if (settleFollowFrames !== null && fitViewOnSettle === "follow") {
+          settleFollowFrames += 1;
+          if (settleFollowFrames > SETTLE_FOLLOW_CAP_FRAMES) {
+            cancelSettleFollow();
+          } else if (settleFollowFrames % SETTLE_FOLLOW_INTERVAL_FRAMES === 0) {
+            settleFollowFit(s.engine, 650);
+          }
+        }
         pressureSampler.noteFrame(timeMs, !store.getState().simulationRunning);
         flushCrossfilterNotify();
         if (timeMs - lastPerfSampleAt >= PERF_SAMPLE_THROTTLE_MS) {
@@ -12128,6 +12214,10 @@ function createGraphInstance(opts) {
       },
       onSimulationEnd() {
         if (!active()) return;
+        if (settleFollowFrames !== null) {
+          settleFollowFit(s.engine, 800);
+          cancelSettleFollow();
+        }
         if (accretionPinIds !== null) {
           accretionPinIds = null;
           pushPinsToEngine(s.engine, store.getState().pins);
@@ -12361,6 +12451,7 @@ function createGraphInstance(opts) {
     s.alive = false;
     session = null;
     mountPromise = null;
+    cancelSettleFollow();
     cancelRerankTimer();
     flushCrossfilterNotify();
     if (quiescenceTimer !== null) {
@@ -12489,33 +12580,34 @@ function createGraphInstance(opts) {
       return void 0;
     }
     if (!isScaleValue(value)) return void 0;
-    if (value.kind === "sequential") {
+    const scale = value;
+    if (scale.kind === "sequential") {
       return {
         kind: "sequential",
-        metric: value.metric,
-        range: value.range,
+        metric: scale.metric,
+        range: scale.range,
         // The numeric-array domain form is data; a DomainPolicy is app
         // behavior config and stays with the app.
-        ...Array.isArray(value.domain) ? { domain: value.domain } : {}
+        ...Array.isArray(scale.domain) ? { domain: scale.domain } : {}
       };
     }
-    if (value.kind === "diverging") {
+    if (scale.kind === "diverging") {
       return {
         kind: "diverging",
-        metric: value.metric,
-        range: value.range,
-        mid: value.mid
+        metric: scale.metric,
+        range: scale.range,
+        mid: scale.mid
       };
     }
-    if (typeof value.by !== "string") {
+    if (typeof scale.by !== "string") {
       warnViewStateDrop(channel, "a function-`by` categorical scale does not serialize");
       return void 0;
     }
     return {
       kind: "categorical",
-      by: value.by,
-      ...value.palette !== void 0 ? { palette: value.palette } : {},
-      ...value.domain !== void 0 ? { domain: value.domain } : {}
+      by: scale.by,
+      ...scale.palette !== void 0 ? { palette: scale.palette } : {},
+      ...scale.domain !== void 0 ? { domain: scale.domain } : {}
     };
   }
   function serializableThemeOf() {
@@ -12835,7 +12927,7 @@ function createGraphInstance(opts) {
                   ...prevState.revisions,
                   render: prevState.revisions.render + 1
                 };
-                eng.commit({
+                commitToEngine(eng, {
                   revision: nextRevisions.render,
                   structure: {
                     pointCount: scene.count,
@@ -12843,6 +12935,7 @@ function createGraphInstance(opts) {
                     links: scene.links
                   }
                 });
+                nextRevisions.appliedRender = eng.appliedRevision();
                 eng.pause();
                 const patch = { revisions: nextRevisions };
                 if (prevState.simulationRunning) patch.simulationRunning = false;
@@ -12851,6 +12944,7 @@ function createGraphInstance(opts) {
             }
           }
           if (state.camera !== null) {
+            cancelSettleFollow();
             const eng = engineIfReady();
             if (eng !== null) {
               if (effectiveReducedMotion()) eng.setViewport(state.camera, { durationMs: 0 });
@@ -13170,6 +13264,7 @@ function createGraphInstance(opts) {
     });
   }
   function focusNode(id, opts2) {
+    cancelSettleFollow();
     const eng = engineIfReady();
     if (eng === null || scene === null) return EMPTY_IDS;
     const idx = scene.indexById.get(id);
@@ -13250,6 +13345,7 @@ function createGraphInstance(opts) {
     return bytes;
   }
   function cameraZoom(factor) {
+    cancelSettleFollow();
     const eng = engineIfReady();
     if (eng === null) return;
     if (effectiveReducedMotion()) eng.zoom(factor, 0);
@@ -13303,10 +13399,11 @@ function createGraphInstance(opts) {
     destroy,
     on,
     fitView: () => {
+      cancelSettleFollow();
       const eng = engineIfReady();
       if (eng === null) return;
-      if (effectiveReducedMotion()) eng.fitView({ durationMs: 0 });
-      else eng.fitView();
+      if (effectiveReducedMotion()) eng.fitView(clampFit({ durationMs: 0 }));
+      else eng.fitView(clampFit({}));
     },
     zoomIn: () => {
       cameraZoom(ZOOM_STEP);
@@ -13315,6 +13412,7 @@ function createGraphInstance(opts) {
       cameraZoom(1 / ZOOM_STEP);
     },
     setViewport: (v) => {
+      cancelSettleFollow();
       const eng = engineIfReady();
       if (eng === null) return;
       if (effectiveReducedMotion()) eng.setViewport(v, { durationMs: 0 });