@statelyai/graph 1.0.0 → 2.1.0

package/dist/layout/elk.d.mts

@@ -0,0 +1,47 @@
+import { I as VisualGraph, f as Graph } from "../types-BAEQTwK_.mjs";
+import { LayoutOptions } from "./index.mjs";
+import { ElkNode } from "elkjs/lib/elk-api";
+
+//#region src/layout/elk.d.ts
+/** Minimal interface an injected ELK instance must satisfy. */
+interface ElkLike {
+  layout(graph: ElkNode): Promise<ElkNode>;
+}
+interface ElkLayoutOptions extends LayoutOptions {
+  /**
+   * ELK algorithm. Common choices: `'layered'` (default), `'mrtree'`,
+   * `'force'`, `'stress'`, `'radial'`, `'rectpacking'`.
+   */
+  algorithm?: string;
+  /**
+   * Raw ELK layout options, spread onto the root last (override everything).
+   * See https://eclipse.dev/elk/reference/options.html
+   */
+  layoutOptions?: Record<string, string>;
+  /**
+   * Injected ELK instance — e.g. one constructed with a web worker factory.
+   * Defaults to `new ELK()` (in-process).
+   */
+  elk?: ElkLike;
+}
+/**
+ * Lay out a graph with ELK (via `elkjs`, an optional peer dependency).
+ * Pure: returns a new {@link VisualGraph} with node positions/sizes, routed
+ * edge `points`, and computed edge label rects (edge `x`/`y`/`width`/`height`).
+ * Hierarchy (`parentId`) and ports are first-class — ELK is the engine of
+ * choice for compound and port-aware graphs. Child node coordinates are
+ * relative to their parent (matching xyflow's convention).
+ *
+ * @example
+ * ```ts
+ * import { getElkLayout } from '@statelyai/graph/layout/elk';
+ *
+ * const laidOut = await getElkLayout(graph, {
+ *   algorithm: 'layered',
+ *   measure: (node) => measureText(node.label),
+ * });
+ * ```
+ */
+declare function getElkLayout(graph: Graph | VisualGraph, options?: ElkLayoutOptions): Promise<VisualGraph>;
+//#endregion
+export { ElkLayoutOptions, ElkLike, getElkLayout };

package/dist/layout/elk.mjs

@@ -0,0 +1,73 @@
+import { f as createVisualGraph, n as toNodeConfig, t as toEdgeConfig } from "../config-Dt5u1gSf.mjs";
+import { fromELK, toELK } from "../formats/elk/index.mjs";
+import { getNodeSize } from "./index.mjs";
+import ELK from "elkjs";
+
+//#region src/layout/elk.ts
+let defaultElk;
+/**
+* Lay out a graph with ELK (via `elkjs`, an optional peer dependency).
+* Pure: returns a new {@link VisualGraph} with node positions/sizes, routed
+* edge `points`, and computed edge label rects (edge `x`/`y`/`width`/`height`).
+* Hierarchy (`parentId`) and ports are first-class — ELK is the engine of
+* choice for compound and port-aware graphs. Child node coordinates are
+* relative to their parent (matching xyflow's convention).
+*
+* @example
+* ```ts
+* import { getElkLayout } from '@statelyai/graph/layout/elk';
+*
+* const laidOut = await getElkLayout(graph, {
+*   algorithm: 'layered',
+*   measure: (node) => measureText(node.label),
+* });
+* ```
+*/
+async function getElkLayout(graph, options) {
+	const sized = 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) => ({
+			...toNodeConfig(node),
+			...getNodeSize(node, options)
+		})),
+		edges: graph.edges.map((edge) => toEdgeConfig(edge))
+	});
+	const root = toELK(sized);
+	const layerOf = options?.constraints?.layer;
+	let hasPartitions = false;
+	if (layerOf) {
+		const nodeById = new Map(sized.nodes.map((node) => [node.id, node]));
+		const stack = [...root.children ?? []];
+		while (stack.length > 0) {
+			const child = stack.pop();
+			const node = nodeById.get(child.id);
+			const layer = node === void 0 ? void 0 : layerOf(node);
+			if (layer !== void 0) {
+				hasPartitions = true;
+				child.layoutOptions = {
+					...child.layoutOptions,
+					"elk.partitioning.partition": String(layer)
+				};
+			}
+			stack.push(...child.children ?? []);
+		}
+	}
+	root.layoutOptions = {
+		"elk.algorithm": options?.algorithm ?? "layered",
+		...hasPartitions && { "elk.partitioning.activate": "true" },
+		...options?.spacing?.node !== void 0 && { "elk.spacing.nodeNode": String(options.spacing.node) },
+		...options?.spacing?.layer !== void 0 && { "elk.layered.spacing.nodeNodeBetweenLayers": String(options.spacing.layer) },
+		...options?.seed !== void 0 && { "elk.randomSeed": String(options.seed) },
+		...root.layoutOptions,
+		...options?.layoutOptions
+	};
+	return fromELK(await (options?.elk ?? (defaultElk ??= new ELK())).layout(root));
+}
+
+//#endregion
+export { getElkLayout };

