Events

The editor tells your page what happens in it. Listen with on when you open it, so nothing is missed while it loads, or with editor.on() afterwards.

const editor = await createEditor({
  // …
  on: {
    'design:saved': ({ designId, revision }) => saveToMyRecord(designId),
    error: ({ code, message }) => reportToMyLogs(code, message),
  },
});

const stop = editor.on('selection:changed', ({ blockId, type }) => showHelpFor(type));
stop(); // stops listening

In React, every event is a prop: onReady, onDesignLoaded, onDesignUpdated, onDesignSaved, onSelectionChanged, onImageUploaded, onConfigAdjusted, onThemeChanged, onError.

Events are notifications: nothing waits for your listener, and a listener that throws does not affect the editor. Payloads may gain fields within 1.x; ignore fields you do not know.

The order of a session

design:loaded   { designId: '01J9ZQ…', designVersion: 3 }
ready           { release: '1.0.0', protocol: 1, designVersion: 3 }   ← createEditor resolves here
selection:changed { blockId: 'hdg_k2x4q7m1', type: 'heading' }
design:updated  { design: {…}, revision: 1, change: { kind: 'edit', blockId: 'hdg_k2x4q7m1' } }
design:saved    { designId: '01J9ZQ…', revision: 2 }
…

Every event

ready

The editor is on screen and answers calls. createEditor resolves at the same moment.

Field
release	The editor release running, e.g. 1.0.0
protocol	The protocol version the page and the editor agreed on
designVersion	The newest design format this editor reads

design:loaded

A design was opened, new or existing.

Field
designId	Its id
designVersion	The format it was stored in
upgradedFrom	Present when it was upgraded from an older format as it opened (it is saved in the new one; nothing is lost)
hasNewerBlocks	true when it holds blocks from a newer editor release, which are kept exactly as they are

design:updated

The design changed. A burst of edits is one event, so you can react to it without slowing typing down.

Field
design	The whole design document, as it is on screen (what you may rely on)
revision	The saved revision the change is based on
change.kind	edit, undo, redo, restore (a restore point was put back) or assistant (the AI changed it)
change.blockId	The block that changed, when one did

design:saved

The design was saved. Lettrove saves as your user works, so this comes shortly after edits.

Field
designId	Keep this with your own record
revision	Goes up by one with each save

selection:changed

The selected block changed.

Field
blockId	The block, or null when nothing is selected
type	heading, image, button… or null

image:uploaded

Your user uploaded an image and it is ready to use.

Field
url	Where it is served from
width, height	Its size in pixels, when known
id	The stored image's id, when the store gave one

theme:changed

Your user switched light or dark from the editor's own switch.

Field
theme	What they picked: light, dark or auto
applied	What the editor shows now: light or dark

config:adjusted

An option you passed was dropped or changed: an invalid option with a live key, or something the project's plan does not include. See Options only narrow.

Field
option	The option's path, e.g. tools.disabled
reason	Why, in words

error

Something went wrong that you may want to show or log.

Field
code	A stable code from the error codes
message	What happened, in words. Messages may be reworded; codes never change meaning.
recoverable	true when the editor carries on by itself