Apply a revision-checked edit
Wait until the workspace has opened a document. inspect() returns a document summary and its current revision. Pass expectedRevision to reject an edit if the document changed after inspection. Omit frameId and layerId to use the active targets, or supply explicit IDs from your own document workflow.
const api = window.pixelwall;
const before = api.inspect();
await api.apply({
expectedRevision: before.revision,
label: "Draw badge",
commands: [{
type: "draw.ellipse", x: 2, y: 2, width: 12, height: 12,
color: "#ffb34bff", filled: true
}]
});
await api.save();
const preview = await api.preview({ scale: 4 });
// preview contains width, height, and a PNG dataUrl.
await api.export({ format: "png", scale: 4 });Available methods
- version: current browser API version, presently 1.
- inspect(): current document summary and revision. commands(): command descriptions and field reference.
- apply({commands, expectedRevision?, label?}): apply a batch of 1–2000 commands, limited to 16 MiB of command JSON, as one undoable change.
- runLua({source, params?, timeoutMs?, expectedRevision?}): run a bounded Lua script with the current document, selection and colors; successful changes are one undoable transaction.
- colorProfile(options): inspect, assign or convert a document color profile through the editor’s color manager.
- newDocument(options): save the previous document and activate a new one.
- preview({frameId?, scale?}): return an in-memory PNG preview at up to 8× scale.
- save(): await a durable local save. It does not download a backup or create cloud storage.
- export(options): invoke the editor’s export flow. Individual PNG, BMP and TGA frames and editable projects are free; gif, sheet, and zip require Pro.
- undo() and redo(): use the active document’s editing history.
Behavior and limits
An invalid command or mismatched expectedRevision rejects the batch. Catch errors and show them to the user; do not assume that an export or save completed because a call began. The UI’s memory, document, storage, and format limits still apply.
The API is local to the page. It is not an unauthenticated network editing server and does not upload projects. A user-connected external tool may call it, but PixelWall does not embed AI. The CLI provides the corresponding local-file workflow.