pi-mermaid-validator

A Pi extension that tells you why a Mermaid diagram did not render in the TUI, instead of silently falling back to raw source.

Pi's built-in Mermaid renderer (grok-mermaid) supports 5 diagram types: graph/flowchart, sequenceDiagram, classDiagram, erDiagram, stateDiagram(-v2). Everything else — gantt, pie, journey, mindmap, timeline, gitGraph, C4, block-beta, … — fails silently and shows the raw code block with no explanation. The same happens on hard syntax errors and when a diagram is wider than the terminal.

This extension detects those cases and appends a visible one-line reason after the block:

⚠️ mermaid 未渲染：图类型不受原生渲染支持（仅支持 graph/flowchart、sequenceDiagram、classDiagram、erDiagram、stateDiagram(-v2)）——换用支持的类型，或安装完整 Mermaid 渲染器

Install

pi install npm:pi-mermaid-validator

Restart or /reload, then ask for a gantt diagram — you will see the warning instead of silent raw source.

How it works

Pi runs its built-in Mermaid transformer first, then extension transformers. A block that survives as raw source means the renderer gave up on it. This extension re-checks the surviving block with the same grok-mermaid library pi itself uses and annotates only when the block genuinely cannot render:

• unsupported diagram type → tells you what is supported
• syntax error → says so
• wider than the terminal → reports the width and, for horizontal graph LR/flowchart LR diagrams, measures a vertical TD variant with the same engine and suggests it when it fits

Valid blocks are never touched. Streaming output and thinking blocks are skipped, so no flicker while the model is mid-diagram.

Design

• No full Mermaid engine (no ~10MB dependency tree) — reuses grok-mermaid, the same lightweight renderer pi already ships
• Does not replace rendering — valid diagrams still render via pi's native path; this extension only annotates failures
• Display-only — nothing is injected into the LLM context
• If grok-mermaid later supports more types, this extension's annotations disappear automatically for them (it checks the render result, not a hardcoded type list)

Known limits

grok-mermaid is a lenient parser — minor syntax slips are auto-repaired (dropped line) and still render, and pi surfaces those cases with its own warning at final render. This extension only covers the silent failure paths. If you need line-precise parser errors for every diagram type, you need the full Mermaid parser (that is what heavier alternatives bundle).

License

MIT