@invana/graph-layout-d3-force 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+import { Layout } from '@invana/canvas';
+import { GraphNode, GraphLayer } from '@invana/graph';
+
+/**
+ * `D3ForceLayout` options. Every field maps 1:1 to a d3-force setter
+ * documented at https://d3js.org/d3-force.
+ *
+ * **All options default to `undefined`.** A force is only added to the
+ * simulation when its option is provided. A setter is only called when
+ * its sub-option is provided. Anything omitted falls through to
+ * d3-force's own defaults — or, for forces themselves, is not added at
+ * all.
+ *
+ * @example
+ * new D3ForceLayout({
+ *   charge: {},                       // adds forceManyBody at d3 defaults
+ *   link: { distance: 80 },           // adds forceLink, override distance
+ *   center: { x: 0, y: 0 },           // adds forceCenter at (0, 0)
+ *   // no `collide` → no collision force
+ *   // no `alphaDecay` → d3 default decay rate
+ * });
+ */
+interface D3ForceLayoutOptions {
+    /**
+     * When `true` (default), positions are written back to the store on
+     * every d3-force tick — the renderer animates the simulation as it
+     * settles.
+     *
+     * When `false`, per-tick writeback is suppressed and positions are
+     * flushed to the store exactly once when the simulation settles
+     * (`sim.on('end')`). The simulation still runs to completion; only the
+     * mirrored renderer updates are skipped. For large graphs (thousands
+     * of nodes / tens of thousands of edges) this avoids the ~hundreds of
+     * intermediate `setPositionsBulk` → `node:update` → renderer storms
+     * that dominate cost — the run finishes noticeably faster and the
+     * viewer just sees the settled picture appear.
+     *
+     * Lifecycle `tick` events are still emitted in both modes — only the
+     * store writeback is gated.
+     *
+     * Default `true`.
+     */
+    animate?: boolean;
+    /** `simulation.alpha(alpha)`. */
+    alpha?: number;
+    /** `simulation.alphaMin(min)`. */
+    alphaMin?: number;
+    /** `simulation.alphaDecay(decay)`. */
+    alphaDecay?: number;
+    /** `simulation.alphaTarget(target)`. */
+    alphaTarget?: number;
+    /** `simulation.velocityDecay(decay)`. */
+    velocityDecay?: number;
+    /** `forceLink` — pulls connected nodes toward a target distance. */
+    link?: LinkForceOptions;
+    /** `forceManyBody` — n-body charge (negative = repulsion). */
+    charge?: ChargeForceOptions;
+    /** `forceCenter` — translates the cluster's centroid to `(x, y)`. */
+    center?: CenterForceOptions;
+    /** `forceCollide` — prevents overlap. */
+    collide?: CollideForceOptions;
+    /** `forceX` — positioning force along x. */
+    x?: PositionXForceOptions;
+    /** `forceY` — positioning force along y. */
+    y?: PositionYForceOptions;
+    /** `forceRadial` — pulls toward a circle of given radius. Requires `radius`. */
+    radial?: RadialForceOptions;
+}
+/** `forceLink` configuration. */
+interface LinkForceOptions {
+    /** `link.distance(d)`. */
+    distance?: number;
+    /** `link.strength(s)`. */
+    strength?: number;
+    /** `link.iterations(n)`. */
+    iterations?: number;
+}
+/** `forceManyBody` configuration. */
+interface ChargeForceOptions {
+    /** `manyBody.strength(s)` — negative repels, positive attracts. */
+    strength?: number;
+    /** `manyBody.theta(θ)` — Barnes–Hut accuracy threshold. */
+    theta?: number;
+    /** `manyBody.distanceMin(d)`. */
+    distanceMin?: number;
+    /** `manyBody.distanceMax(d)`. */
+    distanceMax?: number;
+}
+/** `forceCenter` configuration. */
+interface CenterForceOptions {
+    /** `center.x(x)`. */
+    x?: number;
+    /** `center.y(y)`. */
+    y?: number;
+    /** `center.strength(s)`. */
+    strength?: number;
+}
+/** `forceCollide` configuration. */
+interface CollideForceOptions {
+    /**
+     * `collide.radius(r)`. Either a constant, or a per-node function called
+     * once per node at `apply()` time with the underlying `GraphNode`. Use
+     * the function form when collision sizes vary per node (e.g. read
+     * `node.data.size`).
+     */
+    radius?: number | ((node: GraphNode) => number);
+    /** `collide.strength(s)` in `[0, 1]`. */
+    strength?: number;
+    /** `collide.iterations(n)`. */
+    iterations?: number;
+}
+/** `forceX` configuration. */
+interface PositionXForceOptions {
+    /** `forceX.x(x)`. */
+    x?: number;
+    /** `forceX.strength(s)`. */
+    strength?: number;
+}
+/** `forceY` configuration. */
+interface PositionYForceOptions {
+    /** `forceY.y(y)`. */
+    y?: number;
+    /** `forceY.strength(s)`. */
+    strength?: number;
+}
+/** `forceRadial` configuration. `radius` is required. */
+interface RadialForceOptions {
+    /** Target circle radius. */
+    radius: number;
+    /** Circle center x. */
+    x?: number;
+    /** Circle center y. */
+    y?: number;
+    /** `radial.strength(s)`. */
+    strength?: number;
+}
+
+/**
+ * `D3ForceLayout` — d3-force-directed `Layout` for `@invana/graph`.
+ *
+ * The flow is intentionally tiny:
+ *   1. Snapshot nodes + edges from `layer.store` into d3-force datums.
+ *   2. Build a simulation. d3 owns the tick loop.
+ *   3. On each tick, bulk-write positions back to the store; the store
+ *      emits `node:update` events and the renderer reacts on its own.
+ *   4. Listen to external `node:update` (e.g. a drag) and mirror new
+ *      positions onto the sim, reheating α so neighbours readjust.
+ *
+ * Every option defaults to `undefined`. A force is only added when its
+ * option is provided; a setter is only called when its sub-option is
+ * provided. d3-force's own defaults apply otherwise. See `./types`.
+ *
+ * @example
+ * const layout = new D3ForceLayout({
+ *   charge: { strength: -300 },
+ *   link: { distance: 80 },
+ *   center: { x: 0, y: 0 },
+ * });
+ * await layout.apply(graphLayer);
+ */
+
+declare class D3ForceLayout extends Layout<GraphLayer> {
+    private readonly opts;
+    private sim;
+    private nodes;
+    private ids;
+    private nodeById;
+    /** GraphNode snapshot indexed by id — used by per-node force callbacks
+     *  (e.g. `collide.radius(d => ...)`) without coupling SimNode to GraphNode. */
+    private graphNodeById;
+    /** Ids of nodes whose `GraphNode.pinned === true` — permanent pins from
+     *  user data. Driven via d3-force's `fx/fy` so the simulation keeps them
+     *  fixed. Live: pin/unpin patches on `node:update` add/remove entries. */
+    private pinnedIds;
+    /** Ids of nodes currently being dragged by a user behaviour. Populated
+     *  on `node:drag-start` from the layer, drained on `node:drag-end`. While
+     *  an id is in this set, position updates mirror onto `fx/fy` so the
+     *  simulation can't push the node away from the cursor. On drag-end the
+     *  transient `fx/fy` clears (unless the node is also in `pinnedIds`,
+     *  which is the permanent-pin path). Decoupled from `pinned` so a drag
+     *  never mutates user-data semantics — pin-on-release is opt-in via a
+     *  separate behaviour. */
+    private draggedIds;
+    private buffer;
+    /** True while our own bulk write is in-flight, so the `node:update`
+     *  events it triggers don't bounce back into the sim. Relies on the
+     *  store's default sync flush firing events inside the bulk call. */
+    private writing;
+    private unsubscribe;
+    private offDragStart;
+    private offDragEnd;
+    /** True while a run is active. Guards `stop()` so it only emits `end`
+     *  once per run, even if called externally after a natural settle. */
+    private running;
+    constructor(opts?: D3ForceLayoutOptions);
+    /**
+     * Run the layout against `layer`. Resolves when the simulation settles
+     * naturally OR is cancelled via `stop()` / a second `apply()` call.
+     * Lifecycle events (`start` / `tick` / `end`) fire around the run.
+     */
+    apply(layer: GraphLayer): Promise<void>;
+    /** Cancel an in-flight run. Positions stay in the store. No-op when idle. */
+    stop(): void;
+    private configureForces;
+    private configureSimulation;
+    private writeBack;
+}
+
+export { type CenterForceOptions, type ChargeForceOptions, type CollideForceOptions, D3ForceLayout, type D3ForceLayoutOptions, type LinkForceOptions, type PositionXForceOptions, type PositionYForceOptions, type RadialForceOptions };

