Scene API

The engine.scene API manages scene creation, pages, layout, and serialization.

Creating a Scene

await engine.scene.create({ width: 1920, height: 1080 });

This creates a scene block, a first page, and sets up the renderer. History is cleared after creation so it isn't undoable.

Active Scene & Page

engine.scene.getScene();       // number | null
engine.scene.getCurrentPage(); // number | null
engine.scene.getPages();       // number[]
engine.scene.setActivePage(pageId);

Page Management

const pageId = engine.scene.addPage({ width: 1080, height: 1080 });
engine.scene.removePage(pageId); // throws if last page

Page Dimensions

engine.scene.setDefaultPageDimensions(1920, 1080);
engine.scene.getDefaultPageDimensions(); // { width, height }

Aspect Ratio Lock

engine.scene.setAspectRatioLock(true);
engine.scene.isAspectRatioLocked();

Page Layout

engine.scene.setPageLayout("Free"); // PageLayoutMode
engine.scene.getPageLayout();

Serialization

Save and restore the entire scene:

const json = engine.scene.saveToString();
await engine.scene.loadFromString(json);

saveToString() emits scene format version 2. Version 2 persists groups, SVG paths, gradient and image fills, text curves, rich run styles, and text background geometry. loadFromString() accepts versions 1 and 2; version 1 documents use feature defaults for fields that did not exist yet. Other versions throw an Unsupported scene version error.

Loading rebuilds the block hierarchy and renderer state, then clears history so the restored document starts with a clean undo stack.

Event API

Subscribe to block lifecycle events:

// Subscribe to specific blocks
const unsubscribeBlock = engine.event.subscribe([blockId], (events) => {
  for (const e of events) {
    console.log(e.type, e.block); // "created" | "updated" | "destroyed"
  }
});

// Subscribe to ALL block events
const unsubscribeAll = engine.event.subscribe([], (events) => {
  // ...
});

// Unsubscribe
unsubscribeBlock();
unsubscribeAll();

With a renderer attached, events are deduplicated and delivered at the end of each engine update cycle. A rendererless engine currently queues lifecycle events without automatically flushing them.