@seed-ship/mcp-ui-solid 5.1.0 → 5.2.0

package/src/services/chat-bus.ts

@@ -14,7 +14,10 @@ import type {
   EventSubscribeOptions,
   ScratchpadSection,
   ClarificationEvent,
+  ElicitationEvent,
+  ElicitationPropertySchema,
   ChatPromptConfig,
+  FormPromptConfig,
 } from '../types/chat-bus'
 
 // ─── Event Emitter ───────────────────────────────────────────
@@ -245,6 +248,118 @@ export function mergeScratchpadSections(
  *   bus.commands.exec('showChatPrompt', clarificationToPromptConfig(clarification))
  * })
  */
+// ─── Elicitation → Prompt Helper (v5.2.0) ───────────────────
+
+/**
+ * Convert an MCP `elicitation/create` payload into a `ChatPromptConfig`.
+ *
+ * Mapping rules :
+ * - Single `boolean` property → `type: 'confirm'`
+ * - Single property with `enum` of ≤4 values → `type: 'choice'` (one option per enum value)
+ * - Anything else → `type: 'form'` with one field per schema property
+ *
+ * JSON Schema primitive types map to mcp-ui form field types :
+ *
+ * | JSON Schema | mcp-ui FormFieldType |
+ * |---|---|
+ * | `type: 'string'` | `'text'` |
+ * | `type: 'string', format: 'email'` | `'email'` |
+ * | `type: 'string', format: 'date'` or `'date-time'` | `'date'` |
+ * | `type: 'string', enum: [...]` | `'select'` |
+ * | `type: 'number' \| 'integer'` | `'number'` |
+ * | `type: 'boolean'` | `'checkbox'` |
+ *
+ * Unknown shapes fall through to plain text with a `helpText` warning.
+ *
+ * @experimental
+ * @since v5.2.0
+ *
+ * @example
+ * bus.events.on('onElicitation', ({ elicitation }) => {
+ *   bus.commands.exec('showChatPrompt', elicitationToPromptConfig(elicitation))
+ * })
+ */
+export function elicitationToPromptConfig(event: ElicitationEvent): ChatPromptConfig {
+  const propEntries = Object.entries(event.requestedSchema.properties)
+
+  // Shortcut 1 : single boolean → confirm
+  if (propEntries.length === 1 && propEntries[0][1].type === 'boolean') {
+    return {
+      type: 'confirm',
+      title: event.message,
+      config: {
+        message: propEntries[0][1].description,
+      },
+    }
+  }
+
+  // Shortcut 2 : single enum property with ≤4 values → choice
+  if (propEntries.length === 1) {
+    const [, schema] = propEntries[0]
+    if (schema.enum && schema.enum.length > 0 && schema.enum.length <= 4) {
+      return {
+        type: 'choice',
+        title: event.message,
+        config: {
+          options: schema.enum.map((val, idx) => ({
+            value: String(val),
+            label: schema.enumNames?.[idx] ?? String(val),
+          })),
+          layout: 'vertical',
+        },
+      }
+    }
+  }
+
+  // Default : full form
+  const required = new Set(event.requestedSchema.required ?? [])
+  const fields: FormPromptConfig['fields'] = propEntries.map(([name, schema]) => ({
+    name,
+    label: schema.title ?? name,
+    ...schemaToFieldType(schema),
+    required: required.has(name),
+    helpText: schema.description,
+    ...(schema.default !== undefined ? { placeholder: String(schema.default) } : {}),
+  }))
+
+  return {
+    type: 'form',
+    title: event.message,
+    config: { fields },
+  }
+}
+
+function schemaToFieldType(
+  schema: ElicitationPropertySchema
+):
+  | { type: FormPromptConfig['fields'][number]['type']; options?: Array<{ label: string; value: string }> }
+  | { type: FormPromptConfig['fields'][number]['type']; helpText?: string } {
+  // Enum → select
+  if (schema.enum && schema.enum.length > 0) {
+    return {
+      type: 'select',
+      options: schema.enum.map((val, idx) => ({
+        label: schema.enumNames?.[idx] ?? String(val),
+        value: String(val),
+      })),
+    }
+  }
+
+  if (schema.type === 'boolean') return { type: 'checkbox' }
+  if (schema.type === 'number' || schema.type === 'integer') return { type: 'number' }
+  if (schema.type === 'string') {
+    if (schema.format === 'email') return { type: 'email' }
+    if (schema.format === 'date' || schema.format === 'date-time') return { type: 'date' }
+    return { type: 'text' }
+  }
+
+  // Unknown primitive — fall back to text with a warning
+  console.warn(
+    `[MCP-UI] elicitationToPromptConfig: unsupported schema type "${(schema as { type?: string }).type}", falling back to text.`
+  )
+  return { type: 'text' }
+}
+
 export function clarificationToPromptConfig(
   event: ClarificationEvent
 ): ChatPromptConfig {

package/src/services/chat-prompt-controller.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Tests for createChatPromptController — v5.2.0
+ */
+
+import { describe, it, expect } from 'vitest'
+import { createRoot } from 'solid-js'
+import {
+  createChatPromptController,
+  PromptReplacedError,
+} from './chat-prompt-controller'
+import type { ChatPromptConfig, ChatPromptResponse } from '../types/chat-bus'
+
+const choiceConfig = (title = 'Pick one'): ChatPromptConfig => ({
+  type: 'choice',
+  title,
+  config: { options: [{ value: 'a', label: 'A' }, { value: 'b', label: 'B' }] },
+})
+
+const confirmConfig = (title = 'Confirm?'): ChatPromptConfig => ({
+  type: 'confirm',
+  title,
+  config: { message: 'Sure?' },
+})
+
+const choiceResponse = (value: string): ChatPromptResponse => ({
+  type: 'choice',
+  value,
+  label: value,
+})
+
+describe('createChatPromptController — v5.2.0', () => {
+  it('sequential prompts both resolve', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+
+      const p1 = ctrl.handle(choiceConfig('First'))
+      expect(ctrl.activePrompt()?.title).toBe('First')
+      ctrl.resolveActive(choiceResponse('a'))
+      expect(ctrl.activePrompt()).toBeNull()
+      const r1 = await p1
+      expect(r1.value).toBe('a')
+
+      const p2 = ctrl.handle(choiceConfig('Second'))
+      expect(ctrl.activePrompt()?.title).toBe('Second')
+      ctrl.resolveActive(choiceResponse('b'))
+      const r2 = await p2
+      expect(r2.value).toBe('b')
+
+      dispose()
+    })
+  })
+
+  it('re-entrant call rejects previous Promise with PromptReplacedError', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+
+      const p1 = ctrl.handle(choiceConfig('First'))
+      // Don't resolve — fire a second one
+      const p2 = ctrl.handle(choiceConfig('Second'))
+
+      await expect(p1).rejects.toBeInstanceOf(PromptReplacedError)
+
+      // The second prompt is now active and can still resolve
+      expect(ctrl.activePrompt()?.title).toBe('Second')
+      ctrl.resolveActive(choiceResponse('b'))
+      await expect(p2).resolves.toMatchObject({ value: 'b' })
+
+      dispose()
+    })
+  })
+
+  it('AbortSignal already aborted on entry rejects with DOMException AbortError', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+      const ac = new AbortController()
+      ac.abort()
+
+      const p = ctrl.handle(choiceConfig('Never shown'), ac.signal)
+      expect(ctrl.activePrompt()).toBeNull() // UI never installed
+
+      await expect(p).rejects.toMatchObject({ name: 'AbortError' })
+      dispose()
+    })
+  })
+
+  it('AbortSignal aborted during prompt rejects + clears activePrompt', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+      const ac = new AbortController()
+
+      const p = ctrl.handle(choiceConfig('Pending'), ac.signal)
+      expect(ctrl.activePrompt()?.title).toBe('Pending')
+
+      ac.abort()
+      await expect(p).rejects.toMatchObject({ name: 'AbortError' })
+      expect(ctrl.activePrompt()).toBeNull()
+
+      dispose()
+    })
+  })
+
+  it('abort() method rejects pending Promise with AbortError', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+
+      const p = ctrl.handle(choiceConfig('Will abort'))
+      ctrl.abort('Navigated away')
+
+      await expect(p).rejects.toMatchObject({ name: 'AbortError' })
+      expect(ctrl.activePrompt()).toBeNull()
+
+      dispose()
+    })
+  })
+
+  it('dismissActive resolves with dismissed: true and preserves the prompt type', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+      const p = ctrl.handle(confirmConfig('Really?'))
+
+      ctrl.dismissActive()
+      const r = await p
+      expect(r).toMatchObject({ type: 'confirm', dismissed: true })
+      expect(ctrl.activePrompt()).toBeNull()
+
+      dispose()
+    })
+  })
+
+  it('resolve/dismiss after abort is a no-op (double-settle protection)', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+      const p = ctrl.handle(choiceConfig('x'))
+
+      ctrl.abort()
+      // These should not throw or re-settle
+      ctrl.resolveActive(choiceResponse('ignored'))
+      ctrl.dismissActive()
+
+      await expect(p).rejects.toMatchObject({ name: 'AbortError' })
+      dispose()
+    })
+  })
+})

