sfn-diagram 1.8.0 → 1.9.0

package/README.md

@@ -6,10 +6,12 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Docs](https://img.shields.io/badge/docs-sfn.yusufaf.dev-brightgreen)](https://sfn.yusufaf.dev)
 
-Generate diagrams from AWS Step Functions ASL (Amazon States Language) definitions, CloudFormation/SAM/CDK templates, or live AWS state machines. Outputs SVG, Mermaid, standalone HTML, and PNG.
+Generate diagrams from AWS Step Functions ASL (Amazon States Language) definitions, CloudFormation/SAM/CDK templates, Terraform configs, or live AWS state machines. Outputs SVG, Mermaid, standalone HTML, and PNG.
 
 **📖 [Documentation](https://sfn.yusufaf.dev)** · **▶ [Live playground](https://sfn.yusufaf.dev/playground/)** — paste any ASL definition and preview the diagram instantly, no install required.
 
+**Use it as:** [CLI & Node library](https://www.npmjs.com/package/sfn-diagram) · VS Code extension ([Marketplace](https://marketplace.visualstudio.com/items?itemName=yusufaf.vscode-sfn-diagram) · [Open VSX](https://open-vsx.org/extension/yusufaf/vscode-sfn-diagram)) · [GitHub Action](https://github.com/marketplace/actions/step-functions-diagram-preview) · [React component](https://www.npmjs.com/package/sfn-diagram-react)
+
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/images/parallel-dark.svg">
   <img src="docs/images/parallel-light.svg" alt="Example diagram of a Parallel state Step Functions workflow generated by sfn-diagram" width="410">
@@ -27,7 +29,7 @@ The core package pulls in **no browser engine or native rasterizer** — SVG and
 npm install sfn-diagram @resvg/resvg-js
 ```
 
-Not a Node project? The CLI also ships as standalone binaries for Linux, macOS, and Windows on every [release](https://github.com/yusufaf/sfn-diagram/releases), or via Homebrew (`brew install yusufaf/tap/sfn-diagram`), and as a [Docker image](https://sfn.yusufaf.dev/guides/cli/#docker). See [using sfn-diagram from other languages](https://sfn.yusufaf.dev/guides/other-languages/).
+Not a Node project? The CLI also ships as standalone binaries for Linux, macOS, and Windows, attached to every core release from v1.6.0 on ([download](https://sfn.yusufaf.dev/installation/#cli-without-node)), or via Homebrew (`brew install yusufaf/tap/sfn-diagram`), and as a [Docker image](https://sfn.yusufaf.dev/guides/cli/#docker). See [using sfn-diagram from other languages](https://sfn.yusufaf.dev/guides/other-languages/).
 
 ## Quick start
 
@@ -55,7 +57,24 @@ Prefer the command line:
 npx sfn-diagram my-workflow.asl.json --format svg -o diagram.svg
 ```
 
-Or render what is actually deployed, with `--from-aws`:
+## Why sfn-diagram
+
+There's no shortage of ways to look at a state machine — this is where sfn-diagram fits versus the other two most common options:
+
+| | **sfn-diagram** | AWS Console visualizer | Mermaid Live Editor |
+|---|---|---|---|
+| Input | ASL, CloudFormation/SAM/CDK templates, Terraform configs, live AWS state machines | Deployed state machine only | Manual Mermaid you write by hand |
+| Output | SVG, Mermaid, PNG, interactive HTML | Static graph in-browser | Mermaid diagram only |
+| CI / PR integration | [GitHub Action](https://sfn.yusufaf.dev/ecosystem/github-action/) or [GitLab CI](https://sfn.yusufaf.dev/ecosystem/gitlab/) posts a diff overlay on every PR/MR that touches ASL | None | None |
+| Execution overlays | Paints a real run's path/status/duration onto the diagram | Basic per-execution highlighting, console-only | Not applicable |
+| Runs where | CLI, Node, browser, edge runtimes | AWS Console only | Web app only |
+| Automation | Full programmatic API (`generateSvg`, `generateMermaid`, etc.) | None — UI only | None — UI only |
+
+In short: reach for the AWS Console visualizer to eyeball a state machine you already deployed, reach for Mermaid Live if you're hand-drawing a diagram from scratch — reach for sfn-diagram when you want diagrams generated automatically from your actual definition, checked into CI, and diffed on every pull request.
+
+## Command line
+
+Render what is actually deployed, with `--from-aws`:
 
 ```bash
 pnpm add @aws-sdk/client-sfn   # optional peer, only needed for --from-aws
@@ -70,42 +89,45 @@ drift), `--execution` and `--check`. It needs the optional peer above, so it is
 unavailable in the [standalone binary](https://sfn.yusufaf.dev/guides/cli/#standalone-binary).
 See [Rendering a live state machine](https://sfn.yusufaf.dev/guides/cli/#rendering-a-live-state-machine).
 
-It exits `0` on success, `1` when something goes wrong while running — including a failed
-AWS call — and `2` when the invocation itself was wrong, so a CI job can tell a bad flag
-from a bad definition. See
-[Exit codes](https://sfn.yusufaf.dev/guides/cli/#exit-codes).
+`--scale` raises PNG resolution without changing the layout; see
+[PNG resolution and fonts](https://sfn.yusufaf.dev/guides/cli/#png-resolution-and-fonts)
+for the font options.
 
-## Why sfn-diagram
+```bash
+sfn-diagram my-workflow.asl.json --format png --scale 2 -o diagram@2x.png
+```
 
-There's no shortage of ways to look at a state machine — this is where sfn-diagram fits versus the other two most common options:
+An HTML document inlines every state's raw ASL for its detail panel. `--redact-fields`
+replaces the named fields with `[redacted]`, and `--no-raw-state` replaces every state's;
+see [Redacting the HTML document](https://sfn.yusufaf.dev/guides/cli/#redacting-the-html-document)
+for what they don't cover.
 
-| | **sfn-diagram** | AWS Console visualizer | Mermaid Live Editor |
-|---|---|---|---|
-| Input | ASL, CloudFormation/SAM/CDK templates, live AWS state machines | Deployed state machine only | Manual Mermaid you write by hand |
-| Output | SVG, Mermaid, PNG, interactive HTML | Static graph in-browser | Mermaid diagram only |
-| CI / PR integration | [GitHub Action](https://sfn.yusufaf.dev/ecosystem/github-action/) or [GitLab CI](https://sfn.yusufaf.dev/ecosystem/gitlab/) posts a diff overlay on every PR/MR that touches ASL | None | None |
-| Execution overlays | Paints a real run's path/status/duration onto the diagram | Basic per-execution highlighting, console-only | Not applicable |
-| Runs where | CLI, Node, browser, edge runtimes | AWS Console only | Web app only |
-| Automation | Full programmatic API (`generateSvg`, `generateMermaid`, etc.) | None — UI only | None — UI only |
+```bash
+sfn-diagram my-workflow.asl.json --format html --redact-fields Parameters,Arguments -o share.html
+```
 
-In short: reach for the AWS Console visualizer to eyeball a state machine you already deployed, reach for Mermaid Live if you're hand-drawing a diagram from scratch — reach for sfn-diagram when you want diagrams generated automatically from your actual definition, checked into CI, and diffed on every pull request.
+The CLI exits `0` on success, `1` when something goes wrong while running — including a failed
+AWS call — and `2` when the invocation itself was wrong, so a CI job can tell a bad flag
+from a bad definition. See
+[Exit codes](https://sfn.yusufaf.dev/guides/cli/#exit-codes).
 
 ## Features
 
-- **Multiple Output Formats**: SVG (D3.js), Mermaid syntax, and PNG
+- **Multiple Output Formats**: SVG, Mermaid syntax, a self-contained interactive HTML viewer, 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, plus `Catch`/`Retry` rendering
 - **Modern ASL**: Variables (`Assign`) shown per state, and Distributed Map rendered distinctly from an inline Map — including its `MaxConcurrency`, `ItemReader` source, and `ResultWriter` sink
 - **Visual Diffing**: Compare two definitions and highlight added / modified / removed states — drives the PR-preview GitHub Action
 - **Linting**: `lintAsl()` returns every structural and semantic finding at once (unreachable states, dangling transitions, `End` with `Next`, JSONPath/JSONata field mixing, …); `sfn-diagram --check` fails CI on errors
-- **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. From a saved history file or live from an execution ARN, and `--follow` keeps re-rendering until the run finishes
-- **Customizable Themes**: AWS light/dark themes plus custom theme support
+- **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. From a saved history file or live from an execution ARN, and `--follow` keeps re-rendering until the run finishes; with `--format html` it can be painted onto a `--diff` in the same viewer
+- **Customizable Themes**: AWS light/dark themes, an `auto` theme that follows the system colour scheme, plus custom theme support
 - **Flexible Layouts**: Top-bottom, left-right, right-left, bottom-top
 - **Type-Safe**: Full TypeScript support with comprehensive type definitions
 - **AWS SDK Integration**: Direct integration with AWS Step Functions API, from the API (`generateFromAwsResponse`) or the CLI (`--from-aws <arn>`)
 - **Dual APIs**: Function-based and class-based interfaces
 - **Runs Anywhere**: SVG and Mermaid generation has zero platform dependencies — works in Node, the browser, and edge runtimes
 - **Collapse Large Diagrams**: Replace Parallel/Map containers with placeholder nodes before layout so huge diagrams stay readable, with a live toggle in the interactive HTML viewer. See the [configuration guide](https://sfn.yusufaf.dev/guides/configuration/) for `collapse` and every other option.
+- **Layout Cache**: `createLayoutCache()` keeps dagre layouts between renders that don't change geometry, such as a light/dark theme switch, so a long-lived host re-renders a large diagram without laying it out again. Opt-in and bounded; see [Reusing layouts across renders](https://sfn.yusufaf.dev/guides/configuration/#reusing-layouts-across-renders).
 
 ## Supported state types