@statelyai/graph 0.3.1 → 0.4.0

package/README.md

@@ -4,17 +4,6 @@ A TypeScript graph library built on plain JSON objects. Supports directed/undire
 
 Made from our experience at [stately.ai](https://stately.ai), where we build visual tools for complex systems.
 
-## Why this library?
-
-Graph file formats (GEXF, GraphML) define how to _store_ graphs. Visualization libraries (Cytoscape.js, D3) define how to _render_ them. Neither gives you a good way to _work with_ them in between.
-
-This library is the computational layer: plain JSON objects in, algorithms and mutations, plain JSON objects out. No classes, no DOM, no rendering engine — just data and functions.
-
-```
-GEXF file → fromGEXF() → Graph → run algorithms, mutate → toCytoscapeJSON() → render
-```
-
-Your `Graph` is a plain object that survives `JSON.stringify`, `structuredClone`, `postMessage`, and `localStorage` without adapters. Format converters are the I/O ports — read from any supported format, do your work, export to whatever your renderer or database expects.
 
 ## Install
 
@@ -126,6 +115,18 @@ const back = cytoscapeConverter.from(cyto);
 const myConverter = createFormatConverter(myToFn, myFromFn);
 ```
 
+## Why this library?
+
+Graph file formats (GEXF, GraphML) define how to _store_ graphs. Visualization libraries (Cytoscape.js, D3) define how to _render_ them. Neither gives you a good way to _work with_ them in between.
+
+This library is the computational layer: plain JSON objects in, algorithms and mutations, plain JSON objects out. No classes, no DOM, no rendering engine; just data and functions.
+
+```
+GEXF file → fromGEXF() → Graph → run algorithms, mutate → toCytoscapeJSON() → render
+```
+
+Your `Graph` is a plain object that survives `JSON.stringify`, `structuredClone`, `postMessage`, and `localStorage` without adapters. Format converters are the I/O ports: read from any supported format, do your work, export to whatever your renderer or database expects.
+
 ## API
 
 ### Graph Creation

package/dist/{algorithms-NWSB2RWj.mjs → algorithms-CnTmuX9t.mjs}

@@ -1,12 +1,14 @@
-import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-eNDrXdDA.mjs";
+import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-DitHphT7.mjs";
 
 //#region src/graph.ts
 function resolveNode(config) {
+	if (!config.id) throw new Error("Node id must be a non-empty string");
+	if (config.parentId === "") throw new Error("Node parentId must be a non-empty string");
 	const node = {
 		type: "node",
 		id: config.id,
-		parentId: config.parentId ?? null,
-		initialNodeId: config.initialNodeId ?? null,
+		...config.parentId !== void 0 && { parentId: config.parentId ?? null },
+		...config.initialNodeId !== void 0 && { initialNodeId: config.initialNodeId ?? null },
 		label: config.label ?? "",
 		data: config.data
 	};
@@ -20,6 +22,9 @@ function resolveNode(config) {
 	return node;
 }
 function resolveEdge(config) {
+	if (!config.id) throw new Error("Edge id must be a non-empty string");
+	if (!config.sourceId) throw new Error("Edge sourceId must be a non-empty string");
+	if (!config.targetId) throw new Error("Edge targetId must be a non-empty string");
 	const edge = {
 		type: "edge",
 		id: config.id,
@@ -251,10 +256,10 @@ function hasEdge(graph, id) {
 * ```
 */
 function addNode(graph, config) {
+	const node = resolveNode(config);
 	const idx = getIndex(graph);
 	if (idx.nodeById.has(config.id)) throw new Error(`Node "${config.id}" already exists`);
-	if (config.parentId != null && !idx.nodeById.has(config.parentId)) throw new Error(`Parent node "${config.parentId}" does not exist`);
-	const node = resolveNode(config);
+	if (config.parentId && !idx.nodeById.has(config.parentId)) throw new Error(`Parent node "${config.parentId}" does not exist`);
 	indexAddNode(idx, node, graph.nodes.push(node) - 1);
 	return node;
 }
@@ -270,11 +275,11 @@ function addNode(graph, config) {
 * ```
 */
 function addEdge(graph, config) {
+	const edge = resolveEdge(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`);
-	const edge = resolveEdge(config);
 	indexAddEdge(idx, edge, graph.edges.push(edge) - 1);
 	return edge;
 }

