@statelyai/graph 0.1.0 → 0.3.0

package/README.md

@@ -4,6 +4,18 @@ 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
 
 ```bash
@@ -77,22 +89,41 @@ const diagram = createVisualGraph({
 });
 ```
 
-### Serialization
+### Format Conversion
 
 ```ts
-import { toDOT, toGraphML, toAdjacencyList, toEdgeList } from '@statelyai/graph';
+import { toCytoscapeJSON } from '@statelyai/graph/cytoscape';
+import { fromJGF } from '@statelyai/graph/jgf';
+import { toD3Graph } from '@statelyai/graph/d3';
+import { toDOT } from '@statelyai/graph/dot';
+import { toGraphML } from '@statelyai/graph/graphml';
+import { fromGEXF } from '@statelyai/graph/gexf';
+
+// Export to web visualization libraries
+const cytoData = toCytoscapeJSON(graph); // Cytoscape.js JSON (compound graphs preserved)
+const d3Data = toD3Graph(graph);         // D3.js { nodes, links }
+
+// Export to text formats
+const dot = toDOT(graph);               // Graphviz DOT
+const xml = toGraphML(graph);            // GraphML XML
+
+// Import from any format
+const g1 = fromJGF(jsonGraphData);       // JSON Graph Format
+const g2 = fromGEXF(gexfXmlString);      // GEXF (Gephi)
+```
 
-console.log(toDOT(graph));
-// Logs a Graphviz DOT string
+Each bidirectional format also has a converter object for a unified interface:
 
-console.log(toGraphML(graph));
-// Logs a GraphML XML string
+```ts
+import { createFormatConverter } from '@statelyai/graph';
+import { cytoscapeConverter } from '@statelyai/graph/cytoscape';
 
-console.log(toAdjacencyList(graph));
-// Logs an adjacency object, e.g. { a: ['b'], b: ['c'] }
+// Use a built-in converter
+const cyto = cytoscapeConverter.to(graph);
+const back = cytoscapeConverter.from(cyto);
 
-console.log(toEdgeList(graph));
-// Logs an array of [sourceId, targetId] pairs, e.g. [['a', 'b'], ['b', 'c']]
+// Create your own
+const myConverter = createFormatConverter(myToFn, myFromFn);
 ```
 
 ## API
@@ -176,15 +207,34 @@ console.log(toEdgeList(graph));
 
 Generator variants: `genShortestPaths`, `genSimplePaths`, `genCycles`, `genPreorders`, `genPostorders`.
 
-### Transforms & Formats
+### Transforms
 
 | Function | Description |
 |----------|-------------|
 | `flatten(graph)` | Decompose hierarchy into flat leaf-node graph |
-| `toDOT` / `toGraphML` | Export to Graphviz DOT / GraphML |
-| `fromGraphML` | Import from GraphML |
-| `toAdjacencyList` / `fromAdjacencyList` | Adjacency list conversion |
-| `toEdgeList` / `fromEdgeList` | Edge list conversion |
+
+### Formats
+
+Import format converters from subpaths (for example, `@statelyai/graph/dot` or `@statelyai/graph/mermaid`).
+
+| Format | Export | Import | Compound? | Notes |
+|--------|--------|--------|-----------|-------|
+| **Cytoscape.js JSON** | `toCytoscapeJSON` | `fromCytoscapeJSON` | Yes | `parent` maps to `parentId` |
+| **D3.js JSON** | `toD3Graph` | `fromD3Graph` | No | `{ nodes, links }` for force layouts |
+| **JSON Graph Format** | `toJGF` | `fromJGF` | Yes | Formal spec, metadata-extensible |
+| **GEXF** | `toGEXF` | `fromGEXF` | Yes | Gephi native, `pid` hierarchy, viz module |
+| **GraphML** | `toGraphML` | `fromGraphML` | Yes | XML standard, requires `fast-xml-parser` |
+| **GML** | `toGML` | `fromGML` | Yes | Nested node blocks for hierarchy |
+| **TGF** | `toTGF` | `fromTGF` | No | Minimal (id + label only) |
+| **DOT** | `toDOT` | `fromDOT` | Yes (subgraphs) | Graphviz DOT (`dotparser` peer dep) |
+| **Mermaid** | `toMermaid*` | `fromMermaid*` | Varies by diagram | Sequence, flowchart, state, class, ER, mindmap, block |
+| **Adjacency list** | `toAdjacencyList` | `fromAdjacencyList` | No | `Record<string, string[]>` |
+| **Edge list** | `toEdgeList` | `fromEdgeList` | No | `[source, target][]` |
+
+Optional peer deps by format:
+- `@statelyai/graph/gexf` and `@statelyai/graph/graphml` use `fast-xml-parser`
+- `@statelyai/graph/dot` uses `dotparser`
+- Other formats are dependency-free
 
 ## License
 

