@changfenhuang/dsh-genui 0.9.3 → 0.9.7

package/src/client/blocks/advanced.tsx

@@ -121,8 +121,13 @@ export function TabsNode({ tabs, onAction, depth = 0, answers }: {
   const [active, setActive] = useState(0)
   const uid = useId()
   const list = tabs.tabs.slice(0, GENUI_LIMITS.maxTabs)
-  const current = list[active]
+  const safeActive = list.length === 0 ? 0 : Math.min(active, list.length - 1)
+  const current = list[safeActive]
+  useEffect(() => {
+    if (safeActive !== active) setActive(safeActive)
+  }, [active, safeActive])
   const move = (next: number): void => {
+    if (list.length === 0) return
     const n = (next + list.length) % list.length
     setActive(n)
     document.getElementById(`${uid}-tab-${n}`)?.focus()
@@ -134,8 +139,8 @@ export function TabsNode({ tabs, onAction, depth = 0, answers }: {
         role="tablist"
         aria-orientation="horizontal"
         onKeyDown={e => {
-          if (e.key === 'ArrowRight') { e.preventDefault(); move(active + 1) }
-          else if (e.key === 'ArrowLeft') { e.preventDefault(); move(active - 1) }
+          if (e.key === 'ArrowRight') { e.preventDefault(); move(safeActive + 1) }
+          else if (e.key === 'ArrowLeft') { e.preventDefault(); move(safeActive - 1) }
           else if (e.key === 'Home') { e.preventDefault(); move(0) }
           else if (e.key === 'End') { e.preventDefault(); move(list.length - 1) }
         }}
@@ -146,10 +151,10 @@ export function TabsNode({ tabs, onAction, depth = 0, answers }: {
             id={`${uid}-tab-${i}`}
             type="button"
             role="tab"
-            aria-selected={i === active}
+            aria-selected={i === safeActive}
             aria-controls={`${uid}-panel-${i}`}
-            tabIndex={i === active ? 0 : -1}
-            className={`${css.tab} ${i === active ? css.tabActive : ''}`}
+            tabIndex={i === safeActive ? 0 : -1}
+            className={`${css.tab} ${i === safeActive ? css.tabActive : ''}`}
             onClick={() => setActive(i)}
           >
             {tab.label}
@@ -157,7 +162,7 @@ export function TabsNode({ tabs, onAction, depth = 0, answers }: {
         ))}
       </div>
       {current !== undefined && (
-        <div className={css.col} role="tabpanel" id={`${uid}-panel-${active}`} aria-labelledby={`${uid}-tab-${active}`}>
+        <div className={css.col} role="tabpanel" id={`${uid}-panel-${safeActive}`} aria-labelledby={`${uid}-tab-${safeActive}`}>
           {current.items.map((c, i) => renderNode(c, i, onAction, depth + 1, answers))}
         </div>
       )}
@@ -264,26 +269,32 @@ export const CopyNode = memo(function CopyNode({ node }: { node: GenuiCopy }) {
   )
 })
 
+type MermaidRenderState =
+  | { status: 'loading' }
+  | { status: 'ready'; html: string }
+  | { status: 'error' }
+
 /** Mermaid: lazily loaded diagram renderer. */
 export const MermaidNode = memo(function MermaidNode({ node }: { node: GenuiMermaid }) {
-  const [html, setHtml] = useState<string | null>(null)
-  const [failed, setFailed] = useState(false)
+  const [state, setState] = useState<MermaidRenderState>({ status: 'loading' })
   const code = node.code.slice(0, GENUI_LIMITS.maxMermaid)
   useEffect(() => {
     let alive = true
-    void import('../mermaid-lazy.ts').then(async m => {
+    setState({ status: 'loading' })
+    void (async () => {
       try {
+        const m = await import('../mermaid-lazy.ts')
         const svg = await m.renderMermaid(code)
-        if (alive) setHtml(svg)
+        if (alive) setState({ status: 'ready', html: svg })
       } catch {
-        if (alive) setFailed(true)
+        if (alive) setState({ status: 'error' })
       }
-    })
+    })()
     return () => { alive = false }
   }, [code])
-  if (failed) return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidErr}>图语法有误，已降级显示源码</div></div>
-  if (html === null) return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidHint}>渲染中…</div></div>
-  return <div className={css.mermaid} dangerouslySetInnerHTML={{ __html: html }} data-genui-mermaid />
+  if (state.status === 'error') return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidErr}>图语法有误，已降级显示源码</div></div>
+  if (state.status === 'loading') return <div className={css.mermaidFallback}><pre>{code}</pre><div className={css.mermaidHint}>渲染中…</div></div>
+  return <div className={css.mermaid} dangerouslySetInnerHTML={{ __html: state.html }} data-genui-mermaid />
 })
 
 /** Scene3D: three.js WebGL canvas, lazily imported. */
@@ -346,7 +357,6 @@ export const TimelineNode = memo(function TimelineNode({ node }: { node: GenuiTi
  * — click a dir to fold/unfold, default fully open. Zero model round trip. */
 export const FileTreeNode = memo(function FileTreeNode({ node }: { node: GenuiFileTree }) {
   const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(new Set())
-  const pathKey = (depth: number, i: number): string => `${depth}-${i}`
   const toggle = (k: string): void => {
     setCollapsed(prev => {
       const next = new Set(prev)
@@ -355,27 +365,26 @@ export const FileTreeNode = memo(function FileTreeNode({ node }: { node: GenuiFi
       return next
     })
   }
-  const renderNode = (n: GenuiFileTreeNode, depth: number, i: number): ReactNode => {
+  const renderNode = (n: GenuiFileTreeNode, depth: number, path: string): ReactNode => {
     if (depth > GENUI_LIMITS.maxTreeDepth) return null
     const isDir = n.type === 'dir' || (n.children !== undefined && n.children.length > 0)
-    const k = pathKey(depth, i)
-    const folded = isDir && collapsed.has(k)
+    const folded = isDir && collapsed.has(path)
     return (
-      <div key={k} className={css.ftRow} style={{ paddingLeft: `${depth * 16}px` }}>
+      <div key={path} className={css.ftRow} style={{ paddingLeft: `${depth * 16}px` }}>
         <button
           type="button"
           className={css.ftNameBtn}
           aria-expanded={isDir ? !folded : undefined}
-          onClick={isDir ? () => toggle(k) : undefined}
+          onClick={isDir ? () => toggle(path) : undefined}
         >
           <span className={`${css.ftIcon} ${isDir ? css.ftIconDir : ''}`} aria-hidden>{isDir ? (folded ? '▸' : '▾') : '·'}</span>
           <span className={`${css.ftName} ${isDir ? css.ftDir : ''}`}>{n.name}</span>
         </button>
-        {isDir && !folded && (n.children ?? []).map((c, ci) => renderNode(c, depth + 1, ci))}
+        {isDir && !folded && (n.children ?? []).map((c, ci) => renderNode(c, depth + 1, `${path}/${ci}`))}
       </div>
     )
   }
-  return <div className={css.fileTree}>{node.items.slice(0, GENUI_LIMITS.maxListItems).map((n, i) => renderNode(n, 0, i))}</div>
+  return <div className={css.fileTree}>{node.items.slice(0, GENUI_LIMITS.maxListItems).map((n, i) => renderNode(n, 0, String(i)))}</div>
 })
 
 /** Quiz: a self-contained teaching question. Selecting an option marks it
@@ -464,4 +473,4 @@ export const BreadcrumbNode = memo(function BreadcrumbNode({ node }: { node: Gen
  * names stay independent. The model round-trip takes seconds, so a few
  * hundred ms of trailing delay is imperceptible — and it stops bursts of
  * queued user turns.
- */
+ */

package/src/client/blocks/charts.tsx

@@ -138,7 +138,7 @@ export const BarsNode = memo(function BarsNode({ chart }: { chart: GenuiChart })
     const labels = grouped[0]!.data.map(d => d.label)
     const max = Math.max(...grouped.flatMap(s => s.data.map(d => Number(d.value) || 0)), 1)
     return (
-      <div className={css.chart}>
+      <div className={css.chart} data-genui-chart="bars">
         <div className={css.chartPlot}>
           {[0, 25, 50, 75].map(p => (
             <span key={p} className={p === 0 ? css.baseline : css.gridline} style={{ bottom: `${p}%` }} />
@@ -181,7 +181,7 @@ export const BarsNode = memo(function BarsNode({ chart }: { chart: GenuiChart })
   // and used to collapse the bar entirely.
   const max = Math.max(...data.map(d => Number(d.value) || 0), 1)
   return (
-    <div className={css.chart}>
+    <div className={css.chart} data-genui-chart="bars">
       <div className={css.chartPlot}>
         {[0, 25, 50, 75].map(p => (
           <span key={p} className={p === 0 ? css.baseline : css.gridline} style={{ bottom: `${p}%` }} />
@@ -233,7 +233,7 @@ export const LineChartNode = memo(function LineChartNode({ chart }: { chart: Gen
     return t.toFixed(1)
   }
   return (
-    <div className={css.lineChart}>
+    <div className={css.lineChart} data-genui-chart="line">
       <svg width="100%" viewBox={`0 0 ${W} ${H}`}>
         {ticks.map((t, i) => {
           const y = padT + (1 - (t - min) / span) * (H - padT - padB)
@@ -277,7 +277,7 @@ export const DonutNode = memo(function DonutNode({ chart }: { chart: GenuiChart
   const C = 2 * Math.PI * R
   let offset = 0
   return (
-    <div className={css.donut}>
+    <div className={css.donut} data-genui-chart="donut">
       <svg width="120" height="120" viewBox="0 0 120 120">
         <circle cx="60" cy="60" r={R} fill="none" strokeWidth="14" className={css.donutTrack} />
         {clamped.map((d, i) => {

package/src/client/blocks/image.tsx

@@ -0,0 +1,25 @@
+import { useState, type ReactNode } from 'react'
+import css from '../GenuiBlock.module.css'
+import type { GenuiImage } from '../spec.ts'
+
+/** Native image display; source safety is enforced by repairGenuiSpec/safeMediaSrc. */
+export function ImageNode({ node }: { node: GenuiImage }): ReactNode {
+  const [failed, setFailed] = useState(false)
+
+  return (
+    <figure className={css.media}>
+      {node.alt !== undefined && <figcaption className={css.mediaLabel}>{node.alt}</figcaption>}
+      {failed
+        ? <div className={css.mediaError} role="alert">图片无法加载</div>
+        : <img
+            className={css.mediaPlayer}
+            src={node.src}
+            alt={node.alt ?? '图片'}
+            loading="lazy"
+            decoding="async"
+            style={{ maxHeight: 'min(70vh, 720px)', objectFit: 'contain' }}
+            onError={() => setFailed(true)}
+          />}
+    </figure>
+  )
+}

package/src/client/blocks/render-node.tsx

@@ -20,6 +20,7 @@ import {
   MermaidNode, PlotNode, QuizNode, Scene3DNode, StepsNode, TabsNode, TimelineNode,
 } from './advanced.tsx'
 import { DiagramNode } from './diagram/index.tsx'
+import { ImageNode } from './image.tsx'
 
 import { EChartNode } from '../EChartNode.tsx'
 
@@ -58,6 +59,7 @@ export function renderNode(
   // against the same limit; this is the belt-and-suspenders for direct
   // GenuiBlock use and plugin-registered custom renderers.
   if (depth > GENUI_LIMITS.maxDepth) return null
+
   switch (node.type) {
     case 'text': {
       const size = node.size ?? 'body'
@@ -143,6 +145,7 @@ export function renderNode(
         ? <a key={key} className={css.link} href={href} target="_blank" rel="noopener noreferrer">{node.label}</a>
         : <span key={key} className={css.linkText}>{node.label}</span>
     }
+    case 'image': return <ImageNode key={`${key}:${node.src}`} node={node} />
     case 'audio': return <AudioNode key={`${key}:${node.src}`} node={node} />
     case 'video': return <VideoNode key={`${key}:${node.src}`} node={node} />
     case 'badge': {

package/src/client/blocks/state.ts

@@ -20,6 +20,8 @@ export interface GenuiBlockProps {
    * v2.7: durable-state key (session + slot + content fingerprint). When set,
    * interaction state (radio answers, submit lock, field values) persists to
    * localStorage and restores on refresh / re-render of the same content.
+   * Changing this key also starts a fresh in-memory interaction-state lifetime;
+   * callers only provide stateKey — GenuiBlock owns the matching React identity.
    */
   stateKey?: string | undefined
 }

package/src/client/dom-fence.tsx

@@ -354,6 +354,8 @@ export function installDomFenceRenderer(
   driftWarned = false
   plausibilityWarned = false
   const mounts = new Map<HTMLElement, Mount>()
+  let disposed = false
+  let rafId: number | null = null
 
   const sessionIdOf = (): SessionId | undefined => {
     try {
@@ -513,6 +515,7 @@ export function installDomFenceRenderer(
    * the streaming→settled transition), repair surgery, then take over every
    * new dsh-ui block — settled or still streaming. */
   function sweep(): void {
+    if (disposed) return
     for (const [block, mount] of mounts) {
       if (!block.isConnected) {
         unmountBlock(block)
@@ -605,12 +608,11 @@ export function installDomFenceRenderer(
     }
   }
 
-  let scheduled = false
   const schedule = (): void => {
-    if (scheduled) return
-    scheduled = true
-    requestAnimationFrame(() => {
-      scheduled = false
+    if (disposed || rafId !== null) return
+    rafId = requestAnimationFrame(() => {
+      rafId = null
+      if (disposed) return
       sweep()
     })
   }
@@ -634,8 +636,13 @@ export function installDomFenceRenderer(
   sweep()
 
   return () => {
+    disposed = true
     observer.disconnect()
     window.clearInterval(interval)
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId)
+      rafId = null
+    }
     for (const block of Array.from(mounts.keys())) unmountBlock(block)
   }
 }

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)`)