background

Lite API 3.4; requires manifest.background. bluetooth: true requests all GATT services on the user-selected device; an optional services whitelist narrows access. Omitted operation fields allow all supported operations; explicit fields deny omitted operations. network: true requests public HTTPS/WSS; networkOrigins optionally restricts it and takes precedence. start requests host approval and starts on demand. Initial approval is cancellable, has a five-minute deadline, and does not consume the command execution budget. Closing the initiating caller cancels pending startup; after readiness, closing a View does not stop the background. stop releases the run and connections. request uses matching requestId envelopes and a 30-second reply timeout after startup. Messages must be JSON-compatible. onMessage belongs to the current run and caller; subscribe again after restarting. requestDevice has a five-minute deadline: cancellation preserves the run, confirmation replaces it with a fresh device grant. Network and BLE permissions are independent of browser permissions.

Usage guide: background. API index.

Signatures, parameters and return types are generated from the SDK. Optional members are not available in every host and context.

PluginBackground

Source

PluginBackground.isRunning

Supported hosts: Lite

Lite API 3.6. Returns true only for a ready, unrevoked run in the current window and Space. Does not start a background or prompt for permission.

isRunning(): Promise<boolean>;

Returns: Promise<boolean>.

PluginBackground.requestDevice

Supported hosts: Lite

Open the native BLE picker. Confirmation replaces the current run; cancellation leaves it running.

requestDevice(): Promise<{
    id: string;
    name?: string;
}>;

Returns: Promise<{ id: string; name?: string; }>.

PluginBackground.start

Supported hosts: Lite

Start the plugin background with host approval. Reuses an existing run.

start(): Promise<void>;

Returns: Promise<void>.

PluginBackground.stop

Supported hosts: Lite

Stop the current run and release its resources and grants.

stop(): Promise<void>;

Returns: Promise<void>.

PluginBackground.postMessage

Supported hosts: Lite

Send a raw JSON-compatible message; completion does not mean the background finished processing it.

postMessage(message: BackgroundMessage): Promise<void>;

Parameter	Type	Required
message	BackgroundMessage	Yes

Returns: Promise<void>.

PluginBackground.request

Supported hosts: Lite

Send a request envelope and wait for a response with the same requestId. Rejects on timeout.

request(message: BackgroundMessage): Promise<BackgroundMessage>;

Parameter	Type	Required
message	BackgroundMessage	Yes

Returns: Promise<BackgroundMessage>.

PluginBackground.onMessage

Supported hosts: Lite

Subscribe to raw messages from the current run. Dispose when the caller closes; resubscribe after restarting the background.

onMessage(listener: (message: BackgroundMessage) => void): Promise<Disposable>;

Parameter	Type	Required
listener	(message: BackgroundMessage) => void	Yes

Returns: Promise<Disposable>.

Related types: BackgroundMessage, Disposable.

BackgroundHost

Source

BackgroundHost.spaceId

Supported hosts: Lite

Lite API 3.6. Background modules access this host object through globalThis.ctx. Identifies the current Space, not a filesystem path.

readonly spaceId: string;

BackgroundHost.instanceId

Supported hosts: Lite

Unique to this run. Changes after stop/restart; remains stable when Views close.

readonly instanceId: string;

BackgroundHost.events

Supported hosts: Lite

Requires background.fileHistory: true and host approval. events.on(“file.opened”, listener) returns a disposable listener for successful file opens, with no initial snapshot or replay. Events contain metadata only and stop on revocation. See the background guide for counting rules.

readonly events: PluginEvents;

BackgroundHost.storage

Supported hosts: Lite

Requires storage.maxBytes. Uses the same plugin-private device-local binary store and quota as Views/actions. Shared across Spaces; use spaceId in keys when separation is needed. Concurrent read-modify-write operations are not transactions.

readonly storage?: PluginStorage;

Related types: PluginEvents, PluginStorage.