@nimblebrain/synapse 0.2.1 → 0.3.0

package/README.md

@@ -7,12 +7,13 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
 
-Agent-aware app SDK for the [MCP ext-apps](https://modelcontextprotocol.io/specification/2025-06-18/user-interaction/ext-apps) protocol. Typed tool calls, reactive data sync, and React hooks — works in any host that implements ext-apps (Claude Desktop, VS Code, ChatGPT, [NimbleBrain](https://nimblebrain.ai), or your own runtime).
+Agent-aware app SDK for the [MCP ext-apps](https://modelcontextprotocol.io/specification/2025-06-18/user-interaction/ext-apps) protocol. One `await connect()` and you're live — typed tool calls, reactive data sync, and React hooks that work in any host implementing ext-apps (Claude Desktop, VS Code, ChatGPT, [NimbleBrain](https://nimblebrain.ai), or your own runtime).
 
 ## What is Synapse?
 
 Synapse is an optional enhancement layer over `@modelcontextprotocol/ext-apps`. It wraps the ext-apps protocol handshake and adds:
 
+- **Zero-config handshake** — `await connect()` resolves when the host is ready. You never see `ui/initialize`.
 - **Typed tool calls** — call MCP tools with full TypeScript input/output types
 - **Reactive data sync** — subscribe to data change events from the agent
 - **Theme tracking** — automatic light/dark mode and custom design tokens
@@ -40,36 +41,36 @@ npm install @nimblebrain/synapse
 
 | Entry Point | Description |
 |-------------|-------------|
-| `@nimblebrain/synapse` | Vanilla JS core (no framework dependency) |
-| `@nimblebrain/synapse/react` | React hooks and provider |
+| `@nimblebrain/synapse` | Vanilla JS core — `connect()`, `createSynapse()`, `createStore()` |
+| `@nimblebrain/synapse/react` | React hooks and providers (`AppProvider`, `SynapseProvider`) |
 | `@nimblebrain/synapse/vite` | Vite plugin for dev mode |
 | `@nimblebrain/synapse/codegen` | CLI + programmatic code generation |
+| `@nimblebrain/synapse/iife` | Pre-built IIFE bundle for `<script>` tags (`window.Synapse`) |
 
 ## Quick Start
 
 ### Vanilla JS
 
 ```typescript
-import { createSynapse } from "@nimblebrain/synapse";
+import { connect } from "@nimblebrain/synapse";
 
-const synapse = createSynapse({
-  name: "my-app",
-  version: "1.0.0",
-});
+const app = await connect({ name: "my-app", version: "1.0.0" });
 
-await synapse.ready;
+// Theme, host info, and tool context are available immediately
+console.log(app.theme.mode); // "dark"
+console.log(app.hostInfo);   // { name: "nimblebrain", version: "2.0.0" }
+
+// Subscribe to tool results from the agent
+app.on("tool-result", (data) => {
+  console.log(data.content); // parsed JSON or raw string
+});
 
 // Call an MCP tool
-const result = await synapse.callTool("get_items", { limit: 10 });
+const result = await app.callTool("get_items", { limit: 10 });
 console.log(result.data);
 
-// React to data changes from the agent
-synapse.onDataChanged((event) => {
-  console.log(`${event.tool} was called on ${event.server}`);
-});
-
-// Push state visible to the LLM
-synapse.setVisibleState(
+// Tell the agent what the user sees
+app.updateModelContext(
   { selectedItem: "item-42" },
   "User is viewing item 42",
 );
@@ -78,31 +79,44 @@ synapse.setVisibleState(
 ### React
 
 ```tsx
-import { SynapseProvider, useCallTool, useTheme } from "@nimblebrain/synapse/react";
+import { AppProvider, useToolResult, useCallTool, useResize } from "@nimblebrain/synapse/react";
 
 function App() {
   return (
-    <SynapseProvider name="my-app" version="1.0.0">
+    <AppProvider name="my-app" version="1.0.0">
       <ItemList />
-    </SynapseProvider>
+    </AppProvider>
   );
 }
 
 function ItemList() {
-  const { call, data, isPending } = useCallTool<Item[]>("list_items");
-  const theme = useTheme();
+  const result = useToolResult();
+  const { call, data, isPending } = useCallTool("list_items");
+  const resize = useResize();
 
-  return (
-    <div style={{ colorScheme: theme.mode }}>
-      <button onClick={() => call()} disabled={isPending}>
-        Load Items
-      </button>
-      {data?.map((item) => <div key={item.id}>{item.name}</div>)}
-    </div>
-  );
+  useEffect(() => { if (result) resize(); }, [result, resize]);
+
+  if (!result) return <p>Waiting for data...</p>;
+  return result.content.items.map((item) => <div key={item.id}>{item.name}</div>);
 }
 ```
 
+### Script Tag (IIFE)
+
+Drop a single `<script>` tag — no bundler required:
+
+```html
+<script src="https://unpkg.com/@nimblebrain/synapse/dist/connect.iife.global.js"></script>
+<script>
+Synapse.connect({ name: "widget", version: "1.0.0", autoResize: true })
+  .then(app => {
+    app.on("tool-result", (data) => {
+      document.getElementById("root").innerHTML = render(data.content);
+    });
+  });
+</script>
+```
+
 ### Vite Plugin
 
 ```typescript
@@ -138,6 +152,54 @@ Or from a directory of `.schema.json` files (generates CRUD tool types):
 npx synapse --from-schema ./schemas --out src/generated/types.ts
 ```
 
+## Handling Events
+
+The `App` object returned by `connect()` uses a unified `on()` method for all events. Each call returns an unsubscribe function.
+
+```typescript
+const app = await connect({ name: "my-app", version: "1.0.0" });
+
+// Tool results from the agent (parsed content, not raw JSON-RPC)
+const unsub = app.on("tool-result", (data) => {
+  console.log(data.content);            // parsed JSON or raw string
+  console.log(data.structuredContent);   // structuredContent if host sent it
+  console.log(data.raw);                // original params for advanced use
+});
+
+// Tool input arguments (what the agent is calling with)
+app.on("tool-input", (args) => {
+  console.log(args); // Record<string, unknown>
+});
+
+// Theme changes
+app.on("theme-changed", (theme) => {
+  document.body.classList.toggle("dark", theme.mode === "dark");
+});
+
+// Lifecycle — clean up when the host tears down the view
+app.on("teardown", () => {
+  saveState();
+});
+
+// NimbleBrain extensions work as passthrough event names
+app.on("synapse/data-changed", (params) => {
+  refreshData();
+});
+
+// Unsubscribe when done
+unsub();
+```
+
+| `on()` Event | Spec Method | Data |
+|---|---|---|
+| `"tool-result"` | `ui/notifications/tool-result` | `ToolResultData` (parsed) |
+| `"tool-input"` | `ui/notifications/tool-input` | `Record<string, unknown>` |
+| `"tool-input-partial"` | `ui/notifications/tool-input-partial` | `Record<string, unknown>` |
+| `"tool-cancelled"` | `ui/notifications/tool-cancelled` | — |
+| `"theme-changed"` | `ui/notifications/host-context-changed` | `Theme` |
+| `"teardown"` | `ui/resource-teardown` | — |
+| Any custom string | Passed through as-is | `unknown` |
+
 ## State Store
 
 Create a typed, reactive store with optional persistence and agent visibility:
@@ -178,9 +240,53 @@ function Counter() {
 
 ## API Reference
 
-### `createSynapse(options)`
+### `connect(options)` — Recommended
 
-Creates a Synapse instance. Returns a `Synapse` object.
+Creates a connected `App` instance. The returned promise resolves after the ext-apps handshake completes — theme, host info, and tool context are available immediately.
+
+```typescript
+import { connect } from "@nimblebrain/synapse";
+
+const app = await connect({ name: "my-app", version: "1.0.0" });
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | `string` | App name (must match registered bundle name) |
+| `version` | `string` | Semver version |
+| `autoResize` | `boolean?` | Observe `document.body` and auto-send `size-changed`. Default: `false` |
+
+### `App` Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `theme` | `Theme` | Current theme (`mode`, `tokens`) |
+| `hostInfo` | `{ name, version }` | Host identity |
+| `toolInfo` | `{ tool } \| null` | Tool context if launched from a tool call |
+| `containerDimensions` | `Dimensions \| null` | Container size constraints from host |
+
+### `App` Methods
+
+| Method | Description |
+|--------|-------------|
+| `on(event, handler)` | Subscribe to events. Returns unsubscribe function. |
+| `resize(width?, height?)` | Send size to host. Auto-measures `document.body` if no args. |
+| `openLink(url)` | Open a URL (host-aware) |
+| `updateModelContext(state, summary?)` | Push LLM-visible state |
+| `callTool(name, args?)` | Call an MCP tool and get typed result |
+| `sendMessage(text, context?)` | Send a chat message to the agent |
+| `destroy()` | Clean up all listeners, observers, and timers |
+
+### `createSynapse(options)` — Advanced / Legacy
+
+The original Synapse API. Still fully supported — use it when you need the state store, agent actions, file operations, or NimbleBrain-specific features not yet surfaced in `connect()`.
+
+```typescript
+import { createSynapse } from "@nimblebrain/synapse";
+
+const synapse = createSynapse({ name: "my-app", version: "1.0.0" });
+await synapse.ready;
+```
 
 | Option | Type | Description |
 |--------|------|-------------|
@@ -197,27 +303,57 @@ Creates a Synapse instance. Returns a `Synapse` object.
 | `isNimbleBrainHost` | Whether the host is a NimbleBrain platform |
 | `callTool(name, args?)` | Call an MCP tool and get typed result |
 | `onDataChanged(cb)` | Subscribe to data change events |
+| `onAction(cb)` | Subscribe to agent actions (typed, declarative) |
 | `getTheme()` | Get current theme |
 | `onThemeChanged(cb)` | Subscribe to theme changes |
 | `action(name, params?)` | Dispatch a NB platform action |
 | `chat(message, context?)` | Send a chat message to the agent |
 | `setVisibleState(state, summary?)` | Push LLM-visible state (debounced 250ms) |
-| `downloadFile(name, content, mime?)` | Trigger a file download |
+| `saveFile(name, content, mime?)` | Trigger a file save (NB-only) |
+| `pickFile(options?)` | Open native file picker, single file (NB-only) |
+| `pickFiles(options?)` | Open native file picker, multiple files (NB-only) |
 | `openLink(url)` | Open a URL (host-aware) |
 | `destroy()` | Clean up all listeners and timers |
 
-### React Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useSynapse()` | Access the Synapse instance |
-| `useCallTool(name)` | `{ call, data, isPending, error }` for a tool |
-| `useDataSync(cb)` | Subscribe to data change events |
-| `useTheme()` | Reactive theme object |
-| `useAction()` | Dispatch platform actions |
-| `useChat()` | Send chat messages |
-| `useVisibleState()` | Push LLM-visible state |
-| `useStore(store)` | `{ state, dispatch }` for a store |
+## React Hooks
+
+### `AppProvider`-based (Recommended)
+
+Wrap your app with `<AppProvider>` and use these hooks. Each is a thin wrapper over `connect()`.
+
+```tsx
+import { AppProvider, useApp, useToolResult, useToolInput, useResize, useCallTool } from "@nimblebrain/synapse/react";
+```
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useApp()` | `App` | Access the connected `App` instance |
+| `useToolResult()` | `ToolResultData \| null` | Re-renders on every `tool-result` event |
+| `useToolInput()` | `Record<string, unknown> \| null` | Re-renders on every `tool-input` event |
+| `useConnectTheme()` | `Theme` | Reactive theme from `connect()` |
+| `useResize()` | `(w?, h?) => void` | Resize helper — auto-measures body if no args |
+| `useCallTool(name)` | `{ call, data, isPending, error }` | Call a tool with loading/error state |
+
+### `SynapseProvider`-based (Legacy)
+
+For existing apps using `createSynapse()`. Still fully supported.
+
+```tsx
+import { SynapseProvider, useSynapse, useCallTool, useTheme } from "@nimblebrain/synapse/react";
+```
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useSynapse()` | `Synapse` | Access the Synapse instance |
+| `useCallTool(name)` | `{ call, data, isPending, error }` | Call a tool with loading/error state |
+| `useDataSync(cb)` | — | Subscribe to data change events |
+| `useTheme()` | `SynapseTheme` | Reactive theme object |
+| `useAction()` | `(name, params?) => void` | Dispatch platform actions |
+| `useAgentAction(cb)` | — | Subscribe to agent actions |
+| `useChat()` | `(msg, ctx?) => void` | Send chat messages |
+| `useVisibleState()` | `(state, summary?) => void` | Push LLM-visible state |
+| `useFileUpload()` | File picker helpers | File upload (NB-only) |
+| `useStore(store)` | `{ state, dispatch }` | Bind a store to React |
 
 ## Development