sfn-diagram 1.4.0 → 1.5.0

package/dist/cli.js

@@ -209,6 +209,57 @@ function extractAslFromTemplate(params) {
 	};
 }
 //#endregion
+//#region src/config/defaults.ts
+/**
+* Default diagram options - used when options not provided
+*/
+const DEFAULT_DIAGRAM_OPTIONS = {
+	format: "svg",
+	theme: "light",
+	customColors: void 0,
+	layout: "TB",
+	rankSeparation: 50,
+	nodeSeparation: 50,
+	width: void 0,
+	height: void 0,
+	nodeWidth: 120,
+	nodeHeight: 60,
+	padding: 20,
+	includeComments: true,
+	showStateTypes: false,
+	showVariables: true,
+	edgeStyle: "curved",
+	catchHandling: "show",
+	catchLabelStyle: "error-type",
+	collapse: void 0,
+	stylePreset: "aws-standard",
+	iconPosition: "left",
+	iconResolver: void 0,
+	iconSize: 24,
+	showIcons: false,
+	pngQuality: 90,
+	backgroundColor: "transparent",
+	nodeOverrides: void 0,
+	edgeOverrides: void 0,
+	nodeAnnotations: void 0
+};
+/**
+* Merge user-provided options with defaults
+*/
+function mergeOptions(options = {}) {
+	return {
+		...DEFAULT_DIAGRAM_OPTIONS,
+		...options
+	};
+}
+function mergeRecordOptions(base, override) {
+	if (!base && !override) return void 0;
+	return {
+		...base,
+		...override
+	};
+}
+//#endregion
 //#region src/config/themes.ts
 /**
 * AWS Light Theme - matches the AWS Step Functions console light mode
@@ -320,10 +371,7 @@ function getTheme(theme, customColors) {
 	else baseTheme = theme;
 	if (customColors) return {
 		...baseTheme,
-		nodeColors: {
-			...baseTheme.nodeColors,
-			...customColors
-		}
+		nodeColors: mergeRecordOptions(baseTheme.nodeColors, customColors)
 	};
 	return baseTheme;
 }
@@ -696,6 +744,228 @@ function detectServiceFromResource(params) {
 	};
 }
 //#endregion
+//#region src/graph/collapseContainers.ts
+/** Synthetic marker node types that don't count as real states. */
+const SYNTHETIC_MARKER_TYPES = new Set(["BranchEnd", "IteratorEnd"]);
+/**
+* Resolve a collapse selection against a graph: which containers end up with a
+* placeholder, and which node ids each one hides. Shared by {@link applyCollapse}
+* (which rewrites the graph) and callers that only need to know what a collapse
+* *would* do — e.g. deciding whether a second render is worth paying for, or
+* checking whether a diff-changed state falls inside a placeholder.
+*
+* Descendant membership is derived by walking `StateNode.children` recursively —
+* `parent` is never populated by the parser, and a container's own `children` only
+* lists its direct level (entry state, end marker, direct branch/iterator states),
+* not further-nested containers' own descendants. Recursing into any visited child
+* that `isContainer` produces the full multi-level closure.
+*/
+function computeCollapsePlan(params) {
+	const { collapse, edges, nodes } = params;
+	const nodesById = new Map(nodes.map((node) => [node.id, node]));
+	const containerIds = new Set(nodes.filter((node) => node.isContainer).map((node) => node.id));
+	const requestedTargets = !collapse ? /* @__PURE__ */ new Set() : collapse === true ? containerIds : new Set(collapse.filter((name) => containerIds.has(name)));
+	if (requestedTargets.size === 0) return {
+		effectiveTargets: requestedTargets,
+		hiddenIdsByTarget: /* @__PURE__ */ new Map(),
+		removedIds: /* @__PURE__ */ new Set()
+	};
+	const closureFor = (containerId) => {
+		const closure = /* @__PURE__ */ new Set();
+		const queue = [...nodesById.get(containerId)?.children ?? []];
+		while (queue.length > 0) {
+			const currentId = queue.shift();
+			if (closure.has(currentId)) continue;
+			closure.add(currentId);
+			const current = nodesById.get(currentId);
+			if (current?.isContainer) queue.push(...current.children ?? []);
+		}
+		return closure;
+	};
+	const hiddenIdsByTarget = /* @__PURE__ */ new Map();
+	const removedIds = /* @__PURE__ */ new Set();
+	for (const targetId of requestedTargets) {
+		const closure = closureFor(targetId);
+		hiddenIdsByTarget.set(targetId, closure);
+		for (const id of closure) removedIds.add(id);
+	}
+	for (const edge of edges) {
+		const fromNode = nodesById.get(edge.from);
+		const toNode = nodesById.get(edge.to);
+		if (fromNode && MAP_IO_NODE_TYPES.has(fromNode.type) && removedIds.has(edge.to)) removedIds.add(edge.from);
+		if (toNode && MAP_IO_NODE_TYPES.has(toNode.type) && removedIds.has(edge.from)) removedIds.add(edge.to);
+	}
+	return {
+		effectiveTargets: new Set([...requestedTargets].filter((targetId) => !removedIds.has(targetId))),
+		hiddenIdsByTarget,
+		removedIds
+	};
+}
+/**
+* Replace each targeted Parallel/Map container's subgraph with a placeholder node.
+*
+* No edge is ever rerouted, only deleted: every edge that should still exist after
+* a collapse already targets the container's own id (external entry edges, the
+* container -> Next visual edge, and Catch/Retry on the container state are all
+* anchored at the container id by `AslParser`, never at a descendant).
+*/
+function applyCollapse(params) {
+	const { collapse, edges, nodes } = params;
+	if (!collapse) return {
+		edges,
+		nodes
+	};
+	const { effectiveTargets, hiddenIdsByTarget, removedIds } = computeCollapsePlan({
+		collapse,
+		edges,
+		nodes
+	});
+	if (effectiveTargets.size === 0) return {
+		edges,
+		nodes
+	};
+	const nodesById = new Map(nodes.map((node) => [node.id, node]));
+	const resultNodes = nodes.filter((node) => !removedIds.has(node.id)).map((node) => {
+		if (!effectiveTargets.has(node.id)) return node;
+		const closure = hiddenIdsByTarget.get(node.id);
+		let collapsedCount = 0;
+		for (const id of closure) {
+			const descendant = nodesById.get(id);
+			if (descendant && !SYNTHETIC_MARKER_TYPES.has(descendant.type)) collapsedCount += 1;
+		}
+		return {
+			...node,
+			children: [],
+			collapsed: true,
+			collapsedCount
+		};
+	});
+	return {
+		edges: edges.filter((edge) => !removedIds.has(edge.from) && !removedIds.has(edge.to)),
+		nodes: resultNodes
+	};
+}
+//#endregion
+//#region src/graph/catchHandling.ts
+/**
+* Apply catch-branch handling to a parsed graph.
+*
+* In 'hide' mode, removes every error edge and then any node that is not
+* reachable from the start state by following the remaining (non-error) edges.
+* This drops catch-handler chains entirely, including ones that only reference
+* each other (e.g. a cyclic handler chain unreachable from the happy path), since
+* reachability is computed with a single forward pass from the start state rather
+* than an incoming-edge check. If no start state id is provided, every node that
+* still has a surviving incoming or outgoing edge is kept instead. In 'show' mode
+* the graph is returned unchanged.
+*
+* Distributed Map `ItemReader` / `ResultWriter` satellites are exempt from the
+* forward-reachability rule: they are attached to their Map structurally, and an
+* ItemReader is a graph source that no forward pass can reach. Each is kept
+* whenever the node it connects to survives.
+*/
+function applyCatchHandling(params) {
+	const { edges, mode, nodes, startStateId } = params;
+	if (mode === "show") return {
+		edges,
+		nodes
+	};
+	const keptEdges = edges.filter((edge) => edge.type !== "error");
+	let reachableIds;
+	if (startStateId !== void 0) {
+		const adjacency = /* @__PURE__ */ new Map();
+		for (const edge of keptEdges) {
+			const targets = adjacency.get(edge.from);
+			if (targets) targets.push(edge.to);
+			else adjacency.set(edge.from, [edge.to]);
+		}
+		reachableIds = new Set([startStateId]);
+		const queue = [startStateId];
+		while (queue.length > 0) {
+			const currentId = queue.shift();
+			for (const targetId of adjacency.get(currentId) ?? []) if (!reachableIds.has(targetId)) {
+				reachableIds.add(targetId);
+				queue.push(targetId);
+			}
+		}
+	} else {
+		reachableIds = /* @__PURE__ */ new Set();
+		for (const edge of keptEdges) {
+			reachableIds.add(edge.from);
+			reachableIds.add(edge.to);
+		}
+	}
+	const nodesById = new Map(nodes.map((node) => [node.id, node]));
+	for (const edge of keptEdges) {
+		const source = nodesById.get(edge.from);
+		if (source && MAP_IO_NODE_TYPES.has(source.type) && reachableIds.has(edge.to)) reachableIds.add(edge.from);
+	}
+	const survivingNodes = nodes.filter((node) => reachableIds.has(node.id));
+	const survivingIds = new Set(survivingNodes.map((node) => node.id));
+	return {
+		edges: keptEdges.filter((edge) => survivingIds.has(edge.from) && survivingIds.has(edge.to)),
+		nodes: survivingNodes
+	};
+}
+//#endregion
+//#region src/graph/containers.ts
+/**
+* True for a container node that is still drawn as a group with its own child
+* nodes — a collapsed container is a plain placeholder node instead, and every
+* layout/render call site that branches on "is this an open container" needs
+* both halves of that check.
+*/
+function isOpenContainer(node) {
+	return node.isContainer === true && !node.collapsed;
+}
+//#endregion
+//#region src/graph/edgeIdentity.ts
+/**
+* Stamp each edge with a stable identity, unique across the whole graph.
+*
+* Several legitimate ASL shapes produce two edges with the same `from`/`to` — two
+* Choice rules sharing a `Next`, a `Retry` self-loop beside a genuine self-transition,
+* a `Catch` pointing back at its own state. Without a discriminator those edges collapse
+* onto one dagre edge, one routing path, and one `edgeOverrides` key.
+*
+* The id is `${from}->${to}#${type}#${ordinal}`, where `type` falls back to `'normal'`
+* and `ordinal` counts edges already seen with that same `(from, to, type)` triple.
+* Normalizing the type before counting matters: an edge with no `type` and one typed
+* `'normal'` must share a counter, or they would render identical ids.
+*
+* Run this once, over the fully assembled edge array, so ordinals are global and
+* deterministic. Downstream transforms (`applyCollapse`, `applyCatchHandling`) only
+* filter edges, so ids survive them untouched — gaps in the ordinal sequence are
+* intentional, since renumbering would silently invalidate a caller's override key.
+*
+* @param params - Object parameters
+* @param params.edges - Every edge in the graph, in parser order
+* @returns The same edges, in the same order, each with an `id`
+*
+* @example
+* ```typescript
+* assignEdgeIds({ edges: [
+*     { from: 'Route', to: 'Work', type: 'choice' },
+*     { from: 'Route', to: 'Work', type: 'choice' },
+* ] });
+* // ids: 'Route->Work#choice#0', 'Route->Work#choice#1'
+* ```
+*/
+function assignEdgeIds(params) {
+	const { edges } = params;
+	const ordinals = /* @__PURE__ */ new Map();
+	return edges.map((edge) => {
+		const type = edge.type ?? "normal";
+		const pairKey = `${edge.from}->${edge.to}#${type}`;
+		const ordinal = ordinals.get(pairKey) ?? 0;
+		ordinals.set(pairKey, ordinal + 1);
+		return {
+			...edge,
+			id: `${pairKey}#${ordinal}`
+		};
+	});
+}
+//#endregion
 //#region src/AslParser.ts
 /**
 * Error thrown when ASL validation fails
@@ -803,7 +1073,7 @@ function parseAsl(params) {
 		options
 	});
 	return {
-		edges,
+		edges: assignEdgeIds({ edges }),
 		nodes
 	};
 }
@@ -1217,182 +1487,12 @@ function extractNestedEdges(params) {
 	}
 }
 //#endregion
-//#region src/graph/collapseContainers.ts
-/** Synthetic marker node types that don't count as real states. */
-const SYNTHETIC_MARKER_TYPES = new Set(["BranchEnd", "IteratorEnd"]);
-/**
-* Resolve a collapse selection against a graph: which containers end up with a
-* placeholder, and which node ids each one hides. Shared by {@link applyCollapse}
-* (which rewrites the graph) and callers that only need to know what a collapse
-* *would* do — e.g. deciding whether a second render is worth paying for, or
-* checking whether a diff-changed state falls inside a placeholder.
-*
-* Descendant membership is derived by walking `StateNode.children` recursively —
-* `parent` is never populated by the parser, and a container's own `children` only
-* lists its direct level (entry state, end marker, direct branch/iterator states),
-* not further-nested containers' own descendants. Recursing into any visited child
-* that `isContainer` produces the full multi-level closure.
-*/
-function computeCollapsePlan(params) {
-	const { collapse, edges, nodes } = params;
-	const nodesById = new Map(nodes.map((node) => [node.id, node]));
-	const containerIds = new Set(nodes.filter((node) => node.isContainer).map((node) => node.id));
-	const requestedTargets = !collapse ? /* @__PURE__ */ new Set() : collapse === true ? containerIds : new Set(collapse.filter((name) => containerIds.has(name)));
-	if (requestedTargets.size === 0) return {
-		effectiveTargets: requestedTargets,
-		hiddenIdsByTarget: /* @__PURE__ */ new Map(),
-		removedIds: /* @__PURE__ */ new Set()
-	};
-	const closureFor = (containerId) => {
-		const closure = /* @__PURE__ */ new Set();
-		const queue = [...nodesById.get(containerId)?.children ?? []];
-		while (queue.length > 0) {
-			const currentId = queue.shift();
-			if (closure.has(currentId)) continue;
-			closure.add(currentId);
-			const current = nodesById.get(currentId);
-			if (current?.isContainer) queue.push(...current.children ?? []);
-		}
-		return closure;
-	};
-	const hiddenIdsByTarget = /* @__PURE__ */ new Map();
-	const removedIds = /* @__PURE__ */ new Set();
-	for (const targetId of requestedTargets) {
-		const closure = closureFor(targetId);
-		hiddenIdsByTarget.set(targetId, closure);
-		for (const id of closure) removedIds.add(id);
-	}
-	for (const edge of edges) {
-		const fromNode = nodesById.get(edge.from);
-		const toNode = nodesById.get(edge.to);
-		if (fromNode && MAP_IO_NODE_TYPES.has(fromNode.type) && removedIds.has(edge.to)) removedIds.add(edge.from);
-		if (toNode && MAP_IO_NODE_TYPES.has(toNode.type) && removedIds.has(edge.from)) removedIds.add(edge.to);
-	}
-	return {
-		effectiveTargets: new Set([...requestedTargets].filter((targetId) => !removedIds.has(targetId))),
-		hiddenIdsByTarget,
-		removedIds
-	};
-}
-/**
-* Replace each targeted Parallel/Map container's subgraph with a placeholder node.
-*
-* No edge is ever rerouted, only deleted: every edge that should still exist after
-* a collapse already targets the container's own id (external entry edges, the
-* container -> Next visual edge, and Catch/Retry on the container state are all
-* anchored at the container id by `AslParser`, never at a descendant).
-*/
-function applyCollapse(params) {
-	const { collapse, edges, nodes } = params;
-	if (!collapse) return {
-		edges,
-		nodes
-	};
-	const { effectiveTargets, hiddenIdsByTarget, removedIds } = computeCollapsePlan({
-		collapse,
-		edges,
-		nodes
-	});
-	if (effectiveTargets.size === 0) return {
-		edges,
-		nodes
-	};
-	const nodesById = new Map(nodes.map((node) => [node.id, node]));
-	const resultNodes = nodes.filter((node) => !removedIds.has(node.id)).map((node) => {
-		if (!effectiveTargets.has(node.id)) return node;
-		const closure = hiddenIdsByTarget.get(node.id);
-		let collapsedCount = 0;
-		for (const id of closure) {
-			const descendant = nodesById.get(id);
-			if (descendant && !SYNTHETIC_MARKER_TYPES.has(descendant.type)) collapsedCount += 1;
-		}
-		return {
-			...node,
-			children: [],
-			collapsed: true,
-			collapsedCount
-		};
-	});
-	return {
-		edges: edges.filter((edge) => !removedIds.has(edge.from) && !removedIds.has(edge.to)),
-		nodes: resultNodes
-	};
-}
-//#endregion
-//#region src/graph/catchHandling.ts
-/**
-* Apply catch-branch handling to a parsed graph.
-*
-* In 'hide' mode, removes every error edge and then any node that is not
-* reachable from the start state by following the remaining (non-error) edges.
-* This drops catch-handler chains entirely, including ones that only reference
-* each other (e.g. a cyclic handler chain unreachable from the happy path), since
-* reachability is computed with a single forward pass from the start state rather
-* than an incoming-edge check. If no start state id is provided, every node that
-* still has a surviving incoming or outgoing edge is kept instead. In 'show' mode
-* the graph is returned unchanged.
-*
-* Distributed Map `ItemReader` / `ResultWriter` satellites are exempt from the
-* forward-reachability rule: they are attached to their Map structurally, and an
-* ItemReader is a graph source that no forward pass can reach. Each is kept
-* whenever the node it connects to survives.
-*/
-function applyCatchHandling(params) {
-	const { edges, mode, nodes, startStateId } = params;
-	if (mode === "show") return {
-		edges,
-		nodes
-	};
-	const keptEdges = edges.filter((edge) => edge.type !== "error");
-	let reachableIds;
-	if (startStateId !== void 0) {
-		const adjacency = /* @__PURE__ */ new Map();
-		for (const edge of keptEdges) {
-			const targets = adjacency.get(edge.from);
-			if (targets) targets.push(edge.to);
-			else adjacency.set(edge.from, [edge.to]);
-		}
-		reachableIds = new Set([startStateId]);
-		const queue = [startStateId];
-		while (queue.length > 0) {
-			const currentId = queue.shift();
-			for (const targetId of adjacency.get(currentId) ?? []) if (!reachableIds.has(targetId)) {
-				reachableIds.add(targetId);
-				queue.push(targetId);
-			}
-		}
-	} else {
-		reachableIds = /* @__PURE__ */ new Set();
-		for (const edge of keptEdges) {
-			reachableIds.add(edge.from);
-			reachableIds.add(edge.to);
-		}
-	}
-	const nodesById = new Map(nodes.map((node) => [node.id, node]));
-	for (const edge of keptEdges) {
-		const source = nodesById.get(edge.from);
-		if (source && MAP_IO_NODE_TYPES.has(source.type) && reachableIds.has(edge.to)) reachableIds.add(edge.from);
-	}
-	const survivingNodes = nodes.filter((node) => reachableIds.has(node.id));
-	const survivingIds = new Set(survivingNodes.map((node) => node.id));
-	return {
-		edges: keptEdges.filter((edge) => survivingIds.has(edge.from) && survivingIds.has(edge.to)),
-		nodes: survivingNodes
-	};
-}
-//#endregion
-//#region src/graph/containers.ts
-/**
-* True for a container node that is still drawn as a group with its own child
-* nodes — a collapsed container is a plain placeholder node instead, and every
-* layout/render call site that branches on "is this an open container" needs
-* both halves of that check.
-*/
-function isOpenContainer(node) {
-	return node.isContainer === true && !node.collapsed;
-}
-//#endregion
 //#region src/layout/DagreLayout.ts
