Skip to content

Free open-source image editor for the browser

Serve the WebMCP origin trial, batch commands, and explain failed image requests (#59)

Rodrigo Belfiore52c281548370
diff --git a/API.md b/API.md
index 6b80e0e..9672793 100644
--- a/API.md
+++ b/API.md
@@ -21,7 +21,7 @@ Export returns a `File`. It does not start a download.
## Loading
-These methods accept browser `File` objects and return `Promise<void>`. Await them before editing.
+These methods return promises; await them before editing. All but `loadUrl`, which takes a URL, accept browser `File` objects.
| Method | Behavior |
| --- | --- |
@@ -34,7 +34,7 @@ These methods accept browser `File` objects and return `Promise<void>`. Await th
| `loadUrl(url)` | Fetches an image and loads it. A URL on another origin must allow CORS; the response's content type identifies an image whose URL has no extension. |
| `importXmp(file)` | Applies supported Camera Raw adjustments as one undoable edit. |
-Loading calls are queued. XMP import is skipped if no document is ready; an invalid XMP import can reject without blocking later loads. Image and scene failures do not reject the loading promise. Without a document open, a failure leaves the workspace in its error state; with one, that document stays open and keeps its history. Either way `getState().failure` names the file and the error, and settings loaded in the same batch are skipped. Check `getState().documentId` or `failure` to confirm success. Loading completion does not guarantee the preview has rendered.
+File loads are queued; `loadUrl` starts at once, and when two opens overlap the later one wins. XMP import is skipped if no document is ready; an invalid XMP import can reject without blocking later loads. Image and scene failures do not reject the loading promise. Without a document open, a failure leaves the workspace in its error state; with one, that document stays open and keeps its history. Either way `getState().failure` names the file and the error, and settings loaded in the same batch are skipped. Check `getState().documentId` or `failure` to confirm success. Loading completion does not guarantee the preview has rendered.
## Editing
@@ -205,4 +205,6 @@ In browsers with [WebMCP](https://webmachinelearning.github.io/webmcp/), OpenLig
A read-only `get-state` tool returns the file, source size, frame, layers, comparison, and history, counting brush strokes and healing patches rather than listing them.
-WebMCP passes only JSON, so no tool takes or returns a file. `open-image` takes an http(s) `url` instead and opens it like `loadUrl`, in place of the open photo; it returns the new state like `get-state`, or why the image could not open. An agent opens a local file, such as an image attached to its chat, by serving it over HTTP with CORS and passing its URL. From a public origin such as openlight.app, Chrome's [Local Network Access](https://developer.chrome.com/blog/local-network-access) asks the user before the page reaches a local address; an automated browser can grant the `local-network-access` permission instead.
+WebMCP passes only JSON, so no tool takes or returns a file. `open-image` takes an http(s) `url` instead and opens it like `loadUrl`, in place of the open photo; it returns the new state like `get-state`, or why the image could not open. An agent opens a local file, such as an image attached to its chat, by serving it over HTTP with CORS and passing its URL. From a public origin such as openlight.app, Chrome's [Local Network Access](https://developer.chrome.com/blog/local-network-access) asks the user before the page reaches a local address; an automated browser can grant the `local-network-access` permission instead. When the request itself fails, the error names these causes, since the browser does not say which one it was.
+
+`run-commands` takes `commands`, a list of objects shaped like `run`'s, and runs them in order in one call, so an agent can apply an edit of several steps without a round trip for each. Each command is its own undo step. It returns each command's result; at the first error it stops, names the failing command, and keeps the ones before it.
diff --git a/index.html b/index.html
index ecc4135..9d93617 100644
--- a/index.html
+++ b/index.html
@@ -5,6 +5,8 @@
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="color-scheme" content="dark" />
<meta name="theme-color" content="#171717" />
+ <!-- WebMCP origin trial for openlight.app and its subdomains, until 2026-11-17. -->
+ <meta http-equiv="origin-trial" content="Ag2MmOhk9WrUwkj/P+C+qWF+RFZYjzI3i6mcf09yy2jIgONZstFdmMSV1dw3a57ho/GdNTKkYztMV8QzPeUgVwUAAABgeyJvcmlnaW4iOiJodHRwczovL29wZW5saWdodC5hcHA6NDQzIiwiZmVhdHVyZSI6IldlYk1DUCIsImV4cGlyeSI6MTc5NDg3MzYwMCwiaXNTdWJkb21haW4iOnRydWV9" />
<link rel="icon" href="/logo.svg" type="image/svg+xml" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
<link rel="canonical" href="https://openlight.app/" />
diff --git a/public/llms.txt b/public/llms.txt
index b554dbf..5dd6b2a 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -11,7 +11,7 @@ Open https://openlight.app in a WebGPU-capable browser (recent Chrome, Edge, Saf
```js
const editor = window.openlight;
-await editor.loadImage(file); // a File; loadUrl(url) accepts a same-origin URL
+await editor.loadImage(file); // a File; loadUrl(url) fetches a same-origin or CORS URL
editor.setAdjustments({ exposure: 0.5, contrast: 10, highlights: -30, shadows: 20, vibrance: 15 });
editor.setToneCurve([{ x: 0, y: 0 }, { x: 0.25, y: 0.2 }, { x: 0.75, y: 0.8 }, { x: 1, y: 1 }]);
editor.addLayer("mask"); // linear gradient mask; also "details", "exposure", "color-mixer", "vignette"
@@ -23,6 +23,15 @@ editor.undo(); editor.redo();
Adjustments use UI units: exposure in stops, other sliders in -100..100. RAW files expose `setWhiteBalance({ temperature, tint })`. Camera Raw XMP files import through `importXmp(file)`.
+## Using WebMCP
+
+In browsers with [WebMCP](https://webmachinelearning.github.io/webmcp/), such as Chrome 149 or later and ChatGPT's browser, the page registers tools on `document.modelContext`, so an agent can edit without scripting the page:
+
+- `get-state` describes the open photo: size, frame, layers, and history.
+- `open-image` opens an image from an http(s) URL the page can fetch; another origin must allow CORS. To open a local file, such as one attached to a chat, serve it over HTTP with CORS and pass its URL.
+- One tool per editing command, such as `set-adjustments`, `add-mask`, `set-color-mixer`, `set-crop`, `undo`, and `set-preview`.
+- `run-commands` runs several commands in one call.
+
## Reference
- [Control API](https://github.com/roprgm/openlight/blob/main/API.md): every command, its arguments, and the state shape.
diff --git a/src/app/loaders/image.ts b/src/app/loaders/image.ts
index b579b69..a865ca5 100644
--- a/src/app/loaders/image.ts
+++ b/src/app/loaders/image.ts
@@ -35,7 +35,12 @@ export function createImageLoader(gpu: Gpu, workspace: Workspace) {
pathname.slice(pathname.lastIndexOf("/") + 1),
);
return workspace.open(name, async () => {
- const response = await fetch(url);
+ // The browser hides why a request failed, so name the usual causes.
+ const response = await fetch(url).catch(() => {
+ throw new Error(
+ "The request failed. Another origin must allow CORS, and a local address needs the browser's permission.",
+ );
+ });
if (!response.ok) {
throw new Error(`${response.status} ${response.statusText}`);
}
diff --git a/src/app/webmcp.ts b/src/app/webmcp.ts
index e238098..1b07549 100644
--- a/src/app/webmcp.ts
+++ b/src/app/webmcp.ts
@@ -1,7 +1,7 @@
import { z } from "zod/mini";
import type { EditorDocument } from "@/core/document";
import { parse } from "@/lib/parse";
-import { commands } from "./commands";
+import { commands, runCommand } from "./commands";
import type { createControls } from "./controls";
import type { Workspace } from "./workspace";
@@ -81,8 +81,11 @@ function describe(workspace: Workspace, controls: Controls) {
}
const openImage = z.strictObject({ url: z.url({ protocol: /^https?$/ }) });
+const batch = z.strictObject({
+ commands: z.array(z.looseObject({ type: z.string() })).check(z.minLength(1)),
+});
-/** Registers `get-state`, `open-image`, and every command as WebMCP tools for browser agents until `signal` aborts. */
+/** Registers `get-state`, `open-image`, every command, and `run-commands` as WebMCP tools for browser agents until `signal` aborts. */
export function registerTools(
workspace: Workspace,
controls: Controls,
@@ -124,6 +127,23 @@ export function registerTools(
return result.layerId ? result : "Done.";
}),
),
+ defineTool(
+ "run-commands",
+ "Runs several commands in order in one call. Each command is an object with the name of another tool as its type, such as set-adjustments or add-mask, and that tool's fields. Each is its own undo step. Returns each command's result; at the first error it stops and says which command failed, keeping the ones before it.",
+ batch,
+ (input) => {
+ const { commands: list } = parse(batch, input, "Invalid run-commands");
+ return list.map((command, index) => {
+ try {
+ return runCommand(workspace, command);
+ } catch (error) {
+ throw Error(
+ `Command ${index + 1} of ${list.length} failed, after the ones before it ran: ${String(error)}`,
+ );
+ }
+ });
+ },
+ ),
];
for (const tool of tools) {
void context.registerTool(tool, { signal });
diff --git a/tests/webmcp.e2e.ts b/tests/webmcp.e2e.ts
index 8d1037b..7057a8b 100644
--- a/tests/webmcp.e2e.ts
+++ b/tests/webmcp.e2e.ts
@@ -80,4 +80,22 @@ test("a browser agent opens, edits, masks, crops, undoes, and resets through Web
expect(await readImage(page)).toEqual(gray);
await callTool(page, "undo");
expect(await readEnds()).toEqual(masked);
+
+ // A batch runs in order and stops at its first invalid command, keeping the ones before it.
+ const { undoCount } = (await state()).history;
+ expect(
+ await callTool(page, "run-commands", {
+ commands: [
+ { type: "set-adjustments", exposure: -1 },
+ { type: "set-vignette", intensity: 40 },
+ { type: "set-adjustments", exposure: 9 },
+ ],
+ }),
+ ).toMatch(/^Error: Command 3 of 3 failed/);
+ const batched = await state();
+ expect(batched.history.undoCount).toBe(undoCount + 2);
+ expect(batched.layers[0].adjustments.exposure).toBe(-1);
+ expect(batched.layers).toContainEqual(
+ expect.objectContaining({ kind: "vignette" }),
+ );
});