package/dist/index.js

@@ -0,0 +1,255 @@
+import { forceSimulation, forceLink, forceManyBody, forceCenter, forceCollide, forceX, forceY, forceRadial } from 'd3-force';
+import { Layout } from '@invana/canvas';
+
+// src/D3ForceLayout.ts
+var REHEAT_ALPHA = 0.3;
+var D3ForceLayout = class extends Layout {
+  opts;
+  sim = null;
+  nodes = [];
+  ids = [];
+  nodeById = /* @__PURE__ */ new Map();
+  /** GraphNode snapshot indexed by id — used by per-node force callbacks
+   *  (e.g. `collide.radius(d => ...)`) without coupling SimNode to GraphNode. */
+  graphNodeById = /* @__PURE__ */ new Map();
+  /** Ids of nodes whose `GraphNode.pinned === true` — permanent pins from
+   *  user data. Driven via d3-force's `fx/fy` so the simulation keeps them
+   *  fixed. Live: pin/unpin patches on `node:update` add/remove entries. */
+  pinnedIds = /* @__PURE__ */ new Set();
+  /** Ids of nodes currently being dragged by a user behaviour. Populated
+   *  on `node:drag-start` from the layer, drained on `node:drag-end`. While
+   *  an id is in this set, position updates mirror onto `fx/fy` so the
+   *  simulation can't push the node away from the cursor. On drag-end the
+   *  transient `fx/fy` clears (unless the node is also in `pinnedIds`,
+   *  which is the permanent-pin path). Decoupled from `pinned` so a drag
+   *  never mutates user-data semantics — pin-on-release is opt-in via a
+   *  separate behaviour. */
+  draggedIds = /* @__PURE__ */ new Set();
+  buffer = new Float32Array(0);
+  /** True while our own bulk write is in-flight, so the `node:update`
+   *  events it triggers don't bounce back into the sim. Relies on the
+   *  store's default sync flush firing events inside the bulk call. */
+  writing = false;
+  unsubscribe = null;
+  offDragStart = null;
+  offDragEnd = null;
+  /** True while a run is active. Guards `stop()` so it only emits `end`
+   *  once per run, even if called externally after a natural settle. */
+  running = false;
+  constructor(opts = {}) {
+    super();
+    this.opts = opts;
+  }
+  /**
+   * Run the layout against `layer`. Resolves when the simulation settles
+   * naturally OR is cancelled via `stop()` / a second `apply()` call.
+   * Lifecycle events (`start` / `tick` / `end`) fire around the run.
+   */
+  async apply(layer) {
+    this.stop();
+    const store = layer.store;
+    this.nodes = [];
+    this.ids = [];
+    this.nodeById.clear();
+    this.graphNodeById.clear();
+    this.pinnedIds.clear();
+    this.draggedIds.clear();
+    for (const n of store.nodes()) {
+      const pos = store.getPosition(n.id);
+      const node = { id: n.id };
+      if (n.pinned) {
+        const px = pos?.x ?? 0;
+        const py = pos?.y ?? 0;
+        node.fx = px;
+        node.fy = py;
+        node.x = px;
+        node.y = py;
+        this.pinnedIds.add(n.id);
+      } else if (pos && (pos.x !== 0 || pos.y !== 0)) {
+        node.x = pos.x;
+        node.y = pos.y;
+      }
+      this.nodes.push(node);
+      this.ids.push(n.id);
+      this.nodeById.set(n.id, node);
+      this.graphNodeById.set(n.id, n);
+    }
+    if (this.nodes.length === 0) return;
+    this.buffer = new Float32Array(this.nodes.length * 2);
+    const links = [];
+    for (const e of store.edges()) {
+      links.push({ source: e.source, target: e.target });
+    }
+    const sim = forceSimulation(this.nodes);
+    this.configureForces(sim, links);
+    this.configureSimulation(sim);
+    this.sim = sim;
+    const animate = this.opts.animate ?? true;
+    sim.on("tick", () => {
+      if (animate) this.writeBack(store);
+      this.events.emit("tick", {});
+    });
+    this.unsubscribe = store.events.on("node:update", ({ nodeId, patch }) => {
+      if (this.writing) return;
+      const node = this.nodeById.get(nodeId);
+      if (!node) return;
+      if ("pinned" in patch) {
+        if (patch.pinned) this.pinnedIds.add(nodeId);
+        else this.pinnedIds.delete(nodeId);
+      }
+      if (!patch.position) return;
+      const locked = this.pinnedIds.has(nodeId) || this.draggedIds.has(nodeId);
+      if (locked) {
+        node.fx = patch.position.x;
+        node.fy = patch.position.y;
+        node.x = patch.position.x;
+        node.y = patch.position.y;
+      } else {
+        if (node.fx !== void 0) node.fx = void 0;
+        if (node.fy !== void 0) node.fy = void 0;
+        node.x = patch.position.x;
+        node.y = patch.position.y;
+      }
+      if (sim.alpha() < REHEAT_ALPHA) sim.alpha(REHEAT_ALPHA).restart();
+    });
+    this.offDragStart = layer.events.on("node:drag-start", ({ nodeId, nodeIds }) => {
+      for (const id of nodeIds ?? [nodeId]) {
+        const node = this.nodeById.get(id);
+        if (!node) continue;
+        this.draggedIds.add(id);
+        const pos = store.getNode(id)?.position;
+        if (pos) {
+          node.fx = pos.x;
+          node.fy = pos.y;
+          node.x = pos.x;
+          node.y = pos.y;
+        }
+      }
+      if (sim.alpha() < REHEAT_ALPHA) sim.alpha(REHEAT_ALPHA).restart();
+    });
+    this.offDragEnd = layer.events.on("node:drag-end", ({ nodeId, nodeIds }) => {
+      for (const id of nodeIds ?? [nodeId]) {
+        this.draggedIds.delete(id);
+        const node = this.nodeById.get(id);
+        if (!node) continue;
+        if (!this.pinnedIds.has(id)) {
+          node.fx = void 0;
+          node.fy = void 0;
+        }
+      }
+    });
+    this.running = true;
+    this.events.emit("start", {});
+    return new Promise((resolve) => {
+      sim.on("end", () => {
+        if (this.running) {
+          if (!animate) this.writeBack(store);
+          this.running = false;
+          this.events.emit("end", { reason: "completed" });
+        }
+        resolve();
+      });
+    });
+  }
+  /** Cancel an in-flight run. Positions stay in the store. No-op when idle. */
+  stop() {
+    const wasRunning = this.running;
+    this.running = false;
+    this.sim?.stop();
+    this.sim = null;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.offDragStart?.();
+    this.offDragStart = null;
+    this.offDragEnd?.();
+    this.offDragEnd = null;
+    this.nodes = [];
+    this.ids = [];
+    this.nodeById.clear();
+    this.graphNodeById.clear();
+    this.pinnedIds.clear();
+    this.draggedIds.clear();
+    if (wasRunning) this.events.emit("end", { reason: "stopped" });
+  }
+  // ─── Configuration ─────────────────────────────────────────────────────
+  configureForces(sim, links) {
+    const { link, charge, center, collide, x, y, radial } = this.opts;
+    if (link !== void 0) {
+      const force = forceLink(links).id((d) => d.id);
+      if (link.distance !== void 0) force.distance(link.distance);
+      if (link.strength !== void 0) force.strength(link.strength);
+      if (link.iterations !== void 0) force.iterations(link.iterations);
+      sim.force("link", force);
+    }
+    if (charge !== void 0) {
+      const force = forceManyBody();
+      if (charge.strength !== void 0) force.strength(charge.strength);
+      if (charge.theta !== void 0) force.theta(charge.theta);
+      if (charge.distanceMin !== void 0) force.distanceMin(charge.distanceMin);
+      if (charge.distanceMax !== void 0) force.distanceMax(charge.distanceMax);
+      sim.force("charge", force);
+    }
+    if (center !== void 0) {
+      const force = forceCenter(center.x ?? 0, center.y ?? 0);
+      if (center.strength !== void 0) force.strength(center.strength);
+      sim.force("center", force);
+    }
+    if (collide !== void 0) {
+      const force = forceCollide();
+      if (collide.radius !== void 0) {
+        if (typeof collide.radius === "function") {
+          const fn = collide.radius;
+          const refs = this.graphNodeById;
+          force.radius((d) => {
+            const node = refs.get(d.id);
+            return node ? fn(node) : 0;
+          });
+        } else {
+          force.radius(collide.radius);
+        }
+      }
+      if (collide.strength !== void 0) force.strength(collide.strength);
+      if (collide.iterations !== void 0) force.iterations(collide.iterations);
+      sim.force("collide", force);
+    }
+    if (x !== void 0) {
+      const force = forceX();
+      if (x.x !== void 0) force.x(x.x);
+      if (x.strength !== void 0) force.strength(x.strength);
+      sim.force("x", force);
+    }
+    if (y !== void 0) {
+      const force = forceY();
+      if (y.y !== void 0) force.y(y.y);
+      if (y.strength !== void 0) force.strength(y.strength);
+      sim.force("y", force);
+    }
+    if (radial !== void 0) {
+      const force = forceRadial(radial.radius, radial.x ?? 0, radial.y ?? 0);
+      if (radial.strength !== void 0) force.strength(radial.strength);
+      sim.force("radial", force);
+    }
+  }
+  configureSimulation(sim) {
+    const { alpha, alphaMin, alphaDecay, alphaTarget, velocityDecay } = this.opts;
+    if (alpha !== void 0) sim.alpha(alpha);
+    if (alphaMin !== void 0) sim.alphaMin(alphaMin);
+    if (alphaDecay !== void 0) sim.alphaDecay(alphaDecay);
+    if (alphaTarget !== void 0) sim.alphaTarget(alphaTarget);
+    if (velocityDecay !== void 0) sim.velocityDecay(velocityDecay);
+  }
+  writeBack(store) {
+    const { nodes, buffer } = this;
+    for (let i = 0, j = 0; i < nodes.length; i++, j += 2) {
+      buffer[j] = nodes[i].x;
+      buffer[j + 1] = nodes[i].y;
+    }
+    this.writing = true;
+    store.setPositionsBulk(this.ids, buffer);
+    this.writing = false;
+  }
+};
+
+export { D3ForceLayout };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/D3ForceLayout.ts"],"names":[],"mappings":";;;;AAiDA,IAAM,YAAA,GAAe,GAAA;AAEd,IAAM,aAAA,GAAN,cAA4B,MAAA,CAAmB;AAAA,EACnC,IAAA;AAAA,EACT,GAAA,GAA2C,IAAA;AAAA,EAC3C,QAAmB,EAAC;AAAA,EACpB,MAAgB,EAAC;AAAA,EACjB,QAAA,uBAAe,GAAA,EAAqB;AAAA;AAAA;AAAA,EAGpC,aAAA,uBAAoB,GAAA,EAAuB;AAAA;AAAA;AAAA;AAAA,EAI3C,SAAA,uBAAgB,GAAA,EAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAS5B,UAAA,uBAAiB,GAAA,EAAY;AAAA,EAC7B,MAAA,GAAS,IAAI,YAAA,CAAa,CAAC,CAAA;AAAA;AAAA;AAAA;AAAA,EAI3B,OAAA,GAAU,KAAA;AAAA,EACV,WAAA,GAAmC,IAAA;AAAA,EACnC,YAAA,GAAoC,IAAA;AAAA,EACpC,UAAA,GAAkC,IAAA;AAAA;AAAA;AAAA,EAGlC,OAAA,GAAU,KAAA;AAAA,EAElB,WAAA,CAAY,IAAA,GAA6B,EAAC,EAAG;AAC3C,IAAA,KAAA,EAAM;AACN,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,MAAM,KAAA,EAAkC;AAC5C,IAAA,IAAA,CAAK,IAAA,EAAK;AACV,IAAA,MAAM,QAAQ,KAAA,CAAM,KAAA;AAGpB,IAAA,IAAA,CAAK,QAAQ,EAAC;AACd,IAAA,IAAA,CAAK,MAAM,EAAC;AACZ,IAAA,IAAA,CAAK,SAAS,KAAA,EAAM;AACpB,IAAA,IAAA,CAAK,cAAc,KAAA,EAAM;AACzB,IAAA,IAAA,CAAK,UAAU,KAAA,EAAM;AACrB,IAAA,IAAA,CAAK,WAAW,KAAA,EAAM;AACtB,IAAA,KAAA,MAAW,CAAA,IAAK,KAAA,CAAM,KAAA,EAAM,EAAG;AAC7B,MAAA,MAAM,GAAA,GAAM,KAAA,CAAM,WAAA,CAAY,CAAA,CAAE,EAAE,CAAA;AAClC,MAAA,MAAM,IAAA,GAAgB,EAAE,EAAA,EAAI,CAAA,CAAE,EAAA,EAAG;AACjC,MAAA,IAAI,EAAE,MAAA,EAAQ;AAIZ,QAAA,MAAM,EAAA,GAAK,KAAK,CAAA,IAAK,CAAA;AACrB,QAAA,MAAM,EAAA,GAAK,KAAK,CAAA,IAAK,CAAA;AACrB,QAAA,IAAA,CAAK,EAAA,GAAK,EAAA;AACV,QAAA,IAAA,CAAK,EAAA,GAAK,EAAA;AACV,QAAA,IAAA,CAAK,CAAA,GAAI,EAAA;AACT,QAAA,IAAA,CAAK,CAAA,GAAI,EAAA;AACT,QAAA,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,CAAA,CAAE,EAAE,CAAA;AAAA,MACzB,WAAW,GAAA,KAAQ,GAAA,CAAI,MAAM,CAAA,IAAK,GAAA,CAAI,MAAM,CAAA,CAAA,EAAI;AAK9C,QAAA,IAAA,CAAK,IAAI,GAAA,CAAI,CAAA;AACb,QAAA,IAAA,CAAK,IAAI,GAAA,CAAI,CAAA;AAAA,MACf;AACA,MAAA,IAAA,CAAK,KAAA,CAAM,KAAK,IAAI,CAAA;AACpB,MAAA,IAAA,CAAK,GAAA,CAAI,IAAA,CAAK,CAAA,CAAE,EAAE,CAAA;AAClB,MAAA,IAAA,CAAK,QAAA,CAAS,GAAA,CAAI,CAAA,CAAE,EAAA,EAAI,IAAI,CAAA;AAC5B,MAAA,IAAA,CAAK,aAAA,CAAc,GAAA,CAAI,CAAA,CAAE,EAAA,EAAI,CAAC,CAAA;AAAA,IAChC;AACA,IAAA,IAAI,IAAA,CAAK,KAAA,CAAM,MAAA,KAAW,CAAA,EAAG;AAC7B,IAAA,IAAA,CAAK,SAAS,IAAI,YAAA,CAAa,IAAA,CAAK,KAAA,CAAM,SAAS,CAAC,CAAA;AAEpD,IAAA,MAAM,QAAmB,EAAC;AAC1B,IAAA,KAAA,MAAW,CAAA,IAAK,KAAA,CAAM,KAAA,EAAM,EAAG;AAC7B,MAAA,KAAA,CAAM,IAAA,CAAK,EAAE,MAAA,EAAQ,CAAA,CAAE,QAAQ,MAAA,EAAQ,CAAA,CAAE,QAAQ,CAAA;AAAA,IACnD;AAGA,IAAA,MAAM,GAAA,GAAM,eAAA,CAAkC,IAAA,CAAK,KAAK,CAAA;AACxD,IAAA,IAAA,CAAK,eAAA,CAAgB,KAAK,KAAK,CAAA;AAC/B,IAAA,IAAA,CAAK,oBAAoB,GAAG,CAAA;AAC5B,IAAA,IAAA,CAAK,GAAA,GAAM,GAAA;AAOX,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,IAAA,CAAK,OAAA,IAAW,IAAA;AACrC,IAAA,GAAA,CAAI,EAAA,CAAG,QAAQ,MAAM;AACnB,MAAA,IAAI,OAAA,EAAS,IAAA,CAAK,SAAA,CAAU,KAAK,CAAA;AACjC,MAAA,IAAA,CAAK,MAAA,CAAO,IAAA,CAAK,MAAA,EAAQ,EAAE,CAAA;AAAA,IAC7B,CAAC,CAAA;AAaD,IAAA,IAAA,CAAK,WAAA,GAAc,MAAM,MAAA,CAAO,EAAA,CAAG,eAAe,CAAC,EAAE,MAAA,EAAQ,KAAA,EAAM,KAAM;AACvE,MAAA,IAAI,KAAK,OAAA,EAAS;AAClB,MAAA,MAAM,IAAA,GAAO,IAAA,CAAK,QAAA,CAAS,GAAA,CAAI,MAAM,CAAA;AACrC,MAAA,IAAI,CAAC,IAAA,EAAM;AAEX,MAAA,IAAI,YAAY,KAAA,EAAO;AACrB,QAAA,IAAI,KAAA,CAAM,MAAA,EAAQ,IAAA,CAAK,SAAA,CAAU,IAAI,MAAM,CAAA;AAAA,aACtC,IAAA,CAAK,SAAA,CAAU,MAAA,CAAO,MAAM,CAAA;AAAA,MACnC;AAEA,MAAA,IAAI,CAAC,MAAM,QAAA,EAAU;AACrB,MAAA,MAAM,MAAA,GACJ,KAAK,SAAA,CAAU,GAAA,CAAI,MAAM,CAAA,IAAK,IAAA,CAAK,UAAA,CAAW,GAAA,CAAI,MAAM,CAAA;AAC1D,MAAA,IAAI,MAAA,EAAQ;AACV,QAAA,IAAA,CAAK,EAAA,GAAK,MAAM,QAAA,CAAS,CAAA;AACzB,QAAA,IAAA,CAAK,EAAA,GAAK,MAAM,QAAA,CAAS,CAAA;AAGzB,QAAA,IAAA,CAAK,CAAA,GAAI,MAAM,QAAA,CAAS,CAAA;AACxB,QAAA,IAAA,CAAK,CAAA,GAAI,MAAM,QAAA,CAAS,CAAA;AAAA,MAC1B,CAAA,MAAO;AAEL,QAAA,IAAI,IAAA,CAAK,EAAA,KAAO,MAAA,EAAW,IAAA,CAAK,EAAA,GAAK,MAAA;AACrC,QAAA,IAAI,IAAA,CAAK,EAAA,KAAO,MAAA,EAAW,IAAA,CAAK,EAAA,GAAK,MAAA;AACrC,QAAA,IAAA,CAAK,CAAA,GAAI,MAAM,QAAA,CAAS,CAAA;AACxB,QAAA,IAAA,CAAK,CAAA,GAAI,MAAM,QAAA,CAAS,CAAA;AAAA,MAC1B;AACA,MAAA,IAAI,GAAA,CAAI,OAAM,GAAI,YAAA,MAAkB,KAAA,CAAM,YAAY,EAAE,OAAA,EAAQ;AAAA,IAClE,CAAC,CAAA;AAYD,IAAA,IAAA,CAAK,YAAA,GAAe,MAAM,MAAA,CAAO,EAAA,CAAG,mBAAmB,CAAC,EAAE,MAAA,EAAQ,OAAA,EAAQ,KAAM;AAC9E,MAAA,KAAA,MAAW,EAAA,IAAM,OAAA,IAAW,CAAC,MAAM,CAAA,EAAG;AACpC,QAAA,MAAM,IAAA,GAAO,IAAA,CAAK,QAAA,CAAS,GAAA,CAAI,EAAE,CAAA;AACjC,QAAA,IAAI,CAAC,IAAA,EAAM;AACX,QAAA,IAAA,CAAK,UAAA,CAAW,IAAI,EAAE,CAAA;AACtB,QAAA,MAAM,GAAA,GAAM,KAAA,CAAM,OAAA,CAAQ,EAAE,CAAA,EAAG,QAAA;AAC/B,QAAA,IAAI,GAAA,EAAK;AACP,UAAA,IAAA,CAAK,KAAK,GAAA,CAAI,CAAA;AACd,UAAA,IAAA,CAAK,KAAK,GAAA,CAAI,CAAA;AACd,UAAA,IAAA,CAAK,IAAI,GAAA,CAAI,CAAA;AACb,UAAA,IAAA,CAAK,IAAI,GAAA,CAAI,CAAA;AAAA,QACf;AAAA,MACF;AACA,MAAA,IAAI,GAAA,CAAI,OAAM,GAAI,YAAA,MAAkB,KAAA,CAAM,YAAY,EAAE,OAAA,EAAQ;AAAA,IAClE,CAAC,CAAA;AACD,IAAA,IAAA,CAAK,UAAA,GAAa,MAAM,MAAA,CAAO,EAAA,CAAG,iBAAiB,CAAC,EAAE,MAAA,EAAQ,OAAA,EAAQ,KAAM;AAC1E,MAAA,KAAA,MAAW,EAAA,IAAM,OAAA,IAAW,CAAC,MAAM,CAAA,EAAG;AACpC,QAAA,IAAA,CAAK,UAAA,CAAW,OAAO,EAAE,CAAA;AACzB,QAAA,MAAM,IAAA,GAAO,IAAA,CAAK,QAAA,CAAS,GAAA,CAAI,EAAE,CAAA;AACjC,QAAA,IAAI,CAAC,IAAA,EAAM;AACX,QAAA,IAAI,CAAC,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,EAAE,CAAA,EAAG;AAC3B,UAAA,IAAA,CAAK,EAAA,GAAK,MAAA;AACV,UAAA,IAAA,CAAK,EAAA,GAAK,MAAA;AAAA,QACZ;AAAA,MACF;AAAA,IACF,CAAC,CAAA;AAID,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AACf,IAAA,IAAA,CAAK,MAAA,CAAO,IAAA,CAAK,OAAA,EAAS,EAAE,CAAA;AAK5B,IAAA,OAAO,IAAI,OAAA,CAAc,CAAC,OAAA,KAAY;AACpC,MAAA,GAAA,CAAI,EAAA,CAAG,OAAO,MAAM;AAClB,QAAA,IAAI,KAAK,OAAA,EAAS;AAIhB,UAAA,IAAI,CAAC,OAAA,EAAS,IAAA,CAAK,SAAA,CAAU,KAAK,CAAA;AAClC,UAAA,IAAA,CAAK,OAAA,GAAU,KAAA;AACf,UAAA,IAAA,CAAK,OAAO,IAAA,CAAK,KAAA,EAAO,EAAE,MAAA,EAAQ,aAAa,CAAA;AAAA,QACjD;AACA,QAAA,OAAA,EAAQ;AAAA,MACV,CAAC,CAAA;AAAA,IACH,CAAC,CAAA;AAAA,EACH;AAAA;AAAA,EAGA,IAAA,GAAa;AACX,IAAA,MAAM,aAAa,IAAA,CAAK,OAAA;AACxB,IAAA,IAAA,CAAK,OAAA,GAAU,KAAA;AACf,IAAA,IAAA,CAAK,KAAK,IAAA,EAAK;AACf,IAAA,IAAA,CAAK,GAAA,GAAM,IAAA;AACX,IAAA,IAAA,CAAK,WAAA,IAAc;AACnB,IAAA,IAAA,CAAK,WAAA,GAAc,IAAA;AACnB,IAAA,IAAA,CAAK,YAAA,IAAe;AACpB,IAAA,IAAA,CAAK,YAAA,GAAe,IAAA;AACpB,IAAA,IAAA,CAAK,UAAA,IAAa;AAClB,IAAA,IAAA,CAAK,UAAA,GAAa,IAAA;AAClB,IAAA,IAAA,CAAK,QAAQ,EAAC;AACd,IAAA,IAAA,CAAK,MAAM,EAAC;AACZ,IAAA,IAAA,CAAK,SAAS,KAAA,EAAM;AACpB,IAAA,IAAA,CAAK,cAAc,KAAA,EAAM;AACzB,IAAA,IAAA,CAAK,UAAU,KAAA,EAAM;AACrB,IAAA,IAAA,CAAK,WAAW,KAAA,EAAM;AACtB,IAAA,IAAI,UAAA,OAAiB,MAAA,CAAO,IAAA,CAAK,OAAO,EAAE,MAAA,EAAQ,WAAW,CAAA;AAAA,EAC/D;AAAA;AAAA,EAIQ,eAAA,CAAgB,KAAmC,KAAA,EAAwB;AACjF,IAAA,MAAM,EAAE,MAAM,MAAA,EAAQ,MAAA,EAAQ,SAAS,CAAA,EAAG,CAAA,EAAG,MAAA,EAAO,GAAI,IAAA,CAAK,IAAA;AAE7D,IAAA,IAAI,SAAS,MAAA,EAAW;AACtB,MAAA,MAAM,KAAA,GAAQ,UAA4B,KAAK,CAAA,CAAE,GAAG,CAAC,CAAA,KAAM,EAAE,EAAE,CAAA;AAC/D,MAAA,IAAI,KAAK,QAAA,KAAa,MAAA,EAAW,KAAA,CAAM,QAAA,CAAS,KAAK,QAAQ,CAAA;AAC7D,MAAA,IAAI,KAAK,QAAA,KAAa,MAAA,EAAW,KAAA,CAAM,QAAA,CAAS,KAAK,QAAQ,CAAA;AAC7D,MAAA,IAAI,KAAK,UAAA,KAAe,MAAA,EAAW,KAAA,CAAM,UAAA,CAAW,KAAK,UAAU,CAAA;AACnE,MAAA,GAAA,CAAI,KAAA,CAAM,QAAQ,KAAK,CAAA;AAAA,IACzB;AAEA,IAAA,IAAI,WAAW,MAAA,EAAW;AACxB,MAAA,MAAM,QAAQ,aAAA,EAAuB;AACrC,MAAA,IAAI,OAAO,QAAA,KAAa,MAAA,EAAW,KAAA,CAAM,QAAA,CAAS,OAAO,QAAQ,CAAA;AACjE,MAAA,IAAI,OAAO,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,KAAA,CAAM,OAAO,KAAK,CAAA;AACxD,MAAA,IAAI,OAAO,WAAA,KAAgB,MAAA,EAAW,KAAA,CAAM,WAAA,CAAY,OAAO,WAAW,CAAA;AAC1E,MAAA,IAAI,OAAO,WAAA,KAAgB,MAAA,EAAW,KAAA,CAAM,WAAA,CAAY,OAAO,WAAW,CAAA;AAC1E,MAAA,GAAA,CAAI,KAAA,CAAM,UAAU,KAAK,CAAA;AAAA,IAC3B;AAEA,IAAA,IAAI,WAAW,MAAA,EAAW;AACxB,MAAA,MAAM,QAAQ,WAAA,CAAqB,MAAA,CAAO,KAAK,CAAA,EAAG,MAAA,CAAO,KAAK,CAAC,CAAA;AAC/D,MAAA,IAAI,OAAO,QAAA,KAAa,MAAA,EAAW,KAAA,CAAM,QAAA,CAAS,OAAO,QAAQ,CAAA;AACjE,MAAA,GAAA,CAAI,KAAA,CAAM,UAAU,KAAK,CAAA;AAAA,IAC3B;AAEA,IAAA,IAAI,YAAY,MAAA,EAAW;AACzB,MAAA,MAAM,QAAQ,YAAA,EAAsB;AACpC,MAAA,IAAI,OAAA,CAAQ,WAAW,MAAA,EAAW;AAChC,QAAA,IAAI,OAAO,OAAA,CAAQ,MAAA,KAAW,UAAA,EAAY;AACxC,UAAA,MAAM,KAAK,OAAA,CAAQ,MAAA;AACnB,UAAA,MAAM,OAAO,IAAA,CAAK,aAAA;AAClB,UAAA,KAAA,CAAM,MAAA,CAAO,CAAC,CAAA,KAAM;AAClB,YAAA,MAAM,IAAA,GAAO,IAAA,CAAK,GAAA,CAAI,CAAA,CAAE,EAAE,CAAA;AAC1B,YAAA,OAAO,IAAA,GAAO,EAAA,CAAG,IAAI,CAAA,GAAI,CAAA;AAAA,UAC3B,CAAC,CAAA;AAAA,QACH,CAAA,MAAO;AACL,UAAA,KAAA,CAAM,MAAA,CAAO,QAAQ,MAAM,CAAA;AAAA,QAC7B;AAAA,MACF;AACA,MAAA,IAAI,QAAQ,QAAA,KAAa,MAAA,EAAW,KAAA,CAAM,QAAA,CAAS,QAAQ,QAAQ,CAAA;AACnE,MAAA,IAAI,QAAQ,UAAA,KAAe,MAAA,EAAW,KAAA,CAAM,UAAA,CAAW,QAAQ,UAAU,CAAA;AACzE,MAAA,GAAA,CAAI,KAAA,CAAM,WAAW,KAAK,CAAA;AAAA,IAC5B;AAEA,IAAA,IAAI,MAAM,MAAA,EAAW;AACnB,MAAA,MAAM,QAAQ,MAAA,EAAgB;AAC9B,MAAA,IAAI,EAAE,CAAA,KAAM,MAAA,EAAW,KAAA,CAAM,CAAA,CAAE,EAAE,CAAC,CAAA;AAClC,MAAA,IAAI,EAAE,QAAA,KAAa,MAAA,EAAW,KAAA,CAAM,QAAA,CAAS,EAAE,QAAQ,CAAA;AACvD,MAAA,GAAA,CAAI,KAAA,CAAM,KAAK,KAAK,CAAA;AAAA,IACtB;AAEA,IAAA,IAAI,MAAM,MAAA,EAAW;AACnB,MAAA,MAAM,QAAQ,MAAA,EAAgB;AAC9B,MAAA,IAAI,EAAE,CAAA,KAAM,MAAA,EAAW,KAAA,CAAM,CAAA,CAAE,EAAE,CAAC,CAAA;AAClC,MAAA,IAAI,EAAE,QAAA,KAAa,MAAA,EAAW,KAAA,CAAM,QAAA,CAAS,EAAE,QAAQ,CAAA;AACvD,MAAA,GAAA,CAAI,KAAA,CAAM,KAAK,KAAK,CAAA;AAAA,IACtB;AAEA,IAAA,IAAI,WAAW,MAAA,EAAW;AACxB,MAAA,MAAM,KAAA,GAAQ,YAAqB,MAAA,CAAO,MAAA,EAAQ,OAAO,CAAA,IAAK,CAAA,EAAG,MAAA,CAAO,CAAA,IAAK,CAAC,CAAA;AAC9E,MAAA,IAAI,OAAO,QAAA,KAAa,MAAA,EAAW,KAAA,CAAM,QAAA,CAAS,OAAO,QAAQ,CAAA;AACjE,MAAA,GAAA,CAAI,KAAA,CAAM,UAAU,KAAK,CAAA;AAAA,IAC3B;AAAA,EACF;AAAA,EAEQ,oBAAoB,GAAA,EAAyC;AACnE,IAAA,MAAM,EAAE,KAAA,EAAO,QAAA,EAAU,YAAY,WAAA,EAAa,aAAA,KAAkB,IAAA,CAAK,IAAA;AACzE,IAAA,IAAI,KAAA,KAAU,MAAA,EAAW,GAAA,CAAI,KAAA,CAAM,KAAK,CAAA;AACxC,IAAA,IAAI,QAAA,KAAa,MAAA,EAAW,GAAA,CAAI,QAAA,CAAS,QAAQ,CAAA;AACjD,IAAA,IAAI,UAAA,KAAe,MAAA,EAAW,GAAA,CAAI,UAAA,CAAW,UAAU,CAAA;AACvD,IAAA,IAAI,WAAA,KAAgB,MAAA,EAAW,GAAA,CAAI,WAAA,CAAY,WAAW,CAAA;AAC1D,IAAA,IAAI,aAAA,KAAkB,MAAA,EAAW,GAAA,CAAI,aAAA,CAAc,aAAa,CAAA;AAAA,EAClE;AAAA,EAEQ,UAAU,KAAA,EAAkC;AAClD,IAAA,MAAM,EAAE,KAAA,EAAO,MAAA,EAAO,GAAI,IAAA;AAC1B,IAAA,KAAA,IAAS,CAAA,GAAI,GAAG,CAAA,GAAI,CAAA,EAAG,IAAI,KAAA,CAAM,MAAA,EAAQ,CAAA,EAAA,EAAK,CAAA,IAAK,CAAA,EAAG;AACpD,MAAA,MAAA,CAAO,CAAC,CAAA,GAAI,KAAA,CAAM,CAAC,CAAA,CAAG,CAAA;AACtB,MAAA,MAAA,CAAO,CAAA,GAAI,CAAC,CAAA,GAAI,KAAA,CAAM,CAAC,CAAA,CAAG,CAAA;AAAA,IAC5B;AACA,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AACf,IAAA,KAAA,CAAM,gBAAA,CAAiB,IAAA,CAAK,GAAA,EAAK,MAAM,CAAA;AACvC,IAAA,IAAA,CAAK,OAAA,GAAU,KAAA;AAAA,EACjB;AACF","file":"index.js","sourcesContent":["/**\n * `D3ForceLayout` — d3-force-directed `Layout` for `@invana/graph`.\n *\n * The flow is intentionally tiny:\n *   1. Snapshot nodes + edges from `layer.store` into d3-force datums.\n *   2. Build a simulation. d3 owns the tick loop.\n *   3. On each tick, bulk-write positions back to the store; the store\n *      emits `node:update` events and the renderer reacts on its own.\n *   4. Listen to external `node:update` (e.g. a drag) and mirror new\n *      positions onto the sim, reheating α so neighbours readjust.\n *\n * Every option defaults to `undefined`. A force is only added when its\n * option is provided; a setter is only called when its sub-option is\n * provided. d3-force's own defaults apply otherwise. See `./types`.\n *\n * @example\n * const layout = new D3ForceLayout({\n *   charge: { strength: -300 },\n *   link: { distance: 80 },\n *   center: { x: 0, y: 0 },\n * });\n * await layout.apply(graphLayer);\n */\n\nimport {\n  forceCenter,\n  forceCollide,\n  forceLink,\n  forceManyBody,\n  forceRadial,\n  forceSimulation,\n  forceX,\n  forceY,\n  type Simulation,\n  type SimulationLinkDatum,\n  type SimulationNodeDatum,\n} from 'd3-force';\n\nimport { Layout } from '@invana/canvas';\nimport type { GraphLayer, GraphNode } from '@invana/graph';\n\nimport type { D3ForceLayoutOptions } from './types';\n\ninterface SimNode extends SimulationNodeDatum {\n  id: string;\n}\ninterface SimLink extends SimulationLinkDatum<SimNode> {}\n\n/** α target re-applied when an external `node:update` arrives. */\nconst REHEAT_ALPHA = 0.3;\n\nexport class D3ForceLayout extends Layout<GraphLayer> {\n  private readonly opts: D3ForceLayoutOptions;\n  private sim: Simulation<SimNode, SimLink> | null = null;\n  private nodes: SimNode[] = [];\n  private ids: string[] = [];\n  private nodeById = new Map<string, SimNode>();\n  /** GraphNode snapshot indexed by id — used by per-node force callbacks\n   *  (e.g. `collide.radius(d => ...)`) without coupling SimNode to GraphNode. */\n  private graphNodeById = new Map<string, GraphNode>();\n  /** Ids of nodes whose `GraphNode.pinned === true` — permanent pins from\n   *  user data. Driven via d3-force's `fx/fy` so the simulation keeps them\n   *  fixed. Live: pin/unpin patches on `node:update` add/remove entries. */\n  private pinnedIds = new Set<string>();\n  /** Ids of nodes currently being dragged by a user behaviour. Populated\n   *  on `node:drag-start` from the layer, drained on `node:drag-end`. While\n   *  an id is in this set, position updates mirror onto `fx/fy` so the\n   *  simulation can't push the node away from the cursor. On drag-end the\n   *  transient `fx/fy` clears (unless the node is also in `pinnedIds`,\n   *  which is the permanent-pin path). Decoupled from `pinned` so a drag\n   *  never mutates user-data semantics — pin-on-release is opt-in via a\n   *  separate behaviour. */\n  private draggedIds = new Set<string>();\n  private buffer = new Float32Array(0);\n  /** True while our own bulk write is in-flight, so the `node:update`\n   *  events it triggers don't bounce back into the sim. Relies on the\n   *  store's default sync flush firing events inside the bulk call. */\n  private writing = false;\n  private unsubscribe: (() => void) | null = null;\n  private offDragStart: (() => void) | null = null;\n  private offDragEnd: (() => void) | null = null;\n  /** True while a run is active. Guards `stop()` so it only emits `end`\n   *  once per run, even if called externally after a natural settle. */\n  private running = false;\n\n  constructor(opts: D3ForceLayoutOptions = {}) {\n    super();\n    this.opts = opts;\n  }\n\n  /**\n   * Run the layout against `layer`. Resolves when the simulation settles\n   * naturally OR is cancelled via `stop()` / a second `apply()` call.\n   * Lifecycle events (`start` / `tick` / `end`) fire around the run.\n   */\n  async apply(layer: GraphLayer): Promise<void> {\n    this.stop();\n    const store = layer.store;\n\n    // 1. Snapshot store → sim datums.\n    this.nodes = [];\n    this.ids = [];\n    this.nodeById.clear();\n    this.graphNodeById.clear();\n    this.pinnedIds.clear();\n    this.draggedIds.clear();\n    for (const n of store.nodes()) {\n      const pos = store.getPosition(n.id);\n      const node: SimNode = { id: n.id };\n      if (n.pinned) {\n        // Pinned nodes use d3-force's `fx/fy` so the sim treats them as\n        // immovable but still applies their forces to neighbours\n        // (e.g. a cursor-follower that pushes other nodes via collide).\n        const px = pos?.x ?? 0;\n        const py = pos?.y ?? 0;\n        node.fx = px;\n        node.fy = py;\n        node.x = px;\n        node.y = py;\n        this.pinnedIds.add(n.id);\n      } else if (pos && (pos.x !== 0 || pos.y !== 0)) {\n        // Only seed if the store has a real position. (0, 0) is treated as\n        // the typed-array default; leaving x/y `undefined` lets\n        // `forceSimulation` phyllotaxis-scatter the cluster — without it,\n        // all-colocated nodes can't break their tie under d3 defaults.\n        node.x = pos.x;\n        node.y = pos.y;\n      }\n      this.nodes.push(node);\n      this.ids.push(n.id);\n      this.nodeById.set(n.id, node);\n      this.graphNodeById.set(n.id, n);\n    }\n    if (this.nodes.length === 0) return;\n    this.buffer = new Float32Array(this.nodes.length * 2);\n\n    const links: SimLink[] = [];\n    for (const e of store.edges()) {\n      links.push({ source: e.source, target: e.target });\n    }\n\n    // 2. Build simulation + apply only options the user provided.\n    const sim = forceSimulation<SimNode, SimLink>(this.nodes);\n    this.configureForces(sim, links);\n    this.configureSimulation(sim);\n    this.sim = sim;\n\n    // 3. Each d3 tick → optionally bulk write to store + emit lifecycle\n    //    `tick`. When `animate` is `false` we skip the per-tick store\n    //    writeback (and the renderer storm that follows) and defer to a\n    //    single writeback in the natural-end handler below — see\n    //    `D3ForceLayoutOptions.animate` for the rationale.\n    const animate = this.opts.animate ?? true;\n    sim.on('tick', () => {\n      if (animate) this.writeBack(store);\n      this.events.emit('tick', {});\n    });\n\n    // 4. External writes (drag, cursor-follower, etc.) → mirror onto sim,\n    //    reheat. Nodes that are either permanently pinned (`pinnedIds`,\n    //    user-data semantics) or transiently locked by an in-flight drag\n    //    (`draggedIds`, signalled by `node:drag-start` / `node:drag-end`\n    //    on the layer's events) write to `fx/fy` so the simulation can't\n    //    push them away from the supplied position. Otherwise the update\n    //    flows into `x/y` and the next force tick may move the node.\n    //\n    //    Pin patches are tracked live so a mid-run flip (e.g. a feed\n    //    enabling `pinned: true` on a node) takes effect on the next\n    //    `node:update` without needing a fresh `apply()`.\n    this.unsubscribe = store.events.on('node:update', ({ nodeId, patch }) => {\n      if (this.writing) return;\n      const node = this.nodeById.get(nodeId);\n      if (!node) return;\n\n      if ('pinned' in patch) {\n        if (patch.pinned) this.pinnedIds.add(nodeId);\n        else this.pinnedIds.delete(nodeId);\n      }\n\n      if (!patch.position) return;\n      const locked =\n        this.pinnedIds.has(nodeId) || this.draggedIds.has(nodeId);\n      if (locked) {\n        node.fx = patch.position.x;\n        node.fy = patch.position.y;\n        // Mirror onto `x/y` so rendered position matches before the next\n        // force tick — `forceCenter`/`forceX`/`forceY` read `x/y`.\n        node.x = patch.position.x;\n        node.y = patch.position.y;\n      } else {\n        // Free node: ensure no stale `fx/fy` are holding it.\n        if (node.fx !== undefined) node.fx = undefined as unknown as number;\n        if (node.fy !== undefined) node.fy = undefined as unknown as number;\n        node.x = patch.position.x;\n        node.y = patch.position.y;\n      }\n      if (sim.alpha() < REHEAT_ALPHA) sim.alpha(REHEAT_ALPHA).restart();\n    });\n\n    // 4b. Subscribe to drag lifecycle on the layer. `node:drag-start` puts\n    //     the node in `draggedIds` (so subsequent position updates lock via\n    //     `fx/fy`) and reheats the sim. `node:drag-end` removes it and —\n    //     unless the node is also permanently pinned — clears `fx/fy` so\n    //     forces can move it again. The store's `pinned` flag is never\n    //     touched here; permanent pin-on-release is a separate behaviour's\n    //     concern.\n    // `nodeIds` carries every primary being dragged (a multi-selection drag\n    // moves them all); fall back to `[nodeId]` for safety. Clamp / release\n    // each one's `fx/fy` independently.\n    this.offDragStart = layer.events.on('node:drag-start', ({ nodeId, nodeIds }) => {\n      for (const id of nodeIds ?? [nodeId]) {\n        const node = this.nodeById.get(id);\n        if (!node) continue;\n        this.draggedIds.add(id);\n        const pos = store.getNode(id)?.position;\n        if (pos) {\n          node.fx = pos.x;\n          node.fy = pos.y;\n          node.x = pos.x;\n          node.y = pos.y;\n        }\n      }\n      if (sim.alpha() < REHEAT_ALPHA) sim.alpha(REHEAT_ALPHA).restart();\n    });\n    this.offDragEnd = layer.events.on('node:drag-end', ({ nodeId, nodeIds }) => {\n      for (const id of nodeIds ?? [nodeId]) {\n        this.draggedIds.delete(id);\n        const node = this.nodeById.get(id);\n        if (!node) continue;\n        if (!this.pinnedIds.has(id)) {\n          node.fx = undefined as unknown as number;\n          node.fy = undefined as unknown as number;\n        }\n      }\n    });\n\n    // 5. Mark run as active and announce `start` after wiring is in place\n    //    so handlers see a fully-initialised layout.\n    this.running = true;\n    this.events.emit('start', {});\n\n    // 6. Resolve on natural settle. The `end` emission happens here (not in\n    //    `stop()`) so a natural settle reports `reason: 'completed'`;\n    //    external `stop()` flips `running` first and emits `'stopped'`.\n    return new Promise<void>((resolve) => {\n      sim.on('end', () => {\n        if (this.running) {\n          // `animate: false` runs deferred every per-tick writeback —\n          // flush the final settled positions now so the renderer\n          // actually sees the layout result.\n          if (!animate) this.writeBack(store);\n          this.running = false;\n          this.events.emit('end', { reason: 'completed' });\n        }\n        resolve();\n      });\n    });\n  }\n\n  /** Cancel an in-flight run. Positions stay in the store. No-op when idle. */\n  stop(): void {\n    const wasRunning = this.running;\n    this.running = false;\n    this.sim?.stop();\n    this.sim = null;\n    this.unsubscribe?.();\n    this.unsubscribe = null;\n    this.offDragStart?.();\n    this.offDragStart = null;\n    this.offDragEnd?.();\n    this.offDragEnd = null;\n    this.nodes = [];\n    this.ids = [];\n    this.nodeById.clear();\n    this.graphNodeById.clear();\n    this.pinnedIds.clear();\n    this.draggedIds.clear();\n    if (wasRunning) this.events.emit('end', { reason: 'stopped' });\n  }\n\n  // ─── Configuration ─────────────────────────────────────────────────────\n\n  private configureForces(sim: Simulation<SimNode, SimLink>, links: SimLink[]): void {\n    const { link, charge, center, collide, x, y, radial } = this.opts;\n\n    if (link !== undefined) {\n      const force = forceLink<SimNode, SimLink>(links).id((d) => d.id);\n      if (link.distance !== undefined) force.distance(link.distance);\n      if (link.strength !== undefined) force.strength(link.strength);\n      if (link.iterations !== undefined) force.iterations(link.iterations);\n      sim.force('link', force);\n    }\n\n    if (charge !== undefined) {\n      const force = forceManyBody<SimNode>();\n      if (charge.strength !== undefined) force.strength(charge.strength);\n      if (charge.theta !== undefined) force.theta(charge.theta);\n      if (charge.distanceMin !== undefined) force.distanceMin(charge.distanceMin);\n      if (charge.distanceMax !== undefined) force.distanceMax(charge.distanceMax);\n      sim.force('charge', force);\n    }\n\n    if (center !== undefined) {\n      const force = forceCenter<SimNode>(center.x ?? 0, center.y ?? 0);\n      if (center.strength !== undefined) force.strength(center.strength);\n      sim.force('center', force);\n    }\n\n    if (collide !== undefined) {\n      const force = forceCollide<SimNode>();\n      if (collide.radius !== undefined) {\n        if (typeof collide.radius === 'function') {\n          const fn = collide.radius;\n          const refs = this.graphNodeById;\n          force.radius((d) => {\n            const node = refs.get(d.id);\n            return node ? fn(node) : 0;\n          });\n        } else {\n          force.radius(collide.radius);\n        }\n      }\n      if (collide.strength !== undefined) force.strength(collide.strength);\n      if (collide.iterations !== undefined) force.iterations(collide.iterations);\n      sim.force('collide', force);\n    }\n\n    if (x !== undefined) {\n      const force = forceX<SimNode>();\n      if (x.x !== undefined) force.x(x.x);\n      if (x.strength !== undefined) force.strength(x.strength);\n      sim.force('x', force);\n    }\n\n    if (y !== undefined) {\n      const force = forceY<SimNode>();\n      if (y.y !== undefined) force.y(y.y);\n      if (y.strength !== undefined) force.strength(y.strength);\n      sim.force('y', force);\n    }\n\n    if (radial !== undefined) {\n      const force = forceRadial<SimNode>(radial.radius, radial.x ?? 0, radial.y ?? 0);\n      if (radial.strength !== undefined) force.strength(radial.strength);\n      sim.force('radial', force);\n    }\n  }\n\n  private configureSimulation(sim: Simulation<SimNode, SimLink>): void {\n    const { alpha, alphaMin, alphaDecay, alphaTarget, velocityDecay } = this.opts;\n    if (alpha !== undefined) sim.alpha(alpha);\n    if (alphaMin !== undefined) sim.alphaMin(alphaMin);\n    if (alphaDecay !== undefined) sim.alphaDecay(alphaDecay);\n    if (alphaTarget !== undefined) sim.alphaTarget(alphaTarget);\n    if (velocityDecay !== undefined) sim.velocityDecay(velocityDecay);\n  }\n\n  private writeBack(store: GraphLayer['store']): void {\n    const { nodes, buffer } = this;\n    for (let i = 0, j = 0; i < nodes.length; i++, j += 2) {\n      buffer[j] = nodes[i]!.x!;\n      buffer[j + 1] = nodes[i]!.y!;\n    }\n    this.writing = true;\n    store.setPositionsBulk(this.ids, buffer);\n    this.writing = false;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@invana/graph-layout-d3-force",
+  "version": "0.0.2",
+  "description": "D3 force-directed Layout for @invana/graph.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typedocOptions": {
+    "entryPoints": [
+      "src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "d3-force": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@invana/graph": "0.0.2",
+    "@invana/canvas": "0.0.2"
+  },
+  "devDependencies": {
+    "@types/d3-force": "^3.0.10",
+    "tsup": "^8.3.5",
+    "typescript": "5.9.2",
+    "vitest": "^2.1.8",
+    "@invana/canvas": "0.0.2",
+    "@invana/graph": "0.0.2",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "keywords": [
+    "canvas",
+    "graph",
+    "layout",
+    "d3",
+    "d3-force",
+    "force-directed"
+  ],
+  "license": "Apache-2.0",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "check-types": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}