Commands

The editor’s handle, EmbedEditorHandle, runs the editor from code. Its commands do what the controls on screen do, its reads tell what the editor holds, and its events tell you what changed.

Group	What it does	Page
`history`	Undo, Redo and Reset, as the toolbar.	History and output
`output`	Save, or the file Save would make.	History and output
`editor`	Close the editor.	History and output
`menu`	Show a menu item, or tap its ring.	Menu and reads
`read`	What the editor holds now.	Menu and reads
`crop`	Crop, straighten, turn, mirror and zoom the photo, as Adjust.	Adjust commands
`size`	The size Save writes, as Resize.	Adjust commands
`view`	Compare with the original, recenter, and zoom and move Annotate’s view.	Adjust commands
`filter`	Choose a filter and its intensity.	Filter, frame and adjustments
`frame`	Choose a frame and its color.	Filter, frame and adjustments
`adjust`	Set the adjustments, as their rulers.	Filter, frame and adjustments
`auto`	Turn Auto on and off, and set its amount.	Filter, frame and adjustments
`palette`	Choose the set of colors every color row shows.	Filter, frame and adjustments
`obfuscate`	Draw, change, select and remove the areas that hide parts of the photo.	Obfuscate and marks
`marks`	Adjust, place, hide and show the watermark and the signature.	Obfuscate and marks
`annotate`	Add, change and remove annotations, and open Annotate.	Annotate
`run`, `commands()`	Any command by its name, and the list of them, for a model.	For AI
`ready`, `on`	The image on screen, and the events.	This page

Get the Handle

The same handle comes three ways: a ref on EmbedEditor, or what mountEditor and openEditor return. Both entries export the EmbedEditorHandle type.

import { useCallback, useRef } from 'react';
import { EmbedEditor } from '@embededitor/full/react';
import type { EmbedEditorHandle } from '@embededitor/full/react';

const PhotoEditor = ({ src }: { src: string }) => {
	const editor = useRef<EmbedEditorHandle>(null);

	const showFilters = useCallback(async () => {
		await editor.current?.menu.select({ item: 'FILTER' });
	}, []);

	return (
		<div style={{ height: 600 }}>
			<button onClick={showFilters}>Filters</button>
			<EmbedEditor
				ref={editor}
				src={src}
			/>
		</div>
	);
};

import { mountEditor } from '@embededitor/full/standalone';

const editInline = async (element: HTMLElement, src: string) => {
	const editor = mountEditor(element, { src });

	// waits for the image, then shows the filters
	await editor.menu.select({ item: 'FILTER' });

	return editor;
};

import { openEditor } from '@embededitor/full/react';

const editPhoto = async (file: File) => {
	const editor = openEditor({ src: file });

	await editor.menu.select({ item: 'FILTER' });

	return editor;
};

EmbedEditor forwards its ref, in React 18 and 19. The handle is made once and stays the same through every new set of props.
mountEditor returns the handle with update and destroy. See mountEditor().
openEditor returns the handle with close. See openEditor().

The examples on these pages call the handle editor.

How Every Command Behaves

It returns a Promise. It resolves once the editor rendered the result: the step is in the history and on screen. It resolves to null, or to what it made (output.save gives { dest, state }). A command that changes nothing, such as an undo with nothing to undo, still resolves.
It takes one object, or nothing: editor.menu.select({ item: 'FILTER' }). The same object is its input in run.
It waits its turn. Commands run one at a time, in the order you call them. You don’t need to await one before you call the next.
It waits for the image. ready resolves once the image is on screen, and commands start then. A command called before that waits for it, and doesn’t fail. A load that fails keeps it waiting until a new src, or a picked image, loads.
It never runs under the user’s hand. While the user holds a drag, a pinch or an arrow key on a control, while a Save is on its way, or while they type the words of an annotation or a mark, a command waits, then runs.
An edit is one undo step, as the same control on screen makes, and history.undo takes it back. A command that only changes what is shown, such as menu.select, makes no step.
Its values are the saved state’s. Coordinates are in the px of the size the editor works the image at (read.size()), adjustments run −100 to 100, rotation is in degrees, and filters and frames go by the ids the state writes. If you can read an EditState, you can write a command.
It acts from outside. A command runs the same code as the control on screen, with its motion and its undo step, but not as a hand: the tool’s name doesn’t show over the photo, and a ruler doesn’t go into its focus mode.

The undo below runs once the toggle is done, and takes it back:

queue.ts

editor.menu.toggle({ item: 'FILTER' });
await editor.history.undo();

When the Editor Leaves

Once the editor leaves the page, every command waiting and every one you call after rejects with NOT_AVAILABLE. A command running as it leaves rejects too, though what it already changed stays, and it changes nothing more, even once the editor is back. ready rejects the same way if the image wasn’t on screen yet, and stays rejected: an editor shown again takes commands, but its ready doesn’t come back.

EmbedEditor unmounted. Hidden by an <Activity> instead, its commands work again once it is shown.
mountEditor’s destroy, or another mountEditor on the same element: that handle takes no more commands.
openEditor’s modal closed, however it closes (close, its Close button, Escape, a Save that went through): that handle takes no more commands.

