pixelkiln 0.3.0 → 0.4.0

package/dist/cli.js

@@ -38,6 +38,71 @@ function applyEnv(contents) {
   }
 }
 
+// src/provider.ts
+function validateCostEstimate(providerId, value) {
+  if (!value || typeof value !== "object") {
+    throw new Error(`Provider "${providerId}" returned an invalid cost estimate`);
+  }
+  const estimate = value;
+  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) {
+    throw new Error(`Provider "${providerId}" returned an invalid cost amount`);
+  }
+  if (estimate.unit === "free" && estimate.amount !== 0) {
+    throw new Error(`Provider "${providerId}" returned a nonzero amount with the free cost unit`);
+  }
+  if (!Number.isInteger(estimate.candidates) || estimate.candidates < 1) {
+    throw new Error(`Provider "${providerId}" returned an invalid candidate count`);
+  }
+  return estimate;
+}
+function measureBalanceChange(before, after) {
+  if (before.unit !== after.unit || !Number.isFinite(before.remaining) || !Number.isFinite(after.remaining)) return null;
+  const delta = before.remaining - after.remaining;
+  return {
+    unit: before.unit,
+    before: before.remaining,
+    after: after.remaining,
+    spent: Math.max(0, delta),
+    credited: Math.max(0, -delta)
+  };
+}
+var DEFAULT_RATE_LIMIT = { spacingMs: 2500, maxInFlight: 8 };
+var UnsupportedCapabilityError = class extends Error {
+  constructor(providerId, capability) {
+    super(
+      `Provider "${providerId}" does not support ${capability}. That command is unavailable with this backend.`
+    );
+    this.name = "UnsupportedCapabilityError";
+  }
+};
+function requireList(provider) {
+  if (!provider.list) throw new UnsupportedCapabilityError(provider.id, "listing remote assets");
+  return provider.list.bind(provider);
+}
+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)}`;
+  if (unit === "generations") return `${amount} generation${amount === 1 ? "" : "s"}`;
+  return `${amount} ${unit}`;
+}
+
 // src/providers/pixellab.ts
 import { mkdirSync, existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { randomUUID } from "crypto";
@@ -748,7 +813,8 @@ function parseHex(hex2) {
 
 // src/types.ts
 import { z as z2 } from "zod";
-var GeneratorSchema = z2.enum(["1dir", "map", "pixflux", "tiles"]);
+var MediaTypeSchema = z2.enum(["image/png", "image/gif"]);
+var GeneratorSchema = z2.enum(["1dir", "map", "pixflux", "tiles", "animation"]);
 function tileVariationCount(descriptions) {
   return Math.max(1, descriptions) * 4;
 }
@@ -780,7 +846,7 @@ function tilesCost(tileSize, variations) {
   return 40;
 }
 var StyleImageSchema = z2.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: z2.string()
 });
 var StyleSchema = z2.object({
@@ -891,7 +957,9 @@ var StyleSchema = z2.object({
     out: z2.string()
   }).strict().optional(),
   /** Tags applied to every object generated in this style, for server-side filtering. */
-  tags: z2.array(z2.string()).default([])
+  tags: z2.array(z2.string()).default([]),
+  /** Adapter-owned settings, keyed by provider id. */
+  providerOptions: z2.record(z2.record(z2.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"]
@@ -906,7 +974,7 @@ var AssetSchema = z2.object({
   height: z2.number().int().min(16).max(400).optional(),
   /** Overrides the style default. `1dir` generator only. */
   size: z2.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: z2.string().optional(),
   /**
    * Grid cell this asset owns in a mounted style, as [column, row].
@@ -958,6 +1026,8 @@ var AssetSchema = z2.object({
 var ManifestSchema = z2.object({
   $schema: z2.string().optional(),
   name: z2.string(),
+  /** Generation backend. Existing manifests remain PixelLab by default. */
+  provider: z2.string().min(1).default("pixellab"),
   styles: z2.record(StyleSchema),
   assets: z2.record(AssetSchema)
 }).strict();
@@ -995,7 +1065,8 @@ var LockEntrySchema = z2.object({
   sourceUrls: z2.array(
     z2.object({
       url: z2.string(),
-      role: z2.string().optional()
+      role: z2.string().optional(),
+      mediaType: MediaTypeSchema.optional()
     })
   ).default([]),
   /**
@@ -1010,7 +1081,8 @@ var LockEntrySchema = z2.object({
     z2.object({
       path: z2.string(),
       sha256: z2.string(),
-      role: z2.string().optional()
+      role: z2.string().optional(),
+      mediaType: MediaTypeSchema.optional()
     })
   ).default([]),
   /**
@@ -1024,7 +1096,7 @@ var LockEntrySchema = z2.object({
   /** Successful-submission estimate in `costUnit`; may be fractional USD. */
   cost: z2.number().finite().nonnegative().default(0),
   /** Unit for `cost`. Defaults preserve pre-unit PixelLab lockfiles. */
-  costUnit: z2.enum(["generations", "usd", "free"]).default("generations"),
+  costUnit: z2.string().min(1).default("generations"),
   /** Which provider produced this. Absent on entries written before providers. */
   provider: z2.string().default("pixellab")
 });
@@ -1094,7 +1166,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({
@@ -1280,6 +1389,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);
 }
@@ -1288,60 +1402,442 @@ function firstUrl(urls) {
   return Object.values(urls).find((u) => typeof u === "string") ?? null;
 }
 
-// src/provider.ts
-function validateCostEstimate(providerId, value) {
-  if (!value || typeof value !== "object") {
-    throw new Error(`Provider "${providerId}" returned an invalid cost estimate`);
+// 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}`);
   }
