@statelyai/graph 0.6.0 → 0.8.0

package/dist/{algorithms-oVD9PYil.mjs → algorithms-Pbj9dJB1.mjs}

@@ -1,7 +1,47 @@
 import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-DyfgLuzw.mjs";
 
 //#region src/graph.ts
-function resolveNode(config) {
+/**
+* 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: undefined }
+* ```
+*/
+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
+	};
+	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 = {
@@ -12,6 +52,10 @@ function resolveNode(config) {
 		label: config.label ?? "",
 		data: config.data
 	};
+	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;
@@ -21,7 +65,16 @@ function resolveNode(config) {
 	if (config.style !== void 0) node.style = config.style;
 	return node;
 }
-function resolveEdge(config) {
+/**
+* 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: undefined }
+* ```
+*/
+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");
@@ -33,6 +86,8 @@ function resolveEdge(config) {
 		label: config.label ?? null,
 		data: config.data
 	};
+	if (config.sourcePort !== void 0) edge.sourcePort = config.sourcePort;
+	if (config.targetPort !== void 0) edge.targetPort = config.targetPort;
 	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;
@@ -58,8 +113,8 @@ function createGraph(config) {
 		id: config?.id ?? "",
 		type: config?.type ?? "directed",
 		initialNodeId: config?.initialNodeId ?? null,
-		nodes: (config?.nodes ?? []).map(resolveNode),
-		edges: (config?.edges ?? []).map(resolveEdge),
+		nodes: (config?.nodes ?? []).map(createGraphNode),
+		edges: (config?.edges ?? []).map(createGraphEdge),
 		data: config?.data ?? void 0
 	};
 	if (config?.direction !== void 0) graph.direction = config.direction;
@@ -83,14 +138,24 @@ function createVisualGraph(config) {
 	return {
 		...base,
 		direction: config?.direction ?? "down",
-		nodes: base.nodes.map((n) => ({
-			...n,
-			x: n.x ?? 0,
-			y: n.y ?? 0,
-			width: n.width ?? 0,
-			height: n.height ?? 0,
-			...n.shape !== void 0 && { shape: n.shape }
-		})),
+		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,
@@ -257,7 +322,7 @@ function hasEdge(graph, id) {
 * ```
 */
 function addNode(graph, config) {
-	const node = resolveNode(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`);
@@ -276,11 +341,17 @@ function addNode(graph, config) {
 * ```
 */
 function addEdge(graph, config) {
-	const edge = resolveEdge(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;
 }
@@ -351,6 +422,7 @@ function updateNode(graph, id, update) {
 	if (update.parentId !== void 0 && update.parentId !== null) {
 		if (!idx.nodeById.has(update.parentId)) throw new Error(`Parent node "${update.parentId}" does not exist`);
 	}
+	if (update.ports !== void 0 && update.ports.length > 0) validatePortNames(update.ports);
 	const node = graph.nodes[arrayIdx];
 	const oldParentId = node.parentId;
 	const updated = {
@@ -358,7 +430,8 @@ function updateNode(graph, id, update) {
 		...update.parentId !== void 0 && { parentId: update.parentId ?? null },
 		...update.initialNodeId !== void 0 && { initialNodeId: update.initialNodeId ?? null },
 		...update.label !== void 0 && { label: update.label },
-		...update.data !== void 0 && { data: update.data }
+		...update.data !== void 0 && { data: update.data },
+		...update.ports !== void 0 && { ports: update.ports.map(createGraphPort) }
 	};
 	graph.nodes[arrayIdx] = updated;
 	if (update.parentId !== void 0 && updated.parentId !== oldParentId) indexReparentNode(idx, id, oldParentId, updated.parentId);
@@ -387,12 +460,22 @@ function updateEdge(graph, id, update) {
 	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;
+	if (update.sourcePort !== void 0) {
+		if (!graph.nodes[idx.nodeById.get(effectiveSourceId)].ports?.some((p) => p.name === update.sourcePort)) throw new Error(`Port "${update.sourcePort}" does not exist on source node "${effectiveSourceId}"`);
+	}
+	if (update.targetPort !== void 0) {
+		if (!graph.nodes[idx.nodeById.get(effectiveTargetId)].ports?.some((p) => p.name === update.targetPort)) throw new Error(`Port "${update.targetPort}" does not exist on target node "${effectiveTargetId}"`);
+	}
 	const updated = {
 		...edge,
 		...update.sourceId !== void 0 && { sourceId: update.sourceId },
 		...update.targetId !== void 0 && { targetId: update.targetId },
 		...update.label !== void 0 && { label: update.label },
-		...update.data !== void 0 && { data: update.data }
+		...update.data !== void 0 && { data: update.data },
+		...update.sourcePort !== void 0 && { sourcePort: update.sourcePort },
+		...update.targetPort !== void 0 && { targetPort: update.targetPort }
 	};
 	graph.edges[arrayIdx] = updated;
 	if (updated.sourceId !== oldSourceId || updated.targetId !== oldTargetId) indexUpdateEdgeEndpoints(idx, id, oldSourceId, oldTargetId, updated.sourceId, updated.targetId);
@@ -2121,4 +2204,4 @@ function joinPaths(headPath, tailPath) {
 }
 
 //#endregion
-export { addEntities as A, hasEdge as B, hasPath as C, joinPaths as D, isTree as E, deleteEdge as F, updateEdge as H, deleteEntities as I, deleteNode as L, createGraph as M, createGraphFromTransition as N, GraphInstance as O, createVisualGraph as P, getEdge as R, getTopologicalSort as S, isConnected as T, updateEntities as U, hasNode as V, updateNode as W, getShortestPath as _, genPreorders as a, getSimplePaths as b, getAStarPath as c, getCycles as d, getMinimumSpanningTree as f, getPreorders as g, getPreorder as h, genPostorders as i, addNode as j, addEdge as k, getAllPairsShortestPaths as l, getPostorders as m, dfs as n, genShortestPaths as o, getPostorder as p, genCycles as r, genSimplePaths as s, bfs as t, getConnectedComponents as u, getShortestPaths as v, isAcyclic as w, getStronglyConnectedComponents as x, getSimplePath as y, getNode as z };
+export { addEntities as A, deleteNode as B, hasPath as C, joinPaths as D, isTree as E, createGraphNode as F, updateEdge as G, getNode as H, createGraphPort as I, updateEntities as K, createVisualGraph as L, createGraph as M, createGraphEdge as N, GraphInstance as O, createGraphFromTransition as P, deleteEdge as R, getTopologicalSort as S, isConnected as T, hasEdge as U, getEdge as V, hasNode as W, getShortestPath as _, genPreorders as a, getSimplePaths as b, getAStarPath as c, getCycles as d, getMinimumSpanningTree as f, getPreorders as g, getPreorder as h, genPostorders as i, addNode as j, addEdge as k, getAllPairsShortestPaths as l, getPostorders as m, dfs as n, genShortestPaths as o, getPostorder as p, updateNode as q, genCycles as r, genSimplePaths as s, bfs as t, getConnectedComponents as u, getShortestPaths as v, isAcyclic as w, getStronglyConnectedComponents as x, getSimplePath as y, deleteEntities as z };

package/dist/algorithms.d.mts

@@ -1,4 +1,4 @@
-import { C as SinglePathOptions, S as PathOptions, T as TraversalOptions, _ as GraphPath, h as GraphNode, n as AllPairsShortestPathsOptions, t as AStarOptions, u as Graph, y as MSTOptions } from "./types-DF-HNw50.mjs";
+import { A as TraversalOptions, O as SinglePathOptions, S as MSTOptions, T as PathOptions, _ as GraphNode, n as AllPairsShortestPathsOptions, t as AStarOptions, u as Graph, y as GraphPath } from "./types-BzckPChi.mjs";
 
 //#region src/algorithms.d.ts
 

package/dist/algorithms.mjs

@@ -1,3 +1,3 @@
-import { C as hasPath, D as joinPaths, E as isTree, S as getTopologicalSort, T as isConnected, _ as getShortestPath, a as genPreorders, b as getSimplePaths, c as getAStarPath, d as getCycles, f as getMinimumSpanningTree, g as getPreorders, h as getPreorder, i as genPostorders, l as getAllPairsShortestPaths, m as getPostorders, n as dfs, o as genShortestPaths, p as getPostorder, r as genCycles, s as genSimplePaths, t as bfs, u as getConnectedComponents, v as getShortestPaths, w as isAcyclic, x as getStronglyConnectedComponents, y as getSimplePath } from "./algorithms-oVD9PYil.mjs";
+import { C as hasPath, D as joinPaths, E as isTree, S as getTopologicalSort, T as isConnected, _ as getShortestPath, a as genPreorders, b as getSimplePaths, c as getAStarPath, d as getCycles, f as getMinimumSpanningTree, g as getPreorders, h as getPreorder, i as genPostorders, l as getAllPairsShortestPaths, m as getPostorders, n as dfs, o as genShortestPaths, p as getPostorder, r as genCycles, s as genSimplePaths, t as bfs, u as getConnectedComponents, v as getShortestPaths, w as isAcyclic, x as getStronglyConnectedComponents, y as getSimplePath } from "./algorithms-Pbj9dJB1.mjs";
 
 export { bfs, dfs, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAStarPath, getAllPairsShortestPaths, getConnectedComponents, getCycles, getMinimumSpanningTree, getPostorder, getPostorders, getPreorder, getPreorders, getShortestPath, getShortestPaths, getSimplePath, getSimplePaths, getStronglyConnectedComponents, getTopologicalSort, hasPath, isAcyclic, isConnected, isTree, joinPaths };

package/dist/formats/adjacency-list/index.d.mts

@@ -1,4 +1,4 @@
-import { u as Graph } from "../../types-DF-HNw50.mjs";
+import { u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/adjacency-list/index.d.ts
 

package/dist/formats/converter/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/converter/index.d.ts
 

package/dist/formats/cytoscape/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/cytoscape/index.d.ts
 interface CytoscapeNode {

package/dist/formats/d3/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/d3/index.d.ts
 interface D3Node {

package/dist/formats/dot/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/dot/index.d.ts
 

package/dist/formats/edge-list/index.d.mts

@@ -1,4 +1,4 @@
-import { u as Graph } from "../../types-DF-HNw50.mjs";
+import { u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/edge-list/index.d.ts
 

package/dist/formats/elk/index.d.mts

@@ -1,4 +1,4 @@
-import { D as VisualGraph, k as VisualGraphFormatConverter } from "../../types-DF-HNw50.mjs";
+import { F as VisualGraphFormatConverter, M as VisualGraph } from "../../types-BzckPChi.mjs";
 import { ElkEdge, ElkEdgeSection, ElkExtendedEdge, ElkGraphElement, ElkLabel, ElkNode, ElkNode as ElkNode$1, ElkPoint, ElkPort, ElkPrimitiveEdge, ElkShape, LayoutOptions } from "elkjs/lib/elk-api";
 
 //#region src/formats/elk/index.d.ts

package/dist/formats/elk/index.mjs

@@ -16,12 +16,24 @@ const ELK_TO_DIRECTION = {
 function convertEdge(edge) {
 	const elkEdge = {
 		id: edge.id,
-		sources: [edge.sourceId],
-		targets: [edge.targetId]
+		sources: [edge.sourcePort ?? edge.sourceId],
+		targets: [edge.targetPort ?? edge.targetId]
 	};
 	if (edge.label) elkEdge.labels = [{ text: edge.label }];
 	return elkEdge;
 }
+function convertPort(port) {
+	const elkPort = {
+		id: port.name,
+		x: port.x,
+		y: port.y,
+		width: port.width,
+		height: port.height
+	};
+	if (port.label) elkPort.labels = [{ text: port.label }];
+	if (port.direction !== "inout") elkPort.layoutOptions = { "org.eclipse.elk.port.side": port.direction === "in" ? "WEST" : "EAST" };
+	return elkPort;
+}
 function convertNode(graph, node) {
 	const elkNode = {
 		id: node.id,
@@ -31,6 +43,7 @@ function convertNode(graph, node) {
 		height: node.height
 	};
 	if (node.label) elkNode.labels = [{ text: node.label }];
+	if (node.ports && node.ports.length > 0) elkNode.ports = node.ports.map(convertPort);
 	const children = getChildren(graph, node.id);
 	if (children.length > 0) {
 		elkNode.children = children.map((child) => convertNode(graph, child));
@@ -84,7 +97,7 @@ function toELK(graph) {
 	if (rootEdges.length > 0) root.edges = rootEdges.map(convertEdge);
 	return root;
 }
-function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx) {
+function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx, portOwner) {
 	if (elkNode.children) for (const child of elkNode.children) {
 		const label = child.labels?.[0]?.text ?? "";
 		const node = {
@@ -99,15 +112,34 @@ function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx) {
 			width: child.width ?? 0,
 			height: child.height ?? 0
 		};
+		if (child.ports && child.ports.length > 0) node.ports = child.ports.map((elkPort) => {
+			portOwner.set(elkPort.id, child.id);
+			const sideOpt = elkPort.layoutOptions?.["org.eclipse.elk.port.side"];
+			let direction = "inout";
+			if (sideOpt === "WEST") direction = "in";
+			else if (sideOpt === "EAST") direction = "out";
+			return {
+				name: elkPort.id,
+				direction,
+				label: elkPort.labels?.[0]?.text,
+				data: void 0,
+				x: elkPort.x ?? 0,
+				y: elkPort.y ?? 0,
+				width: elkPort.width ?? 0,
+				height: elkPort.height ?? 0
+			};
+		});
 		nodes.push(node);
-		flattenElkNodes(child, child.id, nodes, edges, edgeIdx);
+		flattenElkNodes(child, child.id, nodes, edges, edgeIdx, portOwner);
 	}
 	if (elkNode.edges) for (const elkEdge of elkNode.edges) for (const source of elkEdge.sources) for (const target of elkEdge.targets) {
+		const sourceNodeId = portOwner.get(source);
+		const targetNodeId = portOwner.get(target);
 		const edge = {
 			type: "edge",
 			id: elkEdge.id ?? `e${edgeIdx.value++}`,
-			sourceId: source,
-			targetId: target,
+			sourceId: sourceNodeId ?? source,
+			targetId: targetNodeId ?? target,
 			label: elkEdge.labels?.[0]?.text ?? "",
 			data: void 0,
 			x: 0,
@@ -115,6 +147,8 @@ function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx) {
 			width: 0,
 			height: 0
 		};
+		if (sourceNodeId) edge.sourcePort = source;
+		if (targetNodeId) edge.targetPort = target;
 		edges.push(edge);
 	}
 }
@@ -141,7 +175,7 @@ function flattenElkNodes(elkNode, parentId, nodes, edges, edgeIdx) {
 function fromELK(elkRoot) {
 	const nodes = [];
 	const edges = [];
-	flattenElkNodes(elkRoot, null, nodes, edges, { value: 0 });
+	flattenElkNodes(elkRoot, null, nodes, edges, { value: 0 }, /* @__PURE__ */ new Map());
 	const seenEdges = /* @__PURE__ */ new Map();
 	for (const edge of edges) if (!seenEdges.has(edge.id)) seenEdges.set(edge.id, edge);
 	const elkDir = elkRoot.layoutOptions?.["elk.direction"];

package/dist/formats/gexf/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/gexf/index.d.ts
 declare function toGEXF(graph: Graph): string;

package/dist/formats/gml/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/gml/index.d.ts
 

package/dist/formats/graphml/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/graphml/index.d.ts
 declare function toGraphML(graph: Graph): string;

package/dist/formats/jgf/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/jgf/index.d.ts
 interface JGFNode {

package/dist/formats/mermaid/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/mermaid/sequence.d.ts
 interface SequenceNodeData {

package/dist/formats/mermaid/index.mjs

@@ -1836,7 +1836,10 @@ function fromMermaidClass(input) {
 		if (classBlockMatch) {
 			currentClass = classBlockMatch[1];
 			const node = ensureNode(currentClass);
-			if (classBlockMatch[2]) node.data.genericType = classBlockMatch[2];
+			if (classBlockMatch[2]) {
+				node.data ??= {};
+				node.data.genericType = classBlockMatch[2];
+			}
 			inClassBlock = true;
 			braceDepth = 1;
 			continue;
@@ -1852,10 +1855,13 @@ function fromMermaidClass(input) {
 			}
 			const annotMatch = line.match(/^<<(.+)>>$/);
 			if (annotMatch) {
-				nodeMap.get(currentClass).data.annotation = annotMatch[1];
+				const node$1 = nodeMap.get(currentClass);
+				node$1.data ??= {};
+				node$1.data.annotation = annotMatch[1];
 				continue;
 			}
 			const node = nodeMap.get(currentClass);
+			node.data ??= {};
 			if (!node.data.members) node.data.members = [];
 			node.data.members.push(parseMember(line));
 			continue;
@@ -1863,12 +1869,16 @@ function fromMermaidClass(input) {
 		const classInlineMatch = line.match(/^class\s+(\S+?)(?:~(.+?)~)?\s*$/);
 		if (classInlineMatch) {
 			const node = ensureNode(classInlineMatch[1]);
-			if (classInlineMatch[2]) node.data.genericType = classInlineMatch[2];
+			if (classInlineMatch[2]) {
+				node.data ??= {};
+				node.data.genericType = classInlineMatch[2];
+			}
 			continue;
 		}
 		const annotLineMatch = line.match(/^<<(.+)>>\s+(\S+)\s*$/);
 		if (annotLineMatch) {
 			const node = ensureNode(annotLineMatch[2]);
+			node.data ??= {};
 			node.data.annotation = annotLineMatch[1];
 			continue;
 		}
@@ -1876,6 +1886,7 @@ function fromMermaidClass(input) {
 		if (inlineMemberMatch) {
 			if (!parseRelationship(line)) {
 				const node = ensureNode(inlineMemberMatch[1]);
+				node.data ??= {};
 				if (!node.data.members) node.data.members = [];
 				node.data.members.push(parseMember(inlineMemberMatch[2]));
 				continue;
@@ -2067,7 +2078,10 @@ function fromMermaidER(input) {
 			const attrMatch = line.match(/^(\S+)\s+(\S+)(?:\s+(PK|FK|UK))?(?:\s+"([^"]*)")?$/);
 			if (attrMatch) {
 				const node = nodeMap.get(currentEntity);
-				if (!node.data.attributes) node.data.attributes = [];
+				if (!node.data?.attributes) {
+					if (!node.data) node.data = {};
+					node.data.attributes = [];
+				}
 				node.data.attributes.push({
 					type: attrMatch[1],
 					name: attrMatch[2],
@@ -2289,7 +2303,7 @@ function toMermaidMindmap(graph) {
 			const indent = "  ".repeat(depth + 1);
 			const shape = child.shape;
 			const brackets = shape ? SHAPE_TO_BRACKETS[shape] : void 0;
-			const label = escapeMermaidLabel(child.label);
+			const label = escapeMermaidLabel(child.label ?? child.id);
 			const text = brackets ? `${brackets[0]}${label}${brackets[1]}` : label;
 			let extra = "";
 			if (child.data?.icon) extra = `\n${"  ".repeat(depth + 2)}::icon(${child.data.icon})`;
@@ -2442,7 +2456,7 @@ function fromMermaidBlock(input) {
 			const label = spanMatch[2] ?? id;
 			const span = parseInt(spanMatch[3], 10);
 			const node = ensureNode(id, label);
-			node.data.span = span;
+			if (node.data) node.data.span = span;
 			continue;
 		}
 		const parts = line.split(/\s+/);

package/dist/formats/tgf/index.d.mts

@@ -1,4 +1,4 @@
-import { m as GraphFormatConverter, u as Graph } from "../../types-DF-HNw50.mjs";
+import { g as GraphFormatConverter, u as Graph } from "../../types-BzckPChi.mjs";
 
 //#region src/formats/tgf/index.d.ts
 

package/dist/formats/xyflow/index.d.mts

@@ -1,4 +1,4 @@
-import { D as VisualGraph, k as VisualGraphFormatConverter } from "../../types-DF-HNw50.mjs";
+import { F as VisualGraphFormatConverter, M as VisualGraph } from "../../types-BzckPChi.mjs";
 import { EdgeBase, NodeBase } from "@xyflow/system";
 
 //#region src/formats/xyflow/index.d.ts

package/dist/formats/xyflow/index.mjs

@@ -42,6 +42,8 @@ function toXYFlow(graph) {
 				source: e.sourceId,
 				target: e.targetId
 			};
+			if (e.sourcePort) edge.sourceHandle = e.sourcePort;
+			if (e.targetPort) edge.targetHandle = e.targetPort;
 			if (e.data !== void 0) edge.data = e.data;
 			if (e.label) edge.data = {
 				...edge.data,
@@ -96,6 +98,8 @@ function fromXYFlow(flow) {
 			sourceId: e.source,
 			targetId: e.target,
 			label: e.data?.label?.toString() ?? "",
+			...e.sourceHandle && { sourcePort: e.sourceHandle },
+			...e.targetHandle && { targetPort: e.targetHandle },
 			data: e.data,
 			x: 0,
 			y: 0,

package/dist/index.d.mts

@@ -1,10 +1,40 @@
-import { A as VisualNode, C as SinglePathOptions, D as VisualGraph, E as VisualEdge, M as WalkOptions, N as WeightedWalkOptions, O as VisualGraphConfig, S as PathOptions, T as TraversalOptions, _ as GraphPath, a as EdgeChange, b as NodeChange, c as EntitiesUpdate, d as GraphConfig, f as GraphDiff, g as GraphPatch, h as GraphNode, i as DeleteNodeOptions, j as WalkContext, l as EntityRect, m as GraphFormatConverter, n as AllPairsShortestPathsOptions, o as EdgeConfig, p as GraphEdge, r as CoverageStats, s as EntitiesConfig, t as AStarOptions, u as Graph, v as GraphStep, w as TransitionOptions, x as NodeConfig, y as MSTOptions } from "./types-DF-HNw50.mjs";
+import { A as TraversalOptions, B as WeightedWalkOptions, C as NodeChange, D as PortDirection, E as PortConfig, I as VisualNode, L as VisualPort, M as VisualGraph, N as VisualGraphConfig, O as SinglePathOptions, P as VisualGraphEntity, R as WalkContext, S as MSTOptions, T as PathOptions, _ as GraphNode, a as EdgeChange, b as GraphPort, c as EntitiesUpdate, d as GraphConfig, f as GraphDiff, g as GraphFormatConverter, h as GraphEntityConfig, i as DeleteNodeOptions, j as VisualEdge, k as TransitionOptions, l as EntityRect, m as GraphEntity, n as AllPairsShortestPathsOptions, o as EdgeConfig, p as GraphEdge, r as CoverageStats, s as EntitiesConfig, t as AStarOptions, u as Graph, v as GraphPatch, w as NodeConfig, x as GraphStep, y as GraphPath, z as WalkOptions } from "./types-BzckPChi.mjs";
 import { bfs, dfs, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAStarPath, getAllPairsShortestPaths, getConnectedComponents, getCycles, getMinimumSpanningTree, getPostorder, getPostorders, getPreorder, getPreorders, getShortestPath, getShortestPaths, getSimplePath, getSimplePaths, getStronglyConnectedComponents, getTopologicalSort, hasPath, isAcyclic, isConnected, isTree, joinPaths } from "./algorithms.mjs";
 import { createFormatConverter } from "./formats/converter/index.mjs";
-import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
+import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPort, getPorts, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
 
 //#region src/graph.d.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: undefined }
+ * ```
+ */
+declare function createGraphPort<P = any>(config: PortConfig<P>): GraphPort<P>;
+/**
+ * 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' } }
+ * ```
+ */
+declare function createGraphNode<N = any, P = any>(config: NodeConfig<N, P>): GraphNode<N, P>;
+/**
+ * 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: undefined }
+ * ```
+ */
+declare function createGraphEdge<T = any>(config: EdgeConfig<T>): GraphEdge<T>;
 /**
  * Create a graph from a config. Resolves defaults for all fields.
  *
@@ -16,7 +46,7 @@ import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdge
  * });
  * ```
  */
-declare function createGraph<N = any, E = any, G = any>(config?: GraphConfig<N, E, G>): Graph<N, E, G>;
+declare function createGraph<N = any, E = any, G = any, P = any>(config?: GraphConfig<N, E, G, P>): Graph<N, E, G, P>;
 /**
  * Create a visual graph with required position/size on all nodes and edges.
  *
@@ -29,7 +59,7 @@ declare function createGraph<N = any, E = any, G = any>(config?: GraphConfig<N,
  * // graph.nodes[0].x === 0
  * ```
  */
-declare function createVisualGraph<N = any, E = any, G = any>(config?: VisualGraphConfig<N, E, G>): VisualGraph<N, E, G>;
+declare function createVisualGraph<N = any, E = any, G = any, P = any>(config?: VisualGraphConfig<N, E, G, P>): VisualGraph<N, E, G, P>;
 /**
  * Create a graph by BFS exploration of a transition function.
  * Each unique state becomes a node; each (state, event) -> nextState becomes an edge.
@@ -119,7 +149,7 @@ declare function hasEdge(graph: Graph, id: string): boolean;
  * // graph.nodes.length === 1
  * ```
  */
-declare function addNode<N>(graph: Graph<N>, config: NodeConfig<N>): GraphNode<N>;
+declare function addNode<N, P = any>(graph: Graph<N, any, any, P>, config: NodeConfig<N, P>): GraphNode<N, P>;
 /**
  * **Mutable.** Add an edge to the graph. Mutates `graph.edges` in place.
  * @returns The resolved edge that was added.
@@ -175,7 +205,7 @@ declare function deleteEdge(graph: Graph, id: string): void;
  * // updated.label === 'new'
  * ```
  */
-declare function updateNode<N>(graph: Graph<N>, id: string, update: Partial<Omit<NodeConfig<N>, 'id'>>): GraphNode<N>;
+declare function updateNode<N, P = any>(graph: Graph<N, any, any, P>, id: string, update: Partial<Omit<NodeConfig<N, P>, 'id'>>): GraphNode<N, P>;
 /**
  * **Mutable.** Update an edge in place.
  * @returns The updated edge.
@@ -253,9 +283,9 @@ declare function updateEntities<N, E>(graph: Graph<N, E>, updates: EntitiesUpdat
  * instance.toJSON(); // plain Graph object
  * ```
  */
-declare class GraphInstance<N = any, E = any, G = any> {
-  graph: Graph<N, E, G>;
-  constructor(config?: GraphConfig<N, E, G>);
+declare class GraphInstance<N = any, E = any, G = any, P = any> {
+  graph: Graph<N, E, G, P>;
+  constructor(config?: GraphConfig<N, E, G, P>);
   /**
    * Wrap an existing plain graph object.
    *
@@ -266,26 +296,26 @@ declare class GraphInstance<N = any, E = any, G = any> {
    * instance.hasNode('a'); // true
    * ```
    */
-  static from<N = any, E = any, G = any>(graph: Graph<N, E, G>): GraphInstance<N, E, G>;
+  static from<N = any, E = any, G = any, P = any>(graph: Graph<N, E, G, P>): GraphInstance<N, E, G, P>;
   get id(): string;
   get type(): "directed" | "undirected";
-  get nodes(): GraphNode<N>[];
+  get nodes(): GraphNode<N, P>[];
   get edges(): GraphEdge<E>[];
   get data(): G;
-  getNode(id: string): GraphNode<N> | undefined;
+  getNode(id: string): GraphNode<N, any> | undefined;
   getEdge(id: string): GraphEdge<E> | undefined;
   hasNode(id: string): boolean;
   hasEdge(id: string): boolean;
-  addNode(config: NodeConfig<N>): GraphNode<N>;
+  addNode(config: NodeConfig<N, P>): GraphNode<N, P>;
   addEdge(config: EdgeConfig<E>): GraphEdge<E>;
   deleteNode(id: string, opts?: DeleteNodeOptions): void;
   deleteEdge(id: string): void;
-  updateNode(id: string, update: Partial<Omit<NodeConfig<N>, 'id'>>): GraphNode<N>;
+  updateNode(id: string, update: Partial<Omit<NodeConfig<N, P>, 'id'>>): GraphNode<N, P>;
   updateEdge(id: string, update: Partial<Omit<EdgeConfig<E>, 'id'>>): GraphEdge<E>;
-  addEntities(entities: EntitiesConfig<N, E>): void;
+  addEntities(entities: EntitiesConfig<N, E, P>): void;
   deleteEntities(ids: string | string[], opts?: DeleteNodeOptions): void;
-  updateEntities(updates: EntitiesUpdate<N, E>): void;
-  toJSON(): Graph<N, E, G>;
+  updateEntities(updates: EntitiesUpdate<N, E, P>): void;
+  toJSON(): Graph<N, E, G, P>;
 }
 //#endregion
 //#region src/indexing.d.ts
@@ -547,4 +577,4 @@ declare function getCoverage<N, E>(graph: Graph<N, E>, steps: GraphStep<N, E>[],
   from?: string;
 }): CoverageStats;
 //#endregion
-export { type AStarOptions, type AllPairsShortestPathsOptions, type CoverageStats, type DeleteNodeOptions, type EdgeChange, type EdgeConfig, type EntitiesConfig, type EntitiesUpdate, type Graph, type GraphConfig, type GraphDiff, type GraphEdge, type GraphFormatConverter, GraphInstance, type GraphNode, type GraphPatch, type GraphPath, type GraphStep, type MSTOptions, type NodeChange, type NodeConfig, type PathOptions, type EntityRect as Positioned, type SinglePathOptions, type TransitionOptions, type TraversalOptions, type VisualEdge, type VisualGraph, type VisualGraphConfig, type VisualNode, type WalkContext, type WalkOptions, type WeightedWalkOptions, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphFromTransition, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCoverage, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };
+export { type AStarOptions, type AllPairsShortestPathsOptions, type CoverageStats, type DeleteNodeOptions, type EdgeChange, type EdgeConfig, type EntitiesConfig, type EntitiesUpdate, type Graph, type GraphConfig, type GraphDiff, type GraphEdge, type GraphEntity, type GraphEntityConfig, type GraphFormatConverter, GraphInstance, type GraphNode, type GraphPatch, type GraphPath, type GraphPort, type GraphStep, type MSTOptions, type NodeChange, type NodeConfig, type PathOptions, type PortConfig, type PortDirection, type EntityRect as Positioned, type SinglePathOptions, type TransitionOptions, type TraversalOptions, type VisualEdge, type VisualGraph, type VisualGraphConfig, type VisualGraphEntity, type VisualNode, type VisualPort, type WalkContext, type WalkOptions, type WeightedWalkOptions, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphEdge, createGraphFromTransition, createGraphNode, createGraphPort, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCoverage, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPort, getPorts, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { o as invalidateIndex, t as getIndex } from "./indexing-DyfgLuzw.mjs";
-import { A as addEntities, B as hasEdge, C as hasPath, D as joinPaths, E as isTree, F as deleteEdge, H as updateEdge, I as deleteEntities, L as deleteNode, M as createGraph, N as createGraphFromTransition, O as GraphInstance, P as createVisualGraph, R as getEdge, S as getTopologicalSort, T as isConnected, U as updateEntities, V as hasNode, W as updateNode, _ as getShortestPath, a as genPreorders, b as getSimplePaths, c as getAStarPath, d as getCycles, f as getMinimumSpanningTree, g as getPreorders, h as getPreorder, i as genPostorders, j as addNode, k as addEdge, l as getAllPairsShortestPaths, m as getPostorders, n as dfs, o as genShortestPaths, p as getPostorder, r as genCycles, s as genSimplePaths, t as bfs, u as getConnectedComponents, v as getShortestPaths, w as isAcyclic, x as getStronglyConnectedComponents, y as getSimplePath, z as getNode } from "./algorithms-oVD9PYil.mjs";
-import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
+import { A as addEntities, B as deleteNode, C as hasPath, D as joinPaths, E as isTree, F as createGraphNode, G as updateEdge, H as getNode, I as createGraphPort, K as updateEntities, L as createVisualGraph, M as createGraph, N as createGraphEdge, O as GraphInstance, P as createGraphFromTransition, R as deleteEdge, S as getTopologicalSort, T as isConnected, U as hasEdge, V as getEdge, W as hasNode, _ as getShortestPath, a as genPreorders, b as getSimplePaths, c as getAStarPath, d as getCycles, f as getMinimumSpanningTree, g as getPreorders, h as getPreorder, i as genPostorders, j as addNode, k as addEdge, l as getAllPairsShortestPaths, m as getPostorders, n as dfs, o as genShortestPaths, p as getPostorder, q as updateNode, r as genCycles, s as genSimplePaths, t as bfs, u as getConnectedComponents, v as getShortestPaths, w as isAcyclic, x as getStronglyConnectedComponents, y as getSimplePath, z as deleteEntities } from "./algorithms-Pbj9dJB1.mjs";
+import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPort, getPorts, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
 import { n as createFormatConverter } from "./converter-B5CUD0r9.mjs";
 
 //#region src/diff.ts
@@ -813,4 +813,4 @@ function getCoverage(graph, steps, options) {
 }
 
 //#endregion
-export { GraphInstance, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphFromTransition, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCoverage, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };
+export { GraphInstance, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphEdge, createGraphFromTransition, createGraphNode, createGraphPort, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPredefinedWalk, genPreorders, genQuickRandomWalk, genRandomWalk, genShortestPaths, genSimplePaths, genWeightedRandomWalk, getAStarPath, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCoverage, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPort, getPorts, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRelativeDistance, getRelativeDistanceMap, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSubgraph, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, reverseGraph, takeSteps, takeUntilEdge, takeUntilEdgeCoverage, takeUntilNode, takeUntilNodeCoverage, toDiff, toPatches, updateEdge, updateEntities, updateNode };

package/dist/queries.d.mts

@@ -1,4 +1,4 @@
-import { h as GraphNode, p as GraphEdge, u as Graph } from "./types-DF-HNw50.mjs";
+import { _ as GraphNode, b as GraphPort, p as GraphEdge, u as Graph } from "./types-BzckPChi.mjs";
 
 //#region src/queries.d.ts
 
@@ -454,5 +454,62 @@ declare function getSources<N>(graph: Graph<N>): GraphNode<N>[];
  * ```
  */
 declare function getSinks<N>(graph: Graph<N>): GraphNode<N>[];
+/**
+ * Get a port by name on a node, or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{
+ *     id: 'a',
+ *     ports: [{ name: 'out', direction: 'out' }],
+ *   }],
+ * });
+ * getPort(graph, 'a', 'out'); // => { name: 'out', direction: 'out', ... }
+ * getPort(graph, 'a', 'missing'); // => undefined
+ * ```
+ */
+declare function getPort<P = any>(graph: Graph<any, any, any, P>, nodeId: string, portName: string): GraphPort<P> | undefined;
+/**
+ * Get all ports on a node. Returns `[]` if the node has no ports or doesn't exist.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [{
+ *     id: 'a',
+ *     ports: [
+ *       { name: 'in', direction: 'in' },
+ *       { name: 'out', direction: 'out' },
+ *     ],
+ *   }],
+ * });
+ * getPorts(graph, 'a'); // => [port in, port out]
+ * ```
+ */
+declare function getPorts<P = any>(graph: Graph<any, any, any, P>, nodeId: string): GraphPort<P>[];
+/**
+ * Get all edges connected to a specific port on a node.
+ *
+ * Returns edges where:
+ * - `sourceId === nodeId && sourcePort === portName`, or
+ * - `targetId === nodeId && targetPort === portName`
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'a', ports: [{ name: 'out', direction: 'out' }] },
+ *     { id: 'b', ports: [{ name: 'in', direction: 'in' }] },
+ *   ],
+ *   edges: [{
+ *     id: 'e1', sourceId: 'a', targetId: 'b',
+ *     sourcePort: 'out', targetPort: 'in',
+ *   }],
+ * });
+ * getEdgesByPort(graph, 'a', 'out'); // => [edge e1]
+ * ```
+ */
+declare function getEdgesByPort<E = any>(graph: Graph<any, E>, nodeId: string, portName: string): GraphEdge<E>[];
 //#endregion
-export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };
+export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPort, getPorts, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };

package/dist/queries.mjs

@@ -565,7 +565,7 @@ function getRelativeDistanceMap(graph, parentId) {
 	if (parentId !== null) {
 		const pi = idx.nodeById.get(parentId);
 		if (pi !== void 0) sourceId = graph.nodes[pi].initialNodeId ?? null;
-	} else sourceId = graph.initialNodeId;
+	} else sourceId = graph.initialNodeId ?? null;
 	if (!sourceId) return {};
 	const siblingSet = new Set(idx.childNodes.get(parentId) ?? []);
 	if (!siblingSet.has(sourceId)) return {};
@@ -679,6 +679,83 @@ function getSinks(graph) {
 	const idx = getIndex(graph);
 	return graph.nodes.filter((n) => (idx.outEdges.get(n.id)?.length ?? 0) === 0);
 }
+/**
+* Get a port by name on a node, or `undefined` if not found.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{
+*     id: 'a',
+*     ports: [{ name: 'out', direction: 'out' }],
+*   }],
+* });
+* getPort(graph, 'a', 'out'); // => { name: 'out', direction: 'out', ... }
+* getPort(graph, 'a', 'missing'); // => undefined
+* ```
+*/
+function getPort(graph, nodeId, portName) {
+	const ni = getIndex(graph).nodeById.get(nodeId);
+	if (ni === void 0) return void 0;
+	return graph.nodes[ni].ports?.find((p) => p.name === portName);
+}
+/**
+* Get all ports on a node. Returns `[]` if the node has no ports or doesn't exist.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{
+*     id: 'a',
+*     ports: [
+*       { name: 'in', direction: 'in' },
+*       { name: 'out', direction: 'out' },
+*     ],
+*   }],
+* });
+* getPorts(graph, 'a'); // => [port in, port out]
+* ```
+*/
+function getPorts(graph, nodeId) {
+	const ni = getIndex(graph).nodeById.get(nodeId);
+	if (ni === void 0) return [];
+	return graph.nodes[ni].ports ?? [];
+}
+/**
+* Get all edges connected to a specific port on a node.
+*
+* Returns edges where:
+* - `sourceId === nodeId && sourcePort === portName`, or
+* - `targetId === nodeId && targetPort === portName`
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'a', ports: [{ name: 'out', direction: 'out' }] },
+*     { id: 'b', ports: [{ name: 'in', direction: 'in' }] },
+*   ],
+*   edges: [{
+*     id: 'e1', sourceId: 'a', targetId: 'b',
+*     sourcePort: 'out', targetPort: 'in',
+*   }],
+* });
+* getEdgesByPort(graph, 'a', 'out'); // => [edge e1]
+* ```
+*/
+function getEdgesByPort(graph, nodeId, portName) {
+	const idx = getIndex(graph);
+	const result = [];
+	for (const eid of idx.outEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0 && graph.edges[ai].sourcePort === portName) result.push(graph.edges[ai]);
+	}
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		const ai = idx.edgeById.get(eid);
+		if (ai !== void 0 && graph.edges[ai].targetPort === portName) result.push(graph.edges[ai]);
+	}
+	return result;
+}
 
 //#endregion
-export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };
+export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesByPort, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPort, getPorts, getPredecessors, getRelativeDistance, getRelativeDistanceMap, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };

