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.themeand 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.