Secure Diagram Rendering

Context

Use this when a frontend needs richer architecture diagrams from untrusted LLM output without falling back to fake CSS overlays or weakening Mermaid security. It applies especially to AKS/Azure visuals where nested subgraphs, multiline subtitles, and shared icon registries matter.

Patterns

• Diagram-first contract: Prefer a raw Mermaid diagram string for grouped architectures; keep nodes/edges only as a legacy fallback.
• ELK over default layout: Register @mermaid-js/layout-elk and set defaultRenderer: 'elk' for cleaner clustered layouts.
• Sanitize before render: Normalize literal \\n to <br/>, then run sanitizeDiagramInput() before Mermaid render. Preserve securityLevel: 'antiscript'.
• Strict icon placeholders: Expand %%icon:name%% only after render, only for allowlisted keys, and only from a shared registry. Unknown keys should collapse to plain text.