> ## Documentation Index
> Fetch the complete documentation index at: https://motiadev-docs-deployment-guide.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser SDK

> Public surface of the iii Browser SDK (`iii-browser-sdk`).

<Note>
  This page is a hand-authored snapshot of the planned public surface. The final reference will be
  generated from the SDK source. The Browser SDK is a standalone implementation alongside the
  Node SDK, not a build of it.
</Note>

## Installation

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
npm install iii-browser-sdk
```

## Common methods

### `registerWorker`

Connect a browser tab to a running iii engine and return its handle.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
function registerWorker(address: string, options?: InitOptions): ISdk;
```

`address` is the engine's SDK WebSocket URL. The returned `ISdk` carries every method below.

### `registerFunction`

Register a callable function in this tab.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
worker.registerFunction(
  functionId: string,
  handler: RemoteFunctionHandler,
  options?: RegisterFunctionOptions,
): FunctionRef;
```

### `registerTrigger`

Bind a registered function to a configured trigger instance.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
worker.registerTrigger(trigger: RegisterTriggerInput): Trigger;
```

Drop the trigger with `Trigger.unregister()` on the returned handle. There is no top-level
`unregisterTrigger`.

### `registerTriggerType`

Declare a new trigger type that this tab advertises.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
worker.registerTriggerType<TConfig>(
  triggerType: RegisterTriggerTypeInput,
  handler: TriggerHandler<TConfig>,
): TriggerTypeRef<TConfig>;
```

### `unregisterTriggerType`

Remove a previously registered trigger type.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
worker.unregisterTriggerType(triggerType: RegisterTriggerTypeInput): void;
```

### `trigger`

Invoke a registered function.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
worker.trigger<TInput, TOutput>(request: TriggerRequest<TInput>): Promise<TOutput>;
```

Resolves with the function's return value for synchronous calls, with an `EnqueueResult` for
`TriggerAction.Enqueue` actions, and with `undefined` for `TriggerAction.Void`.

### `shutdown`

Disconnect from the engine and release resources.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
worker.shutdown(): Promise<void>;
```

## Trigger actions

`TriggerAction` is a runtime const that produces the value passed to `trigger`'s `action` field.

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
TriggerAction.Void();                       // fire-and-forget
TriggerAction.Enqueue({ queue: "math" });   // route through iii-queue
```

The underlying type is `{ type: "enqueue"; queue: string } | { type: "void" }`.

## Channels

`ChannelReader` and `ChannelWriter` are runtime classes wrapping the engine's stream WebSockets
using the browser's native WebSocket API. `StreamChannelRef` is the type passed between SDK calls
to identify a channel:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
type StreamChannelRef = {
  channel_id: string;
  access_key: string;
  direction: "read" | "write";
};
```

`ChannelReader` exposes `onMessage`, `onBinary`, `readAll`, and `close`. `ChannelWriter` exposes
`sendMessage(msg: string)`, `sendBinary(data: Uint8Array)`, and `close()`.

## Connection state

`IIIConnectionState` is the literal-type alias `"disconnected" | "connecting" | "connected" |
"reconnecting" | "failed"`, exported from the package root.

## Info types

* `FunctionInfo`. `function_id`, optional `description`, optional `request_format` /
  `response_format`, optional `metadata`.
* `TriggerInfo`. `id`, `trigger_type`, `function_id`, optional `config` / `metadata`.

`WorkerInfo` and `WorkerMetadata` are not part of this SDK. Use the engine introspection
functions ([`engine::workers::list`](./engine-sdk#engine-discovery-functions)) when a
browser client needs metadata about other workers.

## `MessageType`

A runtime enum naming every wire frame the SDK exchanges with the engine. Rarely needed by
callers.

## Surfaces not in this SDK

* **`Logger`.** The Browser SDK does not ship a structured logger; use the browser's built-in
  `console` and rely on the OpenTelemetry surfaces provided by the
  iii-observability worker for export.
* **Error class.** There is no `IIIError` / `IIIInvocationError` class. Failures are surfaced as
  rejected promises carrying `Error` instances; inspect the message and any attached `code` for
  the engine error code.