graphomaton 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01b9006b89b4b5e93348f4dd47e9c8173ed036a8cffb357a165f68d1048e8be6
-  data.tar.gz: 2b8c1975ce405f8ffa6a2f550431281cc82605f536b76efa72d6e092e05902bc
+  metadata.gz: 168a8c5641230bf2da705a71bbc3156757a0cc820047d47f18c1c69f3ab08f0a
+  data.tar.gz: 52152b9aded87cdae3bca6f47bddd5cded06c91f7c7c4ca8450c0e1b51401084
 SHA512:
-  metadata.gz: 538893d73e2cdbcfe697bcf194ab259c7c796d6efdb9cd100b810ed7aa5363144819880d6d813ec76dc9350d455bdb232608b7b0ec39c00efa664cba54bcc2bd
-  data.tar.gz: 41e703f607023ceebd0aba66965084f3466cd60b414a3ba14670cc0f4e6d82391e18cd64d47911d80efa28dbb4f05378ea693de3ebb0461f84a465e9721de9ca
+  metadata.gz: 3cb2d71e65478459dc6cd4968cffcaeb13681124143116f73a5c175de394f55dc14b1335b6a2cae111f07903ddbd2235aa9b62fd18fed233bcde2b3f266f0b7e
+  data.tar.gz: c86a638ddb2d0c98bb05a39e396abbe541e483de706dba43437a368462cc3f9d2c2d0460b0152780dccf553d3bfa2d25b9f2d2a6dae5dff7a6cfdaa33ce7b5c3

data/CHANGELOG.md

@@ -1,16 +1,120 @@
-# Change log
+# Changelog
 
