ima2-gen 3.12.2 → 3.12.3

package/bin/commands/vectorize.js

@@ -0,0 +1,108 @@
+// wp5: ima2 vectorize - raster-to-SVG tracing. Runs fully local: unlike
+// `upscale`, no server or provider is involved, so the command works offline.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { parseArgs } from "../lib/args.js";
+import { color, die, fail, json, out } from "../lib/output.js";
+import { VECTOR_PRESETS, vectorizeImageBuffer, isVectorPreset } from "../../lib/vectorizeImage.js";
+const SPEC = {
+    flags: {
+        preset: { type: "string" },
+        "color-precision": { type: "string" },
+        "filter-speckle": { type: "string" },
+        "corner-threshold": { type: "string" },
+        "no-optimize": { type: "boolean" },
+        out: { short: "o", type: "string" },
+        "out-dir": { short: "d", type: "string" },
+        json: { type: "boolean" },
+        help: { short: "h", type: "boolean" },
+    },
+};
+const HELP = `
+  ima2 vectorize <image> [options]
+
+  Trace a raster image (png/jpeg/webp) into a real SVG. Runs locally; no server needed.
+
+  Best on cutouts, icons, logos, and flat art. Photographs and small text will smear.
+
+  Options:
+    --preset <auto|flat|detailed|mono>   Trace mode. Default: auto
+    --color-precision <1-8>              Colour bits per channel
+    --filter-speckle <0-128>             Discard patches smaller than N pixels
+    --corner-threshold <0-180>           Minimum angle treated as a corner
+    --no-optimize                        Skip SVG optimization (larger output)
+    -o, --out <file>                     Output path. Default: <input>.svg
+    -d, --out-dir <dir>                  Output directory
+    --json                               Print one JSON result to stdout
+`;
+function parseRange(raw, label, min, max) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < min || n > max)
+        die(2, `${label} must be an integer ${min}-${max}`);
+    return n;
+}
+export default async function vectorizeCmd(argv) {
+    const args = parseArgs(argv, SPEC);
+    if (args.help) {
+        out(HELP);
+        return;
+    }
+    const input = args.positional[0];
+    if (!input)
+        die(2, "usage: ima2 vectorize <image> [options]");
+    const preset = args.preset === undefined ? "auto" : String(args.preset);
+    if (!isVectorPreset(preset)) {
+        die(2, `--preset must be one of: ${VECTOR_PRESETS.join(", ")}`);
+    }
+    const colorPrecision = parseRange(args["color-precision"], "--color-precision", 1, 8);
+    const filterSpeckle = parseRange(args["filter-speckle"], "--filter-speckle", 0, 128);
+    const cornerThreshold = parseRange(args["corner-threshold"], "--corner-threshold", 0, 180);
+    const inputPath = resolve(String(input));
+    const stem = basename(inputPath, extname(inputPath));
+    const target = args.out
+        ? resolve(String(args.out))
+        : args["out-dir"]
+            ? join(resolve(String(args["out-dir"])), `${stem}.svg`)
+            : join(dirname(inputPath), `${stem}.svg`);
+    try {
+        const source = await readFile(inputPath);
+        const result = await vectorizeImageBuffer(source, {
+            preset,
+            // Omit an unset knob: any value counts as an override and would bypass
+            // the tuned preset.
+            ...(colorPrecision !== undefined ? { colorPrecision } : {}),
+            ...(filterSpeckle !== undefined ? { filterSpeckle } : {}),
+            ...(cornerThreshold !== undefined ? { cornerThreshold } : {}),
+            optimize: !args["no-optimize"],
+        });
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, result.svg, "utf8");
+        if (args.json) {
+            json({
+                ok: true,
+                input: inputPath,
+                output: target,
+                preset: result.preset,
+                pathCount: result.pathCount,
+                bytes: result.bytes,
+                elapsedMs: result.elapsedMs,
+                width: result.width,
+                height: result.height,
+            });
+        }
+        else {
+            out(color.green("OK ") + `${target} (${result.pathCount} paths, ${Math.round(result.bytes / 1024)}KB)`);
+        }
+    }
+    catch (error) {
+        const typed = error;
+        fail({
+            json: Boolean(args.json),
+            code: typed.code ?? "VECTORIZE_FAILED",
+            message: typed.message,
+            exitCode: 1,
+        });
+    }
+}

