@nimblebrain/synapse 0.15.0 → 0.17.0

package/dist/{detect-C_qmYsh9.d.cts → detect-BHYg26_d.d.cts}

@@ -1,4 +1,4 @@
-import { F as FontFaceDescriptor } from './types-BSZasM8q.cjs';
+import { g as FontFaceDescriptor } from './types-uEO4VFJ2.cjs';
 
 /**
  * Cross-host UI client — types and wire constants.

package/dist/{detect-Dfd0upoz.d.ts → detect-Bf8Q_0dK.d.ts}

@@ -1,4 +1,4 @@
-import { F as FontFaceDescriptor } from './types-BSZasM8q.js';
+import { g as FontFaceDescriptor } from './types-uEO4VFJ2.js';
 
 /**
  * Cross-host UI client — types and wire constants.

package/dist/host/index.cjs

@@ -1,57 +1,57 @@
 'use strict';
 
-var chunkSN7YXLAV_cjs = require('../chunk-SN7YXLAV.cjs');
-require('../chunk-RYWW6EHB.cjs');
+var chunkEHLQWCYV_cjs = require('../chunk-EHLQWCYV.cjs');
+require('../chunk-TXJMGQYF.cjs');
 
 
 
 Object.defineProperty(exports, "HostUnsupportedError", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.HostUnsupportedError; }
+  get: function () { return chunkEHLQWCYV_cjs.HostUnsupportedError; }
 });
 Object.defineProperty(exports, "SYNAPSE_DATA_ELEMENT_ID", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.SYNAPSE_DATA_ELEMENT_ID; }
+  get: function () { return chunkEHLQWCYV_cjs.SYNAPSE_DATA_ELEMENT_ID; }
 });
 Object.defineProperty(exports, "adapterForKind", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.adapterForKind; }
+  get: function () { return chunkEHLQWCYV_cjs.adapterForKind; }
 });
 Object.defineProperty(exports, "applyHostTheme", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.applyHostTheme; }
+  get: function () { return chunkEHLQWCYV_cjs.applyHostTheme; }
 });
 Object.defineProperty(exports, "coerceMode", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.coerceMode; }
+  get: function () { return chunkEHLQWCYV_cjs.coerceMode; }
 });
 Object.defineProperty(exports, "connectUI", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.connectUI; }
+  get: function () { return chunkEHLQWCYV_cjs.connectUI; }
 });
 Object.defineProperty(exports, "createChatGPTAdapter", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.createChatGPTAdapter; }
+  get: function () { return chunkEHLQWCYV_cjs.createChatGPTAdapter; }
 });
 Object.defineProperty(exports, "createInlineAdapter", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.createInlineAdapter; }
+  get: function () { return chunkEHLQWCYV_cjs.createInlineAdapter; }
 });
 Object.defineProperty(exports, "createMcpAppsAdapter", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.createMcpAppsAdapter; }
+  get: function () { return chunkEHLQWCYV_cjs.createMcpAppsAdapter; }
 });
 Object.defineProperty(exports, "detectHostKind", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.detectHostKind; }
+  get: function () { return chunkEHLQWCYV_cjs.detectHostKind; }
 });
 Object.defineProperty(exports, "preferredMode", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.preferredMode; }
+  get: function () { return chunkEHLQWCYV_cjs.preferredMode; }
 });
 Object.defineProperty(exports, "selectAdapter", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.selectAdapter; }
+  get: function () { return chunkEHLQWCYV_cjs.selectAdapter; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/host/index.d.cts

@@ -1,6 +1,6 @@
-import { C as ConnectUIOptions, g as HostAdapter, d as SynapseUITheme } from '../detect-C_qmYsh9.cjs';
-export { H as HostCapabilities, a as HostKind, b as HostUnsupportedError, S as SYNAPSE_DATA_ELEMENT_ID, c as SynapseUIClient, h as adapterForKind, e as connectUI, f as detectHostKind, s as selectAdapter } from '../detect-C_qmYsh9.cjs';
-import '../types-BSZasM8q.cjs';
+import { C as ConnectUIOptions, g as HostAdapter, d as SynapseUITheme } from '../detect-BHYg26_d.cjs';
+export { H as HostCapabilities, a as HostKind, b as HostUnsupportedError, S as SYNAPSE_DATA_ELEMENT_ID, c as SynapseUIClient, h as adapterForKind, e as connectUI, f as detectHostKind, s as selectAdapter } from '../detect-BHYg26_d.cjs';
+import '../types-uEO4VFJ2.cjs';
 import '@modelcontextprotocol/ext-apps';
 import '@modelcontextprotocol/sdk/types.js';
 

package/dist/host/index.d.ts

@@ -1,6 +1,6 @@
-import { C as ConnectUIOptions, g as HostAdapter, d as SynapseUITheme } from '../detect-Dfd0upoz.js';
-export { H as HostCapabilities, a as HostKind, b as HostUnsupportedError, S as SYNAPSE_DATA_ELEMENT_ID, c as SynapseUIClient, h as adapterForKind, e as connectUI, f as detectHostKind, s as selectAdapter } from '../detect-Dfd0upoz.js';
-import '../types-BSZasM8q.js';
+import { C as ConnectUIOptions, g as HostAdapter, d as SynapseUITheme } from '../detect-Bf8Q_0dK.js';
+export { H as HostCapabilities, a as HostKind, b as HostUnsupportedError, S as SYNAPSE_DATA_ELEMENT_ID, c as SynapseUIClient, h as adapterForKind, e as connectUI, f as detectHostKind, s as selectAdapter } from '../detect-Bf8Q_0dK.js';
+import '../types-uEO4VFJ2.js';
 import '@modelcontextprotocol/ext-apps';
 import '@modelcontextprotocol/sdk/types.js';
 

package/dist/host/index.js

@@ -1,4 +1,4 @@
-export { HostUnsupportedError, SYNAPSE_DATA_ELEMENT_ID, adapterForKind, applyHostTheme, coerceMode, connectUI, createChatGPTAdapter, createInlineAdapter, createMcpAppsAdapter, detectHostKind, preferredMode, selectAdapter } from '../chunk-E7OOOYVR.js';
-import '../chunk-J5ICAHK2.js';
+export { HostUnsupportedError, SYNAPSE_DATA_ELEMENT_ID, adapterForKind, applyHostTheme, coerceMode, connectUI, createChatGPTAdapter, createInlineAdapter, createMcpAppsAdapter, detectHostKind, preferredMode, selectAdapter } from '../chunk-SRQNQ26I.js';
+import '../chunk-UPDBDXQB.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.cjs

@@ -1,113 +1,54 @@
 'use strict';
 
-var chunkSN7YXLAV_cjs = require('./chunk-SN7YXLAV.cjs');
-var chunkZMNYUGSF_cjs = require('./chunk-ZMNYUGSF.cjs');
-var chunkRYWW6EHB_cjs = require('./chunk-RYWW6EHB.cjs');
+var chunkEHLQWCYV_cjs = require('./chunk-EHLQWCYV.cjs');
+var chunkFDMRJZKT_cjs = require('./chunk-FDMRJZKT.cjs');
+var chunkTXJMGQYF_cjs = require('./chunk-TXJMGQYF.cjs');
+
 
-// src/store.ts
-function createStore(synapse, config) {
-  let state = structuredClone(config.initialState);
-  const subscribers = /* @__PURE__ */ new Set();
-  let destroyed = false;
-  let persistTimer = null;
-  const dispatch = {};
-  for (const key of Object.keys(config.actions)) {
-    dispatch[key] = (payload) => {
-      if (destroyed) return;
-      state = config.actions[key](state, payload);
-      notify();
-    };
-  }
-  function notify() {
-    for (const cb of subscribers) cb(state);
-    if (config.visibleToAgent) pushToAgent();
-    if (config.persist) schedulePersist();
-  }
-  function pushToAgent() {
-    const summary = config.summarize?.(state);
-    synapse.setVisibleState(state, summary);
-  }
-  function schedulePersist() {
-    if (persistTimer) clearTimeout(persistTimer);
-    persistTimer = setTimeout(() => {
-      synapse._request("synapse/persist-state", {
-        state,
-        version: config.version
-      }).catch(() => {
-      });
-      persistTimer = null;
-    }, 500);
-  }
-  let unsubStateLoaded;
-  if (config.persist) {
-    unsubStateLoaded = synapse._onMessage("synapse/state-loaded", (params) => {
-      if (!params?.state) return;
-      let loaded = params.state;
-      const loadedVersion = params.version ?? 1;
-      const currentVersion = config.version ?? 1;
-      if (config.migrations && loadedVersion < currentVersion) {
-        const startIdx = loadedVersion - 1;
-        for (let i = startIdx; i < config.migrations.length; i++) {
-          loaded = config.migrations[i](loaded);
-        }
-      }
-      store.hydrate(loaded);
-    });
-  }
-  const store = {
-    getState() {
-      return state;
-    },
-    subscribe(callback) {
-      subscribers.add(callback);
-      return () => {
-        subscribers.delete(callback);
-      };
-    },
-    dispatch,
-    hydrate(newState) {
-      state = newState;
-      for (const cb of subscribers) cb(state);
-    },
-    destroy() {
-      if (destroyed) return;
-      destroyed = true;
-      if (persistTimer) clearTimeout(persistTimer);
-      subscribers.clear();
-      unsubStateLoaded?.();
-    }
-  };
-  return store;
-}
 
 Object.defineProperty(exports, "HostUnsupportedError", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.HostUnsupportedError; }