package/dist/{adjacency-list-CXpOCibq.mjs → adjacency-list-A4_Eiwj3.mjs}

@@ -1,4 +1,4 @@
-//#region src/formats/adjacency-list.ts
+//#region src/formats/adjacency-list/index.ts
 function toAdjacencyList(graph) {
 	const adj = {};
 	for (const node of graph.nodes) adj[node.id] = [];

package/dist/{algorithms-R35X6ro4.mjs → algorithms-DBU7nmIV.mjs}

@@ -1,4 +1,4 @@
-import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-BHg1VhqN.mjs";
+import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-BFFVMnjF.mjs";
 
 //#region src/graph.ts
 function resolveNode(config) {
@@ -73,6 +73,72 @@ function createVisualGraph(config) {
 		}))
 	};
 }
+/**
+* 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.
+*/
+function createGraphFromTransition(transition, options) {
+	const serializeState = options.serializeState ?? JSON.stringify;
+	const serializeEvent = options.serializeEvent ?? JSON.stringify;
+	const limit = options.limit ?? Infinity;
+	const getEvents = typeof options.events === "function" ? options.events : () => options.events;
+	const nodes = [];
+	const edges = [];
+	const visited = /* @__PURE__ */ new Set();
+	const edgeSet = /* @__PURE__ */ new Set();
+	const queue = [options.initialState];
+	const initialStateId = serializeState(options.initialState);
+	visited.add(initialStateId);
+	nodes.push({
+		id: initialStateId,
+		label: initialStateId,
+		data: options.initialState
+	});
+	let iterations = 0;
+	while (queue.length > 0) {
+		const state = queue.shift();
+		const stateId = serializeState(state);
+		if (++iterations > limit) throw new Error("Traversal limit exceeded");
+		if (options.stopWhen?.(state)) continue;
+		const events = getEvents(state);
+		for (const event of events) {
+			const nextState = transition(state, event);
+			const nextStateId = serializeState(nextState);
+			const eventStr = serializeEvent(event);
+			if (!visited.has(nextStateId)) {
+				visited.add(nextStateId);
+				nodes.push({
+					id: nextStateId,
+					label: nextStateId,
+					data: nextState
+				});
+				queue.push(nextState);
+			}
+			const edgeKey = `${stateId}|${eventStr}|${nextStateId}`;
+			if (!edgeSet.has(edgeKey)) {
+				edgeSet.add(edgeKey);
+				edges.push({
+					id: edgeKey,
+					sourceId: stateId,
+					targetId: nextStateId,
+					label: eventStr,
+					data: event
+				});
+			}
+		}
+	}
+	return createGraph({
+		id: options.id ?? "",
+		type: "directed",
+		initialNodeId: initialStateId,
+		nodes,
+		edges
+	});
+}
 /** Get a node by id, or `undefined` if not found. */
 function getNode(graph, id) {
 	const arrayIdx = getIndex(graph).nodeById.get(id);
@@ -1192,6 +1258,21 @@ function fwReconstruct(graph, prev, idxOf, nodeIds, sourceNode, sourceIdx, targe
 	}
 	return results;
 }
