@changfenhuang/dsh-genui 0.9.3 → 0.9.6

package/src/client/achievement-store.ts

@@ -0,0 +1,151 @@
+/**
+ * achievement-store.ts — 成就状态存储与埋点入口（模块级单例）。
+ *
+ * 只存计数与解锁时间戳；绝不含消息/内容。localStorage 持久化，
+ * 订阅接口供 toast 与成就页消费。埋点入口：
+ *  - recordFence(spec)：一次「内容不重复」的界面渲染（按 spec 指纹去重，
+ *    LRU 指纹表跨刷新防重放重复计数）
+ *  - recordPanel()：面板 dock 出现
+ *  - recordInteraction()：组件动作回传（去抖后）
+ *  - recordTemplateUse()：模板中心试用
+ */
+import type { GenuiSpec } from './spec.ts'
+import { ACHIEVEMENTS, checkAchievements, countSpecKinds, emptyState, type AchieveState, type AchievementDef } from './achievements.ts'
+
+const STORE_KEY = 'dsh.genui.achievements'
+const SEEN_KEY = 'dsh.genui.achievements.seen'
+const SEEN_MAX = 200
+
+interface AchieveStore {
+  state: AchieveState
+  unlocked: Record<string, number>
+}
+
+let store: AchieveStore = loadStore()
+const listeners = new Set<() => void>()
+/** 解锁 toast 队列（FIFO；成就页打开时也读）。 */
+let toastQueue: AchievementDef[] = []
+
+function loadStore(): AchieveStore {
+  try {
+    const raw = localStorage.getItem(STORE_KEY)
+    if (raw === null) return { state: emptyState(), unlocked: {} }
+    const parsed = JSON.parse(raw) as Partial<AchieveStore>
+    const state = { ...emptyState(), ...(parsed.state ?? {}) }
+    return { state, unlocked: typeof parsed.unlocked === 'object' && parsed.unlocked !== null ? parsed.unlocked as Record<string, number> : {} }
+  } catch {
+    return { state: emptyState(), unlocked: {} }
+  }
+}
+
+function saveStore(): void {
+  try {
+    localStorage.setItem(STORE_KEY, JSON.stringify(store))
+  } catch {
+    // Quota / privacy-mode failures are non-fatal: achievements still tick
+    // in memory for this page session.
+  }
+}
+
+function readSeen(): string[] {
+  try {
+    const raw = localStorage.getItem(SEEN_KEY)
+    if (raw === null) return []
+    const parsed = JSON.parse(raw) as unknown
+    return Array.isArray(parsed) ? parsed.filter((v): v is string => typeof v === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+function writeSeen(list: string[]): void {
+  try {
+    localStorage.setItem(SEEN_KEY, JSON.stringify(list.slice(0, SEEN_MAX)))
+  } catch {
+    // non-fatal
+  }
+}
+
+function emit(): void {
+  for (const listener of listeners) listener()
+}
+
+/** 应用一次状态更新：持久化 + 检查新解锁（进 toast 队列）+ 通知订阅者。 */
+function applyDelta(patch: Partial<AchieveState>): void {
+  store.state = { ...store.state, ...patch }
+  const fresh = checkAchievements(store.state, store.unlocked)
+  for (const ach of fresh) store.unlocked[ach.id] = Date.now()
+  if (fresh.length > 0) toastQueue.push(...fresh)
+  saveStore()
+  emit()
+}
+
+/** 53-bit string hash (cyrb53-style): dedupe fingerprints are stored as
+ *  hashes, never as the serialized spec itself — localStorage must not
+ *  persist conversation-derived content (table rows, text, …). */
+function fingerprintOf(spec: GenuiSpec): string {
+  const s = JSON.stringify(spec)
+  let h1 = 0xdeadbeef
+  let h2 = 0x41c6ce57
+  for (let i = 0; i < s.length; i++) {
+    const ch = s.charCodeAt(i)
+    h1 = Math.imul(h1 ^ ch, 2654435761)
+    h2 = Math.imul(h2 ^ ch, 1597334677)
+  }
+  return `${(h1 >>> 0).toString(36)}-${(h2 >>> 0).toString(36)}`
+}
+
+/** 记录一次「内容不重复」的 fence 渲染。 */
+export function recordFence(spec: GenuiSpec): void {
+  const fingerprint = fingerprintOf(spec)
+  const seen = readSeen()
+  if (seen.includes(fingerprint)) return
+  writeSeen([fingerprint, ...seen])
+  const kinds = countSpecKinds(spec)
+  applyDelta({
+    fences: store.state.fences + 1,
+    charts: store.state.charts + (kinds.charts > 0 ? 1 : 0),
+    advanced: store.state.advanced + (kinds.advanced > 0 ? 1 : 0),
+  })
+}
+
+/** 记录一次面板 dock 出现（仅会话从无到有时）。 */
+export function recordPanel(): void {
+  applyDelta({ panels: store.state.panels + 1 })
+}
+
+/** 记录一次组件交互动作回传。 */
+export function recordInteraction(): void {
+  applyDelta({ interactions: store.state.interactions + 1 })
+}
+
+/** 记录一次模板试用。 */
+export function recordTemplateUse(): void {
+  applyDelta({ templates: store.state.templates + 1 })
+}
+
+/** 当前状态快照（订阅者读取）。 */
+export function getAchievementSnapshot(): { state: AchieveState, unlocked: Record<string, number> } {
+  return store
+}
+
+/** 取走新解锁（toast 消费；一次性）。 */
+export function consumeUnlocks(): AchievementDef[] {
+  const queue = toastQueue
+  toastQueue = []
+  return queue
+}
+
+/** 订阅状态变化（toast 与成就页）。 */
+export function subscribeAchievements(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}
+
+/** 成就页 spec 数据源（面板内渲染用）。 */
+export function achievementCount(): { total: number, unlocked: number } {
+  return {
+    total: ACHIEVEMENTS.length,
+    unlocked: ACHIEVEMENTS.filter(a => store.unlocked[a.id] !== undefined).length,
+  }
+}

package/src/client/achievement-toast.tsx

@@ -0,0 +1,68 @@
+/**
+ * achievement-toast.tsx — 解锁 toast 栈（右下角，3.6s 自动消退）。
+ *
+ * 独立 React root（document.body 级）：面板/inline fence 任一解锁都会
+ * 弹——不依赖面板存在。消费 achievement-store 的新解锁队列。
+ */
+import { createElement, useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import { createRoot } from 'react-dom/client'
+import { consumeUnlocks, subscribeAchievements } from './achievement-store.ts'
+import type { AchievementDef } from './achievements.ts'
+import css from './GenuiBlock.module.css'
+
+interface ToastItem {
+  key: number
+  ach: AchievementDef
+}
+
+let toastKey = 0
+
+/** 底部固定栈：显示队列中的最后一个（FIFO 展开为纵向栈）。 */
+function AchievementToasts() {
+  const [, force] = useSyncExternalStore(subscribeAchievements, () => '')
+  const [items, setItems] = useState<ToastItem[]>([])
+  const timers = useRef<Map<number, number>>(new Map())
+
+  useEffect(() => {
+    const queue = consumeUnlocks()
+    if (queue.length === 0) return
+    const next: ToastItem[] = queue.map(ach => ({ key: ++toastKey, ach }))
+    setItems(prev => [...prev, ...next])
+    for (const item of next) {
+      const t = window.setTimeout(() => {
+        setItems(prev => prev.filter(i => i.key !== item.key))
+        timers.current.delete(item.key)
+      }, 3600)
+      timers.current.set(item.key, t)
+    }
+  }, [force])
+
+  useEffect(() => () => {
+    for (const t of timers.current.values()) window.clearTimeout(t)
+  }, [])
+
+  if (items.length === 0) return null
+  return createElement('div', { className: css.achToasts, 'data-genui-achievement-toasts': true },
+    items.map(item => createElement('div', { key: item.key, className: css.achToast },
+      createElement('span', { className: css.achToastBadge, 'aria-hidden': true }, '🏆'),
+      createElement('div', { className: css.achToastBody },
+        createElement('div', { className: css.achToastName }, `成就解锁：${item.ach.name}`),
+        createElement('div', { className: css.achToastDesc }, item.ach.description),
+      ),
+    )),
+  )
+}
+
+/** 挂载 toast 栈（apply 调用；返回卸载函数）。 */
+export function mountAchievementToasts(): () => void {
+  if (typeof document === 'undefined') return () => {}
+  const host = document.createElement('div')
+  host.dataset.dshGenuiAchievements = '1'
+  document.body.appendChild(host)
+  const root = createRoot(host)
+  root.render(createElement(AchievementToasts))
+  return () => {
+    root.unmount()
+    host.remove()
+  }
+}

package/src/client/achievements.ts

@@ -0,0 +1,111 @@
+/**
+ * achievements.ts — GenUI 探索成就（0.9.5）。
+ *
+ * 轻量本地成就：只统计「使用事件计数」（渲染过的 fence、面板出现、
+ * 交互回传、模板试用），绝不读消息/内容；状态存 localStorage，跨会话
+ * 保留。解锁时进 toast 队列（achievement-toast 消费），面板「成就」
+ * tab 用 dsh-ui 渲染自己的成就页（dogfooding）。
+ *
+ * 设计与 dsh-achievements 的分层快照思路一致，但零宿主改动：埋点全部
+ * 在本包的渲染/交互路径上（GenuiBlock/TemplateDrawer/GenuiPanel）。
+ */
+import type { GenuiSpec, GenuiNode } 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 function emptyState(): AchieveState {
+  return { fences: 0, panels: 0, interactions: 0, templates: 0, charts: 0, advanced: 0 }
+}
+
+export interface AchievementDef {
+  id: string
+  name: string
+  description: string
+  /** 解锁前隐藏名称/描述（彩蛋）。 */
+  hidden?: boolean
+  /** 稀有度。 */
+  rarity: 'common' | 'rare' | 'legendary'
+  check: (s: AchieveState) => boolean
+}
+
+const fences = (n: number) => (s: AchieveState): boolean => s.fences >= n
+
+export const ACHIEVEMENTS: readonly AchievementDef[] = [
+  { id: 'first-fence', name: '初次相见', description: '渲染了第一块 GenUI 界面。', rarity: 'common', check: fences(1) },
+  { id: 'fence-5', name: '渐入佳境', description: '累计渲染 5 个界面。', rarity: 'common', check: fences(5) },
+  { id: 'fence-25', name: '界面编织者', description: '累计渲染 25 个界面。', rarity: 'rare', check: fences(25) },
+  { id: 'fence-50', name: '蓝图之魂', description: '累计渲染 50 个界面——你是 GenUI 的老朋友了。', rarity: 'legendary', hidden: true, check: fences(50) },
+  { id: 'first-interaction', name: '按钮按得动', description: '触发了一次组件交互（动作回传）。', rarity: 'common', check: s => s.interactions >= 1 },
+  { id: 'interaction-10', name: '小小操纵者', description: '累计触发 10 次组件交互。', rarity: 'rare', check: s => s.interactions >= 10 },
+  { id: 'first-panel', name: '钉在墙上', description: '第一次把内容钉进了会话面板。', rarity: 'common', check: s => s.panels >= 1 },
+  { id: 'panel-5', name: '面板管家', description: '5 个会话都用过面板。', rarity: 'rare', check: s => s.panels >= 5 },
+  { id: 'first-chart', name: '图表爱好者', description: '渲染了第一张图表（chart/plot/echart）。', rarity: 'common', check: s => s.charts >= 1 },
+  { id: 'chart-10', name: '数据可视化人', description: '10 个界面里出现过图表。', rarity: 'rare', check: s => s.charts >= 10 },
+  { id: 'first-advanced', name: '高级玩家', description: '用上了 3D/图表引擎/架构图之一。', rarity: 'rare', check: s => s.advanced >= 1 },
+  { id: 'template-1', name: '模板学员', description: '从模板中心试用了一个模板。', rarity: 'common', check: s => s.templates >= 1 },
+]
+
+/** 统计一个 spec 里出现的相关节点类别（与 guard 同口径遍历）。 */
+export function countSpecKinds(spec: GenuiSpec): { charts: number, advanced: number } {
+  let charts = 0
+  let advanced = 0
+  const walk = (list: unknown): void => {
+    if (!Array.isArray(list)) return
+    for (const item of list) {
+      if (typeof item !== 'object' || item === null) continue
+      const v = item as Record<string, unknown>
+      const type = v.type
+      if (type === 'chart' || type === 'plot' || type === 'echart') charts += 1
+      if (type === 'scene3d' || type === 'mermaid' || type === 'diagram') advanced += 1
+      // 容器与列表项递归
+      if (Array.isArray(v.items)) walk(v.items as unknown[])
+      if (Array.isArray((v as { tabs?: unknown }).tabs)) {
+        for (const tab of (v as { tabs: Array<{ items?: unknown }> }).tabs) walk(tab.items)
+      }
+    }
+  }
+  walk(spec.items)
+  return { charts, advanced }
+}
+
+/** 生成成就页 spec（dsh-ui 渲染）：进度 stat + 解锁列表 + 稀有度徽标。 */
+export function buildAchievementsSpec(state: AchieveState, unlocked: Record<string, number>): GenuiSpec {
+  const total = ACHIEVEMENTS.length
+  const unlockedCount = ACHIEVEMENTS.filter(a => unlocked[a.id] !== undefined).length
+  const items: GenuiNode[] = [
+    { type: 'grid', cols: 3, items: [
+      { type: 'stat', label: '已解锁', value: `${unlockedCount} / ${total}` },
+      { type: 'stat', label: '渲染界面', value: String(state.fences) },
+      { type: 'stat', label: '组件交互', value: String(state.interactions) },
+    ] },
+    { type: 'progress', label: '探索进度', value: Math.round(unlockedCount / total * 100), valueLabel: `${Math.round(unlockedCount / total * 100)}%` },
+    { type: 'list', items: ACHIEVEMENTS.map(a => ({
+      type: 'row',
+      items: [
+        { type: 'badge', label: a.rarity === 'legendary' ? '传说' : a.rarity === 'rare' ? '稀有' : '普通', tone: unlocked[a.id] !== undefined ? 'success' : 'warn' },
+        { type: 'text', size: 'body', content: a.hidden && unlocked[a.id] === undefined ? '？' : a.name },
+        { type: 'text', size: 'muted', content: a.hidden && unlocked[a.id] === undefined ? '继续探索以揭示' : a.description },
+      ],
+    })) },
+  ]
+  return { title: 'GenUI 探索成就', items }
+}
+
+/** 检查给定状态下的新解锁（不受 hidden 限制——规则只管阈值）。 */
+export function checkAchievements(state: AchieveState, unlocked: Record<string, number>): AchievementDef[] {
+  return ACHIEVEMENTS.filter(a => unlocked[a.id] === undefined && a.check(state))
+}

package/src/client/index.tsx

@@ -32,6 +32,7 @@ import { renderGenuiFence, type GenuiFenceContext } from './fence-render.tsx'
 import { createPanelSlashSource } from './panel-command.ts'
 import { GenuiPanel, type GenuiPanelInjected } from './panel.tsx'
 import { GenuiToolView } from './toolview.tsx'
+import { mountAchievementToasts } from './achievement-toast.tsx'
 import type { InputTriggerServiceContract } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
 import { assetUrl } from './asset-loader.ts'
 
@@ -77,6 +78,16 @@ function panelActionSend(ctx: Context, sessionId: SessionId): GenuiPanelInjected
         console.warn(`[genui] 面板动作 "${action}" 发送失败（session ${sessionId}）：`, err instanceof Error ? err.message : String(err))
       })
     },
+    insertTemplate: (text) => {
+      // Same insert channel as dsh-memory's organizeMemory: the standard
+      // conversation.input.for(scope).setDraft — templates land in the
+      // composer draft, not a queued message, so the user can edit before
+      // sending.
+      const input = (conversation as unknown as {
+        input?: { for?(actx: unknown): { setDraft(text: string): void } | undefined }
+      } | undefined)?.input?.for?.(scoped)
+      input?.setDraft(text)
+    },
   }
 }
 