+  get: function () { return chunkEHLQWCYV_cjs.HostUnsupportedError; }
 });
 Object.defineProperty(exports, "SYNAPSE_DATA_ELEMENT_ID", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.SYNAPSE_DATA_ELEMENT_ID; }
+  get: function () { return chunkEHLQWCYV_cjs.SYNAPSE_DATA_ELEMENT_ID; }
 });
 Object.defineProperty(exports, "connectUI", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.connectUI; }
+  get: function () { return chunkEHLQWCYV_cjs.connectUI; }
 });
 Object.defineProperty(exports, "detectHostKind", {
   enumerable: true,
-  get: function () { return chunkSN7YXLAV_cjs.detectHostKind; }
+  get: function () { return chunkEHLQWCYV_cjs.detectHostKind; }
+});
+Object.defineProperty(exports, "action", {
+  enumerable: true,
+  get: function () { return chunkFDMRJZKT_cjs.action; }
+});
+Object.defineProperty(exports, "callToolAsTask", {
+  enumerable: true,
+  get: function () { return chunkFDMRJZKT_cjs.callToolAsTask; }
 });
 Object.defineProperty(exports, "connect", {
   enumerable: true,
-  get: function () { return chunkZMNYUGSF_cjs.connect; }
+  get: function () { return chunkFDMRJZKT_cjs.connect; }
+});
+Object.defineProperty(exports, "downloadFile", {
+  enumerable: true,
+  get: function () { return chunkFDMRJZKT_cjs.downloadFile; }
+});
+Object.defineProperty(exports, "pickFile", {
+  enumerable: true,
+  get: function () { return chunkFDMRJZKT_cjs.pickFile; }
 });