+/**
+* Joins two paths end-to-end. The last node of the head path must equal
+* the source of the tail path (the overlap node).
+*
+* Steps are concatenated: head.steps ++ tail.steps (tail already starts
+* from the overlap node, so no slicing is needed).
+*/
+function joinPaths(headPath, tailPath) {
+	const headEnd = headPath.steps.length > 0 ? headPath.steps[headPath.steps.length - 1].node : headPath.source;
+	if (headEnd.id !== tailPath.source.id) throw new Error(`Paths cannot be joined: head path ends at "${headEnd.id}" but tail path starts at "${tailPath.source.id}"`);
+	return {
+		source: headPath.source,
+		steps: [...headPath.steps, ...tailPath.steps]
+	};
+}
 
 //#endregion
-export { createGraph as A, updateEntities as B, isAcyclic as C, addEdge as D, GraphInstance as E, getEdge as F, getNode as I, hasEdge as L, deleteEdge as M, deleteEntities as N, addEntities as O, deleteNode as P, hasNode as R, hasPath as S, isTree as T, updateNode as V, getShortestPaths as _, genPreorders as a, getStronglyConnectedComponents as b, getAllPairsShortestPaths as c, getMinimumSpanningTree as d, getPostorder as f, getShortestPath as g, getPreorders as h, genPostorders as i, createVisualGraph as j, addNode as k, getConnectedComponents as l, getPreorder as m, dfs as n, genShortestPaths as o, getPostorders as p, genCycles as r, genSimplePaths as s, bfs as t, getCycles as u, getSimplePath as v, isConnected as w, getTopologicalSort as x, getSimplePaths as y, updateEdge as z };
+export { addNode as A, hasNode as B, isAcyclic as C, GraphInstance as D, joinPaths as E, deleteEntities as F, updateEntities as H, deleteNode as I, getEdge as L, createGraphFromTransition as M, createVisualGraph as N, addEdge as O, deleteEdge as P, getNode as R, hasPath as S, isTree as T, updateNode as U, updateEdge as V, getShortestPaths as _, genPreorders as a, getStronglyConnectedComponents as b, getAllPairsShortestPaths as c, getMinimumSpanningTree as d, getPostorder as f, getShortestPath as g, getPreorders as h, genPostorders as i, createGraph as j, addEntities as k, getConnectedComponents as l, getPreorder as m, dfs as n, genShortestPaths as o, getPostorders as p, genCycles as r, genSimplePaths as s, bfs as t, getCycles as u, getSimplePath as v, isConnected as w, getTopologicalSort as x, getSimplePaths as y, hasEdge as z };

package/dist/algorithms.d.mts

@@ -1,4 +1,4 @@
-import { b as SinglePathOptions, c as Graph, f as GraphNode, g as MSTOptions, m as GraphPath, t as AllPairsShortestPathsOptions, x as TraversalOptions, y as PathOptions } from "./types-XV3S5Jnh.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-B6Tpeerk.mjs";
 
 //#region src/algorithms.d.ts
 declare function bfs<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;
@@ -78,5 +78,13 @@ declare function getMinimumSpanningTree<N, E>(graph: Graph<N, E>, opts?: MSTOpti
  * Algorithm 'floyd-warshall': classic O(V³) dynamic programming.
  */
 declare function getAllPairsShortestPaths<N, E>(graph: Graph<N, E>, opts?: AllPairsShortestPathsOptions<E>): GraphPath<N, E>[];
+/**
+ * Joins two paths end-to-end. The last node of the head path must equal
+ * the source of the tail path (the overlap node).
+ *
+ * Steps are concatenated: head.steps ++ tail.steps (tail already starts
+ * from the overlap node, so no slicing is needed).
+ */
+declare function joinPaths<N, E>(headPath: GraphPath<N, E>, tailPath: GraphPath<N, E>): GraphPath<N, E>;
 //#endregion
-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 };
+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/algorithms.mjs

@@ -1,3 +1,3 @@
-import { C as isAcyclic, 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-R35X6ro4.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-DBU7nmIV.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 };
+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-DnbeyE_p.mjs