package/src/services/chat-prompt-controller.ts

@@ -0,0 +1,214 @@
+/**
+ * createChatPromptController — centralised lifecycle for `showChatPrompt`
+ *
+ * @experimental
+ * @since v5.2.0
+ *
+ * The controller owns the resolver closure, AbortSignal wiring, and
+ * re-entrance policy in one primitive. Consumers go from ~20 LOC of manual
+ * wiring per app to :
+ *
+ * ```ts
+ * const ctrl = createChatPromptController()
+ * bus.commands.handle('showChatPrompt', ctrl.handle)
+ * // ...
+ * <Show when={ctrl.activePrompt()}>
+ *   {(cfg) => (
+ *     <ChatPrompt
+ *       config={cfg()}
+ *       onSubmit={ctrl.resolveActive}
+ *       onDismiss={ctrl.dismissActive}
+ *     />
+ *   )}
+ * </Show>
+ * ```
+ *
+ * ## Re-entrance policy
+ *
+ * If a new `showChatPrompt` arrives while a previous Promise is still
+ * pending, the previous Promise rejects **synchronously** with a
+ * `PromptReplacedError` before the new prompt is installed. Callers that
+ * care can branch on `err instanceof PromptReplacedError` or `err.name ===
+ * 'PromptReplacedError'`.
+ *
+ * ## Abort semantics
+ *
+ * `handle(config, signal?)` honours `AbortSignal` :
+ *
+ * - If `signal.aborted === true` on entry → returns a rejected Promise with
+ *   `new DOMException('Prompt aborted', 'AbortError')`, does NOT set
+ *   `activePrompt`.
+ * - Otherwise registers a once-only listener that rejects with the same
+ *   `DOMException` on abort, clearing the active state.
+ *
+ * `AbortError` is the Web Platform convention (matches `fetch()`,
+ * `Response.body.cancel()`, etc.) — callers can branch on `err.name ===
+ * 'AbortError'` without importing any mcp-ui type.
+ */
+
+import { createSignal, type Accessor } from 'solid-js'
+import type { ChatPromptConfig, ChatPromptResponse } from '../types/chat-bus'
+
+// ─── Error class ─────────────────────────────────────────────
+
+/**
+ * Thrown when an active `showChatPrompt` Promise is rejected because a new
+ * prompt arrived before the previous one resolved. Consumers can use
+ * `instanceof PromptReplacedError` or `err.name === 'PromptReplacedError'` to
+ * branch (retry, bail, log).
+ *
+ * @experimental
+ * @since v5.2.0
+ */
+export class PromptReplacedError extends Error {
+  readonly name = 'PromptReplacedError' as const
+  constructor(message = 'Prompt replaced by a newer one') {
+    super(message)
+  }
+}
+
+// ─── Controller shape ────────────────────────────────────────
+
+export interface ChatPromptController {
+  /**
+   * Register as the bus handler :
+   * `bus.commands.handle('showChatPrompt', ctrl.handle)`
+   */
+  handle: (config: ChatPromptConfig, signal?: AbortSignal) => Promise<ChatPromptResponse>
+
+  /**
+   * Reactive accessor for the currently active prompt config (null when no
+   * prompt is pending). Use in JSX to drive `<ChatPrompt>` rendering.
+   */
+  activePrompt: Accessor<ChatPromptConfig | null>
+
+  /** Call this from `<ChatPrompt>`'s `onSubmit` prop. */
+  resolveActive: (response: ChatPromptResponse) => void
+
+  /** Call this from `<ChatPrompt>`'s `onDismiss` prop. */
+  dismissActive: () => void
+
+  /**
+   * Cancel the active prompt programmatically (e.g. on route change). Rejects
+   * the pending Promise with the supplied reason or an `AbortError`.
+   */
+  abort: (reason?: string) => void
+}
+
+// ─── Factory ─────────────────────────────────────────────────
+
+/**
+ * Create a stateful controller that owns the active prompt Promise, the
+ * AbortSignal listener, and the re-entrance policy. See module JSDoc for
+ * full usage.
+ *
+ * @experimental
+ * @since v5.2.0
+ */
+export function createChatPromptController(): ChatPromptController {
+  const [activePrompt, setActivePrompt] = createSignal<ChatPromptConfig | null>(null)
+
+  interface PendingEntry {
+    type: ChatPromptConfig['type']
+    resolve: (r: ChatPromptResponse) => void
+    reject: (err: unknown) => void
+    signal?: AbortSignal
+    onAbort?: () => void
+  }
+
+  let pending: PendingEntry | null = null
+
+  function cleanupAbort(entry: PendingEntry): void {
+    if (entry.signal && entry.onAbort) {
+      entry.signal.removeEventListener('abort', entry.onAbort)
+    }
+  }
+
+  function clearPending(): void {
+    if (pending) {
+      cleanupAbort(pending)
+      pending = null
+    }
+    setActivePrompt(null)
+  }
+
+  function handle(
+    config: ChatPromptConfig,
+    signal?: AbortSignal
+  ): Promise<ChatPromptResponse> {
+    // Re-entrance : synchronously reject the previous Promise before
+    // installing the new prompt. The caller's .catch sees the rejection
+    // on the microtask boundary regardless.
+    if (pending) {
+      const previous = pending
+      pending = null
+      cleanupAbort(previous)
+      previous.reject(new PromptReplacedError())
+    }
+
+    // Abort already tripped on entry : return a rejected Promise without
+    // ever showing the UI.
+    if (signal?.aborted) {
+      setActivePrompt(null)
+      return Promise.reject(new DOMException('Prompt aborted', 'AbortError'))
+    }
+
+    return new Promise<ChatPromptResponse>((resolve, reject) => {
+      const entry: PendingEntry = { type: config.type, resolve, reject, signal }
+
+      if (signal) {
+        entry.onAbort = () => {
+          // If this entry is still active, reject + clear. If a newer prompt
+          // has since replaced it, the cleanup already ran — no-op.
+          if (pending === entry) {
+            pending = null
+            cleanupAbort(entry)
+            setActivePrompt(null)
+            reject(new DOMException('Prompt aborted', 'AbortError'))
+          }
+        }
+        signal.addEventListener('abort', entry.onAbort, { once: true })
+      }
+
+      pending = entry
+      setActivePrompt(config)
+    })
+  }
+
+  function resolveActive(response: ChatPromptResponse): void {
+    if (!pending) return
+    const entry = pending
+    pending = null
+    cleanupAbort(entry)
+    setActivePrompt(null)
+    entry.resolve(response)
+  }
+
+  function dismissActive(): void {
+    if (!pending) return
+    const entry = pending
+    pending = null
+    cleanupAbort(entry)
+    setActivePrompt(null)
+    // Surface as a resolved Promise with dismissed: true — matches existing
+    // ChatPrompt onDismiss contract from v4.x.
+    entry.resolve({ type: entry.type, value: '', label: '', dismissed: true })
+  }
+
+  function abort(reason = 'Prompt aborted'): void {
+    if (!pending) return
+    const entry = pending
+    pending = null
+    cleanupAbort(entry)
+    setActivePrompt(null)
+    entry.reject(new DOMException(reason, 'AbortError'))
+  }
+
+  return {
+    handle,
+    activePrompt,
+    resolveActive,
+    dismissActive,
+    abort,
+  }
+}

