@statelyai/graph 0.13.0 → 2.0.0

package/dist/schemas.d.mts

@@ -1,4 +1,4 @@
-import { g as GraphNode, p as GraphEdge, u as Graph, y as GraphPort } from "./types-CnZ01raw.mjs";
+import { d as Graph, m as GraphEdge, v as GraphNode, x as GraphPort } from "./types-DNYdIU21.mjs";
 import * as z from "zod";
 
 //#region src/schemas.d.ts
@@ -15,7 +15,7 @@ declare const PortSchema: z.ZodObject<{
   y: z.ZodOptional<z.ZodNumber>;
   width: z.ZodOptional<z.ZodNumber>;
   height: z.ZodOptional<z.ZodNumber>;
-  style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+  style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
 }, z.core.$strip>;
 declare const NodeSchema: z.ZodObject<{
   type: z.ZodLiteral<"node">;
@@ -30,7 +30,7 @@ declare const NodeSchema: z.ZodObject<{
   height: z.ZodOptional<z.ZodNumber>;
   shape: z.ZodOptional<z.ZodString>;
   color: z.ZodOptional<z.ZodString>;
-  style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+  style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
   ports: z.ZodOptional<z.ZodArray<z.ZodObject<{
     name: z.ZodString;
     direction: z.ZodEnum<{
@@ -44,7 +44,7 @@ declare const NodeSchema: z.ZodObject<{
     y: z.ZodOptional<z.ZodNumber>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
-    style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
   }, z.core.$strip>>>;
 }, z.core.$strip>;
 declare const EdgeSchema: z.ZodObject<{
@@ -56,19 +56,25 @@ declare const EdgeSchema: z.ZodObject<{
   weight: z.ZodOptional<z.ZodNumber>;
   sourcePort: z.ZodOptional<z.ZodString>;
   targetPort: z.ZodOptional<z.ZodString>;
+  mode: z.ZodOptional<z.ZodEnum<{
+    directed: "directed";
+    undirected: "undirected";
+    bidirectional: "bidirectional";
+  }>>;
   data: z.ZodAny;
   x: z.ZodOptional<z.ZodNumber>;
   y: z.ZodOptional<z.ZodNumber>;
   width: z.ZodOptional<z.ZodNumber>;
   height: z.ZodOptional<z.ZodNumber>;
   color: z.ZodOptional<z.ZodString>;
-  style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+  style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
 }, z.core.$strip>;
 declare const GraphSchema: z.ZodObject<{
   id: z.ZodString;
-  type: z.ZodEnum<{
+  mode: z.ZodEnum<{
     directed: "directed";
     undirected: "undirected";
+    bidirectional: "bidirectional";
   }>;
   initialNodeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   nodes: z.ZodArray<z.ZodObject<{
@@ -84,7 +90,7 @@ declare const GraphSchema: z.ZodObject<{
     height: z.ZodOptional<z.ZodNumber>;
     shape: z.ZodOptional<z.ZodString>;
     color: z.ZodOptional<z.ZodString>;
-    style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     ports: z.ZodOptional<z.ZodArray<z.ZodObject<{
       name: z.ZodString;
       direction: z.ZodEnum<{
@@ -98,7 +104,7 @@ declare const GraphSchema: z.ZodObject<{
       y: z.ZodOptional<z.ZodNumber>;
       width: z.ZodOptional<z.ZodNumber>;
       height: z.ZodOptional<z.ZodNumber>;
-      style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+      style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     }, z.core.$strip>>>;
   }, z.core.$strip>>;
   edges: z.ZodArray<z.ZodObject<{
@@ -110,13 +116,18 @@ declare const GraphSchema: z.ZodObject<{
     weight: z.ZodOptional<z.ZodNumber>;
     sourcePort: z.ZodOptional<z.ZodString>;
     targetPort: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+      directed: "directed";
+      undirected: "undirected";
+      bidirectional: "bidirectional";
+    }>>;
     data: z.ZodAny;
     x: z.ZodOptional<z.ZodNumber>;
     y: z.ZodOptional<z.ZodNumber>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
     color: z.ZodOptional<z.ZodString>;
-    style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
   }, z.core.$strip>>;
   data: z.ZodAny;
   direction: z.ZodOptional<z.ZodEnum<{
@@ -125,7 +136,7 @@ declare const GraphSchema: z.ZodObject<{
     left: "left";
     right: "right";
   }>>;
-  style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+  style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
 }, z.core.$strip>;
 interface GraphValidationIssue {
   code: string;

package/dist/schemas.mjs

@@ -1,7 +1,17 @@
+import { t as getGraphIssues$1 } from "./validate-TtH-x3JV.mjs";
 import * as z from "zod";
 
 //#region src/schemas.ts
-const StyleSchema = z.record(z.string(), z.union([z.string(), z.number()]));
+const StyleSchema = z.record(z.string(), z.union([
+	z.string(),
+	z.number(),
+	z.boolean()
+]));
+const ModeSchema = z.enum([
+	"directed",
+	"undirected",
+	"bidirectional"
+]);
 const PortDirectionSchema = z.enum([
 	"in",
 	"out",
@@ -43,6 +53,7 @@ const EdgeSchema = z.object({
 	weight: z.number().optional(),
 	sourcePort: z.string().optional(),
 	targetPort: z.string().optional(),
+	mode: ModeSchema.optional(),
 	data: z.any(),
 	x: z.number().optional(),
 	y: z.number().optional(),
@@ -53,7 +64,7 @@ const EdgeSchema = z.object({
 });
 const GraphSchema = z.object({
 	id: z.string(),
-	type: z.enum(["directed", "undirected"]),
+	mode: ModeSchema,
 	initialNodeId: z.string().nullable().optional(),
 	nodes: z.array(NodeSchema),
 	edges: z.array(EdgeSchema),
@@ -106,37 +117,30 @@ function createIssue(code, message, path) {
 		path
 	};
 }
-function getDuplicateIndexes(items, getKey) {
-	const indexesByKey = /* @__PURE__ */ new Map();
-	items.forEach((item, index) => {
-		const key = getKey(item);
-		if (key == null) return;
-		const indexes = indexesByKey.get(key) ?? [];
-		indexes.push(index);
-		indexesByKey.set(key, indexes);
-	});
-	for (const [key, indexes] of indexesByKey) if (indexes.length < 2) indexesByKey.delete(key);
-	return indexesByKey;
+/** Maps structural issue codes from `validate.ts` to this module's codes. */
+const STRUCTURAL_CODE_MAP = {
+	"duplicate-node-id": "duplicate_node_id",
+	"duplicate-edge-id": "duplicate_edge_id",
+	"missing-initial-node": "missing_initial_node",
+	"missing-parent": "missing_parent",
+	"missing-node-initial": "missing_node_initial",
+	"duplicate-port-name": "duplicate_port_name",
+	"parent-cycle": "parent_cycle",
+	"missing-source-port": "missing_source_port",
+	"missing-target-port": "missing_target_port"
+};
+function toValidationIssue(issue) {
+	const path = issue.path ?? [];
+	let code = STRUCTURAL_CODE_MAP[issue.code] ?? issue.code;
+	if (issue.code === "dangling-edge-endpoint") code = path[path.length - 1] === "sourceId" ? "missing_source_node" : "missing_target_node";
+	return {
+		code,
+		message: issue.message,
+		path
+	};
 }
 function getGraphInvariantIssues(graph) {
-	const issues = [];
-	const nodeIndexes = /* @__PURE__ */ new Map();
-	const nodesById = /* @__PURE__ */ new Map();
-	for (const [id, indexes] of getDuplicateIndexes(graph.nodes, (node) => node.id)) for (const index of indexes) issues.push(createIssue("duplicate_node_id", `Duplicate node id "${id}"`, [
-		"nodes",
-		index,
-		"id"
-	]));
-	for (const [id, indexes] of getDuplicateIndexes(graph.edges, (edge) => edge.id)) for (const index of indexes) issues.push(createIssue("duplicate_edge_id", `Duplicate edge id "${id}"`, [
-		"edges",
-		index,
-		"id"
-	]));
-	graph.nodes.forEach((node, index) => {
-		nodeIndexes.set(node.id, index);
-		nodesById.set(node.id, node);
-	});
-	if (graph.initialNodeId && !nodeIndexes.has(graph.initialNodeId)) issues.push(createIssue("missing_initial_node", `Initial node "${graph.initialNodeId}" does not exist`, ["initialNodeId"]));
+	const issues = getGraphIssues$1(graph).map(toValidationIssue);
 	graph.nodes.forEach((node, index) => {
 		if (node.id === "") issues.push(createIssue("empty_node_id", "Node id must be a non-empty string", [
 			"nodes",
@@ -148,68 +152,13 @@ function getGraphInvariantIssues(graph) {
 			index,
 			"parentId"
 		]));
-		else if (node.parentId != null && !nodeIndexes.has(node.parentId)) issues.push(createIssue("missing_parent", `Parent node "${node.parentId}" does not exist`, [
-			"nodes",
-			index,
-			"parentId"
-		]));
-		if (node.initialNodeId && !nodeIndexes.has(node.initialNodeId)) issues.push(createIssue("missing_node_initial", `Initial node "${node.initialNodeId}" does not exist`, [
-			"nodes",
-			index,
-			"initialNodeId"
-		]));
-		for (const [name, indexes] of getDuplicateIndexes(node.ports ?? [], (port) => port.name)) for (const portIndex of indexes) issues.push(createIssue("duplicate_port_name", `Duplicate port name "${name}" on node "${node.id}"`, [
-			"nodes",
-			index,
-			"ports",
-			portIndex,
-			"name"
-		]));
 	});
-	for (const node of graph.nodes) {
-		const seen = /* @__PURE__ */ new Set();
-		let current = node.parentId;
-		while (current != null) {
-			if (current === node.id || seen.has(current)) {
-				issues.push(createIssue("parent_cycle", `Node "${node.id}" is part of a parent cycle`, [
-					"nodes",
-					nodeIndexes.get(node.id) ?? 0,
-					"parentId"
-				]));
-				break;
-			}
-			seen.add(current);
-			current = nodesById.get(current)?.parentId;
-		}
-	}
 	graph.edges.forEach((edge, index) => {
 		if (edge.id === "") issues.push(createIssue("empty_edge_id", "Edge id must be a non-empty string", [
 			"edges",
 			index,
 			"id"
 		]));
-		const source = nodesById.get(edge.sourceId);
-		const target = nodesById.get(edge.targetId);
-		if (!source) issues.push(createIssue("missing_source_node", `Source node "${edge.sourceId}" does not exist`, [
-			"edges",
-			index,
-			"sourceId"
-		]));
-		if (!target) issues.push(createIssue("missing_target_node", `Target node "${edge.targetId}" does not exist`, [
-			"edges",
-			index,
-			"targetId"
-		]));
-		if (source && edge.sourcePort !== void 0 && !source.ports?.some((port) => port.name === edge.sourcePort)) issues.push(createIssue("missing_source_port", `Port "${edge.sourcePort}" does not exist on source node "${edge.sourceId}"`, [
-			"edges",
-			index,
-			"sourcePort"
-		]));
-		if (target && edge.targetPort !== void 0 && !target.ports?.some((port) => port.name === edge.targetPort)) issues.push(createIssue("missing_target_port", `Port "${edge.targetPort}" does not exist on target node "${edge.targetId}"`, [
-			"edges",
-			index,
-			"targetPort"
-		]));
 	});
 	return issues;
 }

package/dist/{types-CnZ01raw.d.mts → types-DNYdIU21.d.mts}

@@ -1,4 +1,15 @@
 //#region src/types.d.ts
+/**
+ * Directedness of a graph or an individual edge.
+ *
+ * - `'directed'` — edge points from source to target.
+ * - `'undirected'` — edge has no direction; traversable both ways.
+ * - `'bidirectional'` — edge points both ways (arrows on both ends).
+ *
+ * Set at the graph level as the default ({@link Graph.mode}); individual edges
+ * may override it ({@link GraphEdge.mode}).
+ */
+type GraphMode = 'directed' | 'undirected' | 'bidirectional';
 interface EntityRect {
   x: number;
   y: number;
@@ -11,7 +22,7 @@ interface GraphEntity {
   y?: number;
   width?: number;
   height?: number;
-  style?: Record<string, string | number>;
+  style?: Record<string, string | number | boolean>;
 }
 /** Visual entity base — required position/size. */
 interface VisualGraphEntity {
@@ -19,7 +30,7 @@ interface VisualGraphEntity {
   y: number;
   width: number;
   height: number;
-  style?: Record<string, string | number>;
+  style?: Record<string, string | number | boolean>;
 }
 type PortDirection = 'in' | 'out' | 'inout';
 interface PortConfig<TPortData = any> extends GraphEntity {
@@ -42,13 +53,14 @@ interface VisualPort<TPortData = any> extends GraphPort<TPortData> {
 }
 interface GraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any, TPortData = any> {
   id?: string;
-  type?: 'directed' | 'undirected';
+  /** Default directedness for all edges. Defaults to `'directed'`. */
+  mode?: GraphMode;
   initialNodeId?: string;
   nodes?: NodeConfig<TNodeData, TPortData>[];
   edges?: EdgeConfig<TEdgeData>[];
   data?: TGraphData;
   direction?: 'up' | 'down' | 'left' | 'right';
-  style?: Record<string, string | number>;
+  style?: Record<string, string | number | boolean>;
 }
 interface NodeConfig<TNodeData = any, TPortData = any> extends GraphEntity {
   id: string;
@@ -87,18 +99,24 @@ interface EdgeConfig<TEdgeData = any> extends GraphEntity {
   sourcePort?: string;
   /** Port name on the target node this edge connects to. */
   targetPort?: string;
+  /**
+   * Per-edge directedness override. When absent, the edge inherits the graph's
+   * {@link GraphConfig.mode}.
+   */
+  mode?: GraphMode;
   data?: TEdgeData;
   color?: string;
 }
 interface Graph<TNodeData = any, TEdgeData = any, TGraphData = any, TPortData = any> {
   id: string;
-  type: 'directed' | 'undirected';
+  /** Default directedness for all edges. */
+  mode: GraphMode;
   initialNodeId?: string | null;
   nodes: GraphNode<TNodeData, TPortData>[];
   edges: GraphEdge<TEdgeData>[];
   data: TGraphData;
   direction?: 'up' | 'down' | 'left' | 'right';
-  style?: Record<string, string | number>;
+  style?: Record<string, string | number | boolean>;
 }
 interface GraphNode<TNodeData = any, TPortData = any> extends GraphEntity {
   type: 'node';
@@ -127,6 +145,11 @@ interface GraphEdge<TEdgeData = any> extends GraphEntity {
   sourcePort?: string;
   /** Port name on the target node this edge connects to. */
   targetPort?: string;
+  /**
+   * Per-edge directedness override. When absent, the edge inherits the graph's
+   * {@link Graph.mode}.
+   */
+  mode?: GraphMode;
   data: TEdgeData;
   color?: string;
 }
@@ -154,15 +177,64 @@ interface VisualGraphConfig<TNodeData = any, TEdgeData = any, TGraphData = any,
 interface DeleteNodeOptions {
   reparent?: boolean;
 }
+/**
+ * Update payload for {@link updateNode}/`updateEntities`.
+ *
+ * Optional fields (`x`, `y`, `width`, `height`, `shape`, `color`, `style`,
+ * `ports`) accept `null` to **unset** the field. `undefined` (or omitting the
+ * key) leaves the field unchanged. `null` is used for unsetting so update
+ * payloads stay JSON-serializable.
+ */
+interface NodeUpdate<TNodeData = any, TPortData = any> {
+  parentId?: string | null;
+  initialNodeId?: string | null;
+  label?: string | null;
+  data?: TNodeData;
+  /** New ports for the node, or `null` to remove all ports. */
+  ports?: PortConfig<TPortData>[] | null;
+  x?: number | null;
+  y?: number | null;
+  width?: number | null;
+  height?: number | null;
+  shape?: string | null;
+  color?: string | null;
+  style?: Record<string, string | number | boolean> | null;
+}
+/**
+ * Update payload for {@link updateEdge}/`updateEntities`.
+ *
+ * Optional fields (`weight`, `mode`, `sourcePort`, `targetPort`, `x`, `y`,
+ * `width`, `height`, `color`, `style`) accept `null` to **unset** the field.
+ * `undefined` (or omitting the key) leaves the field unchanged. `null` is
+ * used for unsetting so update payloads stay JSON-serializable.
+ */
+interface EdgeUpdate<TEdgeData = any> {
+  sourceId?: string;
+  targetId?: string;
+  label?: string | null;
+  data?: TEdgeData;
+  weight?: number | null;
+  mode?: GraphMode | null;
+  /** Port name on the source node, or `null` to clear the port reference. */
+  sourcePort?: string | null;
+  /** Port name on the target node, or `null` to clear the port reference. */
+  targetPort?: string | null;
+  x?: number | null;
+  y?: number | null;
+  width?: number | null;
+  height?: number | null;
+  color?: string | null;
+  style?: Record<string, string | number | boolean> | null;
+}
 interface EntitiesConfig<TNodeData = any, TEdgeData = any, TPortData = any> {
   nodes?: NodeConfig<TNodeData, TPortData>[];
   edges?: EdgeConfig<TEdgeData>[];
 }
 interface EntitiesUpdate<TNodeData = any, TEdgeData = any, TPortData = any> {
-  nodes?: (Partial<Omit<NodeConfig<TNodeData, TPortData>, 'id'>> & {
+  nodes?: (NodeUpdate<TNodeData, TPortData> & {
     id: string;
   })[];
-  edges?: (Partial<Omit<EdgeConfig<TEdgeData>, 'id'>> & {
+  edges?: (EdgeUpdate<TEdgeData> & {
     id: string;
   })[];
 }
@@ -258,7 +330,7 @@ type GraphPatch<TNodeData = any, TEdgeData = any> = {
 } | {
   op: 'updateNode';
   id: string;
-  data: Partial<Omit<NodeConfig<TNodeData>, 'id'>>;
+  data: NodeUpdate<TNodeData>;
   description?: string;
 } | {
   op: 'deleteNode';
@@ -271,7 +343,7 @@ type GraphPatch<TNodeData = any, TEdgeData = any> = {
 } | {
   op: 'updateEdge';
   id: string;
-  data: Partial<Omit<EdgeConfig<TEdgeData>, 'id'>>;
+  data: EdgeUpdate<TEdgeData>;
   description?: string;
 } | {
   op: 'deleteEdge';
@@ -352,4 +424,4 @@ interface TransitionOptions<TState, TEvent> {
   id?: string;
 }
 //#endregion
-export { VisualEdge as A, NodeConfig as C, SinglePathOptions as D, PortDirection as E, VisualNode as F, VisualPort as I, WalkContext as L, VisualGraphConfig as M, VisualGraphEntity as N, TransitionOptions as O, VisualGraphFormatConverter as P, WalkOptions as R, NodeChange as S, PortConfig as T, GraphPatch as _, EdgeChange as a, GraphStep as b, EntitiesUpdate as c, GraphConfig as d, GraphDiff as f, GraphNode as g, GraphFormatConverter as h, DeleteNodeOptions as i, VisualGraph as j, TraversalOptions as k, EntityRect as l, GraphEntity as m, AllPairsShortestPathsOptions as n, EdgeConfig as o, GraphEdge as p, CoverageStats as r, EntitiesConfig as s, AStarOptions as t, Graph as u, GraphPath as v, PathOptions as w, MSTOptions as x, GraphPort as y, WeightedWalkOptions as z };
+export { SinglePathOptions as A, WalkContext as B, MSTOptions as C, PathOptions as D, NodeUpdate as E, VisualGraphConfig as F, WeightedWalkOptions as H, VisualGraphEntity as I, VisualGraphFormatConverter as L, TraversalOptions as M, VisualEdge as N, PortConfig as O, VisualGraph as P, VisualNode as R, GraphStep as S, NodeConfig as T, WalkOptions as V, GraphMode as _, EdgeChange as a, GraphPath as b, EntitiesConfig as c, Graph as d, GraphConfig as f, GraphFormatConverter as g, GraphEntity as h, DeleteNodeOptions as i, TransitionOptions as j, PortDirection as k, EntitiesUpdate as l, GraphEdge as m, AllPairsShortestPathsOptions as n, EdgeConfig as o, GraphDiff as p, CoverageStats as r, EdgeUpdate as s, AStarOptions as t, EntityRect as u, GraphNode as v, NodeChange as w, GraphPort as x, GraphPatch as y, VisualPort as z };

package/dist/validate-TtH-x3JV.mjs

@@ -0,0 +1,190 @@
+//#region src/validate.ts
+function getDuplicateIndexes(items, getKey) {
+	const indexesByKey = /* @__PURE__ */ new Map();
+	items.forEach((item, index) => {
+		const key = getKey(item);
+		if (key == null) return;
+		const indexes = indexesByKey.get(key) ?? [];
+		indexes.push(index);
+		indexesByKey.set(key, indexes);
+	});
+	for (const [key, indexes] of indexesByKey) if (indexes.length < 2) indexesByKey.delete(key);
+	return indexesByKey;
+}
+/**
+* Returns the parent cycles in a graph's hierarchy, each cycle reported once
+* as the list of node ids forming the cycle (cycle members only — nodes whose
+* ancestry merely *leads into* a cycle are not included).
+*/
+function getParentCycles(nodesById) {
+	const cycles = [];
+	const visited = /* @__PURE__ */ new Set();
+	for (const startId of nodesById.keys()) {
+		if (visited.has(startId)) continue;
+		const path = [];
+		const positions = /* @__PURE__ */ new Map();
+		let currentId = startId;
+		while (currentId != null && !visited.has(currentId) && nodesById.has(currentId)) {
+			const position = positions.get(currentId);
+			if (position !== void 0) {
+				cycles.push(path.slice(position));
+				break;
+			}
+			positions.set(currentId, path.length);
+			path.push(currentId);
+			currentId = nodesById.get(currentId).parentId;
+		}
+		for (const id of path) visited.add(id);
+	}
+	return cycles;
+}
+/**
+* Validates the structural invariants of a graph and returns the issues
+* found, or `[]` when the graph is valid. Pure — never throws, never mutates.
+*
+* This is the recommended gate for untrusted or imported graphs (e.g. parsed
+* from a file or received over the wire) before handing them to queries and
+* algorithms: the mutation APIs (`addNode`, `addEdge`, `updateNode`, …)
+* validate incrementally, but `createGraph` does **not** — it accepts
+* dangling `parentId`/edge references and even `parentId` cycles as-is.
+*
+* For Zod-based shape validation of arbitrary unknown values, see
+* `validateGraph` in `@statelyai/graph/schemas` (which reuses these checks).
+*
+* Issue codes: `duplicate-node-id`, `duplicate-edge-id`,
+* `missing-initial-node`, `missing-parent`, `missing-node-initial`,
+* `duplicate-port-name`, `parent-cycle`, `dangling-edge-endpoint`,
+* `missing-source-port`, `missing-target-port`.
+*
+* @example
+* ```ts
+* const graph = createGraph({
+*   nodes: [{ id: 'a', parentId: 'ghost' }],
+*   edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
+* });
+* getGraphIssues(graph);
+* // => [
+* //   { code: 'missing-parent', message: '...', path: ['nodes', 0, 'parentId'] },
+* //   { code: 'dangling-edge-endpoint', message: '...', path: ['edges', 0, 'targetId'] },
+* // ]
+* ```
+*/
+function getGraphIssues(graph) {
+	const issues = [];
+	const nodeIndexes = /* @__PURE__ */ new Map();
+	const nodesById = /* @__PURE__ */ new Map();
+	graph.nodes.forEach((node, index) => {
+		nodeIndexes.set(node.id, index);
+		nodesById.set(node.id, node);
+	});
+	for (const [id, indexes] of getDuplicateIndexes(graph.nodes, (node) => node.id)) for (const index of indexes) issues.push({
+		code: "duplicate-node-id",
+		message: `Duplicate node id "${id}". Node ids must be unique; rename or remove the duplicates.`,
+		path: [
+			"nodes",
+			index,
+			"id"
+		]
+	});
+	for (const [id, indexes] of getDuplicateIndexes(graph.edges, (edge) => edge.id)) for (const index of indexes) issues.push({
+		code: "duplicate-edge-id",
+		message: `Duplicate edge id "${id}". Edge ids must be unique; rename or remove the duplicates.`,
+		path: [
+			"edges",
+			index,
+			"id"
+		]
+	});
+	if (graph.initialNodeId && !nodesById.has(graph.initialNodeId)) issues.push({
+		code: "missing-initial-node",
+		message: `Graph initialNodeId references missing node "${graph.initialNodeId}". Add that node or update the graph's initialNodeId.`,
+		path: ["initialNodeId"]
+	});
+	graph.nodes.forEach((node, index) => {
+		if (node.parentId != null && !nodesById.has(node.parentId)) issues.push({
+			code: "missing-parent",
+			message: `Node "${node.id}" has parentId "${node.parentId}", which does not exist. Add that node or remove the parentId.`,
+			path: [
+				"nodes",
+				index,
+				"parentId"
+			]
+		});
+		if (node.initialNodeId && !nodesById.has(node.initialNodeId)) issues.push({
+			code: "missing-node-initial",
+			message: `Node "${node.id}" has initialNodeId "${node.initialNodeId}", which does not exist. Add that node or remove the initialNodeId.`,
+			path: [
+				"nodes",
+				index,
+				"initialNodeId"
+			]
+		});
+		for (const [name, portIndexes] of getDuplicateIndexes(node.ports ?? [], (port) => port.name)) for (const portIndex of portIndexes) issues.push({
+			code: "duplicate-port-name",
+			message: `Duplicate port name "${name}" on node "${node.id}". Port names must be unique per node; rename or remove the duplicates.`,
+			path: [
+				"nodes",
+				index,
+				"ports",
+				portIndex,
+				"name"
+			]
+		});
+	});
+	for (const cycle of getParentCycles(nodesById)) {
+		const chain = [...cycle, cycle[0]].join(" → ");
+		issues.push({
+			code: "parent-cycle",
+			message: `Parent cycle detected: ${chain}. Break the cycle by changing the parentId of one of these nodes.`,
+			path: [
+				"nodes",
+				nodeIndexes.get(cycle[0]) ?? 0,
+				"parentId"
+			]
+		});
+	}
+	graph.edges.forEach((edge, index) => {
+		const source = nodesById.get(edge.sourceId);
+		const target = nodesById.get(edge.targetId);
+		if (!source) issues.push({
+			code: "dangling-edge-endpoint",
+			message: `Edge "${edge.id}" has sourceId "${edge.sourceId}", which references a missing node. Add that node or fix the edge's sourceId.`,
+			path: [
+				"edges",
+				index,
+				"sourceId"
+			]
+		});
+		if (!target) issues.push({
+			code: "dangling-edge-endpoint",
+			message: `Edge "${edge.id}" has targetId "${edge.targetId}", which references a missing node. Add that node or fix the edge's targetId.`,
+			path: [
+				"edges",
+				index,
+				"targetId"
+			]
+		});
+		if (source && edge.sourcePort !== void 0 && !source.ports?.some((port) => port.name === edge.sourcePort)) issues.push({
+			code: "missing-source-port",
+			message: `Edge "${edge.id}" has sourcePort "${edge.sourcePort}", but source node "${edge.sourceId}" has no port with that name. Add the port or fix the edge's sourcePort.`,
+			path: [
+				"edges",
+				index,
+				"sourcePort"
+			]
+		});
+		if (target && edge.targetPort !== void 0 && !target.ports?.some((port) => port.name === edge.targetPort)) issues.push({
+			code: "missing-target-port",
+			message: `Edge "${edge.id}" has targetPort "${edge.targetPort}", but target node "${edge.targetId}" has no port with that name. Add the port or fix the edge's targetPort.`,
+			path: [
+				"edges",
+				index,
+				"targetPort"
+			]
+		});
+	});
+	return issues;
+}
+
+//#endregion
+export { getGraphIssues as t };