ima2-gen 1.1.8 → 1.1.10

package/README.md

@@ -1,5 +1,9 @@
 # ima2-gen
 
+<p align="center">
+  <img src="assets/logo.png" alt="ima2-gen logo" width="240">
+</p>
+
 [![npm version](https://img.shields.io/npm/v/ima2-gen)](https://www.npmjs.com/package/ima2-gen)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -10,7 +14,7 @@
 
 `ima2-gen` is a local image generation studio for people who want the ChatGPT/Codex image workflow in a small desktop-like web app.
 
-Run it with `npx`, sign in with Codex OAuth, type a prompt, and keep iterating with history, references, style sheets, and node branches. No OpenAI API key is required for image generation in the default path.
+Run it with `npx`, sign in with Codex OAuth, type a prompt, and keep iterating with history, references, node branches, multimode batches, and Canvas Mode cleanup. No OpenAI API key is required for the default path, but API-key generation is also supported when configured.
 
 ![ima2-gen classic generation screen with prompt composer, generated image, compact model label, and result metadata.](assets/screenshots/classic-generate-light.png)
 
@@ -47,20 +51,25 @@ persists, reboot and run the update before starting ima2 again.
 
 - **Classic mode**: generate, edit, reuse the current image, paste references, and continue from history.
 - **Node mode**: branch a good image into multiple directions without losing the original.
+- **Multimode batches**: launch several Classic outputs from one prompt, watch slot-by-slot progress, and continue from the best result.
+- **Canvas Mode**: zoom, pan, annotate, erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions.
 - **Local gallery**: keep generated assets on your machine with session-aware history.
 - **Reference images**: drag, drop, paste, and attach up to 5 references; large images are compressed before upload.
-- **Style sheets**: extract and reuse a visual direction across classic and node prompts.
+- **Prompt library imports**: import local prompt packs, GitHub folders, and curated GPT-image prompt hints into the built-in prompt library.
+- **Mobile shell**: use the app bar, compose sheet, and compact settings toggle on smaller screens.
 - **Observable jobs**: active and recent jobs are tracked with safe logs and request IDs.
 
-## OAuth Only For Image Generation
+## Provider Paths
 
-Image generation currently runs through the local Codex/ChatGPT OAuth path.
+Image generation can run through either the local Codex/ChatGPT OAuth path or a configured OpenAI API key.
 
-API keys may still be detected for auxiliary developer features such as billing checks or style-sheet extraction, but generation routes reject `provider: "api"` with `APIKEY_DISABLED`.
+- `provider: "oauth"` uses the local Codex OAuth proxy.
+- `provider: "api"` calls the OpenAI Responses API with the hosted `image_generation` tool.
+- API-key generation supports classic generate, edit, mask-guided edit, multimode, and node generation.
 
-If the settings page says **Configured but disabled**, that means an API key exists in env/config but image generation still uses OAuth.
+If no provider is specified, the app keeps the current OAuth/default behavior. API-key generation defaults to `gpt-5.4-mini`, `low` reasoning, and `1024x1024` unless the request passes validated model, reasoning, size, or web-search options.
 
-![Settings workspace showing OAuth active and API key configured but disabled.](assets/screenshots/settings-oauth-generation.png)
+![Settings workspace showing OAuth active and API key provider available.](assets/screenshots/settings-oauth-generation.png)
 
 ## Model Guidance
 
@@ -81,7 +90,10 @@ Use Classic when you want one strong result quickly.
 1. Write a prompt.
 2. Attach or paste references if needed.
 3. Pick model, quality, size, format, and moderation.
-4. Generate, copy, download, or continue from the result.
+4. Generate one image, or enable multimode to fan out several candidate slots from the same prompt.
+5. Copy, download, continue from the result, or send it into Canvas Mode.
+
+![Multimode sequence with four candidate slots generating from one prompt and active job history in the sidebar.](assets/screenshots/multimode-sequence.png)
 
 ### Node Mode
 
@@ -91,22 +103,36 @@ Use Node mode when you want to explore branches.
 
 Each node keeps its own prompt and result. Root nodes can attach local references; child nodes use the parent image as their source. Completed jobs are matched back to nodes by request ID, so reloads and graph version conflicts can recover finished results.
 
+### Canvas Mode
+
+Use Canvas Mode when a generated image is close but needs targeted cleanup before the next prompt.
+
+- Separate viewport panning from selection so you can move around a zoomed image without accidentally changing annotations.
+- Use annotation, eraser, multiselect, grouping, undo/redo, and sticky notes while keeping the original gallery image available.
+- Pick background-cleanup seeds, preview the mask, and save the cleanup as a canvas version.
+- Detect transparent images and show a checkerboard preview; export with preserved alpha or with a chosen matte color.
+- Saved canvas versions stay hidden from Gallery and HistoryStrip, but Canvas Mode can reuse them and attach a canvas version as the next reference.
+
+![Canvas Mode with zoom controls, annotation marks, a sticky note, and the canvas toolbar.](assets/screenshots/canvas-mode-cleanup.png)
+
+### Prompt Library And Imports
+
+The prompt library can now be filled from local files, GitHub folders, curated sources, and GPT-image hint packs. Imported prompts are indexed locally so search and ranking work without re-importing the same source every session.
+
+![Prompt import dialog for bringing prompts into the library, showing GitHub folder controls, curated sources, and searched prompt candidates before import.](assets/screenshots/prompt-import-dialog.png)
+
 ### Experimental Card News Mode
 
 Card News is still dev-only and experimental. It is hidden in the default
 published runtime unless explicitly enabled for development, and it should not
 be treated as a stable public feature yet.
 
-### Settings And Style Sheets
+### Settings
 
 The settings workspace keeps account, model, appearance, and language controls away from the generation sidebar.
 
 ![Settings workspace with account navigation and generation model controls.](assets/screenshots/settings-workspace.png)
 
-Style sheets let you capture a reusable visual direction.
-
-![Style sheet editor with medium, composition, mood, subject, palette, and negative fields.](assets/screenshots/style-sheet-editor.png)
-
 ## CLI Commands
 
 ### Server
@@ -122,27 +148,32 @@ Style sheets let you capture a reusable visual direction.
 
 ### Client
 
-These require a running `ima2 serve`.
+These require a running `ima2 serve`. The CLI covers every server route. The most common ones are below — the [full CLI reference](docs/CLI.md) lists everything (generation, history, sessions, prompt library, annotations, Card News, observability, config).
 
 | Command | Description |
 |---|---|
 | `ima2 gen <prompt>` | Generate from the CLI |
 | `ima2 edit <file> --prompt <text>` | Edit an existing image |
-| `ima2 ls` | List local history |
-| `ima2 show <name>` | Reveal a generated asset |
-| `ima2 ps` | List active jobs |
-| `ima2 cancel <requestId>` | Mark an in-flight job canceled |
+| `ima2 multimode <prompt>` | Multi-image SSE generation |
+| `ima2 ls [--session <id>] [--favorites]` | List recent history |
+| `ima2 show <name> [--metadata]` | Reveal a generated asset |
+| `ima2 prompt ls -q <search>` | Search the prompt library |
+| `ima2 inflight ls [--terminal]` | List active and recent jobs (alias of `ps`) |
+| `ima2 config set <key> <value>` | Write to `~/.ima2/config.json` |
 | `ima2 ping` | Health-check the running server |
 
-The server advertises its actual port at `~/.ima2/server.json`. If `3333` is busy, the backend can fall back to `3334+` and CLI commands follow the advertised URL. Override discovery with `--server <url>` or `IMA2_SERVER=http://localhost:3333`.
+The server advertises its actual port at `~/.ima2/server.json`. If `3333` is busy, the backend falls back to `3334+` and CLI commands follow the advertised URL. Override discovery with `--server <url>` or `IMA2_SERVER=http://localhost:3333`.
 
 ```bash
-ima2 gen "poster" --model gpt-5.4 --mode direct --moderation low
-ima2 edit input.png --prompt "make it rainy" --model gpt-5.4
-ima2 ps --terminal
-ima2 cancel <requestId>
+ima2 gen "poster" --model gpt-5.4 --reasoning-effort high
+ima2 edit input.png --prompt "make it rainy" --web-search
+ima2 multimode "two cats playing" -n 2
+ima2 inflight ls --terminal
+ima2 config set imageModels.reasoningEffort high
 ```
 
+Full reference: [docs/CLI.md](docs/CLI.md).
+
 ## Configuration
 
 Config priority:
@@ -164,7 +195,7 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_NO_OAUTH_PROXY` | — | Set `1` to disable the auto-started OAuth proxy |
 | `IMA2_LOG_LEVEL` | `warn` | Normal serve defaults to `warn`; dev mode defaults to `debug`; supports `debug`, `info`, `warn`, `error`, or `silent` |
 | `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | Recent terminal job retention for debug views |
-| `OPENAI_API_KEY` | — | API key for supported auxiliary paths, not image generation |
+| `OPENAI_API_KEY` | — | API key for the `provider: "api"` Responses API image path and auxiliary API-key features |
 
 ### Logging modes
 
@@ -178,6 +209,7 @@ The endpoint list moved to [docs/API.md](docs/API.md) so this README can stay fo
 
 Useful references:
 
+- [CLI Reference](docs/CLI.md)
 - [API Reference](docs/API.md)
 - [FAQ](docs/FAQ.md)
 - [Recover old images](docs/RECOVER_OLD_IMAGES.md)
@@ -196,8 +228,8 @@ Run `npx @openai/codex login`, confirm `ima2 status`, then restart `ima2 serve`.
 **`fetch failed` repeats on a proxy/VPN network**
 Check that the local OAuth proxy is reachable. On networks that require a proxy, enable your proxy client's TUN/TURN-style mode, then retry `npx openai-oauth --port 10531`. If it still fails, set `HTTP_PROXY` and `HTTPS_PROXY` in the same terminal that runs `ima2 serve` or `openai-oauth`.
 
-**Images fail with `APIKEY_DISABLED`**
-Use OAuth for generation. API-key image generation is intentionally disabled in this build.
+**Images fail with `API_KEY_REQUIRED`**
+Set `OPENAI_API_KEY` or configure an API key before using `provider: "api"`. The default OAuth path still works without an API key.
 
 **A large reference image fails**
 The app compresses large JPEG/PNG references before upload. If a file still fails, convert it to JPEG or PNG at a lower resolution and try again. HEIC/HEIF files are not supported by the browser path.
@@ -223,11 +255,12 @@ git clone https://github.com/lidge-jun/ima2-gen.git
 cd ima2-gen
 npm install
 npm run dev
+npm run typecheck
 npm test
 npm run build
 ```
 
-`npm run dev` builds the UI and starts `server.js` with `--watch` and verbose server diagnostics. Node mode is part of the packaged UI by default.
+`npm run dev` builds the UI and starts the TypeScript server entry with `--watch` and verbose server diagnostics. `npm run typecheck`, `npm run build:server`, and `npm run build:cli` verify the TypeScript migration and package emit path. Node mode and Canvas Mode are part of the packaged UI by default.
 
 ## License
 

package/bin/commands/annotate.js

@@ -0,0 +1,139 @@
+import { readFile } from "fs/promises";
+import { parseArgs } from "../lib/args.js";
+import { resolveServer, request } from "../lib/client.js";
+import { readStdin } from "../lib/files.js";
+import { out, die, color, json, exitCodeForError } from "../lib/output.js";
+import { getCliBrowserId } from "../lib/browser-id.js";
+const HELP = `
+  ima2 annotate <subcommand> <filename> [options]
+
+  Subcommands:
+    get <filename> [--json]
+    set <filename> --body <json|@file|->
+    rm  <filename> [--yes]
+`;
+const FLAGS = {
+    json: { type: "boolean" },
+    server: { type: "string" },
+    yes: { type: "boolean" },
+    body: { type: "string" },
+    help: { short: "h", type: "boolean" },
+};
+async function getServer(args) {
+    try {
+        return await resolveServer({ serverFlag: args.server });
+    }
+    catch (e) {
+        die(exitCodeForError(e), e.message);
+        throw e;
+    }
+}
+async function resolveBody(value) {
+    if (!value)
+        return null;
+    if (typeof value !== "string")
+        return null;
+    let text;
+    if (value === "-")
+        text = await readStdin();
+    else if (value.startsWith("@"))
+        text = await readFile(value.slice(1), "utf-8");
+    else
+        text = value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        die(2, "--body must be valid JSON");
+        throw 0;
+    }
+}
+async function readLine() {
+    return new Promise((resolve) => {
+        let buf = "";
+        process.stdin.setEncoding("utf-8");
+        const onData = (chunk) => {
+            buf += chunk;
+            const nl = buf.indexOf("\n");
+            if (nl !== -1) {
+                process.stdin.removeListener("data", onData);
+                process.stdin.pause();
+                resolve(buf.slice(0, nl));
+            }
+        };
+        process.stdin.resume();
+        process.stdin.on("data", onData);
+    });
+}
+async function getSub(argv) {
+    const args = parseArgs(argv, { flags: FLAGS });
+    const filename = args.positional[0];
+    if (!filename)
+        die(2, "filename required");
+    const server = await getServer(args);
+    const browserId = getCliBrowserId();
+    const resp = await request(server.base, `/api/annotations/${encodeURIComponent(filename)}`, {
+        headers: { "X-Ima2-Browser-Id": browserId },
+    }).catch((e) => { const err = e; die(exitCodeForError(e), `${err.message}${err.code ? ` (${err.code})` : ""}`); });
+    json(resp);
+}
+async function setSub(argv) {
+    const args = parseArgs(argv, { flags: FLAGS });
+    const filename = args.positional[0];
+    if (!filename)
+        die(2, "filename required");
+    if (!args.body)
+        die(2, "--body <json|@file|-> required");
+    const body = await resolveBody(args.body);
+    const server = await getServer(args);
+    const browserId = getCliBrowserId();
+    const resp = await request(server.base, `/api/annotations/${encodeURIComponent(filename)}`, {
+        method: "PUT",
+        body,
+        headers: { "X-Ima2-Browser-Id": browserId },
+    }).catch((e) => { const err = e; die(exitCodeForError(e), `${err.message}${err.code ? ` (${err.code})` : ""}`); });
+    if (args.json) {
+        json(resp);
+        return;
+    }
+    out(color.green("✓ annotation saved"));
+}
+async function rmSub(argv) {
+    const args = parseArgs(argv, { flags: FLAGS });
+    const filename = args.positional[0];
+    if (!filename)
+        die(2, "filename required");
+    if (!args.yes && !process.stdin.isTTY)
+        die(2, "destructive: pass --yes for non-TTY");
+    if (!args.yes) {
+        process.stdout.write(`Delete annotation for ${filename}? [y/N] `);
+        const ans = await readLine();
+        if (!/^y(es)?$/i.test(ans.trim())) {
+            out("(canceled)");
+            return;
+        }
+    }
+    const server = await getServer(args);
+    const browserId = getCliBrowserId();
+    await request(server.base, `/api/annotations/${encodeURIComponent(filename)}`, {
+        method: "DELETE",
+        headers: { "X-Ima2-Browser-Id": browserId },
+    }).catch((e) => { const err = e; die(exitCodeForError(e), `${err.message}${err.code ? ` (${err.code})` : ""}`); });
+    out(color.green("✓ deleted"));
+}
+const SUB = {
+    get: getSub,
+    set: setSub,
+    rm: rmSub,
+};
+export default async function annotateCmd(argv) {
+    const sub = argv[0];
+    if (!sub || sub === "--help" || sub === "-h") {
+        out(HELP);
+        return;
+    }
+    const handler = SUB[sub];
+    if (!handler)
+        die(2, `unknown subcommand: ${sub}\n${HELP}`);
+    return handler(argv.slice(1));
+}

package/bin/commands/annotate.ts

@@ -0,0 +1,119 @@
+import { readFile } from "fs/promises";
+import { parseArgs, type ParsedArgs } from "../lib/args.js";
+import { resolveServer, request } from "../lib/client.js";
+import { readStdin } from "../lib/files.js";
+import { out, die, color, json, exitCodeForError } from "../lib/output.js";
+import { getCliBrowserId } from "../lib/browser-id.js";
+
+const HELP = `
+  ima2 annotate <subcommand> <filename> [options]
+
+  Subcommands:
+    get <filename> [--json]
+    set <filename> --body <json|@file|->
+    rm  <filename> [--yes]
+`;
+
+const FLAGS = {
+  json: { type: "boolean" },
+  server: { type: "string" },
+  yes: { type: "boolean" },
+  body: { type: "string" },
+  help: { short: "h", type: "boolean" },
+};
+
+async function getServer(args: ParsedArgs) {
+  try { return await resolveServer({ serverFlag: args.server }); }
+  catch (e: any) { die(exitCodeForError(e), e.message); throw e; }
+}
+
+async function resolveBody(value: unknown): Promise<any> {
+  if (!value) return null;
+  if (typeof value !== "string") return null;
+  let text: string;
+  if (value === "-") text = await readStdin();
+  else if (value.startsWith("@")) text = await readFile(value.slice(1), "utf-8");
+  else text = value;
+  try { return JSON.parse(text); }
+  catch { die(2, "--body must be valid JSON"); throw 0; }
+}
+
+async function readLine(): Promise<string> {
+  return new Promise((resolve) => {
+    let buf = "";
+    process.stdin.setEncoding("utf-8");
+    const onData = (chunk: Buffer | string) => {
+      buf += chunk;
+      const nl = buf.indexOf("\n");
+      if (nl !== -1) {
+        process.stdin.removeListener("data", onData);
+        process.stdin.pause();
+        resolve(buf.slice(0, nl));
+      }
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+
+async function getSub(argv: string[]) {
+  const args = parseArgs(argv, { flags: FLAGS });
+  const filename = args.positional[0];
+  if (!filename) die(2, "filename required");
+  const server = await getServer(args);
+  const browserId = getCliBrowserId();
+  const resp = await request(server.base, `/api/annotations/${encodeURIComponent(filename)}`, {
+    headers: { "X-Ima2-Browser-Id": browserId },
+  }).catch((e: unknown) => { const err = e as { message?: string; code?: string }; die(exitCodeForError(e), `${err.message}${err.code ? ` (${err.code})` : ""}`); });
+  json(resp);
+}
+
+async function setSub(argv: string[]) {
+  const args = parseArgs(argv, { flags: FLAGS });
+  const filename = args.positional[0];
+  if (!filename) die(2, "filename required");
+  if (!args.body) die(2, "--body <json|@file|-> required");
+  const body = await resolveBody(args.body);
+  const server = await getServer(args);
+  const browserId = getCliBrowserId();
+  const resp = await request(server.base, `/api/annotations/${encodeURIComponent(filename)}`, {
+    method: "PUT",
+    body,
+    headers: { "X-Ima2-Browser-Id": browserId },
+  }).catch((e: unknown) => { const err = e as { message?: string; code?: string }; die(exitCodeForError(e), `${err.message}${err.code ? ` (${err.code})` : ""}`); });
+  if (args.json) { json(resp); return; }
+  out(color.green("✓ annotation saved"));
+}
+
+async function rmSub(argv: string[]) {
+  const args = parseArgs(argv, { flags: FLAGS });
+  const filename = args.positional[0];
+  if (!filename) die(2, "filename required");
+  if (!args.yes && !process.stdin.isTTY) die(2, "destructive: pass --yes for non-TTY");
+  if (!args.yes) {
+    process.stdout.write(`Delete annotation for ${filename}? [y/N] `);
+    const ans = await readLine();
+    if (!/^y(es)?$/i.test(ans.trim())) { out("(canceled)"); return; }
+  }
+  const server = await getServer(args);
+  const browserId = getCliBrowserId();
+  await request(server.base, `/api/annotations/${encodeURIComponent(filename)}`, {
+    method: "DELETE",
+    headers: { "X-Ima2-Browser-Id": browserId },
+  }).catch((e: unknown) => { const err = e as { message?: string; code?: string }; die(exitCodeForError(e), `${err.message}${err.code ? ` (${err.code})` : ""}`); });
+  out(color.green("✓ deleted"));
+}
+
+const SUB: Record<string, (argv: any[]) => Promise<void>> = {
+  get: getSub,
+  set: setSub,
+  rm: rmSub,
+};
+
+export default async function annotateCmd(argv: string[]) {
+  const sub = argv[0];
+  if (!sub || sub === "--help" || sub === "-h") { out(HELP); return; }
+  const handler = SUB[sub];
+  if (!handler) die(2, `unknown subcommand: ${sub}\n${HELP}`);
+  return handler(argv.slice(1));
+}

package/bin/commands/cancel.js

@@ -1,45 +1,52 @@
 import { parseArgs } from "../lib/args.js";
 import { resolveServer, request } from "../lib/client.js";
 import { out, die, dieWithError, color, json } from "../lib/output.js";
-
+import { errInfo } from "../../lib/errInfo.js";
 const SPEC = {
-  flags: {
-    json: { type: "boolean" },
-    server: { type: "string" },
-    help: { short: "h", type: "boolean" },
-  },
+    flags: {
+        json: { type: "boolean" },
+        server: { type: "string" },
+        help: { short: "h", type: "boolean" },
+    },
 };
-
 const HELP = `
   ima2 cancel <requestId> [--json]
 
   Mark an in-flight job as canceled in the local ima2 server registry.
 `;
-
 export default async function cancelCmd(argv) {
-  const args = parseArgs(argv, SPEC);
-  if (args.help) { out(HELP); return; }
-
-  const requestId = args.positional[0];
-  if (!requestId) die(2, "requestId required");
-
-  let server;
-  try { server = await resolveServer({ serverFlag: args.server }); }
-  catch (e) {
-    if (args.json) json({ ok: false, requestId, error: e.message, code: e.code, status: e.status });
-    dieWithError(e);
-  }
-
-  try {
-    await request(server.base, `/api/inflight/${encodeURIComponent(requestId)}`, {
-      method: "DELETE",
-      timeoutMs: 30_000,
-    });
-  } catch (e) {
-    if (args.json) json({ ok: false, requestId, error: e.message, code: e.code, status: e.status });
-    dieWithError(e);
-  }
-
-  if (args.json) json({ ok: true, requestId });
-  else out(color.green("✓ ") + `canceled ${requestId}`);
+    const args = parseArgs(argv, SPEC);
+    if (args.help) {
+        out(HELP);
+        return;
+    }
+    const requestId = args.positional[0];
+    if (!requestId)
+        die(2, "requestId required");
+    let server;
+    try {
+        server = await resolveServer({ serverFlag: args.server });
+    }
+    catch (e) {
+        const err = errInfo(e);
+        if (args.json)
+            json({ ok: false, requestId, error: err.message, code: err.code, status: err.status });
+        dieWithError(e);
+    }
+    try {
+        await request(server.base, `/api/inflight/${encodeURIComponent(requestId)}`, {
+            method: "DELETE",
+            timeoutMs: 30_000,
+        });
+    }
+    catch (e) {
+        const err = errInfo(e);
+        if (args.json)
+            json({ ok: false, requestId, error: err.message, code: err.code, status: err.status });
+        dieWithError(e);
+    }
+    if (args.json)
+        json({ ok: true, requestId });
+    else
+        out(color.green("✓ ") + `canceled ${requestId}`);
 }

package/bin/commands/cancel.ts

@@ -0,0 +1,48 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer, request } from "../lib/client.js";
+import { out, die, dieWithError, color, json } from "../lib/output.js";
+
+import { errInfo } from "../../lib/errInfo.js";
+const SPEC = {
+  flags: {
+    json: { type: "boolean" },
+    server: { type: "string" },
+    help: { short: "h", type: "boolean" },
+  },
+};
+
+const HELP = `
+  ima2 cancel <requestId> [--json]
+
+  Mark an in-flight job as canceled in the local ima2 server registry.
+`;
+
+export default async function cancelCmd(argv: string[]) {
+  const args = parseArgs(argv, SPEC);
+  if (args.help) { out(HELP); return; }
+
+  const requestId = args.positional[0];
+  if (!requestId) die(2, "requestId required");
+
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); }
+  catch (e) {
+    const err = errInfo(e);
+    if (args.json) json({ ok: false, requestId, error: err.message, code: err.code, status: err.status });
+    dieWithError(e);
+  }
+
+  try {
+    await request(server.base, `/api/inflight/${encodeURIComponent(requestId)}`, {
+      method: "DELETE",
+      timeoutMs: 30_000,
+    });
+  } catch (e) {
+    const err = errInfo(e);
+    if (args.json) json({ ok: false, requestId, error: err.message, code: err.code, status: err.status });
+    dieWithError(e);
+  }
+
+  if (args.json) json({ ok: true, requestId });
+  else out(color.green("✓ ") + `canceled ${requestId}`);
+}

package/bin/commands/canvas-versions.js

@@ -0,0 +1,91 @@
+import { readFile } from "fs/promises";
+import { parseArgs } from "../lib/args.js";
+import { resolveServer, request } from "../lib/client.js";
+import { out, die, color, json, exitCodeForError } from "../lib/output.js";
+const HELP = `
+  ima2 canvas-versions <subcommand> [options]
+
+  Subcommands:
+    save <imagefile> [--source <filename>] [--prompt <text>]
+    update <filename> <imagefile> [--source <filename>] [--prompt <text>]
+
+  Notes: server only exposes POST /api/canvas-versions (collection) and
+  PUT /api/canvas-versions/:filename. No GET, no DELETE.
+`;
+const FLAGS = {
+    json: { type: "boolean" },
+    server: { type: "string" },
+    source: { type: "string" },
+    prompt: { type: "string" },
+    help: { short: "h", type: "boolean" },
+};
+async function getServer(args) {
+    try {
+        return await resolveServer({ serverFlag: args.server });
+    }
+    catch (e) {
+        die(exitCodeForError(e), e.message);
+        throw e;
+    }
+}
+function buildHeaders(args) {
+    const h = { "Content-Type": "image/png" };
+    if (args.source)
+        h["X-Ima2-Canvas-Source-Filename"] = String(args.source);
+    if (args.prompt)
+        h["X-Ima2-Canvas-Prompt"] = String(args.prompt);
+    return h;
+}
+async function saveSub(argv) {
+    const args = parseArgs(argv, { flags: FLAGS });
+    const file = args.positional[0];
+    if (!file)
+        die(2, "image file required");
+    const buf = await readFile(file);
+    const server = await getServer(args);
+    const resp = await request(server.base, "/api/canvas-versions", {
+        method: "POST",
+        body: buf,
+        raw: true,
+        headers: buildHeaders(args),
+    }).catch((e) => { const err = e; die(exitCodeForError(e), `${err.message}${err.code ? ` (${err.code})` : ""}`); });
+    if (args.json) {
+        json(resp);
+        return;
+    }
+    out(color.green("✓ saved canvas version"));
+}
+async function updateSub(argv) {
+    const args = parseArgs(argv, { flags: FLAGS });
+    const [filename, file] = args.positional;
+    if (!filename || !file)
+        die(2, "usage: canvas-versions update <filename> <imagefile>");
+    const buf = await readFile(file);
+    const server = await getServer(args);
+    const resp = await request(server.base, `/api/canvas-versions/${encodeURIComponent(filename)}`, {
+        method: "PUT",
+        body: buf,
+        raw: true,
+        headers: buildHeaders(args),
+    }).catch((e) => { const err = e; die(exitCodeForError(e), `${err.message}${err.code ? ` (${err.code})` : ""}`); });
+    if (args.json) {
+        json(resp);
+        return;
+    }
+    out(color.green("✓ updated"));
+}
+const SUB = {
+    save: saveSub,
+    update: updateSub,
+};
+export default async function canvasVersionsCmd(argv) {
+    const sub = argv[0];
+    if (!sub || sub === "--help" || sub === "-h") {
+        out(HELP);
+        return;
+    }
+    const handler = SUB[sub];
+    if (!handler)
+        die(2, `unknown subcommand: ${sub}\n${HELP}`);
+    return handler(argv.slice(1));
+}