English | 简体中文
dsh-smart-ui
Structured UI cards for DSH conversations. The model calls one tool, ui_render, writes a JSON spec — and the page renders an interactive card: comparisons, charts, headline figures, ordered steps, tables, live calculators, unit conversions, flowcharts.
Answers are often structures: three or more things compared on shared criteria, a series of magnitudes, a handful of headline numbers, ordered steps, rows of records, arithmetic the user wants to redo with their own numbers. In plain text those cost tokens and read badly. This plugin hands the structure to a card and leaves the prose as the conclusion.
- The model writes data, never HTML/JSX. The spec is plain JSON; it goes into the session log and redraws identically after a fork or a resume.
- The card is a pure function of the tool arguments. Nothing is fetched from the host, so a reload or a resumed session gets the same card.
- Light and dark both work. A spec only carries semantic tones (
success, warn, …); the client resolves them to theme tokens, so the model never writes a literal color.
Card types
kind | When to use | Main fields |
|---|
compare | three or more things compared on shared criteria | columns, rows[{label, cells[]}] |
chart | a series of magnitudes (bar), a trend (line), parts of one whole (pie / donut) | series[{label, value, tone?, hint?}], variant, unit |
stats | two to six headline figures | stats[{label, value, tone?, hint?}] |
progress | one ratio to feel at a glance — pass rate, quota used | value, max, label, unit, tone |
steps | three or more ordered steps | steps["text" | {text, detail?}] |
table | rows and columns of records | columns, rows[][] |
diagram | boxes joined by arrows: flow, decision tree, hierarchy, dependency or class sketch | nodes[{id, label, detail?, tone?}] + edges[{from, to, label?}] + layout, or raw mermaid |
calculator | arithmetic the user will redo with their own numbers — bill split, tip | mode: split | tip, fields[{label, value, min?, max?}] |
unit | a quantity converted between units | units, factors?, from, to, value |
note | one thing the reader must not miss | text, tone |
Every card also takes title (heading) and caption (footnote).
diagram has two forms: a structured nodes + edges list (compiled to a Mermaid flowchart; layout: "tree" draws a top-down hierarchy) or complete mermaid source (sequence, state machine, Gantt, ER, and the rest of the diagram family). Exactly one of the two.
How it works
the model writes a spec (plain JSON)
↓
index.js registers the ui_render tool and one prompt section:
validation, normalization, oversize errors back to the model
↓
client.js renders the card in the tool.call.toolview slot
index.js is the host half: the tool schema, normalizeSpec and the Mermaid compilation all live here, so the session log stores exactly the diagram that was drawn.client.js is the client half: compare / stats / steps / table / note / calculator / unit are plain React, progress is inline SVG, chart goes through ECharts, diagram through Mermaid.- The chart libraries are lazy chunks:
client.echarts.js / client.mermaid.js are generated, loaded on first use, and never committed.
Install
Add this repo to your DSH profile dependencies — a local link: or a GitHub URL both work:
{
"dependencies": { "dsh-smart-ui": "link:<absolute path>" },
"dsh": { "profile": { "bundles": ["dsh-smart-ui"] } }
}
Insert the plugin line in the profile's cordis.patch.yml:
- insert:
- id: smart-ui
name: 'dsh-smart-ui'
Then install:
cd "$DSH_PROFILE_DIR"
pnpm install --no-frozen-lockfile
Build
The two chart chunks are generated and git-ignored. Build them after installing, or charts fall back to a plain-text summary:
pnpm install
node build-echarts.mjs # writes client.echarts.js
node build-mermaid.mjs # writes client.mermaid.js
The scripts wrap the npm dist files in DSH's module-loader envelope: ECharts takes its UMD exports branch (no global leak), and Mermaid's API is captured off globalThis before the global is deleted again.
Tests
node test/normalize.mjs # spec normalizer self-check: happy path + guards, per kind
node test/echarts-chunk.mjs # loads the generated chunk without a browser, asserts a usable ECharts
node test/render-svg.mjs # ECharts SSR renders charts and flowcharts into test/out for inspection
node test/render-mermaid.mjs # renders the Mermaid diagram families headless into test/out-mermaid
node test/shot-mermaid.mjs # Chrome screenshots (Mermaid labels are foreignObject HTML)
The last two look for Chrome / Edge (default Windows install paths).
Deliberate limits
| Limit | Value | Why |
|---|
| nodes per spec | 400 (apply(ctx, { maxNodes })) | a runaway model cannot wedge the page |
raw mermaid source | 12000 chars | one card cannot swallow the page |
diagram forms | exactly one | the two paths can never disagree |
Acknowledgments
Thanks to everyone who contributed to this project:
@windzxy @anyiba
License
MIT, see LICENSE.
This repo contains no chart-library code (the generated chunks are git-ignored); the build pulls them from npm: ECharts under Apache License 2.0, Mermaid under MIT.