package/dist/schemas.d.mts

@@ -6,7 +6,7 @@ declare const NodeSchema: z.ZodObject<{
   id: z.ZodString;
   parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   initialNodeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-  label: z.ZodString;
+  label: z.ZodOptional<z.ZodString>;
   data: z.ZodAny;
   x: z.ZodOptional<z.ZodNumber>;
   y: z.ZodOptional<z.ZodNumber>;
@@ -21,7 +21,7 @@ declare const EdgeSchema: z.ZodObject<{
   id: z.ZodString;
   sourceId: z.ZodString;
   targetId: z.ZodString;
-  label: z.ZodString;
+  label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   weight: z.ZodOptional<z.ZodNumber>;
   data: z.ZodAny;
   x: z.ZodOptional<z.ZodNumber>;
@@ -37,13 +37,13 @@ declare const GraphSchema: z.ZodObject<{
     directed: "directed";
     undirected: "undirected";
   }>;
-  initialNodeId: z.ZodNullable<z.ZodString>;
+  initialNodeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   nodes: z.ZodArray<z.ZodObject<{
     type: z.ZodLiteral<"node">;
     id: z.ZodString;
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     initialNodeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    label: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
     data: z.ZodAny;
     x: z.ZodOptional<z.ZodNumber>;
     y: z.ZodOptional<z.ZodNumber>;
@@ -58,7 +58,7 @@ declare const GraphSchema: z.ZodObject<{
     id: z.ZodString;
     sourceId: z.ZodString;
     targetId: z.ZodString;
-    label: z.ZodString;
+    label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     weight: z.ZodOptional<z.ZodNumber>;
     data: z.ZodAny;
     x: z.ZodOptional<z.ZodNumber>;

package/dist/schemas.mjs

@@ -7,7 +7,7 @@ const NodeSchema = z.object({
 	id: z.string(),
 	parentId: z.string().nullable().optional(),
 	initialNodeId: z.string().nullable().optional(),
-	label: z.string(),
+	label: z.string().optional(),
 	data: z.any(),
 	x: z.number().optional(),
 	y: z.number().optional(),
@@ -22,7 +22,7 @@ const EdgeSchema = z.object({
 	id: z.string(),
 	sourceId: z.string(),
 	targetId: z.string(),
-	label: z.string(),
+	label: z.string().nullable().optional(),
 	weight: z.number().optional(),
 	data: z.any(),
 	x: z.number().optional(),
@@ -35,7 +35,7 @@ const EdgeSchema = z.object({
 const GraphSchema = z.object({
 	id: z.string(),
 	type: z.enum(["directed", "undirected"]),
-	initialNodeId: z.string().nullable(),
+	initialNodeId: z.string().nullable().optional(),
 	nodes: z.array(NodeSchema),
 	edges: z.array(EdgeSchema),
 	data: z.any(),

package/dist/{types-DF-HNw50.d.mts → types-BzckPChi.d.mts}

@@ -5,31 +5,59 @@ interface EntityRect {
   width: number;
   height: number;
 }
-interface GraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any> {
+/** Config-level base — shared optional visual/style props for nodes, edges, ports. */
+interface GraphEntityConfig {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  style?: Record<string, string | number>;
+}
+/** Resolved entity base — optional visual props (non-visual graphs may omit). */
+interface GraphEntity extends GraphEntityConfig {}
+/** Visual entity base — required position/size. */
+interface VisualGraphEntity {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  style?: Record<string, string | number>;
+}
+type PortDirection = 'in' | 'out' | 'inout';
+interface PortConfig<TPortData = any> extends GraphEntityConfig {
+  name: string;
+  direction?: PortDirection;
+  label?: string;
+  data?: TPortData;
+}
+interface GraphPort<TPortData = any> extends GraphEntity {
+  name: string;
+  direction: PortDirection;
+  label?: string;
+  data: TPortData;
+}
+interface VisualPort<TPortData = any> extends Omit<GraphPort<TPortData>, keyof EntityRect>, VisualGraphEntity {}
+interface GraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any, TPortData = any> {
   id?: string;
   type?: 'directed' | 'undirected';
   initialNodeId?: string;
-  nodes?: NodeConfig<TNodeData>[];
+  nodes?: NodeConfig<TNodeData, TPortData>[];
   edges?: EdgeConfig<TEdgeData>[];
   data?: TGraphData;
   direction?: 'up' | 'down' | 'left' | 'right';
   style?: Record<string, string | number>;
 }
-interface NodeConfig<TNodeData = any> {
+interface NodeConfig<TNodeData = any, TPortData = any> extends GraphEntityConfig {
   id: string;
   parentId?: string | null;
   initialNodeId?: string;
   label?: string;
   data?: TNodeData;
-  x?: number;
-  y?: number;
-  width?: number;
-  height?: number;
+  ports?: PortConfig<TPortData>[];
   shape?: string;
   color?: string;
-  style?: Record<string, string | number>;
 }
-interface EdgeConfig<TEdgeData = any> {
+interface EdgeConfig<TEdgeData = any> extends GraphEntityConfig {
   /**
    * The id of the edge.
    */
@@ -52,80 +80,75 @@ interface EdgeConfig<TEdgeData = any> {
    * When `getWeight` is not provided, algorithms default to `edge.weight ?? 1`.
    */
   weight?: number;
+  /** Port name on the source node this edge connects from. */
+  sourcePort?: string;
+  /** Port name on the target node this edge connects to. */
+  targetPort?: string;
   data?: TEdgeData;
-  x?: number;
-  y?: number;
-  width?: number;
-  height?: number;
   color?: string;
-  style?: Record<string, string | number>;
 }
-interface Graph<TNodeData = any, TEdgeData = any, TGraphData = any> {
+interface Graph<TNodeData = any, TEdgeData = any, TGraphData = any, TPortData = any> {
   id: string;
   type: 'directed' | 'undirected';
-  initialNodeId: string | null;
-  nodes: GraphNode<TNodeData>[];
+  initialNodeId?: string | null;
+  nodes: GraphNode<TNodeData, TPortData>[];
   edges: GraphEdge<TEdgeData>[];
   data: TGraphData;
   direction?: 'up' | 'down' | 'left' | 'right';
   style?: Record<string, string | number>;
 }
-interface GraphNode<TNodeData = any> {
+interface GraphNode<TNodeData = any, TPortData = any> extends GraphEntity {
   type: 'node';
   id: string;
   parentId?: string | null;
   initialNodeId?: string | null;
-  label: string;
+  label?: string;
   data: TNodeData;
-  x?: number;
-  y?: number;
-  width?: number;
-  height?: number;
+  ports?: GraphPort<TPortData>[];
   shape?: string;
   color?: string;
-  style?: Record<string, string | number>;
 }
-interface GraphEdge<TEdgeData = any> {
+interface GraphEdge<TEdgeData = any> extends GraphEntity {
   type: 'edge';
   id: string;
   sourceId: string;
   targetId: string;
-  label: string | null;
+  label?: string | null;
   /**
    * Optional numeric weight for the edge.
    * Used by pathfinding, MST, and other weighted algorithms.
    * When `getWeight` is not provided, algorithms default to `edge.weight ?? 1`.
    */
   weight?: number;
+  /** Port name on the source node this edge connects from. */
+  sourcePort?: string;
+  /** Port name on the target node this edge connects to. */
+  targetPort?: string;
   data: TEdgeData;
-  x?: number;
-  y?: number;
-  width?: number;
-  height?: number;
   color?: string;
-  style?: Record<string, string | number>;
 }
-interface VisualNode<TNodeData = any> extends Omit<GraphNode<TNodeData>, keyof EntityRect>, EntityRect {
+interface VisualNode<TNodeData = any, TPortData = any> extends Omit<GraphNode<TNodeData, TPortData>, keyof EntityRect>, VisualGraphEntity {
   shape?: string;
+  ports?: VisualPort<TPortData>[];
 }
-interface VisualEdge<TEdgeData = any> extends Omit<GraphEdge<TEdgeData>, keyof EntityRect>, EntityRect {}
-interface VisualGraph<TNodeData = any, TEdgeData = any, TGraphData = any> extends Omit<Graph<TNodeData, TEdgeData, TGraphData>, 'nodes' | 'edges'> {
-  nodes: VisualNode<TNodeData>[];
+interface VisualEdge<TEdgeData = any> extends Omit<GraphEdge<TEdgeData>, keyof EntityRect>, VisualGraphEntity {}
+interface VisualGraph<TNodeData = any, TEdgeData = any, TGraphData = any, TPortData = any> extends Omit<Graph<TNodeData, TEdgeData, TGraphData, TPortData>, 'nodes' | 'edges'> {
+  nodes: VisualNode<TNodeData, TPortData>[];
   edges: VisualEdge<TEdgeData>[];
   direction: 'up' | 'down' | 'left' | 'right';
 }
-interface VisualGraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any> extends GraphConfig<TNodeData, TEdgeData, TGraphData> {
+interface VisualGraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any, TPortData = any> extends GraphConfig<TNodeData, TEdgeData, TGraphData, TPortData> {
   direction?: 'up' | 'down' | 'left' | 'right';
 }
 interface DeleteNodeOptions {
   reparent?: boolean;
 }
-interface EntitiesConfig<TNodeData = any, TEdgeData = any> {
-  nodes?: NodeConfig<TNodeData>[];
+interface EntitiesConfig<TNodeData = any, TEdgeData = any, TPortData = any> {
+  nodes?: NodeConfig<TNodeData, TPortData>[];
   edges?: EdgeConfig<TEdgeData>[];
 }
-interface EntitiesUpdate<TNodeData = any, TEdgeData = any> {
-  nodes?: (Partial<Omit<NodeConfig<TNodeData>, 'id'>> & {
+interface EntitiesUpdate<TNodeData = any, TEdgeData = any, TPortData = any> {
+  nodes?: (Partial<Omit<NodeConfig<TNodeData, TPortData>, 'id'>> & {
     id: string;
   })[];
   edges?: (Partial<Omit<EdgeConfig<TEdgeData>, 'id'>> & {
@@ -314,4 +337,4 @@ interface TransitionOptions<TState, TEvent> {
   id?: string;
 }
 //#endregion
-export { VisualNode as A, SinglePathOptions as C, VisualGraph as D, VisualEdge as E, WalkOptions as M, WeightedWalkOptions as N, VisualGraphConfig as O, PathOptions as S, TraversalOptions as T, GraphPath as _, EdgeChange as a, NodeChange as b, EntitiesUpdate as c, GraphConfig as d, GraphDiff as f, GraphPatch as g, GraphNode as h, DeleteNodeOptions as i, WalkContext as j, VisualGraphFormatConverter as k, EntityRect as l, GraphFormatConverter as m, AllPairsShortestPathsOptions as n, EdgeConfig as o, GraphEdge as p, CoverageStats as r, EntitiesConfig as s, AStarOptions as t, Graph as u, GraphStep as v, TransitionOptions as w, NodeConfig as x, MSTOptions as y };
+export { TraversalOptions as A, WeightedWalkOptions as B, NodeChange as C, PortDirection as D, PortConfig as E, VisualGraphFormatConverter as F, VisualNode as I, VisualPort as L, VisualGraph as M, VisualGraphConfig as N, SinglePathOptions as O, VisualGraphEntity as P, WalkContext as R, MSTOptions as S, PathOptions as T, GraphNode as _, EdgeChange as a, GraphPort as b, EntitiesUpdate as c, GraphConfig as d, GraphDiff as f, GraphFormatConverter as g, GraphEntityConfig as h, DeleteNodeOptions as i, VisualEdge as j, TransitionOptions as k, EntityRect as l, GraphEntity as m, AllPairsShortestPathsOptions as n, EdgeConfig as o, GraphEdge as p, CoverageStats as r, EntitiesConfig as s, AStarOptions as t, Graph as u, GraphPatch as v, NodeConfig as w, GraphStep as x, GraphPath as y, WalkOptions as z };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statelyai/graph",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A TypeScript-first graph library with plain JSON-serializable objects",
   "author": "David Khourshid <david@stately.ai>",
   "license": "MIT",