sfn-diagram 0.3.0 → 0.5.1

package/README.md

@@ -2,9 +2,12 @@
 
 [![npm version](https://img.shields.io/npm/v/sfn-diagram.svg)](https://www.npmjs.com/package/sfn-diagram)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Live Playground](https://img.shields.io/badge/playground-live-brightgreen)](https://yusufaf.github.io/sfn-diagram/)
 
 Generate beautiful, interactive diagrams from AWS Step Functions ASL (Amazon States Language) definitions. Supports dual output formats: D3.js-based SVG and Mermaid.js diagram code, plus PNG export.
 
+**▶ [Try it in the live playground](https://yusufaf.github.io/sfn-diagram/)** — paste any ASL definition and preview the diagram instantly, no install required.
+
 ## Features
 
 - **Multiple Output Formats**: SVG (D3.js), Mermaid syntax, and PNG
@@ -15,6 +18,7 @@ Generate beautiful, interactive diagrams from AWS Step Functions ASL (Amazon Sta
 - **Type-Safe**: Full TypeScript support with comprehensive type definitions
 - **AWS SDK Integration**: Direct integration with AWS Step Functions API
 - **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
 
 ## Installation
 
@@ -22,6 +26,50 @@ Generate beautiful, interactive diagrams from AWS Step Functions ASL (Amazon Sta
 npm install sfn-diagram
 ```
 
+## Runtime Support
+
+The core entry (`sfn-diagram`) builds SVG with a DOM-free string renderer, so
+`generateSvg`, `generateMermaid`, `generateDiagram`, and `generateFromAwsResponse`
+run in **Node, browsers, and edge runtimes** (Cloudflare Workers, Vercel Edge, Deno, Bun)
+with no DOM polyfill.
+
+PNG export (`sfn-diagram/png`) and the CLI are **Node-only** — they rely on a headless
+browser (`node-html-to-image`) and Node's filesystem respectively.
+
+```ts
+// Works in Node, browser, and edge:
+import { generateSvg } from 'sfn-diagram';
+
+// Node-only:
+import { exportPng } from 'sfn-diagram/png';
+```
+
+## Command-line Usage
+
+The package ships a CLI for use without writing any JavaScript:
+
+```bash
+npx sfn-diagram state.asl.json --format svg -o diagram.svg
+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`.
+
+## Docker
+
+A prebuilt image is published to GitHub Container Registry with Chromium baked in, so PNG export works out of the box:
+
+```bash
+docker run --rm -v "$PWD":/work ghcr.io/yusufaf/sfn-diagram:latest \
+  /work/state.asl.json --format svg -o /work/diagram.svg
+
+docker run --rm -v "$PWD":/work ghcr.io/yusufaf/sfn-diagram:latest \
+  /work/state.asl.json --format png -o /work/diagram.png
+```
+
+Tags: `latest`, `<major>`, `<major>.<minor>`, `<major>.<minor>.<patch>`.
+
 ## Quick Start
 
 ### Function-based API
@@ -56,15 +104,15 @@ console.log(`Generated ${width}x${height} diagram`);
 ```typescript
 import { SfnDiagramGenerator } from 'sfn-diagram';
 
-const generator = new SfnDiagramGenerator()
-  .setAsl(asl)
-  .setTheme('dark')
-  .setLayout('TB')
-  .setNodeDimensions({ width: 150, height: 80 });
+const generator = new SfnDiagramGenerator({
+  theme: 'dark',
+  layout: 'TB',
+  nodeWidth: 150,
+  nodeHeight: 80,
+});
 
-const { svg } = generator.generateSvg();
-const { mermaid } = generator.generateMermaid();
-const { png } = await generator.exportPng();
+const { svg } = generator.generateSvg({ aslDefinition: asl });
+const { code } = generator.generateMermaid({ aslDefinition: asl });
 ```
 
 ## API Reference
@@ -91,7 +139,7 @@ const result = generateSvg({
   customColors: {}                 // Override colors for specific states
 });
 
-// Returns: { svg: string, width: number, height: number, nodeCount: number }
+// Returns SvgOutput: { svg: string, width: number, height: number, metadata: { edgeCount: number, nodeCount: number } }
 ```
 
 ### generateMermaid(params)
@@ -106,40 +154,43 @@ const result = generateMermaid({
   includeComments: true
 });
 
-// Returns: { mermaid: string, nodeCount: number, edgeCount: number }
+// Returns MermaidOutput: { code: string, metadata: { edgeCount: number, stateCount: number } }
 ```
 
 ### generateDiagram(params)
 
-Generate both SVG and Mermaid output simultaneously.
+Generate a diagram, choosing the output format via the `format` option (defaults to `'svg'`).
 
 ```typescript
 import { generateDiagram } from 'sfn-diagram';
 
-const result = generateDiagram({
+const svgResult = generateDiagram({
   aslDefinition: asl,
   theme: 'dark'
-});
+});                                // Returns SvgOutput
 
-// Returns: { svg: SvgOutput, mermaid: MermaidOutput }
+const mermaidResult = generateDiagram({
+  aslDefinition: asl,
+  format: 'mermaid'
+});                                // Returns MermaidOutput
 ```
 
 ### exportPng(params)
 
-Export diagram as PNG image.
+Export diagram as PNG image. Node-only — imported from the `sfn-diagram/png` subpath.
 
 ```typescript
-import { exportPng } from 'sfn-diagram';
+import { exportPng } from 'sfn-diagram/png';
 
 const result = await exportPng({
   aslDefinition: asl,
   theme: 'light',
-  quality: 1.0,
-  transparent: false
+  pngQuality: 90,               // 1–100 (default 90)
+  backgroundColor: 'transparent'
 });
 
-// Returns: { png: Buffer, width: number, height: number }
-writeFileSync('diagram.png', result.png);
+// Returns PngOutput: { buffer: Buffer, width: number, height: number, metadata: { format: 'png' } }
+writeFileSync('diagram.png', result.buffer);
 ```
 
 ### generateFromAwsResponse(params)
@@ -158,33 +209,39 @@ const response = await client.send(
 );
 
 const { svg } = generateFromAwsResponse({
-  awsResponse: response,
+  response,
   theme: 'dark'
 });
 ```
 
 ### SfnDiagramGenerator Class
 
-Fluent interface for generating diagrams.
+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.
 
 ```typescript
 import { SfnDiagramGenerator } from 'sfn-diagram';
 
-const generator = new SfnDiagramGenerator()
-  .setAsl(asl)
-  .setTheme('dark')
-  .setLayout('LR')
-  .setNodeDimensions({ width: 150, height: 80 })
-  .setSpacing({ rankSeparation: 60, nodeSeparation: 60 })
-  .setEdgeStyle('curved')
-  .setPadding(30);
-
-// Generate outputs
-const svgResult = generator.generateSvg();
-const mermaidResult = generator.generateMermaid();
-const pngResult = await generator.exportPng({ quality: 1.0 });
+const generator = new SfnDiagramGenerator({
+  theme: 'dark',
+  layout: 'LR',
+  nodeWidth: 150,
+  nodeHeight: 80,
+  rankSeparation: 60,
+  nodeSeparation: 60,
+  edgeStyle: 'curved',
+  padding: 30,
+});
+
+// Update options later (chainable)
+generator.setOptions({ theme: 'light' });
+
+// Generate outputs (aslDefinition passed per call)
+const svgResult = generator.generateSvg({ aslDefinition: asl });
+const mermaidResult = generator.generateMermaid({ aslDefinition: asl });
 ```
 
+> PNG export is a standalone function from `sfn-diagram/png` (`exportPng`), not a method on this class.
+
 ## Configuration Options
 
 ### Themes
@@ -408,21 +465,23 @@ const { svg } = generateSvg({ aslDefinition: parallelAsl });
 ### Export Multiple Formats
 
 ```typescript
-import { generateDiagram, exportPng } from 'sfn-diagram';
+import { generateSvg, generateMermaid } from 'sfn-diagram';
+import { exportPng } from 'sfn-diagram/png';
 import { writeFileSync } from 'fs';
 
 // Generate SVG and Mermaid
-const { svg, mermaid } = generateDiagram({ aslDefinition: asl });
-writeFileSync('diagram.svg', svg.svg);
-writeFileSync('diagram.mmd', mermaid.mermaid);
+const { svg } = generateSvg({ aslDefinition: asl });
+const { code } = generateMermaid({ aslDefinition: asl });
+writeFileSync('diagram.svg', svg);
+writeFileSync('diagram.mmd', code);
 
-// Generate PNG
-const { png } = await exportPng({
+// Generate PNG (Node-only)
+const { buffer } = await exportPng({
   aslDefinition: asl,
-  quality: 1.0,
-  transparent: false
+  pngQuality: 90,
+  backgroundColor: 'transparent'
 });
-writeFileSync('diagram.png', png);
+writeFileSync('diagram.png', buffer);
 ```
 
 ## TypeScript Support
@@ -435,10 +494,62 @@ import type {
   DiagramOptions,
   SvgOutput,
   MermaidOutput,
-  PngOutput,
   CustomTheme,
   StateType
 } from 'sfn-diagram';
+
+// PNG types live on the Node-only subpath
+import type { PngOutput, ExportPngParams } from 'sfn-diagram/png';
+```
+
+## Ecosystem
+
+### Playground
+
+An interactive browser-based editor for exploring ASL definitions and previewing diagrams in real time. **[Open the live playground →](https://yusufaf.github.io/sfn-diagram/)** or run it locally from the [`playground/`](playground/) directory.
+
+```bash
+cd playground
+pnpm install
+pnpm dev
+```
+
+Paste any ASL JSON, switch themes, and see the SVG diagram update instantly — no install required beyond the dev server.
+
+### VS Code Extension
+
+Preview Step Functions diagrams directly inside VS Code. Located in [`packages/vscode-sfn-diagram/`](packages/vscode-sfn-diagram/).
+
+**Install from source:**
+```bash
+cd packages/vscode-sfn-diagram
+pnpm install
+pnpm package          # produces vscode-sfn-diagram-*.vsix
+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.
+
+### 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/).
+
+```yaml
+# .github/workflows/sfn-preview.yml
+name: Step Functions Preview
+on:
+  pull_request:
+    paths: ['**/*.asl.json']
+
+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 }}
 ```
 
 ## Contributing