ima2-gen 1.1.4 → 1.1.5

package/config.js

@@ -74,6 +74,11 @@ export const config = {
   },
   limits: {
     maxRefB64Bytes: pickInt(env.IMA2_MAX_REF_B64_BYTES, fileCfg.limits?.maxRefB64Bytes, 7 * 1024 * 1024),
+    maxMetadataReadB64Bytes: pickInt(
+      env.IMA2_MAX_METADATA_READ_B64_BYTES,
+      fileCfg.limits?.maxMetadataReadB64Bytes,
+      12 * 1024 * 1024,
+    ),
     maxRefCount: pickInt(env.IMA2_MAX_REF_COUNT, fileCfg.limits?.maxRefCount, 5),
     maxParallel: pickInt(env.IMA2_MAX_PARALLEL, fileCfg.limits?.maxParallel, 8),
     graphMaxNodes: pickInt(env.IMA2_GRAPH_MAX_NODES, fileCfg.limits?.graphMaxNodes, 500),

package/lib/db.js

@@ -96,12 +96,50 @@ function migrate(database) {
     );
   }
 
+  // ── Prompt Library (schema v4) ──
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS prompt_folders (
+      id          TEXT PRIMARY KEY,
+      parent_id   TEXT NOT NULL,
+      name        TEXT NOT NULL COLLATE NOCASE,
+      created_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+      updated_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+      UNIQUE(parent_id, name)
+    );
+
+    CREATE TABLE IF NOT EXISTS prompts (
+      id            TEXT PRIMARY KEY,
+      folder_id     TEXT NOT NULL DEFAULT '__root__',
+      name          TEXT NOT NULL,
+      text          TEXT NOT NULL,
+      tags          TEXT,
+      mode          TEXT,
+      is_favorite   INTEGER NOT NULL DEFAULT 0,
+      favorited_at  INTEGER,
+      created_at    INTEGER NOT NULL DEFAULT (unixepoch()),
+      updated_at    INTEGER NOT NULL DEFAULT (unixepoch()),
+      FOREIGN KEY (folder_id) REFERENCES prompt_folders(id) ON DELETE SET DEFAULT
+    );
+
+    CREATE TABLE IF NOT EXISTS gallery_favorites (
+      id            TEXT PRIMARY KEY,
+      browser_id    TEXT NOT NULL,
+      filename      TEXT NOT NULL,
+      favorited_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+      UNIQUE(browser_id, filename)
+    );
+
+    INSERT OR IGNORE INTO prompt_folders (id, parent_id, name) VALUES
+      ('__root__', '__root__', '__root__'),
+      ('__trash__', '__root__', '__trash__');
+  `);
+
   const row = database.prepare("SELECT value FROM _meta WHERE key = 'schema_version'").get();
   if (!row) {
-    database.prepare("INSERT INTO _meta (key, value) VALUES ('schema_version', '3')").run();
-  } else if (row.value !== "3") {
+    database.prepare("INSERT INTO _meta (key, value) VALUES ('schema_version', '4')").run();
+  } else if (row.value !== "4") {
     database
-      .prepare("UPDATE _meta SET value = '3' WHERE key = 'schema_version'")
+      .prepare("UPDATE _meta SET value = '4' WHERE key = 'schema_version'")
       .run();
   }
 }

package/lib/generationErrors.js

@@ -12,6 +12,19 @@ const PASSTHROUGH_CODES = new Set([
 
 const SAFETY_CODES = new Set(["SAFETY_REFUSAL", "MODERATION_REFUSED", "moderation_blocked"]);
 
+function has4kSize(size) {
+  if (typeof size !== "string") return false;
+  const [w, h] = size.split("x").map((part) => Number(part));
+  return Number.isFinite(w) && Number.isFinite(h) && Math.max(w, h) >= 3840;
+}
+
+function diagnosticReasonFrom(err) {
+  if (typeof err?.diagnosticReason === "string" && err.diagnosticReason) return err.diagnosticReason;
+  if (Number(err?.referenceMismatchCount) > 0) return "reference_mime_mismatch_candidate";
+  if (has4kSize(err?.size)) return "experimental_4k_empty_response";
+  return null;
+}
+
 export function errorCodeFrom(err) {
   if (!err) return "UNKNOWN";
   const upstreamCode = classifyUpstreamErrorCode(err.upstreamCode);
@@ -86,6 +99,17 @@ export function normalizeGenerationFailure(lastErr, options = {}) {
     if (lastErr.size) err.size = lastErr.size;
     if (lastErr.quality) err.quality = lastErr.quality;
     if (lastErr.model) err.model = lastErr.model;
+    if (typeof lastErr.eventCount === "number") err.eventCount = lastErr.eventCount;
+    if (lastErr.eventTypes) err.eventTypes = lastErr.eventTypes;
+    if (typeof lastErr.refsCount === "number") err.refsCount = lastErr.refsCount;
+    if (typeof lastErr.inputImageCount === "number") err.inputImageCount = lastErr.inputImageCount;
+    if (Array.isArray(lastErr.referenceDiagnostics)) err.referenceDiagnostics = lastErr.referenceDiagnostics;
+    if (typeof lastErr.referenceMismatchCount === "number") err.referenceMismatchCount = lastErr.referenceMismatchCount;
+    if (lastErr.retryKind) err.retryKind = lastErr.retryKind;
+    if (typeof lastErr.referencesDroppedOnRetry === "boolean") err.referencesDroppedOnRetry = lastErr.referencesDroppedOnRetry;
+    if (typeof lastErr.developerPromptDroppedOnRetry === "boolean") err.developerPromptDroppedOnRetry = lastErr.developerPromptDroppedOnRetry;
+    const diagnosticReason = diagnosticReasonFrom(lastErr);
+    if (diagnosticReason) err.diagnosticReason = diagnosticReason;
     return err;
   }
   // Unrecognized errors → UNKNOWN (do not pretend they are safety refusals)

package/lib/historyList.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, readdir, stat } from "fs/promises";
 import { dirname, join } from "path";
 import { config } from "../config.js";
+import { readEmbeddedImageMetadataFromFile } from "./imageMetadataStore.js";
 
 async function listImageFiles(baseDir) {
   const out = [];
@@ -28,7 +29,7 @@ export async function listHistoryRows(baseDir = config.storage.generatedDir) {
   const setRows = await listCardNewsSetRows(baseDir);
   const rows = await Promise.all(imgs.map(async ({ full, rel, name }) => {
     const st = await stat(full).catch(() => null);
-    const meta = await readImageSidecar(full, rel);
+    const meta = await readImageMetadata(full, rel);
     return {
       filename: rel,
       url: `/generated/${rel.split("/").map(encodeURIComponent).join("/")}`,
@@ -81,6 +82,18 @@ async function readImageSidecar(full, rel) {
   return null;
 }
 
+async function readImageMetadata(full, rel) {
+  const sidecar = await readImageSidecar(full, rel);
+  if (sidecar) return sidecar;
+  try {
+    const embedded = await readEmbeddedImageMetadataFromFile(full);
+    return embedded.metadata;
+  } catch (e) {
+    if (e.code !== "ENOENT") console.warn("[history] embedded metadata read fail:", rel, e.message);
+    return null;
+  }
+}
+
 async function listCardNewsSetRows(baseDir) {
   const root = join(baseDir, "cardnews");
   const entries = await readdir(root, { withFileTypes: true }).catch(() => []);

package/lib/imageMetadata.js

@@ -0,0 +1,107 @@
+export const IMA2_METADATA_SCHEMA = "ima2.generation.v1";
+export const IMA2_XMP_NAMESPACE = "https://github.com/lidge-jun/ima2-gen/ns/1.0/";
+export const IMA2_XMP_PROPERTY = "GenerationMetadata";
+export const MAX_EMBEDDED_METADATA_CHARS = 64 * 1024;
+
+function isPlainObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringOrNull(value, max = 4000) {
+  if (typeof value !== "string") return null;
+  return value.slice(0, max);
+}
+
+function numberOrNull(value) {
+  return Number.isFinite(value) ? value : null;
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function xmlUnescape(value) {
+  return String(value)
+    .replace(/&quot;/g, "\"")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+export function buildIma2MetadataPayload(meta = {}, context = {}) {
+  const payload = {
+    schema: IMA2_METADATA_SCHEMA,
+    app: "ima2-gen",
+    version: stringOrNull(context.version, 80) || null,
+    createdAt: numberOrNull(meta.createdAt) || Date.now(),
+    kind: stringOrNull(meta.kind, 80),
+    prompt: stringOrNull(meta.prompt),
+    userPrompt: stringOrNull(meta.userPrompt) || stringOrNull(meta.prompt),
+    revisedPrompt: stringOrNull(meta.revisedPrompt),
+    promptMode: meta.promptMode === "direct" ? "direct" : "auto",
+    quality: stringOrNull(meta.quality, 40),
+    size: stringOrNull(meta.size, 40),
+    format: stringOrNull(meta.format, 20),
+    moderation: stringOrNull(meta.moderation, 40),
+    model: stringOrNull(meta.model, 80),
+    provider: stringOrNull(meta.provider, 40),
+    sessionId: stringOrNull(meta.sessionId, 120),
+    nodeId: stringOrNull(meta.nodeId, 120),
+    parentNodeId: stringOrNull(meta.parentNodeId, 120),
+    clientNodeId: stringOrNull(meta.clientNodeId, 120),
+    requestId: stringOrNull(meta.requestId, 160),
+    refsCount: Number.isFinite(meta.refsCount) ? meta.refsCount : 0,
+    webSearchCalls: Number.isFinite(meta.webSearchCalls) ? meta.webSearchCalls : 0,
+    styleSheetApplied: Boolean(meta.styleSheetApplied),
+  };
+  return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
+}
+
+export function normalizeEmbeddedMetadata(value) {
+  if (!isPlainObject(value)) return null;
+  if (value.schema !== IMA2_METADATA_SCHEMA || value.app !== "ima2-gen") return null;
+  return buildIma2MetadataPayload(value, { version: value.version });
+}
+
+export function buildIma2Xmp(metadataPayload) {
+  const normalized = normalizeEmbeddedMetadata(metadataPayload);
+  if (!normalized) {
+    const err = new Error("Invalid ima2 metadata payload");
+    err.code = "IMAGE_METADATA_INVALID";
+    throw err;
+  }
+  const json = JSON.stringify(normalized);
+  if (json.length > MAX_EMBEDDED_METADATA_CHARS) {
+    const err = new Error("ima2 metadata payload is too large");
+    err.code = "IMAGE_METADATA_TOO_LARGE";
+    throw err;
+  }
+  const escaped = xmlEscape(json);
+  return [
+    "<?xpacket begin=\"\" id=\"W5M0MpCehiHzreSzNTczkc9d\"?>",
+    "<x:xmpmeta xmlns:x=\"adobe:ns:meta/\">",
+    "<rdf:RDF xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\">",
+    `<rdf:Description xmlns:ima2="${IMA2_XMP_NAMESPACE}" ima2:${IMA2_XMP_PROPERTY}="${escaped}"/>`,
+    "</rdf:RDF>",
+    "</x:xmpmeta>",
+    "<?xpacket end=\"w\"?>",
+  ].join("");
+}
+
+export function parseIma2Xmp(xmpString) {
+  if (typeof xmpString !== "string" || xmpString.length === 0) return null;
+  const attrPattern = new RegExp(`ima2:${IMA2_XMP_PROPERTY}="([^"]*)"`);
+  const attrMatch = attrPattern.exec(xmpString);
+  const raw = attrMatch?.[1];
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(xmlUnescape(raw));
+    return normalizeEmbeddedMetadata(parsed);
+  } catch {
+    return null;
+  }
+}