package/bin/ima2.js

@@ -344,6 +344,9 @@ function showHelp() {
     stop           Stop the running server safely (graceful, then signals)
     service        Background service management (install/status/... ; -h)
 
+  Local commands (no running server needed):
+    vectorize <image>  Trace a raster image into SVG   (ima2 vectorize --help)
+
   Agent skills (SKILL.md + references/):
     skill ls                         List packaged skills (ima2, front, uiux)
     skill [front|uiux]               Print a skill's SKILL.md
@@ -402,7 +405,7 @@ if (args.includes("-v") || args.includes("--version")) {
     console.log(pkg.version);
     exitFlushed(0);
 }
-const helpOwningCommands = ["doctor", "gen", "video", "edit", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "config", "defaults", "models", "capabilities", "tools", "skill", "ping", "backfill-thumbs", "service"];
+const helpOwningCommands = ["doctor", "gen", "video", "edit", "vectorize", "ls", "show", "ps", "cancel", "session", "history", "prompt", "multimode", "node", "annotate", "canvas-versions", "metadata", "comfy", "cardnews", "inflight", "storage", "billing", "providers", "oauth", "grok", "config", "defaults", "models", "capabilities", "tools", "skill", "ping", "backfill-thumbs", "service"];
 if (!command) {
     showHelp();
     exitFlushed(1);
@@ -468,6 +471,7 @@ switch (command) {
     case "video":
     case "upscale":
     case "edit":
+    case "vectorize":
     case "ls":
     case "show":
     case "ps":

package/docs/API.md

@@ -600,7 +600,7 @@ files inside `generated/`; deleting an asset never deletes the file.
 | `GET` | `/api/assets/:id` | Fetch one asset by ID; returns `404 ASSET_NOT_FOUND` when absent |
 | `POST` | `/api/assets` | Promote/create an asset (`filePath`, `kind`, `name?`, `folderId?`, `tags?`, `metadata?`) |
 | `POST` | `/api/assets/promote-element` | Promote a gallery result to an `element` asset (`result.path` or `filePath`, `elementKind`, `name?`, `notes?`, `folderId?`, `tags?`) |
-| `POST` | `/api/assets/derived` | Save a derived asset (raw `image/png` body; query `source`, `kind=keyed-png`, `projectId?`, `name?`, `meta?` JSON) — writes `<src>-keyed-<ts>.png` + sidecar with `derivedFrom` and registers an asset record |
+| `POST` | `/api/assets/derived` | Save a derived asset (raw `image/png` body; query `source`, `kind=keyed-png`, `projectId?`, `name?`, `meta?` JSON) — writes `<src>-keyed-<ts>.png` + sidecar with `derivedFrom` and registers an asset record `kind=vector-svg` sends NO body: the server reads the validated `source` from generated storage, traces it via `lib/vectorizeImage.ts`, and writes `<src>-vector-<ts>.svg` (query `preset?`, `colorPrecision?`, `filterSpeckle?`, `cornerThreshold?`; a non-raster source is refused with `DERIVED_SOURCE_NOT_RASTER`). Traced SVGs are served with a restrictive CSP and `nosniff`. |
 | `POST` | `/api/video/keying` | Derive an alpha WebM from a generated green-screen mp4 (`source`, `keyParams{tolerance,softness,keyColor?}`, `projectId?`, `name?`) — responds `202 {requestId, filePath}`, publishes `keying-start/progress/done/error` on the event bus, writes sidecar with `derivedFrom` and registers a video asset |
 | `PATCH` | `/api/assets/:id` | Update name/folder/notes/tags/metadata |
 | `POST` | `/api/assets/:id/test-sheet` | Run an element test sheet; currently returns `501 TEST_SHEET_NOT_IMPLEMENTED` after validating the element asset |

package/docs/API.zh-CN.md

@@ -585,7 +585,7 @@ Grok视频 API 使用的提示界面：
 | `GET` | `/api/assets/:id` |通过ID获取一项资产；回报`404 ASSET_NOT_FOUND`当缺席时|
 | `POST` | `/api/assets` |推广/创建资产（`filePath`, `kind`, `name?`, `folderId?`, `tags?`, `metadata?`) |
 | `POST` | `/api/assets/promote-element` |将图库结果推广到`element`资产 （`result.path`或者`filePath`, `elementKind`, `name?`, `notes?`, `folderId?`, `tags?`) |
-| `POST` | `/api/assets/derived` |保存派生资产（原始资产`image/png`身体;询问`source`, `kind=keyed-png`, `projectId?`, `name?`, `meta?` JSON）——写道`<src>-keyed-<ts>.png`+ 边车与`derivedFrom`并登记资产记录|
+| `POST` | `/api/assets/derived` |保存派生资产（原始资产`image/png`身体;询问`source`, `kind=keyed-png`, `projectId?`, `name?`, `meta?` JSON）——写道`<src>-keyed-<ts>.png`+ 边车与`derivedFrom`并登记资产记录 `kind=vector-svg` 不发送请求体：服务器直接读取已校验的 `source` 并通过 `lib/vectorizeImage.ts` 转换，写出 `<src>-vector-<ts>.svg`（查询参数 `preset?`、`colorPrecision?`、`filterSpeckle?`、`cornerThreshold?`；非栅格源以 `DERIVED_SOURCE_NOT_RASTER` 拒绝）。生成的 SVG 附带严格 CSP 与 `nosniff`。 |
 | `POST` | `/api/video/keying` |从生成的绿屏 mp4 导出 alpha WebM (`source`, `keyParams{tolerance,softness,keyColor?}`, `projectId?`, `name?`) — 回应`202 {requestId, filePath}`，发布`keying-start/progress/done/error`在事件总线上，写入 sidecar`derivedFrom`并注册视频资产|
 | `PATCH` | `/api/assets/:id` |更新名称/文件夹/注释/标签/元数据|
 | `POST` | `/api/assets/:id/test-sheet` |运行元素测试表；目前返回`501 TEST_SHEET_NOT_IMPLEMENTED`验证元素资产后|

package/docs/API.zh-TW.md

@@ -585,7 +585,7 @@ Grok視訊 API 使用的提示介面：
 | `GET` | `/api/assets/:id` |透過ID獲取一項資產；回報`404 ASSET_NOT_FOUND`當缺席時|
 | `POST` | `/api/assets` |推廣/創建資產（`filePath`, `kind`, `name?`, `folderId?`, `tags?`, `metadata?`) |
 | `POST` | `/api/assets/promote-element` |將圖庫結果推廣到`element`資產 （`result.path`或者`filePath`, `elementKind`, `name?`, `notes?`, `folderId?`, `tags?`) |
