@nimblebrain/synapse 0.16.0 → 0.17.0

package/dist/react/index.d.cts

@@ -1,115 +1,99 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { C as ConnectOptions, A as App, q as Theme, s as ToolResultData, S as SynapseOptions, g as CallToolAsTaskOptions, o as TaskHandle, r as ToolCallResult, e as AgentAction, D as DataChangedEvent, R as RequestFileOptions, i as FileResult, b as ActionReducer, d as Store, m as StoreDispatch, a as Synapse, n as SynapseTheme } from '../types-BSZasM8q.cjs';
+import { C as ConnectOptions, a as CallToolAsTaskOptions, T as TaskHandle, b as ToolCallResult, c as CallToolOptions, R as RequestFileOptions, F as FileResult, A as App, D as DataChangedEvent, M as ModelContext, d as Theme, e as ToolResultData } from '../types-uEO4VFJ2.cjs';
 import { McpUiHostContext } from '@modelcontextprotocol/ext-apps';
 import { Task } from '@modelcontextprotocol/sdk/types.js';
 
 interface AppProviderProps extends ConnectOptions {
     children: ReactNode;
 }
-declare function AppProvider({ children, name, version, autoResize }: AppProviderProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Connect on mount and provide the {@link App} to everything below.
+ *
+ * Renders nothing until the handshake completes, so no hook below can observe
+ * a half-connected app and no tool call can be fired into a host that has not
+ * answered `ui/initialize` yet.
+ */
+declare function AppProvider({ children, ...options }: AppProviderProps): react_jsx_runtime.JSX.Element | null;
 
+/** The connected app. Throws outside an `<AppProvider>`. */
 declare function useApp(): App;
-declare function useToolResult(): ToolResultData | null;
-declare function useToolInput(): Record<string, unknown> | null;
-declare function useConnectTheme(): Theme;
-declare function useResize(): (width?: number, height?: number) => void;
-
-interface SynapseProviderProps extends SynapseOptions {
-    children: ReactNode;
-}
-declare function SynapseProvider({ children, ...options }: SynapseProviderProps): react_jsx_runtime.JSX.Element;
-
-declare function useSynapse(): Synapse;
-declare function useCallTool<TOutput = unknown>(toolName: string): {
-    call: (args?: Record<string, unknown>) => Promise<ToolCallResult<TOutput>>;
-    isPending: boolean;
-    error: Error | null;
-    data: TOutput | null;
-};
-declare function useDataSync(callback: (event: DataChangedEvent) => void): void;
 /**
- * Subscribe to agent actions — typed, declarative commands from the server.
- *
- * Actions are emitted by tools as deterministic side effects (e.g., "navigate
- * to the board I just created"). The UI decides how to handle each action type.
+ * The current theme, re-rendering only when it actually moves.
  *
- * @example
- * ```tsx
- * useAgentAction((action) => {
- *   if (action.type === "navigate") {
- *     const { entity, id } = action.payload as NavigatePayload;
- *     if (entity === "board") setSelectedBoardId(id);
- *   }
- * });
- * ```
+ * `App` filters `host-context-changed` notifications through a theme equality
+ * check, so a context update that leaves the derived theme untouched (a
+ * workspace switch, say) does not re-render every themed component.
  */
-declare function useAgentAction(callback: (action: AgentAction) => void): void;
+declare function useTheme(): Theme;
 /**
- * Subscribe to the full ext-apps host context.
- *
- * Returns the host context bag — spec-standardized fields (`theme`, `styles`,
- * `displayMode`, `toolInfo`) plus any host extensions. Re-renders on every
- * `ui/notifications/host-context-changed` notification.
+ * The full ext-apps host context — spec fields (`theme`, `styles`,
+ * `displayMode`, `toolInfo`) plus whatever the host publishes alongside.
+ * Re-renders on every `host-context-changed`.
  *
- * Prefer `useTheme()` when only theming matters (it filters no-op fires and
- * returns a typed `SynapseTheme`). Reach for `useHostContext()` for non-theme
- * fields like host-specific extensions, e.g. on NimbleBrain:
+ * Prefer `useTheme()` when only theming matters: it filters no-op fires.
+ * Reach for this one for host extensions, e.g. on NimbleBrain:
  *
  * ```tsx
  * const { workspace } = useHostContext<{ workspace?: { id: string } }>();
  * ```
  */
 declare function useHostContext<T extends McpUiHostContext = McpUiHostContext>(): T;
+/** The latest tool result pushed by the host, or `null` before one arrives. */
+declare function useToolResult(): ToolResultData | null;
+/** The arguments the host is calling the bound tool with, as they arrive. */
+declare function useToolInput(): Record<string, unknown> | null;
+/** Ask the host to resize this app's frame. */
+declare function useResize(): (width?: number, height?: number) => void;
+interface UseCallToolResult<TOutput> {
+    call: (args?: Record<string, unknown>, options?: CallToolOptions) => Promise<ToolCallResult<TOutput>>;
+    isPending: boolean;
+    error: Error | null;
+    data: TOutput | null;
+}
+/** Call one tool, with pending/error/data state for the latest call. */
+declare function useCallTool<TOutput = unknown>(toolName: string): UseCallToolResult<TOutput>;
+/** Run `callback` whenever the agent changes data this app displays. */
+declare function useDataSync(callback: (event: DataChangedEvent) => void): void;
 /**
- * Re-renders only when the derived `SynapseTheme` actually changes (mode,
- * primaryColor, or any token value). Routes through `synapse.onThemeChanged`
- * — which is itself a `themesEqual`-filtered selector over the unified host
- * context — so a host-context update that doesn't move the theme (e.g. a
- * workspace switch) does NOT cause this hook's consumers to re-render.
- *
- * Building this on `useHostContext` instead would skip the filter: every
- * host-context-changed notification produces a new context reference, which
- * would propagate through `useState` and force a re-render even when the
- * derived theme is unchanged.
- */
-declare function useTheme(): SynapseTheme;
-declare function useAction(): (action: string, params?: Record<string, unknown>) => void;
-declare function useChat(): (message: string, context?: {
-    action?: string;
-    entity?: string;
-}) => void;
-/**
- * Push the app's visible state to the agent via ext-apps `ui/update-model-context`.
- *
- * **Imperative** (no args) — returns a push function you call manually:
- * ```tsx
- * const push = useVisibleState();
- * push({ board: selectedBoard }, "Viewing board X");
- * ```
+ * Push what the user is looking at to the agent (ext-apps
+ * `ui/update-model-context`), debounced so a selection the user drags through
+ * costs one frame rather than thirty.
  *
- * **Declarative** (factory + deps) — auto-pushes when deps change:
+ * **Declarative** — pushes when `deps` change:
  * ```tsx
- * useVisibleState(() => ({
+ * useModelContext(() => ({
  *   state: { board: selectedBoard },
  *   summary: `Viewing "${selectedBoard?.name}"`,
  * }), [selectedBoard]);
  * ```
+ *
+ * **Imperative** — returns a push function:
+ * ```tsx
+ * const push = useModelContext();
+ * push({ board: selectedBoard }, "Viewing board X");
+ * ```
+ *
+ * The debounce lives here rather than on `app.updateModelContext`, which
+ * sends immediately: the rapid-change problem is a React one, and the plain
+ * method should do what it says.
  */
-declare function useVisibleState(): (state: Record<string, unknown>, summary?: string) => void;
-declare function useVisibleState(factory: () => {
-    state: Record<string, unknown>;
-    summary?: string;
-}, deps: unknown[]): void;
-declare function useFileUpload(): {
+declare function useModelContext(): (state: Record<string, unknown>, summary?: string) => void;
+declare function useModelContext(factory: () => ModelContext, deps: unknown[]): void;
+/** Send a user message into the agent conversation. */
+declare function useSendMessage(): (text: string, context?: {
+    action?: string;
+    entity?: string;
+}) => void;
+/** Trigger a host-side action. No-op off a NimbleBrain host. */
+declare function useAction(): (name: string, params?: Record<string, unknown>) => void;
+interface UseFileUploadResult {
     pickFile: (options?: RequestFileOptions) => Promise<FileResult | null>;
     pickFiles: (options?: RequestFileOptions) => Promise<FileResult[]>;
     isPending: boolean;
-};
-declare function useStore<TState, TActions extends Record<string, ActionReducer<TState, any>>>(store: Store<TState, TActions>): {
-    state: TState;
-    dispatch: StoreDispatch<TActions>;
-};
+}
+/** The host's native file picker, with a pending flag. NimbleBrain only. */
+declare function useFileUpload(): UseFileUploadResult;
 interface UseCallToolAsTaskResult<TInput, TOutput> {
     /**
      * Start (or re-start) a task-augmented tool call. Returns the
@@ -140,7 +124,7 @@ interface UseCallToolAsTaskResult<TInput, TOutput> {
     cancel(): Promise<void>;
 }
 /**
- * React hook wrapper around `synapse.callToolAsTask`.
+ * React wrapper around `callToolAsTask(app, …)`.
  *
  * Handles the full MCP 2025-11-25 task lifecycle:
  *
@@ -162,4 +146,4 @@ interface UseCallToolAsTaskResult<TInput, TOutput> {
  */
 declare function useCallToolAsTask<TInput = Record<string, unknown>, TOutput = unknown>(toolName: string): UseCallToolAsTaskResult<TInput, TOutput>;
 
-export { AppProvider, type AppProviderProps, SynapseProvider, type SynapseProviderProps, type UseCallToolAsTaskResult, useAction, useAgentAction, useApp, useCallTool, useCallToolAsTask, useChat, useConnectTheme, useDataSync, useFileUpload, useHostContext, useResize, useStore, useSynapse, useTheme, useToolInput, useToolResult, useVisibleState };
+export { AppProvider, type AppProviderProps, type UseCallToolAsTaskResult, type UseCallToolResult, type UseFileUploadResult, useAction, useApp, useCallTool, useCallToolAsTask, useDataSync, useFileUpload, useHostContext, useModelContext, useResize, useSendMessage, useTheme, useToolInput, useToolResult };

package/dist/react/index.d.ts

@@ -1,115 +1,99 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { C as ConnectOptions, A as App, q as Theme, s as ToolResultData, S as SynapseOptions, g as CallToolAsTaskOptions, o as TaskHandle, r as ToolCallResult, e as AgentAction, D as DataChangedEvent, R as RequestFileOptions, i as FileResult, b as ActionReducer, d as Store, m as StoreDispatch, a as Synapse, n as SynapseTheme } from '../types-BSZasM8q.js';
+import { C as ConnectOptions, a as CallToolAsTaskOptions, T as TaskHandle, b as ToolCallResult, c as CallToolOptions, R as RequestFileOptions, F as FileResult, A as App, D as DataChangedEvent, M as ModelContext, d as Theme, e as ToolResultData } from '../types-uEO4VFJ2.js';
 import { McpUiHostContext } from '@modelcontextprotocol/ext-apps';
 import { Task } from '@modelcontextprotocol/sdk/types.js';
 
 interface AppProviderProps extends ConnectOptions {
     children: ReactNode;
 }
-declare function AppProvider({ children, name, version, autoResize }: AppProviderProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Connect on mount and provide the {@link App} to everything below.
+ *
+ * Renders nothing until the handshake completes, so no hook below can observe
+ * a half-connected app and no tool call can be fired into a host that has not
+ * answered `ui/initialize` yet.
+ */
+declare function AppProvider({ children, ...options }: AppProviderProps): react_jsx_runtime.JSX.Element | null;
 
+/** The connected app. Throws outside an `<AppProvider>`. */
 declare function useApp(): App;
-declare function useToolResult(): ToolResultData | null;
-declare function useToolInput(): Record<string, unknown> | null;
-declare function useConnectTheme(): Theme;
-declare function useResize(): (width?: number, height?: number) => void;
-
-interface SynapseProviderProps extends SynapseOptions {
-    children: ReactNode;
-}
-declare function SynapseProvider({ children, ...options }: SynapseProviderProps): react_jsx_runtime.JSX.Element;
-
-declare function useSynapse(): Synapse;
-declare function useCallTool<TOutput = unknown>(toolName: string): {
-    call: (args?: Record<string, unknown>) => Promise<ToolCallResult<TOutput>>;
-    isPending: boolean;
-    error: Error | null;
-    data: TOutput | null;
-};
-declare function useDataSync(callback: (event: DataChangedEvent) => void): void;
 /**
- * Subscribe to agent actions — typed, declarative commands from the server.
- *
- * Actions are emitted by tools as deterministic side effects (e.g., "navigate
- * to the board I just created"). The UI decides how to handle each action type.
+ * The current theme, re-rendering only when it actually moves.
  *
- * @example
- * ```tsx
- * useAgentAction((action) => {
- *   if (action.type === "navigate") {
- *     const { entity, id } = action.payload as NavigatePayload;
- *     if (entity === "board") setSelectedBoardId(id);
- *   }
- * });
- * ```
+ * `App` filters `host-context-changed` notifications through a theme equality
+ * check, so a context update that leaves the derived theme untouched (a
+ * workspace switch, say) does not re-render every themed component.
  */
-declare function useAgentAction(callback: (action: AgentAction) => void): void;
+declare function useTheme(): Theme;
 /**
- * Subscribe to the full ext-apps host context.
- *
- * Returns the host context bag — spec-standardized fields (`theme`, `styles`,
- * `displayMode`, `toolInfo`) plus any host extensions. Re-renders on every
- * `ui/notifications/host-context-changed` notification.
+ * The full ext-apps host context — spec fields (`theme`, `styles`,
+ * `displayMode`, `toolInfo`) plus whatever the host publishes alongside.
+ * Re-renders on every `host-context-changed`.
  *
- * Prefer `useTheme()` when only theming matters (it filters no-op fires and
- * returns a typed `SynapseTheme`). Reach for `useHostContext()` for non-theme
- * fields like host-specific extensions, e.g. on NimbleBrain:
+ * Prefer `useTheme()` when only theming matters: it filters no-op fires.
+ * Reach for this one for host extensions, e.g. on NimbleBrain:
  *
  * ```tsx
  * const { workspace } = useHostContext<{ workspace?: { id: string } }>();
  * ```
  */
 declare function useHostContext<T extends McpUiHostContext = McpUiHostContext>(): T;
+/** The latest tool result pushed by the host, or `null` before one arrives. */
+declare function useToolResult(): ToolResultData | null;
+/** The arguments the host is calling the bound tool with, as they arrive. */
+declare function useToolInput(): Record<string, unknown> | null;
+/** Ask the host to resize this app's frame. */
+declare function useResize(): (width?: number, height?: number) => void;
+interface UseCallToolResult<TOutput> {
+    call: (args?: Record<string, unknown>, options?: CallToolOptions) => Promise<ToolCallResult<TOutput>>;
+    isPending: boolean;
+    error: Error | null;
+    data: TOutput | null;
+}
+/** Call one tool, with pending/error/data state for the latest call. */
+declare function useCallTool<TOutput = unknown>(toolName: string): UseCallToolResult<TOutput>;
+/** Run `callback` whenever the agent changes data this app displays. */
+declare function useDataSync(callback: (event: DataChangedEvent) => void): void;
 /**
- * Re-renders only when the derived `SynapseTheme` actually changes (mode,
- * primaryColor, or any token value). Routes through `synapse.onThemeChanged`
- * — which is itself a `themesEqual`-filtered selector over the unified host
- * context — so a host-context update that doesn't move the theme (e.g. a
- * workspace switch) does NOT cause this hook's consumers to re-render.
- *
- * Building this on `useHostContext` instead would skip the filter: every
- * host-context-changed notification produces a new context reference, which
- * would propagate through `useState` and force a re-render even when the
- * derived theme is unchanged.
- */
-declare function useTheme(): SynapseTheme;
-declare function useAction(): (action: string, params?: Record<string, unknown>) => void;
-declare function useChat(): (message: string, context?: {
-    action?: string;
-    entity?: string;
-}) => void;
-/**
- * Push the app's visible state to the agent via ext-apps `ui/update-model-context`.
- *
- * **Imperative** (no args) — returns a push function you call manually:
- * ```tsx
- * const push = useVisibleState();
- * push({ board: selectedBoard }, "Viewing board X");
- * ```
+ * Push what the user is looking at to the agent (ext-apps
+ * `ui/update-model-context`), debounced so a selection the user drags through
+ * costs one frame rather than thirty.
  *
- * **Declarative** (factory + deps) — auto-pushes when deps change:
+ * **Declarative** — pushes when `deps` change:
  * ```tsx
- * useVisibleState(() => ({
+ * useModelContext(() => ({
  *   state: { board: selectedBoard },
  *   summary: `Viewing "${selectedBoard?.name}"`,
  * }), [selectedBoard]);
  * ```
+ *
+ * **Imperative** — returns a push function:
+ * ```tsx
+ * const push = useModelContext();
+ * push({ board: selectedBoard }, "Viewing board X");
+ * ```
+ *
+ * The debounce lives here rather than on `app.updateModelContext`, which
+ * sends immediately: the rapid-change problem is a React one, and the plain
+ * method should do what it says.
  */
-declare function useVisibleState(): (state: Record<string, unknown>, summary?: string) => void;
-declare function useVisibleState(factory: () => {
-    state: Record<string, unknown>;
-    summary?: string;
-}, deps: unknown[]): void;
-declare function useFileUpload(): {
+declare function useModelContext(): (state: Record<string, unknown>, summary?: string) => void;
+declare function useModelContext(factory: () => ModelContext, deps: unknown[]): void;
+/** Send a user message into the agent conversation. */
+declare function useSendMessage(): (text: string, context?: {
+    action?: string;
+    entity?: string;
+}) => void;
+/** Trigger a host-side action. No-op off a NimbleBrain host. */
+declare function useAction(): (name: string, params?: Record<string, unknown>) => void;
+interface UseFileUploadResult {
     pickFile: (options?: RequestFileOptions) => Promise<FileResult | null>;
     pickFiles: (options?: RequestFileOptions) => Promise<FileResult[]>;
     isPending: boolean;
-};
-declare function useStore<TState, TActions extends Record<string, ActionReducer<TState, any>>>(store: Store<TState, TActions>): {
-    state: TState;
-    dispatch: StoreDispatch<TActions>;
-};
+}
+/** The host's native file picker, with a pending flag. NimbleBrain only. */
+declare function useFileUpload(): UseFileUploadResult;
 interface UseCallToolAsTaskResult<TInput, TOutput> {
     /**
      * Start (or re-start) a task-augmented tool call. Returns the
@@ -140,7 +124,7 @@ interface UseCallToolAsTaskResult<TInput, TOutput> {
     cancel(): Promise<void>;
 }
 /**
- * React hook wrapper around `synapse.callToolAsTask`.
+ * React wrapper around `callToolAsTask(app, …)`.
  *
  * Handles the full MCP 2025-11-25 task lifecycle:
  *
@@ -162,4 +146,4 @@ interface UseCallToolAsTaskResult<TInput, TOutput> {
  */
 declare function useCallToolAsTask<TInput = Record<string, unknown>, TOutput = unknown>(toolName: string): UseCallToolAsTaskResult<TInput, TOutput>;
 
-export { AppProvider, type AppProviderProps, SynapseProvider, type SynapseProviderProps, type UseCallToolAsTaskResult, useAction, useAgentAction, useApp, useCallTool, useCallToolAsTask, useChat, useConnectTheme, useDataSync, useFileUpload, useHostContext, useResize, useStore, useSynapse, useTheme, useToolInput, useToolResult, useVisibleState };
+export { AppProvider, type AppProviderProps, type UseCallToolAsTaskResult, type UseCallToolResult, type UseFileUploadResult, useAction, useApp, useCallTool, useCallToolAsTask, useDataSync, useFileUpload, useHostContext, useModelContext, useResize, useSendMessage, useTheme, useToolInput, useToolResult };