@seed-ship/mcp-ui-solid 5.5.1 → 5.7.0

package/src/components/StreamingUIRenderer.tsx

@@ -21,12 +21,13 @@
  * ```
  */
 
-import { Show, For, createSignal, onMount } from 'solid-js'
+import { Show, For, createSignal, onMount, onCleanup } from 'solid-js'
 import { useStreamingUI, type UseStreamingUIOptions } from '../hooks/useStreamingUI'
 import type { UIComponent, RendererError } from '../types'
 import { validateComponent } from '../services/validation'
 import { GenerativeUIErrorBoundary } from './GenerativeUIErrorBoundary'
-import { markRenderStart, markRenderEnd } from '../utils/perf'
+import { markRenderStart, markRenderEnd, PERF_PREFIX } from '../utils/perf'
+import { useTelemetry } from '../context/MCPUITelemetryContext'
 import type { ValidationErrorMode } from './UIResourceRenderer'
 
 export interface StreamingUIRendererProps extends UseStreamingUIOptions {
@@ -53,7 +54,47 @@ function StreamingComponentRenderer(props: {
 }) {
   // Performance marks (v5.4.0) — see utils/perf.ts
   markRenderStart(props.component.id)
-  onMount(() => markRenderEnd(props.component.id))
+
+  // Telemetry sink (B.5 — v5.6.0). Same wiring as ComponentRenderer in
+  // UIResourceRenderer.tsx — null when no Provider, no-op everywhere then.
+  const telemetry = useTelemetry()
+
+  onMount(() => {
+    markRenderEnd(props.component.id)
+    if (telemetry) {
+      const ts = Date.now()
+      telemetry.dispatch({
+        type: 'component:mounted',
+        id: props.component.id,
+        componentType: props.component.type,
+        ts,
+      })
+      if (typeof performance !== 'undefined' && typeof performance.getEntriesByName === 'function') {
+        const entries = performance.getEntriesByName(`${PERF_PREFIX}${props.component.id}:render`, 'measure')
+        const last = entries[entries.length - 1]
+        if (last) {
+          telemetry.dispatch({
+            type: 'component:rendered',
+            id: props.component.id,
+            componentType: props.component.type,
+            durationMs: last.duration,
+            ts,
+          })
+        }
+      }
+    }
+  })
+
+  onCleanup(() => {
+    if (telemetry) {
+      telemetry.dispatch({
+        type: 'component:unmounted',
+        id: props.component.id,
+        componentType: props.component.type,
+        ts: Date.now(),
+      })
+    }
+  })
 
   // Validate component before rendering
   const validation = validateComponent(props.component)
@@ -65,6 +106,17 @@ function StreamingComponentRenderer(props: {
       details: validation.errors,
     })
 
+    if (telemetry) {
+      telemetry.dispatch({
+        type: 'validation:failed',
+        id: props.component.id,
+        componentType: props.component.type,
+        errorCount: validation.errors?.length ?? 0,
+        firstErrorCode: validation.errors?.[0]?.code ?? null,
+        ts: Date.now(),
+      })
+    }
+
     const mode: ValidationErrorMode = props.errorMode ?? 'block'
     const firstError = validation.errors?.[0]?.message || 'Unknown validation error'
 

package/src/components/TableRenderer.citation.test.tsx

@@ -0,0 +1,157 @@
+/**
+ * Citation chip rendering inside `<TableRenderer>` cells (v5.7.0).
+ *
+ * Spec: `mcp-ui-solid/docs/briefs/BRIEF-citations-in-table-cells.md`.
+ *
+ * Tests are split between the pure `renderCellValue(value, citationCtx)`
+ * helper (fast, no DOM) and a couple of integration assertions on a real
+ * `<UIResourceRenderer>` mount to catch wiring bugs.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { render, cleanup } from '@solidjs/testing-library'
+import { renderCellValue, UIResourceRenderer } from './UIResourceRenderer'
+import type { CitationCtx } from './UIResourceRenderer'
+import type { UIComponent, TableComponentParams } from '../types'
+
+const baseMap: CitationCtx['map'] = {
+  '1': { page: 5, file: 'A.pdf' },
+  '2': { page: 12, file: 'B.pdf' },
+}
+
+describe('renderCellValue — citation transform (v5.7.0)', () => {
+  it('NO citationCtx → cell text is unchanged (regression)', () => {
+    expect(renderCellValue('[1] ; [4]')).toBe('[1] ; [4]')
+  })
+
+  it('citationCtx with mapped id → cell HTML carries data-citation-page + data-citation-doc', () => {
+    const html = renderCellValue('[1]', { map: baseMap })
+    expect(html).toContain('data-citation-page="5"')
+    expect(html).toContain('data-citation-doc="A.pdf"')
+    expect(html).toContain('data-citation-verified="true"')
+    expect(html).toContain('class="citation-ref')
+  })
+
+  it('multi-citation cell → multiple chips emitted', () => {
+    const html = renderCellValue('[1] ; [2]', { map: baseMap })
+    const matches = html.match(/data-citation-page="(\d+)"/g) ?? []
+    expect(matches).toHaveLength(2)
+    expect(html).toContain('data-citation-page="5"')
+    expect(html).toContain('data-citation-page="12"')
+  })
+
+  it('unresolved id with NON-EMPTY map → marker dropped silently (likely hallucination)', () => {
+    const html = renderCellValue('[99]', { map: baseMap })
+    expect(html).not.toContain('99')
+    expect(html).not.toContain('citation-ref')
+    expect(html).not.toContain('réf')
+  })
+
+  it('unresolved id with EMPTY map → human-visible `[réf. N]` placeholder', () => {
+    const html = renderCellValue('[99]', { map: {} })
+    expect(html).toContain('[réf. 99]')
+  })
+
+  it('citationRender override → wins over default chip shape', () => {
+    const html = renderCellValue('[1]', {
+      map: baseMap,
+      render: (id, mapping) => `<a class="custom-chip" data-id="${id}">${mapping?.file ?? '?'}</a>`,
+    })
+    expect(html).toContain('class="custom-chip"')
+    expect(html).toContain('data-id="1"')
+    expect(html).not.toContain('data-citation-verified')
+  })
+
+  it('`[p.5]` page form → NOT touched (negative lookbehind)', () => {
+    const html = renderCellValue('See [p.5]', { map: baseMap })
+    expect(html).toContain('[p.5]')
+    expect(html).not.toContain('data-citation-page')
+  })
+
+  it('`[text](url)` markdown link → NOT touched (citation regex skips parens)', () => {
+    const html = renderCellValue('[click](https://example.com)', { map: baseMap })
+    expect(html).toContain('href="https://example.com"')
+    expect(html).not.toContain('data-citation-page')
+  })
+
+  it('mixed `**bold** [1]` → bold becomes <strong> AND chip is rendered (compose)', () => {
+    const html = renderCellValue('**MSP** [1]', { map: baseMap })
+    expect(html).toContain('<strong>MSP</strong>')
+    expect(html).toContain('data-citation-page="5"')
+  })
+
+  it('canonical `[📄 CITATION 1]` marker → chip emitted directly (no normalize step needed)', () => {
+    const html = renderCellValue('[📄 CITATION 1]', { map: baseMap })
+    expect(html).toContain('data-citation-page="5"')
+  })
+
+  it('all 3 data-citation-* attrs survive DOMPurify (whitelist intact)', () => {
+    const html = renderCellValue('[1]', { map: baseMap })
+    expect(html).toContain('data-citation-page')
+    expect(html).toContain('data-citation-doc')
+    expect(html).toContain('data-citation-verified')
+  })
+
+  it('chip emits a button element (host click delegation target)', () => {
+    const html = renderCellValue('[1]', { map: baseMap })
+    expect(html).toContain('<button')
+    expect(html).toMatch(/<button[^>]*data-citation-page="5"/)
+  })
+})
+
+describe('<TableRenderer> — citationMap wiring (v5.7.0)', () => {
+  beforeEach(() => {
+    cleanup()
+  })
+
+  function tableComponent(params: Partial<TableComponentParams>): UIComponent {
+    return {
+      id: 'tbl-cit',
+      type: 'table',
+      position: { colStart: 1, colSpan: 12 },
+      params: {
+        columns: [
+          { key: 'name', label: 'Name' },
+          { key: 'cites', label: 'Citations' },
+        ],
+        rows: [
+          { name: 'MSP', cites: '[1] ; [2]' },
+          { name: 'Other', cites: '[1]' },
+        ],
+        ...params,
+      } as TableComponentParams,
+    }
+  }
+
+  it('NO citationMap → cells render plain text (regression)', () => {
+    const { container } = render(() => (
+      <UIResourceRenderer content={tableComponent({})} />
+    ))
+    const buttons = container.querySelectorAll('[data-citation-page]')
+    expect(buttons.length).toBe(0)
+    expect(container.textContent).toContain('[1] ; [2]')
+  })
+
+  it('with citationMap → DOM has clickable chips per resolved marker', () => {
+    const { container } = render(() => (
+      <UIResourceRenderer content={tableComponent({ citationMap: baseMap })} />
+    ))
+    const buttons = container.querySelectorAll('button[data-citation-page]')
+    // Row 1 has 2 markers, row 2 has 1 → 3 chips total
+    expect(buttons.length).toBe(3)
+    const pages = Array.from(buttons).map((b) => b.getAttribute('data-citation-page'))
+    expect(pages.sort()).toEqual(['12', '5', '5'])
+  })
+
+  it('with citationRender override → custom chips replace defaults', () => {
+    const customRender = (id: number) => `<a class="my-chip" data-id="${id}">x</a>`
+    const { container } = render(() => (
+      <UIResourceRenderer
+        content={tableComponent({ citationMap: baseMap, citationRender: customRender })}
+      />
+    ))
+    const customs = container.querySelectorAll('a.my-chip')
+    expect(customs.length).toBe(3)
+    expect(container.querySelector('[data-citation-page]')).toBeNull()
+  })
+})

package/src/components/UIResourceRenderer.tsx

@@ -4,12 +4,13 @@
  */
 
 import DOMPurify from 'dompurify'
-import { Component, createSignal, Show, For, createMemo, createEffect, onMount } from 'solid-js'
+import { Component, createSignal, Show, For, createMemo, createEffect, onMount, onCleanup } from 'solid-js'
 import { isServer } from 'solid-js/web'
 import type { UIComponent, UILayout, RendererError, TableVirtualizeOptions } from '../types'
 import { validateComponent, DEFAULT_RESOURCE_LIMITS, getIframeSandbox } from '../services/validation'
 import { GenerativeUIErrorBoundary } from './GenerativeUIErrorBoundary'
-import { markRenderStart, markRenderEnd } from '../utils/perf'
+import { markRenderStart, markRenderEnd, PERF_PREFIX } from '../utils/perf'
+import { useTelemetry } from '../context/MCPUITelemetryContext'
 
 /**
  * How `<UIResourceRenderer>` reacts when `validateComponent()` rejects a
@@ -286,7 +287,98 @@ export function highlightQuery(html: string, query: string): string {
   })
 }
 
-export function renderCellValue(value: any): string {
+/**
+ * Citation context — opt-in input to `renderCellValue` (v5.7.0).
+ *
+ * When passed, `[N]`, `Citation [N]`, `[CITATION N]` and `[📄 CITATION N]`
+ * markers in the cell text are normalized then replaced with chip HTML.
+ * Chips carry `data-citation-page`, `data-citation-doc`, and
+ * `data-citation-verified` attributes (already in the DOMPurify whitelist
+ * since v5.6.0) so a host's `target.closest('[data-citation-page]')`
+ * delegated click handler routes the click to the source-doc panel.
+ *
+ * See `mcp-ui-solid/docs/briefs/BRIEF-citations-in-table-cells.md`.
+ */
+export interface CitationCtx {
+  /**
+   * `Record<id, mapping>` keyed by the citation marker number (string-keyed
+   * because JSON serialization always produces strings; the runtime call
+   * sites accept either number or string ids and normalize internally).
+   */
+  map: Record<string | number, { page: number | string; file?: string; file_id?: number | string }>
+  /**
+   * Optional override returning sanitized chip HTML for one marker. Wins
+   * over the default `defaultCitationChip` shape. Function inputs are
+   * intentionally `any`-loose so consumers can swap shapes (e.g. web
+   * citations vs doc citations) without subtyping the entry shape here.
+   */
+  render?: (
+    id: number,
+    mapping: { page: number | string; file?: string; file_id?: number | string } | undefined
+  ) => string
+}
+
+/**
+ * Default chip HTML emitted by `transformCellCitations` when no
+ * `citationRender` override is supplied. Neutral Tailwind classes — hosts
+ * can override visual styling via the `.citation-ref` CSS class without
+ * passing a render override.
+ */
+function defaultCitationChip(
+  pageNum: number | string,
+  fileName: string,
+  verified = true
+): string {
+  const safeDocName = encodeURIComponent(fileName || '')
+  const label = fileName ? `${fileName} - ${pageNum}` : `${pageNum}`
+  if (!verified) {
+    return `<span class="citation-ref inline-flex items-center gap-0.5 align-middle opacity-60"><span class="text-gray-500 line-through">[${label}]</span></span>`
+  }
+  return [
+    '<span class="citation-ref inline-flex items-center gap-0.5 align-middle">',
+    `<span class="text-gray-500">[${label}]</span>`,
+    '<button class="inline-flex items-center ml-0.5 px-1 py-0.5 text-xs bg-gray-800 hover:bg-gray-700 border border-gray-600 hover:border-teal-500 rounded cursor-pointer transition-colors align-middle"',
+    ` data-citation-page="${pageNum}"`,
+    ` data-citation-doc="${safeDocName}"`,
+    ' data-citation-verified="true"',
+    ` title="View source - ${label}">`,
+    '<svg class="w-3 h-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/></svg>',
+    '</button>',
+    '</span>',
+  ].join('')
+}
+
+/**
+ * Normalize bare `[N]`, `Citation [N]`, `[CITATION N]` markers to canonical
+ * `[📄 CITATION N]` then replace each canonical marker with chip HTML.
+ *
+ * Negative lookbehind `(?<![p.])` skips `[p.5]` (page form). Negative
+ * lookahead `(?!\()` skips `[text](url)` markdown links.
+ */
+function transformCellCitations(text: string, ctx: CitationCtx): string {
+  // 1. normalize bare [N] / Citation [N] / [CITATION N] → [📄 CITATION N]
+  let out = text.replace(/(?<![p.])\[(\d{1,2})\](?!\()/g, '[📄 CITATION $1]')
+  out = out.replace(/\bCitations?\s*\[(\d+)\]/gi, '[📄 CITATION $1]')
+  out = out.replace(/\[CITATION\s+(\d+)\]/gi, '[📄 CITATION $1]')
+
+  // 2. replace each canonical marker with chip HTML
+  return out.replace(
+    /[【[]\s*📄\s*CITATION\s*(\d+)\s*[】\]]/gi,
+    (_m, idStr) => {
+      const id = parseInt(idStr, 10)
+      const mapping = ctx.map[id] ?? ctx.map[String(id)]
+      if (ctx.render) return ctx.render(id, mapping)
+      if (mapping) return defaultCitationChip(mapping.page, mapping.file ?? '', true)
+      // Unresolved id: when the map is non-empty (consumer claims to know
+      // the citations), drop silently — it's likely an LLM hallucination.
+      // When the map is empty (consumer didn't supply one), preserve a
+      // human-visible placeholder so the marker isn't lost.
+      return Object.keys(ctx.map).length > 0 ? '' : `[réf. ${id}]`
+    }
+  )
+}
+
+export function renderCellValue(value: any, citationCtx?: CitationCtx): string {
   // Handle null/undefined
   if (value === null || value === undefined) {
     return '-'
@@ -330,7 +422,9 @@ export function renderCellValue(value: any): string {
     return '-'
   }
 
-  // Detect and convert markdown links: [text](url)
+  // Detect and convert markdown links: [text](url) — runs FIRST because
+  // the citation transform's negative lookahead `(?!\()` would also skip
+  // these, but handling them here keeps the existing return path.
   const markdownLinkRegex = /\[([^\]]+)\]\(([^)]+)\)/g
   if (markdownLinkRegex.test(strValue)) {
     // Replace all markdown links with HTML links
@@ -341,8 +435,36 @@ export function renderCellValue(value: any): string {
     return DOMPurify.sanitize(htmlValue, { ADD_ATTR: ['target', 'rel'] })
   }
 
+  // v5.7.0 — citation transform (opt-in). Replaces `[N]` style markers
+  // with chip HTML carrying `data-citation-*` attrs. Runs BEFORE the
+  // hasHtml / hasMarkdown branches so the resulting string flows through
+  // them naturally (chips are inline HTML; surviving markdown like
+  // **bold** is preserved by marked.parse since marked passes inline HTML
+  // through unchanged).
+  if (citationCtx) {
+    strValue = transformCellCitations(strValue, citationCtx)
+  }
+
+  // Markdown markers WITHOUT square brackets — `[` and `]` were excluded
+  // because chip labels (`[Doc - 5]`) and unresolved-marker fallbacks
+  // (`[réf. 12]`) would otherwise force a marked.parse for cells that
+  // have no actual markdown. The hasMarkdown check ALSO runs before
+  // hasHtml so that mixed cells (`**bold** [1]` → `**bold** <chip>`)
+  // get marked first; marked preserves the inline chip HTML, then
+  // DOMPurify keeps the citation attrs via the extended whitelist.
+  const hasMarkdown = /[*_`#]/.test(strValue)
+  if (hasMarkdown) {
+    const parsed = marked.parse(strValue, { async: false }) as string
+    return DOMPurify.sanitize(parsed, {
+      ALLOWED_TAGS: ['a', 'strong', 'em', 'b', 'i', 'code', 'span', 'br', 'button', 'svg', 'path', 'p', 'ul', 'ol', 'li', 'pre', 'blockquote', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+      ALLOWED_ATTR: ['href', 'target', 'rel', 'class', 'data-citation-page', 'data-citation-source', 'data-citation-doc', 'data-citation-verified', 'title', 'fill', 'stroke', 'viewBox', 'stroke-linecap', 'stroke-linejoin', 'stroke-width', 'd'],
+      ADD_ATTR: ['target', 'rel'],
+    })
+  }
+
   // Detect raw HTML in cell values (e.g. <a href="..." data-citation-page="5">text</a>)
   // This handles cases where cell data comes from innerHTML extraction
+  // OR where the citation transform above injected chip HTML.
   const hasHtml = /<[a-z][\s\S]*>/i.test(strValue)
   if (hasHtml) {
     return DOMPurify.sanitize(strValue, {
@@ -352,14 +474,6 @@ export function renderCellValue(value: any): string {
     })
   }
 
-  // Check if value contains markdown formatting (bold, italic, code, etc.)
-  const hasMarkdown = /[*_`[\]#]/.test(strValue)
-  if (hasMarkdown) {
-    // Parse with marked and sanitize
-    const parsed = marked.parse(strValue, { async: false }) as string
-    return DOMPurify.sanitize(parsed, { ADD_ATTR: ['target', 'rel'] })
-  }
-
   // Plain text — sanitize to prevent XSS via innerHTML
   return DOMPurify.sanitize(strValue)
 }
@@ -375,6 +489,14 @@ function TableRenderer(props: {
   const tableParams = props.component.params as any
   let scrollContainerRef: HTMLDivElement | undefined
 
+  // v5.7.0 — opt-in citation chip rendering inside cells. When `citationMap`
+  // is present in params, build a CitationCtx once and thread it through
+  // every `renderCellValue` call below. Absent → undefined → cells render
+  // as before (regression-safe).
+  const citationCtx: CitationCtx | undefined = tableParams.citationMap
+    ? { map: tableParams.citationMap, render: tableParams.citationRender }
+    : undefined
+
   // ─── Client-side sorting (v4.0.5) ────────────────────────
   const allRows = () => tableParams.rows || []
   const columns = () => tableParams.columns || []
@@ -637,7 +759,7 @@ function TableRenderer(props: {
             <For each={tableParams.columns}>
               {(column: any) => (
                 <td class="px-6 py-4 text-sm text-gray-700 dark:text-gray-200 whitespace-normal break-words leading-relaxed first:pl-6 last:pr-6">
-                  <div innerHTML={highlightQuery(renderCellValue(row[column.key]), debouncedQuery())} />
+                  <div innerHTML={highlightQuery(renderCellValue(row[column.key], citationCtx), debouncedQuery())} />
                 </td>
               )}
             </For>
@@ -676,7 +798,7 @@ function TableRenderer(props: {
                 <For each={tableParams.columns}>
                   {(column: any) => (
                     <td class="px-6 py-4 text-sm text-gray-700 dark:text-gray-200 whitespace-normal break-words leading-relaxed first:pl-6 last:pr-6">
-                      <div innerHTML={highlightQuery(renderCellValue(row[column.key]), debouncedQuery())} />
+                      <div innerHTML={highlightQuery(renderCellValue(row[column.key], citationCtx), debouncedQuery())} />
                     </td>
                   )}
                 </For>
@@ -1133,7 +1255,51 @@ function ComponentRenderer(props: {
   // Performance marks — visible in Chrome DevTools "Performance" panel under
   // user timings. Always-on, SSR-safe (see utils/perf.ts).
   markRenderStart(props.component.id)
-  onMount(() => markRenderEnd(props.component.id))
+
+  // Telemetry sink (B.5 — v5.6.0). null when no MCPUITelemetryProvider is
+  // mounted above; null-checked at every dispatch site so apps that don't
+  // opt in see zero behavior change.
+  const telemetry = useTelemetry()
+
+  onMount(() => {
+    markRenderEnd(props.component.id)
+    if (telemetry) {
+      const ts = Date.now()
+      telemetry.dispatch({
+        type: 'component:mounted',
+        id: props.component.id,
+        componentType: props.component.type,
+        ts,
+      })
+      // Read the perf measure we just emitted to surface durationMs without
+      // double-measuring. The measure may be missing if `performance` is
+      // unavailable (SSR) — skip rendered event in that case.
+      if (typeof performance !== 'undefined' && typeof performance.getEntriesByName === 'function') {
+        const entries = performance.getEntriesByName(`${PERF_PREFIX}${props.component.id}:render`, 'measure')
+        const last = entries[entries.length - 1]
+        if (last) {
+          telemetry.dispatch({
+            type: 'component:rendered',
+            id: props.component.id,
+            componentType: props.component.type,
+            durationMs: last.duration,
+            ts,
+          })
+        }
+      }
+    }
+  })
+
+  onCleanup(() => {
+    if (telemetry) {
+      telemetry.dispatch({
+        type: 'component:unmounted',
+        id: props.component.id,
+        componentType: props.component.type,
+        ts: Date.now(),
+      })
+    }
+  })
 
   // Validate component before rendering
   const validation = validateComponent(props.component)
@@ -1145,6 +1311,19 @@ function ComponentRenderer(props: {
       details: validation.errors,
     })
 
+    // Privacy: only counts + first error code, NO error messages or paths
+    // (which could leak payload data — §M.6.2 hard rule).
+    if (telemetry) {
+      telemetry.dispatch({
+        type: 'validation:failed',
+        id: props.component.id,
+        componentType: props.component.type,
+        errorCount: validation.errors?.length ?? 0,
+        firstErrorCode: validation.errors?.[0]?.code ?? null,
+        ts: Date.now(),
+      })
+    }
+
     const mode: ValidationErrorMode = props.errorMode ?? 'block'
     const firstError = validation.errors?.[0]?.message || 'Unknown validation error'
 
@@ -1264,9 +1443,27 @@ function ComponentRenderer(props: {
 function ActionRenderer(props: { component: UIComponent }) {
   const params = props.component.params as any
   const { execute, isExecuting } = useAction()
+  const telemetry = useTelemetry()
+
+  // Telemetry: action:dispatched on click (B.5 — v5.6.0). Fires for every
+  // click attempt (tool-call or link), regardless of execute success.
+  // Privacy: actionName is `toolName` (tool-call) or the action kind
+  // (link/submit) — NO `params.params` payload, NO URL.
+  function dispatchTelemetry() {
+    if (!telemetry) return
+    const actionName: string = params.toolName ?? params.action ?? 'unknown'
+    telemetry.dispatch({
+      type: 'action:dispatched',
+      id: props.component.id,
+      componentType: 'action',
+      actionName,
+      ts: Date.now(),
+    })
+  }
 
   // Handle click to execute tool via Context (falls back to CustomEvent if no provider)
   const handleClick = async (e: MouseEvent) => {
+    dispatchTelemetry()
     if (params.action === 'tool-call' && params.toolName) {
       e.preventDefault()
       await execute(params.toolName, params.params || {})

package/src/context/MCPUITelemetryContext.test.tsx

@@ -0,0 +1,119 @@
+/**
+ * Integration tests for MCPUITelemetryProvider + dispatch wiring (B.5 — v5.6.0)
+ *
+ * Verifies that the Provider correctly wraps a dispatcher and that dispatches
+ * from real renderer components arrive at the consumer sink — without the
+ * Provider, no events should fire (existing tests prove this implicitly,
+ * but we lock it explicitly here).
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { render, cleanup } from '@solidjs/testing-library'
+import { UIResourceRenderer } from '../components/UIResourceRenderer'
+import { MCPUITelemetryProvider } from './MCPUITelemetryContext'
+import type { TelemetryEvent, TelemetrySink } from '../services/telemetry'
+import type { UIComponent } from '../types'
+
+const validMetric: UIComponent = {
+  id: 'metric-1',
+  type: 'metric',
+  position: { colStart: 1, colSpan: 6 },
+  params: { title: 'OK', value: 42 },
+}
+
+const invalidMetric: UIComponent = {
+  id: 'metric-bad',
+  type: 'metric',
+  position: { colStart: 1, colSpan: 6 },
+  params: {} as any, // missing title + value → validation:failed
+}
+
+describe('MCPUITelemetryProvider — integration with renderers (v5.6.0)', () => {
+  beforeEach(() => {
+    cleanup()
+  })
+
+  it('NO Provider = no events dispatched (renderer works as before)', () => {
+    // Render without Provider — should not throw, no events anywhere
+    expect(() => render(() => <UIResourceRenderer content={validMetric} />)).not.toThrow()
+    // No way to assert "no dispatch" without a sink; but the absence of
+    // throws + Provider's null-check semantics is what we lock here.
+  })
+
+  it('Provider receives component:mounted event for a valid component', async () => {
+    const events: TelemetryEvent[] = []
+    const sink: TelemetrySink = (batch) => {
+      events.push(...batch)
+    }
+
+    render(() => (
+      <MCPUITelemetryProvider sink={sink} options={{ bufferMs: 0 }}>
+        <UIResourceRenderer content={validMetric} />
+      </MCPUITelemetryProvider>
+    ))
+
+    const mounted = events.find((e) => e.type === 'component:mounted')
+    expect(mounted).toBeDefined()
+    expect(mounted?.id).toBe('metric-1')
+    expect(mounted?.componentType).toBe('metric')
+    expect(typeof mounted?.ts).toBe('number')
+  })
+
+  it('Provider receives validation:failed event with errorCount + firstErrorCode (NO error message)', async () => {
+    const events: TelemetryEvent[] = []
+    const sink: TelemetrySink = (batch) => {
+      events.push(...batch)
+    }
+
+    render(() => (
+      <MCPUITelemetryProvider sink={sink} options={{ bufferMs: 0 }}>
+        <UIResourceRenderer content={invalidMetric} errorMode="silent" />
+      </MCPUITelemetryProvider>
+    ))
+
+    const failed = events.find((e) => e.type === 'validation:failed')
+    expect(failed).toBeDefined()
+    expect(failed).toMatchObject({
+      type: 'validation:failed',
+      id: 'metric-bad',
+      componentType: 'metric',
+      firstErrorCode: 'INVALID_METRIC',
+    })
+    if (failed?.type === 'validation:failed') {
+      expect(failed.errorCount).toBeGreaterThan(0)
+    }
+
+    // Privacy hard rule: NO `errorMessage`, NO `errors` array, NO payload
+    // fields anywhere on the validation:failed event.
+    const failedKeys = failed ? Object.keys(failed) : []
+    expect(failedKeys.sort()).toEqual(
+      ['componentType', 'errorCount', 'firstErrorCode', 'id', 'ts', 'type'].sort()
+    )
+  })
+
+  it('FAIL-OPEN — sink that throws does NOT crash the renderer', () => {
+    const sink: TelemetrySink = () => {
+      throw new Error('sink down hard')
+    }
+
+    expect(() =>
+      render(() => (
+        <MCPUITelemetryProvider sink={sink} options={{ bufferMs: 0 }}>
+          <UIResourceRenderer content={validMetric} />
+        </MCPUITelemetryProvider>
+      ))
+    ).not.toThrow()
+  })
+
+  it('options.sampleRate=0 results in no events at the sink (everything dropped)', () => {
+    const sink = vi.fn<TelemetrySink>()
+
+    render(() => (
+      <MCPUITelemetryProvider sink={sink} options={{ sampleRate: 0, bufferMs: 0 }}>
+        <UIResourceRenderer content={validMetric} />
+      </MCPUITelemetryProvider>
+    ))
+
+    expect(sink).not.toHaveBeenCalled()
+  })
+})