-| `POST` | `/api/assets/derived` |保存派生資產（原始資產`image/png`身體;詢問`source`, `kind=keyed-png`, `projectId?`, `name?`, `meta?` JSON）——寫道`<src>-keyed-<ts>.png`+ 邊車與`derivedFrom`並登記資產記錄|
+| `POST` | `/api/assets/derived` |保存派生資產（原始資產`image/png`身體;詢問`source`, `kind=keyed-png`, `projectId?`, `name?`, `meta?` JSON）——寫道`<src>-keyed-<ts>.png`+ 邊車與`derivedFrom`並登記資產記錄 `kind=vector-svg` 不傳送請求主體：伺服器直接讀取已驗證的 `source` 並透過 `lib/vectorizeImage.ts` 轉換，寫出 `<src>-vector-<ts>.svg`（查詢參數 `preset?`、`colorPrecision?`、`filterSpeckle?`、`cornerThreshold?`；非點陣來源以 `DERIVED_SOURCE_NOT_RASTER` 拒絕）。產生的 SVG 附帶嚴格 CSP 與 `nosniff`。 |
 | `POST` | `/api/video/keying` |從生成的綠幕 mp4 匯出 alpha WebM (`source`, `keyParams{tolerance,softness,keyColor?}`, `projectId?`, `name?`) — 回應`202 {requestId, filePath}`，發布`keying-start/progress/done/error`在事件總線上，寫入 sidecar`derivedFrom`並註冊視訊資產|
 | `PATCH` | `/api/assets/:id` |更新名稱/資料夾/註釋/標籤/元數據|
 | `POST` | `/api/assets/:id/test-sheet` |運行元素測試表；目前返回`501 TEST_SHEET_NOT_IMPLEMENTED`驗證元素資產後|

