@statelyai/graph 1.0.0 → 2.1.0

package/dist/config-Dt5u1gSf.mjs

@@ -0,0 +1,793 @@
+import { A as indexAddNode, M as indexUpdateEdgeEndpoints, N as invalidateIndex, O as getIndex, P as touchIndex, j as indexReparentNode, k as indexAddEdge } from "./queries-BMM0XAv_.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);
+	}
+}
+function validateNodeReference(nodeIds, ref, message) {
+	if (ref != null && !nodeIds.has(ref)) throw new Error(message(ref));
+}
+/**
+* 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.points !== void 0) edge.points = config.points.map((p) => ({ ...p }));
+	if (config.routing !== void 0) edge.routing = config.routing;
+	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`);
+	validateNodeReference(new Set([...idx.nodeById.keys(), config.id]), config.initialNodeId, (initialNodeId) => `Initial node "${initialNodeId}" 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",
+	"points",
+	"routing",
+	"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;
+		}
+	}
+	validateNodeReference(new Set(idx.nodeById.keys()), update.initialNodeId, (initialNodeId) => `Initial node "${initialNodeId}" does not exist`);
+	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) {
+	const nodeConfigs = entities.nodes ?? [];
+	if (nodeConfigs.length > 0) {
+		const idx = getIndex(graph);
+		const nodeIds = new Set(idx.nodeById.keys());
+		for (const nodeConfig of nodeConfigs) {
+			if (nodeIds.has(nodeConfig.id)) throw new Error(`Node "${nodeConfig.id}" already exists`);
+			nodeIds.add(nodeConfig.id);
+		}
+		const nodes = nodeConfigs.map(createGraphNode);
+		for (const nodeConfig of nodeConfigs) {
+			validateNodeReference(nodeIds, nodeConfig.parentId, (parentId) => `Parent node "${parentId}" does not exist`);
+			validateNodeReference(nodeIds, nodeConfig.initialNodeId, (initialNodeId) => `Initial node "${initialNodeId}" does not exist`);
+		}
+		for (const node of nodes) indexAddNode(idx, node, graph.nodes.push(node) - 1);
+	}
+	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/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.points !== void 0) config.points = edge.points.map((p) => ({ ...p }));
+	if (edge.routing !== void 0) config.routing = edge.routing;
+	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
+export { updateNode as S, getNode as _, addEntities as a, updateEdge as b, createGraphEdge as c, createGraphPort as d, createVisualGraph as f, getEdge as g, deleteNode as h, addEdge as i, createGraphFromTransition as l, deleteEntities as m, toNodeConfig as n, addNode as o, deleteEdge as p, GraphInstance as r, createGraph as s, toEdgeConfig as t, createGraphNode as u, hasEdge as v, updateEntities as x, hasNode as y };