@@ -0,0 +1,33 @@
+import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-A4_Eiwj3.mjs";
+import { n as toEdgeList, t as fromEdgeList } from "./edge-list-DuHMz8hf.mjs";
+
+//#region src/formats/converter/index.ts
+/**
+* Create a `GraphFormatConverter` from a pair of `to`/`from` functions.
+*
+* @example
+* ```ts
+* import { createFormatConverter } from '@statelyai/graph';
+*
+* const yamlConverter = createFormatConverter(
+*   (graph) => toYAML(graph),
+*   (yaml) => fromYAML(yaml),
+* );
+*
+* const yaml = yamlConverter.to(graph);
+* const graph = yamlConverter.from(yaml);
+* ```
+*/
+function createFormatConverter(to, from) {
+	return {
+		to,
+		from
+	};
+}
+/** Bidirectional converter for adjacency-list format (`Record<string, string[]>`). */
+const adjacencyListConverter = createFormatConverter(toAdjacencyList, fromAdjacencyList);
+/** Bidirectional converter for edge-list format (`[source, target][]`). */
+const edgeListConverter = createFormatConverter(toEdgeList, fromEdgeList);
+
+//#endregion
+export { createFormatConverter as n, edgeListConverter as r, adjacencyListConverter as t };

package/dist/{edge-list-BRujEnnU.mjs → edge-list-DuHMz8hf.mjs}

@@ -1,4 +1,4 @@
-//#region src/formats/edge-list.ts
+//#region src/formats/edge-list/index.ts
 function toEdgeList(graph) {
 	return graph.edges.map((e) => [e.sourceId, e.targetId]);
 }

package/dist/{adjacency-list-DW-lAUe8.d.mts → formats/adjacency-list/index.d.mts}

@@ -1,10 +1,10 @@
-import { c as Graph } from "./types-XV3S5Jnh.mjs";
+import { c as Graph } from "../../types-B6Tpeerk.mjs";
 
-//#region src/formats/adjacency-list.d.ts
+//#region src/formats/adjacency-list/index.d.ts
 declare function toAdjacencyList(graph: Graph): Record<string, string[]>;
 declare function fromAdjacencyList(adj: Record<string, string[]>, options?: {
   directed?: boolean;
   id?: string;
 }): Graph;
 //#endregion
-export { toAdjacencyList as n, fromAdjacencyList as t };
+export { fromAdjacencyList, toAdjacencyList };

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

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

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

@@ -0,0 +1,27 @@
+import { c as Graph, f as GraphFormatConverter } from "../../types-B6Tpeerk.mjs";
+
+//#region src/formats/converter/index.d.ts
+
+/**
+ * Create a `GraphFormatConverter` from a pair of `to`/`from` functions.
+ *
+ * @example
+ * ```ts
+ * import { createFormatConverter } from '@statelyai/graph';
+ *
+ * const yamlConverter = createFormatConverter(
+ *   (graph) => toYAML(graph),
+ *   (yaml) => fromYAML(yaml),
+ * );
+ *
+ * const yaml = yamlConverter.to(graph);
+ * const graph = yamlConverter.from(yaml);
+ * ```
+ */
+declare function createFormatConverter<TSerial>(to: (graph: Graph) => TSerial, from: (input: TSerial) => Graph): GraphFormatConverter<TSerial>;
+/** Bidirectional converter for adjacency-list format (`Record<string, string[]>`). */
+declare const adjacencyListConverter: GraphFormatConverter<Record<string, string[]>>;
+/** Bidirectional converter for edge-list format (`[source, target][]`). */
+declare const edgeListConverter: GraphFormatConverter<[string, string][]>;
+//#endregion
+export { adjacencyListConverter, createFormatConverter, edgeListConverter };

package/dist/formats/converter/index.mjs

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

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