-  const estimate = value;
-  if (!["generations", "usd", "free"].includes(estimate.unit)) {
-    throw new Error(`Provider "${providerId}" returned an invalid cost unit`);
+  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)}`);
   }
-  if (!Number.isFinite(estimate.amount) || estimate.amount < 0) {
-    throw new Error(`Provider "${providerId}" returned an invalid cost amount`);
+  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");
   }
-  if (estimate.unit === "free" && estimate.amount !== 0) {
-    throw new Error(`Provider "${providerId}" returned a nonzero amount with the free cost unit`);
+}
+function cacheFileName(hash, mediaType = MediaType.PNG) {
+  return `${hash}${mediaExtension(mediaType)}`;
+}
+
+// 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;
   }
-  if (!Number.isInteger(estimate.candidates) || estimate.candidates < 1) {
-    throw new Error(`Provider "${providerId}" returned an invalid candidate count`);
+  async task(id) {
+    return await this.call(`/inferences/tasks/${encodeURIComponent(id)}`);
   }
-  return estimate;
+  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(path19, init = {}) {
+    if (!this.token) throw new Error("RD_API_KEY is not set");
+    const response = await this.request(`${this.baseUrl}${path19}`, {
+      ...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 measureBalanceChange(before, after) {
-  if (before.unit !== after.unit || !Number.isFinite(before.remaining) || !Number.isFinite(after.remaining)) return null;
-  const delta = before.remaining - after.remaining;
-  return {
-    unit: before.unit,
-    before: before.remaining,
-    after: after.remaining,
-    spent: Math.max(0, delta),
-    credited: Math.max(0, -delta)
-  };
+function resolvedPromptStyle(spec, options) {
+  return options.promptStyle ?? (spec.generator === "animation" ? "rd_animation__any_animation" : spec.generator === "tiles" ? "rd_tile__tileset" : "rd_plus__default");
 }
-var DEFAULT_RATE_LIMIT = { spacingMs: 2500, maxInFlight: 8 };
-var UnsupportedCapabilityError = class extends Error {
-  constructor(providerId, capability) {
-    super(
-      `Provider "${providerId}" does not support ${capability}. That command is unavailable with this backend.`
-    );
-    this.name = "UnsupportedCapabilityError";
+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 requireList(provider) {
-  if (!provider.list) throw new UnsupportedCapabilityError(provider.id, "listing remote assets");
-  return provider.list.bind(provider);
 }
-function requireDelete(provider) {
-  if (!provider.delete) throw new UnsupportedCapabilityError(provider.id, "deleting remote assets");
-  return provider.delete.bind(provider);
+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 formatCost(unit, amount) {
-  if (unit === "free") return "free";
-  if (unit === "usd") return `$${amount.toFixed(2)}`;
-  return `${amount} generation${amount === 1 ? "" : "s"}`;
+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/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);
+}
+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
 import { readFile as readFile2 } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
@@ -1359,6 +1855,10 @@ async function sha256File(path19) {
 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,
@@ -1372,7 +1872,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,
@@ -1412,6 +1912,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)
@@ -1437,10 +1938,8 @@ async function resolveSpecs(loaded, filter) {
       const buf = await readFile2(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);
@@ -1460,8 +1959,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;
@@ -1488,6 +1987,8 @@ async function resolveSpecs(loaded, filter) {
       const base = {
         styleId,
         assetId,
+        provider: activeProvider.id,
+        providerOptions: style.providerOptions[activeProvider.id] ?? {},
         generator,
         prompt,
         width,
@@ -1519,11 +2020,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,
@@ -1532,12 +2028,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(path3.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);
     }
   }
@@ -1561,10 +2060,8 @@ async function resolveStyleImages(loaded, styleId) {
     const buf = await readFile2(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 });
   }
@@ -1770,7 +2267,8 @@ 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;
 }
@@ -1788,16 +2286,16 @@ function resolveOutputPath(recordedPath, manifestDir) {
   if (path5.win32.isAbsolute(recordedPath)) return recordedPath;
   return path5.resolve(manifestDir, recordedPath.split(/[\\/]/).join(path5.sep));
 }
-function expectedOutputPath(spec, role, index, total) {
-  if (total === 1) return spec.outFile;
+function expectedOutputPath(spec, role, index, total, mediaType) {
   const originalExt = path5.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];
@@ -2255,7 +2753,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) {
@@ -2307,7 +2805,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,
@@ -2357,7 +2855,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 });
@@ -2395,7 +2894,6 @@ async function poll(provider, lock, lockPath, opts = {}) {
 import { existsSync as existsSync6 } from "fs";
 import { mkdir as mkdir2, readFile as readFile4, rename as rename2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
 import path8 from "path";
-var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   const log2 = opts.onProgress ?? (() => {
   });
@@ -2427,7 +2925,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",
@@ -2443,7 +2941,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 (existsSync6(target)) {
             if (!recorded) {
               throw new Error(`refusing to overwrite untracked output ${target}`);
@@ -2451,11 +2949,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 readFile4(target), recorded.sha256);
+            if (cacheDir) {
+              await cacheMedia(
+                cacheDir,
+                await readFile4(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) {
             log2(`  cached  ${path8.relative(process.cwd(), target)}`);
           } else {
@@ -2464,24 +2970,25 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             }
             buf = await provider.download(source.url);
           }
-          if (!buf.subarray(0, 8).equals(PNG_SIGNATURE)) {
-            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 mkdir2(path8.dirname(target), { recursive: true });
           const tmp = `${target}.pixelkiln.tmp`;
           await writeFile2(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);
@@ -2518,22 +3025,23 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   await saveLock(lockPath, lock);
   return result;
 }
-async function readCachedPng(cacheDir, hash) {
-  const file = path8.join(cacheDir, `${hash}.png`);
+async function readCachedMedia(cacheDir, hash, mediaType) {
+  const file = path8.join(cacheDir, cacheFileName(hash, mediaType));
   if (!existsSync6(file)) return null;
   try {
     const buf = await readFile4(file);
-    if (!buf.subarray(0, 8).equals(PNG_SIGNATURE) || 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 = path8.join(cacheDir, `${hash}.png`);
-  if (await readCachedPng(cacheDir, hash)) return;
+  validateMedia(buf, mediaType);
+  const file = path8.join(cacheDir, cacheFileName(hash, mediaType));
+  if (await readCachedMedia(cacheDir, hash, mediaType)) return;
   await mkdir2(cacheDir, { recursive: true });
   const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   await writeFile2(tmp, buf);
@@ -2638,7 +3146,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 = path9.join(cacheDir, `${output.sha256}.png`);
+      const cached = path9.join(
+        cacheDir,
+        cacheFileName(output.sha256, output.mediaType ?? MediaType.PNG)
+      );
       if (existsSync7(cached) && await sha256File(cached) === output.sha256) {
         hasCache = true;
         break;
@@ -2668,11 +3179,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)}`);
@@ -3259,7 +3773,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}`,
@@ -3349,6 +3863,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
   }
   return {
     name,
+    provider: "pixellab",
     styles: {
       [styleId]: {
         generator,
@@ -3361,7 +3876,8 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
         styleImages: [],
         palette: [],
         outDir,
-        tags: [name]
+        tags: [name],
+        providerOptions: {}
       }
     },
     assets
@@ -3727,7 +4243,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 };
@@ -3741,6 +4256,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);
@@ -3752,7 +4268,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,
@@ -3945,7 +4461,6 @@ function hex(c) {
 import { existsSync as existsSync14 } from "fs";
 import { readFile as readFile11, readdir as readdir2, rm as rm5 } from "fs/promises";
 import path15 from "path";
-var PNG_SIGNATURE2 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 async function inspectCaches(lock, lockPath, options = {}) {
   if (options.prune && !existsSync14(lockPath)) {
     throw new Error(`Refusing to prune without an existing lockfile at ${path15.resolve(lockPath)}`);
@@ -4014,7 +4529,8 @@ async function inspectContentCache(contentDir, referenced) {
     }
     report.files++;
     const file = path15.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 readFile11(file);
@@ -4027,11 +4543,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_SIGNATURE2)) {
-      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) {
@@ -4039,11 +4551,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;
     }
@@ -4499,7 +5011,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 log2 = opts.onProgress ?? (() => {
   });
@@ -4531,7 +5043,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 = path16.join("_salvaged", `${assetId}.png`);
@@ -5234,7 +5746,7 @@ function parseArgs(argv) {
     account: get("--account")
   };
 }
-var HELP = `pixelkiln \u2014 manifest-driven pixel art generation (PixelLab)
+var HELP = `pixelkiln \u2014 manifest-driven pixel art generation
 
   pixelkiln <command> [options]
 
@@ -5383,8 +5895,9 @@ async function main() {
   if (args.command === "balance") {
     loadEnvFiles(path18.dirname(path18.resolve(args.manifest)));
     loadEnvFiles(process.cwd());
-    const p = PixelLabProvider.fromEnv();
-    const b = await p.balance();
+    const loaded2 = await loadManifest(args.manifest);
+    const p = createProvider(loaded2.manifest.provider, "online");
+    const b = await requireBalance(p)();
     log(`  provider:  ${p.id}`);
     log(`  plan:      ${b.plan ?? "n/a"}`);
     log(`  remaining: ${formatCost(b.unit, b.remaining)}${b.total ? ` of ${b.total}` : ""}`);
@@ -5506,7 +6019,7 @@ async function main() {
         id,
         manifest: toPortablePath(dir, manifestPath),
         lock: toPortablePath(dir, lockPath),
-        provider: args.provider ?? "pixellab",
+        provider: args.provider ?? loadedTarget.manifest.provider,
         ...args.account ? { account: args.account } : {}
       };
       await saveWorkspace(workspacePath, { version: 1, projects: [...ws.projects, project] });
@@ -5576,15 +6089,15 @@ async function main() {
   ${p.id}  (${p.provider}${p.account ? `, ${p.account}` : ""})`);
           log(`    ${p.entries} lock entries`);
           for (const [state, n] of Object.entries(p.byState)) if (n) log(`      ${state.padEnd(12)} ${n}`);
