pixelkiln 0.17.0 → 0.19.0

package/dist/cli.js

@@ -123,13 +123,14 @@ async function sha256File(path25) {
     stream.on("end", () => resolve(hash.digest("hex")));
   });
 }
-function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions) {
+function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions, providerInputIdentity = spec.providerInputs ?? {}) {
   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: providerOptionIdentity && (typeof providerOptionIdentity !== "object" || Object.keys(providerOptionIdentity).length > 0) ? providerOptionIdentity : void 0,
+      providerInputs: providerInputIdentity && (typeof providerInputIdentity !== "object" || Object.keys(providerInputIdentity).length > 0) ? providerInputIdentity : void 0,
       generator: spec.generator,
       prompt: spec.prompt,
       width: spec.width,
@@ -604,6 +605,16 @@ function cacheFileName(hash, mediaType = MediaType.PNG) {
 
 // src/providers/comfyui.ts
 var DEFAULT_BASE_URL = "http://127.0.0.1:8188";
+var BUILTIN_BINDINGS = /* @__PURE__ */ new Set([
+  "prompt",
+  "width",
+  "height",
+  "batchSize",
+  "seed",
+  "sourceImage",
+  "maskImage",
+  "strength"
+]);
 var ComfyUIClient = class {
   constructor(baseUrl = process.env.COMFYUI_BASE_URL ?? DEFAULT_BASE_URL, request = fetch) {
     this.request = request;
@@ -748,23 +759,105 @@ var ComfyUIProvider = class _ComfyUIProvider {
       identity: {
         outputNodeId: options.outputNodeId,
         numImages: options.numImages,
+        ...options.frames ? { frames: options.frames } : {},
         bindings: options.bindings,
         workflowSha256
       }
     };
   }
+  async resolveInputs(value, context) {
+    const options = parseOptions(context.providerOptions);
+    if (!options.workflow || !options.workflowSha256) {
+      throw new Error("ComfyUI provider inputs require resolved workflow options");
+    }
+    const inputs = {};
+    const identity = {};
+    for (const [name, input] of Object.entries(value)) {
+      if (BUILTIN_BINDINGS.has(name)) {
+        throw new Error(
+          `ComfyUI providerInputs.${name} is reserved; use PixelKiln's built-in ${name} field`
+        );
+      }
+      const binding = Object.hasOwn(options.bindings, name) ? options.bindings[name] : void 0;
+      if (!binding) {
+        throw new Error(
+          `ComfyUI providerInputs.${name} has no matching bindings.${name} target`
+        );
+      }
+      const resolveValue = async (item, index) => {
+        const label = `providerInputs.${name}${index == null ? "" : `[${index}]`}`;
+        if (isImageBinding(options.workflow, binding)) {
+          if (typeof item !== "string") {
+            throw new Error(`ComfyUI ${label} must be a manifest-relative PNG or JPEG path`);
+          }
+          const file = path2.resolve(context.root, item);
+          let bytes;
+          try {
+            bytes = await readFile(file);
+          } catch (error) {
+            throw new Error(
+              `ComfyUI ${label} could not be read at ${file}: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+          const format = inputImageFormat(bytes);
+          if (!format) throw new Error(`ComfyUI ${label} is not a PNG or JPEG: ${file}`);
+          const hash = sha256(bytes);
+          return {
+            runtime: { kind: "image", path: file, sha256: hash, format },
+            stable: { kind: "image", sha256: hash, format }
+          };
+        }
+        const current = options.workflow[binding.nodeId].inputs[binding.input];
+        if (typeof current !== "string" && typeof current !== "number" && typeof current !== "boolean") {
+          throw new Error(
+            `ComfyUI ${label} cannot replace non-scalar ${binding.nodeId}.${binding.input}`
+          );
+        }
+        if (typeof current !== typeof item) {
+          throw new Error(
+            `ComfyUI ${label} must be ${typeof current} to match ${binding.nodeId}.${binding.input}`
+          );
+        }
+        return { runtime: item, stable: item };
+      };
+      if (Array.isArray(input)) {
+        if (!options.frames || name !== options.frames.vary) {
+          throw new Error(
+            `ComfyUI providerInputs.${name} is an array but frames.vary is ${options.frames ? `"${options.frames.vary}"` : "not configured"}`
+          );
+        }
+        const resolved = await Promise.all(input.map((item, index) => resolveValue(item, index)));
+        inputs[name] = resolved.map((item) => item.runtime);
+        identity[name] = resolved.map((item) => item.stable);
+      } else {
+        const resolved = await resolveValue(input);
+        inputs[name] = resolved.runtime;
+        identity[name] = resolved.stable;
+      }
+    }
+    return { inputs, identity };
+  }
   supports(generator) {
-    return generator === "map";
+    return generator === "map" || generator === "frames";
   }
   supportsRevision(_mode) {
     return true;
   }
   estimate(spec) {
-    return { unit: "free", amount: 0, candidates: resolvedOptions(spec).numImages };
+    return {
+      unit: "free",
+      amount: 0,
+      candidates: spec.generator === "frames" ? 1 : resolvedOptions(spec).numImages
+    };
   }
   validate(spec, styleImages) {
     const options = resolvedOptions(spec);
-    if (spec.source && !spec.revision) return;
+    if (spec.source && !spec.revision) {
+      if (spec.generator === "frames") {
+        throw new Error("ComfyUI frame sets require generated provider outputs, not asset.source");
+      }
+      return;
+    }
     if (spec.width < 16 || spec.height < 16 || spec.width > 4096 || spec.height > 4096) {
       throw new Error("ComfyUI output dimensions must be between 16 and 4096 pixels");
     }
@@ -786,6 +879,25 @@ var ComfyUIProvider = class _ComfyUIProvider {
     if (options.numImages > 1 && !options.bindings.batchSize) {
       throw new Error("ComfyUI numImages greater than 1 requires bindings.batchSize");
     }
+    if (spec.generator === "frames") {
+      if (!options.frames) throw new Error("ComfyUI frames generation requires providerOptions.comfyui.frames");
+      if (options.numImages !== 1) throw new Error("ComfyUI frames generation requires numImages: 1");
+      if (spec.revision) throw new Error("ComfyUI frame sets do not support asset revisions yet");
+      const values = spec.providerInputs?.[options.frames.vary];
+      if (!Array.isArray(values) || values.length < 2 || values.length > 64) {
+        throw new Error(
+          `ComfyUI frames.vary "${options.frames.vary}" requires a providerInputs array of 2\u201364 values`
+        );
+      }
+      if (options.frames.seedStep !== 0 && (spec.seed == null || !options.bindings.seed)) {
+        throw new Error("ComfyUI frames.seedStep requires a style seed and bindings.seed");
+      }
+      if (spec.seed != null && !Number.isSafeInteger(spec.seed + (values.length - 1) * options.frames.seedStep)) {
+        throw new Error("ComfyUI frame seed schedule exceeds JavaScript's safe integer range");
+      }
+    } else if (options.frames) {
+      throw new Error("ComfyUI providerOptions.frames requires generator: frames");
+    }
     if (spec.revision) {
       if (!options.bindings.sourceImage) {
         throw new Error("ComfyUI revisions require bindings.sourceImage");
@@ -810,16 +922,64 @@ var ComfyUIProvider = class _ComfyUIProvider {
   async submit(spec, styleImages) {
     this.validate(spec, styleImages);
     const options = resolvedOptions(spec);
-    const workflow = structuredClone(options.workflow);
-    setBinding(workflow, options.bindings.prompt, spec.prompt);
-    if (options.bindings.width) setBinding(workflow, options.bindings.width, spec.width);
-    if (options.bindings.height) setBinding(workflow, options.bindings.height, spec.height);
-    if (options.bindings.batchSize) {
-      setBinding(workflow, options.bindings.batchSize, options.numImages);
-    }
-    if (spec.seed != null && options.bindings.seed) {
-      setBinding(workflow, options.bindings.seed, spec.seed);
+    const uploadedImages = /* @__PURE__ */ new Map();
+    const bindInput = async (workflow2, name, input) => {
+      const binding = Object.hasOwn(options.bindings, name) ? options.bindings[name] : void 0;
+      if (!binding) throw new Error(`ComfyUI provider input "${name}" has no binding`);
+      if (!isComfyImageInput(input)) {
+        setBinding(workflow2, binding, input);
+        return;
+      }
+      const bytes = await readFile(input.path);
+      if (sha256(bytes) !== input.sha256) {
+        throw new Error(`ComfyUI provider input "${name}" changed before upload`);
+      }
+      let uploaded = uploadedImages.get(input.sha256);
+      if (!uploaded) {
+        uploaded = await this.client.uploadImage(bytes, input.sha256, input.format);
+        uploadedImages.set(input.sha256, uploaded);
+      }
+      setBinding(workflow2, binding, uploaded);
+    };
+    const buildWorkflow = async (frameIndex) => {
+      const workflow2 = structuredClone(options.workflow);
+      setBinding(workflow2, options.bindings.prompt, spec.prompt);
+      if (options.bindings.width) setBinding(workflow2, options.bindings.width, spec.width);
+      if (options.bindings.height) setBinding(workflow2, options.bindings.height, spec.height);
+      if (options.bindings.batchSize) setBinding(workflow2, options.bindings.batchSize, options.numImages);
+      if (spec.seed != null && options.bindings.seed) {
+        const seed = frameIndex == null ? spec.seed : spec.seed + frameIndex * (options.frames?.seedStep ?? 0);
+        setBinding(workflow2, options.bindings.seed, seed);
+      }
+      for (const [name, input] of Object.entries(spec.providerInputs ?? {})) {
+        const selected = Array.isArray(input) ? frameIndex == null ? input : input[frameIndex] : input;
+        await bindInput(workflow2, name, selected);
+      }
+      return workflow2;
+    };
+    const inputs = providerInputProvenance(spec.providerInputs);
+    if (spec.generator === "frames") {
+      const frames = options.frames;
+      const values = spec.providerInputs[frames.vary];
+      const promptIds = [];
+      for (let index = 0; index < values.length; index++) {
+        promptIds.push(await this.client.submit(await buildWorkflow(index)));
+      }
+      return {
+        jobId: encodeFrameSetJob({ promptIds, outputNodeId: options.outputNodeId }),
+        metadata: {
+          inputs,
+          frameSet: {
+            count: values.length,
+            vary: frames.vary,
+            seedStep: frames.seedStep,
+            fps: spec.quality?.fps ?? 12,
+            promptIds
+          }
+        }
+      };
     }
+    const workflow = await buildWorkflow();
     if (spec.revision) {
       if (!spec.revision.sourceSha256 || !spec.revision.sourceFormat) {
         throw new Error("ComfyUI revision source is not ready");
@@ -854,21 +1014,63 @@ var ComfyUIProvider = class _ComfyUIProvider {
       }
     }
     const promptId = await this.client.submit(workflow);
-    return {
-      jobId: encodeJob(promptId, options.outputNodeId),
+    const metadata = {
+      ...Object.keys(inputs).length ? { inputs } : {},
       ...spec.revision ? {
-        metadata: {
-          revision: {
-            mode: spec.revision.mode,
-            sourceAssetId: spec.revision.sourceAssetId,
-            sourceSha256: spec.revision.sourceSha256,
-            ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {}
-          }
+        revision: {
+          mode: spec.revision.mode,
+          sourceAssetId: spec.revision.sourceAssetId,
+          sourceSha256: spec.revision.sourceSha256,
+          ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {}
         }
       } : {}
     };
+    return {
+      jobId: encodeJob(promptId, options.outputNodeId),
+      ...Object.keys(metadata).length ? { metadata } : {}
+    };
   }
-  async poll(jobId, _generator, context) {
+  async poll(jobId, generator, context) {
+    if (generator === "frames") {
+      const frameJob = decodeFrameSetJob(jobId);
+      const images2 = [];
+      for (let index = 0; index < frameJob.promptIds.length; index++) {
+        const promptId2 = frameJob.promptIds[index];
+        const history2 = await this.client.history(promptId2);
+        const entry2 = historyEntry(history2, promptId2);
+        if (!entry2) return { status: "processing" };
+        const status2 = isObject(entry2.status) ? entry2.status : {};
+        if (status2.status_str === "error") {
+          return { status: "failed", error: `frame ${index}: ${historyError(status2)}` };
+        }
+        if (status2.completed === false) return { status: "processing" };
+        const output = outputImages(entry2, frameJob.outputNodeId);
+        if (output instanceof Error) {
+          return { status: "failed", error: `frame ${index}: ${output.message}` };
+        }
+        if (output.length !== 1) {
+          return {
+            status: "failed",
+            error: `frame ${index}: ComfyUI returned ${output.length} images, expected 1`
+          };
+        }
+        images2.push(output[0]);
+      }
+      const fps = context?.spec?.quality?.fps ?? 12;
+      const sources = images2.map((image, index) => ({
+        url: sourceRef(image),
+        role: frameRole(index),
+        mediaType: MediaType.PNG
+      }));
+      return {
+        status: "review-set",
+        objectId: jobId,
+        frameUrls: images2.map((image) => this.client.viewUrl(image)),
+        sources,
+        fps,
+        metadata: context?.spec ? comfyFrameMetadata(context.spec, frameJob, images2, fps) : { frameSet: { count: images2.length, fps, promptIds: frameJob.promptIds } }
+      };
+    }
     const { promptId, outputNodeId } = decodeJob(jobId);
     const history = await this.client.history(promptId);
     const entry = historyEntry(history, promptId);
@@ -931,7 +1133,15 @@ var ComfyUIProvider = class _ComfyUIProvider {
   }
 };
 function parseOptions(value) {
-  const allowed = /* @__PURE__ */ new Set(["workflowFile", "outputNodeId", "numImages", "bindings", "workflow", "workflowSha256"]);
+  const allowed = /* @__PURE__ */ new Set([
+    "workflowFile",
+    "outputNodeId",
+    "numImages",
+    "frames",
+    "bindings",
+    "workflow",
+    "workflowSha256"
+  ]);
   const extra = Object.keys(value).filter((key) => !allowed.has(key));
   if (extra.length) throw new Error(`Unknown ComfyUI option(s): ${extra.join(", ")}`);
   const workflowFile = requiredString(value.workflowFile, "workflowFile");
@@ -941,28 +1151,19 @@ function parseOptions(value) {
     throw new Error("ComfyUI numImages must be a whole number from 1 to 16");
   }
   if (!isObject(value.bindings)) throw new Error("ComfyUI bindings must be an object");
-  const bindingKeys = /* @__PURE__ */ new Set([
-    "prompt",
-    "width",
-    "height",
-    "batchSize",
-    "seed",
-    "sourceImage",
-    "maskImage",
-    "strength"
-  ]);
-  const extraBindings = Object.keys(value.bindings).filter((key) => !bindingKeys.has(key));
-  if (extraBindings.length) throw new Error(`Unknown ComfyUI binding(s): ${extraBindings.join(", ")}`);
-  const bindings = {
-    prompt: parseBinding(value.bindings.prompt, "prompt"),
-    ...value.bindings.width == null ? {} : { width: parseBinding(value.bindings.width, "width") },
-    ...value.bindings.height == null ? {} : { height: parseBinding(value.bindings.height, "height") },
-    ...value.bindings.batchSize == null ? {} : { batchSize: parseBinding(value.bindings.batchSize, "batchSize") },
-    ...value.bindings.seed == null ? {} : { seed: parseBinding(value.bindings.seed, "seed") },
-    ...value.bindings.sourceImage == null ? {} : { sourceImage: parseBinding(value.bindings.sourceImage, "sourceImage") },
-    ...value.bindings.maskImage == null ? {} : { maskImage: parseBinding(value.bindings.maskImage, "maskImage") },
-    ...value.bindings.strength == null ? {} : { strength: parseBinding(value.bindings.strength, "strength") }
-  };
+  const bindings = Object.fromEntries(
+    Object.entries(value.bindings).map(([name, binding]) => [name, parseBinding(binding, name)])
+  );
+  if (!bindings.prompt) throw new Error("ComfyUI bindings.prompt must be an object");
+  const frames = value.frames == null ? void 0 : parseFrames(value.frames);
+  if (frames) {
+    if (BUILTIN_BINDINGS.has(frames.vary)) {
+      throw new Error(`ComfyUI frames.vary must name a custom binding, not "${frames.vary}"`);
+    }
+    if (!Object.hasOwn(bindings, frames.vary)) {
+      throw new Error(`ComfyUI frames.vary "${frames.vary}" has no matching binding`);
+    }
+  }
   const workflow = value.workflow == null ? void 0 : parseWorkflow(value.workflow, workflowFile);
   const workflowSha256 = value.workflowSha256 == null ? void 0 : requiredString(value.workflowSha256, "workflowSha256");
   return {
@@ -970,10 +1171,22 @@ function parseOptions(value) {
     outputNodeId,
     numImages: Number(numImages),
     bindings,
+    ...frames ? { frames } : {},
     ...workflow ? { workflow } : {},
     ...workflowSha256 ? { workflowSha256 } : {}
   };
 }
+function parseFrames(value) {
+  if (!isObject(value)) throw new Error("ComfyUI frames must be an object");
+  const extra = Object.keys(value).filter((key) => key !== "vary" && key !== "seedStep");
+  if (extra.length) throw new Error(`Unknown ComfyUI frames field(s): ${extra.join(", ")}`);
+  const vary = requiredString(value.vary, "frames.vary");
+  const seedStep = value.seedStep ?? 0;
+  if (!Number.isSafeInteger(seedStep) || Math.abs(Number(seedStep)) > 1e6) {
+    throw new Error("ComfyUI frames.seedStep must be a safe integer from -1000000 to 1000000");
+  }
+  return { vary, seedStep: Number(seedStep) };
+}
 function resolvedOptions(spec) {
   const options = parseOptions(spec.providerOptions);
   if (!options.workflow || !options.workflowSha256) {
@@ -1002,6 +1215,7 @@ function parseWorkflow(value, label) {
   return value;
 }
 function validateWorkflowBindings(workflow, options) {
+  const targets = /* @__PURE__ */ new Map();
   for (const [name, binding] of Object.entries(options.bindings)) {
     if (!binding) continue;
     const node = workflow[binding.nodeId];
@@ -1011,6 +1225,12 @@ function validateWorkflowBindings(workflow, options) {
         `ComfyUI ${name} binding refers to missing input "${binding.input}" on node "${binding.nodeId}"`
       );
     }
+    const target = `${binding.nodeId}.${binding.input}`;
+    const prior = targets.get(target);
+    if (prior) {
+      throw new Error(`ComfyUI bindings.${name} and bindings.${prior} target the same input ${target}`);
+    }
+    targets.set(target, name);
   }
   if (!workflow[options.outputNodeId]) {
     throw new Error(`ComfyUI outputNodeId refers to missing node "${options.outputNodeId}"`);
@@ -1048,6 +1268,7 @@ function outputImages(entry, outputNodeId) {
 }
 function comfyMetadata(spec, promptId, outputNodeId, images) {
   const options = resolvedOptions(spec);
+  const inputs = providerInputProvenance(spec.providerInputs);
   return {
     promptId,
     outputNodeId,
@@ -1055,6 +1276,7 @@ function comfyMetadata(spec, promptId, outputNodeId, images) {
     workflowFile: options.workflowFile,
     workflowSha256: options.workflowSha256,
     files: images.map((image) => ({ ...image })),
+    ...Object.keys(inputs).length ? { inputs } : {},
     ...spec.revision ? {
       revision: {
         mode: spec.revision.mode,
@@ -1066,9 +1288,83 @@ function comfyMetadata(spec, promptId, outputNodeId, images) {
     } : {}
   };
 }
+function comfyFrameMetadata(spec, job, images, fps) {
+  const options = resolvedOptions(spec);
+  return {
+    workflowFile: options.workflowFile,
+    workflowSha256: options.workflowSha256,
+    outputNodeId: job.outputNodeId,
+    inputs: providerInputProvenance(spec.providerInputs),
+    frameSet: {
+      count: images.length,
+      vary: options.frames.vary,
+      seedStep: options.frames.seedStep,
+      fps,
+      promptIds: job.promptIds,
+      frames: images.map((image, index) => ({ role: frameRole(index), ...image }))
+    }
+  };
+}
+function isImageBinding(workflow, binding) {
+  const node = workflow[binding.nodeId];
+  return binding.input === "image" && (node?.class_type === "LoadImage" || node?.class_type === "LoadImageMask");
+}
+function isComfyImageInput(value) {
+  return isObject(value) && value.kind === "image" && typeof value.path === "string" && typeof value.sha256 === "string" && (value.format === "png" || value.format === "jpeg");
+}
+function providerInputProvenance(inputs) {
+  return Object.fromEntries(Object.entries(inputs ?? {}).map(([name, input]) => [
+    name,
+    Array.isArray(input) ? { kind: "sequence", values: input.map(providerInputValueProvenance) } : providerInputValueProvenance(input)
+  ]));
+}
+function providerInputValueProvenance(input) {
+  return isComfyImageInput(input) ? { kind: "image", sha256: input.sha256, format: input.format } : { kind: "value", value: input };
+}
+function inputImageFormat(bytes) {
+  if (bytes.length >= 24 && bytes.readUInt32BE(0) === 2303741511 && bytes.readUInt32BE(4) === 218765834 && bytes.toString("ascii", 12, 16) === "IHDR" && bytes.readUInt32BE(16) > 0 && bytes.readUInt32BE(20) > 0) return "png";
+  if (bytes.length < 4 || bytes[0] !== 255 || bytes[1] !== 216) return null;
+  let offset = 2;
+  while (offset + 3 < bytes.length) {
+    if (bytes[offset] !== 255) return null;
+    while (bytes[offset] === 255) offset++;
+    const marker = bytes[offset++];
+    if (marker == null || marker === 217 || marker === 218) break;
+    if (marker === 1 || marker >= 208 && marker <= 215) continue;
+    if (offset + 2 > bytes.length) return null;
+    const length = bytes.readUInt16BE(offset);
+    if (length < 2 || offset + length > bytes.length) return null;
+    const isStartOfFrame = marker >= 192 && marker <= 207 && ![196, 200, 204].includes(marker);
+    if (isStartOfFrame) {
+      if (length < 7) return null;
+      return bytes.readUInt16BE(offset + 3) > 0 && bytes.readUInt16BE(offset + 5) > 0 ? "jpeg" : null;
+    }
+    offset += length;
+  }
+  return null;
+}
 function encodeJob(promptId, outputNodeId) {
   return `${promptId}#${encodeURIComponent(outputNodeId)}`;
 }
+function frameRole(index) {
+  return `frame-${String(index).padStart(2, "0")}`;
+}
+function encodeFrameSetJob(job) {
+  return `frames:${Buffer.from(JSON.stringify(job)).toString("base64url")}`;
+}
+function decodeFrameSetJob(jobId) {
+  if (!jobId.startsWith("frames:")) throw new Error(`Invalid ComfyUI frame-set job id "${jobId}"`);
+  let value;
+  try {
+    value = JSON.parse(Buffer.from(jobId.slice(7), "base64url").toString("utf8"));
+  } catch {
+    throw new Error(`Invalid ComfyUI frame-set job id "${jobId}"`);
+  }
+  if (!isObject(value) || typeof value.outputNodeId !== "string" || !value.outputNodeId || !Array.isArray(value.promptIds) || value.promptIds.length < 2 || value.promptIds.length > 64 || !value.promptIds.every((id) => typeof id === "string" && id.length > 0)) {
+    throw new Error(`Invalid ComfyUI frame-set job id "${jobId}"`);
+  }
+  return { outputNodeId: value.outputNodeId, promptIds: value.promptIds };
+}
 function decodeJob(jobId) {
   const split = jobId.lastIndexOf("#");
   if (split < 1 || split === jobId.length - 1) throw new Error(`Invalid ComfyUI job id "${jobId}"`);
@@ -1502,7 +1798,7 @@ function clientFromEnv() {
 // src/types.ts
 import { z as z2 } from "zod";
 var MediaTypeSchema = z2.enum(["image/png", "image/gif"]);
-var GeneratorSchema = z2.enum(["1dir", "map", "pixflux", "tiles", "animation"]);
+var GeneratorSchema = z2.enum(["1dir", "map", "pixflux", "tiles", "animation", "frames"]);
 var GridConfidenceSchema = z2.enum(["low", "medium", "high"]);
 var RevisionModeSchema = z2.enum(["image-to-image", "inpaint", "outpaint"]);
 function tileVariationCount(descriptions) {
@@ -1552,7 +1848,9 @@ var QualityProfileSchema = z2.object({
   /** Pixel Art Fixer revision written into the quality record. */
   fixerRevision: z2.string().min(1).optional(),
   /** Python executable containing Pixel Art Fixer, relative to the manifest unless absolute. */
-  fixerPython: z2.string().min(1).optional()
+  fixerPython: z2.string().min(1).optional(),
+  /** Playback rate recorded for an ordered frame set. */
+  fps: z2.number().int().min(1).max(60).optional()
 }).strict().refine(
   (profile) => new Set(profile.palette.map((color) => color.replace(/^#/, "").toLowerCase())).size === profile.palette.length,
   { message: "quality palette colors must be unique", path: ["palette"] }
@@ -1768,7 +2066,18 @@ var AssetSchema = z2.object({
    * exactly right for a colour style. Editing the shared prompt to suit one
    * style would invalidate every other style's already-generated art.
    */
-  promptByStyle: z2.record(z2.string()).default({})
+  promptByStyle: z2.record(z2.string()).default({}),
+  /**
+   * Named per-asset values consumed by the active provider's declared
+   * bindings. Values are JSON scalars, or a frame-set sequence of scalars;
+   * adapters may interpret a string as a manifest-relative uploaded file.
+   */
+  providerInputs: z2.record(z2.union([
+    z2.string(),
+    z2.number().finite(),
+    z2.boolean(),
+    z2.array(z2.union([z2.string(), z2.number().finite(), z2.boolean()])).min(2).max(64)
+  ])).default({})
 }).strict().superRefine((asset, context) => {
   if (asset.source && asset.revision) {
     context.addIssue({
@@ -3078,113 +3387,390 @@ registerProvider({
 });
 
 // src/manifest.ts
-import { readFile as readFile2 } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import path6 from "path";
+
+// src/outputs.ts
+import path5 from "path";
+
+// src/lock.ts
+import { readFile as readFile2, writeFile, rename, mkdir, rmdir, rm, stat } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
 import path4 from "path";
-async function loadManifest(manifestPath) {
-  const abs = path4.resolve(manifestPath);
-  if (!existsSync3(abs)) throw new Error(`No manifest at ${abs}`);
-  const parsed = ManifestSchema.safeParse(JSON.parse(await readFile2(abs, "utf8")));
-  if (!parsed.success) {
-    const issues = parsed.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
-    throw new Error(`Manifest at ${abs} is invalid:
-${issues}`);
-  }
-  const styleIds = new Set(Object.keys(parsed.data.styles));
-  const unknownReferences = [];
-  for (const [assetId, asset] of Object.entries(parsed.data.assets)) {
-    for (const styleId of asset.styles) {
-      if (!styleIds.has(styleId)) unknownReferences.push(`assets.${assetId}.styles: unknown style "${styleId}"`);
-    }
-    for (const styleId of Object.keys(asset.promptByStyle)) {
-      if (!styleIds.has(styleId)) {
-        unknownReferences.push(`assets.${assetId}.promptByStyle: unknown style "${styleId}"`);
-      }
-    }
-    if (asset.revision) {
-      if (!parsed.data.assets[asset.revision.from]) {
-        unknownReferences.push(
-          `assets.${assetId}.revision.from: unknown asset "${asset.revision.from}"`
-        );
-      } else if (asset.revision.from === assetId) {
-        unknownReferences.push(`assets.${assetId}.revision.from: an asset cannot revise itself`);
-      }
-    }
+async function loadLock(lockPath) {
+  if (!existsSync3(lockPath)) return { version: 2, entries: {} };
+  try {
+    return parseLock(JSON.parse(await readFile2(lockPath, "utf8")));
+  } catch (err) {
+    throw new Error(
+      `Lockfile at ${lockPath} is malformed:
+${err instanceof Error ? err.message : String(err)}`
+    );
   }
-  const visiting = /* @__PURE__ */ new Set();
-  const visited = /* @__PURE__ */ new Set();
-  const visitRevision = (assetId, chain) => {
-    if (visited.has(assetId)) return;
-    if (visiting.has(assetId)) {
-      const start = chain.indexOf(assetId);
-      unknownReferences.push(
-        `assets.${assetId}.revision.from: revision cycle ${[...chain.slice(start), assetId].join(" -> ")}`
-      );
-      return;
-    }
-    visiting.add(assetId);
-    const parent = parsed.data.assets[assetId]?.revision?.from;
-    if (parent && parent !== assetId && parsed.data.assets[parent]) {
-      visitRevision(parent, [...chain, assetId]);
-    }
-    visiting.delete(assetId);
-    visited.add(assetId);
+}
+var saveQueues = /* @__PURE__ */ new Map();
+var dirtyPatches = /* @__PURE__ */ new WeakMap();
+var dirtyDeletes = /* @__PURE__ */ new WeakMap();
+function saveLock(lockPath, lock) {
+  const queueKey = path4.resolve(lockPath);
+  const previous = saveQueues.get(queueKey) ?? Promise.resolve();
+  const next = previous.catch(() => {
+  }).then(() => writeLockNow(lockPath, lock));
+  saveQueues.set(queueKey, next);
+  const cleanup = () => {
+    if (saveQueues.get(queueKey) === next) saveQueues.delete(queueKey);
   };
-  for (const assetId of Object.keys(parsed.data.assets)) visitRevision(assetId, []);
-  if (unknownReferences.length) {
-    throw new Error(`Manifest at ${abs} is invalid:
-${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
+  void next.then(cleanup, cleanup);
+  return next;
+}
+async function writeLockNow(lockPath, lock) {
+  await mkdir(path4.dirname(path4.resolve(lockPath)), { recursive: true });
+  const release = await acquireFileLock(lockPath);
+  try {
+    await writeLockWhileHeld(lockPath, lock);
+  } finally {
+    await release();
   }
-  return { manifest: parsed.data, root: path4.dirname(abs), path: abs };
 }
-async function resolveSpecs(loaded, filter) {
-  const { manifest, root } = loaded;
-  const providerOverride = filter?.provider;
-  const providers = /* @__PURE__ */ new Map();
-  const providerFor = (id) => {
-    if (providerOverride) return providerOverride;
-    let provider = providers.get(id);
-    if (!provider) {
-      provider = createProvider(id, "offline");
-      providers.set(id, provider);
-    }
-    return provider;
-  };
-  const specs = [];
-  const styleIds = Object.keys(manifest.styles).filter(
-    (id) => !filter?.styles?.length || filter.styles.includes(id)
-  );
-  for (const unknownStyle of filter?.styles ?? []) {
-    if (!manifest.styles[unknownStyle]) {
+async function writeLockWhileHeld(file, lock) {
+  let disk = { version: 2, entries: {} };
+  if (existsSync3(file)) {
+    try {
+      disk = parseLock(JSON.parse(await readFile2(file, "utf8")));
+    } catch (err) {
       throw new Error(
-        `Unknown style "${unknownStyle}". Defined: ${Object.keys(manifest.styles).join(", ") || "(none)"}`
+        `Refusing to overwrite malformed lockfile at ${file}: ${err instanceof Error ? err.message : String(err)}`
       );
     }
   }
-  for (const unknownAsset of filter?.assets ?? []) {
-    if (!manifest.assets[unknownAsset]) {
-      throw new Error(`Unknown asset "${unknownAsset}".`);
-    }
+  const dirty = dirtyPatches.get(lock) ?? /* @__PURE__ */ new Map();
+  const snapshot = /* @__PURE__ */ new Map();
+  for (const [key, patch] of dirty) snapshot.set(key, { ...patch });
+  const merged = { ...disk.entries };
+  for (const [key, patch] of snapshot) {
+    const local = lock.entries[key];
+    if (!local) continue;
+    merged[key] = merged[key] ? { ...merged[key], ...patch } : local;
   }
-  const requestedAssetIds = new Set(filter?.assets?.length ? filter.assets : Object.keys(manifest.assets));
-  const resolutionAssetIds = new Set(requestedAssetIds);
-  for (const assetId of [...requestedAssetIds]) {
-    let current = manifest.assets[assetId]?.revision?.from;
-    while (current && !resolutionAssetIds.has(current)) {
-      resolutionAssetIds.add(current);
-      current = manifest.assets[current]?.revision?.from;
-    }
+  for (const [key, entry] of Object.entries(lock.entries)) {
+    if (!merged[key]) merged[key] = entry;
   }
-  const styleImageCache = /* @__PURE__ */ new Map();
-  async function loadStyleImage(rel) {
-    const abs = path4.resolve(root, rel);
-    let hit = styleImageCache.get(abs);
-    if (!hit) {
-      if (!existsSync3(abs)) throw new Error(`Style image not found: ${abs}`);
-      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) {
+  const deletes = dirtyDeletes.get(lock);
+  const deleteSnapshot = deletes ? new Set(deletes) : /* @__PURE__ */ new Set();
+  for (const key of deleteSnapshot) delete merged[key];
+  const sorted = {};
+  for (const key of Object.keys(merged).sort()) {
+    sorted[key] = merged[key];
+  }
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify({ version: 2, entries: sorted }, null, 2) + "\n");
+    await rename(tmp, file);
+  } finally {
+    await rm(tmp, { force: true });
+  }
+  const currentDirty = dirtyPatches.get(lock);
+  if (currentDirty) {
+    for (const [key, patch] of snapshot) {
+      const current = currentDirty.get(key);
+      if (!current) continue;
+      for (const [field, value] of Object.entries(patch)) {
+        if (Object.is(current[field], value)) {
+          delete current[field];
+        }
+      }
+      if (Object.keys(current).length === 0) currentDirty.delete(key);
+    }
+  }
+  const stillDirty = dirtyDeletes.get(lock);
+  if (stillDirty) {
+    for (const key of deleteSnapshot) stillDirty.delete(key);
+    if (stillDirty.size === 0) dirtyDeletes.delete(lock);
+  }
+  const localAfterWrite = lock.entries;
+  lock.entries = { ...merged };
+  for (const [key, patch] of currentDirty ?? []) {
+    const base = lock.entries[key] ?? localAfterWrite[key];
+    if (base) lock.entries[key] = { ...base, ...patch };
+  }
+}
+function upsert(lock, key, patch) {
+  dirtyDeletes.get(lock)?.delete(key);
+  const existing = lock.entries[key];
+  const next = { ...existing, ...patch };
+  lock.entries[key] = next;
+  let dirty = dirtyPatches.get(lock);
+  if (!dirty) {
+    dirty = /* @__PURE__ */ new Map();
+    dirtyPatches.set(lock, dirty);
+  }
+  dirty.set(key, { ...dirty.get(key) ?? {}, ...patch });
+  return next;
+}
+function remove(lock, key) {
+  if (!lock.entries[key]) return false;
+  delete lock.entries[key];
+  const patches = dirtyPatches.get(lock);
+  if (patches) {
+    patches.delete(key);
+    if (patches.size === 0) dirtyPatches.delete(lock);
+  }
+  let deletes = dirtyDeletes.get(lock);
+  if (!deletes) {
+    deletes = /* @__PURE__ */ new Set();
+    dirtyDeletes.set(lock, deletes);
+  }
+  deletes.add(key);
+  return true;
+}
+var FILE_LOCK_TIMEOUT_MS = 1e4;
+var STALE_FILE_LOCK_MS = 2 * 60 * 1e3;
+async function acquireFileLock(file) {
+  const lockDir = `${file}.lock`;
+  const deadline = Date.now() + FILE_LOCK_TIMEOUT_MS;
+  for (; ; ) {
+    try {
+      await mkdir(lockDir);
+      return async () => {
+        await rmdir(lockDir).catch(() => {
+        });
+      };
+    } catch (err) {
+      const code = err.code;
+      if (code !== "EEXIST") throw err;
+      try {
+        const age = Date.now() - (await stat(lockDir)).mtimeMs;
+        if (age > STALE_FILE_LOCK_MS) {
+          await rmdir(lockDir);
+          continue;
+        }
+      } catch (lockErr) {
+        if (lockErr.code === "ENOENT") continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out waiting for lockfile writer ${lockDir}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25 + Math.floor(Math.random() * 25)));
+    }
+  }
+}
+function spendByUnit(lock) {
+  const totals = { generations: 0, usd: 0, free: 0 };
+  for (const entry of Object.values(lock.entries)) {
+    const unit = entry.costUnit ?? "generations";
+    totals[unit] = (totals[unit] ?? 0) + (entry.cost ?? 0);
+  }
+  return totals;
+}
+
+// src/outputs.ts
+function portableOutputPath(file, manifestDir) {
+  const root = path5.resolve(manifestDir);
+  const absolute = path5.isAbsolute(file) ? path5.normalize(file) : path5.resolve(root, file);
+  const relative = path5.relative(root, absolute);
+  const value = path5.isAbsolute(relative) ? absolute : relative;
+  return value.split(path5.sep).join("/");
+}
+function resolveOutputPath(recordedPath, manifestDir) {
+  if (path5.isAbsolute(recordedPath)) return path5.normalize(recordedPath);
+  if (path5.win32.isAbsolute(recordedPath)) return recordedPath;
+  return path5.resolve(manifestDir, recordedPath.split(/[\\/]/).join(path5.sep));
+}
+function expectedOutputPath(spec, role, index, total, mediaType) {
+  const originalExt = path5.extname(spec.outFile);
+  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, output.mediaType);
+}
+function currentEntryOutputPath(entry, spec, index) {
+  const output = entry.outputs[index];
+  const sourceIndex = output.role ? (entry.sourceUrls ?? []).findIndex((source) => source.role === output.role) : -1;
+  const position = sourceIndex >= 0 ? sourceIndex : index;
+  const total = Math.max(entry.outputs.length, entry.sourceUrls?.length ?? 0);
+  return currentOutputPath(output, spec, position, total);
+}
+function normalizeLockOutputPaths(lock, specs) {
+  const byKey = new Map(specs.map((spec) => [lockKey(spec.styleId, spec.assetId), spec]));
+  let changed = 0;
+  for (const [key, entry] of Object.entries(lock.entries)) {
+    const spec = byKey.get(key);
+    if (!spec) continue;
+    let entryChanged = false;
+    const outputs = entry.outputs.map((output, index) => {
+      const absolute = currentEntryOutputPath(entry, spec, index);
+      const portable = portableOutputPath(absolute, spec.root);
+      if (portable === output.path) return output;
+      changed++;
+      entryChanged = true;
+      return { ...output, path: portable };
+    });
+    if (entryChanged) upsert(lock, key, { outputs });
+  }
+  return changed;
+}
+function fallbackOutputRole(index) {
+  return `output-${String(index).padStart(2, "0")}`;
+}
+function outputId(assetId, output, index, total) {
+  if (total === 1) return assetId;
+  return `${assetId}/${output.role ?? fallbackOutputRole(index)}`;
+}
+function resolveEntryOutputs(entry, assetId, manifestDir) {
+  return entry.outputs.map((output, index) => ({
+    ...output,
+    assetId,
+    id: outputId(assetId, output, index, entry.outputs.length),
+    index,
+    absolutePath: resolveOutputPath(output.path, manifestDir)
+  }));
+}
+function resolveSpecEntryOutputs(entry, spec) {
+  return entry.outputs.map((output, index) => ({
+    ...output,
+    assetId: spec.assetId,
+    id: outputId(spec.assetId, output, index, entry.outputs.length),
+    index,
+    absolutePath: currentEntryOutputPath(entry, spec, index)
+  }));
+}
+function selectEntryOutput(entry, role) {
+  if (role) {
+    const output = entry.outputs.find((candidate) => candidate.role === role);
+    return output ? { ok: true, output } : { ok: false, reason: `output role "${role}" is not recorded` };
+  }
+  if (entry.outputs.length === 0) return { ok: false, reason: "no output recorded in the lockfile" };
+  if (entry.outputs.length === 1) return { ok: true, output: entry.outputs[0] };
+  const primary = entry.outputs.filter((output) => !output.role);
+  if (primary.length === 1) return { ok: true, output: primary[0] };
+  return {
+    ok: false,
+    reason: `${entry.outputs.length} outputs are recorded; set \`outputRole\` to choose one`
+  };
+}
+function resolveSpecOutputs(spec, lock, manifestDir) {
+  const entry = lock?.entries[lockKey(spec.styleId, spec.assetId)];
+  if (entry?.outputs.length) return resolveSpecEntryOutputs(entry, spec);
+  return [{
+    assetId: spec.assetId,
+    id: spec.assetId,
+    index: 0,
+    path: spec.outFile,
+    absolutePath: path5.resolve(spec.outFile),
+    sha256: ""
+  }];
+}
+
+// src/manifest.ts
+async function loadManifest(manifestPath) {
+  const abs = path6.resolve(manifestPath);
+  if (!existsSync4(abs)) throw new Error(`No manifest at ${abs}`);
+  const parsed = ManifestSchema.safeParse(JSON.parse(await readFile3(abs, "utf8")));
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+    throw new Error(`Manifest at ${abs} is invalid:
+${issues}`);
+  }
+  const styleIds = new Set(Object.keys(parsed.data.styles));
+  const unknownReferences = [];
+  for (const [assetId, asset] of Object.entries(parsed.data.assets)) {
+    for (const styleId of asset.styles) {
+      if (!styleIds.has(styleId)) unknownReferences.push(`assets.${assetId}.styles: unknown style "${styleId}"`);
+    }
+    for (const styleId of Object.keys(asset.promptByStyle)) {
+      if (!styleIds.has(styleId)) {
+        unknownReferences.push(`assets.${assetId}.promptByStyle: unknown style "${styleId}"`);
+      }
+    }
+    if (asset.revision) {
+      if (!parsed.data.assets[asset.revision.from]) {
+        unknownReferences.push(
+          `assets.${assetId}.revision.from: unknown asset "${asset.revision.from}"`
+        );
+      } else if (asset.revision.from === assetId) {
+        unknownReferences.push(`assets.${assetId}.revision.from: an asset cannot revise itself`);
+      }
+    }
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const visitRevision = (assetId, chain) => {
+    if (visited.has(assetId)) return;
+    if (visiting.has(assetId)) {
+      const start = chain.indexOf(assetId);
+      unknownReferences.push(
+        `assets.${assetId}.revision.from: revision cycle ${[...chain.slice(start), assetId].join(" -> ")}`
+      );
+      return;
+    }
+    visiting.add(assetId);
+    const parent = parsed.data.assets[assetId]?.revision?.from;
+    if (parent && parent !== assetId && parsed.data.assets[parent]) {
+      visitRevision(parent, [...chain, assetId]);
+    }
+    visiting.delete(assetId);
+    visited.add(assetId);
+  };
+  for (const assetId of Object.keys(parsed.data.assets)) visitRevision(assetId, []);
+  if (unknownReferences.length) {
+    throw new Error(`Manifest at ${abs} is invalid:
+${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
+  }
+  return { manifest: parsed.data, root: path6.dirname(abs), path: abs };
+}
+async function resolveSpecs(loaded, filter) {
+  const { manifest, root } = loaded;
+  const providerOverride = filter?.provider;
+  const providers = /* @__PURE__ */ new Map();
+  const providerFor = (id) => {
+    if (providerOverride) return providerOverride;
+    let provider = providers.get(id);
+    if (!provider) {
+      provider = createProvider(id, "offline");
+      providers.set(id, provider);
+    }
+    return provider;
+  };
+  const specs = [];
+  const styleIds = Object.keys(manifest.styles).filter(
+    (id) => !filter?.styles?.length || filter.styles.includes(id)
+  );
+  for (const unknownStyle of filter?.styles ?? []) {
+    if (!manifest.styles[unknownStyle]) {
+      throw new Error(
+        `Unknown style "${unknownStyle}". Defined: ${Object.keys(manifest.styles).join(", ") || "(none)"}`
+      );
+    }
+  }
+  for (const unknownAsset of filter?.assets ?? []) {
+    if (!manifest.assets[unknownAsset]) {
+      throw new Error(`Unknown asset "${unknownAsset}".`);
+    }
+  }
+  const requestedAssetIds = new Set(filter?.assets?.length ? filter.assets : Object.keys(manifest.assets));
+  const resolutionAssetIds = new Set(requestedAssetIds);
+  for (const assetId of [...requestedAssetIds]) {
+    let current = manifest.assets[assetId]?.revision?.from;
+    while (current && !resolutionAssetIds.has(current)) {
+      resolutionAssetIds.add(current);
+      current = manifest.assets[current]?.revision?.from;
+    }
+  }
+  const styleImageCache = /* @__PURE__ */ new Map();
+  async function loadStyleImage(rel) {
+    const abs = path6.resolve(root, rel);
+    let hit = styleImageCache.get(abs);
+    if (!hit) {
+      if (!existsSync4(abs)) throw new Error(`Style image not found: ${abs}`);
+      const buf = await readFile3(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) {
         throw new Error(`Style image has invalid dimensions: ${abs}`);
       }
       hit = { base64: buf.toString("base64"), hash: sha256(buf), ...metadata };
@@ -3207,10 +3793,11 @@ async function resolveSpecs(loaded, filter) {
       styleImageDimensions.push(loadedImage);
     }
     const resolvedImages = style.styleImages.map((image) => {
-      const hit = styleImageCache.get(path4.resolve(root, image.path));
+      const hit = styleImageCache.get(path6.resolve(root, image.path));
       return { base64: hit.base64, width: hit.width, height: hit.height, format: hit.format };
     });
     const styleSpecs = /* @__PURE__ */ new Map();
+    const providerInputIdentities = /* @__PURE__ */ new Map();
     for (const [assetId, asset] of Object.entries(manifest.assets)) {
       if (!resolutionAssetIds.has(assetId)) continue;
       if (asset.styles.length && !asset.styles.includes(styleId)) continue;
@@ -3218,6 +3805,21 @@ async function resolveSpecs(loaded, filter) {
       if (!activeProvider.supports(generator)) {
         throw new Error(`Provider "${activeProvider.id}" does not support generator "${generator}"`);
       }
+      if (Object.keys(asset.providerInputs).length && !activeProvider.resolveInputs) {
+        throw new Error(
+          `Provider "${activeProvider.id}" does not support asset providerInputs (${styleId}/${assetId})`
+        );
+      }
+      const inputResolution = activeProvider.resolveInputs ? await activeProvider.resolveInputs(asset.providerInputs, {
+        root,
+        styleId,
+        assetId,
+        generator,
+        providerOptions
+      }) : { inputs: {} };
+      const providerInputs = inputResolution.inputs;
+      const providerInputIdentity = inputResolution.identity ?? providerInputs;
+      providerInputIdentities.set(assetId, providerInputIdentity);
       let width;
       let height;
       let size;
@@ -3236,9 +3838,9 @@ async function resolveSpecs(loaded, filter) {
       }
       const subject = asset.promptByStyle[styleId] ?? asset.prompt;
       const prompt = [style.promptPrefix, subject, style.promptSuffix].map((p) => p.trim()).filter(Boolean).join(", ");
-      const relFile = asset.file ?? path4.join(asset.category ?? "", `${assetId}.png`);
-      const outFile = path4.resolve(root, style.outDir, relFile);
-      const qualityOutFile = style.quality ? path4.resolve(root, style.quality.outDir, pngPath(relFile)) : void 0;
+      const relFile = asset.file ?? path6.join(asset.category ?? "", `${assetId}.png`);
+      const outFile = path6.resolve(root, style.outDir, relFile);
+      const qualityOutFile = style.quality ? path6.resolve(root, style.quality.outDir, pngPath(relFile)) : void 0;
       const tileSize = generator === "tiles" ? size : style.tileSize ?? 32;
       const tileVariations = tileFeatureOutputCount(generator === "tiles" ? style.tileFeature : void 0) ?? tileVariationCount(countNumberedDescriptions(prompt));
       const base = {
@@ -3246,6 +3848,7 @@ async function resolveSpecs(loaded, filter) {
         assetId,
         provider: activeProvider.id,
         providerOptions,
+        providerInputs,
         generator,
         prompt,
         width,
@@ -3288,7 +3891,8 @@ async function resolveSpecs(loaded, filter) {
             minGridConfidence: style.quality.minGridConfidence,
             ...style.quality.minTransparency == null ? {} : { minTransparency: style.quality.minTransparency },
             ...style.quality.fixerRevision ? { fixerRevision: style.quality.fixerRevision } : {},
-            ...style.quality.fixerPython ? { fixerPython: path4.resolve(root, style.quality.fixerPython) } : {}
+            ...style.quality.fixerPython ? { fixerPython: path6.resolve(root, style.quality.fixerPython) } : {},
+            ...style.quality.fps == null ? {} : { fps: style.quality.fps }
           }
         } : {},
         tags,
@@ -3316,9 +3920,9 @@ async function resolveSpecs(loaded, filter) {
           );
         }
         const sourceSpec = await finalize(asset.revision.from);
-        const sourceFile = sourceSpec.quality?.outFile ?? (sourceSpec.source ? path4.resolve(root, sourceSpec.source) : sourceSpec.outFile);
+        const sourceFile = sourceSpec.quality?.outFile ?? (sourceSpec.source ? path6.resolve(root, sourceSpec.source) : sourceSpec.outFile);
         const sourceImage = await optionalRevisionImage(sourceFile, "revision source");
-        const maskFile = asset.revision.mask ? path4.resolve(root, asset.revision.mask) : void 0;
+        const maskFile = asset.revision.mask ? path6.resolve(root, asset.revision.mask) : void 0;
         const maskImage = maskFile ? await optionalRevisionImage(maskFile, "revision mask", "png") : null;
         if (sourceImage && maskImage && (sourceImage.width !== maskImage.width || sourceImage.height !== maskImage.height)) {
           throw new Error(
@@ -3344,7 +3948,12 @@ async function resolveSpecs(loaded, filter) {
           ...asset.revision.strength == null ? {} : { strength: asset.revision.strength }
         };
       }
-      resolved.specHash = specHash(resolved, styleImageHashes, providerOptionIdentity);
+      resolved.specHash = specHash(
+        resolved,
+        styleImageHashes,
+        providerOptionIdentity,
+        providerInputIdentities.get(assetId)
+      );
       activeProvider.validate?.(resolved, resolvedImages);
       const estimate = validateCostEstimate(activeProvider.id, activeProvider.estimate(resolved));
       resolved.cost = estimate.amount;
@@ -3369,349 +3978,92 @@ async function resolveSpecs(loaded, filter) {
   for (const spec of specs) {
     const key = `${spec.styleId}/${spec.assetId}`;
     claimOutput(spec.outFile, key);
-    if (spec.quality) claimOutput(spec.quality.outFile, `${key} quality output`);
-  }
-  return specs;
-}
-function pngPath(file) {
-  const extension = path4.extname(file);
-  return extension ? `${file.slice(0, -extension.length)}.png` : `${file}.png`;
-}
-async function optionalRevisionImage(file, label, requiredFormat) {
-  if (!existsSync3(file)) return null;
-  const bytes = await readFile2(file);
-  const metadata = imageMetadata(bytes);
-  if (!metadata) throw new Error(`${label} is not a readable PNG or JPEG: ${file}`);
-  if (requiredFormat && metadata.format !== requiredFormat) {
-    throw new Error(`${label} must be ${requiredFormat.toUpperCase()}: ${file}`);
-  }
-  return { hash: sha256(bytes), ...metadata };
-}
-async function resolveStyleImages(loaded, styleId) {
-  const style = loaded.manifest.styles[styleId];
-  if (!style) throw new Error(`Unknown style "${styleId}"`);
-  const out = [];
-  for (const img of style.styleImages) {
-    const file = path4.resolve(loaded.root, img.path);
-    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) {
-      throw new Error(`Style image has invalid dimensions: ${file}`);
-    }
-    out.push({ base64: buf.toString("base64"), ...metadata });
-  }
-  return out;
-}
-function imageMetadata(buf) {
-  if (buf.length >= 24 && buf.readUInt32BE(0) === 2303741511 && buf.readUInt32BE(4) === 218765834 && buf.toString("ascii", 12, 16) === "IHDR") {
-    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20), format: "png" };
-  }
-  if (buf.length < 4 || buf[0] !== 255 || buf[1] !== 216) return null;
-  let offset = 2;
-  while (offset + 3 < buf.length) {
-    if (buf[offset] !== 255) return null;
-    while (buf[offset] === 255) offset++;
-    const marker = buf[offset++];
-    if (marker == null || marker === 217 || marker === 218) break;
-    if (marker === 1 || marker >= 208 && marker <= 215) continue;
-    if (offset + 2 > buf.length) return null;
-    const length = buf.readUInt16BE(offset);
-    if (length < 2 || offset + length > buf.length) return null;
-    const isStartOfFrame = marker >= 192 && marker <= 207 && ![196, 200, 204].includes(marker);
-    if (isStartOfFrame) {
-      if (length < 7) return null;
-      return {
-        width: buf.readUInt16BE(offset + 5),
-        height: buf.readUInt16BE(offset + 3),
-        format: "jpeg"
-      };
-    }
-    offset += length;
-  }
-  return null;
-}
-
-// src/pipeline/pack.ts
-import { readFileSync as readFileSync3 } from "fs";
-import path7 from "path";
-
-// src/outputs.ts
-import path6 from "path";
-
-// src/lock.ts
-import { readFile as readFile3, writeFile, rename, mkdir, rmdir, rm, stat } from "fs/promises";
-import { existsSync as existsSync4 } from "fs";
-import path5 from "path";
-async function loadLock(lockPath) {
-  if (!existsSync4(lockPath)) return { version: 2, entries: {} };
-  try {
-    return parseLock(JSON.parse(await readFile3(lockPath, "utf8")));
-  } catch (err) {
-    throw new Error(
-      `Lockfile at ${lockPath} is malformed:
-${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-}
-var saveQueues = /* @__PURE__ */ new Map();
-var dirtyPatches = /* @__PURE__ */ new WeakMap();
-var dirtyDeletes = /* @__PURE__ */ new WeakMap();
-function saveLock(lockPath, lock) {
-  const queueKey = path5.resolve(lockPath);
-  const previous = saveQueues.get(queueKey) ?? Promise.resolve();
-  const next = previous.catch(() => {
-  }).then(() => writeLockNow(lockPath, lock));
-  saveQueues.set(queueKey, next);
-  const cleanup = () => {
-    if (saveQueues.get(queueKey) === next) saveQueues.delete(queueKey);
-  };
-  void next.then(cleanup, cleanup);
-  return next;
-}
-async function writeLockNow(lockPath, lock) {
-  await mkdir(path5.dirname(path5.resolve(lockPath)), { recursive: true });
-  const release = await acquireFileLock(lockPath);
-  try {
-    await writeLockWhileHeld(lockPath, lock);
-  } finally {
-    await release();
-  }
-}
-async function writeLockWhileHeld(file, lock) {
-  let disk = { version: 2, entries: {} };
-  if (existsSync4(file)) {
-    try {
-      disk = parseLock(JSON.parse(await readFile3(file, "utf8")));
-    } catch (err) {
-      throw new Error(
-        `Refusing to overwrite malformed lockfile at ${file}: ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-  }
-  const dirty = dirtyPatches.get(lock) ?? /* @__PURE__ */ new Map();
-  const snapshot = /* @__PURE__ */ new Map();
-  for (const [key, patch] of dirty) snapshot.set(key, { ...patch });
-  const merged = { ...disk.entries };
-  for (const [key, patch] of snapshot) {
-    const local = lock.entries[key];
-    if (!local) continue;
-    merged[key] = merged[key] ? { ...merged[key], ...patch } : local;
-  }
-  for (const [key, entry] of Object.entries(lock.entries)) {
-    if (!merged[key]) merged[key] = entry;
-  }
-  const deletes = dirtyDeletes.get(lock);
-  const deleteSnapshot = deletes ? new Set(deletes) : /* @__PURE__ */ new Set();
-  for (const key of deleteSnapshot) delete merged[key];
-  const sorted = {};
-  for (const key of Object.keys(merged).sort()) {
-    sorted[key] = merged[key];
-  }
-  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
-  try {
-    await writeFile(tmp, JSON.stringify({ version: 2, entries: sorted }, null, 2) + "\n");
-    await rename(tmp, file);
-  } finally {
-    await rm(tmp, { force: true });
-  }
-  const currentDirty = dirtyPatches.get(lock);
-  if (currentDirty) {
-    for (const [key, patch] of snapshot) {
-      const current = currentDirty.get(key);
-      if (!current) continue;
-      for (const [field, value] of Object.entries(patch)) {
-        if (Object.is(current[field], value)) {
-          delete current[field];
-        }
-      }
-      if (Object.keys(current).length === 0) currentDirty.delete(key);
-    }
-  }
-  const stillDirty = dirtyDeletes.get(lock);
-  if (stillDirty) {
-    for (const key of deleteSnapshot) stillDirty.delete(key);
-    if (stillDirty.size === 0) dirtyDeletes.delete(lock);
-  }
-  const localAfterWrite = lock.entries;
-  lock.entries = { ...merged };
-  for (const [key, patch] of currentDirty ?? []) {
-    const base = lock.entries[key] ?? localAfterWrite[key];
-    if (base) lock.entries[key] = { ...base, ...patch };
-  }
-}
-function upsert(lock, key, patch) {
-  dirtyDeletes.get(lock)?.delete(key);
-  const existing = lock.entries[key];
-  const next = { ...existing, ...patch };
-  lock.entries[key] = next;
-  let dirty = dirtyPatches.get(lock);
-  if (!dirty) {
-    dirty = /* @__PURE__ */ new Map();
-    dirtyPatches.set(lock, dirty);
-  }
-  dirty.set(key, { ...dirty.get(key) ?? {}, ...patch });
-  return next;
-}
-function remove(lock, key) {
-  if (!lock.entries[key]) return false;
-  delete lock.entries[key];
-  const patches = dirtyPatches.get(lock);
-  if (patches) {
-    patches.delete(key);
-    if (patches.size === 0) dirtyPatches.delete(lock);
-  }
-  let deletes = dirtyDeletes.get(lock);
-  if (!deletes) {
-    deletes = /* @__PURE__ */ new Set();
-    dirtyDeletes.set(lock, deletes);
-  }
-  deletes.add(key);
-  return true;
-}
-var FILE_LOCK_TIMEOUT_MS = 1e4;
-var STALE_FILE_LOCK_MS = 2 * 60 * 1e3;
-async function acquireFileLock(file) {
-  const lockDir = `${file}.lock`;
-  const deadline = Date.now() + FILE_LOCK_TIMEOUT_MS;
-  for (; ; ) {
-    try {
-      await mkdir(lockDir);
-      return async () => {
-        await rmdir(lockDir).catch(() => {
-        });
-      };
-    } catch (err) {
-      const code = err.code;
-      if (code !== "EEXIST") throw err;
-      try {
-        const age = Date.now() - (await stat(lockDir)).mtimeMs;
-        if (age > STALE_FILE_LOCK_MS) {
-          await rmdir(lockDir);
-          continue;
-        }
-      } catch (lockErr) {
-        if (lockErr.code === "ENOENT") continue;
-      }
-      if (Date.now() >= deadline) {
-        throw new Error(`Timed out waiting for lockfile writer ${lockDir}`);
+    if (spec.quality) {
+      if (spec.generator === "frames") {
+        const frameInputs = Object.values(spec.providerInputs ?? {}).find(Array.isArray);
+        const count = frameInputs?.length ?? 0;
+        for (let index = 0; index < count; index++) {
+          const role = `frame-${String(index).padStart(2, "0")}`;
+          claimOutput(
+            expectedOutputPath(
+              { ...spec, outFile: spec.quality.outFile },
+              role,
+              index,
+              count,
+              MediaType.PNG
+            ),
+            `${key} quality ${role}`
+          );
+        }
+      } else {
+        claimOutput(spec.quality.outFile, `${key} quality output`);
       }
-      await new Promise((resolve) => setTimeout(resolve, 25 + Math.floor(Math.random() * 25)));
     }
   }
+  return specs;
 }
-function spendByUnit(lock) {
-  const totals = { generations: 0, usd: 0, free: 0 };
-  for (const entry of Object.values(lock.entries)) {
-    const unit = entry.costUnit ?? "generations";
-    totals[unit] = (totals[unit] ?? 0) + (entry.cost ?? 0);
-  }
-  return totals;
-}
-
-// src/outputs.ts
-function portableOutputPath(file, manifestDir) {
-  const root = path6.resolve(manifestDir);
-  const absolute = path6.isAbsolute(file) ? path6.normalize(file) : path6.resolve(root, file);
-  const relative = path6.relative(root, absolute);
-  const value = path6.isAbsolute(relative) ? absolute : relative;
-  return value.split(path6.sep).join("/");
-}
-function resolveOutputPath(recordedPath, manifestDir) {
-  if (path6.isAbsolute(recordedPath)) return path6.normalize(recordedPath);
-  if (path6.win32.isAbsolute(recordedPath)) return recordedPath;
-  return path6.resolve(manifestDir, recordedPath.split(/[\\/]/).join(path6.sep));
-}
-function expectedOutputPath(spec, role, index, total, mediaType) {
-  const originalExt = path6.extname(spec.outFile);
-  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, output.mediaType);
-}
-function currentEntryOutputPath(entry, spec, index) {
-  const output = entry.outputs[index];
-  const sourceIndex = output.role ? (entry.sourceUrls ?? []).findIndex((source) => source.role === output.role) : -1;
-  const position = sourceIndex >= 0 ? sourceIndex : index;
-  const total = Math.max(entry.outputs.length, entry.sourceUrls?.length ?? 0);
-  return currentOutputPath(output, spec, position, total);
+function pngPath(file) {
+  const extension = path6.extname(file);
+  return extension ? `${file.slice(0, -extension.length)}.png` : `${file}.png`;
 }
-function normalizeLockOutputPaths(lock, specs) {
-  const byKey = new Map(specs.map((spec) => [lockKey(spec.styleId, spec.assetId), spec]));
-  let changed = 0;
-  for (const [key, entry] of Object.entries(lock.entries)) {
-    const spec = byKey.get(key);
-    if (!spec) continue;
-    let entryChanged = false;
-    const outputs = entry.outputs.map((output, index) => {
-      const absolute = currentEntryOutputPath(entry, spec, index);
-      const portable = portableOutputPath(absolute, spec.root);
-      if (portable === output.path) return output;
-      changed++;
-      entryChanged = true;
-      return { ...output, path: portable };
-    });
-    if (entryChanged) upsert(lock, key, { outputs });
+async function optionalRevisionImage(file, label, requiredFormat) {
+  if (!existsSync4(file)) return null;
+  const bytes = await readFile3(file);
+  const metadata = imageMetadata(bytes);
+  if (!metadata) throw new Error(`${label} is not a readable PNG or JPEG: ${file}`);
+  if (requiredFormat && metadata.format !== requiredFormat) {
+    throw new Error(`${label} must be ${requiredFormat.toUpperCase()}: ${file}`);
   }
-  return changed;
-}
-function fallbackOutputRole(index) {
-  return `output-${String(index).padStart(2, "0")}`;
-}
-function outputId(assetId, output, index, total) {
-  if (total === 1) return assetId;
-  return `${assetId}/${output.role ?? fallbackOutputRole(index)}`;
-}
-function resolveEntryOutputs(entry, assetId, manifestDir) {
-  return entry.outputs.map((output, index) => ({
-    ...output,
-    assetId,
-    id: outputId(assetId, output, index, entry.outputs.length),
-    index,
-    absolutePath: resolveOutputPath(output.path, manifestDir)
-  }));
-}
-function resolveSpecEntryOutputs(entry, spec) {
-  return entry.outputs.map((output, index) => ({
-    ...output,
-    assetId: spec.assetId,
-    id: outputId(spec.assetId, output, index, entry.outputs.length),
-    index,
-    absolutePath: currentEntryOutputPath(entry, spec, index)
-  }));
+  return { hash: sha256(bytes), ...metadata };
 }
-function selectEntryOutput(entry, role) {
-  if (role) {
-    const output = entry.outputs.find((candidate) => candidate.role === role);
-    return output ? { ok: true, output } : { ok: false, reason: `output role "${role}" is not recorded` };
+async function resolveStyleImages(loaded, styleId) {
+  const style = loaded.manifest.styles[styleId];
+  if (!style) throw new Error(`Unknown style "${styleId}"`);
+  const out = [];
+  for (const img of style.styleImages) {
+    const file = path6.resolve(loaded.root, img.path);
+    const buf = await readFile3(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) {
+      throw new Error(`Style image has invalid dimensions: ${file}`);
+    }
+    out.push({ base64: buf.toString("base64"), ...metadata });
   }
-  if (entry.outputs.length === 0) return { ok: false, reason: "no output recorded in the lockfile" };
-  if (entry.outputs.length === 1) return { ok: true, output: entry.outputs[0] };
-  const primary = entry.outputs.filter((output) => !output.role);
-  if (primary.length === 1) return { ok: true, output: primary[0] };
-  return {
-    ok: false,
-    reason: `${entry.outputs.length} outputs are recorded; set \`outputRole\` to choose one`
-  };
+  return out;
 }
-function resolveSpecOutputs(spec, lock, manifestDir) {
-  const entry = lock?.entries[lockKey(spec.styleId, spec.assetId)];
-  if (entry?.outputs.length) return resolveSpecEntryOutputs(entry, spec);
-  return [{
-    assetId: spec.assetId,
-    id: spec.assetId,
-    index: 0,
-    path: spec.outFile,
-    absolutePath: path6.resolve(spec.outFile),
-    sha256: ""
-  }];
+function imageMetadata(buf) {
+  if (buf.length >= 24 && buf.readUInt32BE(0) === 2303741511 && buf.readUInt32BE(4) === 218765834 && buf.toString("ascii", 12, 16) === "IHDR") {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20), format: "png" };
+  }
+  if (buf.length < 4 || buf[0] !== 255 || buf[1] !== 216) return null;
+  let offset = 2;
+  while (offset + 3 < buf.length) {
+    if (buf[offset] !== 255) return null;
+    while (buf[offset] === 255) offset++;
+    const marker = buf[offset++];
+    if (marker == null || marker === 217 || marker === 218) break;
+    if (marker === 1 || marker >= 208 && marker <= 215) continue;
+    if (offset + 2 > buf.length) return null;
+    const length = buf.readUInt16BE(offset);
+    if (length < 2 || offset + length > buf.length) return null;
+    const isStartOfFrame = marker >= 192 && marker <= 207 && ![196, 200, 204].includes(marker);
+    if (isStartOfFrame) {
+      if (length < 7) return null;
+      return {
+        width: buf.readUInt16BE(offset + 5),
+        height: buf.readUInt16BE(offset + 3),
+        format: "jpeg"
+      };
+    }
+    offset += length;
+  }
+  return null;
 }
 
 // src/pipeline/pack.ts
+import { readFileSync as readFileSync3 } from "fs";
+import path7 from "path";
 function resolvePackInputs(raw, inputsFilePath) {
   if (!Array.isArray(raw) || !raw.length) {
     throw new Error("--inputs must be a non-empty JSON array of { id, path }");
@@ -3790,7 +4142,7 @@ function packSprites(inputs, options = {}) {
 function packStyle(lock, styleId, manifestDir, options = {}) {
   if (options.sourceOverrides) {
     if (options.outputRoles?.length) {
-      throw new Error("Quality-profile packing does not accept --output-role; profiles own one PNG per asset.");
+      throw new Error("Quality-profile packing does not accept --output-role; profiles own final output selection.");
     }
     const inputs2 = Object.entries(options.sourceOverrides).map(([id, source]) => ({
       id,
@@ -4602,6 +4954,8 @@ function hex(c) {
 
 // src/pipeline/refine.ts
 var execFileAsync = promisify(execFile);
+var PIXEL_ART_FIXER_MIN_SIDE = 16;
+var PIXEL_ART_FIXER_MAX_PIXELS = 4e6;
 var PIXEL_ART_FIXER_URL = "https://github.com/Retro-Diffusion/pixel-art-fixer";
 var PIXEL_ART_FIXER_REVISION = "ef376e57e1c272633ca2dbf5f29ec3fcf6596465";
 function message2(error) {
@@ -4649,25 +5003,33 @@ function firstJsonObject(text) {
 }
 var PYTHON_FIXER_BRIDGE = [
   "import json, sys",
-  "from pixelfixer.api import process",
-  "result = process(open(sys.argv[1], 'rb').read(), mode='full')",
-  "open(sys.argv[2], 'wb').write(result.pop('png'))",
-  "print(json.dumps(result))"
+  "from PIL import Image",
+  "from pixelfixer.api import _load",
+  "from pixelfixer.core import detect",
+  "from pixelfixer.reconstruct import two_stage_pack",
+  "rgba = _load(open(sys.argv[1], 'rb').read())",
+  "result = detect(rgba, mode='full')",
+  "Image.fromarray(two_stage_pack(rgba, result['cols'], result['rows'])).save(sys.argv[2], 'PNG')",
+  "print(json.dumps({key: result[key] for key in ('cols', 'rows', 'step_x', 'step_y', 'phase_x', 'phase_y', 'consensus')}))"
 ].join("; ");
 function parseDetection(raw) {
   if (!raw || typeof raw !== "object") throw new Error("Pixel Art Fixer returned no detection result.");
   const value = raw;
   const stepX = Number(value.step_x);
   const stepY = Number(value.step_y);
+  const phaseX = Number(value.phase_x);
+  const phaseY = Number(value.phase_y);
   const columns = Number(value.cols);
   const rows = Number(value.rows);
   const consensus = value.consensus;
-  if (!Number.isFinite(stepX) || stepX <= 0 || !Number.isFinite(stepY) || stepY <= 0 || !Number.isInteger(columns) || columns < 1 || !Number.isInteger(rows) || rows < 1 || typeof consensus !== "string" || !consensus) {
+  if (!Number.isFinite(stepX) || stepX <= 0 || !Number.isFinite(stepY) || stepY <= 0 || !Number.isFinite(phaseX) || phaseX < 0 || phaseX > stepX || !Number.isFinite(phaseY) || phaseY < 0 || phaseY > stepY || !Number.isInteger(columns) || columns < 1 || !Number.isInteger(rows) || rows < 1 || typeof consensus !== "string" || !consensus) {
     throw new Error("Pixel Art Fixer returned an invalid grid detection result.");
   }
   return {
     stepX,
     stepY,
+    phaseX,
+    phaseY,
     columns,
     rows,
     consensus,
@@ -4778,6 +5140,23 @@ function auditRefinement(png, detection, palette, minTransparency, minGridConfid
 function isGridConfidence(value) {
   return value === "low" || value === "medium" || value === "high";
 }
+function isDetection(value) {
+  if (!value || typeof value !== "object") return false;
+  const detection = value;
+  return Number.isFinite(detection.stepX) && detection.stepX > 0 && Number.isFinite(detection.stepY) && detection.stepY > 0 && Number.isFinite(detection.phaseX) && detection.phaseX >= 0 && detection.phaseX <= detection.stepX && Number.isFinite(detection.phaseY) && detection.phaseY >= 0 && detection.phaseY <= detection.stepY && Number.isInteger(detection.columns) && detection.columns > 0 && Number.isInteger(detection.rows) && detection.rows > 0 && typeof detection.consensus === "string" && !!detection.consensus && isGridConfidence(detection.confidence);
+}
+function isAudit(value) {
+  if (!value || typeof value !== "object") return false;
+  const audit = value;
+  return Number.isInteger(audit.width) && audit.width > 0 && Number.isInteger(audit.height) && audit.height > 0 && Number.isInteger(audit.colorCount) && audit.colorCount >= 0 && typeof audit.paletteConformant === "boolean" && Number.isFinite(audit.transparency) && audit.transparency >= 0 && audit.transparency <= 1 && !!audit.thresholds && Number.isInteger(audit.thresholds.maxColors) && audit.thresholds.maxColors > 0 && (audit.thresholds.minTransparency === null || Number.isFinite(audit.thresholds.minTransparency) && audit.thresholds.minTransparency >= 0 && audit.thresholds.minTransparency <= 1) && isGridConfidence(audit.thresholds.minGridConfidence) && typeof audit.safe === "boolean" && Array.isArray(audit.reasons) && audit.reasons.every((reason) => typeof reason === "string");
+}
+function validFrameSet(value) {
+  if (!value || typeof value !== "object") return false;
+  const frameSet = value;
+  return Number.isInteger(frameSet.fps) && frameSet.fps >= 1 && frameSet.fps <= 60 && Number.isInteger(frameSet.count) && frameSet.count >= 2 && frameSet.count <= 64 && Array.isArray(frameSet.roles) && frameSet.roles.length === frameSet.count && new Set(frameSet.roles).size === frameSet.roles.length && frameSet.roles.every((role) => typeof role === "string" && !!role) && Array.isArray(frameSet.frames) && frameSet.frames.length === frameSet.count && frameSet.frames.every(
+    (frame, index) => frame.role === frameSet.roles[index] && Number.isInteger(frame.sourceWidth) && frame.sourceWidth > 0 && Number.isInteger(frame.sourceHeight) && frame.sourceHeight > 0 && isDetection(frame.detection) && isAudit(frame.audit)
+  );
+}
 function parseRecordOptions(manifest, record) {
   if (manifest.kind !== "refine") throw new Error(`${record} is not a PixelKiln refinement record.`);
   const raw = manifest.options;
@@ -4787,11 +5166,26 @@ function parseRecordOptions(manifest, record) {
   const palette = options.palette;
   const audit = options.audit;
   const review = options.review;
-  if (options.schema !== "pixelkiln-quality" || options.version !== 1 || !grid || grid.tool !== "pixel-art-fixer" || grid.url !== PIXEL_ART_FIXER_URL || typeof grid.revision !== "string" || !grid.revision || grid.protocol !== "python-api-v1" && grid.protocol !== "python-cli-v1" || !isGridConfidence(grid.confidence) || typeof grid.consensus !== "string" || !Number.isFinite(grid.stepX) || !Number.isFinite(grid.stepY) || !Number.isInteger(grid.sourceWidth) || !Number.isInteger(grid.sourceHeight) || !Number.isInteger(grid.nativeWidth) || !Number.isInteger(grid.nativeHeight) || !palette || !Array.isArray(palette.colors) || palette.colors.length < 2 || !palette.colors.every((color) => typeof color === "string") || palette.dither !== "none" || palette.distance !== "redmean" || !audit || typeof audit.safe !== "boolean" || typeof audit.paletteConformant !== "boolean" || !Array.isArray(audit.reasons) || !review || review.status !== "pending" && review.status !== "approved") {
+  if (options.schema !== "pixelkiln-quality" || options.version !== 1 || !grid || grid.tool !== "pixel-art-fixer" || grid.url !== PIXEL_ART_FIXER_URL || typeof grid.revision !== "string" || !grid.revision || grid.protocol !== "python-api-v1" && grid.protocol !== "python-core-v1" && grid.protocol !== "python-cli-v1" || !isGridConfidence(grid.confidence) || typeof grid.consensus !== "string" || !Number.isFinite(grid.stepX) || !Number.isFinite(grid.stepY) || (grid.phaseX !== void 0 || grid.phaseY !== void 0 || options.frameSet !== void 0) && (!Number.isFinite(grid.phaseX) || !Number.isFinite(grid.phaseY)) || !Number.isInteger(grid.sourceWidth) || !Number.isInteger(grid.sourceHeight) || !Number.isInteger(grid.nativeWidth) || !Number.isInteger(grid.nativeHeight) || !palette || !Array.isArray(palette.colors) || palette.colors.length < 2 || !palette.colors.every((color) => typeof color === "string") || palette.dither !== "none" || palette.distance !== "redmean" || !isAudit(audit) || !review || review.status !== "pending" && review.status !== "approved" || options.frameSet !== void 0 && !validFrameSet(options.frameSet)) {
     throw new Error(`${record} has invalid quality metadata.`);
   }
   return options;
 }
+function safeFrameRole(role, index) {
+  const safe = role.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  return safe || `frame-${String(index).padStart(2, "0")}`;
+}
+function qualityFrameOutputPath(output, role, index) {
+  if (!/\.png$/i.test(output)) throw new Error("Refined frame-set output must use a .png stem.");
+  return output.replace(/\.png$/i, `-${safeFrameRole(role, index)}.png`);
+}
+function sameFrameGrid(first, next) {
+  const phaseMatches = (a, b, step) => {
+    const distance = Math.abs(a - b) % step;
+    return Math.min(distance, step - distance) <= 0.01;
+  };
+  return next.detection.stepX === first.detection.stepX && next.detection.stepY === first.detection.stepY && next.detection.columns === first.detection.columns && next.detection.rows === first.detection.rows && phaseMatches(next.detection.phaseX, first.detection.phaseX, first.detection.stepX) && phaseMatches(next.detection.phaseY, first.detection.phaseY, first.detection.stepY) && next.audit.width === first.audit.width && next.audit.height === first.audit.height && next.sourceWidth === first.sourceWidth && next.sourceHeight === first.sourceHeight;
+}
 async function refineAsset(options) {
   const source = path10.resolve(options.source);
   const output = path10.resolve(options.output);
@@ -4806,9 +5200,21 @@ async function refineAsset(options) {
   } catch (error) {
     throw new Error(`Cannot read refinement source ${source}: ${message2(error)}`, { cause: error });
   }
+  const compatibilityCommand = options.fixerCommand;
+  if (!compatibilityCommand) {
+    if (sourcePng.width < PIXEL_ART_FIXER_MIN_SIDE || sourcePng.height < PIXEL_ART_FIXER_MIN_SIDE) {
+      throw new Error(
+        `Pixel Art Fixer requires each source side to be at least ${PIXEL_ART_FIXER_MIN_SIDE}px; got ${sourcePng.width}x${sourcePng.height}.`
+      );
+    }
+    if (sourcePng.width * sourcePng.height > PIXEL_ART_FIXER_MAX_PIXELS) {
+      throw new Error(
+        `Pixel Art Fixer accepts at most ${PIXEL_ART_FIXER_MAX_PIXELS.toLocaleString("en-US")} source pixels; got ${sourcePng.width}x${sourcePng.height}.`
+      );
+    }
+  }
   const temp = await mkdtemp(path10.join(tmpdir(), "pixelkiln-refine-"));
   const recovered = path10.join(temp, "native.png");
-  const compatibilityCommand = options.fixerCommand;
   const fixerCommand = compatibilityCommand ?? options.fixerPython ?? process.env.PIXELKILN_PIXEL_FIXER_PYTHON ?? "python3";
   const args = compatibilityCommand ? [...options.fixerArgsPrefix ?? [], source, "--extract", recovered] : ["-c", PYTHON_FIXER_BRIDGE, source, recovered];
   try {
@@ -4855,11 +5261,13 @@ async function refineAsset(options) {
         tool: "pixel-art-fixer",
         url: PIXEL_ART_FIXER_URL,
         revision: options.fixerRevision ?? PIXEL_ART_FIXER_REVISION,
-        protocol: compatibilityCommand ? "python-cli-v1" : "python-api-v1",
+        protocol: compatibilityCommand ? "python-cli-v1" : "python-core-v1",
         confidence: detection.confidence,
         consensus: detection.consensus,
         stepX: detection.stepX,
         stepY: detection.stepY,
+        phaseX: detection.phaseX,
+        phaseY: detection.phaseY,
         sourceWidth: sourcePng.width,
         sourceHeight: sourcePng.height,
         nativeWidth: quantized.width,
@@ -4880,19 +5288,142 @@ async function refineAsset(options) {
     await rm3(temp, { recursive: true, force: true });
   }
 }
+async function refineFrameSet(options) {
+  if (!Number.isInteger(options.fps) || options.fps < 1 || options.fps > 60) {
+    throw new Error("Frame-set fps must be an integer between 1 and 60.");
+  }
+  if (options.sources.length < 2 || options.sources.length > 64) {
+    throw new Error(`A frame set must contain 2\u201364 ordered sources; got ${options.sources.length}.`);
+  }
+  const roles = options.sources.map((source) => source.role);
+  if (roles.some((role) => !role.trim()) || new Set(roles).size !== roles.length) {
+    throw new Error("Frame-set roles must be non-empty and unique.");
+  }
+  const output = path10.resolve(options.output);
+  const record = path10.resolve(qualityRecordPath(output));
+  const palette = normalizeRefinementPalette(options.palette);
+  const finalOutputs = options.sources.map((source, index) => qualityFrameOutputPath(output, source.role, index));
+  if (new Set(finalOutputs).size !== finalOutputs.length) {
+    throw new Error("Frame-set roles resolve to duplicate output filenames.");
+  }
+  const sourceSet = new Set(options.sources.map((source) => path10.resolve(source.path)));
+  if (finalOutputs.some((file) => sourceSet.has(file))) {
+    throw new Error("Frame-set refinement sources and outputs must be different files.");
+  }
+  const temp = await mkdtemp(path10.join(tmpdir(), "pixelkiln-refine-frames-"));
+  try {
+    const frames = [];
+    const outputs = [];
+    const provenanceSources = [];
+    const sourcePaths = [];
+    let firstOptions = null;
+    for (const [index, sourceEntry] of options.sources.entries()) {
+      const source = path10.resolve(sourceEntry.path);
+      const temporaryOutput = path10.join(temp, `${String(index).padStart(2, "0")}.png`);
+      const refined = await refineAsset({
+        source,
+        output: temporaryOutput,
+        palette,
+        fixerPython: options.fixerPython,
+        fixerCommand: options.fixerCommand,
+        fixerArgsPrefix: options.fixerArgsPrefix,
+        fixerRevision: options.fixerRevision,
+        minGridConfidence: options.minGridConfidence,
+        minTransparency: options.minTransparency,
+        force: true
+      });
+      const temporaryRecord = await readArtifactBundleManifest(refined.record);
+      const frameOptions = parseRecordOptions(temporaryRecord, refined.record);
+      firstOptions ??= frameOptions;
+      frames.push({
+        role: sourceEntry.role,
+        sourceWidth: frameOptions.nativeGrid.sourceWidth,
+        sourceHeight: frameOptions.nativeGrid.sourceHeight,
+        detection: refined.detection,
+        audit: refined.audit
+      });
+      sourcePaths.push(source);
+      provenanceSources.push({
+        id: sourceEntry.role,
+        path: source,
+        sha256: await sha256File(source),
+        included: true
+      });
+      outputs.push({
+        path: finalOutputs[index],
+        data: await readFile6(temporaryOutput)
+      });
+    }
+    const first = frames[0];
+    const mismatch = frames.find((frame) => !sameFrameGrid(first, frame));
+    if (mismatch) {
+      throw new Error(
+        `Frame-set native grid mismatch: ${first.role} detected ${first.detection.columns}x${first.detection.rows} at ${first.detection.stepX}x${first.detection.stepY}, phase ${first.detection.phaseX},${first.detection.phaseY}; but ${mismatch.role} detected ${mismatch.detection.columns}x${mismatch.detection.rows} at ${mismatch.detection.stepX}x${mismatch.detection.stepY}, phase ${mismatch.detection.phaseX},${mismatch.detection.phaseY}.`
+      );
+    }
+    const reasons = frames.flatMap(
+      (frame) => frame.audit.reasons.map((reason) => `${frame.role}: ${reason}`)
+    );
+    const audit = {
+      width: first.audit.width,
+      height: first.audit.height,
+      colorCount: Math.max(...frames.map((frame) => frame.audit.colorCount)),
+      paletteConformant: frames.every((frame) => frame.audit.paletteConformant),
+      transparency: Math.min(...frames.map((frame) => frame.audit.transparency)),
+      thresholds: first.audit.thresholds,
+      safe: frames.every((frame) => frame.audit.safe) && reasons.length === 0,
+      reasons
+    };
+    const baseOptions = firstOptions;
+    const recordOptions = {
+      ...baseOptions,
+      audit,
+      review: { status: "pending" },
+      frameSet: {
+        fps: options.fps,
+        count: frames.length,
+        roles,
+        frames
+      }
+    };
+    await writeManagedArtifactBundle(
+      record,
+      outputs,
+      { kind: "refine", sources: provenanceSources, options: recordOptions },
+      { force: options.force }
+    );
+    return {
+      sources: sourcePaths,
+      outputs: outputs.map((item) => path10.resolve(item.path)),
+      record,
+      frames,
+      palette,
+      audit
+    };
+  } finally {
+    await rm3(temp, { recursive: true, force: true });
+  }
+}
 async function checkQualityRecord(recordPath) {
   const record = path10.resolve(recordPath);
   const manifest = await readArtifactBundleManifest(record);
   const options = parseRecordOptions(manifest, record);
   const verification = await verifyArtifactBundle(record);
-  const source = manifest.sources.length === 1 ? path10.resolve(path10.dirname(record), manifest.sources[0].path) : "";
-  const output = manifest.outputs.length === 1 ? path10.resolve(path10.dirname(record), manifest.outputs[0].path) : "";
+  const sources = manifest.sources.map((source2) => path10.resolve(path10.dirname(record), source2.path));
+  const outputs = manifest.outputs.map((output2) => path10.resolve(path10.dirname(record), output2.path));
+  const source = sources[0] ?? "";
+  const output = outputs[0] ?? "";
+  const expectedCount = options.frameSet?.count ?? 1;
   const reasons = [];
   if (!verification.fingerprintValid) reasons.push("quality record fingerprint changed");
   for (const source2 of verification.changedSources) reasons.push(`source changed: ${source2}`);
   for (const changed of verification.changedOutputs) reasons.push(`output changed: ${changed}`);
-  if (manifest.sources.length !== 1) reasons.push("quality record must contain exactly one source");
-  if (manifest.outputs.length !== 1) reasons.push("quality record must contain exactly one output");
+  if (manifest.sources.length !== expectedCount) {
+    reasons.push(`quality record must contain exactly ${expectedCount} source(s)`);
+  }
+  if (manifest.outputs.length !== expectedCount) {
+    reasons.push(`quality record must contain exactly ${expectedCount} output(s)`);
+  }
   if (!options.audit.safe) reasons.push(...options.audit.reasons.map((reason) => `audit: ${reason}`));
   if (options.review.status !== "approved") reasons.push("human 1\xD7 review is pending");
   return {
@@ -4903,6 +5434,8 @@ async function checkQualityRecord(recordPath) {
     record,
     source,
     output,
+    sources,
+    outputs,
     options,
     reasons
   };
@@ -4917,7 +5450,7 @@ async function approveQualityRecord(recordPath, approval) {
   if (!verification.current) {
     const changes = [
       ...verification.changedSources.map((source) => `source ${source}`),
-      ...verification.changedOutputs.map((output2) => `output ${output2}`),
+      ...verification.changedOutputs.map((output) => `output ${output}`),
       ...!verification.fingerprintValid ? ["quality metadata"] : []
     ];
     throw new Error(`Cannot approve a stale refinement; changed: ${changes.join(", ")}. Run refine again.`);
@@ -4925,12 +5458,17 @@ async function approveQualityRecord(recordPath, approval) {
   if (!options.audit.safe) {
     throw new Error(`Cannot approve a failed quality audit: ${options.audit.reasons.join("; ")}`);
   }
-  if (manifest.sources.length !== 1 || manifest.outputs.length !== 1) {
-    throw new Error("A refinement record must contain exactly one source and one output.");
+  const expectedCount = options.frameSet?.count ?? 1;
+  if (manifest.sources.length !== expectedCount || manifest.outputs.length !== expectedCount) {
+    throw new Error(
+      `A refinement record must contain exactly ${expectedCount} source(s) and output(s).`
+    );
   }
   const root = path10.dirname(record);
-  const outputPath = path10.resolve(root, manifest.outputs[0].path);
-  const output = await readFile6(outputPath);
+  const outputs = await Promise.all(manifest.outputs.map(async (entry) => {
+    const outputPath = path10.resolve(root, entry.path);
+    return { path: outputPath, data: await readFile6(outputPath) };
+  }));
   const sources = manifest.sources.map((source) => ({
     ...source,
     path: path10.resolve(root, source.path)
@@ -4953,7 +5491,7 @@ async function approveQualityRecord(recordPath, approval) {
   };
   await writeManagedArtifactBundle(
     record,
-    [{ path: outputPath, data: output }],
+    outputs,
     { kind: "refine", sources, options: approved }
   );
   return checkQualityRecord(record);
@@ -4962,33 +5500,46 @@ async function approveQualityRecord(recordPath, approval) {
 // src/pipeline/quality-profile.ts
 async function qualitySource(spec, lock) {
   if (spec.source) {
-    const source2 = path11.resolve(spec.root, spec.source);
-    return existsSync6(source2) ? { path: source2 } : { path: null, reason: `declared source is missing: ${spec.source}` };
+    if (spec.generator === "frames") {
+      return { items: null, reason: "frame-set quality requires ordered downloaded provider outputs" };
+    }
+    const source = path11.resolve(spec.root, spec.source);
+    return existsSync6(source) ? { items: [{ role: "source", path: source }] } : { items: null, reason: `declared source is missing: ${spec.source}` };
   }
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
-  if (!entry) return { path: null, reason: "raw provider output is not in the lockfile" };
+  if (!entry) return { items: null, reason: "raw provider output is not in the lockfile" };
   if (entry.specHash !== spec.specHash) {
-    return { path: null, reason: "raw provider output does not match the current generation spec" };
+    return { items: null, reason: "raw provider output does not match the current generation spec" };
   }
   if (entry.status !== "downloaded") {
-    return { path: null, reason: `raw provider output is ${entry.status}, not downloaded` };
+    return { items: null, reason: `raw provider output is ${entry.status}, not downloaded` };
   }
-  if (entry.outputs.length !== 1) {
+  const frameSet = spec.generator === "frames";
+  if (!frameSet && entry.outputs.length !== 1 || frameSet && entry.outputs.length < 2) {
     return {
-      path: null,
-      reason: `quality profiles require one PNG output; lock entry has ${entry.outputs.length}`
+      items: null,
+      reason: frameSet ? `frame-set quality requires at least two PNG outputs; lock entry has ${entry.outputs.length}` : `quality profiles require one PNG output; lock entry has ${entry.outputs.length}`
     };
   }
-  const output = entry.outputs[0];
-  if (output.mediaType && output.mediaType !== MediaType.PNG) {
-    return { path: null, reason: `quality profiles require PNG input; lock entry is ${output.mediaType}` };
-  }
-  const source = currentEntryOutputPath(entry, spec, 0);
-  if (!existsSync6(source)) return { path: null, reason: `raw provider output is missing: ${source}` };
-  if (await sha256File(source) !== output.sha256) {
-    return { path: null, reason: "raw provider output was modified after download" };
+  const roles = /* @__PURE__ */ new Set();
+  const items = [];
+  for (const [index, output] of entry.outputs.entries()) {
+    if (output.mediaType && output.mediaType !== MediaType.PNG) {
+      return { items: null, reason: `quality profiles require PNG input; lock entry is ${output.mediaType}` };
+    }
+    const role = frameSet ? output.role : "source";
+    if (frameSet && (!role || roles.has(role))) {
+      return { items: null, reason: "frame-set quality requires a unique role for every ordered output" };
+    }
+    if (role) roles.add(role);
+    const source = currentEntryOutputPath(entry, spec, index);
+    if (!existsSync6(source)) return { items: null, reason: `raw provider output is missing: ${source}` };
+    if (await sha256File(source) !== output.sha256) {
+      return { items: null, reason: "raw provider output was modified after download" };
+    }
+    items.push({ role, path: source });
   }
-  return { path: source };
+  return { items };
 }
 async function inspectQualityProfile(spec, lock) {
   if (!spec.quality) return null;
@@ -4996,16 +5547,20 @@ async function inspectQualityProfile(spec, lock) {
   const output = spec.quality.outFile;
   const record = qualityRecordPath(output);
   const source = await qualitySource(spec, lock);
-  if (!source.path) {
+  if (!source.items) {
     return { key, state: "blocked", reason: source.reason, source: null, output, record };
   }
+  const sourcePaths = source.items.map((item) => item.path);
+  const expectedOutputs = spec.generator === "frames" ? source.items.map((item, index) => qualityFrameOutputPath(output, item.role, index)) : [output];
   if (!existsSync6(record)) {
     return {
       key,
       state: "needs-refinement",
       reason: "no refinement record",
-      source: source.path,
+      source: sourcePaths[0],
+      sources: sourcePaths,
       output,
+      outputs: expectedOutputs,
       record
     };
   }
@@ -5014,14 +5569,17 @@ async function inspectQualityProfile(spec, lock) {
     const expectedPalette = normalizeRefinementPalette(spec.quality.palette);
     const expectedRevision = spec.quality.fixerRevision ?? PIXEL_ART_FIXER_REVISION;
     const expectedTransparency = spec.quality.minTransparency ?? null;
-    const contractChanged = path11.resolve(check.source) !== path11.resolve(source.path) || path11.resolve(check.output) !== path11.resolve(output) || JSON.stringify(check.options.palette.colors) !== JSON.stringify(expectedPalette) || check.options.nativeGrid.revision !== expectedRevision || check.options.audit.thresholds.minGridConfidence !== spec.quality.minGridConfidence || check.options.audit.thresholds.minTransparency !== expectedTransparency;
+    const expectedFrameSet = spec.generator === "frames" ? { fps: spec.quality.fps ?? 12, count: source.items.length, roles: source.items.map((item) => item.role) } : null;
+    const contractChanged = JSON.stringify(check.sources.map((item) => path11.resolve(item))) !== JSON.stringify(sourcePaths.map((item) => path11.resolve(item))) || JSON.stringify(check.outputs.map((item) => path11.resolve(item))) !== JSON.stringify(expectedOutputs.map((item) => path11.resolve(item))) || JSON.stringify(check.options.palette.colors) !== JSON.stringify(expectedPalette) || check.options.nativeGrid.revision !== expectedRevision || check.options.audit.thresholds.minGridConfidence !== spec.quality.minGridConfidence || check.options.audit.thresholds.minTransparency !== expectedTransparency || (expectedFrameSet ? !check.options.frameSet || check.options.frameSet.fps !== expectedFrameSet.fps || check.options.frameSet.count !== expectedFrameSet.count || JSON.stringify(check.options.frameSet.roles) !== JSON.stringify(expectedFrameSet.roles) : check.options.frameSet !== void 0);
     if (contractChanged) {
       return {
         key,
         state: "needs-refinement",
         reason: "quality profile changed",
-        source: source.path,
+        source: sourcePaths[0],
+        sources: sourcePaths,
         output,
+        outputs: expectedOutputs,
         record
       };
     }
@@ -5030,8 +5588,10 @@ async function inspectQualityProfile(spec, lock) {
         key,
         state: "needs-refinement",
         reason: check.reasons.filter((reason) => reason !== "human 1\xD7 review is pending").join("; ") || "refinement record is stale",
-        source: source.path,
+        source: sourcePaths[0],
+        sources: sourcePaths,
         output,
+        outputs: expectedOutputs,
         record
       };
     }
@@ -5040,8 +5600,10 @@ async function inspectQualityProfile(spec, lock) {
         key,
         state: "needs-approval",
         reason: "automated checks passed; human 1\xD7 review is pending",
-        source: source.path,
+        source: sourcePaths[0],
+        sources: sourcePaths,
         output,
+        outputs: expectedOutputs,
         record
       };
     }
@@ -5049,8 +5611,10 @@ async function inspectQualityProfile(spec, lock) {
       key,
       state: "approved",
       reason: "refined output and human approval are current",
-      source: source.path,
+      source: sourcePaths[0],
+      sources: sourcePaths,
       output,
+      outputs: expectedOutputs,
       record
     };
   } catch (error) {
@@ -5058,8 +5622,10 @@ async function inspectQualityProfile(spec, lock) {
       key,
       state: "needs-refinement",
       reason: `invalid refinement record: ${error instanceof Error ? error.message : String(error)}`,
-      source: source.path,
+      source: sourcePaths[0],
+      sources: sourcePaths,
       output,
+      outputs: expectedOutputs,
       record
     };
   }
@@ -5083,8 +5649,7 @@ async function refineQualityProfiles(specs, lock, options = {}) {
       continue;
     }
     try {
-      await refineAsset({
-        source: inspection.source,
+      const common = {
         output: inspection.output,
         palette: spec.quality.palette,
         minGridConfidence: spec.quality.minGridConfidence,
@@ -5096,7 +5661,18 @@ async function refineQualityProfiles(specs, lock, options = {}) {
         fixerCommand: options.fixerCommand,
         fixerArgsPrefix: options.fixerArgsPrefix,
         force: options.force
-      });
+      };
+      if (spec.generator === "frames") {
+        const frameSources = await qualitySource(spec, lock);
+        if (!frameSources.items) throw new Error(frameSources.reason);
+        await refineFrameSet({
+          ...common,
+          sources: frameSources.items,
+          fps: spec.quality.fps ?? 12
+        });
+      } else {
+        await refineAsset({ ...common, source: inspection.source });
+      }
       result.processed++;
       result.items.push(await inspectQualityProfile(spec, lock));
     } catch (error) {
@@ -5110,7 +5686,7 @@ async function refineQualityProfiles(specs, lock, options = {}) {
   }
   return result;
 }
-async function requireApprovedQualitySources(specs, lock, assetIds) {
+async function requireApprovedQualitySources(specs, lock, assetIds, outputRoles) {
   const configured = specs.filter(
     (spec) => spec.quality && (!assetIds || assetIds.has(spec.assetId))
   );
@@ -5119,8 +5695,33 @@ async function requireApprovedQualitySources(specs, lock, assetIds) {
   const rejected = [];
   for (const spec of configured) {
     const inspection = await inspectQualityProfile(spec, lock);
-    if (inspection.state === "approved") sources[spec.assetId] = inspection.output;
-    else rejected.push(inspection);
+    if (inspection.state === "approved") {
+      if (spec.generator === "frames") {
+        const check = await checkQualityRecord(inspection.record);
+        const roles = check.options.frameSet.roles;
+        if (outputRoles) {
+          const selectedRole = outputRoles[spec.assetId];
+          if (!selectedRole) {
+            throw new Error(
+              `Mounting quality-approved frame set ${inspection.key} requires asset.outputRole.`
+            );
+          }
+          const index = roles.indexOf(selectedRole);
+          if (index < 0) {
+            throw new Error(
+              `Frame set ${inspection.key} has no approved output role "${selectedRole}".`
+            );
+          }
+          sources[spec.assetId] = check.outputs[index];
+        } else {
+          for (const [index, output] of check.outputs.entries()) {
+            sources[`${spec.assetId}/${roles[index]}`] = output;
+          }
+        }
+      } else {
+        sources[spec.assetId] = inspection.output;
+      }
+    } else rejected.push(inspection);
   }
   if (rejected.length) {
     const detail = rejected.slice(0, 5).map((item) => `${item.key}: ${item.state} (${item.reason})`).join("; ");
@@ -5473,7 +6074,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         jobId,
         // A multi-candidate generator routes through review; record the parent
         // so `pick` knows where to look.
-        reviewObjectId: estimate.candidates > 1 && !spec.tileFeature ? jobId : null,
+        reviewObjectId: spec.generator === "frames" || estimate.candidates > 1 && !spec.tileFeature ? jobId : null,
         status: "processing",
         providerMetadata: metadata ? { ...lock.entries[key].providerMetadata, [provider.id]: metadata } : lock.entries[key].providerMetadata
       });
@@ -5521,7 +6122,7 @@ async function poll(provider, lock, lockPath, opts = {}) {
           tileFeature: entry.tileFeature ?? currentSpec?.tileFeature,
           spec: currentSpec
         });
-        if (state.status === "review") {
+        if (state.status === "review" || state.status === "review-set") {
           upsert(lock, key, {
             status: "review",
             reviewObjectId: entry.jobId,
@@ -5534,7 +6135,9 @@ async function poll(provider, lock, lockPath, opts = {}) {
             } : entry.providerMetadata
           });
           result.review++;
-          log2(`  review  ${key} (${state.candidateUrls.length} candidates)`);
+          log2(
+            state.status === "review-set" ? `  review  ${key} (${state.frameUrls.length} ordered frames)` : `  review  ${key} (${state.candidateUrls.length} candidates)`
+          );
         } else if (state.status === "ready") {
           const sourceUrls = state.sources?.length ? state.sources : state.sourceUrl ? [{ url: state.sourceUrl }] : [];
           upsert(lock, key, {
@@ -6293,12 +6896,17 @@ function renderSheet(groups) {
       linear-gradient(45deg,#0000 25%,#7f7f7f22 25%,#7f7f7f22 75%,#0000 75%);
     background-size:12px 12px; background-position:0 0,6px 6px; }
   .frames { display:flex; flex-wrap:wrap; gap:10px; max-width:100%; overflow-x:auto; }
+  .loop { display:flex; align-items:flex-start; gap:12px; margin-bottom:12px; }
+  .loop img { image-rendering:pixelated; border:2px solid var(--accent); padding:7px;
+    background:var(--panel-deep); max-width:min(var(--preview),calc(100vw - 62px)); height:auto; }
+  .loop-copy { color:var(--dim); font-size:11px; max-width:32ch; }
   .cand { border:2px solid var(--line-strong); border-radius:0; padding:7px; background:var(--panel-deep);
     cursor:pointer; display:flex; flex:0 0 auto; flex-direction:column; align-items:center; gap:5px;
     position:relative; max-width:100%; }
   .cand:hover { border-color:var(--dim); }
   .cand.active { border-color:var(--dim); box-shadow:0 0 0 2px color-mix(in srgb, var(--dim) 20%, transparent); }
   .cand.sel { border-color:var(--ok); box-shadow:0 0 0 3px color-mix(in srgb, var(--ok) 22%, transparent); }
+  .cand.set-frame { cursor:pointer; }
   .cand img { image-rendering:pixelated; display:block;
     background-image:
       linear-gradient(45deg,#0000 25%,#7f7f7f22 25%,#7f7f7f22 75%,#0000 75%),
@@ -6336,7 +6944,8 @@ function renderSheet(groups) {
 </header>
 <main id="root"></main>
 <footer>
-  Click a candidate to choose it; click again to unchoose. In the focused row,
+  Click a candidate to choose it, or any ordered frame to accept its whole set;
+  click again to undo. In the focused row,
   <kbd>\u2190</kbd>/<kbd>\u2192</kbd> browses every candidate and <kbd>Enter</kbd> chooses;
   <kbd>1</kbd>\u2013<kbd>9</kbd> picks directly, <kbd>0</kbd> skips, and
   <kbd>\u2191</kbd>/<kbd>\u2193</kbd> changes rows. Unchosen rows stay in review \u2014 nothing is
@@ -6384,12 +6993,34 @@ GROUPS.forEach((g, gi) => {
     context.append(label, source);
     review.insertBefore(context, frames);
   }
+  if (g.mode === 'frame-set') {
+    const loop = document.createElement('div');
+    loop.className = 'loop';
+    const preview = document.createElement('img');
+    preview.src = g.frameUrls[0];
+    preview.width = displayWidth;
+    preview.height = displayHeight;
+    preview.alt = 'Animated frame-set preview';
+    const copy = document.createElement('div');
+    copy.className = 'loop-copy';
+    copy.textContent = g.frameUrls.length + ' ordered frames \xB7 ' + (g.fps || 12) +
+      ' fps. Accepting keeps every frame; one bad frame means leave the set unchosen.';
+    loop.append(preview, copy);
+    review.insertBefore(loop, frames);
+    let loopIndex = 0;
+    setInterval(() => {
+      loopIndex = (loopIndex + 1) % g.frameUrls.length;
+      preview.src = g.frameUrls[loopIndex];
+    }, Math.max(16, Math.round(1000 / (g.fps || 12))));
+  }
   g.frameUrls.forEach((url, i) => {
     const c = document.createElement('button');
     c.type = 'button';
-    c.className = 'cand';
+    c.className = 'cand' + (g.mode === 'frame-set' ? ' set-frame' : '');
     c.tabIndex = -1;
-    c.setAttribute('aria-label', 'Choose candidate ' + (i + 1) + ' of ' + g.frameUrls.length);
+    c.setAttribute('aria-label', g.mode === 'frame-set'
+      ? 'Accept ordered frame set from frame ' + (i + 1)
+      : 'Choose candidate ' + (i + 1) + ' of ' + g.frameUrls.length);
 
     const preview = document.createElement('img');
     preview.className = 'preview';
@@ -6399,7 +7030,8 @@ GROUPS.forEach((g, gi) => {
     preview.loading = 'lazy';
     const index = document.createElement('span');
     index.className = 'idx';
-    index.textContent = String(i + 1) + ' \xB7 ' + g.width + '\xD7' + g.height + ' \xB7 ' + scaleLabel;
+    index.textContent = (g.frameLabels?.[i] || String(i + 1)) + ' \xB7 ' +
+      g.width + '\xD7' + g.height + ' \xB7 ' + scaleLabel;
     c.append(preview, index);
     if (displayScale > 1 && largestSide <= 96) {
       const actual = document.createElement('img');
@@ -6440,6 +7072,14 @@ function activate(i, frames) {
 }
 
 function choose(gi, i, node, frames, groupEl) {
+  if (GROUPS[gi].mode === 'frame-set') {
+    const selected = picks.has(gi);
+    frames.querySelectorAll('.cand').forEach(n => n.classList.toggle('sel', !selected));
+    if (selected) { picks.delete(gi); groupEl.classList.remove('done'); }
+    else { picks.set(gi, 0); groupEl.classList.add('done'); }
+    refresh();
+    return;
+  }
   const current = picks.get(gi);
   frames.querySelectorAll('.cand').forEach(n => n.classList.remove('sel'));
   if (current === i) { picks.delete(gi); groupEl.classList.remove('done'); }
@@ -6616,7 +7256,8 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
     try {
       const spec = specByKey.get(key);
       const state = await provider.poll(entry.reviewObjectId, entry.generator, { spec });
-      if (state.status !== "review" || !state.candidateUrls.length) continue;
+      if (state.status !== "review" && state.status !== "review-set" || (state.status === "review" ? !state.candidateUrls.length : !state.frameUrls.length)) continue;
+      const frameUrls = state.status === "review" ? state.candidateUrls : state.frameUrls;
       const sourceRoute = spec?.revision ? `/revision-source/${encodeURIComponent(String(groups.length))}` : null;
       if (sourceRoute && spec?.revision) {
         reviewAssets.set(sourceRoute, {
@@ -6630,9 +7271,14 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
         styleId: entry.styleId,
         prompt: entry.prompt,
         reviewObjectId: entry.reviewObjectId,
-        frameUrls: state.candidateUrls,
+        frameUrls,
         width: entry.width,
         height: entry.height,
+        ...state.status === "review-set" ? {
+          mode: "frame-set",
+          frameLabels: state.sources.map((source, index) => source.role ?? `frame-${index}`),
+          fps: state.fps
+        } : { mode: "candidates" },
         ...sourceRoute && spec?.revision && spec.revision.sourceWidth && spec.revision.sourceHeight ? {
           revision: {
             mode: spec.revision.mode,
@@ -6675,6 +7321,31 @@ 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;
+        if (group.mode === "frame-set") {
+          const spec = specByKey.get(key);
+          const state = await provider.poll(entry.reviewObjectId, entry.generator, { spec });
+          if (state.status !== "review-set") {
+            throw new Error(`Frame set ${key} is no longer ready for review`);
+          }
+          upsert(lock, key, {
+            status: "selected",
+            objectId: state.objectId,
+            candidateIndex: null,
+            sourceUrl: state.sources[0]?.url ?? null,
+            sourceUrls: state.sources,
+            provider: provider.id,
+            providerMetadata: state.metadata ? {
+              ...entry.providerMetadata,
+              [provider.id]: {
+                ...entry.providerMetadata[provider.id],
+                ...state.metadata
+              }
+            } : entry.providerMetadata
+          });
+          selected++;
+          log2(`  accepted ${key} \u2192 ${state.sources.length} ordered frames`);
+          continue;
+        }
         const { objectId, sourceUrl, metadata } = await requireSelectCandidate(provider)(
           entry.reviewObjectId,
           index,
@@ -6767,6 +7438,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
       file: asset.file,
       tags: [],
       styles: [],
+      providerInputs: {},
       ...generator === "map" ? { width: asset.width, height: asset.height } : asset.width === asset.height && asset.width !== commonSize ? { size: asset.width } : {}
     };
   }
@@ -7829,6 +8501,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               file: rel,
               tags: ["salvaged"],
               styles: [ctx.styleId],
+              providerInputs: {},
               ...orphan.width === orphan.height ? { size: orphan.width } : { width: orphan.width, height: orphan.height }
             };
             const durableSource = shouldPersistSourceUrl(orphan.previewUrl) ? orphan.previewUrl : null;
@@ -9382,9 +10055,15 @@ async function main() {
       if (!args.reviewer?.trim()) {
         throw new Error("refine approve needs --reviewer <name>.");
       }
-      log(`  Inspect the final PNG at 1\xD7 and integer zoom.`);
+      const pending = await checkQualityRecord(args.from);
+      log(
+        pending.options.frameSet ? `  Inspect all ${pending.options.frameSet.count} ordered frames at 1\xD7, integer zoom, and playback speed.` : `  Inspect the final PNG at 1\xD7 and integer zoom.`
+      );
       log(`  Confirm crisp edges, readable forms, palette separation, alpha, and seams.`);
-      if (!await confirm("  Record this asset as human-approved?", args.yes)) {
+      if (!await confirm(
+        pending.options.frameSet ? "  Record this complete frame set as human-approved?" : "  Record this asset as human-approved?",
+        args.yes
+      )) {
         log("  approval not recorded");
         return;
       }
@@ -9393,7 +10072,11 @@ async function main() {
         note: args.note
       });
       if (args.json) log(JSON.stringify(result2, null, 2));
-      else log(`  approved ${path24.relative(process.cwd(), result2.output)} by ${args.reviewer.trim()}`);
+      else {
+        log(
+          result2.options.frameSet ? `  approved ${result2.outputs.length} frames in ${path24.relative(process.cwd(), result2.record)} by ${args.reviewer.trim()}` : `  approved ${path24.relative(process.cwd(), result2.output)} by ${args.reviewer.trim()}`
+        );
+      }
       return;
     }
     const result = await checkQualityRecord(args.from);
@@ -9906,7 +10589,10 @@ async function main() {
         { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
       ];
       const qualityRecords = qualitySources ? await Promise.all(
-        Object.entries(qualitySources).map(([assetId, source]) => provenanceFile(`$quality/${assetId}`, qualityRecordPath(source)))
+        packagingSpecs.filter((spec) => spec.quality).map((spec) => provenanceFile(
+          `$quality/${spec.assetId}`,
+          qualityRecordPath(spec.quality.outFile)
+        ))
       ) : [];
       await writeManagedArtifactBundle(`${base}.pixelkiln.json`, outputs, {
         kind: "pack",
@@ -9958,7 +10644,8 @@ async function main() {
       const qualitySources = await requireApprovedQualitySources(
         packagingSpecs,
         lock,
-        new Set(Object.keys(cells))
+        new Set(Object.keys(cells)),
+        outputRoles
       );
       if (qualitySources) Object.assign(sources, qualitySources);
       const { png, atlas, skipped, overBase, sources: artifactSources } = mountStyle(
@@ -9978,7 +10665,10 @@ async function main() {
         { path: metadata, data: JSON.stringify(atlas, null, 2) + "\n" }
       ];
       const qualityRecords = qualitySources ? await Promise.all(
-        Object.entries(qualitySources).map(([assetId, source]) => provenanceFile(`$quality/${assetId}`, qualityRecordPath(source)))
+        packagingSpecs.filter((spec) => spec.quality && Object.hasOwn(cells, spec.assetId)).map((spec) => provenanceFile(
+          `$quality/${spec.assetId}`,
+          qualityRecordPath(spec.quality.outFile)
+        ))
       ) : [];
       await writeManagedArtifactBundle(companion, outputs, {
         kind: "mount",