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

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

@@ -92,10 +92,30 @@ export type {
 // Validation error mode (v5.4.0)
 export type { ValidationErrorMode } from './components/UIResourceRenderer'
 
+// Citation chips in table cells (v5.7.0 — brief: BRIEF-citations-in-table-cells.md)
+export { renderCellValue } from './components/UIResourceRenderer'
+export type { CitationCtx } from './components/UIResourceRenderer'
+export type { CitationEntry } from './types'
+
 // Runtime debug mode + perf marks (v5.4.0)
 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 }
+}

package/src/services/validation.ts

@@ -22,6 +22,9 @@ import {
   ImageGalleryParamsSchema,
   ActionGroupParamsSchema,
   CodeComponentParamsSchema,
+  // v5.6.0 — added after spec@5.0.2 relaxations (deposium audit §M)
+  MapComponentParamsSchema,
+  FormComponentParamsSchema,
 } from '@seed-ship/mcp-ui-spec'
 import type {
   UIComponent,
@@ -47,7 +50,7 @@ const KNOWN_COMPONENT_TYPES: Set<string> = new Set<ComponentType>([
 ])
 
 /**
- * Spec-driven validation dispatch table (B.1 — v5.5.0).
+ * Spec-driven validation dispatch table (B.1 — v5.5.0, expanded in v5.6.0).
  *
  * For each ComponentType where we delegate shape validation to a Zod schema
  * from `@seed-ship/mcp-ui-spec`, this table maps:
@@ -56,13 +59,13 @@ const KNOWN_COMPONENT_TYPES: Set<string> = new Set<ComponentType>([
  *     pre-v5.5.0 `errors[].code` API contract — see MCP-UI-AUDIT-2026-04-26.md
  *     §I.3.a + §J.1)
  *
+ * **v5.6.0** : `map` and `form` joined the dispatch after spec@5.0.2 relaxed
+ * their schemas (LatLngPoint union for map.center, regex relax for
+ * field.name) per deposium audit §L answers. Closed B.1 to **14/17 types**.
+ *
  * Types deliberately omitted (kept on the imperative path):
  *   - `chart`, `table` — have rich imperative validators with their own
  *     codes (MISSING_DATA, DATA_LENGTH_MISMATCH, RESOURCE_LIMIT_EXCEEDED, …)
- *   - `form`           — spec FormFieldSchema has strict regex on field
- *     names that could reject LLM-generated payloads. Conservative.
- *   - `map`            — spec center is `tuple([number, number])`; production
- *     payloads use `{lat, lng}` objects. Avoid backward-compat regression.
  *   - `modal`          — all params are optional; nothing to enforce.
  *   - `grid`, `footer`, `composite` — pass-through, validated elsewhere.
  */
@@ -79,6 +82,9 @@ const SPEC_VALIDATORS: Partial<Record<ComponentType, { schema: ZodSchema; legacy
   'action-group': { schema: ActionGroupParamsSchema, legacyCode: 'EMPTY_ACTION_GROUP' },
   code: { schema: CodeComponentParamsSchema, legacyCode: 'INVALID_CODE' },
   artifact: { schema: ArtifactComponentParamsSchema, legacyCode: 'INVALID_ARTIFACT' },
+  // v5.6.0 additions
+  form: { schema: FormComponentParamsSchema, legacyCode: 'EMPTY_FORM' },
+  map: { schema: MapComponentParamsSchema, legacyCode: 'INVALID_MAP' },
 }
 
 /**
@@ -677,35 +683,49 @@ export function validateComponent(
     errors.push(...(sizeResult.errors || []))
   }
 
-  // Type-specific validation (B.1 — v5.5.0).
+  // Type-specific validation (B.1 — v5.5.0, expanded v5.6.0).
   //
-  // 12 types delegate shape validation to Zod schemas in `mcp-ui-spec` via
-  // SPEC_VALIDATORS. The 5 remaining types stay imperative because they
-  // need cross-field consistency, resource limits, or backward-compat logic
-  // that pure Zod can't express without `.refine()` (see SPEC_VALIDATORS docstring).
+  // 14 types delegate shape validation to Zod schemas in `mcp-ui-spec` via
+  // SPEC_VALIDATORS. The 3 remaining types stay imperative because they
+  // need cross-field consistency, resource limits, or have nothing to validate
+  // (see SPEC_VALIDATORS docstring).
   const specValidator = SPEC_VALIDATORS[component.type]
   if (specValidator) {
     const result = specValidator.schema.safeParse(component.params)
     if (!result.success) {
       errors.push(...mapZodIssuesToErrors(result.error.issues, specValidator.legacyCode))
     }
-    // Iframe + video: chain the domain whitelist post-check ONLY when the
-    // shape parse succeeded (i.e. url is present and a string). Skipping the
-    // domain check when shape failed avoids cascading errors on the same field.
-    if (result.success && (component.type === 'iframe' || component.type === 'video')) {
-      const url = (component.params as { url?: string })?.url
-      if (typeof url === 'string') {
-        const domainResult = validateIframeDomain(url, {
-          policy: options?.iframePolicy,
-          customDomains: options?.customIframeDomains,
-        })
-        if (!domainResult.valid) {
-          errors.push(...(domainResult.errors || []))
+    // Post-spec chained checks. Skipped when the shape parse failed to avoid
+    // cascading errors on already-broken payloads.
+    if (result.success) {
+      // Iframe + video: domain whitelist
+      if (component.type === 'iframe' || component.type === 'video') {
+        const url = (component.params as { url?: string })?.url
+        if (typeof url === 'string') {
+          const domainResult = validateIframeDomain(url, {
+            policy: options?.iframePolicy,
+            customDomains: options?.customIframeDomains,
+          })
+          if (!domainResult.valid) {
+            errors.push(...(domainResult.errors || []))
+          }
+        }
+      }
+      // Map (v5.6.0): center OR markers required. Spec has both .optional()
+      // since auto-center from markers is supported, but we need ONE of them.
+      if (component.type === 'map') {
+        const mapParams = component.params as { center?: unknown; markers?: unknown[] }
+        if (!mapParams.center && (!Array.isArray(mapParams.markers) || mapParams.markers.length === 0)) {
+          errors.push({
+            path: 'params',
+            message: 'Map must have center or markers',
+            code: 'INVALID_MAP',
+          })
         }
       }
     }
   } else {
-    // Imperative path for chart/table/form/map/modal/grid/footer/composite.
+    // Imperative path for chart/table/modal/grid/footer/composite.
     switch (component.type) {
       case 'chart': {
         const chartResult = validateChartComponent(component.params as ChartComponentParams, limits)
@@ -723,24 +743,6 @@ export function validateComponent(
         break
       }
 
-      case 'form': {
-        const formParams = component.params as { fields?: unknown[] }
-        if (!Array.isArray(formParams.fields) || formParams.fields.length === 0) {
-          errors.push({ path: 'params.fields', message: 'Form must have non-empty fields array', code: 'EMPTY_FORM' })
-        }
-        break
-      }
-
-      case 'map': {
-        // Map can auto-detect center from markers, so center is not strictly required.
-        // Spec MapComponentParamsSchema would be too strict (tuple-only center) — kept imperative.
-        const mapParams = component.params as { center?: unknown; markers?: unknown[] }
-        if (!mapParams.center && (!Array.isArray(mapParams.markers) || mapParams.markers.length === 0)) {
-          errors.push({ path: 'params', message: 'Map must have center or markers', code: 'INVALID_MAP' })
-        }
-        break
-      }
-
       case 'modal':
         // Modal is valid with minimal params (title optional, content can be children).
         break

package/src/types/index.ts

@@ -173,9 +173,21 @@ export interface TableVirtualizeOptions {
   threshold?: number
 }
 
+/**
+ * Citation map entry — source of a `[N]` citation marker rendered inline
+ * inside table cells (v5.7.0). See
+ * `mcp-ui-solid/docs/briefs/BRIEF-citations-in-table-cells.md`.
+ */
+export interface CitationEntry {
+  page: number | string
+  file?: string
+  file_id?: number | string
+}
+
 /**
  * Table component parameters
  * Updated Sprint Ultimate U.3: Added virtualization support
+ * Updated v5.7.0: Optional citationMap + citationRender for chip rendering
  */
 export interface TableComponentParams {
   title?: string
@@ -211,6 +223,24 @@ export interface TableComponentParams {
    * Custom CSS class (Sprint 7)
    */
   className?: string
+  /**
+   * Opt-in citation chip rendering (v5.7.0). Maps marker id (e.g. `1` from
+   * `[1]` or `[📄 CITATION 1]` in cell text) to its source. When set,
+   * `<TableRenderer>` replaces markers in cell strings with clickable
+   * chips carrying `data-citation-page` / `data-citation-doc` /
+   * `data-citation-verified` attributes that a host's delegated click
+   * handler can route. JSON-serializable — safe to send from MCP servers.
+   */
+  citationMap?: Record<string | number, CitationEntry>
+  /**
+   * Optional override for the chip HTML (v5.7.0). When supplied, wins over
+   * the default chip shape. NOT JSON-serializable — must be wired by the
+   * consumer at render time, not from a server payload.
+   */
+  citationRender?: (
+    id: number,
+    mapping: CitationEntry | undefined
+  ) => string
 }
 
 /**