# API reference

The SDK has two entry points:

- `@shappychat/chat`: the browser entry point
- `@shappychat/chat/node`: the Node entry point

Import the styles one time: `import '@shappychat/chat/style.css'`.

## Mount the UI

| Export | Description |
| --- | --- |
| `mountShappyChatDrawer(container, options)` | Mounts the full chat surface with header and launchers. Returns a `ShappyChatDrawer`. See [Embed the chat](/docs/embed). |
| `mountShappyChat(container, options)` | Mounts only the conversation and the message field. Returns `{ element, unmount }`. |
| `createShappyChatModelPicker(options)` | Creates the model menu. Methods: `open(anchor, runtime)` and `close()`. |

### `MountShappyChatOptions`

| Option | Type | Description |
| --- | --- | --- |
| `runtime` | `ShappyChatRuntime` | Required |
| `onModelSelect` | `(anchor?: HTMLElement) => void \| Promise<void>` | Shows the model button when set |
| `onError` | `(error: unknown) => void` | Called when an error occurs |
| `onBeforeSend` | `() => void \| Promise<void>` | Called before each message is sent |
| `enableAttachments` | `boolean` | Default `true`. The chat sends images only to a model that reads images. It sends documents as text to all models. |
| `showExecutionMode` | `boolean` | Shows the Auto, UI and MCP menu and its Shift + Tab shortcut. Default `false` (Auto). |
| `character` | `GhostCharacter` | The Shappy Ghost shown while a turn is in progress: `classic` (default), `sprout`, `bow`, `headphones`, `cap`, `wizard`, `blush`, `glasses`, `antenna`, `imp`, `snow` or `crown`. `GHOST_CHARACTERS` lists them with their colours. |

### Types

| Type | Values |
| --- | --- |
| `ShappyChatPresentation` | `'drawer' \| 'floating' \| 'island' \| 'inline'` |
| `ShappyChatTheme` | `{ accent?, panel?, field?, ink?, ghost?: string; glow?: boolean }` |
| `ExecutionMode` | `'auto' \| 'ui' \| 'mcp'` |

## Runtimes

| Export | Description |
| --- | --- |
| `RemoteShappyChatRuntime.connect({ url, token, conversationId })` | Connects to a conversation on Shappy Backend |
| `createShappyChatRuntime(options)` | Opens or creates a browser-local Pi Durable conversation, stored in IndexedDB. Options: `scope`, `conversationId?`, `model?`, `systemPrompt?`, `connections?`, `uiCursor?`, `getApiKey?`, `database?`, `onMoved?`. One window at a time writes a conversation. Opening it elsewhere asks the holding window to hand it over: an idle holder closes it and calls its `onMoved`, a holder still answering refuses. |
| `listBrowserConversations(scope)` | Lists the conversations stored in this browser for a scope, newest first |
| `DurableRuntime` | The runtime class behind `createShappyChatRuntime` and the Node runtime |
| `McpConnections` | A set of MCP connections. Use `add({ id, url, headers })`. |
| `discoverOpenAiModels(baseUrl, apiKey?)` | Lists the chat models of an OpenAI-compatible endpoint |
| `openAiCompatibleModel(id, baseUrl, name?)` | Describes one model on an OpenAI-compatible endpoint |

### Runtime methods

| Method | Description |
| --- | --- |
| `getSnapshot()` | Returns the current state, including `conversationId`, `model`, `executionMode` and `activeExecutionMode` |
| `configure(input)` | Changes settings, for example `{ executionMode: 'ui' }` |
| `attachUi(adapter)`, `detachUi()` | Connects or removes UI tools (remote runtime) |
| `setHostTools(tools)` | Sets UI tools (browser-local runtime) |
| `close()` | Stops the updates of this client (remote runtime), or releases the conversation for other windows (browser-local runtime) |

## UI tools

| Export | Description |
| --- | --- |
| `createDomAdapter({ root, cursor? })` | Finds marked controls in `root` and acts on them. Methods: `discover()`, `act(request)`, `register(id, handlers)`, `dispose()`. |
| `createUiCursor({ mode?, storageKey? })` | Creates the visible cursor. Methods: `setMode(mode)`, `dispose()`. |
| `createUiTools(executor)` | Turns a discover and act function into tools for a browser-local runtime |
| `AGENT_ID_ATTRIBUTE` | `'data-agent-id'` |
| `AGENT_DESCRIPTION_ATTRIBUTE` | `'data-agent-description'` |
| `EXECUTION_MODES` | The list of execution modes |

## Node entry point

| Export | Description |
| --- | --- |
| `createNodeShappyChatRuntime(options)` | Creates a runtime with Pi Durable SQLite storage in `storageDirectory`. Returns `{ runtime, host, close }`. |
| `addStdioConnection(connections, config)` | Adds an MCP server that runs as a local process |
| `openNodeDurableHost(directory, getApiKey?)` | Opens the Pi Durable host for `directory/chat.sqlite` and claims it for this process. Returns `{ host, close }`. |
| `createRuntimeBridge(config)` | Serves a runtime over authenticated HTTP. Its optional `celld` setting connects to a bound cell host. |
| `CelldShappyChatRuntime.connect(options)` | Source Node export for a trusted celld connection. See [Durable Chat](/docs/durable-chat). |
| `CelldRuntimeOptions` | `{ url, token, conversationId, scope, clientId? }`. Keep the service token in the backend. |