Web GUI: render ```mermaid fences (4th request — consolidating #1065/#1135/#2711/#3346 with the exact seam, in-repo precedent and a mergeable branch)

[liukjx]

TL;DR — this is at least the fourth request for the same thing (#1065, #1135, #2711, #3346), so rather than another bare "+1" this post collects everything needed to decide once: the exact seam, the in-repo precedent, the fact that mermaid is already a dependency of this repo, two community plugins that already ship it, and a mergeable branch in #6056. Please consolidate into one canonical thread if that helps — I'm happy to have this closed as a duplicate of #2711.

Current behavior (observed on dsh 0.1.5-rc.1)

Chat messages render markdown, but a ```mermaid fence falls through to the generic code block. The renderer has exactly one special arm, and it is math:

// packages/client/ui-primitives/src/markdown/render.tsx — renderCode()
const lang = language === undefined ? undefined : /^[\w-]+/.exec(language)?.[0]
if (!context.streaming && lang === 'math') {
  // ```math fences render as display TeX once settled (rehype-katex parity)
  return <Fragment key={key}>{renderTexToReact(`${node.value}\n`, true)}</Fragment>
}
return <CodeBlock ... />   // <- mermaid lands here

Repro — paste this into a session; you get a highlighted code block, not a chart:

xychart-beta
    title "Daily reviews at 100 new cards/day"
    x-axis "Month" [1,3,5,7,9,11,13,15,17,19,21,23]
    y-axis "cards/day" 0 --> 800
    line [100,466,598,700,759,847,902,960,1019,1087,1197,1284]

Loading

Flowcharts and sequence diagrams are the common case, but numeric xychart (trend data from a simulation) is the one that hurts most here — there is no way to eyeball the shape without leaving the app for mermaid.live.

Everything needed already exists in this repo

The missing piece really is just the client arm:

