@seed-ship/mcp-ui-solid 5.5.1 → 5.6.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/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
@@ -1133,7 +1134,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 +1190,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 +1322,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()
+  })
+})

package/src/context/MCPUITelemetryContext.tsx

@@ -0,0 +1,71 @@
+/**
+ * MCPUITelemetryProvider + useTelemetry hook (B.5 — v5.6.0)
+ *
+ * SolidJS Context wrapper around `createTelemetryDispatcher`. Optional —
+ * when no Provider is present, `useTelemetry()` returns `null` and dispatch
+ * sites no-op (zero behavior change for apps that don't opt in).
+ *
+ * See `services/telemetry.ts` for the dispatcher contract and
+ * `MCP-UI-AUDIT-2026-04-26.md` §M.6 for the full specification.
+ */
+
+import {
+  createContext,
+  useContext,
+  onCleanup,
+  type Component,
+  type JSX,
+} from 'solid-js'
+import {
+  createTelemetryDispatcher,
+  type TelemetryDispatcher,
+  type TelemetrySink,
+  type TelemetryOptions,
+} from '../services/telemetry'
+
+export const MCPUITelemetryContext = createContext<TelemetryDispatcher | null>(null)
+
+export interface MCPUITelemetryProviderProps {
+  /** Consumer-supplied sink. Receives a batch of events. Fail-open. */
+  sink: TelemetrySink
+  /** Sampling + buffering knobs (defaults: 100% / 100ms / max 50). */
+  options?: TelemetryOptions
+  children: JSX.Element
+}
+
+export const MCPUITelemetryProvider: Component<MCPUITelemetryProviderProps> = (props) => {
+  // Dispatcher is created once per Provider mount. `props.sink` and
+  // `props.options` are captured at that moment — consumers should treat
+  // them as effectively immutable for the Provider's lifetime (re-mount the
+  // Provider to swap them).
+  const dispatcher = createTelemetryDispatcher(props.sink, props.options)
+
+  // Force-flush on unmount so any buffered events from the last bufferMs
+  // window aren't lost (e.g. tab close, route change with cleanup).
+  onCleanup(() => {
+    dispatcher.flush()
+  })
+
+  return (
+    <MCPUITelemetryContext.Provider value={dispatcher}>
+      {props.children}
+    </MCPUITelemetryContext.Provider>
+  )
+}
+
+/**
+ * Returns the current telemetry dispatcher, or `null` when no Provider is
+ * mounted in the tree above. Dispatch sites should null-check and no-op
+ * when null — telemetry is OPT-IN and must not impose a Provider on apps.
+ *
+ * @example
+ * ```tsx
+ * const telemetry = useTelemetry()
+ * onMount(() => {
+ *   telemetry?.dispatch({ type: 'component:mounted', id, componentType, ts: Date.now() })
+ * })
+ * ```
+ */
+export function useTelemetry(): TelemetryDispatcher | null {
+  return useContext(MCPUITelemetryContext)
+}

package/src/index.ts

@@ -96,6 +96,21 @@ export type { ValidationErrorMode } from './components/UIResourceRenderer'
 export { setDebugMode, isDebugEnabled } from './utils/logger'
 export { markRenderStart, markRenderEnd, PERF_PREFIX } from './utils/perf'
 
+// Telemetry sink (B.5 — v5.6.0)
+export {
+  MCPUITelemetryProvider,
+  MCPUITelemetryContext,
+  useTelemetry,
+} from './context/MCPUITelemetryContext'
+export type { MCPUITelemetryProviderProps } from './context/MCPUITelemetryContext'
+export { createTelemetryDispatcher } from './services/telemetry'
+export type {
+  TelemetryEvent,
+  TelemetrySink,
+  TelemetryOptions,
+  TelemetryDispatcher,
+} from './services/telemetry'
+
 export type { DraggableGridItemProps } from './components/DraggableGridItem'
 export type { ResizeHandleProps as ResizeHandleComponentProps } from './components/ResizeHandle'
 export type { EditableUIResourceRendererProps } from './components/EditableUIResourceRenderer'

