# dsh-genui

> Enables the DSH model to directly generate interactive charts, forms, statistical cards, and other UI elements in responses. Users can

## Metadata

- Author: [@omdsh-dev](https://github.com/omdsh-dev)
- Repo: <https://github.com/omdsh-dev/dsh-genui.git>
- GitHub: [omdsh-dev/dsh-genui](https://github.com/omdsh-dev/dsh-genui)
- Stars: 265
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `dsh`, `dsh-plugin`
- Forks: 23
- Open Issues: 3
- Last push: 2026-08-20T10:59:48.000Z
- Added: 2026-08-13T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:omdsh-dev/dsh-genui
```

## Wiki

## One-line Positioning
Let DSH model generate interactive UI components (stat cards, charts, forms, panels) directly in chat responses. Users can browse data, interact with components, and pass interactions back to the model without leaving the conversation.

## Core Capabilities
- Stream-render JSON-described components in model responses: model renders while writing, first completed component appears immediately without waiting for entire response
- Provides 30+ whitelisted components: text, cards, tables, charts (bar/line/pie), forms (input/select/checkbox/switch/slider/radio/submit), progress bar, step bar, timeline, file tree, Mermaid charts, 3D scenes, math function plotting, conversational Q&A, etc.
- Register `render_ui` tool: model can also render the same component spec as a tool-row card via tool call (suitable for "deliverable-type" UI)
- Register `validate_dsh_ui` tool: model self-checks before emitting complex fences, bad nodes are auto-fixed with the fixed JSON attached
- Support component action event flowback: buttons/inputs/switches with `action` trigger a `[genui-action]` message back to the model when clicked, model updates UI accordingly (300ms trailing debounce)
- Provide session top panel: model can continuously stack/replace components in the panel (`/panel` command to invoke), drag top border to change height

## Technical Implementation
- **Language**: TypeScript
- **Key Dependencies**: `@deepseek-ai/cordis` (Cordis injects into host), `@deepseek-ai/dsh-client-runtime` and `@deepseek-ai/dsh-client-ui-primitives` (browser rendering primitives), `@deepseek-ai/dsh-tools` (register render_ui/validate_dsh_ui tools), `react` (UI framework)
- **Architecture Pattern**: Plugin consists of "server half + browser half" two parts. Server half (`src/plugin/index.ts`) injects into host via Cordis, inserts `dsh-ui` fence language description into system prompt, registers two tools, and mounts an on-demand resource route for mermaid/three on host WebServer; browser half (`src/client/index.tsx`) detects at startup whether host provides fence-registry extension point, chooses "registry channel" or "DOM channel" to render fence
- **Entry Files**: `src/index.ts` (package entry) → `src/plugin/index.ts` (server logic); client logic in `src/client/index.tsx`

## Use Cases
Upgrade model responses from plain text to interactive panels: business monitoring, order/revenue trend display, teaching question cards with self-grading, flowcharts and architecture diagrams, real-time function curve parameter tuning, lightweight form collection, etc. Best suited for "user asks one question, model replies with clickable components" scenario, eliminating back-and-forth jumps to external BI/tool pages.

## Prerequisites and Compatibility
| Dependency | Min Version | Description |
|---|---|---|
| DSH (@deepseek-ai/dsh-client-runtime / dsh-client-ui-primitives / dsh-client-ui-slots / dsh-client-ui-tool / dsh-invariants / dsh-llm / dsh-system-prompt / dsh-tools / cordis) | ^0.1.0-rc.6 | Host needs fence-registry extension point or DOM channel rendering capability (DOM channel covers any 0.1.0-rc.6+ build) |
| Node.js | ^22.19.0 or >=24.0.0 | Required by install script and build script |
| pnpm | >=11.7.0 and <12 | Required by `dsh plugin` command; can be enabled via corepack |
| React | ^18.0.0 or ^19.0.0 | Injected via peerDependencies, provided by host |
| Platform | Cross-platform | No os/cpu restrictions; mermaid and three loaded on-demand as IIFE resources |

## Installation
```bash
dsh plugin --profile web add github:omdsh-dev/dsh-genui
```

## Configuration
No additional configuration required. After installation, host automatically injects `dsh-ui` fence language segment, registers `render_ui` and `validate_dsh_ui` tools, and mounts `/plugins/@omdsh-dev/dsh-genui/assets/*` static resource route on host WebServer for on-demand loading of mermaid and three engines. Model output fence specs have built-in hard resource limits (200 nodes / 8 nesting levels / field length limits), excess parts are silently dropped without crashing the UI.

## FAQ

**Q: Fence renders as regular code block, what to do?**

A: Check three things in order: whether host dsh has fence-registry extension point (falls back to DOM channel if not), whether `dsh plugin --profile web list` shows this plugin, finally restart dsh web and hard refresh (Cmd/Ctrl+Shift+R).

**Q: Installation fails with `pnpm not found on PATH`, how to fix?**

A: dsh's plugin subcommand depends on pnpm. Run `corepack enable` or `npm i -g pnpm` to install, must open a new terminal for PATH to take effect, confirm `pnpm -v` outputs before retrying.

**Q: Installed but mermaid or 3D scene won't render?**

A: These two engines load on-demand, first use pulls from `/plugins/@omdsh-dev/dsh-genui/assets/*.js`. Hard refresh browser once; if still fails, remove and reinstall (`dsh plugin --profile web remove @omdsh-dev/dsh-genui` then add).

**Q: Model doesn't output dsh-ui fence, only returns text?**

A: New sessions need dsh web restart to take effect; or directly say "use dsh-ui to draw a stat panel" in your question to remind the model.

**Q: Just cloned, no lib/ directory, can I use it directly?**

A: Cannot use directly. lib/ is build output, need to run `pnpm install` then `pnpm run check` (builds automatically).

**Q: Will too many fence nodes get truncated?**

A: Yes. Plugin has hard resource limits: max 200 nodes per fence, 8 nesting levels; excess parts are silently dropped without crashing the UI.

**Q: How to uninstall this plugin?**

A: Run `dsh plugin --profile web remove @omdsh-dev/dsh-genui`, then restart dsh web; fence will naturally degrade to regular code block without polluting existing sessions.

## Learning Curve
Beginner — ordinary users need no configuration; model's syntax is automatically taught via `SKILL.md` and system prompt, users only need to describe "use dsh-ui to draw an XX panel" in prompt. Developers doing secondary development need familiarity with React, Cordis, and DSH client runtime.

## Known Issues and Limitations
- Hardcoded resource limits: single fence max 200 nodes / 8 nesting levels; panel max 200 nodes / 200 appends, after hitting limit model needs to send `replace` to rebuild (`src/client/guard.ts:25-65`, `src/client/panel-store.ts:29-34`)
- mermaid / three engines load on-demand from `/plugins/@omdsh-dev/dsh-genui/assets/*.js`; very old host builds without this resource route degrade to source/failure message, need to update dsh (`README.md:136`)
- Tool registration depends on optional `tools` service: hosts without tools channel still retain fence channel but lose `render_ui` / `validate_dsh_ui` tools (`src/plugin/index.ts:157-197`)
- DOM channel may wipe plugin-mounted root when host React re-renders: plugin uses MutationObserver + 1 second scan as double insurance fix, but extreme cases still have visual jitter (`src/client/dom-fence.tsx:25-28`)
- Passwords, API Keys, access tokens and other "secrets" in fence content are disabled by protocol layer: model is prompted to refuse fetching, but this plugin has no runtime forced masking, relies on model following prompt

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-genui](https://deepseek-plugin.org/plugins/omdsh-dev/dsh-genui)
Wiki generated by AI (model: `MiniMax-M2.5`)