@modernrelay/orbit-engine-cosmos 0.13.6 → 0.15.0

package/dist/index.js

@@ -67,21 +67,21 @@ var DEFAULT_SPACE_SIZE = 4096;
 var DEFAULT_RESTORE_DEADLINE_MS = 1e4;
 var CosmosEngine = class {
   capabilities = {
-    // Evidence-backed S6 flip: the M0 probe measured native onLinkClick/
+    // Evidence-backed flip: the probe measured native onLinkClick/
     // onLinkMouseOver delivering correct link indices with ~4px perpendicular
-    // tolerance (docs/m0-conformance.json, `link-picking`).
+    // tolerance.
     linkPicking: true,
     rangeUpdates: [],
     trackedPositions: true,
     simulation: true,
-    // §16.12: cosmos 3.3.0 exposes the `linkDefaultArrows` config key
+    // cosmos 3.3.0 exposes the `linkDefaultArrows` config key
     // (config.d.ts) — instanced arrowheads toggle atomically via setConfigPartial.
     edgeArrows: true,
-    // §8: cosmos 3.3.0 exposes setImageData(ImageData[]) +
+    // cosmos 3.3.0 exposes setImageData(ImageData[]) +
     // setPointImageIndices(Float32Array) (index.d.ts) — per-point sprites via
     // an adapter-maintained slot→ImageData atlas.
     pointImages: true,
-    // §16.3 stage 4: cosmos 3.3.0 ships a real GPU cluster force —
+    // stage 4: cosmos 3.3.0 ships a real GPU cluster force
     // `setPointClusters((number|undefined)[])`, `setClusterPositions(
     // (number|undefined)[])`, `setPointClusterStrength(Float32Array)`
     // (index.d.ts) plus the `simulationCluster` coefficient (config.d.ts,
@@ -89,14 +89,14 @@ var CosmosEngine = class {
     // `undefined` is cosmos' documented "not in any cluster" value, which the
     // adapter maps from the contract's NaN.
     clusterForce: true,
-    // §17 stop-at-rest: cosmos 3.4.0 ships on-demand rendering — the M0
+    // stop-at-rest: cosmos 3.4.0 ships on-demand rendering — the M0
     // quiescence row measured 0 idle frames AND 0 rAF registrations per
-    // 750ms at rest (docs/m0-conformance.md, was 91 on 3.3.0/ADR-002).
-    // The adapter's own activity clock is gated to match (ADR-005).
+    // 750ms at rest.
+    // The adapter's own activity clock is gated to match.
     idleFrames: "stops",
     // onFrame is an activity clock, not an exact post-draw hook — cosmos
     // still exposes no public frame hook (probe `post-draw-frames`);
-    // overlays may lag one sample (ADR-002).
+    // overlays may lag one sample.
     postDrawFrames: false
   };
   options;
@@ -118,7 +118,7 @@ var CosmosEngine = class {
   /** Sticky override from EngineConfigUpdate.seedRadius. */
   seedRadiusOverride;
   /** Point count of the last structure-bearing commit — the roster length a
-   * `cluster: null` clear must write an all-unclustered array for (§16.3). */
+   * `cluster: null` clear must write an all-unclustered array for. */
   lastPointCount = 0;
   /**
    * cosmos fires `onClick` (index undefined) AND `onBackgroundClick` for the
@@ -129,7 +129,7 @@ var CosmosEngine = class {
   dragIndex = null;
   /** Last hover reported by cosmos — fallback dragged-point source. */
   lastHoverIndex = null;
-  /** Live native link hover (review P1: gates the unified onClick's
+  /** Live native link hover gates the unified onClick's
    * background interpretation — a hovered link owns the click). */
   hoveredLinkIndex = null;
   // --- adapter-owned GATED overlay/activity clock (see module header) ---
@@ -143,7 +143,7 @@ var CosmosEngine = class {
   pendingTicks = 0;
   /** One-shot guard for the repulsionTheta deprecation diagnostic. */
   repulsionThetaWarned = false;
-  // --- WebGL context-loss recovery state (§13.1) ---
+  // --- WebGL context-loss recovery state ---
   /** cosmos' canvas (queried post-mount) carrying the webglcontext* listeners. */
   canvas = null;
   contextLost = false;
@@ -152,7 +152,7 @@ var CosmosEngine = class {
   deadline = null;
   /** Graph constructor cached at mount so recovery never re-imports cosmos. */
   cosmosCtor = null;
-  // --- §8 image atlas (capability pointImages) ---
+  // --- image atlas (capability pointImages) ---
   /**
    * slot → ImageData mirror of the cosmos image atlas. ImageData is CPU-side,
    * so the mirror survives context loss — any post-restore atlas commit
@@ -262,7 +262,7 @@ var CosmosEngine = class {
    * zoom — `setViewport(p)` then `getViewport()` returns p, modulo cosmos'
    * d3 scaleExtent clamp. A missing x or y is filled from the current
    * viewport; zoom-only calls keep the `setZoomLevel` path (d3's scaleTo
-   * preserves the current center). Instant unless `durationMs` is given —
+   * preserves the current center). Instant unless `durationMs` is given
    * cosmos' own default duration is 250 ms, which would animate context-
    * recovery replays.
    */
@@ -323,7 +323,7 @@ var CosmosEngine = class {
     });
     this.requestTicks(2);
   }
-  // --- spatial queries & pinning (§13/§15) ---
+  // --- spatial queries & pinning ---
   pointsInPolygon(screenPolygon) {
     const graph = this.activeGraph;
     if (!graph) return [];
@@ -361,7 +361,7 @@ var CosmosEngine = class {
     return graph ? Float32Array.from(graph.getPointPositions()) : null;
   }
   /**
-   * Captures the cosmos canvas via the M0 same-tick method (see module
+   * Captures the cosmos canvas via the same-tick method (see module
    * header): one rAF is scheduled and, inside that tick, the WebGL canvas is
    * drawn synchronously onto an offscreen 2D canvas (cosmos renders with
    * preserveDrawingBuffer:false, so the buffer is only readable same-tick).
@@ -428,13 +428,13 @@ var CosmosEngine = class {
   // --- gated overlay/activity clock (see module header) ---
   /**
    * One rAF tick of the gated activity clock. Ordering is load-bearing:
-   *  1. the tick budget is consumed BEFORE the host callback runs, so work
-   *     scheduled from inside onFrame re-arms a fresh tick instead of being
-   *     coalesced away;
-   *  2. the reschedule/stop decision is made BEFORE the host callback, so a
-   *     throwing host can never kill a should-keep-running clock (and a
-   *     stopping clock stays stopped even if the callback wakes it — the
-   *     wake starts a new loop via requestTicks/wake, not this handle).
+   * 1. the tick budget is consumed BEFORE the host callback runs, so work
+   * scheduled from inside onFrame re-arms a fresh tick instead of being
+   * coalesced away;
+   * 2. the reschedule/stop decision is made BEFORE the host callback, so a
+   * throwing host can never kill a should-keep-running clock (and a
+   * stopping clock stays stopped even if the callback wakes it — the
+   * wake starts a new loop via requestTicks/wake, not this handle).
    * Skips the callback (but keeps its schedule) while the document is hidden.
    */
   frameTick = (timeMs) => {
@@ -488,14 +488,14 @@ var CosmosEngine = class {
     this.runReasons.clear();
     this.pendingTicks = 0;
   }
-  // --- WebGL context-loss recovery (§13.1) ---
+  // --- WebGL context-loss recovery ---
   /** The graph, unless it is unusable (context lost / terminally failed). */
   get activeGraph() {
     return this.contextLost || this.failed ? null : this.graph;
   }
   /**
    * cosmos owns its canvas; we can only wire webglcontext* listeners after
-   * init by querying it. A missing canvas downgrades to an info diagnostic —
+   * init by querying it. A missing canvas downgrades to an info diagnostic
    * the engine keeps working, just without context-loss recovery.
    */
   attachContextListeners() {
@@ -617,31 +617,38 @@ var CosmosEngine = class {
    * later explicit directive (including `false`) replaces it.
    */
   queueCommit(update) {
+    const ownedUpdate = cloneCommitForQueue(update);
     const previous = this.pendingCommit;
     if (previous === null) {
-      this.pendingCommit = update;
+      this.pendingCommit = ownedUpdate;
       return;
     }
-    const merged = { revision: update.revision };
-    const structure = update.structure ?? previous.structure;
+    const merged = { revision: ownedUpdate.revision };
+    const structure = ownedUpdate.structure ?? previous.structure;
     if (structure !== void 0) merged.structure = structure;
-    if (previous.buffers !== void 0 || update.buffers !== void 0) {
-      merged.buffers = { ...previous.buffers, ...update.buffers };
+    if (previous.buffers !== void 0 || ownedUpdate.buffers !== void 0) {
+      merged.buffers = { ...previous.buffers, ...ownedUpdate.buffers };
     }
-    if (previous.config !== void 0 || update.config !== void 0) {
-      const config = { ...previous.config, ...update.config };
-      if (previous.config?.simulation !== void 0 || update.config?.simulation !== void 0) {
+    if (previous.bufferPatches !== void 0 || ownedUpdate.bufferPatches !== void 0) {
+      merged.bufferPatches = {
+        ...previous.bufferPatches,
+        ...ownedUpdate.bufferPatches
+      };
+    }
+    if (previous.config !== void 0 || ownedUpdate.config !== void 0) {
+      const config = { ...previous.config, ...ownedUpdate.config };
+      if (previous.config?.simulation !== void 0 || ownedUpdate.config?.simulation !== void 0) {
         config.simulation = {
           ...previous.config?.simulation,
-          ...update.config?.simulation
+          ...ownedUpdate.config?.simulation
         };
       }
       merged.config = config;
     }
-    if (previous.resources !== void 0 || update.resources !== void 0) {
-      merged.resources = mergeResources(previous.resources, update.resources);
+    if (previous.resources !== void 0 || ownedUpdate.resources !== void 0) {
+      merged.resources = mergeResources(previous.resources, ownedUpdate.resources);
     }
-    const restart = update.restart !== void 0 && update.restart !== false ? update.restart : previous.restart;
+    const restart = ownedUpdate.restart !== void 0 && ownedUpdate.restart !== false ? ownedUpdate.restart : previous.restart;
     if (restart !== void 0) merged.restart = restart;
     this.pendingCommit = merged;
   }
@@ -669,10 +676,10 @@ var CosmosEngine = class {
       // cosmos 3.4 defaults this to true. Pinned OFF for the 3.4 upgrade:
       // occlusion culling changes which overlapping pixels draw, and the M5
       // pixel-diff thresholds (CHANGED_MIN/RESTORED_MAX) were tuned against
-      // un-culled rendering. One variable at a time — flipping it is a
-      // registered follow-up with its own threshold re-validation.
+      // un-culled rendering. Keep one variable at a time; enabling culling
+      // requires its own threshold re-validation.
       pointOcclusionCulling: false,
-      // Native point dragging; the core owns pin semantics on top (§16.3).
+      // Native point dragging; the core owns pin semantics on top.
       enableDrag: this.options.enableDrag ?? true,
       onPointClick: (index, _position, event) => {
         this.events?.onPointClick?.(index, clickModifiers(event));
@@ -733,7 +740,7 @@ var CosmosEngine = class {
         this.requestTicks(2);
         this.emitViewportChange();
       },
-      // --- gated-clock run reasons (§17 stop-at-rest, ADR-005) ---
+      // --- gated-clock run reasons ---
       onSimulationStart: () => {
         this.wake("sim");
       },
@@ -833,8 +840,8 @@ var CosmosEngine = class {
     if (viewport) this.events?.onViewportChange?.(viewport);
   }
   /**
-   * One visibly atomic update (§13): all channels and config are staged, then
-   * exactly one render() draws them; restart reheats after the render.
+   * One visibly atomic update: all channels and config are staged, then
+   * exactly one render draws them; restart reheats after the render.
    */
   applyCommit(graph, update) {
     const { config, structure, buffers, resources, restart } = update;
@@ -909,17 +916,17 @@ var CosmosEngine = class {
     this.requestTicks(2);
   }
   /**
-   * Applies the §16.3 stage-4 cluster force (capability `clusterForce`).
+   * Applies the stage-4 cluster force (capability `clusterForce`).
    *
    * Contract mapping, verified against the 3.3.0 dist (`index.d.ts`):
-   *  - `pointClusters` (Float32Array, NaN = unclustered) →
-   *    `setPointClusters((number | undefined)[])`, where cosmos' documented
-   *    "does not belong to any cluster" value is `undefined`;
-   *  - `centers` (Float32Array, `[x0,y0,x1,y1,…]`) →
-   *    `setClusterPositions((number | undefined)[])`; a non-finite entry means
-   *    "no position" and cosmos falls back to that cluster's centermass;
-   *  - `null` clears: an all-`undefined` array of the CURRENT roster length
-   *    (length must track the roster) plus empty cluster positions.
+   * - `pointClusters` (Float32Array, NaN = unclustered) →
+   * `setPointClusters((number | undefined)[])`, where cosmos' documented
+   * "does not belong to any cluster" value is `undefined`;
+   * - `centers` (Float32Array, `[x0,y0,x1,y1,…]`) →
+   * `setClusterPositions((number | undefined)[])`; a non-finite entry means
+   * "no position" and cosmos falls back to that cluster's centermass;
+   * - `null` clears: an all-`undefined` array of the CURRENT roster length
+   * (length must track the roster) plus empty cluster positions.
    * `strength` is the scene-wide `simulationCluster` config coefficient
    * applied in the config block, not the per-point
    * `setPointClusterStrength` buffer (Orbit's strength is scene-wide).
@@ -948,12 +955,12 @@ var CosmosEngine = class {
     }
   }
   /**
-   * Applies the §8 image-atlas channel: upserts convert ImageBitmap →
+   * Applies the image-atlas channel: upserts convert ImageBitmap →
    * ImageData through an offscreen 2D canvas into the slot mirror, removals
    * blank their slot, and any atlas change re-uploads the FULL ImageData
    * array (cosmos' setImageData is whole-array only, matching
    * `rangeUpdates: []`). Environments without a usable 2D context (jsdom)
-   * no-op the channel and report `engine:image-channel-unavailable` once —
+   * no-op the channel and report `engine:image-channel-unavailable` once
    * never throw.
    */
   applyResources(graph, resources) {
@@ -999,7 +1006,7 @@ var CosmosEngine = class {
   /**
    * Reads an ImageData of the given size off an offscreen 2D canvas, drawing
    * `bitmap` onto it first when provided (ImageBitmap → ImageData transcode;
-   * without a bitmap: a transparent blank). Returns null — never throws —
+   * without a bitmap: a transparent blank). Returns null — never throws
    * where no 2D context exists (jsdom without the canvas package).
    */
   canvasImageData(width, height, bitmap) {
@@ -1028,7 +1035,7 @@ var CosmosEngine = class {
     });
   }
   /**
-   * Replaces NaN pairs (= "no known position", §7.3) with random points on a
+   * Replaces NaN pairs (= "no known position") with random points on a
    * ring of radius seedRadius around the space center. cosmos treats NaN
    * positions as *absent* points, so they must never reach setPointPositions.
    * Known positions pass through verbatim (same array when nothing to seed).
@@ -1055,6 +1062,98 @@ var CosmosEngine = class {
     return out;
   }
 };
+function cloneCommitForQueue(update) {
+  const owned = { revision: update.revision };
+  if (update.structure !== void 0) {
+    owned.structure = {
+      pointCount: update.structure.pointCount,
+      positions: update.structure.positions.slice(),
+      links: update.structure.links.slice()
+    };
+  }
+  if (update.buffers !== void 0) {
+    const buffers = {};
+    if (update.buffers.pointColor !== void 0) {
+      buffers.pointColor = update.buffers.pointColor.slice();
+    }
+    if (update.buffers.pointSize !== void 0) {
+      buffers.pointSize = update.buffers.pointSize.slice();
+    }
+    if (update.buffers.linkColor !== void 0) {
+      buffers.linkColor = update.buffers.linkColor.slice();
+    }
+    if (update.buffers.linkWidth !== void 0) {
+      buffers.linkWidth = update.buffers.linkWidth.slice();
+    }
+    owned.buffers = buffers;
+  }
+  if (update.bufferPatches !== void 0) {
+    const patches = {};
+    if (update.bufferPatches.pointColor !== void 0) {
+      patches.pointColor = update.bufferPatches.pointColor.map(({ start, data }) => ({
+        start,
+        data: data.slice()
+      }));
+    }
+    if (update.bufferPatches.pointSize !== void 0) {
+      patches.pointSize = update.bufferPatches.pointSize.map(({ start, data }) => ({
+        start,
+        data: data.slice()
+      }));
+    }
+    if (update.bufferPatches.linkColor !== void 0) {
+      patches.linkColor = update.bufferPatches.linkColor.map(({ start, data }) => ({
+        start,
+        data: data.slice()
+      }));
+    }
+    if (update.bufferPatches.linkWidth !== void 0) {
+      patches.linkWidth = update.bufferPatches.linkWidth.map(({ start, data }) => ({
+        start,
+        data: data.slice()
+      }));
+    }
+    owned.bufferPatches = patches;
+  }
+  if (update.config !== void 0) {
+    const config = { ...update.config };
+    if (update.config.simulation !== void 0) {
+      config.simulation = { ...update.config.simulation };
+    }
+    if (update.config.cluster !== void 0) {
+      config.cluster = update.config.cluster === null ? null : {
+        ...update.config.cluster,
+        pointClusters: update.config.cluster.pointClusters.slice(),
+        ...update.config.cluster.centers === void 0 ? {} : { centers: update.config.cluster.centers.slice() }
+      };
+    }
+    owned.config = config;
+  }
+  if (update.resources !== void 0) {
+    const resources = {};
+    if (update.resources.imageAtlas !== void 0) {
+      const imageAtlas = {};
+      if (update.resources.imageAtlas.upserts !== void 0) {
+        imageAtlas.upserts = update.resources.imageAtlas.upserts.map(({ slot, bitmap }) => ({
+          slot,
+          bitmap
+        }));
+      }
+      if (update.resources.imageAtlas.removeSlots !== void 0) {
+        imageAtlas.removeSlots = Array.from(update.resources.imageAtlas.removeSlots);
+      }
+      resources.imageAtlas = imageAtlas;
+    }
+    if (update.resources.pointImageIndex !== void 0) {
+      resources.pointImageIndex = update.resources.pointImageIndex.slice();
+    }
+    owned.resources = resources;
+  }
+  if (update.restart !== void 0) {
+    owned.restart = update.restart === false ? false : { alpha: update.restart.alpha };
+  }
+  return owned;
+}
 function mergeResources(previous, update) {
   const upsertBySlot = /* @__PURE__ */ new Map();
   const removes = /* @__PURE__ */ new Set();