@statelyai/graph 1.0.0 → 2.0.0

package/dist/formats/gexf/index.mjs

@@ -1,5 +1,5 @@
 import { t as getEdgeMode } from "../../mode-D8OnHFBk.mjs";
-import { n as createFormatConverter } from "../../converter-udLITX36.mjs";
+import { n as createFormatConverter } from "../../converter-DyCJJfTe.mjs";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
 
 //#region src/formats/gexf/index.ts
@@ -129,7 +129,7 @@ function toGEXF(graph) {
 		});
 		const node = {
 			"@_id": n.id,
-			"@_label": n.label || n.id
+			"@_label": n.label ?? ""
 		};
 		if (n.parentId) node["@_pid"] = n.parentId;
 		if (attvalues.length > 0) node.attvalues = { attvalue: attvalues };
@@ -250,7 +250,8 @@ function fromGEXF(xml) {
 			"attribute",
 			"attvalue",
 			"attributes"
-		].includes(name)
+		].includes(name),
+		trimValues: false
 	});
 	let parsed;
 	try {
@@ -283,16 +284,16 @@ function fromGEXF(xml) {
 			if (attvals["ports"] !== void 0) node.ports = tryParseJSON(attvals["ports"]);
 			const pos = n["viz:position"];
 			if (pos) {
-				node.x = Number(pos["@_x"] ?? 0);
-				node.y = Number(pos["@_y"] ?? 0);
+				node.x = parseNumber(pos["@_x"] ?? 0, "<viz:position> x", "node", id);
+				node.y = parseNumber(pos["@_y"] ?? 0, "<viz:position> y", "node", id);
 			}
 			const size = n["viz:size"];
 			if (size) {
-				node.width = Number(size["@_value"] ?? 0);
-				node.height = Number(size["@_value"] ?? 0);
+				node.width = parseNumber(size["@_value"] ?? 0, "<viz:size>", "node", id);
+				node.height = node.width;
 			}
-			if (attvals["width"] !== void 0) node.width = Number(attvals["width"]);
-			if (attvals["height"] !== void 0) node.height = Number(attvals["height"]);
+			if (attvals["width"] !== void 0) node.width = parseNumber(attvals["width"], "width attribute", "node", id);
+			if (attvals["height"] !== void 0) node.height = parseNumber(attvals["height"], "height attribute", "node", id);
 			const color = n["viz:color"];
 			if (color) {
 				const r = Number(color["@_r"] ?? 0);
@@ -308,18 +309,19 @@ function fromGEXF(xml) {
 	parseNodes(graphEl.nodes?.node ?? graphEl.node, null);
 	const edges = asArray(graphEl.edges?.edge ?? graphEl.edge).map((e, i) => {
 		const attvals = getAttValues(e, attrMap);
+		const id = String(e["@_id"] ?? `e${i}`);
 		const edge = {
 			type: "edge",
-			id: String(e["@_id"] ?? `e${i}`),
+			id,
 			sourceId: String(e["@_source"]),
 			targetId: String(e["@_target"]),
 			label: e["@_label"] ?? "",
 			data: attvals["data"] !== void 0 ? tryParseJSON(attvals["data"]) : void 0,
-			...attvals["weight"] !== void 0 && { weight: Number(attvals["weight"]) },
-			...attvals["x"] !== void 0 && { x: Number(attvals["x"]) },
-			...attvals["y"] !== void 0 && { y: Number(attvals["y"]) },
-			...attvals["width"] !== void 0 && { width: Number(attvals["width"]) },
-			...attvals["height"] !== void 0 && { height: Number(attvals["height"]) },
+			...attvals["weight"] !== void 0 && { weight: parseNumber(attvals["weight"], "weight attribute", "edge", id) },
+			...attvals["x"] !== void 0 && { x: parseNumber(attvals["x"], "x attribute", "edge", id) },
+			...attvals["y"] !== void 0 && { y: parseNumber(attvals["y"], "y attribute", "edge", id) },
+			...attvals["width"] !== void 0 && { width: parseNumber(attvals["width"], "width attribute", "edge", id) },
+			...attvals["height"] !== void 0 && { height: parseNumber(attvals["height"], "height attribute", "edge", id) },
 			...attvals["style"] !== void 0 && { style: tryParseJSON(attvals["style"]) },
 			...attvals["sourcePort"] !== void 0 && { sourcePort: attvals["sourcePort"] },
 			...attvals["targetPort"] !== void 0 && { targetPort: attvals["targetPort"] }
@@ -366,6 +368,11 @@ function tryParseJSON(str) {
 		return str;
 	}
 }
+function parseNumber(value, field, kind, ownerId) {
+	const parsed = Number(value);
+	if (Number.isNaN(parsed)) throw new Error(`GEXF: ${field} value "${value}" on ${kind} "${ownerId}" is not a number. Fix the value or remove the attribute.`);
+	return parsed;
+}
 function hex(n) {
 	return n.toString(16).padStart(2, "0");
 }

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

@@ -1,4 +1,4 @@
-import { h as GraphFormatConverter, u as Graph } from "../../types-3-FS9NV2.mjs";
+import { d as Graph, g as GraphFormatConverter } from "../../types-DNYdIU21.mjs";
 
 //#region src/formats/gml/index.d.ts
 

package/dist/formats/gml/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-udLITX36.mjs";
+import { n as createFormatConverter } from "../../converter-DyCJJfTe.mjs";
 
 //#region src/formats/gml/index.ts
 /**
@@ -27,6 +27,7 @@ function toGML(graph) {
 	const lines = [];
 	lines.push("graph [");
 	lines.push(`  directed ${graph.mode === "undirected" ? 0 : 1}`);
+	if (graph.mode === "bidirectional") lines.push(`  mode ${gmlString(graph.mode)}`);
 	if (graph.id) lines.push(`  id ${gmlString(graph.id)}`);
 	if (graph.initialNodeId) lines.push(`  initialNodeId ${gmlString(graph.initialNodeId)}`);
 	if (graph.data !== void 0) lines.push(`  data ${gmlString(JSON.stringify(graph.data))}`);
@@ -67,6 +68,7 @@ function toGML(graph) {
 		lines.push(`    id ${gmlString(edge.id)}`);
 		lines.push(`    source ${gmlString(edge.sourceId)}`);
 		lines.push(`    target ${gmlString(edge.targetId)}`);
+		if (edge.mode) lines.push(`    mode ${gmlString(edge.mode)}`);
 		if (edge.label) lines.push(`    label ${gmlString(edge.label)}`);
 		if (edge.data !== void 0) lines.push(`    data ${gmlString(JSON.stringify(edge.data))}`);
 		if (edge.weight !== void 0) lines.push(`    weight ${edge.weight}`);
@@ -134,10 +136,10 @@ function fromGML(gml) {
 				...n["shape"] && { shape: n["shape"] },
 				...n["color"] && { color: n["color"] },
 				...n["style"] !== void 0 && { style: tryParseJSON(n["style"]) },
-				...gfx?.x !== void 0 && { x: gfx.x },
-				...gfx?.y !== void 0 && { y: gfx.y },
-				...gfx?.w !== void 0 && { width: gfx.w },
-				...gfx?.h !== void 0 && { height: gfx.h }
+				...gfx?.x !== void 0 && { x: parseNumber(gfx.x, "graphics x", "node", id) },
+				...gfx?.y !== void 0 && { y: parseNumber(gfx.y, "graphics y", "node", id) },
+				...gfx?.w !== void 0 && { width: parseNumber(gfx.w, "graphics w", "node", id) },
+				...gfx?.h !== void 0 && { height: parseNumber(gfx.h, "graphics h", "node", id) }
 			});
 			if (n["node"] !== void 0) parseNodes(n, id);
 		}
@@ -146,27 +148,29 @@ function fromGML(gml) {
 	const edgeEntries = asArray(graphBlock["edge"]);
 	for (const e of edgeEntries) {
 		const gfx = e["graphics"];
+		const id = String(e["id"] ?? `e${edges.length}`);
 		edges.push({
 			type: "edge",
-			id: String(e["id"] ?? `e${edges.length}`),
+			id,
 			sourceId: String(e["source"] ?? ""),
 			targetId: String(e["target"] ?? ""),
 			label: e["label"] ?? "",
+			...e["mode"] && { mode: String(e["mode"]) },
 			data: e["data"] !== void 0 ? tryParseJSON(e["data"]) : void 0,
-			...e["weight"] !== void 0 && { weight: Number(e["weight"]) },
+			...e["weight"] !== void 0 && { weight: parseNumber(e["weight"], "weight", "edge", id) },
 			...e["sourcePort"] !== void 0 && { sourcePort: String(e["sourcePort"]) },
 			...e["targetPort"] !== void 0 && { targetPort: String(e["targetPort"]) },
 			...e["color"] && { color: e["color"] },
 			...e["style"] !== void 0 && { style: tryParseJSON(e["style"]) },
-			...gfx?.x !== void 0 && { x: gfx.x },
-			...gfx?.y !== void 0 && { y: gfx.y },
-			...gfx?.w !== void 0 && { width: gfx.w },
-			...gfx?.h !== void 0 && { height: gfx.h }
+			...gfx?.x !== void 0 && { x: parseNumber(gfx.x, "graphics x", "edge", id) },
+			...gfx?.y !== void 0 && { y: parseNumber(gfx.y, "graphics y", "edge", id) },
+			...gfx?.w !== void 0 && { width: parseNumber(gfx.w, "graphics w", "edge", id) },
+			...gfx?.h !== void 0 && { height: parseNumber(gfx.h, "graphics h", "edge", id) }
 		});
 	}
 	return {
 		id: graphId,
-		mode: directed ? "directed" : "undirected",
+		mode: graphBlock["mode"] ? String(graphBlock["mode"]) : directed ? "directed" : "undirected",
 		initialNodeId: graphBlock["initialNodeId"] ?? null,
 		nodes,
 		edges,
@@ -301,6 +305,11 @@ function tryParseJSON(str) {
 		return str;
 	}
 }
+function parseNumber(value, field, kind, ownerId) {
+	const parsed = Number(value);
+	if (Number.isNaN(parsed)) throw new Error(`GML: ${field} value "${value}" on ${kind} "${ownerId}" is not a number. Fix the value or remove the attribute.`);
+	return parsed;
+}
 /**
 * Bidirectional converter for GML (Graph Modelling Language) format.
 *

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

@@ -1,4 +1,4 @@
-import { h as GraphFormatConverter, u as Graph } from "../../types-3-FS9NV2.mjs";
+import { d as Graph, g as GraphFormatConverter } from "../../types-DNYdIU21.mjs";
 
 //#region src/formats/graphml/index.d.ts
 declare function toGraphML(graph: Graph): string;

package/dist/formats/graphml/index.mjs

@@ -1,5 +1,5 @@
 import { t as getEdgeMode } from "../../mode-D8OnHFBk.mjs";
-import { n as createFormatConverter } from "../../converter-udLITX36.mjs";
+import { n as createFormatConverter } from "../../converter-DyCJJfTe.mjs";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
 
 //#region src/formats/graphml/index.ts
@@ -281,8 +281,12 @@ function fromGraphML(xml) {
 			"node",
 			"edge",
 			"data",
-			"key"
-		].includes(name)
+			"key",
+			"graph",
+			"port"
+		].includes(name),
+		parseTagValue: false,
+		trimValues: false
 	});
 	let parsed;
 	try {
@@ -292,50 +296,77 @@ function fromGraphML(xml) {
 	}
 	const graphml = parsed?.graphml;
 	if (!graphml) throw new Error("GraphML: missing <graphml> root element");
-	const graphEl = graphml.graph;
+	const graphEl = asArray(graphml.graph)[0];
 	if (!graphEl) throw new Error("GraphML: missing <graph> element");
 	const graphType = graphEl["@_edgedefault"] === "undirected" ? "undirected" : "directed";
 	const graphDataMap = parseDataElements(graphEl.data);
 	const graphData = graphDataMap.graphData !== void 0 ? tryParseJSON(graphDataMap.graphData) : void 0;
-	const nodes = asArray(graphEl.node).map((nodeEl) => {
+	const nodeEntries = [];
+	const edgeEls = [];
+	function collectGraphContents(gEl, parentId) {
+		for (const nodeEl of asArray(gEl.node)) {
+			nodeEntries.push({
+				el: nodeEl,
+				structuralParentId: parentId
+			});
+			for (const subgraphEl of asArray(nodeEl.graph)) collectGraphContents(subgraphEl, String(nodeEl["@_id"]));
+		}
+		edgeEls.push(...asArray(gEl.edge));
+	}
+	collectGraphContents(graphEl, null);
+	const nodes = nodeEntries.map(({ el: nodeEl, structuralParentId }) => {
 		const dataMap = parseDataElements(nodeEl.data);
+		const id = String(nodeEl["@_id"]);
 		const node = {
 			type: "node",
-			id: String(nodeEl["@_id"]),
-			parentId: dataMap.parentId ?? null,
+			id,
+			parentId: dataMap.parentId ?? structuralParentId,
 			initialNodeId: dataMap.initialNodeId ?? null,
 			label: dataMap.label ?? "",
 			data: dataMap.data !== void 0 ? tryParseJSON(dataMap.data) : void 0
 		};
-		if (dataMap.x !== void 0) node.x = parseNumber(dataMap.x);
-		if (dataMap.y !== void 0) node.y = parseNumber(dataMap.y);
-		if (dataMap.width !== void 0) node.width = parseNumber(dataMap.width);
-		if (dataMap.height !== void 0) node.height = parseNumber(dataMap.height);
+		if (dataMap.x !== void 0) node.x = parseNumber(dataMap.x, "x", "node", id);
+		if (dataMap.y !== void 0) node.y = parseNumber(dataMap.y, "y", "node", id);
+		if (dataMap.width !== void 0) node.width = parseNumber(dataMap.width, "width", "node", id);
+		if (dataMap.height !== void 0) node.height = parseNumber(dataMap.height, "height", "node", id);
 		if (dataMap.shape !== void 0) node.shape = dataMap.shape;
 		if (dataMap.color !== void 0) node.color = dataMap.color;
 		if (dataMap.style !== void 0) node.style = tryParseJSON(dataMap.style);
 		if (dataMap.ports !== void 0) node.ports = tryParseJSON(dataMap.ports);
+		else if (nodeEl.port !== void 0) node.ports = collectPorts(nodeEl.port);
 		return node;
 	});
-	const edges = asArray(graphEl.edge).map((edgeEl) => {
+	const usedEdgeIds = new Set(edgeEls.filter((edgeEl) => edgeEl["@_id"] != null).map((edgeEl) => String(edgeEl["@_id"])));
+	const edges = edgeEls.map((edgeEl, i) => {
 		const dataMap = parseDataElements(edgeEl.data);
+		const source = String(edgeEl["@_source"]);
+		const target = String(edgeEl["@_target"]);
+		let id;
+		if (edgeEl["@_id"] != null) id = String(edgeEl["@_id"]);
+		else {
+			id = `${source}-${target}-${i}`;
+			for (let suffix = 0; usedEdgeIds.has(id); suffix++) id = `${source}-${target}-${i}#e${suffix}`;
+			usedEdgeIds.add(id);
+		}
 		const edge = {
 			type: "edge",
-			id: String(edgeEl["@_id"]),
-			sourceId: String(edgeEl["@_source"]),
-			targetId: String(edgeEl["@_target"]),
+			id,
+			sourceId: source,
+			targetId: target,
 			label: dataMap.label ?? "",
 			data: dataMap.data !== void 0 ? tryParseJSON(dataMap.data) : void 0
 		};
-		if (dataMap.weight !== void 0) edge.weight = parseNumber(dataMap.weight);
-		if (dataMap.x !== void 0) edge.x = parseNumber(dataMap.x);
-		if (dataMap.y !== void 0) edge.y = parseNumber(dataMap.y);
-		if (dataMap.width !== void 0) edge.width = parseNumber(dataMap.width);
-		if (dataMap.height !== void 0) edge.height = parseNumber(dataMap.height);
+		if (dataMap.weight !== void 0) edge.weight = parseNumber(dataMap.weight, "weight", "edge", id);
+		if (dataMap.x !== void 0) edge.x = parseNumber(dataMap.x, "x", "edge", id);
+		if (dataMap.y !== void 0) edge.y = parseNumber(dataMap.y, "y", "edge", id);
+		if (dataMap.width !== void 0) edge.width = parseNumber(dataMap.width, "width", "edge", id);
+		if (dataMap.height !== void 0) edge.height = parseNumber(dataMap.height, "height", "edge", id);
 		if (dataMap.color !== void 0) edge.color = dataMap.color;
 		if (dataMap.style !== void 0) edge.style = tryParseJSON(dataMap.style);
 		if (dataMap.sourcePort !== void 0) edge.sourcePort = dataMap.sourcePort;
+		else if (edgeEl["@_sourceport"] != null) edge.sourcePort = String(edgeEl["@_sourceport"]);
 		if (dataMap.targetPort !== void 0) edge.targetPort = dataMap.targetPort;
+		else if (edgeEl["@_targetport"] != null) edge.targetPort = String(edgeEl["@_targetport"]);
 		const directedAttr = edgeEl["@_directed"];
 		if (directedAttr !== void 0) edge.mode = String(directedAttr) === "false" ? "undirected" : "directed";
 		return edge;
@@ -368,8 +399,28 @@ function tryParseJSON(str) {
 		return str;
 	}
 }
-function parseNumber(value) {
-	return Number(value);
+/**
+* Flattens native GraphML <port> elements (which may nest) into our port
+* shape. Standard GraphML ports carry only a name; direction is unknowable,
+* so they import as advisory 'inout' with null data.
+*/
+function collectPorts(portEls) {
+	const ports = [];
+	for (const portEl of asArray(portEls)) {
+		if (portEl?.["@_name"] == null) continue;
+		ports.push({
+			name: String(portEl["@_name"]),
+			direction: "inout",
+			data: null
+		});
+		if (portEl.port !== void 0) ports.push(...collectPorts(portEl.port) ?? []);
+	}
+	return ports;
+}
+function parseNumber(value, key, kind, ownerId) {
+	const parsed = Number(value);
+	if (Number.isNaN(parsed)) throw new Error(`GraphML: <data key="${key}"> value "${value}" on ${kind} "${ownerId}" is not a number. Fix the value or remove the attribute.`);
+	return parsed;
 }
 function parseDirection(value) {
 	return [

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

@@ -1,4 +1,4 @@
-import { h as GraphFormatConverter, u as Graph } from "../../types-3-FS9NV2.mjs";
+import { d as Graph, g as GraphFormatConverter } from "../../types-DNYdIU21.mjs";
 
 //#region src/formats/jgf/index.d.ts
 interface JGFNode {

package/dist/formats/jgf/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-udLITX36.mjs";
+import { n as createFormatConverter } from "../../converter-DyCJJfTe.mjs";
 
 //#region src/formats/jgf/index.ts
 /**
@@ -20,6 +20,7 @@ import { n as createFormatConverter } from "../../converter-udLITX36.mjs";
 */
 function toJGF(graph) {
 	const metadata = {};
+	if (graph.mode === "bidirectional") metadata.mode = graph.mode;
 	if (graph.initialNodeId) metadata.initialNodeId = graph.initialNodeId;
 	if (graph.data !== void 0) metadata.data = graph.data;
 	if (graph.direction) metadata.direction = graph.direction;
@@ -49,6 +50,7 @@ function toJGF(graph) {
 		}),
 		edges: graph.edges.map((e) => {
 			const meta = {};
+			if (e.mode) meta.mode = e.mode;
 			if (e.data !== void 0) meta.data = e.data;
 			if (e.weight !== void 0) meta.weight = e.weight;
 			if (e.x !== void 0) meta.x = e.x;
@@ -93,7 +95,7 @@ function fromJGF(jgf) {
 	if (!Array.isArray(g.edges)) throw new Error("JGF: \"graph.edges\" must be an array");
 	return {
 		id: g.id ?? "",
-		mode: g.directed === false ? "undirected" : "directed",
+		mode: g.metadata?.mode ?? (g.directed === false ? "undirected" : "directed"),
 		initialNodeId: g.metadata?.initialNodeId ?? null,
 		data: g.metadata?.data,
 		...g.metadata?.direction && { direction: g.metadata.direction },
@@ -120,6 +122,7 @@ function fromJGF(jgf) {
 			sourceId: e.source,
 			targetId: e.target,
 			label: e.label ?? "",
+			...e.metadata?.mode && { mode: e.metadata.mode },
 			data: e.metadata?.data,
 			...e.metadata?.weight !== void 0 && { weight: e.metadata.weight },
 			...e.metadata?.x !== void 0 && { x: e.metadata.x },

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

@@ -1,4 +1,4 @@
-import { h as GraphFormatConverter, u as Graph } from "../../types-3-FS9NV2.mjs";
+import { d as Graph, g as GraphFormatConverter } from "../../types-DNYdIU21.mjs";
 
 //#region src/formats/mermaid/sequence.d.ts
 interface SequenceNodeData {

package/dist/formats/mermaid/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-udLITX36.mjs";
+import { n as createFormatConverter } from "../../converter-DyCJJfTe.mjs";
 
 //#region src/formats/mermaid/shared.ts
 const MERMAID_TO_DIRECTION = {
@@ -16,11 +16,11 @@ const DIRECTION_TO_MERMAID = {
 };
 /** Escape a label for Mermaid output (quotes special chars). */
 function escapeMermaidLabel(s) {
-	return s.replace(/\\/g, "\\\\").replace(/"/g, "#quot;").replace(/;/g, "#59;").replace(/#(?!quot;|59;|35;)/g, "#35;");
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "#quot;").replace(/;/g, "#59;").replace(/\|/g, "#124;").replace(/#(?!quot;|59;|35;|124;)/g, "#35;");
 }
 /** Unescape a Mermaid label back to plain text. */
 function unescapeMermaidLabel(s) {
-	return s.replace(/#quot;/g, "\"").replace(/#59;/g, ";").replace(/#35;/g, "#");
+	return s.replace(/#quot;/g, "\"").replace(/#59;/g, ";").replace(/#124;/g, "|").replace(/#35;/g, "#");
 }
 /** Generate a deterministic edge ID from source, target, and index. */
 function generateEdgeId(sourceId, targetId, index) {
@@ -1389,6 +1389,19 @@ const mermaidFlowchartConverter = createFormatConverter(toMermaidFlowchart, from
 //#endregion
 //#region src/formats/mermaid/state.ts
 /**
+* Whether a node is a parallel-region marker. Region nodes are generated with
+* the exact id `${parentId}_region_${integer}`, so a node only counts when its
+* id matches that structure for its *actual* parent and that parent is a
+* parallel state. User ids that merely contain `_region_` (e.g.
+* `foo_region_bar`) are ordinary states.
+*/
+function isParallelRegionNode(node, nodesById) {
+	if (!node || !node.parentId) return false;
+	if (nodesById.get(node.parentId)?.data?.stateType !== "parallel") return false;
+	const prefix = `${node.parentId}_region_`;
+	return node.id.startsWith(prefix) && /^\d+$/.test(node.id.slice(prefix.length));
+}
+/**
 * Parses a Mermaid state diagram string into a Graph.
 *
 * @example
@@ -1410,6 +1423,7 @@ function fromMermaidState(input) {
 	let startCounter = 0;
 	let endCounter = 0;
 	let graphDirection;
+	let initialNodeId = null;
 	const classDefs = {};
 	const classAssignments = {};
 	const parentStack = [null];
@@ -1474,6 +1488,7 @@ function fromMermaidState(input) {
 			const stateId = compositeStateAsMatch[2];
 			const node = ensureNode(stateId);
 			node.data.description = description;
+			node.label = description;
 			parentStack.push(stateId);
 			continue;
 		}
@@ -1492,12 +1507,13 @@ function fromMermaidState(input) {
 			const stateId = stateAsMatch[2];
 			const node = ensureNode(stateId);
 			node.data.description = description;
+			node.label = description;
 			continue;
 		}
 		if (line === "}" || line === "end") {
 			if (parentStack.length > 1) {
 				const top = parentStack[parentStack.length - 1];
-				if (top && top.includes("_region_")) parentStack.pop();
+				if (top && isParallelRegionNode(nodeMap.get(top), nodeMap)) parentStack.pop();
 				parentStack.pop();
 			}
 			continue;
@@ -1506,7 +1522,7 @@ function fromMermaidState(input) {
 			const compositeParent = (() => {
 				for (let s = parentStack.length - 1; s >= 0; s--) {
 					const id = parentStack[s];
-					if (id && !id.includes("_region_")) return id;
+					if (id && !isParallelRegionNode(nodeMap.get(id), nodeMap)) return id;
 				}
 				return null;
 			})();
@@ -1540,7 +1556,7 @@ function fromMermaidState(input) {
 					regionCounters.set(compositeParent, 2);
 				} else {
 					const top = parentStack[parentStack.length - 1];
-					if (top && top.includes("_region_")) parentStack.pop();
+					if (top && isParallelRegionNode(nodeMap.get(top), nodeMap)) parentStack.pop();
 					const nextRegionId = `${compositeParent}_region_${regionIndex}`;
 					const nextRegion = {
 						type: "node",
@@ -1588,6 +1604,7 @@ function fromMermaidState(input) {
 			let targetId = transMatch[3];
 			const targetClass = transMatch[4];
 			const label = transMatch[5]?.trim() ?? "";
+			const isTopLevelStart = sourceId === "[*]" && parentStack[parentStack.length - 1] === null;
 			if (sourceId === "[*]") sourceId = resolveStarNode("source");
 			else {
 				ensureNode(sourceId);
@@ -1603,6 +1620,7 @@ function fromMermaidState(input) {
 					if (!classAssignments[targetId]) classAssignments[targetId] = [];
 					classAssignments[targetId].push(targetClass);
 				}
+				if (isTopLevelStart && initialNodeId === null) initialNodeId = targetId;
 			}
 			const edgeId = generateEdgeId(sourceId, targetId, edgeCounter++);
 			edges.push({
@@ -1676,7 +1694,7 @@ function fromMermaidState(input) {
 	return {
 		id: "",
 		mode: "directed",
-		initialNodeId: null,
+		initialNodeId,
 		nodes: Array.from(nodeMap.values()),
 		edges,
 		data: {
@@ -1699,6 +1717,7 @@ function toMermaidState(graph) {
 		const mDir = DIRECTION_TO_MERMAID[graph.direction];
 		if (mDir) lines.push(`    direction ${mDir}`);
 	}
+	const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
 		const pid = node.parentId ?? null;
@@ -1707,28 +1726,44 @@ function toMermaidState(graph) {
 	}
 	const isParent = /* @__PURE__ */ new Set();
 	for (const node of graph.nodes) if (childrenMap.has(node.id)) isParent.add(node.id);
+	const referencedByEdge = /* @__PURE__ */ new Set();
+	for (const edge of graph.edges) {
+		referencedByEdge.add(edge.sourceId);
+		referencedByEdge.add(edge.targetId);
+	}
+	if (graph.initialNodeId) referencedByEdge.add(graph.initialNodeId);
 	function writeNodes(parentId, indent) {
 		const children = childrenMap.get(parentId) ?? [];
 		for (const node of children) {
 			if (node.data?.isStart || node.data?.isEnd) continue;
-			if (node.id.includes("_region_")) continue;
-			if (node.data?.stateType && node.data.stateType !== "parallel") lines.push(`${indent}state ${node.id} <<${node.data.stateType}>>`);
+			if (isParallelRegionNode(node, nodesById)) continue;
+			const description = node.data?.description ?? (node.label && node.label !== node.id ? node.label : void 0);
+			let declared = false;
+			if (node.data?.stateType && node.data.stateType !== "parallel") {
+				lines.push(`${indent}state ${node.id} <<${node.data.stateType}>>`);
+				declared = true;
+			}
 			if (isParent.has(node.id)) {
-				const stateDecl = node.data?.description ? `state "${escapeMermaidLabel(node.data.description)}" as ${node.id} {` : `state ${node.id} {`;
+				const stateDecl = description ? `state "${escapeMermaidLabel(description)}" as ${node.id} {` : `state ${node.id} {`;
 				lines.push(`${indent}${stateDecl}`);
 				if (node.data?.direction) {
 					const mDir = DIRECTION_TO_MERMAID[node.data.direction];
 					if (mDir) lines.push(`${indent}    direction ${mDir}`);
 				}
 				if (node.data?.stateType === "parallel") {
-					const regions = (childrenMap.get(node.id) ?? []).filter((r) => r.id.includes("_region_"));
+					const regions = (childrenMap.get(node.id) ?? []).filter((r) => isParallelRegionNode(r, nodesById));
 					for (let ri = 0; ri < regions.length; ri++) {
 						if (ri > 0) lines.push(`${indent}    --`);
 						writeNodes(regions[ri].id, indent + "    ");
 					}
 				} else writeNodes(node.id, indent + "    ");
 				lines.push(`${indent}}`);
-			} else if (node.data?.description) lines.push(`${indent}state "${escapeMermaidLabel(node.data.description)}" as ${node.id}`);
+				declared = true;
+			} else if (description) {
+				lines.push(`${indent}state "${escapeMermaidLabel(description)}" as ${node.id}`);
+				declared = true;
+			}
+			if (!declared && !referencedByEdge.has(node.id)) lines.push(`${indent}${node.id}`);
 			if (node.data?.notes) for (const note of node.data.notes) if (note.format === "block" || note.text.includes("\n")) {
 				lines.push(`${indent}note ${note.position} of ${node.id}`);
 				for (const noteLine of note.text.split("\n")) lines.push(`${indent}    ${escapeMermaidLabel(noteLine)}`);
@@ -1737,6 +1772,8 @@ function toMermaidState(graph) {
 		}
 	}
 	writeNodes(null, "    ");
+	const hasTopLevelStart = graph.nodes.some((n) => n.data?.isStart && (n.parentId ?? null) === null);
+	if (graph.initialNodeId && !hasTopLevelStart) lines.push(`    [*] --> ${graph.initialNodeId}`);
 	for (const edge of graph.edges) {
 		let sourceId = edge.sourceId;
 		let targetId = edge.targetId;

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

@@ -1,4 +1,4 @@
-import { h as GraphFormatConverter, u as Graph } from "../../types-3-FS9NV2.mjs";
+import { d as Graph, g as GraphFormatConverter } from "../../types-DNYdIU21.mjs";
 
 //#region src/formats/tgf/index.d.ts
 

package/dist/formats/tgf/index.mjs

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

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

@@ -1,4 +1,4 @@
-import { F as VisualGraphFormatConverter, M as VisualGraph } from "../../types-3-FS9NV2.mjs";
+import { L as VisualGraphFormatConverter, P as VisualGraph } from "../../types-DNYdIU21.mjs";
 import { EdgeBase, NodeBase } from "@xyflow/system";
 
 //#region src/formats/xyflow/index.d.ts

package/dist/formats/xyflow/index.mjs

@@ -19,8 +19,33 @@ function readMetadata(value) {
 }
 function readUserData(value) {
 	const metadata = readMetadata(value);
-	if (metadata && "data" in metadata) return metadata.data;
-	return value;
+	if (!metadata) return value;
+	return "data" in metadata ? metadata.data : void 0;
+}
+/**
+* React Flow requires parent nodes to appear before their children in the
+* nodes array. Reorders iteratively, keeping authored order otherwise: each
+* pass emits nodes whose parent is already emitted (or absent). Nodes left
+* over by a parentId cycle are appended in authored order rather than hanging.
+*/
+function orderParentsFirst(nodes) {
+	const nodeIds = new Set(nodes.map((n) => n.id));
+	const emitted = /* @__PURE__ */ new Set();
+	const result = [];
+	let remaining = nodes;
+	while (remaining.length > 0) {
+		const deferred = [];
+		for (const node of remaining) if (!node.parentId || emitted.has(node.parentId) || !nodeIds.has(node.parentId)) {
+			result.push(node);
+			emitted.add(node.id);
+		} else deferred.push(node);
+		if (deferred.length === remaining.length) {
+			result.push(...deferred);
+			break;
+		}
+		remaining = deferred;
+	}
+	return result;
 }
 /**
 * Converts a visual graph to xyflow (React Flow / Svelte Flow) format.
@@ -52,7 +77,7 @@ function toXYFlow(graph) {
 			direction: graph.direction,
 			style: graph.style
 		} } },
-		nodes: graph.nodes.map((n) => {
+		nodes: orderParentsFirst(graph.nodes.map((n) => {
 			const node = {
 				id: n.id,
 				position: {
@@ -72,7 +97,7 @@ function toXYFlow(graph) {
 			if (n.width !== void 0) node.width = n.width;
 			if (n.height !== void 0) node.height = n.height;
 			return node;
-		}),
+		})),
 		edges: graph.edges.map((e) => {
 			const edge = {
 				id: e.id,
@@ -83,6 +108,7 @@ function toXYFlow(graph) {
 			if (e.targetPort) edge.targetHandle = e.targetPort;
 			edge.data = withMetadata(e.data, { edge: {
 				label: e.label,
+				mode: e.mode,
 				weight: e.weight,
 				color: e.color,
 				style: e.style,
@@ -158,6 +184,7 @@ function fromXYFlow(flow) {
 				y: metadata?.y ?? 0,
 				width: metadata?.width ?? 0,
 				height: metadata?.height ?? 0,
+				...metadata?.mode !== void 0 && { mode: metadata.mode },
 				...metadata?.weight !== void 0 && { weight: metadata.weight },
 				...metadata?.color !== void 0 && { color: metadata.color },
 				...metadata?.style !== void 0 && { style: metadata.style }