ima2-gen 2.0.1 → 2.0.2

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **SSE multiplexing** — shared `GET /api/events` endpoint with ring-buffer replay and `Last-Event-ID` reconnect support (`lib/eventBus.ts`, `routes/events.ts`).
+- **Async POST generation mode** — multimode, node, and video routes accept async POST and dual-emit progress on both per-request SSE and the shared event bus.
+- **Frontend event channel** — singleton `EventSource` client (`ui/src/lib/eventChannel.ts`) replaces per-request SSE streams for UI generation flows.
+- **Subscribe-before-fetch contract** — `tests/async-stream-subscribe-order.test.js` locks the race where ultra-fast server publish could arrive before client handler registration.
+- Store modularization — split monolithic `useAppStore` into focused impl modules (`storeGenImpl`, `storeNodeGenImpl`, `storeVideoImpl`, `storeInflightImpl`, etc.).
+- Frontend/API barrel splits — `ui/src/lib/api.ts` and `ui/src/index.css` decomposed into ≤500-line modules.
+- Storyboard workflow — 9-panel grid with black Panel 1 lead-in for image and video generation.
+- Gallery hang fix — video decoder/connection exhaustion on focus change (RCA 01).
+
+### Changed
+
+- UI clients migrated from per-request SSE to `eventChannel` + async POST for multimode, node, and video generation.
+- Multimode concurrency tracking uses `activeFlightIds` Set instead of `multimodeAbortControllers`.
+- Test suite grew to **968** cases across **186** files (65 runtime-importing, 121 contract-only).
+
+### Fixed
+
+- SSE multiplexing hardening — inflight cancel/done race guards, replay-gap handling, subscribe/timeout/requestId races, and frontend reconnect/error parsing (`sseStreamError.ts`).
+- Node route validation order — `startJob`/202 response moved after request validation.
+- CI typecheck — unused imports in card-news tests and store split type mismatches.
+- Thumbnail backfill failure reporting (#94).
+- AGY Windows pipe handling, Gemini API aspect ratio string values, multimode same-prompt batching.
+- Moderation over-filtering — removed safety tags and added error enrichment.
+
+## [2.0.1] - 2026-06-03
+
+### Added
+
+- **Gemini API provider** (`provider: "gemini-api"`) — direct Generative Language API and Vertex AI paths with `nano-banana-2` / `nano-banana-pro` model picker, aspect ratio, and resolution controls.
+- **Grok billing quota bar** — `$used/$limit` on QuotaCard via `GET /api/quota`.
+- **Switch Account** — device-code OAuth re-auth for Grok and Codex without leaving the app.
+- **Grok video model picker** — V / V1.5 selection in video controls.
+- Image/video thumbnails and history sidebar cards.
+- Centralized recursive thumbnail backfill.
+- Gemini/Vertex API key management routes and web UI.
+
+### Changed
+
+- Provider plumbing and CLI parity for gemini-api, grok-api, and vertex paths.
+- Grok model/size pickers and adapter updates.
+- Pages and developer docs reorganized to be feature-centric.
+
+### Fixed
+
+- Preserve video metadata in sequence history and thumbnail fallbacks in history UI.
+- Vertex AI integration — auth mode persistence, skip unsupported `response_format`, prefer Vertex over API key when both configured.
+- Gemini image cost corrected to official pricing; aspect ratio/resolution UI layout polish.
+- Skip GPT pixel-limit size confirm for Grok/Gemini providers.
+- Reap orphaned codex device-auth child on abandoned Switch Account flow.
+- Document Gemini providers in CLI help; harden provider paths and CLI metadata.
+
+### Security
+
+- Atomic `config.json` writes in keys routes; atomic token write with codex env scrubbing.
+- Cap sharp input pixels to prevent decompression bombs.
+- Audit fixes — crypto session IDs, session cap, double-click guard, API key in header only.
+
+## [2.0.0] - 2026-06-02
+
+### Added
+
+- Major version bump packaging the Gemini API, Grok API key, Vertex AI, and expanded provider surface shipped in the 1.1.x preview line.
+
+## [1.1.23] - 2026-06-02
+
+### Added
+
+- Gallery skeleton shimmer and F5 refresh fix (#93).
+- Hero one-click install scripts on the documentation site.
+
+## [1.1.22] - 2026-06-02
+
+### Fixed
+
+- Graceful shutdown releases file handles on Windows (EBUSY fix).
+- Ctrl+C clean shutdown — database close, child process stop, file lock release.
+
+## [1.1.21] - 2026-05-31
+
+### Changed
+
+- Bump bundled progrok 0.1.1 → 0.2.0 (video edit + extend commands).
+
+## [1.1.15] - 2026-05-31
+
+### Added
+
+- **Agent Mode** — conversational image workspace with sessions, turns, durable queue, slash commands (`/api/agent/*`).
+- **Grok provider** — bundled progrok, Classic/Node/Agent through search + planner + xAI Images API.
+- **Video generation** — text/image/reference-to-video via Grok, edit/extend/frame/analyze routes, branch-local last-frame continuation.
+- `GET /api/capabilities` discovery endpoint (#62).
+- `POST /api/prompt-builder/chat` assistant and `ima2 prompt build` CLI wrapper.
+- Grok model/size pickers, billing API, and `ima2 grok` helpers.
+
+### Fixed
+
+- Prompt Studio regression (#75), long-prompt preview (#77), prompt autofill perf (#78).
+- Per-image metadata persistence (#79), batch comparison matrix (#80).
+
+## [1.1.10] - 2026-05-06
+
+### Added
+
+- API-key provider Responses parity for generate/edit/multimode/node (#49).
+- Masked-edit feature flag groundwork (`IMA2_OAUTH_MASKED_EDIT_ENABLED`, #31).
+- Gallery default-to-current-session with All Images toggle (#42).
+- Centralized `persistenceRegistry` for `ima2.*` localStorage keys (#43).
+- `typecheck:tests` and `test:inventory` quality gates.
+
+### Changed
+
+- Split `lib/oauthProxy.ts` into `lib/oauthProxy/*` subtree.
+- Added `lib/runtimeContext.ts`, `lib/responsesImageAdapter.ts`, `lib/providerOptions.ts`, `lib/errInfo.ts`, `lib/promptSafetyPolicy.ts`.
+
+## [1.1.0] - 2026-04-25
+
+### Added
+
+- TypeScript migration complete — route, lib, server, config, and bin sources are `*.ts` with committed build artifacts.
+- CLI feature parity with server API (#45).
+- Canvas Mode workspace split and dual-mask cleanup.
+- OS-trash soft-delete for history.
+
+## [1.0.3] - 2026-04-23
+
+### Added
+
+- Initial npm publish of `ima2-gen` — local OAuth image generation studio with Classic mode, Node mode, Canvas Mode, and CLI.
+
+[Unreleased]: https://github.com/lidge-jun/ima2-gen/compare/v2.0.1...HEAD
+[2.0.1]: https://github.com/lidge-jun/ima2-gen/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.23...v2.0.0
+[1.1.23]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.22...v1.1.23
+[1.1.22]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.21...v1.1.22
+[1.1.21]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.20...v1.1.21
+[1.1.15]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.14...v1.1.15
+[1.1.10]: https://github.com/lidge-jun/ima2-gen/compare/v1.1.9...v1.1.10
+[1.1.0]: https://github.com/lidge-jun/ima2-gen/compare/v1.0.11...v1.1.0
+[1.0.3]: https://github.com/lidge-jun/ima2-gen/releases/tag/v1.0.3

package/README.md

@@ -69,7 +69,7 @@ Each script checks for nvm/fnm/brew/winget, installs Node LTS through the best a
 1. **GPT OAuth** — login with ChatGPT account (free, images only)
 2. **Grok OAuth** — login with xAI/Grok account (images + video)
 3. **Both** — GPT OAuth + Grok OAuth (full feature access)
-4. **API Key** — paste your OpenAI API key (paid)
+4. **Web setup** — configure everything in the web UI
 
 Video generation requires Grok OAuth (option 2 or 3). Run `ima2 grok login` separately if you already have GPT OAuth configured and want to add video support; it defaults to the manual-paste flow.
 
@@ -97,6 +97,10 @@ Ctrl+C now performs a clean shutdown — closing the database, stopping child pr
 - **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.
 
+### SSE Multiplexing
+
+The web UI uses a single `GET /api/events` Server-Sent Events connection for all generation progress. Multimode, node, and video requests are submitted as async POST (`202 { requestId }`) and progress events are multiplexed through a shared event bus. This eliminates the browser 6-connection limit that previously caused gallery hangs during concurrent generation. CLI clients that do not send `async: true` still receive per-request SSE streams for backward compatibility.
+
 ## Provider Paths
 
 Image generation can run through the local Codex/ChatGPT OAuth path, a configured OpenAI API key, the bundled Grok provider, or the Gemini provider via Antigravity CLI.
@@ -105,11 +109,14 @@ Image generation can run through the local Codex/ChatGPT OAuth path, a configure
 - `provider: "api"` calls the OpenAI Responses API with the hosted `image_generation` tool.
 - `provider: "grok"` starts bundled `progrok` on `127.0.0.1:18645`, runs mandatory xAI Web Search plus a planner pass (default: `grok-4.3`, configurable in settings or via `--planner-model`), then calls xAI Images API through the local proxy.
 - `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool (model: `nano-banana-2`). Output is fixed at 1024×1024 JPEG, max 3 reference images. No web search, quality, or size controls.
+- `provider: "gemini-api"` calls the Google Generative Language API directly. Supports two models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Auth is via `GEMINI_API_KEY` env var, web UI key management, or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON`). When both an API key and Vertex credentials are configured, Vertex takes priority. Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these controls are only honored on the direct API path — the Vertex AI endpoint ignores aspect/size because it does not accept the `response_format` field. Per-model cost differs: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
 - API-key generation supports classic generate, edit, mask-guided edit, multimode, and node generation.
 - Grok generation supports Classic, Node, and Agent flows. If a Classic reference, Node parent image, or Agent current image is present, ima2 switches the final Grok call to xAI image edit so image-to-image context is preserved.
 
 If no provider is specified, the app keeps the current GPT 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. Grok defaults to `grok-imagine-image`; `quality: "high"` promotes the final image call to `grok-imagine-image-quality`.
 
+Grok image generation exposes a model picker (`grok-imagine-image` / `grok-imagine-image-quality`) and a size picker (aspect ratio + 1k/2k resolution). The Settings page shows a billing/quota bar with `$used/$limit` drawn from the Grok billing API, and a **Switch Account** button that starts a device-code OAuth flow (`POST /api/auth/switch`) for re-authenticating without leaving the app.
+
 Grok video generation uses `grok-imagine-video` (default) or `grok-imagine-video-1.5-preview`. Three modes are auto-detected from reference count: text-to-video (0 refs), image-to-video (1 ref), and reference-to-video (2–7 refs, max 10s duration). `grok-imagine-video-1.5-preview` supports image-to-video but not `reference_images` Ref2V, so 2+ refs use `grok-imagine-video` as the effective model. Video edit and extension are also base-model only. Video controls include duration (1–15s), resolution (480p, 720p), and aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto).
 
 ![Settings workspace showing GPT OAuth active and API key provider available.](assets/screenshots/settings-oauth-generation.png)
@@ -260,6 +267,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image` | Default final Grok image model |
 | `IMA2_GROK_GENERATION_TIMEOUT_MS` | `120000` | Timeout for the final Grok Images API call |
 | `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |
+| `GEMINI_API_KEY` | — | API key for `provider: "gemini-api"` direct Generative Language API path |
+| `VERTEX_SERVICE_ACCOUNT_JSON` | — | Google service account JSON for Vertex AI auth with `provider: "gemini-api"`; takes priority over `GEMINI_API_KEY` when both are set |
 
 ### Logging modes
 

package/bin/commands/backfillThumbs.js

@@ -15,4 +15,10 @@ export async function backfillThumbs() {
     if (r.created > 0)
         invalidateHistoryIndex();
     console.log(`[thumbs] Done: ${r.created} created, ${r.skipped} skipped (already exist), ${r.failed} failed out of ${r.total} media files.`);
+    if (r.failures.length > 0) {
+        console.log(`[thumbs] Showing ${r.failures.length} thumbnail failure(s):`);
+        for (const failure of r.failures) {
+            console.log(`  - ${failure.kind}: ${failure.file} (${failure.reason})`);
+        }
+    }
 }

package/bin/commands/gen.js

@@ -39,6 +39,11 @@ const HELP = `
 
   Generate image(s) via the running ima2 server.
 
+  Batch/async note:
+    Use -n <N> for multiple candidates in one request. Independent CLI
+    commands can run concurrently against the server; monitor active requestIds
+    with 'ima2 ps --json' and stop one with 'ima2 cancel <requestId>'.
+
   Options:
     -q, --quality <low|medium|high>         Default: low
     -s, --size <WxH | auto>                 Default: 1024x1024
@@ -63,6 +68,7 @@ const HELP = `
 
   Examples:
     ima2 gen "a shiba in space"
+    ima2 gen "a shiba in space" -n 4 -d ./out
     ima2 gen "poster" --model gpt-5.4 --mode direct --moderation low
     ima2 gen "merge" --ref a.png --ref b.png -q high -o out.png
     cat prompt.txt | ima2 gen --stdin -n 2 -d ./out

package/bin/ima2.js

@@ -65,20 +65,15 @@ async function setup() {
     console.log("    1) GPT OAuth   — login with ChatGPT account (free, images only)");
     console.log("    2) Grok OAuth  — login with xAI/Grok account (images + video)");
     console.log("    3) Both        — GPT OAuth + Grok OAuth");
-    console.log("    4) API Key     — paste your OpenAI API key (paid)\n");
+    console.log("    4) Web setup   — configure everything in the web UI\n");
     const choice = await rl.question("  Enter 1-4: ");
     const config = loadConfig();
     if (choice.trim() === "4") {
-        const key = await rl.question("  OpenAI API Key: ");
-        if (!key.startsWith("sk-")) {
-            console.log("  Invalid API key format. Expected sk-...");
-            rl.close();
-            process.exit(1);
-        }
-        config.provider = "api";
-        config.apiKey = key.trim();
+        config.provider = "oauth";
+        delete config.apiKey;
         saveConfig(config);
-        console.log("\n  API key saved. Starting server...\n");
+        console.log("\n  You can set up everything from the web UI.");
+        console.log("  Run 'ima2 serve', then open Settings in the browser to sign in or add API keys.\n");
     }
     else if (choice.trim() === "2") {
         config.provider = "grok";
@@ -260,6 +255,12 @@ function showHelp() {
 
   Usage: ima2 <command> [options]
 
+  Generation workflow:
+    Image/video jobs run on the server. For multiple candidates, prefer
+    'ima2 gen -n <N>' or 'ima2 multimode <prompt>' instead of repeating
+    one-image prompts. Start independent CLI jobs concurrently when needed;
+    use 'ima2 ps --json' to monitor requestIds and 'ima2 cancel <id>' to stop.
+
   Server commands:
     serve [--dev]  Start the image generation server
     setup, login   Configure API key or GPT OAuth (interactive)
@@ -316,6 +317,9 @@ function showHelp() {
     ima2 serve                       Start server
     ima2 serve --dev                 Start with verbose server diagnostics
     ima2 gen "a shiba in space"      Generate from CLI
+    ima2 gen "a shiba in space" -n 4 -d ./out
+                                      Generate 4 candidates in one request
+    ima2 ps --json                    Watch active async generation jobs
     ima2 gen "merge" --ref a.png --ref b.png -q high -o out.png
     ima2 video "a cat playing piano" --duration 10
     ima2 ls -n 10                    Last 10 generations

package/docs/API.md

@@ -10,14 +10,14 @@ http://localhost:3333
 
 ## Provider Policy
 
-Image generation supports OAuth, API-key, Grok, and Gemini (agy) providers.
+Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-api`) providers.
 
 - `provider: "oauth"` uses the local Codex OAuth proxy.
 - `provider: "api"` uses the OpenAI Responses API with the hosted `image_generation` tool.
 - `provider: "grok"` uses the bundled progrok xAI proxy. Classic, Node, and Agent generation run mandatory xAI Web Search through `/v1/responses`, then run a `grok-4.3` planner call with a forced local `generate_image` function, then ima2 executes xAI `/v1/images/generations`. If reference images, a Node parent image, or an Agent current image are attached, the final step switches to xAI `/v1/images/edits` so image-to-image context is preserved.
 - `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool. Model is `nano-banana-2`. Output is fixed at 1024×1024 JPEG. Max 3 reference images (i2i). No web search, quality, size, or mask controls. Multimode returns a single image. Video is unsupported (`AGY_VIDEO_UNSUPPORTED`).
 - `provider: "grok-api"` uses a direct xAI API key instead of the bundled progrok OAuth proxy. Same pipeline as `grok` (Web Search → planner → `/v1/images/generations`), same aspect ratio and resolution options. Requires an xAI API key configured via the web UI key management or `XAI_API_KEY` env var. Also supports video generation.
-- `provider: "gemini-api"` calls the Google Generative Language API directly (or Vertex AI with a service account JSON). Supports models `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Supports variable aspect ratios and resolutions (512px–4K). Requires a `GEMINI_API_KEY` env var, web UI key management, or a Vertex AI service account JSON. No web search or mask controls.
+- `provider: "gemini-api"` calls the Google Generative Language API directly (or Vertex AI with a service account JSON). Supports models `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these are honored only on the direct API path — the Vertex AI endpoint (`aiplatform.googleapis.com`) rejects the `response_format` field and always returns a default 1K/1:1 image regardless of requested size. Auth: `GEMINI_API_KEY` env var, web UI key management (`/api/keys/gemini`), or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON` or `/api/keys/vertex`). When both Vertex credentials and an API key are configured, Vertex takes priority. The chosen auth mode (`apikey` or `vertex`) persists to `~/.ima2/config.json` as `geminiAuthMode` and is restored on server startup. Per-model cost: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
 - API-key generation covers classic generate, edit, mask-guided edit, multimode, and node generation.
 - If `provider: "api"` is requested without an API key, routes fail before upstream with `401` and `API_KEY_REQUIRED`.
 - Grok generation maps `size` to xAI `aspect_ratio` and `resolution`; it does not send an OpenAI-style `size` field upstream. Grok edit uses xAI `/v1/images/edits`; Grok mask edit remains unsupported and returns `GROK_MASK_UNSUPPORTED`.
@@ -35,6 +35,16 @@ Generation section below for the full endpoint specification.
 | `GET` | `/api/oauth/status` | OAuth proxy status and visible models |
 | `GET` | `/api/grok/status` | Bundled progrok status and visible xAI image models |
 | `GET` | `/api/billing` | Billing/status probe, including API key source when configured |
+| `GET` | `/api/quota` | Provider quota: returns `{ codex, grok }`. Grok result includes `billing: { usedUsd, limitUsd }` and a `monthly` percent window drawn from the xAI billing API. |
+
+## Account Switching
+
+| Method | Path | Notes |
+|---|---|---|
+| `POST` | `/api/auth/switch` | Start a device-code OAuth flow. Body: `{ "provider": "grok" \| "codex" }`. Returns `{ sessionId, userCode, verificationUrl }`. |
+| `GET` | `/api/auth/switch/:sessionId` | Poll switch-account session status. Returns `{ status }` where status is `pending`, `complete`, `error`, or `expired`. |
+
+The Switch Account flow opens a browser verification URL. Once the user completes the device-code step, the server saves the new credentials (Grok: `~/.progrok/auth.json`; Codex: via `codex login --device-auth`) and the session transitions to `complete`. This endpoint is surfaced as a **Switch Account** button in the Settings QuotaCard for Grok and Codex providers.
 
 ## Storage
 
@@ -84,9 +94,81 @@ Storage `state` values:
 | `GET` | `/api/inflight` | Active jobs only by default |
 | `GET` | `/api/inflight?includeTerminal=1` | Includes recent terminal jobs for debugging |
 | `DELETE` | `/api/inflight/:requestId` | Cancel or forget an active job |
+| `GET` | `/api/events` | Persistent SSE multiplex channel for all async generation progress (see below) |
 
 In-flight logs and responses use `requestId` for correlation. Logs should not include raw prompts, reference data URLs, generated base64, tokens, cookies, auth headers, or raw upstream bodies.
 
+## Events (SSE Multiplexing)
+
+### `GET /api/events` (SSE Multiplexing)
+
+Single persistent Server-Sent Events channel that carries progress for all async generation jobs. The browser UI opens one `EventSource` here instead of holding a per-request SSE connection for each job, avoiding browser per-origin connection limits.
+
+| Query | Notes |
+|---|---|
+| `lastEventId` | Optional. Reconnect cursor; also accepted via the `Last-Event-ID` request header |
+
+**Response**: `text/event-stream` (persistent). Each frame uses standard SSE fields `id`, `event`, and `data` (JSON).
+
+**Connection limits**: When active listeners reach 512, the server returns `503` with `SSE_CAPACITY` before opening the stream.
+
+**Heartbeat**: Every 15 seconds the server writes a comment frame:
+
+```text
+: ping
+```
+
+**Replay**: On reconnect, the server replays events from an in-memory ring buffer (size 2000) for IDs newer than `lastEventId`. Large image payloads (>1000 characters) are omitted from replay with `_imageOmitted: true` in the `data` payload. If the requested ID is older than the oldest buffered event, the server emits a `replay-gap` event before live fan-out:
+
+| Event | Data | Description |
+|---|---|---|
+| `replay-gap` | `{ lastEventId, oldestAvailableId }` | Client should reconcile inflight state (for example via `GET /api/inflight`) |
+
+**Job routing**: Every `data` payload includes `jobId` (same value as the job's `requestId`). Event bodies also carry `requestId` where applicable. Clients filter events by matching `data.jobId` or `data.requestId` to the job they started.
+
+**Event types** (fan-out to all connected clients):
+
+| Event | Emitted by | Description |
+|---|---|---|
+| `phase` | node, multimode, video | Lifecycle phase change |
+| `partial` | node, multimode | Progressive preview image (base64 data URL) |
+| `image` | multimode | Final saved `GenerateItem` for one sequence image |
+| `done` | node, multimode, video | Terminal success payload (route-specific shape) |
+| `error` | all generation routes | Terminal failure |
+| `submitted` | video | Job submitted to xAI |
+| `progress` | video | Progress fraction 0.0–1.0 |
+| `planning` | video | Video planner running |
+
+Example SSE frame:
+
+```text
+id: 42
+event: phase
+data: {"requestId":"req_abc","jobId":"req_abc","phase":"streaming"}
+```
+
+### Async generation mode
+
+`POST /api/node/generate`, `POST /api/generate/multimode`, and `POST /api/video/generate` support an async POST mode for clients that already hold `GET /api/events`:
+
+```json
+{
+  "async": true,
+  "requestId": "req_xxx",
+  "...": "other route fields"
+}
+```
+
+| Outcome | HTTP | Body |
+|---|---|---|
+| Accepted | `202` | `{ "requestId": "req_xxx" }` |
+| Duplicate active `requestId` | `409` | `REQUEST_ID_IN_USE` |
+| More than 12 concurrent active jobs | `429` | `TOO_MANY_JOBS` with `Retry-After: 5` |
+
+Progress events are published on `GET /api/events`. The POST response returns immediately; clients must not expect SSE on the POST connection when `async: true`.
+
+CLI and legacy clients omit `async` and keep the original behavior: per-request SSE on the same POST response (`Accept: text/event-stream` where applicable). The server dual-emits in that mode — it writes SSE to the POST response and also publishes the same events on `GET /api/events`.
+
 ## Generation
 
 ### `POST /api/generate`
@@ -195,14 +277,46 @@ Body fields:
 }
 ```
 
-When `parentNodeId` is present, the server loads the stored parent node image and uses the edit path. Extra node references are currently supported only for root nodes.
+When `parentNodeId` is present, the server loads the stored parent node image and uses the edit path. Node-local references are allowed on both root and child/edit nodes; for child/edit nodes the parent image is sent first, then references, then the text prompt.
 
 With `provider: "grok"`, Node Mode uses the same xAI search + `grok-4.3` planner + Images API pipeline as classic generation. A parent node image, `externalSrc`, or extra references are passed to the planner and then to xAI `/v1/images/edits`; otherwise the final call uses `/v1/images/generations`. Grok Node requests are capped at three total input images, counting the parent/current image plus references, and return `GROK_REF_TOO_MANY` before upstream when that limit is exceeded. `quality: "high"` promotes the final image model to `grok-imagine-image-quality`.
 
-The route can stream Server-Sent Events when the client sends `Accept: text/event-stream`. Possible events include `phase`, `partial`, `done`, and `error`.
+The route can stream Server-Sent Events when the client sends `Accept: text/event-stream`. Possible events include `phase`, `partial`, `done`, and `error`. Alternatively, send `{ "async": true, "requestId": "req_xxx" }` in the body to receive `202 { requestId }` immediately and follow progress on `GET /api/events` (see Events section).
 
 Grok Node SSE responses do not include Responses API `partial` image events because the xAI Images API call is synchronous JSON. They still emit `phase` and `done`/`error` events so the Node UI can use the same in-flight lifecycle.
 
+### `POST /api/generate/multimode` (SSE)
+
+Multi-image sequence generation. SSE-only on the POST response unless async mode is used.
+
+```json
+{
+  "prompt": "a story in four panels",
+  "maxImages": 4,
+  "quality": "medium",
+  "size": "1024x1024",
+  "format": "png",
+  "moderation": "low",
+  "model": "gpt-5.4",
+  "provider": "oauth",
+  "references": [],
+  "requestId": "optional-client-id",
+  "async": false
+}
+```
+
+Send `Accept: text/event-stream` for per-request SSE on the POST connection. Or set `"async": true` with a client `requestId` to get `202 { requestId }` and receive events on `GET /api/events`.
+
+**SSE events**:
+
+| Event | Data | Description |
+|---|---|---|
+| `phase` | `{ requestId, phase, sequenceId?, maxImages? }` | Lifecycle phase |
+| `partial` | `{ requestId, image, index }` | Progressive preview |
+| `image` | full `GenerateItem` | One saved sequence image |
+| `done` | route-specific summary; may include `status: "partial"` after timeout if at least one image was saved | Sequence complete |
+| `error` | `{ requestId, error, code?, status? }` | Generation failed |
+
 ### `GET /api/node/:nodeId`
 
 Fetch stored node metadata and asset URL.
@@ -228,7 +342,7 @@ Server-side validation may return these reference codes:
 
 ### `POST /api/video/generate` (SSE)
 
-Generate a video via the Grok video provider. Returns Server-Sent Events.
+Generate a video via the Grok video provider. Returns Server-Sent Events on the POST connection, or accepts async mode (`{ "async": true, "requestId": "req_xxx" }`) for `202 { requestId }` with progress on `GET /api/events` (see Events section).
 
 ```json
 {
@@ -263,7 +377,7 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
 | Field | Type | Default | Notes |
 |---|---|---|---|
 | `prompt` | string | — | Required |
-| `provider` | string | `"grok"` | Must be `"grok"` |
+| `provider` | string | `"grok"` | `"grok"` or `"grok-api"` |
 | `model` | string | `grok-imagine-video` | Video model |
 | `duration` | integer | `5` | 1–15 seconds (clamped to 10 for reference-to-video) |
 | `resolution` | string | `"480p"` | `480p` or `720p` |
@@ -488,6 +602,9 @@ Style-sheet extraction can require an API key/openai client. Image generation al
 | `GEMINI_API_SAFETY_BLOCKED` | Gemini API generation blocked by safety filter |
 | `GEMINI_API_NO_IMAGE` | Gemini API returned no image in response |
 | `VIDEO_PROVIDER_UNSUPPORTED` | Video generation requires provider `"grok"` or `"grok-api"` |
+| `SSE_CAPACITY` | More than 512 concurrent `GET /api/events` listeners |
+| `REQUEST_ID_IN_USE` | Async POST used a `requestId` that already has an active job |
+| `TOO_MANY_JOBS` | More than 12 concurrent active generation jobs (`Retry-After: 5`) |
 
 ## Key Management
 
@@ -529,7 +646,7 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `POST /api/node/generate` (SSE) / `GET /api/node/:id` | `ima2 node generate` / `ima2 node show` |
 | `GET /api/history` | `ima2 ls` |
 | `DELETE /api/history/:name` / `…/permanent` | `ima2 history rm [--permanent]` |
-| `POST /api/history/restore` | `ima2 history restore --trash-id` |
+| `POST /api/history/:filename/restore` | `ima2 history restore --trash-id` |
 | `POST /api/history/favorite` | `ima2 history favorite` |
 | `POST /api/history/import-local` | `ima2 history import` |
 | `POST /api/metadata/read` | `ima2 metadata` / `ima2 show --metadata` |
@@ -544,10 +661,16 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `…/api/cardnews/…` (gated on `features.cardNews`) | `ima2 cardnews …` |
 | `POST /api/comfy/export-image` | `ima2 comfy export` |
 | `GET /api/inflight` / `DELETE /api/inflight/:id` | `ima2 inflight ls` (alias `ps`) / `ima2 inflight rm` (alias `cancel`) |
+| `GET /api/events` (SSE multiplex) | Web UI only (persistent `EventSource`; no CLI wrapper) |
 | `GET /api/storage/status` / `POST /api/storage/open-generated-dir` | `ima2 storage status` / `ima2 storage open` |
 | `GET /api/billing` / `GET /api/providers` / `GET /api/oauth/status` / `GET /api/grok/status` | `ima2 billing` / `ima2 providers` / `ima2 oauth status` / `ima2 grok status` |
+| `GET /api/quota` | `ima2 billing` (includes Grok `usedUsd`/`limitUsd`) |
+| `POST /api/auth/switch` / `GET /api/auth/switch/:sessionId` | Web UI only (Settings > QuotaCard > Switch Account) |
 | `GET /api/health` | `ima2 ping` |
 | `GET /api/capabilities` | `ima2 capabilities` |
+| `GET /api/config/grok-planner` | — (Grok planner model query) |
+| `PATCH /api/config/grok-planner` | — (Grok planner model update) |
+| `GET /api/agy/status` | — (Antigravity CLI install status) |
 | `POST /api/history/backfill-thumbnails` | `ima2 backfill-thumbs` |
 | `GET /api/keys/status`, `PUT/DELETE /api/keys/:provider`, `PUT/DELETE /api/keys/vertex` | Web UI only (Settings > API Keys) |
 | `GET/POST/PATCH/DELETE /api/agent/*` (sessions, turns, queue) | — (Agent Mode; web UI only, no CLI) |
@@ -556,7 +679,7 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 Notes:
 - `ima2 history favorite` and `ima2 annotate …` send `X-Ima2-Browser-Id: cli-<sha1prefix>` derived from the config dir, so CLI activity does not collide with browser sessions.
 - `ima2 session graph save` performs a GET-then-PUT with `If-Match: "<version>"` to guard against `GRAPH_VERSION_CONFLICT`.
-- `ima2 history import` and `ima2 canvas-versions save/update` send raw bytes with `Content-Type: image/<png|jpeg|webp>`; the SSE endpoints (`multimode`, `node generate`) use `Accept: text/event-stream`.
+- `ima2 history import` and `ima2 canvas-versions save/update` send raw bytes with `Content-Type: image/<png|jpeg|webp>`; the SSE endpoints (`multimode`, `node generate`, `video`) use `Accept: text/event-stream`. The web UI instead uses `GET /api/events` plus `async: true` on POST routes.
 - `ima2 cardnews …` checks `runtimeConfig.features.cardNews` before calling the gated endpoints; when disabled the CLI exits 2 with a clear message instead of producing a 404.
 
 ## CLI Discovery

package/docs/CLI.md

@@ -62,6 +62,7 @@ Provider override semantics:
 - `oauth` forces the local OAuth proxy path.
 - `grok` uses the bundled progrok xAI proxy (`127.0.0.1:18645`). Classic generation first runs mandatory xAI Web Search through Responses API, then asks `grok-4.3` to call ima2's local `generate_image` tool, then ima2 executes xAI `/v1/images/generations`. If `--ref` images are attached, the final step uses xAI `/v1/images/edits` instead so image-to-image/reference context is preserved. Models: `grok-imagine-image`, `grok-imagine-image-quality`. Size is mapped to xAI `aspect_ratio` and `resolution`; the UI web-search toggle is OpenAI-provider-only because Grok search is always on in this path.
 - `agy` spawns the Antigravity CLI to generate via Google Gemini (`nano-banana-2`). Fixed 1024×1024 JPEG output, max 3 refs. No web search, quality, size, or mask controls.
+- `gemini-api` calls the Google Generative Language API directly. Models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Use `--model nano-banana-2` or `--model nano-banana-pro` to select. Supports `--size` for aspect ratio and resolution (512px–4K) on the direct API path; Vertex AI ignores aspect/size. Requires `GEMINI_API_KEY` or a Vertex AI service account (`VERTEX_SERVICE_ACCOUNT_JSON`). Switching from `agy` or `gemini-api` provider auto-selects the corresponding Gemini model; switching away resets to the GPT default.
 - `auto` preserves route default behavior and currently resolves to GPT OAuth unless server routing changes.
 
 `ima2 serve` starts the bundled Grok proxy automatically. No separate `progrok`
@@ -317,7 +318,7 @@ Card News requires the server to be started with `IMA2_CARD_NEWS=1` (or `feature
 | `ima2 inflight rm <requestId>` | Force-remove a stuck job |
 | `ima2 storage status` | Storage inspection (richer than `doctor`) |
 | `ima2 storage open` | Open the generated dir in the OS file manager (POST) |
-| `ima2 billing` | API usage / quota |
+| `ima2 billing` | API usage / quota; Grok result includes `billing.usedUsd` / `billing.limitUsd` drawn from the xAI billing API |
 | `ima2 providers` | Configured providers |
 | `ima2 oauth status` | OAuth proxy state |
 | `ima2 grok status` | Bundled progrok / xAI image-model probe state |

package/docs/FAQ.ko.md

@@ -323,6 +323,22 @@ export HTTPS_PROXY=http://127.0.0.1:7890
 
 GPT OAuth는 OpenAI와 ChatGPT/Codex 관련 호스트 접근이 필요할 수 있습니다. 회사 방화벽, TLS 검사, VPN, 프록시가 흐름을 깨뜨릴 수 있습니다. 로그인 실패와 `failed to fetch`가 반복되면 다른 네트워크에서도 시도해 보세요.
 
+## SSE 멀티플렉싱
+
+### 왜 웹 UI가 단일 SSE 연결을 쓰나요?
+
+브라우저는 같은 origin에 대해 동시 HTTP 연결 수를 제한합니다(보통 6개). 여러 이미지를 동시에 생성할 때 각 요청이 SSE 연결을 점유하면, multimode+node+video가 동시에 돌아갈 때 연결이 포화되어 갤러리 썸네일이 멈췄습니다.
+
+이제 웹 UI는 `GET /api/events`로 하나의 SSE 연결만 열고, 모든 생성 진행 이벤트를 멀티플렉싱합니다. 생성 요청은 `async: true`로 보내면 즉시 `202 { requestId }` 응답을 받아 연결을 바로 해제합니다. CLI는 영향 없이 기존 per-request SSE를 그대로 사용합니다.
+
+### SSE 연결이 끊기면 어떻게 되나요?
+
+이벤트 채널 클라이언트가 지수 백오프로 자동 재연결합니다. 재연결 시 `Last-Event-ID`를 보내서 서버의 링 버퍼(최대 2000건)에서 놓친 이벤트를 재전송받습니다. 버퍼에서 이미 사라진 이벤트가 있으면 `replay-gap` 이벤트로 알려줍니다.
+
+### 동시 작업 상한은 얼마인가요?
+
+서버는 동시 생성 작업을 12건(`MAX_CONCURRENT_JOBS`)으로 제한합니다. 초과 요청은 `429`와 `Retry-After: 5`를 받습니다. SSE 엔드포인트 자체는 512개 동시 연결까지 지원합니다.
+
 ## CLI 점검 순서
 
 아래 순서대로 확인해 보세요.

package/docs/FAQ.md

@@ -103,6 +103,20 @@ ima2 serve
 
 If this happens on a company network, a firewall, VPN, proxy, or captive portal may also be blocking the OAuth flow.
 
+### How do I use the Gemini providers?
+
+Two Gemini providers are available:
+
+- **`agy`** — uses the Antigravity CLI (`agy -p`) with no API key needed. Requires the `agy` binary to be installed and logged in. Model is `nano-banana-2`, output is fixed at 1024×1024.
+
+- **`gemini-api`** — calls the Google Generative Language API directly. Add a `GEMINI_API_KEY` env var, or configure a key via Settings > API Keys. For Vertex AI, add a service account JSON via Settings or the `VERTEX_SERVICE_ACCOUNT_JSON` env var. When both an API key and Vertex credentials are present, Vertex takes priority. Use the auth-mode dropdown in Settings to switch between `apikey` and `vertex`; the choice is saved and restored automatically.
+
+The `gemini-api` provider supports two models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). The web UI shows aspect-ratio and resolution controls (512px–4K) for `gemini-api`; these are honored only on the direct Gemini API path and are ignored by Vertex AI.
+
+### How do I re-authenticate Grok or Codex without restarting?
+
+Use the **Switch Account** button in Settings > QuotaCard for the provider. This starts a device-code OAuth flow: a new browser tab opens the verification URL, you complete the login, and the server automatically picks up the new credentials. The Grok quota bar also shows `$used / $limit` (in USD) drawn from the xAI billing API.
+
 ## Models and quota
 
 ### Which model should I use?
@@ -334,6 +348,22 @@ Use the host and port from your proxy client. If `ima2-gen` still fails after th
 
 GPT OAuth may require access to OpenAI and ChatGPT/Codex-related hosts. A corporate firewall, TLS inspection, VPN, or proxy can break the flow. Try a different network if login and `failed to fetch` errors keep repeating.
 
+## SSE Multiplexing
+
+### Why does the web UI use a single SSE connection?
+
+Browsers limit the number of concurrent HTTP connections to the same origin (typically 6). When generating multiple images at once, each generation request used to hold a Server-Sent Events connection open. With multimode, node, and video running simultaneously, the browser would run out of connections and gallery thumbnails would hang.
+
+The web UI now opens a single persistent `GET /api/events` SSE connection and all generation progress is multiplexed through it. Generation requests use `async: true` and receive an immediate `202 { requestId }` response, freeing the connection immediately. The CLI is unaffected — it still uses per-request SSE when `async` is not set.
+
+### What happens if the SSE connection drops?
+
+The event channel client reconnects automatically with exponential backoff. On reconnect, it sends `Last-Event-ID` so the server can replay missed events from its ring buffer (up to 2000 entries). If events have been evicted from the buffer, the server sends a `replay-gap` event so the client knows some updates may have been lost.
+
+### What is the maximum number of concurrent jobs?
+
+The server caps concurrent generation jobs at 12 (`MAX_CONCURRENT_JOBS`). Additional requests receive `429` with `Retry-After: 5`. The SSE endpoint itself caps at 512 simultaneous connections.
+
 ## CLI troubleshooting checklist
 
 Run these in order:

package/docs/README.ko.md

@@ -78,7 +78,7 @@ v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리
 1. **GPT OAuth** — ChatGPT 계정으로 로그인 (무료, 이미지만)
 2. **Grok OAuth** — xAI/Grok 계정으로 로그인 (이미지 + 영상)
 3. **Both** — GPT + Grok 둘 다 (전체 기능)
-4. **API Key** — OpenAI API 키 입력 (유료)
+4. **Web setup** — 웹 UI에서 전체 설정
 
 영상 생성은 Grok OAuth(2번 또는 3번)가 필요합니다.
 
@@ -95,6 +95,10 @@ v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리
 - **Mobile shell**: 작은 화면에서는 app bar, compose sheet, compact settings toggle로 조작합니다.
 - **Observable jobs**: 진행 중인 작업과 최근 완료된 작업을 request ID로 추적합니다.
 
+### SSE 멀티플렉싱
+
+웹 UI는 단일 `GET /api/events` Server-Sent Events 연결로 모든 생성 진행 상황을 수신합니다. Multimode, node, video 요청은 비동기 POST(`202 { requestId }`)로 제출되고, 이벤트 버스를 통해 진행 이벤트가 멀티플렉싱됩니다. 기존 브라우저 6-연결 제한으로 인한 동시 생성 시 갤러리 hang 문제가 해결됩니다. `async: true`를 보내지 않는 CLI 클라이언트는 기존 per-request SSE 스트림을 그대로 사용할 수 있습니다.
+
 ## 이미지 생성 공급자
 
 이미지 생성은 로컬 Codex/ChatGPT OAuth, OpenAI API key, 번들 Grok 공급자를 지원합니다.
@@ -232,8 +236,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_NO_GROK_PROXY` | — | `1`이면 progrok 자동 시작 비활성화 |
 | `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | Grok 플래너 모델 (설정 UI 또는 `--planner-model` CLI 플래그로도 변경 가능) |
 | `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image` | 기본 Grok 이미지 모델 |
-| `IMA2_LOG_LEVEL` | `warn` | 일반 `serve`는 `warn`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
-| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | 디버그용 최근 작업 보존 시간 |
+| `IMA2_LOG_LEVEL` | `info` | 일반 `serve`는 `info`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | 디버그용 최근 작업 보존 시간 (5분) |
 | `OPENAI_API_KEY` | — | `provider: "api"` Responses 이미지 경로와 보조 기능용 API 키 |
 
 ### 로그 모드