@statelyai/graph 2.0.0 → 2.1.0

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

@@ -1,719 +1,7 @@
-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";
+import { O as getIndex, l as getInDegree, p as getOutDegree, r as getDegree } from "./queries-BMM0XAv_.mjs";
+import { n as toNodeConfig, s as createGraph, t as toEdgeConfig } from "./config-Dt5u1gSf.mjs";
+import { t as getEdgeMode } from "./mode-gu_mhKKs.mjs";
 
-//#region src/graph.ts
-/**
-* Create a resolved graph port from a config. Fills in defaults.
-*
-* @example
-* ```ts
-* const port = createGraphPort({ name: 'output', direction: 'out' });
-* // { name: 'output', direction: 'out', data: null }
-* ```
-*/
-function createGraphPort(config) {
-	if (!config.name) throw new Error("Port name must be a non-empty string");
-	const port = {
-		name: config.name,
-		direction: config.direction ?? "inout",
-		data: config.data ?? null
-	};
-	if (config.label !== void 0) port.label = config.label;
-	if (config.x !== void 0) port.x = config.x;
-	if (config.y !== void 0) port.y = config.y;
-	if (config.width !== void 0) port.width = config.width;
-	if (config.height !== void 0) port.height = config.height;
-	if (config.style !== void 0) port.style = config.style;
-	return port;
-}
-function validatePortNames(ports) {
-	const seen = /* @__PURE__ */ new Set();
-	for (const port of ports) {
-		if (seen.has(port.name)) throw new Error(`Duplicate port name "${port.name}" on node`);
-		seen.add(port.name);
-	}
-}
-/**
-* Create a resolved graph node from a config. Fills in defaults.
-*
-* @example
-* ```ts
-* const node = createGraphNode({ id: 'a', data: { label: 'hi' } });
-* // { type: 'node', id: 'a', label: '', data: { label: 'hi' } }
-* ```
-*/
-function createGraphNode(config) {
-	if (!config.id) throw new Error("Node id must be a non-empty string");
-	if (config.parentId === "") throw new Error("Node parentId must be a non-empty string");
-	const node = {
-		type: "node",
-		id: config.id,
-		...config.parentId !== void 0 && { parentId: config.parentId ?? null },
-		...config.initialNodeId !== void 0 && { initialNodeId: config.initialNodeId ?? null },
-		label: config.label ?? null,
-		data: config.data ?? null
-	};
-	if (config.ports !== void 0 && config.ports.length > 0) {
-		validatePortNames(config.ports);
-		node.ports = config.ports.map(createGraphPort);
-	}
-	if (config.x !== void 0) node.x = config.x;
-	if (config.y !== void 0) node.y = config.y;
-	if (config.width !== void 0) node.width = config.width;
-	if (config.height !== void 0) node.height = config.height;
-	if (config.shape !== void 0) node.shape = config.shape;
-	if (config.color !== void 0) node.color = config.color;
-	if (config.style !== void 0) node.style = config.style;
-	return node;
-}
-/**
-* Create a resolved graph edge from a config. Fills in defaults.
-*
-* @example
-* ```ts
-* const edge = createGraphEdge({ id: 'e1', sourceId: 'a', targetId: 'b' });
-* // { type: 'edge', id: 'e1', sourceId: 'a', targetId: 'b', label: null, data: null }
-* ```
-*/
-function createGraphEdge(config) {
-	if (!config.id) throw new Error("Edge id must be a non-empty string");
-	if (!config.sourceId) throw new Error("Edge sourceId must be a non-empty string");
-	if (!config.targetId) throw new Error("Edge targetId must be a non-empty string");
-	const edge = {
-		type: "edge",
-		id: config.id,
-		sourceId: config.sourceId,
-		targetId: config.targetId,
-		label: config.label ?? null,
-		data: config.data ?? null
-	};
-	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;
-	if (config.width !== void 0) edge.width = config.width;
-	if (config.height !== void 0) edge.height = config.height;
-	if (config.color !== void 0) edge.color = config.color;
-	if (config.style !== void 0) edge.style = config.style;
-	return edge;
-}
-/**
-* Create a graph from a config. Resolves defaults for all fields.
-*
-* @example
-* ```ts
-* const graph = createGraph({
-*   nodes: [{ id: 'a' }, { id: 'b' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
-* });
-* ```
-*/
-function createGraph(config) {
-	const graph = {
-		id: config?.id ?? "",
-		mode: config?.mode ?? "directed",
-		initialNodeId: config?.initialNodeId ?? null,
-		nodes: (config?.nodes ?? []).map(createGraphNode),
-		edges: (config?.edges ?? []).map(createGraphEdge),
-		data: config?.data ?? null
-	};
-	if (config?.direction !== void 0) graph.direction = config.direction;
-	if (config?.style !== void 0) graph.style = config.style;
-	return graph;
-}
-/**
-* Create a visual graph with required position/size on all nodes and edges.
-*
-* @example
-* ```ts
-* const graph = createVisualGraph({
-*   nodes: [{ id: 'a', x: 0, y: 0, width: 100, height: 50 }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'a', x: 0, y: 0, width: 0, height: 0 }],
-* });
-* // graph.nodes[0].x === 0
-* ```
-*/
-function createVisualGraph(config) {
-	const base = createGraph(config);
-	return {
-		...base,
-		direction: config?.direction ?? "down",
-		nodes: base.nodes.map((n) => {
-			const { ports, ...rest } = n;
-			return {
-				...rest,
-				x: n.x ?? 0,
-				y: n.y ?? 0,
-				width: n.width ?? 0,
-				height: n.height ?? 0,
-				...n.shape !== void 0 && { shape: n.shape },
-				...ports !== void 0 && { ports: ports.map((p) => ({
-					...p,
-					x: p.x ?? 0,
-					y: p.y ?? 0,
-					width: p.width ?? 0,
-					height: p.height ?? 0
-				})) }
-			};
-		}),
-		edges: base.edges.map((e) => ({
-			...e,
-			x: e.x ?? 0,
-			y: e.y ?? 0,
-			width: e.width ?? 0,
-			height: e.height ?? 0
-		}))
-	};
-}
-/**
-* Create a graph by BFS exploration of a transition function.
-* Each unique state becomes a node; each (state, event) -> nextState becomes an edge.
-*
-* - Node IDs are determined by `serializeState` (default: `JSON.stringify`).
-* - Edge IDs use the format `sourceId|serializedEvent|targetId` for uniqueness
-*   and debuggability. Edge labels are just the serialized event string.
-*
-* @example
-* ```ts
-* const graph = createGraphFromTransition(
-*   (state, event) => {
-*     if (state === 'green' && event === 'TIMER') return 'yellow';
-*     if (state === 'yellow' && event === 'TIMER') return 'red';
-*     if (state === 'red' && event === 'TIMER') return 'green';
-*     return state;
-*   },
-*   {
-*     initialState: 'green',
-*     events: ['TIMER'],
-*     serializeState: (s) => s,
-*     serializeEvent: (e) => e,
-*   },
-* );
-* // graph.nodes.length === 3
-* ```
-*/
-function createGraphFromTransition(transition, options) {
-	const serializeState = options.serializeState ?? JSON.stringify;
-	const serializeEvent = options.serializeEvent ?? JSON.stringify;
-	const limit = options.limit ?? Infinity;
-	const getEvents = typeof options.events === "function" ? options.events : () => options.events;
-	const nodes = [];
-	const edges = [];
-	const visited = /* @__PURE__ */ new Set();
-	const edgeSet = /* @__PURE__ */ new Set();
-	const queue = [options.initialState];
-	const initialStateId = serializeState(options.initialState);
-	visited.add(initialStateId);
-	nodes.push({
-		id: initialStateId,
-		label: initialStateId,
-		data: options.initialState
-	});
-	let iterations = 0;
-	while (queue.length > 0) {
-		const state = queue.shift();
-		const stateId = serializeState(state);
-		if (++iterations > limit) throw new Error("Traversal limit exceeded");
-		if (options.stopWhen?.(state)) continue;
-		const events = getEvents(state);
-		for (const event of events) {
-			const nextState = transition(state, event);
-			const nextStateId = serializeState(nextState);
-			const eventStr = serializeEvent(event);
-			if (!visited.has(nextStateId)) {
-				visited.add(nextStateId);
-				nodes.push({
-					id: nextStateId,
-					label: nextStateId,
-					data: nextState
-				});
-				queue.push(nextState);
-			}
-			const edgeKey = `${stateId}|${eventStr}|${nextStateId}`;
-			if (!edgeSet.has(edgeKey)) {
-				edgeSet.add(edgeKey);
-				edges.push({
-					id: edgeKey,
-					sourceId: stateId,
-					targetId: nextStateId,
-					label: eventStr,
-					data: event
-				});
-			}
-		}
-	}
-	return createGraph({
-		id: options.id ?? "",
-		mode: "directed",
-		initialNodeId: initialStateId,
-		nodes,
-		edges
-	});
-}
-/**
-* Get a node by id, or `undefined` if not found.
-*
-* @example
-* ```ts
-* const graph = createGraph({ nodes: [{ id: 'a' }] });
-* const node = getNode(graph, 'a'); // GraphNode
-* const missing = getNode(graph, 'z'); // undefined
-* ```
-*/
-function getNode(graph, id) {
-	const arrayIdx = getIndex(graph).nodeById.get(id);
-	return arrayIdx !== void 0 ? graph.nodes[arrayIdx] : void 0;
-}
-/**
-* Get an edge by id, or `undefined` if not found.
-*
-* @example
-* ```ts
-* const graph = createGraph({
-*   nodes: [{ id: 'a' }, { id: 'b' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
-* });
-* const edge = getEdge(graph, 'e1'); // GraphEdge
-* const missing = getEdge(graph, 'z'); // undefined
-* ```
-*/
-function getEdge(graph, id) {
-	const arrayIdx = getIndex(graph).edgeById.get(id);
-	return arrayIdx !== void 0 ? graph.edges[arrayIdx] : void 0;
-}
-/**
-* Check if a node exists in the graph.
-*
-* @example
-* ```ts
-* const graph = createGraph({ nodes: [{ id: 'a' }] });
-* hasNode(graph, 'a'); // true
-* hasNode(graph, 'z'); // false
-* ```
-*/
-function hasNode(graph, id) {
-	return getIndex(graph).nodeById.has(id);
-}
-/**
-* Check if an edge exists in the graph.
-*
-* @example
-* ```ts
-* const graph = createGraph({
-*   nodes: [{ id: 'a' }, { id: 'b' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
-* });
-* hasEdge(graph, 'e1'); // true
-* hasEdge(graph, 'z'); // false
-* ```
-*/
-function hasEdge(graph, id) {
-	return getIndex(graph).edgeById.has(id);
-}
-/**
-* **Mutable.** Add a node to the graph. Mutates `graph.nodes` in place.
-* @returns The resolved node that was added.
-*
-* @example
-* ```ts
-* const graph = createGraph();
-* const node = addNode(graph, { id: 'a', label: 'Node A' });
-* // graph.nodes.length === 1
-* ```
-*/
-function addNode(graph, config) {
-	const node = createGraphNode(config);
-	const idx = getIndex(graph);
-	if (idx.nodeById.has(config.id)) throw new Error(`Node "${config.id}" already exists`);
-	if (config.parentId && !idx.nodeById.has(config.parentId)) throw new Error(`Parent node "${config.parentId}" does not exist`);
-	indexAddNode(idx, node, graph.nodes.push(node) - 1);
-	return node;
-}
-/**
-* **Mutable.** Add an edge to the graph. Mutates `graph.edges` in place.
-* @returns The resolved edge that was added.
-*
-* @example
-* ```ts
-* const graph = createGraph({ nodes: [{ id: 'a' }, { id: 'b' }] });
-* const edge = addEdge(graph, { id: 'e1', sourceId: 'a', targetId: 'b' });
-* // graph.edges.length === 1
-* ```
-*/
-function addEdge(graph, config) {
-	const edge = createGraphEdge(config);
-	const idx = getIndex(graph);
-	if (idx.edgeById.has(config.id)) throw new Error(`Edge "${config.id}" already exists`);
-	if (!idx.nodeById.has(config.sourceId)) throw new Error(`Source node "${config.sourceId}" does not exist`);
-	if (!idx.nodeById.has(config.targetId)) throw new Error(`Target node "${config.targetId}" does not exist`);
-	if (config.sourcePort !== void 0) {
-		if (!graph.nodes[idx.nodeById.get(config.sourceId)].ports?.some((p) => p.name === config.sourcePort)) throw new Error(`Port "${config.sourcePort}" does not exist on source node "${config.sourceId}"`);
-	}
-	if (config.targetPort !== void 0) {
-		if (!graph.nodes[idx.nodeById.get(config.targetId)].ports?.some((p) => p.name === config.targetPort)) throw new Error(`Port "${config.targetPort}" does not exist on target node "${config.targetId}"`);
-	}
-	indexAddEdge(idx, edge, graph.edges.push(edge) - 1);
-	return edge;
-}
-/**
-* **Mutable.** Delete a node and its connected edges. Mutates `graph.nodes`
-* and `graph.edges` in place.
-*
-* By default, children are deleted recursively.
-* With `{ reparent: true }`, children are re-parented to the deleted node's parent.
-*
-* @example
-* ```ts
-* const graph = createGraph({
-*   nodes: [{ id: 'a' }, { id: 'b' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
-* });
-* deleteNode(graph, 'a');
-* // graph.nodes.length === 1, edge e1 also removed
-* ```
-*/
-function deleteNode(graph, id, opts) {
-	const node = getNode(graph, id);
-	if (!node) throw new Error(`Node "${id}" does not exist`);
-	if (opts?.reparent) {
-		for (const n of graph.nodes) if (n.parentId === id) n.parentId = node.parentId;
-		graph.nodes = graph.nodes.filter((n) => n.id !== id);
-		graph.edges = graph.edges.filter((e) => e.sourceId !== id && e.targetId !== id);
-	} else {
-		const toDelete = collectDescendants(graph, id);
-		graph.nodes = graph.nodes.filter((n) => !toDelete.has(n.id));
-		graph.edges = graph.edges.filter((e) => !toDelete.has(e.sourceId) && !toDelete.has(e.targetId));
-	}
-	invalidateIndex(graph);
-}
-/**
-* **Mutable.** Delete an edge. Mutates `graph.edges` in place.
-*
-* @example
-* ```ts
-* const graph = createGraph({
-*   nodes: [{ id: 'a' }, { id: 'b' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
-* });
-* deleteEdge(graph, 'e1');
-* // graph.edges.length === 0
-* ```
-*/
-function deleteEdge(graph, id) {
-	if (!hasEdge(graph, id)) throw new Error(`Edge "${id}" does not exist`);
-	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', x: 100 });
-* // updated.label === 'new', updated.x === 100
-* ```
-*/
-function updateNode(graph, id, update) {
-	const idx = getIndex(graph);
-	const arrayIdx = idx.nodeById.get(id);
-	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 != 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 }
-	};
-	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
-* ```ts
-* const graph = createGraph({
-*   nodes: [{ id: 'a' }, { id: 'b' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b', label: 'old' }],
-* });
-* const updated = updateEdge(graph, 'e1', { label: 'new', weight: 2 });
-* // updated.label === 'new', updated.weight === 2
-* ```
-*/
-function updateEdge(graph, id, update) {
-	const idx = getIndex(graph);
-	const arrayIdx = idx.edgeById.get(id);
-	if (arrayIdx === void 0) throw new Error(`Edge "${id}" does not exist`);
-	if (update.sourceId !== void 0 && !idx.nodeById.has(update.sourceId)) throw new Error(`Source node "${update.sourceId}" does not exist`);
-	if (update.targetId !== void 0 && !idx.nodeById.has(update.targetId)) throw new Error(`Target node "${update.targetId}" does not exist`);
-	const edge = graph.edges[arrayIdx];
-	const oldSourceId = edge.sourceId;
-	const oldTargetId = edge.targetId;
-	const effectiveSourceId = update.sourceId ?? edge.sourceId;
-	const effectiveTargetId = update.targetId ?? edge.targetId;
-	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 (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 }
-	};
-	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;
-}
-/**
-* **Mutable.** Add multiple nodes and edges to the graph.
-* Nodes are added first, then edges (so edges can reference new nodes).
-*
-* @example
-* ```ts
-* const graph = createGraph();
-* addEntities(graph, {
-*   nodes: [{ id: 'a' }, { id: 'b' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
-* });
-* // graph.nodes.length === 2, graph.edges.length === 1
-* ```
-*/
-function addEntities(graph, entities) {
-	for (const nodeConfig of entities.nodes ?? []) addNode(graph, nodeConfig);
-	for (const edgeConfig of entities.edges ?? []) addEdge(graph, edgeConfig);
-}
-/**
-* **Mutable.** Delete entities by id(s). Automatically detects whether each id
-* is a node or edge. Node deletions cascade to children and connected edges.
-*
-* @example
-* ```ts
-* const graph = createGraph({
-*   nodes: [{ id: 'a' }, { id: 'b' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
-* });
-* deleteEntities(graph, ['a', 'e1']);
-* // graph.nodes.length === 1, graph.edges.length === 0
-* ```
-*/
-function deleteEntities(graph, ids, opts) {
-	const idArray = Array.isArray(ids) ? ids : [ids];
-	for (const id of idArray) if (hasNode(graph, id)) deleteNode(graph, id, opts);
-	else if (hasEdge(graph, id)) deleteEdge(graph, id);
-}
-/**
-* **Mutable.** Update multiple nodes and edges in place.
-* Each entry must include an `id` to identify which entity to update.
-*
-* @example
-* ```ts
-* const graph = createGraph({
-*   nodes: [{ id: 'a', label: 'old' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'a', label: 'old' }],
-* });
-* updateEntities(graph, {
-*   nodes: [{ id: 'a', label: 'new' }],
-*   edges: [{ id: 'e1', label: 'new' }],
-* });
-* ```
-*/
-function updateEntities(graph, updates) {
-	for (const nodeUpdate of updates.nodes ?? []) {
-		const { id, ...patch } = nodeUpdate;
-		updateNode(graph, id, patch);
-	}
-	for (const edgeUpdate of updates.edges ?? []) {
-		const { id, ...patch } = edgeUpdate;
-		updateEdge(graph, id, patch);
-	}
-}
-/**
-* OOP wrapper around a plain `Graph` object.
-* Delegates to the standalone mutable functions.
-*
-* @example
-* ```ts
-* const instance = new GraphInstance({
-*   nodes: [{ id: 'a' }, { id: 'b' }],
-*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
-* });
-* instance.addNode({ id: 'c' });
-* instance.hasNode('c'); // true
-* instance.toJSON(); // plain Graph object
-* ```
-*/
-var GraphInstance = class GraphInstance {
-	graph;
-	constructor(config) {
-		this.graph = createGraph(config);
-	}
-	/**
-	* Wrap an existing plain graph object.
-	*
-	* @example
-	* ```ts
-	* const graph = createGraph({ nodes: [{ id: 'a' }] });
-	* const instance = GraphInstance.from(graph);
-	* instance.hasNode('a'); // true
-	* ```
-	*/
-	static from(graph) {
-		const instance = Object.create(GraphInstance.prototype);
-		instance.graph = graph;
-		return instance;
-	}
-	get id() {
-		return this.graph.id;
-	}
-	/** Default directedness for all edges. */
-	get mode() {
-		return this.graph.mode;
-	}
-	get nodes() {
-		return this.graph.nodes;
-	}
-	get edges() {
-		return this.graph.edges;
-	}
-	get data() {
-		return this.graph.data;
-	}
-	getNode(id) {
-		return getNode(this.graph, id);
-	}
-	getEdge(id) {
-		return getEdge(this.graph, id);
-	}
-	hasNode(id) {
-		return hasNode(this.graph, id);
-	}
-	hasEdge(id) {
-		return hasEdge(this.graph, id);
-	}
-	addNode(config) {
-		return addNode(this.graph, config);
-	}
-	addEdge(config) {
-		return addEdge(this.graph, config);
-	}
-	deleteNode(id, opts) {
-		return deleteNode(this.graph, id, opts);
-	}
-	deleteEdge(id) {
-		return deleteEdge(this.graph, id);
-	}
-	updateNode(id, update) {
-		return updateNode(this.graph, id, update);
-	}
-	updateEdge(id, update) {
-		return updateEdge(this.graph, id, update);
-	}
-	addEntities(entities) {
-		return addEntities(this.graph, entities);
-	}
-	deleteEntities(ids, opts) {
-		return deleteEntities(this.graph, ids, opts);
-	}
-	updateEntities(updates) {
-		return updateEntities(this.graph, updates);
-	}
-	toJSON() {
-		return this.graph;
-	}
-};
-function collectDescendants(graph, id) {
-	const idx = getIndex(graph);
-	const toDelete = /* @__PURE__ */ new Set();
-	const walk = (nodeId) => {
-		toDelete.add(nodeId);
-		const childIds = idx.childNodes.get(nodeId) ?? [];
-		for (const childId of childIds) if (!toDelete.has(childId)) walk(childId);
-	};
-	walk(id);
-	return toDelete;
-}
-
-//#endregion
 //#region src/algorithms/shared.ts
 var MinPriorityQueue = class {
 	items = [];
@@ -764,6 +52,19 @@ var MinPriorityQueue = class {
 	}
 };
 /**
+* Seeded PRNG (mulberry32). Same generator as src/walks.ts — kept here so
+* algorithm modules and generators can share it without importing walks.
+*/
+function mulberry32(seed) {
+	let s = seed | 0;
+	return () => {
+		s = s + 1831565813 | 0;
+		let t = Math.imul(s ^ s >>> 15, 1 | s);
+		t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+}
+/**
 * 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`.
@@ -954,19 +255,84 @@ function buildCSR(graph) {
 
 //#endregion
 //#region src/algorithms/paths.ts
+/**
+* Flat binary min-heap of `(distance, node position)` entries in parallel
+* typed arrays. The Dijkstra/A* hot loops push one entry per relaxation, so
+* avoiding a `{ pos, dist }` wrapper object per push (allocation + property
+* loads in the sift comparisons) is a measurable win on 10k+ node graphs.
+* Sifts move "holes" instead of swapping, halving array writes.
+*/
+var TypedMinHeap = class {
+	keys;
+	vals;
+	size = 0;
+	constructor(capacity) {
+		const cap = Math.max(capacity, 16);
+		this.keys = new Float64Array(cap);
+		this.vals = new Int32Array(cap);
+	}
+	push(key, val) {
+		if (this.size === this.keys.length) {
+			const keys$1 = new Float64Array(this.keys.length * 2);
+			const vals$1 = new Int32Array(this.vals.length * 2);
+			keys$1.set(this.keys);
+			vals$1.set(this.vals);
+			this.keys = keys$1;
+			this.vals = vals$1;
+		}
+		const { keys, vals } = this;
+		let hole = this.size++;
+		while (hole > 0) {
+			const parent = hole - 1 >> 1;
+			if (keys[parent] <= key) break;
+			keys[hole] = keys[parent];
+			vals[hole] = vals[parent];
+			hole = parent;
+		}
+		keys[hole] = key;
+		vals[hole] = val;
+	}
+	/** Key of the minimum entry; garbage when empty (check `size` first). */
+	peekKey() {
+		return this.keys[0];
+	}
+	/** Value of the minimum entry; garbage when empty (check `size` first). */
+	peekVal() {
+		return this.vals[0];
+	}
+	/** Remove the minimum entry (no-op shape: read via peek* first). */
+	pop() {
+		const { keys, vals } = this;
+		const last = --this.size;
+		if (last === 0) return;
+		const key = keys[last];
+		const val = vals[last];
+		let hole = 0;
+		for (;;) {
+			let child = hole * 2 + 1;
+			if (child >= last) break;
+			const right = child + 1;
+			if (right < last && keys[right] < keys[child]) child = right;
+			if (keys[child] >= key) break;
+			keys[hole] = keys[child];
+			vals[hole] = vals[child];
+			hole = child;
+		}
+		keys[hole] = key;
+		vals[hole] = val;
+	}
+};
 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, []);
+	if (algorithm === "bellman-ford") return bellmanFordTyped(graph, sourceId, getWeight);
 	const csr = getCSR(graph);
+	const n = csr.ids.length;
 	const source = csr.indexOf.get(sourceId);
 	if (source === void 0) return {
-		dist,
-		prev
+		source: -1,
+		distArr: new Float64Array(0),
+		prevArr: [],
+		stopDistance: Infinity
 	};
-	const n = csr.ids.length;
 	const distArr = new Float64Array(n).fill(Infinity);
 	const prevArr = new Array(n);
 	distArr[source] = 0;
@@ -996,13 +362,12 @@ function computeShortestDistances(graph, sourceId, getWeight, algorithm, stopAtI
 	} else {
 		const effectiveWeight = getWeight ?? ((edge) => edge.weight ?? 1);
 		const visited = new Uint8Array(n);
-		const pq = new MinPriorityQueue((a, b) => a.dist - b.dist);
-		pq.push({
-			pos: source,
-			dist: 0
-		});
+		const pq = new TypedMinHeap(n);
+		pq.push(0, source);
 		while (pq.size > 0) {
-			const { pos: u, dist: distance } = pq.pop();
+			const distance = pq.peekKey();
+			const u = pq.peekVal();
+			pq.pop();
 			if (visited[u] || distance !== distArr[u]) continue;
 			if (distance > stopDistance) break;
 			if (u === stopAt) stopDistance = distance;
@@ -1016,28 +381,48 @@ function computeShortestDistances(graph, sourceId, getWeight, algorithm, stopAtI
 				if (nextDistance < distArr[v]) {
 					distArr[v] = nextDistance;
 					prevArr[v] = [u, csr.outEdgeIndex[a]];
-					pq.push({
-						pos: v,
-						dist: nextDistance
-					});
+					pq.push(nextDistance, v);
 				} 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 {
+		source,
+		distArr,
+		prevArr,
+		stopDistance
+	};
+}
+/**
+* Bellman-Ford adapted to the typed-array result shape. The O(VE) relaxation
+* dominates, so the id→position conversion here is noise — and it keeps a
+* single reconstruction path for both algorithms.
+*/
+function bellmanFordTyped(graph, sourceId, getWeight) {
+	const { dist, prev } = bellmanFord(graph, sourceId, getWeight);
+	const csr = getCSR(graph);
+	const idx = getIndex(graph);
+	const n = csr.ids.length;
+	const distArr = new Float64Array(n).fill(Infinity);
+	const prevArr = new Array(n);
+	for (const [id, distance] of dist) {
+		const pos = csr.indexOf.get(id);
+		if (pos === void 0) continue;
+		distArr[pos] = distance;
+		const pairs = [];
+		for (const { from, edge } of prev.get(id) ?? []) {
+			const fromPos = csr.indexOf.get(from);
+			const edgeIndex = idx.edgeById.get(edge.id);
+			if (fromPos === void 0 || edgeIndex === void 0) continue;
+			pairs.push(fromPos, edgeIndex);
+		}
+		prevArr[pos] = pairs;
 	}
 	return {
-		dist,
-		prev
+		source: csr.indexOf.get(sourceId) ?? -1,
+		distArr,
+		prevArr,
+		stopDistance: Infinity
 	};
 }
 function bellmanFord(graph, sourceId, getWeight) {
@@ -1100,22 +485,23 @@ function bellmanFord(graph, sourceId, getWeight) {
 		prev
 	};
 }
-function* reconstructPaths(graph, prev, sourceNode, targetId, onPath = /* @__PURE__ */ new Set()) {
-	if (targetId === sourceNode.id) {
+function* reconstructPathsAt(graph, prevArr, sourceNode, sourcePos, targetPos, onPath = /* @__PURE__ */ new Set()) {
+	if (targetPos === sourcePos) {
 		yield {
 			source: sourceNode,
 			steps: []
 		};
 		return;
 	}
-	const predecessors = prev.get(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);
-	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 {
+	const pairs = prevArr[targetPos];
+	if (!pairs || pairs.length === 0) return;
+	const targetNode = graph.nodes[targetPos];
+	onPath.add(targetPos);
+	for (let k = 0; k < pairs.length; k += 2) {
+		const fromPos = pairs[k];
+		if (onPath.has(fromPos)) continue;
+		const edge = graph.edges[pairs[k + 1]];
+		for (const prefix of reconstructPathsAt(graph, prevArr, sourceNode, sourcePos, fromPos, onPath)) yield {
 			source: sourceNode,
 			steps: [...prefix.steps, {
 				edge,
@@ -1123,16 +509,30 @@ function* reconstructPaths(graph, prev, sourceNode, targetId, onPath = /* @__PUR
 			}]
 		};
 	}
-	onPath.delete(targetId);
+	onPath.delete(targetPos);
 }
 function* genShortestPaths(graph, opts) {
-	const idx = getIndex(graph);
 	const sourceId = resolveFrom(graph, opts);
-	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);
-	for (const targetId of targets) yield* reconstructPaths(graph, prev, sourceNode, targetId);
+	const { source, distArr, prevArr, stopDistance } = computeShortestDistances(graph, sourceId, opts?.getWeight, opts?.algorithm, opts?.to);
+	const sourceNode = source !== -1 ? graph.nodes[source] : graph.nodes.find((node) => node.id === sourceId);
+	if (source === -1) {
+		if (opts?.to === sourceId) yield {
+			source: sourceNode,
+			steps: []
+		};
+		return;
+	}
+	const csr = getCSR(graph);
+	if (opts?.to) {
+		const target = csr.indexOf.get(opts.to);
+		if (target === void 0 || distArr[target] === Infinity || distArr[target] > stopDistance) return;
+		yield* reconstructPathsAt(graph, prevArr, sourceNode, source, target);
+		return;
+	}
+	for (let target = 0; target < distArr.length; target++) {
+		if (target === source || distArr[target] === Infinity || distArr[target] > stopDistance) continue;
+		yield* reconstructPathsAt(graph, prevArr, sourceNode, source, target);
+	}
 }
 function getShortestPaths(graph, opts) {
 	return [...genShortestPaths(graph, opts)];
@@ -1193,35 +593,30 @@ function bidirectionalShortestPath(graph, sourceId, targetId, getWeight) {
 	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);
+	const pqF = new TypedMinHeap(n);
+	const pqB = new TypedMinHeap(n);
 	distF[source] = 0;
 	distB[target] = 0;
-	pqF.push({
-		pos: source,
-		dist: 0
-	});
-	pqB.push({
-		pos: target,
-		dist: 0
-	});
+	pqF.push(0, source);
+	pqB.push(0, target);
 	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]) {
+		while (pq.size > 0) {
+			const key = pq.peekKey();
+			const pos = pq.peekVal();
+			if (settled[pos] || key !== dist[pos]) {
 				pq.pop();
 				continue;
 			}
-			return top.dist;
+			return key;
 		}
 	};
 	const scanForward = () => {
-		const { pos: u, dist: d } = pqF.pop();
+		const d = pqF.peekKey();
+		const u = pqF.peekVal();
+		pqF.pop();
 		settledF[u] = 1;
 		for (let a = csr.outOffsets[u]; a < csr.outOffsets[u + 1]; a++) {
 			const edge = graph.edges[csr.outEdgeIndex[a]];
@@ -1232,10 +627,7 @@ function bidirectionalShortestPath(graph, sourceId, targetId, getWeight) {
 				distF[v] = next;
 				predF[v] = u;
 				predFEdge[v] = csr.outEdgeIndex[a];
-				pqF.push({
-					pos: v,
-					dist: next
-				});
+				pqF.push(next, v);
 			}
 			if (distB[v] !== Infinity && next + distB[v] < mu) {
 				mu = next + distB[v];
@@ -1244,7 +636,9 @@ function bidirectionalShortestPath(graph, sourceId, targetId, getWeight) {
 		}
 	};
 	const scanBackward = () => {
-		const { pos: u, dist: d } = pqB.pop();
+		const d = pqB.peekKey();
+		const u = pqB.peekVal();
+		pqB.pop();
 		settledB[u] = 1;
 		for (let a = csr.inOffsets[u]; a < csr.inOffsets[u + 1]; a++) {
 			const edge = graph.edges[csr.inEdgeIndex[a]];
@@ -1255,10 +649,7 @@ function bidirectionalShortestPath(graph, sourceId, targetId, getWeight) {
 				distB[v] = next;
 				predB[v] = u;
 				predBEdge[v] = csr.inEdgeIndex[a];
-				pqB.push({
-					pos: v,
-					dist: next
-				});
+				pqB.push(next, v);
 			}
 			if (distF[v] !== Infinity && next + distF[v] < mu) {
 				mu = next + distF[v];
@@ -1642,15 +1033,13 @@ function getAStarPath(graph, opts) {
 	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);
+	const openSet = new TypedMinHeap(n);
 	assertNoNegativeWeights(graph, csr, opts.getWeight, "A*", "Use getShortestPath with { algorithm: 'bellman-ford' } instead.");
 	gScore[source] = 0;
-	openSet.push({
-		pos: source,
-		f: heuristic(sourceId)
-	});
+	openSet.push(heuristic(sourceId), source);
 	while (openSet.size > 0) {
-		const { pos: current } = openSet.pop();
+		const current = openSet.peekVal();
+		openSet.pop();
 		if (closed[current]) continue;
 		if (current === target) {
 			const steps = [];
@@ -1678,15 +1067,12 @@ function getAStarPath(graph, opts) {
 				cameFromPos[neighbor] = current;
 				cameFromEdge[neighbor] = csr.outEdgeIndex[a];
 				gScore[neighbor] = tentativeScore;
-				openSet.push({
-					pos: neighbor,
-					f: tentativeScore + heuristic(csr.ids[neighbor])
-				});
+				openSet.push(tentativeScore + heuristic(csr.ids[neighbor]), neighbor);
 			}
 		}
 	}
 }
-function joinPaths(headPath, tailPath) {
+function getJoinedPath(headPath, tailPath) {
 	const headEnd = headPath.steps.length > 0 ? headPath.steps[headPath.steps.length - 1].node : headPath.source;
 	if (headEnd.id !== tailPath.source.id) throw new Error(`Paths cannot be joined: head path ends at "${headEnd.id}" but tail path starts at "${tailPath.source.id}"`);
 	return {
@@ -1694,57 +1080,11 @@ function joinPaths(headPath, tailPath) {
 		steps: [...headPath.steps, ...tailPath.steps]
 	};
 }
-
-//#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.
+* @deprecated Use {@link getJoinedPath}.
 */
-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;
+function joinPaths(headPath, tailPath) {
+	return getJoinedPath(headPath, tailPath);
 }
 
 //#endregion
@@ -1759,7 +1099,7 @@ function toEdgeConfig(edge) {
 *
 * @example
 * ```ts
-* import { createGraph, flatten } from '@statelyai/graph';
+* import { createGraph, getFlattenedGraph } from '@statelyai/graph';
 *
 * const graph = createGraph({
 *   nodes: [
@@ -1771,12 +1111,12 @@ function toEdgeConfig(edge) {
 *   edges: [{ id: 'e1', sourceId: 'other', targetId: 'parent' }],
 * });
 *
-* const flat = flatten(graph);
+* const flat = getFlattenedGraph(graph);
 * // flat.nodes → [child1, child2, other] (leaf nodes only)
 * // flat.edges → edge from 'other' → 'child1' (resolved via initialNodeId)
 * ```
 */
-function flatten(graph) {
+function getFlattenedGraph(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);
@@ -1843,6 +1183,12 @@ function flatten(graph) {
 	});
 }
 /**
+* @deprecated Use {@link getFlattenedGraph}.
+*/
+function flatten(graph) {
+	return getFlattenedGraph(graph);
+}
+/**
 * Convert a node to a config, stripping parentId/initialNodeId references
 * to nodes outside the given set.
 */
@@ -1893,7 +1239,7 @@ function getSubgraph(graph, nodeIds) {
 *
 * @example
 * ```ts
-* import { createGraph, reverseGraph } from '@statelyai/graph';
+* import { createGraph, getReversedGraph } from '@statelyai/graph';
 *
 * const graph = createGraph({
 *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
@@ -1903,14 +1249,14 @@ function getSubgraph(graph, nodeIds) {
 *   ],
 * });
 *
-* const rev = reverseGraph(graph);
+* const rev = getReversedGraph(graph);
 * // rev edges: b→a, c→b
 *
-* const filtered = reverseGraph(graph, (e) => e.id !== 'bc');
+* const filtered = getReversedGraph(graph, (e) => e.id !== 'bc');
 * // filtered edges: b→a (only ab reversed, bc excluded)
 * ```
 */
-function reverseGraph(graph, filterEdge) {
+function getReversedGraph(graph, filterEdge) {
 	const edges = filterEdge ? graph.edges.filter(filterEdge) : graph.edges;
 	return createGraph({
 		id: graph.id,
@@ -1930,10 +1276,16 @@ function reverseGraph(graph, filterEdge) {
 		data: graph.data
 	});
 }
+/**
+* @deprecated Use {@link getReversedGraph}.
+*/
+function reverseGraph(graph, filterEdge) {
+	return getReversedGraph(graph, filterEdge);
+}
 
 //#endregion
 //#region src/algorithms/traversal.ts
-function* bfs(graph, startId) {
+function* genBFS(graph, startId) {
 	const csr = getCSR(graph);
 	const start = csr.indexOf.get(startId);
 	if (start === void 0) return;
@@ -1956,7 +1308,13 @@ function* bfs(graph, startId) {
 		}
 	}
 }
-function* dfs(graph, startId) {
+/**
+* @deprecated Use {@link genBFS}.
+*/
+function* bfs(graph, startId) {
+	yield* genBFS(graph, startId);
+}
+function* genDFS(graph, startId) {
 	const csr = getCSR(graph);
 	const start = csr.indexOf.get(startId);
 	if (start === void 0) return;
@@ -1974,6 +1332,12 @@ function* dfs(graph, startId) {
 		}
 	}
 }
+/**
+* @deprecated Use {@link genDFS}.
+*/
+function* dfs(graph, startId) {
+	yield* genDFS(graph, startId);
+}
 function isAcyclic(graph) {
 	const kind = getEffectiveModeKind(graph);
 	if (kind === "mixed") return isAcyclicMixed(graph);
@@ -2636,31 +2000,366 @@ function getHITS(graph, options) {
 /**
 * Returns eigenvector centrality scores for all nodes.
 *
-* Uses power iteration over incoming neighbors for directed graphs and
-* undirected adjacency for undirected graphs.
+* Power iteration with the `A + I` shift (same scheme as graphology and
+* networkx, so bipartite structures converge instead of oscillating).
+* Scores flow along edge direction: a node's score is fed by its incoming
+* neighbors; undirected edges feed both endpoints. The result vector is
+* Euclidean (L2) normalized.
+*
+* Throws when the iteration has not converged (L1 error < `n × tolerance`)
+* within `maxIterations`.
 */
 function getEigenvectorCentrality(graph, options) {
 	if (getNodeIds(graph).length === 0) return {};
 	const maxIterations = options?.maxIterations ?? 100;
 	const tolerance = options?.tolerance ?? 1e-6;
+	const getWeight = options?.getWeight;
 	const csr = getCSR(graph);
 	const n = csr.ids.length;
-	let current = new Float64Array(n).fill(1);
-	normalizeTypedVector(current);
+	let current = new Float64Array(n).fill(1 / n);
+	let converged = false;
 	for (let iteration = 0; iteration < maxIterations; iteration++) {
-		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]];
+		const next = Float64Array.from(current);
+		for (let w = 0; w < n; w++) for (let a = csr.inOffsets[w]; a < csr.inOffsets[w + 1]; a++) {
+			const weight = getWeight ? getWeight(graph.edges[csr.inEdgeIndex[a]]) : 1;
+			next[w] += current[csr.inOrigins[a]] * weight;
+		}
 		normalizeTypedVector(next);
-		let diff = 0;
-		for (let i = 0; i < n; i++) diff = Math.max(diff, Math.abs(current[i] - next[i]));
+		let error = 0;
+		for (let i = 0; i < n; i++) error += Math.abs(next[i] - current[i]);
 		current = next;
-		if (diff <= tolerance) break;
+		if (error < n * tolerance) {
+			converged = true;
+			break;
+		}
+	}
+	if (!converged) throw new Error(`getEigenvectorCentrality: power iteration failed to converge within ${maxIterations} iterations (tolerance ${tolerance}) — increase options.maxIterations or loosen options.tolerance`);
+	const scores = createEmptyScoreMap(graph);
+	for (let i = 0; i < n; i++) scores[csr.ids[i]] = current[i];
+	return scores;
+}
+/**
+* Returns Katz centrality scores for all nodes.
+*
+* Iterates `x' = alpha · Aᵀx + beta` to its fixed point (networkx-style),
+* then Euclidean (L2) normalizes the result. Scores flow along edge
+* direction: a node's score is fed by its incoming neighbors; undirected
+* edges feed both endpoints.
+*
+* Converges only when `alpha` is below the reciprocal of the largest
+* eigenvalue of the adjacency matrix; throws when the iteration has not
+* converged (L1 error < `n × tolerance`) within `maxIterations`.
+*/
+function getKatzCentrality(graph, options) {
+	if (getNodeIds(graph).length === 0) return {};
+	const alpha = options?.alpha ?? .1;
+	const beta = options?.beta ?? 1;
+	const maxIterations = options?.maxIterations ?? 100;
+	const tolerance = options?.tolerance ?? 1e-6;
+	const getWeight = options?.getWeight;
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	let current = new Float64Array(n);
+	let converged = false;
+	for (let iteration = 0; iteration < maxIterations; iteration++) {
+		const next = new Float64Array(n).fill(beta);
+		for (let w = 0; w < n; w++) for (let a = csr.inOffsets[w]; a < csr.inOffsets[w + 1]; a++) {
+			const weight = getWeight ? getWeight(graph.edges[csr.inEdgeIndex[a]]) : 1;
+			next[w] += alpha * current[csr.inOrigins[a]] * weight;
+		}
+		let error = 0;
+		for (let i = 0; i < n; i++) error += Math.abs(next[i] - current[i]);
+		current = next;
+		if (error < n * tolerance) {
+			converged = true;
+			break;
+		}
 	}
+	if (!converged) throw new Error(`getKatzCentrality: iteration failed to converge within ${maxIterations} iterations — alpha ${alpha} may be >= 1/λ_max of the adjacency matrix; decrease options.alpha or increase options.maxIterations`);
+	normalizeTypedVector(current);
 	const scores = createEmptyScoreMap(graph);
 	for (let i = 0; i < n; i++) scores[csr.ids[i]] = current[i];
 	return scores;
 }
 
+//#endregion
+//#region src/algorithms/cores.ts
+/**
+* Undirected adjacency over node positions: every edge (regardless of mode
+* or direction) contributes both arcs, matching the standard k-core
+* definition. Self-loops are ignored. Positions come from the CSR snapshot
+* so `ids` order matches `graph.nodes`.
+*/
+function buildUndirectedAdjacency(graph) {
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	const m = graph.edges.length;
+	const sourcePos = new Int32Array(m);
+	const targetPos = new Int32Array(m);
+	const degree = new Int32Array(n);
+	let arcCount = 0;
+	for (let e = 0; e < m; e++) {
+		const edge = graph.edges[e];
+		const s = csr.indexOf.get(edge.sourceId);
+		const t = csr.indexOf.get(edge.targetId);
+		if (s === t) {
+			sourcePos[e] = -1;
+			continue;
+		}
+		sourcePos[e] = s;
+		targetPos[e] = t;
+		degree[s]++;
+		degree[t]++;
+		arcCount += 2;
+	}
+	const offsets = new Int32Array(n + 1);
+	for (let i = 0; i < n; i++) offsets[i + 1] = offsets[i] + degree[i];
+	const targets = new Int32Array(arcCount);
+	const cursor = Int32Array.from(offsets.subarray(0, n));
+	for (let e = 0; e < m; e++) {
+		if (sourcePos[e] === -1) continue;
+		targets[cursor[sourcePos[e]]++] = targetPos[e];
+		targets[cursor[targetPos[e]]++] = sourcePos[e];
+	}
+	return {
+		ids: csr.ids,
+		offsets,
+		targets
+	};
+}
+/**
+* Returns the core number of every node (largest `k` such that the node
+* belongs to the k-core).
+*
+* Uses Batagelj–Zaveršnik bucket peeling — O(m). Edges are treated as
+* undirected (the standard k-core definition); self-loops are ignored.
+*
+* @example
+* ```ts
+* const cores = getCoreNumbers(graph);
+* console.log(cores.a); // 3
+* ```
+*/
+function getCoreNumbers(graph) {
+	const { ids, offsets, targets } = buildUndirectedAdjacency(graph);
+	const n = ids.length;
+	const core = new Int32Array(n);
+	let maxDegree = 0;
+	for (let i = 0; i < n; i++) {
+		core[i] = offsets[i + 1] - offsets[i];
+		if (core[i] > maxDegree) maxDegree = core[i];
+	}
+	const bin = new Int32Array(maxDegree + 1);
+	for (let i = 0; i < n; i++) bin[core[i]]++;
+	let start = 0;
+	for (let d = 0; d <= maxDegree; d++) {
+		const count = bin[d];
+		bin[d] = start;
+		start += count;
+	}
+	const vert = new Int32Array(n);
+	const pos = new Int32Array(n);
+	for (let i = 0; i < n; i++) {
+		pos[i] = bin[core[i]];
+		vert[pos[i]] = i;
+		bin[core[i]]++;
+	}
+	for (let d = maxDegree; d > 0; d--) bin[d] = bin[d - 1];
+	bin[0] = 0;
+	for (let k = 0; k < n; k++) {
+		const v = vert[k];
+		for (let a = offsets[v]; a < offsets[v + 1]; a++) {
+			const u = targets[a];
+			if (core[u] > core[v]) {
+				const du = core[u];
+				const pu = pos[u];
+				const pw = bin[du];
+				const w = vert[pw];
+				if (u !== w) {
+					vert[pu] = w;
+					pos[w] = pu;
+					vert[pw] = u;
+					pos[u] = pw;
+				}
+				bin[du]++;
+				core[u]--;
+			}
+		}
+	}
+	const result = {};
+	for (let i = 0; i < n; i++) result[ids[i]] = core[i];
+	return result;
+}
+/**
+* Returns the ids of all nodes in the k-core: the maximal subgraph in which
+* every node has at least `k` neighbors (edges treated as undirected).
+*
+* Node order follows `graph.nodes`. `k <= 0` returns every node id.
+*/
+function getKCore(graph, k) {
+	const cores = getCoreNumbers(graph);
+	return graph.nodes.filter((node) => cores[node.id] >= k).map((node) => node.id);
+}
+
+//#endregion
+//#region src/algorithms/bipartite.ts
+/**
+* BFS 2-coloring over undirected adjacency. Edges are treated as undirected
+* regardless of mode/direction. Returns either the coloring or the edge that
+* proves the graph is not bipartite.
+*/
+function getTwoColoring(graph) {
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	const m = graph.edges.length;
+	const degree = new Int32Array(n);
+	for (let e = 0; e < m; e++) {
+		const edge = graph.edges[e];
+		if (edge.sourceId === edge.targetId) return { conflictEdgeId: edge.id };
+		degree[csr.indexOf.get(edge.sourceId)]++;
+		degree[csr.indexOf.get(edge.targetId)]++;
+	}
+	const offsets = new Int32Array(n + 1);
+	for (let i = 0; i < n; i++) offsets[i + 1] = offsets[i] + degree[i];
+	const targets = new Int32Array(offsets[n]);
+	const arcEdge = new Int32Array(offsets[n]);
+	const cursor = Int32Array.from(offsets.subarray(0, n));
+	for (let e = 0; e < m; e++) {
+		const edge = graph.edges[e];
+		const s = csr.indexOf.get(edge.sourceId);
+		const t = csr.indexOf.get(edge.targetId);
+		targets[cursor[s]] = t;
+		arcEdge[cursor[s]++] = e;
+		targets[cursor[t]] = s;
+		arcEdge[cursor[t]++] = e;
+	}
+	const colors = new Int8Array(n).fill(-1);
+	const queue = new Int32Array(n);
+	for (let root = 0; root < n; root++) {
+		if (colors[root] !== -1) continue;
+		colors[root] = 0;
+		queue[0] = root;
+		let head = 0;
+		let tail = 1;
+		while (head < tail) {
+			const u = queue[head++];
+			for (let a = offsets[u]; a < offsets[u + 1]; a++) {
+				const v = targets[a];
+				if (colors[v] === -1) {
+					colors[v] = 1 - colors[u];
+					queue[tail++] = v;
+				} else if (colors[v] === colors[u]) return { conflictEdgeId: graph.edges[arcEdge[a]].id };
+			}
+		}
+	}
+	return { colors };
+}
+/**
+* Returns whether the graph is bipartite (2-colorable).
+*
+* Edges are treated as undirected; self-loops make a graph non-bipartite.
+* Runs a BFS 2-coloring per connected component — O(n + m).
+*/
+function isBipartite(graph) {
+	return "colors" in getTwoColoring(graph);
+}
+/**
+* Returns a maximum-cardinality matching of a bipartite graph using
+* Hopcroft–Karp — O(m·√n).
+*
+* The bipartition is derived by 2-coloring (edges treated as undirected).
+* Each match reports the realizing edge with its stored `sourceId`/
+* `targetId` orientation; for parallel edges between a matched pair, the
+* first edge used by the algorithm is reported.
+*
+* Throws if the graph is not bipartite, naming the offending edge.
+*/
+function getMaximumBipartiteMatching(graph) {
+	const coloring = getTwoColoring(graph);
+	if (!("colors" in coloring)) throw new Error(`getMaximumBipartiteMatching: graph is not bipartite — edge "${coloring.conflictEdgeId}" closes an odd cycle (or is a self-loop); a maximum bipartite matching requires a bipartite graph, check with isBipartite() first`);
+	const { colors } = coloring;
+	const csr = getCSR(graph);
+	const n = csr.ids.length;
+	const m = graph.edges.length;
+	const degree = new Int32Array(n);
+	for (let e = 0; e < m; e++) {
+		const edge = graph.edges[e];
+		const s = csr.indexOf.get(edge.sourceId);
+		const t = csr.indexOf.get(edge.targetId);
+		degree[colors[s] === 0 ? s : t]++;
+	}
+	const offsets = new Int32Array(n + 1);
+	for (let i = 0; i < n; i++) offsets[i + 1] = offsets[i] + degree[i];
+	const targets = new Int32Array(offsets[n]);
+	const arcEdge = new Int32Array(offsets[n]);
+	const cursor = Int32Array.from(offsets.subarray(0, n));
+	for (let e = 0; e < m; e++) {
+		const edge = graph.edges[e];
+		const s = csr.indexOf.get(edge.sourceId);
+		const t = csr.indexOf.get(edge.targetId);
+		const left = colors[s] === 0 ? s : t;
+		const right = colors[s] === 0 ? t : s;
+		targets[cursor[left]] = right;
+		arcEdge[cursor[left]++] = e;
+	}
+	const INF = 2147483647;
+	const matchLeft = new Int32Array(n).fill(-1);
+	const matchRight = new Int32Array(n).fill(-1);
+	const matchEdge = new Int32Array(n).fill(-1);
+	const dist = new Int32Array(n);
+	const queue = new Int32Array(n);
+	function hasAugmentingLayer() {
+		let head = 0;
+		let tail = 0;
+		for (let u = 0; u < n; u++) {
+			if (colors[u] !== 0) continue;
+			if (matchLeft[u] === -1) {
+				dist[u] = 0;
+				queue[tail++] = u;
+			} else dist[u] = INF;
+		}
+		let foundAugmenting = false;
+		while (head < tail) {
+			const u = queue[head++];
+			for (let a = offsets[u]; a < offsets[u + 1]; a++) {
+				const w = matchRight[targets[a]];
+				if (w === -1) foundAugmenting = true;
+				else if (dist[w] === INF) {
+					dist[w] = dist[u] + 1;
+					queue[tail++] = w;
+				}
+			}
+		}
+		return foundAugmenting;
+	}
+	function hasAugmentedMatchFrom(u) {
+		for (let a = offsets[u]; a < offsets[u + 1]; a++) {
+			const v = targets[a];
+			const w = matchRight[v];
+			if (w === -1 || dist[w] === dist[u] + 1 && hasAugmentedMatchFrom(w)) {
+				matchLeft[u] = v;
+				matchRight[v] = u;
+				matchEdge[u] = arcEdge[a];
+				return true;
+			}
+		}
+		dist[u] = INF;
+		return false;
+	}
+	while (hasAugmentingLayer()) for (let u = 0; u < n; u++) if (colors[u] === 0 && matchLeft[u] === -1) hasAugmentedMatchFrom(u);
+	const matches = [];
+	for (let u = 0; u < n; u++) {
+		if (matchEdge[u] === -1) continue;
+		const edge = graph.edges[matchEdge[u]];
+		matches.push({
+			sourceId: edge.sourceId,
+			targetId: edge.targetId,
+			edgeId: edge.id
+		});
+	}
+	return matches;
+}
+
 //#endregion
 //#region src/algorithms/community.ts
 function getUndirectedNeighbors$1(graph, nodeId) {
@@ -2777,14 +2476,52 @@ function toCommunityIds(communities) {
 	return communities.map((community) => new Set(community.map((node) => node.id)));
 }
 /**
+* Asynchronous LPA: labels update in place as the (seeded-shuffled) round
+* proceeds; ties among maximal neighbor labels break uniformly at random,
+* keeping the current label when it is already maximal so rounds terminate.
+* Deterministic per seed.
+*/
+function getSeededLabelPropagation(graph, seed, maxIterations) {
+	const rng = mulberry32(seed);
+	const labels = Object.fromEntries(graph.nodes.map((node) => [node.id, node.id]));
+	const order = graph.nodes.map((node) => node.id);
+	for (let iteration = 0; iteration < maxIterations; iteration++) {
+		for (let i = order.length - 1; i > 0; i--) {
+			const j = Math.floor(rng() * (i + 1));
+			[order[i], order[j]] = [order[j], order[i]];
+		}
+		let changed = false;
+		for (const nodeId of order) {
+			const counts = /* @__PURE__ */ new Map();
+			for (const neighbor of getUndirectedNeighbors$1(graph, nodeId)) {
+				const label = labels[neighbor.nodeId];
+				counts.set(label, (counts.get(label) ?? 0) + 1);
+			}
+			if (counts.size === 0) continue;
+			let maxCount = 0;
+			for (const count of counts.values()) if (count > maxCount) maxCount = count;
+			const best = [];
+			for (const [label, count] of counts) if (count === maxCount) best.push(label);
+			if (best.includes(labels[nodeId])) continue;
+			labels[nodeId] = best[Math.floor(rng() * best.length)];
+			changed = true;
+		}
+		if (!changed) break;
+	}
+	return normalizeCommunities(graph, labels);
+}
+/**
 * Returns label-propagation communities for the graph.
 *
 * The implementation is deterministic: ties are broken by lexicographic label
-* order so test results remain stable.
+* order so test results remain stable. Pass `options.seed` for the classic
+* asynchronous variant (shuffled node order per round, random tie-breaking)
+* — still deterministic per seed.
 */
 function getLabelPropagationCommunities(graph, options) {
 	if (graph.nodes.length === 0) return [];
 	const maxIterations = options?.maxIterations ?? 50;
+	if (options?.seed !== void 0) return getSeededLabelPropagation(graph, options.seed, maxIterations);
 	let labels = Object.fromEntries(graph.nodes.map((node) => [node.id, node.id]));
 	const nodeIds = graph.nodes.map((node) => node.id).sort();
 	for (let iteration = 0; iteration < maxIterations; iteration++) {
@@ -3242,30 +2979,14 @@ function getLouvainCommunities(graph, options) {
 //#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' });
-* ```
+* Shared Edmonds-Karp solver behind {@link getMaxFlow} and {@link getMinCut}.
+* `caller`/`fromOption`/`toOption` only shape the error messages.
 */
-function getMaxFlow(graph, options) {
-	const { from, to } = options;
-	const getCapacity = options.getCapacity ?? ((edge) => edge.weight ?? 1);
+function solveMaxFlow(graph, caller, fromOption, toOption, from, to, getCapacity) {
 	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`);
+	if (!idx.nodeById.has(from)) throw new Error(`${caller}: source node "${from}" not found in graph — pass an existing node id as ${fromOption}`);
+	if (!idx.nodeById.has(to)) throw new Error(`${caller}: sink node "${to}" not found in graph — pass an existing node id as ${toOption}`);
+	if (from === to) throw new Error(`${caller}: 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, []);
@@ -3287,7 +3008,7 @@ function getMaxFlow(graph, options) {
 	}
 	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 (capacity < 0) throw new Error(`${caller}: 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);
@@ -3349,12 +3070,73 @@ function getMaxFlow(graph, options) {
 		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,
+		sourceSide
+	};
+}
+/**
+* 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 getCapacity = options.getCapacity ?? ((edge) => edge.weight ?? 1);
+	const { value, flows, cutEdges } = solveMaxFlow(graph, "getMaxFlow", "options.from", "options.to", options.from, options.to, getCapacity);
 	return {
 		value,
 		flows,
 		cutEdges
 	};
 }
+/**
+* Returns a minimum s-t cut between `source` and `sink` via the max-flow
+* min-cut theorem: runs the same Edmonds-Karp solver as {@link getMaxFlow},
+* then splits the nodes by residual reachability from the source.
+*
+* `partition.source` holds every node reachable from `source` in the final
+* residual graph; `partition.sink` holds the rest (both in `graph.nodes`
+* order). `cutEdges` are the ids of the edges crossing the cut, and their
+* total capacity equals `value` (the max-flow value).
+*
+* @example
+* ```ts
+* const { value, cutEdges, partition } = getMinCut(graph, {
+*   source: 's',
+*   sink: 't',
+* });
+* ```
+*/
+function getMinCut(graph, options) {
+	const getCapacity = options.getCapacity ?? ((edge) => edge.weight ?? 1);
+	const { value, cutEdges, sourceSide } = solveMaxFlow(graph, "getMinCut", "options.source", "options.sink", options.source, options.sink, getCapacity);
+	const sourcePartition = [];
+	const sinkPartition = [];
+	for (const node of graph.nodes) (sourceSide.has(node.id) ? sourcePartition : sinkPartition).push(node.id);
+	return {
+		value,
+		cutEdges: cutEdges.map((edge) => edge.id),
+		partition: {
+			source: sourcePartition,
+			sink: sinkPartition
+		}
+	};
+}
 
 //#endregion
 //#region src/algorithms/dominators.ts
@@ -3524,4 +3306,4 @@ function getTransitiveReduction(graph) {
 }
 
 //#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 };
+export { getAStarPath as $, genPreorders as A, getTopologicalSort as B, getHITS as C, getPageRank as D, getOutDegreeCentrality as E, bfs as F, flatten as G, isAcyclic as H, dfs as I, getSubgraph as J, getFlattenedGraph as K, genBFS as L, getPostorders as M, getPreorder as N, getMinimumSpanningTree as O, getPreorders as P, genSimplePaths as Q, genDFS as R, getEigenvectorCentrality as S, getKatzCentrality as T, isConnected as U, hasPath as V, isTree as W, genCycles as X, reverseGraph as Y, genShortestPaths as Z, getCoreNumbers as _, getLouvainCommunities as a, getSimplePath as at, getClosenessCentrality as b, getBiconnectedComponents as c, joinPaths as ct, getGirvanNewmanCommunities as d, getAllPairsShortestPaths as et, getGreedyModularityCommunities as f, isBipartite as g, getMaximumBipartiteMatching as h, getMinCut as i, getShortestPaths as it, getPostorder as j, genPostorders as k, getBridges as l, mulberry32 as lt, getModularity as m, getDominatorTree as n, getJoinedPath as nt, isIsomorphic as o, getSimplePaths as ot, getLabelPropagationCommunities as p, getReversedGraph as q, getMaxFlow as r, getShortestPath as rt, getArticulationPoints as s, getStronglyConnectedComponents as st, getTransitiveReduction as t, getCycles as tt, genGirvanNewmanCommunities as u, getKCore as v, getInDegreeCentrality as w, getDegreeCentrality as x, getBetweennessCentrality as y, getConnectedComponents as z };