@statelyai/graph 0.1.0 → 0.3.0

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

@@ -0,0 +1,9 @@
+import { c as Graph, f as GraphFormatConverter } from "../../types-B6Tpeerk.mjs";
+
+//#region src/formats/tgf/index.d.ts
+declare function toTGF(graph: Graph): string;
+declare function fromTGF(tgf: string): Graph;
+/** Bidirectional converter for TGF (Trivial Graph Format). */
+declare const tgfConverter: GraphFormatConverter<string>;
+//#endregion
+export { fromTGF, tgfConverter, toTGF };

package/dist/formats/tgf/index.mjs

@@ -0,0 +1,67 @@
+import { n as createFormatConverter } from "../../converter-DnbeyE_p.mjs";
+
+//#region src/formats/tgf/index.ts
+function toTGF(graph) {
+	const lines = [];
+	for (const node of graph.nodes) lines.push(node.label ? `${node.id} ${node.label}` : node.id);
+	lines.push("#");
+	for (const edge of graph.edges) {
+		const parts = [edge.sourceId, edge.targetId];
+		if (edge.label) parts.push(edge.label);
+		lines.push(parts.join(" "));
+	}
+	return lines.join("\n");
+}
+function fromTGF(tgf) {
+	if (typeof tgf !== "string") throw new Error("TGF: expected a string");
+	const lines = tgf.split("\n");
+	const sepIdx = lines.indexOf("#");
+	const nodeLines = sepIdx >= 0 ? lines.slice(0, sepIdx) : lines;
+	const edgeLines = sepIdx >= 0 ? lines.slice(sepIdx + 1) : [];
+	const nodes = [];
+	for (const line of nodeLines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const spaceIdx = trimmed.indexOf(" ");
+		const id = spaceIdx >= 0 ? trimmed.slice(0, spaceIdx) : trimmed;
+		const label = spaceIdx >= 0 ? trimmed.slice(spaceIdx + 1) : "";
+		nodes.push({
+			type: "node",
+			id,
+			parentId: null,
+			initialNodeId: null,
+			label,
+			data: void 0
+		});
+	}
+	const edges = [];
+	for (const line of edgeLines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const parts = trimmed.split(" ");
+		const sourceId = parts[0];
+		const targetId = parts[1];
+		const label = parts.slice(2).join(" ");
+		edges.push({
+			type: "edge",
+			id: `e${edges.length}`,
+			sourceId,
+			targetId,
+			label,
+			data: void 0
+		});
+	}
+	return {
+		id: "",
+		type: "directed",
+		initialNodeId: null,
+		nodes,
+		edges,
+		data: void 0
+	};
+}
+/** Bidirectional converter for TGF (Trivial Graph Format). */
+const tgfConverter = createFormatConverter(toTGF, fromTGF);
+
+//#endregion
+export { fromTGF, tgfConverter, toTGF };

package/dist/index.d.mts

