@changfenhuang/dsh-genui 0.9.6 → 0.9.7

package/lib/types/client/guard.d.ts

@@ -109,13 +109,18 @@ export declare function countGenuiNodes(value: unknown, cap?: number): number;
  * `"type"` strings (e.g. file-tree's `{type:'file'}` children). */
 export declare const GENUI_NODE_TYPES: ReadonlySet<string>;
 /**
- * Count DECLARED nodes in a raw spec tree: objects whose `type` is a
- * white-listed string, descending the same containers `countGenuiNodes`
- * walks. `validate_dsh_ui` compares this with the repaired count to surface
- * children the repair silently dropped (blank-render class of bugs, issue
- * #42) instead of reporting a green check on a half-empty tree.
+ * Count white-listed nodes declared by a raw spec before repair drops invalid entries.
+ * @param value - raw GenUI spec.
+ * @param cap - traversal ceiling.
+ * @returns declared node count up to the ceiling.
  */
 export declare function countDeclaredGenuiNodes(value: unknown, cap?: number): number;
+/**
+ * Return field-level chart errors without changing other repairable component families.
+ * @param value - raw GenUI spec.
+ * @returns chart semantic errors in tree order.
+ */
+export declare function validateGenuiChartSemantics(value: unknown): string[];
 /**
  * Validate a raw spec value against the white list and limits, collecting
  * human-readable problems. Unlike repair this never mutates: it is a

package/lib/types/client/spec.d.ts

@@ -9,7 +9,7 @@
  * are operable, but events do NOT flow back to the model.
  */
 /** One node in the component tree. */
-export type GenuiNode = GenuiText | GenuiRow | GenuiCol | GenuiGrid | GenuiCard | GenuiButton | GenuiInput | GenuiSelect | GenuiCheckbox | GenuiLink | GenuiAudio | GenuiVideo | GenuiBadge | GenuiStat | GenuiProgress | GenuiDivider | GenuiList | GenuiTable | GenuiChart | GenuiTabs | GenuiAvatar | GenuiSpacer | GenuiPlot | GenuiCallout | GenuiSteps | GenuiKeyValue | GenuiDiff | GenuiJson | GenuiCode | GenuiRadio | GenuiSubmit | GenuiSwitch | GenuiSlider | GenuiTextarea | GenuiAccordion | GenuiCopy | GenuiMermaid | GenuiScene3D | GenuiTimeline | GenuiFileTree | GenuiBreadcrumb | GenuiQuiz | GenuiDiagram | GenuiEChart;
+export type GenuiNode = GenuiText | GenuiRow | GenuiCol | GenuiGrid | GenuiCard | GenuiButton | GenuiInput | GenuiSelect | GenuiCheckbox | GenuiLink | GenuiImage | GenuiAudio | GenuiVideo | GenuiBadge | GenuiStat | GenuiProgress | GenuiDivider | GenuiList | GenuiTable | GenuiChart | GenuiTabs | GenuiAvatar | GenuiSpacer | GenuiPlot | GenuiCallout | GenuiSteps | GenuiKeyValue | GenuiDiff | GenuiJson | GenuiCode | GenuiRadio | GenuiSubmit | GenuiSwitch | GenuiSlider | GenuiTextarea | GenuiAccordion | GenuiCopy | GenuiMermaid | GenuiScene3D | GenuiTimeline | GenuiFileTree | GenuiBreadcrumb | GenuiQuiz | GenuiDiagram | GenuiEChart;
 export interface GenuiSpec {
     /** Short title shown as the card banner. */
     title?: string;
@@ -95,6 +95,13 @@ export interface GenuiLink {
      */
     href?: string;
 }
+/** User-controlled image from a browser-reachable URL. */
+export interface GenuiImage {
+    type: 'image';
+    src: string;
+    /** Visible caption and accessible image description. */
+    alt?: string;
+}
 /** User-controlled audio from a browser-reachable URL. */
 export interface GenuiAudio {
     type: 'audio';

package/lib/types/plugin/chart-contract.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validate the native chart contract all the way to something the renderer
+ * can actually draw. The shared guard still owns field/type validation; this
+ * layer adds renderer-specific invariants that would otherwise produce an
+ * empty line/donut chart or a grouped-bars shell with no points.
+ */
+export declare function validateRenderableChartSemantics(value: unknown): string[];

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

@@ -16,7 +16,7 @@ export declare const GENUI_SECTION_ORDER = 105;
  *  Deliberately slim: the `genui` skill carries the full component→field
  *  mapping; this section keeps only the contract that must always be
  *  present (fence syntax, type whitelist, and critical behavioral rules). */
-export declare const GENUI_SECTION_TEXT = "You can render interactive UI components INSIDE your reply \u2014 between paragraphs \u2014 by emitting a fenced block with the language tag `dsh-ui` containing a JSON spec:\n\n```dsh-ui\n{\"title\":\"\u53EF\u9009\u6807\u9898\",\"gap\":14,\"items\":[...]}\n```\n\nThe spec is a white-listed component tree rendered inline where the fence sits. Only these `type` values; the `genui` skill, when available, carries the full content\u2192component mapping and per-component field details:\n\n- \u5E03\u5C40: text \u00B7 row \u00B7 col \u00B7 grid \u00B7 card \u00B7 divider \u00B7 spacer\n- \u5C55\u793A: badge \u00B7 stat \u00B7 progress \u00B7 list \u00B7 table \u00B7 keyvalue \u00B7 avatar \u00B7 audio \u00B7 video \u00B7 timeline \u00B7 file-tree \u00B7 breadcrumb \u00B7 callout \u00B7 steps \u00B7 diff \u00B7 json \u00B7 code \u00B7 copy\n- \u56FE\u8868: chart (bars|line|donut) \u00B7 echart (preset|option) \u00B7 plot (\u51FD\u6570\u56FE)\n- \u4EA4\u4E92: button \u00B7 input \u00B7 textarea \u00B7 select \u00B7 checkbox \u00B7 switch \u00B7 slider \u00B7 radio \u00B7 submit \u00B7 quiz \u00B7 link \u00B7 tabs \u00B7 accordion\n- \u9AD8\u7EA7: mermaid (flowchart/sequence/class/gantt/pie/er/state/journey) \u00B7 diagram (\u7F16\u8F91\u7EA7\u67B6\u6784/\u6D41\u7A0B\u56FE\uFF0C27 \u79CD kind) \u00B7 scene3d (3D WebGL)\n\nRules:\n- \u89E6\u53D1: \u7ED3\u6784\u5316\u8868\u8FBE\u4F18\u4E8E\u7EAF\u6587\u672C\u65F6\u4E3B\u52A8\u7528\uFF08\u8981\u70B9\u3001\u5F3A\u8C03\u3001\u5BF9\u6BD4\u3001\u6D41\u7A0B\u3001\u6B65\u9AA4\u3001\u72B6\u6001\u3001\u6570\u636E\u3001\u6F14\u793A\uFF09\uFF0C\u7EAF\u95EE\u7B54\u4E0E\u4E00\u53E5\u8BDD\u4E0D\u5957 UI\uFF1B\u4E00\u4E2A\u4E3B\u9898\u4E00\u4E2A\u4E3B\u7EC4\u4EF6\uFF0C\u6BCF\u6B21 3\u20138 \u4E2A\u7EC4\u4EF6\uFF0C\u540C\u4E00\u6570\u636E\u4E0D\u91CD\u590D\u51FA\u73B0\u3002\n- JSON \u4E25\u683C: \u574F\u56F4\u680F\u964D\u7EA7\u4E3A\u4EE3\u7801\u5757\uFF1B\u22653 \u8282\u70B9\u6216\u542B table \u7684\u56F4\u680F\u53D1\u51FA\u524D\u8C03\u7528 validate_dsh_ui\uFF0C\u274C \u4FEE\u597D\u518D\u53D1\uFF08\u82E5\u9644\u300C\u5DF2\u81EA\u52A8\u4FEE\u590D\u300DJSON \u7167\u6284\u5373\u53EF\uFF09\u3002\n- \u89C4\u6A21: \u2264200 \u8282\u70B9\u3001\u5D4C\u5957\u22648 \u5C42\uFF08\u8D85\u51FA\u88AB\u622A\u65AD\uFF09\uFF1B3D mesh 1\u20135\uFF1Bplot \u7ED9\u5408\u7406 xMin/xMax\u3002\n- LOCAL-FIRST + actions: UI \u80FD\u81EA\u5DF1\u505A\u7684\u72B6\u6001\u53D8\u5316\uFF08\u5224\u5377\u3001\u5224\u9898\u3001\u91CD\u7F6E\u3001\u5C55\u5F00\u3001\u9009\u4E2D\uFF09\u5C31\u5730\u5B8C\u6210\uFF0C\u96F6\u5F80\u8FD4\uFF1Baction \u53EA\u7528\u4E8E\u5FC5\u987B\u6A21\u578B\u53C2\u4E0E\u7684\u4E8B\u3002\u4EA4\u4E92\u7EC4\u4EF6\u5E26 \"action\":\"name\"\uFF0C\u4EA4\u4E92\u4EE5 [genui-action] name + \u7EC4\u4EF6\u6570\u636E\u56DE\u4F20\uFF0C\u5C4A\u65F6\u91CD\u6E32\u67D3\u66F4\u65B0 UI\uFF1B\u65E0 action \u7684\u6309\u94AE\u7981\u7528\u3002\n- Durable state: \u4EA4\u4E92\u72B6\u6001\u6309\u300C\u4F1A\u8BDD+\u5185\u5BB9\u6307\u7EB9\u300D\u6301\u4E45\u5316\u2014\u2014\u5237\u65B0/\u91CD\u653E\u6062\u590D\uFF1B\u91CD\u6E32\u67D3\u76F8\u540C\u5185\u5BB9\u4FDD\u7559\uFF0C\u65B0\u5185\u5BB9\u91CD\u7F6E\u3002\n- \u5377\u5B50\u6A21\u5F0F: \u6BCF\u9898\u4E00\u4E2A radio\uFF08group+answer+explanation\uFF09+ \u4E00\u4E2A submit\uFF08groups \u5168\u5217\uFF09\uFF0C\u672C\u5730\u5224\u5206\u3002\n- Secrets ban: \u4E0D\u7D22\u53D6\u5BC6\u7801\u3001API Key\u3001Token\u3001\u6062\u590D\u7801\uFF1B\u9700\u8981\u65F6\u62D2\u7EDD\u5E76\u89E3\u91CA\u3002\n- Tool channel: render_ui \u5DE5\u5177\u628A\u540C\u4E00 spec \u6E32\u67D3\u4E3A\u5DE5\u5177\u884C\u5361\u7247\uFF08\u4EA4\u4ED8\u7269\u578B\u754C\u9762\u7528\uFF09\uFF1B\u56F4\u680F\u7528\u4E8E\u56DE\u7B54\u5185\u8054 UI\u3002\n- Panel: \"panel\":true \u53EA\u6E32\u67D3\u8FDB\u4F1A\u8BDD\u9762\u677F dock \u5E76\u539F\u5730\u66F4\u65B0\uFF1B\"append\":true \u8FFD\u52A0\u5408\u5E76\uFF08\u540C\u6807\u7B7E tabs \u8FFD\u52A0/\u65B0\u6807\u7B7E\u52A0\u5165/\u5C3E\u90E8\u8FFD\u52A0\uFF09\uFF1B\u4E0A\u9650 200 \u8282\u70B9/200 \u6B21\u8FFD\u52A0\uFF0C\u6EE1\u4E86\u53D1 replace \u91CD\u5EFA\u3002\u9762\u677F\u7EC4\u4EF6\u6765\u7684 [genui-action] \u53EA\u56DE\u4E00\u4E2A panel:true \u56F4\u680F + \u81F3\u591A\u4E00\u884C 10 \u5B57\u5185\u786E\u8BA4\uFF0C\u4E0D\u89E3\u91CA\u3001\u4E0D\u7528\u666E\u901A\u56F4\u680F\u3002";
+export declare const GENUI_SECTION_TEXT = "You can render interactive UI components INSIDE your reply \u2014 between paragraphs \u2014 by emitting a fenced block with the language tag `dsh-ui` containing a JSON spec:\n\n```dsh-ui\n{\"title\":\"\u53EF\u9009\u6807\u9898\",\"gap\":14,\"items\":[...]}\n```\n\nThe spec is a white-listed component tree rendered inline where the fence sits. Only these `type` values; the `genui` skill, when available, carries the full content\u2192component mapping and per-component field details:\n\n- \u5E03\u5C40: text \u00B7 row \u00B7 col \u00B7 grid \u00B7 card \u00B7 divider \u00B7 spacer\n- \u5C55\u793A: badge \u00B7 stat \u00B7 progress \u00B7 list \u00B7 table \u00B7 keyvalue \u00B7 avatar \u00B7 audio \u00B7 video \u00B7 timeline \u00B7 file-tree \u00B7 breadcrumb \u00B7 callout \u00B7 steps \u00B7 diff \u00B7 json \u00B7 code \u00B7 copy\n- \u56FE\u8868: chart {\"type\":\"chart\",\"kind\":\"bars|line|donut\",\"data\":[{\"label\":\"...\",\"value\":n,\"color\":\"#hex?\"}],\"series\":[...]?}\uFF08series \u4EC5 bars\uFF1B\u672A\u77E5\u6269\u5C55\u5B57\u6BB5\u53EF\u901A\u8FC7\u6821\u9A8C\uFF0C\u4F46\u539F\u751F chart repair/render \u4F1A\u5FFD\u7565\uFF09 \u00B7 echart (preset|option) \u00B7 plot (\u51FD\u6570\u56FE)\n- \u4EA4\u4E92: button \u00B7 input \u00B7 textarea \u00B7 select \u00B7 checkbox \u00B7 switch \u00B7 slider \u00B7 radio \u00B7 submit \u00B7 quiz \u00B7 link \u00B7 tabs \u00B7 accordion\n- \u9AD8\u7EA7: mermaid (flowchart/sequence/class/gantt/pie/er/state/journey) \u00B7 diagram (\u7F16\u8F91\u7EA7\u67B6\u6784/\u6D41\u7A0B\u56FE\uFF0C27 \u79CD kind) \u00B7 scene3d (3D WebGL)\n\nRules:\n- \u89E6\u53D1: \u7ED3\u6784\u5316\u8868\u8FBE\u4F18\u4E8E\u7EAF\u6587\u672C\u65F6\u4E3B\u52A8\u7528\uFF08\u8981\u70B9\u3001\u5F3A\u8C03\u3001\u5BF9\u6BD4\u3001\u6D41\u7A0B\u3001\u6B65\u9AA4\u3001\u72B6\u6001\u3001\u6570\u636E\u3001\u6F14\u793A\uFF09\uFF0C\u7EAF\u95EE\u7B54\u4E0E\u4E00\u53E5\u8BDD\u4E0D\u5957 UI\uFF1B\u4E00\u4E2A\u4E3B\u9898\u4E00\u4E2A\u4E3B\u7EC4\u4EF6\uFF0C\u6BCF\u6B21 3\u20138 \u4E2A\u7EC4\u4EF6\uFF0C\u540C\u4E00\u6570\u636E\u4E0D\u91CD\u590D\u51FA\u73B0\u3002\n- JSON \u4E25\u683C: \u574F\u56F4\u680F\u964D\u7EA7\u4E3A\u4EE3\u7801\u5757\uFF1B\u22653 \u8282\u70B9\u6216\u542B table \u7684\u56F4\u680F\u53D1\u51FA\u524D\u8C03\u7528 validate_dsh_ui\uFF0C\u274C \u4FEE\u597D\u518D\u53D1\uFF08\u82E5\u9644\u300C\u5DF2\u81EA\u52A8\u4FEE\u590D\u300DJSON \u7167\u6284\u5373\u53EF\uFF09\u3002\n- \u89C4\u6A21: \u2264200 \u8282\u70B9\u3001\u5D4C\u5957\u22648 \u5C42\uFF08\u8D85\u51FA\u88AB\u622A\u65AD\uFF09\uFF1B3D mesh 1\u20135\uFF1Bplot \u7ED9\u5408\u7406 xMin/xMax\u3002\n- LOCAL-FIRST + actions: UI \u80FD\u81EA\u5DF1\u505A\u7684\u72B6\u6001\u53D8\u5316\uFF08\u5224\u5377\u3001\u5224\u9898\u3001\u91CD\u7F6E\u3001\u5C55\u5F00\u3001\u9009\u4E2D\uFF09\u5C31\u5730\u5B8C\u6210\uFF0C\u96F6\u5F80\u8FD4\uFF1Baction \u53EA\u7528\u4E8E\u5FC5\u987B\u6A21\u578B\u53C2\u4E0E\u7684\u4E8B\u3002\u4EA4\u4E92\u7EC4\u4EF6\u5E26 \"action\":\"name\"\uFF0C\u4EA4\u4E92\u4EE5 [genui-action] name + \u7EC4\u4EF6\u6570\u636E\u56DE\u4F20\uFF0C\u5C4A\u65F6\u91CD\u6E32\u67D3\u66F4\u65B0 UI\uFF1B\u65E0 action \u7684\u6309\u94AE\u7981\u7528\u3002\n- Durable state: \u4EA4\u4E92\u72B6\u6001\u6309\u300C\u4F1A\u8BDD+\u5185\u5BB9\u6307\u7EB9\u300D\u6301\u4E45\u5316\u2014\u2014\u5237\u65B0/\u91CD\u653E\u6062\u590D\uFF1B\u91CD\u6E32\u67D3\u76F8\u540C\u5185\u5BB9\u4FDD\u7559\uFF0C\u65B0\u5185\u5BB9\u91CD\u7F6E\u3002\n- \u5377\u5B50\u6A21\u5F0F: \u6BCF\u9898\u4E00\u4E2A radio\uFF08group+answer+explanation\uFF09+ \u4E00\u4E2A submit\uFF08groups \u5168\u5217\uFF09\uFF0C\u672C\u5730\u5224\u5206\u3002\n- Secrets ban: \u4E0D\u7D22\u53D6\u5BC6\u7801\u3001API Key\u3001Token\u3001\u6062\u590D\u7801\uFF1B\u9700\u8981\u65F6\u62D2\u7EDD\u5E76\u89E3\u91CA\u3002\n- Tool channel: render_ui \u5DE5\u5177\u628A\u540C\u4E00 spec \u6E32\u67D3\u4E3A\u5DE5\u5177\u884C\u5361\u7247\uFF08\u4EA4\u4ED8\u7269\u578B\u754C\u9762\u7528\uFF09\uFF1B\u56F4\u680F\u7528\u4E8E\u56DE\u7B54\u5185\u8054 UI\u3002\n- Panel: \"panel\":true \u53EA\u6E32\u67D3\u8FDB\u4F1A\u8BDD\u9762\u677F dock \u5E76\u539F\u5730\u66F4\u65B0\uFF1B\"append\":true \u8FFD\u52A0\u5408\u5E76\uFF08\u540C\u6807\u7B7E tabs \u8FFD\u52A0/\u65B0\u6807\u7B7E\u52A0\u5165/\u5C3E\u90E8\u8FFD\u52A0\uFF09\uFF1B\u4E0A\u9650 200 \u8282\u70B9/200 \u6B21\u8FFD\u52A0\uFF0C\u6EE1\u4E86\u53D1 replace \u91CD\u5EFA\u3002\u9762\u677F\u7EC4\u4EF6\u6765\u7684 [genui-action] \u53EA\u56DE\u4E00\u4E2A panel:true \u56F4\u680F + \u81F3\u591A\u4E00\u884C 10 \u5B57\u5185\u786E\u8BA4\uFF0C\u4E0D\u89E3\u91CA\u3001\u4E0D\u7528\u666E\u901A\u56F4\u680F\u3002";
 /**
  * Register the GenUI output-language section and the render_ui tool.
  * @param ctx - cordis context.

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.6",
+  "version": "0.9.7",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/plugin/index.d.ts",
@@ -64,6 +64,7 @@
     "react": "^18.3.1"
   },
   "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
     "@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",
@@ -73,9 +74,9 @@
     "@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-skill": "^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": {
@@ -85,18 +86,18 @@
     "@types/react": "^18.0.0",
     "@types/react-dom": "^18.0.0",
     "@types/three": "^0.185.4",
+    "echarts": "^5.6.0",
     "jsdom": "^25.0.0",
     "lightningcss": "^1.25.0",
+    "mermaid": "11.16.0",
+    "react-dom": "^18.3.1",
+    "three": "^0.180.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"
+    "yaml": "^2.4.2"
   },
   "scripts": {
     "build": "rm -rf lib && tsc -p tsconfig.json && tsdown",
@@ -118,4 +119,4 @@
     "node": "^22.19.0 || >=24.0.0",
     "pnpm": ">=11.7.0 <12"
   }
-}
+}

package/src/client/GenuiBlock.module.css

@@ -350,7 +350,6 @@
   line-height: 1.5;
 }
 .table tr:last-child td { border-bottom: none; }
-.table tbody tr { transition: background 0.12s; }
 .table tbody tr:hover { background: var(--dsl-g-hover); }
 /* Numeric columns (auto-detected) right-align with tabular numerals — the
    table's data voice. */
@@ -965,8 +964,7 @@ button.ftNameBtn[aria-expanded] { cursor: pointer; }
 /* "✓ 已触发" confirmation chip: appears next to the button without layout
    shift risk (it inherits the flex row's gap). `backwards`, not `both`: the
    chip's natural (post-animation) style is already visible/no-transform, so
-   pinning the end keyframe would only keep a translateY(0) transform layer
-   alive forever — the exact mechanism behind issues #55/#69. */
+   pinning the end keyframe would only retain an unnecessary transform. */
 .btnSent { animation: genuiPopIn 0.2s ease backwards; }
 
 /* 尊重用户的减弱动效偏好 */

package/src/client/GenuiBlock.tsx

@@ -21,31 +21,32 @@ export const GENUI_ACTION_DEBOUNCE_MS = 300
  * Wrap the harness action callback with the per-action trailing debounce.
  * Absent provider = v1 behavior (components are display-only, callback
  * stays undefined). Pending timers are cleared on unmount so a click that
- * never fired does not leak into the next mount.
+ * never fired does not leak into the next mount. Timers live in one stable
+ * map and read the latest handler through a ref, so provider updates cannot
+ * leave stale callbacks behind.
  */
 function useDebouncedAction(onAction: GenuiBlockProps['onAction'] | undefined): GenuiBlockProps['onAction'] {
-  const pending = useRef<Map<string, ReturnType<typeof setTimeout>> | null>(null)
+  const pending = useRef(new Map<string, ReturnType<typeof setTimeout>>())
+  const actionRef = useRef(onAction)
+  actionRef.current = onAction
+
   useEffect(() => {
     return () => {
-      const timers = pending.current
-      if (timers === null) return
-      for (const timer of timers.values()) clearTimeout(timer)
-      timers.clear()
+      for (const timer of pending.current.values()) clearTimeout(timer)
+      pending.current.clear()
     }
   }, [])
-  return useMemo(() => {
-    if (onAction === undefined) return undefined
-    const timers = new Map<string, ReturnType<typeof setTimeout>>()
-    pending.current = timers
-    return (action: string, payload: Record<string, unknown>): void => {
-      const existing = timers.get(action)
-      if (existing !== undefined) clearTimeout(existing)
-      timers.set(action, setTimeout(() => {
-        timers.delete(action)
-        onAction(action, payload)
-      }, GENUI_ACTION_DEBOUNCE_MS))
-    }
-  }, [onAction])
+
+  const debounced = useCallback((action: string, payload: Record<string, unknown>): void => {
+    const existing = pending.current.get(action)
+    if (existing !== undefined) clearTimeout(existing)
+    pending.current.set(action, setTimeout(() => {
+      pending.current.delete(action)
+      actionRef.current?.(action, payload)
+    }, GENUI_ACTION_DEBOUNCE_MS))
+  }, [])
+
+  return onAction === undefined ? undefined : debounced
 }
 
 /**
@@ -66,11 +67,11 @@ function specEquivalent(a: GenuiSpec, b: GenuiSpec): boolean {
   return JSON.stringify(a) === JSON.stringify(b)
 }
 
-/**
- * Render a GenUI spec as an inline block. Falls back to nothing when the spec
- * carries no items (the fence renderer already refused non-specs before us).
- */
-export const GenuiBlock = memo(function GenuiBlock({ spec, stateKey }: GenuiBlockProps) {
+/** Stateful implementation. Its mount lifetime is the interaction-state
+ * lifetime: useState seeds durable data exactly once, and every later save
+ * belongs to the same stateKey. The exported shell below owns the React key
+ * that enforces this invariant for every caller. */
+function GenuiBlockInstance({ spec, stateKey }: GenuiBlockProps) {
   const gap = spec.gap ?? 16
   const onAction = useDebouncedAction(useGenuiAction())
   // v2.5/v2.6 answers registry: grouped radios record selections + question
@@ -178,4 +179,16 @@ export const GenuiBlock = memo(function GenuiBlock({ spec, stateKey }: GenuiBloc
       </div>
     </div>
   )
+}
+
+/**
+ * Render a GenUI spec as an inline block. `stateKey` is also the durable
+ * component identity: changing it remounts the stateful implementation so
+ * state loaded for one block can never leak into or be saved under another
+ * key. Identity-less streaming renders deliberately share one stable
+ * volatile instance, preserving local interaction state as the spec grows.
+ */
+export const GenuiBlock = memo(function GenuiBlock(props: GenuiBlockProps) {
+  const instanceKey = props.stateKey === undefined ? 'volatile' : `durable:${props.stateKey}`
+  return <GenuiBlockInstance key={instanceKey} {...props} />
 }, (prev, next) => prev.stateKey === next.stateKey && specEquivalent(prev.spec, next.spec))

package/src/client/PlotBlock.tsx

@@ -194,29 +194,44 @@ export const PlotBlock = memo(function PlotBlock({
 
   useEffect(() => {
     if (!playing || animParam === null) return
-    const from = params[`${animParam.si}:${animParam.param.name}`] ?? animParam.param.value
+    const key = `${animParam.si}:${animParam.param.name}`
+    let cycleFrom = params[key] ?? animParam.param.value
     const to = animParam.param.animateTo!
-    const duration = animParam.param.durationMs ?? 4000
-    const start = performance.now()
+    const duration = Math.max(0, animParam.param.durationMs ?? 4000)
+    let cycleStart = performance.now()
     const tick = (now: number): void => {
-      const t = Math.min(1, (now - start) / duration)
+      const t = duration === 0 ? 1 : Math.min(1, Math.max(0, (now - cycleStart) / duration))
       const eased = 1 - Math.pow(1 - t, 3) // easeOutCubic
-      const value = from + (to - from) * eased
-      setParams(prev => ({ ...prev, [`${animParam.si}:${animParam.param.name}`]: value }))
+      const value = cycleFrom + (to - cycleFrom) * eased
+      setParams(prev => ({ ...prev, [key]: value }))
       setAnimProgress(t)
       if (t < 1) {
         animRef.current = requestAnimationFrame(tick)
       } else if (animParam.param.loop === true) {
-        setParams(prev => ({ ...prev, [`${animParam.si}:${animParam.param.name}`]: animParam.param.value }))
+        cycleFrom = animParam.param.value
+        cycleStart = now
+        setParams(prev => ({ ...prev, [key]: cycleFrom }))
         setAnimProgress(0)
-        animRef.current = requestAnimationFrame(() => setPlaying(p => p))
+        animRef.current = requestAnimationFrame(tick)
       } else {
+        animRef.current = null
         setPlaying(false)
       }
     }
     animRef.current = requestAnimationFrame(tick)
-    return () => { if (animRef.current !== null) cancelAnimationFrame(animRef.current) }
-  }, [playing, animParam?.si, animParam?.param.name, animParam?.param.animateTo])
+    return () => {
+      if (animRef.current !== null) cancelAnimationFrame(animRef.current)
+      animRef.current = null
+    }
+  }, [
+    playing,
+    animParam?.si,
+    animParam?.param.name,
+    animParam?.param.value,
+    animParam?.param.animateTo,
+    animParam?.param.durationMs,
+    animParam?.param.loop,
+  ])
 
   const xMin = view.xMin
   const xMax = view.xMax

package/src/client/blocks/advanced.tsx

@@ -121,8 +121,13 @@ export function TabsNode({ tabs, onAction, depth = 0, answers }: {
   const [active, setActive] = useState(0)
   const uid = useId()
   const list = tabs.tabs.slice(0, GENUI_LIMITS.maxTabs)
-  const current = list[active]
+  const safeActive = list.length === 0 ? 0 : Math.min(active, list.length - 1)
+  const current = list[safeActive]
+  useEffect(() => {
+    if (safeActive !== active) setActive(safeActive)
+  }, [active, safeActive])
   const move = (next: number): void => {
+    if (list.length === 0) return
     const n = (next + list.length) % list.length
     setActive(n)
     document.getElementById(`${uid}-tab-${n}`)?.focus()
@@ -134,8 +139,8 @@ export function TabsNode({ tabs, onAction, depth = 0, answers }: {
         role="tablist"
         aria-orientation="horizontal"
         onKeyDown={e => {
-          if (e.key === 'ArrowRight') { e.preventDefault(); move(active + 1) }
-          else if (e.key === 'ArrowLeft') { e.preventDefault(); move(active - 1) }
+          if (e.key === 'ArrowRight') { e.preventDefault(); move(safeActive + 1) }
+          else if (e.key === 'ArrowLeft') { e.preventDefault(); move(safeActive - 1) }
           else if (e.key === 'Home') { e.preventDefault(); move(0) }
           else if (e.key === 'End') { e.preventDefault(); move(list.length - 1) }
         }}
@@ -146,10 +151,10 @@ export function TabsNode({ tabs, onAction, depth = 0, answers }: {
             id={`${uid}-tab-${i}`}
             type="button"
             role="tab"
-            aria-selected={i === active}
+            aria-selected={i === safeActive}
             aria-controls={`${uid}-panel-${i}`}
-            tabIndex={i === active ? 0 : -1}
-            className={`${css.tab} ${i === active ? css.tabActive : ''}`}
+            tabIndex={i === safeActive ? 0 : -1}
+            className={`${css.tab} ${i === safeActive ? css.tabActive : ''}`}
             onClick={() => setActive(i)}
           >
             {tab.label}
@@ -157,7 +162,7 @@ export function TabsNode({ tabs, onAction, depth = 0, answers }: {
         ))}
       </div>
       {current !== undefined && (
-        <div className={css.col} role="tabpanel" id={`${uid}-panel-${active}`} aria-labelledby={`${uid}-tab-${active}`}>
+        <div className={css.col} role="tabpanel" id={`${uid}-panel-${safeActive}`} aria-labelledby={`${uid}-tab-${safeActive}`}>
           {current.items.map((c, i) => renderNode(c, i, onAction, depth + 1, answers))}
         </div>
       )}
@@ -264,26 +269,32 @@ export const CopyNode = memo(function CopyNode({ node }: { node: GenuiCopy }) {
   )
 })
 
+type MermaidRenderState =
+  | { status: 'loading' }
+  | { status: 'ready'; html: string }
+  | { status: 'error' }
+
 /** Mermaid: lazily loaded diagram renderer. */
 export const MermaidNode = memo(function MermaidNode({ node }: { node: GenuiMermaid }) {
-  const [html, setHtml] = useState<string | null>(null)
-  const [failed, setFailed] = useState(false)
+  const [state, setState] = useState<MermaidRenderState>({ status: 'loading' })
   const code = node.code.slice(0, GENUI_LIMITS.maxMermaid)
   useEffect(() => {
     let alive = true
-    void import('../mermaid-lazy.ts').then(async m => {
+    setState({ status: 'loading' })
+    void (async () => {
       try {
+        const m = await import('../mermaid-lazy.ts')
         const svg = await m.renderMermaid(code)
-        if (alive) setHtml(svg)
+        if (alive) setState({ status: 'ready', html: svg })
       } catch {
-        if (alive) setFailed(true)
+        if (alive) setState({ status: 'error' })
       }
-    })
+    })()
     return () => { alive = false }
   }, [code])
-  if (failed) return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidErr}>图语法有误，已降级显示源码</div></div>
-  if (html === null) return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidHint}>渲染中…</div></div>
-  return <div className={css.mermaid} dangerouslySetInnerHTML={{ __html: html }} data-genui-mermaid />
+  if (state.status === 'error') return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidErr}>图语法有误，已降级显示源码</div></div>
+  if (state.status === 'loading') return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidHint}>渲染中…</div></div>
+  return <div className={css.mermaid} dangerouslySetInnerHTML={{ __html: state.html }} data-genui-mermaid />
 })
 
 /** Scene3D: three.js WebGL canvas, lazily imported. */
@@ -346,7 +357,6 @@ export const TimelineNode = memo(function TimelineNode({ node }: { node: GenuiTi
  * — click a dir to fold/unfold, default fully open. Zero model round trip. */
 export const FileTreeNode = memo(function FileTreeNode({ node }: { node: GenuiFileTree }) {
   const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(new Set())
-  const pathKey = (depth: number, i: number): string => `${depth}-${i}`
   const toggle = (k: string): void => {
     setCollapsed(prev => {
       const next = new Set(prev)
@@ -355,27 +365,26 @@ export const FileTreeNode = memo(function FileTreeNode({ node }: { node: GenuiFi
       return next
     })
   }
-  const renderNode = (n: GenuiFileTreeNode, depth: number, i: number): ReactNode => {
+  const renderNode = (n: GenuiFileTreeNode, depth: number, path: string): ReactNode => {
     if (depth > GENUI_LIMITS.maxTreeDepth) return null
     const isDir = n.type === 'dir' || (n.children !== undefined && n.children.length > 0)
-    const k = pathKey(depth, i)
-    const folded = isDir && collapsed.has(k)
+    const folded = isDir && collapsed.has(path)
     return (
-      <div key={k} className={css.ftRow} style={{ paddingLeft: `${depth * 16}px` }}>
+      <div key={path} className={css.ftRow} style={{ paddingLeft: `${depth * 16}px` }}>
         <button
           type="button"
           className={css.ftNameBtn}
           aria-expanded={isDir ? !folded : undefined}
-          onClick={isDir ? () => toggle(k) : undefined}
+          onClick={isDir ? () => toggle(path) : undefined}
         >
           <span className={`${css.ftIcon} ${isDir ? css.ftIconDir : ''}`} aria-hidden>{isDir ? (folded ? '▸' : '▾') : '·'}</span>
           <span className={`${css.ftName} ${isDir ? css.ftDir : ''}`}>{n.name}</span>
         </button>
-        {isDir && !folded && (n.children ?? []).map((c, ci) => renderNode(c, depth + 1, ci))}
+        {isDir && !folded && (n.children ?? []).map((c, ci) => renderNode(c, depth + 1, `${path}/${ci}`))}
       </div>
     )
   }
-  return <div className={css.fileTree}>{node.items.slice(0, GENUI_LIMITS.maxListItems).map((n, i) => renderNode(n, 0, i))}</div>
+  return <div className={css.fileTree}>{node.items.slice(0, GENUI_LIMITS.maxListItems).map((n, i) => renderNode(n, 0, String(i)))}</div>
 })
 
 /** Quiz: a self-contained teaching question. Selecting an option marks it
@@ -464,4 +473,4 @@ export const BreadcrumbNode = memo(function BreadcrumbNode({ node }: { node: Gen
  * names stay independent. The model round-trip takes seconds, so a few
  * hundred ms of trailing delay is imperceptible — and it stops bursts of
  * queued user turns.
- */
+ */

package/src/client/blocks/charts.tsx

@@ -138,7 +138,7 @@ export const BarsNode = memo(function BarsNode({ chart }: { chart: GenuiChart })
     const labels = grouped[0]!.data.map(d => d.label)
     const max = Math.max(...grouped.flatMap(s => s.data.map(d => Number(d.value) || 0)), 1)
     return (
-      <div className={css.chart}>
+      <div className={css.chart} data-genui-chart="bars">
         <div className={css.chartPlot}>
           {[0, 25, 50, 75].map(p => (
             <span key={p} className={p === 0 ? css.baseline : css.gridline} style={{ bottom: `${p}%` }} />
@@ -181,7 +181,7 @@ export const BarsNode = memo(function BarsNode({ chart }: { chart: GenuiChart })
   // and used to collapse the bar entirely.
   const max = Math.max(...data.map(d => Number(d.value) || 0), 1)
   return (
-    <div className={css.chart}>
+    <div className={css.chart} data-genui-chart="bars">
       <div className={css.chartPlot}>
         {[0, 25, 50, 75].map(p => (
           <span key={p} className={p === 0 ? css.baseline : css.gridline} style={{ bottom: `${p}%` }} />
@@ -233,7 +233,7 @@ export const LineChartNode = memo(function LineChartNode({ chart }: { chart: Gen
     return t.toFixed(1)
   }
   return (
-    <div className={css.lineChart}>
+    <div className={css.lineChart} data-genui-chart="line">
       <svg width="100%" viewBox={`0 0 ${W} ${H}`}>
         {ticks.map((t, i) => {
           const y = padT + (1 - (t - min) / span) * (H - padT - padB)
@@ -277,7 +277,7 @@ export const DonutNode = memo(function DonutNode({ chart }: { chart: GenuiChart
   const C = 2 * Math.PI * R
   let offset = 0
   return (
-    <div className={css.donut}>
+    <div className={css.donut} data-genui-chart="donut">
       <svg width="120" height="120" viewBox="0 0 120 120">
         <circle cx="60" cy="60" r={R} fill="none" strokeWidth="14" className={css.donutTrack} />
         {clamped.map((d, i) => {

package/src/client/blocks/image.tsx

@@ -0,0 +1,25 @@
+import { useState, type ReactNode } from 'react'
+import css from '../GenuiBlock.module.css'
+import type { GenuiImage } from '../spec.ts'
+
+/** Native image display; source safety is enforced by repairGenuiSpec/safeMediaSrc. */
+export function ImageNode({ node }: { node: GenuiImage }): ReactNode {
+  const [failed, setFailed] = useState(false)
+
+  return (
+    <figure className={css.media}>
+      {node.alt !== undefined && <figcaption className={css.mediaLabel}>{node.alt}</figcaption>}
+      {failed
+        ? <div className={css.mediaError} role="alert">图片无法加载</div>
+        : <img
+            className={css.mediaPlayer}
+            src={node.src}
+            alt={node.alt ?? '图片'}
+            loading="lazy"
+            decoding="async"
+            style={{ maxHeight: 'min(70vh, 720px)', objectFit: 'contain' }}
+            onError={() => setFailed(true)}
+          />}
+    </figure>
+  )
+}

package/src/client/blocks/render-node.tsx

@@ -20,6 +20,7 @@ import {
   MermaidNode, PlotNode, QuizNode, Scene3DNode, StepsNode, TabsNode, TimelineNode,
 } from './advanced.tsx'
 import { DiagramNode } from './diagram/index.tsx'
+import { ImageNode } from './image.tsx'
 
 import { EChartNode } from '../EChartNode.tsx'
 
@@ -58,6 +59,7 @@ export function renderNode(
   // against the same limit; this is the belt-and-suspenders for direct
   // GenuiBlock use and plugin-registered custom renderers.
   if (depth > GENUI_LIMITS.maxDepth) return null
+
   switch (node.type) {
     case 'text': {
       const size = node.size ?? 'body'
@@ -143,6 +145,7 @@ export function renderNode(
         ? <a key={key} className={css.link} href={href} target="_blank" rel="noopener noreferrer">{node.label}</a>
         : <span key={key} className={css.linkText}>{node.label}</span>
     }
+    case 'image': return <ImageNode key={`${key}:${node.src}`} node={node} />
     case 'audio': return <AudioNode key={`${key}:${node.src}`} node={node} />
     case 'video': return <VideoNode key={`${key}:${node.src}`} node={node} />
     case 'badge': {

package/src/client/blocks/state.ts

@@ -20,6 +20,8 @@ export interface GenuiBlockProps {
    * v2.7: durable-state key (session + slot + content fingerprint). When set,
    * interaction state (radio answers, submit lock, field values) persists to
    * localStorage and restores on refresh / re-render of the same content.
+   * Changing this key also starts a fresh in-memory interaction-state lifetime;
+   * callers only provide stateKey — GenuiBlock owns the matching React identity.
    */
   stateKey?: string | undefined
 }

package/src/client/dom-fence.tsx

@@ -354,6 +354,8 @@ export function installDomFenceRenderer(
   driftWarned = false
   plausibilityWarned = false
   const mounts = new Map<HTMLElement, Mount>()
+  let disposed = false
+  let rafId: number | null = null
 
   const sessionIdOf = (): SessionId | undefined => {
     try {
@@ -513,6 +515,7 @@ export function installDomFenceRenderer(
    * the streaming→settled transition), repair surgery, then take over every
    * new dsh-ui block — settled or still streaming. */
   function sweep(): void {
+    if (disposed) return
     for (const [block, mount] of mounts) {
       if (!block.isConnected) {
         unmountBlock(block)
@@ -605,12 +608,11 @@ export function installDomFenceRenderer(
     }
   }
 
-  let scheduled = false
   const schedule = (): void => {
-    if (scheduled) return
-    scheduled = true
-    requestAnimationFrame(() => {
-      scheduled = false
+    if (disposed || rafId !== null) return
+    rafId = requestAnimationFrame(() => {
+      rafId = null
+      if (disposed) return
       sweep()
     })
   }
@@ -634,8 +636,13 @@ export function installDomFenceRenderer(
   sweep()
 
   return () => {
+    disposed = true
     observer.disconnect()
     window.clearInterval(interval)
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId)
+      rafId = null
+    }
     for (const block of Array.from(mounts.keys())) unmountBlock(block)
   }
 }