Mermaid Diagram Integration

Mermaid Diagram Integration Guide

This feature renders Mermaid diagrams directly in chat messages and other markdown surfaces, automatically fixing common syntax issues and providing export options.

High-level flow

• 1. Authoring: A model or user outputs a Mermaid block in markdown (mermaid ... ).
• 2. Detection: The markdown renderer detects language-mermaid code blocks and mounts the MermaidBlock component.
• 3. Render or Fix: MermaidBlock tries to parse and render via Mermaid; if parsing fails, a deterministic fixer runs, and optionally an AI-assisted fixer is invoked.
• 4. Display: Successful renders are injected as SVG into the DOM, themed for the editor, and can be exported as PNG.
• 5. Inline preference: If a tool attempts to write a file containing a Mermaid diagram, the system prefers inline rendering in the conversation instead of creating a file.

Where the logic lives

• Rendering and UI (webview):

  • webview-ui/src/components/common/MarkdownBlock.tsx
    • Detects language-mermaid code blocks and routes them to MermaidBlock.
  • webview-ui/src/components/common/MermaidBlock-sypha.tsx
    • Initializes Mermaid with a dark theme, parses and renders diagrams, makes SVG responsive, shows loading/errors, and exposes export via MermaidButton.
  • webview-ui/src/components/common/MermaidButton.tsx and MermaidActionButtons.tsx
    • Houses action buttons (copy/export/etc.) displayed over the rendered diagram container.

• Syntax fixing (webview):

  • webview-ui/src/services/mermaidSyntaxFixer.ts
    • Deterministic fixes: strip fences, decode HTML arrows, remove zero‑width chars, validate with mermaid.parse.
    • AI-assisted fix: posts a fixMermaidSyntax request to the host with an error hint; resolves on mermaidFixResponse.

• Host bridge (VS Code extension side):

  • src/hosts/vscode/VscodeWebviewProvider.ts
    • Handles fixMermaidSyntax messages from the webview.
    • Calls the configured API with a targeted system prompt to correct Mermaid content and replies with mermaidFixResponse.

• Inline-over-file preference (core):

  • src/core/task/ToolExecutor.ts
    • If a write-to-file block contains Mermaid content (either fenced or bare starting with graph|flowchart|sequenceDiagram|classDiagram|stateDiagram|erDiagram|gantt|journey|mindmap|pie), it emits the diagram inline to chat instead of writing a file.

Rendering details

• Theme and init:

  • MermaidBlock-sypha.tsx sets a dark theme (MERMAID_THEME) and calls mermaid.initialize({ startOnLoad: false, securityLevel: "loose", theme: "dark", flowchart: { useMaxWidth: true }, themeVariables: { ... } }).

• Parse and render:

  • Debounced effect calls mermaid.parse(renderCode) then mermaid.render(id, renderCode) and injects returned SVG into a container.
  • After insertion, width/height attributes are removed, preserveAspectRatio is set, and CSS ensures responsiveness.

• Error handling and auto-fix:

  • On parse failure, runs MermaidSyntaxFixer.autoFixSyntax (deterministic). If still invalid, shows an error and keeps original code visible as escaped text.
  • Users can click “Fix with AI,” which triggers autoFixSyntaxWithAI → posts fixMermaidSyntax to the extension → extension uses the active provider to return corrected code → component re-renders.

• Export to PNG:

  • Clicking the SVG area runs svgToPng, which clones the SVG, sets a large width (e.g., 3600), draws onto a canvas with the themed background, and opens the PNG via FileServiceClient.openImage.

Markdown detection

• MarkdownBlock.tsx maps code nodes with language-mermaid to <MermaidBlock code={...} />.
• It also avoids wrapping those blocks with the generic copy button container, since the diagram UI provides its own actions.

Message protocol for AI fixes

• Webview → Host: { type: "fixMermaidSyntax", requestId, text, values: { error } }.
• Host computes a fix using the configured API and replies:
  • { type: "mermaidFixResponse", requestId, success: true, fixedCode } on success
  • { type: "mermaidFixResponse", requestId, success: false, error } on failure

Developer tips

• To change theming: edit MERMAID_THEME and themeVariables in MermaidBlock-sypha.tsx.
• To add more auto-fixes: extend applyDeterministicFixes and optionally the host prompt in VscodeWebviewProvider.
• To support more diagram kinds: update the detection regexes in ToolExecutor.ts and ensure Mermaid version supports them.

Quick start

• Paste a fenced Mermaid block in chat or markdown:

graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Do x]
  B -->|No| D[Do y]

• Ensure the code fence language is exactly mermaid.

Getting Started Workflow (New Users)

1. Paste a Mermaid code block into the chat using ```mermaid fences.
2. If it fails to render, click “Fix with AI” to auto-correct syntax.
3. Click the diagram area to export as PNG if needed.

Export and copy behavior

• Click on the rendered diagram area to export a PNG. The canvas renders at width 3600 for crisp images; height scales automatically.
• The diagram UI provides its own actions; generic copy buttons are suppressed for Mermaid blocks.

Troubleshooting

• Parse error: Unknown diagram type: Ensure the first line starts with a supported keyword (e.g., graph, flowchart, sequenceDiagram).
• Broken arrows or missing edges: HTML-escaped arrows like --> are auto-decoded; try “Fix with AI” if layout still breaks.
• Invisible or clipped diagram: Large graphs may render off-screen; the SVG is responsive (width/height removed), so ensure the container is wide enough.
• Still failing: Click “Fix with AI” to run the extension-side syntax repair and re-render.

Performance and limits

• Rendering is debounced by ~500ms after input changes.
• Very large diagrams can be slow; consider simplifying or splitting.
• SVG responsiveness is applied by removing width/height and setting preserveAspectRatio.

Theming specifics

• Theme variables inherit from VS Code theme variables where available.
• Adjust colors in MERMAID_THEME and extend themeVariables in webview-ui/src/components/common/MermaidBlock-sypha.tsx.

Version and supported types

• Mermaid version is defined in webview-ui/package.json.
• Detection supports: graph, flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, journey, mindmap, pie.

Inline-over-file behavior

• Implemented in src/core/task/ToolExecutor.ts. When file content includes a Mermaid diagram, it’s rendered inline in chat instead of writing the file.