dsh-plugin-mermaid-preview

dsh-plugin-mermaid-preview

Mermaid diagrams in DeepSeek Harness, in the two places they belong:

• .mmd / .mermaid files open in the right-sidebar document viewer as diagrams instead of plain text.
• ```mermaid fences in chat messages render as diagrams instead of syntax-highlighted code blocks.

What it does

• Registers a document-preview implementation for the mmd and mermaid file suffixes through the harness's public documentPreviews extension point.
• Claims the mermaid Markdown fence language through ui-primitives's fence registry, so chat transcripts render the diagram with no cooperation from the chat package.
• Renders with mermaid 11, bundled into the plugin's own client artifact. Both surfaces share one runtime (configuration, palette sampling, measurement, device-pixel sizing), so a diagram cannot look right in one place and wrong in the other.
• Follows the shell's light/dark palette and re-renders when the theme changes.
• Zooms per diagram view: − / percentage / + / 重置 in a small control under the diagram, plus Ctrl (or ⌘) + wheel over it. 100% means "fills the pane width", the remembered zoom is a view preference rather than document state, and each preview tab keeps its own zoom because the state lives in the renderer instance.
• In chat, a fence that is still streaming keeps its code block until the body is complete: a half-drawn diagram is worse than the source the reader can already see.
• Falls back to showing the source, with the parse error above it, when a diagram does not parse — a file the agent is still writing is the common case, so a failed render never hides the content.
• Ships Simplified Chinese and English copy through the shell's locale service.

Supported diagram types are mermaid's own: flowchart, sequence, class, state, entity-relationship, gantt, pie, git graph, mindmap, timeline, quadrant, requirement, sankey, block, architecture, and the rest.

Requirements

• DSH with the web profile (@deepseek-ai/dsh-web-app), which mounts @deepseek-ai/dsh-client-ui-sidebar-documentpreview. The plugin stays parked until that viewer is mounted, because documentPreviews is the service it extends.
• Chat fences additionally need a harness that has the Markdown fence registry — a ui-primitives exporting registeredFences. On an older harness the .mmd preview works normally and ```mermaid blocks keep rendering as code blocks; the plugin logs one line saying so. It does not fail, and it does not take the file preview down with it.

Install

From npm

dsh plugin --profile web add dsh-plugin-mermaid-preview

The published tarball ships the built artifacts, and prepublishOnly rebuilds them before every release.

From a checkout

The harness serves the built lib/client.js and never reads sources, and build output is not committed, so build first:

git clone https://github.com/huiyeo/dsh-plugin-mermaid-preview
cd dsh-plugin-mermaid-preview
pnpm install
pnpm run build

Then install that directory as a profile layer:

dsh plugin --profile web add /path/to/dsh-plugin-mermaid-preview

dsh plugin add installs the package and, because the manifest declares dsh.bundle.patch, appends it to dsh.profile.bundles. The bundle layer is read at process start, so restart the dsh web process, then reload the page.

To see it without waiting for a restart, a profile with patchReload: live also accepts the row directly in $DSH_HOME/profiles/web/cordis.patch.yml, which hot-mounts on save so only a page reload is needed:

- insert:
    - id: mermaid-preview
      name: dsh-plugin-mermaid-preview

Add that only while iterating, and remove it once the process restarts: the bundle layer then mounts the same row, and documentPreviews.register() throws on a duplicate implementation id.

Verify the layer landed:

node -e "console.log(require('./package.json').dsh.profile.bundles)" \
  # run in $DSH_HOME/profiles/web  →  should list dsh-plugin-mermaid-preview

Remove it with dsh plugin --profile web remove dsh-plugin-mermaid-preview.

Development

pnpm install
pnpm run build          # lib/index.js (host half) + lib/client.js (browser half)
pnpm test               # load the built artifact the way the module system does

tests/browser-smoke.mjs additionally renders a diagram in headless Chrome and asserts on the produced SVG. It needs a browser that can actually start — a confined sandbox blocks Chrome's own IPC, so run it somewhere unrestricted:

CHROME_PATH=/path/to/chrome pnpm run test:browser

How the two halves fit together

lib/index.js is the host half and deliberately contributes nothing: a package is only scanned for a browser half when it is mounted as a host row, so the row exists to make the browser half discoverable.

lib/client.js is a single classic script that calls window.__ModuleLoader__.load({ id, factory }) with a CommonJS-style factory. That format is the harness's own client-bundle contract; the browser half of @deepseek-ai/dsh-client-modules serves the file and drives it. Two consequences shape the build:

• Only the harness browser platform's module-table words may stay external (react, react/jsx-runtime, the UI registries). Everything else — mermaid included — must be inlined, because a require() the module table cannot answer throws when the bundle materializes.
• The artifact must be one file. mermaid loads each diagram grammar through a dynamic import(); the plugin loader serves exactly one file per package and there is no dynamic-import hook, so codeSplitting: false folds every grammar into the factory. The result is ~7 MB uncompressed, fetched once and cached by revision.

The document body receives loading: 'bytes-complete' content, so it gets the whole file in one shot and never has to page — the paged mode would hand it an accumulated prefix with no way to request the rest.

Zoom must snap to the DEVICE pixel grid

The renderer re-sizes the SVG through its own width/height attributes rather than through CSS, so the browser re-rasterizes the vector at the target size instead of resampling a bitmap. The size it writes is snapped so that width × devicePixelRatio is a whole number:

devicePixels / devicePixelRatio   // not Math.round(cssPixels)

A whole number of CSS pixels is not a whole number of device pixels. On a 125%-scaled Windows display (devicePixelRatio === 1.25) a 326 px box covers 407.5 device pixels — half a pixel off the grid — and the browser resolves that by resampling, which reads as blur. It shows up at only some zoom steps: 50% was soft while 100% happened to land whole. Rounding CSS pixels does not fix it; snapping device pixels does. tests/ cannot catch this, because jsdom has no rasterizer.

If it ever needs re-checking, the numbers are visible from the page itself — getBoundingClientRect() on the SVG times devicePixelRatio must be a whole number at every zoom step. To reach a real browser from an agent session, the DSH Browser Control extension (Chrome MV3 + a local WebSocket bridge on 127.0.0.1:9777) works when a sandbox forbids launching one: the extension dials out as a client, so the agent only has to accept that socket and can then eval in the tab.

Layout

src/index.js                 host half (empty by design)
src/client/index.ts          plugin body: file-preview registration + chat fence claim
src/client/MermaidBody.tsx   the document-preview renderer (owns its zoom)
src/client/MermaidFence.tsx  the chat fence renderer (falls back to the code block)
src/client/mermaid-runtime.ts  shared by both: config, palette, measurement, sizing
src/client/theme.ts          shell palette sampling + dark-mode subscription
src/client/locales.ts        zh/en copy
src/client/styles.ts         plugin-owned stylesheet, injected with a tagged tag
src/client/types.ts          the minimal ambient contracts this package compiles against
cordis.patch.yml             the profile patch that mounts the row
tests/load-artifact.mjs      loads the artifact; asserts the shared-registry contract
tests/load-artifact-legacy.mjs  asserts clean degradation without the fence registry
tests/browser-smoke.mjs      headless render check (needs an unrestricted browser)
tests/zoom.html              two-instance harness proving zoom is per-view

License

MIT