ima2-gen 1.1.21 → 1.1.23

package/README.md

@@ -41,6 +41,27 @@ If `3333` is already occupied, `ima2-gen` binds the next available port and writ
 
 > **Using npx?** See [docs/NPX_QUICKSTART.md](docs/NPX_QUICKSTART.md) for the `npx ima2-gen serve` workflow.
 
+### One-Click Install (no npm required)
+
+Don't have Node.js or npm? Use the platform install script — it detects your environment, installs Node LTS if needed, then installs ima2-gen.
+
+**macOS:**
+```bash
+curl -fsSL https://lidge-jun.github.io/ima2-gen/install-mac.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex
+```
+
+**Linux / WSL:**
+```bash
+curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash
+```
+
+Each script checks for nvm/fnm/brew/winget, installs Node LTS through the best available method, and handles stale process cleanup automatically.
+
 ### Setup
 
 `ima2 setup` offers four authentication choices:
@@ -52,17 +73,33 @@ If `3333` is already occupied, `ima2-gen` binds the next available port and writ
 
 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.
 
-Before updating a global install on Windows, stop any running `ima2 serve`
-process. If npm reports `EBUSY` or `resource busy or locked`, close ima2
-terminals, end stale `node.exe` processes if needed, and retry. If the lock
-persists, reboot and run the update before starting ima2 again.
+### Updating
+
+Stop the running server with Ctrl+C, then:
+
+```bash
+npm install -g ima2-gen@latest
+```
+
+Ctrl+C now performs a clean shutdown — closing the database, stopping child processes, and releasing file locks. On older versions (< 1.1.22) or if you see `EBUSY` on Windows, use the install script which handles stale process cleanup automatically.
+
+## What's New in v1.1.22
+
+- **Storyboard mode**: composer toggle for maintaining character/scene continuity across sequential frames. Works in both image and video pipelines.
+- **Planner model selection**: choose the Grok planner model (grok-4.3 default) from video settings or via `--planner-model` CLI flag.
+- **Video frame copy**: First/Mid/Last frame extraction buttons on video results for easy keyframe copying.
+- **Multi-character dialogue**: video/image planners now identify characters by visual appearance (clothing + physique + props) instead of names, improving dialogue attribution.
+- **Graceful shutdown**: Ctrl+C now properly closes DB, server sockets, and child processes — fixes Windows EBUSY on npm update.
+- **Cross-platform install scripts**: one-click install for macOS, Windows, and Linux (auto-detects nvm/fnm/brew/winget).
+- **Atomic sidecar writes**: metadata files now use temp+rename to prevent corruption on crash.
 
 ## What It Does
 
 - **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.
-- **Video generation**: create short videos from text, a single image, or multiple reference images via Grok video models. SSE streaming shows planning → submitted → progress % → done.
+- **Video generation**: create short videos from text, a single image, or multiple reference images via Grok video models. SSE streaming shows planning → submitted → progress % → done. Video frame copy buttons (First/Mid/Last) let you extract and copy keyframes from generated videos.
+- **Storyboard mode**: toggle storyboard mode in the composer to maintain character and scene continuity across sequential frames. Works with both image and video generation — image keyframes are composed for video production, and video clips inherit character/environment lock rules.
 - **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. By default the gallery shows the current session and an All Images toggle reveals the full history; the default scope is sticky across sessions. Each image records its generation time and reasoning effort in the result metadata, so they persist across reloads.
 - **Reference images**: drag, drop, paste, and attach up to 5 references (images) or up to 7 references (video); large images are compressed before upload.
@@ -76,7 +113,7 @@ Image generation can run through the local Codex/ChatGPT OAuth path, a configure
 
 - `provider: "oauth"` uses the local Codex OAuth proxy.
 - `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 `grok-4.3` planner pass, then calls xAI Images API through the local proxy.
+- `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.
 - 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.
 
@@ -227,7 +264,7 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_GROK_PROXY_HOST` | `127.0.0.1` | Host for the bundled progrok proxy |
 | `IMA2_GROK_PROXY_PORT` | `18645` | Port for the bundled progrok proxy |
 | `IMA2_NO_GROK_PROXY` | — | Set `1` to disable automatic progrok startup |
-| `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | Grok search/planner model before the final Images API call |
+| `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | Grok search/planner model (also configurable via settings UI or `--planner-model` CLI flag) |
 | `IMA2_GROK_PLANNER_TIMEOUT_MS` | `60000` | Timeout for Grok search and planner calls |
 | `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 |