@@ -1,17 +1,22 @@
-import { C as VisualGraph, S as VisualEdge, T as VisualNode, _ as NodeChange, a as EntitiesConfig, b as SinglePathOptions, c as Graph, d as GraphEdge, f as GraphNode, g as MSTOptions, h as GraphStep, i as EdgeConfig, l as GraphConfig, m as GraphPath, n as DeleteNodeOptions, o as EntitiesUpdate, p as GraphPatch, r as EdgeChange, s as EntityRect, t as AllPairsShortestPathsOptions, u as GraphDiff, v as NodeConfig, w as VisualGraphConfig, x as TraversalOptions, y as PathOptions } from "./types-XV3S5Jnh.mjs";
-import { bfs, dfs, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getConnectedComponents, getCycles, getMinimumSpanningTree, getPostorder, getPostorders, getPreorder, getPreorders, getShortestPath, getShortestPaths, getSimplePath, getSimplePaths, getStronglyConnectedComponents, getTopologicalSort, hasPath, isAcyclic, isConnected, isTree } from "./algorithms.mjs";
-import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-DW-lAUe8.mjs";
-import { t as toDOT } from "./dot-HmJeUMsj.mjs";
-import { n as toEdgeList, t as fromEdgeList } from "./edge-list-CJmfoNu2.mjs";
-import { n as toGraphML, t as fromGraphML } from "./graphml-CMjPzSfY.mjs";
-import { EdgeSchema, GraphSchema, NodeSchema } from "./schemas.mjs";
-import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
+import { C as TraversalOptions, D as VisualNode, E as VisualGraphConfig, S as TransitionOptions, T as VisualGraph, _ as MSTOptions, a as EntitiesConfig, b as PathOptions, c as Graph, d as GraphEdge, f as GraphFormatConverter, g as GraphStep, h as GraphPath, i as EdgeConfig, l as GraphConfig, m as GraphPatch, n as DeleteNodeOptions, o as EntitiesUpdate, p as GraphNode, r as EdgeChange, s as EntityRect, t as AllPairsShortestPathsOptions, u as GraphDiff, v as NodeChange, w as VisualEdge, x as SinglePathOptions, y as NodeConfig } from "./types-B6Tpeerk.mjs";
+import { bfs, dfs, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, 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";
 
 //#region src/graph.d.ts
 /** Create a graph from a config. Resolves defaults for all fields. */
 declare function createGraph<N = any, E = any, G = any>(config?: GraphConfig<N, E, G>): Graph<N, E, G>;
 /** Create a visual graph with required position/size on all nodes and edges. */
 declare function createVisualGraph<N = any, E = any, G = any>(config?: VisualGraphConfig<N, E, G>): VisualGraph<N, E, G>;
+/**
+ * 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.
+ */
+declare function createGraphFromTransition<TState, TEvent>(transition: (state: TState, event: TEvent) => TState, options: TransitionOptions<TState, TEvent>): Graph<TState, TEvent>;
 /** Get a node by id, or `undefined` if not found. */
 declare function getNode<N>(graph: Graph<N>, id: string): GraphNode<N> | undefined;
 /** Get an edge by id, or `undefined` if not found. */
@@ -139,4 +144,4 @@ declare function toDiff<N, E>(patches: GraphPatch<N, E>[]): GraphDiff<N, E>;
  */
 declare function flatten<N, E, G>(graph: Graph<N, E, G>): Graph<N, E, G>;
 //#endregion
-export { type AllPairsShortestPathsOptions, type DeleteNodeOptions, type EdgeChange, type EdgeConfig, EdgeSchema, type EntitiesConfig, type EntitiesUpdate, type Graph, type GraphConfig, type GraphDiff, type GraphEdge, GraphInstance, type GraphNode, type GraphPatch, type GraphPath, GraphSchema, type GraphStep, type MSTOptions, type NodeChange, type NodeConfig, NodeSchema, type PathOptions, type EntityRect as Positioned, type SinglePathOptions, type TraversalOptions, type VisualEdge, type VisualGraph, type VisualGraphConfig, type VisualNode, addEdge, addEntities, addNode, applyPatches, bfs, createGraph, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, fromAdjacencyList, fromEdgeList, fromGraphML, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, toAdjacencyList, toDOT, toDiff, toEdgeList, toGraphML, toPatches, updateEdge, updateEntities, updateNode };
+export { type AllPairsShortestPathsOptions, 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, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphFromTransition, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, 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, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, toDiff, toPatches, updateEdge, updateEntities, updateNode };

package/dist/index.mjs

@@ -1,11 +1,7 @@
-import { o as invalidateIndex, t as getIndex } from "./indexing-BHg1VhqN.mjs";
-import { A as createGraph, B as updateEntities, C as isAcyclic, D as addEdge, E as GraphInstance, F as getEdge, I as getNode, L as hasEdge, M as deleteEdge, N as deleteEntities, O as addEntities, P as deleteNode, R as hasNode, S as hasPath, T as isTree, V as updateNode, _ as getShortestPaths, a as genPreorders, b as getStronglyConnectedComponents, c as getAllPairsShortestPaths, d as getMinimumSpanningTree, f as getPostorder, g as getShortestPath, h as getPreorders, i as genPostorders, j as createVisualGraph, k as addNode, l as getConnectedComponents, m as getPreorder, n as dfs, o as genShortestPaths, p as getPostorders, r as genCycles, s as genSimplePaths, t as bfs, u as getCycles, v as getSimplePath, w as isConnected, x as getTopologicalSort, y as getSimplePaths, z as updateEdge } from "./algorithms-R35X6ro4.mjs";
-import { EdgeSchema, GraphSchema, NodeSchema } from "./schemas.mjs";
-import { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf } from "./queries.mjs";
-import { n as toGraphML, t as fromGraphML } from "./graphml-CUTNRXqd.mjs";
-import { t as toDOT } from "./dot-BRtq3e3c.mjs";
-import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-CXpOCibq.mjs";
-import { n as toEdgeList, t as fromEdgeList } from "./edge-list-BRujEnnU.mjs";
+import { o as invalidateIndex, t as getIndex } from "./indexing-BFFVMnjF.mjs";
+import { A as addNode, B as hasNode, C as isAcyclic, D as GraphInstance, E as joinPaths, F as deleteEntities, H as updateEntities, I as deleteNode, L as getEdge, M as createGraphFromTransition, N as createVisualGraph, O as addEdge, P as deleteEdge, R as getNode, S as hasPath, T as isTree, U as updateNode, V as updateEdge, _ as getShortestPaths, a as genPreorders, b as getStronglyConnectedComponents, c as getAllPairsShortestPaths, d as getMinimumSpanningTree, f as getPostorder, g as getShortestPath, h as getPreorders, i as genPostorders, j as createGraph, k as addEntities, l as getConnectedComponents, m as getPreorder, n as dfs, o as genShortestPaths, p as getPostorders, r as genCycles, s as genSimplePaths, t as bfs, u as getCycles, v as getSimplePath, w as isConnected, x as getTopologicalSort, y as getSimplePaths, z as hasEdge } from "./algorithms-DBU7nmIV.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 { n as createFormatConverter } from "./converter-DnbeyE_p.mjs";
 
 //#region src/diff.ts
 function nodeToConfig(node) {
@@ -353,4 +349,4 @@ function flatten(graph) {
 }
 
 //#endregion
-export { EdgeSchema, GraphInstance, GraphSchema, NodeSchema, addEdge, addEntities, addNode, applyPatches, bfs, createGraph, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, fromAdjacencyList, fromEdgeList, fromGraphML, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, getCycles, getDegree, getDepth, getDescendants, getDiff, getEdge, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getMinimumSpanningTree, getNeighbors, getNode, getOutDegree, getOutEdges, getParent, getPatches, getPostorder, getPostorders, getPredecessors, getPreorder, getPreorders, getRoots, getShortestPath, getShortestPaths, getSiblings, getSimplePath, getSimplePaths, getSinks, getSources, getStronglyConnectedComponents, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, toAdjacencyList, toDOT, toDiff, toEdgeList, toGraphML, toPatches, updateEdge, updateEntities, updateNode };
+export { GraphInstance, addEdge, addEntities, addNode, applyPatches, bfs, createFormatConverter, createGraph, createGraphFromTransition, createVisualGraph, deleteEdge, deleteEntities, deleteNode, dfs, flatten, genCycles, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAllPairsShortestPaths, getAncestors, getChildren, getConnectedComponents, 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, getSuccessors, getTopologicalSort, hasEdge, hasNode, hasPath, invalidateIndex, invertDiff, isAcyclic, isCompound, isConnected, isEmptyDiff, isLeaf, isTree, joinPaths, toDiff, toPatches, updateEdge, updateEntities, updateNode };

package/dist/queries.d.mts

@@ -1,4 +1,4 @@
-import { c as Graph, d as GraphEdge, f as GraphNode } from "./types-XV3S5Jnh.mjs";
+import { c as Graph, d as GraphEdge, p as GraphNode } from "./types-B6Tpeerk.mjs";
 
 //#region src/queries.d.ts
 declare function getEdgesOf<E>(graph: Graph<any, E>, nodeId: string): GraphEdge<E>[];
@@ -29,9 +29,85 @@ declare function getSiblings<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[]
  * A proper ancestor excludes the input nodes themselves.
  */
 declare function getLCA<N>(graph: Graph<N>, ...nodeIds: string[]): GraphNode<N> | undefined;
+/**
+ * Returns a map of nodeId → shortest-path distance for all sibling nodes
+ * (same parentId). Distance is measured from the parent's `initialNodeId`
+ * (or `graph.initialNodeId` for root-level nodes).
+ *
+ * Only follows edges between siblings. Unreachable siblings are omitted.
+ *
+ * @example Root-level nodes (uses `graph.initialNodeId`):
+ * ```ts
+ * const graph = createGraph({
+ *   initialNodeId: 'a',
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ * getRelativeDistanceMap(graph, null);
+ * // => { a: 0, b: 1, c: 2 }
+ * ```
+ *
+ * @example Nested nodes (uses parent's `initialNodeId`):
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent', initialNodeId: 's1' },
+ *     { id: 's1', parentId: 'parent' },
+ *     { id: 's2', parentId: 'parent' },
+ *     { id: 's3', parentId: 'parent' },
+ *   ],
+ *   edges: [
+ *     { id: 'e1', sourceId: 's1', targetId: 's2' },
+ *     { id: 'e2', sourceId: 's2', targetId: 's3' },
+ *   ],
+ * });
+ * getRelativeDistanceMap(graph, 'parent');
+ * // => { s1: 0, s2: 1, s3: 2 }
+ * ```
+ */
+declare function getRelativeDistanceMap(graph: Graph, parentId: string | null): Record<string, number>;
+/**
+ * Returns the shortest-path distance of a node from its parent's initial node.
+ * Automatically scopes to the node's sibling group (same `parentId`).
+ *
+ * Returns `undefined` if the node is not found or unreachable.
+ *
+ * @example
+ * ```ts
+ * const graph = createGraph({
+ *   initialNodeId: 'a',
+ *   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+ *   edges: [
+ *     { id: 'e1', sourceId: 'a', targetId: 'b' },
+ *     { id: 'e2', sourceId: 'b', targetId: 'c' },
+ *   ],
+ * });
+ * getRelativeDistance(graph, 'a'); // => 0
+ * getRelativeDistance(graph, 'b'); // => 1
+ * getRelativeDistance(graph, 'c'); // => 2
+ * ```
+ *
+ * @example Nested nodes:
+ * ```ts
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'parent', initialNodeId: 's1' },
+ *     { id: 's1', parentId: 'parent' },
+ *     { id: 's2', parentId: 'parent' },
+ *   ],
+ *   edges: [{ id: 'e1', sourceId: 's1', targetId: 's2' }],
+ * });
+ * getRelativeDistance(graph, 's1'); // => 0
+ * getRelativeDistance(graph, 's2'); // => 1
+ * ```
+ */
+declare function getRelativeDistance(graph: Graph, nodeId: string): number | undefined;
 /** Nodes with no incoming edges (inDegree 0). */
 declare function getSources<N>(graph: Graph<N>): GraphNode<N>[];
 /** Nodes with no outgoing edges (outDegree 0). */
 declare function getSinks<N>(graph: Graph<N>): GraphNode<N>[];
 //#endregion
-export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };
+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 };

