[Feature]: mermaid render support within the markdown render view

[tnh]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/desktop

Problem or use case

Like other editors, I would like t3code to render mermaid diagrams encoded in markdown.

Proposed solution

Example mermiad diagram rendered within Cursor

Why this matters

GitHub supports mermiad https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams

Most other providers support mermiad diagramts.

Smallest useful scope

Have t3code use https://github.com/mermaid-js/mermaid

Alternatives considered

No response

Risks or tradeoffs

No response

Examples or references

No response

Contribution

• I would be open to helping implement this.

[cloudbridgeuy]

I built this on a fork and I am not opening a PR here, since CONTRIBUTING says contributions are not being accepted right now. Posting it in case the design is useful to whoever does land this.

Branch and full write-up: cloudbridgeuy#2

#4989 is already open for the same feature. I read it after finishing mine and took three things from it — credit to @jdalmeida:

• Copying a message dropped the diagram. markdown-clipboard.ts skips every <svg>, and a drawn diagram's container holds exactly one child: the svg. So a copied message lost its diagrams silently. The container now carries the rebuilt fence as data-markdown-copy.
• Mermaid init options — the app's own font, and no console noise or injected error graphic on a failed render.
• The pre renderer belongs at module scope. ChatMarkdown's markdownComponents is a useMemo keyed on the message body, so an inline pre handler gets a new identity every token and React remounts the whole code-block subtree once per token for the rest of the turn. Lifting it out fixes that for every fenced block, mermaid or not.

I did not take pan/zoom. The 70vh cap plus scrolling covers the case it addresses, and a wheel-capturing pan surface inside a scrolling timeline is its own design problem.

