@changfenhuang/dsh-genui 0.9.1

package/src/client/fence-render.tsx

@@ -0,0 +1,230 @@
+/**
+ * The dsh-ui fence render pipeline, shared by both render channels:
+ *
+ * - **Registry channel** (contract hosts): the host's MarkdownText resolves
+ *   ```dsh-ui fences through the fence-registry extension point and calls
+ *   {@link renderGenuiFence} with a session-scoped context (sessionId + the
+ *   settled source identity). An unrepairable body renders {@link FenceFallback}.
+ * - **DOM channel** (pristine hosts, no extension point): the DOM observer
+ *   (`dom-fence.ts`) finds stock code blocks labelled `dsh-ui` and mounts
+ *   {@link renderResolvedFenceNode} into its own React root, wrapped in the
+ *   plugin-owned action context. An unrepairable body returns `null` so the
+ *   stock code block stays visible.
+ *
+ * Structural types are declared locally on purpose: the context contract is
+ * a data shape, and pristine hosts do not export the host-side type names.
+ */
+import { Fragment, useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type Key, type ReactNode } from 'react'
+import { CodeBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import { ErrorBoundary } from './ErrorBoundary.tsx'
+import { GenuiBlock } from './GenuiBlock.tsx'
+import { repairGenuiSpec } from './guard.ts'
+import { fenceStateKey } from './interaction-store.ts'
+import { parsePartialGenuiSpec } from './parse-partial.ts'
+import { applyPanelOperation, diagnosePanelBudget, type PanelOperationStatus } from './panel-store.ts'
+import type { GenuiSpec } from './spec.ts'
+import { completeFenceJson, describeJsonFailure, isCompleteJson, repairFenceJson } from '../shared/fence-repair.ts'
+
+/** Settled fence source identity (data shape, host-independent). */
+export interface GenuiFenceSource {
+  /** Stable structural id, e.g. `['assistant', seq, block, fence]` or `dom:<anchor>:<i>`. */
+  readonly id: string
+  /** Three-part order: [messageSeq, textBlockIndex, fenceIndex]. */
+  readonly order: readonly [number, number, number]
+}
+
+/** Context a fence renderer receives beside the raw source and React key. */
+export interface GenuiFenceContext {
+  /** Owning session route; absent outside a session-scoped render. */
+  readonly sessionId?: string
+  /** Present only for settled/interrupted renders with a stable identity. */
+  readonly source?: GenuiFenceSource
+}
+
+const FENCE_ERROR_STYLE: CSSProperties = {
+  margin: '0 0 6px',
+  padding: '6px 10px',
+  borderRadius: 6,
+  background: 'rgba(239, 68, 68, 0.14)',
+  border: '1px solid rgba(239, 68, 68, 0.4)',
+  color: '#f87171',
+  fontSize: 12,
+  lineHeight: 1.55,
+  whiteSpace: 'pre-wrap',
+}
+
+/**
+ * Fallback for a ```dsh-ui fence whose body has no finished component yet.
+ * Two very different situations land here and they must not be conflated:
+ *
+ * 1. **Streaming partial** — the reply is still being written and the JSON
+ *    simply is not complete. The host marks the streaming message with
+ *    `[data-streaming]` on the AssistantMarkdown root, which is an ancestor
+ *    of every fence. While that marker is present, a plain code block is the
+ *    correct rendering (partial JSON must never look like an error).
+ *
+ * 2. **Settled defect** — the message is finished but the body still does
+ *    not parse as JSON (a malformed fence like a missing `}`). This used to
+ *    fail silently: the fence degraded to a code block with no hint, and the
+ *    author had no way to know the UI never rendered. Once the streaming
+ *    marker is gone, surface a compact diagnostic with the parse position so
+ *    the defect is visible instead of silent.
+ */
+function FenceFallback({ raw, fenceKey }: { raw: string; fenceKey: Key }) {
+  const ref = useRef<HTMLDivElement | null>(null)
+  const [settled, setSettled] = useState(false)
+  useLayoutEffect(() => {
+    const node = ref.current
+    if (node !== null && node.closest('[data-streaming]') === null) setSettled(true)
+  })
+  const diagnostic = settled && raw.trim() !== '' ? describeJsonFailure(raw) : null
+  return (
+    <div ref={ref}>
+      {diagnostic !== null && (
+        <div style={FENCE_ERROR_STYLE} role="alert">
+          ⚠️ dsh-ui fence JSON 解析失败{diagnostic} —— 围栏保持为代码块；请让模型检查并修复 JSON 后重发。
+        </div>
+      )}
+      <CodeBlock key={fenceKey} code={`${raw}\n`} lang="dsh-ui" />
+    </div>
+  )
+}
+
+/**
+ * Keyed publisher for a settled `panel:true` fence: submits ONE panel
+ * operation from the host-provided stable source (id + order), in an
+ * effect — never inside the render function. StrictMode's duplicate effects
+ * are absorbed by the operation map's per-source dedup, so the panel folds
+ * and notifies exactly once per source. Renders nothing.
+ */
+function FencePanelPublisher({ sessionId, sourceId, order, spec }: {
+  sessionId: string
+  sourceId: string
+  order: readonly [number, number, number]
+  spec: GenuiSpec
+}) {
+  useEffect(() => {
+    const status: PanelOperationStatus = applyPanelOperation(sessionId, {
+      sourceId,
+      order,
+      mode: spec.append === true ? 'append' : 'replace',
+      spec,
+    })
+    if (status === 'overflow') diagnosePanelBudget(sessionId, sourceId)
+  }, [sessionId, sourceId, order, spec])
+  return null
+}
+
+/**
+ * Resolve a raw fence body to a guarded spec.
+ *
+ * - Tier-1 repair (quote escape + trailing commas): safe at any time —
+ *   adopted only when the whole body parses, so a still-growing streaming
+ *   half keeps falling back to the code block, never flashing a banner.
+ * - Tier-2 completion (missing quotes/brackets): settled renders only —
+ *   `context.source` exists exclusively once the message finished, so
+ *   streaming halves are never completed early.
+ */
+export function resolveGenuiSpec(raw: string, context?: GenuiFenceContext): GenuiSpec | null {
+  const parsed = parsePartialGenuiSpec(raw)
+  let spec = parsed === null ? null : repairGenuiSpec(parsed)
+  if (spec === null) {
+    const repaired = repairFenceJson(raw)
+    if (repaired !== null) {
+      const reparsed = parsePartialGenuiSpec(repaired.text)
+      spec = reparsed === null ? null : repairGenuiSpec(reparsed)
+    }
+    if (spec === null && context?.source !== undefined) {
+      const completed = completeFenceJson(raw)
+      if (completed !== null) {
+        const reparsed = parsePartialGenuiSpec(completed.text)
+        spec = reparsed === null ? null : repairGenuiSpec(reparsed)
+      }
+    }
+  }
+  return spec
+}
+
+/** The inline GenuiBlock tree for a resolved non-panel spec. */
+function renderInlineFence(key: Key, context: GenuiFenceContext | undefined, spec: GenuiSpec): ReactNode {
+  const sessionId = context?.sessionId
+  return (
+    // React key carries the stable source identity when present (atomic
+    // remount at streaming→settled), falling back to the document key.
+    // Repaired specs render SILENTLY: once the UI renders, no amber note
+    // tells the user something was wrong — only an unrecoverable body keeps
+    // the red diagnostic.
+    <ErrorBoundary key={context?.source?.id ?? key} label="该界面">
+      <GenuiBlock
+        spec={spec}
+        // v2.7 durable state: session + stable source + content fingerprint —
+        // replaying the same content restores answers/lock/field values; new
+        // content (换题, edited spec) gets a fresh key. Without a stable
+        // source (streaming / non-conversation surfaces) state is not
+        // persisted.
+        stateKey={sessionId === undefined
+          ? undefined
+          : fenceStateKey(sessionId, context?.source?.id ?? String(key), JSON.stringify(spec))}
+      />
+    </ErrorBoundary>
+  )
+}
+
+/**
+ * The resolved fence render for the DOM channel: `null` when the body is
+ * unrepairable (the stock code block stays visible), otherwise the panel
+ * publisher (`panel:true`; renders nothing in the flow — mounted as an empty
+ * root so the taken-over block is hidden) or the inline GenuiBlock tree.
+ * Shared verbatim by both channels.
+ */
+export function renderResolvedFenceNode(raw: string, key: Key, context?: GenuiFenceContext): ReactNode | null {
+  const spec = resolveGenuiSpec(raw, context)
+  if (spec === null) return null
+  if (spec.panel === true) {
+    // Publish only with a settled stable source — streaming/identity-less
+    // renders keep the panel untouched. Appends additionally gate on a
+    // complete body (a settled-but-malformed append never merges partial
+    // content).
+    if (context !== undefined && context.sessionId !== undefined && context.source !== undefined) {
+      if (spec.append === true && !isCompleteJson(raw)) return <Fragment key={key} />
+      return (
+        <FencePanelPublisher
+          key={key}
+          sessionId={context.sessionId}
+          sourceId={context.source.id}
+          order={context.source.order}
+          spec={spec}
+        />
+      )
+    }
+    return <Fragment key={key} />
+  }
+  return renderInlineFence(key, context, spec)
+}
+
+/**
+ * Registry-channel fence renderer (contract hosts): like the resolved node,
+ * but an unrepairable body renders the fallback code block + settled
+ * diagnostic — the host replaced its own block with our output — and an
+ * unpublishable `panel:true` fence renders `null` (nothing in the flow).
+ */
+export function renderGenuiFence(raw: string, key: Key, context?: GenuiFenceContext): ReactNode {
+  const spec = resolveGenuiSpec(raw, context)
+  if (spec === null) return <FenceFallback key={key} fenceKey={key} raw={raw} />
+  if (spec.panel === true) {
+    if (context !== undefined && context.sessionId !== undefined && context.source !== undefined) {
+      if (spec.append === true && !isCompleteJson(raw)) return null
+      return (
+        <FencePanelPublisher
+          key={key}
+          sessionId={context.sessionId}
+          sourceId={context.source.id}
+          order={context.source.order}
+          spec={spec}
+        />
+      )
+    }
+    return null
+  }
+  return renderInlineFence(key, context, spec)
+}

package/src/client/gallery.ts

@@ -0,0 +1,128 @@
+/**
+ * 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).
+ */
+import type { GenuiSpec } from './spec.ts'
+
+/** A single spec covering all 40 node types in the vocabulary. */
+export const gallerySpec: GenuiSpec = {
+  title: 'GenUI · 组件画廊',
+  gap: 14,
+  items: [
+    { type: 'text', size: 'h1', content: '排版层级' },
+    { type: 'text', size: 'h2', content: '二级标题' },
+    { type: 'text', size: 'h3', content: '三级标题' },
+    { type: 'text', size: 'body', content: '正文：组件白名单渲染，不经过任意 HTML 路径。' },
+    { type: 'text', size: 'muted', content: '弱化文本' },
+    { type: 'text', size: 'caption', content: '说明文字', center: true },
+    { type: 'row', items: [
+      { type: 'badge', label: '成功', tone: 'success' },
+      { type: 'badge', label: '警告', tone: 'warn' },
+      { type: 'badge', label: '危险', tone: 'danger' },
+      { type: 'badge', label: '强调', tone: 'accent', icon: '★' },
+      { type: 'avatar', name: 'Alice' },
+      { type: 'avatar', name: 'Bob', color: '#3d9e8f' },
+      { type: 'link', label: '详情链接' },
+    ], wrap: true },
+    { type: 'divider' },
+    { type: 'audio', src: '/demo-audio.mp3', alt: '音频播放器演示' },
+    { type: 'video', src: '/demo-video.mp4', alt: '视频播放器演示', poster: '/demo-video.jpg', aspectRatio: '16:9' },
+    { type: 'grid', cols: 3, items: [
+      { type: 'stat', label: 'CPU', value: '42%', delta: '+3.1%' },
+      { type: 'stat', label: '内存', value: '6.8 GB', delta: '-1.2%' },
+      { type: 'stat', label: '请求数', value: '128.4k' },
+    ] },
+    { type: 'progress', label: '训练进度', value: 72, valueLabel: '72%' },
+    { type: 'card', title: '性能指标', items: [
+      // 表头可点击排序：数值感知（千分位 / k / 万 / % 都能正确比较），
+      // 数值列自动右对齐。
+      { type: 'table', columns: ['指标', 'Q1', 'Q2', 'Q3'], rows: [
+        ['延迟', 92, 87, 81], ['吞吐', '1.2k', '1.4k', '1.6k'], ['错误率', '0.3%', '0.2%', '0.1%'],
+        ['营收', '3.5万', '4.1万', '5.2万'], ['注册', '1,234', '2,345', '3,456'],
+      ] },
+      { type: 'keyvalue', pairs: [
+        { key: '版本', value: 'v0.1.0' }, { key: '环境', value: 'production' }, { key: '区域', value: 'cn-east' },
+      ] },
+    ] },
+    { type: 'list', items: [
+      { title: '标题项', desc: '带描述的列表项' },
+      '纯文本列表项',
+      { title: '另一个标题' },
+    ] },
+    { type: 'chart', kind: 'bars', data: [
+      { label: '一', value: 10 }, { label: '二', value: 20 }, { label: '三', value: 15 },
+    ] },
+    { type: 'chart', kind: 'line', data: [
+      { label: '周一', value: 8 }, { label: '周二', value: 12 }, { label: '周三', value: 9 },
+    ] },
+    { type: 'chart', kind: 'donut', data: [
+      { label: 'A', value: 30 }, { label: 'B', value: 70 },
+    ] },
+    { type: 'chart', data: [], series: [
+      { label: '本月', data: [{ label: 'Q1', value: 3 }, { label: 'Q2', value: 5 }] },
+      { label: '上月', data: [{ label: 'Q1', value: 2 }, { label: 'Q2', value: 4 }] },
+    ] },
+    { type: 'tabs', tabs: [
+      { label: '概览', items: [{ type: 'text', content: '标签页一的内容' }] },
+      { label: '明细', items: [{ type: 'list', items: ['明细 A', '明细 B'] }] },
+      { label: '图表', items: [{ type: 'chart', kind: 'donut', data: [{ label: 'X', value: 40 }, { label: 'Y', value: 60 }] }] },
+    ] },
+    { type: 'col', gap: 8, items: [
+      { type: 'button', label: '主按钮', tone: 'primary' },
+      { type: 'button', label: '危险', tone: 'danger', small: true },
+      { type: 'button', label: '成功', tone: 'success' },
+      { type: 'button', label: '幽灵', tone: 'ghost', icon: '↗' },
+    ] },
+    { type: 'row', items: [
+      { type: 'input', label: '名称', placeholder: '输入…' },
+      { type: 'select', label: '环境', options: ['dev', 'staging', 'production'] },
+    ], wrap: true },
+    { type: 'row', items: [
+      { type: 'checkbox', label: '自动保存', checked: true },
+      { type: 'switch', label: '通知', checked: true },
+      { type: 'radio', label: '主题', options: ['浅色', '深色', '跟随系统'] },
+    ], wrap: true },
+    { type: 'textarea', label: '备注', placeholder: '多行输入…', rows: 3 },
+    { type: 'accordion', items: [
+      { title: '第一项', items: [{ type: 'json', value: { ok: true, count: 3 } }] },
+      { title: '第二项', items: [{ type: 'code', lang: 'ts', code: 'export const x = 1' }] },
+    ] },
+    { type: 'copy', label: '复制令牌', text: 'sk-1234567890' },
+    { type: 'plot', title: '波动叠加', xMin: -6.28, xMax: 6.28, series: [
+      { expr: 'sin(x)', label: 'sin(x)', color: '#4f8ef7' },
+      { expr: '0.8*cos(x)', label: 'cos', color: '#3ecf8e' },
+    ] },
+    { type: 'callout', tone: 'info', title: '提示', content: '画廊覆盖全部组件词汇。' },
+    { type: 'steps', current: 2, steps: [
+      { title: '起草', desc: '写规格' }, { title: '渲染', desc: '画组件' }, { title: '验证', desc: '跑测试' },
+    ] },
+    { type: 'diff', diffs: [
+      { path: 'a.ts', oldText: 'const x = 1', newText: 'const x = 2' },
+    ] },
+    { type: 'code', lang: 'json', code: '{"hello": "world"}' },
+    { type: 'mermaid', code: 'graph TD\nA[模型] --> B[渲染器]\nB --> C[组件]' },
+    { type: 'scene3d', title: '几何演示', ambient: 1, meshes: [
+      { shape: 'box', color: '#4f8ef7', position: [-1.4, 0, 0], rotation: [0.5, 0.8, 0] },
+      { shape: 'sphere', color: '#3ecf8e', position: [0, 0, 0] },
+      { shape: 'cone', color: '#e0a458', position: [1.4, 0, 0] },
+    ] },
+    { type: 'timeline', items: [
+      { title: '发布 v0.1', desc: '首个可用版本', time: '08-01' },
+      { title: '事件循环', desc: 'action 回流', time: '08-08' },
+    ] },
+    { type: 'file-tree', items: [
+      { name: 'src', type: 'dir', children: [
+        { name: 'client', type: 'dir', children: [{ name: 'GenuiBlock.tsx', type: 'file' }] },
+        { name: 'spec.ts', type: 'file' },
+      ] },
+      { name: 'README.md', type: 'file' },
+    ] },
+    { type: 'breadcrumb', items: ['首页', '组件', '画廊'] },
+    { type: 'quiz', question: '1 + 1 = ?', id: 'gallery-q1', options: [
+      { label: '1', feedback: '再想想' }, { label: '2', correct: true }, { label: '3' },
+    ], explanation: '二进制里 1+1=10，十进制里是 2。' },
+    { type: 'spacer' },
+  ],
+}