@@ -0,0 +1,35 @@
+import { c as Graph, f as GraphFormatConverter } from "../../types-B6Tpeerk.mjs";
+
+//#region src/formats/cytoscape/index.d.ts
+interface CytoscapeNode {
+  data: {
+    id: string;
+    parent?: string;
+    [key: string]: any;
+  };
+  position?: {
+    x: number;
+    y: number;
+  };
+}
+interface CytoscapeEdge {
+  data: {
+    id: string;
+    source: string;
+    target: string;
+    [key: string]: any;
+  };
+}
+interface CytoscapeJSON {
+  data?: Record<string, any>;
+  elements: {
+    nodes: CytoscapeNode[];
+    edges: CytoscapeEdge[];
+  };
+}
+declare function toCytoscapeJSON(graph: Graph): CytoscapeJSON;
+declare function fromCytoscapeJSON(cyto: CytoscapeJSON): Graph;
+/** Bidirectional converter for Cytoscape.js JSON format. */
+declare const cytoscapeConverter: GraphFormatConverter<CytoscapeJSON>;
+//#endregion
+export { CytoscapeEdge, CytoscapeJSON, CytoscapeNode, cytoscapeConverter, fromCytoscapeJSON, toCytoscapeJSON };

package/dist/formats/cytoscape/index.mjs

@@ -0,0 +1,87 @@
+import { n as createFormatConverter } from "../../converter-DnbeyE_p.mjs";
+
+//#region src/formats/cytoscape/index.ts
+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.data !== void 0) graphData.graphData = graph.data;
+	if (graph.direction) graphData.direction = graph.direction;
+	return {
+		...Object.keys(graphData).length > 0 && { data: graphData },
+		elements: {
+			nodes: graph.nodes.map((n) => {
+				const data = { id: n.id };
+				if (n.parentId !== null) data.parent = n.parentId;
+				if (n.label) data.label = n.label;
+				if (n.initialNodeId !== null) 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;
+				if (n.shape) data.shape = n.shape;
+				if (n.color) data.color = n.color;
+				const node = { data };
+				if (n.x !== void 0 && n.y !== void 0) node.position = {
+					x: n.x,
+					y: n.y
+				};
+				return node;
+			}),
+			edges: graph.edges.map((e) => {
+				const data = {
+					id: e.id,
+					source: e.sourceId,
+					target: e.targetId
+				};
+				if (e.label) data.label = e.label;
+				if (e.data !== void 0) data.edgeData = e.data;
+				if (e.color) data.color = e.color;
+				return { data };
+			})
+		}
+	};
+}
+function fromCytoscapeJSON(cyto) {
+	if (!cyto || typeof cyto !== "object") throw new Error("Cytoscape: expected an object");
+	if (!cyto.elements || typeof cyto.elements !== "object") throw new Error("Cytoscape: missing \"elements\" property");
+	if (!Array.isArray(cyto.elements.nodes)) throw new Error("Cytoscape: \"elements.nodes\" must be an array");
+	if (!Array.isArray(cyto.elements.edges)) throw new Error("Cytoscape: \"elements.edges\" must be an array");
+	return {
+		id: cyto.data?.id ?? "",
+		type: cyto.data?.type === "undirected" ? "undirected" : "directed",
+		initialNodeId: cyto.data?.initialNodeId ?? null,
+		data: cyto.data?.graphData,
+		...cyto.data?.direction && { direction: cyto.data.direction },
+		nodes: cyto.elements.nodes.map((n) => ({
+			type: "node",
+			id: n.data.id,
+			parentId: n.data.parent ?? null,
+			initialNodeId: n.data.initialNodeId ?? null,
+			label: n.data.label ?? "",
+			data: n.data.nodeData,
+			...n.position && {
+				x: n.position.x,
+				y: n.position.y
+			},
+			...n.data.width !== void 0 && { width: n.data.width },
+			...n.data.height !== void 0 && { height: n.data.height },
+			...n.data.shape && { shape: n.data.shape },
+			...n.data.color && { color: n.data.color }
+		})),
+		edges: cyto.elements.edges.map((e, i) => ({
+			type: "edge",
+			id: e.data.id ?? `e${i}`,
+			sourceId: e.data.source,
+			targetId: e.data.target,
+			label: e.data.label ?? "",
+			data: e.data.edgeData,
+			...e.data.color && { color: e.data.color }
+		}))
+	};
+}
+/** Bidirectional converter for Cytoscape.js JSON format. */
+const cytoscapeConverter = createFormatConverter(toCytoscapeJSON, fromCytoscapeJSON);
+
+//#endregion
+export { cytoscapeConverter, fromCytoscapeJSON, toCytoscapeJSON };

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

