@statelyai/graph 2.0.0 → 2.1.0

package/dist/index.mjs

@@ -1,9 +1,98 @@
-import { C as getSinks, D as isLeaf, E as isCompound, N as invalidateIndex, S as getSiblings, T as getSuccessors, _ as getPorts, a as getDescendants, b as getRelativeDistanceMap, c as getEdgesOf, d as getLCA, f as getNeighbors, g as getPort, h as getParent, i as getDepth, l as getInDegree, m as getOutEdges, n as getChildren, o as getEdgesBetween, p as getOutDegree, r as getDegree, s as getEdgesByPort, t as getAncestors, u as getInEdges, v as getPredecessors, w as getSources, x as getRoots, y as getRelativeDistance } from "./queries-KirMDR7e.mjs";
-import { $ as joinPaths, A as dfs, B as toEdgeConfig, C as genPostorders, D as getPreorder, E as getPostorders, F as isConnected, G as getAStarPath, H as genCycles, I as isTree, J as getShortestPath, K as getAllPairsShortestPaths, L as flatten, M as getTopologicalSort, N as hasPath, O as getPreorders, P as isAcyclic, Q as getStronglyConnectedComponents, R as getSubgraph, S as getMinimumSpanningTree, T as getPostorder, U as genShortestPaths, V as toNodeConfig, W as genSimplePaths, X as getSimplePath, Y as getShortestPaths, Z as getSimplePaths, _ as getEigenvectorCentrality, _t as updateEdge, a as isIsomorphic, at as createGraphEdge, b as getOutDegreeCentrality, c as getBridges, ct as createGraphPort, d as getGreedyModularityCommunities, dt as deleteEntities, et as GraphInstance, f as getLabelPropagationCommunities, ft as deleteNode, g as getDegreeCentrality, gt as hasNode, h as getClosenessCentrality, ht as hasEdge, i as getLouvainCommunities, it as createGraph, j as getConnectedComponents, k as bfs, l as genGirvanNewmanCommunities, lt as createVisualGraph, m as getBetweennessCentrality, mt as getNode, n as getDominatorTree, nt as addEntities, o as getArticulationPoints, ot as createGraphFromTransition, p as getModularity, pt as getEdge, q as getCycles, r as getMaxFlow, rt as addNode, s as getBiconnectedComponents, st as createGraphNode, t as getTransitiveReduction, tt as addEdge, u as getGirvanNewmanCommunities, ut as deleteEdge, v as getHITS, vt as updateEntities, w as genPreorders, x as getPageRank, y as getInDegreeCentrality, yt as updateNode, z as reverseGraph } from "./algorithms-DF1pSQGv.mjs";
-import { n as isEdgeDirected, t as getEdgeMode } from "./mode-D8OnHFBk.mjs";
-import { t as getGraphIssues } from "./validate-TtH-x3JV.mjs";
-import { n as createFormatConverter } from "./converter-DyCJJfTe.mjs";
+import { C as getSinks, D as isLeaf, E as isCompound, N as invalidateIndex, S as getSiblings, T as getSuccessors, _ as getPorts, a as getDescendants, b as getRelativeDistanceMap, c as getEdgesOf, d as getLCA, f as getNeighbors, g as getPort, h as getParent, i as getDepth, l as getInDegree, m as getOutEdges, n as getChildren, o as getEdgesBetween, p as getOutDegree, r as getDegree, s as getEdgesByPort, t as getAncestors, u as getInEdges, v as getPredecessors, w as getSources, x as getRoots, y as getRelativeDistance } from "./queries-BMM0XAv_.mjs";
+import { S as updateNode, _ as getNode, a as addEntities, b as updateEdge, c as createGraphEdge, d as createGraphPort, f as createVisualGraph, g as getEdge, h as deleteNode, i as addEdge, l as createGraphFromTransition, m as deleteEntities, n as toNodeConfig, o as addNode, p as deleteEdge, r as GraphInstance, s as createGraph, t as toEdgeConfig, u as createGraphNode, v as hasEdge, x as updateEntities, y as hasNode } from "./config-Dt5u1gSf.mjs";
+import { n as isEdgeDirected, t as getEdgeMode } from "./mode-gu_mhKKs.mjs";
+import { t as getGraphIssues } from "./validate-BsfSOv0S.mjs";
+import { $ as getAStarPath, A as genPreorders, B as getTopologicalSort, C as getHITS, D as getPageRank, E as getOutDegreeCentrality, F as bfs, G as flatten, H as isAcyclic, I as dfs, J as getSubgraph, K as getFlattenedGraph, L as genBFS, M as getPostorders, N as getPreorder, O as getMinimumSpanningTree, P as getPreorders, Q as genSimplePaths, R as genDFS, S as getEigenvectorCentrality, T as getKatzCentrality, U as isConnected, V as hasPath, W as isTree, X as genCycles, Y as reverseGraph, Z as genShortestPaths, _ as getCoreNumbers, a as getLouvainCommunities, at as getSimplePath, b as getClosenessCentrality, c as getBiconnectedComponents, ct as joinPaths, d as getGirvanNewmanCommunities, et as getAllPairsShortestPaths, f as getGreedyModularityCommunities, g as isBipartite, h as getMaximumBipartiteMatching, i as getMinCut, it as getShortestPaths, j as getPostorder, k as genPostorders, l as getBridges, lt as mulberry32$1, m as getModularity, n as getDominatorTree, nt as getJoinedPath, o as isIsomorphic, ot as getSimplePaths, p as getLabelPropagationCommunities, q as getReversedGraph, r as getMaxFlow, rt as getShortestPath, s as getArticulationPoints, st as getStronglyConnectedComponents, t as getTransitiveReduction, tt as getCycles, u as genGirvanNewmanCommunities, v as getKCore, w as getInDegreeCentrality, x as getDegreeCentrality, y as getBetweennessCentrality, z as getConnectedComponents } from "./algorithms-DBpH74hR.mjs";
+import { n as createFormatConverter } from "./converter-DB6Rg6Vd.mjs";
 
