dsh-widget

English | 中文

Inline visualization for DeepSeek Harness. The model calls one tool with a self-contained SVG or HTML fragment, and the fragment renders as a card in the conversation — diagrams, charts, timelines, comparison tables, annotated layouts — instead of being described in prose.

Install

From GitHub:

dsh plugin --profile web add github:anneqaq/dsh-widget

Or from a local checkout:

dsh plugin --profile web add /absolute/path/to/dsh-widget

Then restart dsh web. The plugin mounts at startup and has no hot reload.

Verify the row landed in the config tree:

dsh --profile web --dump-config | grep -A2 dsh-widget

If pnpm refuses with ERR_PNPM_ADDING_TO_ROOT — the shipped web profile is a single-package workspace, so its root check fires — allow the root write:

npm_config_ignore_workspace_root_check=true dsh plugin --profile web add github:anneqaq/dsh-widget

Remove with:

dsh plugin --profile web remove dsh-widget

This package has no build step — lib/ is committed, so a git install needs no prepare script and no pnpm allowBuilds grant. Installing it runs no build code on your machine.

Use

The model does the work; there is nothing to configure. Ask for something visual and it calls render_widget:

Draw me the request lifecycle for this service as a timeline.

render_widget takes four arguments:

Argument	Required	Meaning
html	yes	One self-contained SVG or HTML fragment.
title	no	Caption above the card; also the frame title.
height	no	Frame height in CSS pixels. Default 420, clamped to 80–2000.
allowScripts	no	Enable scripts inside the fragment. Off by default.

The tool returns only a short acknowledgement. The fragment is not echoed back into the model context — the card reads it from the logged call arguments, so a large diagram costs one copy in the transcript, not two.

How it works

Two halves, one name:

dsh-widget/
├── package.json        dsh.bundle.patch + dsh.client, no dependencies
├── cordis.patch.yml    inserts this plugin's node-half row
├── icon.svg            plugin icon (display metadata)
├── locale/             display metadata: en.json / zh.json
├── lib/
│   ├── index.js        node half  → registers the tool + one prompt section
│   └── client.js       browser half → renders the tool's calls
└── test/               36 tests, no browser and no harness required

Node half registers a plain ToolDefinition and a system-prompt section stating the authoring contract. It holds no state and draws nothing.

Browser half claims the wire name render_widget in the keyed tool.call.toolview slot. Because the slot is keyed by wire tool name, this is additive: it never touches the shipped tool cards.

No build step. The browser half is hand-authored in the window.__ModuleLoader__.load({ id, factory }) lazy-CJS format the shell expects, so the package ships lib/client.js directly — no tsdown, no TypeScript, no bundler. react is the only module it requires, and react is a member of the shell's frozen platform module table.

No dependencies at all. A bundle is loaded through its real path under the profile, so a bare specifier such as @deepseek-ai/dsh-tools resolves only if the package carries its own node_modules. This package imports nothing, which is what lets it install from any directory — including a symlinked development checkout. The input checks the defineTool helper would have generated are written out in lib/index.js instead.

Isolation

The fragment is model-authored, so it is treated as untrusted content. It renders through a sandboxed srcdoc frame, never through dangerouslySetInnerHTML in the app's own DOM.

• sandbox="" — no scripts, opaque origin. sandbox="allow-scripts" only when the caller asked with allowScripts: true, and never together with allow-same-origin (that pair would let the fragment reach the host document).
• The frame's CSP is default-src 'none' with img-src data: blob:, style-src 'unsafe-inline', and connect-src 'none'. A stray CDN import or a fetch fails closed rather than silently exfiltrating.
• Widgets carry no theme state of their own. The frame injects the palette the app is currently painting with, tracked via body[data-ds-dark-theme] so a live theme switch re-renders the frame.

Limits worth knowing

• The card appears when the fragment argument closes, not while it streams. Reading a half-arrived fragment would render broken markup, so the view shows a placeholder until html is complete — which is usually before the tool result lands.
• 512 KB per fragment. The markup is stored in the session log, so the ceiling bounds the transcript as well as the wire request.
• No network in the frame, by design. Inline everything.
• The card is a tool row, not prose. It renders where the call sits in the turn. Inline-in-the-middle-of-a-paragraph rendering is not available through a public extension point; the tool.call.toolview slot is the sanctioned seam.

Compatibility

package.json declares engines.dsh as >=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0.

The multi-clause || form is required by semver's prerelease rule: a prerelease version only satisfies a comparator set when a comparator in the same [major, minor, patch] tuple carries a prerelease, so a bare >=0.1.2-rc.1 <0.2.0 does not admit 0.1.5-rc.1. Every new upstream prerelease tuple needs its own clause.

Developed and verified against 0.1.7-rc.2. This package deliberately declares no peerDependencies on @deepseek-ai/dsh-*: it imports no host package, and peerDependencies is an enforced install gate (evaluatePluginCompatibility, fail-closed), so declaring one would add a gate without adding truth. engines.dsh is declarative and is what the plugin market reads for its compatibility display.

Development

npm test

36 tests, no browser and no harness required. They run the real projections: the streaming-JSON recovery that decides whether a card renders, the frame's CSP, and the tool contract.

Two checks are deliberate regression guards rather than behavior tests — the module must import nothing, and output.schema must stay closed. Both encode mistakes that fail loudly at harness boot rather than at unit-test time.

License

MIT