+/** Self-loop arc geometry. Each additional loop on a node nests one step further out. */
+const LOOP_BASE_REACH = 40;
+const LOOP_REACH_STEP = 22;
+const LOOP_BASE_SPREAD = 12;
+const LOOP_SPREAD_STEP = 5;
 /**
 * DagreLayout - Calculates node positions and edge routing using Dagre algorithm
 */
@@ -1405,7 +1505,7 @@ var DagreLayout = class {
 	* Calculate layout positions for nodes and edges
 	*/
 	calculate(nodes, edges) {
-		const graph = new dagre.graphlib.Graph();
+		const graph = new dagre.graphlib.Graph({ multigraph: true });
 		graph.setGraph({
 			marginx: this.options.padding || 20,
 			marginy: this.options.padding || 20,
@@ -1443,14 +1543,14 @@ var DagreLayout = class {
 				for (const child of entryChildrenByContainer.get(edge.to) ?? []) graph.setEdge(edge.from, child, {
 					label: edge.label,
 					type: edge.type
-				});
+				}, `${edge.id}#entry#${child}`);
 				return;
 			}
 			if (fromIsContainer || toIsContainer) return;
 			graph.setEdge(edge.from, edge.to, {
 				label: edge.label,
 				type: edge.type
-			});
+			}, edge.id);
 		});
 		dagre.layout(graph);
 		const positionedNodes = layoutNodes.map((node) => {
@@ -1470,18 +1570,29 @@ var DagreLayout = class {
 		});
 		const allPositionedNodes = [...positionedNodes, ...containerNodes];
 		const positionedNodesById = new Map(allPositionedNodes.map((node) => [node.id, node]));
+		const loopIndexById = /* @__PURE__ */ new Map();
+		const loopCountByNode = /* @__PURE__ */ new Map();
+		for (const edge of edges) {
+			if (edge.from !== edge.to) continue;
+			const loopIndex = loopCountByNode.get(edge.from) ?? 0;
+			loopIndexById.set(edge.id, loopIndex);
+			loopCountByNode.set(edge.from, loopIndex + 1);
+		}
 		const routedEdges = edges.map((edge) => {
 			const fromNode = positionedNodesById.get(edge.from);
 			const toNode = positionedNodesById.get(edge.to);
 			const touchesContainer = Boolean(fromNode && isOpenContainer(fromNode) || toNode && isOpenContainer(toNode));
-			if (edge.visualOnly || touchesContainer || edge.from === edge.to) return {
+			const isSelfLoop = edge.from === edge.to;
+			if (edge.visualOnly || touchesContainer || isSelfLoop) return {
 				...edge,
+				...isSelfLoop ? { loopIndex: loopIndexById.get(edge.id) ?? 0 } : {},
 				points: this.calculateVisualEdgePoints({
 					edge,
+					loopIndex: loopIndexById.get(edge.id) ?? 0,
 					positionedNodesById
 				})
 			};
-			const dagEdge = graph.edge(edge.from, edge.to);
+			const dagEdge = graph.edge(edge.from, edge.to, edge.id);
 			return {
 				...edge,
 				points: dagEdge?.points ?? []
@@ -1548,14 +1659,14 @@ var DagreLayout = class {
 	* Calculate routing points for visual-only edges
 	*/
 	calculateVisualEdgePoints(params) {
-		const { edge, positionedNodesById } = params;
+		const { edge, loopIndex, positionedNodesById } = params;
 		const fromNode = positionedNodesById.get(edge.from);
 		const toNode = positionedNodesById.get(edge.to);
 		if (!fromNode || !toNode) return [];
 		if (edge.from === edge.to) {
 			const rankdir = this.options.layout || "TB";
-			const loopReach = 40;
-			const loopSpread = 12;
+			const loopReach = LOOP_BASE_REACH + loopIndex * LOOP_REACH_STEP;
+			const loopSpread = LOOP_BASE_SPREAD + loopIndex * LOOP_SPREAD_STEP;
 			if (rankdir === "LR" || rankdir === "RL") {
 				const topY = (fromNode.y || 0) - (fromNode.height || 0) / 2;
 				const centerX = fromNode.x || 0;
@@ -1698,11 +1809,14 @@ function estimateTextWidth(text, fontSize) {
 /**
 * Escape a string for use as a double-quoted HTML attribute value.
 *
-* Matches the HTML serialization algorithm: only `&`, U+00A0, and `"` are escaped
-* (`<` and `>` are intentionally left untouched inside attribute values).
+* Goes one step further than the HTML serialization algorithm, which leaves `<` and
+* `>` untouched inside attribute values. An edge id is `${from}->${to}#...`, so a raw
+* `>` would put a tag-looking character inside every edge's `data-edge-id` and break
+* the `<path[^>]*>` style scans callers run over the serialized SVG. The escaping is
+* transparent to any XML/DOM parser, which hands back the original string.
 */
 function escapeAttribute(value) {
-	return value.replace(/&/g, "&amp;").replace(/\u00A0/g, "&nbsp;").replace(/"/g, "&quot;");
+	return value.replace(/&/g, "&amp;").replace(/\u00A0/g, "&nbsp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 /**
 * Escape a string for use as element text content.
@@ -1772,7 +1886,11 @@ var SvgRenderer = class {
 	* Render the diagram to SVG string
 	*/
 	render(layout) {
-		const bounds = this.calculateBounds(layout);
+		const selfLoopLabelWidths = this.calculateSelfLoopLabelWidths(layout.edges);
+		const bounds = this.calculateBounds({
+			layout,
+			selfLoopLabelWidths
+		});
 		const svg = new SvgElement("svg").attr("width", bounds.width).attr("height", bounds.height).attr("xmlns", "http://www.w3.org/2000/svg").attr("viewBox", `${bounds.minX} ${bounds.minY} ${bounds.width} ${bounds.height}`);
 		if (this.theme.background && this.theme.background !== "transparent") svg.append("rect").attr("x", bounds.minX).attr("y", bounds.minY).attr("width", bounds.width).attr("height", bounds.height).attr("fill", this.theme.background);
 		const defs = svg.append("defs");
@@ -1793,7 +1911,8 @@ var SvgRenderer = class {
 			this.renderEdge({
 				edge,
 				group: edgesGroup,
-				nodes: layout.nodes
+				nodes: layout.nodes,
+				selfLoopLabelWidths
 			});
 		});
 		containerNodes.forEach((node) => {
@@ -1821,7 +1940,8 @@ var SvgRenderer = class {
 	/**
 	* Calculate bounding box including all nodes and edge points
 	*/
-	calculateBounds(layout) {
+	calculateBounds(params) {
+		const { layout, selfLoopLabelWidths } = params;
 		let minX = Infinity;
 		let minY = Infinity;
 		let maxX = -Infinity;
@@ -1843,7 +1963,11 @@ var SvgRenderer = class {
 				maxY = Math.max(maxY, point.y);
 			});
 			if (edge.label && edge.points && edge.points.length > 0) {
-				const midpoint = this.edgeLabelCenter(edge, layout.nodes);
+				const midpoint = this.edgeLabelCenter({
+					edge,
+					nodes: layout.nodes,
+					selfLoopLabelWidths
+				});
 				const labelDimensions = this.calculateLabelDimensions(edge.label);
 				const labelMinX = midpoint.x - labelDimensions.width / 2;
 				const labelMaxX = midpoint.x + labelDimensions.width / 2;
@@ -2032,21 +2156,30 @@ var SvgRenderer = class {
 	* Render an edge
 	*/
 	renderEdge(params) {
-		const { edge, group, nodes } = params;
+		const { edge, group, nodes, selfLoopLabelWidths } = params;
 		if (!edge.points || edge.points.length < 2) return;
 		const edgeColor = this.resolveEdgeColor(edge.type);
 		const markerType = edge.type || "normal";
 		const pathData = edge.from === edge.to ? this.buildSelfLoopPath(edge.points) : this.pathGenerator(edge.points) ?? "";
-		const override = this.options.edgeOverrides?.[`${edge.from}->${edge.to}`];
+		const broadOverride = this.options.edgeOverrides?.[`${edge.from}->${edge.to}`];
+		const exactOverride = this.options.edgeOverrides?.[edge.id];
+		const override = broadOverride || exactOverride ? {
+			...broadOverride,
+			...exactOverride
+		} : void 0;
 		const strokeColor = override?.stroke ?? edgeColor;
 		const strokeWidth = override?.strokeWidth ?? (edge.type === "error" ? 2 : 1.5);
-		const pathElement = group.append("path").attr("d", pathData).attr("fill", "none").attr("stroke", strokeColor).attr("stroke-width", strokeWidth).attr("marker-end", `url(#arrowhead-${markerType})`);
+		const pathElement = group.append("path").attr("d", pathData).attr("data-edge-id", edge.id).attr("fill", "none").attr("stroke", strokeColor).attr("stroke-width", strokeWidth).attr("marker-end", `url(#arrowhead-${markerType})`);
 		if (override?.strokeOpacity !== void 0) pathElement.attr("stroke-opacity", override.strokeOpacity);
 		if (edge.type === "error") pathElement.attr("stroke-dasharray", "5,5");
 		else if (edge.type === "default") pathElement.attr("stroke-dasharray", "8,4");
 		else if (edge.type === "retry") pathElement.attr("stroke-dasharray", "4,3");
 		if (edge.label) {
-			const midpoint = this.edgeLabelCenter(edge, nodes);
+			const midpoint = this.edgeLabelCenter({
+				edge,
+				nodes,
+				selfLoopLabelWidths
+			});
 			const labelDimensions = this.calculateLabelDimensions(edge.label);
 			group.append("rect").attr("x", midpoint.x - labelDimensions.width / 2).attr("y", midpoint.y - labelDimensions.height / 2).attr("width", labelDimensions.width).attr("height", labelDimensions.height).attr("fill", this.theme.background || "#ffffff").attr("stroke", edgeColor).attr("stroke-width", .5).attr("rx", 3);
 			group.append("text").attr("x", midpoint.x).attr("y", midpoint.y).attr("text-anchor", "middle").attr("dominant-baseline", "middle").attr("fill", edgeColor).attr("font-size", this.theme.fontSize - 2).text(edge.label);
@@ -2073,16 +2206,40 @@ var SvgRenderer = class {
 	* path midpoint; self-loops anchor off the loop's apex instead, falling back to a
 	* spot clear of neighbouring nodes if the default placement would land on one.
 	*/
-	edgeLabelCenter(edge, nodes = []) {
+	edgeLabelCenter(params) {
+		const { edge, nodes, selfLoopLabelWidths } = params;
 		const points = edge.points ?? [];
 		if (edge.from === edge.to && edge.label && points.length >= 3) return this.selfLoopLabelCenter({
 			edge,
 			nodes,
-			points
+			points,
+			selfLoopLabelWidths
 		});
 		return this.getPathMidpoint(points);
 	}
 	/**
+	* Measure the widest self-loop label on each node, keyed by the looping node's id.
+	*
+	* `selfLoopLabelCenter` staggers nested self-loop labels by one step per loop index,
+	* and a step only guarantees separation if it is at least as large as the labels it
+	* is separating. Label *height* is fixed by the font size, so the horizontal-bulge
+	* arm can step by its own label's height safely; label *width* is per-edge, so the
+	* vertical-bulge arm has to step by the widest label on the node instead of its own.
+	*
+	* @param edges - Every routed edge in the layout
+	* @returns Widest measured label width per looping node id; nodes with no labelled
+	*   self-loop are absent
+	*/
+	calculateSelfLoopLabelWidths(edges) {
+		const widths = /* @__PURE__ */ new Map();
+		for (const edge of edges) {
+			if (edge.from !== edge.to || !edge.label) continue;
+			const { width } = this.calculateLabelDimensions(edge.label);
+			widths.set(edge.from, Math.max(widths.get(edge.from) ?? 0, width));
+		}
+		return widths;
+	}
+	/**
 	* Self-loop labels can't use the path midpoint the way normal edges do: for a
 	* 3-point self-loop path the midpoint *is* the apex, but the apex is a Bezier
 	* *control* point that `buildSelfLoopPath` never actually draws through. The
@@ -2091,12 +2248,28 @@ var SvgRenderer = class {
 	* If that would overlap another node - a tight nodesep can leave less room than
 	* the loop needs - the label is stacked on the loop's other axis instead, staying
 	* over the looping node's own footprint rather than reaching toward a neighbour.
+	*
+	* Nested loops on the same node all bulge along the same axis and land on the same
+	* peak coordinate along that axis, so without further adjustment their labels would
+	* sit exactly on top of one another. `edge.loopIndex` (stamped by DagreLayout for
+	* self-loops) staggers each loop's label one step further along the axis
+	* *perpendicular* to the bulge, so nested loops fan their labels apart the same way
+	* they fan their arcs. Index 0 gets a zero offset, so a node with exactly one loop
+	* renders in exactly the same place as before loopIndex existed.
+	*
+	* The step has to be a quantity shared by every loop on the node, not each edge's
+	* own label size, or a short inner label can land inside a long outer one's rect and
+	* occlude it. Height is shared already (fixed font size); width is not, so the
+	* vertical-bulge arm steps by the node's widest self-loop label
+	* (`selfLoopLabelWidths`) rather than by this edge's width.
 	*/
 	selfLoopLabelCenter(params) {
-		const { edge, nodes, points } = params;
+		const { edge, nodes, points, selfLoopLabelWidths } = params;
 		const [entry, apex, exit] = points;
 		const gap = 8;
 		const { width: labelWidth, height: labelHeight } = this.calculateLabelDimensions(edge.label ?? "");
+		const loopIndex = edge.loopIndex ?? 0;
+		const widthStep = (selfLoopLabelWidths.get(edge.from) ?? labelWidth) + gap;
 		const peak = {
 			x: entry.x * .125 + apex.x * .75 + exit.x * .125,
 			y: entry.y * .125 + apex.y * .75 + exit.y * .125
@@ -2104,9 +2277,9 @@ var SvgRenderer = class {
 		const bulgesHorizontally = Math.abs(apex.x - entry.x) >= Math.abs(apex.y - entry.y);
 		const primary = bulgesHorizontally ? {
 			x: peak.x + gap + labelWidth / 2,
-			y: peak.y
+			y: peak.y + loopIndex * (labelHeight + gap)
 		} : {
-			x: peak.x,
+			x: peak.x + loopIndex * widthStep,
 			y: peak.y - gap - labelHeight / 2
 		};
 		const otherNodes = nodes.filter((node) => node.id !== edge.from);
@@ -2118,10 +2291,10 @@ var SvgRenderer = class {
 		const loopingNode = nodes.find((node) => node.id === edge.from);
 		if (bulgesHorizontally) return {
 			x: loopingNode?.x ?? peak.x,
-			y: (loopingNode?.y ?? peak.y) + (loopingNode?.height || 0) / 2 + gap + labelHeight / 2
+			y: (loopingNode?.y ?? peak.y) + (loopingNode?.height || 0) / 2 + gap + labelHeight / 2 + loopIndex * (labelHeight + gap)
 		};
 		return {
-			x: peak.x + gap + labelWidth / 2,
+			x: peak.x + gap + labelWidth / 2 + loopIndex * widthStep,
 			y: peak.y
 		};
 	}
@@ -2687,50 +2860,6 @@ ${stateDataScript}<script>${buildViewerScript({ hasStateData })}<\/script>
 </html>`;
 }
 //#endregion
-//#region src/config/defaults.ts
-/**
-* Default diagram options - used when options not provided
-*/
-const DEFAULT_DIAGRAM_OPTIONS = {
-	format: "svg",
-	theme: "light",
-	customColors: void 0,
-	layout: "TB",
-	rankSeparation: 50,
-	nodeSeparation: 50,
-	width: void 0,
-	height: void 0,
-	nodeWidth: 120,
-	nodeHeight: 60,
-	padding: 20,
-	includeComments: true,
-	showStateTypes: false,
-	showVariables: true,
-	edgeStyle: "curved",
-	catchHandling: "show",
-	catchLabelStyle: "error-type",
-	collapse: void 0,
-	stylePreset: "aws-standard",
-	iconPosition: "left",
-	iconResolver: void 0,
-	iconSize: 24,
-	showIcons: false,
-	pngQuality: 90,
-	backgroundColor: "transparent",
-	nodeOverrides: void 0,
-	edgeOverrides: void 0,
-	nodeAnnotations: void 0
-};
-/**
-* Merge user-provided options with defaults
-*/
-function mergeOptions(options = {}) {
-	return {
-		...DEFAULT_DIAGRAM_OPTIONS,
-		...options
-	};
-}
-//#endregion
 //#region src/utils/iconEmbedder.ts
 /** Default timeout for icon fetch operations in milliseconds */
 const DEFAULT_FETCH_TIMEOUT_MS = 5e3;
@@ -3096,6 +3225,16 @@ function computeOverlay(history) {
 * @param params - Any additional {@link DiagramOptions}
 * @returns {@link ExecutionOutput} with SVG markup and a per-status summary
 *
+* @remarks
+* A caller-supplied `edgeOverrides` / `nodeAnnotations` / `nodeOverrides` entry wins
+* over the overlay's computed value for that same key; every key the caller does not
+* name keeps the overlay's styling. A legacy bare `${from}->${to}` edge key claims
+* every edge between that pair, suppressing the overlay's own styling for all of them.
+*
+* Execution history records transitions as `{ from, to }` only, so two Choice rules
+* sharing a `Next` are both highlighted when either fires. `Retry` self-loops are
+* never highlighted — retries emit no transition event.
+*
 * @example
 * ```typescript
 * import { generateExecution } from 'sfn-diagram';
@@ -3103,7 +3242,7 @@ function computeOverlay(history) {
 * ```
 */
 function generateExecution(params) {
-	const { aslDefinition, history, ...options } = params;
+	const { aslDefinition, edgeOverrides: callerEdgeOverrides, history, nodeAnnotations: callerNodeAnnotations, nodeOverrides: callerNodeOverrides, ...options } = params;
 	const aslObj = typeof aslDefinition === "string" ? JSON.parse(aslDefinition) : aslDefinition;
 	const overlay = computeOverlay(history);
 	const mergedOptions = mergeOptions(options);
@@ -3122,17 +3261,21 @@ function generateExecution(params) {
 			if (annotation) nodeAnnotations[node.id] = annotation;
 		}
 	}
+	const pairKeys = new Set(edges.map((edge) => `${edge.from}->${edge.to}`));
+	const callerBarePairs = new Set(Object.keys(callerEdgeOverrides ?? {}).filter((key) => pairKeys.has(key)));
 	const takenKeys = new Set(overlay.takenEdges.map((edge) => `${edge.from}->${edge.to}`));
 	const edgeOverrides = {};
 	for (const edge of edges) {
-		const key = `${edge.from}->${edge.to}`;
-		edgeOverrides[key] = takenKeys.has(key) ? TAKEN_EDGE_STYLE : UNTAKEN_EDGE_STYLE;
+		const pairKey = `${edge.from}->${edge.to}`;
+		if (callerBarePairs.has(pairKey)) continue;
+		const isTaken = edge.type !== "retry" && takenKeys.has(pairKey);
+		edgeOverrides[edge.id] = isTaken ? TAKEN_EDGE_STYLE : UNTAKEN_EDGE_STYLE;
 	}
 	const renderOptions = {
 		...mergedOptions,
-		edgeOverrides,
-		nodeAnnotations,
-		nodeOverrides
+		edgeOverrides: mergeRecordOptions(edgeOverrides, callerEdgeOverrides),
+		nodeAnnotations: mergeRecordOptions(nodeAnnotations, callerNodeAnnotations),
+		nodeOverrides: mergeRecordOptions(nodeOverrides, callerNodeOverrides)
 	};
 	const positioned = new DagreLayout(renderOptions).calculate(nodes, edges);
 	const svgOutput = new SvgRenderer(renderOptions).render(positioned);
@@ -3648,14 +3791,8 @@ function generateDiff(params) {
 	}
 	const svgOutput = generateSvg({
 		aslDefinition: mergedAsl,
-		nodeAnnotations: {
-			...containerAnnotations,
-			...callerAnnotations
-		},
-		nodeOverrides: {
-			...nodeOverrides,
-			...callerOverrides
-		},
+		nodeAnnotations: mergeRecordOptions(containerAnnotations, callerAnnotations),
+		nodeOverrides: mergeRecordOptions(nodeOverrides, callerOverrides),
 		...options
 	});
 	return {