@@ -130,6 +141,8 @@ export function apply(ctx: Context): () => void {
   // a session usually hits a warm cache instead of paying the fetch on first
   // use. Never blocks first paint; the loader still handles a miss.
   prefetchGenuiAssets()
+  // Achievement toasts (0.9.5): a body-level stack independent of the panel.
+  disposers.push(mountAchievementToasts())
   // Keyed toolview: the harness dispatches 'tool.call.toolview' by wire tool
   // name; registering under 'render_ui' gives the tool's result card the
   // GenUI renderer (reading the repaired spec from result meta). The toolview

package/src/client/panel.tsx

@@ -25,11 +25,13 @@
  */
 import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react'
 import type {} from '@deepseek-ai/dsh-client-runtime/client'
+import { IconChevronDownOutline14, IconChevronUpOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import { GenuiActionContext, type GenuiActionHandler } from './action-context.ts'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import { GenuiBlock } from './GenuiBlock.tsx'
 import { ErrorBoundary } from './ErrorBoundary.tsx'
 import { panelStateKey } from './interaction-store.ts'
+import { TemplateDrawer } from './TemplateDrawer.tsx'
 import { clearSessionPanel, getPanelExpandToken, getPanelSpec, setLocalPanel, subscribePanel, subscribePanelExpand } from './panel-store.ts'
 import css from './GenuiBlock.module.css'
 
@@ -37,10 +39,20 @@ import css from './GenuiBlock.module.css'
 const PANEL_HEIGHT_MIN = 120
 const PANEL_HEIGHT_MAX = 600
 
+/** First-panel hint dismissal flag (module-level localStorage key):
+ *  shown once beside the first rendered spec, never again. */
+const ONBOARD_KEY = 'dsh.genui.panel-hint'
+
+// Achievement telemetry re-exports (already injected at apply).
+import { recordPanel, recordTemplateUse } from './achievement-store.ts'
+
 /** Injection face built per session in apply (scoped conversation send). */
 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
@@ -51,7 +63,7 @@ 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 function GenuiPanel({ sessionId, sendGenuiAction }: GenuiPanelProps) {
+export function GenuiPanel({ sessionId, sendGenuiAction, insertTemplate }: GenuiPanelProps) {
   const spec = useSyncExternalStore(subscribePanel, () => getPanelSpec(sessionId))
   const expandToken = useSyncExternalStore(subscribePanelExpand, () => getPanelExpandToken(sessionId))
   const [collapsed, setCollapsed] = useState(true)
@@ -60,6 +72,39 @@ export function GenuiPanel({ sessionId, sendGenuiAction }: GenuiPanelProps) {
   const [resizing, setResizing] = useState(false)
   const dragStart = useRef<{ y: number; height: number } | null>(null)
   const bodyRef = useRef<HTMLDivElement | null>(null)
+  // Template center (0.9.4) + achievements (0.9.5): the drawer host —
+  // null = closed, 'templates' | 'achievements' = open on that tab.
+  const [drawer, setDrawer] = useState<null | 'templates' | 'achievements'>(null)
+  const [flash, setFlash] = useState<string | null>(null)
+  const flashTimer = useRef(0)
+  const hasSpec = spec !== null && spec.items.length > 0
+  // First-panel hint: shown once beside the first rendered spec (never on the
+  // hero — the host composer hero flex-compresses dock items with no content,
+  // and the template button is a permanent header entry anyway).
+  const [hint, setHint] = useState<boolean>(() => {
+    try {
+      return hasSpec && localStorage.getItem(ONBOARD_KEY) !== '1'
+    } catch {
+      return hasSpec
+    }
+  })
+  useEffect(() => {
+    if (!hint) return
+    const t = window.setTimeout(() => {
+      try {
+        localStorage.setItem(ONBOARD_KEY, '1')
+      } catch {
+        // Private-mode storage failures are non-fatal: the hint may reappear.
+      }
+      setHint(false)
+    }, 6000)
+    return () => window.clearTimeout(t)
+  }, [hint])
+  // Achievement telemetry (0.9.5): one panel appearance per dock mount.
+  useEffect(() => {
+    if (!hasSpec) return
+    recordPanel()
+  }, [hasSpec])
 
   // Explicit expand requests (the /panel command) open the dock even when the
   // user collapsed it manually: the monotone token guarantees a fresh request
@@ -89,6 +134,9 @@ export function GenuiPanel({ sessionId, sendGenuiAction }: GenuiPanelProps) {
     }
   }, [resizing])
 
+  // Template-center flash timer must not outlive the dock.
+  useEffect(() => () => window.clearTimeout(flashTimer.current), [])
+
   /** Start a vertical resize drag on the panel's top edge. Dragging UP grows
    * the panel (the edge moves toward the message flow); dragging down shrinks
    * it. Pointer capture binds move/up/cancel to the HANDLE, so dragging past
@@ -126,7 +174,14 @@ export function GenuiPanel({ sessionId, sendGenuiAction }: GenuiPanelProps) {
     handle.addEventListener('pointercancel', onUp)
   }, [bodyHeight])
 
-  if (spec === null || spec.items.length === 0) return null
+  if (!hasSpec) return null
+
+  const showFlash = (text: string): void => {
+    setFlash(text)
+    window.clearTimeout(flashTimer.current)
+    flashTimer.current = window.setTimeout(() => setFlash(null), 2500)
+  }
+
   return (
     <div className={css.panel} data-genui-panel>
       {/* Resize grip on the panel's TOP EDGE (above the header): the drag
@@ -149,8 +204,33 @@ export function GenuiPanel({ sessionId, sendGenuiAction }: GenuiPanelProps) {
           onClick={() => setCollapsed(c => !c)}
         >
           <span className={css.panelBadge}>面板</span>
-          <span className={css.panelTitle}>{spec.title ?? 'GenUI 面板'}</span>
-          <span className={css.panelChevron} aria-hidden>{collapsed ? '▸' : '▾'}</span>
+          <span className={css.panelTitle}>{spec?.title ?? (drawer !== null ? 'GenUI 探索' : 'GenUI 面板')}</span>
+          <span className={css.panelChevron} aria-hidden>
+            {/* Host-style glyphs (same icon set as the TodoDock header) instead of typed arrows. */}
+            {collapsed ? <IconChevronUpOutline14 /> : <IconChevronDownOutline14 />}
+          </span>
+        </button>
+        {/* Template center (0.9.4): one button — the discovery surface for
+            new users and a quick-start entry for everyone. */}
+        <button
+          type="button"
+          className={`${css.panelTpl}${drawer === 'templates' ? ` ${css.panelTplActive}` : ''}`}
+          aria-label="模板中心"
+          title="模板中心：预览并试用 GenUI 示例"
+          onClick={() => { setCollapsed(false); setDrawer(d => (d === 'templates' ? null : 'templates')) }}
+        >
+          模板
+        </button>
+        {/* Achievements (0.9.5): the exploration trophies, rendered by GenUI
+            itself (dogfooding). */}
+        <button
+          type="button"
+          className={`${css.panelTpl}${drawer === 'achievements' ? ` ${css.panelTplActive}` : ''}`}
+          aria-label="探索成就"
+          title="探索成就：解锁徽章与进度"
+          onClick={() => { setCollapsed(false); setDrawer(d => (d === 'achievements' ? null : 'achievements')) }}
+        >
+          成就
         </button>
         {/* In-place dismiss (issue #23): the same local override `/panel
             clear` applies — persists to localStorage, notifies subscribers,
@@ -165,6 +245,11 @@ export function GenuiPanel({ sessionId, sendGenuiAction }: GenuiPanelProps) {
           <span aria-hidden>✕</span>
         </button>
       </div>
+      {hint && drawer === null && (
+        <div className={css.panelHint} role="status">
+          💡 这是 GenUI 会话面板：点右上角「模板」可浏览并试用示例
+        </div>
+      )}
       {!collapsed && (
         <div
           ref={bodyRef}
@@ -172,14 +257,28 @@ export function GenuiPanel({ sessionId, sendGenuiAction }: GenuiPanelProps) {
           data-genui-panel-body
           style={bodyHeight === null ? undefined : { height: bodyHeight }}
         >
-          <GenuiActionContext.Provider value={sendGenuiAction}>
-            <ErrorBoundary label="面板">
-              {/* content-fingerprinted: same panel spec re-published restores its state */}
-              <GenuiBlock spec={spec} stateKey={panelStateKey(sessionId, JSON.stringify(spec))} />
-            </ErrorBoundary>
-          </GenuiActionContext.Provider>
+          {drawer !== null ? (
+            <TemplateDrawer
+              tab={drawer}
+              onUse={(text) => {
+                recordTemplateUse()
+                insertTemplate(text)
+                showFlash('指令已插入输入框，发送即可让模型生成')
+              }}
+            />
+          ) : spec !== null ? (
+            <GenuiActionContext.Provider value={sendGenuiAction}>
+              <ErrorBoundary label="面板">
+                {/* content-fingerprinted: same panel spec re-published restores its state */}
+                <GenuiBlock spec={spec} stateKey={panelStateKey(sessionId, JSON.stringify(spec))} />
+              </ErrorBoundary>
+            </GenuiActionContext.Provider>
+          ) : null}
         </div>
       )}
+      {flash !== null && (
+        <div className={css.panelFlash} role="status">{flash}</div>
+      )}
     </div>
   )
 }