@changfenhuang/dsh-genui 0.9.6 → 0.9.8

package/src/client/fence-render.tsx

@@ -24,6 +24,7 @@ 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 {
@@ -53,6 +54,14 @@ const FENCE_ERROR_STYLE: CSSProperties = {
   whiteSpace: 'pre-wrap',
 }
 
+/** Return a chart-semantic diagnostic for parseable raw fence content. */
+function chartSemanticFailure(raw: string): string | null {
+  const parsed = parsePartialGenuiSpec(raw)
+  if (parsed === null) return null
+  const errors = validateRenderableChartSemantics(parsed)
+  return errors.length === 0 ? null : errors.join('；')
+}
+
 /**
  * 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:
@@ -64,11 +73,11 @@ const FENCE_ERROR_STYLE: CSSProperties = {
  *    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.
+ *    not parse as JSON (a malformed fence like a missing `}`) or violates the
+ *    native chart contract. 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
+ *    so the defect is visible instead of silent.
  */
 function FenceFallback({ raw, fenceKey }: { raw: string; fenceKey: Key }) {
   const ref = useRef<HTMLDivElement | null>(null)
@@ -77,12 +86,18 @@ function FenceFallback({ raw, fenceKey }: { raw: string; fenceKey: Key }) {
     const node = ref.current
     if (node !== null && node.closest('[data-streaming]') === null) setSettled(true)
   })
-  const diagnostic = settled && raw.trim() !== '' ? describeJsonFailure(raw) : null
+  const chartDiagnostic = settled ? chartSemanticFailure(raw) : null
+  const parseDiagnostic = settled && chartDiagnostic === null && raw.trim() !== '' ? describeJsonFailure(raw) : null
   return (
     <div ref={ref}>
-      {diagnostic !== null && (
+      {chartDiagnostic !== null && (
+        <div style={FENCE_ERROR_STYLE} role="alert">
+          ⚠️ dsh-ui chart 字段验证失败：{chartDiagnostic} —— 围栏保持为代码块；请修正 chart 字段后重发。
+        </div>
+      )}
+      {chartDiagnostic === null && parseDiagnostic !== null && (
         <div style={FENCE_ERROR_STYLE} role="alert">
-          ⚠️ dsh-ui fence JSON 解析失败{diagnostic} —— 围栏保持为代码块；请让模型检查并修复 JSON 后重发。
+          ⚠️ dsh-ui fence JSON 解析失败{parseDiagnostic} —— 围栏保持为代码块；请让模型检查并修复 JSON 后重发。
         </div>
       )}
       <CodeBlock key={fenceKey} code={`${raw}\n`} lang="dsh-ui" />
@@ -115,6 +130,12 @@ function FencePanelPublisher({ sessionId, sourceId, order, spec }: {
   return null
 }
 
+/** Repair one parsed value only when its native charts are actually renderable. */
+function repairRenderableSpec(value: unknown): GenuiSpec | null {
+  if (validateRenderableChartSemantics(value).length > 0) return null
+  return repairGenuiSpec(value)
+}
+
 /**
  * Resolve a raw fence body to a guarded spec.
  *
@@ -124,21 +145,24 @@ function FencePanelPublisher({ sessionId, sourceId, order, spec }: {
  * - Tier-2 completion (missing quotes/brackets): settled renders only —
  *   `context.source` exists exclusively once the message finished, so
  *   streaming halves are never completed early.
+ * - Native chart semantics are checked before repair on every candidate so
+ *   aliases, empty collections, or line/donut series cannot repair into a
+ *   default/blank chart.
  */
 export function resolveGenuiSpec(raw: string, context?: GenuiFenceContext): GenuiSpec | null {
   const parsed = parsePartialGenuiSpec(raw)
-  let spec = parsed === null ? null : repairGenuiSpec(parsed)
+  let spec = parsed === null ? null : repairRenderableSpec(parsed)
   if (spec === null) {
     const repaired = repairFenceJson(raw)
     if (repaired !== null) {
       const reparsed = parsePartialGenuiSpec(repaired.text)
-      spec = reparsed === null ? null : repairGenuiSpec(reparsed)
+      spec = reparsed === null ? null : repairRenderableSpec(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)
+        spec = reparsed === null ? null : repairRenderableSpec(reparsed)
       }
     }
   }

package/src/client/gallery.ts

@@ -1,12 +1,10 @@
 /**
- * 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).
+ * GenUI gallery: canonical broad-coverage sample of built-in node types.
+ * Docs, demos, and renderer tests reuse it as the component gallery fence.
  */
 import type { GenuiSpec } from './spec.ts'
 
-/** A single spec covering all 40 node types in the vocabulary. */
+/** Canonical gallery spec for the built-in GenUI component vocabulary. */
 export const gallerySpec: GenuiSpec = {
   title: 'GenUI · 组件画廊',
   gap: 14,
@@ -27,6 +25,7 @@ export const gallerySpec: GenuiSpec = {
       { type: 'link', label: '详情链接' },
     ], wrap: true },
     { type: 'divider' },
+    { type: 'image', src: '/demo-image.png', alt: '图片展示演示' },
     { 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: [

package/src/client/guard.ts

@@ -283,6 +283,14 @@ function repairNode(value: unknown, ctx: RepairCtx, depth: number): GenuiNode |
       if (label === undefined) return null
       return { type: 'link', label, ...opt('href', safeHref(v.href)) }
     }
+    case 'image': {
+      const src = safeMediaSrc(v.src)
+      if (src === undefined) return null
+      return {
+        type: 'image', src,
+        ...opt('alt', str(v.alt, GENUI_LIMITS.maxString)),
+      }
+    }
     case 'audio': {
       const src = safeMediaSrc(v.src)
       if (src === undefined) return null
@@ -1179,61 +1187,96 @@ export function countGenuiNodes(value: unknown, cap = Number.POSITIVE_INFINITY):
  * `"type"` strings (e.g. file-tree's `{type:'file'}` children). */
 export const GENUI_NODE_TYPES: ReadonlySet<string> = new Set([
   'accordion', 'audio', 'avatar', 'badge', 'breadcrumb', 'button', 'callout', 'card', 'chart',
-  'checkbox', 'code', 'col', 'copy', 'diff', 'divider', 'file-tree', 'grid', 'input', 'json',
+  'checkbox', 'code', 'col', 'copy', 'diff', 'divider', 'file-tree', 'grid', 'image', 'input', 'json',
   'keyvalue', 'link', 'list', 'mermaid', 'plot', 'progress', 'quiz', 'radio', 'row', 'scene3d',
   'select', 'slider', 'spacer', 'stat', 'steps', 'submit', 'switch', 'table', 'tabs', 'text',
   'textarea', 'timeline', 'video', 'echart', 'diagram',
 ])
 
 /**
- * Count DECLARED nodes in a raw spec tree: objects whose `type` is a
+ * Visit and count declared nodes in a raw spec tree: objects whose `type` is a
  * white-listed string, descending the same containers `countGenuiNodes`
- * walks. `validate_dsh_ui` compares this with the repaired count to surface
- * children the repair silently dropped (blank-render class of bugs, issue
- * #42) instead of reporting a green check on a half-empty tree.
+ * walks. Callers can inspect field semantics or compare the count with the
+ * repaired tree without maintaining another traversal.
  */
-export function countDeclaredGenuiNodes(value: unknown, cap = Number.POSITIVE_INFINITY): number {
+function visitDeclaredGenuiNodes(
+  value: unknown,
+  cap: number,
+  visit: (node: Record<string, unknown>, at: string) => void,
+): number {
   let count = 0
   const declared = (candidate: unknown): boolean => {
     const o = obj(candidate)
     return o !== undefined && typeof o.type === 'string' && GENUI_NODE_TYPES.has(o.type)
   }
-  const walk = (list: unknown): void => {
+  function walk(list: unknown, path: string): void {
     if (!Array.isArray(list)) return
-    for (const item of list) {
+    for (let index = 0; index < list.length; index++) {
+      walkNode(list[index], `${path}[${index}]`)
       if (count >= cap) return
-      if (!declared(item)) continue
-      count += 1
-      const v = obj(item)
-      if (v === undefined) continue
-      if (v.type === 'tabs' && Array.isArray(v.tabs)) {
-        for (const t of v.tabs) walkItemsOf(t)
-      } else if (v.type === 'accordion' && Array.isArray(v.items)) {
-        for (const it of v.items) walkItemsOf(it)
-      } else if ((v.type === 'row' || v.type === 'col' || v.type === 'grid' || v.type === 'card') && Array.isArray(v.items)) {
-        walk(v.items)
-      } else if (v.type === 'list' && Array.isArray(v.items)) {
-        for (const li of v.items) {
-          if (declared(li)) walk([li])
-        }
+    }
+  }
+  function walkNode(item: unknown, at: string): void {
+    if (count >= cap || !declared(item)) return
+    const v = obj(item)
+    if (v === undefined) return
+    count += 1
+    visit(v, at)
+    if (v.type === 'tabs' && Array.isArray(v.tabs)) {
+      for (let tab = 0; tab < v.tabs.length; tab++) {
+        walkItemsOf(v.tabs[tab], `${at}.tabs[${tab}]`)
+      }
+    } else if (v.type === 'accordion' && Array.isArray(v.items)) {
+      for (let row = 0; row < v.items.length; row++) {
+        walkItemsOf(v.items[row], `${at}.items[${row}]`)
+      }
+    } else if ((v.type === 'row' || v.type === 'col' || v.type === 'grid' || v.type === 'card') && Array.isArray(v.items)) {
+      walk(v.items, `${at}.items`)
+    } else if (v.type === 'list' && Array.isArray(v.items)) {
+      for (let row = 0; row < v.items.length; row++) {
+        walkNode(v.items[row], `${at}.items[${row}]`)
       }
     }
   }
-  const walkItemsOf = (holder: unknown): void => {
+  function walkItemsOf(holder: unknown, path: string): void {
     const o = obj(holder)
     if (o === undefined) return
     const items = o.items !== undefined ? o.items : o.content
-    if (Array.isArray(items)) walk(items)
-    else if (declared(items)) walk([items])
+    if (Array.isArray(items)) walk(items, `${path}.items`)
+    else walkNode(items, `${path}.items`)
   }
   const root = obj(value)
   if (root === undefined) return count
   // Single-component root (no items array): the root itself is the declared node.
-  if (!Array.isArray(root.items) && declared(value)) walk([value])
-  else walk(root.items)
+  if (!Array.isArray(root.items) && declared(value)) walkNode(value, 'spec')
+  else walk(root.items, 'items')
   return count
 }
 
+/**
+ * Count white-listed nodes declared by a raw spec before repair drops invalid entries.
+ * @param value - raw GenUI spec.
+ * @param cap - traversal ceiling.
+ * @returns declared node count up to the ceiling.
+ */
+export function countDeclaredGenuiNodes(value: unknown, cap = Number.POSITIVE_INFINITY): number {
+  return visitDeclaredGenuiNodes(value, cap, () => {})
+}
+
+/**
+ * Return field-level chart errors without changing other repairable component families.
+ * @param value - raw GenUI spec.
+ * @returns chart semantic errors in tree order.
+ */
+export function validateGenuiChartSemantics(value: unknown): string[] {
+  const errors: string[] = []
+  visitDeclaredGenuiNodes(value, GENUI_LIMITS.maxNodes + 1, (node, at) => {
+    if (node.type !== 'chart') return
+    validateChartNode(node, at, errors)
+  })
+  return errors
+}
+
 /**
  * Validate a raw spec value against the white list and limits, collecting
  * human-readable problems. Unlike repair this never mutates: it is a
@@ -1281,6 +1324,59 @@ export function validateGenuiSpec(value: unknown): GenuiValidation {
 
 type Walker = (list: unknown, depth: number, path: string) => void
 
+function validateChartData(value: unknown, at: string, errors: string[]): void {
+  if (!Array.isArray(value)) return
+  for (let index = 0; index < value.length; index++) {
+    const datum = obj(value[index])
+    const path = `${at}[${index}]`
+    if (datum === undefined) {
+      errors.push(`${path} must be an object`)
+      continue
+    }
+    if (typeof datum.label !== 'string') errors.push(`${path}.label must be a string`)
+    if (typeof datum.value !== 'number' || !Number.isFinite(datum.value)) {
+      errors.push(`${path}.value must be a finite number`)
+    }
+    if (datum.color !== undefined && typeof datum.color !== 'string') {
+      errors.push(`${path}.color must be a string`)
+    }
+  }
+}
+
+function validateChartSeries(value: unknown, at: string, errors: string[]): void {
+  if (!Array.isArray(value)) return
+  for (let index = 0; index < value.length; index++) {
+    const series = obj(value[index])
+    const path = `${at}[${index}]`
+    if (series === undefined) {
+      errors.push(`${path} must be an object`)
+      continue
+    }
+    if (typeof series.label !== 'string') errors.push(`${path}.label must be a string`)
+    if (series.color !== undefined && typeof series.color !== 'string') {
+      errors.push(`${path}.color must be a string`)
+    }
+    if (!Array.isArray(series.data)) errors.push(`${path}.data must be an array`)
+    validateChartData(series.data, `${path}.data`, errors)
+  }
+}
+
+function validateChartNode(v: Record<string, unknown>, at: string, errors: string[]): void {
+  if (!Array.isArray(v.data) && !Array.isArray(v.series)) {
+    errors.push(`${at}: type 'chart' requires data or series (array)`)
+  }
+  if (v.variant !== undefined) errors.push(`${at}.variant is unsupported; use kind`)
+  if (v.data !== undefined && !Array.isArray(v.data)) errors.push(`${at}.data must be an array`)
+  if (v.series !== undefined && !Array.isArray(v.series)) errors.push(`${at}.series must be an array`)
+  if (v.kind !== undefined
+    && (typeof v.kind !== 'string'
+      || !CHART_KINDS.includes(v.kind as typeof CHART_KINDS[number]))) {
+    errors.push(`${at}.kind must be bars, line, or donut`)
+  }
+  validateChartData(v.data, `${at}.data`, errors)
+  validateChartSeries(v.series, `${at}.series`, errors)
+}
+
 function validateNode(value: unknown, depth: number, at: string, errors: string[], walk: Walker): void {
   if (depth > GENUI_LIMITS.maxDepth) {
     errors.push(`${at}: exceeds max depth ${GENUI_LIMITS.maxDepth}`)
@@ -1315,7 +1411,7 @@ function validateNode(value: unknown, depth: number, at: string, errors: string[
       if (typeof v.label !== 'string') errors.push(`${at}: type '${type}' requires label (string)`)
       isStr('label')
       break
-    case 'audio': case 'video':
+    case 'image': case 'audio': case 'video':
       if (typeof v.src !== 'string') errors.push(`${at}: type '${type}' requires src (string)`)
       isStr('src')
       isStr('alt')
@@ -1378,7 +1474,7 @@ function validateNode(value: unknown, depth: number, at: string, errors: string[
       if (!Array.isArray(v.rows)) errors.push(`${at}: type 'table' requires rows (array)`)
       break
     case 'chart':
-      if (!Array.isArray(v.data) && !Array.isArray(v.series)) errors.push(`${at}: type 'chart' requires data or series (array)`)
+      validateChartNode(v, at, errors)
       break
     case 'tabs': {
       if (!Array.isArray(v.tabs)) errors.push(`${at}: type 'tabs' requires tabs (array)`)

package/src/client/panel-command.ts

@@ -103,11 +103,20 @@ export function createPanelSlashSource(sendInstruction: (sessionId: SessionId, i
     trigger: '/',
     name: 'genui',
     order: 60,
-    candidates: async (_session, _req) => [{
-      name: 'panel',
-      description: '开启 GenUI 面板（/panel clear 清空；/panel <指令> 定制内容）',
-      hint: '/panel',
-    }],
+    candidates: async (_session, req) => {
+      // Filter by query prefix: once the user types past "panel" the genui
+      // group must disappear. Unfiltered candidates kept this group the only
+      // ready non-empty group for unmatched queries, so the menu's default
+      // highlight fell through to `panel` and Enter picked it instead of the
+      // intended command/skill candidate.
+      const query = req.query.toLowerCase()
+      if (query !== '' && !'panel'.startsWith(query)) return []
+      return [{
+        name: 'panel',
+        description: '开启 GenUI 面板（/panel clear 清空；/panel <指令> 定制内容）',
+        hint: '/panel',
+      }]
+    },
     onPick(pick) {
       return { claim: panelClaim(pick.session.sessionId, sendInstruction) }
     },

package/src/client/parse-partial.ts

@@ -8,9 +8,10 @@
  * 1. Full parse first (the common settled case) — at most one.
  * 2. ONE left-to-right scan collects the repair candidates: every position
  *    where the prefix is bracket-balanced (trailing comma / fence tail) and
- *    every `}` object close within the depth budget (an unfinished trailing
- *    element, closed by appending the remaining brackets). The ring buffer
- *    keeps only the longest-direction candidates (≤ MAX_PARTIAL_REPAIR_ATTEMPTS),
+ *    every top-level `items[]` component close (an unfinished trailing
+ *    component is dropped by closing the root array/object). Partial candidates
+ *    must parse as a spec root; bare components wait for their own root close.
+ *    The ring buffer keeps only the longest-direction candidates (≤ MAX_PARTIAL_REPAIR_ATTEMPTS),
  *    so the work is O(n) with a hard parse-attempt cap — a pathological
  *    input can never re-scan prefixes or burn seconds in JSON.parse.
  * 3. Candidates are tried longest first; the first that parses as a GenUI
@@ -19,11 +20,10 @@
  * The result is only ever a PREFIX of the intended spec, so it is always
  * safe to render: components already present are complete and valid.
  *
- * `ponytail:` the 32-candidate / 33-parse budget is the protection ceiling
- * for depth 8 / 200 nodes; only real streaming samples proving a recovery
- * shortfall justify switching to a tokenizing parser.
+ * `ponytail:` the 32-candidate / 33-parse budget is the protection ceiling;
+ * only real streaming samples proving a recovery shortfall justify switching
+ * to a tokenizing parser.
  */
-import { GENUI_LIMITS } from './guard.ts'
 import { isGenuiSpec, type GenuiSpec } from './spec.ts'
 import { wrapSingleComponentRoot } from './spec.ts'
 
@@ -48,9 +48,9 @@ export interface PartialCandidate {
  *  (skipping strings/escapes correctly) and records:
  *  - every position where the prefix is fully balanced (trailing comma or
  *    fence tail) — candidate with an empty closing suffix;
- *  - every `}` object close whose remaining depth fits the spec budget —
- *    candidate with the remaining brackets closed (an unfinished trailing
- *    element).
+ *  - every top-level `items[]` component close — candidate with the root
+ *    array/object closed (an unfinished trailing component is dropped). Nested
+ *    object closes are not candidates because their component is still partial.
  *  Candidates are ring-buffered to the attempts budget (the LAST pushes are
  *  the longest), then returned longest-first, deduplicated by end. The scan
  *  stops at the first unbalanced close — earlier balanced prefixes remain
@@ -93,10 +93,11 @@ export function collectPartialCandidates(raw: string): { candidates: PartialCand
         // balanced prefixes recorded earlier stay valid. Stop scanning.
         break
       }
-      if (ch === '}' && stack.length <= GENUI_LIMITS.maxDepth) {
-        // A finished object element: closing the remaining brackets yields
-        // the longest legal prefix (an unfinished trailing element drops).
-        push({ end: scanned + 1, closingSuffix: closeSuffix(stack) })
+      if (ch === '}' && stack.length === 2 && stack[0] === '{' && stack[1] === '[') {
+        // Only a direct root-array member can be a finished component.
+        // Partial parsing later requires an actual spec root, so a bare
+        // component's data[] member cannot become a candidate.
+        push({ end: scanned + 1, closingSuffix: ']}' })
       }
       if (stack.length === 0) {
         // Whole prefix balanced: a complete-JSON candidate (trailing comma /
@@ -114,22 +115,15 @@ export function collectPartialCandidates(raw: string): { candidates: PartialCand
   return { candidates: deduped.slice(0, repairAttemptsLimit), scannedChars: scanned }
 }
 
-/** Closing brackets for the remaining open stack (top first). */
-function closeSuffix(stack: string[]): string {
-  let suffix = ''
-  for (let i = stack.length - 1; i >= 0; i--) suffix += stack[i] === '{' ? '}' : ']'
-  return suffix
-}
-
 /** Try to parse a candidate as a GenuiSpec. */
-function trySpec(candidate: string): GenuiSpec | null {
+function trySpec(candidate: string, allowSingleComponentRoot: boolean): GenuiSpec | null {
   try {
     const value: unknown = JSON.parse(candidate)
     if (isGenuiSpec(value)) return value
     // Single-component roots are part of the documented fence vocabulary
     // (e.g. a bare {"type":"callout",…} body) — wrap into a col so the
     // items-gated pipeline renders them (panel/append hoisted).
-    return wrapSingleComponentRoot(value)
+    return allowSingleComponentRoot ? wrapSingleComponentRoot(value) : null
   } catch {
     return null
   }
@@ -146,14 +140,14 @@ export function parsePartialGenuiSpec(raw: string): GenuiSpec | null {
   if (text === '') return null
 
   // 1. Full parse (settled / already-complete body).
-  const full = trySpec(text)
+  const full = trySpec(text, true)
   if (full !== null) return full
 
   // 2. Bounded repair: ONE forward scan, at most `repairAttemptsLimit`
   //    candidates, longest first — never a re-scan per `}`.
   const { candidates } = collectPartialCandidates(text)
   for (const candidate of candidates) {
-    const spec = trySpec(text.slice(0, candidate.end) + candidate.closingSuffix)
+    const spec = trySpec(text.slice(0, candidate.end) + candidate.closingSuffix, false)
     if (spec !== null) return spec
   }
 

package/src/client/safe-math.ts

@@ -139,7 +139,35 @@ class SafeMathParser {
 
   private parseNumber(): number {
     const start = this.i
-    while (this.i < this.src.length && /[0-9.eE+\-]/.test(this.src[this.i]!)) this.i++
+    let sawDigit = false
+
+    while (this.i < this.src.length && /[0-9]/.test(this.src[this.i]!)) {
+      sawDigit = true
+      this.i++
+    }
+
+    if (this.peek() === '.') {
+      this.i++
+      while (this.i < this.src.length && /[0-9]/.test(this.src[this.i]!)) {
+        sawDigit = true
+        this.i++
+      }
+    }
+
+    if (!sawDigit) {
+      throw new ParseError(`invalid number '${this.src.slice(start, this.i)}'`, start)
+    }
+
+    if (this.peek() === 'e' || this.peek() === 'E') {
+      this.i++
+      if (this.peek() === '+' || this.peek() === '-') this.i++
+      const exponentStart = this.i
+      while (this.i < this.src.length && /[0-9]/.test(this.src[this.i]!)) this.i++
+      if (this.i === exponentStart) {
+        throw new ParseError(`invalid number '${this.src.slice(start, this.i)}'`, start)
+      }
+    }
+
     const text = this.src.slice(start, this.i)
     const value = Number(text)
     if (Number.isNaN(value)) throw new ParseError(`invalid number '${text}'`, start)

package/src/client/scene3d-core.ts

@@ -135,8 +135,11 @@ export async function mountScene(container: HTMLElement, scene: GenuiScene3D): P
   }
   const onPointerMove = (e: PointerEvent): void => {
     if (!isDragging) return
-    theta -= (e.clientX - prevX) * 0.01
-    phi = Math.max(0.1, Math.min(Math.PI - 0.1, phi + (e.clientY - prevY) * 0.01))
+    // Drag follows the cursor (standard orbit feel): dragging right/left
+    // sweeps the azimuth with the pointer, dragging up/down tilts the polar
+    // angle with the pointer (phi grows from +Y down toward the equator).
+    theta += (e.clientX - prevX) * 0.01
+    phi = Math.max(0.1, Math.min(Math.PI - 0.1, phi - (e.clientY - prevY) * 0.01))
     prevX = e.clientX
     prevY = e.clientY
     orbit()

package/src/client/spec.ts

@@ -21,6 +21,7 @@ export type GenuiNode =
   | GenuiSelect
   | GenuiCheckbox
   | GenuiLink
+  | GenuiImage
   | GenuiAudio
   | GenuiVideo
   | GenuiBadge
@@ -151,6 +152,14 @@ export interface GenuiLink {
   href?: string
 }
 
+/** User-controlled image from a browser-reachable URL. */
+export interface GenuiImage {
+  type: 'image'
+  src: string
+  /** Visible caption and accessible image description. */
+  alt?: string
+}
+
 /** User-controlled audio from a browser-reachable URL. */
 export interface GenuiAudio {
   type: 'audio'
@@ -517,7 +526,6 @@ export interface GenuiScene3D {
 }
 
 /* ---------------- v1.4: more content structure ---------------- */
-
 export interface GenuiTimelineItem {
   /** Title of the event. */
   title: string

package/src/plugin/chart-contract.ts

@@ -0,0 +1,103 @@
+import { validateGenuiChartSemantics } from '../client/guard.ts'
+
+/** Plain object helper for raw model-authored specs. */
+function obj(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+/**
+ * Visit chart nodes through the component-bearing containers understood by
+ * the GenUI guard. This deliberately does not recursively inspect arbitrary
+ * objects (for example `json.value` or `echart.option`), where a nested
+ * `{type:"chart"}` is data rather than a GenUI node.
+ */
+function visitChartNodes(
+  value: unknown,
+  visit: (node: Record<string, unknown>, at: string) => void,
+): void {
+  function walkNode(value: unknown, at: string): void {
+    const node = obj(value)
+    if (node === undefined || typeof node.type !== 'string') return
+    if (node.type === 'chart') visit(node, at)
+
+    if ((node.type === 'row' || node.type === 'col' || node.type === 'grid' || node.type === 'card') && Array.isArray(node.items)) {
+      walk(node.items, `${at}.items`)
+      return
+    }
+    if (node.type === 'tabs' && Array.isArray(node.tabs)) {
+      for (let index = 0; index < node.tabs.length; index++) {
+        const tab = obj(node.tabs[index])
+        if (tab === undefined) continue
+        const items = tab.items !== undefined ? tab.items : tab.content
+        if (Array.isArray(items)) walk(items, `${at}.tabs[${index}].items`)
+        else walkNode(items, `${at}.tabs[${index}].items`)
+      }
+      return
+    }
+    if (node.type === 'accordion' && Array.isArray(node.items)) {
+      for (let index = 0; index < node.items.length; index++) {
+        const item = obj(node.items[index])
+        if (item === undefined) continue
+        const items = item.items !== undefined ? item.items : item.content
+        if (Array.isArray(items)) walk(items, `${at}.items[${index}].items`)
+        else walkNode(items, `${at}.items[${index}].items`)
+      }
+      return
+    }
+    if (node.type === 'list' && Array.isArray(node.items)) {
+      for (let index = 0; index < node.items.length; index++) {
+        walkNode(node.items[index], `${at}.items[${index}]`)
+      }
+    }
+  }
+
+  function walk(list: unknown, path: string): void {
+    if (!Array.isArray(list)) return
+    for (let index = 0; index < list.length; index++) {
+      walkNode(list[index], `${path}[${index}]`)
+    }
+  }
+
+  const root = obj(value)
+  if (root === undefined) return
+  if (!Array.isArray(root.items) && root.type === 'chart') walkNode(root, 'spec')
+  else walk(root.items, 'items')
+}
+
+/**
+ * Validate the native chart contract all the way to something the renderer
+ * can actually draw. The shared guard still owns field/type validation; this
+ * layer adds renderer-specific invariants that would otherwise produce an
+ * empty line/donut chart or a grouped-bars shell with no points.
+ */
+export function validateRenderableChartSemantics(value: unknown): string[] {
+  const errors = validateGenuiChartSemantics(value)
+  visitChartNodes(value, (node, at) => {
+    const kind = node.kind === undefined ? 'bars' : node.kind
+
+    if (Array.isArray(node.data) && node.data.length === 0) {
+      errors.push(`${at}.data must not be empty`)
+    }
+    if (Array.isArray(node.series)) {
+      if (node.series.length === 0) errors.push(`${at}.series must not be empty`)
+      for (let index = 0; index < node.series.length; index++) {
+        const series = obj(node.series[index])
+        if (series !== undefined && Array.isArray(series.data) && series.data.length === 0) {
+          errors.push(`${at}.series[${index}].data must not be empty`)
+        }
+      }
+    }
+
+    if (kind === 'line' || kind === 'donut') {
+      if (node.series !== undefined) {
+        errors.push(`${at}.series is only supported for bars`)
+      }
+      if (node.data === undefined) {
+        errors.push(`${at}.data is required for ${kind}`)
+      }
+    }
+  })
+  return errors
+}