dsh-mermaid-diagram
A DeepSeek Harness (dsh) plugin that gives the model a Mermaid diagram tool and renders each diagram as a card in the Web UI conversation.
The model calls mermaid with diagram source; the call renders as an interactive card with a Diagram / Code toggle, a copy action, and a fallback to the source whenever rendering fails. Diagrams are ordinary session events, so a card replays from the log.
Features
- One model-facing tool,
mermaid, with source and optional title parameters.
- Renders any Mermaid-supported diagram type: flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, pie charts, and more.
- Theme-aware: the diagram follows the host light/dark theme and re-renders when the theme changes.
- Streaming-safe: a card shows progress while the call streams and renders once the arguments are complete.
- Replay-safe: the source is read from the logged call arguments, so a card survives reload and history paging.
- Failure-safe: invalid source falls back to the source view with a notice instead of a broken card.
- Localized card copy (English and Simplified Chinese), following the host language.
- Bundles Mermaid locally and serves it from the plugin's own host route; no CDN and no network dependency at render time.
- The ~3.5 MB Mermaid runtime is loaded only after the first diagram appears, so it costs nothing at boot.
Requirements
dsh 0.2.1-alpha.1 (verified) or a compatible release.- Node.js
^22.19 || >=24.
- A Web profile (
dsh web) for the card. The tool itself also registers in profiles without a web server.
Install
From this repository (a git install builds the package during installation):
dsh plugin --profile web add -w github:ButterHost69/dsh-mermaid-diagram
pnpm ≥10 refuses to run a git dependency's prepare script until it is allowed. If the first add fails, copy the exact package key pnpm prints into allowBuilds in the profile's pnpm-workspace.yaml:
allowBuilds:
dsh-mermaid-diagram: true
Then run the add again. Treat that allowance as permission to run this package's build on your machine.
From a local checkout:
dsh plugin --profile web add -w /absolute/path/to/dsh-mermaid-diagram
Restart dsh web (or reload the page) after installing.
Usage
Ask the model for a diagram, for example:
Draw a flowchart of our release process.
The model calls the mermaid tool, and the result appears as a card:
- Diagram shows the rendered SVG (the default).
- Code shows the diagram source.
- Copy source copies the source to the clipboard.
When the source cannot be rendered, the card opens in Code with the render error above the source.
How it works
| Piece | Responsibility |
|---|
src/index.ts (host) | Registers the mermaid tool and serves the bundled Mermaid runtime from /dsh-mermaid-diagram/mermaid-runtime.js. |
src/diagram.ts | Argument normalization, the size bound, and the model-facing summary. Shared by both halves. |
src/client/index.ts | Registers one keyed tool.call.toolview entry for the mermaid wire tool. |
src/client/MermaidCard.tsx | Reads the diagram from the call, lazily loads the runtime, renders the SVG, and owns the card states. |
src/client/mermaid-runtime.ts | Loads the runtime asset once per page and caches it on globalThis.mermaid. |
The tool's call and result are ordinary session events, so the card derives everything from the log: the recorded call.argsRaw supplies the source, and result.meta is not needed.
Limits
- A source over 50,000 characters is rejected by the tool before it reaches the browser, because Mermaid parses and lays out synchronously.
- The card renders Mermaid's
strict security level; labels are sanitized by Mermaid.
- Very tall diagrams scroll inside the card rather than expanding the transcript.
Development
npm install
npm run build # tsc declarations + tsdown bundles + the Mermaid runtime asset
npm test # vitest: host logic, card model, and card component
npm run typecheck
Build output lands in lib/: index.js (host), client.js (browser half, wrapped for the DSH client module loader), and mermaid-runtime.js (the bundled Mermaid UMD asset plus its license notice).
License
MIT. See LICENSE.
The bundled Mermaid runtime is Mermaid, MIT licensed; its notice ships beside the asset as lib/mermaid-runtime.js.LEGAL.txt.
Prior art: MrmoLabs/dsh-mermaid renders Mermaid fenced code blocks by enhancing the transcript DOM. This plugin takes the documented tool-view seam instead, so the capability is an explicit model tool rather than a Markdown rewrite.
