Evaluate beautiful-mermaid for SVG/ASCII diagram rendering

[darko-mijic]

Context

We generate Mermaid diagrams from source annotations via ArchitectureCodec (src/renderable/codecs/architecture.ts). Currently the universal renderer wraps Mermaid source in ```mermaid fences, relying on client-side rendering (GitHub, VS Code).

beautiful-mermaid (v0.1.3, MIT, by Craft/lukilabs) is a zero-DOM TypeScript library that renders Mermaid → SVG or ASCII/Unicode. It supports flowcharts, state, sequence, class, and ER diagrams with 15 built-in themes and Shiki compatibility.

Spike Results

Tested against our actual generated ARCHITECTURE.md Mermaid content.

What Works

Test	Result
SVG — small filtered diagram (8 nodes, 2 subgraphs)	Excellent. Clean layout, proper subgraph containment, readable arrows
SVG — full 105-node diagram (10 subgraphs)	Good. Proper bounded context grouping, scrollable. 53KB, 133ms
SVG — themed (tokyo-night, github-light)	Works. CSS custom properties enable live theme switching
ASCII — small filtered diagram	Good. Unicode box-drawing with subgraph nesting
Solid arrows (-->) and dashed arrows (-.->)	Visually distinct in both SVG and ASCII

Issues Found

Issue	Severity	Detail
Label truncation	High	Labels like ["ProcessAPICLIImpl[service]"] break — inner ] terminates the Mermaid label delimiter. This is a codec-side fix (escape brackets or use different syntax).
ASCII at full scale	High	105-node diagram renders as unusable horizontal band (thousands of chars wide). Only viable for filtered per-context diagrams.
..-> and -->> arrows	Medium	Dotted and open arrow styles may not render correctly. Needs verification — could be v0.1.3 limitation.
Literal quotes in labels	Low	Node labels render with surrounding " characters. Cosmetic.

Performance

Metric	Value
SVG render (105 nodes)	133ms
ASCII render (105 nodes)	613ms
SVG render (8 nodes)	~50ms
Package size	3 additional deps

Recommendation

Use beautiful-mermaid for per-context filtered diagrams — not the full mega-diagram.

Integration Points

1. SVG output mode in render.ts — opt-in alternative to ```mermaid fences for generated docs:

   case 'mermaid':
     if (options.renderMermaidAsSvg) {
       const svg = await renderMermaid(block.content, theme);
       return [svg, ''];
     }
     return ['```mermaid', block.content, '```', ''];

2. ASCII in CLI output pipeline (src/cli/output-pipeline.ts) — render architecture diagrams directly in terminal for process:query -- arch context <name>.

3. Per-context SVG files — generate individual SVG per bounded context instead of one 105-node diagram. The filterContexts option in ArchitectureCodecOptions already supports this.

Prerequisites

• Fix bracket escaping in ArchitectureCodec label generation (architecture.ts:336)
• Verify ..-> and -->> arrow support (or open upstream issue)
• beautiful-mermaid is v0.1.3 — monitor for maturity before hard dependency

References

• Library: https://github.com/lukilabs/beautiful-mermaid
• Live demo: https://agents.craft.do/mermaid
• Our codec: src/renderable/codecs/architecture.ts
• Our renderer: src/renderable/render.ts
• Existing filterContexts support: ArchitectureCodecOptions interface