package/dist/queries.mjs

@@ -1,4 +1,4 @@
-import { t as getIndex } from "./indexing-BHg1VhqN.mjs";
+import { t as getIndex } from "./indexing-BFFVMnjF.mjs";
 
 //#region src/queries.ts
 function getEdgesOf(graph, nodeId) {
@@ -206,6 +206,125 @@ function getLCA(graph, ...nodeIds) {
 	const ni = idx.nodeById.get(lcaId);
 	return ni !== void 0 ? graph.nodes[ni] : void 0;
 }
+/**
+* Returns a map of nodeId → shortest-path distance for all sibling nodes
+* (same parentId). Distance is measured from the parent's `initialNodeId`
+* (or `graph.initialNodeId` for root-level nodes).
+*
+* Only follows edges between siblings. Unreachable siblings are omitted.
+*
+* @example Root-level nodes (uses `graph.initialNodeId`):
+* ```ts
+* const graph = createGraph({
+*   initialNodeId: 'a',
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'e1', sourceId: 'a', targetId: 'b' },
+*     { id: 'e2', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+* getRelativeDistanceMap(graph, null);
+* // => { a: 0, b: 1, c: 2 }
+* ```
+*
+* @example Nested nodes (uses parent's `initialNodeId`):
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent', initialNodeId: 's1' },
+*     { id: 's1', parentId: 'parent' },
+*     { id: 's2', parentId: 'parent' },
+*     { id: 's3', parentId: 'parent' },
+*   ],
+*   edges: [
+*     { id: 'e1', sourceId: 's1', targetId: 's2' },
+*     { id: 'e2', sourceId: 's2', targetId: 's3' },
+*   ],
+* });
+* getRelativeDistanceMap(graph, 'parent');
+* // => { s1: 0, s2: 1, s3: 2 }
+* ```
+*/
+function getRelativeDistanceMap(graph, parentId) {
+	const idx = getIndex(graph);
+	let sourceId = null;
+	if (parentId !== null) {
+		const pi = idx.nodeById.get(parentId);
+		if (pi !== void 0) sourceId = graph.nodes[pi].initialNodeId;
+	} else sourceId = graph.initialNodeId;
+	if (!sourceId) return {};
+	const siblingSet = new Set(idx.childNodes.get(parentId) ?? []);
+	if (!siblingSet.has(sourceId)) return {};
+	const dist = /* @__PURE__ */ new Map();
+	dist.set(sourceId, 0);
+	const queue = [sourceId];
+	while (queue.length > 0) {
+		const id = queue.shift();
+		const d = dist.get(id);
+		for (const eid of idx.outEdges.get(id) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const neighborId = graph.edges[ai].targetId;
+			if (siblingSet.has(neighborId) && !dist.has(neighborId)) {
+				dist.set(neighborId, d + 1);
+				queue.push(neighborId);
+			}
+		}
+		if (graph.type === "undirected") for (const eid of idx.inEdges.get(id) ?? []) {
+			const ai = idx.edgeById.get(eid);
+			if (ai === void 0) continue;
+			const neighborId = graph.edges[ai].sourceId;
+			if (siblingSet.has(neighborId) && !dist.has(neighborId)) {
+				dist.set(neighborId, d + 1);
+				queue.push(neighborId);
+			}
+		}
+	}
+	const result = {};
+	for (const [id, d] of dist) result[id] = d;
+	return result;
+}
+/**
+* Returns the shortest-path distance of a node from its parent's initial node.
+* Automatically scopes to the node's sibling group (same `parentId`).
+*
+* Returns `undefined` if the node is not found or unreachable.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   initialNodeId: 'a',
+*   nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+*   edges: [
+*     { id: 'e1', sourceId: 'a', targetId: 'b' },
+*     { id: 'e2', sourceId: 'b', targetId: 'c' },
+*   ],
+* });
+* getRelativeDistance(graph, 'a'); // => 0
+* getRelativeDistance(graph, 'b'); // => 1
+* getRelativeDistance(graph, 'c'); // => 2
+* ```
+*
+* @example Nested nodes:
+* ```ts
+* const graph = createGraph({
+*   nodes: [
+*     { id: 'parent', initialNodeId: 's1' },
+*     { id: 's1', parentId: 'parent' },
+*     { id: 's2', parentId: 'parent' },
+*   ],
+*   edges: [{ id: 'e1', sourceId: 's1', targetId: 's2' }],
+* });
+* getRelativeDistance(graph, 's1'); // => 0
+* getRelativeDistance(graph, 's2'); // => 1
+* ```
+*/
+function getRelativeDistance(graph, nodeId) {
+	const ni = getIndex(graph).nodeById.get(nodeId);
+	if (ni === void 0) return void 0;
+	const node = graph.nodes[ni];
+	return getRelativeDistanceMap(graph, node.parentId)[nodeId];
+}
 /** Nodes with no incoming edges (inDegree 0). */
 function getSources(graph) {
 	const idx = getIndex(graph);
@@ -218,4 +337,4 @@ function getSinks(graph) {
 }
 
 //#endregion
-export { getAncestors, getChildren, getDegree, getDepth, getDescendants, getEdgeBetween, getEdgesOf, getInDegree, getInEdges, getLCA, getNeighbors, getOutDegree, getOutEdges, getParent, getPredecessors, getRoots, getSiblings, getSinks, getSources, getSuccessors, isCompound, isLeaf };
+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 };

package/dist/{types-XV3S5Jnh.d.mts → types-B6Tpeerk.d.mts}

@@ -215,5 +215,40 @@ type GraphPatch<TNodeData = any, TEdgeData = any> = {
   id: string;
   description?: string;
 };
+/**
+ * A bidirectional converter between `Graph` and a serialized format.
+ *
+ * Implement this interface to create a custom format converter.
+ *
+ * @example
+ * ```ts
+ * const myConverter: GraphFormatConverter<string> = {
+ *   to(graph) { return JSON.stringify(graph); },
+ *   from(input) { return JSON.parse(input); },
+ * };
+ * ```
+ */
+interface GraphFormatConverter<TSerial> {
+  /** Convert a Graph to the serialized format. */
+  to(graph: Graph): TSerial;
+  /** Convert from the serialized format to a Graph. */
+  from(input: TSerial): Graph;
+}
+interface TransitionOptions<TState, TEvent> {
+  /** Initial state to begin BFS exploration from. */
+  initialState: TState;
+  /** Events to try at each state. Array or function of state. */
+  events: TEvent[] | ((state: TState) => TEvent[]);
+  /** Serialize state to unique string for node dedup. Default: JSON.stringify */
+  serializeState?: (state: TState) => string;
+  /** Serialize event to string for edge labels/IDs. Default: JSON.stringify */
+  serializeEvent?: (event: TEvent) => string;
+  /** Max BFS iterations before throwing. Default: Infinity */
+  limit?: number;
+  /** When true, node is kept but outgoing transitions are not explored. */
+  stopWhen?: (state: TState) => boolean;
+  /** Optional graph ID. */
+  id?: string;
+}
 //#endregion
-export { VisualGraph as C, VisualEdge as S, VisualNode as T, NodeChange as _, EntitiesConfig as a, SinglePathOptions as b, Graph as c, GraphEdge as d, GraphNode as f, MSTOptions as g, GraphStep as h, EdgeConfig as i, GraphConfig as l, GraphPath as m, DeleteNodeOptions as n, EntitiesUpdate as o, GraphPatch as p, EdgeChange as r, EntityRect as s, AllPairsShortestPathsOptions as t, GraphDiff as u, NodeConfig as v, VisualGraphConfig as w, TraversalOptions as x, PathOptions as y };
+export { TraversalOptions as C, VisualNode as D, VisualGraphConfig as E, TransitionOptions as S, VisualGraph as T, MSTOptions as _, EntitiesConfig as a, PathOptions as b, Graph as c, GraphEdge as d, GraphFormatConverter as f, GraphStep as g, GraphPath as h, EdgeConfig as i, GraphConfig as l, GraphPatch as m, DeleteNodeOptions as n, EntitiesUpdate as o, GraphNode as p, EdgeChange as r, EntityRect as s, AllPairsShortestPathsOptions as t, GraphDiff as u, NodeChange as v, VisualEdge as w, SinglePathOptions as x, NodeConfig as y };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statelyai/graph",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A TypeScript-first graph library with plain JSON-serializable objects",
   "author": "David Khourshid <david@stately.ai>",
   "license": "MIT",
@@ -24,10 +24,18 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./algorithms": "./dist/algorithms.mjs",
-    "./formats/adjacency-list": "./dist/formats/adjacency-list.mjs",
-    "./formats/dot": "./dist/formats/dot.mjs",
-    "./formats/edge-list": "./dist/formats/edge-list.mjs",
-    "./formats/graphml": "./dist/formats/graphml.mjs",
+    "./adjacency-list": "./dist/formats/adjacency-list/index.mjs",
+    "./converter": "./dist/formats/converter/index.mjs",
+    "./cytoscape": "./dist/formats/cytoscape/index.mjs",
+    "./d3": "./dist/formats/d3/index.mjs",
+    "./dot": "./dist/formats/dot/index.mjs",
+    "./edge-list": "./dist/formats/edge-list/index.mjs",
+    "./gexf": "./dist/formats/gexf/index.mjs",
+    "./gml": "./dist/formats/gml/index.mjs",
+    "./graphml": "./dist/formats/graphml/index.mjs",
+    "./jgf": "./dist/formats/jgf/index.mjs",
+    "./mermaid": "./dist/formats/mermaid/index.mjs",
+    "./tgf": "./dist/formats/tgf/index.mjs",
     "./queries": "./dist/queries.mjs",
     "./schemas": "./dist/schemas.mjs",
     "./package.json": "./package.json"
@@ -39,39 +47,57 @@
     "dist",
     "schemas"
   ],
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest",
-    "typecheck": "tsc --noEmit",
-    "generate-schema": "tsx scripts/generate-json-schema.ts",
-    "changeset": "changeset",
-    "version": "changeset version",
-    "release": "pnpm run build && changeset publish",
-    "prepublishOnly": "pnpm run build"
-  },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
+    "@types/d3-array": "^3.2.2",
+    "@types/d3-force": "^3.0.10",
     "@types/node": "^25.0.3",
     "bumpp": "^10.3.2",
