@changfenhuang/dsh-genui 0.9.1

package/lib/types/plugin/tool.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `render_ui` tool: a model-facing channel that renders a GenUI spec as
+ * an interactive card in the conversation TOOL ROW (route A of the design
+ * doc). The ```dsh-ui fence channel renders inline in the reply; this tool
+ * renders in the tool row and rides the harness's result `meta` projection:
+ * `presentationMeta` stores the repaired spec, the browser toolview
+ * (`src/client/toolview.tsx`) reads it from the result node and renders.
+ *
+ * Zero runtime harness imports, deliberately: an external plugin's node half
+ * must not depend on the harness module graph at runtime (the profile
+ * resolves only the plugin package itself). The definition is therefore a
+ * plain `ToolDefinition` object — the exact shape `defineTool` returns — with
+ * the arguments schema authored as JSON Schema (the harness validates args
+ * and output with the same JSON Schema validator defineTool uses). Deep
+ * validation, deterministic repair, and resource limits live in the shared
+ * guard (`src/client/guard.ts`), which the schema deliberately stays loose
+ * enough to reach.
+ * @module @changfenhuang/dsh-genui/plugin/tool
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+/**
+ * Build the render_ui tool definition. Registered by the plugin node half;
+ * `ctx.tools.register` consumes it exactly like a `defineTool` result.
+ */
+export declare function createRenderUiTool(): ToolDefinition;
+/** Build the validate_dsh_ui tool definition (registered alongside render_ui). */
+export declare function createValidateDshUiTool(): ToolDefinition;

package/lib/types/shared/fence-repair.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared fence-body JSON repair — pure string functions, no DOM, no I/O.
+ * Used by BOTH the client fence renderer (tier-1/tier-2 auto-repair before
+ * rendering) and the node-side validate_dsh_ui tool (which returns the
+ * repaired JSON to the model instead of making it re-author the fix).
+ *
+ * Two tiers, deliberately gated differently by the callers:
+ * - Tier-1 (`repairFenceJson`): heals the most common model JSON typos that
+ *   do NOT change the body's structure — unescaped half-width quotes inside
+ *   string values and trailing commas. Safe at any time (streaming included),
+ *   adopted only when the WHOLE body parses afterwards.
+ * - Tier-2 (`completeFenceJson`): heals structural incompleteness — missing
+ *   closing quotes/brackets — by appending the missing terminators, and
+ *   skips mismatched closers (a `]` mistyped as `}`, duplicated terminators).
+ *   SETTLED MESSAGES ONLY: a streaming half must never be adopted as a
+ *   finished prefix.
+ * @module @changfenhuang/dsh-genui/shared/fence-repair
+ */
+/** A fence body counts as complete when it parses as a whole JSON value. */
+export declare function isCompleteJson(raw: string): boolean;
+/** Short human-readable reason for a body that fails whole-JSON parsing, or
+ * null when it parses. Positions come from the host's JSON.parse error. */
+export declare function describeJsonFailure(raw: string): string | null;
+/**
+ * Tier-1 repair — SAFE AT ANY TIME (streaming included): heals the most
+ * common model JSON typos that do NOT change the body's structure, and only
+ * when the whole body parses afterwards (so a still-growing streaming half
+ * can never be adopted):
+ *
+ * 1. Unescaped half-width `"` inside a string value — Chinese text quoted
+ *    with ASCII quotes (e.g. `对"别名路径"判定失败`), which makes JSON.parse
+ *    fail near that quote with "Expected ',' or ']'...".
+ * 2. Trailing commas before `}` / `]` or at end of input.
+ *
+ * The state-machine scan walks the raw body tracking string-open state:
+ * - inside a string, a quote whose next non-space char is NOT one of `, ] } :`
+ *   (or end of input) cannot legally close the string → escape it as `\"`;
+ * - a `,` whose next non-space char is `}` / `]` / end of input is a trailing
+ *   comma → drop it.
+ *
+ * Returns `{ text, repairs }` on success, or null when nothing needed fixing
+ * or the body still does not parse (callers fall through to tier-2 / banner).
+ */
+export declare function repairFenceJson(raw: string): {
+    text: string;
+    repairs: number;
+} | null;
+/**
+ * Tier-2 repair — SETTLED MESSAGES ONLY (never while streaming): heals
+ * structural incompleteness — missing closing quotes/brackets — by appending
+ * the missing terminators, and heals stray closers — a `]` mistyped as `}` or
+ * a duplicated terminator — by skipping closers that do not match the open
+ * stack (they cannot be legal JSON). Callers gate it on settled messages (the
+ * client uses the host-provided fence source; the validate tool is by
+ * definition pre-emission), so a streaming half can never flash premature UI.
+ *
+ * ONE unified scan: the tier-1 fixes (quote escaping + trailing-comma drops)
+ * are folded into the same pass, so bodies that combine BOTH defect classes
+ * (a trailing comma AND a missing closer) heal in one shot — the old
+ * two-phase chain lost tier-1's partial work when its whole-body parse
+ * failed, and re-scanning the raw text could not compose the repairs.
+ * Adopted only when the completed body parses as whole JSON.
+ */
+export declare function completeFenceJson(raw: string): {
+    text: string;
+    repairs: number;
+} | null;

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@changfenhuang/dsh-genui",
+  "description": "GenUI for DeepSeek Harness: interactive UI components rendered inline in assistant replies via the ```dsh-ui fence — layout, charts, plots, forms, quizzes, mermaid, 3D scenes, and an action event loop back to the model. Ships the fence-teaching host plugin, the browser renderer (client half), and the genui skill.",
+  "version": "0.9.1",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/plugin/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/plugin/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/plugin/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/assets/mermaid.js",
+    "lib/assets/three.js",
+    "lib/assets/echarts.js",
+    "lib/types/plugin/index.d.ts",
+    "lib/types/plugin/invariant.d.ts",
+    "lib/types/client/index.d.ts",
+    "SKILL.md",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "demo-prompts.md",
+    "cordis.patch.yml",
+    "lib",
+    "src",
+    "tsconfig.json",
+    "tsdown.config.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omdsh-dev/dsh-genui.git"
+  },
+  "homepage": "https://github.com/omdsh-dev/dsh-genui",
+  "bugs": {
+    "url": "https://github.com/omdsh-dev/dsh-genui/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "generative-ui",
+    "plugin",
+    "ui"
+  ],
+  "dependencies": {
+    "react": "^18.3.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-tool": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8 || >=0.1.1-rc.0 <0.2.0",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^22.19.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@types/three": "^0.185.4",
+    "jsdom": "^25.0.0",
+    "lightningcss": "^1.25.0",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vitest": "^3.0.0",
+    "echarts": "^5.6.0",
+    "yaml": "^2.4.2",
+    "mermaid": "11.16.0",
+    "three": "^0.180.0",
+    "react-dom": "^18.3.1"
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.json && tsdown",
+    "test": "vitest run",
+    "check": "rm -rf lib && tsc -p tsconfig.json && vitest run && tsdown",
+    "prepack": "node scripts/prepack.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [],
+      "platform": "web"
+    }
+  },
+  "packageManager": "pnpm@11.7.0",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "pnpm": ">=11.7.0 <12"
+  }
+}