package/lib/imageMetadataStore.js

@@ -0,0 +1,67 @@
+import { readFile } from "node:fs/promises";
+import sharp from "sharp";
+import { buildIma2MetadataPayload, buildIma2Xmp, parseIma2Xmp } from "./imageMetadata.js";
+
+const SUPPORTED_FORMATS = new Set(["png", "jpeg", "jpg", "webp"]);
+
+export function normalizeImageMetadataFormat(format) {
+  const normalized = String(format || "").toLowerCase();
+  if (normalized === "jpg") return "jpeg";
+  return normalized;
+}
+
+export function isSupportedMetadataFormat(format) {
+  return SUPPORTED_FORMATS.has(String(format || "").toLowerCase());
+}
+
+export async function embedImageMetadata(buffer, format, metadata, context = {}) {
+  const normalizedFormat = normalizeImageMetadataFormat(format);
+  if (!isSupportedMetadataFormat(normalizedFormat)) {
+    const err = new Error(`Unsupported image metadata format: ${format}`);
+    err.code = "IMAGE_METADATA_UNSUPPORTED_FORMAT";
+    throw err;
+  }
+  const payload = buildIma2MetadataPayload(metadata, context);
+  const xmp = buildIma2Xmp(payload);
+  const next = await sharp(buffer)
+    .toFormat(normalizedFormat)
+    .withXmp(xmp)
+    .toBuffer();
+  return { buffer: next, embedded: true, metadata: payload };
+}
+
+export async function embedImageMetadataBestEffort(buffer, format, metadata, context = {}) {
+  try {
+    return await embedImageMetadata(buffer, format, metadata, context);
+  } catch (error) {
+    return {
+      buffer,
+      embedded: false,
+      warning: error?.message || "metadata embedding failed",
+      code: error?.code || "IMAGE_METADATA_EMBED_FAILED",
+    };
+  }
+}
+
+export async function readEmbeddedImageMetadata(buffer) {
+  const meta = await sharp(buffer, { failOn: "none" }).metadata();
+  const xmpString = meta.xmpAsString || (meta.xmp ? meta.xmp.toString("utf8") : "");
+  const xmp = parseIma2Xmp(xmpString);
+  if (xmp) return { metadata: xmp, source: "xmp", warnings: [] };
+
+  for (const comment of meta.comments || []) {
+    const text = comment?.text || "";
+    const parsed = parseIma2Xmp(text);
+    if (parsed) return { metadata: parsed, source: "png-comment", warnings: [] };
+  }
+
+  return {
+    metadata: null,
+    source: null,
+    warnings: ["No ima2 metadata found in this image."],
+  };
+}
+
+export async function readEmbeddedImageMetadataFromFile(path) {
+  return readEmbeddedImageMetadata(await readFile(path));
+}