package/src/services/telemetry.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Tests for createTelemetryDispatcher (B.5 — v5.6.0).
+ * Spec: MCP-UI-AUDIT-2026-04-26.md §M.6
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { createTelemetryDispatcher, type TelemetryEvent, type TelemetrySink } from './telemetry'
+
+function evt(type: TelemetryEvent['type'], id = 'cmp-1'): TelemetryEvent {
+  const base = { id, componentType: 'metric' as const, ts: 1_700_000_000_000 }
+  switch (type) {
+    case 'component:rendered':
+      return { type, durationMs: 4, ...base }
+    case 'validation:failed':
+      return { type, errorCount: 1, firstErrorCode: 'INVALID_METRIC', ...base }
+    case 'render:error':
+      return { type, errorMessage: 'boom', ...base }
+    case 'action:dispatched':
+      return { type, actionName: 'submit', ...base }
+    default:
+      return { type, ...base }
+  }
+}
+
+describe('createTelemetryDispatcher (v5.6.0 — B.5)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('delivers events as a BATCH (array), even with bufferMs=0', () => {
+    const sink = vi.fn<TelemetrySink>()
+    const d = createTelemetryDispatcher(sink, { bufferMs: 0 })
+    d.dispatch(evt('component:mounted'))
+    expect(sink).toHaveBeenCalledTimes(1)
+    expect(sink.mock.calls[0][0]).toHaveLength(1)
+    expect(Array.isArray(sink.mock.calls[0][0])).toBe(true)
+  })
+
+  it('buffers and flushes after bufferMs', () => {
+    const sink = vi.fn<TelemetrySink>()
+    const d = createTelemetryDispatcher(sink, { bufferMs: 100 })
+    d.dispatch(evt('component:mounted', 'a'))
+    d.dispatch(evt('component:mounted', 'b'))
+    d.dispatch(evt('component:mounted', 'c'))
+    expect(sink).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(100)
+
+    expect(sink).toHaveBeenCalledTimes(1)
+    expect(sink.mock.calls[0][0]).toHaveLength(3)
+  })
+
+  it('forces flush when bufferMax reached', () => {
+    const sink = vi.fn<TelemetrySink>()
+    const d = createTelemetryDispatcher(sink, { bufferMs: 5_000, bufferMax: 3 })
+    d.dispatch(evt('component:mounted', 'a'))
+    d.dispatch(evt('component:mounted', 'b'))
+    expect(sink).not.toHaveBeenCalled()
+    d.dispatch(evt('component:mounted', 'c')) // hits bufferMax
+    expect(sink).toHaveBeenCalledTimes(1)
+    expect(sink.mock.calls[0][0]).toHaveLength(3)
+  })
+
+  it('flush() is idempotent on empty buffer (no sink call)', () => {
+    const sink = vi.fn<TelemetrySink>()
+    const d = createTelemetryDispatcher(sink, { bufferMs: 1_000 })
+    d.flush()
+    d.flush()
+    expect(sink).not.toHaveBeenCalled()
+  })
+
+  it('manual flush() clears the pending bufferMs timer', () => {
+    const sink = vi.fn<TelemetrySink>()
+    const d = createTelemetryDispatcher(sink, { bufferMs: 1_000 })
+    d.dispatch(evt('component:mounted'))
+    d.flush()
+    expect(sink).toHaveBeenCalledTimes(1)
+    vi.advanceTimersByTime(2_000)
+    // timer was cleared — no second call
+    expect(sink).toHaveBeenCalledTimes(1)
+  })
+
+  it('FAIL-OPEN — sink throw does NOT propagate', () => {
+    const sink = vi.fn<TelemetrySink>(() => {
+      throw new Error('sink down')
+    })
+    const d = createTelemetryDispatcher(sink, { bufferMs: 0 })
+    expect(() => d.dispatch(evt('component:mounted'))).not.toThrow()
+    expect(sink).toHaveBeenCalledTimes(1)
+  })
+
+  it('FAIL-OPEN — sink rejected promise does NOT throw at dispatch site', async () => {
+    const sink = vi.fn<TelemetrySink>(async () => {
+      throw new Error('async sink down')
+    })
+    const d = createTelemetryDispatcher(sink, { bufferMs: 0 })
+    expect(() => d.dispatch(evt('component:mounted'))).not.toThrow()
+    // Microtask flush — should NOT bubble unhandled rejection
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(sink).toHaveBeenCalledTimes(1)
+  })
+
+  it('sampleRate 0 drops every event', () => {
+    const sink = vi.fn<TelemetrySink>()
+    const d = createTelemetryDispatcher(sink, { sampleRate: 0, bufferMs: 0 })
+    for (let i = 0; i < 100; i++) d.dispatch(evt('component:mounted'))
+    expect(sink).not.toHaveBeenCalled()
+  })
+
+  it('sampleRate 1 keeps every event', () => {
+    const sink = vi.fn<TelemetrySink>()
+    const d = createTelemetryDispatcher(sink, { sampleRate: 1, bufferMs: 0 })
+    for (let i = 0; i < 5; i++) d.dispatch(evt('component:mounted'))
+    expect(sink).toHaveBeenCalledTimes(5)
+  })
+
+  it('sampleByType overrides sampleRate per event type', () => {
+    const sink = vi.fn<TelemetrySink>()
+    const d = createTelemetryDispatcher(sink, {
+      sampleRate: 0, // would drop everything
+      sampleByType: { 'render:error': 1.0 }, // ...except errors
+      bufferMs: 0,
+    })
+    d.dispatch(evt('component:mounted')) // dropped
+    d.dispatch(evt('render:error')) // kept
+    d.dispatch(evt('validation:failed')) // dropped
+    expect(sink).toHaveBeenCalledTimes(1)
+    expect(sink.mock.calls[0][0][0].type).toBe('render:error')
+  })
+})

