sfn-diagram 0.7.0 → 1.0.0

package/README.md

@@ -95,6 +95,10 @@ browser (`node-html-to-image`) and Node's filesystem respectively. Because `node
 is an **optional peer dependency**, install it alongside `sfn-diagram` when you need PNG output;
 `exportPng` throws an actionable error if it is missing.
 
+**Node versions:** the package requires **Node >= 20**. PNG export additionally requires
+**Node >= 22.12.0**, the floor set by `node-html-to-image` v6 — SVG, Mermaid, and HTML
+output are unaffected and keep working on Node 20.
+
 ```ts
 // Works in Node, browser, and edge:
 import { generateSvg } from 'sfn-diagram';
@@ -113,7 +117,11 @@ npx sfn-diagram state.asl.json --format mermaid > diagram.mmd
 cat state.asl.json | npx sfn-diagram - --format svg
 ```
 
-Flags: `--format <svg|mermaid|png>`, `-o/--output <path>`, `--theme <light|dark>`, `--layout <TB|LR|RL|BT>`, `-h/--help`, `-v/--version`.
+Flags: `--format <svg|mermaid|png|html>`, `-o/--output <path>`, `--theme <light|dark>`, `--layout <TB|LR|RL|BT>`, `--hide-catch`, `--resolve-cfn`, `--resource <logicalId>`, `-h/--help`, `-v/--version`.
+
+CloudFormation/SAM/CDK templates work as input too — see [Extracting ASL from a CDK/CloudFormation template](#extracting-asl-from-a-cdkcloudformation-template).
+
+> **`--format png` needs the optional `node-html-to-image` peer.** It is not installed by default. With `npx`, run `npx --package sfn-diagram --package node-html-to-image sfn-diagram …`; in a project, `npm install node-html-to-image`. Without it the CLI exits with an actionable error. Or skip the install entirely with the [Docker image](#docker), which bundles Chromium.
 
 ## Docker
 
@@ -273,6 +281,35 @@ const { svg } = generateFromAwsResponse({
 });
 ```
 
+### Extracting ASL from a CDK/CloudFormation template
+
+`cdk synth` emits a state machine whose `DefinitionString` is an `Fn::Join` full
+of intrinsics, not plain ASL. The `sfn-diagram/cfn` subpath flattens it:
+
+```typescript
+import { extractAslFromTemplate } from 'sfn-diagram/cfn';
+import { generateMermaid } from 'sfn-diagram';
+
+const { aslDefinition, warnings } = extractAslFromTemplate({ template: cdkSynthJson });
+const { code } = generateMermaid({ aslDefinition });
+```
+
+Both JSON and YAML templates are supported (CloudFormation short-form tags like
+`!Sub` / `!GetAtt` included), and `DefinitionSubstitutions` are applied. When a
+template contains more than one state machine, pass `resourceId` to pick one.
+
+CLI (JSON templates auto-detect; use `--resolve-cfn` for YAML):
+
+```bash
+cdk synth > template.json
+npx sfn-diagram template.json --format mermaid
+npx sfn-diagram template.yaml --resolve-cfn --resource MyMachine --format svg -o out.svg
+```
+
+Intrinsics that don't affect the flow become readable placeholders
+(`${AWS::Partition}`, `<Ref:LogicalId>`). External `DefinitionUri` definitions
+are not supported — pass a template with an inline definition.
+
 ### 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.
@@ -475,6 +512,29 @@ generateSvg({ aslDefinition: asl, theme: customTheme });
 - `'straight'` - Direct straight lines
 - `'orthogonal'` - Right-angled paths
 
+### Large diagrams
+
+Big, branchy state machines are hard to read as a static image. A few options help:
+
+- **`--format html`** (or `generateHtml()`) — a self-contained interactive viewer
+  (drag to pan, wheel to zoom, fit/reset toolbar). No external dependencies, opens
+  offline straight from `file://`.
+  ```bash
+  npx sfn-diagram state.asl.json --format html -o diagram.html
+  ```
+  > **Known limitation:** if you also pass `showIcons: true`, the embedded SVG
+  > references AWS service icons hosted on a jsDelivr CDN (see
+  > [AWS Service Icons](#aws-service-icons) below), so the HTML is no longer fully
+  > offline — icons won't load without network access.
+- **`--hide-catch`** (or `catchHandling: 'hide'`) — drop per-state error-handler
+  (`Catch`) branches so the happy path stands out. A handler that's also reachable
+  via the happy path is kept.
+  ```bash
+  npx sfn-diagram state.asl.json --hide-catch --format svg -o diagram.svg
+  ```
+- **`--layout LR`** (or `layout: 'LR'`) — the default `TB` layout makes catch-heavy
+  or deeply branching machines extremely tall; `LR` reads better for wide graphs.
+
 ### AWS Service Icons
 
 Display AWS service icons on Task state nodes to improve diagram readability and quickly identify which AWS services are being used.

package/dist/aws.cjs

@@ -2,7 +2,9 @@ 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`.
+* @module
+*
+* Node-only AWS convenience helpers for `sfn-diagram` (the `sfn-diagram/aws` subpath).
 *
 * 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

package/dist/aws.d.cts

@@ -10,27 +10,27 @@ interface FetchExecutionHistoryParams {
   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 });
- * ```
- */
+* 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

@@ -10,27 +10,27 @@ interface FetchExecutionHistoryParams {
   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 });
- * ```
- */
+* 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

@@ -1,7 +1,9 @@
 import { GetExecutionHistoryCommand } from "@aws-sdk/client-sfn";
 //#region src/aws.ts
 /**
-* Node-only AWS convenience helpers for `sfn-diagram`.
+* @module
+*
+* Node-only AWS convenience helpers for `sfn-diagram` (the `sfn-diagram/aws` subpath).
 *
 * 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

package/dist/cfn.cjs

@@ -0,0 +1,207 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let yaml = require("yaml");
+//#region src/cfn/intrinsics.ts
+function isPseudoParam(name) {
+	return name.startsWith("AWS::");
+}
+function substitute(template, substitutions) {
+	return template.replace(/\$\{([^}]+)\}/g, (match, name) => {
+		if (isPseudoParam(name)) return match;
+		if (name in substitutions) return substitutions[name];
+		return match;
+	});
+}
+/**
+* Replaces every CloudFormation intrinsic in a parsed template value with a
+* readable placeholder string, so the result can be parsed as ASL.
+*
+* `Fn::Join` is concatenated, `Fn::Sub` variables are filled from the
+* substitutions map, `Ref`/`Fn::GetAtt` become `<Ref:Id>` / `<Res.Attr>`, and
+* pseudo-parameters stay as `${AWS::Partition}`-style tokens. Anything else is
+* stubbed as `<Fn::Name>` and reported in `warnings`.
+*
+* @param params - The value to resolve plus optional DefinitionSubstitutions.
+* @returns The resolved value and any non-fatal warnings.
+*
+* @example
+* ```typescript
+* const { value } = resolveIntrinsics({ value: { Ref: 'AWS::Partition' } });
+* // value === '${AWS::Partition}'
+* ```
+*/
+function resolveIntrinsics(params) {
+	const { substitutions = {}, value } = params;
+	const warnings = [];
+	function walk(current) {
+		if (Array.isArray(current)) return current.map(walk);
+		if (current === null || typeof current !== "object") return current;
+		const objectKeys = Object.keys(current);
+		if (objectKeys.length === 1) {
+			const key = objectKeys[0];
+			const inner = current[key];
+			if (key === "Ref" && typeof inner === "string") return isPseudoParam(inner) ? `\${${inner}}` : `<Ref:${inner}>`;
+			if (key === "Fn::GetAtt") return `<${(Array.isArray(inner) ? inner : String(inner).split(".")).join(".")}>`;
+			if (key === "Fn::Join") {
+				const [delimiter, parts] = inner;
+				return parts.map((part) => String(walk(part))).join(delimiter);
+			}
+			if (key === "Fn::Sub") {
+				if (typeof inner === "string") return substitute(inner, substitutions);
+				if (Array.isArray(inner)) {
+					const [subTemplate, localMap] = inner;
+					const localResolved = { ...substitutions };
+					for (const localKey of Object.keys(localMap)) localResolved[localKey] = String(walk(localMap[localKey]));
+					return substitute(subTemplate, localResolved);
+				}
+			}
+			if (key.startsWith("Fn::")) {
+				warnings.push(`Unresolved intrinsic ${key} replaced with placeholder`);
+				return `<${key}>`;
+			}
+		}
+		const output = {};
+		for (const key of objectKeys) output[key] = walk(current[key]);
+		return output;
+	}
+	return {
+		value: walk(value),
+		warnings
+	};
+}
+//#endregion
+//#region src/cfn/templateParser.ts
+/**
+* CloudFormation short-form YAML tags, mapped to the JSON long form the rest of
+* the pipeline understands. `!Ref x` becomes `{ Ref: 'x' }`; every `Fn::*` tag
+* becomes `{ 'Fn::Name': value }`.
+*/
+const CFN_TAG_NAMES = [
+	"Ref",
+	"Base64",
+	"Cidr",
+	"FindInMap",
+	"GetAtt",
+	"GetAZs",
+	"ImportValue",
+	"Join",
+	"Select",
+	"Split",
+	"Sub",
+	"Transform",
+	"And",
+	"Equals",
+	"If",
+	"Not",
+	"Or",
+	"Condition"
+];
+function longFormKey(tagName) {
+	return tagName === "Ref" || tagName === "Condition" ? tagName : `Fn::${tagName}`;
+}
+function buildCfnTags() {
+	const tags = [];
+	for (const tagName of CFN_TAG_NAMES) {
+		const toLongForm = (value) => {
+			if (tagName === "GetAtt" && typeof value === "string") return { "Fn::GetAtt": value.split(".") };
+			return { [longFormKey(tagName)]: value };
+		};
+		tags.push({
+			identify: () => false,
+			resolve: (value) => toLongForm(value),
+			tag: `!${tagName}`
+		});
+		tags.push({
+			collection: "seq",
+			identify: () => false,
+			resolve: (value) => toLongForm(value.toJSON()),
+			tag: `!${tagName}`
+		});
+		tags.push({
+			collection: "map",
+			identify: () => false,
+			resolve: (value) => toLongForm(value.toJSON()),
+			tag: `!${tagName}`
+		});
+	}
+	return tags;
+}
+const CFN_TAGS = buildCfnTags();
+function looksLikeJson(text) {
+	return text.trimStart().startsWith("{");
+}
+/**
+* Parses a CloudFormation/SAM/CDK template into a plain object.
+*
+* JSON is parsed with `JSON.parse`; YAML is parsed with CloudFormation
+* short-form intrinsic tags normalized to their JSON long form, so downstream
+* code only has to understand `{ Ref: ... }` / `{ 'Fn::Sub': ... }` shapes.
+*
+* @param params - Template source and optional explicit format.
+* @returns The parsed template object.
+*
+* @example
+* ```typescript
+* const template = parseTemplate({ template: yamlSource, format: 'yaml' });
+* ```
+*/
+function parseTemplate(params) {
+	const { format = "auto", template } = params;
+	if (typeof template !== "string") return template;
+	if (format === "json" || format === "auto" && looksLikeJson(template)) return JSON.parse(template);
+	return (0, yaml.parse)(template, { customTags: CFN_TAGS });
+}
+//#endregion
+//#region src/cfn/extract.ts
+const STATE_MACHINE_TYPE = "AWS::StepFunctions::StateMachine";
+function findStateMachineIds(resources) {
+	return Object.keys(resources).filter((logicalId) => resources[logicalId]?.Type === STATE_MACHINE_TYPE);
+}
+/**
+* Recovers a renderable ASL definition from a CloudFormation/SAM/CDK template.
+*
+* Locates the `AWS::StepFunctions::StateMachine` resource (disambiguated with
+* `resourceId` when the template has more than one), flattens the intrinsics in
+* its `DefinitionString`/`Definition`, applies `DefinitionSubstitutions`, and
+* parses the result as ASL.
+*
+* @param params - Template source, optional format, optional resource id.
+* @returns The extracted ASL definition, the logical id used, and any warnings.
+* @throws If no state machine is found, the choice is ambiguous, or the
+* definition is external (`DefinitionUri`).
+*
+* @example
+* ```typescript
+* const { aslDefinition } = extractAslFromTemplate({ template: cdkSynthJson });
+* ```
+*/
+function extractAslFromTemplate(params) {
+	const { format = "auto", resourceId, template } = params;
+	const resources = parseTemplate({
+		format,
+		template
+	}).Resources ?? {};
+	const machineIds = findStateMachineIds(resources);
+	if (machineIds.length === 0) throw new Error(`Template contains no ${STATE_MACHINE_TYPE} resource.`);
+	let chosenId;
+	if (resourceId) {
+		if (!machineIds.includes(resourceId)) throw new Error(`Resource '${resourceId}' is not an ${STATE_MACHINE_TYPE}. Found: ${machineIds.join(", ")}.`);
+		chosenId = resourceId;
+	} else if (machineIds.length === 1) chosenId = machineIds[0];
+	else throw new Error(`Template has multiple state machines (${machineIds.join(", ")}). Pass resourceId (or --resource) to choose one.`);
+	const properties = resources[chosenId].Properties ?? {};
+	if ("DefinitionUri" in properties && !("DefinitionString" in properties) && !("Definition" in properties)) throw new Error(`State machine '${chosenId}' uses an external DefinitionUri, which is not supported. Pass a template with an inline DefinitionString or Definition.`);
+	const substitutions = properties.DefinitionSubstitutions ?? {};
+	const rawDefinition = properties.DefinitionString ?? properties.Definition;
+	if (rawDefinition === void 0) throw new Error(`State machine '${chosenId}' has no DefinitionString or Definition.`);
+	const { value: resolved, warnings } = resolveIntrinsics({
+		substitutions,
+		value: rawDefinition
+	});
+	return {
+		aslDefinition: typeof resolved === "string" ? JSON.parse(resolved) : resolved,
+		resourceId: chosenId,
+		warnings
+	};
+}
+//#endregion
+exports.extractAslFromTemplate = extractAslFromTemplate;

package/dist/cfn.d.cts

@@ -0,0 +1,102 @@
+//#region src/types/index.d.ts
+/** The set of Amazon States Language state types a state machine can contain. */
+type StateType = "Pass" | "Task" | "Choice" | "Wait" | "Succeed" | "Fail" | "Parallel" | "Map";
+/** An ASL `Catch` handler: routes matching errors to a fallback state. */
+interface CatchBlock {
+  ErrorEquals: string[];
+  Next?: string;
+  ResultPath?: string;
+}
+/** An ASL `Retry` policy: re-attempts a state on matching errors with backoff. */
+interface RetryBlock {
+  BackoffRate?: number;
+  ErrorEquals: string[];
+  IntervalSeconds?: number;
+  MaxAttempts?: number;
+}
+/** A single rule in a Choice state: a condition plus the `Next` state to take when it matches. */
+interface ChoiceRule {
+  BooleanEquals?: boolean;
+  Next: string;
+  NumericEquals?: number;
+  StringEquals?: string;
+  Variable?: string;
+  [key: string]: any;
+}
+/** A single state within an ASL definition, covering fields for every state type. */
+interface AslState {
+  Assign?: Record<string, any>;
+  Branches?: AslDefinition[];
+  Catch?: CatchBlock[];
+  Cause?: string;
+  Choices?: ChoiceRule[];
+  Comment?: string;
+  Default?: string;
+  End?: boolean;
+  Error?: string;
+  ItemProcessor?: AslDefinition;
+  Iterator?: AslDefinition;
+  Next?: string;
+  Output?: any;
+  Parameters?: Record<string, any>;
+  QueryLanguage?: "JSONata" | "JSONPath";
+  Resource?: string;
+  Result?: any;
+  ResultPath?: string;
+  Retry?: RetryBlock[];
+  Seconds?: number | string;
+  SecondsPath?: string;
+  Timestamp?: string;
+  TimestampPath?: string;
+  Type: StateType;
+}
+/** A complete Amazon States Language state machine definition. */
+interface AslDefinition {
+  Comment?: string;
+  QueryLanguage?: "JSONata" | "JSONPath";
+  StartAt: string;
+  States: Record<string, AslState>;
+  TimeoutSeconds?: number;
+  Version?: string;
+}
+/** Parameters for `extractAslFromTemplate` (from the `sfn-diagram/cfn` subpath). */
+interface ExtractAslFromTemplateParams {
+  /** Input format. 'auto' (default) sniffs JSON vs YAML. */
+  format?: "auto" | "json" | "yaml";
+  /** Logical id of the state machine to extract when the template has more than one. */
+  resourceId?: string;
+  /** Raw template string (JSON or YAML) or an already-parsed template object. */
+  template: string | Record<string, unknown>;
+}
+/** Result of extracting an ASL definition from a CloudFormation/SAM template. */
+interface ExtractAslResult {
+  /** The recovered ASL definition, ready for generateSvg/generateMermaid/etc. */
+  aslDefinition: AslDefinition;
+  /** Logical id of the state machine that was extracted. */
+  resourceId: string;
+  /** Non-fatal notes (e.g. unresolved intrinsics replaced with placeholders). */
+  warnings: string[];
+}
+//#endregion
+//#region src/cfn/extract.d.ts
+/**
+* Recovers a renderable ASL definition from a CloudFormation/SAM/CDK template.
+*
+* Locates the `AWS::StepFunctions::StateMachine` resource (disambiguated with
+* `resourceId` when the template has more than one), flattens the intrinsics in
+* its `DefinitionString`/`Definition`, applies `DefinitionSubstitutions`, and
+* parses the result as ASL.
+*
+* @param params - Template source, optional format, optional resource id.
+* @returns The extracted ASL definition, the logical id used, and any warnings.
+* @throws If no state machine is found, the choice is ambiguous, or the
+* definition is external (`DefinitionUri`).
+*
+* @example
+* ```typescript
+* const { aslDefinition } = extractAslFromTemplate({ template: cdkSynthJson });
+* ```
+*/
+declare function extractAslFromTemplate(params: ExtractAslFromTemplateParams): ExtractAslResult;
+//#endregion
+export { type ExtractAslFromTemplateParams, type ExtractAslResult, extractAslFromTemplate };

package/dist/cfn.d.ts

@@ -0,0 +1,102 @@
+//#region src/types/index.d.ts
+/** The set of Amazon States Language state types a state machine can contain. */
+type StateType = "Pass" | "Task" | "Choice" | "Wait" | "Succeed" | "Fail" | "Parallel" | "Map";
+/** An ASL `Catch` handler: routes matching errors to a fallback state. */
+interface CatchBlock {
+  ErrorEquals: string[];
+  Next?: string;
+  ResultPath?: string;
+}
+/** An ASL `Retry` policy: re-attempts a state on matching errors with backoff. */
+interface RetryBlock {
+  BackoffRate?: number;
+  ErrorEquals: string[];
+  IntervalSeconds?: number;
+  MaxAttempts?: number;
+}
+/** A single rule in a Choice state: a condition plus the `Next` state to take when it matches. */
+interface ChoiceRule {
+  BooleanEquals?: boolean;
+  Next: string;
+  NumericEquals?: number;
+  StringEquals?: string;
+  Variable?: string;
+  [key: string]: any;
+}
+/** A single state within an ASL definition, covering fields for every state type. */
+interface AslState {
+  Assign?: Record<string, any>;
+  Branches?: AslDefinition[];
+  Catch?: CatchBlock[];
+  Cause?: string;
+  Choices?: ChoiceRule[];
+  Comment?: string;
+  Default?: string;
+  End?: boolean;
+  Error?: string;
+  ItemProcessor?: AslDefinition;
+  Iterator?: AslDefinition;
+  Next?: string;
+  Output?: any;
+  Parameters?: Record<string, any>;
+  QueryLanguage?: "JSONata" | "JSONPath";
+  Resource?: string;
+  Result?: any;
+  ResultPath?: string;
+  Retry?: RetryBlock[];
+  Seconds?: number | string;
+  SecondsPath?: string;
+  Timestamp?: string;
+  TimestampPath?: string;
+  Type: StateType;
+}
+/** A complete Amazon States Language state machine definition. */
+interface AslDefinition {
+  Comment?: string;
+  QueryLanguage?: "JSONata" | "JSONPath";
+  StartAt: string;
+  States: Record<string, AslState>;
+  TimeoutSeconds?: number;
+  Version?: string;
+}
+/** Parameters for `extractAslFromTemplate` (from the `sfn-diagram/cfn` subpath). */
+interface ExtractAslFromTemplateParams {
+  /** Input format. 'auto' (default) sniffs JSON vs YAML. */
+  format?: "auto" | "json" | "yaml";
+  /** Logical id of the state machine to extract when the template has more than one. */
+  resourceId?: string;
+  /** Raw template string (JSON or YAML) or an already-parsed template object. */
+  template: string | Record<string, unknown>;
+}
+/** Result of extracting an ASL definition from a CloudFormation/SAM template. */
+interface ExtractAslResult {
+  /** The recovered ASL definition, ready for generateSvg/generateMermaid/etc. */
+  aslDefinition: AslDefinition;
+  /** Logical id of the state machine that was extracted. */
+  resourceId: string;
+  /** Non-fatal notes (e.g. unresolved intrinsics replaced with placeholders). */
+  warnings: string[];
+}
+//#endregion
+//#region src/cfn/extract.d.ts
+/**
+* Recovers a renderable ASL definition from a CloudFormation/SAM/CDK template.
+*
+* Locates the `AWS::StepFunctions::StateMachine` resource (disambiguated with
+* `resourceId` when the template has more than one), flattens the intrinsics in
+* its `DefinitionString`/`Definition`, applies `DefinitionSubstitutions`, and
+* parses the result as ASL.
+*
+* @param params - Template source, optional format, optional resource id.
+* @returns The extracted ASL definition, the logical id used, and any warnings.
+* @throws If no state machine is found, the choice is ambiguous, or the
+* definition is external (`DefinitionUri`).
+*
+* @example
+* ```typescript
+* const { aslDefinition } = extractAslFromTemplate({ template: cdkSynthJson });
+* ```
+*/
+declare function extractAslFromTemplate(params: ExtractAslFromTemplateParams): ExtractAslResult;
+//#endregion
+export { type ExtractAslFromTemplateParams, type ExtractAslResult, extractAslFromTemplate };