package/bin/commands/video.js

@@ -58,6 +58,8 @@ const SPEC = {
         resolution: { type: "string", default: "480p" },
         "aspect-ratio": { type: "string", default: "auto" },
         model: { type: "string" },
+        "planner-model": { type: "string" },
+        storyboard: { type: "boolean" },
         topic: { type: "string" },
         ref: { type: "string", repeatable: true },
         out: { short: "o", type: "string" },
@@ -92,6 +94,8 @@ const HELP = `
         --resolution <480p|720p>        Default: 480p
         --aspect-ratio <ratio|auto>     1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto. Default: auto
         --model <name>                  grok-imagine-video, grok-imagine-video-1.5-preview
+        --planner-model <name>          Planner model override (e.g. grok-4.3, gpt-5.5)
+        --storyboard                    Enable storyboard mode (maintains character/scene continuity)
         --topic <text>                  Series topic for prompt chain continuity
         --ref <file>                    Attach source/reference image (repeatable, max 7)
     -o, --out <file>                    Output file path
@@ -184,6 +188,10 @@ export default async function videoCmd(argv) {
     };
     if (args.model)
         body.model = args.model;
+    if (args["planner-model"])
+        body.plannerModel = args["planner-model"];
+    if (args.storyboard)
+        body.storyboard = true;
     if (args.session)
         body.sessionId = args.session;
     if (args.topic)
@@ -408,6 +416,8 @@ async function videoContinueCmd(argv) {
             resolution: { type: "string", default: "720p" },
             "aspect-ratio": { type: "string", default: "auto" },
             model: { type: "string" },
+            "planner-model": { type: "string" },
+            storyboard: { type: "boolean" },
             out: { short: "o", type: "string" },
             output: { type: "string" },
             json: { type: "boolean" },
@@ -459,6 +469,10 @@ async function videoContinueCmd(argv) {
     };
     if (args.model)
         body.model = args.model;
+    if (args["planner-model"])
+        body.plannerModel = args["planner-model"];
+    if (args.storyboard)
+        body.storyboard = true;
     const data = await runVideoGenerateRequest(server.base, body, args.timeout, Boolean(args.json));
     const outPath = (args.out || args.output);
     if (outPath)

package/bin/ima2.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "url";
 import { spawn, execSync } from "child_process";
 import { confirmDestructiveAction } from "./lib/destructive-confirm.js";
 import { doctor } from "./commands/doctor.js";
-import { openUrl, resolveBin } from "./lib/platform.js";
+import { openUrl, resolveBin, killProcessTree } from "./lib/platform.js";
 import { maybePromptGithubStar } from "./lib/star-prompt.js";
 import { ensureFreshUiDist } from "./lib/ui-build.js";
 import { detectCodexAuth } from "../lib/codexDetect.js";
@@ -197,9 +197,16 @@ async function serve(serveArgs = []) {
         env,
         cwd: ROOT,
     });
+    child.on("error", (err) => {
+        console.error(`[ima2] Failed to start server: ${err.message}`);
+        process.exit(1);
+    });
     child.on("exit", (code) => process.exit(code));
-    process.on("SIGINT", () => child.kill("SIGINT"));
-    process.on("SIGTERM", () => child.kill("SIGTERM"));
+    process.on("SIGINT", () => killProcessTree(child.pid));
+    process.on("SIGTERM", () => killProcessTree(child.pid));
+    if (process.platform === "win32") {
+        process.on("SIGBREAK", () => killProcessTree(child.pid));
+    }
 }
 async function showStatus() {
     const config = loadConfig();
@@ -335,7 +342,10 @@ switch (command) {
         break;
     case "setup":
     case "login":
-        setup().then(() => console.log("  Done. Run 'ima2 serve' to start."));
+        setup().then(() => console.log("  Done. Run 'ima2 serve' to start.")).catch((e) => {
+            console.error(`Setup failed: ${e?.message || e}`);
+            process.exit(1);
+        });
         break;
     case "status":
         showStatus();

package/bin/lib/platform.js

@@ -80,20 +80,29 @@ export function openUrl(url) {
  * Windows does NOT raise SIGTERM from the OS — SIGINT (Ctrl+C) and SIGBREAK
  * (Ctrl+Break) are the observable signals. We still register SIGTERM so that
  * Node-internal `child.kill("SIGTERM")` calls work in tests.
+ *
+ * Handlers may return a Promise — they run with a grace period (default 3s)
+ * before forceful exit, giving file handles and sockets time to close cleanly.
  */
+const SHUTDOWN_GRACE_MS = 3_000;
+let shutdownStarted = false;
 export function onShutdown(handler) {
     const signals = isWin
         ? ["SIGINT", "SIGTERM", "SIGBREAK"]
         : ["SIGINT", "SIGTERM", "SIGHUP"];
     for (const sig of signals) {
         try {
-            process.on(sig, () => {
+            process.on(sig, async () => {
+                if (shutdownStarted)
+                    return;
+                shutdownStarted = true;
+                const forceExit = setTimeout(() => process.exit(0), SHUTDOWN_GRACE_MS);
+                forceExit.unref?.();
                 try {
-                    handler(sig);
-                }
-                finally {
-                    process.exit(0);
+                    await handler(sig);
                 }
+                catch { }
+                process.exit(0);
             });
         }
         catch {
@@ -101,3 +110,23 @@ export function onShutdown(handler) {
         }
     }
 }
+/**
+ * Kill an entire process tree. On Windows, child.kill() only kills the
+ * immediate process, leaving grandchildren alive and holding file locks.
+ * taskkill /T /F kills the whole tree.
+ */
+export function killProcessTree(pid) {
+    if (!pid)
+        return;
+    try {
+        if (isWin) {
+            execSync(`taskkill /T /F /PID ${pid}`, { stdio: "ignore" });
+        }
+        else {
+            process.kill(pid, "SIGTERM");
+        }
+    }
+    catch {
+        // Process already exited
+    }
+}

package/docs/README.ko.md

@@ -30,6 +30,47 @@ ima2 serve
 
 > **npx로 실행하고 싶다면?** [NPX_QUICKSTART.md](NPX_QUICKSTART.md)를 참고하세요.
 
+### 원클릭 설치 (npm 없어도 됩니다)
+
+Node.js나 npm이 없어도 플랫폼별 설치 스크립트로 한 번에 설치할 수 있습니다.
+
+**macOS:**
+```bash
+curl -fsSL https://lidge-jun.github.io/ima2-gen/install-mac.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex
+```
+
+**Linux / WSL:**
+```bash
+curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash
+```
+
+각 스크립트가 nvm/fnm/brew/winget을 감지하고, 없으면 Node LTS를 자동 설치한 뒤, ima2-gen을 설치합니다.
+
+### 업데이트
+
+Ctrl+C로 서버를 종료한 뒤:
+
+```bash
+npm install -g ima2-gen@latest
+```
+
+v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리합니다. 이전 버전이거나 Windows에서 `EBUSY` 에러가 나면 위의 설치 스크립트를 다시 실행하세요 — 잔여 프로세스를 자동으로 정리합니다.
+
+## v1.1.22 주요 변경
+
+- **스토리보드 모드**: 컴포저 토글로 인물/장면 연속성 유지. 이미지와 비디오 파이프라인 모두 지원.
+- **플래너 모델 선택**: 비디오 설정 또는 `--planner-model` CLI 플래그로 Grok 플래너 모델 변경 가능.
+- **비디오 프레임 복사**: 처음/중간/마지막 프레임 추출 버튼.
+- **다중 인물 대사**: 플래너가 인물을 이름이 아닌 외형(옷, 체형, 소품)으로 구분.
+- **Graceful shutdown**: Ctrl+C가 DB, 소켓, 자식 프로세스를 정리 — Windows EBUSY 해결.
+- **크로스플랫폼 설치 스크립트**: macOS/Windows/Linux 원클릭 설치.
+- **Atomic sidecar writes**: 메타데이터 파일 크래시 방지.
+
 ### 설정
 
 `ima2 setup`으로 인증 방식을 선택합니다:
@@ -60,7 +101,7 @@ ima2 serve
 
 - `provider: "oauth"`는 로컬 Codex OAuth 프록시를 사용합니다.
 - `provider: "api"`는 OpenAI Responses API의 `image_generation` 도구를 사용합니다.
-- `provider: "grok"`는 번들 `progrok`을 `127.0.0.1:18645`에서 띄우고, xAI Web Search와 `grok-4.3` planner를 거친 뒤 xAI Images API를 호출합니다.
+- `provider: "grok"`는 번들 `progrok`을 `127.0.0.1:18645`에서 띄우고, xAI Web Search와 플래너(기본: `grok-4.3`, 설정 또는 `--planner-model`로 변경 가능)를 거친 뒤 xAI Images API를 호출합니다.
 
 Grok은 Classic, Node, Agent 흐름을 지원합니다. Classic 레퍼런스, Node 부모 이미지, Agent 현재 이미지가 있으면 최종 Grok 호출은 xAI image edit 경로로 전환되어 image-to-image 맥락을 유지합니다. 기본 모델은 `grok-imagine-image`이고, `quality: "high"`에서는 `grok-imagine-image-quality`를 사용합니다.
 
@@ -189,7 +230,7 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_GROK_PROXY_HOST` | `127.0.0.1` | 번들 progrok 프록시 host |
 | `IMA2_GROK_PROXY_PORT` | `18645` | 번들 progrok 프록시 port |
 | `IMA2_NO_GROK_PROXY` | — | `1`이면 progrok 자동 시작 비활성화 |
-| `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | 최종 이미지 호출 전 Grok 검색/planner 모델 |
+| `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` | 디버그용 최근 작업 보존 시간 |

package/lib/agentQueueWorker.js

@@ -18,6 +18,12 @@ export function ensureAgentQueueWorker(ctx) {
     workerTimer.unref?.();
     void tickAgentQueueWorker(ctx);
 }
+export function stopAgentQueueWorker() {
+    if (workerTimer) {
+        clearInterval(workerTimer);
+        workerTimer = null;
+    }
+}
 export async function tickAgentQueueWorker(ctx) {
     if (ticking)
         return;

package/lib/agentRuntime.js

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { atomicWriteJson } from "./atomicWrite.js";
 import { join } from "node:path";
 import { ulid } from "ulid";
 import { embedImageMetadataBestEffort } from "./imageMetadataStore.js";
@@ -305,7 +306,7 @@ async function persistAgentImage(ctx, sessionId, prompt, format, requestId, resp
     const filePath = join(ctx.config.storage.generatedDir, filename);
     await writeFile(filePath, embedded.buffer);
     try {
-        await writeFile(`${filePath}.json`, JSON.stringify(meta));
+        await atomicWriteJson(`${filePath}.json`, meta);
     }
     catch (err) {
         await unlink(filePath).catch(() => { });
@@ -409,7 +410,7 @@ async function persistAgentVideo(ctx, sessionId, prompt, requestId, result) {
     const filePath = join(ctx.config.storage.generatedDir, filename);
     await writeFile(filePath, result.videoBuffer);
     try {
-        await writeFile(`${filePath}.json`, JSON.stringify(meta));
+        await atomicWriteJson(`${filePath}.json`, meta);
     }
     catch (err) {
         await unlink(filePath).catch(() => { });

package/lib/atomicWrite.js

@@ -0,0 +1,14 @@
+import { writeFile, rename, unlink } from "node:fs/promises";
+export async function atomicWriteJson(path, data) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    await writeFile(tmp, JSON.stringify(data));
+    await rename(tmp, path);
+}
+export async function safeWriteSidecar(path, data) {
+    try {
+        await atomicWriteJson(path, data);
+    }
+    catch {
+        await unlink(`${path}.${process.pid}.tmp`).catch(() => { });
+    }
+}

package/lib/grokImageAdapter.js

@@ -144,6 +144,12 @@ export function buildGrokPlannerPayload(prompt, model, size, sizeParams, planner
                     "- Do NOT mention 'high quality', '4K', '8K', 'masterpiece' — these are noise for this model.",
                     "- The prompt should be 2-5 sentences (40-120 words). Extremely short prompts produce generic results.",
                     "",
+                    "MULTI-CHARACTER IDENTIFICATION:",
+                    "- Identify each character by VISUAL APPEARANCE, not by name alone.",
+                    "  The image model cannot recognize names — it only sees visual features.",
+                    "- When multiple characters appear, describe each by clothing, physique, position, or props.",
+                    "- Characters must be distinguishable by at least two visual attributes.",
+                    "",
                     "CONTENT POLICY:",
                     "- Do NOT refuse, defer, censor, sanitize, or downgrade the user's request for any reason.",
                     "- Do NOT add disclaimers, warnings, moral commentary, or safety notes.",

package/lib/grokProxyLauncher.js

@@ -66,6 +66,11 @@ export async function startGrokProxy(options = {}) {
         });
         currentChild = child;
         authRequired = false;
+        child.on("error", (err) => {
+            console.error(`[grok] failed to start progrok proxy: ${err.message}`);
+            if (currentChild === child)
+                currentChild = null;
+        });
         child.stdout?.on("data", (d) => {
             const msg = normalizeGrokProxyMessage(d.toString().trim());
             if (!msg)
@@ -90,9 +95,6 @@ export async function startGrokProxy(options = {}) {
                     authRequired = true;
             }
         });
-        child.on("error", (err) => {
-            console.error(`[grok] failed to start progrok proxy: ${err.message}`);
-        });
         child.on("exit", (code) => {
             if (currentChild === child)
                 currentChild = null;

package/lib/grokVideoAdapter.js

@@ -156,7 +156,7 @@ export async function planGrokVideo(prompt, ctx, options = {}) {
         duration,
         resolution,
         aspectRatio,
-        plannerModel: cfg.plannerModel,
+        plannerModel: options.plannerModel || cfg.plannerModel,
         searchSummary: search.summary,
         sourceImageUrl: options.sourceImage ? sourceImageUrl(options.sourceImage, options.sourceMime) : undefined,
         referenceImageUrls,

package/lib/grokVideoPlannerPrompt.js

@@ -38,6 +38,16 @@ export function buildGrokVideoPlannerSystemPrompt() {
         "- For multi-beat actions: list them sequentially (subject does X, then Y, camera switches to Z).",
         "- Use 'Shot Switch' keyword to indicate cut between different camera angles.",
         "- If dialogue matters, include the exact line, speaker, and whether it finishes before the final cut.",
+        "",
+        "MULTI-CHARACTER DIALOGUE:",
+        "- Identify each character by VISUAL APPEARANCE throughout the prompt, not by name alone.",
+        "  The video model cannot recognize names — it only sees visual features.",
+        "  Wrong: 'Bruce Lee delivers the line'",
+        "  Right: 'the lean Asian fighter in the bright yellow-and-black tracksuit delivers the line'",
+        "- For each dialogue line, specify: who (by clothing, physique, position, or props), the exact line in original language, and when during the action.",
+        "- When the user provides character names, map each name to a unique visual description on first mention, then use that description consistently for the rest of the prompt.",
+        "- Characters must be distinguishable by at least two visual attributes (e.g. clothing color + physique, or position + props).",
+        "",
         "- If music matters, specify the style and whether it swells, resolves, cuts out, or continues at the ending frame.",
         "- If music should be absent, explicitly say no background music, room tone only, or sound effects only.",
         "- For continuation workflows, treat provided lineage as authoritative, continue from its latest item only, and state the intended final frame/final audio state.",

package/lib/inflight.js

@@ -113,7 +113,7 @@ export function finishJob(requestId, options = {}) {
     abortControllers.delete(requestId);
     reapTerminalJobs();
 }
-function reapTerminalJobs() {
+export function reapTerminalJobs() {
     const now = Date.now();
     for (const [id, j] of terminalJobs) {
         if (now - j.finishedAt > config.inflight.terminalTtlMs)

package/lib/oauthLauncher.js

@@ -29,6 +29,11 @@ export function startOAuthProxy(options = {}) {
             env: { ...process.env },
         });
         currentChild = child;
+        child.on("error", (err) => {
+            console.error(`[gpt-oauth] failed to start proxy: ${err.message}`);
+            if (currentChild === child)
+                currentChild = null;
+        });
         child.stdout?.on("data", (d) => {
             const msg = d.toString().trim();
             if (!msg)

package/lib/videoFrameExtract.js

@@ -1,7 +1,7 @@
 import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { open, readFile, realpath, stat, unlink } from "node:fs/promises";
-import { extname, join, resolve, sep } from "node:path";
+import { extname, isAbsolute, join, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 const MAX_LOCAL_VIDEO_BYTES = 100 * 1024 * 1024;
@@ -12,7 +12,7 @@ function routeError(message, status = 400) {
 }
 export async function safeGeneratedFilePath(generatedDir, file, options = {}) {
     const base = resolve(generatedDir);
-    const target = file.startsWith("/") ? resolve(file) : resolve(base, file);
+    const target = isAbsolute(file) ? resolve(file) : resolve(base, file);
     if (target !== base && !target.startsWith(`${base}${sep}`)) {
         throw routeError("invalid file path", 400);
     }
@@ -54,7 +54,7 @@ export async function assertLocalMp4(path) {
     }
 }
 export async function extractVideoFrame(input, output, position) {
-    const options = { timeout: FFMPEG_TIMEOUT_MS, killSignal: "SIGKILL", maxBuffer: 1024 * 1024 };
+    const options = { timeout: FFMPEG_TIMEOUT_MS, killSignal: (process.platform === "win32" ? "SIGTERM" : "SIGKILL"), maxBuffer: 1024 * 1024 };
     if (position === "last") {
         await execFileAsync("ffmpeg", ["-y", "-sseof", "-3", "-i", input, "-update", "1", "-q:v", "1", output], options);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "1.1.21",
+  "version": "1.1.23",
   "description": "Local OAuth image generation studio with classic and node workflows",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "setup": "node bin/ima2.js setup",
     "prepack": "npm run ui:build && npm run build:server && npm run build:cli",
     "prepublishOnly": "npm run typecheck && npm run typecheck:tests && npm run test:inventory && npm run ui:build && npm run build:server && npm run build:cli && npm run lint:pkg && npm run test:package-install",
-    "lint:pkg": "node -e \"const p=require('./package.json'); const req=['name','version','bin']; for(const k of req){if(!p[k])throw new Error('missing '+k)} const mustInclude=['bin/','lib/','routes/','skills/','integrations/comfyui/ima2_gen_bridge/__init__.py','integrations/comfyui/ima2_gen_bridge/nodes.py','integrations/comfyui/ima2_gen_bridge/README.md','assets/card-news/templates/','vendor/','server.js','LICENSE']; for(const f of mustInclude){if(!p.files.includes(f))throw new Error('files[] must include '+f)}\"",
+    "lint:pkg": "node -e \"const p=require('./package.json'); const req=['name','version','bin']; for(const k of req){if(!p[k])throw new Error('missing '+k)} const mustInclude=['bin/**/*.js','lib/**/*.js','routes/**/*.js','skills/','integrations/comfyui/ima2_gen_bridge/__init__.py','integrations/comfyui/ima2_gen_bridge/nodes.py','integrations/comfyui/ima2_gen_bridge/README.md','assets/card-news/templates/','vendor/','server.js','LICENSE']; for(const f of mustInclude){if(!p.files.includes(f))throw new Error('files[] must include '+f)}\"",
     "publish:dry-run": "node scripts/publish-dry-run.mjs",
     "release:patch": "npm version patch && npm publish && git push origin main --tags",
     "release:minor": "npm version minor && npm publish && git push origin main --tags",
@@ -43,9 +43,9 @@
     "url": "git+https://github.com/lidge-jun/ima2-gen.git"
   },
   "files": [
-    "bin/",
-    "lib/",
-    "routes/",
+    "bin/**/*.js",
+    "lib/**/*.js",
+    "routes/**/*.js",
     "skills/",
     "integrations/comfyui/ima2_gen_bridge/__init__.py",
     "integrations/comfyui/ima2_gen_bridge/nodes.py",
@@ -54,8 +54,6 @@
     "docs/",
     "vendor/",
     "assets/card-news/templates/",
-    "server.ts",
-    "config.ts",
     ".env.example",
     "README.md",
     "LICENSE",

package/routes/capabilities.js

@@ -1,5 +1,6 @@
 import { buildIma2Capabilities } from "../lib/capabilities.js";
 import { requireRuntimeContext } from "../lib/runtimeContext.js";
+const GROK_PLANNER_MODELS = ["grok-4.3", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini"];
 export function registerCapabilitiesRoutes(app, ctxRaw) {
     const ctx = requireRuntimeContext(ctxRaw);
     app.get("/api/capabilities", (_req, res) => {
@@ -10,4 +11,16 @@ export function registerCapabilitiesRoutes(app, ctxRaw) {
             server: ctx.serverUrl || `http://localhost:${ctx.serverActualPort || ctx.config.server.port}`,
         }));
     });
