Browser-Side API
Lookup tables for a devframe's browser side. Each section links the guide page that teaches the concept.
connectDevframe options
The options of connectDevframe() / getDevframeRpcClient(): Client.
| Option | Description |
|---|---|
connection | Connection prepared by setupDevframeConnection(). |
baseURL | Mount path to probe for __connection.json (array = fallback). Default './' (relative to document.baseURI); use an absolute path ('/__devframe/') from outside the SPA. |
authToken | Override the auth token (default: a locally-persisted id). |
cacheOptions | true for default caching, or an options object. |
callTimeout | Ms before a pending rpc.call rejects with a 'timeout' DevframeConnectionError; 0/omit = wait forever. |
wsOptions | Transport overrides: onConnected / onError / onDisconnected hooks, socket URL. |
rpcOptions | Forwarded to birpc. |
connectionMeta | Descriptor that skips the __connection.json fetch. |
webmcp | Mirror agent-flagged client RPC functions onto the page's WebMCP model context as tools; false opts out. Default true (applies only when the browser provides one). See Agent-Native. |
RPC client events
Emitted over rpc.events: Events.
| Event | Fires when |
|---|---|
rpc:is-trusted:updated | Trust granted, denied, or revoked. Carries the new isTrusted boolean. |
connection:status | The connection status changes. Carries (status, previous). |
connection:error | A connection-level failure: socket error or trust refused. Carries the Error. |
rpc:error | An rpc.call rejects, from the node side or a down connection. Carries (error, method). |
Connection statuses
The values of rpc.status: Handling connection and auth errors.
| Status | Meaning |
|---|---|
connecting | Establishing socket / handshake. Calls queue until open. |
connected | Socket open and trusted; calls are served. |
unauthorized | Socket open, trust refused. Prompt for authentication. |
disconnected | Socket closed (dropped mid-session or never opened). |
error | Fatal: the socket errored or connection meta couldn't load. |
In-page channel endpoints
The browser-only endpoint methods of the in-page channel. emit() sends to the opposite endpoint; on() handles events arriving from that endpoint.
InPageChannelProtocol separates functions and events. Each section has optional pageScript and panel maps naming the receiving direction. Endpoint options require a complete functions map with handlers; events is optional, and when provided can include optional handlers (use {} to declare an event without a handler for channel.on()). call() uses function names regardless of return type, while emit(), callEvent() (deprecated), and on() use event names. A function returning void or Promise<void> remains an awaitable request/response call.
| Method or property | Page-script endpoint | Panel endpoint |
|---|---|---|
emit(name, ...args) | Fans an event out to every connected panel. | Sends an event to the page script, buffering while connecting. |
on(name, listener) | Subscribes to events emitted by a panel. Returns an unsubscribe function. | Subscribes to events emitted by the page script. Returns an unsubscribe function. |
call(name, ...args) | Available through a specific PanelPeer. | Calls a page-script function and awaits its result. |
events | Local panel:connected / panel:disconnected lifecycle events. | Local status:updated lifecycle event. |
sharedState | Owns the authoritative state. | Mirrors the page-script state. |
In-page channel error codes
The error.code values of InPageChannelError: Errors and fallbacks.
| Code | When | What to do |
|---|---|---|
timeout | A call outlived callTimeoutMs (default 15s), or whenConnected(ms) expired | The message carries the endpoint status: connecting usually means the page script isn't loaded in this context |
closed | The endpoint was closed with calls pending | Expected during teardown |
not-serializable | A jsonSerializable: true payload contained a non-JSON value | The message names the offending path (e.g. its arguments[0].nodes[2] is a Map) |
not-cloneable | The port refused to clone a payload (DataCloneError) | Strip functions/DOM nodes/reactivity proxies, or declare jsonSerializable: true for the precise error above |
invalid-args | Incoming arguments failed their Standard-Schema validation | The message lists the schema issues |
state-uninitialized | The page script read a shared state before providing its initialValue | Initialize on first access |
Node-Side API
Lookup tables for the node side: DevframeDefinition fields, CLI options, storage scopes, RPC function types, broadcast options, streaming lifecycle, remote assets, the cross-devframe services surface, diagnostics prefixes, and the auth surface.
Hub API
Lookup tables for the hub: subsystems, launcher fields, duplication strategies, dock categories, the hub UI protocol, the namespace routes, the client runtime, the client context, and dock entry types.