@statelyai/graph 2.0.0 → 2.1.0

package/dist/layout/graphviz.mjs

@@ -0,0 +1,179 @@
+import { f as createVisualGraph, n as toNodeConfig, t as toEdgeConfig } from "../config-Dt5u1gSf.mjs";
+import { getNodeSize } from "./index.mjs";
+import { Graphviz } from "@hpcc-js/wasm-graphviz";
+
+//#region src/layout/graphviz.ts
+const POINTS_PER_INCH = 72;
+const DOT_KEYWORDS = new Set([
+	"node",
+	"edge",
+	"graph",
+	"digraph",
+	"subgraph",
+	"strict"
+]);
+function escapeId(id) {
+	if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(id) && !DOT_KEYWORDS.has(id.toLowerCase())) return id;
+	return `"${id.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+function escapeLabel(label) {
+	return label.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n");
+}
+const DIRECTION_TO_RANKDIR = {
+	down: "TB",
+	up: "BT",
+	right: "LR",
+	left: "RL"
+};
+function parsePoint(pos) {
+	const [x, y] = pos.split(",").map(Number);
+	return {
+		x,
+		y
+	};
+}
+/**
+* Parse a Graphviz spline `pos` string into route points (tail → head),
+* including the arrow endpoints: `s,x,y` (tail arrow tip) is prepended and
+* `e,x,y` (head arrow tip) is appended to the b-spline control points.
+*/
+function parseSplinePos(pos) {
+	let start;
+	let end;
+	const controls = [];
+	for (const token of pos.trim().split(/\s+/)) if (token.startsWith("e,")) end = parsePoint(token.slice(2));
+	else if (token.startsWith("s,")) start = parsePoint(token.slice(2));
+	else controls.push(parsePoint(token));
+	const points = [...controls];
+	if (start) points.unshift(start);
+	if (end) points.push(end);
+	return points;
+}
+let graphvizPromise;
+/**
+* Lay out a graph with Graphviz (via `@hpcc-js/wasm-graphviz`, an optional
+* peer dependency). Pure: returns a new {@link VisualGraph} with node
+* positions/sizes, routed edge `points` (`routing: 'splines'` — Graphviz
+* b-spline control points, tail → head, endpoints included), and computed
+* edge label rects (edge `x`/`y`).
+*
+* Node sizes are resolved via {@link getNodeSize} and passed to Graphviz as
+* fixed sizes, so layout never depends on Graphviz's own text measurement.
+*
+* Notes:
+* - Compound graphs (`parentId`) are not supported — use `getElkLayout`, or
+*   `getFlattenedGraph()` the graph first. (Graphviz clusters: planned.)
+* - In a directed graph, edges with `mode: 'undirected'` are laid out as
+*   directed but drawn without arrowheads (`dir=none`); in an undirected
+*   graph, per-edge `mode: 'directed'` overrides are ignored (DOT `graph`
+*   has no directed edge operator).
+* - `options.seed` maps to the Graphviz `start` attribute (used by the
+*   randomized engines neato/fdp/sfdp; ignored by deterministic engines).
+* - `options.constraints.layer` maps to `{ rank=same; … }` groups (`dot`
+*   engine only — the other engines have no rank concept).
+*
+* @example
+* ```ts
+* import { getGraphvizLayout } from '@statelyai/graph/layout/graphviz';
+*
+* const laidOut = await getGraphvizLayout(graph, {
+*   engine: 'dot',
+*   measure: (node) => measureText(node.label),
+* });
+* ```
+*/
+async function getGraphvizLayout(graph, options) {
+	const compoundNode = graph.nodes.find((node) => node.parentId != null);
+	if (compoundNode) throw new Error(`getGraphvizLayout: compound graphs are not supported by the Graphviz adapter yet (node "${compoundNode.id}" has parentId "${compoundNode.parentId}"). Use getElkLayout for hierarchical layout, or getFlattenedGraph() the graph first.`);
+	const engine = options?.engine ?? "dot";
+	const isDirected = graph.mode !== "undirected";
+	const direction = options?.direction ?? graph.direction;
+	const sizes = new Map(graph.nodes.map((node) => [node.id, getNodeSize(node, options)]));
+	const lines = [];
+	lines.push(`${isDirected ? "digraph" : "graph"} ${escapeId(graph.id)} {`);
+	if (direction) lines.push(`  rankdir=${DIRECTION_TO_RANKDIR[direction] ?? "TB"};`);
+	if (options?.spacing?.node !== void 0) lines.push(`  nodesep=${options.spacing.node / POINTS_PER_INCH};`);
+	if (options?.spacing?.layer !== void 0) lines.push(`  ranksep=${options.spacing.layer / POINTS_PER_INCH};`);
+	if (options?.seed !== void 0) lines.push(`  start=${options.seed};`);
+	for (const [key, value] of Object.entries(options?.graphAttributes ?? {})) lines.push(`  ${escapeId(key)}="${escapeLabel(value)}";`);
+	for (const node of graph.nodes) {
+		const { width, height } = sizes.get(node.id);
+		lines.push(`  ${escapeId(node.id)} [width=${width / POINTS_PER_INCH}, height=${height / POINTS_PER_INCH}, fixedsize=true, shape=box];`);
+	}
+	const layerOf = options?.constraints?.layer;
+	if (engine === "dot" && layerOf) {
+		const layers = /* @__PURE__ */ new Map();
+		for (const node of graph.nodes) {
+			const layer = layerOf(node);
+			if (layer === void 0) continue;
+			let ids = layers.get(layer);
+			if (ids === void 0) layers.set(layer, ids = []);
+			ids.push(node.id);
+		}
+		for (const [, ids] of [...layers].sort((a, b) => a[0] - b[0])) lines.push(`  { rank=same; ${ids.map(escapeId).join("; ")}; }`);
+	}
+	for (const edge of graph.edges) {
+		const attrs = [];
+		if (edge.label) attrs.push(`label="${escapeLabel(edge.label)}"`);
+		if (isDirected && edge.mode === "undirected") attrs.push("dir=none");
+		const attrStr = attrs.length > 0 ? ` [${attrs.join(", ")}]` : "";
+		lines.push(`  ${escapeId(edge.sourceId)} ${isDirected ? "->" : "--"} ${escapeId(edge.targetId)}${attrStr};`);
+	}
+	lines.push("}");
+	const dot = lines.join("\n");
+	const graphviz = await (graphvizPromise ??= Graphviz.load());
+	let outputJson;
+	try {
+		outputJson = graphviz.layout(dot, "json", engine);
+	} catch (e) {
+		throw new Error(`getGraphvizLayout: Graphviz (engine "${engine}") failed — ${e instanceof Error ? e.message : String(e)}`);
+	}
+	const output = JSON.parse(outputJson);
+	const yMax = output.bb ? Number(output.bb.split(",")[3]) : 0;
+	const flip = (p) => ({
+		x: p.x,
+		y: yMax - p.y
+	});
+	const objectsByName = new Map((output.objects ?? []).map((obj) => [obj.name, obj]));
+	const outputEdges = output.edges ?? [];
+	return createVisualGraph({
+		id: graph.id,
+		mode: graph.mode,
+		initialNodeId: graph.initialNodeId ?? void 0,
+		direction,
+		data: graph.data,
+		...graph.style !== void 0 && { style: graph.style },
+		nodes: graph.nodes.map((node) => {
+			const config = toNodeConfig(node);
+			const obj = objectsByName.get(node.id);
+			const size = sizes.get(node.id);
+			const width = obj?.width !== void 0 ? Number(obj.width) * POINTS_PER_INCH : size.width;
+			const height = obj?.height !== void 0 ? Number(obj.height) * POINTS_PER_INCH : size.height;
+			if (obj?.pos !== void 0) {
+				const center = flip(parsePoint(obj.pos));
+				config.x = center.x - width / 2;
+				config.y = center.y - height / 2;
+			}
+			config.width = width;
+			config.height = height;
+			return config;
+		}),
+		edges: graph.edges.map((edge, i) => {
+			const config = toEdgeConfig(edge);
+			const out = outputEdges[i];
+			if (out?.pos !== void 0) {
+				config.points = parseSplinePos(out.pos).map(flip);
+				config.routing = "splines";
+			}
+			if (out?.lp !== void 0) {
+				const center = flip(parsePoint(out.lp));
+				config.x = center.x - (edge.width ?? 0) / 2;
+				config.y = center.y - (edge.height ?? 0) / 2;
+			}
+			return config;
+		})
+	});
+}
+
+//#endregion
+export { getGraphvizLayout };

package/dist/layout/index.d.mts

@@ -0,0 +1,185 @@
+import { I as VisualGraph, d as EntityRect, f as Graph, k as Point, y as GraphNode } from "../types-BAEQTwK_.mjs";
+
+//#region src/layout/index.d.ts
+
+/**
+ * Common options understood by every layout adapter. Engine-specific options
+ * extend this per adapter.
+ */
+interface LayoutOptions {
+  /**
+   * Layout direction. Defaults to `graph.direction ?? 'down'`.
+   */
+  direction?: 'up' | 'down' | 'left' | 'right';
+  /**
+   * Spacing hints (engines map these to their native options where the
+   * mapping is well-defined; engines without one ignore them — see each
+   * adapter's JSDoc).
+   */
+  spacing?: {
+    /** Space between sibling nodes. */
+    node?: number;
+    /** Space between layers/ranks (hierarchical engines). */
+    layer?: number;
+  };
+  /**
+   * Node size resolver. Text measurement belongs to the renderer, so layout
+   * adapters never guess: sizes come from this callback, falling back to the
+   * node's own `width`/`height`, falling back to {@link DEFAULT_NODE_SIZE}.
+   */
+  measure?: (node: GraphNode) => {
+    width: number;
+    height: number;
+  };
+  /**
+   * Pinned nodes keep their current `x`/`y` (for engines that support
+   * fixing, e.g. d3-force `fx`/`fy`).
+   */
+  isFixed?: (node: GraphNode) => boolean;
+  /** Seed for engines with randomness — same seed, same layout. */
+  seed?: number;
+  /**
+   * Portable layout constraints. **Advisory**, like port `direction`: engines
+   * that can express a constraint honor it, others ignore it. Per-adapter
+   * support is documented on each adapter.
+   */
+  constraints?: LayoutConstraints;
+}
+/**
+ * Portable constraints understood by (some) layout adapters.
+ *
+ * | Constraint | ELK | Graphviz (dot) | dagre | force engines |
+ * |------------|-----|----------------|-------|----------------|
+ * | `layer`    | partitions | `rank=same` groups | ignored | ignored |
+ */
+interface LayoutConstraints {
+  /**
+   * Assign nodes to ordered layers along the flow axis (`0`, `1`, `2`, …;
+   * `undefined` leaves the node unconstrained). Nodes with the same value
+   * land in the same layer; smaller values come earlier in the layout
+   * direction. ELK maps this to partitions
+   * (`elk.partitioning.partition`); the Graphviz `dot` engine maps it to
+   * `{ rank=same; … }` groups (same-layer grouping — ordering *between*
+   * constrained layers still follows the edges).
+   */
+  layer?: (node: GraphNode) => number | undefined;
+}
+/**
+ * A one-shot layout: pure function from graph to a positioned
+ * {@link VisualGraph}. Async when the engine is async (ELK, Graphviz WASM) —
+ * engine async-ness is not ours to hide.
+ */
+type LayoutFn<O extends LayoutOptions = LayoutOptions> = (graph: Graph | VisualGraph, options?: O) => VisualGraph | Promise<VisualGraph>;
+/**
+ * One frame of an iterative (physics) layout: node positions by id, plus the
+ * simulation's remaining energy. Positions are node *top-left* corners,
+ * consistent with `VisualNode.x/y`.
+ */
+interface LayoutFrame {
+  positions: Record<string, Point>;
+  /** Remaining simulation energy, 1 → 0. */
+  alpha: number;
+}
+/**
+ * An iterative layout (force simulations): each `next()` advances one tick
+ * and yields a {@link LayoutFrame}; the caller owns pacing (e.g. one tick per
+ * animation frame) and cancellation (drop the generator). The generator's
+ * return value is the settled {@link VisualGraph}.
+ */
+type IterativeLayoutFn<O extends LayoutOptions = LayoutOptions> = (graph: Graph | VisualGraph, options?: O) => Generator<LayoutFrame, VisualGraph>;
+/** Fallback node size when neither `measure` nor node dimensions are set. */
+declare const DEFAULT_NODE_SIZE: {
+  readonly width: 100;
+  readonly height: 50;
+};
+/**
+ * Resolve a node's layout size: `options.measure` → node `width`/`height` →
+ * {@link DEFAULT_NODE_SIZE}. Zero sizes count as unset (layout engines
+ * overlap zero-sized nodes).
+ */
+declare function getNodeSize(node: GraphNode, options?: Pick<LayoutOptions, 'measure'>): {
+  width: number;
+  height: number;
+};
+/**
+ * **Mutable.** Write a {@link LayoutFrame}'s positions onto the graph's nodes
+ * in place. Positions are non-structural, so this is safe under the index
+ * contract (no `invalidateIndex` needed) and cheap enough for per-animation-
+ * frame use. Nodes absent from the frame are left untouched.
+ *
+ * @example
+ * ```ts
+ * for (const frame of genForceLayout(graph)) {
+ *   applyLayoutFrame(graph, frame);
+ *   render(graph);
+ * }
+ * ```
+ */
+declare function applyLayoutFrame(graph: Graph, frame: LayoutFrame): void;
+/**
+ * Bounding rect of all positioned nodes (and edge route points, when
+ * present). Returns a zero rect for graphs with no geometry.
+ *
+ * @example
+ * ```ts
+ * const bounds = getLayoutBounds(laidOut);
+ * svg.setAttribute('viewBox', `${bounds.x} ${bounds.y} ${bounds.width} ${bounds.height}`);
+ * ```
+ */
+declare function getLayoutBounds(graph: Graph | VisualGraph): EntityRect;
+interface LayoutTransitionOptions {
+  /** Number of frames to yield. Default: 30. */
+  steps?: number;
+  /**
+   * Easing function mapping linear progress `t` (0 → 1] to eased progress.
+   * Default: smoothstep (`t² · (3 − 2t)`).
+   */
+  ease?: (t: number) => number;
+}
+/**
+ * Animate between two layouts of the same graph: yields interpolated
+ * {@link LayoutFrame}s from the node positions in `from` to those in `to`
+ * (drive them with {@link applyLayoutFrame}, e.g. one per animation frame),
+ * and returns `to`. This is what makes layouts swappable live — lay out with
+ * one engine, re-lay out with another, and tween between them.
+ *
+ * Nodes are matched by id; nodes without a position in `from` (or absent from
+ * it) start at their `to` position. Edge routes are not interpolated — frames
+ * carry node positions only; hide or re-route edges during the transition.
+ * `alpha` cools linearly 1 → 0 like the physics layouts.
+ *
+ * @example
+ * ```ts
+ * const next = await getElkLayout(graph);
+ * for (const frame of genLayoutTransition(graph, next)) {
+ *   applyLayoutFrame(graph, frame);
+ *   render(graph);
+ * }
+ * ```
+ */
+declare function genLayoutTransition(from: Graph | VisualGraph, to: VisualGraph, options?: LayoutTransitionOptions): Generator<LayoutFrame, VisualGraph>;
+/**
+ * **Mutable.** Shift the graph's geometry by `(dx, dy)` in place: node
+ * positions, edge route `points`, and edge label rects. Non-structural, so no
+ * index invalidation is needed.
+ *
+ * Hierarchy-aware: child nodes (`parentId` set) use parent-relative
+ * coordinates (the ELK/xyflow convention), so only top-level nodes are
+ * shifted — children move with their parents. Likewise, an edge's geometry is
+ * shifted only when its containing coordinate system is the root (the LCA of
+ * its endpoints is no node).
+ */
+declare function translateGraph(graph: Graph, dx: number, dy: number): void;
+/**
+ * **Mutable.** Translate the graph in place so its {@link getLayoutBounds}
+ * center coincides with `rect`'s center — e.g. center a fresh layout in the
+ * viewport. Graphs without geometry are left untouched.
+ *
+ * @example
+ * ```ts
+ * centerGraph(laidOut, { x: 0, y: 0, width: canvas.width, height: canvas.height });
+ * ```
+ */
+declare function centerGraph(graph: Graph, rect: EntityRect): void;
+//#endregion
+export { DEFAULT_NODE_SIZE, IterativeLayoutFn, LayoutConstraints, LayoutFn, LayoutFrame, LayoutOptions, LayoutTransitionOptions, applyLayoutFrame, centerGraph, genLayoutTransition, getLayoutBounds, getNodeSize, translateGraph };

package/dist/layout/index.mjs

@@ -0,0 +1,181 @@
+import { d as getLCA } from "../queries-BMM0XAv_.mjs";
+
+//#region src/layout/index.ts
+/** Fallback node size when neither `measure` nor node dimensions are set. */
+const DEFAULT_NODE_SIZE = {
+	width: 100,
+	height: 50
+};
+/**
+* Resolve a node's layout size: `options.measure` → node `width`/`height` →
+* {@link DEFAULT_NODE_SIZE}. Zero sizes count as unset (layout engines
+* overlap zero-sized nodes).
+*/
+function getNodeSize(node, options) {
+	const measured = options?.measure?.(node);
+	if (measured) return measured;
+	const width = node.width !== void 0 && node.width > 0 ? node.width : 0;
+	const height = node.height !== void 0 && node.height > 0 ? node.height : 0;
+	return {
+		width: width || DEFAULT_NODE_SIZE.width,
+		height: height || DEFAULT_NODE_SIZE.height
+	};
+}
+/**
+* **Mutable.** Write a {@link LayoutFrame}'s positions onto the graph's nodes
+* in place. Positions are non-structural, so this is safe under the index
+* contract (no `invalidateIndex` needed) and cheap enough for per-animation-
+* frame use. Nodes absent from the frame are left untouched.
+*
+* @example
+* ```ts
+* for (const frame of genForceLayout(graph)) {
+*   applyLayoutFrame(graph, frame);
+*   render(graph);
+* }
+* ```
+*/
+function applyLayoutFrame(graph, frame) {
+	for (const node of graph.nodes) {
+		const position = frame.positions[node.id];
+		if (position !== void 0) {
+			node.x = position.x;
+			node.y = position.y;
+		}
+	}
+}
+/**
+* Bounding rect of all positioned nodes (and edge route points, when
+* present). Returns a zero rect for graphs with no geometry.
+*
+* @example
+* ```ts
+* const bounds = getLayoutBounds(laidOut);
+* svg.setAttribute('viewBox', `${bounds.x} ${bounds.y} ${bounds.width} ${bounds.height}`);
+* ```
+*/
+function getLayoutBounds(graph) {
+	let minX = Infinity;
+	let minY = Infinity;
+	let maxX = -Infinity;
+	let maxY = -Infinity;
+	for (const node of graph.nodes) {
+		if (node.x === void 0 || node.y === void 0) continue;
+		minX = Math.min(minX, node.x);
+		minY = Math.min(minY, node.y);
+		maxX = Math.max(maxX, node.x + (node.width ?? 0));
+		maxY = Math.max(maxY, node.y + (node.height ?? 0));
+	}
+	for (const edge of graph.edges) for (const point of edge.points ?? []) {
+		minX = Math.min(minX, point.x);
+		minY = Math.min(minY, point.y);
+		maxX = Math.max(maxX, point.x);
+		maxY = Math.max(maxY, point.y);
+	}
+	if (minX === Infinity) return {
+		x: 0,
+		y: 0,
+		width: 0,
+		height: 0
+	};
+	return {
+		x: minX,
+		y: minY,
+		width: maxX - minX,
+		height: maxY - minY
+	};
+}
+/**
+* Animate between two layouts of the same graph: yields interpolated
+* {@link LayoutFrame}s from the node positions in `from` to those in `to`
+* (drive them with {@link applyLayoutFrame}, e.g. one per animation frame),
+* and returns `to`. This is what makes layouts swappable live — lay out with
+* one engine, re-lay out with another, and tween between them.
+*
+* Nodes are matched by id; nodes without a position in `from` (or absent from
+* it) start at their `to` position. Edge routes are not interpolated — frames
+* carry node positions only; hide or re-route edges during the transition.
+* `alpha` cools linearly 1 → 0 like the physics layouts.
+*
+* @example
+* ```ts
+* const next = await getElkLayout(graph);
+* for (const frame of genLayoutTransition(graph, next)) {
+*   applyLayoutFrame(graph, frame);
+*   render(graph);
+* }
+* ```
+*/
+function* genLayoutTransition(from, to, options) {
+	const steps = Math.max(1, Math.floor(options?.steps ?? 30));
+	const ease = options?.ease ?? ((t) => t * t * (3 - 2 * t));
+	const fromById = new Map(from.nodes.map((node) => [node.id, node]));
+	const tweens = to.nodes.map((node) => {
+		const fromNode = fromById.get(node.id);
+		const hasStart = fromNode?.x !== void 0 && fromNode.y !== void 0;
+		return {
+			id: node.id,
+			startX: hasStart ? fromNode.x : node.x,
+			startY: hasStart ? fromNode.y : node.y,
+			endX: node.x,
+			endY: node.y
+		};
+	});
+	for (let step = 1; step <= steps; step++) {
+		const t = ease(step / steps);
+		const positions = {};
+		for (const tween of tweens) positions[tween.id] = {
+			x: tween.startX + (tween.endX - tween.startX) * t,
+			y: tween.startY + (tween.endY - tween.startY) * t
+		};
+		yield {
+			positions,
+			alpha: 1 - step / steps
+		};
+	}
+	return to;
+}
+/**
+* **Mutable.** Shift the graph's geometry by `(dx, dy)` in place: node
+* positions, edge route `points`, and edge label rects. Non-structural, so no
+* index invalidation is needed.
+*
+* Hierarchy-aware: child nodes (`parentId` set) use parent-relative
+* coordinates (the ELK/xyflow convention), so only top-level nodes are
+* shifted — children move with their parents. Likewise, an edge's geometry is
+* shifted only when its containing coordinate system is the root (the LCA of
+* its endpoints is no node).
+*/
+function translateGraph(graph, dx, dy) {
+	for (const node of graph.nodes) {
+		if (node.parentId != null) continue;
+		if (node.x !== void 0) node.x += dx;
+		if (node.y !== void 0) node.y += dy;
+	}
+	for (const edge of graph.edges) {
+		if (getLCA(graph, edge.sourceId, edge.targetId) !== void 0) continue;
+		if (edge.x !== void 0) edge.x += dx;
+		if (edge.y !== void 0) edge.y += dy;
+		for (const point of edge.points ?? []) {
+			point.x += dx;
+			point.y += dy;
+		}
+	}
+}
+/**
+* **Mutable.** Translate the graph in place so its {@link getLayoutBounds}
+* center coincides with `rect`'s center — e.g. center a fresh layout in the
+* viewport. Graphs without geometry are left untouched.
+*
+* @example
+* ```ts
+* centerGraph(laidOut, { x: 0, y: 0, width: canvas.width, height: canvas.height });
+* ```
+*/
+function centerGraph(graph, rect) {
+	const bounds = getLayoutBounds(graph);
+	translateGraph(graph, rect.x + rect.width / 2 - (bounds.x + bounds.width / 2), rect.y + rect.height / 2 - (bounds.y + bounds.height / 2));
+}
+
+//#endregion
+export { DEFAULT_NODE_SIZE, applyLayoutFrame, centerGraph, genLayoutTransition, getLayoutBounds, getNodeSize, translateGraph };

package/dist/layout/webcola.d.mts

@@ -0,0 +1,40 @@
+import { I as VisualGraph, f as Graph } from "../types-BAEQTwK_.mjs";
+import { LayoutOptions } from "./index.mjs";
+
+//#region src/layout/webcola.d.ts
+interface ColaLayoutOptions extends LayoutOptions {
+  /** Target distance between linked nodes. Default: 80. */
+  linkDistance?: number;
+}
+/**
+ * Constraint-based layout via WebCola (optional peer dependency). Runs the
+ * solver to convergence synchronously (`keepRunning: false`) and returns a
+ * positioned {@link VisualGraph}.
+ *
+ * - Overlap avoidance is always on: node rects (from `options.measure` →
+ *   node `width`/`height` → defaults) are kept disjoint.
+ * - Deterministic: WebCola itself has no `Math.random` in its 2D solver
+ *   (its descent uses an internally seeded PRNG), so the seeded initial
+ *   scatter (`options.seed`) fully pins the result — same seed, same layout.
+ * - `options.isFixed` pins positioned nodes at their current `x`/`y` (cola's
+ *   `fixed` flag). During overlap projection cola holds fixed nodes with a
+ *   large-but-finite weight, so pinning is within a small tolerance, not
+ *   exact.
+ * - `options.direction ?? graph.direction` set → DAG-flow constraints via
+ *   cola's `flowLayout`: edges are separated along the axis ('down'/'up' →
+ *   `y`, 'left'/'right' → `x`) by at least `spacing.layer` (default 50).
+ *   Note: cola only separates source-before-target along the axis — 'up' and
+ *   'left' flow the same way as 'down'/'right', not reversed.
+ * - Hierarchy is ignored (flat layout); self-loops are skipped by the solver
+ *   but kept in the output graph.
+ *
+ * @example
+ * ```ts
+ * import { getColaLayout } from '@statelyai/graph/layout/webcola';
+ *
+ * const laidOut = getColaLayout(graph, { seed: 42, direction: 'down' });
+ * ```
+ */
+declare function getColaLayout(graph: Graph | VisualGraph, options?: ColaLayoutOptions): VisualGraph;
+//#endregion
+export { ColaLayoutOptions, getColaLayout };

package/dist/layout/webcola.mjs

@@ -0,0 +1,104 @@
+import { f as createVisualGraph, n as toNodeConfig, t as toEdgeConfig } from "../config-Dt5u1gSf.mjs";
+import { getNodeSize } from "./index.mjs";
+import { Layout } from "webcola";
+
+//#region src/layout/webcola.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;
+	};
+}
+/**
+* Constraint-based layout via WebCola (optional peer dependency). Runs the
+* solver to convergence synchronously (`keepRunning: false`) and returns a
+* positioned {@link VisualGraph}.
+*
+* - Overlap avoidance is always on: node rects (from `options.measure` →
+*   node `width`/`height` → defaults) are kept disjoint.
+* - Deterministic: WebCola itself has no `Math.random` in its 2D solver
+*   (its descent uses an internally seeded PRNG), so the seeded initial
+*   scatter (`options.seed`) fully pins the result — same seed, same layout.
+* - `options.isFixed` pins positioned nodes at their current `x`/`y` (cola's
+*   `fixed` flag). During overlap projection cola holds fixed nodes with a
+*   large-but-finite weight, so pinning is within a small tolerance, not
+*   exact.
+* - `options.direction ?? graph.direction` set → DAG-flow constraints via
+*   cola's `flowLayout`: edges are separated along the axis ('down'/'up' →
+*   `y`, 'left'/'right' → `x`) by at least `spacing.layer` (default 50).
+*   Note: cola only separates source-before-target along the axis — 'up' and
+*   'left' flow the same way as 'down'/'right', not reversed.
+* - Hierarchy is ignored (flat layout); self-loops are skipped by the solver
+*   but kept in the output graph.
+*
+* @example
+* ```ts
+* import { getColaLayout } from '@statelyai/graph/layout/webcola';
+*
+* const laidOut = getColaLayout(graph, { seed: 42, direction: 'down' });
+* ```
+*/
+function getColaLayout(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 colaNodes = graph.nodes.map((node) => {
+		const size = getNodeSize(node, options);
+		sizes.set(node.id, size);
+		const colaNode = {
+			id: node.id,
+			...size
+		};
+		if (node.x !== void 0 && node.y !== void 0) {
+			colaNode.x = node.x + size.width / 2;
+			colaNode.y = node.y + size.height / 2;
+			if (options?.isFixed?.(node)) colaNode.fixed = 1;
+		} else {
+			const angle = rng() * 2 * Math.PI;
+			const radius = scatterRadius * Math.sqrt(rng());
+			colaNode.x = Math.cos(angle) * radius;
+			colaNode.y = Math.sin(angle) * radius;
+		}
+		return colaNode;
+	});
+	const indexById = new Map(graph.nodes.map((node, i) => [node.id, i]));
+	const colaLinks = graph.edges.filter((edge) => indexById.has(edge.sourceId) && indexById.has(edge.targetId) && edge.sourceId !== edge.targetId).map((edge) => ({
+		source: indexById.get(edge.sourceId),
+		target: indexById.get(edge.targetId)
+	}));
+	const layout = new Layout().nodes(colaNodes).links(colaLinks).linkDistance(options?.linkDistance ?? 80).avoidOverlaps(true);
+	const direction = options?.direction ?? graph.direction;
+	if (direction !== void 0) {
+		const axis = direction === "left" || direction === "right" ? "x" : "y";
+		layout.flowLayout(axis, options?.spacing?.layer ?? 50);
+	}
+	const centerGraph = !colaNodes.some((colaNode) => colaNode.fixed);
+	layout.start(30, 30, 60, 0, false, centerGraph);
+	const byId = new Map(colaNodes.map((colaNode) => [colaNode.id, colaNode]));
+	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 colaNode = byId.get(node.id);
+			return {
+				...toNodeConfig(node),
+				...size,
+				x: (colaNode.x ?? 0) - size.width / 2,
+				y: (colaNode.y ?? 0) - size.height / 2
+			};
+		}),
+		edges: graph.edges.map((edge) => toEdgeConfig(edge))
+	});
+}
+
+//#endregion
+export { getColaLayout };