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

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

package/src/stores/scratchpad-store.tsx

@@ -0,0 +1,244 @@
+/**
+ * Scratchpad Store — reactive state for HITL scratchpad
+ *
+ * @experimental
+ *
+ * **v5.2.0 :** the store is now a factory (`createScratchpadStore()`) with a
+ * module-level singleton kept as default. Two consumption modes :
+ *
+ * 1. **Singleton mode (default, zero-config)** — `dispatchScratchpad(event)` +
+ *    `useScratchpadState()` read/write the module singleton. This is the v4.x
+ *    path and keeps working unchanged.
+ *
+ * 2. **Multi-instance mode** — wrap a subtree in `<ScratchpadStoreProvider>`
+ *    (it creates a scoped `ScratchpadStoreHandle` internally, or use your own
+ *    via the `store` prop). `useScratchpadState()` auto-detects the context
+ *    and reads from it; `ScratchpadPanel` mounted inside the provider reads
+ *    the scoped store. Non-reactive callers (SSE parsers) should pass the
+ *    handle explicitly — do NOT try to reach context from a non-reactive
+ *    scope.
+ */
+
+import { createContext, useContext, type ParentComponent, type JSX } from 'solid-js'
+import { createStore, produce } from 'solid-js/store'
+import type { ScratchpadState, ScratchpadEvent, ScratchpadSection } from '../types/chat-bus'
+
+// ─── Handle shape ─────────────────────────────────────────────
+
+export interface ScratchpadStoreHandle {
+  /** Mutate the store from an SSE/parser callback. */
+  dispatch: (event: ScratchpadEvent) => void
+  /** Reactive accessor for the current scratchpad state (null when closed). */
+  state: () => ScratchpadState | null
+  /** Reactive accessor for the pinned flag. */
+  pinned: () => boolean
+  /** Close the scratchpad (equivalent to dispatching an action='close'). */
+  close: () => void
+}
+
+// ─── Factory ──────────────────────────────────────────────────
+
+/**
+ * Create an isolated scratchpad store instance.
+ *
+ * Use this when you need two or more scratchpads live at the same time
+ * (e.g. chat scratchpad + admin dashboard scratchpad). Pair with
+ * `<ScratchpadStoreProvider store={...}>` to scope a SolidJS subtree.
+ *
+ * @experimental
+ * @since v5.2.0
+ */
+export function createScratchpadStore(): ScratchpadStoreHandle {
+  const [scratchpadStore, setScratchpadStore] = createStore<{
+    current: ScratchpadState | null
+    pinned: boolean
+  }>({ current: null, pinned: false })
+
+  const dispatch = (event: ScratchpadEvent): void => {
+    if (event.action === 'create') {
+      console.info(
+        `%c[MCP-UI] dispatchScratchpad%c create id=${event.id} sections=${event.sections?.length || 0} status=${event.status || 'loading'}${event.pinned ? ' pinned' : ''}`,
+        'color: #10b981; font-weight: bold',
+        'color: inherit'
+      )
+      setScratchpadStore({
+        current: {
+          id: event.id,
+          title: event.title || '',
+          sections: event.sections || [],
+          filters: event.filters || {},
+          preview: event.preview,
+          agentMessages: event.agentMessages || [],
+          status: event.status || 'loading',
+          previewEndpoint: (event as any).previewEndpoint,
+          previewDebounce: (event as any).previewDebounce,
+          previewMethod: (event as any).previewMethod,
+          previewHeaders: (event as any).previewHeaders,
+          turn: (event as any).turn,
+          totalTurns: (event as any).totalTurns,
+          turnHistory: (event as any).turnHistory,
+        },
+        pinned: event.pinned || false,
+      })
+    } else if (event.action === 'update') {
+      console.info(
+        `%c[MCP-UI] dispatchScratchpad%c update id=${event.id} sectionMode=${event.sectionMode || 'replace'} sections=${event.sections?.length || 0} status=${event.status || '-'}`,
+        'color: #3b82f6; font-weight: bold',
+        'color: inherit'
+      )
+      setScratchpadStore(
+        produce((s) => {
+          if (!s.current || s.current.id !== event.id) {
+            console.warn(
+              `[MCP-UI] dispatchScratchpad: update for id=${event.id} but current is ${s.current?.id || 'null'}. Ignoring.`
+            )
+            return
+          }
+
+          if (event.sections) {
+            const mode = event.sectionMode || 'replace'
+            if (mode === 'replace') {
+              s.current.sections = event.sections
+            } else if (mode === 'append') {
+              s.current.sections = [...s.current.sections, ...event.sections]
+            } else if (mode === 'upsert') {
+              let matchCount = 0
+              for (const incoming of event.sections) {
+                const idx = s.current.sections.findIndex(
+                  (sec: ScratchpadSection) => sec.id === incoming.id
+                )
+                if (idx >= 0) {
+                  s.current.sections[idx] = incoming
+                  matchCount++
+                } else {
+                  s.current.sections.push(incoming)
+                }
+              }
+              if (matchCount === 0 && event.sections.length > 0) {
+                console.warn(
+                  `[MCP-UI] dispatchScratchpad: sectionMode='upsert' but no IDs matched. ` +
+                    `Incoming: [${event.sections.map((s: ScratchpadSection) => s.id).join(', ')}] ` +
+                    `Existing: [${s.current.sections.map((s: ScratchpadSection) => s.id).join(', ')}]. All appended.`
+                )
+              }
+            }
+          }
+          if (event.agentMessages) s.current.agentMessages = event.agentMessages
+          if (event.status) s.current.status = event.status
+          if (event.filters) s.current.filters = event.filters
+          if (event.preview) s.current.preview = event.preview
+          if (event.pinned != null) s.pinned = event.pinned
+          if ((event as any).turnHistory) s.current.turnHistory = (event as any).turnHistory
+          if ((event as any).turn != null) s.current.turn = (event as any).turn
+        })
+      )
+    } else if (event.action === 'close') {
+      console.info(
+        `%c[MCP-UI] dispatchScratchpad%c close id=${event.id}`,
+        'color: #6b7280; font-weight: bold',
+        'color: inherit'
+      )
+      setScratchpadStore({ current: null, pinned: false })
+    }
+  }
+
+  return {
+    dispatch,
+    state: () => scratchpadStore.current,
+    pinned: () => scratchpadStore.pinned,
+    close: () => setScratchpadStore({ current: null, pinned: false }),
+  }
+}
+
+// ─── Module-level singleton (v4.x-compatible default) ─────────
+
+const defaultStore: ScratchpadStoreHandle = createScratchpadStore()
+
+/**
+ * Function for the PARSER/STORE — mutates the **module-level singleton**
+ * scratchpad state. Use this when you only need one scratchpad at a time
+ * (single-instance consumer, the v4.x pattern).
+ *
+ * For multi-instance scenarios, prefer `createScratchpadStore()` and pass the
+ * handle around explicitly.
+ *
+ * @example
+ * // In your SSE parser callback — ONE LINE
+ * onScratchpad: (data) => dispatchScratchpad(data as ScratchpadEvent)
+ */
+export function dispatchScratchpad(event: ScratchpadEvent): void {
+  defaultStore.dispatch(event)
+}
+
+// ─── Context (v5.2.0) ─────────────────────────────────────────
+
+/**
+ * Context for a scoped scratchpad store. Populated by
+ * `<ScratchpadStoreProvider>`. Read by `useScratchpadState()` with automatic
+ * fallback to the module-level singleton when the context is absent.
+ *
+ * @experimental
+ * @since v5.2.0
+ */
+export const ScratchpadStoreContext = createContext<ScratchpadStoreHandle | undefined>(undefined)
+
+/**
+ * Provide a scoped `ScratchpadStoreHandle` to a SolidJS subtree. Children
+ * reading via `useScratchpadState()` or rendering a `<ScratchpadPanel>` will
+ * bind to this store instead of the module singleton.
+ *
+ * If no `store` prop is passed, a fresh store is created for the provider's
+ * lifetime. Pass `store` explicitly when you need the handle outside the
+ * tree (e.g. in an SSE parser that lives at the app root).
+ *
+ * @experimental
+ * @since v5.2.0
+ *
+ * @example
+ * const chatStore = createScratchpadStore()
+ * const adminStore = createScratchpadStore()
+ *
+ * <ScratchpadStoreProvider store={chatStore}>
+ *   <ChatInterface />
+ * </ScratchpadStoreProvider>
+ * <ScratchpadStoreProvider store={adminStore}>
+ *   <AdminDashboard />
+ * </ScratchpadStoreProvider>
+ */
+export const ScratchpadStoreProvider: ParentComponent<{
+  store?: ScratchpadStoreHandle
+}> = (props): JSX.Element => {
+  const store = props.store ?? createScratchpadStore()
+  return (
+    <ScratchpadStoreContext.Provider value={store}>{props.children}</ScratchpadStoreContext.Provider>
+  )
+}
+
+// ─── Reactive hook (context-aware) ────────────────────────────
+
+/**
+ * Hook for the COMPONENT — reads the scratchpad state reactively.
+ *
+ * **v5.2.0 :** if called inside a `<ScratchpadStoreProvider>`, reads the
+ * scoped handle; otherwise falls back to the module singleton. Old v4.x
+ * consumers keep working unchanged.
+ *
+ * @example
+ * const { state, pinned, close } = useScratchpadState()
+ * <Show when={state()}>
+ *   <ScratchpadPanel state={state()!} pinned={pinned()} onClose={close} />
+ * </Show>
+ */
+export function useScratchpadState(): {
+  state: () => ScratchpadState | null
+  pinned: () => boolean
+  close: () => void
+} {
+  const scoped = useContext(ScratchpadStoreContext)
+  const handle = scoped ?? defaultStore
+  return {
+    state: handle.state,
+    pinned: handle.pinned,
+    close: handle.close,
+  }
+}