package/src/client/EChartNode.tsx

@@ -0,0 +1,242 @@
+/**
+ * ECharts node: renders a full ECharts chart from a declarative option
+ * object. The echarts engine is lazy-loaded (lib/assets/echarts.js) only when
+ * an `echart` node appears — the main client bundle never carries the engine.
+ *
+ * The `option` field accepts a standard ECharts `EChartsCoreOption`. For
+ * simple use cases the `preset` + `data` shorthand builds the option
+ * automatically: `preset: 'bar' | 'line' | 'pie' | 'scatter' | 'area'` maps
+ * to a themed option template that reads the same `data`/`series` shape as
+ * the `chart` node, so a model can upgrade a `chart` to ECharts by changing
+ * `type` to `echart` and adding `preset`.
+ * @module @changfenhuang/dsh-genui/client/EChartNode
+ */
+import { useEffect, useRef, useState } from 'react'
+import css from './GenuiBlock.module.css'
+import { createChart as lazyCreateChart, type EChartsInstance } from './echarts-lazy.ts'
+import { CHART_COLORS } from './blocks/charts.tsx'
+import type { GenuiEChart } from './spec.ts'
+
+/** Read a CSS custom property from the document root (host theme token). */
+function readToken(name: string, fallback: string): string {
+  const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim()
+  return v || fallback
+}
+
+/** Resolve the host accent and label colors for ECharts theming. */
+function themeColors(): {
+  accent: string
+  labelPrimary: string
+  labelSecondary: string
+  labelTertiary: string
+  border: string
+  bgLayer1: string
+} {
+  return {
+    accent: readToken('--dsw-alias-state-business-primary', '#4f8ef7'),
+    labelPrimary: readToken('--dsw-alias-label-primary', '#e6e6e6'),
+    labelSecondary: readToken('--dsw-alias-label-secondary', '#a0a0a0'),
+    labelTertiary: readToken('--dsw-alias-label-tertiary', '#6b6b6b'),
+    border: readToken('--dsw-alias-border-l1', 'rgba(255,255,255,0.12)'),
+    bgLayer1: readToken('--dsw-alias-bg-layer-1', '#1a1a1e'),
+  }
+}
+
+/** Build a full ECharts option from a preset + the simple data/series shape. */
+function presetOption(node: GenuiEChart): Record<string, unknown> {
+  const t = themeColors()
+  const colors = CHART_COLORS.map(c => readToken(c.replace('var(', '').replace(')', ''), t.accent))
+  const data = node.data ?? []
+  const series = node.series
+
+  // Shared tooltip base: renderMode 'richText' prevents ECharts from writing
+  // tooltip content via innerHTML — labels/formatters are model output and
+  // must never reach the HTML parser.
+  const tt = (extra: Record<string, unknown> = {}): Record<string, unknown> => ({
+    renderMode: 'richText',
+    backgroundColor: t.bgLayer1,
+    borderColor: t.border,
+    textStyle: { color: t.labelPrimary },
+    ...extra,
+  })
+
+  const base = {
+    color: colors,
+    textStyle: { color: t.labelSecondary, fontFamily: 'inherit' },
+    backgroundColor: 'transparent',
+    grid: { left: 48, right: 16, top: 24, bottom: 32 },
+    tooltip: tt({ trigger: 'item' }),
+  }
+
+  switch (node.preset) {
+    case 'pie': {
+      return {
+        ...base,
+        tooltip: tt({ trigger: 'item', formatter: '{b}: {c} ({d}%)' }),
+        legend: { bottom: 0, textStyle: { color: t.labelTertiary } },
+        series: [{
+          type: 'pie',
+          radius: ['40%', '70%'],
+          avoidLabelOverlap: true,
+          itemStyle: { borderRadius: 6, borderColor: t.bgLayer1, borderWidth: 2 },
+          label: { color: t.labelSecondary },
+          data: data.map(d => ({ name: d.label, value: d.value })),
+        }],
+      }
+    }
+    case 'scatter': {
+      // xAxis is 'category' so string labels (e.g. 「一月」) render correctly;
+      // the previous `type: 'value'` xAxis could not plot non-numeric labels.
+      return {
+        ...base,
+        tooltip: tt({ trigger: 'item' }),
+        xAxis: { type: 'category', data: data.map(d => d.label), axisLine: { lineStyle: { color: t.border } }, axisLabel: { color: t.labelTertiary }, splitLine: { lineStyle: { color: t.border, opacity: 0.5 } } },
+        yAxis: { type: 'value', axisLine: { lineStyle: { color: t.border } }, axisLabel: { color: t.labelTertiary }, splitLine: { lineStyle: { color: t.border, opacity: 0.5 } } },
+        series: [{
+          type: 'scatter',
+          symbolSize: 10,
+          data: data.map(d => d.value),
+        }],
+      }
+    }
+    case 'area': {
+      return {
+        ...base,
+        tooltip: tt({ trigger: 'axis' }),
+        xAxis: { type: 'category', data: data.map(d => d.label), axisLine: { lineStyle: { color: t.border } }, axisLabel: { color: t.labelTertiary } },
+        yAxis: { type: 'value', axisLine: { lineStyle: { color: t.border } }, axisLabel: { color: t.labelTertiary }, splitLine: { lineStyle: { color: t.border, opacity: 0.5 } } },
+        series: (series ?? [{ label: '', data }]).map((s, i) => ({
+          name: s.label,
+          type: 'line',
+          smooth: true,
+          areaStyle: { opacity: 0.15 },
+          data: s.data.map(d => d.value),
+          ...optItemStyleColor(s.color, i, series),
+        })),
+        legend: series !== undefined ? { bottom: 0, textStyle: { color: t.labelTertiary } } : undefined,
+      }
+    }
+    case 'line': {
+      return {
+        ...base,
+        tooltip: tt({ trigger: 'axis' }),
+        xAxis: { type: 'category', data: data.map(d => d.label), axisLine: { lineStyle: { color: t.border } }, axisLabel: { color: t.labelTertiary } },
+        yAxis: { type: 'value', axisLine: { lineStyle: { color: t.border } }, axisLabel: { color: t.labelTertiary }, splitLine: { lineStyle: { color: t.border, opacity: 0.5 } } },
+        series: (series ?? [{ label: '', data }]).map((s, i) => ({
+          name: s.label,
+          type: 'line',
+          smooth: true,
+          showSymbol: true,
+          symbolSize: 6,
+          data: s.data.map(d => d.value),
+          ...optItemStyleColor(s.color, i, series),
+        })),
+        legend: series !== undefined ? { bottom: 0, textStyle: { color: t.labelTertiary } } : undefined,
+      }
+    }
+    default: {
+      // 'bar' or unspecified
+      return {
+        ...base,
+        tooltip: tt({ trigger: 'axis', axisPointer: { type: 'shadow' } }),
+        xAxis: { type: 'category', data: data.map(d => d.label), axisLine: { lineStyle: { color: t.border } }, axisLabel: { color: t.labelTertiary } },
+        yAxis: { type: 'value', axisLine: { lineStyle: { color: t.border } }, axisLabel: { color: t.labelTertiary }, splitLine: { lineStyle: { color: t.border, opacity: 0.5 } } },
+        series: (series ?? [{ label: '', data }]).map(s => ({
+          name: s.label,
+          type: 'bar',
+          barMaxWidth: 40,
+          itemStyle: { borderRadius: [4, 4, 2, 2], ...(s.color !== undefined ? { color: s.color } : {}) },
+          data: s.data.map(d => d.value),
+        })),
+        legend: series !== undefined ? { bottom: 0, textStyle: { color: t.labelTertiary } } : undefined,
+      }
+    }
+  }
+}
+
+/** Per-series itemStyle.color override when the preset series declares one
+ * (aligns with the `chart` node which respects `series[].color`). */
+function optItemStyleColor(color: string | undefined, _i: number, _series: unknown): Record<string, unknown> {
+  return color !== undefined ? { itemStyle: { color } } : {}
+}
+
+export function EChartNode({ node }: { node: GenuiEChart }) {
+  const ref = useRef<HTMLDivElement | null>(null)
+  const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading')
+  const instanceRef = useRef<EChartsInstance | null>(null)
+
+  useEffect(() => {
+    let alive = true
+    const el = ref.current
+    if (el === null) return
+
+    // Full `option` wins over preset shorthand.
+    const option = node.option ?? presetOption(node)
+
+    void lazyCreateChart(el, option, { height: node.height ?? 300 }).then((inst) => {
+      if (!alive) {
+        inst.dispose()
+        return
+      }
+      instanceRef.current = inst
+      setStatus('ready')
+    }).catch(() => {
+      if (alive) setStatus('error')
+    })
+
+    return () => {
+      alive = false
+      instanceRef.current?.dispose()
+      instanceRef.current = null
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  // Resize observer: keep the chart responsive.
+  useEffect(() => {
+    if (status !== 'ready') return
+    const el = ref.current
+    if (el === null) return
+    const ro = new ResizeObserver(() => {
+      instanceRef.current?.resize()
+    })
+    ro.observe(el)
+    return () => { ro.disconnect() }
+  }, [status])
+
+  // Update option when the node changes (model re-render). `status` is in
+  // deps so that when the engine finishes loading (status: 'loading' →
+  // 'ready'), this effect re-runs and applies the LATEST option — without
+  // it, a spec update that arrived during engine load would be lost forever
+  // (the mount effect captured the old option, and this effect would have
+  // returned early when status was 'loading' and never re-run).
+  useEffect(() => {
+    if (status !== 'ready' || instanceRef.current === null) return
+    const option = node.option ?? presetOption(node)
+    instanceRef.current.setOption(option, true)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [node, status])
+
+  if (status === 'error') {
+    return (
+      <div className={css.echartFallback} data-genui-echart>
+        <div className={css.echartErr}>ECharts 渲染失败</div>
+        {node.title !== undefined && <div className={css.echartHint}>{node.title}</div>}
+      </div>
+    )
+  }
+
+  return (
+    <div className={css.echartWrap} data-genui-echart>
+      {node.title !== undefined && <div className={css.echartTitle}>{node.title}</div>}
+      <div
+        ref={ref}
+        className={css.echartCanvas}
+        style={{ height: `${node.height ?? 300}px` }}
+        role="img"
+        aria-label={node.title ?? 'ECharts chart'}
+      />
+      {status === 'loading' && <div className={css.echartHint}>加载图表…</div>}
+    </div>
+  )
+}

package/src/client/ErrorBoundary.tsx

@@ -0,0 +1,66 @@
+/**
+ * Rendering error boundary: a component render failure inside one GenUI
+ * block must never take down the whole chat surface (pre-2026-08-09 builds
+ * crashed the entire conversation tree on a missing API). Every fence,
+ * toolview card and panel body renders under this boundary; on error the
+ * block degrades to a compact inline alert instead of unmounting the tree.
+ * @module @changfenhuang/dsh-genui/client
+ */
+
+import { Component, type ErrorInfo, type ReactNode } from 'react'
+
+interface ErrorBoundaryProps {
+  /** What the block is, shown in the fallback alert (fence / tool / panel). */
+  label?: string
+  children: ReactNode
+}
+
+interface ErrorBoundaryState {
+  error: Error | null
+}
+
+const fallbackStyle: Record<string, string | number> = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: '4px',
+  padding: '8px 12px',
+  margin: '4px 0',
+  borderRadius: '8px',
+  border: '1px solid rgba(127,127,127,0.35)',
+  background: 'rgba(127,127,127,0.08)',
+  color: 'inherit',
+  fontSize: '12px',
+  lineHeight: 1.5,
+  fontFamily: 'inherit',
+}
+
+/**
+ * Class boundary because function components cannot catch their own subtree
+ * errors. `getDerivedStateFromError` flips to the fallback render; the error
+ * itself is logged (and its message surfaced in the alert) so the user sees
+ * a hint instead of a silent white region.
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  override state: ErrorBoundaryState = { error: null }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error }
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo): void {
+    console.error('[dsh-genui] render failed:', error, info.componentStack ?? '')
+  }
+
+  override render(): ReactNode {
+    const { error } = this.state
+    if (error === null) return this.props.children
+    return (
+      <div style={fallbackStyle} role="alert" data-genui-error>
+        <span style={{ fontWeight: 600 }}>
+          ⚠️ {this.props.label ?? '此界面'}渲染失败（已隔离，不影响其他内容）
+        </span>
+        <span style={{ opacity: 0.75, overflowWrap: 'anywhere' }}>{error.message}</span>
+      </div>
+    )
+  }
+}