Mermaid Formatter

Model output containing a mermaid block:

  "Here's the architecture:
   ```mermaid
   graph TD
       A[Client] -->|HTTP| B[Server]
       B --> C[Database]
       B --> D[Cache]
   ```
   As shown above..."

The formatter:
1. Yields "Here's the architecture:" immediately
2. Buffers the mermaid source
3. Renders to PNG via mmdc
4. Displays inline using terminal protocol
5. Saves artifact to /tmp/jaato_vision/
6. Yields "As shown above..."

# Gold standard renderer (requires Node.js)
npm install -g @mermaid-js/mermaid-cli

# Verify installation
mmdc --version

# 1. Explicit override (always wins)
os.environ["JAATO_MERMAID_BACKEND"] = "kitty"

# 2. Global graphics override
os.environ["JAATO_GRAPHICS_PROTOCOL"] = "sixel"

# 3. Auto-detection from TERM_PROGRAM
#    kitty/ghostty    → Kitty protocol
#    iTerm.app/WezTerm → iTerm2 protocol
#    foot/mlterm       → Sixel protocol

# 4. Universal fallback
#    Everything else   → Unicode half-blocks

# Kitty: sends PNG via escape sequences
ESC_Gf=100,a=T,m=1;base64data...ESC\
ESC_Gm=0;base64data...ESC\

# iTerm2: single OSC escape sequence
ESC]1337;File=inline=1;size=N:base64...BEL

# Sixel: DCS with color palette + bitmap
ESC P0;1;0q"1;1;W;H #0;2;R;G;B ...data... ESC\

# rich_pixels: Unicode half-block characters
▀▀▀▀▀▀▀▀▀  (with ANSI fg/bg colors)
▀▀▀▀▀▀▀▀▀  (2 pixels per cell height)

```mermaid source
    │
    ├── mmdc available?
    │   └── YES → subprocess mmdc → PNG bytes
    │
    ├── mermaid-py available?
    │   └── YES → mermaid.Graph → SVG → cairosvg → PNG bytes
    │
    └── Neither available
        └── Pass through as ```mermaid code block
            + hint: "npm install -g @mermaid-js/mermaid-cli"

graph TD/LR      Flowcharts
sequenceDiagram  Sequence diagrams
classDiagram     Class diagrams
stateDiagram     State diagrams
erDiagram        Entity relationship
gantt             Gantt charts
pie               Pie charts
gitgraph         Git branch diagrams
mindmap          Mind maps
timeline         Timelines
quadrantChart    Quadrant charts
sankey            Sankey diagrams

# Force Kitty protocol (e.g., inside tmux with passthrough)
export JAATO_MERMAID_BACKEND=kitty

# Use dark theme for diagrams
export JAATO_MERMAID_THEME=dark

# Higher resolution for retina displays
export JAATO_MERMAID_SCALE=3

# Disable diagram rendering entirely
export JAATO_MERMAID_BACKEND=off

# Save artifacts to custom directory
export JAATO_VISION_DIR=~/diagrams

{
  "formatters": [
    {"name": "hidden_content_filter", "enabled": true},
    {"name": "diff_formatter", "enabled": true},
    {"name": "table_formatter", "enabled": true},
    {"name": "mermaid_formatter", "enabled": true, "config": {
      "theme": "dark",
      "scale": 2,
      "background": "transparent"
    }},
    {"name": "code_block_formatter", "enabled": true,
     "config": {"line_numbers": true}}
  ]
}

from shared.plugins.mermaid_formatter import create_plugin

formatter = create_plugin()
formatter.initialize({
    "theme": "dark",
    "scale": 2,
    "background": "white",
    "console_width": 120,
})
formatter.set_console_width(terminal_width)

# After rendering a diagram, the output includes:

[rendered diagram inline]
    [saved: /tmp/jaato_vision/mermaid_001.png]

# Multiple diagrams in one turn:
[first diagram]
    [saved: /tmp/jaato_vision/mermaid_001.png]

[second diagram]
    [saved: /tmp/jaato_vision/mermaid_002.png]

Pipeline flow:

  mermaid_formatter (priority 28)
      │
      ├── Renders diagram inline
      ├── Saves PNG to JAATO_VISION_DIR
      │
      ▼
  vision_capture_formatter (priority 95)
      │
      └── Observes rendered output
          for model feedback loop

# Minimal (Unicode half-block rendering only)
pip install jaato

# With mermaid-cli (recommended)
pip install jaato
npm install -g @mermaid-js/mermaid-cli

# Full setup (all optional deps)
pip install jaato[mermaid]
npm install -g @mermaid-js/mermaid-cli

from shared.plugins.mermaid_formatter.renderer import (
    is_renderer_available
)
from shared.terminal_caps import detect

# Check if rendering will work
print(is_renderer_available())  # True/False

# Check which graphics backend will be used
caps = detect()
print(caps["graphics"])  # "kitty"/"iterm"/"sixel"/None