@statelyai/graph 0.11.1 → 0.13.0

package/README.md

@@ -1,10 +1,6 @@
----
-title: '@statelyai/graph'
----
-
 # @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.
 
@@ -18,24 +14,24 @@ Optional peers are only needed for specific adapters:
 
 <!-- optional peer dependencies derived from package.json#peerDependencies -->
 
-| Package | Needed for |
-| --- | --- |
+| Package           | Needed for                                          |
+| ----------------- | --------------------------------------------------- |
 | `fast-xml-parser` | `@statelyai/graph/gexf`, `@statelyai/graph/graphml` |
-| `dotparser` | `@statelyai/graph/dot` parsing |
-| `cytoscape` | Cytoscape integration tests and consumer typing |
-| `d3-force` | D3 force integration tests and consumer typing |
-| `elkjs` | `@statelyai/graph/elk` |
-| `zod` | `@statelyai/graph/schemas` |
+| `dotparser`       | `@statelyai/graph/dot` parsing                      |
+| `cytoscape`       | Cytoscape integration tests and consumer typing     |
+| `d3-force`        | D3 force integration tests and consumer typing      |
+| `elkjs`           | `@statelyai/graph/elk`                              |
+| `zod`             | `@statelyai/graph/schemas`                          |
 
 ## 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
@@ -43,7 +39,12 @@ Optional peers are only needed for specific adapters:
 Graphs are plain JSON-serializable objects. All operations are standalone functions — no classes, no DOM, no rendering engine.
 
 ```ts
-import { createGraph, addNode, addEdge, getShortestPath } from '@statelyai/graph';
+import {
+  createGraph,
+  addNode,
+  addEdge,
+  getShortestPath,
+} from '@statelyai/graph';
 
 const graph = createGraph({
   nodes: [
@@ -70,12 +71,17 @@ const path = getShortestPath(graph, { from: 'a', to: 'c' });
 Look up, add, delete, and update nodes and edges. Query neighbors, predecessors, successors, degree, and more.
 
 ```ts
-import { getNode, deleteNode, getNeighbors, getSources } from '@statelyai/graph';
+import {
+  getNode,
+  deleteNode,
+  getNeighbors,
+  getSources,
+} from '@statelyai/graph';
 
-const node = getNode(graph, 'a');       // lookup by id
-deleteNode(graph, 'd');                 // removes node + connected edges
+const node = getNode(graph, 'a'); // lookup by id
+deleteNode(graph, 'd'); // removes node + connected edges
 const neighbors = getNeighbors(graph, 'a'); // adjacent nodes
-const roots = getSources(graph);        // nodes with no incoming edges
+const roots = getSources(graph); // nodes with no incoming edges
 ```
 
 Batch operations (`addEntities`, `deleteEntities`, `updateEntities`) let you apply multiple changes at once.
@@ -96,14 +102,14 @@ const graph = createGraph({
     { id: 'c' },
   ],
   edges: [
-    { id: 'e1', sourceId: 'a', targetId: 'b' },   // resolves to a -> b1
+    { id: 'e1', sourceId: 'a', targetId: 'b' }, // resolves to a -> b1
     { id: 'e2', sourceId: 'b1', targetId: 'b2' },
-    { id: 'e3', sourceId: 'b', targetId: 'c' },    // expands from all leaves of b
+    { id: 'e3', sourceId: 'b', targetId: 'c' }, // expands from all leaves of b
   ],
 });
 
 const children = getChildren(graph, 'b'); // [b1, b2]
-const flat = flatten(graph);              // only leaf nodes, edges resolved
+const flat = flatten(graph); // only leaf nodes, edges resolved
 ```
 
 ## Ports
@@ -139,6 +145,26 @@ getPorts(graph, 'fetch'); // [{ name: 'result', ... }]
 getEdgesByPort(graph, 'render', 'input'); // [e1]
 ```
 
+## Schema Validation
+
+<!-- validation helpers exported from src/schemas.ts -->
+
+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, isGraph, validateGraph } from '@statelyai/graph/schemas';
+
+const unknownValue: unknown = JSON.parse(input);
+
+if (isGraph(unknownValue)) {
+  // fully typed Graph
+} else {
+  console.error(validateGraph(unknownValue));
+}
+
+const parsed = GraphSchema.parse(unknownValue);
+```
+
 ## Algorithms
 
 <!-- algorithm functions exported from src/algorithms.ts -->