package/src/services/telemetry.ts

@@ -0,0 +1,149 @@
+/**
+ * UI telemetry sink (B.5 — v5.6.0)
+ *
+ * Minimal OpenTelemetry-like Provider that lets a consumer (e.g. deposium
+ * `/admin/ui-telemetry`) collect lifecycle + error + action events from
+ * mcp-ui components without imposing any API change on apps that don't use
+ * it. Spec'd in `MCP-UI-AUDIT-2026-04-26.md` §M.6.
+ *
+ * Three hard rules:
+ *   1. Provider is OPTIONAL. When absent, `useTelemetry()` returns `null`
+ *      and dispatch sites no-op. Existing apps see zero behavior change.
+ *   2. Sink is FAIL-OPEN. A `sink()` throw or rejected promise is caught
+ *      silently — telemetry never crashes the renderer.
+ *   3. Events carry NO payload data. Only meta (type + id + counts + timing)
+ *      to avoid PII / data leaks in centralized logs.
+ */
+
+import type { ComponentType } from '../types'
+
+interface TelemetryEventBase {
+  /** Component instance id (from `UIComponent.id` or auto-generated). */
+  id: string
+  /** ComponentType, e.g. 'chart' / 'metric' / 'iframe'. */
+  componentType: ComponentType
+  /** Wall-clock timestamp (ms epoch) for cross-stack correlation. */
+  ts: number
+}
+
+/**
+ * Discriminated union of all telemetry events emitted by mcp-ui.
+ * See §M.6.2 for field semantics + privacy rules.
+ */
+export type TelemetryEvent =
+  | ({ type: 'component:mounted' } & TelemetryEventBase)
+  | ({ type: 'component:rendered'; durationMs: number } & TelemetryEventBase)
+  | ({ type: 'component:unmounted' } & TelemetryEventBase)
+  | ({
+      type: 'validation:failed'
+      errorCount: number
+      firstErrorCode: string | null
+    } & TelemetryEventBase)
+  | ({ type: 'render:error'; errorMessage: string } & TelemetryEventBase)
+  | ({ type: 'action:dispatched'; actionName: string } & TelemetryEventBase)
+
+/**
+ * Consumer-supplied sink. Receives a batch of events (always an array,
+ * even for `bufferMs: 0` — single-element array in that case). Errors
+ * and rejected promises are caught silently by the dispatcher.
+ */
+export interface TelemetrySink {
+  (events: TelemetryEvent[]): void | Promise<void>
+}
+
+export interface TelemetryOptions {
+  /** Per-event base sampling rate, 0..1, default 1.0 (all events). */
+  sampleRate?: number
+  /** Buffer events and flush after N ms (default 100). 0 = no buffer. */
+  bufferMs?: number
+  /** Max buffered events before forced flush (default 50). */
+  bufferMax?: number
+  /** Per-event-type override on sampling (high-volume types can be lower). */
+  sampleByType?: Partial<Record<TelemetryEvent['type'], number>>
+}
+
+/**
+ * Dispatcher returned by `createTelemetryDispatcher`. Used internally by
+ * the Provider, exposed only so tests can drive it without React/Solid.
+ */
+export interface TelemetryDispatcher {
+  /**
+   * Push an event. Sampling + buffering applied transparently. Never throws.
+   */
+  dispatch(event: TelemetryEvent): void
+  /**
+   * Force-flush the buffer. Useful on tab-hidden / unload, or for tests.
+   * Never throws.
+   */
+  flush(): void
+}
+
+const DEFAULT_BUFFER_MS = 100
+const DEFAULT_BUFFER_MAX = 50
+
+function shouldSample(
+  eventType: TelemetryEvent['type'],
+  options: TelemetryOptions | undefined
+): boolean {
+  const perTypeRate = options?.sampleByType?.[eventType]
+  const rate = perTypeRate !== undefined ? perTypeRate : (options?.sampleRate ?? 1.0)
+  if (rate >= 1) return true
+  if (rate <= 0) return false
+  return Math.random() < rate
+}
+
+/**
+ * Create a telemetry dispatcher. Pure function, no Solid context — exists
+ * separately from the Provider so it can be unit-tested in isolation.
+ */
+export function createTelemetryDispatcher(
+  sink: TelemetrySink,
+  options?: TelemetryOptions
+): TelemetryDispatcher {
+  const buffer: TelemetryEvent[] = []
+  const bufferMs = options?.bufferMs ?? DEFAULT_BUFFER_MS
+  const bufferMax = options?.bufferMax ?? DEFAULT_BUFFER_MAX
+  let flushTimer: ReturnType<typeof setTimeout> | undefined
+
+  function deliver(batch: TelemetryEvent[]): void {
+    try {
+      const result = sink(batch)
+      // Promise rejections are silenced too (fail-open, §M.6.1).
+      if (result && typeof (result as Promise<void>).then === 'function') {
+        ;(result as Promise<void>).catch(() => {
+          /* silent */
+        })
+      }
+    } catch {
+      /* silent */
+    }
+  }
+
+  function flush(): void {
+    if (flushTimer !== undefined) {
+      clearTimeout(flushTimer)
+      flushTimer = undefined
+    }
+    if (buffer.length === 0) return
+    const batch = buffer.splice(0, buffer.length)
+    deliver(batch)
+  }
+
+  function dispatch(event: TelemetryEvent): void {
+    if (!shouldSample(event.type, options)) return
+    buffer.push(event)
+    if (buffer.length >= bufferMax) {
+      flush()
+      return
+    }
+    if (bufferMs <= 0) {
+      flush()
+      return
+    }
+    if (flushTimer === undefined) {
+      flushTimer = setTimeout(flush, bufferMs)
+    }
+  }
+
+  return { dispatch, flush }
+}