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