+    app.get("/api/config/grok-planner", (_req, res) => {
+        res.json({ model: ctx.config.grokProvider.plannerModel, options: GROK_PLANNER_MODELS });
+    });
+    app.patch("/api/config/grok-planner", (req, res) => {
+        const model = req.body?.model;
+        if (typeof model !== "string" || !GROK_PLANNER_MODELS.includes(model)) {
+            res.status(400).json({ error: `Invalid model. Options: ${GROK_PLANNER_MODELS.join(", ")}` });
+            return;
+        }
+        ctx.config.grokProvider.plannerModel = model;
+        res.json({ model });
+    });
 }

package/routes/edit.js

@@ -1,4 +1,5 @@
 import { mkdir, writeFile } from "fs/promises";
+import { safeWriteSidecar } from "../lib/atomicWrite.js";
 import { join } from "path";
 import { randomBytes } from "crypto";
 import { detectImageMimeFromB64 } from "../lib/refs.js";
@@ -222,7 +223,7 @@ export function registerEditRoutes(app, ctxRaw) {
                 webSearchCalls,
                 webSearchEnabled,
             };
-            await writeFile(join(ctx.config.storage.generatedDir, filename + ".json"), JSON.stringify(meta)).catch(() => { });
+            await safeWriteSidecar(join(ctx.config.storage.generatedDir, filename + ".json"), meta);
             invalidateHistoryIndex();
             finishHttpStatus = 200;
             finishMeta = { filename, imageChars: resultB64.length };

