@seed-ship/mcp-ui-solid 6.4.0 → 6.6.0

package/src/context/MCPUIStringsContext.tsx

@@ -0,0 +1,128 @@
+/**
+ * MCPUIStringsContext — i18n for the library's own "chrome" strings.
+ *
+ * @since v6.6.0 (D2 / R4 of ROADMAP-opendata-macro-mcpui)
+ *
+ * ## Scope — chrome only, NOT content
+ *
+ * MCP-UI renders two kinds of text :
+ *
+ * - **Content** — table headers, chart titles, action labels, prompt
+ *   questions. These come from the payload and are ALREADY localized by
+ *   whoever produced the payload (the connector / MCP server). MCP-UI
+ *   renders them verbatim and this context never touches them.
+ * - **Chrome** — the handful of strings the library itself hardcodes :
+ *   the expand-button tooltip, the feedback acknowledgements, etc. THIS
+ *   is what `MCPUIStrings` covers.
+ *
+ * There is deliberately no full i18n framework here : no per-renderer
+ * `locale` prop, no message catalogue, no ICU. A flat string map behind a
+ * context is enough — the chrome surface is small and static.
+ *
+ * ## Defaults are English
+ *
+ * `DEFAULT_MCPUI_STRINGS` is English. A published library should not ship
+ * hardcoded French. Consumers that want another language wrap their tree
+ * in `<MCPUIStringsProvider strings={...}>` with a partial override.
+ *
+ * Component props that already carry a label (e.g. `FeedbackInline`'s
+ * `positiveAck`, `ExpandableWrapper`'s `copyLabel`) keep priority over the
+ * provider — the provider only fills the gap when no explicit prop is set.
+ *
+ * @example
+ * ```tsx
+ * import { MCPUIStringsProvider } from '@seed-ship/mcp-ui-solid'
+ *
+ * <MCPUIStringsProvider strings={{ expand: 'Agrandir', feedbackUseful: 'Utile' }}>
+ *   <App />
+ * </MCPUIStringsProvider>
+ * ```
+ */
+
+import { createContext, useContext, type JSX } from 'solid-js'
+
+/**
+ * The library's own chrome strings. Flat map, no interpolation.
+ *
+ * Marked exhaustive as of v6.6.0 ; new chrome strings added by later
+ * renderers extend this interface (the `MCPUIStringsProvider` merge keeps
+ * older consumers working — any unset key falls back to the EN default).
+ */
+export interface MCPUIStrings {
+  // ── ExpandableWrapper toolbar ──────────────────────────────
+  /** `title` of the expand-to-fullscreen button. */
+  expand: string
+  /** Heading + `aria-label` of the fullscreen modal when no title is given. */
+  expandedView: string
+  /** Default tooltip of the copy button (overridden by `copyLabel` prop). */
+  copyToClipboard: string
+  /** `aria-label` of the close button in the fullscreen modal. */
+  closeExpandedView: string
+
+  // ── FeedbackInline (response-quality feedback) ─────────────
+  /** `title` of the thumb-up button. */
+  feedbackUseful: string
+  /** `title` of the thumb-down button. */
+  feedbackNotUseful: string
+  /** Acknowledgement shown after a positive rating (overridden by `positiveAck`). */
+  feedbackPositiveAck: string
+  /** Acknowledgement shown after a negative rating (overridden by `negativeAck`). */
+  feedbackNegativeAck: string
+
+  // ── Generic chrome ────────────────────────────────────────
+  /** Label of the streaming retry button. */
+  retry: string
+}
+
+/**
+ * English defaults. A published library ships no hardcoded non-English
+ * chrome — consumers localize via `<MCPUIStringsProvider>`.
+ */
+export const DEFAULT_MCPUI_STRINGS: MCPUIStrings = {
+  expand: 'Expand',
+  expandedView: 'Expanded view',
+  copyToClipboard: 'Copy to clipboard',
+  closeExpandedView: 'Close expanded view',
+  feedbackUseful: 'Useful',
+  feedbackNotUseful: 'Not useful',
+  feedbackPositiveAck: 'Thanks!',
+  feedbackNegativeAck: "Noted — we'll improve",
+  retry: 'Retry',
+}
+
+export const MCPUIStringsContext = createContext<MCPUIStrings>(DEFAULT_MCPUI_STRINGS)
+
+/**
+ * Reads the active chrome strings. Returns `DEFAULT_MCPUI_STRINGS` when no
+ * `<MCPUIStringsProvider>` is mounted above — every renderer works
+ * standalone with English chrome.
+ */
+export function useMCPUIStrings(): MCPUIStrings {
+  return useContext(MCPUIStringsContext)
+}
+
+export interface MCPUIStringsProviderProps {
+  /**
+   * Partial override of the chrome strings. Any key left unset falls back
+   * to the English `DEFAULT_MCPUI_STRINGS` — so a consumer can localize
+   * just the strings they care about.
+   */
+  strings?: Partial<MCPUIStrings>
+  children: JSX.Element
+}
+
+/**
+ * Provides localized chrome strings to every MCP-UI renderer below it.
+ * Merges the partial `strings` override over the English defaults.
+ */
+export function MCPUIStringsProvider(props: MCPUIStringsProviderProps): JSX.Element {
+  // `props.strings` is read inside the getter so a reactive override
+  // (signal-backed) re-propagates ; for the common static case it is read
+  // once at mount.
+  const value = (): MCPUIStrings => ({ ...DEFAULT_MCPUI_STRINGS, ...props.strings })
+  return (
+    <MCPUIStringsContext.Provider value={value()}>
+      {props.children}
+    </MCPUIStringsContext.Provider>
+  )
+}

