Skip to main content

The engine

State ownership, lifecycle, reads, commands, and subscriptions.

The engine is the board source of truth. It owns document state, runtime session state, commands, validation, events, and installed plugin slices.

Create it once with createBoardEngine(). Read immutable runtime state with getState() and focused methods such as getSelection(). Observe reactive channels such as $nodes, or subscribe to semantic events.

Change state through commands. Directly mutating a returned node record does not update the engine and bypasses its invariants.

Lifecycle

Plugins install during construction. Duplicate plugin names fail before installation. destroy() is idempotent but terminal: it clears listeners, guards, plugin cleanup, and reactive resources. Later commands throw BoardDestroyedError.

Listener, subscriber, and finalized commit-effect failures occur after commit. They are isolated and reported through onUnhandledError; they cannot roll committed state back. Inspect context.source to distinguish event-listener, subscriber, and commit-effect failures.

Use the root package API in applications. The exported /internal subpath is an unsupported ABI for first-party packages.