Render Mermaid diagrams instead of describing them in ASCII

[Paul Lizer (paullizer)]

Asking for a diagram came back as ASCII box art in a ```text fence: unreadable, not exportable as a picture, meaningless to a screen reader.

This is not a Mermaid rendering bug. The renderer never saw a mermaid fence.

Two causes

1. Nothing told the model that ```mermaid renders. SimpleChat already attaches capability guidance for inline charts and image proposals when a request calls for one. Diagrams had none, so the model fell back on drawing with keyboard characters. The chart guidance made it worse — it ended with "Do not output Mermaid, matplotlib/Python, Vega, or other chart code blocks", steering the model away from diagrams on any analytical request.

2. The classic UI never rendered mermaid in chat. Mermaid was wired only into the export rasterizer, so a diagram became a picture in an exported Word file or PDF while the same diagram stayed a code block in the conversation it came from. V2 (MermaidDiagram.tsx) was already fine.

Changes

Backend

New functions_diagram_operations.py, mirroring functions_chart_operations.py:

• user_requested_diagram() — matches diagram, flowchart, sequence, architecture, data flow, ERD, state machine, mind map, and phrasings like "turn this into a diagram" or "map out the architecture".
• Guidance that names the fence that actually renders, rules out ASCII art and ```text, maps intent onto supported diagram types, and gives the syntax constraints that decide whether a generated diagram parses first time — quoted node labels above all.

Detection is deliberately narrow so it does not compete with chart detection:

Request	Routed to
draw the request flow	diagram
give me an ERD for the orders table	diagram
visualize revenue by month	chart
plot the sales trend	chart

maybe_append_diagram_system_message() is wired into all three generation paths (agent, model fallback, streaming), inserted after existing system messages and never duplicated.

The chart guidance is rescoped: Mermaid is barred only as a substitute for a data chart, and structural diagrams are explicitly still expected to use a ```mermaid fence.

Classic UI

chat-inline-diagrams.js follows the same extract → tokenize → sanitize → inject → hydrate pipeline as chat-inline-charts.js. Fences are lifted out before marked parses, which also protects diagram source from the table-conversion passes.

• Streaming fence becomes a "Preparing diagram" placeholder instead of being handed half its own source and failing to parse on every token.
• Unparseable diagram falls back to showing its source rather than vanishing — the source is still the answer the model gave.
• SVG cached by theme and source; diagrams re-render on light/dark switch.
• Copy and export still produce the original fence.
• DOMPurify pass over the SVG on top of Mermaid's securityLevel: 'strict'; bindFunctions is never called.

The non-obvious trap

mermaid.initialize() sets global config and mermaid.render() reads it back. Inline chat wants a theme-aware, useMaxWidth diagram; export wants neutral and fixed-size, because a dark, width-constrained diagram does not survive being painted onto a canvas. Whichever configured last would have decided for both — meaning inline rendering could silently corrupt export PNGs.

chat-mermaid-runtime.js now owns the library: it loads the 3.4 MB bundle once (lazily), applies the caller's preset immediately before each render, and serialises renders so config always stays paired with the diagram that asked for it. The rasterizer requests export, chat requests inline. V2 already solves this the same way internally.

Also fixed

Reply previews and text-to-speech were reading internal chart/diagram/image placeholder tokens aloud. Now stripped.

Coverage

Surface	Before	After
V2 chat	Rendered	Rendered
Classic chat	Code block	Rendered
Exports	Image	Image
Model asked for a diagram	ASCII art in text fence	mermaid fence

V2 needed no rendering change — it picks up the guidance and starts receiving diagrams it could already draw.

Testing

10 suites pass:

• test_mermaid_diagram_prompt_guidance.py (new) — intent detection including chart requests that must not trigger it, guidance content, idempotent insertion, wiring on all three paths, and that chart guidance no longer contradicts diagram guidance.
• test_chat_inline_diagram_rendering.py (new) — headless Chromium renders a real diagram and asserts its labels survive; pending placeholder, source fallback, render cache, teardown, fence-detection parity with the rasterizer, and no request leaves the origin.
• test_export_mermaid_browser_rasterizer.py, test_export_mermaid_server_render.py, test_conversation_export_mermaid_tex_images.py — exports unchanged.
• test_chart_tool_prompt_handoff.py, test_v2_rich_rendering.py, test_browser_alert_replacement.py, test_docs_app_surface_coverage.py, test_docs_site_quality.py.

Two export tests pinned Mermaid config strings to the rasterizer file. Those assertions moved to the runtime, preserving their intent (browser and server renderers must still agree on htmlLabels: false, securityLevel: 'strict', suppressErrorRendering: true, neutral theme).

Notes

• Version 0.261.027 → 0.261.028.
• No new enable_* setting and no new chat control, so the generated docs inventory is untouched.
• No new browser dependency; the Mermaid bundle was already vendored.
• Docs: new MERMAID_DIAGRAM_RENDERING.md, corrected the now-stale "the classic chat interface does not render Mermaid" claim in the export doc, plus release notes.