console.log('Hallucinated:', item)}\n/>\n```\n\n### DataPreviewSection — Source data table\n\n```tsx\nimport { DataPreviewSection } from '@seed-ship/mcp-ui-solid'\n\n\n```\n\n## GeoJSON Maps\n\nMap coordinates accept either `[lat, lng]` or `{ lat, lng }`. This package does\nnot geocode addresses or place names; resolve them before building the map\npayload. The default base tiles come from OpenStreetMap; Leaflet is the internal\nrendering engine.\n\n### GeoJSON + Choropleth + Popups\n\n```tsx\nimport { MapRenderer } from '@seed-ship/mcp-ui-solid'\n\n\n```\n\n### Multi-layer Maps\n\n```tsx\n\n```\n\n### PMTiles — Large Datasets\n\n```tsx\n\n```\n\nRequires `protomaps-leaflet` peer dependency.\n\n## Time-Series Charts (v4.0.0)\n\n```tsx\n\n```\n\n## Chat Bus — Agent Interactions (`@experimental`)\n\nBidirectional event/command system for agent-driven chat interactions. Your app keeps full control of its chat UI — the bus adds structured interactivity on top.\n\n### Architecture\n\n```\n +----------------------+\n | AGENT LAYER |\n | (your app logic) |\n +--+----------+-------+\n events | | commands\n v v\n+--------------------------------------------------+\n| Chat Messages (your app renders these) |\n| + UIResourceRenderer for MCP components |\n+--------------------------------------------------+\n| ChatPrompt (MCP-UI) - choice | confirm | form |\n+--------------------------------------------------+\n| Chat Input (your app controls this) |\n+--------------------------------------------------+\n```\n\n### Usage\n\n```tsx\nimport { ChatBusProvider, useChatBus, ChatPrompt, createChatBus } from '@seed-ship/mcp-ui-solid'\n\n// 1. Wrap your app\nfunction App() {\n return (\n \n \n \n \n )\n}\n\n// 2. Bridge your SSE events to the bus\nfunction ChatInterface() {\n const bus = useChatBus()\n const [activePrompt, setActivePrompt] = createSignal(null)\n\n onSSEEvent('done', (data) =>\n bus.events.emit('onStreamEnd', { streamKey: 'main', metadata: data }))\n\n bus.commands.handle('injectPrompt', (text) => setInputValue(text))\n bus.commands.handle('showChatPrompt', (config) => setActivePrompt(config))\n\n return (\n \n \n \n setActivePrompt(null)} />\n \n \n
\n )\n}\n```\n\n### Event Types (18) / Command Types (11)\n\nSee [Chat Bus documentation](https://github.com/theseedship/mcp-ui#chat-bus--agent-interactions-experimental) for the full event/command reference.\n\n### Bridging external clarification events (v4.3.9)\n\nWhen your MCP server emits a clarification event via SSE (e.g. a `_pause`\nframe asking the user to disambiguate intent), convert it to a `ChatPrompt`\nusing the universal `clarificationToPromptConfig` helper — no app-specific\nglue required:\n\n```tsx\nimport { clarificationToPromptConfig } from '@seed-ship/mcp-ui-solid'\n\n// In your SSE parser, when you decode a clarification frame:\nbus.events.emit('onClarificationNeeded', {\n streamKey: 'main',\n clarification: {\n question: 'Which space do you mean?',\n options: [\n { value: 'sp-1', label: 'Immobilier', metadata: { confidence: 0.9 } },\n { value: 'sp-2', label: 'Santé', metadata: { confidence: 0.6 } },\n ],\n type: 'intent_disambiguate', // opaque tag for host routing\n },\n})\n\n// Wire the event to a prompt:\nbus.events.on('onClarificationNeeded', async ({ clarification }) => {\n const response = await bus.commands.exec(\n 'showChatPrompt',\n clarificationToPromptConfig(clarification)\n )\n // POST response.value to your /api/agent-resume endpoint, etc.\n})\n```\n\nLegacy `option.file_id` is automatically migrated into `metadata.file_id`.\nArbitrary `metadata` (confidence scores, source tags, ...) flows through\nunchanged and can be rendered by a custom `ChoiceBody` wrapper.\n\n### ChatPromptResponse — dismissed / aborted / answered\n\nEvery `ChatPrompt` exchange ends in one of three outcomes:\n\n| Outcome | How | `response.dismissed` | Promise |\n|---------|-----|----------------------|---------|\n| Explicit answer | Click a choice / submit a form | `undefined` | resolves |\n| Dismissed | Click the X icon, click Cancel (confirm type) | `true` | resolves |\n| Aborted | Host app rejects the Promise via `AbortSignal` | *(n/a — never resolves)* | rejects with `DOMException('AbortError')` |\n\n> **v5.2.0** — use `createChatPromptController()` (below). The manual pattern\n> documented after it is kept for context and for consumers who prefer full\n> control over the resolver lifecycle.\n\n#### Recommended — `createChatPromptController()` (v5.2.0)\n\n```tsx\nimport { Show } from 'solid-js'\nimport {\n ChatPrompt,\n useChatBus,\n createChatPromptController,\n PromptReplacedError,\n} from '@seed-ship/mcp-ui-solid'\n\nfunction HitlHost() {\n const bus = useChatBus()\n const ctrl = createChatPromptController()\n bus.commands.handle('showChatPrompt', ctrl.handle)\n\n return (\n \n {(cfg) => (\n \n )}\n \n )\n}\n```\n\nCaller-side, re-entrance and abort are standard :\n\n```ts\ntry {\n const response = await bus.commands.exec('showChatPrompt', config, ac.signal)\n // ...\n} catch (err) {\n if (err instanceof PromptReplacedError) return // superseded by a newer prompt\n if (err instanceof Error && err.name === 'AbortError') return // navigation killed it\n throw err\n}\n```\n\n`ctrl.abort(reason?)` is also available for programmatic cancellation\n(modal close, route change, ...).\n\n#### Manual wiring (v5.1.0 reference pattern)\n\nEquivalent to the controller above — useful if you want full control over\nthe resolver closure, or if you're maintaining a v5.1.0 codebase :\n\n```tsx\nimport { createSignal } from 'solid-js'\nimport { useChatBus } from '@seed-ship/mcp-ui-solid'\nimport type { ChatPromptConfig, ChatPromptResponse } from '@seed-ship/mcp-ui-solid'\n\nfunction HitlHost() {\n const bus = useChatBus()\n const [activePrompt, setActivePrompt] = createSignal(null)\n\n // Mutable resolver + optional abort cleanup — one prompt at a time\n let active: {\n resolve: (response: ChatPromptResponse) => void\n reject: (err: unknown) => void\n cleanupAbort?: () => void\n } | null = null\n\n bus.commands.handle('showChatPrompt', (config, signal) => {\n // Re-entrance: auto-reject any previous in-flight prompt\n if (active) {\n const stale = active\n active = null\n stale.reject(new Error('PromptReplaced'))\n stale.cleanupAbort?.()\n }\n\n // Already-aborted signal → reject synchronously, never render\n if (signal?.aborted) {\n return Promise.reject(new DOMException('Prompt aborted', 'AbortError'))\n }\n\n return new Promise((resolve, reject) => {\n const onAbort = () => {\n setActivePrompt(null)\n active = null\n reject(new DOMException('Prompt aborted', 'AbortError'))\n }\n signal?.addEventListener('abort', onAbort, { once: true })\n\n active = {\n resolve,\n reject,\n cleanupAbort: () => signal?.removeEventListener('abort', onAbort),\n }\n setActivePrompt(config)\n })\n })\n\n const handleSubmit = (response: ChatPromptResponse) => {\n const a = active\n active = null\n setActivePrompt(null)\n a?.cleanupAbort?.()\n a?.resolve(response)\n }\n\n const handleDismiss = () => {\n const a = active\n active = null\n setActivePrompt(null)\n a?.cleanupAbort?.()\n a?.resolve({ type: 'choice', value: '', label: '', dismissed: true })\n }\n\n return (\n \n \n \n )\n}\n```\n\nConsumer-side the error is standard and branch-able without any mcp-ui import:\n\n```ts\ntry {\n const response = await bus.commands.exec('showChatPrompt', config, ctrl.signal)\n // ...\n} catch (err) {\n if (err instanceof Error && err.name === 'AbortError') return // navigation killed it\n throw err\n}\n```\n\nv5.2.0 collapses this to a single `createChatPromptController()` call — see\nabove. Prefer the controller unless you have a reason to manage the\nlifecycle yourself.\n\n### correlationId — host-propagated (v4.3.9)\n\n`ChatEventBase.correlationId` is opaque to mcp-ui. When an agent calls\n`sendPrompt('...')` the returned string is a correlation ID — the host app's\nSSE parser must forward this value into every subsequent event emission\n(`onToken`, `onStreamEnd`, etc.) so agents can match responses back to their\noriginal prompts. mcp-ui does not auto-propagate it across the bus.\n\n## ScratchpadPanel — HITL/AITL Shared Workspace (`@experimental`)\n\nA shared workspace where agent and human collaborate in real-time. 18 section types:\n\n| Type | Renders | Use case |\n|------|---------|----------|\n| `data` | Key-value pairs | Dataset info |\n| `filter` | Editable chips | Active filters |\n| `preview` | Count + mini-table | Live result count |\n| `message` | Agent bubble | Explanations |\n| `action` | Buttons | Validate, refine |\n| `steps` | Stepper | Guided workflow |\n| `form` | FormFieldRenderer | Interactive params |\n| `understanding` | Confidence badges | Agent comprehension |\n| `feedback` | Thumbs up/down | User validation |\n| `prompt` | Query + params | Agent interpretation |\n| `stepper` | Progress stepper | Multi-turn progress |\n| `error` | Error card | Error display + retry |\n| `source_card` | Source info card | Data source details |\n| `diff` | Before/after diff | Change preview |\n| `verified_text` | Inline badges | Data verification |\n| `data_preview` | Paginated table | Source data display |\n| `map` | GeoJSON map | Geographic data |\n| `chart` | Chart.js chart | Time-series, analytics |\n\n### Direct store (recommended)\n\n```tsx\nimport { dispatchScratchpad, useScratchpadState } from '@seed-ship/mcp-ui-solid'\n\n// In your SSE callback — ONE LINE\nonScratchpad: (data) => dispatchScratchpad(data as ScratchpadEvent)\n\n// In your component\nconst { state, pinned, close } = useScratchpadState()\n```\n\n## Component Renderers (20 types)\n\n| Type | Features |\n|------|----------|\n| `chart` | Bar, line, pie, doughnut, radar, scatter, bubble, polarArea. Native Chart.js with Chart/Data switch and PNG export; external QuickChart only on host opt-in. Time axes require a date adapter. |\n| `table` | Sortable, pagination, virtualization (10K+), CSV/TSV/JSON export |\n| `metric` | KPI cards with trends and sparklines |\n| `text` | Markdown via marked.js |\n| `code` | Syntax highlighting (highlight.js), line numbers, word wrap |\n| `map` | OpenStreetMap base tiles via Leaflet: markers, clustering, GeoJSON, choropleth, popups, multi-layer, PMTiles |\n| `graph` | Node-link relationships with optional G6; seven schema-supported layouts and layout options |\n| `form` | 18 field types, conditional fields, persistence, tool call submit |\n| `modal` | Portal overlay, sizes sm-full, Escape/backdrop close |\n| `image-gallery` | Grid layout, lightbox, keyboard nav |\n| `video` | YouTube/Vimeo/direct URL |\n| `iframe` | Tiered sandbox, 80+ whitelisted domains, COEP `credentialless` (v6.21.0) |\n| `image` | Responsive with lazy loading |\n| `link` | Styled link cards |\n| `action` | Tool call buttons |\n| `action-group` | Grouped actions with layout options |\n| `grid` | Nested CSS Grid; read-only layouts stack in narrow containers |\n| `carousel` | Content carousel |\n| `artifact` | File download/preview |\n| `footer` | Metadata display |\n\n## Iframes under COEP — `MCPUIConfigProvider` (v6.21.0)\n\nThe library renders exactly two iframes: the `iframe` component\n(`IframeRenderer`) and `VideoRenderer`'s YouTube / Vimeo embed. Both are\nconstrained by `DEFAULT_IFRAME_DOMAINS` (the allow-list) and\n`getIframeSandbox()` (the tiered sandbox — `allow-same-origin allow-forms`\nfor `TRUSTED_IFRAME_DOMAINS`, `allow-scripts allow-popups` for everything\nelse).\n\nA host that serves `Cross-Origin-Embedder-Policy: credentialless` adds a\nthird constraint: the browser refuses any cross-origin iframe whose own\ndocument sends no COEP header — which is YouTube, Vimeo, Google Docs, Notion\nand most of the allow-list. The frame stays blank, and the page cannot even\ndetect it (a refused cross-origin document fires no `error` event). The fix\nis the boolean HTML attribute `