-          for (const unit of ["generations", "usd", "free"]) {
-            if (p.spendByUnit[unit]) log(`    spend: ${formatCost(unit, p.spendByUnit[unit])}`);
+          for (const [unit, amount] of Object.entries(p.spendByUnit).sort()) {
+            if (amount) log(`    spend: ${formatCost(unit, amount)}`);
           }
         }
         log(`
   totals:`);
         for (const [state, n] of Object.entries(report.totals.byState)) if (n) log(`    ${state.padEnd(12)} ${n}`);
-        for (const unit of ["generations", "usd", "free"]) {
-          if (report.totals.spendByUnit[unit]) log(`    spend: ${formatCost(unit, report.totals.spendByUnit[unit])}`);
+        for (const [unit, amount] of Object.entries(report.totals.spendByUnit).sort()) {
+          if (amount) log(`    spend: ${formatCost(unit, amount)}`);
         }
         log(`    claims: ${report.totals.claims}`);
         for (const d of report.diagnostics) log(`  ${d.level === "error" ? "ERROR" : "WARN "} ${d.id.padEnd(18)} ${d.message}`);
@@ -5618,7 +6131,7 @@ async function main() {
   const envFiles = [...loadEnvFiles(manifestDir)];
   if (path18.resolve(process.cwd()) !== manifestDir) envFiles.push(...loadEnvFiles(process.cwd()));
   const loaded = await loadManifest(args.manifest);
-  const estimator = PixelLabProvider.forOffline();
+  const estimator = createProvider(loaded.manifest.provider, "offline");
   const specs = await resolveSpecs(loaded, {
     styles: args.styles,
     assets: args.assets,
@@ -5637,9 +6150,9 @@ async function main() {
     for (const [s, n] of Object.entries(byStatus).sort()) log(`    ${s.padEnd(12)} ${n}`);
     const spend = spendByUnit(lock);
     let reported = false;
-    for (const unit of ["generations", "usd", "free"]) {
-      if (spend[unit]) {
-        log(`  recorded successful submissions: ${formatCost(unit, spend[unit])}`);
+    for (const [unit, amount] of Object.entries(spend).sort()) {
+      if (amount) {
+        log(`  recorded successful submissions: ${formatCost(unit, amount)}`);
         reported = true;
       }
     }
@@ -5648,12 +6161,14 @@ async function main() {
   }
   const plan = await buildPlan(specs, lock, { force: args.force });
   if (args.command === "doctor") {
-    const apiKeyPresent = Boolean(process.env.PIXELLAB_API_KEY);
-    const provider2 = !args.dryRun && apiKeyPresent ? PixelLabProvider.fromEnv() : void 0;
+    const factory = providerFactory(loaded.manifest.provider);
+    const apiKeyPresent = !factory.credentialEnv || Boolean(process.env[factory.credentialEnv]);
+    const provider2 = !args.dryRun && apiKeyPresent ? createProvider(loaded.manifest.provider, "online") : void 0;
     const report = await doctor(loaded, specs, lock, args.lock, {
       provider: provider2,
       offline: args.dryRun,
-      apiKeyPresent
+      apiKeyPresent,
+      credentialEnv: factory.credentialEnv
     });
     if (args.json) {
       log(JSON.stringify(report, null, 2));
@@ -5953,7 +6468,7 @@ async function main() {
     }
     return;
   }
-  const provider = args.command === "restore" || args.command === "fetch" && !args.tag ? PixelLabProvider.forDownloads() : PixelLabProvider.fromEnv();
+  const provider = args.command === "restore" || args.command === "fetch" && !args.tag ? createProvider(loaded.manifest.provider, "downloads") : createProvider(loaded.manifest.provider, "online");
   if (args.command === "adopt") {
     log(`
   Reconciling account objects against files already on disk\u2026`);
@@ -6196,7 +6711,7 @@ async function main() {
       return;
     }
     log(`
-  This permanently deletes them from your PixelLab account.`);
+  This permanently deletes them from your ${provider.id} account.`);
     log(`  Any local files already downloaded are untouched, but the objects`);
     log(`  and their URLs are gone and cannot be re-downloaded.`);
     if (!await confirm(`  Delete ${doomed.length} object(s)?`, args.yes)) {
@@ -6231,21 +6746,26 @@ async function main() {
       return;
     }
     if (plan.actionable.length) {
-      const balance = await provider.balance();
-      log(`
+      const balance = provider.balance ? await provider.balance() : null;
+      if (balance) {
+        log(`
   balance: ${formatCost(balance.unit, balance.remaining)} remaining (${provider.id})`);
-      if (balance.unit !== plan.costUnit) {
-        throw new Error(
-          `Provider estimate unit ${plan.costUnit} does not match balance unit ${balance.unit}.`
-        );
-      }
-      if (balance.unit !== "free" && plan.cost > balance.remaining) {
-        throw new Error(
-          `This run needs ${formatCost(balance.unit, plan.cost)} but only ${formatCost(balance.unit, balance.remaining)} remain.`
-        );
+        if (balance.unit !== plan.costUnit) {
+          throw new Error(
+            `Provider estimate unit ${plan.costUnit} does not match balance unit ${balance.unit}.`
+          );
+        }
+        if (balance.unit !== "free" && plan.cost > balance.remaining) {
+          throw new Error(
+            `This run needs ${formatCost(balance.unit, plan.cost)} but only ${formatCost(balance.unit, balance.remaining)} remain.`
+          );
+        }
+      } else {
+        log(`
+  ${provider.id} does not expose an account balance; enforcing the explicit run budget`);
       }
       const ok = await confirm(
-        `  Spend ${formatCost(balance.unit, plan.cost)} on ${plan.actionable.length} asset(s)?`,
+        `  Spend ${formatCost(plan.costUnit, plan.cost)} on ${plan.actionable.length} asset(s)?`,
         args.yes
       );
       if (!ok) {
@@ -6263,7 +6783,8 @@ async function main() {
   submitted ${res.submitted}, failed ${res.failed}, estimated ${formatCost(res.unit, res.spent)}`
       );
       try {
-        const after = await provider.balance();
+        const after = balance && provider.balance ? await provider.balance() : null;
+        if (!balance || !after) throw new Error("balance reporting is unsupported");
         const measured = measureBalanceChange(balance, after);
         if (measured) {
           const movement = measured.credited ? `${formatCost(measured.unit, measured.credited)} credited` : `${formatCost(measured.unit, measured.spent)} consumed`;