Plugin SDK Overview
2026-11-15
The plugin SDK is the entire interface surface between a plugin and the host: the backend entry blc-plugin-sdk, the page entry blc-plugin-sdk/browser, and the manifest schema. It ships as a public npm package (npm install blc-plugin-sdk); the authoritative types are the bundled index.d.ts and browser.d.ts. The API major version is 1, extended by revisions: revision 1 added chunked document export, revision 2 color scheme, page readiness and user-entry declarations, revision 3 document navigation. This page covers the overview and core concepts; field-level details live in SDK Manifest Schema, SDK Backend API and SDK Page API.
Two entries
| Entry | Runs in | Import | Capability boundary |
|---|---|---|---|
blc-plugin-sdk |
plugin backend (Node 22, own process) | import { definePlugin } from 'blc-plugin-sdk' |
Full Node file, network and subprocess capabilities |
blc-plugin-sdk/browser |
plugin page (browser renderer) | import { connect } from 'blc-plugin-sdk/browser' |
Only this page's view session and the SDK APIs; Node modules must not be imported |
Pages may also import the host bridge from ./__sdk.mjs next to the page (synchronous connect). Backend and page bridge to the host separately without shared memory; both share the "shared API" below. The SDK also ships helpers: PluginError (error with a machine-readable code), waitForTask (polls a task to completion, 30 s default timeout, 150 ms interval; cancel and timeout never replay the task) and readDocument (wraps chunked export with boundary checks, timeout and SHA-256 verification).
Invocation & task states
Every command and service method receives an invocation:
| Field | Notes |
|---|---|
| signal | AbortSignal; long tasks should call signal.throwIfAborted() regularly for cooperative cancellation |
| invocationId | Unique id of this call |
| taskId | Host task id (command calls only) |
| progress(value, message?) | Report 0–1 progress and a message |
| source | Call origin |
| workspaceId / workspaceSession | Workspace identity; after a switch, old sessions are rejected (WORKSPACE_CHANGED) |
| windowId / editorId / documentId / revision / selection | Window, editor, document, revision and selection identity carried by menu triggers |
| sessionId / resource | Session and resource identity |
Tasks are host-owned: closing a page or AI conversation does not end the background task. States: waiting, running, cancelling, completed, failed, cancelled, interrupted, uncertain. Cancel, exit and timeout can leave uncertain external results (the other side may have executed); operations with side effects are never retried automatically. Commands have no single overall deadline — heartbeats only check event-loop responsiveness; a cancel timeout ends other tasks in the same instance.
Core types
interface DocumentSnapshot extends DocumentTarget {
content: string
format: 'markdown' | 'tiptap'
formatVersion?: 1
revision: string
draftHash: string
dirty: boolean
}
interface DocumentExportChunk {
exportId: string; format: 'markdown'; formatVersion: 1
chunk: string; offset: number; nextOffset: number; totalBytes: number
hash: string; revision: string; draftHash: string; dirty: boolean
}
interface DocumentChange extends DocumentTarget {
operationId: string
revision: string
draftHash: string
content: string
}
interface Operation {
operationId: string
state: 'pending' | 'completed' | 'failed' | 'uncertain'
result?: Json
error?: string
}
interface Task {
id: string; pluginId: string; version: string; generation: string; command: string
context: InvocationContext
state: 'waiting' | 'running' | 'cancelling' | 'completed' | 'failed'
| 'cancelled' | 'interrupted' | 'uncertain'
progress: number; hasResult: boolean; result?: Json; error?: string; errorCode?: string
}
interface ViewOptions {
location?: 'tab' | 'panel' | 'window'
context?: InvocationContext
state?: Json
instanceId?: string
}
interface ViewSession {
pluginId: string; viewId: string; instanceId: string; title: string; location: string
context: InvocationContext
state?: Json; dirty: boolean; connected: boolean
theme?: Record<string, string>
colorScheme: 'light' | 'dark'
uiReady: boolean
timings?: Record<string, number>
}
DocumentTarget is { workspaceId, workspaceSession, documentId, editorId, windowId? }; DocumentNavigationTarget (revision 3) is { workspaceId, workspaceSession, documentId }; ResourceRequest is { workspaceId, workspaceSession, path?, query?, offset?, limit?, content?, expectedHash?, operationId? }; Json is null, boolean, number, string, arrays or plain objects, recursively.
Error codes
| Code | Meaning |
|---|---|
| API_MISMATCH | Manifest apiVersion differs from the host |
| NODE_MISMATCH | Node/npm versions do not satisfy the requirement |
| BACKPRESSURE | Concurrency limit exceeded |
| STALE_GENERATION | Response from a stale generation |
| WORKSPACE_CHANGED | The workspace has switched |
| DRAFT_CONFLICT | Document snapshot stale or draft conflict |
| RESOURCE_CHANGED | Resource changed while being read |
| MESSAGE_TOO_LARGE | Response exceeds the control-frame limit |
| DIRTY_VIEW | Page has unsaved changes (e.g. refusing close) |
| SAVE_TIMEOUT | Save confirmation timed out |
| OPERATION_CONFLICT | Operation conflict (e.g. same operationId, different arguments) |
| NAVIGATION_CANCELLED / NAVIGATION_TIMEOUT | Document navigation cancelled / timed out |
PluginError.code is machine-readable; throw stable string codes of your own so external AI and diagnostics can locate failures.
Limits & quotas
| Item | Cap |
|---|---|
| Plugin background processes | 16 |
| Plugin pages | 32 |
| Unfinished command tasks | 128 |
| Install / development prep tasks | 8, scripts serialized and cancellable |
| Page restore state | 64 KiB |
| Control frames | 1 MiB |
| Single command result | under 1 MiB |
| Document export snapshots | 4 per plugin, 64 MiB per host, 2-minute expiry |
| Document export chunks | 96 KiB per chunk, 32 MiB total |
| Resource writes | 700 KiB per call |
| Text reads | 512 KiB per call, 16 MiB total |
| Image reads | 384 KiB per chunk, 28 MiB total, 100 per page |
| Service calls | 20 seconds, depth 8 |
| Plugin logs | 500 entries / 256 KiB per plugin |
| V8 heap | 256 MiB default |
| Process-tree memory / total CPU | 512 MiB / 25% |
Windows enforces quotas with a Job Object; macOS/Linux sample once per second and only stop after CPU exceeds the threshold 10 consecutive times — the sampling threshold is not a hard memory cap on every platform. A crashed background restarts with 2 s / 4 s backoff at most twice, re-activating only — commands, events and external operations are not replayed; the consecutive-failure counter survives app restarts and needs an explicit enable or restart to reset. Build pages for ES2022, Chromium 109 / Safari 16.4 or equivalent WebKit; final platform support follows the host's native UI acceptance.
Where to look next
- Manifest fields and contribution points: SDK Manifest Schema;
- Backend context, documents and resources, services and schedules: SDK Backend API;
- Page bridge, restore state, save contract and document navigation: SDK Page API.