@changfenhuang/dsh-genui 0.9.3 → 0.9.7

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

@@ -0,0 +1,48 @@
+/**
+ * achievements.ts — GenUI 探索成就（0.9.5）。
+ *
+ * 轻量本地成就：只统计「使用事件计数」（渲染过的 fence、面板出现、
+ * 交互回传、模板试用），绝不读消息/内容；状态存 localStorage，跨会话
+ * 保留。解锁时进 toast 队列（achievement-toast 消费），面板「成就」
+ * tab 用 dsh-ui 渲染自己的成就页（dogfooding）。
+ *
+ * 设计与 dsh-achievements 的分层快照思路一致，但零宿主改动：埋点全部
+ * 在本包的渲染/交互路径上（GenuiBlock/TemplateDrawer/GenuiPanel）。
+ */
+import type { GenuiSpec } from './spec.ts';
+/** 累积使用计数（成就的输入）。 */
+export interface AchieveState {
+    /** 渲染过的不重复 fence 数。 */
+    fences: number;
+    /** 面板（panel dock）出现过的会话数。 */
+    panels: number;
+    /** 交互组件动作回传次数（去抖后）。 */
+    interactions: number;
+    /** 模板试用次数。 */
+    templates: number;
+    /** 图表节点（chart/plot/echart）出现过的 fence 数。 */
+    charts: number;
+    /** 高级节点（scene3d/mermaid/diagram）出现过的 fence 数。 */
+    advanced: number;
+}
+export declare function emptyState(): AchieveState;
+export interface AchievementDef {
+    id: string;
+    name: string;
+    description: string;
+    /** 解锁前隐藏名称/描述（彩蛋）。 */
+    hidden?: boolean;
+    /** 稀有度。 */
+    rarity: 'common' | 'rare' | 'legendary';
+    check: (s: AchieveState) => boolean;
+}
+export declare const ACHIEVEMENTS: readonly AchievementDef[];
+/** 统计一个 spec 里出现的相关节点类别（与 guard 同口径遍历）。 */
+export declare function countSpecKinds(spec: GenuiSpec): {
+    charts: number;
+    advanced: number;
+};
+/** 生成成就页 spec（dsh-ui 渲染）：进度 stat + 解锁列表 + 稀有度徽标。 */
+export declare function buildAchievementsSpec(state: AchieveState, unlocked: Record<string, number>): GenuiSpec;
+/** 检查给定状态下的新解锁（不受 hidden 限制——规则只管阈值）。 */
+export declare function checkAchievements(state: AchieveState, unlocked: Record<string, number>): AchievementDef[];

package/lib/types/client/blocks/advanced.d.ts