-Object.defineProperty(exports, "createSynapse", {
+Object.defineProperty(exports, "pickFiles", {
   enumerable: true,
-  get: function () { return chunkZMNYUGSF_cjs.createSynapse; }
+  get: function () { return chunkFDMRJZKT_cjs.pickFiles; }
 });
 Object.defineProperty(exports, "FONT_FACES_CONTEXT_KEY", {
   enumerable: true,
-  get: function () { return chunkRYWW6EHB_cjs.FONT_FACES_CONTEXT_KEY; }
+  get: function () { return chunkTXJMGQYF_cjs.FONT_FACES_CONTEXT_KEY; }
 });
-exports.createStore = createStore;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/store.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { ActionReducer, Store, StoreConfig, StoreDispatch, Synapse } from \"./types.js\";\n\n/**\n * Create a typed state store with optional persistence and agent visibility.\n *\n * - `persist: true` — state survives iframe reloads via host storage\n * - `visibleToAgent: true` — state is pushed to the LLM context\n * - Both are independent and can be enabled separately\n */\nexport function createStore<\n  TState,\n  TActions extends Record<string, ActionReducer<TState, any>> = Record<\n    string,\n    ActionReducer<TState, any>\n  >,\n>(synapse: Synapse, config: StoreConfig<TState> & { actions: TActions }): Store<TState, TActions> {\n  let state = structuredClone(config.initialState);\n  const subscribers = new Set<(state: TState) => void>();\n  let destroyed = false;\n  let persistTimer: ReturnType<typeof setTimeout> | null = null;\n\n  // Build dispatch object from action reducers\n  const dispatch = {} as StoreDispatch<TActions>;\n  for (const key of Object.keys(config.actions)) {\n    (dispatch as any)[key] = (payload: unknown) => {\n      if (destroyed) return;\n      state = config.actions[key](state, payload);\n      notify();\n    };\n  }\n\n  function notify(): void {\n    for (const cb of subscribers) cb(state);\n    if (config.visibleToAgent) pushToAgent();\n    if (config.persist) schedulePersist();\n  }\n\n  function pushToAgent(): void {\n    const summary = config.summarize?.(state);\n    synapse.setVisibleState(state as unknown as Record<string, unknown>, summary);\n  }\n\n  function schedulePersist(): void {\n    if (persistTimer) clearTimeout(persistTimer);\n    persistTimer = setTimeout(() => {\n      synapse\n        ._request(\"synapse/persist-state\", {\n          state: state as unknown as Record<string, unknown>,\n          version: config.version,\n        })\n        .catch(() => {\n          // Silently ignore persist failures (host may not support it)\n        });\n      persistTimer = null;\n    }, 500);\n  }\n\n  // Listen for state loaded from host (on init)\n  let unsubStateLoaded: (() => void) | undefined;\n  if (config.persist) {\n    unsubStateLoaded = synapse._onMessage(\"synapse/state-loaded\", (params) => {\n      if (!params?.state) return;\n      let loaded = params.state as TState;\n      const loadedVersion = (params.version as number) ?? 1;\n      const currentVersion = config.version ?? 1;\n\n      // Run migrations if needed\n      if (config.migrations && loadedVersion < currentVersion) {\n        const startIdx = loadedVersion - 1;\n        for (let i = startIdx; i < config.migrations.length; i++) {\n          loaded = config.migrations[i](loaded);\n        }\n      }\n\n      store.hydrate(loaded);\n    });\n  }\n\n  const store: Store<TState, TActions> = {\n    getState(): TState {\n      return state;\n    },\n\n    subscribe(callback: (state: TState) => void): () => void {\n      subscribers.add(callback);\n      return () => {\n        subscribers.delete(callback);\n      };\n    },\n\n    dispatch,\n\n    hydrate(newState: TState): void {\n      state = newState;\n      for (const cb of subscribers) cb(state);\n    },\n\n    destroy(): void {\n      if (destroyed) return;\n      destroyed = true;\n      if (persistTimer) clearTimeout(persistTimer);\n      subscribers.clear();\n      unsubStateLoaded?.();\n    },\n  };\n\n  return store;\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/index.d.cts

@@ -1,27 +1,21 @@
 export { CreateTaskResult, ReadResourceRequest, ReadResourceResult, Task, TaskStatus } from '@modelcontextprotocol/sdk/types.js';
-import { C as ConnectOptions, A as App, S as SynapseOptions, a as Synapse, b as ActionReducer, c as StoreConfig, d as Store } from './types-BSZasM8q.cjs';
-export { e as AgentAction, f as AppEventName, B as BuiltinActionType, g as CallToolAsTaskOptions, D as DataChangedEvent, h as Dimensions, i as FileResult, j as FontDisplayValue, F as FontFaceDescriptor, H as HostInfo, K as KeyForwardConfig, N as NavigatePayload, k as NotifyPayload, R as RequestFileOptions, l as StateAcknowledgement, m as StoreDispatch, n as SynapseTheme, o as TaskHandle, p as TasksCapability, q as Theme, r as ToolCallResult, T as ToolDefinition, s as ToolResultData, V as VisibleState } from './types-BSZasM8q.cjs';
-export { C as ConnectUIOptions, H as HostCapabilities, a as HostKind, b as HostUnsupportedError, S as SYNAPSE_DATA_ELEMENT_ID, c as SynapseUIClient, d as SynapseUITheme, e as connectUI, f as detectHostKind } from './detect-C_qmYsh9.cjs';
-import '@modelcontextprotocol/ext-apps';
+import { C as ConnectOptions, A as App, R as RequestFileOptions, F as FileResult, a as CallToolAsTaskOptions, T as TaskHandle } from './types-uEO4VFJ2.cjs';
+export { h as AgentAction, i as AppEventName, B as BuiltinActionType, c as CallToolOptions, D as DataChangedEvent, j as Dimensions, k as FontDisplayValue, g as FontFaceDescriptor, H as HostInfo, K as KeyForwardConfig, M as ModelContext, N as NavigatePayload, l as NotifyPayload, m as TasksCapability, d as Theme, b as ToolCallResult, f as ToolDefinition, e as ToolResultData } from './types-uEO4VFJ2.cjs';
+export { C as ConnectUIOptions, H as HostCapabilities, a as HostKind, b as HostUnsupportedError, S as SYNAPSE_DATA_ELEMENT_ID, c as SynapseUIClient, d as SynapseUITheme, e as connectUI, f as detectHostKind } from './detect-BHYg26_d.cjs';
+export { McpUiHostContext } from '@modelcontextprotocol/ext-apps';
 
 /**
- * Connect to a MCP Apps host.
+ * Connect to an MCP Apps host.
  *
- * Owns the full ext-apps handshake, content parsing, resize management,
- * and event routing. Returns a ready-to-use `App` object.
- */
-declare function connect(options: ConnectOptions): Promise<App>;
-
-/**
- * Create a Synapse instance.
- *
- * Wraps the ext-apps protocol handshake via `SynapseTransport` and provides
- * a typed, framework-agnostic API for calling tools, reacting to data changes,
- * dispatching actions, and pushing LLM-visible state.
+ * The one entry point: owns the ext-apps handshake, theme injection, content
+ * parsing, resize management, and event routing, and resolves to a ready
+ * {@link App}.
  *
- * In non-NimbleBrain hosts, NB-specific methods degrade to no-ops.
+ * The `App` it returns stays deliberately small. NimbleBrain's own extensions
+ * (`action`, the file picker, `downloadFile`) and the MCP tasks utility are
+ * composable functions over it — import them from the package root.
  */
-declare function createSynapse(options: SynapseOptions): Synapse;
+declare function connect(options: ConnectOptions): Promise<App>;
 
 /**
  * Host-context key carrying `@font-face` descriptors.
@@ -36,14 +30,52 @@ declare function createSynapse(options: SynapseOptions): Synapse;
 declare const FONT_FACES_CONTEXT_KEY = "synapse/fontFaces";
 
 /**
- * Create a typed state store with optional persistence and agent visibility.
+ * Trigger a host-side action.
+ *
+ * The inverse direction of the `action` event: this sends a command *to* the
+ * host (navigate, open a panel), where `app.on("action", …)` receives the ones
+ * a tool emits. No-op off a NimbleBrain host.
+ */
+declare function action(app: App, name: string, params?: Record<string, unknown>): void;
+/**
+ * Hand the user a file to save.
+ *
+ * Precedence for the MIME type: the explicit argument, then the Blob's own
+ * type, then `application/octet-stream`. An empty-string argument falls
+ * through — a `""` MIME is effectively "no type".
+ */
+declare function downloadFile(app: App, filename: string, content: string | Blob, mimeType?: string): void;
+/**
+ * Request one file from the user via the host's native file picker.
+ *
+ * Resolves `null` if the user cancels. Throws off a NimbleBrain host.
+ */
+declare function pickFile(app: App, options?: RequestFileOptions): Promise<FileResult | null>;
+/**
+ * Request several files from the user.
+ *
+ * Resolves `[]` if the user cancels. Throws off a NimbleBrain host.
+ */
+declare function pickFiles(app: App, options?: RequestFileOptions): Promise<FileResult[]>;
+
+/**
+ * Task-augment a `tools/call` per the MCP 2025-11-25 tasks utility.
+ *
+ * A composable helper over {@link App} rather than a method on it: the object
+ * `connect()` returns carries the ext-apps surface, and tasks ride alongside.
+ * The receiver answers a task-augmented call with a `CreateTaskResult`
+ * promptly; the actual `CallToolResult` arrives later via `tasks/result`.
+ *
+ * ```ts
+ * const handle = await callToolAsTask(app, "deep_research", { topic });
+ * handle.onStatus((t) => setStatus(t.status));
+ * const result = await handle.result();
+ * ```
  *
- * - `persist: true` — state survives iframe reloads via host storage
- * - `visibleToAgent: true` — state is pushed to the LLM context
- * - Both are independent and can be enabled separately
+ * Throws if the host did not advertise `tasks.requests.tools.call` — per spec
+ * a requestor MUST NOT task-augment without matching receiver capability.
+ * Fall back to `app.callTool`.
  */
-declare function createStore<TState, TActions extends Record<string, ActionReducer<TState, any>> = Record<string, ActionReducer<TState, any>>>(synapse: Synapse, config: StoreConfig<TState> & {
-    actions: TActions;
-}): Store<TState, TActions>;
+declare function callToolAsTask<TOutput = unknown>(app: App, toolName: string, args?: unknown, options?: CallToolAsTaskOptions): Promise<TaskHandle<TOutput>>;
 
-export { ActionReducer, App, ConnectOptions, FONT_FACES_CONTEXT_KEY, Store, StoreConfig, Synapse, SynapseOptions, connect, createStore, createSynapse };
+export { App, CallToolAsTaskOptions, ConnectOptions, FONT_FACES_CONTEXT_KEY, FileResult, RequestFileOptions, TaskHandle, action, callToolAsTask, connect, downloadFile, pickFile, pickFiles };

package/dist/index.d.ts

@@ -1,27 +1,21 @@
 export { CreateTaskResult, ReadResourceRequest, ReadResourceResult, Task, TaskStatus } from '@modelcontextprotocol/sdk/types.js';
-import { C as ConnectOptions, A as App, S as SynapseOptions, a as Synapse, b as ActionReducer, c as StoreConfig, d as Store } from './types-BSZasM8q.js';
-export { e as AgentAction, f as AppEventName, B as BuiltinActionType, g as CallToolAsTaskOptions, D as DataChangedEvent, h as Dimensions, i as FileResult, j as FontDisplayValue, F as FontFaceDescriptor, H as HostInfo, K as KeyForwardConfig, N as NavigatePayload, k as NotifyPayload, R as RequestFileOptions, l as StateAcknowledgement, m as StoreDispatch, n as SynapseTheme, o as TaskHandle, p as TasksCapability, q as Theme, r as ToolCallResult, T as ToolDefinition, s as ToolResultData, V as VisibleState } from './types-BSZasM8q.js';
-export { C as ConnectUIOptions, H as HostCapabilities, a as HostKind, b as HostUnsupportedError, S as SYNAPSE_DATA_ELEMENT_ID, c as SynapseUIClient, d as SynapseUITheme, e as connectUI, f as detectHostKind } from './detect-Dfd0upoz.js';
-import '@modelcontextprotocol/ext-apps';
+import { C as ConnectOptions, A as App, R as RequestFileOptions, F as FileResult, a as CallToolAsTaskOptions, T as TaskHandle } from './types-uEO4VFJ2.js';
+export { h as AgentAction, i as AppEventName, B as BuiltinActionType, c as CallToolOptions, D as DataChangedEvent, j as Dimensions, k as FontDisplayValue, g as FontFaceDescriptor, H as HostInfo, K as KeyForwardConfig, M as ModelContext, N as NavigatePayload, l as NotifyPayload, m as TasksCapability, d as Theme, b as ToolCallResult, f as ToolDefinition, e as ToolResultData } from './types-uEO4VFJ2.js';
+export { C as ConnectUIOptions, H as HostCapabilities, a as HostKind, b as HostUnsupportedError, S as SYNAPSE_DATA_ELEMENT_ID, c as SynapseUIClient, d as SynapseUITheme, e as connectUI, f as detectHostKind } from './detect-Bf8Q_0dK.js';
+export { McpUiHostContext } from '@modelcontextprotocol/ext-apps';
 
 /**
- * Connect to a MCP Apps host.
+ * Connect to an MCP Apps host.
  *
- * Owns the full ext-apps handshake, content parsing, resize management,
- * and event routing. Returns a ready-to-use `App` object.
- */
-declare function connect(options: ConnectOptions): Promise<App>;
-
-/**
- * Create a Synapse instance.
- *
- * Wraps the ext-apps protocol handshake via `SynapseTransport` and provides
- * a typed, framework-agnostic API for calling tools, reacting to data changes,
- * dispatching actions, and pushing LLM-visible state.
+ * The one entry point: owns the ext-apps handshake, theme injection, content
+ * parsing, resize management, and event routing, and resolves to a ready
+ * {@link App}.
  *
- * In non-NimbleBrain hosts, NB-specific methods degrade to no-ops.
+ * The `App` it returns stays deliberately small. NimbleBrain's own extensions
+ * (`action`, the file picker, `downloadFile`) and the MCP tasks utility are
+ * composable functions over it — import them from the package root.
  */
-declare function createSynapse(options: SynapseOptions): Synapse;
+declare function connect(options: ConnectOptions): Promise<App>;
 
 /**
  * Host-context key carrying `@font-face` descriptors.
@@ -36,14 +30,52 @@ declare function createSynapse(options: SynapseOptions): Synapse;
 declare const FONT_FACES_CONTEXT_KEY = "synapse/fontFaces";
 
 /**
- * Create a typed state store with optional persistence and agent visibility.
+ * Trigger a host-side action.
+ *
+ * The inverse direction of the `action` event: this sends a command *to* the
+ * host (navigate, open a panel), where `app.on("action", …)` receives the ones
+ * a tool emits. No-op off a NimbleBrain host.
+ */
+declare function action(app: App, name: string, params?: Record<string, unknown>): void;
+/**
+ * Hand the user a file to save.
+ *
+ * Precedence for the MIME type: the explicit argument, then the Blob's own
+ * type, then `application/octet-stream`. An empty-string argument falls
+ * through — a `""` MIME is effectively "no type".
+ */
+declare function downloadFile(app: App, filename: string, content: string | Blob, mimeType?: string): void;
+/**
+ * Request one file from the user via the host's native file picker.
+ *
+ * Resolves `null` if the user cancels. Throws off a NimbleBrain host.
+ */
+declare function pickFile(app: App, options?: RequestFileOptions): Promise<FileResult | null>;
+/**
+ * Request several files from the user.
+ *
+ * Resolves `[]` if the user cancels. Throws off a NimbleBrain host.
+ */
+declare function pickFiles(app: App, options?: RequestFileOptions): Promise<FileResult[]>;
+
+/**
+ * Task-augment a `tools/call` per the MCP 2025-11-25 tasks utility.
+ *
+ * A composable helper over {@link App} rather than a method on it: the object
+ * `connect()` returns carries the ext-apps surface, and tasks ride alongside.
+ * The receiver answers a task-augmented call with a `CreateTaskResult`
+ * promptly; the actual `CallToolResult` arrives later via `tasks/result`.
+ *
+ * ```ts
+ * const handle = await callToolAsTask(app, "deep_research", { topic });
+ * handle.onStatus((t) => setStatus(t.status));
+ * const result = await handle.result();
+ * ```
  *
- * - `persist: true` — state survives iframe reloads via host storage
- * - `visibleToAgent: true` — state is pushed to the LLM context
- * - Both are independent and can be enabled separately
+ * Throws if the host did not advertise `tasks.requests.tools.call` — per spec
+ * a requestor MUST NOT task-augment without matching receiver capability.
+ * Fall back to `app.callTool`.
  */
-declare function createStore<TState, TActions extends Record<string, ActionReducer<TState, any>> = Record<string, ActionReducer<TState, any>>>(synapse: Synapse, config: StoreConfig<TState> & {
-    actions: TActions;
-}): Store<TState, TActions>;
+declare function callToolAsTask<TOutput = unknown>(app: App, toolName: string, args?: unknown, options?: CallToolAsTaskOptions): Promise<TaskHandle<TOutput>>;
 
-export { ActionReducer, App, ConnectOptions, FONT_FACES_CONTEXT_KEY, Store, StoreConfig, Synapse, SynapseOptions, connect, createStore, createSynapse };
+export { App, CallToolAsTaskOptions, ConnectOptions, FONT_FACES_CONTEXT_KEY, FileResult, RequestFileOptions, TaskHandle, action, callToolAsTask, connect, downloadFile, pickFile, pickFiles };

package/dist/index.js

@@ -1,83 +1,5 @@
-export { HostUnsupportedError, SYNAPSE_DATA_ELEMENT_ID, connectUI, detectHostKind } from './chunk-E7OOOYVR.js';
-export { connect, createSynapse } from './chunk-GNTQJSQX.js';
-export { FONT_FACES_CONTEXT_KEY } from './chunk-J5ICAHK2.js';
-
-// src/store.ts
-function createStore(synapse, config) {
-  let state = structuredClone(config.initialState);
-  const subscribers = /* @__PURE__ */ new Set();
-  let destroyed = false;
-  let persistTimer = null;
-  const dispatch = {};
-  for (const key of Object.keys(config.actions)) {
-    dispatch[key] = (payload) => {
-      if (destroyed) return;
-      state = config.actions[key](state, payload);
-      notify();
-    };
-  }
-  function notify() {
-    for (const cb of subscribers) cb(state);
-    if (config.visibleToAgent) pushToAgent();
-    if (config.persist) schedulePersist();
-  }
-  function pushToAgent() {
-    const summary = config.summarize?.(state);
-    synapse.setVisibleState(state, summary);
-  }
-  function schedulePersist() {
-    if (persistTimer) clearTimeout(persistTimer);
-    persistTimer = setTimeout(() => {
-      synapse._request("synapse/persist-state", {
-        state,
-        version: config.version
-      }).catch(() => {
-      });
-      persistTimer = null;
-    }, 500);
-  }
-  let unsubStateLoaded;
-  if (config.persist) {
-    unsubStateLoaded = synapse._onMessage("synapse/state-loaded", (params) => {
-      if (!params?.state) return;
-      let loaded = params.state;
-      const loadedVersion = params.version ?? 1;
-      const currentVersion = config.version ?? 1;
-      if (config.migrations && loadedVersion < currentVersion) {
-        const startIdx = loadedVersion - 1;
-        for (let i = startIdx; i < config.migrations.length; i++) {
-          loaded = config.migrations[i](loaded);
-        }
-      }
-      store.hydrate(loaded);
-    });
-  }
-  const store = {
-    getState() {
-      return state;
-    },
-    subscribe(callback) {
-      subscribers.add(callback);
-      return () => {
-        subscribers.delete(callback);
-      };
-    },
-    dispatch,
-    hydrate(newState) {
-      state = newState;
-      for (const cb of subscribers) cb(state);
-    },
-    destroy() {
-      if (destroyed) return;
-      destroyed = true;
-      if (persistTimer) clearTimeout(persistTimer);
-      subscribers.clear();
-      unsubStateLoaded?.();
-    }
-  };
-  return store;
-}
-
-export { createStore };
+export { HostUnsupportedError, SYNAPSE_DATA_ELEMENT_ID, connectUI, detectHostKind } from './chunk-SRQNQ26I.js';
+export { action, callToolAsTask, connect, downloadFile, pickFile, pickFiles } from './chunk-VYR6V47N.js';
+export { FONT_FACES_CONTEXT_KEY } from './chunk-UPDBDXQB.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/store.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { ActionReducer, Store, StoreConfig, StoreDispatch, Synapse } from \"./types.js\";\n\n/**\n * Create a typed state store with optional persistence and agent visibility.\n *\n * - `persist: true` — state survives iframe reloads via host storage\n * - `visibleToAgent: true` — state is pushed to the LLM context\n * - Both are independent and can be enabled separately\n */\nexport function createStore<\n  TState,\n  TActions extends Record<string, ActionReducer<TState, any>> = Record<\n    string,\n    ActionReducer<TState, any>\n  >,\n>(synapse: Synapse, config: StoreConfig<TState> & { actions: TActions }): Store<TState, TActions> {\n  let state = structuredClone(config.initialState);\n  const subscribers = new Set<(state: TState) => void>();\n  let destroyed = false;\n  let persistTimer: ReturnType<typeof setTimeout> | null = null;\n\n  // Build dispatch object from action reducers\n  const dispatch = {} as StoreDispatch<TActions>;\n  for (const key of Object.keys(config.actions)) {\n    (dispatch as any)[key] = (payload: unknown) => {\n      if (destroyed) return;\n      state = config.actions[key](state, payload);\n      notify();\n    };\n  }\n\n  function notify(): void {\n    for (const cb of subscribers) cb(state);\n    if (config.visibleToAgent) pushToAgent();\n    if (config.persist) schedulePersist();\n  }\n\n  function pushToAgent(): void {\n    const summary = config.summarize?.(state);\n    synapse.setVisibleState(state as unknown as Record<string, unknown>, summary);\n  }\n\n  function schedulePersist(): void {\n    if (persistTimer) clearTimeout(persistTimer);\n    persistTimer = setTimeout(() => {\n      synapse\n        ._request(\"synapse/persist-state\", {\n          state: state as unknown as Record<string, unknown>,\n          version: config.version,\n        })\n        .catch(() => {\n          // Silently ignore persist failures (host may not support it)\n        });\n      persistTimer = null;\n    }, 500);\n  }\n\n  // Listen for state loaded from host (on init)\n  let unsubStateLoaded: (() => void) | undefined;\n  if (config.persist) {\n    unsubStateLoaded = synapse._onMessage(\"synapse/state-loaded\", (params) => {\n      if (!params?.state) return;\n      let loaded = params.state as TState;\n      const loadedVersion = (params.version as number) ?? 1;\n      const currentVersion = config.version ?? 1;\n\n      // Run migrations if needed\n      if (config.migrations && loadedVersion < currentVersion) {\n        const startIdx = loadedVersion - 1;\n        for (let i = startIdx; i < config.migrations.length; i++) {\n          loaded = config.migrations[i](loaded);\n        }\n      }\n\n      store.hydrate(loaded);\n    });\n  }\n\n  const store: Store<TState, TActions> = {\n    getState(): TState {\n      return state;\n    },\n\n    subscribe(callback: (state: TState) => void): () => void {\n      subscribers.add(callback);\n      return () => {\n        subscribers.delete(callback);\n      };\n    },\n\n    dispatch,\n\n    hydrate(newState: TState): void {\n      state = newState;\n      for (const cb of subscribers) cb(state);\n    },\n\n    destroy(): void {\n      if (destroyed) return;\n      destroyed = true;\n      if (persistTimer) clearTimeout(persistTimer);\n      subscribers.clear();\n      unsubStateLoaded?.();\n    },\n  };\n\n  return store;\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}