Upload 12 files

.gitattributes

@@ -1,39 +1,3 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
-
 # Auto-detect text files and normalize line endings to LF on checkout.
 * text=auto eol=lf
 
@@ -84,4 +48,3 @@ build/** linguist-generated
 *.bin filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.safetensors filter=lfs diff=lfs merge=lfs -text
-

.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Output files
+*.png
+*.svg
+*.pdf
+!examples/expected/*.png
+!examples/expected/*.svg
+
+# Temp
+*.tmp
+*.log
+puppeteer_cfg_*.json
+mermaid_cfg_*.json
+
+# Node
+node_modules/
+npm-debug.log*
+package-lock.json
+yarn.lock
+.pnpm-debug.log*
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Puppeteer cache (large)
+.cache/
+
+# Coverage
+.coverage
+htmlcov/
+.pytest_cache/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 algorembrant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,354 @@
+---
+title: mermaid-renderer
+emoji: diagram
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: "4.44.0"
+app_file: app.py
+pinned: false
+license: mit
+tags:
+  - mermaid
+  - diagram
+  - visualization
+  - code-generation
+  - developer-tools
+  - png
+  - svg
+  - pdf
+  - cli
+authors:
+  - algorembrant
+---
+
+# mermaid-renderer
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![Node.js](https://img.shields.io/badge/node.js-18%2B-green.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Mermaid CLI](https://img.shields.io/badge/@mermaid--js%2Fmermaid--cli-11%2B-purple.svg)](https://github.com/mermaid-js/mermaid-cli)
+[![Formats](https://img.shields.io/badge/output-PNG%20%7C%20SVG%20%7C%20PDF-orange.svg)](#supported-formats)
+[![Themes](https://img.shields.io/badge/themes-15%20built--in-teal.svg)](#built-in-themes)
+
+Convert Mermaid diagrams to high-quality PNG, SVG, or PDF images from the command line. Supports all diagram types, 15 built-in themes from [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid), batch processing, parallel rendering, and file-watch mode.
+
+---
+
+## Features
+
+- All Mermaid diagram types: flowcharts, sequence, state, class, ER, XY charts
+- 15 curated themes (tokyo-night, catppuccin, dracula, nord, github, etc.)
+- PNG, SVG, and PDF output
+- Batch rendering with parallel workers
+- Watch mode for live re-render on file change
+- Custom background and foreground color overrides
+- Scale factor control for high-DPI output
+- Zero Python runtime dependencies beyond stdlib (Pillow optional)
+
+---
+
+## Requirements
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Python | 3.9+ | Standard library only |
+| Node.js | 18+ | Required by mmdc |
+| npm | 9+ | For installing mmdc |
+| @mermaid-js/mermaid-cli | 11+ | The render engine |
+| Chrome or Chromium | any | Headless browser for rendering |
+
+---
+
+## Installation
+
+### 1. Install Node.js and npm
+
+Download from https://nodejs.org/ or use your package manager:
+
+```bash
+# Ubuntu / Debian
+sudo apt install nodejs npm
+
+# macOS (Homebrew)
+brew install node
+
+# Windows (Chocolatey)
+choco install nodejs
+```
+
+### 2. Install @mermaid-js/mermaid-cli
+
+```bash
+npm install -g @mermaid-js/mermaid-cli
+```
+
+Verify:
+```bash
+mmdc --version
+```
+
+### 3. Install Chrome or Chromium
+
+**Option A — Puppeteer-managed (recommended, automatic):**
+
+```bash
+# After installing mermaid-cli, install its bundled Chrome:
+node -e "const p = require('puppeteer'); p.executablePath();"
+# Or use npx to install it:
+npx puppeteer browsers install chrome
+```
+
+**Option B — System Chromium:**
+
+```bash
+# Ubuntu / Debian
+sudo apt install chromium-browser
+
+# macOS
+brew install --cask google-chrome
+
+# Windows: download from https://www.google.com/chrome/
+```
+
+### 4. Clone this repo and install Python deps
+
+```bash
+git clone https://github.com/algorembrant/mermaid-renderer.git
+cd mermaid-renderer
+pip install -r requirements.txt
+```
+
+### 5. Verify everything works
+
+```bash
+python render.py --check
+```
+
+Expected output:
+```
+mermaid-renderer — environment check
+----------------------------------------
+  Python      : 3.12.3
+  mmdc        : /usr/local/bin/mmdc
+  Chrome/Chrom: /home/user/.cache/puppeteer/chrome/.../chrome
+  mmdc version: 11.12.0
+
+  All dependencies OK. Rendering should work.
+```
+
+---
+
+## Quick Start
+
+### Render a file
+
+```bash
+python render.py diagram.mmd
+# Output: diagram.png
+```
+
+### Inline diagram
+
+```bash
+python render.py --text "graph TD; A[Start] --> B{Decision}; B -->|Yes| C[Done]; B -->|No| D[End]"
+# Output: diagram.png
+```
+
+### SVG output
+
+```bash
+python render.py diagram.mmd -o output.svg
+```
+
+### Apply a theme
+
+```bash
+python render.py diagram.mmd --theme tokyo-night
+python render.py diagram.mmd --theme catppuccin-mocha -o dark.png
+```
+
+---
+
+## Usage Reference
+
+### Single File
+
+| Command | Description |
+|---------|-------------|
+| `python render.py diagram.mmd` | Render to PNG (same name) |
+| `python render.py diagram.mmd -o out.png` | Specify output path |
+| `python render.py diagram.mmd -o out.svg` | SVG output |
+| `python render.py diagram.mmd -o out.pdf` | PDF output |
+| `python render.py --text "graph LR; A-->B"` | Inline diagram text |
+
+### Themes
+
+| Command | Description |
+|---------|-------------|
+| `python render.py d.mmd --theme tokyo-night` | Apply dark theme |
+| `python render.py d.mmd --theme github-light` | Apply light theme |
+| `python render.py d.mmd --bg "#1a1b26" --fg "#a9b1d6"` | Custom colors |
+| `python render.py d.mmd --bg transparent` | Transparent background |
+| `python render.py --list-themes` | Print all built-in themes |
+
+### Quality / Size
+
+| Command | Description |
+|---------|-------------|
+| `python render.py d.mmd --scale 2` | 2x resolution (default) |
+| `python render.py d.mmd --scale 3` | 3x for print quality |
+| `python render.py d.mmd --width 1920` | Set canvas width |
+
+### Batch Mode
+
+| Command | Description |
+|---------|-------------|
+| `python render.py --batch ./diagrams/` | Render all .mmd in directory |
+| `python render.py --batch ./diagrams/ -o ./out/` | Output to separate directory |
+| `python render.py --batch "./diagrams/*.mmd"` | Glob pattern |
+| `python render.py --batch ./diagrams/ --workers 4` | Parallel (4 processes) |
+| `python render.py --batch ./diagrams/ --format svg` | SVG batch output |
+
+### Watch Mode
+
+| Command | Description |
+|---------|-------------|
+| `python render.py diagram.mmd --watch` | Re-render on file change |
+| `python render.py --batch ./diagrams/ --watch` | Watch entire directory |
+
+### Utility
+
+| Command | Description |
+|---------|-------------|
+| `python render.py --check` | Verify environment and deps |
+| `python render.py --list-themes` | List all 15 built-in themes |
+| `python render.py -v diagram.mmd` | Verbose (show mmdc output) |
+| `python render.py --help` | Show help |
+
+---
+
+## Built-in Themes
+
+| Theme | Type | Background | Accent |
+|-------|------|------------|--------|
+| `default` | light | `#FFFFFF` | (derived) |
+| `zinc-light` | light | `#FFFFFF` | (derived) |
+| `zinc-dark` | dark | `#18181B` | (derived) |
+| `tokyo-night` | dark | `#1a1b26` | `#7aa2f7` |
+| `tokyo-night-storm` | dark | `#24283b` | `#7aa2f7` |
+| `tokyo-night-light` | light | `#d5d6db` | `#34548a` |
+| `catppuccin-mocha` | dark | `#1e1e2e` | `#cba6f7` |
+| `catppuccin-latte` | light | `#eff1f5` | `#8839ef` |
+| `nord` | dark | `#2e3440` | `#88c0d0` |
+| `nord-light` | light | `#eceff4` | `#5e81ac` |
+| `dracula` | dark | `#282a36` | `#bd93f9` |
+| `github-light` | light | `#ffffff` | `#0969da` |
+| `github-dark` | dark | `#0d1117` | `#4493f8` |
+| `solarized-light` | light | `#fdf6e3` | `#268bd2` |
+| `solarized-dark` | dark | `#002b36` | `#268bd2` |
+| `one-dark` | dark | `#282c34` | `#c678dd` |
+
+---
+
+## Supported Diagram Types
+
+All Mermaid diagram types are supported:
+
+- Flowcharts (`graph TD`, `graph LR`, etc.)
+- Sequence diagrams (`sequenceDiagram`)
+- State diagrams (`stateDiagram-v2`)
+- Class diagrams (`classDiagram`)
+- Entity-relationship diagrams (`erDiagram`)
+- XY charts / bar / line (`xychart-beta`)
+- Gantt charts (`gantt`)
+- Pie charts (`pie`)
+- Mindmaps (`mindmap`)
+- Journey diagrams (`journey`)
+- Git graphs (`gitGraph`)
+
+---
+
+## Supported Formats
+
+| Format | Extension | Notes |
+|--------|-----------|-------|
+| PNG | `.png` | Raster, recommended for most uses. Use `--scale 2` or `--scale 3` for sharpness. |
+| SVG | `.svg` | Vector, lossless, ideal for web and print. |
+| PDF | `.pdf` | Vector PDF, fitted to diagram bounds. |
+
+---
+
+## Troubleshooting
+
+### mmdc not found
+
+```bash
+npm install -g @mermaid-js/mermaid-cli
+# Then ensure npm bin is on PATH:
+export PATH="$(npm bin -g):$PATH"
+```
+
+### Chrome not found
+
+```bash
+# Install puppeteer-managed Chrome:
+npx puppeteer browsers install chrome
+# Or install system Chrome:
+sudo apt install chromium-browser   # Linux
+brew install --cask google-chrome   # macOS
+```
+
+### Sandbox errors on Linux
+
+Add to your puppeteer config or run with:
+```bash
+# render.py auto-adds --no-sandbox when using puppeteer config
+```
+
+### Diagram renders blank / cut off
+
+Increase canvas width:
+```bash
+python render.py diagram.mmd --width 2000
+```
+
+---
+
+## Project Structure
+
+```
+mermaid-renderer/
+  render.py           Main CLI script
+  requirements.txt    Python dependencies (minimal)
+  README.md           This file
+  .gitignore          Git ignore rules
+  .gitattributes      Git attributes
+  examples/           Sample .mmd files
+    flowchart.mmd
+    sequence.mmd
+    statediagram.mmd
+    classdagram.mmd
+    er.mmd
+    xychart.mmd
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+---
+
+## Author
+
+algorembrant
+
+---
+
+## Acknowledgments
+
+- [mermaid-js/mermaid-cli](https://github.com/mermaid-js/mermaid-cli) — the render engine
+- [lukilabs/beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) — theme system reference
+- [mermaid.js.org](https://mermaid.js.org/) — Mermaid diagram specification

render.py

@@ -0,0 +1,802 @@
+"""
+mermaid-renderer — Convert Mermaid diagrams to images using @mermaid-js/mermaid-cli
+Author: algorembrant
+License: MIT
+
+USAGE COMMANDS
+==============
+
+  Single file:
+    python render.py diagram.mmd
+    python render.py diagram.mmd -o output.png
+    python render.py diagram.mmd -o output.svg
+    python render.py diagram.mmd -o output.pdf
+
+  Inline diagram:
+    python render.py --text "graph TD; A --> B --> C"
+    python render.py --text "sequenceDiagram; Alice->>Bob: Hello"
+
+  Themes (15 built-in from beautiful-mermaid):
+    python render.py diagram.mmd --theme tokyo-night
+    python render.py diagram.mmd --theme catppuccin-mocha
+    python render.py diagram.mmd --theme github-light
+    python render.py diagram.mmd --theme dracula
+    python render.py diagram.mmd --theme nord
+    python render.py diagram.mmd --theme one-dark
+
+  Custom colors:
+    python render.py diagram.mmd --bg "#1a1b26" --fg "#a9b1d6"
+    python render.py diagram.mmd --bg "#ffffff" --fg "#333333" --accent "#0969da"
+
+  Background:
+    python render.py diagram.mmd --background white
+    python render.py diagram.mmd --background transparent
+    python render.py diagram.mmd --background "#1e1e2e"
+
+  Scale / quality:
+    python render.py diagram.mmd --scale 2
+    python render.py diagram.mmd --scale 3
+    python render.py diagram.mmd --width 1920
+
+  Batch (directory or glob):
+    python render.py --batch ./diagrams/
+    python render.py --batch ./diagrams/ -o ./output/ --format png
+    python render.py --batch "./diagrams/*.mmd" --theme tokyo-night --scale 2
+
+  Batch parallel workers:
+    python render.py --batch ./diagrams/ --workers 4
+
+  Watch mode (re-render on change):
+    python render.py diagram.mmd --watch
+    python render.py --batch ./diagrams/ --watch
+
+  List built-in themes:
+    python render.py --list-themes
+
+  Check environment / dependencies:
+    python render.py --check
+
+  Verbose logging:
+    python render.py diagram.mmd -v
+    python render.py --batch ./diagrams/ -v --workers 2
+
+  Help:
+    python render.py --help
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import logging
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+logging.basicConfig(
+    level=logging.WARNING,
+    format="[%(levelname)s] %(message)s",
+)
+log = logging.getLogger("mermaid-renderer")
+
+
+# ---------------------------------------------------------------------------
+# Theme definitions (mirrors beautiful-mermaid THEMES)
+# ---------------------------------------------------------------------------
+THEMES: dict[str, dict] = {
+    "default": {
+        "bg": "#FFFFFF",
+        "fg": "#27272A",
+        "mermaid_theme": "default",
+    },
+    "zinc-light": {
+        "bg": "#FFFFFF",
+        "fg": "#18181B",
+        "mermaid_theme": "default",
+    },
+    "zinc-dark": {
+        "bg": "#18181B",
+        "fg": "#E4E4E7",
+        "mermaid_theme": "dark",
+    },
+    "tokyo-night": {
+        "bg": "#1a1b26",
+        "fg": "#a9b1d6",
+        "accent": "#7aa2f7",
+        "mermaid_theme": "dark",
+    },
+    "tokyo-night-storm": {
+        "bg": "#24283b",
+        "fg": "#c0caf5",
+        "accent": "#7aa2f7",
+        "mermaid_theme": "dark",
+    },
+    "tokyo-night-light": {
+        "bg": "#d5d6db",
+        "fg": "#343b58",
+        "accent": "#34548a",
+        "mermaid_theme": "default",
+    },
+    "catppuccin-mocha": {
+        "bg": "#1e1e2e",
+        "fg": "#cdd6f4",
+        "accent": "#cba6f7",
+        "mermaid_theme": "dark",
+    },
+    "catppuccin-latte": {
+        "bg": "#eff1f5",
+        "fg": "#4c4f69",
+        "accent": "#8839ef",
+        "mermaid_theme": "default",
+    },
+    "nord": {
+        "bg": "#2e3440",
+        "fg": "#d8dee9",
+        "accent": "#88c0d0",
+        "mermaid_theme": "dark",
+    },
+    "nord-light": {
+        "bg": "#eceff4",
+        "fg": "#2e3440",
+        "accent": "#5e81ac",
+        "mermaid_theme": "default",
+    },
+    "dracula": {
+        "bg": "#282a36",
+        "fg": "#f8f8f2",
+        "accent": "#bd93f9",
+        "mermaid_theme": "dark",
+    },
+    "github-light": {
+        "bg": "#ffffff",
+        "fg": "#1F2328",
+        "accent": "#0969da",
+        "mermaid_theme": "default",
+    },
+    "github-dark": {
+        "bg": "#0d1117",
+        "fg": "#e6edf3",
+        "accent": "#4493f8",
+        "mermaid_theme": "dark",
+    },
+    "solarized-light": {
+        "bg": "#fdf6e3",
+        "fg": "#657b83",
+        "accent": "#268bd2",
+        "mermaid_theme": "default",
+    },
+    "solarized-dark": {
+        "bg": "#002b36",
+        "fg": "#839496",
+        "accent": "#268bd2",
+        "mermaid_theme": "dark",
+    },
+    "one-dark": {
+        "bg": "#282c34",
+        "fg": "#abb2bf",
+        "accent": "#c678dd",
+        "mermaid_theme": "dark",
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Environment detection
+# ---------------------------------------------------------------------------
+
+def find_mmdc() -> Optional[str]:
+    """Return path to mmdc binary or None."""
+    # Prefer the npm-global install used by this environment
+    candidates = [
+        shutil.which("mmdc"),
+        shutil.which("mmdc.cmd"),
+        os.path.expanduser("~/.npm-global/bin/mmdc"),
+        os.path.join(os.environ.get("APPDATA", ""), "npm", "mmdc.cmd"),
+        "/usr/local/bin/mmdc",
+        "/usr/bin/mmdc",
+    ]
+    for c in candidates:
+        if c and os.path.isfile(c):
+            return c
+    return None
+
+
+def find_chrome() -> Optional[str]:
+    """Return path to a Chromium/Chrome binary or None."""
+    candidates = [
+        # Windows paths
+        r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+        r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+        os.path.join(os.environ.get("LOCALAPPDATA", ""), r"Google\Chrome\Application\chrome.exe"),
+        # Puppeteer-managed chrome (most reliable in this env)
+        os.path.expanduser(
+            "~/.cache/puppeteer/chrome/linux-131.0.6778.204/chrome-linux64/chrome"
+        ),
+        "/opt/google/chrome/chrome",
+        "/opt/pw-browsers/chromium-1194/chrome-linux/chrome",
+        shutil.which("google-chrome"),
+        shutil.which("chromium"),
+        shutil.which("chromium-browser"),
+        shutil.which("chrome"),
+    ]
+    for c in candidates:
+        if c and os.path.isfile(c):
+            return c
+    return None
+
+
+def build_puppeteer_config(chrome_path: str) -> str:
+    """Write a puppeteer config JSON to a temp file, return its path."""
+    cfg = {
+        "executablePath": chrome_path,
+        "args": [
+            "--no-sandbox",
+            "--disable-setuid-sandbox",
+            "--disable-dev-shm-usage",
+            "--disable-gpu",
+        ],
+    }
+    fd, path = tempfile.mkstemp(suffix=".json", prefix="puppeteer_cfg_")
+    with os.fdopen(fd, "w") as f:
+        json.dump(cfg, f)
+    return path
+
+
+def build_mermaid_config(theme_cfg: dict, bg: Optional[str]) -> str:
+    """Write a mermaid config JSON, return its path."""
+    mermaid_theme = theme_cfg.get("mermaid_theme", "default")
+    cfg: dict = {
+        "theme": mermaid_theme,
+    }
+    if mermaid_theme == "dark":
+        cfg["themeVariables"] = {
+            "darkMode": True,
+            "background": theme_cfg.get("bg", "#1e1e2e"),
+            "primaryColor": theme_cfg.get("accent", theme_cfg.get("fg", "#88c0d0")),
+            "primaryTextColor": theme_cfg.get("fg", "#d8dee9"),
+            "lineColor": theme_cfg.get("accent", "#88c0d0"),
+        }
+    else:
+        cfg["themeVariables"] = {
+            "darkMode": False,
+            "background": theme_cfg.get("bg", "#ffffff"),
+            "primaryColor": theme_cfg.get("accent", "#ececff"),
+            "primaryTextColor": theme_cfg.get("fg", "#333333"),
+            "lineColor": theme_cfg.get("accent", "#333333"),
+        }
+
+    if bg:
+        cfg["themeVariables"]["background"] = bg
+
+    fd, path = tempfile.mkstemp(suffix=".json", prefix="mermaid_cfg_")
+    with os.fdopen(fd, "w") as f:
+        json.dump(cfg, f)
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Core render function
+# ---------------------------------------------------------------------------
+
+def render_diagram(
+    source: str,
+    output_path: str,
+    *,
+    mmdc: str,
+    puppeteer_cfg: str,
+    theme_name: str = "default",
+    bg: Optional[str] = None,
+    scale: float = 2.0,
+    width: Optional[int] = None,
+    fmt: str = "png",
+    verbose: bool = False,
+) -> dict:
+    """
+    Render a Mermaid diagram string to an image file.
+
+    Parameters
+    ----------
+    source       : Mermaid diagram text
+    output_path  : Destination file path
+    mmdc         : Path to mmdc binary
+    puppeteer_cfg: Path to puppeteer config JSON
+    theme_name   : One of THEMES keys or 'default'
+    bg           : Override background color (hex or 'transparent')
+    scale        : Device pixel ratio (default 2 = 2x)
+    width        : Optional canvas width in pixels
+    fmt          : Output format: png | svg | pdf
+    verbose      : Log mmdc stdout/stderr
+
+    Returns
+    -------
+    dict with keys: success, output, error, duration_ms
+    """
+    theme_cfg = THEMES.get(theme_name, THEMES["default"])
+    t0 = time.perf_counter()
+
+    # Write source to temp .mmd file
+    fd, src_path = tempfile.mkstemp(suffix=".mmd", prefix="mermaid_src_")
+    mermaid_cfg_path = None
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(source)
+
+        mermaid_cfg_path = build_mermaid_config(theme_cfg, bg)
+
+        cmd = [
+            mmdc,
+            "-i", src_path,
+            "-o", output_path,
+            "--puppeteerConfigFile", puppeteer_cfg,
+            "--configFile", mermaid_cfg_path,
+            "--scale", str(scale),
+        ]
+
+        if bg == "transparent":
+            cmd += ["-b", "transparent"]
+        elif bg:
+            cmd += ["-b", bg]
+        elif "bg" in theme_cfg:
+            cmd += ["-b", theme_cfg["bg"]]
+
+        if width:
+            cmd += ["-w", str(width)]
+
+        if fmt == "pdf":
+            cmd += ["--pdfFit"]
+
+        log.debug("CMD: %s", " ".join(cmd))
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+
+        duration_ms = int((time.perf_counter() - t0) * 1000)
+
+        if verbose:
+            if result.stdout.strip():
+                print(f"  [mmdc stdout] {result.stdout.strip()}")
+            if result.stderr.strip():
+                print(f"  [mmdc stderr] {result.stderr.strip()}")
+
+        success = result.returncode == 0 and os.path.isfile(output_path)
+        error = None
+        if not success:
+            error = (result.stderr or result.stdout or "mmdc exited with code "
+                     + str(result.returncode)).strip()
+
+        return {
+            "success": success,
+            "output": output_path if success else None,
+            "error": error,
+            "duration_ms": duration_ms,
+        }
+
+    except subprocess.TimeoutExpired:
+        return {
+            "success": False,
+            "output": None,
+            "error": "Render timed out (60s)",
+            "duration_ms": int((time.perf_counter() - t0) * 1000),
+        }
+    except Exception as exc:
+        return {
+            "success": False,
+            "output": None,
+            "error": str(exc),
+            "duration_ms": int((time.perf_counter() - t0) * 1000),
+        }
+    finally:
+        try:
+            os.unlink(src_path)
+        except OSError:
+            pass
+        if mermaid_cfg_path:
+            try:
+                os.unlink(mermaid_cfg_path)
+            except OSError:
+                pass
+
+
+# ---------------------------------------------------------------------------
+# Batch helpers
+# ---------------------------------------------------------------------------
+
+def _batch_worker(args: tuple) -> dict:
+    """Top-level function for ProcessPoolExecutor (must be picklable)."""
+    (
+        src_file, out_file, mmdc, puppeteer_cfg,
+        theme, bg, scale, width, fmt, verbose,
+    ) = args
+    source = Path(src_file).read_text(encoding="utf-8")
+    return {
+        "input": src_file,
+        **render_diagram(
+            source, out_file,
+            mmdc=mmdc, puppeteer_cfg=puppeteer_cfg,
+            theme_name=theme, bg=bg, scale=scale,
+            width=width, fmt=fmt, verbose=verbose,
+        ),
+    }
+
+
+def resolve_batch_inputs(batch_path: str, fmt: str, out_dir: Optional[str]) -> list[tuple[str, str]]:
+    """Return list of (input_path, output_path) tuples for a batch run."""
+    p = Path(batch_path)
+    pairs: list[tuple[str, str]] = []
+
+    if "*" in batch_path or "?" in batch_path:
+        inputs = sorted(glob.glob(batch_path))
+    elif p.is_dir():
+        inputs = sorted(
+            str(f) for f in p.rglob("*")
+            if f.suffix.lower() in {".mmd", ".mermaid", ".txt"}
+            and f.is_file()
+        )
+    elif p.is_file():
+        inputs = [str(p)]
+    else:
+        print(f"[ERROR] Batch path not found: {batch_path}", file=sys.stderr)
+        return []
+
+    for inp in inputs:
+        in_path = Path(inp)
+        if out_dir:
+            out_base = Path(out_dir)
+            out_base.mkdir(parents=True, exist_ok=True)
+            out_file = str(out_base / (in_path.stem + f".{fmt}"))
+        else:
+            out_file = str(in_path.with_suffix(f".{fmt}"))
+        pairs.append((inp, out_file))
+
+    return pairs
+
+
+# ---------------------------------------------------------------------------
+# Watch mode
+# ---------------------------------------------------------------------------
+
+def watch_file(path: str) -> float:
+    try:
+        return os.path.getmtime(path)
+    except OSError:
+        return 0.0
+
+
+def run_watch(
+    input_files: list[str],
+    output_map: dict[str, str],
+    render_kwargs: dict,
+    poll_interval: float = 0.8,
+) -> None:
+    """Poll input files and re-render on modification."""
+    mtimes = {f: watch_file(f) for f in input_files}
+    print(f"Watching {len(input_files)} file(s). Press Ctrl+C to stop.")
+    try:
+        while True:
+            time.sleep(poll_interval)
+            for f in input_files:
+                mtime = watch_file(f)
+                if mtime != mtimes[f]:
+                    mtimes[f] = mtime
+                    print(f"  Changed: {f} — re-rendering...")
+                    source = Path(f).read_text(encoding="utf-8")
+                    result = render_diagram(source, output_map[f], **render_kwargs)
+                    if result["success"]:
+                        print(f"  OK: {result['output']} ({result['duration_ms']}ms)")
+                    else:
+                        print(f"  FAIL: {result['error']}", file=sys.stderr)
+    except KeyboardInterrupt:
+        print("\nWatch mode stopped.")
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="mermaid-renderer",
+        description="Convert Mermaid diagrams to PNG, SVG, or PDF images.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+
+    p.add_argument(
+        "input",
+        nargs="?",
+        help="Path to .mmd / .mermaid file (omit when using --text or --batch)",
+    )
+    p.add_argument(
+        "-o", "--output",
+        default=None,
+        help="Output file path (default: same name as input, auto-extension)",
+    )
+    p.add_argument(
+        "--text",
+        default=None,
+        help="Inline Mermaid diagram text (alternative to file input)",
+    )
+    p.add_argument(
+        "--batch",
+        default=None,
+        metavar="DIR_OR_GLOB",
+        help="Render all .mmd/.mermaid files in a directory or matching a glob",
+    )
+    p.add_argument(
+        "--format", "-f",
+        default="png",
+        choices=["png", "svg", "pdf"],
+        help="Output format (default: png)",
+    )
+    p.add_argument(
+        "--theme", "-t",
+        default="default",
+        choices=list(THEMES.keys()),
+        help="Named theme (default: default)",
+    )
+    p.add_argument(
+        "--bg", "--background",
+        default=None,
+        dest="bg",
+        help='Background color hex or "transparent"',
+    )
+    p.add_argument(
+        "--fg", "--foreground",
+        default=None,
+        dest="fg",
+        help="Foreground color hex (overrides theme fg — informational only)",
+    )
+    p.add_argument(
+        "--accent",
+        default=None,
+        help="Accent color hex (overrides theme accent — informational only)",
+    )
+    p.add_argument(
+        "--scale",
+        type=float,
+        default=2.0,
+        help="Device pixel ratio / scale factor (default: 2.0)",
+    )
+    p.add_argument(
+        "--width", "-W",
+        type=int,
+        default=None,
+        help="Canvas width in pixels",
+    )
+    p.add_argument(
+        "--workers", "-j",
+        type=int,
+        default=1,
+        help="Parallel workers for batch mode (default: 1)",
+    )
+    p.add_argument(
+        "--watch", "-w",
+        action="store_true",
+        help="Watch input files and re-render on change",
+    )
+    p.add_argument(
+        "--list-themes",
+        action="store_true",
+        help="Print all available themes and exit",
+    )
+    p.add_argument(
+        "--check",
+        action="store_true",
+        help="Check environment dependencies and exit",
+    )
+    p.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Show mmdc stdout/stderr",
+    )
+
+    return p
+
+
+def cmd_check() -> None:
+    """Print environment diagnostic info."""
+    mmdc = find_mmdc()
+    chrome = find_chrome()
+
+    print("mermaid-renderer — environment check")
+    print("-" * 40)
+    print(f"  Python      : {sys.version.split()[0]}")
+    print(f"  mmdc        : {mmdc or 'NOT FOUND'}")
+    print(f"  Chrome/Chrom: {chrome or 'NOT FOUND'}")
+
+    if mmdc:
+        try:
+            r = subprocess.run([mmdc, "--version"], capture_output=True, text=True, timeout=5)
+            print(f"  mmdc version: {r.stdout.strip()}")
+        except Exception:
+            print("  mmdc version: (could not query)")
+
+    if mmdc and chrome:
+        print("\n  All dependencies OK. Rendering should work.")
+    else:
+        missing = []
+        if not mmdc:
+            missing.append("mmdc (install: npm install -g @mermaid-js/mermaid-cli)")
+        if not chrome:
+            missing.append("Chrome/Chromium")
+        print("\n  MISSING:", ", ".join(missing))
+        sys.exit(1)
+
+
+def cmd_list_themes() -> None:
+    col_w = 24
+    print(f"\n{'Theme':<{col_w}} {'Type':<8} {'Background':<12} {'Accent'}")
+    print("-" * 64)
+    for name, cfg in THEMES.items():
+        theme_type = "dark" if cfg.get("mermaid_theme") == "dark" else "light"
+        accent = cfg.get("accent", "(derived)")
+        print(f"  {name:<{col_w-2}} {theme_type:<8} {cfg.get('bg',''):<12} {accent}")
+    print()
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.verbose:
+        log.setLevel(logging.DEBUG)
+
+    if args.check:
+        cmd_check()
+        return
+
+    if args.list_themes:
+        cmd_list_themes()
+        return
+
+    # Resolve dependencies
+    mmdc = find_mmdc()
+    chrome = find_chrome()
+
+    if not mmdc:
+        print(
+            "[ERROR] mmdc not found. Install with:\n"
+            "  npm install -g @mermaid-js/mermaid-cli\n"
+            "Then run:  python render.py --check",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if not chrome:
+        print(
+            "[ERROR] No Chrome/Chromium found. See README for install instructions.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    puppeteer_cfg = build_puppeteer_config(chrome)
+
+    # Apply per-run theme overrides
+    theme_cfg = dict(THEMES.get(args.theme, THEMES["default"]))
+    if args.fg:
+        theme_cfg["fg"] = args.fg
+    if args.accent:
+        theme_cfg["accent"] = args.accent
+
+    render_kwargs = dict(
+        mmdc=mmdc,
+        puppeteer_cfg=puppeteer_cfg,
+        theme_name=args.theme,
+        bg=args.bg,
+        scale=args.scale,
+        width=args.width,
+        fmt=args.format,
+        verbose=args.verbose,
+    )
+
+    try:
+        # -----------------------------------------------------------------------
+        # BATCH MODE
+        # -----------------------------------------------------------------------
+        if args.batch:
+            pairs = resolve_batch_inputs(args.batch, args.format, args.output)
+            if not pairs:
+                print("[ERROR] No input files found.", file=sys.stderr)
+                sys.exit(1)
+
+            print(f"Batch: {len(pairs)} file(s) | theme={args.theme} | "
+                  f"format={args.format} | workers={args.workers}")
+
+            if args.watch:
+                input_files = [p[0] for p in pairs]
+                output_map = {p[0]: p[1] for p in pairs}
+                run_watch(input_files, output_map, render_kwargs)
+                return
+
+            if args.workers > 1:
+                worker_args = [
+                    (inp, out, mmdc, puppeteer_cfg,
+                     args.theme, args.bg, args.scale, args.width,
+                     args.format, args.verbose)
+                    for inp, out in pairs
+                ]
+                results = []
+                with ProcessPoolExecutor(max_workers=args.workers) as ex:
+                    futures = {ex.submit(_batch_worker, a): a[0] for a in worker_args}
+                    for fut in as_completed(futures):
+                        results.append(fut.result())
+            else:
+                results = []
+                for inp, out in pairs:
+                    source = Path(inp).read_text(encoding="utf-8")
+                    r = render_diagram(source, out, **render_kwargs)
+                    results.append({"input": inp, **r})
+                    status = "OK" if r["success"] else "FAIL"
+                    print(f"  [{status}] {inp} -> {out} ({r['duration_ms']}ms)")
+                    if not r["success"]:
+                        print(f"         Error: {r['error']}", file=sys.stderr)
+
+            ok = sum(1 for r in results if r["success"])
+            fail = len(results) - ok
+            print(f"\nDone: {ok} succeeded, {fail} failed.")
+            if fail > 0:
+                sys.exit(1)
+            return
+
+        # -----------------------------------------------------------------------
+        # SINGLE FILE OR INLINE TEXT
+        # -----------------------------------------------------------------------
+        if args.text:
+            source = args.text.replace("; ", "\n").replace(";", "\n")
+            default_stem = "diagram"
+        elif args.input:
+            in_path = Path(args.input)
+            if not in_path.is_file():
+                print(f"[ERROR] Input file not found: {args.input}", file=sys.stderr)
+                sys.exit(1)
+            source = in_path.read_text(encoding="utf-8")
+            default_stem = in_path.stem
+        else:
+            parser.print_help()
+            sys.exit(0)
+
+        # Determine output path
+        if args.output:
+            out_path = args.output
+        else:
+            suffix = f".{args.format}"
+            out_path = str(Path(default_stem).with_suffix(suffix))
+
+        print(f"Rendering: {out_path} | theme={args.theme} | format={args.format} | scale={args.scale}")
+
+        result = render_diagram(source, out_path, **render_kwargs)
+
+        if result["success"]:
+            size = os.path.getsize(result["output"])
+            print(f"  OK: {result['output']} ({size:,} bytes, {result['duration_ms']}ms)")
+        else:
+            print(f"  FAIL: {result['error']}", file=sys.stderr)
+            sys.exit(1)
+
+        # Watch mode for single file
+        if args.watch and args.input:
+            run_watch([args.input], {args.input: out_path}, render_kwargs)
+
+    finally:
+        try:
+            os.unlink(puppeteer_cfg)
+        except OSError:
+            pass
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,7 @@
+# mermaid-renderer requirements
+# Core — no external Python packages strictly required beyond stdlib.
+# The heavy lifting is done by @mermaid-js/mermaid-cli (Node.js).
+#
+# Optional: install these for extended image post-processing and CLI polish.
+Pillow>=10.0.0
+click>=8.1.0

samples/classdiagram.mmd

@@ -0,0 +1,25 @@
+classDiagram
+    class Animal {
+        +String name
+        +int age
+        +makeSound() void
+        +move() void
+    }
+    class Dog {
+        +String breed
+        +fetch() void
+        +bark() void
+    }
+    class Cat {
+        +bool indoor
+        +purr() void
+        +scratch() void
+    }
+    class Parrot {
+        +String[] vocabulary
+        +speak() String
+        +fly() void
+    }
+    Animal <|-- Dog
+    Animal <|-- Cat
+    Animal <|-- Parrot

samples/er.mmd

@@ -0,0 +1,31 @@
+erDiagram
+    USER {
+        int id PK
+        string email UK
+        string name
+        datetime created_at
+    }
+    ORDER {
+        int id PK
+        int user_id FK
+        decimal total
+        string status
+        datetime placed_at
+    }
+    ORDER_ITEM {
+        int id PK
+        int order_id FK
+        int product_id FK
+        int quantity
+        decimal unit_price
+    }
+    PRODUCT {
+        int id PK
+        string name
+        decimal price
+        int stock
+    }
+
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ ORDER_ITEM : contains
+    PRODUCT ||--o{ ORDER_ITEM : "is in"

samples/flowchart.mmd

@@ -0,0 +1,11 @@
+graph TD
+    A[Start] --> B{Is authenticated?}
+    B -->|Yes| C[Load Dashboard]
+    B -->|No| D[Show Login]
+    D --> E[Submit Credentials]
+    E --> F{Valid?}
+    F -->|Yes| G[Issue JWT]
+    G --> C
+    F -->|No| H[Show Error]
+    H --> D
+    C --> I[End]

samples/sequence.mmd

@@ -0,0 +1,16 @@
+sequenceDiagram
+    participant User
+    participant API
+    participant DB
+    participant Cache
+
+    User->>API: GET /profile
+    API->>Cache: Check cache
+    alt Cache hit
+        Cache-->>API: Return cached profile
+    else Cache miss
+        API->>DB: SELECT * FROM users WHERE id=?
+        DB-->>API: User row
+        API->>Cache: SET profile (TTL 300s)
+    end
+    API-->>User: 200 OK { profile }

samples/statediagram.mmd

@@ -0,0 +1,11 @@
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Connecting: connect()
+    Connecting --> Connected: success
+    Connecting --> Error: timeout
+    Connected --> Idle: disconnect()
+    Connected --> Reconnecting: connection lost
+    Reconnecting --> Connected: reconnected
+    Reconnecting --> Error: max retries
+    Error --> Idle: reset()
+    Error --> [*]: fatal

samples/xychart.mmd

@@ -0,0 +1,6 @@
+xychart-beta
+    title "Monthly Revenue vs Target"
+    x-axis [Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
+    y-axis "Revenue ($K)" 0 --> 600
+    bar [180, 220, 310, 280, 350, 420, 390, 450, 480, 510, 540, 580]
+    line [200, 240, 260, 300, 320, 360, 380, 400, 430, 460, 500, 560]