pixelkiln 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,6 +1,7 @@
 // src/types.ts
 import { z } from "zod";
-var GeneratorSchema = z.enum(["1dir", "map", "pixflux", "tiles"]);
+var MediaTypeSchema = z.enum(["image/png", "image/gif"]);
+var GeneratorSchema = z.enum(["1dir", "map", "pixflux", "tiles", "animation"]);
 function tileVariationCount(descriptions) {
   return Math.max(1, descriptions) * 4;
 }
@@ -32,7 +33,7 @@ function tilesCost(tileSize, variations) {
   return 40;
 }
 var StyleImageSchema = 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: z.string()
 });
 var StyleSchema = z.object({
@@ -143,7 +144,9 @@ var StyleSchema = z.object({
     out: z.string()
   }).strict().optional(),
   /** Tags applied to every object generated in this style, for server-side filtering. */
-  tags: z.array(z.string()).default([])
+  tags: z.array(z.string()).default([]),
+  /** Adapter-owned settings, keyed by provider id. */
+  providerOptions: z.record(z.record(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"]
@@ -158,7 +161,7 @@ var AssetSchema = z.object({
   height: z.number().int().min(16).max(400).optional(),
   /** Overrides the style default. `1dir` generator only. */
   size: 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: z.string().optional(),
   /**
    * Grid cell this asset owns in a mounted style, as [column, row].
@@ -210,6 +213,8 @@ var AssetSchema = z.object({
 var ManifestSchema = z.object({
   $schema: z.string().optional(),
   name: z.string(),
+  /** Generation backend. Existing manifests remain PixelLab by default. */
+  provider: z.string().min(1).default("pixellab"),
   styles: z.record(StyleSchema),
   assets: z.record(AssetSchema)
 }).strict();
@@ -247,7 +252,8 @@ var LockEntrySchema = z.object({
   sourceUrls: z.array(
     z.object({
       url: z.string(),
-      role: z.string().optional()
+      role: z.string().optional(),
+      mediaType: MediaTypeSchema.optional()
     })
   ).default([]),
   /**
@@ -262,7 +268,8 @@ var LockEntrySchema = z.object({
     z.object({
       path: z.string(),
       sha256: z.string(),
-      role: z.string().optional()
+      role: z.string().optional(),
+      mediaType: MediaTypeSchema.optional()
     })
   ).default([]),
   /**
@@ -276,7 +283,7 @@ var LockEntrySchema = z.object({
   /** Successful-submission estimate in `costUnit`; may be fractional USD. */
   cost: z.number().finite().nonnegative().default(0),
   /** Unit for `cost`. Defaults preserve pre-unit PixelLab lockfiles. */
-  costUnit: z.enum(["generations", "usd", "free"]).default("generations"),
+  costUnit: z.string().min(1).default("generations"),
   /** Which provider produced this. Absent on entries written before providers. */
   provider: z.string().default("pixellab")
 });
@@ -409,11 +416,11 @@ var PixelLabClient = class {
    * common than the failure mode of retrying (a duplicate object), and a
    * duplicate is visible and free to delete whereas a silent gap is neither.
    */
-  async request(path15, init, attempt = 0) {
+  async request(path17, init, attempt = 0) {
     const auth = this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`;
     let res;
     try {
-      res = await fetch(`${BASE}${path15}`, {
+      res = await fetch(`${BASE}${path17}`, {
         ...init,
         signal: init?.signal ?? AbortSignal.timeout(this.timeoutMs),
         headers: {
@@ -425,24 +432,24 @@ var PixelLabClient = class {
     } catch (err) {
       if (attempt < MAX_RETRIES) {
         await sleep(backoffMs(attempt));
-        return this.request(path15, init, attempt + 1);
+        return this.request(path17, init, attempt + 1);
       }
       throw err;
     }
     if (!res.ok && shouldRetry(res.status) && attempt < MAX_RETRIES) {
       const waitMs = retryAfterMs(res.headers.get("retry-after")) ?? backoffMs(attempt);
       await sleep(waitMs);
-      return this.request(path15, init, attempt + 1);
+      return this.request(path17, init, attempt + 1);
     }
     const text = await res.text();
     if (!res.ok) {
-      throw new PixelLabError(`${init?.method ?? "GET"} ${path15} \u2192 ${res.status}`, res.status, text);
+      throw new PixelLabError(`${init?.method ?? "GET"} ${path17} \u2192 ${res.status}`, res.status, text);
     }
     if (!text) return {};
     try {
       return JSON.parse(text);
     } catch {
-      throw new Error(`${init?.method ?? "GET"} ${path15} returned invalid JSON`);
+      throw new Error(`${init?.method ?? "GET"} ${path17} returned invalid JSON`);
     }
   }
   async balance() {
@@ -650,7 +657,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) {
@@ -692,18 +699,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
-import { mkdirSync, existsSync, readFileSync, writeFileSync } from "fs";
-import { randomUUID } from "crypto";
-import os from "os";
-import path from "path";
-
 // src/png.ts
 import { deflateSync, inflateSync } from "zlib";
 var SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
@@ -1061,7 +1073,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
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { randomUUID } from "crypto";
+import os from "os";
+import path from "path";
 var PixelLabProvider = class _PixelLabProvider {
   constructor(client) {
     this.client = client;
@@ -1111,7 +1212,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({
@@ -1297,6 +1435,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);
 }
@@ -1305,6 +1448,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
 import { createHash } from "crypto";
 var FAKE_PNG = Buffer.from(
@@ -1449,6 +1905,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
 import { readFile as readFile2 } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
@@ -1460,12 +1957,16 @@ import { readFile } from "fs/promises";
 function sha256(data) {
   return createHash2("sha256").update(data).digest("hex");
 }
-async function sha256File(path15) {
-  return sha256(await readFile(path15));
+async function sha256File(path17) {
+  return sha256(await readFile(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,
@@ -1479,7 +1980,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,
@@ -1519,6 +2020,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)
@@ -1544,10 +2046,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);
@@ -1567,8 +2067,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;
@@ -1595,6 +2095,8 @@ async function resolveSpecs(loaded, filter) {
       const base = {
         styleId,
         assetId,
+        provider: activeProvider.id,
+        providerOptions: style.providerOptions[activeProvider.id] ?? {},
         generator,
         prompt,
         width,
@@ -1626,11 +2128,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,
@@ -1639,12 +2136,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(path2.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);
     }
   }
@@ -1668,10 +2168,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 });
   }
@@ -1873,12 +2371,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
@@ -1895,16 +2394,16 @@ function resolveOutputPath(recordedPath, manifestDir) {
   if (path4.win32.isAbsolute(recordedPath)) return recordedPath;
   return path4.resolve(manifestDir, recordedPath.split(/[\\/]/).join(path4.sep));
 }
-function expectedOutputPath(spec, role, index, total) {
-  if (total === 1) return spec.outFile;
+function expectedOutputPath(spec, role, index, total, mediaType) {
   const originalExt = path4.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];
@@ -2705,10 +3204,10 @@ function isSha256Hash(value) {
 function parseCache(value) {
   return HashCacheSchema.parse(value);
 }
-async function loadCache(path15) {
-  if (!existsSync6(path15)) return { version: 1, hashes: {} };
+async function loadCache(path17) {
+  if (!existsSync6(path17)) return { version: 1, hashes: {} };
   try {
-    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile6(path15, "utf8")));
+    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile6(path17, "utf8")));
     if (!parsed.success) return { version: 1, hashes: {} };
     return {
       version: 1,
@@ -2720,18 +3219,18 @@ async function loadCache(path15) {
     return { version: 1, hashes: {} };
   }
 }
-async function saveCache(path15, cache) {
+async function saveCache(path17, cache) {
   const sorted = {};
   for (const key of Object.keys(cache.hashes).sort()) {
     const hash = cache.hashes[key];
     if (!isSha256Hash(hash)) throw new Error(`Refusing to cache invalid SHA-256 for ${key}`);
     sorted[key] = hash;
   }
-  await mkdir3(pathModule.dirname(pathModule.resolve(path15)), { recursive: true });
-  const tmp = `${path15}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await mkdir3(pathModule.dirname(pathModule.resolve(path17)), { recursive: true });
+  const tmp = `${path17}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
     await writeFile3(tmp, JSON.stringify({ version: 1, hashes: sorted }, null, 2) + "\n");
-    await rename3(tmp, path15);
+    await rename3(tmp, path17);
   } finally {
     await rm3(tmp, { force: true });
   }
@@ -2752,7 +3251,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 && !existsSync7(lockPath)) {
     throw new Error(`Refusing to prune without an existing lockfile at ${path8.resolve(lockPath)}`);
@@ -2821,7 +3319,8 @@ async function inspectContentCache(contentDir, referenced) {
     }
     report.files++;
     const file = path8.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 readFile7(file);
@@ -2834,11 +3333,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) {
@@ -2846,11 +3341,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;
     }
@@ -3439,7 +3934,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) {
@@ -3491,7 +3986,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,
@@ -3541,7 +4036,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 });
@@ -3579,7 +4075,6 @@ async function poll(provider, lock, lockPath, opts = {}) {
 import { existsSync as existsSync8 } from "fs";
 import { mkdir as mkdir4, readFile as readFile8, rename as rename4, rm as rm5, writeFile as writeFile4 } from "fs/promises";
 import path10 from "path";
-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 ?? (() => {
   });
@@ -3611,7 +4106,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",
@@ -3627,7 +4122,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 (existsSync8(target)) {
             if (!recorded) {
               throw new Error(`refusing to overwrite untracked output ${target}`);
@@ -3635,11 +4130,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 readFile8(target), recorded.sha256);
+            if (cacheDir) {
+              await cacheMedia(
+                cacheDir,
+                await readFile8(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  ${path10.relative(process.cwd(), target)}`);
           } else {
@@ -3648,24 +4151,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 mkdir4(path10.dirname(target), { recursive: true });
           const tmp = `${target}.pixelkiln.tmp`;
           await writeFile4(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);
@@ -3702,22 +4206,23 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   await saveLock(lockPath, lock);
   return result;
 }
-async function readCachedPng(cacheDir, hash) {
-  const file = path10.join(cacheDir, `${hash}.png`);
+async function readCachedMedia(cacheDir, hash, mediaType) {
+  const file = path10.join(cacheDir, cacheFileName(hash, mediaType));
   if (!existsSync8(file)) return null;
   try {
     const buf = await readFile8(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 = path10.join(cacheDir, `${hash}.png`);
-  if (await readCachedPng(cacheDir, hash)) return;
+  validateMedia(buf, mediaType);
+  const file = path10.join(cacheDir, cacheFileName(hash, mediaType));
+  if (await readCachedMedia(cacheDir, hash, mediaType)) return;
   await mkdir4(cacheDir, { recursive: true });
   const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   await writeFile4(tmp, buf);
@@ -3822,7 +4327,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 = path11.join(cacheDir, `${output.sha256}.png`);
+      const cached = path11.join(
+        cacheDir,
+        cacheFileName(output.sha256, output.mediaType ?? MediaType.PNG)
+      );
       if (existsSync9(cached) && await sha256File(cached) === output.sha256) {
         hasCache = true;
         break;
@@ -3852,11 +4360,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)}`);
@@ -4347,7 +4858,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}`,
@@ -4437,6 +4948,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
   }
   return {
     name,
+    provider: "pixellab",
     styles: {
       [styleId]: {
         generator,
@@ -4449,7 +4961,8 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
         styleImages: [],
         palette: [],
         outDir,
-        tags: [name]
+        tags: [name],
+        providerOptions: {}
       }
     },
     assets
@@ -4464,6 +4977,7 @@ function mode(values) {
 // src/pipeline/salvage.ts
 import { readFile as readFile11 } from "fs/promises";
 import { existsSync as existsSync12 } from "fs";
+import path14 from "path";
 async function loadClaims(lockPaths) {
   const claimed = /* @__PURE__ */ new Set();
   for (const p of lockPaths) {
@@ -4516,6 +5030,26 @@ function matchOrphanStyle(prompt, manifest) {
   if (styleIds.length <= 1) return styleIds[0] ?? null;
   return matchStyleByPattern(prompt, manifest);
 }
+async function loadSiblingManifests(ownManifestPath, workspaceManifestPaths, claimPaths) {
+  const own = path14.resolve(ownManifestPath);
+  const siblingManifestPaths = [
+    .../* @__PURE__ */ new Set([
+      ...workspaceManifestPaths,
+      ...claimPaths.map((c) => path14.join(path14.dirname(path14.resolve(c)), "pixelkiln.manifest.json"))
+    ])
+  ];
+  const siblings = [];
+  for (const siblingManifestPath of siblingManifestPaths) {
+    if (path14.resolve(siblingManifestPath) === own) continue;
+    if (!existsSync12(siblingManifestPath)) continue;
+    try {
+      const { manifest } = await loadManifest(siblingManifestPath);
+      siblings.push({ label: path14.basename(path14.dirname(siblingManifestPath)), manifest });
+    } catch {
+    }
+  }
+  return siblings;
+}
 function groupOrphansByStyle(orphans, manifest, siblings = []) {
   const matched = /* @__PURE__ */ new Map();
   const elsewhere = /* @__PURE__ */ new Map();
@@ -4627,7 +5161,7 @@ async function applyTags(provider, decisions, existing, opts = {}) {
 
 // src/pick/salvage-server.ts
 import { mkdir as mkdir5, writeFile as writeFile7, readFile as readFile12 } from "fs/promises";
-import path14 from "path";
+import path15 from "path";
 
 // src/pick/salvage-sheet.ts
 var escapeHtml2 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -4786,13 +5320,13 @@ 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 ?? (() => {
   });
   const html = renderSalvageSheet(orphans, {
     styleId: ctx.styleId,
-    importDir: path14.relative(process.cwd(), ctx.importDir) || "."
+    importDir: path15.relative(process.cwd(), ctx.importDir) || "."
   });
   const byId = new Map(orphans.map((o) => [o.id, o]));
   const existingTags = new Map(orphans.map((o) => [o.id, o.tags]));
@@ -4818,12 +5352,12 @@ 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 = path14.join("_salvaged", `${assetId}.png`);
-            const outFile = path14.resolve(ctx.importDir, rel);
-            await mkdir5(path14.dirname(outFile), { recursive: true });
+            const rel = path15.join("_salvaged", `${assetId}.png`);
+            const outFile = path15.resolve(ctx.importDir, rel);
+            await mkdir5(path15.dirname(outFile), { recursive: true });
             await writeFile7(outFile, buf);
             ctx.manifest.assets[assetId] = {
               prompt: orphan.prompt,
@@ -4850,7 +5384,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               error: null,
               sourceUrl: orphan.previewUrl,
               outputs: [{
-                path: portableOutputPath(outFile, path14.dirname(ctx.manifestPath)),
+                path: portableOutputPath(outFile, path15.dirname(ctx.manifestPath)),
                 sha256: sha256(buf)
               }],
               submittedAt: orphan.createdAt,
@@ -4882,6 +5416,233 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
     }
   });
 }
+
+// src/workspace.ts
+import { mkdir as mkdir6, readFile as readFile13, rename as rename5, rm as rm6, writeFile as writeFile8 } from "fs/promises";
+import { existsSync as existsSync13 } from "fs";
+import path16 from "path";
+import { z as z4 } from "zod";
+var WorkspaceProjectSchema = z4.object({
+  id: z4.string().min(1),
+  /** Manifest path, relative to the catalog file's own directory. */
+  manifest: z4.string().min(1),
+  /** Lockfile path, relative to the catalog file's own directory. */
+  lock: z4.string().min(1),
+  provider: z4.string().min(1).default("pixellab"),
+  /** Free-form label for a shared account, e.g. distinguishing sandboxes. */
+  account: z4.string().optional()
+}).strict();
+var WorkspaceSchema = z4.object({
+  version: z4.literal(1),
+  projects: z4.array(WorkspaceProjectSchema).default([])
+}).strict();
+function parseWorkspace(raw) {
+  const parsed = WorkspaceSchema.safeParse(raw);
+  if (parsed.success) return parsed.data;
+  throw new Error(
+    `Workspace catalog is not valid v1:
+${parsed.error.issues.slice(0, 5).map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n")}`
+  );
+}
+async function loadWorkspace(workspacePath) {
+  if (!existsSync13(workspacePath)) return { version: 1, projects: [] };
+  let raw;
+  try {
+    raw = JSON.parse(await readFile13(workspacePath, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `Workspace catalog at ${workspacePath} is malformed:
+${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return parseWorkspace(raw);
+}
+async function saveWorkspace(workspacePath, ws) {
+  const sorted = {
+    version: 1,
+    projects: [...ws.projects].sort((a, b) => a.id.localeCompare(b.id))
+  };
+  await mkdir6(path16.dirname(path16.resolve(workspacePath)), { recursive: true });
+  const tmp = `${workspacePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    await writeFile8(tmp, JSON.stringify(sorted, null, 2) + "\n");
+    await rename5(tmp, workspacePath);
+  } finally {
+    await rm6(tmp, { force: true });
+  }
+}
+function toPortablePath(dir, absolute) {
+  return path16.relative(dir, absolute).split(path16.sep).join("/");
+}
+function resolveProject(dir, project) {
+  return {
+    manifestPath: path16.resolve(dir, project.manifest.split("/").join(path16.sep)),
+    lockPath: path16.resolve(dir, project.lock.split("/").join(path16.sep))
+  };
+}
+function validateWorkspace(ws, dir) {
+  const diagnostics = [];
+  const idCounts = /* @__PURE__ */ new Map();
+  const lockOwners = /* @__PURE__ */ new Map();
+  const manifestOwners = /* @__PURE__ */ new Map();
+  for (const project of ws.projects) {
+    idCounts.set(project.id, (idCounts.get(project.id) ?? 0) + 1);
+    const { manifestPath, lockPath } = resolveProject(dir, project);
+    lockOwners.set(lockPath, [...lockOwners.get(lockPath) ?? [], project.id]);
+    manifestOwners.set(manifestPath, [...manifestOwners.get(manifestPath) ?? [], project.id]);
+    if (path16.isAbsolute(project.manifest) || path16.isAbsolute(project.lock)) {
+      diagnostics.push({
+        id: "absolute-path",
+        level: "warning",
+        message: `project "${project.id}" stores an absolute path \u2014 the catalog will not resolve correctly if this tree is cloned or moved elsewhere`
+      });
+    }
+    if (!existsSync13(manifestPath)) {
+      diagnostics.push({
+        id: "missing-manifest",
+        level: "error",
+        message: `project "${project.id}" manifest not found: ${manifestPath}`
+      });
+    }
+    if (!existsSync13(lockPath)) {
+      diagnostics.push({
+        id: "missing-lock",
+        level: "error",
+        message: `project "${project.id}" lockfile not found: ${lockPath}`
+      });
+    }
+  }
+  for (const [id, count] of idCounts) {
+    if (count > 1) {
+      diagnostics.push({
+        id: "duplicate-id",
+        level: "error",
+        message: `project id "${id}" is registered ${count} times`
+      });
+    }
+  }
+  for (const [lockPath, ids] of lockOwners) {
+    if (ids.length > 1) {
+      diagnostics.push({
+        id: "duplicate-lock",
+        level: "error",
+        message: `${ids.join(", ")} all register the same lockfile: ${lockPath}`
+      });
+    }
+  }
+  for (const [manifestPath, ids] of manifestOwners) {
+    if (ids.length > 1) {
+      diagnostics.push({
+        id: "duplicate-manifest",
+        level: "warning",
+        message: `${ids.join(", ")} share manifest ${manifestPath} \u2014 expected only when they are variant lockfiles beside one manifest`
+      });
+    }
+  }
+  const providers = new Set(ws.projects.map((p) => p.provider));
+  if (providers.size > 1) {
+    diagnostics.push({
+      id: "mixed-provider",
+      level: "warning",
+      message: `registered projects use different providers: ${[...providers].sort().join(", ")} \u2014 spend totals are kept separate per unit, but confirm this is intentional`
+    });
+  }
+  return diagnostics;
+}
+
+// src/pipeline/workspace.ts
+async function workspaceClaims(ws, dir) {
+  const lockPaths = [];
+  const byProject = {};
+  const claimed = /* @__PURE__ */ new Set();
+  for (const project of ws.projects) {
+    const { lockPath } = resolveProject(dir, project);
+    lockPaths.push(lockPath);
+    let projectClaims;
+    try {
+      projectClaims = await loadClaims([lockPath]);
+    } catch (err) {
+      throw new Error(
+        `Project "${project.id}" lockfile is unreadable: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    byProject[project.id] = projectClaims.size;
+    for (const id of projectClaims) claimed.add(id);
+  }
+  return { claimed, byProject, lockPaths };
+}
+function emptyStateCounts() {
+  return {
+    ok: 0,
+    missing: 0,
+    untracked: 0,
+    stale: 0,
+    orphaned: 0,
+    "in-flight": 0,
+    recoverable: 0,
+    failed: 0
+  };
+}
+async function workspaceStatus(ws, dir) {
+  const diagnostics = validateWorkspace(ws, dir);
+  const projects = [];
+  const totalsByState = emptyStateCounts();
+  const totalsSpend = { generations: 0, usd: 0, free: 0 };
+  for (const project of ws.projects) {
+    const { manifestPath, lockPath } = resolveProject(dir, project);
+    const base = {
+      id: project.id,
+      provider: project.provider,
+      account: project.account ?? null,
+      manifest: manifestPath,
+      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);
+      normalizeLockOutputPaths(lock, specs);
+      const plan = await buildPlan(specs, lock);
+      const byState = summarize(plan);
+      const spend = spendByUnit(lock);
+      for (const state of Object.keys(byState)) {
+        totalsByState[state] += byState[state];
+      }
+      for (const unit of Object.keys(spend)) {
+        totalsSpend[unit] = (totalsSpend[unit] ?? 0) + (spend[unit] ?? 0);
+      }
+      projects.push({
+        ...base,
+        entries: Object.keys(lock.entries).length,
+        byState,
+        spendByUnit: spend,
+        error: null
+      });
+    } catch (err) {
+      projects.push({
+        ...base,
+        entries: 0,
+        byState: emptyStateCounts(),
+        spendByUnit: { generations: 0, usd: 0, free: 0 },
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  let claims = 0;
+  try {
+    claims = (await workspaceClaims(ws, dir)).claimed.size;
+  } catch {
+  }
+  return {
+    version: 1,
+    safe: !diagnostics.some((d) => d.level === "error") && projects.every((p) => !p.error),
+    dir,
+    projects,
+    totals: { byState: totalsByState, spendByUnit: totalsSpend, claims },
+    diagnostics
+  };
+}
 export {
   AssetSchema,
   DEFAULT_RATE_LIMIT,
@@ -4893,24 +5654,32 @@ export {
   MAX_DOWNLOAD_BYTES,
   MAX_RETRIES,
   ManifestSchema,
+  MediaType,
   PixelLabClient,
   PixelLabError,
   PixelLabProvider,
+  RetroDiffusionProvider,
   StyleSchema,
   UnsupportedCapabilityError,
+  WorkspaceProjectSchema,
+  WorkspaceSchema,
   adopt,
   applyTags,
   auditStyle,
+  availableProviders,
   backoffMs,
   buildManifest,
   buildPlan,
+  cacheFileName,
   candidateCount,
   clientFromEnv,
   colorDistance,
   countNumberedDescriptions,
   createArtifactBundleManifest,
+  createProvider,
   currentEntryOutputPath,
   currentOutputPath,
+  detectMediaType,
   doctor,
   evaluateAudit,
   expectedOutputPath,
@@ -4928,9 +5697,13 @@ export {
   loadClaims,
   loadLock,
   loadManifest,
+  loadSiblingManifests,
+  loadWorkspace,
   lockKey,
   matchOrphanStyle,
   measureBalanceChange,
+  mediaExtension,
+  mediaTypeFromExtension,
   mergePalettes,
   mountSprites,
   mountStyle,
@@ -4942,19 +5715,25 @@ export {
   packStyle,
   paletteDistance,
   parseLock,
+  parseWorkspace,
   pngSize,
   poll,
   portableOutputPath,
   primaryOutput,
+  providerFactory,
   pushTags,
+  registerProvider,
   remove,
   renderSalvageSheet,
   renderSheet,
+  requireBalance,
   requireDelete,
   requireList,
+  requireSelectCandidate,
   resolveEntryOutputs,
   resolveOutputPath,
   resolvePackInputs,
+  resolveProject,
   resolveSpecEntryOutputs,
   resolveSpecOutputs,
   resolveSpecs,
@@ -4964,6 +5743,7 @@ export {
   runPicker,
   runSalvage,
   saveLock,
+  saveWorkspace,
   scanAssets,
   selectEntryOutput,
   sha256,
@@ -4979,11 +5759,16 @@ export {
   tileFeatureOutputCount,
   tileVariationCount,
   tilesCost,
+  toPortablePath,
   totalSpend,
   upsert,
   validateCostEstimate,
+  validateMedia,
+  validateWorkspace,
   verifyArtifactBundle,
   withArtifactManifest,
+  workspaceClaims,
+  workspaceStatus,
   writeArtifactBundle,
   writeManagedArtifactBundle
 };