5.browser-api.md

title	Browser-Side API
navigation	icon i-lucide-globe
description	Lookup tables for the browser side: connectDevframe options, RPC client events, connection statuses, and in-page channels error codes.

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