@seed-ship/mcp-ui-solid 6.3.1 → 6.5.0

package/src/index.ts

@@ -44,6 +44,7 @@ export type { FeedbackInlineProps, FeedbackInlineContext } from './components/Fe
 export { ChatBusProvider, useChatBus } from './hooks/useChatBus'
 export { ChatPrompt } from './components/ChatPrompt'
 export { ElicitationForm } from './components/ElicitationForm'
+export { PortalDropdownMenu } from './components/PortalDropdownMenu'
 export { ScratchpadPanel } from './components/ScratchpadPanel'
 export {
   dispatchScratchpad,
@@ -104,6 +105,14 @@ 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'
+
 // Telemetry sink (B.5 — v5.6.0)
 export {
   MCPUITelemetryProvider,
@@ -126,6 +135,7 @@ export type { ExpandableWrapperProps } from './components/ExpandableWrapper'
 export type { ComponentToolbarProps, ToolbarAction, ToolbarIcon } from './components/ComponentToolbar'
 export type { ChatPromptProps } from './components/ChatPrompt'
 export type { ElicitationFormProps } from './components/ElicitationForm'
+export type { PortalDropdownMenuProps } from './components/PortalDropdownMenu'
 export type { ScratchpadPanelProps } from './components/ScratchpadPanel'
 export type { VerifiedTextProps } from './components/VerifiedText'
 export type { DataPreviewSectionProps } from './components/DataPreviewSection'

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)))
+}