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, revision, and latestOperation. commands(): command descriptions and field reference.
- apply({commands, expectedRevision?, label?, wait?, requestKey?}): apply 1–2000 commands, limited to 16 MiB of JSON, as one undoable change. wait:false returns an operationId before processing; poll operation(id) for staged commandsProcessed, commandsTotal, revision, completion, or error. A requestKey makes an identical retry reuse the retained result in this editor session; a mismatched or expired key is rejected. The session retains up to 1,024 request keys and 64 operation results.
- 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.
- capturePreview(): retain an immutable baseline for a later visual comparison. The preview and comparison helpers can target frames, layers, crops, and contact-sheet layouts where supported by the current editor.
- validate({commands, expectedRevision?, timeoutMs?}): preflight a command batch without committing it. The timeout bounds validation work; it is not a runtime estimate for applying the batch.
- cancel(operationId): request cancellation of a running batch. Cancellation is checked between commands, and completed commands remain staged until the transaction commits or rolls back.
- save(): await a durable local save. It does not download a backup or create cloud storage.
- export(options): generate files and request browser downloads by default; pass download:false to generate retrievable files without clicking. The returned exportResult separates generated.files from download status, including per-file requests. exportResult() retrieves the latest handoff. Object URLs live until the next export, dismissal, or editor unmount; browser completion is unobservable.
- 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 and opt-in desktop MCP provide corresponding local workflows.
Long edits and file handoff
commandsProcessed counts staged commands. A completed operation has committed once; a failed operation leaves no partial edit. If a client stops waiting, inspect latestOperation before retrying. Save after completion to make the edit durable. The operation log is page-local and disappears on reload.
Use export({format:"project", download:false}) for a compact editable backup or format:"png" for a finished frame. Read each generated file URL inside the same page and confirm persistence in your host; a generated file is not proof of a completed download.