package/src/types/chat-bus.ts

@@ -6,6 +6,7 @@
  * See CHANGELOG for breaking changes on experimental types.
  */
 
+import type { JSX } from 'solid-js'
 import type { UIComponent, UILayout } from './index'
 
 // ─── Event Base ──────────────────────────────────────────────
@@ -52,6 +53,7 @@ export interface ChatEvents {
   // --- Interactions ---
   onChatPromptResponse: (event: ChatEventBase & { response: ChatPromptResponse }) => void
   onClarificationNeeded: (event: ChatEventBase & { clarification: ClarificationEvent }) => void
+  onElicitation: (event: ChatEventBase & { elicitation: ElicitationEvent }) => void
 
   // --- Agentic (handled by app, not MCP-UI) ---
   onAgentSwitch: (event: ChatEventBase & { agent: AgentContext }) => void
@@ -97,15 +99,44 @@ export interface ChatCommands {
   /**
    * Show a ChatPrompt (choice, confirm, form) above the input (C4).
    *
-   * **Known limitation (v4.3.9):** Not re-entrant. If called while another
-   * prompt is already active, the previous prompt's Promise will never resolve
-   * (memory leak). Host apps must queue prompts or dismiss the previous one
-   * manually before showing a new one. Fix planned for v4.4.0 (auto-reject
-   * previous prompt or FIFO queue).
+   * **No default handler in v5.0.0 / v5.1.0.** `showChatPrompt` is a command
+   * *name*, not a default implementation — mcp-ui ships `ChatPrompt` (the
+   * presentation component) and the bus (event/command plumbing), but the
+   * handler that threads a Promise resolver through the SolidJS lifecycle is
+   * the consumer's responsibility. Every host app calls
+   * `bus.commands.handle('showChatPrompt', (config, signal?) => { ... })`.
    *
-   * **AbortSignal limitation (v4.3.9):** The `signal` argument is currently
-   * unused — `ChatPrompt` does not listen to aborts. Host apps must wire
-   * abort → Promise rejection themselves. Fix planned for v4.4.0.
+   * ### Implementer contract
+   *
+   * A conforming handler MUST:
+   *
+   * 1. Return a `Promise<ChatPromptResponse>`.
+   * 2. Resolve the Promise from the `ChatPrompt` component's `onSubmit`
+   *    (explicit answer) or from `onDismiss` (dismissed flag true).
+   * 3. If a `signal` is provided:
+   *    - If `signal.aborted` is already `true`, reject with
+   *      `new DOMException('Prompt aborted', 'AbortError')` synchronously
+   *      (or via `Promise.reject`) and do NOT show the UI.
+   *    - Otherwise, register `signal.addEventListener('abort', () =>
+   *      reject(new DOMException('Prompt aborted', 'AbortError')))` and
+   *      clean up the listener on resolve/dismiss.
+   * 4. Enforce re-entrance policy — if a previous prompt is still active
+   *    when a new one arrives, the recommended behavior is auto-reject the
+   *    previous Promise with a custom error (e.g. `PromptReplacedError`).
+   *    Alternatives: FIFO queue, or throw synchronously.
+   *
+   * The `DOMException('AbortError')` shape is the Web Platform convention
+   * (matches `fetch()`, `Response.body.cancel()`, `WritableStream.abort()`).
+   * Consumers branching on the error can do
+   * `catch (err) { if (err.name === 'AbortError') return; throw err }`.
+   *
+   * ### Planned primitive (v5.2.0)
+   *
+   * A `createChatPromptController(setActivePrompt)` helper will centralise
+   * the resolver lifecycle + abort + re-entrance logic once, so consumers
+   * can write `bus.commands.handle('showChatPrompt', ctrl.handle)` instead
+   * of threading a `let chatPromptResolver` closure by hand. Design doc:
+   * `docs/2026/r&d/mcpui-v5.1.0-consensus.md`.
    */
   showChatPrompt: (config: ChatPromptConfig, signal?: AbortSignal) => Promise<ChatPromptResponse>
   /** Dismiss the active ChatPrompt */
@@ -208,21 +239,95 @@ export interface ChatPromptConfig {
   config: ChoicePromptConfig | ConfirmPromptConfig | FormPromptConfig
 }
 
-export interface ChoicePromptConfig {
-  options: Array<{
-    value: string
-    label: string
-    icon?: string
-    description?: string
-    /**
-     * Free-form metadata (confidence, source, tags, ...).
-     * Opaque to default renderer — use a custom ChoiceBody wrapper to display it.
-     * Preserved through showChatPrompt → ChatPromptResponse roundtrip.
-     * @since v4.3.9
-     */
-    metadata?: Record<string, unknown>
-  }>
+/**
+ * A single choice option. The generic `TMeta` parameter flows through the
+ * whole `ChoicePromptConfig<TMeta>` shape so consumers can strongly-type
+ * their metadata in `optionRenderer` without casting.
+ *
+ * @since v4.3.9 (metadata), v5.1.0 (generic TMeta + optionRenderer typing)
+ */
+export interface ChoiceOption<TMeta = Record<string, unknown>> {
+  value: string
+  label: string
+  icon?: string
+  description?: string
+  /**
+   * Free-form metadata (confidence, source, tags, ...).
+   * Opaque to the default renderer — use `optionRenderer` to display it.
+   * Preserved through `showChatPrompt → ChatPromptResponse` roundtrip.
+   * @since v4.3.9
+   */
+  metadata?: TMeta
+}
+
+export interface ChoicePromptConfig<TMeta = Record<string, unknown>> {
+  options: Array<ChoiceOption<TMeta>>
   layout?: 'horizontal' | 'vertical' | 'grid'
+  /**
+   * Optional render prop for custom option bodies (badges, confidence
+   * indicators, rich layouts). Replaces the default `label + icon +
+   * description` body. mcp-ui still wraps the returned JSX in a `<button>`
+   * with the `onClick` handler, keyboard support, and focus styles — only
+   * the *content* of the button is yours.
+   *
+   * @param option The full `ChoiceOption` including strongly-typed `metadata`.
+   * @param index  Zero-based position in the `options` array.
+   *
+   * @example
+   * ```tsx
+   * interface ConfBadgeMeta { confidence: number; source: string }
+   *
+   * bus.commands.exec('showChatPrompt', {
+   *   type: 'choice',
+   *   title: 'Pick an intent',
+   *   config: {
+   *     layout: 'vertical',
+   *     options: [
+   *       { value: 'a', label: 'Immobilier', metadata: { confidence: 0.9, source: 'llm' } },
+   *       { value: 'b', label: 'Santé',      metadata: { confidence: 0.4, source: 'llm' } },
+   *     ],
+   *     optionRenderer: (opt: ChoiceOption<ConfBadgeMeta>) => (
+   *       <div>
+   *         {opt.label}
+   *         <span class="ml-2 text-xs">
+   *           ({Math.round((opt.metadata?.confidence ?? 0) * 100)}%)
+   *         </span>
+   *       </div>
+   *     ),
+   *   },
+   * } as ChatPromptConfig)
+   * ```
+   *
+   * ### ⚠️ Accessibility
+   * Do NOT return `<button>`, `<a href>`, or other interactive elements from
+   * `optionRenderer`. mcp-ui already wraps the content in a `<button>`, and
+   * nested interactive elements break screen-reader semantics, keyboard
+   * focus order, and click-through behaviour.
+   *
+   * ### ⚠️ Stale closures
+   * `optionRenderer` is called once per option per render. If you capture
+   * SolidJS signals inside the closure, wrap the access in a thunk so the
+   * framework tracks the dependency correctly. Don't destructure signal
+   * values into locals outside reactive scopes.
+   *
+   * @since v5.1.0
+   */
+  optionRenderer?: (option: ChoiceOption<TMeta>, index: number) => JSX.Element
+  /**
+   * Custom Tailwind classes appended to each option button (after mcp-ui's
+   * defaults). Escape hatch for colour/border/radius tweaks that don't
+   * warrant a full `optionRenderer`.
+   *
+   * @since v5.1.0
+   */
+  buttonClass?: string
+  /**
+   * Custom Tailwind classes appended to the options container (the
+   * flex/grid wrapper that lays out the buttons).
+   *
+   * @since v5.1.0
+   */
+  containerClass?: string
 }
 
 export interface ConfirmPromptConfig {
@@ -464,6 +569,45 @@ export interface ToolCallEvent {
   duration_ms?: number
 }
 
+/**
+ * MCP `elicitation/create` request payload — server asks the client to
+ * collect input from the user according to a JSON Schema.
+ *
+ * Derived from MCP spec 2025-06-18. See
+ * `elicitationToPromptConfig()` in `services/chat-bus.ts` for the
+ * helper that converts this to a `ChatPromptConfig`.
+ *
+ * @experimental
+ * @since v5.2.0
+ */
+export interface ElicitationEvent {
+  /** Question / instruction to present to the user. */
+  message: string
+  /** JSON Schema describing the expected response shape. Object with primitive properties only. */
+  requestedSchema: ElicitationRequestedSchema
+}
+
+export interface ElicitationRequestedSchema {
+  type: 'object'
+  properties: Record<string, ElicitationPropertySchema>
+  required?: string[]
+}
+
+export interface ElicitationPropertySchema {
+  type: 'string' | 'number' | 'integer' | 'boolean'
+  title?: string
+  description?: string
+  /** Enum of allowed values (strings or numbers). */
+  enum?: Array<string | number>
+  /** Parallel array with display labels for each enum entry. */
+  enumNames?: string[]
+  default?: unknown
+  minimum?: number
+  maximum?: number
+  /** String format hint — date, date-time, email, uri. */
+  format?: 'date' | 'date-time' | 'email' | 'uri'
+}
+
 export interface ClarificationEvent {
   /** The question to ask the user */
   question: string