+    "cytoscape": "^3.33.1",
+    "d3-array": "^3.2.4",
+    "d3-force": "^3.0.0",
+    "dotparser": "^1.1.1",
     "fast-xml-parser": "^5.3.4",
     "tsdown": "^0.18.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16",
+    "xstate": "^5.28.0",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
+    "cytoscape": "^3.0.0",
+    "d3-force": "^3.0.0",
+    "dotparser": "^1.0.0",
     "fast-xml-parser": "^5.0.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "cytoscape": {
+      "optional": true
+    },
+    "d3-force": {
+      "optional": true
+    },
+    "dotparser": {
+      "optional": true
+    },
     "fast-xml-parser": {
       "optional": true
     },
     "zod": {
       "optional": true
     }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "generate-schema": "tsx scripts/generate-json-schema.ts",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm run build && changeset publish"
   }
-}
+}

package/dist/dot-BRtq3e3c.mjs

@@ -1,59 +0,0 @@
-//#region src/formats/dot.ts
-/** Escape a DOT identifier */
-function escapeId(id) {
-	if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(id)) return id;
-	return `"${id.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
-}
-/** Escape a DOT label string */
-function escapeLabel(label) {
-	return label.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
-}
-const DIRECTION_TO_RANKDIR = {
-	down: "TB",
-	up: "BT",
-	right: "LR",
-	left: "RL"
-};
-const SHAPE_TO_DOT = {
-	rectangle: "box",
-	ellipse: "ellipse",
-	circle: "circle",
-	diamond: "diamond",
-	hexagon: "hexagon",
-	cylinder: "cylinder",
-	parallelogram: "parallelogram"
-};
-function toDOT(graph) {
-	const isDirected = graph.type === "directed";
-	const keyword = isDirected ? "digraph" : "graph";
-	const edgeOp = isDirected ? "->" : "--";
-	const lines = [];
-	lines.push(`${keyword} ${escapeId(graph.id)} {`);
-	if (graph.direction) {
-		const rankdir = DIRECTION_TO_RANKDIR[graph.direction] ?? "TB";
-		lines.push(`  rankdir=${rankdir};`);
-	}
-	for (const node of graph.nodes) {
-		const attrs = [];
-		if (node.label) attrs.push(`label="${escapeLabel(node.label)}"`);
-		if (node.shape) {
-			const dotShape = SHAPE_TO_DOT[node.shape] ?? node.shape;
-			attrs.push(`shape=${dotShape}`);
-		}
-		if (node.color) attrs.push(`fillcolor="${escapeLabel(node.color)}" style=filled`);
-		if (attrs.length > 0) lines.push(`  ${escapeId(node.id)} [${attrs.join(", ")}];`);
-		else lines.push(`  ${escapeId(node.id)};`);
-	}
-	for (const edge of graph.edges) {
-		const attrs = [];
-		if (edge.label) attrs.push(`label="${escapeLabel(edge.label)}"`);
-		if (edge.color) attrs.push(`color="${escapeLabel(edge.color)}"`);
-		const attrStr = attrs.length > 0 ? ` [${attrs.join(", ")}]` : "";
-		lines.push(`  ${escapeId(edge.sourceId)} ${edgeOp} ${escapeId(edge.targetId)}${attrStr};`);
-	}
-	lines.push("}");
-	return lines.join("\n");
-}
-
-//#endregion
-export { toDOT as t };

package/dist/dot-HmJeUMsj.d.mts

@@ -1,6 +0,0 @@
-import { c as Graph } from "./types-XV3S5Jnh.mjs";
-
-//#region src/formats/dot.d.ts
-declare function toDOT(graph: Graph): string;
-//#endregion
-export { toDOT as t };

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

@@ -1,2 +0,0 @@
-import { n as toAdjacencyList, t as fromAdjacencyList } from "../adjacency-list-DW-lAUe8.mjs";
-export { fromAdjacencyList, toAdjacencyList };

package/dist/formats/adjacency-list.mjs

@@ -1,3 +0,0 @@
-import { n as toAdjacencyList, t as fromAdjacencyList } from "../adjacency-list-CXpOCibq.mjs";
-
-export { fromAdjacencyList, toAdjacencyList };

package/dist/formats/dot.d.mts

@@ -1,2 +0,0 @@
-import { t as toDOT } from "../dot-HmJeUMsj.mjs";
-export { toDOT };

package/dist/formats/dot.mjs

@@ -1,3 +0,0 @@
-import { t as toDOT } from "../dot-BRtq3e3c.mjs";
-
-export { toDOT };

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

@@ -1,2 +0,0 @@
-import { n as toEdgeList, t as fromEdgeList } from "../edge-list-CJmfoNu2.mjs";
-export { fromEdgeList, toEdgeList };

package/dist/formats/edge-list.mjs

@@ -1,3 +0,0 @@
-import { n as toEdgeList, t as fromEdgeList } from "../edge-list-BRujEnnU.mjs";
-
-export { fromEdgeList, toEdgeList };

package/dist/formats/graphml.d.mts

@@ -1,2 +0,0 @@
-import { n as toGraphML, t as fromGraphML } from "../graphml-CMjPzSfY.mjs";
-export { fromGraphML, toGraphML };

package/dist/formats/graphml.mjs

@@ -1,3 +0,0 @@
-import { n as toGraphML, t as fromGraphML } from "../graphml-CUTNRXqd.mjs";
-
-export { fromGraphML, toGraphML };

package/dist/graphml-CMjPzSfY.d.mts

@@ -1,7 +0,0 @@
-import { c as Graph } from "./types-XV3S5Jnh.mjs";
-
-//#region src/formats/graphml.d.ts
-declare function toGraphML(graph: Graph): string;
-declare function fromGraphML(xml: string): Graph;
-//#endregion
-export { toGraphML as n, fromGraphML as t };