@@ -0,0 +1,22 @@
+import { c as Graph, f as GraphFormatConverter } from "../../types-B6Tpeerk.mjs";
+
+//#region src/formats/d3/index.d.ts
+interface D3Node {
+  id: string;
+  [key: string]: any;
+}
+interface D3Link {
+  source: string;
+  target: string;
+  [key: string]: any;
+}
+interface D3Graph {
+  nodes: D3Node[];
+  links: D3Link[];
+}
+declare function toD3Graph(graph: Graph): D3Graph;
+declare function fromD3Graph(d3: D3Graph): Graph;
+/** Bidirectional converter for D3.js force-directed JSON format. */
+declare const d3Converter: GraphFormatConverter<D3Graph>;
+//#endregion
+export { D3Graph, D3Link, D3Node, d3Converter, fromD3Graph, toD3Graph };

package/dist/formats/d3/index.mjs

@@ -0,0 +1,65 @@
+import { n as createFormatConverter } from "../../converter-DnbeyE_p.mjs";
+
+//#region src/formats/d3/index.ts
+function toD3Graph(graph) {
+	return {
+		nodes: graph.nodes.map((n) => {
+			const node = { id: n.id };
+			if (n.label) node.label = n.label;
+			if (n.data !== void 0) node.data = n.data;
+			if (n.x !== void 0) node.x = n.x;
+			if (n.y !== void 0) node.y = n.y;
+			if (n.color) node.color = n.color;
+			if (n.shape) node.shape = n.shape;
+			return node;
+		}),
+		links: graph.edges.map((e) => {
+			const link = {
+				source: e.sourceId,
+				target: e.targetId
+			};
+			if (e.id) link.id = e.id;
+			if (e.label) link.label = e.label;
+			if (e.data !== void 0) link.data = e.data;
+			if (e.color) link.color = e.color;
+			return link;
+		})
+	};
+}
+function fromD3Graph(d3) {
+	if (!d3 || typeof d3 !== "object") throw new Error("D3: expected an object");
+	if (!Array.isArray(d3.nodes)) throw new Error("D3: \"nodes\" must be an array");
+	if (!Array.isArray(d3.links)) throw new Error("D3: \"links\" must be an array");
+	return {
+		id: "",
+		type: "directed",
+		initialNodeId: null,
+		data: void 0,
+		nodes: d3.nodes.map((n) => ({
+			type: "node",
+			id: n.id,
+			parentId: null,
+			initialNodeId: null,
+			label: n.label ?? "",
+			data: n.data,
+			...n.x !== void 0 && { x: n.x },
+			...n.y !== void 0 && { y: n.y },
+			...n.color && { color: n.color },
+			...n.shape && { shape: n.shape }
+		})),
+		edges: d3.links.map((l, i) => ({
+			type: "edge",
+			id: l.id ?? `e${i}`,
+			sourceId: typeof l.source === "string" ? l.source : l.source.id,
+			targetId: typeof l.target === "string" ? l.target : l.target.id,
+			label: l.label ?? "",
+			data: l.data,
+			...l.color && { color: l.color }
+		}))
+	};
+}
+/** Bidirectional converter for D3.js force-directed JSON format. */
+const d3Converter = createFormatConverter(toD3Graph, fromD3Graph);
+
+//#endregion
+export { d3Converter, fromD3Graph, toD3Graph };

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

@@ -0,0 +1,9 @@
+import { c as Graph, f as GraphFormatConverter } from "../../types-B6Tpeerk.mjs";
+
+//#region src/formats/dot/index.d.ts
+declare function toDOT(graph: Graph): string;
+declare function fromDOT(dot: string): Graph;
+/** Bidirectional converter for DOT (Graphviz) format. */
+declare const dotConverter: GraphFormatConverter<string>;
+//#endregion
+export { dotConverter, fromDOT, toDOT };