package/docs/CLI.md

@@ -322,6 +322,7 @@ Windows DNS/fragmentation bypass tool such as SecretDNS is in use.
 | `ima2 history favorite <name>` | Toggle favorite (sends `X-Ima2-Browser-Id`) |
 | `ima2 history import <file>` | Import a local image (raw PNG/JPEG/WEBP) into history |
 | `ima2 metadata <file>` | Read embedded metadata from any local image (no server roundtrip needed for the read itself, but the route lives on the server) |
+| `ima2 vectorize <image> [-o <file>] [--preset auto\|flat\|detailed\|mono] [--json]` | Trace a local raster (png/jpeg/webp) into a real SVG. Runs fully local. Best on cutouts, icons, logos and flat art; photographs and small text smear |
 
 ## Sessions and graphs
 

package/docs/migration/runtime-test-inventory.md

@@ -4,9 +4,10 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 407 (runtime: 188, contract: 219)
+Total: 412 (runtime: 191, contract: 221)
 
 ## Runtime-importing tests
+- `tests/agent-image-reference-contract.test.ts`
 - `tests/agent-mode-auto-planner-contract.test.ts`
 - `tests/agent-mode-llm-planner-contract.test.ts`
 - `tests/agent-mode-parallel-contract.test.ts`
@@ -23,6 +24,7 @@ Total: 407 (runtime: 188, contract: 219)
 - `tests/api-cache-policy.test.ts`
 - `tests/api-provider-parity.test.ts`
 - `tests/asset-character-bindings.test.ts`
+- `tests/asset-derived-vector-contract.test.ts`
 - `tests/asset-derived.test.ts`
 - `tests/asset-ref-contract.test.ts`
 - `tests/assets-routes-contract.test.ts`
@@ -181,6 +183,7 @@ Total: 407 (runtime: 188, contract: 219)
 - `tests/transparent-alpha-verification.test.ts`
 - `tests/transparent-background-contract.test.ts`
 - `tests/transparent-background-route.test.ts`
+- `tests/vectorize-image-contract.test.ts`
 - `tests/video-chroma-key.test.ts`
 - `tests/video-concat.test.ts`
 - `tests/video-history-item.test.ts`
@@ -406,6 +409,8 @@ Total: 407 (runtime: 188, contract: 219)
 - `tests/ui-radius-scale-contract.test.ts`
 - `tests/ui-touch-target-contract.test.ts`
 - `tests/ui-typography-rules-contract.test.ts`
+- `tests/vectorize-cli-contract.test.ts`
+- `tests/vectorize-panel-contract.test.ts`
 - `tests/video-continuity-ui-contract.test.js`
 - `tests/video-defaults-persistence-contract.test.js`
 - `tests/video-extend-ui-contract.test.js`

package/lib/agentImageVideoGen.js

@@ -123,7 +123,12 @@ async function generateAgentImage(ctx, sessionId, prompt, manifest, webSearchEna
                             references: await loadAgentCurrentImageReferences(ctx, sessionId, options.sourceImagePolicy ?? "none"),
                             plannerModel: grokPlannerModel,
                         })
