sfn-diagram 0.6.0 → 0.7.0

package/README.md

@@ -8,11 +8,62 @@ Generate beautiful, interactive diagrams from AWS Step Functions ASL (Amazon Sta
 
 **▶ [Try it in the live playground](https://yusufaf.github.io/sfn-diagram/)** — paste any ASL definition and preview the diagram instantly, no install required.
 
+## What it looks like
+
+Give it an ASL definition like this order-processing workflow ([`examples/order-processing.asl.json`](examples/order-processing.asl.json)):
+
+```jsonc
+{
+  "StartAt": "ValidateOrder",
+  "States": {
+    "ValidateOrder": { "Type": "Pass", "Next": "CheckStock" },
+    "CheckStock": {
+      "Type": "Choice",
+      "Choices": [{ "Variable": "$.inStock", "BooleanEquals": true, "Next": "ChargePayment" }],
+      "Default": "CancelOrder"
+    },
+    "ChargePayment": { "Type": "Task", "Resource": "arn:aws:lambda:...:charge-payment", "Next": "ShipOrder" },
+    "ShipOrder":     { "Type": "Task", "Resource": "arn:aws:lambda:...:ship-order", "Next": "OrderComplete" },
+    "CancelOrder":   { "Type": "Fail", "Error": "OutOfStock" },
+    "OrderComplete": { "Type": "Succeed" }
+  }
+}
+```
+
+…and `generateMermaid` turns it into a diagram GitHub renders inline (the same code also drives SVG and PNG output):
+
+```mermaid
+stateDiagram-v2
+
+    [*] --> ValidateOrder
+    ValidateOrder --> CheckStock
+    CheckStock --> ChargePayment: $.inStock == true
+    CheckStock --> CancelOrder: Default
+    ChargePayment --> ShipOrder
+    ShipOrder --> OrderComplete
+
+    CancelOrder --> [*]
+    OrderComplete --> [*]
+
+    classDef successState fill:#e8f5e8,stroke:#4caf50,stroke-width:3px
+    classDef failState fill:#ffebee,stroke:#f44336,stroke-width:3px
+    classDef choiceState fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
+    classDef taskState fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
+
+    class CheckStock choiceState
+    class ChargePayment taskState
+    class ShipOrder taskState
+    class CancelOrder failState
+    class OrderComplete successState
+```
+
 ## Features
 
 - **Multiple Output Formats**: SVG (D3.js), Mermaid syntax, and PNG
 - **Automatic Layout**: Smart graph positioning using Dagre layout engine
-- **Full ASL Support**: All state types (Pass, Task, Choice, Wait, Succeed, Fail, Parallel, Map), both JSONPath and JSONata query languages
+- **Full ASL Support**: All state types (Pass, Task, Choice, Wait, Succeed, Fail, Parallel, Map), both JSONPath and JSONata query languages, plus `Catch`/`Retry` rendering
+- **Visual Diffing**: Compare two definitions and highlight added / modified / removed states — drives the PR-preview GitHub Action
+- **Execution Overlays**: Paint a real execution's history onto the diagram — succeeded/failed/caught/not-reached states, the taken path, and per-state duration & retry counts
 - **Customizable Themes**: AWS light/dark themes plus custom theme support
 - **Flexible Layouts**: Top-bottom, left-right, right-left, bottom-top
 - **Type-Safe**: Full TypeScript support with comprehensive type definitions
@@ -222,6 +273,125 @@ const { svg } = generateFromAwsResponse({
 });
 ```
 
+### generateMermaidDiff(params) / generateDiff(params)
+
+Compare two ASL definitions and highlight what changed. `generateMermaidDiff` returns Mermaid code (renders inline on GitHub); `generateDiff` returns the same comparison as an SVG. Added states are green, modified yellow, removed red — and both return a `metadata` change summary (`added`, `modified`, `removed`, `unchanged`). The comparison is order-insensitive, so reordering a state's properties is **not** flagged as a change.
+
+```typescript
+import { generateMermaidDiff } from 'sfn-diagram';
+
+const { code, metadata } = generateMermaidDiff({
+  before: baseAsl, // old (base) ASL definition, object or JSON string
+  after: headAsl,  // new (head) ASL definition, object or JSON string
+});
+
+metadata; // { added: [...], modified: [...], removed: [...], unchanged: [...], stateCount, edgeCount }
+```
+
+For the order-processing workflow above, adding a `FraudCheck` step, bumping `ChargePayment`'s resource, and dropping `CancelOrder` renders like this:
+
+```mermaid
+stateDiagram-v2
+
+    [*] --> ValidateOrder
+    ValidateOrder --> CheckStock
+    CheckStock --> ChargePayment: $.inStock == true
+    CheckStock --> OrderComplete: Default
+    ChargePayment --> FraudCheck
+    FraudCheck --> ShipOrder
+    ShipOrder --> OrderComplete
+
+    OrderComplete --> [*]
+    CancelOrder --> [*]
+
+    classDef diffAdded fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
+    classDef diffModified fill:#fff9c4,stroke:#f57f17,stroke-width:2px
+    classDef diffRemoved fill:#ffcdd2,stroke:#c62828,stroke-width:2px
+
+    class FraudCheck diffAdded
+    class CheckStock diffModified
+    class ChargePayment diffModified
+    class CancelOrder diffRemoved
+```
+
+> This is exactly what the [GitHub Action](#github-action) posts on pull requests that touch ASL files.
+
+### generateExecution(params) / generateMermaidExecution(params)
+
+Overlay a **real execution** onto the diagram. Where the diff shows how a definition
+_changed_, the execution overlay shows what one _run_ actually did: which path it took,
+which states succeeded (green), failed (red), were caught and recovered (orange), or were
+never reached (grey) — plus per-state duration and retry counts.
+
+Pass the ASL definition plus the execution's history. `history` accepts the events array
+from `GetExecutionHistory`, the raw command output, or a JSON string of either — so the
+core stays credential-free and runs in the browser.
+
+```typescript
+import { generateExecution, generateMermaidExecution } from 'sfn-diagram';
+
+// history: events from `aws stepfunctions get-execution-history`, or the SDK response
+const { svg, metadata } = generateExecution({ aslDefinition: asl, history });
+
+metadata;
+// { succeeded: [...], failed: [...], caught: [...], notReached: [...], running: [...],
+//   takenEdgeCount, executionStatus, nodeCount, edgeCount }
+
+// Mermaid variant (states coloured + duration/retry annotations in labels):
+const { code } = generateMermaidExecution({ aslDefinition: asl, history });
+```
+
+> **Note:** Mermaid `stateDiagram-v2` cannot style individual transitions, so taken-path
+> emphasis in Mermaid is expressed through node colours and label annotations. The SVG
+> overlay additionally dims the transitions the run did not take.
+
+Need just the data (no rendering)? `parseExecutionHistory({ events })` returns the pure
+`ExecutionOverlay` model — per-state status, attempts, duration, and the taken edges — for
+building your own UI.
+
+```typescript
+import { parseExecutionHistory } from 'sfn-diagram';
+
+const overlay = parseExecutionHistory({ events });
+overlay.states['ProcessOrder']; // { status: 'succeeded', attempts: 1, durationMs: 1250 }
+overlay.takenEdges;             // [{ from: 'ValidateOrder', to: 'ProcessOrder' }, ...]
+```
+
+Fetching history from AWS (Node) — use the `sfn-diagram/aws` helper, which paginates `GetExecutionHistory` for you:
+
+```typescript
+import { SFNClient } from '@aws-sdk/client-sfn';
+import { fetchExecutionHistory } from 'sfn-diagram/aws';
+
+const client = new SFNClient({ region: 'us-east-1' });
+const events = await fetchExecutionHistory({ client, executionArn });
+
+const { svg } = generateExecution({ aslDefinition: asl, history: events });
+```
+
+`sfn-diagram/aws` is a Node-only subpath. `@aws-sdk/client-sfn` is an **optional peer dependency** — install it yourself (`npm i @aws-sdk/client-sfn`); the core `sfn-diagram` package stays dependency-free and browser-safe.
+
+<details>
+<summary>Prefer to paginate yourself? The manual loop:</summary>
+
+```typescript
+import { SFNClient, GetExecutionHistoryCommand } from '@aws-sdk/client-sfn';
+
+const client = new SFNClient({ region: 'us-east-1' });
+const events = [];
+let nextToken;
+do {
+  const page = await client.send(
+    new GetExecutionHistoryCommand({ executionArn, nextToken, maxResults: 1000 }),
+  );
+  events.push(...(page.events ?? []));
+  nextToken = page.nextToken;
+} while (nextToken);
+
+const { svg } = generateExecution({ aslDefinition: asl, history: events });
+```
+</details>
+
 ### SfnDiagramGenerator Class
 
 Reusable generator that holds diagram options once and applies them to every call. Configure options via the constructor or the fluent `setOptions()` method; pass the `aslDefinition` per generation.
@@ -259,23 +429,34 @@ const mermaidResult = generator.generateMermaid({ aslDefinition: asl });
 - `'dark'` - AWS dark theme
 
 **Custom theme:**
+
+A `CustomTheme` sets the background, per-state-type fill/stroke colours, edge colours, and typography. Pass it anywhere a theme is accepted.
+
 ```typescript
-const customTheme = {
-  backgroundColor: '#ffffff',
-  nodeStroke: '#232f3e',
-  nodeStrokeWidth: 2,
-  fontSize: 14,
+import type { CustomTheme } from 'sfn-diagram';
+
+const customTheme: CustomTheme = {
+  background: '#ffffff',
+  edgeColors: {
+    choice: '#7b1fa2',
+    default: '#607d8b',
+    error: '#f44336',
+    normal: '#232f3e',
+    retry: '#f9a825', // optional; falls back to `error` when omitted
+  },
   fontFamily: 'Arial, sans-serif',
-  stateColors: {
-    Pass: '#4CAF50',
-    Task: '#2196F3',
-    Choice: '#FF9800',
-    Wait: '#9C27B0',
-    Succeed: '#4CAF50',
-    Fail: '#F44336',
-    Parallel: '#00BCD4',
-    Map: '#3F51B5'
-  }
+  fontSize: 14,
+  nodeColors: {
+    Pass:     { fill: '#e8f5e9', stroke: '#4caf50' },
+    Task:     { fill: '#e3f2fd', stroke: '#2196f3' },
+    Choice:   { fill: '#fff3e0', stroke: '#ff9800' },
+    Wait:     { fill: '#f3e5f5', stroke: '#9c27b0' },
+    Succeed:  { fill: '#e8f5e9', stroke: '#4caf50' },
+    Fail:     { fill: '#ffebee', stroke: '#f44336' },
+    Parallel: { fill: '#e0f7fa', stroke: '#00bcd4' },
+    Map:      { fill: '#e8eaf6', stroke: '#3f51b5' },
+  },
+  textColor: '#232f3e',
 };
 
 generateSvg({ aslDefinition: asl, theme: customTheme });
@@ -531,7 +712,7 @@ pnpm install
 pnpm dev
 ```
 
-Paste any ASL JSON, switch themes, and see the SVG diagram update instantly — no install required beyond the dev server.
+Paste any ASL JSON, switch themes, and see the SVG diagram update instantly — no install required beyond the dev server. Switch **Mode** to _Execution overlay_ to paste an execution history alongside the definition and watch the run's path light up.
 
 ### VS Code Extension
 
@@ -547,28 +728,53 @@ code --install-extension vscode-sfn-diagram-*.vsix
 
 **Usage:** Open any `.json` or `.asl` file and run **Step Functions: Preview Step Functions Diagram** from the command palette, or click the diagram icon in the editor title bar.
 
+### React Component
+
+Render diagrams in a React app with the [`sfn-diagram-react`](packages/sfn-diagram-react/) package. It wraps `generateSvg`/`generateMermaid` in a component with the same platform-agnostic core, so it works in any React renderer.
+
+```tsx
+import { SfnDiagram } from 'sfn-diagram-react';
+
+<SfnDiagram
+  definition={asl}     // ASL object or JSON string
+  format="svg"         // 'svg' (default) | 'mermaid'
+  theme="dark"         // 'light' | 'dark' | CustomTheme
+  layout="LR"          // 'TB' | 'LR' | 'RL' | 'BT'
+  history={history}    // optional: renders an execution overlay
+  onError={(err) => console.error(err)}
+/>
+```
+
 ### GitHub Action
 
-Post SVG diff previews and Mermaid diagrams as PR comments whenever ASL files change. Located in [`packages/github-action-sfn-diagram/`](packages/github-action-sfn-diagram/).
+Comment a Step Functions diagram on every pull request that touches an ASL file. For **changed** files the comment highlights the diff — added states green, modified yellow, removed red — plus a summary table of what changed; **new** and **deleted** files get a plain diagram. Everything is Mermaid, so it renders inline in the PR with no image hosting. The comment is upserted (updated in place) on each push.
+
+Available on the [GitHub Marketplace](https://github.com/marketplace/actions/step-functions-diagram-preview) as [`yusufaf/sfn-diagram-action`](https://github.com/yusufaf/sfn-diagram-action) — pin the moving major tag `@v1`. (Source lives here in [`packages/github-action-sfn-diagram/`](packages/github-action-sfn-diagram/); the Marketplace repo is generated from it.)
 
 ```yaml
 # .github/workflows/sfn-preview.yml
 name: Step Functions Preview
 on:
   pull_request:
-    paths: ['**/*.asl.json']
+    paths: ['**/*.asl.json', '**/*.asl']
+
+permissions:
+  contents: read
+  pull-requests: write   # required to post the comment
 
 jobs:
   preview:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-      - uses: ./packages/github-action-sfn-diagram
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/checkout@v5
+        with: { fetch-depth: 0 }   # needed to diff base vs head
+      - uses: yusufaf/sfn-diagram-action@v1
 ```
 
+Inputs: `github-token` (defaults to `${{ github.token }}`), `asl-glob` (comma-separated globs, default `**/*.asl.json,**/*.asl`), `comment-tag` (marker used to find/update the comment, default `sfn-diagram-preview`).
+
+Optionally overlay a real run: set `execution-mode` (`latest` or `latest-failed`) and `state-machine-arn` to append the most recent (or most recent failed) execution as a Mermaid overlay beneath the diff. This is opt-in (`off` by default), needs AWS credentials (`states:ListExecutions` + `states:GetExecutionHistory`), and applies when exactly one ASL file changed — see the [action README](packages/github-action-sfn-diagram/README.marketplace.md) for a full workflow.
+
 ## Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

package/dist/aws.cjs

@@ -0,0 +1,50 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _aws_sdk_client_sfn = require("@aws-sdk/client-sfn");
+//#region src/aws.ts
+/**
+* Node-only AWS convenience helpers for `sfn-diagram`.
+*
+* This subpath (`sfn-diagram/aws`) is isolated from the core entry so that
+* importing `sfn-diagram` never pulls in `@aws-sdk/client-sfn`, keeping the core
+* dependency-free and browser-safe. `@aws-sdk/client-sfn` is an optional peer
+* dependency — install it yourself to use these helpers.
+*/
+/**
+* Fetches the complete history of a Step Functions execution, paginating through
+* every `GetExecutionHistory` page so callers don't have to hand-roll the
+* `nextToken` loop.
+*
+* The returned `HistoryEvent[]` can be passed straight to `parseExecutionHistory`,
+* `generateExecution`, or `generateMermaidExecution` from `sfn-diagram`.
+*
+* @param params - The SFN client, execution ARN, and optional page size.
+* @returns All history events for the execution, in chronological order.
+*
+* @example
+* ```ts
+* import { SFNClient } from '@aws-sdk/client-sfn';
+* import { fetchExecutionHistory } from 'sfn-diagram/aws';
+* import { generateExecution } from 'sfn-diagram';
+*
+* const client = new SFNClient({ region: 'us-east-1' });
+* const events = await fetchExecutionHistory({ client, executionArn });
+* const { svg } = generateExecution({ aslDefinition: asl, history: events });
+* ```
+*/
+async function fetchExecutionHistory(params) {
+	const { client, executionArn, maxResults = 1e3 } = params;
+	const events = [];
+	let nextToken;
+	do {
+		const page = await client.send(new _aws_sdk_client_sfn.GetExecutionHistoryCommand({
+			executionArn,
+			maxResults,
+			nextToken
+		}));
+		events.push(...page.events ?? []);
+		nextToken = page.nextToken;
+	} while (nextToken);
+	return events;
+}
+//#endregion
+exports.fetchExecutionHistory = fetchExecutionHistory;

package/dist/aws.d.cts

@@ -0,0 +1,36 @@
+import { HistoryEvent, SFNClient } from "@aws-sdk/client-sfn";
+
+//#region src/aws.d.ts
+interface FetchExecutionHistoryParams {
+  /** A caller-constructed SFN client (with the caller's credentials/region). */
+  client: SFNClient;
+  /** ARN of the execution whose history should be fetched. */
+  executionArn: string;
+  /** Page size passed to `GetExecutionHistory`. Defaults to 1000 (the AWS max). */
+  maxResults?: number;
+}
+/**
+ * Fetches the complete history of a Step Functions execution, paginating through
+ * every `GetExecutionHistory` page so callers don't have to hand-roll the
+ * `nextToken` loop.
+ *
+ * The returned `HistoryEvent[]` can be passed straight to `parseExecutionHistory`,
+ * `generateExecution`, or `generateMermaidExecution` from `sfn-diagram`.
+ *
+ * @param params - The SFN client, execution ARN, and optional page size.
+ * @returns All history events for the execution, in chronological order.
+ *
+ * @example
+ * ```ts
+ * import { SFNClient } from '@aws-sdk/client-sfn';
+ * import { fetchExecutionHistory } from 'sfn-diagram/aws';
+ * import { generateExecution } from 'sfn-diagram';
+ *
+ * const client = new SFNClient({ region: 'us-east-1' });
+ * const events = await fetchExecutionHistory({ client, executionArn });
+ * const { svg } = generateExecution({ aslDefinition: asl, history: events });
+ * ```
+ */
+declare function fetchExecutionHistory(params: FetchExecutionHistoryParams): Promise<HistoryEvent[]>;
+//#endregion
+export { FetchExecutionHistoryParams, fetchExecutionHistory };

package/dist/aws.d.ts

@@ -0,0 +1,36 @@
+import { HistoryEvent, SFNClient } from "@aws-sdk/client-sfn";
+
+//#region src/aws.d.ts
+interface FetchExecutionHistoryParams {
+  /** A caller-constructed SFN client (with the caller's credentials/region). */
+  client: SFNClient;
+  /** ARN of the execution whose history should be fetched. */
+  executionArn: string;
+  /** Page size passed to `GetExecutionHistory`. Defaults to 1000 (the AWS max). */
+  maxResults?: number;
+}
+/**
+ * Fetches the complete history of a Step Functions execution, paginating through
+ * every `GetExecutionHistory` page so callers don't have to hand-roll the
+ * `nextToken` loop.
+ *
+ * The returned `HistoryEvent[]` can be passed straight to `parseExecutionHistory`,
+ * `generateExecution`, or `generateMermaidExecution` from `sfn-diagram`.
+ *
+ * @param params - The SFN client, execution ARN, and optional page size.
+ * @returns All history events for the execution, in chronological order.
+ *
+ * @example
+ * ```ts
+ * import { SFNClient } from '@aws-sdk/client-sfn';
+ * import { fetchExecutionHistory } from 'sfn-diagram/aws';
+ * import { generateExecution } from 'sfn-diagram';
+ *
+ * const client = new SFNClient({ region: 'us-east-1' });
+ * const events = await fetchExecutionHistory({ client, executionArn });
+ * const { svg } = generateExecution({ aslDefinition: asl, history: events });
+ * ```
+ */
+declare function fetchExecutionHistory(params: FetchExecutionHistoryParams): Promise<HistoryEvent[]>;
+//#endregion
+export { FetchExecutionHistoryParams, fetchExecutionHistory };

package/dist/aws.js

@@ -0,0 +1,49 @@
+import { GetExecutionHistoryCommand } from "@aws-sdk/client-sfn";
+//#region src/aws.ts
+/**
+* Node-only AWS convenience helpers for `sfn-diagram`.
+*
+* This subpath (`sfn-diagram/aws`) is isolated from the core entry so that
+* importing `sfn-diagram` never pulls in `@aws-sdk/client-sfn`, keeping the core
+* dependency-free and browser-safe. `@aws-sdk/client-sfn` is an optional peer
+* dependency — install it yourself to use these helpers.
+*/
+/**
+* Fetches the complete history of a Step Functions execution, paginating through
+* every `GetExecutionHistory` page so callers don't have to hand-roll the
+* `nextToken` loop.
+*
+* The returned `HistoryEvent[]` can be passed straight to `parseExecutionHistory`,
+* `generateExecution`, or `generateMermaidExecution` from `sfn-diagram`.
+*
+* @param params - The SFN client, execution ARN, and optional page size.
+* @returns All history events for the execution, in chronological order.
+*
+* @example
+* ```ts
+* import { SFNClient } from '@aws-sdk/client-sfn';
+* import { fetchExecutionHistory } from 'sfn-diagram/aws';
+* import { generateExecution } from 'sfn-diagram';
+*
+* const client = new SFNClient({ region: 'us-east-1' });
+* const events = await fetchExecutionHistory({ client, executionArn });
+* const { svg } = generateExecution({ aslDefinition: asl, history: events });
+* ```
+*/
+async function fetchExecutionHistory(params) {
+	const { client, executionArn, maxResults = 1e3 } = params;
+	const events = [];
+	let nextToken;
+	do {
+		const page = await client.send(new GetExecutionHistoryCommand({
+			executionArn,
+			maxResults,
+			nextToken
+		}));
+		events.push(...page.events ?? []);
+		nextToken = page.nextToken;
+	} while (nextToken);
+	return events;
+}
+//#endregion
+export { fetchExecutionHistory };

package/dist/cli.js

@@ -1329,6 +1329,8 @@ var SvgRenderer = class {
 		});
 		nodeGroup.append("text").attr("x", labelX).attr("y", labelY).attr("text-anchor", "middle").attr("dominant-baseline", "middle").attr("fill", this.theme.textColor).attr("font-size", this.theme.fontSize).attr("font-family", this.theme.fontFamily).text(node.label);
 		if (this.options.showStateTypes) nodeGroup.append("text").attr("x", labelX).attr("y", labelY + 20).attr("text-anchor", "middle").attr("dominant-baseline", "middle").attr("fill", this.theme.textColor).attr("font-size", this.theme.fontSize - 2).attr("opacity", .7).text(node.type);
+		const annotation = this.options.nodeAnnotations?.[node.id];
+		if (annotation) nodeGroup.append("text").attr("x", labelX).attr("y", labelY + (this.options.showStateTypes ? 36 : 18)).attr("text-anchor", "middle").attr("dominant-baseline", "middle").attr("fill", this.theme.textColor).attr("font-size", this.theme.fontSize - 3).attr("opacity", .75).text(annotation);
 	}
 	/**
 	* Render rectangle node
@@ -1414,7 +1416,11 @@ var SvgRenderer = class {
 		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 pathElement = group.append("path").attr("d", pathData).attr("fill", "none").attr("stroke", edgeColor).attr("stroke-width", edge.type === "error" ? 2 : 1.5).attr("marker-end", `url(#arrowhead-${markerType})`);
+		const override = this.options.edgeOverrides?.[`${edge.from}->${edge.to}`];
+		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})`);
+		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");
@@ -1482,6 +1488,34 @@ var SvgRenderer = class {
 };
 //#endregion
 //#region src/renderers/MermaidRenderer.ts
+/** Mermaid classDef declarations for diff highlighting, keyed by diff status. */
+const DIFF_CLASS_DEFS = {
+	added: "classDef diffAdded fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px",
+	modified: "classDef diffModified fill:#fff9c4,stroke:#f57f17,stroke-width:2px",
+	removed: "classDef diffRemoved fill:#ffcdd2,stroke:#c62828,stroke-width:2px"
+};
+/** Mermaid class name applied to a state for a given diff status. */
+const DIFF_CLASS_NAMES = {
+	added: "diffAdded",
+	modified: "diffModified",
+	removed: "diffRemoved"
+};
+/** Mermaid classDef declarations for execution highlighting, keyed by status. */
+const EXECUTION_CLASS_DEFS = {
+	caught: "classDef execCaught fill:#ffe0b2,stroke:#e65100,stroke-width:2px",
+	failed: "classDef execFailed fill:#ffcdd2,stroke:#c62828,stroke-width:3px",
+	notReached: "classDef execNotReached fill:#f5f5f5,stroke:#bdbdbd,stroke-width:1px",
+	running: "classDef execRunning fill:#bbdefb,stroke:#1565c0,stroke-width:2px",
+	succeeded: "classDef execSucceeded fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px"
+};
+/** Mermaid class name applied to a state for a given execution status. */
+const EXECUTION_CLASS_NAMES = {
+	caught: "execCaught",
+	failed: "execFailed",
+	notReached: "execNotReached",
+	running: "execRunning",
+	succeeded: "execSucceeded"
+};
 /**
 * MermaidRenderer - Generates Mermaid state diagram syntax from ASL
 */
@@ -1490,7 +1524,7 @@ var MermaidRenderer = class {
 	* Render nodes and edges to Mermaid syntax
 	*/
 	render(params) {
-		const { asl, edges, nodes } = params;
+		const { asl, edges, executionClasses, nodeAnnotations, nodes, stateClasses } = params;
 		const lines = [];
 		lines.push("stateDiagram-v2");
 		lines.push("");
@@ -1503,8 +1537,11 @@ var MermaidRenderer = class {
 		const stateDefinitions = /* @__PURE__ */ new Set();
 		nodes.forEach((node) => {
 			const id = this.sanitizeId(node.id);
-			if (node.label !== node.id && !stateDefinitions.has(id)) {
-				lines.push(`    ${id}: ${this.escapeLabel(node.label)}`);
+			if (stateDefinitions.has(id)) return;
+			const annotation = nodeAnnotations?.[node.id];
+			const displayLabel = annotation ? `${node.label} (${annotation})` : node.label;
+			if (displayLabel !== node.id) {
+				lines.push(`    ${id}: ${this.escapeLabel(displayLabel)}`);
 				stateDefinitions.add(id);
 			}
 		});
@@ -1530,9 +1567,21 @@ var MermaidRenderer = class {
 		lines.push("    classDef failState fill:#ffebee,stroke:#f44336,stroke-width:3px");
 		lines.push("    classDef choiceState fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px");
 		lines.push("    classDef taskState fill:#fff3e0,stroke:#ef6c00,stroke-width:2px");
+		if (stateClasses && Object.keys(stateClasses).length > 0) for (const status of Object.keys(DIFF_CLASS_DEFS)) lines.push(`    ${DIFF_CLASS_DEFS[status]}`);
+		if (executionClasses && Object.keys(executionClasses).length > 0) for (const status of Object.keys(EXECUTION_CLASS_DEFS)) lines.push(`    ${EXECUTION_CLASS_DEFS[status]}`);
 		lines.push("");
 		nodes.forEach((node) => {
 			const id = this.sanitizeId(node.id);
+			const executionStatus = executionClasses?.[node.id];
+			if (executionStatus) {
+				lines.push(`    class ${id} ${EXECUTION_CLASS_NAMES[executionStatus]}`);
+				return;
+			}
+			const diffStatus = stateClasses?.[node.id];
+			if (diffStatus) {
+				lines.push(`    class ${id} ${DIFF_CLASS_NAMES[diffStatus]}`);
+				return;
+			}
 			switch (node.type) {
 				case "Succeed":
 					lines.push(`    class ${id} successState`);
@@ -1606,7 +1655,9 @@ const DEFAULT_DIAGRAM_OPTIONS = {
 	showIcons: false,
 	pngQuality: 90,
 	backgroundColor: "transparent",
-	nodeOverrides: void 0
+	nodeOverrides: void 0,
+	edgeOverrides: void 0,
+	nodeAnnotations: void 0
 };
 /**
 * Merge user-provided options with defaults