package/src/index.ts

@@ -40,6 +40,21 @@ export { ComponentToolbar } from './components/ComponentToolbar'
 export { FeedbackInline } from './components/FeedbackInline'
 export type { FeedbackInlineProps, FeedbackInlineContext } from './components/FeedbackInline'
 
+// Presentation feedback (v6.6.0 — R3 ; separate axis from FeedbackInline)
+export {
+  PresentationFeedback,
+  DEFAULT_PRESENTATION_FEEDBACK_LABELS,
+} from './components/PresentationFeedback'
+export type {
+  PresentationFeedbackProps,
+  PresentationFeedbackLabels,
+} from './components/PresentationFeedback'
+export type {
+  ConnectorRenderFeedback,
+  ConnectorRenderProblem,
+  ConnectorPreferredLayout,
+} from '@seed-ship/mcp-ui-spec'
+
 // Chat Bus (v2.4.0 — @experimental)
 export { ChatBusProvider, useChatBus } from './hooks/useChatBus'
 export { ChatPrompt } from './components/ChatPrompt'
@@ -105,6 +120,26 @@ export { GraphRenderer, isG6Available, graphToMermaid, graphToJSON } from './com
 export { setDebugMode, isDebugEnabled } from './utils/logger'
 export { markRenderStart, markRenderEnd, PERF_PREFIX } from './utils/perf'
 
