@changfenhuang/dsh-genui 0.9.9 → 0.10.0

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

@@ -75,7 +75,20 @@ export const DIAGRAM_NODE_TYPES = ['focal', 'backend', 'store', 'external', 'inp
 export const DIAGRAM_VARIANTS = ['light', 'dark', 'editorial'] as const
 export const DIAGRAM_EDGE_KINDS = ['solid', 'dashed', 'accent', 'link'] as const
 export const DIAGRAM_ROUTES = ['auto', 'orthogonal', 'straight'] as const
-export const ECHART_PRESETS = ['bar', 'line', 'area', 'pie', 'scatter'] as const
+export const ECHART_PRESETS = [
+  'bar', 'line', 'area', 'pie', 'scatter',
+  'radar', 'gauge', 'funnel', 'treemap', 'sankey', 'graph', 'heatmap', 'bigline',
+] as const
+/** Oversized single-number stat (one per fence as the visual anchor). */
+export const STAT_SIZES = ['hero'] as const
+/** Progress shapes: a track (default) or a circular gauge. */
+export const PROGRESS_VARIANTS = ['bar', 'ring'] as const
+/** Semantic card surfaces. */
+export const CARD_TONES = ['info', 'success', 'warning', 'danger'] as const
+/** Hero cover tones. */
+export const HERO_TONES = ['accent', 'success', 'warning', 'danger'] as const
+/** Table cell renderers (`table.types`, one entry per column). */
+export const TABLE_CELL_TYPES = ['text', 'num', 'delta', 'bar', 'badge', 'spark', 'ring', 'index', 'group'] as const
 
 const schema = (
   required: readonly string[],
@@ -119,7 +132,7 @@ const recordSchema = (
   enums: Readonly<Record<string, readonly string[]>> = {},
 ): ComponentRecordSchema => ({ required, fields, enums, nested })
 
-const nodeFields = { type: 'string' } as const
+const nodeFields = { type: 'string', span: 'number' } as const
 
 const chartDatumSchema = recordSchema(['label', 'value'], {
   label: 'string',
@@ -233,11 +246,21 @@ export const COMPONENT_SCHEMAS: Readonly<Record<string, ComponentSchema>> = {
   breadcrumb: schema(['items'], { ...nodeFields, items: 'array' }),
   button: schema(['label'], { ...nodeFields, label: 'string', tone: 'string', full: 'boolean', small: 'boolean', icon: 'string', action: 'string' }, {}, { enums: { tone: BUTTON_TONES } }),
   callout: schema(['content'], { ...nodeFields, title: 'string', content: 'string', tone: 'string' }, { kind: 'tone' }, { enums: { tone: CALLOUT_TONES } }),
-  card: schema(['items'], { ...nodeFields, title: 'string', items: 'nodes' }, { label: 'title', content: 'items' }),
-  chart: schema([], { ...nodeFields, kind: 'string', data: 'array', series: 'array' }, {}, {
+  card: schema(['items'], { ...nodeFields, title: 'string', items: 'nodes', tone: 'string', accent: 'string' }, { label: 'title', content: 'items' }, { enums: { tone: CARD_TONES } }),
+  chart: schema([], {
+    ...nodeFields,
+    kind: 'string',
+    data: 'array',
+    series: 'array',
+    horizontal: 'boolean',
+    stacked: 'boolean',
+    filter: 'string',
+    palette: 'array',
+  }, {}, {
     oneOfRequired: [['data', 'series']],
+    // `line` may carry its points in `series` (multi-series line); only the
+    // donut is a single-series shape that always needs `data`.
     conditionalRequired: [
-      { kind: 'required-if', when: { field: 'kind', equals: 'line' }, required: ['data'] },
       { kind: 'required-if', when: { field: 'kind', equals: 'donut' }, required: ['data'] },
     ],
     nested: { data: chartDatumSchema, series: chartSeriesSchema },
@@ -254,8 +277,9 @@ export const COMPONENT_SCHEMAS: Readonly<Record<string, ComponentSchema>> = {
   }),
   diff: schema(['diffs'], { ...nodeFields, diffs: 'array' }, {}, { nested: { diffs: diffRecordSchema } }),
   divider: schema([], nodeFields),
-  echart: schema([], { ...nodeFields, title: 'string', height: 'number', preset: 'string', data: 'array', series: 'array', option: 'object' }, {}, {
-    oneOfRequired: [['option', 'data', 'series']],
+  echart: schema([], { ...nodeFields, title: 'string', height: 'number', preset: 'string', data: 'array', series: 'array', links: 'array', palette: 'array', option: 'object' }, {}, {
+    // `links` alone is valid: the sankey/graph presets are edge-driven.
+    oneOfRequired: [['option', 'data', 'series', 'links']],
     enums: { preset: ECHART_PRESETS },
   }),
   'file-tree': schema(['items'], { ...nodeFields, items: 'array' }, {}, { nested: { items: fileTreeNodeSchema } }),
@@ -265,10 +289,10 @@ export const COMPONENT_SCHEMAS: Readonly<Record<string, ComponentSchema>> = {
   json: schema(['value'], { ...nodeFields, value: 'unknown' }),
   keyvalue: schema(['pairs'], { ...nodeFields, pairs: 'array' }, {}, { nested: { pairs: keyValueRecordSchema } }),
   link: schema(['label'], { ...nodeFields, label: 'string', href: 'string' }),
-  list: schema(['items'], { ...nodeFields, items: 'array' }),
+  list: schema(['items'], { ...nodeFields, items: 'array', filter: 'string' }),
   mermaid: schema(['code'], { ...nodeFields, code: 'string' }),
   plot: schema(['series'], { ...nodeFields, series: 'array', xMin: 'number', xMax: 'number', yMin: 'number', yMax: 'number', title: 'string' }, {}, { nested: { series: plotSeriesSchema } }),
-  progress: schema(['value'], { ...nodeFields, value: 'number', label: 'string', valueLabel: 'string' }),
+  progress: schema(['value'], { ...nodeFields, value: 'number', label: 'string', valueLabel: 'string', variant: 'string', target: 'number' }, {}, { enums: { variant: PROGRESS_VARIANTS } }),
   quiz: schema(['question', 'options'], { ...nodeFields, question: 'string', options: 'array', explanation: 'string', id: 'string', action: 'string' }),
   radio: schema(['options'], { ...nodeFields, label: 'string', options: 'array', selected: 'number', action: 'string', group: 'string', answer: 'unknown', explanation: 'string' }),
   row: schema(['items'], { ...nodeFields, items: 'nodes', wrap: 'boolean', spacer: 'boolean' }),
@@ -276,11 +300,21 @@ export const COMPONENT_SCHEMAS: Readonly<Record<string, ComponentSchema>> = {
   select: schema(['options'], { ...nodeFields, label: 'string', options: 'array', action: 'string', selected: 'number', id: 'string' }),
   slider: schema([], { ...nodeFields, label: 'string', min: 'number', max: 'number', step: 'number', value: 'number', action: 'string', id: 'string' }),
   spacer: schema([], nodeFields),
-  stat: schema(['label', 'value'], { ...nodeFields, label: 'string', value: 'string', delta: 'string' }),
+  hero: schema(['title'], {
+    ...nodeFields,
+    title: 'string',
+    subtitle: 'string',
+    value: 'string',
+    label: 'string',
+    delta: 'string',
+    spark: 'array',
+    tone: 'string',
+  }, {}, { enums: { tone: HERO_TONES } }),
+  stat: schema(['label', 'value'], { ...nodeFields, label: 'string', value: 'string', delta: 'string', spark: 'array', size: 'string' }, {}, { enums: { size: STAT_SIZES } }),
   steps: schema(['steps'], { ...nodeFields, steps: 'array', current: 'number' }, { items: 'steps' }, { nested: { steps: stepsRecordSchema } }),
   submit: schema(['label'], { ...nodeFields, label: 'string', action: 'string', resetAction: 'string', groups: 'array' }),
   switch: schema(['label'], { ...nodeFields, label: 'string', checked: 'boolean', action: 'string' }),
-  table: schema(['columns', 'rows'], { ...nodeFields, columns: 'array', rows: 'array' }, { headers: 'columns', data: 'rows' }),
+  table: schema(['columns', 'rows'], { ...nodeFields, columns: 'array', rows: 'array', types: 'array', total: 'boolean', details: 'array', filter: 'string', filterColumn: 'number', sortField: 'string', export: 'boolean' }, { headers: 'columns', data: 'rows' }),
   tabs: schema(['tabs'], { ...nodeFields, tabs: 'array' }, {}, { nested: { tabs: tabHolderSchema } }),
   text: schema(['content'], { ...nodeFields, content: 'string', size: 'string', center: 'boolean' }, { text: 'content' }, { enums: { size: TEXT_SIZES } }),
   textarea: schema([], { ...nodeFields, label: 'string', placeholder: 'string', rows: 'number', value: 'string', action: 'string', id: 'string' }),

package/src/client/guard.ts

@@ -21,10 +21,10 @@
 import type { GenuiFileTreeNode, GenuiList, GenuiNode, GenuiPlot, GenuiPlotSeries, GenuiScene3D, GenuiSpec, GenuiDiagram, GenuiDiagramTheme, GenuiDiagramKind } from './spec.ts'
 import { wrapSingleComponentRoot } from './spec.ts'
 import {
-  BADGE_TONES, BUTTON_TONES, CALLOUT_TONES, CHART_KINDS, COMPONENT_SCHEMAS, DIAGRAM_EDGE_KINDS,
-  DIAGRAM_KINDS, DIAGRAM_NODE_TYPES, DIAGRAM_ROUTES, DIAGRAM_VARIANTS, ECHART_PRESETS, FILE_TYPES,
-  GENUI_NATIVE_TYPES, GENUI_SPEC_SCHEMA, INPUT_TYPES, MEDIA_ASPECT_RATIOS, MESH_SHAPES, PLOT_KINDS,
-  TEXT_SIZES,
+  BADGE_TONES, BUTTON_TONES, CALLOUT_TONES, CARD_TONES, CHART_KINDS, COMPONENT_SCHEMAS, HERO_TONES,
+  DIAGRAM_EDGE_KINDS, DIAGRAM_KINDS, DIAGRAM_NODE_TYPES, DIAGRAM_ROUTES, DIAGRAM_VARIANTS,
+  ECHART_PRESETS, FILE_TYPES, GENUI_NATIVE_TYPES, GENUI_SPEC_SCHEMA, INPUT_TYPES,
+  MEDIA_ASPECT_RATIOS, MESH_SHAPES, PLOT_KINDS, PROGRESS_VARIANTS, TABLE_CELL_TYPES, TEXT_SIZES,
 } from './genui-runtime/schema.ts'
 import type { ComponentFieldKind, ComponentRecordSchema, ComponentSchema } from './genui-runtime/schema.ts'
 import { normalizeGenuiSpec } from './genui-runtime/normalize.ts'
@@ -209,7 +209,41 @@ function repairItems(list: unknown, ctx: RepairCtx, depth: number): GenuiNode[]
   return out
 }
 
+/** Optional explicit palette: up to 12 validated colour values. */
+function paletteValues(v: unknown): string[] | undefined {
+  if (!Array.isArray(v)) return undefined
+  const out: string[] = []
+  for (const item of v.slice(0, 12)) {
+    const value = color(item)
+    if (value === undefined) continue
+    out.push(value)
+  }
+  return out.length > 0 ? out : undefined
+}
+
+/** Optional `stat.spark` series: finite numbers only, 2..60 points. */
+function sparkValues(v: unknown): number[] | undefined {
+  if (!Array.isArray(v)) return undefined
+  const out: number[] = []
+  for (const item of v.slice(0, 60)) {
+    const n = typeof item === 'number' ? item : Number(item)
+    if (!Number.isFinite(n)) return undefined
+    out.push(n)
+  }
+  return out.length >= 2 ? out : undefined
+}
+
+/** Layout hints are component-agnostic: `span` survives repair on ANY node
+ *  (the renderer applies it inside a grid). Kept out of the per-case switches
+ *  so a new component type cannot forget it. */
 function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode | null {
+  const node = repairNodeFields(value, ctx, depth)
+  if (node === null) return null
+  const span = int(obj(value)?.span, 2, 12)
+  return span === undefined ? node : ({ ...node, span } as GenuiNode)
+}
+
+function repairNodeFields(value: unknown, ctx: RepairCtx, depth: number): GenuiNode | null {
   if (depth > GENUI_LIMITS.maxDepth) return null
   const v = obj(value)
   if (v === undefined) return null
@@ -231,7 +265,13 @@ function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode |
       return { type: 'grid', cols: int(v.cols, 1, GENUI_LIMITS.maxGridCols) ?? 1, items: repairItems(v.items, ctx, depth + 1) }
     }
     case 'card': {
-      return { type: 'card', items: repairItems(v.items, ctx, depth + 1), ...opt('title', str(v.title, GENUI_LIMITS.maxString)) }
+      return {
+        type: 'card',
+        items: repairItems(v.items, ctx, depth + 1),
+        ...opt('title', str(v.title, GENUI_LIMITS.maxString)),
+        ...opt('tone', enu(v.tone, CARD_TONES)),
+        ...opt('accent', color(v.accent)),
+      }
     }
     case 'button': {
       const label = str(v.label, GENUI_LIMITS.maxString)
@@ -316,16 +356,40 @@ function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode |
       if (label === undefined) return null
       return { type: 'badge', label, ...opt('tone', enu(v.tone, BADGE_TONES)), ...opt('icon', str(v.icon, 64)) }
     }
+    case 'hero': {
+      const title = str(v.title, GENUI_LIMITS.maxString)
+      if (title === undefined) return null
+      return {
+        type: 'hero', title,
+        ...opt('subtitle', str(v.subtitle, GENUI_LIMITS.maxString)),
+        ...opt('value', str(v.value, 128)),
+        ...opt('label', str(v.label, GENUI_LIMITS.maxString)),
+        ...opt('delta', str(v.delta, 64)),
+        ...opt('spark', sparkValues(v.spark)),
+        ...opt('tone', enu(v.tone, HERO_TONES)),
+      }
+    }
     case 'stat': {
       const label = str(v.label, GENUI_LIMITS.maxString)
       const value = str(v.value, 128)
       if (label === undefined || value === undefined) return null
-      return { type: 'stat', label, value, ...opt('delta', str(v.delta, 64)) }
+      return {
+        type: 'stat', label, value,
+        ...opt('delta', str(v.delta, 64)),
+        ...opt('spark', sparkValues(v.spark)),
+        ...opt('size', v.size === 'hero' ? 'hero' as const : undefined),
+      }
     }
     case 'progress': {
       const value = num(v.value, 0, 100)
       if (value === undefined) return null
-      return { type: 'progress', value, ...opt('label', str(v.label, GENUI_LIMITS.maxString)), ...opt('valueLabel', str(v.valueLabel, 64)) }
+      return {
+        type: 'progress', value,
+        ...opt('label', str(v.label, GENUI_LIMITS.maxString)),
+        ...opt('valueLabel', str(v.valueLabel, 64)),
+        ...opt('variant', enu(v.variant, PROGRESS_VARIANTS)),
+        ...opt('target', num(v.target, 0, 100)),
+      }
     }
     case 'divider': return { type: 'divider' }
     case 'spacer': return { type: 'spacer' }
@@ -337,7 +401,7 @@ function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode |
     case 'list': {
       const items = repairListItems(v.items, GENUI_LIMITS.maxListItems, ctx, depth + 1)
       if (items === undefined) return null
-      return { type: 'list', items }
+      return { type: 'list', items, ...opt('filter', str(v.filter, 64)) }
     }
     case 'table': {
       let rawCols = v.columns as unknown
@@ -359,7 +423,36 @@ function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode |
       const columns = repairStrings(rawCols, GENUI_LIMITS.maxTableCols, 128)
       const rows = repairRows(rawRows, GENUI_LIMITS.maxTableRows, GENUI_LIMITS.maxTableCols)
       if (columns === undefined || rows === undefined) return null
-      return { type: 'table', columns, rows }
+      // Optional per-column cell types; unknown entries degrade to 'text'.
+      const rawTypes = Array.isArray(v.types) ? v.types : undefined
+      const types = rawTypes === undefined
+        ? undefined
+        : columns.map((_c, i) => {
+          const raw = rawTypes[i]
+          return typeof raw === 'string' && (TABLE_CELL_TYPES as readonly string[]).includes(raw)
+            ? raw as typeof TABLE_CELL_TYPES[number]
+            : 'text'
+        })
+      // Master-detail payload: positionally aligned with `rows`. Entries that
+      // repair to nothing stay null so the renderer never shows an empty
+      // expander; extra entries beyond the row count are dropped.
+      const rawDetails = Array.isArray(v.details) ? v.details : undefined
+      const details = rawDetails === undefined
+        ? undefined
+        : rows.map((_row, i) => {
+          const entry = repairItems(rawDetails[i], ctx, depth + 1)
+          return entry.length === 0 ? null : entry
+        })
+      return {
+        type: 'table', columns, rows,
+        ...opt('types', types),
+        ...opt('total', v.total === true ? true : undefined),
+        ...opt('export', v.export === true ? true : undefined),
+        ...opt('filter', str(v.filter, 64)),
+        ...opt('filterColumn', int(v.filterColumn, 0, GENUI_LIMITS.maxTableCols - 1)),
+        ...opt('sortField', str(v.sortField, 64)),
+        ...opt('details', details !== undefined && details.some(d => d !== null) ? details : undefined),
+      }
     }
     case 'chart': {
       const data = repairChartData(v.data, GENUI_LIMITS.maxChartPoints)
@@ -368,7 +461,15 @@ function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode |
       // alone; a series-only chart gets an empty data array (the renderer
       // reads `series` in that case).
       if (data === undefined && series === undefined) return null
-      return { type: 'chart', data: data ?? [], ...opt('kind', enu(v.kind, CHART_KINDS)), ...opt('series', series) }
+      return {
+        type: 'chart', data: data ?? [],
+        ...opt('kind', enu(v.kind, CHART_KINDS)),
+        ...opt('series', series),
+        ...opt('horizontal', v.horizontal === true ? true : undefined),
+        ...opt('stacked', v.stacked === true ? true : undefined),
+        ...opt('filter', str(v.filter, 64)),
+        ...opt('palette', paletteValues(v.palette)),
+      }
     }
     case 'tabs': {
       const tabs = repairTabs(v.tabs, ctx, depth)
@@ -541,6 +642,16 @@ function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode |
       const series = v.series !== undefined && Array.isArray(v.series)
         ? repairSeries(v.series, GENUI_LIMITS.maxPlotSeries, GENUI_LIMITS.maxChartPoints)
         : undefined
+      // sankey / graph edges: `from`/`to` must be strings, `value` a number.
+      const links = Array.isArray(v.links)
+        ? v.links.slice(0, GENUI_LIMITS.maxChartPoints).flatMap(entry => {
+          const e = obj(entry)
+          const from = e === undefined ? undefined : str(e.from, 64)
+          const to = e === undefined ? undefined : str(e.to, 64)
+          if (from === undefined || to === undefined) return []
+          return [{ from, to, ...opt('value', num(e!.value, 0, 1e9)) }]
+        })
+        : undefined
       // Full option: depth-bounded pass-through (the model writes the ECharts
       // option object; the guard walks it to cap nesting but does not
       // validate ECharts semantics — that is echarts' own job).
@@ -553,8 +664,9 @@ function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode |
         sanitized === undefined || typeof sanitized !== 'object' || sanitized === null || Array.isArray(sanitized)
           ? undefined
           : sanitized as Record<string, unknown>
-      // At least one of preset+data or option must be present.
-      if (option === undefined && data === undefined && series === undefined) return null
+      // At least one of preset+data, links or option must be present.
+      if (option === undefined && data === undefined && series === undefined
+        && (links === undefined || links.length === 0)) return null
       return {
         type: 'echart',
         ...opt('title', str(v.title, GENUI_LIMITS.maxString)),
@@ -562,6 +674,8 @@ function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode |
         ...opt('preset', enu(v.preset, ECHART_PRESETS)),
         ...opt('data', data),
         ...opt('series', series),
+        ...opt('links', links !== undefined && links.length > 0 ? links : undefined),
+        ...opt('palette', paletteValues(v.palette)),
         ...opt('option', option),
       }
     }
@@ -1480,19 +1594,29 @@ function validateChartNode(v: Record<string, unknown>, at: string, errors: strin
     errors.push(`${at}.kind must be bars, line, or donut`)
   }
   const kind = v.kind === undefined ? 'bars' : v.kind
-  if (Array.isArray(v.data) && v.data.length === 0) errors.push(`${at}.data must not be empty`)
-  if (Array.isArray(v.series)) {
-    if (v.series.length === 0) errors.push(`${at}.series must not be empty`)
-    if (kind === 'line' || kind === 'donut') errors.push(`${at}.series is only supported for bars`)
-    for (let index = 0; index < v.series.length; index++) {
-      const series = obj(v.series[index])
-      if (series !== undefined && Array.isArray(series.data) && series.data.length === 0) {
+  const series = Array.isArray(v.series) ? v.series : undefined
+  // Grouped bars legitimately carry `data: []` and keep every point in
+  // `series`; only an empty data array with NO series is undrawable.
+  if (Array.isArray(v.data) && v.data.length === 0 && (series === undefined || series.length === 0)) {
+    errors.push(`${at}.data must not be empty`)
+  }
+  if (series !== undefined) {
+    if (series.length === 0) errors.push(`${at}.series must not be empty`)
+    // A line chart accepts `series` (one line per entry); the donut is a
+    // share-of-total shape and stays single-series.
+    if (kind === 'donut') errors.push(`${at}.series is only supported for bars and line`)
+    for (let index = 0; index < series.length; index++) {
+      const entry = obj(series[index])
+      if (entry !== undefined && Array.isArray(entry.data) && entry.data.length === 0) {
         errors.push(`${at}.series[${index}].data must not be empty`)
       }
     }
   }
-  if ((kind === 'line' || kind === 'donut') && v.data === undefined) {
-    errors.push(`${at}.data is required for ${kind}`)
+  if (kind === 'donut' && v.data === undefined) {
+    errors.push(`${at}.data is required for donut`)
+  }
+  if (kind === 'line' && v.data === undefined && (series === undefined || series.length === 0)) {
+    errors.push(`${at}.data is required for line (or provide series)`)
   }
   validateChartData(v.data, `${at}.data`, errors)
   validateChartSeries(v.series, `${at}.series`, errors)
@@ -1581,6 +1705,10 @@ function validateNode(value: unknown, depth: number, at: string, errors: string[
       isStr('text')
       isStr('value')
       break
+    case 'hero':
+      if (typeof v.title !== 'string') errors.push(`${at}: type 'hero' requires title (string)`)
+      isStr('subtitle')
+      break
     case 'stat':
       if (typeof v.label !== 'string') errors.push(`${at}: type 'stat' requires label (string)`)
       if (typeof v.value !== 'string') errors.push(`${at}: type 'stat' requires value (string)`)
@@ -1612,6 +1740,12 @@ function validateNode(value: unknown, depth: number, at: string, errors: string[
     case 'table':
       if (!Array.isArray(v.columns)) errors.push(`${at}: type 'table' requires columns (array)`)
       if (!Array.isArray(v.rows)) errors.push(`${at}: type 'table' requires rows (array)`)
+      if (v.types !== undefined && !Array.isArray(v.types)) {
+        errors.push(`${at}.types must be an array of column cell types`)
+      }
+      if (v.details !== undefined && !Array.isArray(v.details)) {
+        errors.push(`${at}.details must be an array aligned with rows`)
+      }
       validateTableRows(v.rows, `${at}.rows`, errors)
       break
     case 'chart':
@@ -1690,8 +1824,12 @@ function validateNode(value: unknown, depth: number, at: string, errors: string[
       break
 
     case 'echart':
-      if (v.option === undefined && v.data === undefined && v.series === undefined) {
-        errors.push(`${at}: type 'echart' requires option, data, or series`)
+      // `links` alone is a valid payload: the sankey/graph presets are driven
+      // by edges only. Missing it here rejected the whole fence as
+      // un-renderable (the render gate turns any error into "render nothing").
+      if (v.option === undefined && v.data === undefined && v.series === undefined
+        && (!Array.isArray(v.links) || v.links.length === 0)) {
+        errors.push(`${at}: type 'echart' requires option, data, series, or links`)
       }
       isNum('height')
       break

package/src/client/index.tsx

@@ -124,6 +124,16 @@ function sendInlineGenuiAction(ctx: Context, sessionId: SessionId, action: strin
   })
 }
 
+/** Visual-regression flag: `scripts/e2e-visual.mts` sets
+ * `window.__DSH_GENUI_E2E__ = true` via an init script BEFORE this bundle
+ * boots, which pins the DOM channel even on hosts that ship the registry
+ * extension point. The DOM channel is what lets the harness inject a gallery
+ * fence into an empty scratch profile and screenshot the real React tree
+ * without a model round trip; production pages never set the flag. */
+function forcedDomChannel(): boolean {
+  return (globalThis as { __DSH_GENUI_E2E__?: boolean }).__DSH_GENUI_E2E__ === true
+}
+
 /** Cordis client entry: register the fence renderer on boot, the keyed
  * toolview for the render_ui tool, and the session panel dock; returning the
  * disposers lets cordis tear all registrations down on plugin unload. */
@@ -132,10 +142,11 @@ export function apply(ctx: Context): () => void {
   // ships it (contract line), the DOM observer otherwise (pristine line).
   // One plugin build serves both deployments.
   const registerFn = (primitives as unknown as HostFenceExt).registerFenceRenderer
-  const channel = typeof registerFn === 'function' ? 'registry' : 'dom'
+  const useRegistry = typeof registerFn === 'function' && !forcedDomChannel()
+  const channel = useRegistry ? 'registry' : 'dom'
   console.info(`[genui] client active; fence-channel=${channel}`)
-  const disposers: Array<() => void> = typeof registerFn === 'function'
-    ? [registerFn('dsh-ui', renderGenuiFence)]
+  const disposers: Array<() => void> = useRegistry
+    ? [registerFn!('dsh-ui', renderGenuiFence)]
     : [installDomFenceRenderer(ctx, (sessionId, action, payload) => sendInlineGenuiAction(ctx, sessionId, action, payload))]
   // Idle prefetch of the lazy engine assets: the browser downloads them at
   // LOW priority whenever the page is idle, so the first mermaid/3D node in

package/src/client/inline.ts

@@ -0,0 +1,73 @@
+/**
+ * Minimal inline markup for text-bearing fields.
+ *
+ * Prose-heavy answers need emphasis INSIDE a sentence: a command, a term, a key
+ * phrase, a link. Until now every field was a plain string, so emphasis meant
+ * splitting one sentence into several nodes and the paragraph read as broken.
+ *
+ * Supported (deliberately tiny, no nesting):
+ *   `code`            inline code chip
+ *   **bold**          emphasis that does not wrap or become a block
+ *   ==mark==          highlight
+ *   [text](https://…) inline link (http/https/mailto only)
+ *
+ * Safety: this NEVER produces HTML. Each token becomes a React element, so the
+ * host's HTML parser is never involved (the whole client builds elements, the
+ * only innerHTML in the project is mermaid's sanitized SVG). An unterminated or
+ * unknown marker is rendered literally rather than erroring, and a link whose
+ * href fails {@link safeHref} degrades to its label text.
+ * @module @changfenhuang/dsh-genui/client/inline
+ */
+import { createElement, type ReactNode } from 'react'
+import css from './GenuiBlock.module.css'
+import { safeHref } from './genui-runtime/value-utils.ts'
+
+/** One pass, no nesting: each alternative is a self-contained token. */
+// Links match ANY target here and are validated by safeHref afterwards, so a
+// `javascript:` target degrades to its label text instead of showing as raw
+// markup the reader has to parse themselves.
+const INLINE = /`[^`\n]+`|\*\*[^*\n]+\*\*|==[^=\n]+==|\[[^\]\n]+\]\([^)\s]+\)/g
+
+/** True when the string contains anything the parser understands. */
+export function hasInlineMarkup(text: string): boolean {
+  return typeof text === 'string' && /[`*=]|\[/.test(text)
+}
+
+/**
+ * Render one string as React nodes with inline markup applied.
+ * @param text - the raw field value.
+ * @returns the original string when nothing matched, else the node list.
+ */
+export function renderInline(text: string): ReactNode {
+  if (typeof text !== 'string' || text === '' || !hasInlineMarkup(text)) return text
+  const out: ReactNode[] = []
+  let last = 0
+  let key = 0
+  for (const match of text.matchAll(INLINE)) {
+    const index = match.index ?? 0
+    const token = match[0]
+    if (index > last) out.push(text.slice(last, index))
+    if (token.startsWith('`')) {
+      out.push(createElement('code', { key: key++, className: css.inlineCode }, token.slice(1, -1)))
+    } else if (token.startsWith('**')) {
+      out.push(createElement('strong', { key: key++, className: css.inlineStrong }, token.slice(2, -2)))
+    } else if (token.startsWith('==')) {
+      out.push(createElement('mark', { key: key++, className: css.inlineMark }, token.slice(2, -2)))
+    } else {
+      const parts = /^\[([^\]\n]+)\]\(([^)\s]+)\)$/.exec(token)
+      if (parts === null) {
+        out.push(token)
+      } else {
+        const href = safeHref(parts[2])
+        out.push(href === undefined
+          ? parts[1]
+          : createElement('a', {
+            key: key++, className: css.inlineLink, href, target: '_blank', rel: 'noreferrer noopener',
+          }, parts[1]))
+      }
+    }
+    last = index + token.length
+  }
+  if (last < text.length) out.push(text.slice(last))
+  return out.length === 0 ? text : out
+}

package/src/client/mermaid-core.ts

@@ -25,15 +25,52 @@ let renderSeq = 0
 function loadMermaid(): Promise<typeof import('mermaid')> {
   mermaidPromise ??= import('mermaid').then(async m => {
     const api = m.default
-    // Follow the host theme: boot-theme sets colorScheme on <html>; a
-    // dark-forced diagram on a light chat looked broken.
-    const dark = typeof document !== 'undefined'
-      && document.documentElement.style.colorScheme === 'dark'
+    // Theme the diagram from the HOST tokens instead of a built-in mermaid
+    // palette: the stock themes render grey boxes with sharp corners, dark
+    // strokes and their own font, which sat next to our components as a
+    // visibly foreign object. `base` + themeVariables is the supported way to
+    // drive every colour (the dark/light branch is gone with it).
+    const token = (name: string, fallback: string): string => {
+      if (typeof document === 'undefined') return fallback
+      const value = getComputedStyle(document.body).getPropertyValue(name).trim()
+      return value === '' ? fallback : value
+    }
     api.initialize({
       startOnLoad: false,
       // Strict default: mermaid escapes/sanitizes; we never enable htmlLabels.
       securityLevel: 'strict',
-      theme: dark ? 'dark' : 'neutral',
+      theme: 'base',
+      themeVariables: {
+        background: 'transparent',
+        fontFamily: 'inherit',
+        fontSize: '13px',
+        primaryColor: token('--dsw-alias-bg-layer-2', '#2c2c2e'),
+        primaryTextColor: token('--dsw-alias-label-primary', '#e6e6e6'),
+        primaryBorderColor: token('--dsw-alias-border-l2', 'rgba(255,255,255,0.12)'),
+        secondaryColor: token('--dsw-alias-bg-layer-2', '#2c2c2e'),
+        secondaryTextColor: token('--dsw-alias-label-primary', '#e6e6e6'),
+        secondaryBorderColor: token('--dsw-alias-border-l2', 'rgba(255,255,255,0.12)'),
+        tertiaryColor: token('--dsw-alias-bg-layer-2', '#2c2c2e'),
+        tertiaryTextColor: token('--dsw-alias-label-primary', '#e6e6e6'),
+        tertiaryBorderColor: token('--dsw-alias-border-l2', 'rgba(255,255,255,0.12)'),
+        mainBkg: token('--dsw-alias-bg-layer-2', '#2c2c2e'),
+        nodeBorder: token('--dsw-alias-border-l2', 'rgba(255,255,255,0.12)'),
+        nodeTextColor: token('--dsw-alias-label-primary', '#e6e6e6'),
+        lineColor: token('--dsw-alias-label-tertiary', '#8a8a92'),
+        textColor: token('--dsw-alias-label-primary', '#e6e6e6'),
+        edgeLabelBackground: 'transparent',
+        clusterBkg: 'transparent',
+        clusterBorder: token('--dsw-alias-border-l2', 'rgba(255,255,255,0.12)'),
+        titleColor: token('--dsw-alias-label-primary', '#e6e6e6'),
+      },
+      // Sharp corners and heavy strokes were the loudest mismatch; the radius
+      // is set here because mermaid emits plain <rect> geometry.
+      themeCSS: [
+        '.node rect, .node polygon, .node circle, .node ellipse { rx: 8px; ry: 8px; stroke-width: 1px; }',
+        '.cluster rect { rx: 10px; ry: 10px; }',
+        '.edgePath .path { stroke-width: 1.4px; }',
+        '.label { color: inherit; }',
+      ].join(' '),
       // Fail loudly: with suppressErrorRendering false (the default) mermaid
       // renders an "error" diagram on parse/draw failure — the caller then
       // receives a normal-looking SVG whose text is the raw engine error