package/dist/algorithms.d.mts

@@ -1,4 +1,4 @@
-import { C as TraversalOptions, _ as MSTOptions, b as PathOptions, c as Graph, h as GraphPath, p as GraphNode, t as AllPairsShortestPathsOptions, x as SinglePathOptions } from "./types-BDXC1O5b.mjs";
+import { C as TraversalOptions, _ as MSTOptions, b as PathOptions, c as Graph, h as GraphPath, p as GraphNode, t as AllPairsShortestPathsOptions, x as SinglePathOptions } from "./types-Bq_fmLwW.mjs";
 
 //#region src/algorithms.d.ts
 

package/dist/algorithms.mjs

@@ -1,3 +1,3 @@
-import { C as isAcyclic, E as joinPaths, S as hasPath, T as isTree, _ 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, 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 } from "./algorithms-NWSB2RWj.mjs";
+import { C as isAcyclic, E as joinPaths, S as hasPath, T as isTree, _ 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, 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 } from "./algorithms-CnTmuX9t.mjs";
 
 export { 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 };

package/dist/{converter-CchokMDg.mjs → converter-C5DlzzHs.mjs}

@@ -1,5 +1,5 @@
-import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-ITO40kmn.mjs";
-import { n as toEdgeList, t as fromEdgeList } from "./edge-list-CgX6bBIF.mjs";
+import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-Bv4tfiM3.mjs";
+import { n as toEdgeList, t as fromEdgeList } from "./edge-list-R1SUbHwe.mjs";
 
 //#region src/formats/converter/index.ts
 /**

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

@@ -1,4 +1,4 @@
-import { c as Graph } from "../../types-BDXC1O5b.mjs";
+import { c as Graph } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/adjacency-list/index.d.ts
 

package/dist/formats/adjacency-list/index.mjs

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

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/converter/index.d.ts
 

package/dist/formats/converter/index.mjs

@@ -1,3 +1,3 @@
-import { n as createFormatConverter, r as edgeListConverter, t as adjacencyListConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter, r as edgeListConverter, t as adjacencyListConverter } from "../../converter-C5DlzzHs.mjs";
 
 export { adjacencyListConverter, createFormatConverter, edgeListConverter };

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/cytoscape/index.d.ts
 interface CytoscapeNode {

package/dist/formats/cytoscape/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/cytoscape/index.ts
 /**
@@ -22,7 +22,7 @@ function toCytoscapeJSON(graph) {
 	const graphData = {};
 	if (graph.id) graphData.id = graph.id;
 	graphData.type = graph.type;
-	if (graph.initialNodeId !== null) graphData.initialNodeId = graph.initialNodeId;
+	if (graph.initialNodeId) graphData.initialNodeId = graph.initialNodeId;
 	if (graph.data !== void 0) graphData.graphData = graph.data;
 	if (graph.direction) graphData.direction = graph.direction;
 	return {
@@ -30,9 +30,9 @@ function toCytoscapeJSON(graph) {
 		elements: {
 			nodes: graph.nodes.map((n) => {
 				const data = { id: n.id };
-				if (n.parentId !== null) data.parent = n.parentId;
+				if (n.parentId) data.parent = n.parentId;
 				if (n.label) data.label = n.label;
-				if (n.initialNodeId !== null) data.initialNodeId = n.initialNodeId;
+				if (n.initialNodeId) data.initialNodeId = n.initialNodeId;
 				if (n.data !== void 0) data.nodeData = n.data;
 				if (n.width !== void 0) data.width = n.width;
 				if (n.height !== void 0) data.height = n.height;

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/d3/index.d.ts
 interface D3Node {

package/dist/formats/d3/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/d3/index.ts
 /**

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/dot/index.d.ts
 

package/dist/formats/dot/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 import parse from "dotparser";
 
 //#region src/formats/dot/index.ts

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

@@ -1,4 +1,4 @@
-import { c as Graph } from "../../types-BDXC1O5b.mjs";
+import { c as Graph } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/edge-list/index.d.ts
 

package/dist/formats/edge-list/index.mjs

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

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/gexf/index.d.ts
 declare function toGEXF(graph: Graph): string;

package/dist/formats/gexf/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
 
 //#region src/formats/gexf/index.ts
@@ -32,11 +32,11 @@ function toGEXF(graph) {
 	}];
 	const nodes = graph.nodes.map((n) => {
 		const attvalues = [];
-		if (n.parentId !== null) attvalues.push({
+		if (n.parentId) attvalues.push({
 			"@_for": "a_parentId",
 			"@_value": n.parentId
 		});
-		if (n.initialNodeId !== null) attvalues.push({
+		if (n.initialNodeId) attvalues.push({
 			"@_for": "a_initialNodeId",
 			"@_value": n.initialNodeId
 		});
@@ -52,7 +52,7 @@ function toGEXF(graph) {
 			"@_id": n.id,
 			"@_label": n.label || n.id
 		};
-		if (n.parentId !== null) node["@_pid"] = n.parentId;
+		if (n.parentId) node["@_pid"] = n.parentId;
 		if (attvalues.length > 0) node.attvalues = { attvalue: attvalues };
 		if (n.color) {
 			const hex$1 = n.color.replace("#", "");
@@ -91,7 +91,7 @@ function toGEXF(graph) {
 		return edge;
 	});
 	const graphData = [];
-	if (graph.initialNodeId !== null) graphData.push({
+	if (graph.initialNodeId) graphData.push({
 		"@_for": "a_initialNodeId",
 		"@_value": graph.initialNodeId
 	});

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/gml/index.d.ts
 

package/dist/formats/gml/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/gml/index.ts
 /**
@@ -30,7 +30,7 @@ function toGML(graph) {
 	if (graph.id) lines.push(`  id ${gmlString(graph.id)}`);
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
-		const pid = node.parentId;
+		const pid = node.parentId ?? null;
 		if (!childrenMap.has(pid)) childrenMap.set(pid, []);
 		childrenMap.get(pid).push(node);
 	}
@@ -38,7 +38,7 @@ function toGML(graph) {
 		lines.push(`${indent}node [`);
 		lines.push(`${indent}  id ${gmlString(node.id)}`);
 		if (node.label) lines.push(`${indent}  label ${gmlString(node.label)}`);
-		if (node.initialNodeId !== null) lines.push(`${indent}  initialNodeId ${gmlString(node.initialNodeId)}`);
+		if (node.initialNodeId) lines.push(`${indent}  initialNodeId ${gmlString(node.initialNodeId)}`);
 		if (node.data !== void 0) lines.push(`${indent}  data ${gmlString(JSON.stringify(node.data))}`);
 		if (node.shape) lines.push(`${indent}  shape ${gmlString(node.shape)}`);
 		if (node.color) lines.push(`${indent}  color ${gmlString(node.color)}`);

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/graphml/index.d.ts
 declare function toGraphML(graph: Graph): string;

package/dist/formats/graphml/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
 
 //#region src/formats/graphml/index.ts
@@ -72,7 +72,7 @@ function toGraphML(graph) {
 			"@_key": "label",
 			"#text": n.label
 		});
-		if (n.parentId !== null) data.push({
+		if (n.parentId) data.push({
 			"@_key": "parentId",
 			"#text": n.parentId
 		});

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/jgf/index.d.ts
 interface JGFNode {

package/dist/formats/jgf/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/jgf/index.ts
 /**
@@ -20,7 +20,7 @@ import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
 */
 function toJGF(graph) {
 	const metadata = {};
-	if (graph.initialNodeId !== null) metadata.initialNodeId = graph.initialNodeId;
+	if (graph.initialNodeId) metadata.initialNodeId = graph.initialNodeId;
 	if (graph.data !== void 0) metadata.data = graph.data;
 	if (graph.direction) metadata.direction = graph.direction;
 	return { graph: {
@@ -29,8 +29,8 @@ function toJGF(graph) {
 		...Object.keys(metadata).length > 0 && { metadata },
 		nodes: graph.nodes.map((n) => {
 			const meta = {};
-			if (n.parentId !== null) meta.parentId = n.parentId;
-			if (n.initialNodeId !== null) meta.initialNodeId = n.initialNodeId;
+			if (n.parentId) meta.parentId = n.parentId;
+			if (n.initialNodeId) meta.initialNodeId = n.initialNodeId;
 			if (n.data !== void 0) meta.data = n.data;
 			if (n.x !== void 0) meta.x = n.x;
 			if (n.y !== void 0) meta.y = n.y;

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/mermaid/sequence.d.ts
 interface SequenceNodeData {

package/dist/formats/mermaid/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/mermaid/shared.ts
 const MERMAID_TO_DIRECTION = {
@@ -1097,7 +1097,7 @@ function toMermaidFlowchart(graph) {
 	}
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
-		const pid = node.parentId;
+		const pid = node.parentId ?? null;
 		if (!childrenMap.has(pid)) childrenMap.set(pid, []);
 		childrenMap.get(pid).push(node);
 	}
@@ -1304,7 +1304,7 @@ function toMermaidState(graph) {
 	const lines = ["stateDiagram-v2"];
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
-		const pid = node.parentId;
+		const pid = node.parentId ?? null;
 		if (!childrenMap.has(pid)) childrenMap.set(pid, []);
 		childrenMap.get(pid).push(node);
 	}
@@ -1995,7 +1995,7 @@ function toMermaidMindmap(graph) {
 	const lines = ["mindmap"];
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
-		const pid = node.parentId;
+		const pid = node.parentId ?? null;
 		if (!childrenMap.has(pid)) childrenMap.set(pid, []);
 		childrenMap.get(pid).push(node);
 	}
@@ -2198,7 +2198,7 @@ function toMermaidBlock(graph) {
 	if (graph.data?.columns) lines.push(`    columns ${graph.data.columns}`);
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
-		const pid = node.parentId;
+		const pid = node.parentId ?? null;
 		if (!childrenMap.has(pid)) childrenMap.set(pid, []);
 		childrenMap.get(pid).push(node);
 	}

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

@@ -1,4 +1,4 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-BDXC1O5b.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/tgf/index.d.ts
 

package/dist/formats/tgf/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-CchokMDg.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/tgf/index.ts
 /**

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

@@ -0,0 +1,73 @@
+import { D as VisualGraphFormatConverter, T as VisualGraph } from "../../types-Bq_fmLwW.mjs";
+import { EdgeBase, NodeBase } from "@xyflow/system";
+
+//#region src/formats/xyflow/index.d.ts
+/** xyflow Node — re-exported from `@xyflow/system`. */
+type XYFlowNode<TNodeData extends Record<string, unknown> = Record<string, unknown>> = NodeBase<TNodeData>;
+/** xyflow Edge — re-exported from `@xyflow/system`. */
+type XYFlowEdge<TEdgeData extends Record<string, unknown> = Record<string, unknown>> = EdgeBase<TEdgeData>;
+interface XYFlow<TNodeData extends Record<string, unknown> = Record<string, unknown>, TEdgeData extends Record<string, unknown> = Record<string, unknown>> {
+  nodes: XYFlowNode<TNodeData>[];
+  edges: XYFlowEdge<TEdgeData>[];
+}
+/**
+ * Converts a visual graph to xyflow (React Flow / Svelte Flow) format.
+ *
+ * @example
+ * ```ts
+ * import { createVisualGraph } from '@statelyai/graph';
+ * import { toXYFlow } from '@statelyai/graph/formats/xyflow';
+ *
+ * const graph = createVisualGraph({
+ *   nodes: [
+ *     { id: 'a', x: 0, y: 0, width: 100, height: 50 },
+ *     { id: 'b', x: 200, y: 100, width: 100, height: 50 },
+ *   ],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+ * });
+ *
+ * const flow = toXYFlow(graph);
+ * // { nodes: [...], edges: [...] }
+ * ```
+ */
+declare function toXYFlow(graph: VisualGraph): XYFlow;
+/**
+ * Parses an xyflow (React Flow / Svelte Flow) object into a visual graph.
+ *
+ * @example
+ * ```ts
+ * import { fromXYFlow } from '@statelyai/graph/formats/xyflow';
+ *
+ * const graph = fromXYFlow({
+ *   nodes: [
+ *     { id: 'a', position: { x: 0, y: 0 }, data: {} },
+ *     { id: 'b', position: { x: 200, y: 100 }, data: {} },
+ *   ],
+ *   edges: [{ id: 'e0', source: 'a', target: 'b' }],
+ * });
+ * ```
+ */
+declare function fromXYFlow(flow: XYFlow): VisualGraph;
+/**
+ * Bidirectional converter for xyflow (React Flow / Svelte Flow) format.
+ *
+ * @example
+ * ```ts
+ * import { createVisualGraph } from '@statelyai/graph';
+ * import { xyflowConverter } from '@statelyai/graph/formats/xyflow';
+ *
+ * const graph = createVisualGraph({
+ *   nodes: [
+ *     { id: 'a', x: 0, y: 0, width: 100, height: 50 },
+ *     { id: 'b', x: 200, y: 100, width: 100, height: 50 },
+ *   ],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+ * });
+ *
+ * const flow = xyflowConverter.to(graph);
+ * const roundTripped = xyflowConverter.from(flow);
+ * ```
+ */
+declare const xyflowConverter: VisualGraphFormatConverter<XYFlow>;
+//#endregion
+export { XYFlow, XYFlowEdge, XYFlowNode, fromXYFlow, toXYFlow, xyflowConverter };

package/dist/formats/xyflow/index.mjs

@@ -0,0 +1,133 @@
+//#region src/formats/xyflow/index.ts
+/**
+* Converts a visual graph to xyflow (React Flow / Svelte Flow) format.
+*
+* @example
+* ```ts
+* import { createVisualGraph } from '@statelyai/graph';
+* import { toXYFlow } from '@statelyai/graph/formats/xyflow';
+*
+* const graph = createVisualGraph({
+*   nodes: [
+*     { id: 'a', x: 0, y: 0, width: 100, height: 50 },
+*     { id: 'b', x: 200, y: 100, width: 100, height: 50 },
+*   ],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const flow = toXYFlow(graph);
+* // { nodes: [...], edges: [...] }
+* ```
+*/
+function toXYFlow(graph) {
+	return {
+		nodes: graph.nodes.map((n) => {
+			const node = {
+				id: n.id,
+				position: {
+					x: n.x,
+					y: n.y
+				},
+				data: n.data ?? {}
+			};
+			if (n.parentId) node.parentId = n.parentId;
+			if (n.shape) node.type = n.shape;
+			if (n.width) node.width = n.width;
+			if (n.height) node.height = n.height;
+			return node;
+		}),
+		edges: graph.edges.map((e) => {
+			const edge = {
+				id: e.id,
+				source: e.sourceId,
+				target: e.targetId
+			};
+			if (e.data !== void 0) edge.data = e.data;
+			if (e.label) edge.data = {
+				...edge.data,
+				label: e.label
+			};
+			return edge;
+		})
+	};
+}
+/**
+* Parses an xyflow (React Flow / Svelte Flow) object into a visual graph.
+*
+* @example
+* ```ts
+* import { fromXYFlow } from '@statelyai/graph/formats/xyflow';
+*
+* const graph = fromXYFlow({
+*   nodes: [
+*     { id: 'a', position: { x: 0, y: 0 }, data: {} },
+*     { id: 'b', position: { x: 200, y: 100 }, data: {} },
+*   ],
+*   edges: [{ id: 'e0', source: 'a', target: 'b' }],
+* });
+* ```
+*/
+function fromXYFlow(flow) {
+	if (!flow || typeof flow !== "object") throw new Error("XYFlow: expected an object");
+	if (!Array.isArray(flow.nodes)) throw new Error("XYFlow: \"nodes\" must be an array");
+	if (!Array.isArray(flow.edges)) throw new Error("XYFlow: \"edges\" must be an array");
+	return {
+		id: "",
+		type: "directed",
+		initialNodeId: null,
+		data: void 0,
+		direction: "down",
+		nodes: flow.nodes.map((n) => ({
+			type: "node",
+			id: n.id,
+			parentId: n.parentId ?? null,
+			initialNodeId: null,
+			label: "",
+			data: n.data,
+			x: n.position.x,
+			y: n.position.y,
+			width: n.measured?.width ?? n.width ?? n.initialWidth ?? 0,
+			height: n.measured?.height ?? n.height ?? n.initialHeight ?? 0,
+			...n.type && { shape: n.type }
+		})),
+		edges: flow.edges.map((e, i) => ({
+			type: "edge",
+			id: e.id ?? `e${i}`,
+			sourceId: e.source,
+			targetId: e.target,
+			label: e.data?.label?.toString() ?? "",
+			data: e.data,
+			x: 0,
+			y: 0,
+			width: 0,
+			height: 0
+		}))
+	};
+}
+/**
+* Bidirectional converter for xyflow (React Flow / Svelte Flow) format.
+*
+* @example
+* ```ts
+* import { createVisualGraph } from '@statelyai/graph';
+* import { xyflowConverter } from '@statelyai/graph/formats/xyflow';
+*
+* const graph = createVisualGraph({
+*   nodes: [
+*     { id: 'a', x: 0, y: 0, width: 100, height: 50 },
+*     { id: 'b', x: 200, y: 100, width: 100, height: 50 },
+*   ],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const flow = xyflowConverter.to(graph);
+* const roundTripped = xyflowConverter.from(flow);
+* ```
+*/
+const xyflowConverter = {
+	to: toXYFlow,
+	from: fromXYFlow
+};
+
+//#endregion
+export { fromXYFlow, toXYFlow, xyflowConverter };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-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-BDXC1O5b.mjs";
+import { C as TraversalOptions, E as VisualGraphConfig, O as VisualNode, 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-Bq_fmLwW.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";

package/dist/index.mjs

@@ -1,13 +1,13 @@
-import { o as invalidateIndex, t as getIndex } from "./indexing-eNDrXdDA.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-NWSB2RWj.mjs";
+import { o as invalidateIndex, t as getIndex } from "./indexing-DitHphT7.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-CnTmuX9t.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-CchokMDg.mjs";
+import { n as createFormatConverter } from "./converter-C5DlzzHs.mjs";
 
 //#region src/diff.ts
 function nodeToConfig(node) {
 	const config = { id: node.id };
-	if (node.parentId !== null) config.parentId = node.parentId;
-	if (node.initialNodeId !== null) config.initialNodeId = node.initialNodeId;
+	if (node.parentId) config.parentId = node.parentId;
+	if (node.initialNodeId) config.initialNodeId = node.initialNodeId;
 	if (node.label !== "") config.label = node.label;
 	if (node.data !== void 0) config.data = node.data;
 	if (node.x !== void 0) config.x = node.x;

package/dist/{indexing-eNDrXdDA.mjs → indexing-DitHphT7.mjs}

@@ -53,7 +53,7 @@ function buildIndex(graph) {
 		nodeById.set(n.id, i);
 		outEdges.set(n.id, []);
 		inEdges.set(n.id, []);
-		const parent = n.parentId;
+		const parent = n.parentId ?? null;
 		if (!childNodes.has(parent)) childNodes.set(parent, []);
 		childNodes.get(parent).push(n.id);
 	}
@@ -77,7 +77,7 @@ function indexAddNode(idx, node, arrayIndex) {
 	idx.nodeById.set(node.id, arrayIndex);
 	idx.outEdges.set(node.id, []);
 	idx.inEdges.set(node.id, []);
-	const parent = node.parentId;
+	const parent = node.parentId ?? null;
 	if (!idx.childNodes.has(parent)) idx.childNodes.set(parent, []);
 	idx.childNodes.get(parent).push(node.id);
 	idx.nodeCount++;
@@ -90,13 +90,14 @@ function indexAddEdge(idx, edge, arrayIndex) {
 }
 /** Update childNodes index when a node's parentId changes. */
 function indexReparentNode(idx, nodeId, oldParentId, newParentId) {
-	const oldSiblings = idx.childNodes.get(oldParentId);
+	const oldSiblings = idx.childNodes.get(oldParentId ?? null);
 	if (oldSiblings) {
 		const pos = oldSiblings.indexOf(nodeId);
 		if (pos !== -1) oldSiblings.splice(pos, 1);
 	}
-	if (!idx.childNodes.has(newParentId)) idx.childNodes.set(newParentId, []);
-	idx.childNodes.get(newParentId).push(nodeId);
+	const np = newParentId ?? null;
+	if (!idx.childNodes.has(np)) idx.childNodes.set(np, []);
+	idx.childNodes.get(np).push(nodeId);
 }
 /** Update adjacency lists when an edge's sourceId/targetId changes. */
 function indexUpdateEdgeEndpoints(idx, edgeId, oldSourceId, oldTargetId, newSourceId, newTargetId) {

package/dist/queries.d.mts

@@ -1,4 +1,4 @@
-import { c as Graph, d as GraphEdge, p as GraphNode } from "./types-BDXC1O5b.mjs";
+import { c as Graph, d as GraphEdge, p as GraphNode } from "./types-Bq_fmLwW.mjs";
 
 //#region src/queries.d.ts
 
@@ -238,7 +238,7 @@ declare function getAncestors<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[
  */
 declare function getDescendants<N>(graph: Graph<N>, nodeId: string): GraphNode<N>[];
 /**
- * Returns all root nodes (nodes with no parent, i.e. `parentId === null`).
+ * Returns all root nodes (nodes with no parent).
  *
  * @example
  * ```ts

package/dist/queries.mjs

@@ -1,4 +1,4 @@
-import { t as getIndex } from "./indexing-eNDrXdDA.mjs";
+import { t as getIndex } from "./indexing-DitHphT7.mjs";
 
 //#region src/queries.ts
 /**
@@ -293,7 +293,7 @@ function getParent(graph, nodeId) {
 	const ni = idx.nodeById.get(nodeId);
 	if (ni === void 0) return void 0;
 	const node = graph.nodes[ni];
-	if (node.parentId === null) return void 0;
+	if (!node.parentId) return void 0;
 	const pi = idx.nodeById.get(node.parentId);
 	return pi !== void 0 ? graph.nodes[pi] : void 0;
 }
@@ -319,7 +319,7 @@ function getAncestors(graph, nodeId) {
 	let ni = idx.nodeById.get(nodeId);
 	if (ni === void 0) return result;
 	let current = graph.nodes[ni];
-	while (current && current.parentId !== null) {
+	while (current && current.parentId) {
 		const pi = idx.nodeById.get(current.parentId);
 		if (pi === void 0) break;
 		const p = graph.nodes[pi];
@@ -361,7 +361,7 @@ function getDescendants(graph, nodeId) {
 	return result;
 }
 /**
-* Returns all root nodes (nodes with no parent, i.e. `parentId === null`).
+* Returns all root nodes (nodes with no parent).
 *
 * @example
 * ```ts
@@ -440,7 +440,7 @@ function getDepth(graph, nodeId) {
 	let ni = idx.nodeById.get(nodeId);
 	if (ni === void 0) return -1;
 	let current = graph.nodes[ni];
-	while (current.parentId !== null) {
+	while (current.parentId) {
 		d++;
 		const pi = idx.nodeById.get(current.parentId);
 		if (pi === void 0) break;
@@ -470,7 +470,7 @@ function getSiblings(graph, nodeId) {
 	const ni = idx.nodeById.get(nodeId);
 	if (ni === void 0) return [];
 	const node = graph.nodes[ni];
-	return (idx.childNodes.get(node.parentId) ?? []).filter((id) => id !== nodeId).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
+	return (idx.childNodes.get(node.parentId ?? null) ?? []).filter((id) => id !== nodeId).map((id) => graph.nodes[idx.nodeById.get(id)]).filter(Boolean);
 }
 /**
 * Least Common Ancestor -- deepest proper ancestor of all given nodes.
@@ -500,7 +500,7 @@ function getLCA(graph, ...nodeIds) {
 		let ni$1 = idx.nodeById.get(id);
 		if (ni$1 === void 0) return result;
 		let current = graph.nodes[ni$1];
-		while (current.parentId !== null) {
+		while (current.parentId) {
 			result.push(current.parentId);
 			const pi = idx.nodeById.get(current.parentId);
 			if (pi === void 0) break;
@@ -564,7 +564,7 @@ function getRelativeDistanceMap(graph, parentId) {
 	let sourceId = null;
 	if (parentId !== null) {
 		const pi = idx.nodeById.get(parentId);
-		if (pi !== void 0) sourceId = graph.nodes[pi].initialNodeId;
+		if (pi !== void 0) sourceId = graph.nodes[pi].initialNodeId ?? null;
 	} else sourceId = graph.initialNodeId;
 	if (!sourceId) return {};
 	const siblingSet = new Set(idx.childNodes.get(parentId) ?? []);
@@ -637,7 +637,7 @@ 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];
+	return getRelativeDistanceMap(graph, node.parentId ?? null)[nodeId];
 }
 /**
 * Nodes with no incoming edges (inDegree 0).

package/dist/{types-BDXC1O5b.d.mts → types-Bq_fmLwW.d.mts}

@@ -67,8 +67,8 @@ interface Graph<TNodeData = any, TEdgeData = any, TGraphData = any> {
 interface GraphNode<TNodeData = any> {
   type: 'node';
   id: string;
-  parentId: string | null;
-  initialNodeId: string | null;
+  parentId?: string | null;
+  initialNodeId?: string | null;
   label: string;
   data: TNodeData;
   x?: number;
@@ -234,6 +234,17 @@ interface GraphFormatConverter<TSerial> {
   /** Convert from the serialized format to a Graph. */
   from(input: TSerial): Graph;
 }
+/**
+ * A bidirectional converter between `VisualGraph` and a serialized format.
+ *
+ * Use this for formats that carry position/size data (e.g. xyflow, cytoscape).
+ */
+interface VisualGraphFormatConverter<TSerial> {
+  /** Convert a VisualGraph to the serialized format. */
+  to(graph: VisualGraph): TSerial;
+  /** Convert from the serialized format to a VisualGraph. */
+  from(input: TSerial): VisualGraph;
+}
 interface TransitionOptions<TState, TEvent> {
   /** Initial state to begin BFS exploration from. */
   initialState: TState;
@@ -251,4 +262,4 @@ interface TransitionOptions<TState, TEvent> {
   id?: string;
 }
 //#endregion
-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 };
+export { TraversalOptions as C, VisualGraphFormatConverter as D, VisualGraphConfig as E, VisualNode as O, 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.3.1",
+  "version": "0.4.0",
   "description": "A TypeScript-first graph library with plain JSON-serializable objects",
   "author": "David Khourshid <david@stately.ai>",
   "license": "MIT",
@@ -36,6 +36,7 @@
     "./jgf": "./dist/formats/jgf/index.mjs",
     "./mermaid": "./dist/formats/mermaid/index.mjs",
     "./tgf": "./dist/formats/tgf/index.mjs",
+    "./xyflow": "./dist/formats/xyflow/index.mjs",
     "./queries": "./dist/queries.mjs",
     "./schemas": "./dist/schemas.mjs",
     "./package.json": "./package.json"
@@ -53,6 +54,7 @@
     "@types/d3-array": "^3.2.2",
     "@types/d3-force": "^3.0.10",
     "@types/node": "^25.0.3",
+    "@xyflow/system": "^0.0.75",
     "bumpp": "^10.3.2",
     "cytoscape": "^3.33.1",
     "d3-array": "^3.2.4",