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

package/dist/stores/scratchpad-store.d.ts

@@ -1,23 +1,101 @@
 /**
- * Scratchpad Store — singleton reactive state for HITL scratchpad
- * v3.0.3: Eliminates ChatBus relay chain race condition
+ * Scratchpad Store — reactive state for HITL scratchpad
  *
  * @experimental
  *
- * Parser calls dispatchScratchpad() → store updates → ScratchpadPanel reads reactively.
- * Zero bus, zero relay, zero race condition.
+ * **v5.2.0 :** the store is now a factory (`createScratchpadStore()`) with a
+ * module-level singleton kept as default. Two consumption modes :
  *
- * **Known limitation (v4.3.9):** This store is a module-level singleton, not
- * a context-scoped factory. Two `ScratchpadPanel` instances in the same app
- * will share the same state. Multi-panel scenarios (e.g. chat + admin dashboard
- * both showing scratchpads simultaneously) are unsupported. Host apps that need
- * isolated scratchpads should not reuse this store — wait for v4.4.0 which
- * will expose `createScratchpadStore()` factory for per-panel instances.
+ * 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 { type ParentComponent } from 'solid-js';
 import type { ScratchpadState, ScratchpadEvent } from '../types/chat-bus';
+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;
+}
+/**
+ * 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 declare function createScratchpadStore(): ScratchpadStoreHandle;
+/**
+ * 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 declare function dispatchScratchpad(event: ScratchpadEvent): void;
+/**
+ * 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 declare const ScratchpadStoreContext: import("solid-js").Context<ScratchpadStoreHandle | 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 declare const ScratchpadStoreProvider: ParentComponent<{
+    store?: ScratchpadStoreHandle;
+}>;
 /**
  * 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()}>
@@ -29,13 +107,4 @@ export declare function useScratchpadState(): {
     pinned: () => boolean;
     close: () => void;
 };
-/**
- * Function for the PARSER/STORE — mutates the scratchpad state.
- * Called from the SSE callback, no bus needed.
- *
- * @example
- * // In your SSE parser callback — ONE LINE
- * onScratchpad: (data) => dispatchScratchpad(data as ScratchpadEvent)
- */
-export declare function dispatchScratchpad(event: ScratchpadEvent): void;
 //# sourceMappingURL=scratchpad-store.d.ts.map

