pixelkiln 0.3.0 → 0.4.1

package/dist/index.cjs

@@ -40,9 +40,11 @@ __export(index_exports, {
   MAX_DOWNLOAD_BYTES: () => MAX_DOWNLOAD_BYTES,
   MAX_RETRIES: () => MAX_RETRIES,
   ManifestSchema: () => ManifestSchema,
+  MediaType: () => MediaType,
   PixelLabClient: () => PixelLabClient,
   PixelLabError: () => PixelLabError,
   PixelLabProvider: () => PixelLabProvider,
+  RetroDiffusionProvider: () => RetroDiffusionProvider,
   StyleSchema: () => StyleSchema,
   UnsupportedCapabilityError: () => UnsupportedCapabilityError,
   WorkspaceProjectSchema: () => WorkspaceProjectSchema,
@@ -50,16 +52,20 @@ __export(index_exports, {
   adopt: () => adopt,
   applyTags: () => applyTags,
   auditStyle: () => auditStyle,
+  availableProviders: () => availableProviders,
   backoffMs: () => backoffMs,
   buildManifest: () => buildManifest,
   buildPlan: () => buildPlan,
+  cacheFileName: () => cacheFileName,
   candidateCount: () => candidateCount,
   clientFromEnv: () => clientFromEnv,
   colorDistance: () => colorDistance,
   countNumberedDescriptions: () => countNumberedDescriptions,
   createArtifactBundleManifest: () => createArtifactBundleManifest,
+  createProvider: () => createProvider,
   currentEntryOutputPath: () => currentEntryOutputPath,
   currentOutputPath: () => currentOutputPath,
+  detectMediaType: () => detectMediaType,
   doctor: () => doctor,
   evaluateAudit: () => evaluateAudit,
   expectedOutputPath: () => expectedOutputPath,
@@ -82,6 +88,8 @@ __export(index_exports, {
   lockKey: () => lockKey,
   matchOrphanStyle: () => matchOrphanStyle,
   measureBalanceChange: () => measureBalanceChange,
+  mediaExtension: () => mediaExtension,
+  mediaTypeFromExtension: () => mediaTypeFromExtension,
   mergePalettes: () => mergePalettes,
   mountSprites: () => mountSprites,
   mountStyle: () => mountStyle,
@@ -98,12 +106,16 @@ __export(index_exports, {
   poll: () => poll,
   portableOutputPath: () => portableOutputPath,
   primaryOutput: () => primaryOutput,
+  providerFactory: () => providerFactory,
   pushTags: () => pushTags,
+  registerProvider: () => registerProvider,
   remove: () => remove,
   renderSalvageSheet: () => renderSalvageSheet,
   renderSheet: () => renderSheet,
+  requireBalance: () => requireBalance,
   requireDelete: () => requireDelete,
   requireList: () => requireList,
+  requireSelectCandidate: () => requireSelectCandidate,
   resolveEntryOutputs: () => resolveEntryOutputs,
   resolveOutputPath: () => resolveOutputPath,
   resolvePackInputs: () => resolvePackInputs,
@@ -137,6 +149,7 @@ __export(index_exports, {
   totalSpend: () => totalSpend,
   upsert: () => upsert,
   validateCostEstimate: () => validateCostEstimate,
+  validateMedia: () => validateMedia,
   validateWorkspace: () => validateWorkspace,
   verifyArtifactBundle: () => verifyArtifactBundle,
   withArtifactManifest: () => withArtifactManifest,
@@ -149,7 +162,8 @@ module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
 var import_zod = require("zod");
-var GeneratorSchema = import_zod.z.enum(["1dir", "map", "pixflux", "tiles"]);
+var MediaTypeSchema = import_zod.z.enum(["image/png", "image/gif"]);
+var GeneratorSchema = import_zod.z.enum(["1dir", "map", "pixflux", "tiles", "animation"]);
 function tileVariationCount(descriptions) {
   return Math.max(1, descriptions) * 4;
 }
@@ -181,7 +195,7 @@ function tilesCost(tileSize, variations) {
   return 40;
 }
 var StyleImageSchema = import_zod.z.object({
-  /** Path to a PNG/JPEG, relative to the manifest file. Max 256x256. */
+  /** Path to a PNG/JPEG, relative to the manifest; the active provider validates limits. */
   path: import_zod.z.string()
 });
 var StyleSchema = import_zod.z.object({
@@ -292,7 +306,9 @@ var StyleSchema = import_zod.z.object({
     out: import_zod.z.string()
   }).strict().optional(),
   /** Tags applied to every object generated in this style, for server-side filtering. */
-  tags: import_zod.z.array(import_zod.z.string()).default([])
+  tags: import_zod.z.array(import_zod.z.string()).default([]),
+  /** Adapter-owned settings, keyed by provider id. */
+  providerOptions: import_zod.z.record(import_zod.z.record(import_zod.z.unknown())).default({})
 }).strict().refine((s) => !(s.tileFeature && s.styleImages.length), {
   message: "tileFeature and styleImages cannot be combined \u2014 a connectable set derives its own tile geometry, so remove one or the other",
   path: ["tileFeature"]
@@ -307,7 +323,7 @@ var AssetSchema = import_zod.z.object({
   height: import_zod.z.number().int().min(16).max(400).optional(),
   /** Overrides the style default. `1dir` generator only. */
   size: import_zod.z.number().int().min(32).max(256).optional(),
-  /** Explicit output path relative to outDir. Defaults to `<category>/<id>.png`. */
+  /** Explicit output path relative to outDir. Media-aware providers may replace its extension. */
   file: import_zod.z.string().optional(),
   /**
    * Grid cell this asset owns in a mounted style, as [column, row].
@@ -359,6 +375,8 @@ var AssetSchema = import_zod.z.object({
 var ManifestSchema = import_zod.z.object({
   $schema: import_zod.z.string().optional(),
   name: import_zod.z.string(),
+  /** Generation backend. Existing manifests remain PixelLab by default. */
+  provider: import_zod.z.string().min(1).default("pixellab"),
   styles: import_zod.z.record(StyleSchema),
   assets: import_zod.z.record(AssetSchema)
 }).strict();
@@ -396,7 +414,8 @@ var LockEntrySchema = import_zod.z.object({
   sourceUrls: import_zod.z.array(
     import_zod.z.object({
       url: import_zod.z.string(),
-      role: import_zod.z.string().optional()
+      role: import_zod.z.string().optional(),
+      mediaType: MediaTypeSchema.optional()
     })
   ).default([]),
   /**
@@ -411,7 +430,8 @@ var LockEntrySchema = import_zod.z.object({
     import_zod.z.object({
       path: import_zod.z.string(),
       sha256: import_zod.z.string(),
-      role: import_zod.z.string().optional()
+      role: import_zod.z.string().optional(),
+      mediaType: MediaTypeSchema.optional()
     })
   ).default([]),
   /**
@@ -425,7 +445,7 @@ var LockEntrySchema = import_zod.z.object({
   /** Successful-submission estimate in `costUnit`; may be fractional USD. */
   cost: import_zod.z.number().finite().nonnegative().default(0),
   /** Unit for `cost`. Defaults preserve pre-unit PixelLab lockfiles. */
-  costUnit: import_zod.z.enum(["generations", "usd", "free"]).default("generations"),
+  costUnit: import_zod.z.string().min(1).default("generations"),
   /** Which provider produced this. Absent on entries written before providers. */
   provider: import_zod.z.string().default("pixellab")
 });
@@ -799,7 +819,7 @@ function validateCostEstimate(providerId, value) {
     throw new Error(`Provider "${providerId}" returned an invalid cost estimate`);
   }
   const estimate = value;
-  if (!["generations", "usd", "free"].includes(estimate.unit)) {
+  if (typeof estimate.unit !== "string" || !estimate.unit.trim()) {
     throw new Error(`Provider "${providerId}" returned an invalid cost unit`);
   }
   if (!Number.isFinite(estimate.amount) || estimate.amount < 0) {
@@ -841,18 +861,23 @@ function requireDelete(provider) {
   if (!provider.delete) throw new UnsupportedCapabilityError(provider.id, "deleting remote assets");
   return provider.delete.bind(provider);
 }
+function requireSelectCandidate(provider) {
+  if (!provider.selectCandidate) {
+    throw new UnsupportedCapabilityError(provider.id, "candidate selection");
+  }
+  return provider.selectCandidate.bind(provider);
+}
+function requireBalance(provider) {
+  if (!provider.balance) throw new UnsupportedCapabilityError(provider.id, "account balance");
+  return provider.balance.bind(provider);
+}
 function formatCost(unit, amount) {
   if (unit === "free") return "free";
   if (unit === "usd") return `$${amount.toFixed(2)}`;
-  return `${amount} generation${amount === 1 ? "" : "s"}`;
+  if (unit === "generations") return `${amount} generation${amount === 1 ? "" : "s"}`;
+  return `${amount} ${unit}`;
 }
 
-// src/providers/pixellab.ts
-var import_node_fs = require("fs");
-var import_node_crypto = require("crypto");
-var import_node_os = __toESM(require("os"), 1);
-var import_node_path = __toESM(require("path"), 1);
-
 // src/png.ts
 var import_node_zlib = require("zlib");
 var SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
@@ -1210,7 +1235,96 @@ function parseHex(hex2) {
   return { r: n >> 16 & 255, g: n >> 8 & 255, b: n & 255 };
 }
 
+// src/media.ts
+var MediaType = {
+  PNG: "image/png",
+  GIF: "image/gif"
+};
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function mediaExtension(mediaType) {
+  return mediaType === MediaType.GIF ? ".gif" : ".png";
+}
+function mediaTypeFromExtension(file) {
+  const lower = file.toLowerCase();
+  if (lower.endsWith(".png")) return MediaType.PNG;
+  if (lower.endsWith(".gif")) return MediaType.GIF;
+  return null;
+}
+function detectMediaType(bytes) {
+  if (bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) return MediaType.PNG;
+  const header = bytes.subarray(0, 6).toString("ascii");
+  if (header === "GIF87a" || header === "GIF89a") return MediaType.GIF;
+  return null;
+}
+function validateMedia(bytes, expected) {
+  const actual = detectMediaType(bytes);
+  if (!actual) throw new Error(`response was not a supported PNG or GIF (${bytes.length} bytes)`);
+  if (expected && actual !== expected) {
+    throw new Error(`response was ${actual}, expected ${expected}`);
+  }
+  if (actual === MediaType.PNG) {
+    decodePng(bytes);
+  } else {
+    validateGif(bytes);
+  }
+  return actual;
+}
+function validateGif(bytes) {
+  if (bytes.length < 14) throw new Error("invalid GIF: truncated logical screen descriptor");
+  const width = bytes.readUInt16LE(6);
+  const height = bytes.readUInt16LE(8);
+  if (!width || !height) throw new Error("invalid GIF: zero-sized logical screen");
+  const packed = bytes[10];
+  let offset = 13;
+  if (packed & 128) offset += 3 * 2 ** ((packed & 7) + 1);
+  if (offset > bytes.length) throw new Error("invalid GIF: truncated global color table");
+  let sawImage = false;
+  while (offset < bytes.length) {
+    const marker = bytes[offset];
+    if (marker === 59) {
+      if (!sawImage) throw new Error("invalid GIF: contains no image frame");
+      return;
+    }
+    if (marker === 44) {
+      if (offset + 10 > bytes.length) throw new Error("invalid GIF: truncated image descriptor");
+      const imagePacked = bytes[offset + 9];
+      offset += 10;
+      if (imagePacked & 128) offset += 3 * 2 ** ((imagePacked & 7) + 1);
+      if (offset >= bytes.length) throw new Error("invalid GIF: missing image data");
+      offset++;
+      offset = skipSubBlocks(bytes, offset);
+      sawImage = true;
+      continue;
+    }
+    if (marker === 33) {
+      if (offset + 2 > bytes.length) throw new Error("invalid GIF: truncated extension");
+      offset = skipSubBlocks(bytes, offset + 2);
+      continue;
+    }
+    throw new Error(`invalid GIF: unexpected block marker 0x${marker.toString(16)}`);
+  }
+  throw new Error("invalid GIF: missing trailer");
+}
+function skipSubBlocks(bytes, start) {
+  let offset = start;
+  for (; ; ) {
+    if (offset >= bytes.length) throw new Error("invalid GIF: truncated data blocks");
+    const size = bytes[offset];
+    offset++;
+    if (size === 0) return offset;
+    offset += size;
+    if (offset > bytes.length) throw new Error("invalid GIF: truncated data block");
+  }
+}
+function cacheFileName(hash, mediaType = MediaType.PNG) {
+  return `${hash}${mediaExtension(mediaType)}`;
+}
+
 // src/providers/pixellab.ts
+var import_node_fs = require("fs");
+var import_node_crypto = require("crypto");
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path = __toESM(require("path"), 1);
 var PixelLabProvider = class _PixelLabProvider {
   constructor(client) {
     this.client = client;
@@ -1260,7 +1374,44 @@ var PixelLabProvider = class _PixelLabProvider {
       candidates: spec.generator === "1dir" ? candidateCount(spec.size) : 1
     };
   }
+  validate(spec, styleImages) {
+    if (spec.generator === "map") {
+      requirePixelLabOption("view", spec.view, ["low top-down", "high top-down", "side"]);
+      requirePixelLabOption("outline", spec.outline, [
+        "single color outline",
+        "selective outline",
+        "lineless"
+      ]);
+      requirePixelLabOption("shading", spec.shading, [
+        "flat shading",
+        "basic shading",
+        "medium shading",
+        "detailed shading"
+      ]);
+      requirePixelLabOption("detail", spec.detail, [
+        "low detail",
+        "medium detail",
+        "high detail"
+      ]);
+    }
+    if ((spec.generator === "map" || spec.generator === "pixflux") && styleImages.length) {
+      throw new Error(`PixelLab ${spec.generator} does not support style images`);
+    }
+    for (const image of styleImages) {
+      if (image.width > 256 || image.height > 256) {
+        throw new Error(
+          `Style image exceeds PixelLab's 256x256 limit (${image.width}x${image.height})`
+        );
+      }
+    }
+    if (spec.tags.length > 20) {
+      throw new Error(
+        `${spec.styleId}/${spec.assetId} resolves to ${spec.tags.length} tags, but PixelLab allows at most 20`
+      );
+    }
+  }
   async submit(spec, styleImages) {
+    this.validate(spec, styleImages);
     if (spec.generator === "pixflux") {
       const swatch = spec.palette.length ? paletteSwatch(spec.palette).toString("base64") : void 0;
       const { png } = await this.client.createImagePixflux({
@@ -1446,6 +1597,11 @@ var PixelLabProvider = class _PixelLabProvider {
     await this.client.deleteObject(assetId);
   }
 };
+function requirePixelLabOption(name, value, allowed) {
+  if (value != null && !allowed.includes(value)) {
+    throw new Error(`PixelLab map ${name} must be one of: ${allowed.join(", ")}`);
+  }
+}
 function tilesInIndexOrder(urls) {
   return Object.entries(urls).map(([key, url]) => ({ index: Number(key.replace(/^tile_/, "")), url })).filter((tile) => Number.isFinite(tile.index)).sort((a, b) => a.index - b.index);
 }
@@ -1454,6 +1610,319 @@ function firstUrl(urls) {
   return Object.values(urls).find((u) => typeof u === "string") ?? null;
 }
 
+// src/providers/retrodiffusion.ts
+var DEFAULT_BASE_URL = "https://api.retrodiffusion.ai/v1";
+var RetroDiffusionClient = class {
+  constructor(token, baseUrl = DEFAULT_BASE_URL, request = fetch) {
+    this.token = token;
+    this.baseUrl = baseUrl;
+    this.request = request;
+  }
+  token;
+  baseUrl;
+  request;
+  async submit(body) {
+    const response = await this.call("/inferences", { method: "POST", body: JSON.stringify(body) });
+    const taskId = response.task_id;
+    if (typeof taskId !== "string" || !taskId) {
+      throw new Error("Retro Diffusion did not return an async task id");
+    }
+    return taskId;
+  }
+  async quote(body) {
+    const response = await this.call("/inferences", {
+      method: "POST",
+      body: JSON.stringify({ ...body, check_cost: true })
+    });
+    const amount = response.balance_cost;
+    if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) {
+      throw new Error("Retro Diffusion returned an invalid cost quote");
+    }
+    return amount;
+  }
+  async task(id) {
+    return await this.call(`/inferences/tasks/${encodeURIComponent(id)}`);
+  }
+  async balance() {
+    const response = await this.call("/inferences/credits");
+    const balance = response.balance;
+    if (typeof balance !== "number" || !Number.isFinite(balance)) {
+      throw new Error("Retro Diffusion returned an invalid balance");
+    }
+    return balance;
+  }
+  async call(path17, init = {}) {
+    if (!this.token) throw new Error("RD_API_KEY is not set");
+    const response = await this.request(`${this.baseUrl}${path17}`, {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        "X-RD-Token": this.token,
+        ...init.headers
+      }
+    });
+    const text = await response.text();
+    let value = null;
+    try {
+      value = text ? JSON.parse(text) : null;
+    } catch {
+      value = text;
+    }
+    if (!response.ok) {
+      const retry = response.headers.get("retry-after");
+      const detail = retroError(value);
+      throw new Error(
+        `Retro Diffusion request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : "")
+      );
+    }
+    return value;
+  }
+};
+var RetroDiffusionProvider = class _RetroDiffusionProvider {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  id = "retrodiffusion";
+  static fromEnv() {
+    return new _RetroDiffusionProvider(new RetroDiffusionClient(process.env.RD_API_KEY));
+  }
+  static forOffline() {
+    return new _RetroDiffusionProvider(new RetroDiffusionClient(void 0));
+  }
+  static forDownloads() {
+    return _RetroDiffusionProvider.forOffline();
+  }
+  supports(generator) {
+    return generator === "map" || generator === "pixflux" || generator === "tiles" || generator === "animation";
+  }
+  estimate(spec) {
+    const options = retroOptions(spec);
+    const style = resolvedPromptStyle(spec, options);
+    const count = options.numImages ?? 1;
+    const pixels = spec.width * spec.height;
+    let each;
+    if (style.startsWith("rd_advanced_animation__")) {
+      each = /__(?:custom_action|subtle_motion)$/.test(style) ? 0.25 : 0.14;
+    } else if (style.startsWith("rd_animation__")) {
+      each = /__(?:any_animation|8_dir_rotation)$/.test(style) ? 0.25 : 0.07;
+    } else if (/^rd_tile__tileset(?:_advanced)?$/.test(style)) {
+      each = 0.1;
+    } else if (style.startsWith("rd_pro__")) {
+      each = 0.18;
+    } else if (style.startsWith("rd_fast__")) {
+      each = Math.max(0.015, (pixels + 1e5) / 6e6);
+    } else if (isLowResolutionStyle(style)) {
+      each = Math.max(0.02, (pixels + 13700) / 6e5);
+    } else {
+      each = Math.max(0.025, (pixels + 5e4) / 2e6);
+    }
+    return { unit: "usd", amount: roundUsdEstimate(each * count), candidates: count };
+  }
+  validate(spec, styleImages) {
+    const options = retroOptions(spec);
+    const promptStyle = resolvedPromptStyle(spec, options);
+    const count = options.numImages ?? 1;
+    const isAnimation = /^(?:rd_animation__|rd_advanced_animation__)/.test(promptStyle);
+    const isTile = promptStyle.startsWith("rd_tile__");
+    if (!promptStyle || spec.generator === "animation" && !isAnimation || spec.generator === "tiles" && !isTile || spec.generator !== "animation" && spec.generator !== "tiles" && (isAnimation || isTile)) {
+      throw new Error(
+        `Retro Diffusion style "${promptStyle}" does not match generator "${spec.generator}"`
+      );
+    }
+    if (!Number.isInteger(count) || count < 1 || count > 16) {
+      throw new Error("Retro Diffusion numImages must be a whole number from 1 to 16");
+    }
+    if (spec.width < 16 || spec.height < 16 || spec.width > 512 || spec.height > 512) {
+      throw new Error("Retro Diffusion output dimensions must be between 16 and 512 pixels");
+    }
+    if (styleImages.length > 9) {
+      throw new Error("Retro Diffusion accepts at most 9 reference images");
+    }
+    if (spec.generator === "animation") {
+      if (count !== 1) throw new Error("Retro Diffusion animations currently require numImages: 1");
+      validateAnimation(promptStyle, spec, styleImages, options);
+    } else if (spec.generator === "tiles") {
+      validateTile(promptStyle, spec, styleImages, count, options);
+    } else if (styleImages.length && !/^(?:rd_pro__|user__)/.test(promptStyle)) {
+      throw new Error(
+        `Retro Diffusion style "${promptStyle}" does not accept reference_images; use an RD Pro or user style`
+      );
+    }
+  }
+  async submit(spec, styleImages) {
+    this.validate(spec, styleImages);
+    const options = retroOptions(spec);
+    const promptStyle = resolvedPromptStyle(spec, options);
+    const animation = spec.generator === "animation";
+    const tiles = spec.generator === "tiles";
+    const body = {
+      prompt: spec.prompt,
+      prompt_style: promptStyle,
+      width: spec.width,
+      height: spec.height,
+      num_images: options.numImages ?? 1,
+      ...!animation && !tiles ? { remove_bg: options.removeBg ?? spec.noBackground } : {},
+      ...spec.seed != null ? { seed: spec.seed } : {},
+      ...animation || tiles ? styleImages[0] ? { input_image: styleImages[0].base64 } : {} : styleImages.length ? { reference_images: styleImages.map((image) => image.base64) } : {},
+      ...tiles && styleImages[1] ? { extra_input_image: styleImages[1].base64 } : {},
+      ...tiles && options.extraPrompt ? { extra_prompt: options.extraPrompt } : {},
+      ...animation && options.framesDuration ? { frames_duration: options.framesDuration } : {},
+      ...animation && options.returnSpritesheet ? { return_spritesheet: true } : {},
+      ...!animation && options.tileX != null ? { tile_x: options.tileX } : {},
+      ...!animation && options.tileY != null ? { tile_y: options.tileY } : {},
+      ...spec.palette.length ? { input_palette: paletteSwatch(spec.palette).toString("base64") } : {}
+    };
+    const quoted = await this.client.quote(body);
+    const estimated = this.estimate(spec).amount;
+    if (quoted > estimated + 1e-6) {
+      throw new Error(
+        `Retro Diffusion quoted $${quoted.toFixed(6)}, above the offline estimate $${estimated.toFixed(6)}; no paid request was sent`
+      );
+    }
+    return {
+      jobId: await this.client.submit({ ...body, async: true, upload_outputs: true })
+    };
+  }
+  async poll(jobId, generator, context) {
+    const task = await this.client.task(jobId);
+    if (task.status === "pending" || task.status === "running") return { status: "processing" };
+    if (task.status === "failed") return { status: "failed", error: retroError(task.error) };
+    if (task.status !== "succeeded") {
+      return { status: "failed", error: `Retro Diffusion returned unknown task status "${String(task.status)}"` };
+    }
+    const options = context?.spec ? retroOptions(context.spec) : {};
+    const mediaType = generator === "animation" && !options.returnSpritesheet ? MediaType.GIF : MediaType.PNG;
+    const sources = resultSources(task.result, mediaType);
+    const urls = sources.map((source) => source.url);
+    if (!urls.length) return { status: "failed", error: "Retro Diffusion task returned no images" };
+    if (urls.length > 1) return { status: "review", candidateUrls: urls };
+    return {
+      status: "ready",
+      objectId: `${jobId}#0`,
+      sourceUrl: urls[0],
+      sources,
+      metadata: {
+        balanceCost: task.result?.balance_cost ?? null,
+        remainingBalance: task.result?.remaining_balance ?? null,
+        mediaType,
+        kind: generator === "animation" ? "animation" : generator === "tiles" ? "tileset" : "image",
+        ...context?.spec ? {
+          promptStyle: resolvedPromptStyle(context.spec, options),
+          width: context.spec.width,
+          height: context.spec.height
+        } : {}
+      }
+    };
+  }
+  async selectCandidate(jobId, index) {
+    const task = await this.client.task(jobId);
+    if (task.status !== "succeeded") throw new Error(`Retro Diffusion task ${jobId} is not ready`);
+    const url = resultSources(task.result, MediaType.PNG)[index]?.url;
+    if (!url) throw new Error(`Retro Diffusion task ${jobId} has no candidate at index ${index}`);
+    return { objectId: `${jobId}#${index}`, sourceUrl: url };
+  }
+  async download(url) {
+    const data = /^data:[^;]+;base64,(.+)$/.exec(url)?.[1];
+    if (data) return Buffer.from(data, "base64");
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Retro Diffusion download failed (${response.status})`);
+    return Buffer.from(await response.arrayBuffer());
+  }
+  async balance() {
+    return { unit: "usd", remaining: await this.client.balance() };
+  }
+};
+function retroOptions(spec) {
+  return spec.providerOptions;
+}
+function resultSources(result, mediaType) {
+  const hosted = (result?.output_urls ?? []).filter((url) => typeof url === "string" && url.length > 0).map((url) => ({ url, mediaType }));
+  if (hosted.length) return hosted;
+  return (result?.base64_images ?? []).filter((data) => typeof data === "string" && data.length > 0).map((data) => ({
+    url: `data:${mediaType};base64,${data}`,
+    mediaType
+  }));
+}
+function resolvedPromptStyle(spec, options) {
+  return options.promptStyle ?? (spec.generator === "animation" ? "rd_animation__any_animation" : spec.generator === "tiles" ? "rd_tile__tileset" : "rd_plus__default");
+}
+function validateAnimation(style, spec, styleImages, options) {
+  if (spec.width !== spec.height) throw new Error("Retro Diffusion animations must be square");
+  if (style.startsWith("rd_advanced_animation__")) {
+    if (styleImages.length !== 1) {
+      throw new Error(`Retro Diffusion advanced animation style "${style}" requires one input image`);
+    }
+    if (spec.width < 32 || spec.width > 256) {
+      throw new Error("Retro Diffusion advanced animations require dimensions from 32 to 256 pixels");
+    }
+  } else if (styleImages.length > 1) {
+    throw new Error("Retro Diffusion prompt animations accept at most one input image");
+  }
+  const exact = style.includes("four_angle_walking") ? 48 : style.endsWith("__small_sprites") ? 32 : style.endsWith("__any_animation") ? 64 : style.endsWith("__big_animation") ? 128 : style.endsWith("__8_dir_rotation") ? 80 : null;
+  if (exact && spec.width !== exact) {
+    throw new Error(`Retro Diffusion style "${style}" requires ${exact}x${exact} dimensions`);
+  }
+  if (style.endsWith("__vfx") && (spec.width < 24 || spec.width > 96)) {
+    throw new Error("Retro Diffusion VFX animations require dimensions from 24 to 96 pixels");
+  }
+  if (options.framesDuration != null && ![4, 6, 8, 10, 12, 16].includes(options.framesDuration)) {
+    throw new Error("Retro Diffusion framesDuration must be 4, 6, 8, 10, 12, or 16");
+  }
+}
+function validateTile(style, spec, styleImages, count, options) {
+  if (spec.width !== spec.height) throw new Error("Retro Diffusion tiles must be square");
+  const size = spec.width;
+  if (/^rd_tile__tileset(?:_advanced)?$/.test(style)) {
+    if (size < 16 || size > 32) throw new Error("Retro Diffusion tilesets require 16\u201332px tiles");
+    if (count !== 1) throw new Error("Retro Diffusion tilesets require numImages: 1");
+  } else if (style === "rd_tile__single_tile" && (size < 16 || size > 64)) {
+    throw new Error("Retro Diffusion single tiles require dimensions from 16 to 64 pixels");
+  } else if (style === "rd_tile__tile_variation") {
+    if (size < 16 || size > 128) throw new Error("Retro Diffusion tile variations require 16\u2013128px tiles");
+    if (styleImages.length !== 1) throw new Error("Retro Diffusion tile variations require one input image");
+  } else if (style === "rd_tile__tile_object" && (size < 16 || size > 96)) {
+    throw new Error("Retro Diffusion tile objects require dimensions from 16 to 96 pixels");
+  } else if (style === "rd_tile__scene_object" && (size < 64 || size > 384)) {
+    throw new Error("Retro Diffusion tile scene objects require dimensions from 64 to 384 pixels");
+  }
+  if (style === "rd_tile__tileset" && styleImages.length > 1) {
+    throw new Error("Retro Diffusion basic tilesets accept at most one input image");
+  }
+  if (style === "rd_tile__tileset_advanced") {
+    if (styleImages.length > 2) throw new Error("Retro Diffusion advanced tilesets accept at most two input images");
+    if (!options.extraPrompt && styleImages.length < 2) {
+      throw new Error("Retro Diffusion advanced tilesets require extraPrompt or a second input image");
+    }
+  }
+}
+function isLowResolutionStyle(style) {
+  return /(?:^|__)(?:mc_|low_res|classic|skill_icon|topdown_item)/.test(style);
+}
+function roundUsdEstimate(value) {
+  return Math.ceil((value - 1e-9) * 1e3) / 1e3;
+}
+function retroError(value) {
+  if (typeof value === "string") return value || "unknown error";
+  if (!value || typeof value !== "object") return "unknown error";
+  const record = value;
+  if (typeof record.message === "string") return record.message;
+  if (typeof record.detail === "string") return record.detail;
+  if (Array.isArray(record.detail)) {
+    const details = record.detail.map((item) => {
+      if (!item || typeof item !== "object") return String(item);
+      const detail = item;
+      return typeof detail.msg === "string" ? detail.msg : JSON.stringify(item);
+    }).filter(Boolean);
+    if (details.length) return details.join("; ");
+  }
+  if (record.detail && typeof record.detail === "object") {
+    const message2 = record.detail.message;
+    if (typeof message2 === "string") return message2;
+  }
+  return JSON.stringify(value);
+}
+
 // src/providers/fake.ts
 var import_node_crypto2 = require("crypto");
 var FAKE_PNG = Buffer.from(
@@ -1598,6 +2067,47 @@ var FakeProvider = class {
   }
 };
 
+// src/providers/registry.ts
+var factories = /* @__PURE__ */ new Map();
+function registerProvider(factory) {
+  const id = factory.id.trim();
+  if (!id) throw new Error("Provider id cannot be empty");
+  if (factories.has(id)) throw new Error(`Provider "${id}" is already registered`);
+  factories.set(id, factory);
+}
+function providerFactory(id) {
+  const factory = factories.get(id);
+  if (!factory) {
+    const available = [...factories.keys()].sort().join(", ") || "(none)";
+    throw new Error(`Unknown provider "${id}". Available providers: ${available}`);
+  }
+  return factory;
+}
+function createProvider(id, mode2) {
+  return providerFactory(id).create(mode2);
+}
+function availableProviders() {
+  return [...factories.keys()].sort();
+}
+registerProvider({
+  id: "pixellab",
+  credentialEnv: "PIXELLAB_API_KEY",
+  create(mode2) {
+    if (mode2 === "online") return PixelLabProvider.fromEnv();
+    if (mode2 === "downloads") return PixelLabProvider.forDownloads();
+    return PixelLabProvider.forOffline();
+  }
+});
+registerProvider({
+  id: "retrodiffusion",
+  credentialEnv: "RD_API_KEY",
+  create(mode2) {
+    if (mode2 === "online") return RetroDiffusionProvider.fromEnv();
+    if (mode2 === "downloads") return RetroDiffusionProvider.forDownloads();
+    return RetroDiffusionProvider.forOffline();
+  }
+});
+
 // src/manifest.ts
 var import_promises2 = require("fs/promises");
 var import_node_fs2 = require("fs");
@@ -1615,6 +2125,10 @@ async function sha256File(path17) {
 function specHash(spec, styleImageHashes) {
   return sha256(
     JSON.stringify({
+      // Preserve every existing PixelLab hash while making a provider switch
+      // invalidate the spec. Older manifests implicitly mean pixellab.
+      provider: spec.provider === "pixellab" ? void 0 : spec.provider,
+      providerOptions: Object.keys(spec.providerOptions).length > 0 ? spec.providerOptions : void 0,
       generator: spec.generator,
       prompt: spec.prompt,
       width: spec.width,
@@ -1628,7 +2142,7 @@ function specHash(spec, styleImageHashes) {
       // `noBackground` only reaches the wire for pixflux; the tile fields are
       // undefined for every other generator. `tileSize` is intentionally
       // absent — width/height are derived from it, so it is already covered.
-      noBackground: spec.generator === "pixflux" ? spec.noBackground : void 0,
+      noBackground: spec.generator === "pixflux" || spec.provider !== "pixellab" ? spec.noBackground : void 0,
       tileType: spec.tileType,
       tileView: spec.tileView,
       tileFeature: spec.tileFeature,
@@ -1668,6 +2182,7 @@ ${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
 }
 async function resolveSpecs(loaded, filter) {
   const { manifest, root } = loaded;
+  const activeProvider = filter?.provider ?? createProvider(manifest.provider, "offline");
   const specs = [];
   const styleIds = Object.keys(manifest.styles).filter(
     (id) => !filter?.styles?.length || filter.styles.includes(id)
@@ -1693,10 +2208,8 @@ async function resolveSpecs(loaded, filter) {
       const buf = await (0, import_promises2.readFile)(abs);
       const metadata = imageMetadata(buf);
       if (!metadata) throw new Error(`Style image is not a readable PNG or JPEG: ${abs}`);
-      if (metadata.width < 1 || metadata.height < 1 || metadata.width > 256 || metadata.height > 256) {
-        throw new Error(
-          `Style image exceeds the API's 256x256 limit: ${abs} (${metadata.width}x${metadata.height})`
-        );
+      if (metadata.width < 1 || metadata.height < 1) {
+        throw new Error(`Style image has invalid dimensions: ${abs}`);
       }
       hit = { base64: buf.toString("base64"), hash: sha256(buf), ...metadata };
       styleImageCache.set(abs, hit);
@@ -1716,8 +2229,8 @@ async function resolveSpecs(loaded, filter) {
       if (filter?.assets?.length && !filter.assets.includes(assetId)) continue;
       if (asset.styles.length && !asset.styles.includes(styleId)) continue;
       const generator = style.generator;
-      if (filter?.provider && !filter.provider.supports(generator)) {
-        throw new Error(`Provider "${filter.provider.id}" does not support generator "${generator}"`);
+      if (!activeProvider.supports(generator)) {
+        throw new Error(`Provider "${activeProvider.id}" does not support generator "${generator}"`);
       }
       let width;
       let height;
@@ -1744,6 +2257,8 @@ async function resolveSpecs(loaded, filter) {
       const base = {
         styleId,
         assetId,
+        provider: activeProvider.id,
+        providerOptions: style.providerOptions[activeProvider.id] ?? {},
         generator,
         prompt,
         width,
@@ -1775,11 +2290,6 @@ async function resolveSpecs(loaded, filter) {
           `style:${styleId}`
         ])
       ];
-      if (tags.length > 20) {
-        throw new Error(
-          `${styleId}/${assetId} resolves to ${tags.length} tags, but PixelLab allows at most 20`
-        );
-      }
       const resolved = {
         ...base,
         root,
@@ -1788,12 +2298,15 @@ async function resolveSpecs(loaded, filter) {
         source: asset.source,
         specHash: specHash(base, styleImageHashes)
       };
-      if (filter?.provider) {
-        const estimate = validateCostEstimate(filter.provider.id, filter.provider.estimate(resolved));
-        resolved.cost = estimate.amount;
-        resolved.costUnit = estimate.unit;
-        resolved.candidates = estimate.candidates;
-      }
+      const resolvedImages = style.styleImages.map((image) => {
+        const hit = styleImageCache.get(import_node_path2.default.resolve(root, image.path));
+        return { base64: hit.base64, width: hit.width, height: hit.height, format: hit.format };
+      });
+      activeProvider.validate?.(resolved, resolvedImages);
+      const estimate = validateCostEstimate(activeProvider.id, activeProvider.estimate(resolved));
+      resolved.cost = estimate.amount;
+      resolved.costUnit = estimate.unit;
+      resolved.candidates = estimate.candidates;
       specs.push(resolved);
     }
   }
@@ -1817,10 +2330,8 @@ async function resolveStyleImages(loaded, styleId) {
     const buf = await (0, import_promises2.readFile)(file);
     const metadata = imageMetadata(buf);
     if (!metadata) throw new Error(`Style image is not a readable PNG or JPEG: ${file}`);
-    if (metadata.width < 1 || metadata.height < 1 || metadata.width > 256 || metadata.height > 256) {
-      throw new Error(
-        `Style image exceeds the API's 256x256 limit: ${file} (${metadata.width}x${metadata.height})`
-      );
+    if (metadata.width < 1 || metadata.height < 1) {
+      throw new Error(`Style image has invalid dimensions: ${file}`);
     }
     out.push({ base64: buf.toString("base64"), ...metadata });
   }
@@ -2022,12 +2533,13 @@ async function acquireFileLock(file) {
 function spendByUnit(lock) {
   const totals = { generations: 0, usd: 0, free: 0 };
   for (const entry of Object.values(lock.entries)) {
-    totals[entry.costUnit ?? "generations"] += entry.cost ?? 0;
+    const unit = entry.costUnit ?? "generations";
+    totals[unit] = (totals[unit] ?? 0) + (entry.cost ?? 0);
   }
   return totals;
 }
 function totalSpend(lock, unit = "generations") {
-  return spendByUnit(lock)[unit];
+  return spendByUnit(lock)[unit] ?? 0;
 }
 
 // src/outputs.ts
@@ -2044,16 +2556,16 @@ function resolveOutputPath(recordedPath, manifestDir) {
   if (import_node_path4.default.win32.isAbsolute(recordedPath)) return recordedPath;
   return import_node_path4.default.resolve(manifestDir, recordedPath.split(/[\\/]/).join(import_node_path4.default.sep));
 }
-function expectedOutputPath(spec, role, index, total) {
-  if (total === 1) return spec.outFile;
+function expectedOutputPath(spec, role, index, total, mediaType) {
   const originalExt = import_node_path4.default.extname(spec.outFile);
-  const ext = originalExt || ".png";
+  const ext = mediaType ? mediaExtension(mediaType) : originalExt || ".png";
   const stem = originalExt ? spec.outFile.slice(0, -originalExt.length) : spec.outFile;
+  if (total === 1) return `${stem}${ext}`;
   const safeRole = (role ?? fallbackOutputRole(index)).replace(/[^a-zA-Z0-9_-]+/g, "-");
   return `${stem}-${safeRole}${ext}`;
 }
 function currentOutputPath(output, spec, index, total) {
-  return expectedOutputPath(spec, output.role, index, total);
+  return expectedOutputPath(spec, output.role, index, total, output.mediaType);
 }
 function currentEntryOutputPath(entry, spec, index) {
   const output = entry.outputs[index];
@@ -2901,7 +3413,6 @@ function cachePathFor(lockPath) {
 }
 
 // src/pipeline/cache-health.ts
-var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 async function inspectCaches(lock, lockPath, options = {}) {
   if (options.prune && !(0, import_node_fs7.existsSync)(lockPath)) {
     throw new Error(`Refusing to prune without an existing lockfile at ${import_node_path9.default.resolve(lockPath)}`);
@@ -2970,7 +3481,8 @@ async function inspectContentCache(contentDir, referenced) {
     }
     report.files++;
     const file = import_node_path9.default.join(contentDir, entry.name);
-    const expected = entry.name.endsWith(".png") ? entry.name.slice(0, -4) : "";
+    const mediaType = mediaTypeFromExtension(entry.name);
+    const expected = mediaType ? entry.name.slice(0, -4) : "";
     let bytes;
     try {
       bytes = await (0, import_promises7.readFile)(file);
@@ -2983,11 +3495,7 @@ async function inspectContentCache(contentDir, referenced) {
       continue;
     }
     if (!isSha256Hash(expected)) {
-      report.invalid.push({ name: entry.name, reason: "filename is not <sha256>.png" });
-      continue;
-    }
-    if (!bytes.subarray(0, 8).equals(PNG_SIGNATURE)) {
-      report.invalid.push({ name: entry.name, reason: "not a PNG" });
+      report.invalid.push({ name: entry.name, reason: "filename is not <sha256>.png or <sha256>.gif" });
       continue;
     }
     if (sha256(bytes) !== expected) {
@@ -2995,11 +3503,11 @@ async function inspectContentCache(contentDir, referenced) {
       continue;
     }
     try {
-      decodePng(bytes);
+      validateMedia(bytes, mediaType);
     } catch (err) {
       report.invalid.push({
         name: entry.name,
-        reason: `invalid PNG: ${err instanceof Error ? err.message : String(err)}`
+        reason: `invalid ${mediaType === "image/gif" ? "GIF" : "PNG"}: ${err instanceof Error ? err.message : String(err)}`
       });
       continue;
     }
@@ -3588,7 +4096,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
   async function pruneInFlight() {
     for (const [id, spec] of [...inFlight]) {
       try {
-        const state = await provider.poll(id, spec.generator, spec);
+        const state = await provider.poll(id, spec.generator, { spec, tileFeature: spec.tileFeature });
         if (state.status !== "processing") inFlight.delete(id);
         lastSlotError = null;
       } catch (err) {
@@ -3640,7 +4148,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
     await saveLock(lockPath, lock);
     lastSubmitAt = Date.now();
     try {
-      const refs = spec.generator === "1dir" || spec.generator === "tiles" ? styleImages.get(spec.styleId) ?? [] : [];
+      const refs = styleImages.get(spec.styleId) ?? [];
       const { jobId } = await provider.submit(spec, refs);
       upsert(lock, key, {
         jobId,
@@ -3690,7 +4198,8 @@ async function poll(provider, lock, lockPath, opts = {}) {
       try {
         const currentSpec = specByKey.get(key);
         const state = await provider.poll(entry.jobId, entry.generator, {
-          tileFeature: entry.tileFeature ?? currentSpec?.tileFeature
+          tileFeature: entry.tileFeature ?? currentSpec?.tileFeature,
+          spec: currentSpec
         });
         if (state.status === "review") {
           upsert(lock, key, { status: "review", reviewObjectId: entry.jobId });
@@ -3728,7 +4237,6 @@ async function poll(provider, lock, lockPath, opts = {}) {
 var import_node_fs9 = require("fs");
 var import_promises8 = require("fs/promises");
 var import_node_path11 = __toESM(require("path"), 1);
-var PNG_SIGNATURE2 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   const log = opts.onProgress ?? (() => {
   });
@@ -3760,7 +4268,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
         result.skipped++;
         continue;
       }
-      const sources = entry.sourceUrls?.length ? entry.sourceUrls : entry.sourceUrl ? [{ url: entry.sourceUrl }] : opts.repair && entry.outputs.length ? entry.outputs.map((o) => ({ url: "", role: o.role })) : [];
+      const sources = entry.sourceUrls?.length ? entry.sourceUrls : entry.sourceUrl ? [{ url: entry.sourceUrl }] : opts.repair && entry.outputs.length ? entry.outputs.map((o) => ({ url: "", role: o.role, mediaType: o.mediaType })) : [];
       if (!sources.length) {
         upsert(lock, key, {
           status: "download-failed",
@@ -3776,7 +4284,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           const recorded = entry.outputs.find(
             (o) => source.role ? o.role === source.role : !o.role && sources.length === 1
           );
-          const target = recorded ? resolveOutputPath(recorded.path, spec.root) : expectedOutputPath(spec, source.role, index, sources.length);
+          const target = recorded ? resolveOutputPath(recorded.path, spec.root) : expectedOutputPath(spec, source.role, index, sources.length, source.mediaType);
           if ((0, import_node_fs9.existsSync)(target)) {
             if (!recorded) {
               throw new Error(`refusing to overwrite untracked output ${target}`);
@@ -3784,11 +4292,19 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             if (await sha256File(target) !== recorded.sha256) {
               throw new Error(`refusing to overwrite modified output ${target}`);
             }
-            if (cacheDir) await cachePng(cacheDir, await (0, import_promises8.readFile)(target), recorded.sha256);
+            if (cacheDir) {
+              await cacheMedia(
+                cacheDir,
+                await (0, import_promises8.readFile)(target),
+                recorded.mediaType ?? MediaType.PNG,
+                recorded.sha256
+              );
+            }
             outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
             continue;
           }
-          let buf = recorded && cacheDir ? await readCachedPng(cacheDir, recorded.sha256) : null;
+          const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
+          let buf = recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null;
           if (buf) {
             log(`  cached  ${import_node_path11.default.relative(process.cwd(), target)}`);
           } else {
@@ -3797,24 +4313,25 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             }
             buf = await provider.download(source.url);
           }
-          if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) {
-            throw new Error(`response for ${source.role ?? "asset"} was not a PNG (${buf.length} bytes)`);
-          }
+          let mediaType;
           try {
-            decodePng(buf);
+            mediaType = validateMedia(buf, expectedMediaType);
           } catch (err) {
+            const label = expectedMediaType === MediaType.GIF ? "GIF" : "PNG";
+            const mismatch = detectMediaType(buf) !== expectedMediaType;
             throw new Error(
-              `response for ${source.role ?? "asset"} was not a valid PNG: ${err instanceof Error ? err.message : String(err)}`
+              `response for ${source.role ?? "asset"} was not ${mismatch ? "a" : "a valid"} ${label}` + (mismatch ? ` (${buf.length} bytes)` : `: ${err instanceof Error ? err.message : String(err)}`)
             );
           }
-          if (cacheDir) await cachePng(cacheDir, buf);
+          if (cacheDir) await cacheMedia(cacheDir, buf, mediaType);
           await (0, import_promises8.mkdir)(import_node_path11.default.dirname(target), { recursive: true });
           const tmp = `${target}.pixelkiln.tmp`;
           await (0, import_promises8.writeFile)(tmp, buf);
           outputs.push({
             path: portableOutputPath(target, spec.root),
             sha256: sha256(buf),
-            ...source.role ? { role: source.role } : {}
+            ...source.role ? { role: source.role } : {},
+            mediaType
           });
           upsert(lock, key, { outputs: mergeOutputs(entry.outputs, outputs) });
           await saveLock(lockPath, lock);
@@ -3851,22 +4368,23 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   await saveLock(lockPath, lock);
   return result;
 }
-async function readCachedPng(cacheDir, hash) {
-  const file = import_node_path11.default.join(cacheDir, `${hash}.png`);
+async function readCachedMedia(cacheDir, hash, mediaType) {
+  const file = import_node_path11.default.join(cacheDir, cacheFileName(hash, mediaType));
   if (!(0, import_node_fs9.existsSync)(file)) return null;
   try {
     const buf = await (0, import_promises8.readFile)(file);
-    if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2) || sha256(buf) !== hash) return null;
-    decodePng(buf);
+    if (sha256(buf) !== hash) return null;
+    validateMedia(buf, mediaType);
     return buf;
   } catch {
     return null;
   }
 }
-async function cachePng(cacheDir, buf, knownHash) {
+async function cacheMedia(cacheDir, buf, mediaType, knownHash) {
   const hash = knownHash ?? sha256(buf);
-  const file = import_node_path11.default.join(cacheDir, `${hash}.png`);
-  if (await readCachedPng(cacheDir, hash)) return;
+  validateMedia(buf, mediaType);
+  const file = import_node_path11.default.join(cacheDir, cacheFileName(hash, mediaType));
+  if (await readCachedMedia(cacheDir, hash, mediaType)) return;
   await (0, import_promises8.mkdir)(cacheDir, { recursive: true });
   const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   await (0, import_promises8.writeFile)(tmp, buf);
@@ -3971,7 +4489,10 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     const hasSource = Boolean(entry.sourceUrl || entry.sourceUrls?.length);
     let hasCache = false;
     for (const output of entry.outputs) {
-      const cached = import_node_path12.default.join(cacheDir, `${output.sha256}.png`);
+      const cached = import_node_path12.default.join(
+        cacheDir,
+        cacheFileName(output.sha256, output.mediaType ?? MediaType.PNG)
+      );
       if ((0, import_node_fs10.existsSync)(cached) && await sha256File(cached) === output.sha256) {
         hasCache = true;
         break;
@@ -4001,11 +4522,14 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     add(
       "provider",
       "error",
-      opts.apiKeyPresent === false ? "PIXELLAB_API_KEY is not configured" : "provider is not configured"
+      opts.apiKeyPresent === false ? `${opts.credentialEnv ?? "PIXELLAB_API_KEY"} is not configured` : "provider is not configured"
     );
+  } else if (!opts.provider.balance) {
+    add("provider", "ok", `${opts.provider.id} configured; balance reporting unavailable`);
   } else {
+    const balanceFn = opts.provider.balance.bind(opts.provider);
     try {
-      const balance = await opts.provider.balance();
+      const balance = await balanceFn();
       add("provider", "ok", `${opts.provider.id} reachable; ${balance.remaining} ${balance.unit} remaining`);
     } catch (err) {
       add("provider", "error", `provider connectivity failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -4496,7 +5020,7 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
         const entry = lock.entries[key];
         if (!group || !entry?.reviewObjectId) continue;
         if (!Number.isInteger(index) || index < 0 || index >= group.frameUrls.length) continue;
-        const { objectId, sourceUrl } = await provider.selectCandidate(
+        const { objectId, sourceUrl } = await requireSelectCandidate(provider)(
           entry.reviewObjectId,
           index,
           `asset:${entry.assetId}`,
@@ -4586,6 +5110,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
   }
   return {
     name,
+    provider: "pixellab",
     styles: {
       [styleId]: {
         generator,
@@ -4598,7 +5123,8 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
         styleImages: [],
         palette: [],
         outDir,
-        tags: [name]
+        tags: [name],
+        providerOptions: {}
       }
     },
     assets
@@ -4956,7 +5482,7 @@ refresh();
 }
 
 // src/pick/salvage-server.ts
-var PNG_SIGNATURE3 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+var PNG_SIGNATURE2 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 async function runSalvage(provider, orphans, ctx, opts = {}) {
   const log = opts.onProgress ?? (() => {
   });
@@ -4988,7 +5514,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
         if (decision.action === "import") {
           try {
             const buf = await provider.download(orphan.previewUrl);
-            if (!buf.subarray(0, 8).equals(PNG_SIGNATURE3)) throw new Error("not a PNG");
+            if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
             decodePng(buf);
             const assetId = idFromPrompt(orphan.prompt, taken);
             const rel = import_node_path16.default.join("_salvaged", `${assetId}.png`);
@@ -5221,7 +5747,6 @@ function emptyStateCounts() {
 }
 async function workspaceStatus(ws, dir) {
   const diagnostics = validateWorkspace(ws, dir);
-  const provider = PixelLabProvider.forOffline();
   const projects = [];
   const totalsByState = emptyStateCounts();
   const totalsSpend = { generations: 0, usd: 0, free: 0 };
@@ -5235,6 +5760,7 @@ async function workspaceStatus(ws, dir) {
       lock: lockPath
     };
     try {
+      const provider = createProvider(project.provider, "offline");
       const loaded = await loadManifest(manifestPath);
       const specs = await resolveSpecs(loaded, { provider });
       const lock = await loadLock(lockPath);
@@ -5246,7 +5772,7 @@ async function workspaceStatus(ws, dir) {
         totalsByState[state] += byState[state];
       }
       for (const unit of Object.keys(spend)) {
-        totalsSpend[unit] += spend[unit];
+        totalsSpend[unit] = (totalsSpend[unit] ?? 0) + (spend[unit] ?? 0);
       }
       projects.push({
         ...base,
@@ -5291,9 +5817,11 @@ async function workspaceStatus(ws, dir) {
   MAX_DOWNLOAD_BYTES,
   MAX_RETRIES,
   ManifestSchema,
+  MediaType,
   PixelLabClient,
   PixelLabError,
   PixelLabProvider,
+  RetroDiffusionProvider,
   StyleSchema,
   UnsupportedCapabilityError,
   WorkspaceProjectSchema,
@@ -5301,16 +5829,20 @@ async function workspaceStatus(ws, dir) {
   adopt,
   applyTags,
   auditStyle,
+  availableProviders,
   backoffMs,
   buildManifest,
   buildPlan,
+  cacheFileName,
   candidateCount,
   clientFromEnv,
   colorDistance,
   countNumberedDescriptions,
   createArtifactBundleManifest,
+  createProvider,
   currentEntryOutputPath,
   currentOutputPath,
+  detectMediaType,
   doctor,
   evaluateAudit,
   expectedOutputPath,
@@ -5333,6 +5865,8 @@ async function workspaceStatus(ws, dir) {
   lockKey,
   matchOrphanStyle,
   measureBalanceChange,
+  mediaExtension,
+  mediaTypeFromExtension,
   mergePalettes,
   mountSprites,
   mountStyle,
@@ -5349,12 +5883,16 @@ async function workspaceStatus(ws, dir) {
   poll,
   portableOutputPath,
   primaryOutput,
+  providerFactory,
   pushTags,
+  registerProvider,
   remove,
   renderSalvageSheet,
   renderSheet,
+  requireBalance,
   requireDelete,
   requireList,
+  requireSelectCandidate,
   resolveEntryOutputs,
   resolveOutputPath,
   resolvePackInputs,
@@ -5388,6 +5926,7 @@ async function workspaceStatus(ws, dir) {
   totalSpend,
   upsert,
   validateCostEstimate,
+  validateMedia,
   validateWorkspace,
   verifyArtifactBundle,
   withArtifactManifest,