package/dist/layout/forceatlas2.d.mts

@@ -0,0 +1,48 @@
+import { I as VisualGraph, f as Graph } from "../types-BAEQTwK_.mjs";
+import { LayoutOptions } from "./index.mjs";
+import { ForceAtlas2Settings } from "graphology-layout-forceatlas2";
+
+//#region src/layout/forceatlas2.d.ts
+interface ForceAtlas2LayoutOptions extends LayoutOptions {
+  /** Number of ForceAtlas2 iterations. Default: 100. */
+  iterations?: number;
+  /**
+   * Pass-through engine settings (`scalingRatio`, `gravity`, `linLogMode`,
+   * `barnesHutOptimize`, …). See graphology-layout-forceatlas2.
+   */
+  settings?: ForceAtlas2Settings;
+}
+/**
+ * One-shot ForceAtlas2 layout via graphology (optional peer dependencies
+ * `graphology` + `graphology-layout-forceatlas2`). Runs the synchronous
+ * engine for `options.iterations` iterations and returns a positioned
+ * {@link VisualGraph}.
+ *
+ * - Deterministic: FA2 itself has no randomness, but it requires initial
+ *   positions. Positioned nodes start from their current centers
+ *   (incremental relayout); unpositioned nodes start in a seeded scatter
+ *   driven by `options.seed` — the same seed always produces the same
+ *   layout.
+ * - `options.isFixed` pins positioned nodes at their current `x`/`y` via
+ *   FA2's `fixed` node attribute (honored natively by the engine).
+ * - Per-edge `weight` feeds FA2's attraction (its default edge-weight
+ *   getter reads the `weight` attribute; tune with
+ *   `settings.edgeWeightInfluence`).
+ * - Self-loops are skipped (zero-distance edges destabilize the forces);
+ *   parallel edges are kept (multigraph). Hierarchy is ignored (force
+ *   layouts are flat).
+ *
+ * @example
+ * ```ts
+ * import { getForceAtlas2Layout } from '@statelyai/graph/layout/forceatlas2';
+ *
+ * const laidOut = getForceAtlas2Layout(graph, {
+ *   seed: 42,
+ *   iterations: 200,
+ *   settings: { gravity: 2 },
+ * });
+ * ```
+ */
+declare function getForceAtlas2Layout(graph: Graph | VisualGraph, options?: ForceAtlas2LayoutOptions): VisualGraph;
+//#endregion
+export { ForceAtlas2LayoutOptions, getForceAtlas2Layout };

package/dist/layout/forceatlas2.mjs