Before the editor first mounts, a command waits for it.

What Isn’t a Command

Copy, Share and the eyedropper. The browser allows the clipboard, the share sheet and the eyedropper only inside a gesture of the user’s own, so they stay buttons. For the file, call output.exportFile() and copy or share it yourself.

Errors

A command rejects with an EmbedEditorError, whose code says what to fix. A rejected command changes nothing.

`code`	When
`INVALID_COMMAND`, off the schema	The input is off the command’s schema, or `run` names a command the handle doesn’t have. `props` names each invalid path (`input.item`, or `command`), and `cause` holds the schema’s own error (none for an unknown name). It rejects at once, without waiting its turn; on a handle whose editor was destroyed or left, `NOT_AVAILABLE` comes first.
`INVALID_COMMAND`, can’t be taken here	The input fits the schema, but not where the editor stands: an area no drag would draw, a key the annotation’s kind doesn’t take, a size off the watermark’s layout. It rejects on the command’s turn, once the image is on screen, with `props` naming the paths and no `cause`.
`NOT_AVAILABLE`	The tool is off by a prop (`enableFilter: false`) or isn’t in the edition, there is no close (`editor.close` with no `onClose`), or the editor was destroyed, closed or left the page. Each page lists its own cases.
`NOT_FOUND`	No area at that index, no annotation with that id.
`EXPORT_FAILED`, `MARK_FAILED`	`output.save`, `output.exportFile` or `read.screenshot` couldn’t make the file, as Save.

errors.ts

import { EmbedEditorError } from '@embededitor/full/react';

try {
	await editor.run({ command: 'menu.select', input: { item: 'CURVES' } });
} catch (err) {
	if (err instanceof EmbedEditorError && err.code === 'INVALID_COMMAND') {
		console.error('invalid:', err.props.join(', '));
	}
}

Events

on: <Name extends keyof EmbedEditorEvents>(name: Name, handler: (payload: EmbedEditorEvents[Name]) => void) => () => void;

on calls handler with what each event says, until you call the function it returns.

Event	Payload	When
`load`	`{ file, size }`	The image is on screen, once per open, at the moment `onLoad` is called, with the same values.
`change`	`{ state }`	A step of the history landed: an edit (a command’s, or the user’s once they let go of a drag), an undo, a redo, a reset; or the ratio the host locks landing on the photo (no step to undo then). Never a gesture’s preview, nor a command that changed nothing. `state` is an `EditState`.
`item`	`{ item, tool }`	The menu item or the tool on the stage changed. `tool` is `'ANNOTATE'` while Annotate is open.
`select`	`EmbedEditorSelection`	The selection changed: an Obfuscate area, by its index in `obfuscation`; in Annotate, an annotation (`{ kind: 'PIECE', id }`), an arrow added to a text (`{ kind: 'ARROW', id, index }`) or the Numbers’ list (`{ kind: 'LIST' }`); or `null`.
`save`	`{ dest, state }`	A Save went through, its button’s or `output.save`’s: what `onProcess` gets.

A handler’s own error is logged with console.error, never the editor’s. After destroy, or once the modal closed, no event fires. Keep a draft of every step, to reopen it later with the state prop:

draft.ts

const stop = editor.on('change', ({ state }) => {
	localStorage.setItem('draft', JSON.stringify(state));
});

Call stop() when you no longer need it.

Editions

Every edition has the same EmbedEditorHandle, as it has the same props. The Free and the Lite have Adjust alone:

A command of a tool only the Full has is still on the handle. It rejects with NOT_AVAILABLE, and a read of it answers null. commands() leaves it out, so a model never sees it.
menu.select and menu.toggle reject with NOT_AVAILABLE for an item the edition doesn’t have, as for one a prop turned off.

The Full has every command.

History and Output

Undo, Redo, Reset, Save, the file and Close.

Menu and Reads

The menu’s items and what the editor holds.

Adjust Commands

The crop, the size and the view.

Filter, Frame and Adjustments

The filter, the frame, the adjustments, Auto and the palette.

Obfuscate and Marks

The areas that hide parts of the photo, the watermark and the signature.

Annotate

The annotations, their style, the action bar’s verbs and the Numbers’ list.

For AI

run, commands() and a model’s tools.

EmbedEditorError

The error and its codes.

Overview

Entry Points

Reference

Commands

Get the Handle

How Every Command Behaves

When the Editor Leaves

What Isn’t a Command

Errors

Events

Editions

History and Output

Menu and Reads

Adjust Commands

Filter, Frame and Adjustments

Obfuscate and Marks

Annotate

For AI

EmbedEditorError

​Get the Handle

​How Every Command Behaves

​When the Editor Leaves

​What Isn’t a Command

​Errors

​Events

​Editions

History and Output

Menu and Reads

Adjust Commands

Filter, Frame and Adjustments

Obfuscate and Marks

Annotate

For AI

EmbedEditorError

Get the Handle

How Every Command Behaves

When the Editor Leaves

What Isn’t a Command

Errors

Events

Editions