feat(web): render mermaid diagrams in pull request bodies

[TijsM]

What Changed

mermaid fences in GitHub-authored markdown now render as diagrams in the pull request panel — bodies, comments, and review annotations, all of which go through PullRequestMarkdown. A toggle in the block's toolbar switches back to the highlighted source, and a diagram that cannot parse falls back to it automatically with a one-line note.

flowchart LR
  Fence["mermaid fence"] --> Pre["ChatMarkdown pre renderer"]
  Pre -->|"mermaidDiagrams off"| Code["Highlighted source"]
  Pre -->|"mermaidDiagrams on"| Cache{"SVG cached?"}
  Cache -->|hit| Draw["Diagram"]
  Cache -->|miss| Load["dynamic import"]
  Load --> Render["Serialized render"]
  Render --> Draw
  Render -->|parse error| Code

Loading

Details worth knowing:

• Mermaid sits behind a dynamic import, so it never lands in the main bundle. The build splits it into mermaid.core plus per-diagram-type chunks fetched on demand; main and the ChatMarkdown chunk contain none of it.
• Rendered SVG is cached per source and theme in an LRU. Scrolling a long body remounts every diagram in it, and mermaid's layout pass is the expensive part.
• Mermaid's config and render target are module-global, so renders join one promise chain instead of trampling each other's theme. A failed diagram cannot poison the queue for the next one.
• securityLevel: "strict": pull request bodies are attacker-controlled text, so mermaid's DOMPurify pass stays on and its click/script directives stay off. suppressErrorRendering keeps mermaid from injecting its own error graph next to the React fallback.
• Rendering is opt-in through a mermaidDiagrams prop, so chat rendering is untouched. Streaming markdown keeps showing source, since a half-written diagram cannot parse.
• Desktop inherits this from web. Mobile has no pull request body view, so there is nothing to do there yet.

Why

GitHub draws a ```mermaid fence in a pull request body as a diagram, so authors write them expecting a diagram. The panel showed the raw source, which is exactly the content GitHub's own rendering promised to draw.

On the diff size: 803 of the changed lines are pnpm-lock.yaml, which pnpm needs for the one new dependency, and 67 are the new test. The source change is about 358 lines.

Related: #9621 takes the same feature much wider — chat, plans, and file previews as well. This one is deliberately limited to the GitHub panel, where GitHub's rendering already sets the expectation, and stays around 250 lines.

UI Changes

Rendering this pull request's own body in the panel, light and dark.

Before

Light	Dark

After

Light	Dark

The <> button in the block's toolbar returns to the source view shown above; the wrap toggle only appears there, since line wrapping cannot affect an SVG.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes — nothing here animates

---

Verified with focused tests for the render cache, concurrent dedupe, per-theme reconfigure, and failure recovery, plus the existing markdown suites; lint, format, and typecheck clean on the changed files.

Model: Claude Opus 5. Harness: Claude Code, driven from T3 Code.

🤖 Generated with Claude Code

Note

Render mermaid diagrams in pull request bodies

• Adds the mermaid package and a mermaidDiagrams flag to ChatMarkdown, enabled by PullRequestMarkdown.
• Renders non-streaming mermaid fences with MarkdownMermaidBlock, which provides a toggle to view highlighted source.
• Caches SVGs (64-entry, 8 MiB LRU) and serializes renders in mermaid.ts to protect Mermaid's global state.
• Behavioral Change: MarkdownCodeBlock accepts optional actions and showWrapToggle props; existing callers retain default behavior.

^{Macroscope summarized 378d286.}

Summary by CodeRabbit

• New Features

  • Mermaid code blocks can now render as diagrams in chat and pull request markdown.
  • Users can switch between the rendered diagram and its source code.
  • Diagrams adapt to light and dark themes and resize responsively.
  • Invalid diagrams display an error notice with the original source available.

• Documentation

  • Pull request markdown documentation now explains Mermaid diagram support.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds a default-on Mermaid rendering capability to production pull-request views, including a large client-side dependency, asynchronous SVG rendering, caching, and source/fallback controls. Its cross-cutting runtime scope and unresolved medium-severity cache/render-lifecycle findings warrant human review.

Not approved because:

• 2 blocking correctness issues found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 1c429b29-3f99-4469-af3f-2d7c46a41bfe

📥 Commits

Reviewing files that changed from the base of the PR and between 8b2838e and 2467d4a.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (7)

• apps/web/package.json
• apps/web/src/components/ChatMarkdown.tsx
• apps/web/src/components/chat/MermaidDiagram.tsx
• apps/web/src/components/pullRequest/PullRequestMarkdown.tsx
• apps/web/src/index.css
• apps/web/src/lib/mermaid.test.ts
• apps/web/src/lib/mermaid.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR adds Mermaid rendering for pull request markdown. It introduces theme-aware SVG caching, serialized asynchronous rendering, diagram/source toggling, error fallbacks, responsive sizing, and Mermaid-focused tests.

Changes

Mermaid rendering

Layer / File(s)	Summary
Rendering service and cache apps/web/package.json, apps/web/src/lib/mermaid.ts, apps/web/src/lib/mermaid.test.ts	Adds Mermaid rendering with lazy loading, strict configuration, theme-aware LRU caching, serialized renders, failure recovery, and tests for caching and parse errors.
Markdown diagram display apps/web/src/components/ChatMarkdown.tsx, apps/web/src/components/chat/MermaidDiagram.tsx, apps/web/src/index.css	Adds Mermaid fence detection, diagram/source toggling, pending and error states, SVG rendering, and responsive sizing.
Pull request markdown wiring apps/web/src/components/pullRequest/PullRequestMarkdown.tsx	Enables Mermaid diagrams and documents the behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 2467d

Mermaid rendering is isolated to pull request markdown, retains source and failure fallbacks, and no actionable merge risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant MarkdownPre
  participant MarkdownMermaidBlock
  participant MermaidDiagram
  participant renderMermaidSvg
  MarkdownPre->>MarkdownMermaidBlock: detect enabled Mermaid fence
  MarkdownMermaidBlock->>MermaidDiagram: render diagram view
  MermaidDiagram->>renderMermaidSvg: request themed SVG
  renderMermaidSvg-->>MermaidDiagram: return cached or rendered SVG
  MermaidDiagram-->>MarkdownMermaidBlock: display SVG or source fallback

Loading

Suggested reviewers: juliusmarminge

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.85% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 5 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description includes the required What Changed, Why, UI Changes, and Checklist sections. It explains the implementation, scope, testing, and UI evidence.
Title check	✅ Passed	The title clearly and concisely describes the primary change: Mermaid diagram rendering in pull request bodies.

Full details: Docstring Coverage

Explanation

Docstring coverage is 53.85% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 5 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[t3-code]

Thanks for adding Mermaid support to PR content

We’re pursuing #9621, which handles Mermaid through the shared Markdown renderer, including PR bodies

closure requested by @Bil0000.