Events and subscriptions

React to state changes with the event system and subscribables.

Events tell you what happened. Subscribables tell you what state looks like now. Use events to react to discrete actions, use subscribables to keep your UI in sync.

Live event stream

No events yet.

Events

const unsub = engine.on('node:created', (node) => {
  console.log('Created', node.id)
})

// Later...
unsub()

Subscribables

Six subscribables give you reactive access to engine state. Each fires independently — a camera change does not trigger a $nodes notification:

engine.$nodes.subscribe((nodes) => {
  console.log('Node count:', nodes.size)
})

Fires when any node is created, updated, moved, resized, or deleted.

engine.$camera.subscribe((camera) => {
  console.log(`Zoom: ${camera.z.toFixed(2)}`)
})

Fires on every pan and zoom change. High-frequency during interaction.

engine.$selection.subscribe((ids) => {
  console.log('Selected:', ids.size)
})

Fires when the selection set changes.

engine.$grid.subscribe((grid) => {
  console.log('Grid size:', grid.size)
})

Fires when snapping or grid settings change.

engine.$interaction.subscribe((state) => {
  console.log('Mode:', state.mode)
})

Fires when the interaction state machine transitions.

engine.$snapGuides.subscribe((guides) => {
  console.log('Active guides:', guides.length)
})

Fires when snap alignment guides appear or disappear.

In Vue, prefer the composables (useBoardCamera(), useBoardNodes(), useBoardSelection()) over raw subscribables. They handle reactivity automatically.

Inside engine.batch(), entity events and subscribable notifications publish only after the outer batch commits. Command lifecycle events describe the outer batch boundary. A blocked command and a validation failure remain observable failure telemetry.

Error taxonomy

BoardInputError: malformed or invalid boundary input.
BoardNotFoundError: requested entity does not exist.
BoardConflictError: an ID, plugin name, or other unique identity conflicts.
CommandBlockedError: a command guard rejected the operation.
BoardDestroyedError: a command targeted a destroyed engine.

Listener, subscriber, and finalized commit-effect errors are reported through onUnhandledError after commit. They do not reverse committed state.

Events and subscriptions

Events

Event catalog

Lifecycle

Node events

Selection and interaction

Camera

Guarded commands

Feature events

Subscribables

Error taxonomy