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

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

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