@@ -0,0 +1,100 @@
+import { f as createVisualGraph, n as toNodeConfig, t as toEdgeConfig } from "../config-Dt5u1gSf.mjs";
+import { getNodeSize } from "./index.mjs";
+import GraphologyGraph from "graphology";
+import forceAtlas2 from "graphology-layout-forceatlas2";
+
+//#region src/layout/forceatlas2.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;
+	};
+}
+/**
+* One-shot ForceAtlas2 layout via graphology (optional peer dependencies
+* `graphology` + `graphology-layout-forceatlas2`). Runs the synchronous
+* engine for `options.iterations` iterations and returns a positioned
+* {@link VisualGraph}.
+*
+* - Deterministic: FA2 itself has no randomness, but it requires initial
+*   positions. Positioned nodes start from their current centers
+*   (incremental relayout); unpositioned nodes start in a seeded scatter
+*   driven by `options.seed` — the same seed always produces the same
+*   layout.
+* - `options.isFixed` pins positioned nodes at their current `x`/`y` via
+*   FA2's `fixed` node attribute (honored natively by the engine).
+* - Per-edge `weight` feeds FA2's attraction (its default edge-weight
+*   getter reads the `weight` attribute; tune with
+*   `settings.edgeWeightInfluence`).
+* - Self-loops are skipped (zero-distance edges destabilize the forces);
+*   parallel edges are kept (multigraph). Hierarchy is ignored (force
+*   layouts are flat).
+*
+* @example
+* ```ts
+* import { getForceAtlas2Layout } from '@statelyai/graph/layout/forceatlas2';
+*
+* const laidOut = getForceAtlas2Layout(graph, {
+*   seed: 42,
+*   iterations: 200,
+*   settings: { gravity: 2 },
+* });
+* ```
+*/
+function getForceAtlas2Layout(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 engineGraph = new GraphologyGraph({ multi: true });
+	for (const node of graph.nodes) {
+		const size = getNodeSize(node, options);
+		sizes.set(node.id, size);
+		if (node.x !== void 0 && node.y !== void 0) engineGraph.addNode(node.id, {
+			x: node.x + size.width / 2,
+			y: node.y + size.height / 2,
+			...options?.isFixed?.(node) && { fixed: true }
+		});
+		else {
+			const angle = rng() * 2 * Math.PI;
+			const radius = scatterRadius * Math.sqrt(rng());
+			engineGraph.addNode(node.id, {
+				x: Math.cos(angle) * radius,
+				y: Math.sin(angle) * radius
+			});
+		}
+	}
+	for (const edge of graph.edges) {
+		if (!sizes.has(edge.sourceId) || !sizes.has(edge.targetId) || edge.sourceId === edge.targetId) continue;
+		engineGraph.addEdgeWithKey(edge.id, edge.sourceId, edge.targetId, edge.weight !== void 0 ? { weight: edge.weight } : {});
+	}
+	const positions = forceAtlas2(engineGraph, {
+		iterations: options?.iterations ?? 100,
+		...options?.settings !== void 0 && { settings: options.settings }
+	});
+	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 position = positions[node.id];
+			return {
+				...toNodeConfig(node),
+				...size,
+				x: position.x - size.width / 2,
+				y: position.y - size.height / 2
+			};
+		}),
+		edges: graph.edges.map((edge) => toEdgeConfig(edge))
+	});
+}
+
+//#endregion
+export { getForceAtlas2Layout };

package/dist/layout/graphviz.d.mts

@@ -0,0 +1,50 @@
+import { I as VisualGraph, f as Graph } from "../types-BAEQTwK_.mjs";
+import { LayoutOptions } from "./index.mjs";
+
+//#region src/layout/graphviz.d.ts
+/** Graphviz layout engines supported by the adapter. */
+type GraphvizEngine = 'dot' | 'neato' | 'fdp' | 'sfdp' | 'circo' | 'twopi' | 'osage' | 'patchwork';
+interface GraphvizLayoutOptions extends LayoutOptions {
+  /** Graphviz layout engine. Defaults to `'dot'`. */
+  engine?: GraphvizEngine;
+  /**
+   * Raw Graphviz graph attributes, emitted last (override everything).
+   * See https://graphviz.org/doc/info/attrs.html
+   */
+  graphAttributes?: Record<string, string>;
+}
+/**
+ * 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),
+ * });
+ * ```
+ */
+declare function getGraphvizLayout(graph: Graph | VisualGraph, options?: GraphvizLayoutOptions): Promise<VisualGraph>;
+//#endregion
+export { GraphvizEngine, GraphvizLayoutOptions, getGraphvizLayout };

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 };