+//#region src/generators.ts
+function assertNonNegativeInteger(caller, name, value) {
+	if (!Number.isInteger(value) || value < 0) throw new Error(`${caller}: ${name} ${value} is invalid — pass a non-negative integer`);
+}
+/**
+* Create the complete graph K_n: every pair of distinct nodes connected by
+* one undirected edge. Nodes are `n0..n{n-1}` (`options.idPrefix` overrides
+* the `n` prefix); edges are `e0..`.
+*/
+function createCompleteGraph(n, options) {
+	assertNonNegativeInteger("createCompleteGraph", "node count", n);
+	const prefix = options?.idPrefix ?? "n";
+	const nodes = [];
+	for (let i = 0; i < n; i++) nodes.push({ id: `${prefix}${i}` });
+	const edges = [];
+	let edgeId = 0;
+	for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) edges.push({
+		id: `e${edgeId++}`,
+		sourceId: `${prefix}${i}`,
+		targetId: `${prefix}${j}`
+	});
+	return createGraph({
+		mode: "undirected",
+		nodes,
+		edges
+	});
+}
+/**
+* Create a `rows × cols` grid graph: node `(r, c)` is connected to its right
+* and down neighbors by undirected edges. Nodes are `n{r}_{c}`
+* (`options.idPrefix` overrides the `n` prefix); edges are `e0..`.
+*/
+function createGridGraph(rows, cols, options) {
+	assertNonNegativeInteger("createGridGraph", "row count", rows);
+	assertNonNegativeInteger("createGridGraph", "column count", cols);
+	const prefix = options?.idPrefix ?? "n";
+	const nodeId = (r, c) => `${prefix}${r}_${c}`;
+	const nodes = [];
+	const edges = [];
+	let edgeId = 0;
+	for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) {
+		nodes.push({ id: nodeId(r, c) });
+		if (c + 1 < cols) edges.push({
+			id: `e${edgeId++}`,
+			sourceId: nodeId(r, c),
+			targetId: nodeId(r, c + 1)
+		});
+		if (r + 1 < rows) edges.push({
+			id: `e${edgeId++}`,
+			sourceId: nodeId(r, c),
+			targetId: nodeId(r + 1, c)
+		});
+	}
+	return createGraph({
+		mode: "undirected",
+		nodes,
+		edges
+	});
+}
+/**
+* Create an Erdős–Rényi G(n, p) random graph: each of the n·(n-1)/2 node
+* pairs gets an undirected edge with probability `probability`. With
+* `options.seed` the result is deterministic per seed (mulberry32);
+* otherwise `Math.random` is used. Nodes are `n0..n{n-1}`
+* (`options.idPrefix` overrides the `n` prefix); edges are `e0..`.
+*/
+function createRandomGraph(n, probability, options) {
+	assertNonNegativeInteger("createRandomGraph", "node count", n);
+	if (!(probability >= 0 && probability <= 1)) throw new Error(`createRandomGraph: probability ${probability} is invalid — pass a number between 0 and 1`);
+	const prefix = options?.idPrefix ?? "n";
+	const rng = options?.seed !== void 0 ? mulberry32$1(options.seed) : Math.random;
+	const nodes = [];
+	for (let i = 0; i < n; i++) nodes.push({ id: `${prefix}${i}` });
+	const edges = [];
+	let edgeId = 0;
+	for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) if (rng() < probability) edges.push({
+		id: `e${edgeId++}`,
+		sourceId: `${prefix}${i}`,
+		targetId: `${prefix}${j}`
+	});
+	return createGraph({
+		mode: "undirected",
+		nodes,
+		edges
+	});
+}
+
+//#endregion
 //#region src/equivalence.ts
 /** Shallow-compare two values, returning true if they differ. */
 function differs$1(a, b) {
@@ -27,6 +116,8 @@ const LAYOUT_KEYS = {
 		"y",
 		"width",
 		"height",
+		"points",
+		"routing",
 		"style",
 		"color"
 	]
@@ -127,6 +218,8 @@ const EDGE_COMPARE_KEYS = [
 	"mode",
 	"sourcePort",
 	"targetPort",
+	"points",
+	"routing",
 	"x",
 	"y",
 	"width",
@@ -232,18 +325,18 @@ function isEmptyDiff(diff) {
 *
 * @example
 * ```ts
-* import { createGraph, getDiff, invertDiff } from '@statelyai/graph';
+* import { createGraph, getDiff, getInvertedDiff } from '@statelyai/graph';
 *
 * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
 * const b = createGraph({ nodes: [{ id: 'n2' }], edges: [] });
 *
 * const diff = getDiff(a, b);
-* const inv = invertDiff(diff);
+* const inv = getInvertedDiff(diff);
 * // inv.nodes.added contains n1 (was removed)
 * // inv.nodes.removed contains n2 (was added)
 * ```
 */
-function invertDiff(diff) {
+function getInvertedDiff(diff) {
 	return {
 		nodes: {
 			added: diff.nodes.removed.map((c) => structuredClone(c)),
@@ -266,6 +359,12 @@ function invertDiff(diff) {
 	};
 }
 /**
+* @deprecated Use {@link getInvertedDiff}.
+*/
+function invertDiff(diff) {
+	return getInvertedDiff(diff);
+}
+/**
 * Compute an ordered patch list from graph `a` to graph `b`.
 * Order (see {@link toPatches}): add nodes → update edges → delete edges →
 * delete nodes → add edges → update nodes.
@@ -290,17 +389,17 @@ function getPatches(a, b) {
 *
 * @example
 * ```ts
-* import { createGraph, getPatches, applyPatches } from '@statelyai/graph';
+* import { createGraph, getPatches, updateGraphWithPatches } from '@statelyai/graph';
 *
 * const a = createGraph({ nodes: [{ id: 'n1' }], edges: [] });
 * const b = createGraph({ nodes: [{ id: 'n1' }, { id: 'n2' }], edges: [] });
 *
 * const patches = getPatches(a, b);
-* applyPatches(a, patches);
+* updateGraphWithPatches(a, patches);
 * // a now contains both n1 and n2
 * ```
 */
-function applyPatches(graph, patches) {
+function updateGraphWithPatches(graph, patches) {
 	for (const patch of patches) switch (patch.op) {
 		case "addNode":
 			addNode(graph, patch.node);
@@ -323,6 +422,12 @@ function applyPatches(graph, patches) {
 	}
 }
 /**
+* @deprecated Use {@link updateGraphWithPatches}.
+*/
+function applyPatches(graph, patches) {
+	updateGraphWithPatches(graph, patches);
+}
+/**
 * Flatten a structured diff into an ordered patch list.
 * Order: add nodes → update edges → delete edges → delete nodes → add edges → update nodes.
 * This avoids cascading deletes removing edges that are being updated,
@@ -679,7 +784,7 @@ function* genPredefinedWalk(graph, edgeIds, options) {
 /**
 * Yield at most `n` steps from the source generator.
 */
-function* takeSteps(gen, n) {
+function* genWalkSteps(gen, n) {
 	let count = 0;
 	for (const step of gen) {
 		yield step;
@@ -687,27 +792,45 @@ function* takeSteps(gen, n) {
 	}
 }
 /**
+* @deprecated Use {@link genWalkSteps}.
+*/
+function* takeSteps(gen, n) {
+	yield* genWalkSteps(gen, n);
+}
+/**
 * Yield steps until a specific node is reached.
 */
-function* takeUntilNode(gen, nodeId) {
+function* genWalkUntilNode(gen, nodeId) {
 	for (const step of gen) {
 		yield step;
 		if (step.node.id === nodeId) return;
 	}
 }
 /**
+* @deprecated Use {@link genWalkUntilNode}.
+*/
+function* takeUntilNode(gen, nodeId) {
+	yield* genWalkUntilNode(gen, nodeId);
+}
+/**
 * Yield steps until a specific edge is traversed.
 */
-function* takeUntilEdge(gen, edgeId) {
+function* genWalkUntilEdge(gen, edgeId) {
 	for (const step of gen) {
 		yield step;
 		if (step.edge.id === edgeId) return;
 	}
 }
 /**
+* @deprecated Use {@link genWalkUntilEdge}.
+*/
+function* takeUntilEdge(gen, edgeId) {
+	yield* genWalkUntilEdge(gen, edgeId);
+}
+/**
 * Yield steps until node coverage reaches the target (0–1).
 */
-function* takeUntilNodeCoverage(gen, graph, coverage, options) {
+function* genWalkUntilNodeCoverage(gen, graph, coverage, options) {
 	const totalNodes = graph.nodes.length;
 	const target = Math.ceil(coverage * totalNodes);
 	const startId = options?.from ?? graph.initialNodeId ?? graph.nodes[0]?.id;
@@ -720,9 +843,15 @@ function* takeUntilNodeCoverage(gen, graph, coverage, options) {
 	}
 }
 /**
+* @deprecated Use {@link genWalkUntilNodeCoverage}.
+*/
+function* takeUntilNodeCoverage(gen, graph, coverage, options) {
+	yield* genWalkUntilNodeCoverage(gen, graph, coverage, options);
+}
+/**
 * Yield steps until edge coverage reaches the target (0–1).
 */
-function* takeUntilEdgeCoverage(gen, graph, coverage) {
+function* genWalkUntilEdgeCoverage(gen, graph, coverage) {
 	const totalEdges = graph.edges.length;
 	const target = Math.ceil(coverage * totalEdges);
 	const visited = /* @__PURE__ */ new Set();
@@ -734,6 +863,12 @@ function* takeUntilEdgeCoverage(gen, graph, coverage) {
 	}
 }
 /**
+* @deprecated Use {@link genWalkUntilEdgeCoverage}.
+*/
+function* takeUntilEdgeCoverage(gen, graph, coverage) {
+	yield* genWalkUntilEdgeCoverage(gen, graph, coverage);
+}
+/**
 * Compute coverage statistics for a completed walk.
 */
 function getCoverage(graph, steps, options) {
@@ -754,4 +889,4 @@ function getCoverage(graph, steps, options) {
 }
 
 //#endregion
-export { GraphInstance, LAYOUT_KEYS, addEdge, addEntities, addNode, applyPatches, areEntitiesEqual, bfs, createFormatConverter, createGraph, createGraphEdge, createGraphFromTransition, createGraphNode, createGraphPort, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genGirvanNewmanCommunities, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getArticulationPoints, getBetweennessCentrality, getBiconnectedComponents, getBridges, getChildren, getClosenessCentrality, getConnectedComponents, getCoverage, getCycles, getDegree, getDegreeCentrality, getDepth, getDescendants, getDiff, getDominatorTree, getEdge, getEdgeMode, getEdgesBetween, getEdgesByPort, getEdgesOf, getEigenvectorCentrality, getGirvanNewmanCommunities, getGraphIssues, getGreedyModularityCommunities, getHITS, getInDegree, getInDegreeCentrality, getInEdges, getLCA, getLabelPropagationCommunities, getLouvainCommunities, getMaxFlow, getMinimumSpanningTree, getModularity, getNeighbors, getNode, getOutDegree, getOutDegreeCentrality, getOutEdges, getPageRank, getParent, getPatches, getPort, getPorts, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, getTransitiveReduction, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEdgeDirected, isEmptyDiff, isIsomorphic, isLayoutEqual, isLeaf, isNonLayoutEqual, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };
+export { GraphInstance, LAYOUT_KEYS, addEdge, addEntities, addNode, applyPatches, areEntitiesEqual, bfs, createCompleteGraph, createFormatConverter, createGraph, createGraphEdge, createGraphFromTransition, createGraphNode, createGraphPort, createGridGraph, createRandomGraph, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genBFS, genCycles, genDFS, genGirvanNewmanCommunities, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWalkSteps, genWalkUntilEdge, genWalkUntilEdgeCoverage, genWalkUntilNode, genWalkUntilNodeCoverage, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getArticulationPoints, getBetweennessCentrality, getBiconnectedComponents, getBridges, getChildren, getClosenessCentrality, getConnectedComponents, getCoreNumbers, getCoverage, getCycles, getDegree, getDegreeCentrality, getDepth, getDescendants, getDiff, getDominatorTree, getEdge, getEdgeMode, getEdgesBetween, getEdgesByPort, getEdgesOf, getEigenvectorCentrality, getFlattenedGraph, getGirvanNewmanCommunities, getGraphIssues, getGreedyModularityCommunities, getHITS, getInDegree, getInDegreeCentrality, getInEdges, getInvertedDiff, getJoinedPath, getKCore, getKatzCentrality, getLCA, getLabelPropagationCommunities, getLouvainCommunities, getMaxFlow, getMaximumBipartiteMatching, getMinCut, getMinimumSpanningTree, getModularity, getNeighbors, getNode, getOutDegree, getOutDegreeCentrality, getOutEdges, getPageRank, getParent, getPatches, getPort, getPorts, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getReversedGraph, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, getTransitiveReduction, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isBipartite, isCompound, isConnected, isEdgeDirected, isEmptyDiff, isIsomorphic, isLayoutEqual, isLeaf, isNonLayoutEqual, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateGraphWithPatches, updateNode };

package/dist/layout/cytoscape.d.mts

@@ -0,0 +1,66 @@
+import { I as VisualGraph, f as Graph } from "../types-BAEQTwK_.mjs";
+import { LayoutOptions } from "./index.mjs";
+import cytoscape from "cytoscape";
+
+//#region src/layout/cytoscape.d.ts
+
+/**
+ * Minimal interface an injected cytoscape factory must satisfy — the
+ * `cytoscape()` function itself. Inject your own when you've registered
+ * layout extensions via `cytoscape.use(...)` (cola, fcose, dagre, …).
+ */
+type CytoscapeLike = (options: cytoscape.CytoscapeOptions) => cytoscape.Core;
+interface CytoscapeLayoutOptions extends LayoutOptions {
+  /**
+   * Cytoscape layout name. Built-ins: `'grid'`, `'circle'`, `'concentric'`,
+   * `'breadthfirst'`, `'cose'` (default), `'random'`. Extension layouts work
+   * when registered on an injected {@link CytoscapeLayoutOptions.cy} factory.
+   */
+  name?: string;
+  /**
+   * Raw cytoscape layout options, merged into the layout call last (override
+   * everything, including `name`). Engine-specific tuning — spacing knobs,
+   * `boundingBox`, `roots`, iteration counts — goes here; the options vary
+   * too much between cytoscape layouts to map `LayoutOptions.spacing`
+   * generically. See https://js.cytoscape.org/#layouts
+   */
+  layoutOptions?: Record<string, unknown>;
+  /**
+   * Injected cytoscape factory — e.g. one with extensions registered via
+   * `cytoscape.use(...)`. Defaults to the imported `cytoscape`.
+   */
+  cy?: CytoscapeLike;
+}
+/**
+ * Lay out a graph with Cytoscape.js (`cytoscape`, an optional peer
+ * dependency) — one call unlocks its whole layout ecosystem. Pure: returns a
+ * new {@link VisualGraph} with node positions and sizes. Cytoscape layouts
+ * position nodes only; edges keep their fields but gain no route `points`.
+ * Compound graphs are supported via cytoscape `parent`; parent nodes get
+ * cytoscape's computed compound dimensions. All coordinates are absolute
+ * (cytoscape does not produce parent-relative positions).
+ *
+ * Runs headless with `styleEnabled: true` so resolved node sizes
+ * ({@link getNodeSize}) participate in overlap avoidance and spacing.
+ *
+ * Option mapping is deliberately minimal: `measure` resolves sizes,
+ * `isFixed` nodes with an existing `x`/`y` are locked in place (cytoscape
+ * layouts skip locked nodes), and everything else — including `direction`
+ * and `spacing` — is engine-specific and belongs in
+ * {@link CytoscapeLayoutOptions.layoutOptions}. `seed` is ignored: the
+ * discrete layouts (grid, circle, concentric, breadthfirst) are
+ * deterministic, and cose is not seedable.
+ *
+ * @example
+ * ```ts
+ * import { getCytoscapeLayout } from '@statelyai/graph/layout/cytoscape';
+ *
+ * const laidOut = await getCytoscapeLayout(graph, {
+ *   name: 'breadthfirst',
+ *   layoutOptions: { roots: ['start'] },
+ * });
+ * ```
+ */
+declare function getCytoscapeLayout(graph: Graph | VisualGraph, options?: CytoscapeLayoutOptions): Promise<VisualGraph>;
+//#endregion
+export { CytoscapeLayoutOptions, CytoscapeLike, getCytoscapeLayout };

package/dist/layout/cytoscape.mjs

@@ -0,0 +1,114 @@
+import { f as createVisualGraph, n as toNodeConfig, t as toEdgeConfig } from "../config-Dt5u1gSf.mjs";
+import { getNodeSize } from "./index.mjs";
+import cytoscape from "cytoscape";
+
+//#region src/layout/cytoscape.ts
+/**
+* Lay out a graph with Cytoscape.js (`cytoscape`, an optional peer
+* dependency) — one call unlocks its whole layout ecosystem. Pure: returns a
+* new {@link VisualGraph} with node positions and sizes. Cytoscape layouts
+* position nodes only; edges keep their fields but gain no route `points`.
+* Compound graphs are supported via cytoscape `parent`; parent nodes get
+* cytoscape's computed compound dimensions. All coordinates are absolute
+* (cytoscape does not produce parent-relative positions).
+*
+* Runs headless with `styleEnabled: true` so resolved node sizes
+* ({@link getNodeSize}) participate in overlap avoidance and spacing.
+*
+* Option mapping is deliberately minimal: `measure` resolves sizes,
+* `isFixed` nodes with an existing `x`/`y` are locked in place (cytoscape
+* layouts skip locked nodes), and everything else — including `direction`
+* and `spacing` — is engine-specific and belongs in
+* {@link CytoscapeLayoutOptions.layoutOptions}. `seed` is ignored: the
+* discrete layouts (grid, circle, concentric, breadthfirst) are
+* deterministic, and cose is not seedable.
+*
+* @example
+* ```ts
+* import { getCytoscapeLayout } from '@statelyai/graph/layout/cytoscape';
+*
+* const laidOut = await getCytoscapeLayout(graph, {
+*   name: 'breadthfirst',
+*   layoutOptions: { roots: ['start'] },
+* });
+* ```
+*/
+async function getCytoscapeLayout(graph, options) {
+	const elements = [];
+	for (const node of graph.nodes) {
+		const size = getNodeSize(node, options);
+		const hasPosition = node.x !== void 0 && node.y !== void 0;
+		elements.push({
+			group: "nodes",
+			data: {
+				id: node.id,
+				...node.parentId != null && { parent: node.parentId },
+				width: size.width,
+				height: size.height
+			},
+			...hasPosition && { position: {
+				x: node.x + size.width / 2,
+				y: node.y + size.height / 2
+			} },
+			...hasPosition && options?.isFixed?.(node) && { locked: true }
+		});
+	}
+	for (const edge of graph.edges) elements.push({
+		group: "edges",
+		data: {
+			id: edge.id,
+			source: edge.sourceId,
+			target: edge.targetId
+		}
+	});
+	const cy = (options?.cy ?? cytoscape)({
+		headless: true,
+		styleEnabled: true,
+		style: [{
+			selector: "node",
+			style: {
+				width: "data(width)",
+				height: "data(height)",
+				shape: "rectangle"
+			}
+		}],
+		elements
+	});
+	try {
+		const layout = cy.layout({
+			name: options?.name ?? "cose",
+			animate: false,
+			...options?.layoutOptions
+		});
+		const stopped = layout.promiseOn("layoutstop");
+		layout.run();
+		await stopped;
+		return createVisualGraph({
+			id: graph.id,
+			mode: graph.mode,
+			initialNodeId: graph.initialNodeId ?? void 0,
+			direction: options?.direction ?? graph.direction,
+			data: graph.data,
+			...graph.style !== void 0 && { style: graph.style },
+			nodes: graph.nodes.map((node) => {
+				const ele = cy.getElementById(node.id);
+				const width = ele.width();
+				const height = ele.height();
+				const position = ele.position();
+				return {
+					...toNodeConfig(node),
+					width,
+					height,
+					x: position.x - width / 2,
+					y: position.y - height / 2
+				};
+			}),
+			edges: graph.edges.map((edge) => toEdgeConfig(edge))
+		});
+	} finally {
+		cy.destroy();
+	}
+}
+
+//#endregion
+export { getCytoscapeLayout };

package/dist/layout/d3-force.d.mts

@@ -0,0 +1,52 @@
+import { I as VisualGraph, f as Graph } from "../types-BAEQTwK_.mjs";
+import { LayoutFrame, LayoutOptions } from "./index.mjs";
+
+//#region src/layout/d3-force.d.ts
+interface ForceLayoutOptions extends LayoutOptions {
+  /** Target distance between linked nodes. Default: 80. */
+  linkDistance?: number;
+  /** Many-body charge strength (negative repels). Default: -300. */
+  chargeStrength?: number;
+  /** Number of simulation ticks. Default: 300 (d3's natural cooling span). */
+  iterations?: number;
+}
+/**
+ * Iterative force-directed layout via d3-force (optional peer dependency).
+ * Each `next()` advances one simulation tick and yields a {@link LayoutFrame}
+ * (top-left node positions by id + remaining `alpha`); the caller owns pacing
+ * (e.g. one tick per animation frame via {@link applyLayoutFrame}) and
+ * cancellation (stop iterating). The generator's return value is the settled
+ * {@link VisualGraph}.
+ *
+ * - Deterministic: `options.seed` drives d3's `randomSource`; the same seed
+ *   always produces the same layout.
+ * - `options.isFixed` pins nodes at their current position (d3 `fx`/`fy`).
+ * - Hierarchy is ignored (force layouts are flat); per-edge `mode` is
+ *   irrelevant (forces are symmetric).
+ *
+ * @example
+ * ```ts
+ * import { genForceLayout } from '@statelyai/graph/layout/d3-force';
+ * import { applyLayoutFrame } from '@statelyai/graph/layout';
+ *
+ * for (const frame of genForceLayout(graph, { seed: 42 })) {
+ *   applyLayoutFrame(graph, frame);
+ *   render(graph);
+ * }
+ * ```
+ */
+declare function genForceLayout(graph: Graph | VisualGraph, options?: ForceLayoutOptions): Generator<LayoutFrame, VisualGraph>;
+/**
+ * Run {@link genForceLayout} to completion and return the settled
+ * {@link VisualGraph}. Convenience for non-animated use.
+ *
+ * @example
+ * ```ts
+ * import { getForceLayout } from '@statelyai/graph/layout/d3-force';
+ *
+ * const laidOut = getForceLayout(graph, { seed: 42 });
+ * ```
+ */
+declare function getForceLayout(graph: Graph | VisualGraph, options?: ForceLayoutOptions): VisualGraph;
+//#endregion
+export { ForceLayoutOptions, genForceLayout, getForceLayout };

package/dist/layout/d3-force.mjs

@@ -0,0 +1,127 @@
+import { f as createVisualGraph, n as toNodeConfig, t as toEdgeConfig } from "../config-Dt5u1gSf.mjs";
+import { getNodeSize } from "./index.mjs";
+import { forceCenter, forceLink, forceManyBody, forceSimulation } from "d3-force";
+
+//#region src/layout/d3-force.ts
+/** mulberry32 — same seeded PRNG the rest of the library uses. */
+function mulberry32(seed) {
+	let s = seed | 0;
+	return () => {
+		s = s + 1831565813 | 0;
+		let t = Math.imul(s ^ s >>> 15, 1 | s);
+		t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+/**
+* Iterative force-directed layout via d3-force (optional peer dependency).
+* Each `next()` advances one simulation tick and yields a {@link LayoutFrame}
+* (top-left node positions by id + remaining `alpha`); the caller owns pacing
+* (e.g. one tick per animation frame via {@link applyLayoutFrame}) and
+* cancellation (stop iterating). The generator's return value is the settled
+* {@link VisualGraph}.
+*
+* - Deterministic: `options.seed` drives d3's `randomSource`; the same seed
+*   always produces the same layout.
+* - `options.isFixed` pins nodes at their current position (d3 `fx`/`fy`).
+* - Hierarchy is ignored (force layouts are flat); per-edge `mode` is
+*   irrelevant (forces are symmetric).
+*
+* @example
+* ```ts
+* import { genForceLayout } from '@statelyai/graph/layout/d3-force';
+* import { applyLayoutFrame } from '@statelyai/graph/layout';
+*
+* for (const frame of genForceLayout(graph, { seed: 42 })) {
+*   applyLayoutFrame(graph, frame);
+*   render(graph);
+* }
+* ```
+*/
+function* genForceLayout(graph, options) {
+	const rng = mulberry32(options?.seed ?? 1);
+	const sizes = /* @__PURE__ */ new Map();
+	const scatterRadius = Math.max(80, 30 * Math.sqrt(graph.nodes.length));
+	const simNodes = graph.nodes.map((node) => {
+		const size = getNodeSize(node, options);
+		sizes.set(node.id, size);
+		const simNode = {
+			id: node.id,
+			...size
+		};
+		if (node.x !== void 0 && node.y !== void 0) {
+			simNode.x = node.x + size.width / 2;
+			simNode.y = node.y + size.height / 2;
+			if (options?.isFixed?.(node)) {
+				simNode.fx = simNode.x;
+				simNode.fy = simNode.y;
+			}
+		} else {
+			const angle = rng() * 2 * Math.PI;
+			const radius = scatterRadius * Math.sqrt(rng());
+			simNode.x = Math.cos(angle) * radius;
+			simNode.y = Math.sin(angle) * radius;
+		}
+		return simNode;
+	});
+	const simLinks = graph.edges.filter((edge) => sizes.has(edge.sourceId) && sizes.has(edge.targetId) && edge.sourceId !== edge.targetId).map((edge) => ({
+		source: edge.sourceId,
+		target: edge.targetId
+	}));
+	const simulation = forceSimulation(simNodes).randomSource(mulberry32(options?.seed ?? 1)).force("link", forceLink(simLinks).id((d) => d.id).distance(options?.linkDistance ?? 80)).force("charge", forceManyBody().strength(options?.chargeStrength ?? -300)).force("center", forceCenter(0, 0)).stop();
+	const iterations = options?.iterations ?? 300;
+	for (let i = 0; i < iterations; i++) {
+		simulation.tick();
+		const positions = {};
+		for (const simNode of simNodes) positions[simNode.id] = {
+			x: (simNode.x ?? 0) - simNode.width / 2,
+			y: (simNode.y ?? 0) - simNode.height / 2
+		};
+		yield {
+			positions,
+			alpha: simulation.alpha()
+		};
+		if (simulation.alpha() < simulation.alphaMin()) break;
+	}
+	const byId = new Map(simNodes.map((simNode) => [simNode.id, simNode]));
+	return createVisualGraph({
+		id: graph.id,
+		mode: graph.mode,
+		initialNodeId: graph.initialNodeId ?? void 0,
+		direction: graph.direction,
+		data: graph.data,
+		...graph.style !== void 0 && { style: graph.style },
+		nodes: graph.nodes.map((node) => {
+			const size = sizes.get(node.id);
+			const simNode = byId.get(node.id);
+			return {
+				...toNodeConfig(node),
+				...size,
+				x: (simNode.x ?? 0) - size.width / 2,
+				y: (simNode.y ?? 0) - size.height / 2
+			};
+		}),
+		edges: graph.edges.map((edge) => toEdgeConfig(edge))
+	});
+}
+/**
+* Run {@link genForceLayout} to completion and return the settled
+* {@link VisualGraph}. Convenience for non-animated use.
+*
+* @example
+* ```ts
+* import { getForceLayout } from '@statelyai/graph/layout/d3-force';
+*
+* const laidOut = getForceLayout(graph, { seed: 42 });
+* ```
+*/
+function getForceLayout(graph, options) {
+	const generator = genForceLayout(graph, options);
+	for (;;) {
+		const step = generator.next();
+		if (step.done) return step.value;
+	}
+}
+
+//#endregion
+export { genForceLayout, getForceLayout };