@@ -101,4 +101,4 @@ export declare const BreadcrumbNode: import("react").NamedExoticComponent<{
  * 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/lib/types/client/blocks/image.d.ts

@@ -0,0 +1,6 @@
+import { type ReactNode } from 'react';
+import type { GenuiImage } from '../spec.ts';
+/** Native image display; source safety is enforced by repairGenuiSpec/safeMediaSrc. */
+export declare function ImageNode({ node }: {
+    node: GenuiImage;
+}): ReactNode;

package/lib/types/client/blocks/state.d.ts

@@ -19,6 +19,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/lib/types/client/fence-render.d.ts

@@ -39,6 +39,9 @@ export interface GenuiFenceContext {
  * - Tier-2 completion (missing quotes/brackets): settled renders only —
  *   `context.source` exists exclusively once the message finished, so
  *   streaming halves are never completed early.
+ * - Native chart semantics are checked before repair on every candidate so
+ *   aliases, empty collections, or line/donut series cannot repair into a
+ *   default/blank chart.
  */
 export declare function resolveGenuiSpec(raw: string, context?: GenuiFenceContext): GenuiSpec | null;
 /**

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

@@ -1,9 +1,7 @@
 /**
- * GenUI gallery: one spec exercising every white-listed node type, used as
- * the canonical full-vocabulary sample (tests render it and assert every
- * component family appears; docs and demos reuse it as the "show everything"
- * fence).
+ * GenUI gallery: canonical broad-coverage sample of built-in node types.
+ * Docs, demos, and renderer tests reuse it as the component gallery fence.
  */
 import type { GenuiSpec } from './spec.ts';
-/** A single spec covering all 40 node types in the vocabulary. */
+/** Canonical gallery spec for the built-in GenUI component vocabulary. */
 export declare const gallerySpec: GenuiSpec;

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/panel.d.ts

@@ -4,6 +4,9 @@ import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
 export interface GenuiPanelInjected {
     sessionId: string;
     sendGenuiAction: GenuiActionHandler;
+    /** Template center "try it": insert the template instruction into the
+     *  current composer draft (standard conversation.input.for channel). */
+    insertTemplate: (text: string) => void;
 }
 export type GenuiPanelProps = PropsRuntime<'conversation.input.dock'> & GenuiPanelInjected;
 /**
@@ -12,4 +15,4 @@ export type GenuiPanelProps = PropsRuntime<'conversation.input.dock'> & GenuiPan
  * default so the dock never steals the message flow's scroll room; the
  * header always shows the current panel title.
  */
-export declare function GenuiPanel({ sessionId, sendGenuiAction }: GenuiPanelProps): import("react").JSX.Element | null;
+export declare function GenuiPanel({ sessionId, sendGenuiAction, insertTemplate }: GenuiPanelProps): import("react").JSX.Element | null;

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/client/templates.d.ts

@@ -0,0 +1,22 @@
+/**
+ * templates.ts — GenUI 模板中心数据（0.9.4）。
+ *
+ * 每个模板 = 一段自然语言 `instruction`（试用时插入输入框，模型按 genui
+ * skill 生成对应界面）+ 一份**合法**的 `demo` spec（预览时由 GenuiBlock
+ * 直接渲染，用户先看到效果再决定试用）。字段对齐 spec.ts / guard.ts 的
+ * 实际 schema（tests/templates.spec.ts 用 validateGenuiSpec 逐条校验）。
+ *
+ * 模板即说明书：覆盖布局/数据/图表/交互/测验/高级各能力面。
+ */
+import type { GenuiSpec } from './spec.ts';
+export interface GenuiTemplate {
+    id: string;
+    category: '仪表盘' | '数据' | '流程' | '图表' | '交互' | '测验' | '高级';
+    name: string;
+    description: string;
+    /** 试用时插入输入框的自然语言指令。 */
+    instruction: string;
+    /** 预览用的合法 spec（≤200 节点、嵌套 ≤8 层）。 */
+    demo: GenuiSpec;
+}
+export declare const GENUI_TEMPLATES: readonly GenuiTemplate[];

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.3",
+  "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

@@ -16,8 +16,13 @@
    literals here are only last-resort fallbacks for hosts without the token
    sheets. */
 
-.block {
-  /* ── design tokens (design system v2) ── */
+.block,
+.panel {
+  /* ── design tokens (design system v2) ──
+     Declared on both the inline fence root and the session panel root: the
+     panel header sits OUTSIDE the inner .block, so without the shared
+     declaration its --dsl-g-* references resolved to undefined (the badge
+     gap/padding collapsed to zero). */
   --dsl-g-radius-surface: 12px;
   --dsl-g-radius-control: 8px;
   --dsl-g-radius-pill: 999px;
@@ -46,7 +51,9 @@
   --dsl-g-tint: 8%;
   --dsl-g-tint-strong: 14%;
   --dsl-g-font-mono: var(--ds-font-family-code, ui-monospace, 'SF Mono', monospace);
+}
 
+.block {
   /* Inline in the conversation: no canvas, no border, no padding — the
      components themselves (card/quiz/plot/…) carry the surfaces. A slab
      around every fence was tried and rejected: a lone stat or text node
@@ -343,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. */
@@ -956,8 +962,10 @@ button.ftNameBtn[aria-expanded] { cursor: pointer; }
 }
 
 /* "✓ 已触发" confirmation chip: appears next to the button without layout
-   shift risk (it inherits the flex row's gap). */
-.btnSent { animation: genuiPopIn 0.2s ease both; }
+   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 retain an unnecessary transform. */
+.btnSent { animation: genuiPopIn 0.2s ease backwards; }
 
 /* 尊重用户的减弱动效偏好 */
 @media (prefers-reduced-motion: reduce) {
@@ -1149,9 +1157,16 @@ button.ftNameBtn[aria-expanded] { cursor: pointer; }
 .panel {
   /* Distinct from ordinary inline fences: accent border + badge header so a
      session panel is recognizable at a glance. */
-  margin: 10px 14px 2px;
+  /* Align with the host's composer width axis (same geometry as the TodoDock
+     cards it shares conversation.input.dock with): centered, inset by the
+     side clearance and the dock inset chain, capped at the composer card
+     width. Falls back to safe literals when the host does not define the
+     --dsh-composer-* tokens. */
+  margin: 10px auto 2px;
+  width: calc(100% - var(--dsh-composer-side-clearance, 16px) * 2 - var(--dsh-composer-dock-inset, 8px) * 4);
+  max-width: calc(var(--dsh-composer-card-max-width, 780px) - var(--dsh-composer-dock-inset, 8px) * 4);
   border: 1px solid color-mix(in srgb, var(--dsw-alias-state-business-primary, #4f8ef7) 35%, transparent);
-  border-radius: 14px;
+  border-radius: 12px;
   background: var(--dsw-alias-bg-layer-1, rgba(255, 255, 255, 0.04));
   overflow: hidden;
 }
@@ -1159,12 +1174,18 @@ button.ftNameBtn[aria-expanded] { cursor: pointer; }
 .panelHeader {
   display: flex;
   align-items: center;
+  /* Header/body divider so the panel reads as a card with a title bar, not a
+     slab with text glued to it (user report: "body 缺少内边框"). */
+  border-bottom: 1px solid var(--dsw-alias-border-l1, rgba(127, 127, 127, 0.25));
 }
 
 .panelToggle {
   display: flex;
   align-items: center;
-  gap: var(--dsl-g-gap-sm);
+  /* 10px matches the TodoDock header rhythm (gap: 10px) — the badge and the
+     title no longer collapse together once the shared --dsl-g-gap-sm token
+     reaches this element. */
+  gap: 10px;
   flex: 1 1 auto;
   min-width: 0;
   padding: 9px 14px;
@@ -1211,6 +1232,112 @@ button.ftNameBtn[aria-expanded] { cursor: pointer; }
   opacity: 1;
 }
 
+/* ---- 0.9.4 template center & onboarding ---- */
+.panelTpl {
+  flex: 0 0 auto;
+  height: 26px;
+  margin-right: 4px;
+  padding: 0 10px;
+  display: flex;
+  align-items: center;
+  border: 1px solid var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.12));
+  border-radius: 8px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary, rgba(255, 255, 255, 0.6));
+  font-size: 12px;
+  line-height: 1.5;
+  cursor: pointer;
+  opacity: 0.85;
+}
+
+.panelTpl:hover {
+  background: rgba(255, 255, 255, 0.08);
+  opacity: 1;
+}
+
+.panelTplActive {
+  border-color: var(--dsw-alias-state-business-primary, #4f8ef7);
+  color: var(--dsw-alias-state-business-primary, #4f8ef7);
+}
+
+.panelOnboard .panelHeader {
+  cursor: default;
+}
+
+.panelOnboardText {
+  flex: 1;
+  min-width: 0;
+  padding: 0 8px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-secondary, rgba(255, 255, 255, 0.6));
+}
+
+.panelFlash {
+  padding: 6px 12px;
+  border-top: 1px solid var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.12));
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-state-success-primary, #6ccb5f);
+  background: color-mix(in srgb, var(--dsw-alias-state-success-primary, #6ccb5f) 8%, transparent);
+}
+
+.panelHint {
+  padding: 6px 14px;
+  border-top: 1px solid var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.12));
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-state-business-primary, #4f8ef7);
+  background: color-mix(in srgb, var(--dsw-alias-state-business-primary, #4f8ef7) 8%, transparent);
+}
+
+/* ---- 0.9.5 achievement toasts ---- */
+.achToasts {
+  position: fixed;
+  right: 16px;
+  bottom: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  z-index: 9999;
+  pointer-events: none;
+}
+
+.achToast {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  width: 300px;
+  padding: 10px 12px;
+  border: 1px solid color-mix(in srgb, var(--dsw-alias-state-business-primary, #4f8ef7) 35%, transparent);
+  border-radius: var(--dsl-g-radius-surface, 12px);
+  background: var(--dsw-alias-bg-layer-2, rgba(0, 0, 0, 0.85));
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.25);
+}
+
+.achToastBadge {
+  flex: none;
+  font-size: 18px;
+  line-height: 1.2;
+}
+
+.achToastBody {
+  min-width: 0;
+}
+
+.achToastName {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--dsw-alias-state-business-primary, #4f8ef7);
+}
+
+.achToastDesc {
+  margin-top: 2px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-secondary, rgba(255, 255, 255, 0.6));
+}
+
 .panelBadge {
   flex: none;
   font-size: 11px;
@@ -1235,9 +1362,13 @@ button.ftNameBtn[aria-expanded] { cursor: pointer; }
 }
 
 .panelChevron {
+  /* Same glyph cell + color as the TodoDock header chevron (grid-centered,
+     label-tertiary), so the arrow reads as a host control, not typed text. */
+  display: grid;
+  place-items: center;
+  flex: none;
   margin-left: auto;
-  color: var(--dsw-alias-label-secondary, rgba(255, 255, 255, 0.55));
-  font-size: var(--dsl-g-font-meta);
+  color: var(--dsw-alias-label-tertiary);
 }
 
 .panelBody {

package/src/client/GenuiBlock.tsx

@@ -10,6 +10,7 @@ import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useGenuiAction } from './action-context.ts'
 import css from './GenuiBlock.module.css'
 import { loadBlockState, saveBlockState } from './interaction-store.ts'
+import { recordFence, recordInteraction } from './achievement-store.ts'
 import { renderNode } from './blocks/render-node.tsx'
 import type { AnswersState, GenuiBlockProps, QuestionMeta } from './blocks/state.ts'
 import type { GenuiSpec } from './spec.ts'
@@ -20,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
 }
 
 /**
@@ -65,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
@@ -127,6 +129,15 @@ export const GenuiBlock = memo(function GenuiBlock({ spec, stateKey }: GenuiBloc
     }),
     [answers, fields, secretFields, meta, locked, round, setAnswer, setField, registerSecretField, registerMeta, clear],
   )
+  // Achievement telemetry: every emitted action counts as one interaction
+  // (the debounced emit fires once per real user action).
+  const trackedAction = useMemo(() => {
+    if (onAction === undefined) return undefined
+    return (action: string, payload: Record<string, unknown>): void => {
+      recordInteraction()
+      onAction(action, payload)
+    }
+  }, [onAction])
   // Durable save (debounced 300ms — typing in a field fires per keystroke).
   // Secret field values are stripped before writing: passwords never persist.
   useEffect(() => {
@@ -143,6 +154,11 @@ export const GenuiBlock = memo(function GenuiBlock({ spec, stateKey }: GenuiBloc
     }, 300)
     return () => clearTimeout(timer)
   }, [stateKey, answers, locked, fields, secretFields])
+  // Achievement telemetry (0.9.5): the store dedupes by spec fingerprint, so
+  // streaming re-renders and replays count once per distinct content.
+  useEffect(() => {
+    recordFence(spec)
+  }, [spec])
   return (
     <div className={css.block} data-genui>
       {spec.title !== undefined && <div className={css.banner}>{spec.title}</div>}
@@ -157,10 +173,22 @@ export const GenuiBlock = memo(function GenuiBlock({ spec, stateKey }: GenuiBloc
             className={css.reveal}
             style={{ animationDelay: `${Math.min(i * 90, 720)}ms` }}
           >
-            {renderNode(c, i, onAction, 0, answersState)}
+            {renderNode(c, i, trackedAction, 0, answersState)}
           </div>
         ))}
       </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))