-## Unreleased
+All notable changes to Graphomaton are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+follows [Semantic Versioning](https://semver.org/).
 
-## 1.0.0 (2025-12-23)
+## [Unreleased]
 
-- Add support multiple style outputs, including .dot, mermaid, and .plantuml formats.
-- Improve output format for SVG files.
+## [1.2.0] - 2026-09-08
 
-## 0.1.1 (2025-08-26)
+### Added
 
-Fix gemspec dependency declaration for 'rexml'.
+- Added a public GitHub Pages landing page for the project.
+- Added CLI selection for reference, FSM-semantic, DFA, and combined validation
+  profiles.
+- Added structured mixed epsilon/symbol labels that retain their semantics
+  through Hash, JSON, and YAML round trips.
 
-## 0.1.0 (2025-08-26)
+### Changed
+
+- Stronger CLI validation profiles now include reference checks, and exporter
+  semantic diagnostics distinguish state and transition tooltips.
+- SVG rendering now reuses immutable state snapshots and linear state ordering
+  while preserving folded-state kinds and unrelated self-loops.
+- Updated the RubyGems trusted-publishing action to 1.4.1.
+
+### Fixed
+
+- Corrected long-word wrapping, explicit-position tracking, duplicate SVG IDs,
+  numeric-root style scoping, auto-sized bounds, and stale clipping diagnostics.
+- Enforced final SVG and scaled PNG dimension limits before conversion, including
+  overflow and non-real numeric inputs.
+- Made metadata-depth checks independent of Hash insertion order and rejected
+  boolean state identifiers consistently at input boundaries.
+- Preserved option-dependent tooltip semantics in strict rendering and retained
+  epsilon meaning in array transition labels.
+- Made `--no-clobber` atomic, including theme-gallery output races and friendly
+  CLI failures.
+
+### Security
+
+- Rejected escaped, comment-obfuscated, and alternate CSS resource functions in
+  themes and per-element SVG styles.
+- Ensured timed-out Unix process groups are terminated even when the direct
+  parent exits first.
+
+## [1.1.0] - 2026-08-13
+
+### Added
+
+- Immutable model records, update/remove APIs, graph revision caches, structured
+  labels, diagnostics, validation profiles, exporter capabilities, semantic-loss
+  reporting, render results, IO output, and RBS signatures.
+- Obstacle-aware curves, adaptive self-loops, spatial label indexing, Barnes-Hut
+  force approximation, deterministic force-layout separation, and convergence
+  detection.
+- CLI commands for validation, discovery, diagnostics, health checks, config
+  files, shell completions, and man-page output.
+- Bounded stdin/stdout workflows, no-clobber protection, format-specific option
+  errors, structured exit statuses, and `--version`.
+- Nonce-based CSP support, trusted local asset inlining for self-contained HTML,
+  and deterministic HTML asset loading with localized generated UI.
+- Restricted gem packaging, gem installation smoke tests, renderer integration
+  jobs, release automation, and immutable GitHub Actions pins.
+
+### Changed
+
+- Curved and orthogonal edges are routed from geometry instead of insertion
+  order, and SVG viewBoxes include rendered paths, shapes, rotated labels, and
+  text content.
+- PNG scaling is separated from logical layout and SVG geometry; layout
+  diagnostics and metadata survive PNG, PDF, and WebP conversion.
+- SCC analysis is iterative and linear-time. Fixed manual positions remain clear
+  of automatic layouts, and dense graphs receive adaptive spacing.
+- Structured transition labels and format-independent pseudostate kinds are kept
+  in the model, while custom exporter registration now produces renderable
+  exporters and rejects ambiguous schema aliases.
+- HTML pan/zoom controls are more accessible, and text exporters terminate
+  output with a newline after normalizing CR/LF label boundaries.
+
+### Fixed
+
+- Corrected force-layout attraction direction, boundary clamping, and analysis
+  of undefined transition endpoints.
+- Isolated states are declared in DOT, Mermaid, and PlantUML output.
+- DOT, Mermaid, PlantUML, and Graphviz layout identifiers are collision-free,
+  including reserved names, hostile text, mixed-type model IDs, and groups.
+- SVG parallel-transition merging preserves presentation metadata and uses
+  tuple endpoint keys; edge endpoints now respect ellipse, diamond, bar, and
+  rounded-rectangle boundaries.
+- Input validation now rejects duplicate states, malformed transition tuples,
+  conflicting initial states, invalid state hierarchies, ignored value types,
+  and non-finite rendering numbers.
+- Partial state upserts preserve omitted coordinates and effective no-op updates
+  do not advance the graph revision.
+
+### Security
+
+- Added URL, HTML JavaScript, theme, and SVG style policies, including safe
+  handling of JavaScript strings, trusted local assets, Windows asset paths, and
+  unsafe URL schemes; Mermaid.js is pinned to 10.9.8.
+- External processes are bounded by timeout and stdout/stderr limits, with
+  portable executable discovery and process termination on Windows.
+- JSON and YAML input, state and transition counts, metadata depth, label size,
+  hierarchy depth, and converter resources are bounded.
+- Exported files are written atomically, and embedded scripts enforce size,
+  encoding, and digest checks.
+
+## [1.0.0] - 2025-12-23
+
+- Add support for multiple output styles, including DOT, Mermaid, and PlantUML.
+- Improve SVG output formatting.
+
+## [0.1.1] - 2025-08-26
+
+- Fix the gemspec dependency declaration for `rexml`.
+
+## [0.1.0] - 2025-08-26
 
 - Initial release

data/README.md

@@ -1,105 +1,488 @@
 # Graphomaton [![Gem Version](https://badge.fury.io/rb/graphomaton.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/graphomaton) [![CI](https://github.com/ydah/graphomaton/actions/workflows/ci.yml/badge.svg)](https://github.com/ydah/graphomaton/actions/workflows/ci.yml)
 
-A tiny Ruby library for generating finite state machine (automaton) diagrams in multiple formats: SVG, HTML (Mermaid.js), GraphViz (DOT), and PlantUML.
+A Ruby toolkit for validating, analyzing, laying out, and exporting finite state machines as SVG, PNG, PDF, WebP, Mermaid.js HTML, GraphViz DOT, and PlantUML.
 
 ![Image](https://github.com/user-attachments/assets/6907869c-1077-4a73-8394-4117f25adc17)
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
 gem 'graphomaton'
 ```
 
-And then execute:
-
 ```bash
 bundle install
-```
-
-Or install it yourself as:
-
-```bash
+# or
 gem install graphomaton
 ```
 
-## Usage
+## Quick start
 
 ```ruby
 require 'graphomaton'
 
-# Create a DFA that accepts strings ending with 'ab'
 automaton = Graphomaton.new
-
-# Add states
-automaton.add_state('q0')
+automaton.add_state('q0', label: 'Start')
 automaton.add_state('q1')
-automaton.add_state('q2')
-
-# Set initial and final states
+automaton.add_state('q2', label: 'Accept')
 automaton.set_initial('q0')
 automaton.add_final('q2')
 
-# Add transitions
 automaton.add_transition('q0', 'q1', 'a')
 automaton.add_transition('q1', 'q2', 'b')
-automaton.add_transition('q0', 'q0', 'b')
-automaton.add_transition('q1', 'q0', 'a')
-automaton.add_transition('q2', 'q0', 'b')
-automaton.add_transition('q2', 'q1', 'a')
+automaton.add_transition('q0', 'q2', :epsilon)
+
+automaton.save_svg('diagram.svg')
+automaton.save_html('diagram.html')
+automaton.save_dot('diagram.dot')
+automaton.save_plantuml('diagram.puml')
+```
+
+Use `render` and `save` when the format is selected dynamically:
+
+```ruby
+automaton.render(format: :svg, width: 800, height: 600)
+automaton.save('diagram.svg', format: :svg, width: 800, height: 600)
+```
 
-# Save in different formats
-automaton.save_svg('output.svg')              # SVG format
-automaton.save_html('output.html')            # HTML with Mermaid.js (requires internet)
-automaton.save_dot('output.dot')              # GraphViz DOT format
-automaton.save_plantuml('output.puml')        # PlantUML format
+Validate and inspect the automaton before rendering:
+
+```ruby
+automaton.validate!
+automaton.layout_warnings(800, 600)
+automaton.reachable_states
+automaton.dead_states
+automaton.trap_states
 ```
 
-### Output Formats
+## Loading data
 
-Graphomaton supports multiple output formats:
+Build an automaton from Hash, JSON, or YAML:
 
-#### 1. SVG (Native)
 ```ruby
-automaton.save_svg('diagram.svg', width = 800, height = 600)
+automaton = Graphomaton.from_hash(
+  states: [
+    { id: 'q0', label: 'Start', initial: true },
+    { id: 'q1', final: true }
+  ],
+  transitions: [
+    { from: 'q0', to: 'q1', label: 'a', line_style: 'dashed' }
+  ]
+)
+
+Graphomaton.from_json(File.read('automaton.json'))
+Graphomaton.from_yaml(File.read('automaton.yml'))
 ```
-Generates a standalone SVG file with custom rendering.
 
-#### 2. HTML (Mermaid.js)
+JSON and YAML parsing is bounded by default to 10 MiB, 10,000 states, and
+100,000 transitions. Lower or raise those limits explicitly for trusted input:
+
+```ruby
+Graphomaton.from_json(
+  File.open('automaton.json'),
+  max_input_bytes: 2 * 1024 * 1024,
+  max_states: 2_000,
+  max_transitions: 20_000
+)
+```
+
+YAML aliases are disabled by default. Only enable `aliases: true` for trusted
+documents that require them.
+
+## Examples
+
+### Styled SVG with metadata
+
+```ruby
+automaton = Graphomaton.new
+automaton.add_state(
+  'idle',
+  label: 'Idle',
+  metadata: { tooltip: 'Waiting for work', group: 'runtime', icon: 'I' }
+)
+automaton.add_state(
+  'running',
+  label: 'Running',
+  metadata: { tooltip: 'Processing job', group: 'runtime', url: 'https://example.com/runbook' }
+)
+automaton.add_state('failed', label: 'Failed', style: { fill: '#fee2e2', stroke: '#dc2626' })
+
+automaton.set_initial('idle')
+automaton.add_transition('idle', 'running', 'start', metadata: { bundle: 'happy-path' })
+automaton.add_transition('running', 'idle', 'finish', metadata: { bundle: 'happy-path' })
+automaton.add_transition('running', 'failed', 'error', line_style: :dashed)
+
+automaton.save_svg(
+  'runtime.svg',
+  900,
+  500,
+  layout: :layered,
+  direction: :lr,
+  theme: :ocean,
+  edge_style: :spline,
+  label_tooltips: true,
+  html_tooltips: true
+)
+```
+
+### Manual coordinates
+
+```ruby
+automaton = Graphomaton.new
+automaton.add_state('north', 300, 80)
+automaton.add_state('east', 520, 260)
+automaton.add_state('south', 300, 440)
+automaton.add_state('west', 80, 260)
+
+automaton.add_transition('north', 'east', 'turn')
+automaton.add_transition('east', 'south', 'turn')
+automaton.add_transition('south', 'west', 'turn')
+automaton.add_transition('west', 'north', 'turn')
+
+automaton.save_svg('manual.svg', 600, 520, layout: :manual, fit: :contain)
+```
+
+### Folded groups
+
+```ruby
+automaton = Graphomaton.new
+automaton.add_state('parse', metadata: { group: 'frontend' })
+automaton.add_state('validate', metadata: { group: 'frontend' })
+automaton.add_state('execute', metadata: { group: 'backend' })
+automaton.add_state('persist', metadata: { group: 'backend' })
+
+automaton.add_transition('parse', 'validate', 'ok')
+automaton.add_transition('validate', 'execute', 'accepted')
+automaton.add_transition('execute', 'persist', 'done')
+
+automaton.save_svg('folded.svg', layout: :layered, fold_groups: true)
+```
+
+### YAML input for the CLI
+
+```yaml
+states:
+  - id: idle
+    label: Idle
+    initial: true
+    metadata:
+      group: runtime
+      tooltip: Waiting for work
+  - id: running
+    label: Running
+    metadata:
+      group: runtime
+  - id: done
+    final: true
+transitions:
+  - from: idle
+    to: running
+    label: start
+  - from: running
+    to: done
+    label: finish
+    line_style: dashed
+```
+
+```bash
+graphomaton --input automaton.yml --output runtime.svg --layout layered --direction lr --theme ocean
+```
+
+### Export several formats
+
+```ruby
+outputs = {
+  svg: 'diagram.svg',
+  html: 'diagram.html',
+  dot: 'diagram.dot',
+  plantuml: 'diagram.puml'
+}
+
+outputs.each do |format, path|
+  automaton.save(path, format: format)
+end
+```
+
+## CLI
+
+```bash
+graphomaton --input automaton.yml --output diagram.svg
+graphomaton --input automaton.yml --output diagram.svg --layout-warnings
+graphomaton --input automaton.json --output diagram.png --format png --theme dark --scale 2 --timeout 15 --max-output-bytes 33554432
+graphomaton --input automaton.yml --output diagram.html --title "Automaton" --show-source --pan-zoom
+graphomaton --input automaton.yml --output diagram.dot --rank-constraints
+cat automaton.yml | graphomaton --input - --output - --format svg > diagram.svg
+graphomaton --version
+```
+
+The command interface also supports structured workflows:
+
+```bash
+graphomaton render automaton.yml diagram.svg
+graphomaton validate automaton.yml --diagnostics json
+graphomaton validate automaton.yml --profile fsm_semantics --fail-on-warning
+graphomaton validate automaton.yml --profile dfa
+graphomaton list formats
+graphomaton list layouts
+graphomaton doctor
+graphomaton completion zsh > _graphomaton
+graphomaton man > graphomaton.1
+```
+
+Project defaults may be stored in `.graphomaton.yml`; command-line options override
+environment variables, which override the config file:
+
+```yaml
+svg:
+  theme: dark
+  layout: layered
+  labels:
+    wrap: true
+```
+
+The CLI validates state references and hierarchy by default. The `validate` command also defaults to that `references` profile; use `--profile fsm_semantics`, `--profile dfa`, or `--profile all` for stronger checks. `--no-validate` is available for intentionally deferred or partial diagrams. Standard input auto-detects JSON documents that start with `{` or `[`, otherwise YAML is assumed; use `--input-format` to override it. `--format` is required when `--output -` is used. Input limits can be lowered with `--max-input-bytes`, `--max-states`, `--max-transitions`, `--max-metadata-depth`, `--max-label-length`, and `--max-group-depth`. Use `--no-clobber` to protect an existing output (and `--force` to opt back into replacement). Usage, parse, validation, conversion, and security failures use distinct exit statuses and are reported without backtraces.
+
+Common SVG options:
+
+```bash
+graphomaton --input automaton.yml --output diagram.svg --layout layered --direction lr
+graphomaton --input automaton.yml --output diagram.svg --layout force --node-spacing 140 --force-iterations 80 --layout-seed 42
+graphomaton --input automaton.yml --output diagram.svg --layout graphviz --graphviz-command dot
+graphomaton --input automaton.yml --output diagram.svg --responsive --fit cover --auto-size
+graphomaton --input automaton.yml --output diagram.svg --state-shape ellipse --edge-style spline --arrow-shape vee
+graphomaton --input automaton.yml --output diagram.svg --wrap-labels --state-wrap --label-tooltips --html-tooltips
+graphomaton --input automaton.yml --output diagram.svg --highlight-unreachable --unreachable-zone right --highlight-dead-states
+graphomaton --input automaton.yml --output diagram.svg --scc-groups --fold-groups
+graphomaton --input automaton.yml --output diagram.svg --theme-file theme.yml
+```
+
+Theme utilities:
+
+```bash
+graphomaton --list-themes
+graphomaton --theme-gallery --output theme_gallery.html
+graphomaton --theme-gallery --theme-gallery-animated --theme-file theme.yml --output theme_gallery.html
+```
+
+For a self-contained HTML file, provide trusted local classic-script assets:
+
+```bash
+graphomaton render automaton.yml diagram.html \
+  --cdn ./vendor/mermaid.min.js \
+  --self-contained --mermaid-sha256 HEX_DIGEST \
+  --nonce generated-nonce-123 --csp
+```
+
+`--self-contained` does not download assets. It embeds the local files named by
+`--cdn` and, when MathJax is enabled, `--mathjax-cdn`. These files execute with the
+document's authority and must be trusted. `--nonce` plus `--csp` applies the nonce
+to every generated script and style and emits a CSP meta tag. The optional
+`--mermaid-sha256` and `--mathjax-sha256` values detect local asset replacement
+before inlining.
+
+## Themes
+
+Native SVG and SVG-backed outputs support named or custom themes:
+
+```ruby
+automaton.save_svg('diagram.svg', theme: :dark)
+automaton.save_png('diagram.png', theme: :forest)
+automaton.save_svg('diagram.svg', theme: :auto) # follows prefers-color-scheme
+
+theme = Graphomaton.theme_from_yaml(File.read('theme.yml'))
+automaton.save_svg('diagram.svg', theme: theme)
+
+Graphomaton::Theme.save_gallery_html('theme_gallery.html')
+```
+
+Built-in themes:
+
+```text
+light, dark, forest, ocean, high_contrast, color_blind, print, minimal, academic, presentation, auto
+```
+
+## SVG output
+
+SVG is Graphomaton's native renderer. It supports multiple layouts, styling options, metadata-driven annotations, and converter-backed raster/vector outputs.
+
+### Layouts
+
+```ruby
+automaton.save_svg('diagram.svg', 800, 600, layout: :linear, direction: :lr)
+automaton.save_svg('diagram.svg', 800, 600, layout: :circle)
+automaton.save_svg('diagram.svg', 800, 600, layout: :grid)
+automaton.save_svg('diagram.svg', 800, 600, layout: :layered)
+automaton.save_svg('diagram.svg', 800, 600, layout: :bfs)
+automaton.save_svg('diagram.svg', 800, 600, layout: :force, layout_seed: 42)
+automaton.save_svg('diagram.svg', 800, 600, layout: :graphviz, graphviz_command: 'dot')
+automaton.save_svg('diagram.svg', 800, 600, layout: :manual)
+```
+
+Layout notes:
+
+- `direction` accepts `:lr`, `:tb`, `:rl`, and `:bt`.
+- `layout` accepts `:linear`, `:circle`, `:grid`, `:layered`, `:bfs`, `:force`, `:graphviz`, `:dot`, and `:manual`.
+- `:layered` and `:bfs` use deterministic barycenter ordering to reduce crossings.
+- `:force` accepts `padding`, `node_spacing`, `rank_spacing`, `force_iterations`, and `layout_seed`.
+- `:graphviz` and `:dot` call `dot -Tplain` through `graphviz_command:` and normalize returned node coordinates into the SVG canvas.
+- `preserve_manual_positions: false` lets automatic layouts reposition states with explicit coordinates.
+- `fit: :contain` fits positions into the canvas; `fit: :cover` stretches positions to use the canvas.
+- `auto_size: true` expands the SVG viewport around rendered positions.
+
+### Styling and labels
+
+```ruby
+automaton.save_svg('diagram.svg', state_shape: :ellipse)
+automaton.save_svg('diagram.svg', state_stroke_width: 3, transition_stroke_width: 2)
+automaton.save_svg('diagram.svg', edge_style: :orthogonal)
+automaton.save_svg('diagram.svg', arrow_shape: :vee, arrow_size: 14)
+automaton.save_svg('diagram.svg', state_effect: :shadow)
+automaton.save_svg('diagram.svg', font_family: '"Noto Sans JP", sans-serif', state_font_weight: 700)
+
+automaton.save_svg('diagram.svg', wrap: true, max_transition_label_width: 120)
+automaton.save_svg('diagram.svg', state_wrap: true, max_state_label_width: 120)
+automaton.save_svg('diagram.svg', label_tooltips: true, html_tooltips: true)
+automaton.save_svg('diagram.svg', rotate_labels: true)
+automaton.save_svg('diagram.svg', label_background: false)
+automaton.save_svg('diagram.svg', label_padding: 16, label_radius: 8, label_border: true)
+```
+
+Other SVG options:
+
+- Default SVG root and marker IDs are deterministic for the graph, layout, and theme. `svg_id:` sets an explicit prefix and should be unique when embedding duplicate diagrams in one HTML document.
+- Embedded CSS selectors and animation names are scoped to the SVG root ID.
+- `css_variables: true` emits theme values as CSS variables.
+- `embed_styles: false` skips the embedded style block.
+- `xml_declaration: true`, `pretty: true`, and `minify: true` control serialization.
+- `initial_arrow_length`, `initial_arrow_label`, `final_arrow_length`, `final_arrow_label`, and `show_final_arrows` control native start/end arrows.
+
+### Metadata
+
+State and transition metadata can enrich generated diagrams without changing state IDs:
+
+```ruby
+automaton.add_state(
+  'q0',
+  label: 'Start',
+  kind: 'choice',
+  metadata: {
+    tooltip: 'Entry point',
+    url: 'https://example.com',
+    group: 'main',
+    icon: 'S'
+  }
+)
+
+automaton.add_transition(
+  'q0',
+  'q1',
+  'next',
+  metadata: {
+    tooltip: 'Main path',
+    bundle: 'primary'
+  }
+)
+```
+
+`kind:` is format-independent and accepts `normal`, `choice`, `fork`, or `join`.
+Exporter-specific shape overrides belong under `metadata.svg`, `metadata.dot`,
+`metadata.mermaid`, or `metadata.plantuml` and do not affect other formats.
+
+Metadata behavior:
+
+- `label` changes the display name while preserving the state ID for transitions.
+- `tooltip` or `description` becomes SVG tooltip text.
+- `url` or `href` creates SVG links and DOT URL attributes.
+- Link URLs may use `https`, `http`, `mailto`, a relative path, or a fragment. Executable and local-file schemes such as `javascript:`, `data:`, and `file:` are rejected.
+- SVG `style` accepts `fill`, `stroke`, stroke settings, opacity settings, font settings, and `color`; raw CSS properties, `url(...)`, and declaration-breaking values are rejected.
+- `group` or `cluster` renders SVG background groups, Mermaid/PlantUML composite states, and DOT clusters.
+- `icon` renders a compact SVG icon label inside the state.
+- `bundle` routes native SVG edges through a shared control point and emits `data-bundle`.
+- `kind` defines a format-independent `choice`, `fork`, or `join` pseudostate. Format-specific nested metadata remains available for overrides.
+- `parent` defines semantic hierarchy and `group` defines visual grouping; validation rejects setting both on one state, missing parents, and parent cycles.
+- `fold_groups: true` collapses grouped SVG states into compound nodes, hides internal transitions, and rewrites external transitions to the folded node.
+- `scc_groups: true` renders SVG groups around strongly connected components.
+
+## Output formats
+
+| Format | Method | Notes |
+| --- | --- | --- |
+| SVG | `save_svg` | Native renderer. |
+| PNG | `save_png` | Converts native SVG. Requires `rsvg-convert`, `magick`, or `convert`. |
+| PDF | `save_pdf` | Converts native SVG. Requires `rsvg-convert`, `magick`, or `convert`. |
+| WebP | `save_webp` | Converts native SVG. Uses librsvg plus ImageMagick when available, or ImageMagick directly. |
+| HTML | `save_html` | Mermaid.js state diagram in an HTML page. |
+| DOT | `save_dot` | GraphViz DOT source. |
+| PlantUML | `save_plantuml` | PlantUML state diagram source. |
+
+### Converter-backed formats
+
+```ruby
+automaton.save_png('diagram.png', 800, 600, scale: 2.0, converter: :magick)
+automaton.save_pdf('diagram.pdf', 800, 600, converter: :magick, timeout: 15, max_output_bytes: 32 * 1024 * 1024)
+automaton.save_webp('diagram.webp', 800, 600, converter: :magick)
+automaton.save_webp('diagram.webp', 800, 600, converter: :rsvg_magick)
+
+Graphomaton.png_available?(converter: :auto)
+Graphomaton.pdf_available?(converter: :auto)
+Graphomaton.webp_available?(converter: :auto)
+```
+
+PNG `scale:` changes only output pixel density. The logical SVG viewBox, state size, and layout remain unchanged.
+Converter processes default to a 30-second timeout, a 64 MiB output limit, and a 1 MiB diagnostic limit. Timeout and output-limit failures terminate the process group and raise the format-specific `ConversionError`.
+
+### HTML with Mermaid.js
+
 ```ruby
 automaton.save_html('diagram.html')
+automaton.save_html('diagram.html', show_source: true)
+automaton.save_html('diagram.html', theme: :auto)
+automaton.save_html('diagram.html', cdn: './mermaid.min.js', inline_mermaid: true)
+automaton.save_html('diagram.html', pan_zoom: true)
+automaton.save_html('diagram.html', mathjax: true)
+automaton.save_html('diagram.html', notes: true, class_defs: true)
 ```
-Generates an HTML file with embedded Mermaid.js state diagram. The diagram is rendered in the browser using Mermaid.js from CDN.
 
-**Note:** Requires internet connection to load Mermaid.js from CDN. Does not work in offline environments.
+By default, HTML output uses the pinned Mermaid.js 10.9.8 module with Mermaid's strict security level. Remote asset URLs must use HTTPS; relative and absolute local paths are also accepted. `offline: true` requires `cdn:` to name a local classic `.js` build; ES module `.mjs` assets are rejected in offline and inline modes. `inline_mermaid: true` reads and embeds the complete file named by `cdn:`, so use it only with a trusted local JavaScript file. Generated UI is English by default and supports `lang: 'en'` or `lang: 'ja'`.
+
+### GraphViz DOT
 
-#### 3. GraphViz (DOT)
 ```ruby
 automaton.save_dot('diagram.dot')
+automaton.save_dot('diagram.dot', theme: :ocean)
+automaton.save_dot('diagram.dot', rank_constraints: true)
 ```
-Generates a DOT file that can be converted to images using GraphViz:
+
 ```bash
 dot -Tpng diagram.dot -o diagram.png
 dot -Tsvg diagram.dot -o diagram.svg
 dot -Tpdf diagram.dot -o diagram.pdf
+neato -Tsvg diagram.dot -o diagram-neato.svg
+sfdp -Tsvg diagram.dot -o diagram-sfdp.svg
 ```
 
-#### 4. PlantUML
+Use `dot` for ranked state-machine layouts. Use `neato` or `sfdp` for dense graphs where free spreading is preferred.
+
+### PlantUML
+
 ```ruby
 automaton.save_plantuml('diagram.puml')
+automaton.save_plantuml('diagram.puml', theme: :forest)
+automaton.save_plantuml('diagram.puml', notes: true)
 ```
-Generates a PlantUML file that can be converted to images using PlantUML server or JAR:
+
 ```bash
-# Using PlantUML JAR
 java -jar plantuml.jar diagram.puml
-
-# Using online server
 curl -X POST --data-binary @diagram.puml https://www.plantuml.com/plantuml/png > diagram.png
 ```
 
 ## Contributing
 
+Architecture, input schema, CLI, exporter capabilities, performance limits,
+migration, release operations, and custom exporter integration are documented in
+the [`docs/`](docs/) directory. See [Custom exporters](docs/custom-exporters.md)
+when adding an application-specific output format.
+
 Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/graphomaton.
 
 ## License
@@ -108,4 +491,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Graphomaton project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ydah/graphomaton/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Graphomaton project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/ydah/graphomaton/blob/main/CODE_OF_CONDUCT.md).