@@ -147,27 +173,40 @@ Includes traversal (BFS, DFS, preorder/postorder), pathfinding (shortest path, s
 
 ```ts
 import {
-  bfs, dfs, hasPath, isAcyclic,
-  getShortestPath, getCycles, getTopologicalSort,
-  getConnectedComponents, getMinimumSpanningTree,
-  getPageRank, getLabelPropagationCommunities,
-  genGirvanNewmanCommunities, getBridges, isIsomorphic,
+  bfs,
+  dfs,
+  hasPath,
+  isAcyclic,
+  getShortestPath,
+  getCycles,
+  getTopologicalSort,
+  getConnectedComponents,
+  getMinimumSpanningTree,
+  getPageRank,
+  getLabelPropagationCommunities,
+  genGirvanNewmanCommunities,
+  getBridges,
+  isIsomorphic,
 } from '@statelyai/graph';
 
-for (const node of bfs(graph, 'a')) { /* breadth-first */ }
-for (const node of dfs(graph, 'a')) { /* depth-first */ }
-
-hasPath(graph, 'a', 'c');                          // reachability
-isAcyclic(graph);                                  // cycle check
-getShortestPath(graph, { from: 'a', to: 'c' });   // single shortest path
-getTopologicalSort(graph);                         // topological order (or null)
-getConnectedComponents(graph);                     // connected components
-getMinimumSpanningTree(graph, { weight: e => e.data?.weight ?? 1 }); // MST
-getPageRank(graph);                                // link analysis scores
-getLabelPropagationCommunities(graph);             // community detection
-[...genGirvanNewmanCommunities(graph)];            // lazy community splits
-getBridges(graph);                                 // bridge edges
-isIsomorphic(graph, otherGraph);                   // structural equivalence
+for (const node of bfs(graph, 'a')) {
+  /* breadth-first */
+}
+for (const node of dfs(graph, 'a')) {
+  /* depth-first */
+}
+
+hasPath(graph, 'a', 'c'); // reachability
+isAcyclic(graph); // cycle check
+getShortestPath(graph, { from: 'a', to: 'c' }); // single shortest path
+getTopologicalSort(graph); // topological order (or null)
+getConnectedComponents(graph); // connected components
+getMinimumSpanningTree(graph, { weight: (e) => e.data?.weight ?? 1 }); // MST
+getPageRank(graph); // link analysis scores
+getLabelPropagationCommunities(graph); // community detection
+[...genGirvanNewmanCommunities(graph)]; // lazy community splits
+getBridges(graph); // bridge edges
+isIsomorphic(graph, otherGraph); // structural equivalence
 ```
 
 ## Diff & Walks
@@ -205,10 +244,10 @@ import { fromGEXF } from '@statelyai/graph/gexf';
 import { toCytoscapeJSON } from '@statelyai/graph/cytoscape';
 import { toD3Graph } from '@statelyai/graph/d3';
 
-const dot = toDOT(graph);                   // Graphviz DOT
-const cytoData = toCytoscapeJSON(graph);     // Cytoscape.js JSON
-const d3Data = toD3Graph(graph);             // D3.js { nodes, links }
-const imported = fromGEXF(gexfXmlString);    // GEXF (Gephi)
+const dot = toDOT(graph); // Graphviz DOT
+const cytoData = toCytoscapeJSON(graph); // Cytoscape.js JSON
+const d3Data = toD3Graph(graph); // D3.js { nodes, links }
+const imported = fromGEXF(gexfXmlString); // GEXF (Gephi)
 ```
 
 <!-- supported format adapters derived from src/formats/* subdirectories -->
@@ -224,6 +263,38 @@ 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 -->
+
+| Format              | Hierarchy | Ports   | Visual  | Round-trip | Notes                                                                      |
+| ------------------- | --------- | ------- | ------- | ---------- | -------------------------------------------------------------------------- |
+| `adjacency-list`    | none      | none    | none    | partial    | Connectivity only; edge metadata is lost.                                  |
+| `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.    |
+| `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    | 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    | full    | full       | Graph, node, and edge metadata round-trip through `metadata` objects.      |
+| `tgf`               | none      | none    | none    | partial    | Minimal ids and labels only.                                               |
+| `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.                                       |
+| `mermaid/flowchart` | partial   | none    | partial | partial    | `linkStyle` indices are fragile.                                           |
+| `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 | 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.
 
 Format-specific docs live alongside the source:
@@ -261,13 +332,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
@@ -275,6 +347,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/{algorithms-BHHg7lGq.mjs → algorithms-BNDQcHU3.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-CJc-ul8e.mjs";
+import { a as indexUpdateEdgeEndpoints, i as indexReparentNode, n as indexAddEdge, o as invalidateIndex, r as indexAddNode, t as getIndex } from "./indexing-DUl3kTqm.mjs";
 
 //#region src/graph.ts
 /**
@@ -7,7 +7,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 +15,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 +50,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 +71,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,7 +84,7 @@ 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;
@@ -115,7 +115,7 @@ function createGraph(config) {
 		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;

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-BNDQcHU3.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/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",
@@ -21,14 +27,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "partial",
-			ports: "none",
-			visual: "partial",
-			style: "partial",
+			hierarchy: "full",
+			ports: "full",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["Uses Cytoscape JSON element data with partial layout/style fidelity."]
+		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,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
-			ports: "none",
-			visual: "partial",
-			style: "none",
+			hierarchy: "full",
+			ports: "full",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["Targets force-graph structures, not compound graph metadata."]
+		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: "dot",
@@ -58,7 +64,7 @@ const FORMAT_SUPPORT_MATRIX = [
 			weight: "none",
 			roundTrip: "partial"
 		},
-		notes: ["Port syntax (`:port:compass`) is not fully mapped.", "HTML labels and layout hints beyond `rankdir` are lossy."]
+		notes: ["Edge port ids round-trip, but compass points and node port definitions are not mapped.", "HTML labels and layout hints beyond `rankdir` are lossy."]
 	},
 	{
 		id: "edge-list",
@@ -84,11 +90,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",
@@ -96,14 +102,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
-			ports: "none",
-			visual: "partial",
-			style: "partial",
+			hierarchy: "full",
+			ports: "full",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["Attribute and viz extensions round-trip partially."]
+		notes: ["Custom attributes preserve graph, node, and edge metadata beyond the standard viz module.", "Ports round-trip via custom node/edge attributes."]
 	},
 	{
 		id: "gml",
@@ -111,14 +117,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
-			ports: "none",
-			visual: "partial",
-			style: "partial",
+			hierarchy: "full",
+			ports: "full",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["GML support focuses on common graph/node/edge attributes."]
+		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",
@@ -126,14 +132,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
-			ports: "none",
+			hierarchy: "full",
+			ports: "full",
 			visual: "partial",
 			style: "partial",
 			weight: "full",
 			roundTrip: "partial"
 		},
-		notes: ["GraphML attribute fidelity is good, but not every extension is represented."]
+		notes: ["GraphML attribute fidelity is good, but not every extension is represented.", "Ports round-trip through node and edge `<data>` fields."]
 	},
 	{
 		id: "jgf",
@@ -141,14 +147,14 @@ const FORMAT_SUPPORT_MATRIX = [
 		features: {
 			directed: "full",
 			undirected: "full",
-			hierarchy: "none",
-			ports: "none",
-			visual: "none",
-			style: "none",
+			hierarchy: "full",
+			ports: "full",
+			visual: "full",
+			style: "full",
 			weight: "full",
-			roundTrip: "partial"
+			roundTrip: "full"
 		},
-		notes: ["JGF preserves core graph structure and data, but not layout primitives."]
+		notes: ["JGF preserves graph, node, and edge metadata via `metadata` objects.", "Ports round-trip through node and edge metadata."]
 	},
 	{
 		id: "tgf",
@@ -171,14 +177,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 +302,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/cytoscape/index.mjs

@@ -25,6 +25,7 @@ function toCytoscapeJSON(graph) {
 	if (graph.initialNodeId) graphData.initialNodeId = graph.initialNodeId;
 	if (graph.data !== void 0) graphData.graphData = graph.data;
 	if (graph.direction) graphData.direction = graph.direction;
+	if (graph.style !== void 0) graphData.style = graph.style;
 	return {
 		...Object.keys(graphData).length > 0 && { data: graphData },
 		elements: {
@@ -38,6 +39,8 @@ function toCytoscapeJSON(graph) {
 				if (n.height !== void 0) data.height = n.height;
 				if (n.shape) data.shape = n.shape;
 				if (n.color) data.color = n.color;
+				if (n.style !== void 0) data.style = n.style;
+				if (n.ports !== void 0) data.ports = n.ports;
 				const node = { data };
 				if (n.x !== void 0 && n.y !== void 0) node.position = {
 					x: n.x,
@@ -53,7 +56,15 @@ function toCytoscapeJSON(graph) {
 				};
 				if (e.label) data.label = e.label;
 				if (e.data !== void 0) data.edgeData = e.data;
+				if (e.weight !== void 0) data.weight = e.weight;
+				if (e.x !== void 0) data.x = e.x;
+				if (e.y !== void 0) data.y = e.y;
+				if (e.width !== void 0) data.width = e.width;
+				if (e.height !== void 0) data.height = e.height;
 				if (e.color) data.color = e.color;
+				if (e.style !== void 0) data.style = e.style;
+				if (e.sourcePort !== void 0) data.sourcePort = e.sourcePort;
+				if (e.targetPort !== void 0) data.targetPort = e.targetPort;
 				return { data };
 			})
 		}
@@ -85,6 +96,7 @@ function fromCytoscapeJSON(cyto) {
 		initialNodeId: cyto.data?.initialNodeId ?? null,
 		data: cyto.data?.graphData,
 		...cyto.data?.direction && { direction: cyto.data.direction },
+		...cyto.data?.style !== void 0 && { style: cyto.data.style },
 		nodes: cyto.elements.nodes.map((n) => ({
 			type: "node",
 			id: n.data.id,
@@ -99,7 +111,9 @@ function fromCytoscapeJSON(cyto) {
 			...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 }
+			...n.data.color && { color: n.data.color },
+			...n.data.style !== void 0 && { style: n.data.style },
+			...n.data.ports !== void 0 && { ports: n.data.ports }
 		})),
 		edges: cyto.elements.edges.map((e, i) => ({
 			type: "edge",
@@ -108,7 +122,15 @@ function fromCytoscapeJSON(cyto) {
 			targetId: e.data.target,
 			label: e.data.label ?? "",
 			data: e.data.edgeData,
-			...e.data.color && { color: e.data.color }
+			...e.data.weight !== void 0 && { weight: e.data.weight },
+			...e.data.x !== void 0 && { x: e.data.x },
+			...e.data.y !== void 0 && { y: e.data.y },
+			...e.data.width !== void 0 && { width: e.data.width },
+			...e.data.height !== void 0 && { height: e.data.height },
+			...e.data.color && { color: e.data.color },
+			...e.data.style !== void 0 && { style: e.data.style },
+			...e.data.sourcePort !== void 0 && { sourcePort: e.data.sourcePort },
+			...e.data.targetPort !== void 0 && { targetPort: e.data.targetPort }
 		}))
 	};
 }

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

@@ -11,8 +11,15 @@ interface D3Link {
   [key: string]: any;
 }
 interface D3Graph {
+  id?: string;
+  type?: Graph['type'];
+  initialNodeId?: string | null;
+  data?: any;
+  direction?: Graph['direction'];
+  style?: Graph['style'];
   nodes: D3Node[];
   links: D3Link[];
+  [key: string]: any;
 }
 /**
  * Converts a graph to D3.js force-directed format.