@modernrelay/orbit-engine-cosmos 0.2.0

package/dist/index.js

@@ -0,0 +1,947 @@
+// src/restoreDeadline.ts
+var RestoreDeadline = class {
+  constructor(doc, ms, onExpire) {
+    this.doc = doc;
+    this.onExpire = onExpire;
+    this.remaining = ms;
+  }
+  doc;
+  onExpire;
+  timer = null;
+  /** Unspent budget in ms; recomputed each time the timer is disarmed. */
+  remaining;
+  /** Timestamp when the current timer was armed (for banking on hide). */
+  armedAt = 0;
+  started = false;
+  /** Terminal: set on expiry or cancel; guarantees onExpire fires at most once. */
+  done = false;
+  handleVisibilityChange = () => {
+    if (this.done) return;
+    if (this.doc.visibilityState === "visible") this.arm();
+    else this.disarm();
+  };
+  start() {
+    if (this.done || this.started) return;
+    this.started = true;
+    this.doc.addEventListener("visibilitychange", this.handleVisibilityChange);
+    if (this.doc.visibilityState === "visible") this.arm();
+  }
+  cancel() {
+    if (this.done) return;
+    this.done = true;
+    if (this.timer !== null) {
+      globalThis.clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.started) {
+      this.doc.removeEventListener("visibilitychange", this.handleVisibilityChange);
+    }
+  }
+  arm() {
+    if (this.timer !== null) return;
+    this.armedAt = Date.now();
+    this.timer = globalThis.setTimeout(() => {
+      this.timer = null;
+      this.done = true;
+      this.doc.removeEventListener("visibilitychange", this.handleVisibilityChange);
+      this.onExpire();
+    }, this.remaining);
+  }
+  disarm() {
+    if (this.timer === null) return;
+    globalThis.clearTimeout(this.timer);
+    this.timer = null;
+    this.remaining = Math.max(0, this.remaining - (Date.now() - this.armedAt));
+  }
+};
+
+// src/CosmosEngine.ts
+function clickModifiers(event) {
+  const e = event;
+  if (e && typeof e.metaKey === "boolean" && typeof e.shiftKey === "boolean") {
+    return { metaKey: e.metaKey, shiftKey: e.shiftKey };
+  }
+  return void 0;
+}
+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/
+    // onLinkMouseOver delivering correct link indices with ~4px perpendicular
+    // tolerance (docs/m0-conformance.json, `link-picking`).
+    linkPicking: true,
+    rangeUpdates: [],
+    trackedPositions: true,
+    simulation: true,
+    // §16.12: 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[]) +
+    // 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 —
+    // `setPointClusters((number|undefined)[])`, `setClusterPositions(
+    // (number|undefined)[])`, `setPointClusterStrength(Float32Array)`
+    // (index.d.ts) plus the `simulationCluster` coefficient (config.d.ts,
+    // default 0.1) and the `Clusters` core module (dist/modules/Clusters).
+    // `undefined` is cosmos' documented "not in any cluster" value, which the
+    // adapter maps from the contract's NaN.
+    clusterForce: true
+  };
+  options;
+  graph = null;
+  innerDiv = null;
+  events = null;
+  /**
+   * Pre-mount/lost-context commits collapse per channel and are applied as one
+   * atomic commit once a usable graph exists.
+   */
+  pendingCommit = null;
+  applied = null;
+  destroyed = false;
+  mounting = false;
+  /** Constructed graph whose `ready` promise has not settled yet. */
+  graphAwaitingReady = null;
+  /** Guards every graph teardown, including async init/recovery races. */
+  destroyedGraphs = /* @__PURE__ */ new WeakSet();
+  /** 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). */
+  lastPointCount = 0;
+  /**
+   * cosmos fires `onClick` (index undefined) AND `onBackgroundClick` for the
+   * same background click; remembering the MouseEvent dedupes the null emit.
+   */
+  lastNullClickEvent = null;
+  /** Point latched at cosmos onDragStart; cleared when the gesture ends. */
+  dragIndex = null;
+  /** Last hover reported by cosmos — fallback dragged-point source. */
+  lastHoverIndex = null;
+  // --- adapter-owned overlay/activity clock (see module header) ---
+  /** rAF id of the pending activity-clock tick; null = clock not running. */
+  frameHandle = null;
+  /** Window driving the clock, cached so stop works after the div detaches. */
+  frameWindow = null;
+  // --- WebGL context-loss recovery state (§13.1) ---
+  /** cosmos' canvas (queried post-mount) carrying the webglcontext* listeners. */
+  canvas = null;
+  contextLost = false;
+  /** Terminal: GL reinitialization failed; commits stash inertly forever. */
+  failed = false;
+  deadline = null;
+  /** Graph constructor cached at mount so recovery never re-imports cosmos. */
+  cosmosCtor = null;
+  // --- §8 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
+   * re-uploads the FULL array to the fresh graph. `null` = removed (blank).
+   */
+  imageSlots = [];
+  /** Lazily created 1×1 transparent entry filling removed/hole slots. */
+  blankImage = null;
+  /** One-shot guard for the `engine:image-channel-unavailable` diagnostic. */
+  imageChannelUnavailable = false;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  async mount(container, events) {
+    if (this.destroyed) throw new Error("CosmosEngine: mount() after destroy()");
+    if (this.mounting || this.graph) throw new Error("CosmosEngine: mount() may only be called once");
+    this.mounting = true;
+    this.events = events;
+    const div = container.ownerDocument.createElement("div");
+    div.style.width = "100%";
+    div.style.height = "100%";
+    container.appendChild(div);
+    this.innerDiv = div;
+    let graph = null;
+    try {
+      const { Graph } = await import('@cosmos.gl/graph');
+      if (this.destroyed) {
+        div.remove();
+        return;
+      }
+      graph = new Graph(div, this.buildInitialConfig());
+      this.graphAwaitingReady = graph;
+      await graph.ready;
+      if (this.graphAwaitingReady === graph) this.graphAwaitingReady = null;
+      if (this.destroyed) {
+        this.destroyGraphOnce(graph);
+        div.remove();
+        return;
+      }
+      this.graph = graph;
+      this.cosmosCtor = Graph;
+      this.attachContextListeners();
+      events.onDiagnostic?.({
+        code: "engine:overlay-activity-clock",
+        severity: "info",
+        message: "CosmosEngine: cosmos exposes no draw-phase hook (postDrawFrames:false); overlays ride an adapter-owned requestAnimationFrame activity clock and may lag the canvas by one frame."
+      });
+      this.startFrameLoop();
+      const pending = this.pendingCommit;
+      this.pendingCommit = null;
+      if (pending) this.applyCommit(graph, pending);
+    } catch (err) {
+      if (graph !== null) {
+        if (this.graph === graph) {
+          this.stopFrameLoop();
+          this.detachContextListeners();
+          this.graph = null;
+        }
+        if (this.graphAwaitingReady === graph) this.graphAwaitingReady = null;
+        this.destroyGraphOnce(graph);
+      }
+      div.remove();
+      if (this.innerDiv === div) this.innerDiv = null;
+      if (this.destroyed) return;
+      const error = err instanceof Error ? err : new Error(String(err));
+      events.onError?.(error);
+      throw error;
+    }
+  }
+  commit(update) {
+    if (this.destroyed) throw new Error("CosmosEngine: commit() after destroy()");
+    const graph = this.activeGraph;
+    if (!graph) {
+      this.queueCommit(update);
+      return;
+    }
+    this.applyCommit(graph, update);
+  }
+  appliedRevision() {
+    return this.applied;
+  }
+  // --- camera ---
+  fitView(opts) {
+    this.activeGraph?.fitView(opts?.durationMs, opts?.padding);
+  }
+  zoom(factor, durationMs) {
+    const graph = this.activeGraph;
+    if (!graph) return;
+    graph.setZoomLevel(graph.getZoomLevel() * factor, durationMs);
+  }
+  /**
+   * REAL pan (the former zoom-only limitation is lifted — see module header):
+   * when a target center is provided, one `setZoomTransformByPointPositions`
+   * call centers space point (x, y) at EXACTLY the requested (or current)
+   * 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 —
+   * cosmos' own default duration is 250 ms, which would animate context-
+   * recovery replays.
+   */
+  setViewport(v, opts) {
+    const graph = this.activeGraph;
+    if (!graph) return;
+    if (v.x !== void 0 || v.y !== void 0) {
+      const current = v.x === void 0 || v.y === void 0 ? this.getViewport() : null;
+      const x = v.x ?? current?.x;
+      const y = v.y ?? current?.y;
+      if (x !== void 0 && y !== void 0) {
+        graph.setZoomTransformByPointPositions(
+          Float32Array.of(x, y),
+          opts?.durationMs ?? 0,
+          v.zoom ?? graph.getZoomLevel()
+        );
+        return;
+      }
+    }
+    if (v.zoom !== void 0) graph.setZoomLevel(v.zoom, opts?.durationMs ?? 0);
+  }
+  getViewport() {
+    const graph = this.activeGraph;
+    const div = this.innerDiv;
+    if (!graph || !div) return null;
+    const [x, y] = graph.screenToSpacePosition([div.clientWidth / 2, div.clientHeight / 2]);
+    return { x, y, zoom: graph.getZoomLevel() };
+  }
+  zoomToIndex(index, durationMs) {
+    this.activeGraph?.zoomToPointByIndex(index, durationMs);
+  }
+  // --- simulation ---
+  start(alpha) {
+    this.activeGraph?.start(alpha);
+  }
+  pause() {
+    this.activeGraph?.pause();
+  }
+  // --- built-in interaction visuals ---
+  setSelectedIndices(indices) {
+    const graph = this.activeGraph;
+    if (!graph) return;
+    graph.setConfigPartial({
+      highlightedPointIndices: indices === null ? void 0 : Array.from(indices)
+    });
+  }
+  setFocusedIndex(index) {
+    const graph = this.activeGraph;
+    if (!graph) return;
+    graph.setConfigPartial({
+      focusedPointIndex: index === null ? void 0 : index
+    });
+  }
+  // --- spatial queries & pinning (§13/§15) ---
+  pointsInPolygon(screenPolygon) {
+    const graph = this.activeGraph;
+    if (!graph) return [];
+    return graph.findPointsInPolygon(screenPolygon.map(([x, y]) => [x, y]));
+  }
+  pointsInRect(screenRect) {
+    const graph = this.activeGraph;
+    if (!graph) return [];
+    const [x0, y0, x1, y1] = screenRect;
+    return graph.findPointsInRect([
+      [Math.min(x0, x1), Math.min(y0, y1)],
+      [Math.max(x0, x1), Math.max(y0, y1)]
+    ]);
+  }
+  neighborIndices(index) {
+    const graph = this.activeGraph;
+    if (!graph) return [];
+    return graph.getNeighboringPointIndices(index).filter((i) => i !== index);
+  }
+  screenToSpace(p) {
+    const graph = this.activeGraph;
+    return graph ? graph.screenToSpacePosition([p[0], p[1]]) : null;
+  }
+  spaceToScreen(p) {
+    const graph = this.activeGraph;
+    return graph ? graph.spaceToScreenPosition([p[0], p[1]]) : null;
+  }
+  setPinnedIndices(indices) {
+    this.activeGraph?.setPinnedPoints(indices === null ? null : Array.from(indices));
+  }
+  // --- readback ---
+  getPositions() {
+    const graph = this.activeGraph;
+    return graph ? Float32Array.from(graph.getPointPositions()) : null;
+  }
+  /**
+   * Captures the cosmos canvas via the M0 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).
+   * Resolves null on any failure or unusable lifecycle state (pre-mount,
+   * context lost/failed, destroyed, no 2D context, toBlob failure).
+   */
+  captureScreenshot() {
+    const canvas = this.activeGraph ? this.canvas : null;
+    const win = canvas?.ownerDocument.defaultView ?? null;
+    if (!canvas || !win || typeof win.requestAnimationFrame !== "function") {
+      return Promise.resolve(null);
+    }
+    return new Promise((resolve) => {
+      win.requestAnimationFrame(() => {
+        if (this.destroyed || !this.activeGraph || this.canvas !== canvas) {
+          resolve(null);
+          return;
+        }
+        try {
+          const off = canvas.ownerDocument.createElement("canvas");
+          off.width = canvas.width;
+          off.height = canvas.height;
+          const ctx = off.getContext("2d");
+          if (!ctx) {
+            resolve(null);
+            return;
+          }
+          ctx.drawImage(canvas, 0, 0);
+          off.toBlob((blob) => {
+            resolve(blob);
+          });
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+  }
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.stopFrameLoop();
+    this.deadline?.cancel();
+    this.deadline = null;
+    this.detachContextListeners();
+    const graph = this.graph;
+    this.graph = null;
+    this.destroyGraphOnce(graph);
+    const awaiting = this.graphAwaitingReady;
+    this.graphAwaitingReady = null;
+    this.destroyGraphOnce(awaiting);
+    this.innerDiv?.remove();
+    this.innerDiv = null;
+    this.events = null;
+    this.pendingCommit = null;
+    this.imageSlots = [];
+    this.blankImage = null;
+  }
+  // --- overlay/activity clock (see module header) ---
+  /**
+   * One rAF tick of the activity clock. Reschedules FIRST so a throwing host
+   * callback can never kill the clock; skips the callback (but keeps ticking)
+   * while the document is hidden. Deliberately cheap: a single callback
+   * invocation — the core skips all work when nothing subscribes.
+   */
+  frameTick = (timeMs) => {
+    const win = this.frameWindow;
+    if (!win || this.frameHandle === null) return;
+    this.frameHandle = win.requestAnimationFrame(this.frameTick);
+    if (!win.document.hidden) this.events?.onFrame?.(timeMs);
+  };
+  startFrameLoop() {
+    if (this.destroyed || this.frameHandle !== null) return;
+    const win = this.innerDiv?.ownerDocument.defaultView ?? null;
+    if (!win || typeof win.requestAnimationFrame !== "function") return;
+    this.frameWindow = win;
+    this.frameHandle = win.requestAnimationFrame(this.frameTick);
+  }
+  stopFrameLoop() {
+    if (this.frameHandle !== null) {
+      this.frameWindow?.cancelAnimationFrame(this.frameHandle);
+      this.frameHandle = null;
+    }
+    this.frameWindow = null;
+  }
+  // --- WebGL context-loss recovery (§13.1) ---
+  /** 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 —
+   * the engine keeps working, just without context-loss recovery.
+   */
+  attachContextListeners() {
+    const canvas = this.innerDiv?.querySelector("canvas") ?? null;
+    if (!canvas) {
+      this.events?.onDiagnostic?.({
+        code: "engine:context-listeners-unavailable",
+        severity: "info",
+        message: "CosmosEngine: no <canvas> found in the cosmos container; WebGL context-loss recovery is disabled."
+      });
+      return;
+    }
+    this.canvas = canvas;
+    canvas.addEventListener("webglcontextlost", this.handleContextLost);
+    canvas.addEventListener("webglcontextrestored", this.handleContextRestored);
+  }
+  detachContextListeners() {
+    const canvas = this.canvas;
+    if (!canvas) return;
+    canvas.removeEventListener("webglcontextlost", this.handleContextLost);
+    canvas.removeEventListener("webglcontextrestored", this.handleContextRestored);
+    this.canvas = null;
+  }
+  /** DOM listener: nothing may throw out of it. */
+  handleContextLost = (event) => {
+    try {
+      event.preventDefault();
+      if (this.destroyed || this.failed || this.contextLost) return;
+      this.contextLost = true;
+      this.stopFrameLoop();
+      this.dragIndex = null;
+      this.lastHoverIndex = null;
+      try {
+        this.graph?.pause();
+      } catch {
+      }
+      this.startRestoreDeadline();
+      this.events?.onContextEvent?.({ type: "lost" });
+    } catch {
+    }
+  };
+  /** DOM listener: nothing may throw out of it (async work is caught below). */
+  handleContextRestored = () => {
+    if (this.destroyed || this.failed || !this.contextLost) return;
+    this.reinitializeAfterRestore().catch((err) => {
+      if (this.destroyed) return;
+      this.failed = true;
+      const error = err instanceof Error ? err : new Error(String(err));
+      try {
+        this.events?.onContextEvent?.({ type: "failed", error });
+      } catch {
+      }
+    });
+  };
+  /**
+   * cosmos cannot reuse a restored context (its GPU resources are gone), so
+   * recovery = tear down the old Graph and build a fresh one in the same div,
+   * flush the stashed commit, and only then report `restored` — the core
+   * re-commits the full scene in response.
+   */
+  async reinitializeAfterRestore() {
+    this.deadline?.cancel();
+    this.deadline = null;
+    this.detachContextListeners();
+    const oldGraph = this.graph;
+    this.graph = null;
+    this.destroyGraphOnce(oldGraph);
+    const div = this.innerDiv;
+    const Ctor = this.cosmosCtor;
+    if (!div || !Ctor) return;
+    const graph = new Ctor(div, this.buildInitialConfig());
+    this.graphAwaitingReady = graph;
+    try {
+      await graph.ready;
+      if (this.graphAwaitingReady === graph) this.graphAwaitingReady = null;
+      if (this.destroyed) {
+        this.destroyGraphOnce(graph);
+        return;
+      }
+      this.graph = graph;
+      this.attachContextListeners();
+      this.contextLost = false;
+      this.startFrameLoop();
+      const pending = this.pendingCommit;
+      this.pendingCommit = null;
+      if (pending) this.applyCommit(graph, pending);
+      this.events?.onContextEvent?.({ type: "restored" });
+    } catch (err) {
+      if (this.graphAwaitingReady === graph) this.graphAwaitingReady = null;
+      this.stopFrameLoop();
+      if (this.graph === graph) {
+        this.detachContextListeners();
+        this.graph = null;
+      }
+      this.destroyGraphOnce(graph);
+      throw err;
+    }
+  }
+  startRestoreDeadline() {
+    const doc = this.canvas?.ownerDocument;
+    if (!doc) return;
+    const ms = this.options.restoreDeadlineMs ?? DEFAULT_RESTORE_DEADLINE_MS;
+    const deadline = new RestoreDeadline(doc, ms, () => {
+      this.deadline = null;
+      this.events?.onDiagnostic?.({
+        code: "engine:context-restore-deadline",
+        severity: "warning",
+        message: `CosmosEngine: WebGL context was not restored within ${ms}ms of visible time.`
+      });
+    });
+    this.deadline = deadline;
+    deadline.start();
+  }
+  // -------------------------------------------------------------------------
+  /**
+   * Coalesces partial commits without discarding independent channels. The
+   * newest call supplies the visible revision; structure is one atomic
+   * channel, buffers/config merge per field, and restart persists until a
+   * later explicit directive (including `false`) replaces it.
+   */
+  queueCommit(update) {
+    const previous = this.pendingCommit;
+    if (previous === null) {
+      this.pendingCommit = update;
+      return;
+    }
+    const merged = { revision: update.revision };
+    const structure = update.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.config !== void 0 || update.config !== void 0) {
+      const config = { ...previous.config, ...update.config };
+      if (previous.config?.simulation !== void 0 || update.config?.simulation !== void 0) {
+        config.simulation = {
+          ...previous.config?.simulation,
+          ...update.config?.simulation
+        };
+      }
+      merged.config = config;
+    }
+    if (previous.resources !== void 0 || update.resources !== void 0) {
+      merged.resources = mergeResources(previous.resources, update.resources);
+    }
+    const restart = update.restart !== void 0 && update.restart !== false ? update.restart : previous.restart;
+    if (restart !== void 0) merged.restart = restart;
+    this.pendingCommit = merged;
+  }
+  /** Invokes a graph's destructor at most once, even across async races. */
+  destroyGraphOnce(graph) {
+    if (graph === null || this.destroyedGraphs.has(graph)) return;
+    this.destroyedGraphs.add(graph);
+    try {
+      graph.destroy();
+    } catch {
+    }
+  }
+  get spaceSize() {
+    const fromInitial = this.options.initialConfig?.["spaceSize"];
+    if (typeof fromInitial === "number") return fromInitial;
+    return this.options.spaceSize ?? DEFAULT_SPACE_SIZE;
+  }
+  get seedRadius() {
+    return this.seedRadiusOverride ?? this.options.seedRadius ?? this.spaceSize / 4;
+  }
+  buildInitialConfig() {
+    const base = {
+      // Default false: the core owns the camera (fitView is driven explicitly).
+      fitViewOnInit: this.options.fitViewOnInit ?? false,
+      // Native point dragging; the core owns pin semantics on top (§16.3).
+      enableDrag: this.options.enableDrag ?? true,
+      onPointClick: (index, _position, event) => {
+        this.events?.onPointClick?.(index, clickModifiers(event));
+      },
+      onBackgroundClick: (event) => {
+        this.emitNullPointClick(event);
+      },
+      // onClick fires for every canvas click; an undefined index means no
+      // point was hit (background clicks — link clicks arrive via onLinkClick).
+      onClick: (index, _position, event) => {
+        if (index === void 0) this.emitNullPointClick(event);
+      },
+      // Unified context-menu channel: fires exactly once per gesture (desktop
+      // right-click AND touch long-press — cosmos synthesizes the latter);
+      // the per-target onPoint/onLink/onBackgroundContextMenu callbacks fire
+      // ADDITIONALLY for the same gesture, so only this one is wired (see
+      // module header). index undefined = background (or a link).
+      onContextMenu: (index, _position, event) => {
+        this.handleContextMenu(index, event);
+      },
+      onPointMouseOver: (index) => {
+        this.lastHoverIndex = index;
+        this.events?.onPointHover?.(index);
+      },
+      onPointMouseOut: () => {
+        this.lastHoverIndex = null;
+        this.events?.onPointHover?.(null);
+      },
+      // Setting any onLink* callback enables cosmos' native link hit-testing.
+      onLinkClick: (linkIndex) => {
+        this.events?.onLinkClick?.(linkIndex);
+      },
+      onLinkMouseOver: (linkIndex) => {
+        this.events?.onLinkHover?.(linkIndex);
+      },
+      onLinkMouseOut: () => {
+        this.events?.onLinkHover?.(null);
+      },
+      onDragStart: () => {
+        this.handleDragStart();
+      },
+      onDragEnd: (e) => {
+        this.handleDragEnd(e);
+      },
+      onZoom: () => {
+        this.emitViewportChange();
+      },
+      onZoomEnd: () => {
+        this.emitViewportChange();
+      },
+      onSimulationEnd: () => {
+        this.events?.onSimulationEnd?.();
+      }
+    };
+    if (this.options.spaceSize !== void 0) base.spaceSize = this.options.spaceSize;
+    return { ...base, ...this.options.initialConfig };
+  }
+  /**
+   * Maps cosmos' unified context-menu callback to the host event: index
+   * undefined → null (background), MouseEvent client coords → container-
+   * relative CSS px (the inner div fills the host container exactly). The
+   * native event is preventDefault-ed so the browser menu never opens — but
+   * only when the host actually registered onContextMenu (it always does in
+   * Orbit: the core owns the typed 'contextMenu' event channel). cosmos'
+   * desktop `contextmenu` handler already prevents the event itself; repeating
+   * it is an idempotent no-op that also covers the touch long-press path
+   * (where cosmos forwards the originating pointerdown event instead).
+   */
+  handleContextMenu(index, event) {
+    const events = this.events;
+    if (!events?.onContextMenu) return;
+    if (typeof event.preventDefault === "function") event.preventDefault();
+    const div = this.innerDiv;
+    if (!div) return;
+    const rect = div.getBoundingClientRect();
+    events.onContextMenu(index ?? null, [event.clientX - rect.left, event.clientY - rect.top]);
+  }
+  /** Emits onPointClick(null) once per originating click event. */
+  emitNullPointClick(event) {
+    if (event != null && event === this.lastNullClickEvent) return;
+    this.lastNullClickEvent = event ?? null;
+    this.events?.onPointClick?.(null, clickModifiers(event));
+  }
+  /**
+   * The D3 drag event carries no point index; cosmos assigns
+   * `store.draggingPointIndex` right before invoking onDragStart (see module
+   * header). The public onPointMouseOver stream is the fallback — cosmos only
+   * starts a drag while a point is hovered.
+   */
+  readDraggingIndex() {
+    const store = this.graph?.store;
+    return store?.draggingPointIndex ?? store?.hoveredPoint?.index ?? this.lastHoverIndex;
+  }
+  handleDragStart() {
+    const index = this.readDraggingIndex();
+    if (index === null) return;
+    this.dragIndex = index;
+    this.events?.onDragStart?.(index);
+  }
+  /**
+   * Reports the dragged point's final SPACE position. cosmos' drag shader
+   * pins the point to the mouse's space position every frame, so converting
+   * the event's screen coords is exact and O(1) (see module header).
+   */
+  handleDragEnd(e) {
+    const index = this.dragIndex;
+    this.dragIndex = null;
+    if (index === null) return;
+    const graph = this.activeGraph;
+    if (!graph) return;
+    const [x, y] = graph.screenToSpacePosition([e.x, e.y]);
+    this.events?.onDragEnd?.(index, x, y);
+  }
+  emitViewportChange() {
+    const viewport = this.getViewport();
+    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.
+   */
+  applyCommit(graph, update) {
+    const { config, structure, buffers, resources, restart } = update;
+    if (config) {
+      if (config.seedRadius !== void 0) this.seedRadiusOverride = config.seedRadius;
+      const partial = {};
+      if (config.backgroundColor !== void 0) partial.backgroundColor = config.backgroundColor;
+      if (config.linkArrows !== void 0) partial.linkDefaultArrows = config.linkArrows;
+      if (config.renderLinks !== void 0) partial.renderLinks = config.renderLinks;
+      if (config.defaultPointColor !== void 0) {
+        partial.pointDefaultColor = config.defaultPointColor;
+      }
+      if (config.defaultLinkColor !== void 0) {
+        partial.linkDefaultColor = config.defaultLinkColor;
+      }
+      const sim = config.simulation;
+      if (sim) {
+        if (sim.gravity !== void 0) partial.simulationGravity = sim.gravity;
+        if (sim.repulsion !== void 0) partial.simulationRepulsion = sim.repulsion;
+        if (sim.friction !== void 0) partial.simulationFriction = sim.friction;
+        if (sim.linkDistance !== void 0) partial.simulationLinkDistance = sim.linkDistance;
+        if (sim.linkSpring !== void 0) partial.simulationLinkSpring = sim.linkSpring;
+        if (sim.decay !== void 0) partial.simulationDecay = sim.decay;
+        if (sim.collision !== void 0) partial.simulationCollision = sim.collision;
+        if (sim.collisionRadius !== void 0) {
+          partial.simulationCollisionRadius = sim.collisionRadius;
+        }
+        if (sim.collisionPadding !== void 0) {
+          partial.simulationCollisionPadding = sim.collisionPadding;
+        }
+        if (sim.repulsionTheta !== void 0) {
+          partial.simulationRepulsionTheta = sim.repulsionTheta;
+        }
+        if (sim.center !== void 0) partial.simulationCenter = sim.center;
+        if (sim.repulsionFromMouse !== void 0) {
+          partial.simulationRepulsionFromMouse = sim.repulsionFromMouse;
+        }
+      }
+      if (config.cluster != null && config.cluster.strength !== void 0) {
+        partial.simulationCluster = config.cluster.strength;
+      }
+      if (Object.keys(partial).length > 0) graph.setConfigPartial(partial);
+    }
+    if (structure) {
+      this.lastPointCount = structure.pointCount;
+      graph.setPointPositions(this.withSeededPositions(structure.positions));
+      graph.setLinks(Float32Array.from(structure.links));
+    }
+    if (config && config.cluster !== void 0) this.applyClusterForce(graph, config.cluster);
+    if (buffers) {
+      if (buffers.pointColor) graph.setPointColors(buffers.pointColor);
+      if (buffers.pointSize) graph.setPointSizes(buffers.pointSize);
+      if (buffers.linkColor) graph.setLinkColors(buffers.linkColor);
+      if (buffers.linkWidth) graph.setLinkWidths(buffers.linkWidth);
+    }
+    if (resources) this.applyResources(graph, resources);
+    graph.render();
+    this.applied = update.revision;
+    if (restart) graph.start(restart.alpha);
+  }
+  /**
+   * Applies the §16.3 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.
+   * `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).
+   */
+  applyClusterForce(graph, cluster) {
+    if (cluster == null) {
+      graph.setPointClusters(new Array(this.lastPointCount).fill(void 0));
+      graph.setClusterPositions([]);
+      return;
+    }
+    const source = cluster.pointClusters;
+    const assignments = new Array(source.length);
+    for (let i = 0; i < source.length; i++) {
+      const value = source[i];
+      assignments[i] = Number.isFinite(value) ? value : void 0;
+    }
+    graph.setPointClusters(assignments);
+    const centers = cluster.centers;
+    if (centers !== void 0) {
+      const positions = new Array(centers.length);
+      for (let i = 0; i < centers.length; i++) {
+        const value = centers[i];
+        positions[i] = Number.isFinite(value) ? value : void 0;
+      }
+      graph.setClusterPositions(positions);
+    }
+  }
+  /**
+   * Applies the §8 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 —
+   * never throw.
+   */
+  applyResources(graph, resources) {
+    const atlas = resources.imageAtlas;
+    if (atlas) {
+      let dirty = false;
+      let conversionFailed = false;
+      if (atlas.upserts) {
+        for (const { slot, bitmap } of atlas.upserts) {
+          if (!Number.isInteger(slot) || slot < 0) continue;
+          const data = this.canvasImageData(bitmap.width, bitmap.height, bitmap);
+          if (data === null) {
+            conversionFailed = true;
+            continue;
+          }
+          while (this.imageSlots.length <= slot) this.imageSlots.push(null);
+          this.imageSlots[slot] = data;
+          dirty = true;
+        }
+      }
+      if (atlas.removeSlots) {
+        for (const slot of atlas.removeSlots) {
+          if (slot >= 0 && slot < this.imageSlots.length && this.imageSlots[slot] != null) {
+            this.imageSlots[slot] = null;
+            dirty = true;
+          }
+        }
+      }
+      if (conversionFailed) this.reportImageChannelUnavailable();
+      if (dirty) {
+        const blank = this.blankImage ?? (this.blankImage = this.canvasImageData(1, 1));
+        if (blank === null) {
+          this.reportImageChannelUnavailable();
+        } else {
+          graph.setImageData(Array.from(this.imageSlots, (d) => d ?? blank));
+        }
+      }
+    }
+    if (resources.pointImageIndex && !this.imageChannelUnavailable) {
+      graph.setPointImageIndices(resources.pointImageIndex);
+    }
+  }
+  /**
+   * 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 —
+   * where no 2D context exists (jsdom without the canvas package).
+   */
+  canvasImageData(width, height, bitmap) {
+    const doc = this.innerDiv?.ownerDocument;
+    if (!doc || !(width > 0) || !(height > 0)) return null;
+    try {
+      const canvas = doc.createElement("canvas");
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext("2d");
+      if (!ctx) return null;
+      if (bitmap) ctx.drawImage(bitmap, 0, 0);
+      return ctx.getImageData(0, 0, width, height);
+    } catch {
+      return null;
+    }
+  }
+  /** Documented degradation, reported at most once per engine instance. */
+  reportImageChannelUnavailable() {
+    if (this.imageChannelUnavailable) return;
+    this.imageChannelUnavailable = true;
+    this.events?.onDiagnostic?.({
+      code: "engine:image-channel-unavailable",
+      severity: "warning",
+      message: "CosmosEngine: no 2D canvas context is available to convert ImageBitmap atlas entries to ImageData; point images are disabled in this environment."
+    });
+  }
+  /**
+   * Replaces NaN pairs (= "no known position", §7.3) 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).
+   */
+  withSeededPositions(positions) {
+    let needsSeeding = false;
+    for (let i = 0; i < positions.length; i += 2) {
+      if (Number.isNaN(positions[i]) || Number.isNaN(positions[i + 1])) {
+        needsSeeding = true;
+        break;
+      }
+    }
+    if (!needsSeeding) return positions;
+    const out = Float32Array.from(positions);
+    const center = this.spaceSize / 2;
+    const radius = this.seedRadius;
+    for (let i = 0; i < out.length; i += 2) {
+      if (Number.isNaN(out[i]) || Number.isNaN(out[i + 1])) {
+        const angle = Math.random() * Math.PI * 2;
+        out[i] = center + radius * Math.cos(angle);
+        out[i + 1] = center + radius * Math.sin(angle);
+      }
+    }
+    return out;
+  }
+};
+function mergeResources(previous, update) {
+  const upsertBySlot = /* @__PURE__ */ new Map();
+  const removes = /* @__PURE__ */ new Set();
+  for (const atlas of [previous?.imageAtlas, update?.imageAtlas]) {
+    if (!atlas) continue;
+    for (const { slot, bitmap } of atlas.upserts ?? []) {
+      upsertBySlot.set(slot, bitmap);
+      removes.delete(slot);
+    }
+    for (const slot of atlas.removeSlots ?? []) {
+      upsertBySlot.delete(slot);
+      removes.add(slot);
+    }
+  }
+  const merged = {};
+  if (upsertBySlot.size > 0 || removes.size > 0) {
+    const imageAtlas = {};
+    if (upsertBySlot.size > 0) {
+      imageAtlas.upserts = Array.from(upsertBySlot, ([slot, bitmap]) => ({ slot, bitmap }));
+    }
+    if (removes.size > 0) imageAtlas.removeSlots = Array.from(removes);
+    merged.imageAtlas = imageAtlas;
+  }
+  const pointImageIndex = update?.pointImageIndex ?? previous?.pointImageIndex;
+  if (pointImageIndex !== void 0) merged.pointImageIndex = pointImageIndex;
+  return merged;
+}
+
+export { CosmosEngine };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map