+// Identity stability + opt-in observability (v6.5.0 — closes BRIEF-MCPUI-2026-05-10)
+export { getUiResourceStableKey } from './utils/stable-key'
+export { setDuplicateMountReporter } from './utils/duplicate-mount-registry'
+export type {
+  DuplicateMountInfo,
+  DuplicateMountReporter,
+} from './utils/duplicate-mount-registry'
+
+// Chrome i18n — library's own strings, EN defaults (v6.6.0 — D2/R4)
+export {
+  MCPUIStringsProvider,
+  MCPUIStringsContext,
+  useMCPUIStrings,
+  DEFAULT_MCPUI_STRINGS,
+} from './context/MCPUIStringsContext'
+export type {
+  MCPUIStrings,
+  MCPUIStringsProviderProps,
+} from './context/MCPUIStringsContext'
+
 // Telemetry sink (B.5 — v5.6.0)
 export {
   MCPUITelemetryProvider,

package/src/utils/duplicate-mount-registry.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import {
+  setDuplicateMountReporter,
+  getDuplicateMountReporter,
+  _registerMount,
+  _unregisterMount,
+  _resetRegistry,
+  _getMountCount,
+} from './duplicate-mount-registry'
+
+describe('duplicate-mount-registry (v6.5.0)', () => {
+  beforeEach(() => {
+    _resetRegistry()
+  })
+
+  it('first mount returns count=1, no duplicate', () => {
+    const info = _registerMount('alpha')
+    expect(info.key).toBe('alpha')
+    expect(info.count).toBe(1)
+    expect(typeof info.firstMountedAt).toBe('number')
+  })
+
+  it('second concurrent mount returns count=2 (caller decides to warn)', () => {
+    _registerMount('beta')
+    const info = _registerMount('beta')
+    expect(info.count).toBe(2)
+  })
+
+  it('unregister decrements and cleans up at 0', () => {
+    _registerMount('gamma')
+    _registerMount('gamma')
+    expect(_getMountCount('gamma')).toBe(2)
+    _unregisterMount('gamma')
+    expect(_getMountCount('gamma')).toBe(1)
+    _unregisterMount('gamma')
+    expect(_getMountCount('gamma')).toBe(0)
+  })
+
+  it('unregister on unknown key is a no-op (no throw)', () => {
+    expect(() => _unregisterMount('does-not-exist')).not.toThrow()
+  })
+
+  it('firstMountedAt is preserved across the lifetime of the entry', () => {
+    const a = _registerMount('delta')
+    const b = _registerMount('delta')
+    expect(b.firstMountedAt).toBe(a.firstMountedAt)
+  })
+
+  it('firstMountedAt resets after a full cleanup cycle', async () => {
+    const first = _registerMount('epsilon')
+    _unregisterMount('epsilon')
+    // Tiny delay to guarantee a different Date.now() reading
+    await new Promise((r) => setTimeout(r, 2))
+    const second = _registerMount('epsilon')
+    expect(second.firstMountedAt).toBeGreaterThanOrEqual(first.firstMountedAt)
+  })
+
+  it('module reporter starts unwired (null)', () => {
+    expect(getDuplicateMountReporter()).toBeNull()
+  })
+
+  it('setDuplicateMountReporter wires + replaces + clears', () => {
+    const r1 = vi.fn()
+    setDuplicateMountReporter(r1)
+    expect(getDuplicateMountReporter()).toBe(r1)
+
+    const r2 = vi.fn()
+    setDuplicateMountReporter(r2)
+    expect(getDuplicateMountReporter()).toBe(r2)
+
+    setDuplicateMountReporter(null)
+    expect(getDuplicateMountReporter()).toBeNull()
+  })
+
+  it('different keys live in independent slots', () => {
+    _registerMount('zeta')
+    _registerMount('eta')
+    _registerMount('zeta')
+    expect(_getMountCount('zeta')).toBe(2)
+    expect(_getMountCount('eta')).toBe(1)
+  })
+})

package/src/utils/duplicate-mount-registry.ts

@@ -0,0 +1,113 @@
+/**
+ * Opt-in duplicate-mount registry (v6.5.0).
+ *
+ * Tracks how many times each `getUiResourceStableKey()` has been mounted
+ * concurrently across all `<UIResourceRenderer>` instances. When the same
+ * key is mounted more than once, registered reporters fire so consumers
+ * can detect double-render bugs in their parent framework.
+ *
+ * **Opt-in by design** : the registry is always populated (cheap), but
+ * notifications only fire when a consumer has wired one of the two opt-in
+ * paths :
+ *   - module-level `setDuplicateMountReporter(fn)` (app-wide telemetry)
+ *   - per-instance `<UIResourceRenderer onMountDuplicate={fn}>` prop
+ *
+ * **What this does NOT do** : visual deduplication. The renderer never
+ * hides or replaces a duplicate mount automatically — that would mask
+ * parent-framework bugs and could remove legitimate co-mounts (e.g. drawer
+ * + main panel showing the same card). Consumers who want dedup implement
+ * it on top of the reported events.
+ */
+
+export interface DuplicateMountInfo {
+  /** Stable key from `getUiResourceStableKey(content)`. */
+  key: string
+  /**
+   * Current concurrent mount count. The reporter fires whenever this
+   * crosses 2 (i.e. on the 2nd, 3rd, etc. mount of the same key while
+   * earlier mounts are still alive).
+   */
+  count: number
+  /** `Date.now()` of the FIRST mount of this key (telemetry, not identity). */
+  firstMountedAt: number
+}
+
+export type DuplicateMountReporter = (info: DuplicateMountInfo) => void
+
+const registry = new Map<string, { count: number; firstMountedAt: number }>()
+let moduleReporter: DuplicateMountReporter | null = null
+
+/**
+ * Wire a module-level reporter for duplicate mount events. Pass `null` to
+ * unwire. Only one module reporter at a time (replaces any previous one).
+ *
+ * @example
+ * ```ts
+ * import { setDuplicateMountReporter } from '@seed-ship/mcp-ui-solid'
+ *
+ * setDuplicateMountReporter(({ key, count }) => {
+ *   telemetry.warn('mcp-ui.duplicate-mount', { key, count })
+ * })
+ * ```
+ */
+export function setDuplicateMountReporter(reporter: DuplicateMountReporter | null): void {
+  moduleReporter = reporter
+}
+
+/**
+ * Internal — read by `<UIResourceRenderer>` to dispatch on mount. Not part
+ * of the public API.
+ *
+ * @internal
+ */
+export function getDuplicateMountReporter(): DuplicateMountReporter | null {
+  return moduleReporter
+}
+
+/**
+ * Internal — registers a mount for `key` and returns the resulting state.
+ * The caller decides whether to surface a notification based on `count > 1`.
+ *
+ * @internal
+ */
+export function _registerMount(key: string): DuplicateMountInfo {
+  const entry = registry.get(key) ?? { count: 0, firstMountedAt: Date.now() }
+  entry.count += 1
+  registry.set(key, entry)
+  return { key, count: entry.count, firstMountedAt: entry.firstMountedAt }
+}
+
+/**
+ * Internal — undoes a prior `_registerMount(key)`. Removes the entry when
+ * the count reaches zero so the registry never leaks across mount/unmount
+ * cycles of unique keys.
+ *
+ * @internal
+ */
+export function _unregisterMount(key: string): void {
+  const entry = registry.get(key)
+  if (!entry) return
+  entry.count -= 1
+  if (entry.count <= 0) registry.delete(key)
+}
+
+/**
+ * Internal — clears the registry and unwires any module reporter. Used by
+ * tests to ensure isolation between cases.
+ *
+ * @internal
+ */
+export function _resetRegistry(): void {
+  registry.clear()
+  moduleReporter = null
+}
+
+/**
+ * Internal — read the current count for a key (0 if not mounted). Useful
+ * for tests and for consumers building their own debug overlays.
+ *
+ * @internal
+ */
+export function _getMountCount(key: string): number {
+  return registry.get(key)?.count ?? 0
+}

package/src/utils/stable-key.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest'
+import { getUiResourceStableKey } from './stable-key'
+
+describe('getUiResourceStableKey (v6.5.0)', () => {
+  it('returns layout.id verbatim when present and non-empty', () => {
+    const layout = { id: 'dashboard-2024-Q3', components: [], grid: { columns: 12, gap: '1rem' } }
+    expect(getUiResourceStableKey(layout)).toBe('dashboard-2024-Q3')
+  })
+
+  it('returns component.id verbatim when present and non-empty', () => {
+    const component = { id: 'chart-revenue', type: 'chart', params: {} }
+    expect(getUiResourceStableKey(component)).toBe('chart-revenue')
+  })
+
+  it('falls back to a content hash when id is missing', () => {
+    const bare = { type: 'chart', params: { type: 'bar', data: { labels: ['a'], datasets: [] } } }
+    const key = getUiResourceStableKey(bare)
+    expect(key).toMatch(/^[a-z0-9]{7}$/)
+  })
+
+  it('falls back to a content hash when id is empty string', () => {
+    const bare = { id: '', type: 'chart', params: {} }
+    const key = getUiResourceStableKey(bare)
+    expect(key).toMatch(/^[a-z0-9]{7}$/)
+  })
+
+  it('produces the same key across calls for structurally identical payloads', () => {
+    const a = { type: 'chart', params: { foo: 1, bar: 2 } }
+    const b = { type: 'chart', params: { foo: 1, bar: 2 } }
+    expect(getUiResourceStableKey(a)).toBe(getUiResourceStableKey(b))
+  })
+
+  it('is independent of object key insertion order', () => {
+    const a = { type: 'chart', params: { foo: 1, bar: 2 } }
+    const b = { params: { bar: 2, foo: 1 }, type: 'chart' }
+    expect(getUiResourceStableKey(a)).toBe(getUiResourceStableKey(b))
+  })
+
+  it('produces different keys for different payloads', () => {
+    const a = { type: 'chart', params: { x: 1 } }
+    const b = { type: 'chart', params: { x: 2 } }
+    expect(getUiResourceStableKey(a)).not.toBe(getUiResourceStableKey(b))
+  })
+
+  it('ignores metadata.generatedAt (timestamp must not affect identity)', () => {
+    const a = { type: 'chart', params: { x: 1 }, metadata: { generatedAt: '2026-05-10T10:00:00Z', llmModel: 'opus' } }
+    const b = { type: 'chart', params: { x: 1 }, metadata: { generatedAt: '2026-05-10T11:00:00Z', llmModel: 'opus' } }
+    expect(getUiResourceStableKey(a)).toBe(getUiResourceStableKey(b))
+  })
+
+  it('still distinguishes payloads with different non-timestamp metadata', () => {
+    const a = { type: 'chart', params: { x: 1 }, metadata: { llmModel: 'opus' } }
+    const b = { type: 'chart', params: { x: 1 }, metadata: { llmModel: 'sonnet' } }
+    expect(getUiResourceStableKey(a)).not.toBe(getUiResourceStableKey(b))
+  })
+
+  it('skips undefined entries deterministically', () => {
+    const a = { type: 'chart', params: { x: 1, y: undefined } }
+    const b = { type: 'chart', params: { x: 1 } }
+    expect(getUiResourceStableKey(a)).toBe(getUiResourceStableKey(b))
+  })
+
+  it('handles nested arrays', () => {
+    const a = { type: 'composite', components: [{ type: 'metric' }, { type: 'chart' }] }
+    const b = { type: 'composite', components: [{ type: 'metric' }, { type: 'chart' }] }
+    expect(getUiResourceStableKey(a)).toBe(getUiResourceStableKey(b))
+  })
+
+  it('different array order yields different keys (order is semantic)', () => {
+    const a = { type: 'composite', components: [{ type: 'metric' }, { type: 'chart' }] }
+    const b = { type: 'composite', components: [{ type: 'chart' }, { type: 'metric' }] }
+    expect(getUiResourceStableKey(a)).not.toBe(getUiResourceStableKey(b))
+  })
+
+  it('handles primitives gracefully', () => {
+    expect(getUiResourceStableKey('a string')).toMatch(/^[a-z0-9]{7}$/)
+    expect(getUiResourceStableKey(42)).toMatch(/^[a-z0-9]{7}$/)
+    expect(getUiResourceStableKey(null)).toMatch(/^[a-z0-9]{7}$/)
+  })
+
+  it('keeps the explicit id even if other fields would hash differently', () => {
+    const a = { id: 'fixed', type: 'chart', params: { x: 1 } }
+    const b = { id: 'fixed', type: 'chart', params: { x: 999 } }
+    expect(getUiResourceStableKey(a)).toBe('fixed')
+    expect(getUiResourceStableKey(b)).toBe('fixed')
+  })
+
+  it('generated timestamp ids are NOT special-cased — passthrough is intentional', () => {
+    // If a consumer (incorrectly) injects `wrap-${Date.now()}` ids, they get
+    // unique keys per render. That's their responsibility — the helper only
+    // strips the `id` field when it's missing or empty.
+    const a = { id: 'wrap-1700000000000', type: 'chart', params: {} }
+    const b = { id: 'wrap-1700000000001', type: 'chart', params: {} }
+    expect(getUiResourceStableKey(a)).not.toBe(getUiResourceStableKey(b))
+  })
+})

package/src/utils/stable-key.ts

@@ -0,0 +1,91 @@
+/**
+ * Stable identity key for UIResource payloads (v6.5.0).
+ *
+ * Consumers need a way to derive a deterministic key from a layout/component
+ * payload — for `<For>` keys, dedup detection, telemetry correlation, etc.
+ *
+ * Spec semantics : `UILayout.id` and `UIComponent.id` are obligatoires for
+ * any well-formed payload. When they are present and non-empty, this helper
+ * returns them as-is. When they are missing (e.g. consumer passing a "bare"
+ * chart payload `{ type: 'chart', params: {...} }` without wrapping it in
+ * a layout), the helper derives a stable key from the *content* — never
+ * from a timestamp or counter.
+ *
+ * The hash is FNV-1a 32-bit on a deterministically stringified form of the
+ * payload (sorted keys, undefined entries skipped). This is intentionally
+ * synchronous and dependency-free so consumers can call it inside a Solid
+ * memo or render function without ceremony.
+ */
+
+const FNV_OFFSET_BASIS = 0x811c9dc5
+const FNV_PRIME = 0x01000193
+
+function fnv1a(str: string): string {
+  let hash = FNV_OFFSET_BASIS
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i)
+    hash = Math.imul(hash, FNV_PRIME)
+  }
+  return (hash >>> 0).toString(36).padStart(7, '0')
+}
+
+/**
+ * Deterministic JSON-like serialization. Object keys are sorted ; entries
+ * with `undefined` values are skipped (mirroring `JSON.stringify` semantics
+ * but with a stable order). Used as the input to `fnv1a()`.
+ */
+function stableStringify(value: unknown): string {
+  if (value === undefined) return 'undefined'
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) {
+    return '[' + value.map(stableStringify).join(',') + ']'
+  }
+  const obj = value as Record<string, unknown>
+  const keys = Object.keys(obj)
+    .sort()
+    .filter((k) => obj[k] !== undefined)
+  return (
+    '{' +
+    keys.map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k])).join(',') +
+    '}'
+  )
+}
+
+/**
+ * Strip fields that should NOT contribute to identity :
+ *   - top-level `id` : we're computing the absent identity
+ *   - `metadata.generatedAt` : timestamp of generation, not of identity
+ */
+function normalizeForHash(input: unknown): unknown {
+  if (!input || typeof input !== 'object') return input
+  const { id: _id, ...rest } = input as Record<string, unknown>
+  void _id
+  if (rest.metadata && typeof rest.metadata === 'object' && !Array.isArray(rest.metadata)) {
+    const meta = rest.metadata as Record<string, unknown>
+    const { generatedAt: _t, ...metaRest } = meta
+    void _t
+    rest.metadata = Object.keys(metaRest).length > 0 ? metaRest : undefined
+  }
+  return rest
+}
+
+/**
+ * Returns a stable identity key for a UIResource payload.
+ *
+ * - If `input.id` is a non-empty string, returns it verbatim. This is the
+ *   path taken by well-formed payloads (cf. spec §Identity).
+ * - Otherwise, returns a 7-char base36 FNV-1a hash of the normalized
+ *   content. Stable across renders, identical for structurally identical
+ *   payloads.
+ *
+ * The hash is NOT cryptographic ; it's a dedup/correlation key. Collisions
+ * are theoretically possible but vanishingly rare for the payload shapes
+ * MCP-UI emits in practice.
+ */
+export function getUiResourceStableKey(input: unknown): string {
+  if (input && typeof input === 'object') {
+    const id = (input as { id?: unknown }).id
+    if (typeof id === 'string' && id.length > 0) return id
+  }
+  return fnv1a(stableStringify(normalizeForHash(input)))
+}