@statelyai/graph 0.13.0 → 2.0.0

package/dist/{algorithms-BNDQcHU3.mjs → algorithms-DF1pSQGv.mjs}

@@ -1,4 +1,5 @@
-import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-DUl3kTqm.mjs";
+import { A as indexAddNode, M as indexUpdateEdgeEndpoints, N as invalidateIndex, O as getIndex, P as touchIndex, j as indexReparentNode, k as indexAddEdge, l as getInDegree, p as getOutDegree, r as getDegree } from "./queries-KirMDR7e.mjs";
+import { t as getEdgeMode } from "./mode-D8OnHFBk.mjs";
 
 //#region src/graph.ts
 /**
@@ -88,6 +89,7 @@ function createGraphEdge(config) {
 	};
 	if (config.sourcePort !== void 0) edge.sourcePort = config.sourcePort;
 	if (config.targetPort !== void 0) edge.targetPort = config.targetPort;
+	if (config.mode !== void 0) edge.mode = config.mode;
 	if (config.weight !== void 0) edge.weight = config.weight;
 	if (config.x !== void 0) edge.x = config.x;
 	if (config.y !== void 0) edge.y = config.y;
@@ -111,7 +113,7 @@ function createGraphEdge(config) {
 function createGraph(config) {
 	const graph = {
 		id: config?.id ?? "",
-		type: config?.type ?? "directed",
+		mode: config?.mode ?? "directed",
 		initialNodeId: config?.initialNodeId ?? null,
 		nodes: (config?.nodes ?? []).map(createGraphNode),
 		edges: (config?.edges ?? []).map(createGraphEdge),
@@ -244,7 +246,7 @@ function createGraphFromTransition(transition, options) {
 	}
 	return createGraph({
 		id: options.id ?? "",
-		type: "directed",
+		mode: "directed",
 		initialNodeId: initialStateId,
 		nodes,
 		edges
@@ -404,15 +406,46 @@ function deleteEdge(graph, id) {
 	graph.edges = graph.edges.filter((e) => e.id !== id);
 	invalidateIndex(graph);
 }
+/** Optional fields where `null` in an update unsets the field. */
+const NODE_OPTIONAL_KEYS = [
+	"x",
+	"y",
+	"width",
+	"height",
+	"shape",
+	"color",
+	"style"
+];
+const EDGE_OPTIONAL_KEYS = [
+	"weight",
+	"mode",
+	"x",
+	"y",
+	"width",
+	"height",
+	"color",
+	"style"
+];
+/** Apply optional-field updates: `null` unsets, a value sets, `undefined` is ignored. */
+function applyOptionalUpdates(target, update, keys) {
+	for (const key of keys) {
+		const value = update[key];
+		if (value === void 0) continue;
+		if (value === null) delete target[key];
+		else target[key] = value;
+	}
+}
 /**
 * **Mutable.** Update a node in place.
+* Optional fields (`x`, `y`, `width`, `height`, `shape`, `color`, `style`,
+* `ports`) accept `null` to unset; `undefined` leaves them unchanged.
 * @returns The updated node.
 *
 * @example
 * ```ts
 * const graph = createGraph({ nodes: [{ id: 'a', label: 'old' }] });
-* const updated = updateNode(graph, 'a', { label: 'new' });
-* // updated.label === 'new'
+* const updated = updateNode(graph, 'a', { label: 'new', x: 100 });
+* // updated.label === 'new', updated.x === 100
 * ```
 */
 function updateNode(graph, id, update) {
@@ -421,24 +454,48 @@ function updateNode(graph, id, update) {
 	if (arrayIdx === void 0) throw new Error(`Node "${id}" does not exist`);
 	if (update.parentId !== void 0 && update.parentId !== null) {
 		if (!idx.nodeById.has(update.parentId)) throw new Error(`Parent node "${update.parentId}" does not exist`);
+		let ancestorId = update.parentId;
+		const seen = /* @__PURE__ */ new Set();
+		while (ancestorId !== null && !seen.has(ancestorId)) {
+			if (ancestorId === id) throw new Error(`Cannot set parentId of node "${id}" to "${update.parentId}": "${update.parentId}" is "${id}" or one of its descendants, which would create a hierarchy cycle. Reparent "${update.parentId}" elsewhere first.`);
+			seen.add(ancestorId);
+			const ai = idx.nodeById.get(ancestorId);
+			ancestorId = ai !== void 0 ? graph.nodes[ai].parentId ?? null : null;
+		}
 	}
-	if (update.ports !== void 0 && update.ports.length > 0) validatePortNames(update.ports);
+	if (update.ports != null && update.ports.length > 0) validatePortNames(update.ports);
 	const node = graph.nodes[arrayIdx];
+	if (update.ports !== void 0) {
+		const newPortNames = new Set((update.ports ?? []).map((p) => p.name));
+		for (const eid of idx.outEdges.get(id) ?? []) {
+			const e = graph.edges[idx.edgeById.get(eid)];
+			if (e.sourcePort !== void 0 && !newPortNames.has(e.sourcePort)) throw new Error(`Cannot update ports of node "${id}": edge "${e.id}" references port "${e.sourcePort}" via sourcePort. Keep that port, or update/delete the edge first.`);
+		}
+		for (const eid of idx.inEdges.get(id) ?? []) {
+			const e = graph.edges[idx.edgeById.get(eid)];
+			if (e.targetPort !== void 0 && !newPortNames.has(e.targetPort)) throw new Error(`Cannot update ports of node "${id}": edge "${e.id}" references port "${e.targetPort}" via targetPort. Keep that port, or update/delete the edge first.`);
+		}
+	}
 	const oldParentId = node.parentId;
 	const updated = {
 		...node,
 		...update.parentId !== void 0 && { parentId: update.parentId ?? null },
 		...update.initialNodeId !== void 0 && { initialNodeId: update.initialNodeId ?? null },
 		...update.label !== void 0 && { label: update.label },
-		...update.data !== void 0 && { data: update.data },
-		...update.ports !== void 0 && { ports: update.ports.map(createGraphPort) }
+		...update.data !== void 0 && { data: update.data }
 	};
+	if (update.ports !== void 0) if (update.ports === null) delete updated.ports;
+	else updated.ports = update.ports.map(createGraphPort);
+	applyOptionalUpdates(updated, update, NODE_OPTIONAL_KEYS);
 	graph.nodes[arrayIdx] = updated;
 	if (update.parentId !== void 0 && updated.parentId !== oldParentId) indexReparentNode(idx, id, oldParentId, updated.parentId);
 	return updated;
 }
 /**
 * **Mutable.** Update an edge in place.
+* Optional fields (`weight`, `mode`, `sourcePort`, `targetPort`, `x`, `y`,
+* `width`, `height`, `color`, `style`) accept `null` to unset; `undefined`
+* leaves them unchanged.
 * @returns The updated edge.
 *
 * @example
@@ -447,8 +504,8 @@ function updateNode(graph, id, update) {
 *   nodes: [{ id: 'a' }, { id: 'b' }],
 *   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b', label: 'old' }],
 * });
-* const updated = updateEdge(graph, 'e1', { label: 'new' });
-* // updated.label === 'new'
+* const updated = updateEdge(graph, 'e1', { label: 'new', weight: 2 });
+* // updated.label === 'new', updated.weight === 2
 * ```
 */
 function updateEdge(graph, id, update) {
@@ -462,22 +519,28 @@ function updateEdge(graph, id, update) {
 	const oldTargetId = edge.targetId;
 	const effectiveSourceId = update.sourceId ?? edge.sourceId;
 	const effectiveTargetId = update.targetId ?? edge.targetId;
-	if (update.sourcePort !== void 0) {
-		if (!graph.nodes[idx.nodeById.get(effectiveSourceId)].ports?.some((p) => p.name === update.sourcePort)) throw new Error(`Port "${update.sourcePort}" does not exist on source node "${effectiveSourceId}"`);
+	const effectiveSourcePort = update.sourcePort !== void 0 ? update.sourcePort ?? void 0 : edge.sourcePort;
+	const effectiveTargetPort = update.targetPort !== void 0 ? update.targetPort ?? void 0 : edge.targetPort;
+	if (effectiveSourcePort !== void 0) {
+		if (!graph.nodes[idx.nodeById.get(effectiveSourceId)].ports?.some((p) => p.name === effectiveSourcePort)) throw new Error(update.sourcePort !== void 0 ? `Port "${effectiveSourcePort}" does not exist on source node "${effectiveSourceId}"` : `Cannot update edge "${id}": its sourcePort "${effectiveSourcePort}" does not exist on the new source node "${effectiveSourceId}". Include sourcePort in the update (a port on "${effectiveSourceId}", or null to clear it).`);
 	}
-	if (update.targetPort !== void 0) {
-		if (!graph.nodes[idx.nodeById.get(effectiveTargetId)].ports?.some((p) => p.name === update.targetPort)) throw new Error(`Port "${update.targetPort}" does not exist on target node "${effectiveTargetId}"`);
+	if (effectiveTargetPort !== void 0) {
+		if (!graph.nodes[idx.nodeById.get(effectiveTargetId)].ports?.some((p) => p.name === effectiveTargetPort)) throw new Error(update.targetPort !== void 0 ? `Port "${effectiveTargetPort}" does not exist on target node "${effectiveTargetId}"` : `Cannot update edge "${id}": its targetPort "${effectiveTargetPort}" does not exist on the new target node "${effectiveTargetId}". Include targetPort in the update (a port on "${effectiveTargetId}", or null to clear it).`);
 	}
 	const updated = {
 		...edge,
 		...update.sourceId !== void 0 && { sourceId: update.sourceId },
 		...update.targetId !== void 0 && { targetId: update.targetId },
 		...update.label !== void 0 && { label: update.label },
-		...update.data !== void 0 && { data: update.data },
-		...update.sourcePort !== void 0 && { sourcePort: update.sourcePort },
-		...update.targetPort !== void 0 && { targetPort: update.targetPort }
+		...update.data !== void 0 && { data: update.data }
 	};
+	if (update.sourcePort !== void 0) if (update.sourcePort === null) delete updated.sourcePort;
+	else updated.sourcePort = update.sourcePort;
+	if (update.targetPort !== void 0) if (update.targetPort === null) delete updated.targetPort;
+	else updated.targetPort = update.targetPort;
+	applyOptionalUpdates(updated, update, EDGE_OPTIONAL_KEYS);
 	graph.edges[arrayIdx] = updated;
+	if (update.mode !== void 0 || update.weight !== void 0) touchIndex(idx);
 	if (updated.sourceId !== oldSourceId || updated.targetId !== oldTargetId) indexUpdateEdgeEndpoints(idx, id, oldSourceId, oldTargetId, updated.sourceId, updated.targetId);
 	return updated;
 }
@@ -582,8 +645,9 @@ var GraphInstance = class GraphInstance {
 	get id() {
 		return this.graph.id;
 	}
-	get type() {
-		return this.graph.type;
+	/** Default directedness for all edges. */
+	get mode() {
+		return this.graph.mode;
 	}
 	get nodes() {
 		return this.graph.nodes;
@@ -663,6 +727,9 @@ var MinPriorityQueue = class {
 		this.items.push(item);
 		this.bubbleUp(this.items.length - 1);
 	}
+	peek() {
+		return this.items[0];
+	}
 	pop() {
 		if (this.items.length === 0) return void 0;
 		const first = this.items[0];
@@ -696,16 +763,35 @@ var MinPriorityQueue = class {
 		}
 	}
 };
-function getNeighborIds$1(graph, nodeId) {
+/**
+* Classify a graph by the *effective* mode of its edges (per-edge `mode`
+* overrides included): all-directed, all-non-directed, or genuinely mixed.
+* Edge-less graphs fall back to `graph.mode`.
+*/
+function getEffectiveModeKind(graph) {
+	let sawDirected = false;
+	let sawNonDirected = false;
+	for (const edge of graph.edges) {
+		if (getEdgeMode(graph, edge) === "directed") sawDirected = true;
+		else sawNonDirected = true;
+		if (sawDirected && sawNonDirected) return "mixed";
+	}
+	if (sawDirected) return "directed";
+	if (sawNonDirected) return "non-directed";
+	return graph.mode === "directed" ? "directed" : "non-directed";
+}
+function getNeighborIds(graph, nodeId) {
 	const idx = getIndex(graph);
 	const ids = [];
 	for (const eid of idx.outEdges.get(nodeId) ?? []) {
 		const ai = idx.edgeById.get(eid);
 		if (ai !== void 0) ids.push(graph.edges[ai].targetId);
 	}
-	if (graph.type === "undirected") for (const eid of idx.inEdges.get(nodeId) ?? []) {
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
 		const ai = idx.edgeById.get(eid);
-		if (ai !== void 0) ids.push(graph.edges[ai].sourceId);
+		if (ai === void 0) continue;
+		const edge = graph.edges[ai];
+		if (getEdgeMode(graph, edge) !== "directed") ids.push(edge.sourceId);
 	}
 	return ids;
 }
@@ -736,11 +822,11 @@ function getNeighborEdges(graph, nodeId) {
 			});
 		}
 	}
-	if (graph.type === "undirected") for (const eid of idx.inEdges.get(nodeId) ?? []) {
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
 		const ai = idx.edgeById.get(eid);
 		if (ai !== void 0) {
 			const edge = graph.edges[ai];
-			result.push({
+			if (getEdgeMode(graph, edge) !== "directed") result.push({
 				neighborId: edge.sourceId,
 				edge
 			});
@@ -774,67 +860,181 @@ function getNeighborEdgesAll(graph, nodeId) {
 	return result;
 }
 
+//#endregion
+//#region src/algorithms/csr.ts
+const csrCache = /* @__PURE__ */ new WeakMap();
+/** Get or lazily (re)build the CSR snapshot for a graph. */
+function getCSR(graph) {
+	const idx = getIndex(graph);
+	const cached = csrCache.get(idx);
+	if (cached && cached.version === idx.version && cached.mode === graph.mode) return cached.csr;
+	const csr = buildCSR(graph);
+	csrCache.set(idx, {
+		version: idx.version,
+		mode: graph.mode,
+		csr
+	});
+	return csr;
+}
+function buildCSR(graph) {
+	const n = graph.nodes.length;
+	const m = graph.edges.length;
+	const ids = new Array(n);
+	const indexOf = /* @__PURE__ */ new Map();
+	for (let i = 0; i < n; i++) {
+		ids[i] = graph.nodes[i].id;
+		indexOf.set(ids[i], i);
+	}
+	const srcPos = new Int32Array(m);
+	const tgtPos = new Int32Array(m);
+	const nonDirected = new Uint8Array(m);
+	const outCounts = new Int32Array(n);
+	const inCounts = new Int32Array(n);
+	let firstNegativeEdge = -1;
+	for (let e = 0; e < m; e++) {
+		const edge = graph.edges[e];
+		if (firstNegativeEdge === -1 && (edge.weight ?? 1) < 0) firstNegativeEdge = e;
+		const s = indexOf.get(edge.sourceId);
+		const t = indexOf.get(edge.targetId);
+		if (s === void 0 || t === void 0) {
+			srcPos[e] = -1;
+			tgtPos[e] = -1;
+			continue;
+		}
+		srcPos[e] = s;
+		tgtPos[e] = t;
+		const nd = getEdgeMode(graph, edge) !== "directed" ? 1 : 0;
+		nonDirected[e] = nd;
+		outCounts[s]++;
+		inCounts[t]++;
+		if (nd) {
+			outCounts[t]++;
+			inCounts[s]++;
+		}
+	}
+	const outOffsets = new Int32Array(n + 1);
+	const inOffsets = new Int32Array(n + 1);
+	for (let i = 0; i < n; i++) {
+		outOffsets[i + 1] = outOffsets[i] + outCounts[i];
+		inOffsets[i + 1] = inOffsets[i] + inCounts[i];
+	}
+	const outTargets = new Int32Array(outOffsets[n]);
+	const outEdgeIndex = new Int32Array(outOffsets[n]);
+	const inOrigins = new Int32Array(inOffsets[n]);
+	const inEdgeIndex = new Int32Array(inOffsets[n]);
+	const outCursor = outOffsets.slice(0, n);
+	const inCursor = inOffsets.slice(0, n);
+	for (let e = 0; e < m; e++) {
+		const s = srcPos[e];
+		const t = tgtPos[e];
+		if (s < 0) continue;
+		outTargets[outCursor[s]] = t;
+		outEdgeIndex[outCursor[s]++] = e;
+		inOrigins[inCursor[t]] = s;
+		inEdgeIndex[inCursor[t]++] = e;
+		if (nonDirected[e]) {
+			outTargets[outCursor[t]] = s;
+			outEdgeIndex[outCursor[t]++] = e;
+			inOrigins[inCursor[s]] = t;
+			inEdgeIndex[inCursor[s]++] = e;
+		}
+	}
+	return {
+		ids,
+		indexOf,
+		outOffsets,
+		outTargets,
+		outEdgeIndex,
+		inOffsets,
+		inOrigins,
+		inEdgeIndex,
+		firstNegativeEdge
+	};
+}
+
 //#endregion
 //#region src/algorithms/paths.ts
-function computeShortestDistances(graph, sourceId, getWeight, algorithm) {
+function computeShortestDistances(graph, sourceId, getWeight, algorithm, stopAtId) {
 	if (algorithm === "bellman-ford") return bellmanFord(graph, sourceId, getWeight);
 	const dist = /* @__PURE__ */ new Map();
 	const prev = /* @__PURE__ */ new Map();
 	dist.set(sourceId, 0);
 	prev.set(sourceId, []);
+	const csr = getCSR(graph);
+	const source = csr.indexOf.get(sourceId);
+	if (source === void 0) return {
+		dist,
+		prev
+	};
+	const n = csr.ids.length;
+	const distArr = new Float64Array(n).fill(Infinity);
+	const prevArr = new Array(n);
+	distArr[source] = 0;
+	prevArr[source] = [];
+	const stopAt = stopAtId !== void 0 ? csr.indexOf.get(stopAtId) : void 0;
+	let stopDistance = Infinity;
+	if (stopAt !== void 0) assertNoNegativeWeights(graph, csr, getWeight, "Dijkstra", "Use { algorithm: 'bellman-ford' } instead.");
 	if (!getWeight && !graph.edges.some((edge) => edge.weight !== void 0)) {
-		const queue = [sourceId];
-		while (queue.length > 0) {
-			const id = queue.shift();
-			const distance = dist.get(id);
-			for (const { neighborId, edge } of getNeighborEdges(graph, id)) {
-				const nextDistance = distance + 1;
-				const existing = dist.get(neighborId);
-				if (existing === void 0) {
-					dist.set(neighborId, nextDistance);
-					prev.set(neighborId, [{
-						from: id,
-						edge
-					}]);
-					queue.push(neighborId);
-				} else if (existing === nextDistance) prev.get(neighborId).push({
-					from: id,
-					edge
-				});
+		const queue = new Int32Array(n);
+		queue[0] = source;
+		let head = 0;
+		let tail = 1;
+		while (head < tail) {
+			const u = queue[head++];
+			if (distArr[u] > stopDistance) break;
+			if (u === stopAt) stopDistance = distArr[u];
+			const nextDistance = distArr[u] + 1;
+			for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) {
+				const v = csr.outTargets[a];
+				if (distArr[v] === Infinity) {
+					distArr[v] = nextDistance;
+					prevArr[v] = [u, csr.outEdgeIndex[a]];
+					queue[tail++] = v;
+				} else if (distArr[v] === nextDistance) prevArr[v].push(u, csr.outEdgeIndex[a]);
 			}
 		}
 	} else {
 		const effectiveWeight = getWeight ?? ((edge) => edge.weight ?? 1);
-		const visited = /* @__PURE__ */ new Set();
+		const visited = new Uint8Array(n);
 		const pq = new MinPriorityQueue((a, b) => a.dist - b.dist);
 		pq.push({
-			id: sourceId,
+			pos: source,
 			dist: 0
 		});
 		while (pq.size > 0) {
-			const { id, dist: distance } = pq.pop();
-			if (visited.has(id) || distance !== dist.get(id)) continue;
-			visited.add(id);
-			for (const { neighborId, edge } of getNeighborEdges(graph, id)) {
-				const nextDistance = distance + effectiveWeight(edge);
-				const existing = dist.get(neighborId);
-				if (existing === void 0 || nextDistance < existing) {
-					dist.set(neighborId, nextDistance);
-					prev.set(neighborId, [{
-						from: id,
-						edge
-					}]);
+			const { pos: u, dist: distance } = pq.pop();
+			if (visited[u] || distance !== distArr[u]) continue;
+			if (distance > stopDistance) break;
+			if (u === stopAt) stopDistance = distance;
+			visited[u] = 1;
+			for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) {
+				const edge = graph.edges[csr.outEdgeIndex[a]];
+				const weight = effectiveWeight(edge);
+				if (weight < 0) throw new Error(`Negative edge weight ${weight} on edge "${edge.sourceId}->${edge.targetId}" (id "${edge.id}"): Dijkstra requires non-negative weights. Use { algorithm: 'bellman-ford' } instead.`);
+				const v = csr.outTargets[a];
+				const nextDistance = distance + weight;
+				if (nextDistance < distArr[v]) {
+					distArr[v] = nextDistance;
+					prevArr[v] = [u, csr.outEdgeIndex[a]];
 					pq.push({
-						id: neighborId,
+						pos: v,
 						dist: nextDistance
 					});
-				} else if (existing === nextDistance) prev.get(neighborId).push({
-					from: id,
-					edge
-				});
+				} else if (nextDistance === distArr[v] && distArr[v] !== Infinity) prevArr[v].push(u, csr.outEdgeIndex[a]);
 			}
 		}
 	}
+	for (let i = 0; i < n; i++) {
+		if (distArr[i] === Infinity || distArr[i] > stopDistance) continue;
+		dist.set(csr.ids[i], distArr[i]);
+		const pairs = prevArr[i];
+		const predecessors = [];
+		for (let k = 0; k < pairs.length; k += 2) predecessors.push({
+			from: csr.ids[pairs[k]],
+			edge: graph.edges[pairs[k + 1]]
+		});
+		prev.set(csr.ids[i], predecessors);
+	}
 	return {
 		dist,
 		prev
@@ -844,7 +1044,6 @@ function bellmanFord(graph, sourceId, getWeight) {
 	const dist = /* @__PURE__ */ new Map();
 	const prev = /* @__PURE__ */ new Map();
 	const effectiveWeight = getWeight ?? ((edge) => edge.weight ?? 1);
-	const isUndirected = graph.type === "undirected";
 	for (const node of graph.nodes) {
 		dist.set(node.id, Infinity);
 		prev.set(node.id, []);
@@ -857,7 +1056,7 @@ function bellmanFord(graph, sourceId, getWeight) {
 			toId: edge.targetId,
 			edge
 		});
-		if (isUndirected) directedEdges.push({
+		if (getEdgeMode(graph, edge) !== "directed") directedEdges.push({
 			fromId: edge.targetId,
 			toId: edge.sourceId,
 			edge
@@ -901,7 +1100,7 @@ function bellmanFord(graph, sourceId, getWeight) {
 		prev
 	};
 }
-function* reconstructPaths(graph, prev, sourceNode, targetId) {
+function* reconstructPaths(graph, prev, sourceNode, targetId, onPath = /* @__PURE__ */ new Set()) {
 	if (targetId === sourceNode.id) {
 		yield {
 			source: sourceNode,
@@ -913,18 +1112,23 @@ function* reconstructPaths(graph, prev, sourceNode, targetId) {
 	if (!predecessors || predecessors.length === 0) return;
 	const targetNi = getIndex(graph).nodeById.get(targetId);
 	const targetNode = targetNi !== void 0 ? graph.nodes[targetNi] : graph.nodes.find((node) => node.id === targetId);
-	for (const { from, edge } of predecessors) for (const prefix of reconstructPaths(graph, prev, sourceNode, from)) yield {
-		source: sourceNode,
-		steps: [...prefix.steps, {
-			edge,
-			node: targetNode
-		}]
-	};
+	onPath.add(targetId);
+	for (const { from, edge } of predecessors) {
+		if (onPath.has(from)) continue;
+		for (const prefix of reconstructPaths(graph, prev, sourceNode, from, onPath)) yield {
+			source: sourceNode,
+			steps: [...prefix.steps, {
+				edge,
+				node: targetNode
+			}]
+		};
+	}
+	onPath.delete(targetId);
 }
 function* genShortestPaths(graph, opts) {
 	const idx = getIndex(graph);
 	const sourceId = resolveFrom(graph, opts);
-	const { dist, prev } = computeShortestDistances(graph, sourceId, opts?.getWeight, opts?.algorithm);
+	const { dist, prev } = computeShortestDistances(graph, sourceId, opts?.getWeight, opts?.algorithm, opts?.to);
 	const targets = opts?.to ? [opts.to].filter((id) => dist.has(id)) : [...dist.keys()].filter((id) => id !== sourceId);
 	const sourceNi = idx.nodeById.get(sourceId);
 	const sourceNode = sourceNi !== void 0 ? graph.nodes[sourceNi] : graph.nodes.find((node) => node.id === sourceId);
@@ -934,8 +1138,161 @@ function getShortestPaths(graph, opts) {
 	return [...genShortestPaths(graph, opts)];
 }
 function getShortestPath(graph, opts) {
+	if (opts.algorithm !== "bellman-ford") return bidirectionalShortestPath(graph, resolveFrom(graph, opts), opts.to, opts.getWeight);
 	for (const path of genShortestPaths(graph, opts)) return path;
 }
+/**
+* Sublinear searches (early-exit, bidirectional) may legitimately terminate
+* without ever scanning a negative edge, so the throw-on-negative contract
+* must be enforced up front: O(1) via the CSR's cached flag for the default
+* weight, or one O(edges) sweep for a custom `getWeight`.
+*/
+function assertNoNegativeWeights(graph, csr, getWeight, algorithmName, remedy) {
+	let offending;
+	let weight = 0;
+	if (getWeight === void 0) {
+		if (csr.firstNegativeEdge !== -1) {
+			offending = graph.edges[csr.firstNegativeEdge];
+			weight = offending.weight ?? 1;
+		}
+	} else for (const edge of graph.edges) {
+		const w = getWeight(edge);
+		if (w < 0) {
+			offending = edge;
+			weight = w;
+			break;
+		}
+	}
+	if (offending) throw new Error(`Negative edge weight ${weight} on edge "${offending.sourceId}->${offending.targetId}" (id "${offending.id}"): ${algorithmName} requires non-negative weights. ${remedy}`);
+}
+/**
+* Bidirectional Dijkstra for a single source→target query. Forward search
+* runs on the traversable arcs, backward search on the reverse arcs; `mu`
+* tracks the best meeting cost and the search stops when the two frontiers
+* prove no better meeting exists (Pohl's `topF + topB >= mu` condition).
+* Returns one shortest path (ties broken arbitrarily, as before).
+*/
+function bidirectionalShortestPath(graph, sourceId, targetId, getWeight) {
+	const csr = getCSR(graph);
+	const source = csr.indexOf.get(sourceId);
+	const target = csr.indexOf.get(targetId);
+	if (source === void 0 || target === void 0) return void 0;
+	const sourceNode = graph.nodes[source];
+	if (source === target) return {
+		source: sourceNode,
+		steps: []
+	};
+	assertNoNegativeWeights(graph, csr, getWeight, "Dijkstra", "Use { algorithm: 'bellman-ford' } instead.");
+	const effectiveWeight = getWeight ?? ((edge) => edge.weight ?? 1);
+	const n = csr.ids.length;
+	const distF = new Float64Array(n).fill(Infinity);
+	const distB = new Float64Array(n).fill(Infinity);
+	const predF = new Int32Array(n).fill(-1);
+	const predFEdge = new Int32Array(n).fill(-1);
+	const predB = new Int32Array(n).fill(-1);
+	const predBEdge = new Int32Array(n).fill(-1);
+	const settledF = new Uint8Array(n);
+	const settledB = new Uint8Array(n);
+	const compare = (a, b) => a.dist - b.dist;
+	const pqF = new MinPriorityQueue(compare);
+	const pqB = new MinPriorityQueue(compare);
+	distF[source] = 0;
+	distB[target] = 0;
+	pqF.push({
+		pos: source,
+		dist: 0
+	});
+	pqB.push({
+		pos: target,
+		dist: 0
+	});
+	let mu = Infinity;
+	let meet = -1;
+	/** Discard stale/settled heap entries; return the next valid key. */
+	const validTop = (pq, dist, settled) => {
+		for (;;) {
+			const top = pq.peek();
+			if (top === void 0) return void 0;
+			if (settled[top.pos] || top.dist !== dist[top.pos]) {
+				pq.pop();
+				continue;
+			}
+			return top.dist;
+		}
+	};
+	const scanForward = () => {
+		const { pos: u, dist: d } = pqF.pop();
+		settledF[u] = 1;
+		for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) {
+			const edge = graph.edges[csr.outEdgeIndex[a]];
+			const weight = effectiveWeight(edge);
+			const v = csr.outTargets[a];
+			const next = d + weight;
+			if (next < distF[v]) {
+				distF[v] = next;
+				predF[v] = u;
+				predFEdge[v] = csr.outEdgeIndex[a];
+				pqF.push({
+					pos: v,
+					dist: next
+				});
+			}
+			if (distB[v] !== Infinity && next + distB[v] < mu) {
+				mu = next + distB[v];
+				meet = v;
+			}
+		}
+	};
+	const scanBackward = () => {
+		const { pos: u, dist: d } = pqB.pop();
+		settledB[u] = 1;
+		for (let a = csr.inOffsets[u]; a < csr.inOffsets[u + 1]; a++) {
+			const edge = graph.edges[csr.inEdgeIndex[a]];
+			const weight = effectiveWeight(edge);
+			const v = csr.inOrigins[a];
+			const next = d + weight;
+			if (next < distB[v]) {
+				distB[v] = next;
+				predB[v] = u;
+				predBEdge[v] = csr.inEdgeIndex[a];
+				pqB.push({
+					pos: v,
+					dist: next
+				});
+			}
+			if (distF[v] !== Infinity && next + distF[v] < mu) {
+				mu = next + distF[v];
+				meet = v;
+			}
+		}
+	};
+	for (;;) {
+		const topF = validTop(pqF, distF, settledF);
+		const topB = validTop(pqB, distB, settledB);
+		if (topF === void 0 || topB === void 0) break;
+		if (topF + topB >= mu) break;
+		if (topF <= topB) scanForward();
+		else scanBackward();
+	}
+	if (meet === -1) return void 0;
+	const steps = [];
+	for (let v = meet; v !== source; v = predF[v]) steps.unshift({
+		edge: graph.edges[predFEdge[v]],
+		node: graph.nodes[v]
+	});
+	for (let v = meet; v !== target;) {
+		const nextNode = predB[v];
+		steps.push({
+			edge: graph.edges[predBEdge[v]],
+			node: graph.nodes[nextNode]
+		});
+		v = nextNode;
+	}
+	return {
+		source: sourceNode,
+		steps
+	};
+}
 function getSimplePaths(graph, opts) {
 	return [...genSimplePaths(graph, opts)];
 }
@@ -993,15 +1350,10 @@ function getStronglyConnectedComponents(graph) {
 		indexCounter++;
 		stack.push(id);
 		onStack.add(id);
-		for (const eid of idx.outEdges.get(id) ?? []) {
-			const ai = idx.edgeById.get(eid);
-			if (ai === void 0) continue;
-			const neighborId = graph.edges[ai].targetId;
-			if (!nodeIndex.has(neighborId)) {
-				strongconnect(neighborId);
-				lowlink.set(id, Math.min(lowlink.get(id), lowlink.get(neighborId)));
-			} else if (onStack.has(neighborId)) lowlink.set(id, Math.min(lowlink.get(id), nodeIndex.get(neighborId)));
-		}
+		for (const neighborId of getNeighborIds(graph, id)) if (!nodeIndex.has(neighborId)) {
+			strongconnect(neighborId);
+			lowlink.set(id, Math.min(lowlink.get(id), lowlink.get(neighborId)));
+		} else if (onStack.has(neighborId)) lowlink.set(id, Math.min(lowlink.get(id), nodeIndex.get(neighborId)));
 		if (lowlink.get(id) === nodeIndex.get(id)) {
 			const component = [];
 			let neighborId;
@@ -1021,7 +1373,9 @@ function getCycles(graph) {
 	return [...genCycles(graph)];
 }
 function* genCycles(graph) {
-	if (graph.type === "undirected") yield* genCyclesUndirected(graph);
+	const kind = getEffectiveModeKind(graph);
+	if (kind === "mixed") yield* genCyclesMixed(graph);
+	else if (kind === "non-directed") yield* genCyclesUndirected(graph);
 	else yield* genCyclesDirected(graph);
 }
 function* genCyclesDirected(graph) {
@@ -1077,17 +1431,14 @@ function* genCyclesUndirected(graph) {
 		const startNi = idx.nodeById.get(startId);
 		const startNode = graph.nodes[startNi];
 		const found = [];
-		function dfsFind(currentId, parentId) {
+		function dfsFind(currentId, arrivalEdgeId) {
 			visited.add(currentId);
 			for (const { neighborId, edge } of getNeighborEdgesAll(graph, currentId)) {
-				if (neighborId === parentId) {
-					parentId = null;
-					continue;
-				}
-				if (neighborId === startId && steps.length >= 2) {
-					const innerIds = steps.map((step) => step.node.id).sort().join(",");
-					if (!seen.has(innerIds)) {
-						seen.add(innerIds);
+				if (edge.id === arrivalEdgeId) continue;
+				if (neighborId === startId && (steps.length >= 1 || edge.sourceId === edge.targetId)) {
+					const cycleEdgeIds = [...steps.map((step) => step.edge.id), edge.id].sort().join(",");
+					if (!seen.has(cycleEdgeIds)) {
+						seen.add(cycleEdgeIds);
 						found.push({
 							source: startNode,
 							steps: [...steps, {
@@ -1102,7 +1453,7 @@ function* genCyclesUndirected(graph) {
 						edge,
 						node: graph.nodes[ni]
 					});
-					dfsFind(neighborId, currentId);
+					dfsFind(neighborId, edge.id);
 					steps.pop();
 				}
 			}
@@ -1112,6 +1463,59 @@ function* genCyclesUndirected(graph) {
 		yield* found;
 	}
 }
+/**
+* Exact simple-cycle enumeration for graphs mixing directed and non-directed
+* edges. Traverses directed edges source→target only and non-directed edges
+* both ways; a cycle may use each edge at most once, visits distinct nodes,
+* and is identified by its set of traversed edge ids.
+*/
+function* genCyclesMixed(graph) {
+	const idx = getIndex(graph);
+	const sortedIds = graph.nodes.map((node) => node.id).sort();
+	const seen = /* @__PURE__ */ new Set();
+	for (let startIndex = 0; startIndex < sortedIds.length; startIndex++) {
+		const startId = sortedIds[startIndex];
+		const allowed = new Set(sortedIds.slice(startIndex));
+		const visited = /* @__PURE__ */ new Set();
+		const steps = [];
+		const pathEdgeIds = /* @__PURE__ */ new Set();
+		const startNi = idx.nodeById.get(startId);
+		const startNode = graph.nodes[startNi];
+		const found = [];
+		function dfsFind(currentId) {
+			visited.add(currentId);
+			for (const { neighborId, edge } of getNeighborEdges(graph, currentId)) {
+				if (pathEdgeIds.has(edge.id)) continue;
+				if (neighborId === startId && (steps.length >= 1 || edge.sourceId === edge.targetId)) {
+					const cycleEdgeIds = [...steps.map((step) => step.edge.id), edge.id].sort().join(",");
+					if (!seen.has(cycleEdgeIds)) {
+						seen.add(cycleEdgeIds);
+						found.push({
+							source: startNode,
+							steps: [...steps, {
+								edge,
+								node: startNode
+							}]
+						});
+					}
+				} else if (allowed.has(neighborId) && !visited.has(neighborId)) {
+					const ni = idx.nodeById.get(neighborId);
+					steps.push({
+						edge,
+						node: graph.nodes[ni]
+					});
+					pathEdgeIds.add(edge.id);
+					dfsFind(neighborId);
+					pathEdgeIds.delete(edge.id);
+					steps.pop();
+				}
+			}
+			visited.delete(currentId);
+		}
+		dfsFind(startId);
+		yield* found;
+	}
+}
 function getAllPairsShortestPaths(graph, opts) {
 	const algorithm = opts?.algorithm ?? "dijkstra";
 	if (algorithm === "floyd-warshall") return floydWarshallAllPaths(graph, opts?.getWeight);
@@ -1160,7 +1564,7 @@ function floydWarshallAllPaths(graph, getWeight) {
 			from: source,
 			edge
 		});
-		if (graph.type === "undirected") {
+		if (getEdgeMode(graph, edge) !== "directed") {
 			if (edgeWeight < dist[target][source]) {
 				dist[target][source] = edgeWeight;
 				prev[target][source] = [{
@@ -1183,6 +1587,7 @@ function floydWarshallAllPaths(graph, getWeight) {
 			for (const entry of prev[k][j]) if (!prev[i][j].some((existing) => existing.edge.id === entry.edge.id)) prev[i][j].push({ ...entry });
 		}
 	}
+	for (let i = 0; i < nodeCount; i++) if (dist[i][i] < 0) throw new Error(`Negative cycle detected through node "${nodeIds[i]}": all-pairs shortest paths are undefined. Remove the negative cycle, or use getShortestPaths with { algorithm: 'bellman-ford' } per source to locate it.`);
 	const results = [];
 	for (let i = 0; i < nodeCount; i++) {
 		const sourceNi = idx.nodeById.get(nodeIds[i]);
@@ -1229,48 +1634,53 @@ function getAStarPath(graph, opts) {
 		source: graph.nodes[sourceNi],
 		steps: []
 	};
-	const gScore = /* @__PURE__ */ new Map();
-	const cameFrom = /* @__PURE__ */ new Map();
-	const closedSet = /* @__PURE__ */ new Set();
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	const source = csr.indexOf.get(sourceId);
+	const target = csr.indexOf.get(targetId);
+	const gScore = new Float64Array(n).fill(Infinity);
+	const cameFromPos = new Int32Array(n).fill(-1);
+	const cameFromEdge = new Int32Array(n).fill(-1);
+	const closed = new Uint8Array(n);
 	const openSet = new MinPriorityQueue((a, b) => a.f - b.f);
-	gScore.set(sourceId, 0);
+	assertNoNegativeWeights(graph, csr, opts.getWeight, "A*", "Use getShortestPath with { algorithm: 'bellman-ford' } instead.");
+	gScore[source] = 0;
 	openSet.push({
-		id: sourceId,
+		pos: source,
 		f: heuristic(sourceId)
 	});
 	while (openSet.size > 0) {
-		const { id: currentId } = openSet.pop();
-		if (closedSet.has(currentId)) continue;
-		if (currentId === targetId) {
+		const { pos: current } = openSet.pop();
+		if (closed[current]) continue;
+		if (current === target) {
 			const steps = [];
-			let current = targetId;
-			while (current !== sourceId) {
-				const previous = cameFrom.get(current);
-				const ni = idx.nodeById.get(current);
+			let cursor = target;
+			while (cursor !== source) {
 				steps.unshift({
-					edge: previous.edge,
-					node: graph.nodes[ni]
+					edge: graph.edges[cameFromEdge[cursor]],
+					node: graph.nodes[cursor]
 				});
-				current = previous.from;
+				cursor = cameFromPos[cursor];
 			}
 			return {
 				source: graph.nodes[sourceNi],
 				steps
 			};
 		}
-		closedSet.add(currentId);
-		for (const { neighborId, edge } of getNeighborEdges(graph, currentId)) {
-			if (closedSet.has(neighborId)) continue;
-			const tentativeScore = (gScore.get(currentId) ?? Infinity) + getWeight(edge);
-			if (tentativeScore < (gScore.get(neighborId) ?? Infinity)) {
-				cameFrom.set(neighborId, {
-					from: currentId,
-					edge
-				});
-				gScore.set(neighborId, tentativeScore);
+		closed[current] = 1;
+		for (let a = csr.outOffsets[current]; a < csr.outOffsets[current + 1]; a++) {
+			const edge = graph.edges[csr.outEdgeIndex[a]];
+			const weight = getWeight(edge);
+			const neighbor = csr.outTargets[a];
+			if (closed[neighbor]) continue;
+			const tentativeScore = gScore[current] + weight;
+			if (tentativeScore < gScore[neighbor]) {
+				cameFromPos[neighbor] = current;
+				cameFromEdge[neighbor] = csr.outEdgeIndex[a];
+				gScore[neighbor] = tentativeScore;
 				openSet.push({
-					id: neighborId,
-					f: tentativeScore + heuristic(neighborId)
+					pos: neighbor,
+					f: tentativeScore + heuristic(csr.ids[neighbor])
 				});
 			}
 		}
@@ -1285,40 +1695,289 @@ function joinPaths(headPath, tailPath) {
 	};
 }
 
+//#endregion
+//#region src/config.ts
+/**
+* Convert a resolved {@link GraphNode} back into a {@link NodeConfig}.
+*
+* Faithful and complete: round-tripping through `createGraphNode` yields a
+* deep-equal node. Optional fields are only included when present; ports are
+* deep-copied so the config does not share port objects with the source node.
+*/
+function toNodeConfig(node) {
+	const config = { id: node.id };
+	if (node.parentId != null) config.parentId = node.parentId;
+	if (node.initialNodeId != null) config.initialNodeId = node.initialNodeId;
+	if (node.label != null) config.label = node.label;
+	if (node.data != null) config.data = node.data;
+	if (node.ports !== void 0) config.ports = node.ports.map((p) => ({ ...p }));
+	if (node.x !== void 0) config.x = node.x;
+	if (node.y !== void 0) config.y = node.y;
+	if (node.width !== void 0) config.width = node.width;
+	if (node.height !== void 0) config.height = node.height;
+	if (node.shape !== void 0) config.shape = node.shape;
+	if (node.color !== void 0) config.color = node.color;
+	if (node.style !== void 0) config.style = node.style;
+	return config;
+}
+/**
+* Convert a resolved {@link GraphEdge} back into an {@link EdgeConfig}.
+*
+* Faithful and complete: round-tripping through `createGraphEdge` yields a
+* deep-equal edge. Optional fields are only included when present.
+*/
+function toEdgeConfig(edge) {
+	const config = {
+		id: edge.id,
+		sourceId: edge.sourceId,
+		targetId: edge.targetId
+	};
+	if (edge.label != null) config.label = edge.label;
+	if (edge.data != null) config.data = edge.data;
+	if (edge.weight !== void 0) config.weight = edge.weight;
+	if (edge.mode !== void 0) config.mode = edge.mode;
+	if (edge.sourcePort !== void 0) config.sourcePort = edge.sourcePort;
+	if (edge.targetPort !== void 0) config.targetPort = edge.targetPort;
+	if (edge.x !== void 0) config.x = edge.x;
+	if (edge.y !== void 0) config.y = edge.y;
+	if (edge.width !== void 0) config.width = edge.width;
+	if (edge.height !== void 0) config.height = edge.height;
+	if (edge.color !== void 0) config.color = edge.color;
+	if (edge.style !== void 0) config.style = edge.style;
+	return config;
+}
+
+//#endregion
+//#region src/transforms.ts
+/**
+* Flattens a hierarchical graph into a flat graph with only leaf nodes.
+*
+* - Edges targeting a compound node resolve to its initial child (recursively).
+* - Edges originating from a compound node expand to all leaf descendants.
+* - Only leaf nodes (nodes with no children) appear in the result.
+* - Duplicate edges (same source + target) are deduplicated.
+*
+* @example
+* ```ts
+* import { createGraph, flatten } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent', initialNodeId: 'child1' },
+*     { id: 'child1', parentId: 'parent' },
+*     { id: 'child2', parentId: 'parent' },
+*     { id: 'other' },
+*   ],
+*   edges: [{ id: 'e1', sourceId: 'other', targetId: 'parent' }],
+* });
+*
+* const flat = flatten(graph);
+* // flat.nodes → [child1, child2, other] (leaf nodes only)
+* // flat.edges → edge from 'other' → 'child1' (resolved via initialNodeId)
+* ```
+*/
+function flatten(graph) {
+	const idx = getIndex(graph);
+	const leaves = /* @__PURE__ */ new Set();
+	for (const node of graph.nodes) if ((idx.childNodes.get(node.id) ?? []).length === 0) leaves.add(node.id);
+	function resolveInitial(nodeId, seen = /* @__PURE__ */ new Set()) {
+		if (leaves.has(nodeId)) return nodeId;
+		if (seen.has(nodeId)) return null;
+		seen.add(nodeId);
+		const ni = idx.nodeById.get(nodeId);
+		if (ni === void 0) return null;
+		const node = graph.nodes[ni];
+		if (node.initialNodeId) return resolveInitial(node.initialNodeId, seen);
+		const childIds = idx.childNodes.get(nodeId) ?? [];
+		if (childIds.length > 0) return resolveInitial(childIds[0], seen);
+		return nodeId;
+	}
+	function getLeafDescendants(nodeId) {
+		if (leaves.has(nodeId)) return [nodeId];
+		const result = [];
+		const collect = (id) => {
+			const childIds = idx.childNodes.get(id) ?? [];
+			for (const childId of childIds) if (leaves.has(childId)) result.push(childId);
+			else collect(childId);
+		};
+		collect(nodeId);
+		return result;
+	}
+	const edgeSeen = /* @__PURE__ */ new Set();
+	const flatEdges = [];
+	for (const edge of graph.edges) {
+		const sources = leaves.has(edge.sourceId) ? [edge.sourceId] : getLeafDescendants(edge.sourceId);
+		const target = leaves.has(edge.targetId) ? edge.targetId : resolveInitial(edge.targetId);
+		if (target === null) continue;
+		for (const source of sources) {
+			const isAuthoredLeafSelfLoop = edge.sourceId === edge.targetId && leaves.has(edge.sourceId);
+			if (source === target && !isAuthoredLeafSelfLoop) continue;
+			const key = `${source}->${target}`;
+			if (edgeSeen.has(key)) continue;
+			edgeSeen.add(key);
+			flatEdges.push({
+				type: "edge",
+				id: `${edge.id}:${source}->${target}`,
+				sourceId: source,
+				targetId: target,
+				label: edge.label,
+				data: edge.data,
+				...edge.weight !== void 0 && { weight: edge.weight },
+				...edge.mode !== void 0 && { mode: edge.mode },
+				...source === edge.sourceId && edge.sourcePort !== void 0 && { sourcePort: edge.sourcePort },
+				...target === edge.targetId && edge.targetPort !== void 0 && { targetPort: edge.targetPort }
+			});
+		}
+	}
+	const leafNodes = graph.nodes.filter((n) => leaves.has(n.id)).map((n) => {
+		const { type, parentId, initialNodeId, ...rest } = n;
+		return rest;
+	});
+	return createGraph({
+		id: graph.id,
+		mode: graph.mode,
+		initialNodeId: graph.initialNodeId ? resolveInitial(graph.initialNodeId) ?? void 0 : void 0,
+		nodes: leafNodes,
+		edges: flatEdges,
+		data: graph.data
+	});
+}
+/**
+* Convert a node to a config, stripping parentId/initialNodeId references
+* to nodes outside the given set.
+*/
+function toScopedNodeConfig(node, nodeIdSet) {
+	const config = toNodeConfig(node);
+	if (nodeIdSet) {
+		if (config.parentId != null && !nodeIdSet.has(config.parentId)) delete config.parentId;
+		if (config.initialNodeId != null && !nodeIdSet.has(config.initialNodeId)) delete config.initialNodeId;
+	}
+	return config;
+}
+/**
+* Returns the induced subgraph containing only the given node IDs
+* and edges whose endpoints are both in the set.
+*
+* Parent references to nodes outside the set are removed.
+*
+* @example
+* ```ts
+* import { createGraph, getSubgraph } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+*
+* const sub = getSubgraph(graph, ['a', 'b']);
+* // sub.nodes: [a, b], sub.edges: [ab]
+* ```
+*/
+function getSubgraph(graph, nodeIds) {
+	const nodeIdSet = new Set(nodeIds);
+	return createGraph({
+		id: graph.id,
+		mode: graph.mode,
+		initialNodeId: graph.initialNodeId && nodeIdSet.has(graph.initialNodeId) ? graph.initialNodeId : void 0,
+		nodes: graph.nodes.filter((n) => nodeIdSet.has(n.id)).map((n) => toScopedNodeConfig(n, nodeIdSet)),
+		edges: graph.edges.filter((e) => nodeIdSet.has(e.sourceId) && nodeIdSet.has(e.targetId)).map(toEdgeConfig),
+		data: graph.data
+	});
+}
+/**
+* Returns a new graph with all edge directions flipped (source ↔ target).
+* Optionally filters which edges to include.
+*
+* @example
+* ```ts
+* import { createGraph, reverseGraph } from '@statelyai/graph';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'ab', sourceId: 'a', targetId: 'b' },
+*     { id: 'bc', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+*
+* const rev = reverseGraph(graph);
+* // rev edges: b→a, c→b
+*
+* const filtered = reverseGraph(graph, (e) => e.id !== 'bc');
+* // filtered edges: b→a (only ab reversed, bc excluded)
+* ```
+*/
+function reverseGraph(graph, filterEdge) {
+	const edges = filterEdge ? graph.edges.filter(filterEdge) : graph.edges;
+	return createGraph({
+		id: graph.id,
+		mode: graph.mode,
+		initialNodeId: graph.initialNodeId ?? void 0,
+		nodes: graph.nodes.map((n) => toNodeConfig(n)),
+		edges: edges.map((e) => {
+			const config = toEdgeConfig(e);
+			config.sourceId = e.targetId;
+			config.targetId = e.sourceId;
+			delete config.sourcePort;
+			delete config.targetPort;
+			if (e.targetPort !== void 0) config.sourcePort = e.targetPort;
+			if (e.sourcePort !== void 0) config.targetPort = e.sourcePort;
+			return config;
+		}),
+		data: graph.data
+	});
+}
+
 //#endregion
 //#region src/algorithms/traversal.ts
 function* bfs(graph, startId) {
-	const idx = getIndex(graph);
-	const visited = /* @__PURE__ */ new Set();
-	const queue = [startId];
-	visited.add(startId);
-	while (queue.length > 0) {
-		const id = queue.shift();
-		const ni = idx.nodeById.get(id);
-		if (ni === void 0) continue;
-		yield graph.nodes[ni];
-		for (const neighborId of getNeighborIds$1(graph, id)) if (!visited.has(neighborId)) {
-			visited.add(neighborId);
-			queue.push(neighborId);
+	const csr = getCSR(graph);
+	const start = csr.indexOf.get(startId);
+	if (start === void 0) return;
+	const n = csr.ids.length;
+	const visited = new Uint8Array(n);
+	const queue = new Int32Array(n);
+	visited[start] = 1;
+	queue[0] = start;
+	let head = 0;
+	let tail = 1;
+	while (head < tail) {
+		const u = queue[head++];
+		yield graph.nodes[u];
+		for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) {
+			const v = csr.outTargets[a];
+			if (!visited[v]) {
+				visited[v] = 1;
+				queue[tail++] = v;
+			}
 		}
 	}
 }
 function* dfs(graph, startId) {
-	const idx = getIndex(graph);
-	const visited = /* @__PURE__ */ new Set();
-	const stack = [startId];
+	const csr = getCSR(graph);
+	const start = csr.indexOf.get(startId);
+	if (start === void 0) return;
+	const n = csr.ids.length;
+	const visited = new Uint8Array(n);
+	const stack = [start];
 	while (stack.length > 0) {
-		const id = stack.pop();
-		if (visited.has(id)) continue;
-		visited.add(id);
-		const ni = idx.nodeById.get(id);
-		if (ni === void 0) continue;
-		yield graph.nodes[ni];
-		for (const neighborId of getNeighborIds$1(graph, id)) if (!visited.has(neighborId)) stack.push(neighborId);
+		const u = stack.pop();
+		if (visited[u]) continue;
+		visited[u] = 1;
+		yield graph.nodes[u];
+		for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) {
+			const v = csr.outTargets[a];
+			if (!visited[v]) stack.push(v);
+		}
 	}
 }
 function isAcyclic(graph) {
-	if (graph.type === "undirected") return isAcyclicUndirected(graph);
+	const kind = getEffectiveModeKind(graph);
+	if (kind === "mixed") return isAcyclicMixed(graph);
+	if (kind === "non-directed") return isAcyclicUndirected(graph);
 	const WHITE = 0;
 	const GRAY = 1;
 	const BLACK = 2;
@@ -1337,6 +1996,63 @@ function isAcyclic(graph) {
 	for (const node of graph.nodes) if (color.get(node.id) === WHITE && hasCycle(node.id)) return false;
 	return true;
 }
+/**
+* Acyclicity for graphs mixing directed and non-directed edges.
+*
+* Polynomial fast paths first: a cycle among directed edges alone, a cycle
+* among non-directed edges alone (union-find), or all-singleton reachability
+* SCCs (then no mixed cycle can exist either). Only ambiguous multi-node
+* SCCs fall back to exact simple-cycle enumeration, restricted to that SCC.
+*/
+function isAcyclicMixed(graph) {
+	const idx = getIndex(graph);
+	const WHITE = 0;
+	const GRAY = 1;
+	const BLACK = 2;
+	const color = /* @__PURE__ */ new Map();
+	for (const node of graph.nodes) color.set(node.id, WHITE);
+	const hasDirectedCycle = (id) => {
+		color.set(id, GRAY);
+		for (const eid of idx.outEdges.get(id) ?? []) {
+			const edge = graph.edges[idx.edgeById.get(eid)];
+			if (getEdgeMode(graph, edge) !== "directed") continue;
+			const current = color.get(edge.targetId);
+			if (current === GRAY) return true;
+			if (current === WHITE && hasDirectedCycle(edge.targetId)) return true;
+		}
+		color.set(id, BLACK);
+		return false;
+	};
+	for (const node of graph.nodes) if (color.get(node.id) === WHITE && hasDirectedCycle(node.id)) return false;
+	const parent = /* @__PURE__ */ new Map();
+	const find = (id) => {
+		let root = id;
+		while (parent.get(root) !== root) root = parent.get(root);
+		let cursor = id;
+		while (parent.get(cursor) !== root) {
+			const next = parent.get(cursor);
+			parent.set(cursor, root);
+			cursor = next;
+		}
+		return root;
+	};
+	for (const node of graph.nodes) parent.set(node.id, node.id);
+	for (const edge of graph.edges) {
+		if (getEdgeMode(graph, edge) === "directed") continue;
+		if (edge.sourceId === edge.targetId) return false;
+		const rootA = find(edge.sourceId);
+		const rootB = find(edge.targetId);
+		if (rootA === rootB) return false;
+		parent.set(rootA, rootB);
+	}
+	const multiNodeSccs = getStronglyConnectedComponents(graph).filter((component) => component.length > 1);
+	if (multiNodeSccs.length === 0) return true;
+	for (const component of multiNodeSccs) {
+		const subgraph = getSubgraph(graph, component.map((node) => node.id));
+		for (const _cycle of genCycles(subgraph)) return false;
+	}
+	return true;
+}
 function isAcyclicUndirected(graph) {
 	const idx = getIndex(graph);
 	const visited = /* @__PURE__ */ new Set();
@@ -1364,34 +2080,33 @@ function isAcyclicUndirected(graph) {
 	return true;
 }
 function getConnectedComponents(graph) {
-	const idx = getIndex(graph);
-	const visited = /* @__PURE__ */ new Set();
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	const visited = new Uint8Array(n);
+	const queue = new Int32Array(n);
 	const components = [];
-	for (const node of graph.nodes) {
-		if (visited.has(node.id)) continue;
+	for (let s = 0; s < n; s++) {
+		if (visited[s]) continue;
 		const component = [];
-		const queue = [node.id];
-		visited.add(node.id);
-		while (queue.length > 0) {
-			const id = queue.shift();
-			const ni = idx.nodeById.get(id);
-			if (ni !== void 0) component.push(graph.nodes[ni]);
-			for (const eid of idx.outEdges.get(id) ?? []) {
-				const ai = idx.edgeById.get(eid);
-				if (ai === void 0) continue;
-				const neighborId = graph.edges[ai].targetId;
-				if (!visited.has(neighborId)) {
-					visited.add(neighborId);
-					queue.push(neighborId);
+		visited[s] = 1;
+		queue[0] = s;
+		let head = 0;
+		let tail = 1;
+		while (head < tail) {
+			const u = queue[head++];
+			component.push(graph.nodes[u]);
+			for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) {
+				const v = csr.outTargets[a];
+				if (!visited[v]) {
+					visited[v] = 1;
+					queue[tail++] = v;
 				}
 			}
-			for (const eid of idx.inEdges.get(id) ?? []) {
-				const ai = idx.edgeById.get(eid);
-				if (ai === void 0) continue;
-				const neighborId = graph.edges[ai].sourceId;
-				if (!visited.has(neighborId)) {
-					visited.add(neighborId);
-					queue.push(neighborId);
+			for (let a = csr.inOffsets[u]; a < csr.inOffsets[u + 1]; a++) {
+				const v = csr.inOrigins[a];
+				if (!visited[v]) {
+					visited[v] = 1;
+					queue[tail++] = v;
 				}
 			}
 		}
@@ -1399,7 +2114,16 @@ function getConnectedComponents(graph) {
 	}
 	return components;
 }
+/**
+* Returns a topological ordering of the graph's nodes, or `null` if no such
+* ordering exists.
+*
+* Any edge whose effective mode (per {@link getEdgeMode}) is not `'directed'`
+* makes ordering impossible — an undirected/bidirectional edge is mutual
+* precedence, i.e. a 2-cycle — so the function returns `null`.
+*/
 function getTopologicalSort(graph) {
+	for (const edge of graph.edges) if (getEdgeMode(graph, edge) !== "directed") return null;
 	const idx = getIndex(graph);
 	const inDegree = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) inDegree.set(node.id, 0);
@@ -1424,17 +2148,33 @@ function getTopologicalSort(graph) {
 	return result;
 }
 function hasPath(graph, sourceId, targetId) {
-	return getShortestPaths(graph, {
-		from: sourceId,
-		to: targetId
-	}).length > 0;
+	if (sourceId === targetId) return true;
+	const visited = new Set([sourceId]);
+	const queue = [sourceId];
+	while (queue.length > 0) {
+		const id = queue.shift();
+		for (const neighborId of getNeighborIds(graph, id)) {
+			if (neighborId === targetId) return true;
+			if (!visited.has(neighborId)) {
+				visited.add(neighborId);
+				queue.push(neighborId);
+			}
+		}
+	}
+	return false;
 }
 function isConnected(graph) {
 	if (graph.nodes.length === 0) return true;
 	return getConnectedComponents(graph).length <= 1;
 }
+/**
+* Returns whether the graph is a tree: connected, acyclic, and with exactly
+* `nodes.length - 1` edges (so directed diamonds and parallel edges are not
+* trees). Empty and single-node graphs are considered trees.
+*/
 function isTree(graph) {
-	return isConnected(graph) && isAcyclic(graph);
+	if (graph.nodes.length === 0) return true;
+	return graph.edges.length === graph.nodes.length - 1 && isConnected(graph) && isAcyclic(graph);
 }
 
 //#endregion
@@ -1449,7 +2189,7 @@ function getPreorder(graph, opts) {
 	const stack = [startId];
 	while (stack.length > 0) {
 		const top = stack[stack.length - 1];
-		const next = getNeighborIds$1(graph, top).find((id) => !visited.has(id));
+		const next = getNeighborIds(graph, top).find((id) => !visited.has(id));
 		if (next === void 0) {
 			stack.pop();
 			continue;
@@ -1470,7 +2210,7 @@ function getPostorder(graph, opts) {
 	const stack = [startId];
 	while (stack.length > 0) {
 		const top = stack[stack.length - 1];
-		const next = getNeighborIds$1(graph, top).find((id) => !visited.has(id));
+		const next = getNeighborIds(graph, top).find((id) => !visited.has(id));
 		if (next === void 0) {
 			stack.pop();
 			const ni = idx.nodeById.get(top);
@@ -1506,7 +2246,7 @@ function* genPreorders(graph, opts) {
 		let branched = false;
 		while (dfsStack.length > 0) {
 			const top = dfsStack[dfsStack.length - 1];
-			const unvisited = getNeighborIds$1(graph, top).filter((id) => !visited.has(id));
+			const unvisited = getNeighborIds(graph, top).filter((id) => !visited.has(id));
 			if (unvisited.length === 0) {
 				dfsStack.pop();
 				continue;
@@ -1544,7 +2284,7 @@ function* genPostorders(graph, opts) {
 		let branched = false;
 		while (dfsStack.length > 0) {
 			const top = dfsStack[dfsStack.length - 1];
-			const unvisited = getNeighborIds$1(graph, top).filter((id) => !visited.has(id));
+			const unvisited = getNeighborIds(graph, top).filter((id) => !visited.has(id));
 			if (unvisited.length === 0) {
 				dfsStack.pop();
 				const ni = idx.nodeById.get(top);
@@ -1576,23 +2316,10 @@ function getMinimumSpanningTree(graph, opts) {
 	const mstEdges = algorithm === "kruskal" ? kruskalMST(graph, getWeight) : primMST(graph, getWeight);
 	return createGraph({
 		id: graph.id,
-		type: graph.type,
+		mode: graph.mode,
 		initialNodeId: graph.initialNodeId ?? void 0,
-		nodes: graph.nodes.map((node) => ({
-			id: node.id,
-			parentId: node.parentId ?? void 0,
-			initialNodeId: node.initialNodeId ?? void 0,
-			label: node.label,
-			data: node.data
-		})),
-		edges: mstEdges.map((edge) => ({
-			id: edge.id,
-			sourceId: edge.sourceId,
-			targetId: edge.targetId,
-			label: edge.label,
-			data: edge.data,
-			...edge.weight !== void 0 && { weight: edge.weight }
-		}))
+		nodes: graph.nodes.map((node) => toNodeConfig(node)),
+		edges: mstEdges.map((edge) => toEdgeConfig(edge))
 	});
 }
 function primMST(graph, getWeight) {
@@ -1611,26 +2338,28 @@ function primMST(graph, getWeight) {
 				edge
 			});
 		}
-		if (graph.type === "undirected") for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		for (const eid of idx.inEdges.get(nodeId) ?? []) {
 			const ai = idx.edgeById.get(eid);
 			if (ai === void 0) continue;
 			const edge = graph.edges[ai];
-			if (!inMST.has(edge.sourceId)) candidates.push({
+			if (getEdgeMode(graph, edge) !== "directed" && !inMST.has(edge.sourceId)) candidates.push({
 				weight: getWeight(edge),
 				edge
 			});
 		}
 	}
-	const startId = graph.nodes[0].id;
-	inMST.add(startId);
-	addEdgesOf(startId);
-	while (candidates.size > 0 && inMST.size < graph.nodes.length) {
-		const { edge } = candidates.pop();
-		const targetId = graph.type === "undirected" && inMST.has(edge.targetId) ? edge.sourceId : edge.targetId;
-		if (inMST.has(targetId)) continue;
-		inMST.add(targetId);
-		mstEdges.push(edge);
-		addEdgesOf(targetId);
+	for (const node of graph.nodes) {
+		if (inMST.has(node.id)) continue;
+		inMST.add(node.id);
+		addEdgesOf(node.id);
+		while (candidates.size > 0 && inMST.size < graph.nodes.length) {
+			const { edge } = candidates.pop();
+			const targetId = getEdgeMode(graph, edge) !== "directed" && inMST.has(edge.targetId) ? edge.sourceId : edge.targetId;
+			if (inMST.has(targetId)) continue;
+			inMST.add(targetId);
+			mstEdges.push(edge);
+			addEdgesOf(targetId);
+		}
 	}
 	return mstEdges;
 }
@@ -1668,60 +2397,38 @@ function kruskalMST(graph, getWeight) {
 function getNodeIds(graph) {
 	return graph.nodes.map((node) => node.id);
 }
-function getNeighborIds(graph, nodeId) {
-	const idx = getIndex(graph);
-	const neighbors = [];
-	for (const edgeId of idx.outEdges.get(nodeId) ?? []) {
-		const edgeIndex = idx.edgeById.get(edgeId);
-		if (edgeIndex !== void 0) neighbors.push(graph.edges[edgeIndex].targetId);
-	}
-	if (graph.type === "undirected") for (const edgeId of idx.inEdges.get(nodeId) ?? []) {
-		const edgeIndex = idx.edgeById.get(edgeId);
-		if (edgeIndex !== void 0) neighbors.push(graph.edges[edgeIndex].sourceId);
-	}
-	return neighbors;
-}
-function getIncomingIds(graph, nodeId) {
-	const idx = getIndex(graph);
-	const incoming = [];
-	for (const edgeId of idx.inEdges.get(nodeId) ?? []) {
-		const edgeIndex = idx.edgeById.get(edgeId);
-		if (edgeIndex !== void 0) incoming.push(graph.edges[edgeIndex].sourceId);
-	}
-	if (graph.type === "undirected") for (const edgeId of idx.outEdges.get(nodeId) ?? []) {
-		const edgeIndex = idx.edgeById.get(edgeId);
-		if (edgeIndex !== void 0) incoming.push(graph.edges[edgeIndex].targetId);
-	}
-	return incoming;
-}
 function createEmptyScoreMap(graph) {
 	return Object.fromEntries(graph.nodes.map((node) => [node.id, 0]));
 }
-function normalizeVector(scores) {
-	const magnitude = Math.sqrt(Object.values(scores).reduce((sum, value) => sum + value * value, 0));
-	if (magnitude === 0) return scores;
-	for (const key of Object.keys(scores)) scores[key] /= magnitude;
-	return scores;
-}
-function maxDiff(previous, next) {
-	let diff = 0;
-	for (const key of Object.keys(next)) diff = Math.max(diff, Math.abs((previous[key] ?? 0) - next[key]));
-	return diff;
+function normalizeTypedVector(values) {
+	let sumOfSquares = 0;
+	for (let i = 0; i < values.length; i++) sumOfSquares += values[i] * values[i];
+	const magnitude = Math.sqrt(sumOfSquares);
+	if (magnitude === 0) return;
+	for (let i = 0; i < values.length; i++) values[i] /= magnitude;
 }
-function getReachableDistances(graph, startId) {
-	const distances = /* @__PURE__ */ new Map();
-	const queue = [startId];
-	distances.set(startId, 0);
-	while (queue.length > 0) {
-		const currentId = queue.shift();
-		const currentDistance = distances.get(currentId);
-		for (const neighborId of getNeighborIds(graph, currentId)) {
-			if (distances.has(neighborId)) continue;
-			distances.set(neighborId, currentDistance + 1);
-			queue.push(neighborId);
+/**
+* BFS hop distances from a start position over the CSR arc snapshot.
+* `dist[i] === -1` means unreachable. Returns the visit count.
+*/
+function bfsDistances(csr, start, dist, queue) {
+	dist.fill(-1);
+	dist[start] = 0;
+	queue[0] = start;
+	let head = 0;
+	let tail = 1;
+	while (head < tail) {
+		const u = queue[head++];
+		const du = dist[u];
+		for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) {
+			const v = csr.outTargets[a];
+			if (dist[v] === -1) {
+				dist[v] = du + 1;
+				queue[tail++] = v;
+			}
 		}
 	}
-	return distances;
+	return tail;
 }
 /**
 * Returns degree centrality scores for all nodes.
@@ -1736,14 +2443,8 @@ function getReachableDistances(graph, startId) {
 */
 function getDegreeCentrality(graph) {
 	const scale = graph.nodes.length > 1 ? 1 / (graph.nodes.length - 1) : 0;
-	const idx = getIndex(graph);
 	const scores = createEmptyScoreMap(graph);
-	for (const node of graph.nodes) {
-		const outDegree = idx.outEdges.get(node.id)?.length ?? 0;
-		const inDegree = idx.inEdges.get(node.id)?.length ?? 0;
-		const degree = graph.type === "undirected" ? new Set([...idx.outEdges.get(node.id) ?? [], ...idx.inEdges.get(node.id) ?? []]).size : outDegree + inDegree;
-		scores[node.id] = degree * scale;
-	}
+	for (const node of graph.nodes) scores[node.id] = getDegree(graph, node.id) * scale;
 	return scores;
 }
 /**
@@ -1753,9 +2454,8 @@ function getDegreeCentrality(graph) {
 */
 function getInDegreeCentrality(graph) {
 	const scale = graph.nodes.length > 1 ? 1 / (graph.nodes.length - 1) : 0;
-	const idx = getIndex(graph);
 	const scores = createEmptyScoreMap(graph);
-	for (const node of graph.nodes) scores[node.id] = (idx.inEdges.get(node.id)?.length ?? 0) * scale;
+	for (const node of graph.nodes) scores[node.id] = getInDegree(graph, node.id) * scale;
 	return scores;
 }
 /**
@@ -1765,9 +2465,8 @@ function getInDegreeCentrality(graph) {
 */
 function getOutDegreeCentrality(graph) {
 	const scale = graph.nodes.length > 1 ? 1 / (graph.nodes.length - 1) : 0;
-	const idx = getIndex(graph);
 	const scores = createEmptyScoreMap(graph);
-	for (const node of graph.nodes) scores[node.id] = (idx.outEdges.get(node.id)?.length ?? 0) * scale;
+	for (const node of graph.nodes) scores[node.id] = getOutDegree(graph, node.id) * scale;
 	return scores;
 }
 /**
@@ -1778,16 +2477,19 @@ function getOutDegreeCentrality(graph) {
 */
 function getClosenessCentrality(graph) {
 	const scores = createEmptyScoreMap(graph);
-	const order = graph.nodes.length;
-	for (const node of graph.nodes) {
-		const distances = getReachableDistances(graph, node.id);
-		distances.delete(node.id);
-		if (distances.size === 0) continue;
-		const totalDistance = [...distances.values()].reduce((sum, distance) => sum + distance, 0);
+	const csr = getCSR(graph);
+	const order = csr.ids.length;
+	const dist = new Int32Array(order);
+	const queue = new Int32Array(order);
+	for (let s = 0; s < order; s++) {
+		const visited = bfsDistances(csr, s, dist, queue);
+		const reachable = visited - 1;
+		if (reachable === 0) continue;
+		let totalDistance = 0;
+		for (let k = 0; k < visited; k++) totalDistance += dist[queue[k]];
 		if (totalDistance === 0) continue;
-		const reachable = distances.size;
 		const closeness = reachable / totalDistance;
-		scores[node.id] = order > 1 ? closeness * (reachable / (order - 1)) : closeness;
+		scores[csr.ids[s]] = order > 1 ? closeness * (reachable / (order - 1)) : closeness;
 	}
 	return scores;
 }
@@ -1798,52 +2500,53 @@ function getClosenessCentrality(graph) {
 * normalized scores.
 */
 function getBetweennessCentrality(graph) {
-	const scores = createEmptyScoreMap(graph);
-	for (const source of graph.nodes) {
-		const stack = [];
-		const predecessors = /* @__PURE__ */ new Map();
-		const sigma = /* @__PURE__ */ new Map();
-		const distance = /* @__PURE__ */ new Map();
-		const queue = [source.id];
-		for (const node of graph.nodes) {
-			predecessors.set(node.id, []);
-			sigma.set(node.id, 0);
-			distance.set(node.id, -1);
-		}
-		sigma.set(source.id, 1);
-		distance.set(source.id, 0);
-		while (queue.length > 0) {
-			const currentId = queue.shift();
-			stack.push(currentId);
-			for (const neighborId of getNeighborIds(graph, currentId)) {
-				if (distance.get(neighborId) === -1) {
-					queue.push(neighborId);
-					distance.set(neighborId, distance.get(currentId) + 1);
-				}
-				if (distance.get(neighborId) === distance.get(currentId) + 1) {
-					sigma.set(neighborId, sigma.get(neighborId) + sigma.get(currentId));
-					predecessors.get(neighborId).push(currentId);
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	const totals = new Float64Array(n);
+	const sigma = new Float64Array(n);
+	const dist = new Int32Array(n);
+	const delta = new Float64Array(n);
+	const order_ = new Int32Array(n);
+	for (let s = 0; s < n; s++) {
+		sigma.fill(0);
+		dist.fill(-1);
+		delta.fill(0);
+		sigma[s] = 1;
+		dist[s] = 0;
+		order_[0] = s;
+		let head = 0;
+		let tail = 1;
+		while (head < tail) {
+			const u = order_[head++];
+			const du = dist[u];
+			for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) {
+				const v = csr.outTargets[a];
+				if (dist[v] === -1) {
+					dist[v] = du + 1;
+					order_[tail++] = v;
 				}
+				if (dist[v] === du + 1) sigma[v] += sigma[u];
 			}
 		}
-		const delta = /* @__PURE__ */ new Map();
-		for (const node of graph.nodes) delta.set(node.id, 0);
-		while (stack.length > 0) {
-			const nodeId = stack.pop();
-			const sigmaNode = sigma.get(nodeId);
-			if (sigmaNode === 0) continue;
-			for (const predecessorId of predecessors.get(nodeId)) {
-				const contribution = sigma.get(predecessorId) / sigmaNode * (1 + delta.get(nodeId));
-				delta.set(predecessorId, delta.get(predecessorId) + contribution);
+		for (let k = tail - 1; k >= 0; k--) {
+			const w = order_[k];
+			const sigmaW = sigma[w];
+			if (sigmaW === 0) continue;
+			const coefficient = (1 + delta[w]) / sigmaW;
+			for (let a = csr.inOffsets[w]; a < csr.inOffsets[w + 1]; a++) {
+				const v = csr.inOrigins[a];
+				if (dist[v] === dist[w] - 1) delta[v] += sigma[v] * coefficient;
 			}
-			if (nodeId !== source.id) scores[nodeId] += delta.get(nodeId);
+			if (w !== s) totals[w] += delta[w];
 		}
 	}
+	const scores = createEmptyScoreMap(graph);
+	for (let i = 0; i < n; i++) scores[csr.ids[i]] = totals[i];
 	const order = graph.nodes.length;
 	if (order <= 2) return scores;
-	const scale = graph.type === "undirected" ? 1 / ((order - 1) * (order - 2) / 2) : 1 / ((order - 1) * (order - 2));
+	const scale = graph.mode !== "directed" ? 1 / ((order - 1) * (order - 2) / 2) : 1 / ((order - 1) * (order - 2));
 	for (const nodeId of Object.keys(scores)) {
-		if (graph.type === "undirected") scores[nodeId] /= 2;
+		if (graph.mode !== "directed") scores[nodeId] /= 2;
 		scores[nodeId] *= scale;
 	}
 	return scores;
@@ -1860,28 +2563,32 @@ function getPageRank(graph, options) {
 	const maxIterations = options?.maxIterations ?? 100;
 	const tolerance = options?.tolerance ?? 1e-6;
 	let scores = Object.fromEntries(nodeIds.map((nodeId) => [nodeId, 1 / nodeIds.length]));
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	let current = new Float64Array(n).fill(1 / n);
+	for (let i = 0; i < n; i++) current[i] = scores[csr.ids[i]];
 	for (let iteration = 0; iteration < maxIterations; iteration++) {
-		const nextScores = Object.fromEntries(nodeIds.map((nodeId) => [nodeId, (1 - alpha) / nodeIds.length]));
+		const next = new Float64Array(n).fill((1 - alpha) / n);
 		let danglingMass = 0;
-		for (const nodeId of nodeIds) {
-			const neighbors = getNeighborIds(graph, nodeId);
-			if (neighbors.length === 0) {
-				danglingMass += scores[nodeId];
+		for (let u = 0; u < n; u++) {
+			const arcCount = csr.outOffsets[u + 1] - csr.outOffsets[u];
+			if (arcCount === 0) {
+				danglingMass += current[u];
 				continue;
 			}
-			const share = scores[nodeId] / neighbors.length;
-			for (const neighborId of neighbors) nextScores[neighborId] += alpha * share;
+			const share = alpha * current[u] / arcCount;
+			for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) next[csr.outTargets[a]] += share;
 		}
 		if (danglingMass > 0) {
-			const share = alpha * danglingMass / nodeIds.length;
-			for (const nodeId of nodeIds) nextScores[nodeId] += share;
-		}
-		if (maxDiff(scores, nextScores) <= tolerance) {
-			scores = nextScores;
-			break;
+			const share = alpha * danglingMass / n;
+			for (let i = 0; i < n; i++) next[i] += share;
 		}
-		scores = nextScores;
+		let diff = 0;
+		for (let i = 0; i < n; i++) diff = Math.max(diff, Math.abs(current[i] - next[i]));
+		current = next;
+		if (diff <= tolerance) break;
 	}
+	for (let i = 0; i < n; i++) scores[csr.ids[i]] = current[i];
 	const total = Object.values(scores).reduce((sum, value) => sum + value, 0);
 	if (total !== 0) for (const nodeId of nodeIds) scores[nodeId] /= total;
 	return scores;
@@ -1892,31 +2599,38 @@ function getPageRank(graph, options) {
 * Uses power iteration and L2 normalization per iteration.
 */
 function getHITS(graph, options) {
-	const nodeIds = getNodeIds(graph);
-	if (nodeIds.length === 0) return {
+	if (getNodeIds(graph).length === 0) return {
 		hubs: {},
 		authorities: {}
 	};
 	const maxIterations = options?.maxIterations ?? 100;
 	const tolerance = options?.tolerance ?? 1e-6;
-	let hubs = Object.fromEntries(nodeIds.map((nodeId) => [nodeId, 1]));
-	let authorities = createEmptyScoreMap(graph);
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	let hubs = new Float64Array(n).fill(1);
+	let authorities = new Float64Array(n);
 	for (let iteration = 0; iteration < maxIterations; iteration++) {
-		const nextAuthorities = createEmptyScoreMap(graph);
-		for (const nodeId of nodeIds) for (const predecessorId of getIncomingIds(graph, nodeId)) nextAuthorities[nodeId] += hubs[predecessorId];
-		normalizeVector(nextAuthorities);
-		const nextHubs = createEmptyScoreMap(graph);
-		for (const nodeId of nodeIds) for (const neighborId of getNeighborIds(graph, nodeId)) nextHubs[nodeId] += nextAuthorities[neighborId];
-		normalizeVector(nextHubs);
-		const hubDiff = maxDiff(hubs, nextHubs);
-		const authorityDiff = maxDiff(authorities, nextAuthorities);
+		const nextAuthorities = new Float64Array(n);
+		for (let w = 0; w < n; w++) for (let a = csr.inOffsets[w]; a < csr.inOffsets[w + 1]; a++) nextAuthorities[w] += hubs[csr.inOrigins[a]];
+		normalizeTypedVector(nextAuthorities);
+		const nextHubs = new Float64Array(n);
+		for (let u = 0; u < n; u++) for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) nextHubs[u] += nextAuthorities[csr.outTargets[a]];
+		normalizeTypedVector(nextHubs);
+		let diff = 0;
+		for (let i = 0; i < n; i++) diff = Math.max(diff, Math.abs(hubs[i] - nextHubs[i]), Math.abs(authorities[i] - nextAuthorities[i]));
 		hubs = nextHubs;
 		authorities = nextAuthorities;
-		if (Math.max(hubDiff, authorityDiff) <= tolerance) break;
+		if (diff <= tolerance) break;
+	}
+	const hubScores = createEmptyScoreMap(graph);
+	const authorityScores = createEmptyScoreMap(graph);
+	for (let i = 0; i < n; i++) {
+		hubScores[csr.ids[i]] = hubs[i];
+		authorityScores[csr.ids[i]] = authorities[i];
 	}
 	return {
-		hubs,
-		authorities
+		hubs: hubScores,
+		authorities: authorityScores
 	};
 }
 /**
@@ -1926,20 +2640,24 @@ function getHITS(graph, options) {
 * undirected adjacency for undirected graphs.
 */
 function getEigenvectorCentrality(graph, options) {
-	const nodeIds = getNodeIds(graph);
-	if (nodeIds.length === 0) return {};
+	if (getNodeIds(graph).length === 0) return {};
 	const maxIterations = options?.maxIterations ?? 100;
 	const tolerance = options?.tolerance ?? 1e-6;
-	let scores = Object.fromEntries(nodeIds.map((nodeId) => [nodeId, 1]));
-	normalizeVector(scores);
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	let current = new Float64Array(n).fill(1);
+	normalizeTypedVector(current);
 	for (let iteration = 0; iteration < maxIterations; iteration++) {
-		const nextScores = createEmptyScoreMap(graph);
-		for (const nodeId of nodeIds) for (const predecessorId of getIncomingIds(graph, nodeId)) nextScores[nodeId] += scores[predecessorId];
-		normalizeVector(nextScores);
-		const diff = maxDiff(scores, nextScores);
-		scores = nextScores;
+		const next = new Float64Array(n);
+		for (let w = 0; w < n; w++) for (let a = csr.inOffsets[w]; a < csr.inOffsets[w + 1]; a++) next[w] += current[csr.inOrigins[a]];
+		normalizeTypedVector(next);
+		let diff = 0;
+		for (let i = 0; i < n; i++) diff = Math.max(diff, Math.abs(current[i] - next[i]));
+		current = next;
 		if (diff <= tolerance) break;
 	}
+	const scores = createEmptyScoreMap(graph);
+	for (let i = 0; i < n; i++) scores[csr.ids[i]] = current[i];
 	return scores;
 }
 
@@ -2247,8 +2965,8 @@ function traverseConnectivity(graph, nodeId, parentEdgeId, state) {
 			traverseConnectivity(graph, neighbor.nodeId, neighbor.edgeId, state);
 			state.low.set(nodeId, Math.min(state.low.get(nodeId), state.low.get(neighbor.nodeId)));
 			if (state.low.get(neighbor.nodeId) > state.disc.get(nodeId)) state.bridges.add(neighbor.edgeId);
-			if (parentEdgeId !== null && state.low.get(neighbor.nodeId) >= state.disc.get(nodeId)) {
-				state.articulationPoints.add(nodeId);
+			if (state.low.get(neighbor.nodeId) >= state.disc.get(nodeId)) {
+				if (parentEdgeId !== null) state.articulationPoints.add(nodeId);
 				popComponentUntil(state, neighbor.edgeId);
 			}
 		} else if (state.disc.get(neighbor.nodeId) < state.disc.get(nodeId)) {
@@ -2312,14 +3030,33 @@ function getBiconnectedComponents(graph) {
 //#region src/algorithms/isomorphism.ts
 function getDegreeSignature(graph, nodeId) {
 	const idx = getIndex(graph);
-	const outDegree = idx.outEdges.get(nodeId)?.length ?? 0;
-	const inDegree = idx.inEdges.get(nodeId)?.length ?? 0;
-	if (graph.type === "undirected") return `u:${new Set([...idx.outEdges.get(nodeId) ?? [], ...idx.inEdges.get(nodeId) ?? []]).size}`;
-	return `d:${inDegree}:${outDegree}`;
+	let inDegree = 0;
+	let outDegree = 0;
+	let undirected = 0;
+	const countedNonDirected = /* @__PURE__ */ new Set();
+	for (const eid of idx.outEdges.get(nodeId) ?? []) {
+		const edge = graph.edges[idx.edgeById.get(eid)];
+		if (getEdgeMode(graph, edge) === "directed") outDegree++;
+		else if (!countedNonDirected.has(eid)) {
+			countedNonDirected.add(eid);
+			undirected++;
+		}
+	}
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		const edge = graph.edges[idx.edgeById.get(eid)];
+		if (getEdgeMode(graph, edge) === "directed") inDegree++;
+		else if (!countedNonDirected.has(eid)) {
+			countedNonDirected.add(eid);
+			undirected++;
+		}
+	}
+	return `d:${inDegree}:${outDegree}:u:${undirected}`;
 }
 function getEdgesBetween(graph, sourceId, targetId) {
-	if (graph.type === "undirected") return graph.edges.filter((edge) => edge.sourceId === sourceId && edge.targetId === targetId || edge.sourceId === targetId && edge.targetId === sourceId);
-	return graph.edges.filter((edge) => edge.sourceId === sourceId && edge.targetId === targetId);
+	return graph.edges.filter((edge) => {
+		if (edge.sourceId === sourceId && edge.targetId === targetId) return true;
+		return edge.sourceId === targetId && edge.targetId === sourceId && getEdgeMode(graph, edge) !== "directed";
+	});
 }
 function edgesAreCompatible(edgesA, edgesB, edgeMatch) {
 	if (edgesA.length !== edgesB.length) return false;
@@ -2339,7 +3076,6 @@ function edgesAreCompatible(edgesA, edgesB, edgeMatch) {
 * node and edge payloads.
 */
 function isIsomorphic(graphA, graphB, options) {
-	if (graphA.type !== graphB.type) return false;
 	if (graphA.nodes.length !== graphB.nodes.length) return false;
 	if (graphA.edges.length !== graphB.edges.length) return false;
 	const nodeMatch = options?.nodeMatch;
@@ -2363,6 +3099,7 @@ function isIsomorphic(graphA, graphB, options) {
 			if (usedB.has(nodeB.id)) continue;
 			if (getDegreeSignature(graphB, nodeB.id) !== signatureA) continue;
 			if (nodeMatch && !nodeMatch(nodeA, nodeB)) continue;
+			if (!edgesAreCompatible(getEdgesBetween(graphA, nodeA.id, nodeA.id), getEdgesBetween(graphB, nodeB.id, nodeB.id), edgeMatch)) continue;
 			let compatible = true;
 			for (const [mappedAId, mappedBId] of mapping.entries()) {
 				if (!edgesAreCompatible(getEdgesBetween(graphA, nodeA.id, mappedAId), getEdgesBetween(graphB, nodeB.id, mappedBId), edgeMatch)) {
@@ -2387,4 +3124,404 @@ function isIsomorphic(graphA, graphB, options) {
 }
 
 //#endregion
-export { createGraphPort as $, isAcyclic as A, getShortestPaths as B, getPreorder as C, getConnectedComponents as D, dfs as E, genSimplePaths as F, GraphInstance as G, getSimplePaths as H, getAStarPath as I, addNode as J, addEdge as K, getAllPairsShortestPaths as L, isTree as M, genCycles as N, getTopologicalSort as O, genShortestPaths as P, createGraphNode as Q, getCycles as R, getPostorders as S, bfs as T, getStronglyConnectedComponents as U, getSimplePath as V, joinPaths as W, createGraphEdge as X, createGraph as Y, createGraphFromTransition as Z, getPageRank as _, genGirvanNewmanCommunities as a, getNode as at, genPreorders as b, getLabelPropagationCommunities as c, updateEdge as ct, getClosenessCentrality as d, createVisualGraph as et, getDegreeCentrality as f, getOutDegreeCentrality as g, getInDegreeCentrality as h, getBridges as i, getEdge as it, isConnected as j, hasPath as k, getModularity as l, updateEntities as lt, getHITS as m, getArticulationPoints as n, deleteEntities as nt, getGirvanNewmanCommunities as o, hasEdge as ot, getEigenvectorCentrality as p, addEntities as q, getBiconnectedComponents as r, deleteNode as rt, getGreedyModularityCommunities as s, hasNode as st, isIsomorphic as t, deleteEdge as tt, getBetweennessCentrality as u, updateNode as ut, getMinimumSpanningTree as v, getPreorders as w, getPostorder as x, genPostorders as y, getShortestPath as z };
+//#region src/algorithms/louvain.ts
+/**
+* Returns communities found by the classic two-phase Louvain modularity
+* optimization (local moving + community aggregation).
+*
+* Like the other community algorithms in this library, the graph is treated
+* as undirected regardless of `graph.mode` or per-edge modes. Parallel edges
+* have their weights summed; self-loops contribute to a community's internal
+* weight.
+*
+* The implementation is deterministic: nodes are visited in `graph.nodes`
+* array order and there is no random shuffling, so tie-breaking is
+* order-dependent but stable across runs.
+*
+* Returns communities of node ids, each community sorted lexicographically
+* and communities sorted by their first id.
+*
+* @example
+* ```ts
+* const communities = getLouvainCommunities(graph);
+* // [['a', 'b', 'c'], ['d', 'e', 'f']]
+* ```
+*/
+function getLouvainCommunities(graph, options) {
+	if (graph.nodes.length === 0) return [];
+	const getWeight = options?.getWeight ?? ((edge) => edge.weight ?? 1);
+	const resolution = options?.resolution ?? 1;
+	const maxPasses = options?.maxPasses ?? 10;
+	const nodeIds = graph.nodes.map((node) => node.id);
+	const indexOf = new Map(nodeIds.map((id, i) => [id, i]));
+	let count = nodeIds.length;
+	let links = Array.from({ length: count }, () => /* @__PURE__ */ new Map());
+	let selfLoops = new Array(count).fill(0);
+	for (const edge of graph.edges) {
+		const u = indexOf.get(edge.sourceId);
+		const v = indexOf.get(edge.targetId);
+		if (u === void 0 || v === void 0) continue;
+		const w = getWeight(edge);
+		if (u === v) selfLoops[u] += w;
+		else {
+			links[u].set(v, (links[u].get(v) ?? 0) + w);
+			links[v].set(u, (links[v].get(u) ?? 0) + w);
+		}
+	}
+	let membership = nodeIds.map((_, i) => i);
+	for (let pass = 0; pass < maxPasses; pass++) {
+		const degree = links.map((neighbors, i) => 2 * selfLoops[i] + [...neighbors.values()].reduce((sum, w) => sum + w, 0));
+		const m2 = degree.reduce((sum, k) => sum + k, 0);
+		if (m2 === 0) break;
+		const communityOf = Array.from({ length: count }, (_, i) => i);
+		const communityTotal = [...degree];
+		let movedAny = false;
+		let movedThisSweep = true;
+		while (movedThisSweep) {
+			movedThisSweep = false;
+			for (let i = 0; i < count; i++) {
+				const current = communityOf[i];
+				const weightTo = /* @__PURE__ */ new Map();
+				for (const [j, w] of links[i]) {
+					const c = communityOf[j];
+					weightTo.set(c, (weightTo.get(c) ?? 0) + w);
+				}
+				communityTotal[current] -= degree[i];
+				const gainOf = (c) => (weightTo.get(c) ?? 0) - resolution * communityTotal[c] * degree[i] / m2;
+				let best = current;
+				let bestGain = gainOf(current);
+				for (const c of weightTo.keys()) {
+					if (c === current) continue;
+					const gain = gainOf(c);
+					if (gain > bestGain + 1e-12) {
+						best = c;
+						bestGain = gain;
+					}
+				}
+				communityTotal[best] += degree[i];
+				if (best !== current) {
+					communityOf[i] = best;
+					movedThisSweep = true;
+					movedAny = true;
+				}
+			}
+		}
+		if (!movedAny) break;
+		const renumber = /* @__PURE__ */ new Map();
+		for (let i = 0; i < count; i++) {
+			const c = communityOf[i];
+			if (!renumber.has(c)) renumber.set(c, renumber.size);
+		}
+		const nextCount = renumber.size;
+		const nextLinks = Array.from({ length: nextCount }, () => /* @__PURE__ */ new Map());
+		const nextSelfLoops = new Array(nextCount).fill(0);
+		for (let i = 0; i < count; i++) {
+			const ci = renumber.get(communityOf[i]);
+			nextSelfLoops[ci] += selfLoops[i];
+			for (const [j, w] of links[i]) {
+				const cj = renumber.get(communityOf[j]);
+				if (ci === cj) nextSelfLoops[ci] += w / 2;
+				else nextLinks[ci].set(cj, (nextLinks[ci].get(cj) ?? 0) + w);
+			}
+		}
+		membership = membership.map((c) => renumber.get(communityOf[c]));
+		links = nextLinks;
+		selfLoops = nextSelfLoops;
+		count = nextCount;
+		if (nextCount === 1) break;
+	}
+	const grouped = /* @__PURE__ */ new Map();
+	for (let i = 0; i < nodeIds.length; i++) {
+		const c = membership[i];
+		if (!grouped.has(c)) grouped.set(c, []);
+		grouped.get(c).push(nodeIds[i]);
+	}
+	return [...grouped.values()].map((ids) => ids.sort((a, b) => a.localeCompare(b))).sort((a, b) => a[0].localeCompare(b[0]));
+}
+
+//#endregion
+//#region src/algorithms/flow.ts
+/**
+* Returns the maximum flow from `from` to `to` using the Edmonds-Karp
+* algorithm (BFS augmenting paths).
+*
+* Directed edges carry capacity from source to target only. Edges whose
+* effective mode is not `'directed'` (undirected/bidirectional) are modeled
+* as two independent opposite arcs, each with the edge's full capacity.
+*
+* The returned `flows` record maps every edge id to its net flow (positive
+* in the source→target direction). `cutEdges` is a minimum s-t cut: the
+* edges crossing from the source side to the sink side of the final
+* residual graph; the sum of their capacities equals `value`.
+*
+* @example
+* ```ts
+* const { value, cutEdges } = getMaxFlow(graph, { from: 's', to: 't' });
+* ```
+*/
+function getMaxFlow(graph, options) {
+	const { from, to } = options;
+	const getCapacity = options.getCapacity ?? ((edge) => edge.weight ?? 1);
+	const idx = getIndex(graph);
+	if (!idx.nodeById.has(from)) throw new Error(`getMaxFlow: source node "${from}" not found in graph — pass an existing node id as options.from`);
+	if (!idx.nodeById.has(to)) throw new Error(`getMaxFlow: sink node "${to}" not found in graph — pass an existing node id as options.to`);
+	if (from === to) throw new Error(`getMaxFlow: source and sink are both "${from}" — they must be different nodes`);
+	const arcs = [];
+	const outArcs = /* @__PURE__ */ new Map();
+	for (const node of graph.nodes) outArcs.set(node.id, []);
+	function addArc(u, v, capacity, edgeId, sign) {
+		outArcs.get(u).push(arcs.length);
+		arcs.push({
+			to: v,
+			capacity,
+			flow: 0,
+			edgeId,
+			sign
+		});
+		outArcs.get(v).push(arcs.length);
+		arcs.push({
+			to: u,
+			capacity: 0,
+			flow: 0
+		});
+	}
+	for (const edge of graph.edges) {
+		const capacity = getCapacity(edge);
+		if (capacity < 0) throw new Error(`getMaxFlow: edge "${edge.id}" has negative capacity ${capacity} — capacities must be >= 0; fix edge.weight or provide a non-negative getCapacity`);
+		if (edge.sourceId === edge.targetId) continue;
+		addArc(edge.sourceId, edge.targetId, capacity, edge.id, 1);
+		if (getEdgeMode(graph, edge) !== "directed") addArc(edge.targetId, edge.sourceId, capacity, edge.id, -1);
+	}
+	function residual(arcIndex) {
+		return arcs[arcIndex].capacity - arcs[arcIndex].flow;
+	}
+	let value = 0;
+	while (true) {
+		const parentArc = /* @__PURE__ */ new Map();
+		const queue$1 = [from];
+		const visited = new Set([from]);
+		while (queue$1.length > 0 && !visited.has(to)) {
+			const u = queue$1.shift();
+			for (const ai of outArcs.get(u) ?? []) {
+				const arc = arcs[ai];
+				if (residual(ai) > 0 && !visited.has(arc.to)) {
+					visited.add(arc.to);
+					parentArc.set(arc.to, ai);
+					queue$1.push(arc.to);
+				}
+			}
+		}
+		if (!visited.has(to)) break;
+		let bottleneck = Infinity;
+		for (let v = to; v !== from;) {
+			const ai = parentArc.get(v);
+			bottleneck = Math.min(bottleneck, residual(ai));
+			v = arcs[ai ^ 1].to;
+		}
+		if (bottleneck === Infinity || bottleneck <= 0) break;
+		for (let v = to; v !== from;) {
+			const ai = parentArc.get(v);
+			arcs[ai].flow += bottleneck;
+			arcs[ai ^ 1].flow -= bottleneck;
+			v = arcs[ai ^ 1].to;
+		}
+		value += bottleneck;
+	}
+	const flows = Object.fromEntries(graph.edges.map((edge) => [edge.id, 0]));
+	for (const arc of arcs) if (arc.edgeId !== void 0 && arc.flow > 0) flows[arc.edgeId] += arc.sign * arc.flow;
+	const sourceSide = new Set([from]);
+	const queue = [from];
+	while (queue.length > 0) {
+		const u = queue.shift();
+		for (const ai of outArcs.get(u) ?? []) {
+			const arc = arcs[ai];
+			if (residual(ai) > 0 && !sourceSide.has(arc.to)) {
+				sourceSide.add(arc.to);
+				queue.push(arc.to);
+			}
+		}
+	}
+	const cutEdgeIds = /* @__PURE__ */ new Set();
+	for (let ai = 0; ai < arcs.length; ai++) {
+		const arc = arcs[ai];
+		if (arc.edgeId === void 0) continue;
+		const arcFrom = arcs[ai ^ 1].to;
+		if (sourceSide.has(arcFrom) && !sourceSide.has(arc.to)) cutEdgeIds.add(arc.edgeId);
+	}
+	const cutEdges = graph.edges.filter((edge) => cutEdgeIds.has(edge.id));
+	return {
+		value,
+		flows,
+		cutEdges
+	};
+}
+
+//#endregion
+//#region src/algorithms/dominators.ts
+/**
+* Returns the dominator tree of the graph rooted at `from`, computed with
+* the Cooper–Harvey–Kennedy iterative algorithm.
+*
+* Each reachable node maps to its immediate dominator's id; the root maps
+* to `null`. Unreachable nodes are omitted. Traversal is mode-aware:
+* undirected/bidirectional edges are traversable both ways.
+*
+* For statecharts this answers "which states must every path from the
+* initial state pass through to reach this state?" — node `d` dominates
+* node `n` when every path from the initial state to `n` goes through `d`.
+*
+* @example
+* ```ts
+* // a→b, a→c, b→d, c→d (diamond)
+* getDominatorTree(graph, { from: 'a' });
+* // { a: null, b: 'a', c: 'a', d: 'a' }
+* ```
+*/
+function getDominatorTree(graph, options) {
+	const root = resolveFrom(graph, options);
+	if (!getIndex(graph).nodeById.has(root)) throw new Error(`getDominatorTree: root node "${root}" not found in graph — pass an existing node id as options.from`);
+	const postorder = [];
+	const visited = new Set([root]);
+	const stack = [{
+		id: root,
+		neighborIndex: 0
+	}];
+	const successors = /* @__PURE__ */ new Map();
+	function getSuccessors(id) {
+		let succ = successors.get(id);
+		if (!succ) {
+			succ = getNeighborEdges(graph, id).map((entry) => entry.neighborId);
+			successors.set(id, succ);
+		}
+		return succ;
+	}
+	while (stack.length > 0) {
+		const frame = stack[stack.length - 1];
+		const succ = getSuccessors(frame.id);
+		if (frame.neighborIndex < succ.length) {
+			const next = succ[frame.neighborIndex++];
+			if (!visited.has(next)) {
+				visited.add(next);
+				stack.push({
+					id: next,
+					neighborIndex: 0
+				});
+			}
+		} else {
+			postorder.push(frame.id);
+			stack.pop();
+		}
+	}
+	const rpo = [...postorder].reverse();
+	const rpoNumber = new Map(rpo.map((id, i) => [id, i]));
+	const predecessors = new Map(rpo.map((id) => [id, []]));
+	for (const id of rpo) for (const succ of getSuccessors(id)) if (visited.has(succ)) predecessors.get(succ).push(id);
+	const idom = /* @__PURE__ */ new Map();
+	idom.set(root, root);
+	function intersect(a, b) {
+		let f1 = a;
+		let f2 = b;
+		while (f1 !== f2) {
+			while (rpoNumber.get(f1) > rpoNumber.get(f2)) f1 = idom.get(f1);
+			while (rpoNumber.get(f2) > rpoNumber.get(f1)) f2 = idom.get(f2);
+		}
+		return f1;
+	}
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const id of rpo) {
+			if (id === root) continue;
+			let newIdom;
+			for (const pred of predecessors.get(id)) {
+				if (!idom.has(pred)) continue;
+				newIdom = newIdom === void 0 ? pred : intersect(pred, newIdom);
+			}
+			if (newIdom !== void 0 && idom.get(id) !== newIdom) {
+				idom.set(id, newIdom);
+				changed = true;
+			}
+		}
+	}
+	const result = {};
+	for (const id of rpo) result[id] = id === root ? null : idom.get(id);
+	return result;
+}
+
+//#endregion
+//#region src/algorithms/reduction.ts
+/**
+* Returns a new graph with all transitively-redundant edges removed (the
+* transitive reduction). The input graph is not mutated; nodes and surviving
+* edges keep all of their fields.
+*
+* An edge u→v is removed when v is also reachable from u via a path of
+* length ≥ 2. Exact-duplicate parallel edges u→v collapse to the first one
+* in `graph.edges` order (a duplicate adds no reachability, so at most one
+* edge per (u, v) pair survives).
+*
+* DAG-only: throws when the graph contains a cycle or any edge whose
+* effective mode is not `'directed'`.
+*
+* @example
+* ```ts
+* // a→b, b→c, a→c
+* const reduced = getTransitiveReduction(graph);
+* // a→c removed; edges: a→b, b→c
+* ```
+*/
+function getTransitiveReduction(graph) {
+	for (const edge of graph.edges) {
+		const mode = getEdgeMode(graph, edge);
+		if (mode !== "directed") throw new Error(`getTransitiveReduction: edge "${edge.id}" has effective mode "${mode}" — transitive reduction is only defined for directed acyclic graphs. Set edge.mode (or graph.mode) to 'directed'.`);
+	}
+	if (getEffectiveModeKind(graph) === "directed" && !isAcyclic(graph)) throw new Error("getTransitiveReduction: the graph contains a cycle — transitive reduction is only defined for directed acyclic graphs. Remove the cycle (see getCycles) first.");
+	const successorsOf = /* @__PURE__ */ new Map();
+	for (const node of graph.nodes) successorsOf.set(node.id, /* @__PURE__ */ new Set());
+	for (const edge of graph.edges) successorsOf.get(edge.sourceId)?.add(edge.targetId);
+	const reach = /* @__PURE__ */ new Map();
+	function getReach(id) {
+		let set = reach.get(id);
+		if (set) return set;
+		set = new Set([id]);
+		reach.set(id, set);
+		for (const succ of successorsOf.get(id) ?? []) for (const reached of getReach(succ)) set.add(reached);
+		return set;
+	}
+	function isRedundant(u, v) {
+		for (const w of successorsOf.get(u)) if (w !== v && getReach(w).has(v)) return true;
+		return false;
+	}
+	const keptPairs = /* @__PURE__ */ new Set();
+	const keptEdges = [];
+	for (const edge of graph.edges) {
+		const pair = `${edge.sourceId}${edge.targetId}`;
+		if (keptPairs.has(pair)) continue;
+		if (isRedundant(edge.sourceId, edge.targetId)) continue;
+		keptPairs.add(pair);
+		keptEdges.push(edge);
+	}
+	return createGraph({
+		id: graph.id,
+		mode: graph.mode,
+		initialNodeId: graph.initialNodeId ?? void 0,
+		data: graph.data ?? void 0,
+		direction: graph.direction,
+		style: graph.style,
+		nodes: graph.nodes.map((node) => {
+			const { type, parentId, initialNodeId, ...rest } = node;
+			return {
+				...rest,
+				parentId: parentId ?? void 0,
+				initialNodeId: initialNodeId ?? void 0
+			};
+		}),
+		edges: keptEdges.map((edge) => {
+			const { type, ...rest } = edge;
+			return rest;
+		})
+	});
+}
+
+//#endregion
+export { joinPaths as $, dfs as A, toEdgeConfig as B, genPostorders as C, getPreorder as D, getPostorders as E, isConnected as F, getAStarPath as G, genCycles as H, isTree as I, getShortestPath as J, getAllPairsShortestPaths as K, flatten as L, getTopologicalSort as M, hasPath as N, getPreorders as O, isAcyclic as P, getStronglyConnectedComponents as Q, getSubgraph as R, getMinimumSpanningTree as S, getPostorder as T, genShortestPaths as U, toNodeConfig as V, genSimplePaths as W, getSimplePath as X, getShortestPaths as Y, getSimplePaths as Z, getEigenvectorCentrality as _, updateEdge as _t, isIsomorphic as a, createGraphEdge as at, getOutDegreeCentrality as b, getBridges as c, createGraphPort as ct, getGreedyModularityCommunities as d, deleteEntities as dt, GraphInstance as et, getLabelPropagationCommunities as f, deleteNode as ft, getDegreeCentrality as g, hasNode as gt, getClosenessCentrality as h, hasEdge as ht, getLouvainCommunities as i, createGraph as it, getConnectedComponents as j, bfs as k, genGirvanNewmanCommunities as l, createVisualGraph as lt, getBetweennessCentrality as m, getNode as mt, getDominatorTree as n, addEntities as nt, getArticulationPoints as o, createGraphFromTransition as ot, getModularity as p, getEdge as pt, getCycles as q, getMaxFlow as r, addNode as rt, getBiconnectedComponents as s, createGraphNode as st, getTransitiveReduction as t, addEdge as tt, getGirvanNewmanCommunities as u, deleteEdge as ut, getHITS as v, updateEntities as vt, genPreorders as w, getPageRank as x, getInDegreeCentrality as y, updateNode as yt, reverseGraph as z };