SDK Page API

2026-11-15

API reference for plugin pages (browser side): the bridge, restore state, the save contract and document navigation.

Pages, state & saving (browser side)

const sdk = await connect() returns a BrowserAPI:

Member Signature Notes
context context(): Promise Current view session (state, theme, color scheme)
setState setState(state, dirty?) Write the page's restore state — a JSON checkpoint up to 64 KiB; one in-flight request and the latest snapshot win, batched writes share results
onSave onSave(handler): () => void Register a save handler; returns an unsubscribe function
commands.invoke invoke(command, args?): Promise Invoke one of this plugin's commands, returns a host task
tasks.list list(): Promise<summaries[]> Summaries of this plugin's tasks; no result payload — hasResult marks availability so large results never flood control frames
tasks.get get(id): Promise Full state and result of one task; only this plugin's tasks
tasks.cancel cancel(id): Promise Request cancellation — cooperative
appearance getColorScheme() / onDidChangeColorScheme(listener) Revision 2: read the host-resolved light / dark synchronously and subscribe to changes; the host sets data-color-scheme before the first paint
ready ready(): Promise Revision 2: call after the first usable frame (including an error screen) so the host ends its loading hint; do not wait for requestAnimationFrame

Save-contract example:

const view = await sdk.context()
let draft = view.state ?? { text: '' }

async function edited(text: string) {
  draft = { text }
  await sdk.setState(draft, true)
}

sdk.onSave(async () => {
  // commit to your own resource first; throw to stay dirty on failure
  await persistDraft(draft)
  await sdk.setState(draft, false)
})
await sdk.ready()
  • The host keys state by pluginId/viewId/instanceId/workspaceId/resource so it never restores onto another file;
  • Themes arrive as CSS variables in view.theme and update dynamically; the title, back and refresh controls are rendered by the plugin itself (revision 3) — the host only provides the container and failure recovery;
  • Concurrency: at most 32 in-flight SDK requests per page, 16 concurrent operations per page in the host; exceeding returns BACKPRESSURE;
  • On bridge timeout or lost connection show an error; never blindly replay side effects;
  • Closing a page releases the bridge and renderer but keeps background tasks running; save confirmation waits for committed state, timeout reports SAVE_TIMEOUT.

Document navigation (revision 3)

sdk.ui.openDocument({workspaceId, workspaceSession, documentId}) locates and opens a document in the main window, reopening the tab if it was closed; collection documents resolve to their chapter. Navigation binds to the workspace session from page open, waits for save coordination and main-window confirmation; cancellation returns NAVIGATION_CANCELLED, timeout NAVIGATION_TIMEOUT, workspace changes WORKSPACE_CHANGED. Plugins decide themselves whether to save their draft before navigating: persist, wait for success, then navigate.