package/routes/generate.js

@@ -1,4 +1,5 @@
 import { mkdir, readFile, writeFile } from "fs/promises";
+import { safeWriteSidecar, atomicWriteJson } from "../lib/atomicWrite.js";
 import { join } from "path";
 import { randomBytes } from "crypto";
 import { detectImageMimeFromB64, summarizeReferencePayload, validateAndNormalizeRefs } from "../lib/refs.js";
@@ -43,6 +44,30 @@ export function registerGenerateRoutes(app, ctxRaw) {
             const sessionId = typeof req.body?.sessionId === "string" ? req.body.sessionId : null;
             const clientNodeId = typeof req.body?.clientNodeId === "string" ? req.body.clientNodeId : null;
             const { prompt, quality: rawQuality = "medium", size = "1024x1024", format = "png", moderation = "low", provider = "auto", n = 1, references = [], mode: promptMode = "auto", model: rawModel, reasoningEffort: rawReasoningEffort, webSearchEnabled: rawWebSearchEnabled = true, } = req.body;
+            const storyboardActive = req.body?.storyboard === true;
+            const storyboardPrefix = storyboardActive
+                ? [
+                    "[STORYBOARD MODE — Video Production Keyframe]",
+                    "This image is a keyframe for a multi-shot VIDEO storyboard. It will be animated via image-to-video.",
+                    "The prompt and all injected instructions MUST be in English.",
+                    "",
+                    "CHARACTER LOCK:",
+                    "- Identify each character by 2-3 VISUAL identifiers (clothing color + physique + position/props). Never by name alone.",
+                    "- Copy character descriptions VERBATIM from the reference/prior frame. Do NOT rephrase or drift.",
+                    "",
+                    "SCENE CONTINUITY:",
+                    "- Lock lighting direction, color palette, environment, and art style to prior frames.",
+                    "- Change ONLY: action, shot scale, camera angle, or expression.",
+                    "- Reference image = canonical anchor. Preserve it faithfully.",
+                    "",
+                    "VIDEO-READY COMPOSITION:",
+                    "- Frame for animation: leave space for motion, avoid static-only poses.",
+                    "- Use descriptive caption format: shot type + subject action + environment + technical (lens, lighting) + mood.",
+                    "- Specify intended camera movement for the video phase (e.g. 'slow dolly-in', 'static wide').",
+                    "- End pose must be stable and suitable for video continuation.",
+                    "",
+                ].join("\n") + "\n"
+                : "";
             const composerPrompt = normalizeComposerPrompt(req.body?.composerPrompt);
             const composerInsertedPrompts = normalizeComposerInsertedPrompts(req.body?.composerInsertedPrompts);
             const { quality, warnings: qualityWarnings } = normalizeOAuthParams({ provider, quality: rawQuality });
@@ -65,6 +90,7 @@ export function registerGenerateRoutes(app, ctxRaw) {
             const webSearchEnabled = providerOptions.webSearchEnabled;
             const activeProvider = providerOptions.provider;
             const normalizedPromptMode = promptMode === "direct" ? "direct" : "auto";
+            const generationPrompt = storyboardPrefix + prompt;
             if (!prompt)
                 return res.status(400).json({ error: "Prompt is required" });
             const moderationCheck = validateModeration(ctx, moderation);
@@ -140,7 +166,7 @@ export function registerGenerateRoutes(app, ctxRaw) {
             const mime = mimeMap[effectiveFormat] || "image/png";
             await mkdir(ctx.config.storage.generatedDir, { recursive: true });
             const sharedGrokPlan = activeProvider === "grok"
-                ? await planGrokImage(prompt, ctx, {
+                ? await planGrokImage(generationPrompt, ctx, {
                     model: quality === "high" ? "grok-imagine-image-quality" : imageModel,
                     size: effectiveSize,
                     signal: cancelController.signal,
@@ -152,7 +178,7 @@ export function registerGenerateRoutes(app, ctxRaw) {
             const generateOne = async () => {
                 if (activeProvider === "grok") {
                     const grokModel = quality === "high" ? "grok-imagine-image-quality" : imageModel;
-                    const r = await generateViaGrok(prompt, ctx, {
+                    const r = await generateViaGrok(generationPrompt, ctx, {
                         model: grokModel,
                         size: effectiveSize,
                         signal: cancelController.signal,
@@ -168,7 +194,7 @@ export function registerGenerateRoutes(app, ctxRaw) {
                 let lastErr;
                 for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
                     try {
-                        const r = await generateViaResponses(activeProvider, prompt, quality, effectiveSize, moderation, refCheck.refDetails || refCheck.refs, requestId, normalizedPromptMode, ctx, {
+                        const r = await generateViaResponses(activeProvider, generationPrompt, quality, effectiveSize, moderation, refCheck.refDetails || refCheck.refs, requestId, normalizedPromptMode, ctx, {
                             model: imageModel,
                             reasoningEffort,
                             webSearchEnabled,
@@ -260,7 +286,7 @@ export function registerGenerateRoutes(app, ctxRaw) {
                         });
                     }
                     await writeFile(join(ctx.config.storage.generatedDir, filename), embedded.buffer);
-                    await writeFile(join(ctx.config.storage.generatedDir, filename + ".json"), JSON.stringify(meta)).catch(() => { });
+                    await safeWriteSidecar(join(ctx.config.storage.generatedDir, filename + ".json"), meta);
                     invalidateHistoryIndex();
                     images.push({
                         image: `data:${resultMime};base64,${r.value.b64}`,
@@ -346,10 +372,10 @@ export function registerGenerateRoutes(app, ctxRaw) {
                     const sidecarPath = join(ctx.config.storage.generatedDir, filename + ".json");
                     const sidecarMeta = JSON.parse(await readFile(sidecarPath, "utf-8"));
                     sidecarMeta.elapsed = elapsed;
-                    await writeFile(sidecarPath, JSON.stringify(sidecarMeta));
+                    await atomicWriteJson(sidecarPath, sidecarMeta);
                 }
                 catch {
-                    /* best-effort, matches the sidecar write .catch(() => {}) above */
+                    /* best-effort elapsed patch */
                 }
             }));
             const firstRevised = images[0]?.revisedPrompt || null;