-                        : await generateViaResponses(activeProvider, `${manifest}\n\nUser request:\n${prompt}`, options.quality ?? "medium", providerOptions.size, options.moderation ?? "low", [], requestId, "auto", ctx, {
+                        : await generateViaResponses(activeProvider, `${manifest}\n\nUser request:\n${prompt}`, options.quality ?? "medium", providerOptions.size, options.moderation ?? "low", 
+                        // The session image must reach the model here too. atlascloud/minimax/grok
+                        // all forward it; this branch used to pass [], so on the default OAuth/API
+                        // path the model was asked to edit an image it could not see and answered in
+                        // prose - which classifies as a retryable no-image result (issue #192).
+                        await loadAgentCurrentImageReferences(ctx, sessionId, options.sourceImagePolicy ?? "none"), requestId, "auto", ctx, {
                             model: providerOptions.model,
                             reasoningEffort: providerOptions.reasoningEffort,
                             webSearchEnabled,
@@ -132,6 +137,15 @@ async function generateAgentImage(ctx, sessionId, prompt, manifest, webSearchEna
     const format = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "atlascloud" || activeProvider === "minimax" || activeProvider === "nai"
         ? imageFormatFromMime(("mime" in response ? response.mime : undefined) || detectImageMimeFromB64(response.b64) || "image/jpeg")
         : options.format ?? "png";
+    if (!response.b64) {
+        // agy and atlascloud can resolve with an empty payload (0-byte artifact or a
+        // 0-byte HTTP 200 body). Without this guard persistAgentImage writes a 0-byte
+        // file and registers it as a real image, which is worse than an error.
+        const emptyErr = new Error("Provider returned an empty image.");
+        emptyErr.code = "PROVIDER_EMPTY_IMAGE";
+        emptyErr.status = 502;
+        throw emptyErr;
+    }
     const image = await persistAgentImage(ctx, sessionId, prompt, format, providerOptions.size, requestId, response, {
         provider: String(activeProvider),
         model: String(effectiveModel),

package/lib/agentQueueStore.js

@@ -32,6 +32,7 @@ export function getAgentQueueItem(id) {
       result_image_ids AS resultImageIds,
       error_code AS errorCode,
       error_class AS errorClass,
+      error_raw_code AS errorRawCode,
       error_message AS errorMessage,
       progress_stage AS progressStage,
       created_at AS createdAt,
@@ -57,6 +58,7 @@ export function listAgentQueueItems(sessionId) {
       result_image_ids AS resultImageIds,
       error_code AS errorCode,
       error_class AS errorClass,
+      error_raw_code AS errorRawCode,
       error_message AS errorMessage,
       progress_stage AS progressStage,
       created_at AS createdAt,
@@ -97,6 +99,7 @@ export function claimNextAgentQueueItem(limits) {
       result_image_ids AS resultImageIds,
       error_code AS errorCode,
       error_class AS errorClass,
+      error_raw_code AS errorRawCode,
       error_message AS errorMessage,
       progress_stage AS progressStage,
       created_at AS createdAt,
@@ -112,7 +115,7 @@ export function claimNextAgentQueueItem(limits) {
             continue;
         const res = getDb().prepare(`
       UPDATE agent_queue_items
-      SET status = 'running', started_at = ?, progress_stage = NULL, error_code = NULL, error_class = NULL, error_message = NULL
+      SET status = 'running', started_at = ?, progress_stage = NULL, error_code = NULL, error_class = NULL, error_raw_code = NULL, error_message = NULL
       WHERE id = ? AND status = 'queued'
     `).run(Date.now(), row.id);
         if (res.changes > 0)
@@ -129,6 +132,7 @@ export function completeAgentQueueItem(id, imageIds) {
         progress_stage = NULL,
         error_code = NULL,
         error_class = NULL,
+        error_raw_code = NULL,
         error_message = NULL
     WHERE id = ? AND status = 'running'
   `).run(JSON.stringify([...imageIds]), Date.now(), id);
@@ -139,16 +143,17 @@ export function failAgentQueueItem(id, error) {
     SET status = 'failed',
         error_code = ?,
         error_class = ?,
+        error_raw_code = ?,
         error_message = ?,
         finished_at = ?,
         progress_stage = NULL
     WHERE id = ? AND status = 'running'
-  `).run(error.code ?? "AGENT_QUEUE_FAILED", error.errorClass ?? null, error.message, Date.now(), id);
+  `).run(error.code ?? "AGENT_QUEUE_FAILED", error.errorClass ?? null, error.rawCode ?? null, error.message, Date.now(), id);
 }
 export function cancelAgentQueueItem(id, reason = "Canceled by user") {
     const res = getDb().prepare(`
     UPDATE agent_queue_items
-    SET status = 'canceled', error_code = 'canceled', error_class = NULL, error_message = ?, finished_at = ?, progress_stage = NULL
+    SET status = 'canceled', error_code = 'canceled', error_class = NULL, error_raw_code = NULL, error_message = ?, finished_at = ?, progress_stage = NULL
     WHERE id = ? AND status IN ('queued', 'running')
   `).run(reason, Date.now(), id);
     return res.changes > 0;
@@ -220,6 +225,7 @@ export function retryAgentQueueItem(id) {
         result_image_ids = '[]',
         error_code = NULL,
         error_class = NULL,
+        error_raw_code = NULL,
         error_message = NULL,
         progress_stage = NULL,
         started_at = NULL,
@@ -243,6 +249,8 @@ function queueItemFromRow(row) {
         // (cancellation, timeout) must carry no class at all, matching the rule
         // that nothing invents a class for non-provider errors.
         ...(row.errorClass ? { errorClass: row.errorClass } : {}),
+        // Same omit-rather-than-null rule: only a real provider cause carries a rawCode.
+        ...(row.errorRawCode ? { errorRawCode: row.errorRawCode } : {}),
         errorMessage: row.errorMessage,
         progressStage: row.progressStage ?? null,
         createdAt: row.createdAt,

package/lib/agentQueueWorker.js

@@ -167,7 +167,12 @@ async function runClaimedQueueItem(ctx, itemId) {
         }
         const err = errInfo(error);
         const timedOut = timeoutController.signal.aborted;
-        const failure = timedOut ? { code: "timeout", message: "timeout" } : { code: err.code, message: err.message, ...errorEnvelopeFields(err.raw) };
+        const envelope = errorEnvelopeFields(err.raw);
+        const failure = timedOut
+            ? { code: "timeout", message: "timeout" }
+            // rawCode must reach the DB: the Agent composer reads the QUEUE, so without it
+            // the user only ever sees the generic wrapper code (issue #192).
+            : { code: err.code, message: err.message, ...envelope };
         failAgentQueueItem(item.id, failure);
         // The chat pane must never fail silently — surface the failure as an
         // assistant error turn unless the runtime already recorded one.

package/lib/agentRuntime.js

@@ -303,6 +303,10 @@ const RETRYABLE_NO_IMAGE_CODES = new Set([
     "WEB_SEARCH_ONLY_RESPONSE",
     "IMAGE_TOOL_COMPLETED_WITHOUT_RESULT",
     "IMAGE_TOOL_FAILED",
+    // A 0-byte provider payload is the same class of transient as IMAGE_TOOL_FAILED:
+    // an empty CDN download usually succeeds on an immediate retry. If the second
+    // attempt is also empty the user still gets this specific code.
+    "PROVIDER_EMPTY_IMAGE",
 ]);
 export function isTextOnlyResult(error) {
     const err = errInfo(error);

package/lib/db.js

@@ -236,6 +236,9 @@ function migrate(database) {
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "result_image_ids", "TEXT NOT NULL DEFAULT '[]'");
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "error_code", "TEXT");
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "error_class", "TEXT");
+    // The wrapper code alone (AGENT_TEXT_ONLY_RESULT) tells the user nothing about WHY.
+    // The worker already computes rawCode; without this column it was dropped here.
+    addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "error_raw_code", "TEXT");
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "error_message", "TEXT");
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "progress_stage", "TEXT");
     addColumnIfMissing(database, agentQueueColumns, "agent_queue_items", "started_at", "INTEGER");

package/lib/imageThumb.js

@@ -4,11 +4,18 @@ const THUMB_WIDTH = 320;
 const THUMB_QUALITY = 70;
 // Guard against decompression-bomb memory exhaustion (default sharp limit is 268M px).
 const MAX_INPUT_PIXELS = 100_000_000; // 100MP (e.g. ~10000x10000)
+const RASTERIZABLE = /\.(png|jpe?g|webp)$/i;
 export function thumbPathForImage(imagePath) {
-    return imagePath.replace(/\.(png|jpe?g|webp)$/i, ".thumb.jpg");
+    // A non-raster path must never map onto itself: returning the input unchanged
+    // would make callers treat the original as its own thumbnail and overwrite it.
+    if (!RASTERIZABLE.test(imagePath))
+        return `${imagePath}.thumb.jpg`;
+    return imagePath.replace(RASTERIZABLE, ".thumb.jpg");
 }
 export function thumbUrlForImage(imageUrl) {
-    return imageUrl.replace(/\.(png|jpe?g|webp)$/i, ".thumb.jpg");
+    if (!RASTERIZABLE.test(imageUrl))
+        return `${imageUrl}.thumb.jpg`;
+    return imageUrl.replace(RASTERIZABLE, ".thumb.jpg");
 }
 export async function generateImageThumbnail(imagePath) {
     const thumbPath = thumbPathForImage(imagePath);

package/lib/vectorizeImage.js

@@ -0,0 +1,132 @@
+import { ColorMode, Hierarchical, PathSimplifyMode, Preset, optimize, vectorize, } from "@neplex/vectorizer";
+import sharp from "sharp";
+/**
+ * Raster -> SVG tracing (VTracer core).
+ *
+ * Traces bitmap regions into real vector paths. This is the opposite of
+ * ui/src/lib/canvas/svgExport.ts, which embeds a raster <image> inside SVG
+ * chrome without converting any pixels.
+ *
+ * Quality boundary (measured, see devlog/_plan/260831_vectorize_assets/000_plan.md):
+ * keyed cutouts, flat art, logos and sprites trace cleanly; photographic gradients
+ * and small text degrade. Callers should present it as a cutout/flat-art tool.
+ */
+export const VECTOR_PRESETS = ["auto", "flat", "detailed", "mono"];
+/** Tracing cost scales with area; mirrors the decompression-bomb guard in imageThumb. */
+const MAX_INPUT_BYTES = 40 * 1024 * 1024;
+const MAX_INPUT_DIMENSION = 8000;
+const MAX_OUTPUT_BYTES = 24 * 1024 * 1024;
+const RASTER_INPUT = /\.(png|jpe?g|webp)$/i;
+export function isRasterPath(path) {
+    return RASTER_INPUT.test(path);
+}
+export function isVectorPreset(value) {
+    return typeof value === "string" && VECTOR_PRESETS.includes(value);
+}
+function vectorizeError(status, code, message) {
+    const error = new Error(message);
+    error.status = status;
+    error.code = code;
+    return error;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Base config per named preset. Numeric overrides promote a preset to an explicit
+ * Config so a caller can tune one axis without restating all nine fields.
+ */
+function baseConfig(preset) {
+    const shared = {
+        hierarchical: Hierarchical.Stacked,
+        mode: PathSimplifyMode.Spline,
+        layerDifference: 5,
+        lengthThreshold: 5,
+        maxIterations: 2,
+        spliceThreshold: 45,
+        pathPrecision: 5,
+    };
+    if (preset === "mono") {
+        return { ...shared, colorMode: ColorMode.Binary, colorPrecision: 6, filterSpeckle: 4, cornerThreshold: 60 };
+    }
+    if (preset === "flat") {
+        return { ...shared, colorMode: ColorMode.Color, colorPrecision: 6, filterSpeckle: 8, cornerThreshold: 60 };
+    }
+    return { ...shared, colorMode: ColorMode.Color, colorPrecision: 8, filterSpeckle: 4, cornerThreshold: 60 };
+}
+function hasOverride(options) {
+    return options.colorPrecision !== undefined
+        || options.filterSpeckle !== undefined
+        || options.cornerThreshold !== undefined;
+}
+/**
+ * Without overrides we pass the library's own Preset enum: measured on a 1254x1254
+ * keyed asset, Preset.Photo produced 722 paths against Poster's 4993 at visually
+ * indistinguishable quality, so it is the default for colour work.
+ */
+function resolveConfig(preset, options) {
+    if (!hasOverride(options)) {
+        if (preset === "mono")
+            return Preset.Bw;
+        if (preset === "flat")
+            return baseConfig("flat");
+        return Preset.Photo;
+    }
+    const config = baseConfig(preset);
+    if (options.colorPrecision !== undefined)
+        config.colorPrecision = clamp(Math.round(options.colorPrecision), 1, 8);
+    if (options.filterSpeckle !== undefined)
+        config.filterSpeckle = clamp(Math.round(options.filterSpeckle), 0, 128);
+    if (options.cornerThreshold !== undefined)
+        config.cornerThreshold = clamp(Math.round(options.cornerThreshold), 0, 180);
+    return config;
+}
+async function probeDimensions(input) {
+    try {
+        const meta = await sharp(input).metadata();
+        return { width: meta.width ?? 0, height: meta.height ?? 0 };
+    }
+    catch {
+        throw vectorizeError(400, "VECTORIZE_DECODE_FAILED", "input could not be decoded as a raster image");
+    }
+}
+function countPaths(svg) {
+    return (svg.match(/<path/g) || []).length;
+}
+/** Trace an encoded raster buffer into an SVG document. */
+export async function vectorizeImageBuffer(input, options = {}) {
+    if (!Buffer.isBuffer(input) || input.length === 0) {
+        throw vectorizeError(400, "VECTORIZE_INPUT_EMPTY", "input buffer is empty");
+    }
+    if (input.length > MAX_INPUT_BYTES) {
+        throw vectorizeError(400, "VECTORIZE_INPUT_TOO_LARGE", "input exceeds 40MB");
+    }
+    const { width, height } = await probeDimensions(input);
+    if (width > MAX_INPUT_DIMENSION || height > MAX_INPUT_DIMENSION) {
+        throw vectorizeError(400, "VECTORIZE_DIMENSIONS_TOO_LARGE", "input exceeds " + MAX_INPUT_DIMENSION + "px on a side");
+    }
+    const preset = isVectorPreset(options.preset) ? options.preset : "auto";
+    const started = Date.now();
+    let svg;
+    try {
+        svg = await vectorize(input, resolveConfig(preset, options));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw vectorizeError(400, "VECTORIZE_DECODE_FAILED", "tracing failed: " + message);
+    }
+    if (options.optimize !== false) {
+        try {
+            svg = await optimize(svg, { multipass: true });
+        }
+        catch {
+            // Optimization is a size win, not a correctness requirement: a failure here
+            // must not discard an otherwise valid trace.
+        }
+    }
+    const bytes = Buffer.byteLength(svg, "utf8");
+    if (bytes > MAX_OUTPUT_BYTES) {
+        throw vectorizeError(413, "VECTORIZE_OUTPUT_TOO_LARGE", "traced SVG exceeds 24MB");
+    }
+    return { svg, bytes, pathCount: countPaths(svg), elapsedMs: Date.now() - started, preset, width, height };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "3.12.2",
+  "version": "3.12.3",
   "packageManager": "npm@11.18.0",
   "description": "Local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.",
   "type": "module",
@@ -18,7 +18,7 @@
     "ui:build": "cd ui && npm run build",
     "build": "npm run ui:build",
     "test": "node scripts/run-tests.mjs",
-    "test:native-deps": "node -e \"require('better-sqlite3'); require('sharp')\"",
+    "test:native-deps": "node -e \"require('better-sqlite3'); require('sharp'); require('@neplex/vectorizer')\"",
     "test:install-policy": "node scripts/check-install-policy.mjs",
     "test:install-policy:npm12": "node scripts/check-install-policy.mjs --npm-pending",
     "test:package-install": "node --test tests/package-install-smoke.mjs",
@@ -89,6 +89,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
+    "@neplex/vectorizer": "0.1.0",
     "@openai/codex": "0.149.1",
     "better-sqlite3": "^13.0.3",
     "dotenv": "^17.4.2",
@@ -120,5 +121,5 @@
     "typescript": "^5.9.3",
     "yaml": "2.9.0"
   },
-  "gitHead": "7f7a581901cc4e91b6387e1dbc4e757d4b0f700f"
+  "gitHead": "9cd60ac1fe483887bd25147679f385c58209ed4f"
 }