@statelyai/graph 0.12.0 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @statelyai/graph
 
-A TypeScript graph library built on plain JSON objects. Supports directed/undirected graphs, hierarchical nodes, graph algorithms, visual properties, and serialization to DOT, GraphML, Mermaid, and more.
+A TypeScript graph library for JSON-serializable graph IR. Use it to validate, analyze, transform, and round-trip directed, undirected, hierarchical, port-aware, and visual graphs across tools.
 
 Made from our experience at [stately.ai](https://stately.ai), where we build visual tools for complex systems.
 
@@ -25,13 +25,13 @@ Optional peers are only needed for specific adapters:
 
 ## Highlights
 
-- Plain JSON graphs with no runtime wrappers required
+- Plain JSON graphs with no runtime wrappers required; omitted `data` defaults to `null`
 - Standalone functions with a consistent `get*`/`gen*`/`is*`/`add*` naming model
 - Directed, undirected, hierarchical, and visual graph support
 - Ports for node-editor and dataflow-style graphs
 - Algorithms for traversal, paths, centrality, communities, connectivity, isomorphism, ordering, MST, and walks
 - Diff/patch utilities for graph state changes
-- Multi-format conversion via package subpaths
+- Multi-format conversion via package subpaths, with fidelity claims tested against fixtures
 - Small, fast test suite with broad format coverage
 
 ## Quick Start
@@ -149,17 +149,17 @@ getEdgesByPort(graph, 'render', 'input'); // [e1]
 
 <!-- validation helpers exported from src/schemas.ts -->
 
-Use the `@statelyai/graph/schemas` subpath when you want runtime validation or JSON Schema generation.
+Use the `@statelyai/graph/schemas` subpath when you want runtime validation or JSON Schema generation. `validateGraph()` combines shape checks with graph invariants such as duplicate ids, dangling edges, missing parents, missing initial nodes, duplicate ports, invalid port references, and parent cycles.
 
 ```ts
-import { GraphSchema, getGraphIssues, isGraph } from '@statelyai/graph/schemas';
+import { GraphSchema, isGraph, validateGraph } from '@statelyai/graph/schemas';
 
 const unknownValue: unknown = JSON.parse(input);
 
 if (isGraph(unknownValue)) {
   // fully typed Graph
 } else {
-  console.error(getGraphIssues(unknownValue));
+  console.error(validateGraph(unknownValue));
 }
 
 const parsed = GraphSchema.parse(unknownValue);
@@ -252,7 +252,7 @@ const imported = fromGEXF(gexfXmlString); // GEXF (Gephi)
 
 <!-- supported format adapters derived from src/formats/* subdirectories -->
 
-**Supported formats:** Cytoscape.js JSON, D3.js JSON, JSON Graph Format, GEXF, GraphML, GML, TGF, DOT, Mermaid (flowchart, state, sequence, class, ER, mindmap, block, Ishikawa), ELK, xyflow, adjacency list, and edge list.
+**Supported formats:** Cytoscape.js JSON, D3.js JSON, D2, JSON Graph Format, GEXF, GraphML, GML, TGF, DOT, Mermaid (flowchart, state, sequence, class, ER, mindmap, block, Ishikawa), ELK, xyflow, adjacency list, and edge list.
 
 Each bidirectional format also has a converter object:
 
@@ -263,6 +263,11 @@ const cyto = cytoscapeConverter.to(graph);
 const back = cytoscapeConverter.from(cyto);
 ```
 
+Round-trip fidelity may use adapter-specific graph, node, and edge `data`
+metadata when the target format does not have a native field for a source
+concept. A `partial` round-trip entry means the adapter still drops meaningful
+source information instead of preserving it as metadata.
+
 ## Format Support
 
 <!-- format support matrix derived from src/formats/support.ts -->
@@ -270,17 +275,18 @@ const back = cytoscapeConverter.from(cyto);
 | Format              | Hierarchy | Ports   | Visual  | Round-trip | Notes                                                                      |
 | ------------------- | --------- | ------- | ------- | ---------- | -------------------------------------------------------------------------- |
 | `adjacency-list`    | none      | none    | none    | partial    | Connectivity only; edge metadata is lost.                                  |
-| `cytoscape`         | full      | full    | partial | partial    | Ports round-trip through element data.                                     |
-| `d3`                | none      | full    | partial | partial    | Ports round-trip through node/link objects.                                |
+| `cytoscape`         | full      | full    | full    | full       | Graph, node, and edge metadata round-trip through element data.            |
+| `d3`                | full      | full    | full    | full       | Graph, node, and edge metadata round-trip through the loose JSON shape.    |
+| `d2`                | full      | full    | full    | full       | D2 syntax, hierarchy, ports, styles, and connector modes round-trip.       |
 | `dot`               | partial   | partial | partial | partial    | Edge port ids round-trip, but `:port:compass` mapping is still incomplete. |
 | `edge-list`         | none      | none    | none    | partial    | Endpoints only.                                                            |
-| `elk`               | full      | full    | full    | partial    | Best for layout exchange.                                                  |
-| `gexf`              | full      | full    | partial | partial    | Ports round-trip via custom attributes.                                    |
-| `gml`               | full      | full    | partial | partial    | Ports round-trip through JSON-stringified metadata.                        |
+| `elk`               | full      | full    | full    | full       | Metadata round-trips through reserved layout options.                      |
+| `gexf`              | full      | full    | full    | full       | Custom attributes preserve metadata beyond the standard viz module.        |
+| `gml`               | full      | full    | full    | full       | Graph, node, and edge metadata round-trip through direct and JSON fields.  |
 | `graphml`           | full      | full    | partial | partial    | Ports round-trip through `<data>` fields.                                  |
-| `jgf`               | full      | full    | none    | partial    | Ports round-trip through metadata.                                         |
+| `jgf`               | full      | full    | full    | full       | Graph, node, and edge metadata round-trip through `metadata` objects.      |
 | `tgf`               | none      | none    | none    | partial    | Minimal ids and labels only.                                               |
-| `xyflow`            | none      | full    | full    | partial    | Ports map directly to handles.                                             |
+| `xyflow`            | full      | full    | full    | full       | Metadata round-trips through reserved data fields.                         |
 | `mermaid/block`     | partial   | none    | partial | partial    | Syntax-driven, not port-aware.                                             |
 | `mermaid/class`     | none      | none    | none    | partial    | Class syntax is stored conservatively.                                     |
 | `mermaid/er`        | none      | none    | none    | partial    | Focuses on entities and cardinality.                                       |
@@ -288,7 +294,7 @@ const back = cytoscapeConverter.from(cyto);
 | `mermaid/ishikawa`  | full      | none    | none    | partial    | Preserves hierarchy, not fishbone layout.                                  |
 | `mermaid/mindmap`   | full      | none    | partial | partial    | Icon syntax is not fully re-emitted.                                       |
 | `mermaid/sequence`  | partial   | none    | none    | partial    | Actor links and menu syntax are incomplete.                                |
-| `mermaid/state`     | full      | none    | partial | partial    | State notes are still lossy.                                               |
+| `mermaid/state`     | full      | none    | partial | full       | State syntax round-trips through graph and node data.                      |
 
 Some formats have optional peer dependencies: `fast-xml-parser` (GEXF, GraphML) and `dotparser` (DOT). All other formats are dependency-free.
 
@@ -299,6 +305,7 @@ Format-specific docs live alongside the source:
 - [Adjacency list](./src/formats/adjacency-list/README.md)
 - [Cytoscape](./src/formats/cytoscape/README.md)
 - [D3](./src/formats/d3/README.md)
+- [D2](./src/formats/d2/README.md)
 - [DOT](./src/formats/dot/README.md)
 - [Edge list](./src/formats/edge-list/README.md)
 - [ELK](./src/formats/elk/README.md)
@@ -327,13 +334,14 @@ The repo includes runnable examples under [`examples/`](./examples):
 ```bash
 pnpm install
 pnpm verify
+pnpm bench
 ```
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for contributor conventions, format-module checklist, and release notes guidance.
 
 ## Why this library?
 
-Graph file formats define how to _store_ graphs. Visualization libraries define how to _render_ them. This library is the computational layer in between: plain JSON objects in, algorithms and mutations, plain JSON objects out.
+Graph file formats define how to _store_ graphs. Visualization libraries define how to _render_ them. This library is the trusted interchange and analysis layer in between: plain JSON objects in, validation, algorithms, transforms, diffing, and format-preserving conversion out.
 
 ```
 GEXF file → fromGEXF() → Graph → run algorithms, mutate → toCytoscapeJSON() → render
@@ -341,6 +349,8 @@ GEXF file → fromGEXF() → Graph → run algorithms, mutate → toCytoscapeJSO
 
 Your `Graph` is a plain object that survives `JSON.stringify`, `structuredClone`, `postMessage`, and `localStorage` without adapters.
 
+A canonical graph is a deterministic projection of a graph for comparison, hashing, snapshots, or caches. A future pure helper would return a new graph with stable node/edge ordering and normalized optional fields. A hash would be a digest of that canonical JSON. A summary would be a small structural report, for example node count, edge count, roots, sinks, component count, compound depth, port count, and whether the graph is acyclic. A pure `sortGraph()` would return a sorted copy and never mutate the input.
+
 ## License
 
 MIT

package/dist/{adjacency-list-Ca0VjKIf.mjs → adjacency-list-VsUaH9SJ.mjs}

@@ -20,7 +20,7 @@ function toAdjacencyList(graph) {
 	for (const node of graph.nodes) adj[node.id] = [];
 	for (const edge of graph.edges) {
 		adj[edge.sourceId]?.push(edge.targetId);
-		if (graph.type === "undirected") adj[edge.targetId]?.push(edge.sourceId);
+		if (graph.mode !== "directed") adj[edge.targetId]?.push(edge.sourceId);
 	}
 	return adj;
 }
@@ -70,7 +70,7 @@ function fromAdjacencyList(adj, options) {
 	}
 	return {
 		id: options?.id ?? "",
-		type: directed ? "directed" : "undirected",
+		mode: directed ? "directed" : "undirected",
 		initialNodeId: null,
 		nodes,
 		edges,

package/dist/{algorithms-BHHg7lGq.mjs → algorithms-Ba7o7niK.mjs}

@@ -1,4 +1,5 @@
-import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-CJc-ul8e.mjs";
+import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-DR8M1vBy.mjs";
+import { t as getEdgeMode } from "./mode-D8OnHFBk.mjs";
 
 //#region src/graph.ts
 /**
@@ -7,7 +8,7 @@ import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdg
 * @example
 * ```ts
 * const port = createGraphPort({ name: 'output', direction: 'out' });
-* // { name: 'output', direction: 'out', data: undefined }
+* // { name: 'output', direction: 'out', data: null }
 * ```
 */
 function createGraphPort(config) {
@@ -15,7 +16,7 @@ function createGraphPort(config) {
 	const port = {
 		name: config.name,
 		direction: config.direction ?? "inout",
-		data: config.data
+		data: config.data ?? null
 	};
 	if (config.label !== void 0) port.label = config.label;
 	if (config.x !== void 0) port.x = config.x;
@@ -50,7 +51,7 @@ function createGraphNode(config) {
 		...config.parentId !== void 0 && { parentId: config.parentId ?? null },
 		...config.initialNodeId !== void 0 && { initialNodeId: config.initialNodeId ?? null },
 		label: config.label ?? null,
-		data: config.data
+		data: config.data ?? null
 	};
 	if (config.ports !== void 0 && config.ports.length > 0) {
 		validatePortNames(config.ports);
@@ -71,7 +72,7 @@ function createGraphNode(config) {
 * @example
 * ```ts
 * const edge = createGraphEdge({ id: 'e1', sourceId: 'a', targetId: 'b' });
-* // { type: 'edge', id: 'e1', sourceId: 'a', targetId: 'b', label: null, data: undefined }
+* // { type: 'edge', id: 'e1', sourceId: 'a', targetId: 'b', label: null, data: null }
 * ```
 */
 function createGraphEdge(config) {
@@ -84,10 +85,11 @@ function createGraphEdge(config) {
 		sourceId: config.sourceId,
 		targetId: config.targetId,
 		label: config.label ?? null,
-		data: config.data
+		data: config.data ?? null
 	};
 	if (config.sourcePort !== void 0) edge.sourcePort = config.sourcePort;
 	if (config.targetPort !== void 0) edge.targetPort = config.targetPort;
+	if (config.mode !== void 0) edge.mode = config.mode;
 	if (config.weight !== void 0) edge.weight = config.weight;
 	if (config.x !== void 0) edge.x = config.x;
 	if (config.y !== void 0) edge.y = config.y;
@@ -111,11 +113,11 @@ function createGraphEdge(config) {
 function createGraph(config) {
 	const graph = {
 		id: config?.id ?? "",
-		type: config?.type ?? "directed",
+		mode: config?.mode ?? "directed",
 		initialNodeId: config?.initialNodeId ?? null,
 		nodes: (config?.nodes ?? []).map(createGraphNode),
 		edges: (config?.edges ?? []).map(createGraphEdge),
-		data: config?.data ?? void 0
+		data: config?.data ?? null
 	};
 	if (config?.direction !== void 0) graph.direction = config.direction;
 	if (config?.style !== void 0) graph.style = config.style;
@@ -244,7 +246,7 @@ function createGraphFromTransition(transition, options) {
 	}
 	return createGraph({
 		id: options.id ?? "",
-		type: "directed",
+		mode: "directed",
 		initialNodeId: initialStateId,
 		nodes,
 		edges
@@ -582,8 +584,9 @@ var GraphInstance = class GraphInstance {
 	get id() {
 		return this.graph.id;
 	}
-	get type() {
-		return this.graph.type;
+	/** Default directedness for all edges. */
+	get mode() {
+		return this.graph.mode;
 	}
 	get nodes() {
 		return this.graph.nodes;
@@ -703,9 +706,11 @@ function getNeighborIds$1(graph, nodeId) {
 		const ai = idx.edgeById.get(eid);
 		if (ai !== void 0) ids.push(graph.edges[ai].targetId);
 	}
-	if (graph.type === "undirected") for (const eid of idx.inEdges.get(nodeId) ?? []) {
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
 		const ai = idx.edgeById.get(eid);
-		if (ai !== void 0) ids.push(graph.edges[ai].sourceId);
+		if (ai === void 0) continue;
+		const edge = graph.edges[ai];
+		if (getEdgeMode(graph, edge) !== "directed") ids.push(edge.sourceId);
 	}
 	return ids;
 }
@@ -736,11 +741,11 @@ function getNeighborEdges(graph, nodeId) {
 			});
 		}
 	}
-	if (graph.type === "undirected") for (const eid of idx.inEdges.get(nodeId) ?? []) {
+	for (const eid of idx.inEdges.get(nodeId) ?? []) {
 		const ai = idx.edgeById.get(eid);
 		if (ai !== void 0) {
 			const edge = graph.edges[ai];
-			result.push({
+			if (getEdgeMode(graph, edge) !== "directed") result.push({
 				neighborId: edge.sourceId,
 				edge
 			});
@@ -844,7 +849,6 @@ function bellmanFord(graph, sourceId, getWeight) {
 	const dist = /* @__PURE__ */ new Map();
 	const prev = /* @__PURE__ */ new Map();
 	const effectiveWeight = getWeight ?? ((edge) => edge.weight ?? 1);
-	const isUndirected = graph.type === "undirected";
 	for (const node of graph.nodes) {
 		dist.set(node.id, Infinity);
 		prev.set(node.id, []);
@@ -857,7 +861,7 @@ function bellmanFord(graph, sourceId, getWeight) {
 			toId: edge.targetId,
 			edge
 		});
-		if (isUndirected) directedEdges.push({
+		if (getEdgeMode(graph, edge) !== "directed") directedEdges.push({
 			fromId: edge.targetId,
 			toId: edge.sourceId,
 			edge
@@ -1021,7 +1025,7 @@ function getCycles(graph) {
 	return [...genCycles(graph)];
 }
 function* genCycles(graph) {
-	if (graph.type === "undirected") yield* genCyclesUndirected(graph);
+	if (graph.mode !== "directed") yield* genCyclesUndirected(graph);
 	else yield* genCyclesDirected(graph);
 }
 function* genCyclesDirected(graph) {
@@ -1160,7 +1164,7 @@ function floydWarshallAllPaths(graph, getWeight) {
 			from: source,
 			edge
 		});
-		if (graph.type === "undirected") {
+		if (getEdgeMode(graph, edge) !== "directed") {
 			if (edgeWeight < dist[target][source]) {
 				dist[target][source] = edgeWeight;
 				prev[target][source] = [{
@@ -1318,7 +1322,7 @@ function* dfs(graph, startId) {
 	}
 }
 function isAcyclic(graph) {
-	if (graph.type === "undirected") return isAcyclicUndirected(graph);
+	if (graph.mode !== "directed") return isAcyclicUndirected(graph);
 	const WHITE = 0;
 	const GRAY = 1;
 	const BLACK = 2;
@@ -1576,7 +1580,7 @@ function getMinimumSpanningTree(graph, opts) {
 	const mstEdges = algorithm === "kruskal" ? kruskalMST(graph, getWeight) : primMST(graph, getWeight);
 	return createGraph({
 		id: graph.id,
-		type: graph.type,
+		mode: graph.mode,
 		initialNodeId: graph.initialNodeId ?? void 0,
 		nodes: graph.nodes.map((node) => ({
 			id: node.id,
@@ -1611,7 +1615,7 @@ function primMST(graph, getWeight) {
 				edge
 			});
 		}
-		if (graph.type === "undirected") for (const eid of idx.inEdges.get(nodeId) ?? []) {
+		if (graph.mode !== "directed") for (const eid of idx.inEdges.get(nodeId) ?? []) {
 			const ai = idx.edgeById.get(eid);
 			if (ai === void 0) continue;
 			const edge = graph.edges[ai];
@@ -1626,7 +1630,7 @@ function primMST(graph, getWeight) {
 	addEdgesOf(startId);
 	while (candidates.size > 0 && inMST.size < graph.nodes.length) {
 		const { edge } = candidates.pop();
-		const targetId = graph.type === "undirected" && inMST.has(edge.targetId) ? edge.sourceId : edge.targetId;
+		const targetId = graph.mode !== "directed" && inMST.has(edge.targetId) ? edge.sourceId : edge.targetId;
 		if (inMST.has(targetId)) continue;
 		inMST.add(targetId);
 		mstEdges.push(edge);
@@ -1675,7 +1679,7 @@ function getNeighborIds(graph, nodeId) {
 		const edgeIndex = idx.edgeById.get(edgeId);
 		if (edgeIndex !== void 0) neighbors.push(graph.edges[edgeIndex].targetId);
 	}
-	if (graph.type === "undirected") for (const edgeId of idx.inEdges.get(nodeId) ?? []) {
+	if (graph.mode !== "directed") for (const edgeId of idx.inEdges.get(nodeId) ?? []) {
 		const edgeIndex = idx.edgeById.get(edgeId);
 		if (edgeIndex !== void 0) neighbors.push(graph.edges[edgeIndex].sourceId);
 	}
@@ -1688,7 +1692,7 @@ function getIncomingIds(graph, nodeId) {
 		const edgeIndex = idx.edgeById.get(edgeId);
 		if (edgeIndex !== void 0) incoming.push(graph.edges[edgeIndex].sourceId);
 	}
-	if (graph.type === "undirected") for (const edgeId of idx.outEdges.get(nodeId) ?? []) {
+	if (graph.mode !== "directed") for (const edgeId of idx.outEdges.get(nodeId) ?? []) {
 		const edgeIndex = idx.edgeById.get(edgeId);
 		if (edgeIndex !== void 0) incoming.push(graph.edges[edgeIndex].targetId);
 	}
@@ -1741,7 +1745,7 @@ function getDegreeCentrality(graph) {
 	for (const node of graph.nodes) {
 		const outDegree = idx.outEdges.get(node.id)?.length ?? 0;
 		const inDegree = idx.inEdges.get(node.id)?.length ?? 0;
-		const degree = graph.type === "undirected" ? new Set([...idx.outEdges.get(node.id) ?? [], ...idx.inEdges.get(node.id) ?? []]).size : outDegree + inDegree;
+		const degree = graph.mode !== "directed" ? new Set([...idx.outEdges.get(node.id) ?? [], ...idx.inEdges.get(node.id) ?? []]).size : outDegree + inDegree;
 		scores[node.id] = degree * scale;
 	}
 	return scores;
@@ -1841,9 +1845,9 @@ function getBetweennessCentrality(graph) {
 	}
 	const order = graph.nodes.length;
 	if (order <= 2) return scores;
-	const scale = graph.type === "undirected" ? 1 / ((order - 1) * (order - 2) / 2) : 1 / ((order - 1) * (order - 2));
+	const scale = graph.mode !== "directed" ? 1 / ((order - 1) * (order - 2) / 2) : 1 / ((order - 1) * (order - 2));
 	for (const nodeId of Object.keys(scores)) {
-		if (graph.type === "undirected") scores[nodeId] /= 2;
+		if (graph.mode !== "directed") scores[nodeId] /= 2;
 		scores[nodeId] *= scale;
 	}
 	return scores;
@@ -2314,11 +2318,11 @@ function getDegreeSignature(graph, nodeId) {
 	const idx = getIndex(graph);
 	const outDegree = idx.outEdges.get(nodeId)?.length ?? 0;
 	const inDegree = idx.inEdges.get(nodeId)?.length ?? 0;
-	if (graph.type === "undirected") return `u:${new Set([...idx.outEdges.get(nodeId) ?? [], ...idx.inEdges.get(nodeId) ?? []]).size}`;
+	if (graph.mode !== "directed") return `u:${new Set([...idx.outEdges.get(nodeId) ?? [], ...idx.inEdges.get(nodeId) ?? []]).size}`;
 	return `d:${inDegree}:${outDegree}`;
 }
 function getEdgesBetween(graph, sourceId, targetId) {
-	if (graph.type === "undirected") return graph.edges.filter((edge) => edge.sourceId === sourceId && edge.targetId === targetId || edge.sourceId === targetId && edge.targetId === sourceId);
+	if (graph.mode !== "directed") return graph.edges.filter((edge) => edge.sourceId === sourceId && edge.targetId === targetId || edge.sourceId === targetId && edge.targetId === sourceId);
 	return graph.edges.filter((edge) => edge.sourceId === sourceId && edge.targetId === targetId);
 }
 function edgesAreCompatible(edgesA, edgesB, edgeMatch) {
@@ -2339,7 +2343,7 @@ function edgesAreCompatible(edgesA, edgesB, edgeMatch) {
 * node and edge payloads.
 */
 function isIsomorphic(graphA, graphB, options) {
-	if (graphA.type !== graphB.type) return false;
+	if (graphA.mode !== graphB.mode) return false;
 	if (graphA.nodes.length !== graphB.nodes.length) return false;
 	if (graphA.edges.length !== graphB.edges.length) return false;
 	const nodeMatch = options?.nodeMatch;

package/dist/{algorithms-BlM-qoJb.d.mts → algorithms-fTqmvhzP.d.mts}

@@ -1,4 +1,4 @@
-import { D as SinglePathOptions, g as GraphNode, k as TraversalOptions, n as AllPairsShortestPathsOptions, p as GraphEdge, t as AStarOptions, u as Graph, v as GraphPath, w as PathOptions, x as MSTOptions } from "./types-CnZ01raw.mjs";
+import { A as TraversalOptions, O as SinglePathOptions, S as MSTOptions, T as PathOptions, _ as GraphNode, n as AllPairsShortestPathsOptions, p as GraphEdge, t as AStarOptions, u as Graph, y as GraphPath } from "./types-3-FS9NV2.mjs";
 
 //#region src/algorithms/traversal.d.ts
 declare function bfs<N>(graph: Graph<N>, startId: string): Generator<GraphNode<N>>;

package/dist/algorithms.d.mts

@@ -1,2 +1,2 @@
-import { A as genCycles, B as getStronglyConnectedComponents, C as getMinimumSpanningTree, D as getPostorders, E as getPostorder, F as getCycles, G as getTopologicalSort, H as bfs, I as getShortestPath, J as isConnected, K as hasPath, L as getShortestPaths, M as genSimplePaths, N as getAStarPath, O as getPreorder, P as getAllPairsShortestPaths, R as getSimplePath, S as getPageRank, T as genPreorders, U as dfs, V as joinPaths, W as getConnectedComponents, Y as isTree, _ as getDegreeCentrality, a as getBridges, b as getInDegreeCentrality, c as genGirvanNewmanCommunities, d as getLabelPropagationCommunities, f as getModularity, g as getClosenessCentrality, h as getBetweennessCentrality, i as getBiconnectedComponents, j as genShortestPaths, k as getPreorders, l as getGirvanNewmanCommunities, m as IterativeCentralityOptions, n as isIsomorphic, o as GirvanNewmanOptions, p as HITSResult, q as isAcyclic, r as getArticulationPoints, s as LabelPropagationOptions, t as IsomorphismOptions, u as getGreedyModularityCommunities, v as getEigenvectorCentrality, w as genPostorders, x as getOutDegreeCentrality, y as getHITS, z as getSimplePaths } from "./algorithms-BlM-qoJb.mjs";
+import { A as genCycles, B as getStronglyConnectedComponents, C as getMinimumSpanningTree, D as getPostorders, E as getPostorder, F as getCycles, G as getTopologicalSort, H as bfs, I as getShortestPath, J as isConnected, K as hasPath, L as getShortestPaths, M as genSimplePaths, N as getAStarPath, O as getPreorder, P as getAllPairsShortestPaths, R as getSimplePath, S as getPageRank, T as genPreorders, U as dfs, V as joinPaths, W as getConnectedComponents, Y as isTree, _ as getDegreeCentrality, a as getBridges, b as getInDegreeCentrality, c as genGirvanNewmanCommunities, d as getLabelPropagationCommunities, f as getModularity, g as getClosenessCentrality, h as getBetweennessCentrality, i as getBiconnectedComponents, j as genShortestPaths, k as getPreorders, l as getGirvanNewmanCommunities, m as IterativeCentralityOptions, n as isIsomorphic, o as GirvanNewmanOptions, p as HITSResult, q as isAcyclic, r as getArticulationPoints, s as LabelPropagationOptions, t as IsomorphismOptions, u as getGreedyModularityCommunities, v as getEigenvectorCentrality, w as genPostorders, x as getOutDegreeCentrality, y as getHITS, z as getSimplePaths } from "./algorithms-fTqmvhzP.mjs";
 export { GirvanNewmanOptions, HITSResult, IsomorphismOptions, IterativeCentralityOptions, LabelPropagationOptions, bfs, dfs, genCycles, genGirvanNewmanCommunities, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAStarPath, getAllPairsShortestPaths, getArticulationPoints, getBetweennessCentrality, getBiconnectedComponents, getBridges, getClosenessCentrality, getConnectedComponents, getCycles, getDegreeCentrality, getEigenvectorCentrality, getGirvanNewmanCommunities, getGreedyModularityCommunities, getHITS, getInDegreeCentrality, getLabelPropagationCommunities, getMinimumSpanningTree, getModularity, getOutDegreeCentrality, getPageRank, getPostorder, getPostorders, getPreorder, getPreorders, getShortestPath, getShortestPaths, getSimplePath, getSimplePaths, getStronglyConnectedComponents, getTopologicalSort, hasPath, isAcyclic, isConnected, isIsomorphic, isTree, joinPaths };

package/dist/algorithms.mjs

@@ -1,3 +1,3 @@
-import { A as isAcyclic, B as getShortestPaths, C as getPreorder, D as getConnectedComponents, E as dfs, F as genSimplePaths, H as getSimplePaths, I as getAStarPath, L as getAllPairsShortestPaths, M as isTree, N as genCycles, O as getTopologicalSort, P as genShortestPaths, R as getCycles, S as getPostorders, T as bfs, U as getStronglyConnectedComponents, V as getSimplePath, W as joinPaths, _ as getPageRank, a as genGirvanNewmanCommunities, b as genPreorders, c as getLabelPropagationCommunities, d as getClosenessCentrality, f as getDegreeCentrality, g as getOutDegreeCentrality, h as getInDegreeCentrality, i as getBridges, j as isConnected, k as hasPath, l as getModularity, m as getHITS, n as getArticulationPoints, o as getGirvanNewmanCommunities, p as getEigenvectorCentrality, r as getBiconnectedComponents, s as getGreedyModularityCommunities, t as isIsomorphic, u as getBetweennessCentrality, v as getMinimumSpanningTree, w as getPreorders, x as getPostorder, y as genPostorders, z as getShortestPath } from "./algorithms-BHHg7lGq.mjs";
+import { A as isAcyclic, B as getShortestPaths, C as getPreorder, D as getConnectedComponents, E as dfs, F as genSimplePaths, H as getSimplePaths, I as getAStarPath, L as getAllPairsShortestPaths, M as isTree, N as genCycles, O as getTopologicalSort, P as genShortestPaths, R as getCycles, S as getPostorders, T as bfs, U as getStronglyConnectedComponents, V as getSimplePath, W as joinPaths, _ as getPageRank, a as genGirvanNewmanCommunities, b as genPreorders, c as getLabelPropagationCommunities, d as getClosenessCentrality, f as getDegreeCentrality, g as getOutDegreeCentrality, h as getInDegreeCentrality, i as getBridges, j as isConnected, k as hasPath, l as getModularity, m as getHITS, n as getArticulationPoints, o as getGirvanNewmanCommunities, p as getEigenvectorCentrality, r as getBiconnectedComponents, s as getGreedyModularityCommunities, t as isIsomorphic, u as getBetweennessCentrality, v as getMinimumSpanningTree, w as getPreorders, x as getPostorder, y as genPostorders, z as getShortestPath } from "./algorithms-Ba7o7niK.mjs";
 
 export { bfs, dfs, genCycles, genGirvanNewmanCommunities, genPostorders, genPreorders, genShortestPaths, genSimplePaths, getAStarPath, getAllPairsShortestPaths, getArticulationPoints, getBetweennessCentrality, getBiconnectedComponents, getBridges, getClosenessCentrality, getConnectedComponents, getCycles, getDegreeCentrality, getEigenvectorCentrality, getGirvanNewmanCommunities, getGreedyModularityCommunities, getHITS, getInDegreeCentrality, getLabelPropagationCommunities, getMinimumSpanningTree, getModularity, getOutDegreeCentrality, getPageRank, getPostorder, getPostorders, getPreorder, getPreorders, getShortestPath, getShortestPaths, getSimplePath, getSimplePaths, getStronglyConnectedComponents, getTopologicalSort, hasPath, isAcyclic, isConnected, isIsomorphic, isTree, joinPaths };

package/dist/{converter-Dspillnn.mjs → converter-udLITX36.mjs}

@@ -1,5 +1,5 @@
-import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-Ca0VjKIf.mjs";
-import { n as toEdgeList, t as fromEdgeList } from "./edge-list-gKe8-iRa.mjs";
+import { n as toAdjacencyList, t as fromAdjacencyList } from "./adjacency-list-VsUaH9SJ.mjs";
+import { n as toEdgeList, t as fromEdgeList } from "./edge-list-DP4otyPU.mjs";
 
 //#region src/formats/converter/index.ts
 /**

package/dist/{edge-list-gKe8-iRa.mjs → edge-list-DP4otyPU.mjs}

@@ -59,7 +59,7 @@ function fromEdgeList(edges, options) {
 	}));
 	return {
 		id: options?.id ?? "",
-		type: directed ? "directed" : "undirected",
+		mode: directed ? "directed" : "undirected",
 		initialNodeId: null,
 		nodes,
 		edges: edgeObjects,

package/dist/format-support.d.mts

@@ -16,6 +16,12 @@ interface FormatSupportEntry {
   features: FormatSupportFeatures;
   notes: string[];
 }
+/**
+ * Round-trip support is allowed to use adapter-specific graph, node, and edge
+ * `data` metadata when the target format has no native field for a source
+ * concept. A `partial` value means the adapter still drops meaningful source
+ * information instead of preserving it as metadata.
+ */
 declare const FORMAT_SUPPORT_MATRIX: FormatSupportEntry[];
 declare function getFormatSupportEntry(id: string): FormatSupportEntry | undefined;
 //#endregion

package/dist/format-support.mjs

@@ -1,4 +1,10 @@
 //#region src/formats/support.ts
+/**
+* Round-trip support is allowed to use adapter-specific graph, node, and edge
+* `data` metadata when the target format has no native field for a source
+* concept. A `partial` value means the adapter still drops meaningful source
+* information instead of preserving it as metadata.
+*/
 const FORMAT_SUPPORT_MATRIX = [
 	{
 		id: "adjacency-list",
@@ -23,12 +29,12 @@ const FORMAT_SUPPORT_MATRIX = [
 			undirected: "full",
 			hierarchy: "full",
 			ports: "full",
-			visual: "partial",
-			style: "partial",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["Uses Cytoscape JSON element data with partial layout/style fidelity.", "Ports round-trip through element data as `ports`, `sourcePort`, and `targetPort`."]
+		notes: ["Uses Cytoscape JSON element data with graph, node, and edge metadata stored in element data.", "Ports round-trip through element data as `ports`, `sourcePort`, and `targetPort`."]
 	},
 	{
 		id: "d3",
@@ -36,14 +42,35 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
+			hierarchy: "full",
 			ports: "full",
-			visual: "partial",
-			style: "none",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
+		},
+		notes: ["Targets force-graph structures, but graph, node, and edge metadata can be preserved on the loose JSON shape.", "Ports round-trip through node/link objects."]
+	},
+	{
+		id: "d2",
+		importPath: "@statelyai/graph/d2",
+		features: {
+			directed: "full",
+			undirected: "full",
+			hierarchy: "full",
+			ports: "full",
+			visual: "full",
+			style: "full",
+			weight: "none",
+			roundTrip: "full"
 		},
-		notes: ["Targets force-graph structures, not compound graph metadata.", "Ports round-trip through node/link objects."]
+		notes: [
+			"Containers map to hierarchy; dot vs block declaration form is preserved per node.",
+			"sql_table/class fields map to ports; node.field connections round-trip as sourcePort/targetPort.",
+			"Per-edge connectors (->, <-, --, <->) map to edge.mode; the authored glyph is preserved in _d2.arrow.",
+			"vars/classes/imports are preserved on graph data; comments attach to the following entity (best-effort).",
+			"d2 has no native edge weight."
+		]
 	},
 	{
 		id: "dot",
@@ -84,11 +111,11 @@ const FORMAT_SUPPORT_MATRIX = [
 			hierarchy: "full",
 			ports: "full",
 			visual: "full",
-			style: "partial",
-			weight: "none",
-			roundTrip: "partial"
+			style: "full",
+			weight: "full",
+			roundTrip: "full"
 		},
-		notes: ["Optimized for layout exchange with ELK rather than exact styling parity."]
+		notes: ["ELK-native layout fields are preserved directly; graph, node, port, and edge metadata round-trip through reserved layout options."]
 	},
 	{
 		id: "gexf",
@@ -98,12 +125,16 @@ const FORMAT_SUPPORT_MATRIX = [
 			undirected: "full",
 			hierarchy: "full",
 			ports: "full",
-			visual: "partial",
-			style: "partial",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["Attribute and viz extensions round-trip partially.", "Ports round-trip via custom node/edge attributes."]
+		notes: [
+			"Custom attributes preserve graph, node, and edge metadata beyond the standard viz module.",
+			"Ports round-trip via custom node/edge attributes.",
+			"Per-edge directedness round-trips via the `type` edge attribute; bidirectional maps to directed."
+		]
 	},
 	{
 		id: "gml",
@@ -113,12 +144,12 @@ const FORMAT_SUPPORT_MATRIX = [
 			undirected: "full",
 			hierarchy: "full",
 			ports: "full",
-			visual: "partial",
-			style: "partial",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["GML support focuses on common graph/node/edge attributes.", "Ports round-trip through JSON-stringified node metadata and edge fields."]
+		notes: ["GML stores graph, node, and edge metadata directly or as JSON-stringified fields.", "Ports round-trip through JSON-stringified node metadata and edge fields."]
 	},
 	{
 		id: "graphml",
@@ -133,7 +164,11 @@ const FORMAT_SUPPORT_MATRIX = [
 			weight: "full",
 			roundTrip: "partial"
 		},
-		notes: ["GraphML attribute fidelity is good, but not every extension is represented.", "Ports round-trip through node and edge `<data>` fields."]
+		notes: [
+			"GraphML attribute fidelity is good, but not every extension is represented.",
+			"Ports round-trip through node and edge `<data>` fields.",
+			"Per-edge directedness round-trips via the `directed` edge attribute; bidirectional maps to directed."
+		]
 	},
 	{
 		id: "jgf",
@@ -143,12 +178,12 @@ const FORMAT_SUPPORT_MATRIX = [
 			undirected: "full",
 			hierarchy: "full",
 			ports: "full",
-			visual: "none",
-			style: "none",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["JGF preserves core graph structure and data, but not layout primitives.", "Ports round-trip through node and edge metadata."]
+		notes: ["JGF preserves graph, node, and edge metadata via `metadata` objects.", "Ports round-trip through node and edge metadata."]
 	},
 	{
 		id: "tgf",
@@ -171,14 +206,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "partial",
-			hierarchy: "none",
+			hierarchy: "full",
 			ports: "full",
 			visual: "full",
-			style: "partial",
-			weight: "none",
-			roundTrip: "partial"
+			style: "full",
+			weight: "full",
+			roundTrip: "full"
 		},
-		notes: ["Ports map cleanly to handles, but styling remains adapter-specific."]
+		notes: ["xyflow-native fields are preserved directly; graph, node, edge, style, weight, and port metadata round-trip through reserved data fields."]
 	},
 	{
 		id: "mermaid/block",
@@ -296,9 +331,9 @@ const FORMAT_SUPPORT_MATRIX = [
 			visual: "partial",
 			style: "partial",
 			weight: "none",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["State notes are stored, but not fully round-trippable as separate graph entities."]
+		notes: ["State-specific syntax such as notes, classes, descriptions, directions, hierarchy, and parallel regions round-trips through node and graph data."]
 	}
 ];
 function getFormatSupportEntry(id) {

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

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