@changfenhuang/dsh-genui 0.9.3 → 0.9.7

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/TemplateDrawer.module.css

@@ -0,0 +1,152 @@
+/* TemplateDrawer: the GenUI template center inside the session panel body.
+   Tokens mirror GenuiBlock.module.css (--dsw-alias-* sheets, fallbacks last). */
+
+.wrap {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 12px 14px;
+  min-height: 0;
+  overflow: auto;
+}
+
+/* ---- achievements tab ---- */
+.achievements {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 0;
+  overflow: auto;
+}
+
+/* ---- category chips ---- */
+.cats {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.cat {
+  padding: 4px 12px;
+  border: 1px solid var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.12));
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary, var(--dsl-g-font-muted-fallback, rgba(255, 255, 255, 0.6)));
+  font-size: 12px;
+  line-height: 1.5;
+  cursor: pointer;
+}
+
+.cat:hover {
+  background: var(--dsw-alias-fill-hover, rgba(255, 255, 255, 0.06));
+}
+
+.catActive {
+  border-color: var(--dsw-alias-state-business-primary, #4f8ef7);
+  color: var(--dsw-alias-state-business-primary, #4f8ef7);
+  background: color-mix(in srgb, var(--dsw-alias-state-business-primary, #4f8ef7) 14%, transparent);
+}
+
+/* ---- template cards ---- */
+.list {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 8px;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 10px 12px;
+  border: 1px solid var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.12));
+  border-radius: var(--dsl-g-radius-surface, 12px);
+  background: var(--dsw-alias-bg-layer-2, rgba(255, 255, 255, 0.04));
+  color: var(--dsw-alias-label-primary);
+  text-align: left;
+  cursor: pointer;
+}
+
+.card:hover {
+  border-color: var(--dsw-alias-border-l2, rgba(255, 255, 255, 0.2));
+}
+
+.cardActive {
+  border-color: var(--dsw-alias-state-business-primary, #4f8ef7);
+}
+
+.cardName {
+  font-size: 13px;
+  font-weight: 600;
+  line-height: 1.5;
+}
+
+.cardMeta {
+  font-size: 11px;
+  color: var(--dsw-alias-label-tertiary, rgba(255, 255, 255, 0.45));
+}
+
+.cardDesc {
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-secondary, rgba(255, 255, 255, 0.6));
+}
+
+/* ---- detail preview ---- */
+.detail {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  border-top: 1px solid var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.12));
+  padding-top: 12px;
+}
+
+.toolbar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.toolbarTitle {
+  flex: 1;
+  min-width: 0;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary);
+}
+
+.try,
+.copy {
+  padding: 5px 12px;
+  border-radius: var(--dsl-g-radius-control, 8px);
+  border: 1px solid transparent;
+  font-size: 12px;
+  line-height: 1.5;
+  cursor: pointer;
+}
+
+.try {
+  border-color: var(--dsw-alias-state-business-primary, #4f8ef7);
+  color: var(--dsw-alias-state-business-primary, #4f8ef7);
+  background: color-mix(in srgb, var(--dsw-alias-state-business-primary, #4f8ef7) 14%, transparent);
+}
+
+.try:hover {
+  background: color-mix(in srgb, var(--dsw-alias-state-business-primary, #4f8ef7) 22%, transparent);
+}
+
+.copy {
+  border-color: var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.12));
+  background: transparent;
+  color: var(--dsw-alias-label-secondary, rgba(255, 255, 255, 0.6));
+}
+
+.preview {
+  border: 1px solid var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.12));
+  border-radius: var(--dsl-g-radius-surface, 12px);
+  padding: 12px;
+  min-height: 0;
+  overflow: auto;
+  background: var(--dsw-alias-bg-layer-1, rgba(0, 0, 0, 0.08));
+}

package/src/client/TemplateDrawer.tsx

@@ -0,0 +1,137 @@
+/**
+ * TemplateDrawer — GenUI 模板中心（0.9.4 新手引导）。
+ *
+ * 分类浏览 → 点击卡片 → 内嵌预览（demo spec 由 GenuiBlock 直接渲染，
+ * dogfooding）+「试用」插入输入框 /「复制指令」。用户先看到效果，
+ * 再决定把指令发给模型——genui 能力说明书。
+ */
+import { useMemo, useRef, useState } from 'react'
+import { GENUI_TEMPLATES, type GenuiTemplate } from './templates.ts'
+import { GenuiBlock } from './GenuiBlock.tsx'
+import { ErrorBoundary } from './ErrorBoundary.tsx'
+import { panelStateKey } from './interaction-store.ts'
+import { buildAchievementsSpec } from './achievements.ts'
+import { getAchievementSnapshot, subscribeAchievements } from './achievement-store.ts'
+import { useSyncExternalStore } from 'react'
+import css from './TemplateDrawer.module.css'
+
+export interface TemplateDrawerProps {
+  /** 试用：把模板指令插入当前输入框草稿。 */
+  onUse: (instruction: string) => void
+  /** 当前面板（模板中心/成就页），由面板 header 按钮控制。 */
+  tab: 'templates' | 'achievements'
+}
+
+const CATEGORIES = ['全部', '仪表盘', '数据', '流程', '图表', '交互', '测验', '高级'] as const
+type Category = (typeof CATEGORIES)[number]
+
+/** Copy to clipboard with a legacy fallback (like GenuiCopy). */
+function copyText(text: string): Promise<void> {
+  if (navigator.clipboard !== undefined) return navigator.clipboard.writeText(text)
+  return new Promise((resolve, reject) => {
+    try {
+      const ta = document.createElement('textarea')
+      ta.value = text
+      ta.style.position = 'fixed'
+      ta.style.opacity = '0'
+      document.body.appendChild(ta)
+      ta.select()
+      document.execCommand('copy')
+      ta.remove()
+      resolve()
+    } catch (error) {
+      reject(error instanceof Error ? error : new Error(String(error)))
+    }
+  })
+}
+
+export function TemplateDrawer({ onUse, tab }: TemplateDrawerProps) {
+  const [category, setCategory] = useState<Category>('全部')
+  const [selected, setSelected] = useState<GenuiTemplate | null>(null)
+  const [copied, setCopied] = useState(false)
+  const timer = useRef(0)
+  // Achievements tab: live state snapshot.
+  const achievements = useSyncExternalStore(subscribeAchievements, () => getAchievementSnapshot())
+  const achievementSpec = useMemo(
+    () => buildAchievementsSpec(achievements.state, achievements.unlocked),
+    [achievements],
+  )
+
+  const items = useMemo(
+    () => (category === '全部' ? [...GENUI_TEMPLATES] : GENUI_TEMPLATES.filter(t => t.category === category)),
+    [category],
+  )
+
+  const copy = async (text: string): Promise<void> => {
+    try {
+      await copyText(text)
+      setCopied(true)
+      window.clearTimeout(timer.current)
+      timer.current = window.setTimeout(() => setCopied(false), 1500)
+    } catch {
+      // Clipboard denied: the instruction stays in the drawer; nothing else
+      // to do — the use flow does not depend on it.
+    }
+  }
+
+  return (
+    <div className={css.wrap} data-genui-templates={tab === 'templates' ? undefined : 'achievements'}>
+      {tab === 'achievements' ? (
+        <div className={css.achievements} data-genui-achievements>
+          <ErrorBoundary label="成就页">
+            <GenuiBlock spec={achievementSpec} stateKey={panelStateKey('genui-achievements', JSON.stringify(achievementSpec))} />
+          </ErrorBoundary>
+        </div>
+      ) : (
+        <>
+          <div className={css.cats} role="tablist" aria-label="模板分类">
+            {CATEGORIES.map(c => (
+              <button
+                key={c}
+                type="button"
+                role="tab"
+                aria-selected={category === c}
+                className={`${css.cat}${category === c ? ` ${css.catActive}` : ''}`}
+                onClick={() => { setCategory(c); setSelected(null) }}
+              >
+                {c}
+              </button>
+            ))}
+          </div>
+          <div className={css.list}>
+            {items.map(tpl => (
+              <button
+                key={tpl.id}
+                type="button"
+                className={`${css.card}${selected?.id === tpl.id ? ` ${css.cardActive}` : ''}`}
+                onClick={() => setSelected(prev => (prev?.id === tpl.id ? null : tpl))}
+              >
+                <span className={css.cardName}>{tpl.name}</span>
+                <span className={css.cardMeta}>{tpl.category}</span>
+                <span className={css.cardDesc}>{tpl.description}</span>
+              </button>
+            ))}
+          </div>
+          {selected !== null && (
+            <div className={css.detail} data-genui-template-preview>
+              <div className={css.toolbar}>
+                <span className={css.toolbarTitle}>{selected.name}</span>
+                <button type="button" className={css.try} onClick={() => onUse(selected.instruction)}>
+                  试用：插入输入框
+                </button>
+                <button type="button" className={css.copy} onClick={() => void copy(selected.instruction)}>
+                  {copied ? '✓ 已复制' : '复制指令'}
+                </button>
+              </div>
+              <div className={css.preview}>
+                <ErrorBoundary label="模板预览">
+                  <GenuiBlock spec={selected.demo} stateKey={panelStateKey('genui-tpl', selected.id)} />
+                </ErrorBoundary>
+              </div>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}

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))
+}