Piece	Where
mermaid@11.16.0 is already a root dependency	package.json (devDependencies)
A gate that parses every repo-authored mermaid fence with mermaid itself	scripts/verify-mermaid.ts (PATTERNS: README, docs/**, packages/*/*.md, .agents/**)
The docs site renders mermaid	website/.vitepress/config.ts — withMermaid(...), and fences ['mermaid','mmd'] mapped to renderFence
The chat renderer already special-cases a diagram-like fence, with its own module, CSS and e2e gate	markdown/render.tsx → katex.tsx → apps/web/tests/math-rendering.e2e.ts
Fallback renderer	packages/client/ui-primitives/src/markdown/CodeBlock.tsx

So mermaid is the only diagram vocabulary that the product UI does not render, while the repo both depends on it and validates it.

Proposed minimal change (mirrors the math arm)

1. if (!context.streaming && (lang === 'mermaid' || lang === 'mmd')) → <MermaidDiagram source={node.value} />, settled-only so a half-streamed fence keeps rendering as code (the math arm already establishes this rule).
2. await import('mermaid') on first use — the ~500 KB stays out of the boot chunk; sessions without diagrams never pay for it.
3. mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' }) — fence source is untrusted model output — and bind the theme to the existing light/dark tokens so it follows the app theme.
4. Render keyed by source; a syntax error falls back to the plain code block plus a small "diagram failed" note, so the source is never lost.
5. Keep a source ⇄ diagram toggle (copyability), and an e2e test mirroring math-rendering.e2e.ts.

Already built, by the community and in branches

• feat(web): 右侧栏 Markdown 预览与 Mermaid 图渲染 #6056 — MermaidDiagram primitive added to ui-primitives (lazy chunk) plus a sidebar markdown preview: 48 files, single commit, reported as Able to merge.
• Proposal: fullscreen zoom viewer for Mermaid diagrams(文档站 Mermaid 图全屏缩放查看器)— implemented, branch ready #4318 — fullscreen zoom viewer for mermaid diagrams, branch ready.
• Plugins — AKS1st/dsh-mermaid (MIT, 9★; keeps the code-block banner, copies source, light/dark, viewport-driven render, fullscreen pan/zoom, error path back to the agent) and timedomain1/dsh-mermaid-renderer (MIT; DOM post-processing, zoom + fullscreen viewer).

Those plugins prove the value but also show the cost of the current gap: each one has to ship its own mermaid bundle, its own theme wiring and its own DOM post-processing.

The actual ask

Either land #6056 (or an equivalent core arm), or expose a documented client seam for fenced-block rendering so a plugin can register a renderer for a language instead of mutating the DOM after the fact. Either outcome closes this class of request for good.

Thanks — and again, consolidating the five threads into one would probably help more than this post's contents.

[PerryLink]

Thanks for doing the archaeology — this is the first of these threads that names the actual dispatch point, so I verified it against the repo at c291e79 (master, 0.1.5-rc.2; you observed on rc.1 — the seam is identical). Verdict: the seam is real and your precedent table is accurate, with two framing corrections and one tracker correction below.

Seam confirmed

packages/client/ui-primitives/src/markdown/render.tsx, renderCode() (lines 363–399). Your quoted excerpt is essentially verbatim: the lang extraction at line 375 (/^[\w-]+/.exec(language)?.[0]), the single special arm at 376–380 (if (!context.streaming && lang === 'math') → renderTexToReact), and everything else — including ```mermaid — falling through to <CodeBlock> at 381+. `math` is indeed the only fence-language arm; the `math`/`inlineMath` cases at 329–332 are node types, not fence dispatch. The settled-only gate is also the right shape: `MarkdownText` renders two passes (`streaming: true` while the fence grows, `false` once settled), streaming fences highlight incrementally (pinned by `apps/web/tests/streaming-fence-highlight.e2e.ts`), and a half-streamed mermaid fence staying a plain code block matches the math arm exactly. Your proposal needs no grammar change — `lang` already sits on the code node, so `parse.ts` is untouched.

Precedent table: all confirmed

• mermaid@11.16.0 root devDependency (package.json:212), introduced by 8caf923196 "docs(graphs): verify mermaid syntax".
• scripts/verify-mermaid.ts exists with exactly those PATTERNS and initialize({ startOnLoad: false, … }), and it is a real gate: scripts/run-gates.ts:736 wires it as pnpmScript('mermaid', 'verify-mermaid').
• website/.vitepress/config.ts uses vitepress-plugin-mermaid's withMermaid and maps ['mermaid','mmd'] to renderFence (lines ~387–406).
• The math chain is exactly as you described: render.tsx → katex.tsx → apps/web/tests/math-rendering.e2e.ts (golden ARIA snapshot, console tripwire, .katex assertions), with CodeBlock.tsx as the fallback.

Two framing corrections (the substance stands)

1. "mermaid is already a dependency" is only true as a docs-gate devDependency — it has never entered the product bundle. That is still a cheap change under this repo's convention (ui-primitives declares bundled deps like katex/shiki as devDependencies; apps/web has no runtime deps at all; Vite does the bundling), so the PR adds mermaid to ui-primitives' devDeps. But "mirrors the math arm" is only half right: katex is imported statically and rides the eager vendor manual chunk (apps/web/vite.config.ts VENDOR_PACKAGES). Your await import('mermaid') actually mirrors the other in-repo precedent — the lazy shiki grammars in markdown/highlight.ts (() => import('@shikijs/langs/…')). That is the correct precedent to follow: mermaid's ESM entry is only the ~50 KB mermaid.core.mjs, with per-diagram chunks loaded on demand (the monolithic UMD is ~3.4 MB minified), so mermaid must stay out of VENDOR_PACKAGES and split into its own lazy chunk — the vite config's own comment says lazy chunks must stay unassigned. Your "~500 KB stays out of the boot chunk" is right in spirit (core + one diagram family; the full chunk set is far larger, but only the needed ones load).
2. New user-visible chrome needs i18n. Labels flow through MarkdownLabels → packages/client/ui-chat/src/client/markdown-labels.ts (t()) → the chat locale dictionaries (zh + en in locale.ts). The math arm added no chrome; your "diagram failed" note and source⇄diagram toggle add keys that must land in both dictionaries. Also expect more than the e2e: render.tsx's header states the DOM is pinned byte-for-byte by tests/fixtures/markdown-dom (settled+streaming pairs), so a mermaid arm should ship unit tests and fixtures in the same style. securityLevel: 'strict' is right and aligns with the renderer's documented untrusted-output policy (fence source is model output); theme binding has a ready vocabulary (--dsw-* tokens, already used by CodeBlock.module.css). THIRD_PARTY_NOTICES.md is generated and already lists mermaid (MIT), so no new notice work.

Tracker correction

On the public repo, Issues and PRs are disabled (has_issues: false, has_pull_requests: false; Discussions enabled) — every number you cite is a discussion. #1065 ("Support Mermaid diagram rendering in fenced code blocks"), #2711 ("Idea: render settled mermaid fences as diagrams in the web GUI"), and #6056 ("feat(web): 右侧栏 Markdown 预览与 Mermaid 图渲染") all check out as discussions; #1135/#3346/#4318 resolve the same way. #6056 "reported as Able to merge" cannot be a mergeability status on the public tracker — there is no refs/pull/6056 on the remote — so if that thread carries a real branch it lives on a fork or the internal mirror, and "land #6056" should be phrased as "port the branch behind #6056". I could not verify the 48-files/single-commit contents of #6056 or #4318's "branch ready" state from here, nor the bodies of #1135/#3346. The two community plugins check out: AKS1st/dsh-mermaid (MIT, 9★) and timedomain1/dsh-mermaid-renderer (MIT, zoom/fullscreen).

Mergeability, maintainer view

The core change is genuinely small and correctly placed: one settled-only arm in renderCode, a lazy mermaid module with startOnLoad: false + securityLevel: 'strict', theme via the existing --dsw-* tokens, and an error fallback back to CodeBlock so the source is never lost — the same shape as the katex three-arm error chain. Nothing conflicts with repo conventions. The realistic PR checklist: mermaid in ui-primitives devDeps; the lazy chunk left unassigned in manualChunks; zh+en keys for the new chrome; unit tests + markdown-dom fixtures; an e2e mirroring math-rendering.e2e.ts. The one thing that is not small is the alternative half of your ask: a documented client seam for registering fence renderers. ui-primitives is deliberately cordis-free ("zero cordis" in its package description) and renderCode's dispatch is a plain if-chain — the merge-extensibility note in render.tsx covers node types, not renderer dispatch. A plugin-registry seam would be a new extension point in the client modules/chat layer, not a line in renderCode. It is a defensible long-term direction (it would end the DOM-post-processing pattern your two plugin citations embody), but it is a separate design decision from landing the mermaid arm, and I'd treat the two asks as two work items rather than one either/or.

Consolidation: agreed — #2711 is the natural canonical thread, and this post plus #1065/#1135/#3346 could fold under it.

[XiaoBinGan]

Following up on @PerryLink's review above: I implemented that checklist as a real branch. It is now published and fetchable.

Branch: https://github.com/XiaoBinGan/deepseek-harness/tree/feat-mermaid — commit 0e5f44275dbe134f9841d6337e1ba3388f602315, parent c36a83ff6b (your observed base; the seam is unchanged). One commit, 30 files, +1107/−26.

Your checklist, item by item

1. "mermaid in ui-primitives devDeps" — done. packages/client/ui-primitives/package.json gains "mermaid": "11.16.0" in devDependencies, alongside katex/shiki. apps/web still declares no runtime deps; Vite bundles.

2. "the lazy chunk left unassigned in manualChunks" — done, and this is the point I took most seriously from your correction. mermaid is deliberately absent from VENDOR_PACKAGES in apps/web/vite.config.ts. Real build output from apps/web/dist:

• assets/mermaid.core-DQo2-oKv.js — 622,429 bytes, its own lazy chunk.
• assets/vendor-Do3oIcgg.js — zero occurrences of the string mermaid (grep -o -i mermaid vendor-*.js | wc -l → 0).
• index.html carries exactly one modulepreload, and it is the vendor chunk — the mermaid chunk is not preloaded.
• The call site is a genuine dynamic import: import("./mermaid.core-DQo2-oKv.js") in the entry chunk.
• The diagram-family chunks are separate and load on demand: 36 family chunks totalling 996,900 bytes (largest cynefin at 688,289, cytoscape.esm at 443,739). Nothing of that is in the boot path.

So you were right that the katex "static + vendor" half of my earlier framing was wrong, and right about the shiki-grammar precedent being the one to follow — that is what the branch does.

3. "zh+en keys for the new chrome" — done. Six keys in each of packages/client/locale/src/locales/zh.ts and en.ts: markdown.mermaid.{diagram,preview,source,view,loading,error}. They reach the arm through MarkdownLabels → ui-chat/src/client/markdown-labels.ts; the arm is only constructed when the owner supplies labels.diagrams.mermaid, so a consumer without labels keeps the plain CodeBlock arm.

4. "unit tests + markdown-dom fixtures" — done. Two new spec files (markdown-diagram.client.spec.tsx 9 cases, mermaid-runtime.client.spec.ts 8 cases) plus 3 cases in code-block.client.spec.tsx and 2 new markdown-dom-parity cases. New fixture pair diagram-fences.settled.txt / diagram-fences.streaming.txt; code-fences, fence-trailing-blank-lines, and math-edge-cases fixtures were updated for the DOM change below.

Measured, just now, on the branch:

Test Files  57 passed (57)
     Tests  1214 passed (1214)

The commit adds 22 test cases and removes 0, so the pre-commit baseline derives to 55 files / 1192 tests. I could not measure that baseline directly without checking out the base commit, so treat 55/1192 as arithmetic from a measured 1214, not as a separately observed run.

5. "an e2e mirroring math-rendering.e2e.ts" — done, and it really ran. Note the runner matters here: *.e2e.ts is not collected by vitest.config.ts (that only matches *.spec.*), so the working invocation is

MODE=replay npx vitest run --config vitest.web.config.ts apps/web/tests/markdown-mermaid.e2e.ts

Real output: Test Files 1 passed (1) / Tests 1 passed (1), duration 2.86s — executed in replay mode, not skipped. The golden ARIA at apps/web/tests/expected/markdown-mermaid/ui.expected.md contains img "Mermaid diagram" and a tablist "Diagram view" with tab "Diagram" [selected] / tab "Source".

Your other points

• securityLevel: 'strict' — in, plus startOnLoad: false and suppressErrorRendering: true. Beyond strict, the rendered SVG is turned into a data URL consumed by an <img>, so the markup never enters the document tree and its own scripts/handlers/links cannot execute; network-capable tags and off-root href/src that strict alone retains are stripped.
• Theme via --dsw-* — in. theme: 'base' with themeVariables read from the live --dsw-* tokens, including --dsw-font-family so a diagram matches the code it replaces.
• Error fallback to CodeBlock — in, same three-arm shape as the katex chain: pending keeps the source visible, success swaps in the image behind the source⇄diagram toggle, and a rejected render falls back to CodeBlock with a role="status" note so source is never lost.
• THIRD_PARTY_NOTICES.md — one divergence from your expectation. You said it is generated and already lists mermaid, so "no new notice work". It does list mermaid, but under the development-only table; since this branch makes mermaid a bundled runtime dependency, the entry had to move to the runtime table. Small, but it is a change you did not predict.
• The renderer-registry seam — deliberately not attempted. You framed it as a separate work item, and the branch is scoped to the mermaid arm alone. ui-primitives stays cordis-free and renderCode's dispatch stays a plain if-chain.

One thing you did not ask for

Restoring a reliable language marker on the real code-block DOM. The language previously reached only the infostring text, so pre code never carried class="language-<lang>". That is exactly the surface your own #6502 thread's two community plugins detect mermaid through — so language-based detection was dead, and graph TD silently failed to render for them even after this arm lands. The branch adds class="language-<lang>" on the <code> and data-language on the block's content element, present on the plain, streaming, and settled shiki arms alike so a consumer never has to know which arm rendered. This is why code-fences / fence-trailing-blank-lines / math-edge-cases fixtures moved.

What is NOT verified

• Whether maintainers want this branch at all. I am not assuming it is wanted; the branch exists so the seam can be evaluated against real code rather than a description.
• SVG rendering security is not claimed here. It is being covered by a separate discussion filed in parallel — deliberately not duplicated in this comment.
• Coverage/lint/duplication/doc-sync not run. The push triggered the repo's pre-push hook, which ran typecheck (✔️ typecheck (11.89 seconds)); the CI coverage gate (test:coverage, not test) and lint/duplication/doc-sync were not executed by me.
• No product decision on the registry seam, per above.

[xwh5]

0.2.1-alpha.2 复测：mermaid 围栏仍然只是代码块（2026-10-12）

补一条版本证据。同类请求已经有 5 条（#1065 / #1135 / #2711 / #3346 / #6056），而到今天为止还没有任何一条进版本。

实测环境：dsh 0.2.1-alpha.2（npm alpha dist-tag 的最新版；latest / next 仍停在 0.2.0-rc.2），Web GUI。

证据（直接在安装包的 299 个 @deepseek-ai/* 依赖里 grep）：

• katex 命中 ⇒ renderCode() 里 math 那条分支确实已经在线上；
• mermaid 只在 dsh-web-frontend/dist/assets/langs/asciidoc-*.js 里出现过一次（那是 shiki 的语法名列表），不是渲染器 ⇒ ```mermaid 依旧落到 CodeBlock；
• 右侧栏 .md 文档预览已经在包内（dsh-client-ui-sidebar-documentpreview 有 markdown body + frontmatter 渲染）⇒ 现在缺的只是「图」这一半。

期望的 UX（对齐 DeepSeek 网页版）：助手气泡里的 ```mermaid 定稿后直接出图，卡片顶部给 图表 / 代码 切换，再加缩放、全屏、复制源码。现状只能整段复制去 mermaid.live。

生态现状：这件事至少有 6 个社区包在各自实现。这既说明缺口真实，也说明 DOM 后处理的成本有多高——每个包都得自带一份 mermaid、自己的主题接线、自己的 DOM 选择器：

插件	亮点
MrmoLabs/dsh-mermaid（npm dsh-mermaid，13★）	代码/图表切换、流式安全、全屏缩放平移、SVG 导出、中英 i18n
timedomain1/dsh-mermaid-renderer	图表/源码切换、卡片内可重复缩放、独立全屏查看器、新标签页打开
AKS1st/dsh-mermaid（9★）	保留原代码横幅与源码复制、报错回环（把错误直接发回当前 agent 修）
lj970926/dsh-plugin-mermaid · XiaoBinGan/dsh-mermaid-fence · baconbao/dsh-mermaid-image-preview	同题的不同切法

ask：#6502 里 PerryLink 已确认 seam 真实可行，XiaoBinGan 也交了真分支（feat-mermaid，30 文件 +1107/−26，含 zh/en 文案与 1214 条单测）。希望官方二选一：合入这条 arm，或给出 fenced-code renderer 的注册 seam，让社区包不必再事后改 DOM。

另：#7614 实测 securityLevel: 'strict' 之后 SVG 里仍可能保留 <img src="x"> 这类元素，建议合并时把这一步加固一并考虑。

（本条是补充版本证据，不是新请求；canonical 仍是 #2711。）

[XiaoBinGan]

Thanks for confirming the seam. My main goal isn't to push a specific implementation, but to avoid every plugin having to patch the DOM independently. If merging the existing branch isn't the preferred direction, an official fenced-code renderer extension point would already solve the ecosystem problem.

[ancientrs]

Retest on 0.2.1-rc.2 (the current npm latest, published 2026-10-17): a ```mermaid fence still lands in CodeBlock as a plain code card — no diagram, no toggle. The math arm is still the only special-cased fence, so this thread's analysis holds unchanged two minor releases later.

Two current-version details that matter for the seam proposal:

1. There is no public fence hook. renderCode() in packages/client/ui-primitives/src/markdown/render.tsx still hard-codes CodeBlock for every non-math fence, and ui-primitives exports MarkdownText / CodeBlock without any per-language renderer parameter. MarkdownRenderContext carries labels, fileMentions, pathImages, targets, and footnote state — nothing a caller (or a plugin) could use to claim a language. A client plugin therefore has exactly two routes today: replace the whole assistant node through the keyed conversation.chat.node slot, or mutate the DOM after render.

2. The plain fallback drops language-<lang>. In CodeBlock's unhighlighted arm the markup is <pre class="…plain"><code> — the language-<lang> class survives only on the empty-fence arm and inside Shiki's HTML. mermaid has no Shiki grammar, so a Mermaid fence arrives in 0.2.1 with no language signal at all. Every DOM-based plugin consequently has to sniff content (first token ∈ flowchart/graph/sequenceDiagram/…), which also upgrades an explicitly labelled ```text fence that happens to start with graph.

What I'd ask for, in order of value:

• A fence-renderer extension point. For example MarkdownText accepting fences?: Record<string, ComponentType<{ code, lang, streaming }>> resolved in renderCode(), or a client Slot keyed by fence language. That lets dsh-mermaid, dsh-mermaid-codex and the rest stop observing the DOM, and keeps the streaming/incremental-freeze path in one place instead of reimplementing it per plugin.
• Keeping language-<lang> on the plain arm in the meantime. One attribute, and every existing plugin's content sniffing becomes an exact match again.

Interim workaround for anyone landing here: dsh plugin --profile web add dsh-mermaid (0.4.2, Mermaid 11.17 inlined, no CDN) does render fences today via MutationObserver. It works, but it is precisely the DOM contract this thread is trying to replace.

[Jarvis-wh]

Confirming the shared-primitive path (0.2.1-rc.2)

Following up on @xwh5's 10-12 note that the sidebar .md preview already ships: it renders through the same shared MarkdownText primitive, so this is one fix, not two. Verified on a clean 0.2.1-rc.2 desktop build (macOS arm64):

• packages/client/ui-sidebar-documentpreview/src/client/markdown/MarkdownBody.tsx renders <MarkdownText … />, and renderCode() in packages/client/ui-primitives/src/markdown/render.tsx still has exactly one fence arm (lang === 'math'). A mermaid fence in a workspace .md therefore lands in the same CodeBlock as in chat — with no language-mermaid signal, as @ancientrs noted for the plain arm.
• The shipped web bundle has no mermaid chunk and no mermaid grammar among its 59 lazy shiki language chunks; mermaid@11.17.2 is used only by the docs site and scripts/verify-mermaid.ts.
• One settled-only arm covers chat and the sidebar preview at once, so the consumer-plumbing question is smaller than it looks.

On #6056: its sidebar-preview half has since been superseded by the built-in preview in 0.2.1-rc.2, but the MermaidDiagram primitive it adds is still exactly the missing piece — a lang === 'mermaid' || 'mmd' arm reusing it (lazy import, securityLevel: 'strict', theme-bound, error falls back to the code block) would close this.

Happy to test a branch on 0.2.1-rc.2 across both chat and the sidebar preview.