Document engine events

The engine reports what it does through document engine events. Subscribe with engine.on(name, handler). It returns a function that unsubscribes. Payloads are fully typed through DocumentEngineEvents.

const unsubscribe = engine.on("save:status", ({ status }) => {
  statusLabel.textContent = status;
});
 
unsubscribe();

In React, useDocumentEvent(engine, name, handler) subscribes with the latest handler.

All document engine events

Event	Payload	When
`load:start`	`{ documentId }`	A load begins
`document:change`	`{ documentId }`	Another document is now open
`load:success`	`{ document, warnings, migratedFrom }`	A load finished
`load:error`	`{ error }`	A load failed. The canvas is unchanged
`assets:warning`	`{ warnings }`	Images or fonts need attention
`save:start`	`{ document }`	A save begins
`save:success`	`{ document }`	A save finished
`save:error`	`{ error }`	A save failed after all retries
`save:retry`	`{ attempt, delay, error }`	A failed save will be retried
`save:status`	`SaveState`	The save status changed
`history:change`	`{ canUndo, canRedo, undoLabel, redoLabel }`	Undo or redo became available or changed
`history:error`	`{ error }`	Undo or redo could not rebuild an object
`recovery:checkpoint`	`{ documentId, savedAt }`	A recovery copy was written
`recovery:restored`	`{ document }`	A recovery copy was restored
`recovery:error`	`{ error }`	A recovery copy could not be written
`export:success`	`{ format, width, height, warnings }`	An export finished
`export:error`	`{ error }`	An export failed
`version:created`	`VersionSummary`	A version was kept
`version:restored`	`{ version, document }`	A version was restored
`version:error`	`{ error }`	An automatic version failed

Every error is a DocumentEngineError with a stable code. See error codes.

The ones most apps need

save:status drives the save indicator.
history:change drives the undo and redo buttons.
load:error and save:error drive error messages.

If you want every value at once, createDocumentStateStore combines these document engine events into one snapshot. See plain JavaScript.