@changfenhuang/dsh-genui 0.9.8 → 0.9.9

package/src/client/fence-render.tsx

@@ -16,15 +16,15 @@
  */
 import { Fragment, useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type Key, type ReactNode } from 'react'
 import { CodeBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import { CODE_BLOCK_LABELS } from './primitive-labels.ts'
 import { ErrorBoundary } from './ErrorBoundary.tsx'
 import { GenuiBlock } from './GenuiBlock.tsx'
-import { repairGenuiSpec } from './guard.ts'
+import { isRenderableProcess, processGenuiSpec } 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'
-import { validateRenderableChartSemantics } from '../plugin/chart-contract.ts'
 
 /** Settled fence source identity (data shape, host-independent). */
 export interface GenuiFenceSource {
@@ -54,12 +54,22 @@ const FENCE_ERROR_STYLE: CSSProperties = {
   whiteSpace: 'pre-wrap',
 }
 
-/** Return a chart-semantic diagnostic for parseable raw fence content. */
-function chartSemanticFailure(raw: string): string | null {
+/** Format chart-specific process errors without maintaining a second validator. */
+function formatChartProcessErrors(errors: string[]): string | null {
+  const chartErrors = errors.filter(error => /(?:variant is unsupported|kind must be bars, line, or donut|requires data or series|(?:data|series) is required for|(?:\.data|\.series)(?:\[\d+\])?(?:\.(?:data|label|value|color))? must|series is only supported for bars)/.test(error))
+  return chartErrors.length === 0 ? null : chartErrors.join('；')
+}
+
+/** Return a semantic/schema diagnostic for parseable raw fence content. */
+function processSemanticFailure(raw: string): string | null {
   const parsed = parsePartialGenuiSpec(raw)
   if (parsed === null) return null
-  const errors = validateRenderableChartSemantics(parsed)
-  return errors.length === 0 ? null : errors.join('；')
+  const processed = processGenuiSpec(parsed)
+  if (isRenderableProcess(processed)) return null
+  const chartErrors = formatChartProcessErrors(processed.errors)
+  return chartErrors === null
+    ? `GenUI 字段验证失败：${processed.errors.join('；')}`
+    : `chart 字段验证失败：${chartErrors}`
 }
 
 /**
@@ -86,21 +96,21 @@ function FenceFallback({ raw, fenceKey }: { raw: string; fenceKey: Key }) {
     const node = ref.current
     if (node !== null && node.closest('[data-streaming]') === null) setSettled(true)
   })
-  const chartDiagnostic = settled ? chartSemanticFailure(raw) : null
-  const parseDiagnostic = settled && chartDiagnostic === null && raw.trim() !== '' ? describeJsonFailure(raw) : null
+  const processDiagnostic = settled ? processSemanticFailure(raw) : null
+  const parseDiagnostic = settled && processDiagnostic === null && raw.trim() !== '' ? describeJsonFailure(raw) : null
   return (
     <div ref={ref}>
-      {chartDiagnostic !== null && (
+      {processDiagnostic !== null && (
         <div style={FENCE_ERROR_STYLE} role="alert">
-          ⚠️ dsh-ui chart 字段验证失败：{chartDiagnostic} —— 围栏保持为代码块；请修正 chart 字段后重发。
+          ⚠️ dsh-ui {processDiagnostic} —— 围栏保持为代码块；请修正后重发。
         </div>
       )}
-      {chartDiagnostic === null && parseDiagnostic !== null && (
+      {processDiagnostic === null && parseDiagnostic !== null && (
         <div style={FENCE_ERROR_STYLE} role="alert">
           ⚠️ dsh-ui fence JSON 解析失败{parseDiagnostic} —— 围栏保持为代码块；请让模型检查并修复 JSON 后重发。
         </div>
       )}
-      <CodeBlock key={fenceKey} code={`${raw}\n`} lang="dsh-ui" />
+      <CodeBlock key={fenceKey} {...CODE_BLOCK_LABELS} code={`${raw}\n`} lang="dsh-ui" />
     </div>
   )
 }
@@ -130,10 +140,11 @@ function FencePanelPublisher({ sessionId, sourceId, order, spec }: {
   return null
 }
 
-/** Repair one parsed value only when its native charts are actually renderable. */
+/** Process one parsed value and return its canonical repaired spec only when the shared pipeline is error-free. */
 function repairRenderableSpec(value: unknown): GenuiSpec | null {
-  if (validateRenderableChartSemantics(value).length > 0) return null
-  return repairGenuiSpec(value)
+  const processed = processGenuiSpec(value)
+  if (!isRenderableProcess(processed)) return null
+  return processed.spec
 }
 
 /**

package/src/client/genui-runtime/diagnostics.ts

@@ -0,0 +1,143 @@
+/** GenUI runtime diagnostics for aliases and unknown fields. */
+import { COMPONENT_SCHEMAS, GENUI_SPEC_SCHEMA } from './schema.ts'
+import type { ComponentRecordSchema, ComponentSchema } from './schema.ts'
+
+export interface GenuiDiagnostic {
+  readonly kind: 'alias' | 'unknown-field'
+  readonly path: string
+  readonly message: string
+  readonly type?: string
+  readonly field?: string
+  readonly canonical?: string
+}
+
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+function isNode(value: unknown): value is Record<string, unknown> {
+  const candidate = record(value)
+  return candidate !== undefined && typeof candidate.type === 'string'
+}
+
+function visitNativeNodes(value: unknown, path: string, visit: (node: Record<string, unknown>, path: string, schema: ComponentSchema) => void): void {
+  if (!isNode(value)) return
+  const type = value.type as string
+  const definition = COMPONENT_SCHEMAS[type]
+  if (definition === undefined) return
+  visit(value, path, definition)
+  const children = (child: unknown, childPath: string): void => visitNativeNodes(child, childPath, visit)
+  if ((type === 'row' || type === 'col' || type === 'grid' || type === 'card') && Array.isArray(value.items)) {
+    value.items.forEach((child, index) => children(child, `${path}.items[${index}]`))
+  } else if (type === 'list' && Array.isArray(value.items)) {
+    value.items.forEach((child, index) => children(child, `${path}.items[${index}]`))
+  } else if (type === 'tabs' && Array.isArray(value.tabs)) {
+    value.tabs.forEach((tab, index) => {
+      const holder = record(tab)
+      if (holder === undefined) return
+      if (Array.isArray(holder.items)) holder.items.forEach((child, childIndex) => children(child, `${path}.tabs[${index}].items[${childIndex}]`))
+      else children(holder.items, `${path}.tabs[${index}].items`)
+    })
+  } else if (type === 'accordion' && Array.isArray(value.items)) {
+    value.items.forEach((item, index) => {
+      const holder = record(item)
+      if (holder?.items !== undefined && Array.isArray(holder.items)) holder.items.forEach((child, childIndex) => children(child, `${path}.items[${index}].items[${childIndex}]`))
+    })
+  }
+}
+
+function pushUnknownField(
+  warnings: GenuiDiagnostic[],
+  path: string,
+  field: string,
+  type: string,
+): void {
+  warnings.push({
+    kind: 'unknown-field',
+    path: `${path}.${field}`,
+    message: `${path}.${field}: unknown field for '${type}'`,
+    type,
+    field,
+  })
+}
+
+function diagnoseRecordFields(
+  value: unknown,
+  path: string,
+  definition: ComponentRecordSchema,
+  type: string,
+  warnings: GenuiDiagnostic[],
+): void {
+  const holder = record(value)
+  if (holder === undefined) return
+  for (const field of Object.keys(holder)) {
+    if (field in definition.fields) continue
+    pushUnknownField(warnings, path, field, type)
+  }
+  for (const [field, nested] of Object.entries(definition.nested)) {
+    const nestedValue = holder[field]
+    if (Array.isArray(nestedValue)) {
+      nestedValue.forEach((item, index) => diagnoseRecordFields(item, `${path}.${field}[${index}]`, nested, type, warnings))
+    } else if (nestedValue !== undefined) {
+      diagnoseRecordFields(nestedValue, `${path}.${field}`, nested, type, warnings)
+    }
+  }
+}
+
+function diagnoseNestedFields(
+  node: Record<string, unknown>,
+  path: string,
+  definition: ComponentSchema,
+  warnings: GenuiDiagnostic[],
+): void {
+  for (const [field, nested] of Object.entries(definition.nested)) {
+    const nestedValue = node[field]
+    if (Array.isArray(nestedValue)) {
+      nestedValue.forEach((item, index) => diagnoseRecordFields(item, `${path}.${field}[${index}]`, nested, node.type as string, warnings))
+    } else if (nestedValue !== undefined) {
+      diagnoseRecordFields(nestedValue, `${path}.${field}`, nested, node.type as string, warnings)
+    }
+  }
+}
+
+/**
+ * Diagnose unknown direct fields on native nodes.
+ *
+ * Unknown types are intentionally skipped so custom renderers retain their
+ * opaque extension payloads. Native unknown fields are warnings, not errors.
+ *
+ * @param value - Canonical or raw GenUI value.
+ * @returns Stable field diagnostics in tree order.
+ */
+export function diagnoseUnknownGenuiFields(value: unknown): GenuiDiagnostic[] {
+  const warnings: GenuiDiagnostic[] = []
+  const root = record(value)
+  if (root === undefined) return warnings
+  const visit = (node: Record<string, unknown>, path: string, definition: ComponentSchema): void => {
+    for (const field of Object.keys(node)) {
+      if (field === 'type' || field in definition.fields) continue
+      pushUnknownField(warnings, path, field, node.type as string)
+    }
+    diagnoseNestedFields(node, path, definition, warnings)
+  }
+  if (Array.isArray(root.items)) {
+    for (const field of Object.keys(root)) {
+      if (field in GENUI_SPEC_SCHEMA.fields) continue
+      pushUnknownField(warnings, 'spec', field, 'spec')
+    }
+    root.items.forEach((item, index) => visitNativeNodes(item, `items[${index}]`, visit))
+  } else if (typeof root.type === 'string') {
+    // A bare component root is a documented shorthand, so its `type` belongs
+    // to the native node schema rather than the root specification schema.
+    visitNativeNodes(root, 'spec', visit)
+  } else {
+    for (const field of Object.keys(root)) {
+      if (field in GENUI_SPEC_SCHEMA.fields) continue
+      pushUnknownField(warnings, 'spec', field, 'spec')
+    }
+  }
+  return warnings
+}

package/src/client/genui-runtime/index.ts

@@ -0,0 +1 @@
+export { GENUI_LIMITS } from './limits.ts'

package/src/client/genui-runtime/limits.ts

@@ -0,0 +1,54 @@
+/** Resource limits shared by GenUI repair, validation, and rendering. */
+export const GENUI_LIMITS = {
+  /** Maximum nesting depth of the component tree. */
+  maxDepth: 8,
+  /** Maximum total nodes across the whole spec. */
+  maxNodes: 200,
+  /** Maximum length of any plain string field. */
+  maxString: 2000,
+  /** Maximum length of a `code` body. */
+  maxCode: 12_000,
+  /** Maximum length of a mermaid source. */
+  maxMermaid: 8000,
+  /** Maximum `grid` columns. */
+  maxGridCols: 12,
+  /** Maximum `tabs` count. */
+  maxTabs: 12,
+  /** Maximum `accordion` items. */
+  maxAccordionItems: 24,
+  /** Maximum `list` items. */
+  maxListItems: 50,
+  /** Maximum `select`/`radio` options. */
+  maxOptions: 50,
+  /** Maximum `table` rows / columns. */
+  maxTableRows: 50,
+  maxTableCols: 12,
+  /** Maximum `chart` data points per series. */
+  maxChartPoints: 60,
+  /** Maximum `plot` series and per-series parameters. */
+  maxPlotSeries: 8,
+  maxPlotParams: 6,
+  /** Maximum `scene3d` meshes. */
+  maxMeshes: 5,
+  /** Maximum `quiz` options. */
+  maxQuizOptions: 8,
+  /** Maximum `steps` / `timeline` / `breadcrumb` / `keyvalue` entries. */
+  maxSteps: 24,
+  maxTimelineItems: 24,
+  maxBreadcrumbItems: 12,
+  maxKeyValuePairs: 24,
+  /** Maximum `file-tree` nesting. */
+  maxTreeDepth: 6,
+  /** Maximum `diagram` nodes / edges / zones / focal accents. */
+  maxDiagramNodes: 9,
+  maxDiagramEdges: 12,
+  maxDiagramZones: 3,
+  maxDiagramFocal: 2,
+  maxDiagramLabel: 14,
+  /** Maximum depth of an `echart` option object. */
+  maxEChartOptionDepth: 10,
+  /** Maximum length of any single array inside an `echart` option. */
+  maxEChartArrayLen: 500,
+  /** Maximum entries traversed while sanitizing an `echart` option. */
+  maxEChartOptionNodes: 2000,
+} as const

package/src/client/genui-runtime/normalize.ts

@@ -0,0 +1,115 @@
+/** Deterministic GenUI alias and structural normalization. */
+import { COMPONENT_SCHEMAS } from './schema.ts'
+import type { GenuiDiagnostic } from './diagnostics.ts'
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+function isNode(value: unknown): value is Record<string, unknown> {
+  const candidate = record(value)
+  return candidate !== undefined && typeof candidate.type === 'string'
+}
+
+function normalizeAliasFields(value: Record<string, unknown>, path: string, type: string, warnings: GenuiDiagnostic[]): Record<string, unknown> {
+  const definition = COMPONENT_SCHEMAS[type]
+  if (definition === undefined) return value
+  const out: Record<string, unknown> = { ...value }
+  for (const [alias, canonical] of Object.entries(definition.aliases)) {
+    if (!(alias in out)) continue
+    const aliasPath = `${path}.${alias}`
+    const keptCanonical = canonical in out
+    if (!keptCanonical) out[canonical] = out[alias]
+    delete out[alias]
+    warnings.push({
+      kind: 'alias',
+      path: aliasPath,
+      message: keptCanonical
+        ? `${aliasPath} is ignored because canonical field '${canonical}' is present`
+        : `${aliasPath} normalized/adopted as '${canonical}'`,
+      type,
+      field: alias,
+      canonical,
+    })
+  }
+  return out
+}
+
+function normalizeNode(value: unknown, path: string, warnings: GenuiDiagnostic[]): unknown {
+  if (!isNode(value)) return value
+  const type = value.type as string
+  const definition = COMPONENT_SCHEMAS[type]
+  // Custom nodes are opaque by contract: don't inspect or rewrite their data.
+  if (definition === undefined) return value
+  const out = normalizeAliasFields(value, path, type, warnings)
+  const normalizeNodeValue = (child: unknown, childPath: string): unknown => normalizeNode(child, childPath, warnings)
+  const normalizeNodeArray = (children: unknown, childPath: string): unknown => Array.isArray(children)
+    ? children.map((child, index) => normalizeNodeValue(child, `${childPath}[${index}]`))
+    : children
+
+  if (type === 'row' || type === 'col' || type === 'grid' || type === 'card' || type === 'file-tree' || type === 'timeline' || type === 'breadcrumb') {
+    if (type !== 'file-tree' && type !== 'timeline' && type !== 'breadcrumb') out.items = normalizeNodeArray(out.items, `${path}.items`)
+  } else if (type === 'list' && Array.isArray(out.items)) {
+    out.items = out.items.map((child, index) => isNode(child) ? normalizeNodeValue(child, `${path}.items[${index}]`) : child)
+  } else if (type === 'tabs' && Array.isArray(out.tabs)) {
+    out.tabs = out.tabs.map((tab, index) => {
+      const holder = record(tab)
+      if (holder === undefined) return tab
+      const normalizedHolder = { ...holder }
+      if ('content' in normalizedHolder) {
+        const tabPath = `${path}.tabs[${index}].content`
+        const hasItems = 'items' in normalizedHolder
+        if (!hasItems) normalizedHolder.items = normalizedHolder.content
+        delete normalizedHolder.content
+        warnings.push({
+          kind: 'alias',
+          path: tabPath,
+          message: hasItems
+            ? `${tabPath} is ignored because canonical field 'items' is present`
+            : `${tabPath} normalized/adopted as 'items'`,
+          type,
+          field: 'content',
+          canonical: 'items',
+        })
+      }
+      normalizedHolder.items = Array.isArray(normalizedHolder.items)
+        ? normalizedHolder.items.map((child, childIndex) => normalizeNodeValue(child, `${path}.tabs[${index}].items[${childIndex}]`))
+        : normalizedHolder.items === undefined
+          ? normalizedHolder.items
+          : [normalizeNodeValue(normalizedHolder.items, `${path}.tabs[${index}].items[0]`)]
+      return normalizedHolder
+    })
+  } else if (type === 'accordion' && Array.isArray(out.items)) {
+    out.items = out.items.map((item, index) => {
+      const holder = record(item)
+      if (holder === undefined) return item
+      return { ...holder, items: Array.isArray(holder.items) ? holder.items.map((child, childIndex) => normalizeNodeValue(child, `${path}.items[${index}].items[${childIndex}]`)) : holder.items }
+    })
+  }
+  return out
+}
+
+/**
+ * Normalize a raw GenUI value into canonical field names.
+ *
+ * Only deterministic aliases and structural aliases are changed. Resource
+ * limits, type repair, security filtering, and semantic validation remain in
+ * the guard layer. Unknown component types are returned opaque.
+ *
+ * @param value - Raw GenUI spec or bare native component.
+ * @returns Canonical value and stable alias diagnostics.
+ */
+export function normalizeGenuiSpec(value: unknown): { value: unknown; warnings: GenuiDiagnostic[] } {
+  const warnings: GenuiDiagnostic[] = []
+  const root = record(value)
+  if (root === undefined) return { value, warnings }
+  const out = { ...root }
+  if (Array.isArray(out.items)) {
+    out.items = out.items.map((item, index) => normalizeNode(item, `items[${index}]`, warnings))
+  } else if (typeof out.type === 'string') {
+    return { value: normalizeNode(out, 'spec', warnings), warnings }
+  }
+  return { value: out, warnings }
+}