package/dist/stores/scratchpad-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scratchpad-store.d.ts","sourceRoot":"","sources":["../../src/stores/scratchpad-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAqB,MAAM,mBAAmB,CAAA;AAO5F;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB;;;;EAMjC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CA2E/D"}
+{"version":3,"file":"scratchpad-store.d.ts","sourceRoot":"","sources":["../../src/stores/scratchpad-store.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAA6B,KAAK,eAAe,EAAY,MAAM,UAAU,CAAA;AAEpF,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAqB,MAAM,mBAAmB,CAAA;AAI5F,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;IAC1C,6EAA6E;IAC7E,KAAK,EAAE,MAAM,eAAe,GAAG,IAAI,CAAA;IACnC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,OAAO,CAAA;IACrB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAID;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI,qBAAqB,CAoG7D;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE/D;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,+DAA8D,CAAA;AAEjG;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAAe,CAAC;IACpD,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAC9B,CAKA,CAAA;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,KAAK,EAAE,MAAM,eAAe,GAAG,IAAI,CAAA;IACnC,MAAM,EAAE,MAAM,OAAO,CAAA;IACrB,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB,CAQA"}

package/dist/stores/scratchpad-store.js

@@ -1,89 +1,117 @@
+import { createComponent } from "solid-js/web";
+import { createContext, useContext } from "solid-js";
 import { createStore, produce } from "solid-js/store";
-const [scratchpadStore, setScratchpadStore] = createStore({ current: null, pinned: false });
-function useScratchpadState() {
+function createScratchpadStore() {
+  const [scratchpadStore, setScratchpadStore] = createStore({
+    current: null,
+    pinned: false
+  });
+  const dispatch = (event) => {
+    var _a, _b;
+    if (event.action === "create") {
+      console.info(`%c[MCP-UI] dispatchScratchpad%c create id=${event.id} sections=${((_a = event.sections) == null ? void 0 : _a.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.previewEndpoint,
+          previewDebounce: event.previewDebounce,
+          previewMethod: event.previewMethod,
+          previewHeaders: event.previewHeaders,
+          turn: event.turn,
+          totalTurns: event.totalTurns,
+          turnHistory: event.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=${((_b = event.sections) == null ? void 0 : _b.length) || 0} status=${event.status || "-"}`, "color: #3b82f6; font-weight: bold", "color: inherit");
+      setScratchpadStore(produce((s) => {
+        var _a2;
+        if (!s.current || s.current.id !== event.id) {
+          console.warn(`[MCP-UI] dispatchScratchpad: update for id=${event.id} but current is ${((_a2 = s.current) == null ? void 0 : _a2.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) => 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((s2) => s2.id).join(", ")}] Existing: [${s.current.sections.map((s2) => s2.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.turnHistory) s.current.turnHistory = event.turnHistory;
+        if (event.turn != null) s.current.turn = event.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 })
+    close: () => setScratchpadStore({
+      current: null,
+      pinned: false
+    })
   };
 }
+const defaultStore = createScratchpadStore();
 function dispatchScratchpad(event) {
-  var _a, _b;
-  if (event.action === "create") {
-    console.info(
-      `%c[MCP-UI] dispatchScratchpad%c create id=${event.id} sections=${((_a = event.sections) == null ? void 0 : _a.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.previewEndpoint,
-        previewDebounce: event.previewDebounce,
-        previewMethod: event.previewMethod,
-        previewHeaders: event.previewHeaders,
-        turn: event.turn,
-        totalTurns: event.totalTurns,
-        turnHistory: event.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=${((_b = event.sections) == null ? void 0 : _b.length) || 0} status=${event.status || "-"}`,
-      "color: #3b82f6; font-weight: bold",
-      "color: inherit"
-    );
-    setScratchpadStore(produce((s) => {
-      var _a2;
-      if (!s.current || s.current.id !== event.id) {
-        console.warn(`[MCP-UI] dispatchScratchpad: update for id=${event.id} but current is ${((_a2 = s.current) == null ? void 0 : _a2.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) => 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((s2) => s2.id).join(", ")}] Existing: [${s.current.sections.map((s2) => s2.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.turnHistory) s.current.turnHistory = event.turnHistory;
-      if (event.turn != null) s.current.turn = event.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 });
-  }
+  defaultStore.dispatch(event);
+}
+const ScratchpadStoreContext = createContext(void 0);
+const ScratchpadStoreProvider = (props) => {
+  const store = props.store ?? createScratchpadStore();
+  return createComponent(ScratchpadStoreContext.Provider, {
+    value: store,
+    get children() {
+      return props.children;
+    }
+  });
+};
+function useScratchpadState() {
+  const scoped = useContext(ScratchpadStoreContext);
+  const handle = scoped ?? defaultStore;
+  return {
+    state: handle.state,
+    pinned: handle.pinned,
+    close: handle.close
+  };
 }
 export {
+  ScratchpadStoreContext,
+  ScratchpadStoreProvider,
+  createScratchpadStore,
   dispatchScratchpad,
   useScratchpadState
 };

package/dist/stores/scratchpad-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"scratchpad-store.js","sources":["../../src/stores/scratchpad-store.ts"],"sourcesContent":["/**\n * Scratchpad Store — singleton reactive state for HITL scratchpad\n * v3.0.3: Eliminates ChatBus relay chain race condition\n *\n * @experimental\n *\n * Parser calls dispatchScratchpad() → store updates → ScratchpadPanel reads reactively.\n * Zero bus, zero relay, zero race condition.\n *\n * **Known limitation (v4.3.9):** This store is a module-level singleton, not\n * a context-scoped factory. Two `ScratchpadPanel` instances in the same app\n * will share the same state. Multi-panel scenarios (e.g. chat + admin dashboard\n * both showing scratchpads simultaneously) are unsupported. Host apps that need\n * isolated scratchpads should not reuse this store — wait for v4.4.0 which\n * will expose `createScratchpadStore()` factory for per-panel instances.\n */\n\nimport { createStore, produce } from 'solid-js/store'\nimport type { ScratchpadState, ScratchpadEvent, ScratchpadSection } from '../types/chat-bus'\n\nconst [scratchpadStore, setScratchpadStore] = createStore<{\n  current: ScratchpadState | null\n  pinned: boolean\n}>({ current: null, pinned: false })\n\n/**\n * Hook for the COMPONENT — reads the scratchpad state reactively.\n *\n * @example\n * const { state, pinned, close } = useScratchpadState()\n * <Show when={state()}>\n *   <ScratchpadPanel state={state()!} pinned={pinned()} onClose={close} />\n * </Show>\n */\nexport function useScratchpadState() {\n  return {\n    state: () => scratchpadStore.current,\n    pinned: () => scratchpadStore.pinned,\n    close: () => setScratchpadStore({ current: null, pinned: false }),\n  }\n}\n\n/**\n * Function for the PARSER/STORE — mutates the scratchpad state.\n * Called from the SSE callback, no bus needed.\n *\n * @example\n * // In your SSE parser callback — ONE LINE\n * onScratchpad: (data) => dispatchScratchpad(data as ScratchpadEvent)\n */\nexport function dispatchScratchpad(event: ScratchpadEvent): void {\n  // DX1: lifecycle logging\n  if (event.action === 'create') {\n    console.info(\n      `%c[MCP-UI] dispatchScratchpad%c create id=${event.id} sections=${event.sections?.length || 0} status=${event.status || 'loading'}${event.pinned ? ' pinned' : ''}`,\n      'color: #10b981; font-weight: bold', 'color: inherit'\n    )\n    setScratchpadStore({\n      current: {\n        id: event.id,\n        title: event.title || '',\n        sections: event.sections || [],\n        filters: event.filters || {},\n        preview: event.preview,\n        agentMessages: event.agentMessages || [],\n        status: event.status || 'loading',\n        previewEndpoint: (event as any).previewEndpoint,\n        previewDebounce: (event as any).previewDebounce,\n        previewMethod: (event as any).previewMethod,\n        previewHeaders: (event as any).previewHeaders,\n        turn: (event as any).turn,\n        totalTurns: (event as any).totalTurns,\n        turnHistory: (event as any).turnHistory,\n      },\n      pinned: event.pinned || false,\n    })\n  } else if (event.action === 'update') {\n    console.info(\n      `%c[MCP-UI] dispatchScratchpad%c update id=${event.id} sectionMode=${event.sectionMode || 'replace'} sections=${event.sections?.length || 0} status=${event.status || '-'}`,\n      'color: #3b82f6; font-weight: bold', 'color: inherit'\n    )\n    setScratchpadStore(produce((s) => {\n      if (!s.current || s.current.id !== event.id) {\n        console.warn(`[MCP-UI] dispatchScratchpad: update for id=${event.id} but current is ${s.current?.id || 'null'}. Ignoring.`)\n        return\n      }\n\n      if (event.sections) {\n        const mode = event.sectionMode || 'replace'\n        if (mode === 'replace') {\n          s.current.sections = event.sections\n        } else if (mode === 'append') {\n          s.current.sections = [...s.current.sections, ...event.sections]\n        } else if (mode === 'upsert') {\n          let matchCount = 0\n          for (const incoming of event.sections) {\n            const idx = s.current.sections.findIndex((sec: ScratchpadSection) => sec.id === incoming.id)\n            if (idx >= 0) {\n              s.current.sections[idx] = incoming\n              matchCount++\n            } else {\n              s.current.sections.push(incoming)\n            }\n          }\n          if (matchCount === 0 && event.sections.length > 0) {\n            console.warn(\n              `[MCP-UI] dispatchScratchpad: sectionMode='upsert' but no IDs matched. ` +\n              `Incoming: [${event.sections.map((s: ScratchpadSection) => s.id).join(', ')}] ` +\n              `Existing: [${s.current.sections.map((s: ScratchpadSection) => s.id).join(', ')}]. All appended.`\n            )\n          }\n        }\n      }\n      if (event.agentMessages) s.current.agentMessages = event.agentMessages\n      if (event.status) s.current.status = event.status\n      if (event.filters) s.current.filters = event.filters\n      if (event.preview) s.current.preview = event.preview\n      if (event.pinned != null) s.pinned = event.pinned\n      if ((event as any).turnHistory) s.current.turnHistory = (event as any).turnHistory\n      if ((event as any).turn != null) s.current.turn = (event as any).turn\n    }))\n  } else if (event.action === 'close') {\n    console.info(`%c[MCP-UI] dispatchScratchpad%c close id=${event.id}`, 'color: #6b7280; font-weight: bold', 'color: inherit')\n    setScratchpadStore({ current: null, pinned: false })\n  }\n}\n"],"names":["_a","s"],"mappings":"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"}
+{"version":3,"file":"scratchpad-store.js","sources":["../../src/stores/scratchpad-store.tsx"],"sourcesContent":["/**\n * Scratchpad Store — reactive state for HITL scratchpad\n *\n * @experimental\n *\n * **v5.2.0 :** the store is now a factory (`createScratchpadStore()`) with a\n * module-level singleton kept as default. Two consumption modes :\n *\n * 1. **Singleton mode (default, zero-config)** — `dispatchScratchpad(event)` +\n *    `useScratchpadState()` read/write the module singleton. This is the v4.x\n *    path and keeps working unchanged.\n *\n * 2. **Multi-instance mode** — wrap a subtree in `<ScratchpadStoreProvider>`\n *    (it creates a scoped `ScratchpadStoreHandle` internally, or use your own\n *    via the `store` prop). `useScratchpadState()` auto-detects the context\n *    and reads from it; `ScratchpadPanel` mounted inside the provider reads\n *    the scoped store. Non-reactive callers (SSE parsers) should pass the\n *    handle explicitly — do NOT try to reach context from a non-reactive\n *    scope.\n */\n\nimport { createContext, useContext, type ParentComponent, type JSX } from 'solid-js'\nimport { createStore, produce } from 'solid-js/store'\nimport type { ScratchpadState, ScratchpadEvent, ScratchpadSection } from '../types/chat-bus'\n\n// ─── Handle shape ─────────────────────────────────────────────\n\nexport interface ScratchpadStoreHandle {\n  /** Mutate the store from an SSE/parser callback. */\n  dispatch: (event: ScratchpadEvent) => void\n  /** Reactive accessor for the current scratchpad state (null when closed). */\n  state: () => ScratchpadState | null\n  /** Reactive accessor for the pinned flag. */\n  pinned: () => boolean\n  /** Close the scratchpad (equivalent to dispatching an action='close'). */\n  close: () => void\n}\n\n// ─── Factory ──────────────────────────────────────────────────\n\n/**\n * Create an isolated scratchpad store instance.\n *\n * Use this when you need two or more scratchpads live at the same time\n * (e.g. chat scratchpad + admin dashboard scratchpad). Pair with\n * `<ScratchpadStoreProvider store={...}>` to scope a SolidJS subtree.\n *\n * @experimental\n * @since v5.2.0\n */\nexport function createScratchpadStore(): ScratchpadStoreHandle {\n  const [scratchpadStore, setScratchpadStore] = createStore<{\n    current: ScratchpadState | null\n    pinned: boolean\n  }>({ current: null, pinned: false })\n\n  const dispatch = (event: ScratchpadEvent): void => {\n    if (event.action === 'create') {\n      console.info(\n        `%c[MCP-UI] dispatchScratchpad%c create id=${event.id} sections=${event.sections?.length || 0} status=${event.status || 'loading'}${event.pinned ? ' pinned' : ''}`,\n        'color: #10b981; font-weight: bold',\n        'color: inherit'\n      )\n      setScratchpadStore({\n        current: {\n          id: event.id,\n          title: event.title || '',\n          sections: event.sections || [],\n          filters: event.filters || {},\n          preview: event.preview,\n          agentMessages: event.agentMessages || [],\n          status: event.status || 'loading',\n          previewEndpoint: (event as any).previewEndpoint,\n          previewDebounce: (event as any).previewDebounce,\n          previewMethod: (event as any).previewMethod,\n          previewHeaders: (event as any).previewHeaders,\n          turn: (event as any).turn,\n          totalTurns: (event as any).totalTurns,\n          turnHistory: (event as any).turnHistory,\n        },\n        pinned: event.pinned || false,\n      })\n    } else if (event.action === 'update') {\n      console.info(\n        `%c[MCP-UI] dispatchScratchpad%c update id=${event.id} sectionMode=${event.sectionMode || 'replace'} sections=${event.sections?.length || 0} status=${event.status || '-'}`,\n        'color: #3b82f6; font-weight: bold',\n        'color: inherit'\n      )\n      setScratchpadStore(\n        produce((s) => {\n          if (!s.current || s.current.id !== event.id) {\n            console.warn(\n              `[MCP-UI] dispatchScratchpad: update for id=${event.id} but current is ${s.current?.id || 'null'}. Ignoring.`\n            )\n            return\n          }\n\n          if (event.sections) {\n            const mode = event.sectionMode || 'replace'\n            if (mode === 'replace') {\n              s.current.sections = event.sections\n            } else if (mode === 'append') {\n              s.current.sections = [...s.current.sections, ...event.sections]\n            } else if (mode === 'upsert') {\n              let matchCount = 0\n              for (const incoming of event.sections) {\n                const idx = s.current.sections.findIndex(\n                  (sec: ScratchpadSection) => sec.id === incoming.id\n                )\n                if (idx >= 0) {\n                  s.current.sections[idx] = incoming\n                  matchCount++\n                } else {\n                  s.current.sections.push(incoming)\n                }\n              }\n              if (matchCount === 0 && event.sections.length > 0) {\n                console.warn(\n                  `[MCP-UI] dispatchScratchpad: sectionMode='upsert' but no IDs matched. ` +\n                    `Incoming: [${event.sections.map((s: ScratchpadSection) => s.id).join(', ')}] ` +\n                    `Existing: [${s.current.sections.map((s: ScratchpadSection) => s.id).join(', ')}]. All appended.`\n                )\n              }\n            }\n          }\n          if (event.agentMessages) s.current.agentMessages = event.agentMessages\n          if (event.status) s.current.status = event.status\n          if (event.filters) s.current.filters = event.filters\n          if (event.preview) s.current.preview = event.preview\n          if (event.pinned != null) s.pinned = event.pinned\n          if ((event as any).turnHistory) s.current.turnHistory = (event as any).turnHistory\n          if ((event as any).turn != null) s.current.turn = (event as any).turn\n        })\n      )\n    } else if (event.action === 'close') {\n      console.info(\n        `%c[MCP-UI] dispatchScratchpad%c close id=${event.id}`,\n        'color: #6b7280; font-weight: bold',\n        'color: inherit'\n      )\n      setScratchpadStore({ current: null, pinned: false })\n    }\n  }\n\n  return {\n    dispatch,\n    state: () => scratchpadStore.current,\n    pinned: () => scratchpadStore.pinned,\n    close: () => setScratchpadStore({ current: null, pinned: false }),\n  }\n}\n\n// ─── Module-level singleton (v4.x-compatible default) ─────────\n\nconst defaultStore: ScratchpadStoreHandle = createScratchpadStore()\n\n/**\n * Function for the PARSER/STORE — mutates the **module-level singleton**\n * scratchpad state. Use this when you only need one scratchpad at a time\n * (single-instance consumer, the v4.x pattern).\n *\n * For multi-instance scenarios, prefer `createScratchpadStore()` and pass the\n * handle around explicitly.\n *\n * @example\n * // In your SSE parser callback — ONE LINE\n * onScratchpad: (data) => dispatchScratchpad(data as ScratchpadEvent)\n */\nexport function dispatchScratchpad(event: ScratchpadEvent): void {\n  defaultStore.dispatch(event)\n}\n\n// ─── Context (v5.2.0) ─────────────────────────────────────────\n\n/**\n * Context for a scoped scratchpad store. Populated by\n * `<ScratchpadStoreProvider>`. Read by `useScratchpadState()` with automatic\n * fallback to the module-level singleton when the context is absent.\n *\n * @experimental\n * @since v5.2.0\n */\nexport const ScratchpadStoreContext = createContext<ScratchpadStoreHandle | undefined>(undefined)\n\n/**\n * Provide a scoped `ScratchpadStoreHandle` to a SolidJS subtree. Children\n * reading via `useScratchpadState()` or rendering a `<ScratchpadPanel>` will\n * bind to this store instead of the module singleton.\n *\n * If no `store` prop is passed, a fresh store is created for the provider's\n * lifetime. Pass `store` explicitly when you need the handle outside the\n * tree (e.g. in an SSE parser that lives at the app root).\n *\n * @experimental\n * @since v5.2.0\n *\n * @example\n * const chatStore = createScratchpadStore()\n * const adminStore = createScratchpadStore()\n *\n * <ScratchpadStoreProvider store={chatStore}>\n *   <ChatInterface />\n * </ScratchpadStoreProvider>\n * <ScratchpadStoreProvider store={adminStore}>\n *   <AdminDashboard />\n * </ScratchpadStoreProvider>\n */\nexport const ScratchpadStoreProvider: ParentComponent<{\n  store?: ScratchpadStoreHandle\n}> = (props): JSX.Element => {\n  const store = props.store ?? createScratchpadStore()\n  return (\n    <ScratchpadStoreContext.Provider value={store}>{props.children}</ScratchpadStoreContext.Provider>\n  )\n}\n\n// ─── Reactive hook (context-aware) ────────────────────────────\n\n/**\n * Hook for the COMPONENT — reads the scratchpad state reactively.\n *\n * **v5.2.0 :** if called inside a `<ScratchpadStoreProvider>`, reads the\n * scoped handle; otherwise falls back to the module singleton. Old v4.x\n * consumers keep working unchanged.\n *\n * @example\n * const { state, pinned, close } = useScratchpadState()\n * <Show when={state()}>\n *   <ScratchpadPanel state={state()!} pinned={pinned()} onClose={close} />\n * </Show>\n */\nexport function useScratchpadState(): {\n  state: () => ScratchpadState | null\n  pinned: () => boolean\n  close: () => void\n} {\n  const scoped = useContext(ScratchpadStoreContext)\n  const handle = scoped ?? defaultStore\n  return {\n    state: handle.state,\n    pinned: handle.pinned,\n    close: handle.close,\n  }\n}\n"],"names":["createScratchpadStore","scratchpadStore","setScratchpadStore","createStore","current","pinned","dispatch","event","action","console","info","id","sections","length","status","title","filters","preview","agentMessages","previewEndpoint","previewDebounce","previewMethod","previewHeaders","turn","totalTurns","turnHistory","sectionMode","produce","s","warn","mode","matchCount","incoming","idx","findIndex","sec","push","map","join","state","close","defaultStore","dispatchScratchpad","ScratchpadStoreContext","createContext","undefined","ScratchpadStoreProvider","props","store","_$createComponent","Provider","value","children","useScratchpadState","scoped","useContext","handle"],"mappings":";;;AAkDO,SAASA,wBAA+C;AAC7D,QAAM,CAACC,iBAAiBC,kBAAkB,IAAIC,YAG3C;AAAA,IAAEC,SAAS;AAAA,IAAMC,QAAQ;AAAA,EAAA,CAAO;AAEnC,QAAMC,WAAWA,CAACC,UAAiC;;AACjD,QAAIA,MAAMC,WAAW,UAAU;AAC7BC,cAAQC,KACN,6CAA6CH,MAAMI,EAAE,eAAaJ,WAAMK,aAANL,mBAAgBM,WAAU,CAAC,WAAWN,MAAMO,UAAU,SAAS,GAAGP,MAAMF,SAAS,YAAY,EAAE,IACjK,qCACA,gBACF;AACAH,yBAAmB;AAAA,QACjBE,SAAS;AAAA,UACPO,IAAIJ,MAAMI;AAAAA,UACVI,OAAOR,MAAMQ,SAAS;AAAA,UACtBH,UAAUL,MAAMK,YAAY,CAAA;AAAA,UAC5BI,SAAST,MAAMS,WAAW,CAAA;AAAA,UAC1BC,SAASV,MAAMU;AAAAA,UACfC,eAAeX,MAAMW,iBAAiB,CAAA;AAAA,UACtCJ,QAAQP,MAAMO,UAAU;AAAA,UACxBK,iBAAkBZ,MAAcY;AAAAA,UAChCC,iBAAkBb,MAAca;AAAAA,UAChCC,eAAgBd,MAAcc;AAAAA,UAC9BC,gBAAiBf,MAAce;AAAAA,UAC/BC,MAAOhB,MAAcgB;AAAAA,UACrBC,YAAajB,MAAciB;AAAAA,UAC3BC,aAAclB,MAAckB;AAAAA,QAAAA;AAAAA,QAE9BpB,QAAQE,MAAMF,UAAU;AAAA,MAAA,CACzB;AAAA,IACH,WAAWE,MAAMC,WAAW,UAAU;AACpCC,cAAQC,KACN,6CAA6CH,MAAMI,EAAE,gBAAgBJ,MAAMmB,eAAe,SAAS,eAAanB,WAAMK,aAANL,mBAAgBM,WAAU,CAAC,WAAWN,MAAMO,UAAU,GAAG,IACzK,qCACA,gBACF;AACAZ,yBACEyB,QAASC,CAAAA,MAAM;;AACb,YAAI,CAACA,EAAExB,WAAWwB,EAAExB,QAAQO,OAAOJ,MAAMI,IAAI;AAC3CF,kBAAQoB,KACN,8CAA8CtB,MAAMI,EAAE,qBAAmBiB,MAAAA,EAAExB,YAAFwB,gBAAAA,IAAWjB,OAAM,MAAM,aAClG;AACA;AAAA,QACF;AAEA,YAAIJ,MAAMK,UAAU;AAClB,gBAAMkB,OAAOvB,MAAMmB,eAAe;AAClC,cAAII,SAAS,WAAW;AACtBF,cAAExB,QAAQQ,WAAWL,MAAMK;AAAAA,UAC7B,WAAWkB,SAAS,UAAU;AAC5BF,cAAExB,QAAQQ,WAAW,CAAC,GAAGgB,EAAExB,QAAQQ,UAAU,GAAGL,MAAMK,QAAQ;AAAA,UAChE,WAAWkB,SAAS,UAAU;AAC5B,gBAAIC,aAAa;AACjB,uBAAWC,YAAYzB,MAAMK,UAAU;AACrC,oBAAMqB,MAAML,EAAExB,QAAQQ,SAASsB,UAC7B,CAACC,QAA2BA,IAAIxB,OAAOqB,SAASrB,EAClD;AACA,kBAAIsB,OAAO,GAAG;AACZL,kBAAExB,QAAQQ,SAASqB,GAAG,IAAID;AAC1BD;AAAAA,cACF,OAAO;AACLH,kBAAExB,QAAQQ,SAASwB,KAAKJ,QAAQ;AAAA,cAClC;AAAA,YACF;AACA,gBAAID,eAAe,KAAKxB,MAAMK,SAASC,SAAS,GAAG;AACjDJ,sBAAQoB,KACN,oFACgBtB,MAAMK,SAASyB,IAAI,CAACT,OAAyBA,GAAEjB,EAAE,EAAE2B,KAAK,IAAI,CAAC,gBAC7DV,EAAExB,QAAQQ,SAASyB,IAAI,CAACT,OAAyBA,GAAEjB,EAAE,EAAE2B,KAAK,IAAI,CAAC,kBACnF;AAAA,YACF;AAAA,UACF;AAAA,QACF;AACA,YAAI/B,MAAMW,cAAeU,GAAExB,QAAQc,gBAAgBX,MAAMW;AACzD,YAAIX,MAAMO,OAAQc,GAAExB,QAAQU,SAASP,MAAMO;AAC3C,YAAIP,MAAMS,QAASY,GAAExB,QAAQY,UAAUT,MAAMS;AAC7C,YAAIT,MAAMU,QAASW,GAAExB,QAAQa,UAAUV,MAAMU;AAC7C,YAAIV,MAAMF,UAAU,KAAMuB,GAAEvB,SAASE,MAAMF;AAC3C,YAAKE,MAAckB,YAAaG,GAAExB,QAAQqB,cAAelB,MAAckB;AACvE,YAAKlB,MAAcgB,QAAQ,KAAMK,GAAExB,QAAQmB,OAAQhB,MAAcgB;AAAAA,MACnE,CAAC,CACH;AAAA,IACF,WAAWhB,MAAMC,WAAW,SAAS;AACnCC,cAAQC,KACN,4CAA4CH,MAAMI,EAAE,IACpD,qCACA,gBACF;AACAT,yBAAmB;AAAA,QAAEE,SAAS;AAAA,QAAMC,QAAQ;AAAA,MAAA,CAAO;AAAA,IACrD;AAAA,EACF;AAEA,SAAO;AAAA,IACLC;AAAAA,IACAiC,OAAOA,MAAMtC,gBAAgBG;AAAAA,IAC7BC,QAAQA,MAAMJ,gBAAgBI;AAAAA,IAC9BmC,OAAOA,MAAMtC,mBAAmB;AAAA,MAAEE,SAAS;AAAA,MAAMC,QAAQ;AAAA,IAAA,CAAO;AAAA,EAAA;AAEpE;AAIA,MAAMoC,eAAsCzC,sBAAAA;AAcrC,SAAS0C,mBAAmBnC,OAA8B;AAC/DkC,eAAanC,SAASC,KAAK;AAC7B;AAYO,MAAMoC,yBAAyBC,cAAiDC,MAAS;AAyBzF,MAAMC,0BAERA,CAACC,UAAuB;AAC3B,QAAMC,QAAQD,MAAMC,SAAShD,sBAAAA;AAC7B,SAAAiD,gBACGN,uBAAuBO,UAAQ;AAAA,IAACC,OAAOH;AAAAA,IAAK,IAAAI,WAAA;AAAA,aAAGL,MAAMK;AAAAA,IAAQ;AAAA,EAAA,CAAA;AAElE;AAiBO,SAASC,qBAId;AACA,QAAMC,SAASC,WAAWZ,sBAAsB;AAChD,QAAMa,SAASF,UAAUb;AACzB,SAAO;AAAA,IACLF,OAAOiB,OAAOjB;AAAAA,IACdlC,QAAQmD,OAAOnD;AAAAA,IACfmC,OAAOgB,OAAOhB;AAAAA,EAAAA;AAElB;"}

package/dist/types/chat-bus.d.ts

@@ -5,6 +5,7 @@
  * @experimental — These types may change without major bump until stabilized in v2.5.0.
  * See CHANGELOG for breaking changes on experimental types.
  */
+import type { JSX } from 'solid-js';
 import type { UIComponent, UILayout } from './index';
 /**
  * @experimental
@@ -58,6 +59,9 @@ export interface ChatEvents {
     onClarificationNeeded: (event: ChatEventBase & {
         clarification: ClarificationEvent;
     }) => void;
+    onElicitation: (event: ChatEventBase & {
+        elicitation: ElicitationEvent;
+    }) => void;
     onAgentSwitch: (event: ChatEventBase & {
         agent: AgentContext;
     }) => void;
@@ -103,15 +107,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?) => { ... })`.
+     *
+     * ### 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)
      *
-     * **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.
+     * 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 */
@@ -184,21 +217,94 @@ export interface ChatPromptConfig {
     /** Type-specific configuration */
     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 {
     message?: string;
@@ -445,6 +551,42 @@ export interface ToolCallEvent {
     results?: unknown;
     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;