package/lib/nodeStore.js

@@ -2,6 +2,7 @@ import { writeFile, readFile, access, mkdir } from "fs/promises";
 import { join, resolve, sep } from "path";
 import { randomBytes } from "crypto";
 import { config } from "../config.js";
+import { embedImageMetadataBestEffort } from "./imageMetadataStore.js";
 
 export function newNodeId() {
   return "n_" + randomBytes(config.ids.nodeHexBytes).toString("hex");
@@ -11,7 +12,18 @@ export async function saveNode(rootDir, { nodeId, b64, meta, ext = "png", genera
   void rootDir;
   const filename = `${nodeId}.${ext}`;
   await mkdir(generatedDir, { recursive: true });
-  await writeFile(join(generatedDir, filename), Buffer.from(b64, "base64"));
+  const imageMeta = {
+    ...meta,
+    kind: meta?.kind || "node",
+    nodeId: meta?.nodeId || nodeId,
+    format: meta?.format || ext,
+  };
+  const rawBuffer = Buffer.from(b64, "base64");
+  const embedded = await embedImageMetadataBestEffort(rawBuffer, ext, imageMeta);
+  if (!embedded.embedded) {
+    console.warn("[nodeStore] metadata embed skipped:", embedded.warning);
+  }
+  await writeFile(join(generatedDir, filename), embedded.buffer);
   await writeFile(join(generatedDir, filename + ".json"), JSON.stringify(meta, null, 2));
   return { filename };
 }

package/lib/oauthProxy.js

@@ -3,6 +3,7 @@ import { config } from "../config.js";
 import { logEvent } from "./logger.js";
 import { classifyUpstreamError, classifyUpstreamErrorCode } from "./errorClassify.js";
 import { compressReferenceB64ForOAuth } from "./referenceImageCompress.js";
+import { detectImageMimeFromB64, safeReferenceDiagnostics } from "./refs.js";
 
 const RESEARCH_SUFFIX = config.oauth.researchSuffix;
 
@@ -41,6 +42,51 @@ export function buildEditResearchTextPrompt(userPrompt, mode) {
   return `Edit this image: ${userPrompt}${RESEARCH_SUFFIX}${AUTO_PROMPT_FIDELITY_SUFFIX}`;
 }
 
+function summarizeEventTypes(eventTypes = {}) {
+  const entries = Object.entries(eventTypes || {});
+  const countFor = (needle) =>
+    entries.reduce((sum, [key, value]) => sum + (key.includes(needle) && Number.isFinite(value) ? value : 0), 0);
+  return {
+    eventTypeCount: entries.length,
+    eventTypeKeys: entries.slice(0, 12).map(([key]) => key).join(","),
+    imageEventCount: countFor("image"),
+    partialEventCount: countFor("partial"),
+    completedEventCount: countFor("completed"),
+  };
+}
+
+function supportedImageMime(mime) {
+  return mime === "image/png" || mime === "image/jpeg" || mime === "image/webp";
+}
+
+function normalizeReferenceForOAuth(ref, index) {
+  const b64 = typeof ref === "string" ? ref : ref?.b64;
+  const declaredMime = typeof ref === "object" && ref ? ref.declaredMime || null : null;
+  const detectedMime = typeof ref === "object" && ref
+    ? ref.detectedMime || detectImageMimeFromB64(b64)
+    : detectImageMimeFromB64(b64);
+  const warnings = Array.isArray(ref?.warnings) ? [...ref.warnings] : [];
+  if (declaredMime && detectedMime && declaredMime !== detectedMime && !warnings.includes("mime_mismatch")) {
+    warnings.push("mime_mismatch");
+  }
+  const requestMime = supportedImageMime(detectedMime)
+    ? detectedMime
+    : supportedImageMime(declaredMime)
+      ? declaredMime
+      : "image/png";
+  return {
+    index,
+    b64,
+    declaredMime,
+    detectedMime,
+    requestMime,
+    b64Chars: typeof b64 === "string" ? b64.length : 0,
+    approxBytes: Number.isFinite(ref?.approxBytes) ? ref.approxBytes : null,
+    source: ref?.source || (declaredMime ? "dataUrl" : "rawBase64"),
+    warnings,
+  };
+}
+
 function getOAuthUrl(ctx = {}) {
   return ctx.oauthUrl || `http://127.0.0.1:${config.oauth.proxyPort}`;
 }
@@ -293,16 +339,29 @@ export async function generateViaOAuth(
   ];
 
   const textPrompt = buildUserTextPrompt(prompt, mode);
-  const userContent = references.length
+  const referenceInputs = references.map(normalizeReferenceForOAuth);
+  const referenceDiagnostics = safeReferenceDiagnostics(referenceInputs);
+  const referenceMismatchCount = referenceDiagnostics.filter((ref) => ref.warnings.includes("mime_mismatch")).length;
+  const userContent = referenceInputs.length
     ? [
-        ...references.map((b64) => ({
+        ...referenceInputs.map(({ b64, requestMime }) => ({
           type: "input_image",
-          image_url: `data:image/png;base64,${b64}`,
+          image_url: `data:${requestMime};base64,${b64}`,
         })),
         { type: "input_text", text: textPrompt },
       ]
     : textPrompt;
 
+  if (referenceInputs.length > 0) {
+    logEvent("oauth", "reference_diagnostics", {
+      requestId,
+      refsCount: referenceInputs.length,
+      referenceMismatchCount,
+      refDetectedMimes: [...new Set(referenceDiagnostics.map((ref) => ref.detectedMime).filter(Boolean))].join(","),
+      refDeclaredMimes: [...new Set(referenceDiagnostics.map((ref) => ref.declaredMime).filter(Boolean))].join(","),
+    });
+  }
+
   const res = await fetchOAuth(`${oauthUrl}/v1/responses`, {
     method: "POST",
     headers: { "Content-Type": "application/json", Accept: "text/event-stream" },
@@ -357,10 +416,20 @@ export async function generateViaOAuth(
     scope: "oauth",
     onPartialImage: options.onPartialImage,
   });
-  logEvent("oauth", "stream_end", { requestId, events: eventCount, hasImage: !!imageB64, eventTypes });
+  logEvent("oauth", "stream_end", {
+    requestId,
+    events: eventCount,
+    hasImage: !!imageB64,
+    ...summarizeEventTypes(eventTypes),
+  });
 
   if (!imageB64) {
-    logEvent("oauth", "retry_json", { requestId });
+    logEvent("oauth", "retry_json", {
+      requestId,
+      retryKind: "prompt_only",
+      referencesDroppedOnRetry: referenceInputs.length > 0,
+      developerPromptDroppedOnRetry: true,
+    });
     const retryRes = await fetchOAuth(`${oauthUrl}/v1/responses`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -376,9 +445,23 @@ export async function generateViaOAuth(
       const json = await retryRes.json();
       for (const item of json.output || []) {
         if (item.type === "image_generation_call" && item.result) {
-          logEvent("oauth", "retry_image", { requestId, imageChars: item.result.length });
+          logEvent("oauth", "retry_image", {
+            requestId,
+            imageChars: item.result.length,
+            retryKind: "prompt_only",
+            referencesDroppedOnRetry: referenceInputs.length > 0,
+          });
           const retryRevised = typeof item.revised_prompt === "string" ? item.revised_prompt : null;
-          return { b64: item.result, usage: json.usage, webSearchCalls, revisedPrompt: retryRevised };
+          return {
+            b64: item.result,
+            usage: json.usage,
+            webSearchCalls,
+            revisedPrompt: retryRevised,
+            retryKind: "prompt_only",
+            referencesDroppedOnRetry: referenceInputs.length > 0,
+            developerPromptDroppedOnRetry: true,
+            initialEventCount: eventCount,
+          };
         }
       }
     } else {
@@ -397,6 +480,13 @@ export async function generateViaOAuth(
     emptyErr.size = size;
     emptyErr.quality = quality;
     emptyErr.model = model;
+    emptyErr.refsCount = referenceInputs.length;
+    emptyErr.inputImageCount = referenceInputs.length;
+    emptyErr.referenceDiagnostics = referenceDiagnostics;
+    emptyErr.referenceMismatchCount = referenceMismatchCount;
+    emptyErr.retryKind = "prompt_only";
+    emptyErr.referencesDroppedOnRetry = referenceInputs.length > 0;
+    emptyErr.developerPromptDroppedOnRetry = true;
     throw emptyErr;
   }
 
@@ -417,8 +507,8 @@ export async function editViaOAuth(prompt, imageB64, quality, size, moderation =
   });
   const references = Array.isArray(options.references) ? options.references : [];
   const referenceImagesForRequest = await Promise.all(
-    references.map((b64) =>
-      compressReferenceB64ForOAuth(b64, {
+    references.map((ref) =>
+      compressReferenceB64ForOAuth(typeof ref === "string" ? ref : ref?.b64, {
         maxB64Bytes: ctx.config?.limits?.maxRefB64Bytes,
         force: true,
       }),
@@ -486,11 +576,25 @@ export async function editViaOAuth(prompt, imageB64, quality, size, moderation =
 
   if (requestId) setJobPhase(requestId, "streaming");
 
-  const { imageB64: resultB64, usage, revisedPrompt, webSearchCalls } = await readImageStream(res, {
+  const { imageB64: resultB64, usage, revisedPrompt, webSearchCalls, eventCount, eventTypes } = await readImageStream(res, {
     scope: "oauth-edit",
     requestId,
   });
-  logEvent("oauth-edit", "stream_end", { requestId, hasImage: !!resultB64 });
+  logEvent("oauth-edit", "stream_end", {
+    requestId,
+    events: eventCount,
+    hasImage: !!resultB64,
+    ...summarizeEventTypes(eventTypes),
+  });
   if (resultB64) return { b64: resultB64, usage, revisedPrompt, webSearchCalls };
-  throw new Error("No image data received from OAuth edit");
+  const emptyErr = new Error("No image data received from OAuth edit");
+  emptyErr.eventCount = eventCount;
+  emptyErr.eventTypes = eventTypes;
+  emptyErr.size = size;
+  emptyErr.quality = quality;
+  emptyErr.model = model;
+  emptyErr.refsCount = references.length;
+  emptyErr.inputImageCount = 1 + references.length;
+  emptyErr.parentImagePresent = true;
+  throw emptyErr;
 }

package/lib/refs.js

@@ -4,6 +4,51 @@
 import { config } from "../config.js";
 
 const BASE64_RE = /^[A-Za-z0-9+/]+=*$/;
+const DATA_URL_RE = /^data:([^;,]+);base64,/i;
+
+function approxBase64Bytes(b64) {
+  try {
+    return Buffer.from(b64, "base64").length;
+  } catch {
+    return Math.floor((b64.length * 3) / 4);
+  }
+}
+
+export function detectImageMimeFromB64(b64) {
+  let buf;
+  try {
+    buf = Buffer.from(b64, "base64");
+  } catch {
+    return null;
+  }
+  if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+    return "image/png";
+  }
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+    return "image/jpeg";
+  }
+  if (
+    buf.length >= 12 &&
+    buf.toString("ascii", 0, 4) === "RIFF" &&
+    buf.toString("ascii", 8, 12) === "WEBP"
+  ) {
+    return "image/webp";
+  }
+  return null;
+}
+
+export function safeReferenceDiagnostics(refDetails = []) {
+  if (!Array.isArray(refDetails)) return [];
+  return refDetails.map((ref) => ({
+    index: ref.index,
+    declaredMime: ref.declaredMime || null,
+    detectedMime: ref.detectedMime || null,
+    b64Chars: ref.b64Chars,
+    approxBytes: ref.approxBytes,
+    source: ref.source,
+    warnings: ref.warnings || [],
+  }));
+}
 
 export function validateAndNormalizeRefs(references, {
   maxCount = config.limits.maxRefCount,
@@ -16,12 +61,15 @@ export function validateAndNormalizeRefs(references, {
     return { error: `references may not exceed ${maxCount} items`, code: "REF_TOO_MANY" };
   }
   const out = [];
+  const refDetails = [];
   for (let i = 0; i < references.length; i++) {
     const r = references[i];
     if (typeof r !== "string") {
       return { error: `references[${i}] must be a string`, code: "REF_NOT_STRING" };
     }
-    const b64 = r.replace(/^data:[^;]+;base64,/, "");
+    const dataUrlMatch = r.match(DATA_URL_RE);
+    const declaredMime = dataUrlMatch?.[1]?.toLowerCase() || null;
+    const b64 = r.replace(DATA_URL_RE, "");
     if (!b64) return { error: `references[${i}] is empty`, code: "REF_EMPTY" };
     if (b64.length > maxB64Bytes) {
       return { error: `references[${i}] exceeds ${maxB64Bytes} bytes`, code: "REF_TOO_LARGE" };
@@ -29,7 +77,22 @@ export function validateAndNormalizeRefs(references, {
     if (!BASE64_RE.test(b64)) {
       return { error: `references[${i}] is not valid base64`, code: "REF_NOT_BASE64" };
     }
+    const detectedMime = detectImageMimeFromB64(b64);
+    const warnings = [];
+    if (declaredMime && detectedMime && declaredMime !== detectedMime) {
+      warnings.push("mime_mismatch");
+    }
     out.push(b64);
+    refDetails.push({
+      index: i,
+      b64,
+      declaredMime,
+      detectedMime,
+      b64Chars: b64.length,
+      approxBytes: approxBase64Bytes(b64),
+      source: declaredMime ? "dataUrl" : "rawBase64",
+      warnings,
+    });
   }
-  return { refs: out };
+  return { refs: out, refDetails, referenceDiagnostics: safeReferenceDiagnostics(refDetails) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Local OAuth image generation studio with classic and node workflows",
   "type": "module",
   "bin": {