package/src/stores/scratchpad-store.test.tsx

@@ -0,0 +1,140 @@
+/**
+ * Tests for scratchpad-store — v5.2.0 createScratchpadStore factory + provider
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { render, cleanup } from '@solidjs/testing-library'
+import {
+  createScratchpadStore,
+  dispatchScratchpad,
+  useScratchpadState,
+  ScratchpadStoreProvider,
+} from './scratchpad-store'
+import type { ScratchpadEvent } from '../types/chat-bus'
+
+const createEvent = (id: string, title: string): ScratchpadEvent => ({
+  id,
+  action: 'create',
+  title,
+  sections: [],
+  status: 'ready',
+})
+
+describe('createScratchpadStore — v5.2.0', () => {
+  beforeEach(() => {
+    cleanup()
+    // Silence the info/warn logs that dispatch emits
+    vi.spyOn(console, 'info').mockImplementation(() => {})
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  it('two stores do not share state', () => {
+    const storeA = createScratchpadStore()
+    const storeB = createScratchpadStore()
+
+    storeA.dispatch(createEvent('a', 'Store A'))
+
+    expect(storeA.state()?.id).toBe('a')
+    expect(storeA.state()?.title).toBe('Store A')
+    expect(storeB.state()).toBeNull()
+  })
+
+  it('close() resets state independently per store', () => {
+    const storeA = createScratchpadStore()
+    const storeB = createScratchpadStore()
+
+    storeA.dispatch(createEvent('a', 'Store A'))
+    storeB.dispatch(createEvent('b', 'Store B'))
+
+    storeA.close()
+
+    expect(storeA.state()).toBeNull()
+    expect(storeB.state()?.id).toBe('b')
+  })
+
+  it('pinned flag is per-store', () => {
+    const storeA = createScratchpadStore()
+    const storeB = createScratchpadStore()
+
+    storeA.dispatch({ ...createEvent('a', 'A'), pinned: true })
+    storeB.dispatch({ ...createEvent('b', 'B'), pinned: false })
+
+    expect(storeA.pinned()).toBe(true)
+    expect(storeB.pinned()).toBe(false)
+  })
+
+  it('ScratchpadStoreProvider without store prop creates a fresh store', () => {
+    let capturedState: ReturnType<typeof useScratchpadState> | null = null
+
+    const Child = () => {
+      capturedState = useScratchpadState()
+      return <div>child</div>
+    }
+
+    render(() => (
+      <ScratchpadStoreProvider>
+        <Child />
+      </ScratchpadStoreProvider>
+    ))
+
+    expect(capturedState).not.toBeNull()
+    expect(capturedState!.state()).toBeNull()
+    expect(capturedState!.pinned()).toBe(false)
+  })
+
+  it('ScratchpadStoreProvider with explicit store prop binds children to it', () => {
+    const scoped = createScratchpadStore()
+    scoped.dispatch(createEvent('scoped', 'Scoped title'))
+
+    let capturedState: ReturnType<typeof useScratchpadState> | null = null
+    const Child = () => {
+      capturedState = useScratchpadState()
+      return <div>child</div>
+    }
+
+    render(() => (
+      <ScratchpadStoreProvider store={scoped}>
+        <Child />
+      </ScratchpadStoreProvider>
+    ))
+
+    expect(capturedState!.state()?.id).toBe('scoped')
+    expect(capturedState!.state()?.title).toBe('Scoped title')
+  })
+
+  it('useScratchpadState outside provider falls back to module singleton', () => {
+    // Reset singleton first by writing a unique id, then verifying dispatch lands on it
+    dispatchScratchpad(createEvent('singleton-test', 'Singleton'))
+
+    let capturedState: ReturnType<typeof useScratchpadState> | null = null
+    const Child = () => {
+      capturedState = useScratchpadState()
+      return <div>child</div>
+    }
+
+    render(() => <Child />)
+
+    expect(capturedState!.state()?.id).toBe('singleton-test')
+    // Cleanup: close singleton for test isolation
+    capturedState!.close()
+  })
+
+  it('dispatchScratchpad (module fn) only writes to singleton, not scoped stores', () => {
+    const scoped = createScratchpadStore()
+    dispatchScratchpad(createEvent('global', 'Global'))
+
+    // scoped store is still empty
+    expect(scoped.state()).toBeNull()
+
+    // and the singleton carries the dispatched event
+    let singletonSnap: ReturnType<typeof useScratchpadState> | null = null
+    const Child = () => {
+      singletonSnap = useScratchpadState()
+      return <div>child</div>
+    }
+    render(() => <Child />)
+    expect(singletonSnap!.state()?.id).toBe('global')
+    // Cleanup
+    singletonSnap!.close()
+  })
+})