What it does. A closed ```mermaid fence in a chat message draws as a diagram, with the source one click away. The diagram-vs-source choice is remembered in localStorage. A diagram scales to the panel by default or expands to its own width, and either way the container caps at 70% of the window height and scrolls. A reader who prefers source never downloads `mermaid` at all — the `import()` is skipped, not just the render. Invalid diagram text renders as mermaid's own parse message plus the source, not a blank box.

Shape. +1970/−217 excluding the lockfile, across apps/web only. 737 of those lines are tests, and 288 are an unmodified relocation of MarkdownCodeBlock out of ChatMarkdown.tsx to avoid an import cycle. Mobile is untouched. Before/after images and the known limitations are in the linked PR.

Happy to shrink or split it if there is any interest, and equally happy for it to be ignored. Built with Claude Code, reviewed by me.

[jamesainslie]

@juliusmarminge, I have moved my proposal from #10789 into this original thread at your request, so the implementation notes and follow-up stay in one place.

Our fork includes the mobile implementation. T3 Mobile uses React Native and Expo, and our implementation supplies the browser APIs Mermaid needs through a locally bundled Expo DOM/WebView. It reuses the same renderer and viewport logic as web/desktop, with a native fullscreen modal and integration into both mobile Markdown rendering paths. It requires no Swift port, CDN, or external rendering service. Android export and offline DOM rendering with touch-pinch controls have passed. Native iOS/Android device testing and profiling remain outstanding, and distributing it requires a separate mobile app build.

The implementation is merged in fork PR #7, at d4070441d. It draws on the Mermaid viewer in my Horde project. I understand the earlier product-direction decision; the following describes concrete mitigations already in the fork and the costs that still need measurement.

User experience

Completed Mermaid fences render as themed diagrams with source toggle, source copy, and Expand. The expanded viewer supports Fit, Center, actual size, pointer-centered wheel zoom, drag-to-pan, and touch pinch. Keyboard controls include arrows for panning, + / - for zoom, F for fit, C for center, 0 for actual size, and Escape to close. The web dialog restores focus to its opener.

Malformed source remains readable with error details and Retry. Ask agent to fix adds the source and renderer error to a composer draft for the user to review and send. It does not automatically start another turn or alter the original conversation.

Performance mitigations already implemented

• Lazy runtime loading: Mermaid is dynamically imported when a diagram needs rendering. Conversations without diagrams do not load that runtime.
• Streaming behavior: Incomplete fences show a waiting state. A closed fence can render while the rest of the response continues, without attempting layout for every partial diagram token.
• Render reuse: SVG promises are cached by source and theme in a 32-entry LRU cache, allowing repeated and remounted diagrams to reuse output. Failed entries are evicted so transient errors can be retried. Rendering is serialized because Mermaid configuration is global.
• Viewport work: Panning and zooming transform the generated image without rerunning Mermaid layout. The controller schedules transform updates with animation frames, rather than a continuous animation loop. Pointer and wheel capture is limited to the expanded canvas, preserving normal inline timeline scrolling. Listeners and resize observers are cleaned up when the viewer closes.
• Input limits: Rendering is configured for a maximum of 50,000 source characters and 500 edges. Oversized source has a readable fallback.

These controls reduce loading and repeated work, but first-render graph layout still runs on the client main thread. The cache is bounded by entry count, not total bytes. Cold rendering, long virtualized histories, off-screen queued work, and memory retention need explicit performance measurements before an upstream port. An explicit Render diagram action is a possible upstream scope reduction; automatic rendering is the current fork behavior.

Security and failure handling

• Mermaid uses strict security mode with HTML labels disabled. The configured trust and theme keys are protected from diagram-authored overrides.
• Generated SVG is displayed through an SVG data-URL image, isolating its styles and identifiers from the surrounding chat DOM. Mermaid still performs temporary DOM work during generation; this is not a claim that graph layout runs in a separate process or worker.
• Parse and render failures are caught. The source remains available, and temporary rendering nodes are cleaned up after failure.
• Rendering stays local to the client. No new rendering service, provider adapter, WebSocket contract, or database migration is needed.

These are concrete restrictions on untrusted output, while Mermaid itself remains an additional dependency and parsing surface to maintain and review.

Mobile tradeoffs and validation

The earlier proposals left native mobile without matching rendering. Our fork provides that code path, but its mobile DOM bundle is approximately 5.5 MB and multiple WebViews can add runtime and memory cost. The Expo export currently disables DOM bundle splitting to work around asset references. That choice needs native-device validation and upstream review.

The fork passed 54 focused tests across chat Markdown and the shared Mermaid helpers, scoped web/mobile/shared-client typechecks, a web production build, Android Expo export, and PR/post-merge CI. Browser checks covered both themes, mouse/keyboard controls, focus restoration, invalid source, and repair drafts. The mobile DOM viewer rendered offline with touch-pinch controls and no HTTP requests; this evidence is not a native-device test.

Whole-message and selection-to-Markdown copying need regression coverage so diagrams survive as their original fences, as earlier contributions in this thread identified. Screen-reader behavior and the other shared Markdown surfaces also need verification before upstreaming.

Fork evidence

Before	After

Pan and zoom recording · Invalid-source recovery · Offline mobile DOM capture

I can contribute focused pieces or work with an existing implementation if maintainers decide to revisit Mermaid. The fork code and evidence are available here for that discussion, with mobile included and the remaining performance and security work made explicit.

[TheRealShek]

Thanks @juliusmarminge, saw #11038 and #9621.

Is there any rough timeline for when we could expect Mermaid rendering to land in nightly? Even if it's just an estimate.

[nbros]

Currently mermaid diagrams look a bit sad in T3 Code 🥲

They're useful for example with the show-me skill from Dex Horthy when asking the agent to show its work.

[TheRealShek]

I ask it to prefer ascii diagrams cause there is no support :(

[camysidron1]

Adding a concrete desktop use case: when an assistant presents a task dependency graph in a fenced mermaid block, T3 Code shows the source rather than the graph. This makes multi-workstream plans and shared prerequisites difficult to review in the conversation; we currently have to generate a PNG as a workaround.

A minimal example is:

flowchart TB
  A[Shared contract] --> B[Workstream A]
  A --> C[Workstream B]
  B --> D[Integration gate]
  C --> D

Loading

For this use case, local rendering of completed fences, readable subgraphs/labels, a source/copy fallback, and an expand-to-fit view would cover the need. Thanks for tracking the existing implementations in #11038 and #9621; adding the use case here rather than opening a duplicate request.

[piotrnowakowski]

It’s frustrating when an agent uses Mermaid to explain a workflow or architecture, but T3 Code shows only the source. Diagram rendering is common in other agent apps, so I’ve come to expect it as part of reading an agent’s response.

I understand the concerns about performance, security, and maintenance. Would you consider an explicit “Render diagram” button, so rendering happens only when requested? Even a basic preview would help.

Having to copy diagrams into another tool interrupts the workflow. If rendering remains out of scope, could you recommend a convenient way to view them from T3 Code?

[KaKi87]

Having to copy diagrams into another tool interrupts the workflow.

Well, if you're going to do that, then you might as well update rules/skills/AGENTS.md to always render all Mermaid diagrams as images using some CLI tool.

But yeah, we need this feature.

[jamesainslie]

I have submitted a PR for this which I think adequately addresses the concerns raised by Theo and Julius. I use it in my own fork everyday and I pay the sun tax of having to rebase against upstream main every day 😔

…

On Oct 1, 2026 at 9:28 AM -0400, KaKi87 ***@***.***>, wrote: > Having to copy diagrams into another tool interrupts the workflow. Well, if you're going to do that, then you might as well update rules/skills/AGENTS.md to always render all Mermaid diagrams as images using some CLI tool. But yeah, we need this feature. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you commented.Message ID: ***@***.***>

[maria-rcks]

Note

Written by claude-opus-5-5 on behalf of Maria

Mermaid fences now render as diagrams in chat, markdown file previews, and PR descriptions. Shipped in #15067.