Markdown: render mermaid / mmd fences as diagrams in the Web chat

[yishu-ziyu]

Summary

Please render fenced mermaid / mmd blocks as diagrams inside the assistant message, the same way MarkdownText already special-cases math fences and KaTeX.

Today those fences only get Shiki highlighting via CodeBlock. Agents emit Mermaid constantly (flowcharts, sequence diagrams, architecture). In the Web UI they stay as source, so users copy them out to mermaid.live.

Current behavior (0.1.0-rc.6)

MarkdownText → renderCode always ends in CodeBlock except for lang === "math":

// packages/client/ui-primitives — renderCode
const lang = language === undefined ? undefined : /^[\w-]+/.exec(language)?.[0]
if (!context.streaming && lang === "math") {
  return renderTexToReact(`${node.value}\n`, true)
}
return <CodeBlock code={`${node.value}\n`} lang={context.streaming ? undefined : lang} … />

CodeBlock is a highlighted source surface (banner + copy). There is no diagram path for mermaid / mmd.

This is inconsistent with the rest of the markdown family: GFM + KaTeX already treat some fences as presentation, not source.

Why a dynamic / Cordis plugin is the wrong layer

I tried to do this from a session-scoped dynamic plugin first. It cannot look native:

• Live Slots (conversation.chat.node, conversation.chat.turnTail, conversation.input.dock, tool.view.cordis, …) never reach an individual markdown fence.
• Replacing conversation.chat.node / assistant-step would shadow the shipped message renderer.
• Injecting mermaid.js + a MutationObserver over .md-code-block can draw a chart, but it fights React reconciliation, can infinite-loop on its own inserts, and blows up layout (huge SVGs, UI freeze).

So “a card under the composer” or “a DOM patch” is a demo, not a product feature. Native rendering belongs in ui-primitives, next to KaTeX.

Proposed behavior

1. Fence langs: mermaid, mmd (infostring first token, same /^[\w-]+/ split as today).
2. Streaming: while streaming === true, keep the current source CodeBlock (no highlight / no mermaid), matching KaTeX (“highlighting and KaTeX land on the finalize swap”).
3. Settled: render a diagram in place of (or immediately under, still inside) that fence — still in the message bubble, not a dock / overlay.
4. Failure: invalid syntax → keep/fallback to CodeBlock plus a short error line. Never blank the message.
5. Safety: untrusted assistant output. securityLevel: "strict" (or equivalent). No dangerouslySetInnerHTML of model HTML; only mermaid-produced SVG. No click/js callbacks from diagrams.
6. Layout: max-width: 100%, bounded height + scroll (e.g. ~360px). A 20-node graph must not take the viewport or lock the main thread.
7. Copy: keep a way to copy the source (existing copy control is enough).
8. Theme: follow light/dark (neutral / dark, or CSS variables already used by markdown).

Example that should become a chart after the turn settles

graph TD
  A[Start] --> B{Done?}
  B -->|Yes| C[Ship]
  B -->|No| D[Fix]
  D --> B

Loading

Suggested implementation

Smallest change, same shape as the math branch:

Area	Package / file (repo paths)
Fence dispatch	packages/client/ui-primitives — src/markdown/render.tsx (renderCode)
Presenter	new MermaidBlock next to CodeBlock.tsx
Dep	official mermaid (or a slim renderer). Keep ui-primitives zero-cordis.
Lazy load	dynamic import('mermaid') so the boot chunk does not pay for it until a settled mermaid fence appears (same spirit as lazy Shiki grammars).

Pseudo-API (illustrative):

if (!context.streaming && (lang === 'mermaid' || lang === 'mmd')) {
  return <MermaidBlock code={node.value} copyLabel={…} copiedLabel={…} />
}

MermaidBlock would:

• mermaid.initialize({ startOnLoad: false, securityLevel: 'strict', theme })
• mermaid.render(stableId, code) → SVG
• cap SVG size in CSS
• on throw, render <CodeBlock code={code} lang="mermaid" />

No Slot, no Host RPC, no tapIndex, no page-wide observer.

Acceptance criteria

• Settled assistant ```mermaid / ```mmd renders a diagram in the message body.
• Streaming mermaid fences stay source until finalize (no per-token mermaid.parse).
• Bad mermaid does not crash the message or the app.
• Copy still yields the original fence text.
• Diagrams respect light/dark and do not overflow the chat column.
• Opening a long history with several mermaid blocks does not freeze the page (lazy + size cap).
• User-authored MessageText unchanged (literal), unless you explicitly want mermaid there too — I only need assistant markdown.

Out of scope

• mermaid.ink / kroki (needs network, breaks offline, privacy).
• Replacing the whole assistant bubble from a dynamic plugin.
• Editing / live mermaid playground.

Environment

• @deepseek-ai/dsh 0.1.0-rc.6 (dsh web)
• Web GUI markdown via @deepseek-ai/dsh-client-ui-primitives

Happy to send a PR against packages/client/ui-primitives if this direction is acceptable.

[yishu-ziyu]

中文摘要

请在 Web 对话里，把 mermaid / mmd 代码块直接画成图，嵌在助手气泡里，做法对齐现有的 math 围栏 + KaTeX。

现在（0.1.0-rc.6）这些围栏只会走 CodeBlock 的 Shiki 高亮，图出不来，只能复制到 mermaid.live。Agent 经常输出流程图 / 时序图 / 架构图，这个缺口很常见。

动态 Cordis 插件做不到「自然嵌在正文里」：Slot 碰不到单条 markdown 围栏；整页注入 mermaid.js + MutationObserver 会和 React 打架，还容易把页面卡死。所以这应该是 packages/client/ui-primitives 的产品能力，不是插件 hack。

建议：

• 流式输出时仍显示源码（和 KaTeX 一样，定稿后再渲染）
• 定稿后在气泡内出图；语法错误则回退到 CodeBlock
• securityLevel: "strict"，只渲染 mermaid 产出的 SVG
• 限制宽度/高度，避免超大图撑满或卡死页面
• 保留复制源码；跟随亮/暗色主题
• 懒加载 mermaid，保持 ui-primitives zero-cordis

最小改动点：renderCode 里给 mermaid / mmd 加一条和 math 同级的分支，新增 MermaidBlock。

如果方向认可，我可以跟进 PR（仓库目前暂不收外部 PR 的话，就当需求投票）。