pixelkiln 0.57.0 → 0.59.0

package/dist/cli.js

@@ -703,6 +703,11 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
       // A mirror's bytes come from its source's recorded outputs; the plan
       // compares those directly, so only the choice of source is identity.
       mirror: spec.mirror ? { of: spec.mirror.sourceAssetId } : void 0,
+      // The whole group's ordered descriptions, not just this asset's own —
+      // any sibling's prompt changing, or a member being added or removed,
+      // must mark every member stale together, since they all ride on one
+      // submitted job with no way to amend it after the fact.
+      batch: spec.batch ? { role: spec.batch.role, itemDescriptions: spec.batch.itemDescriptions, index: spec.batch.index } : void 0,
       revision: spec.revision ? {
         mode: spec.revision.mode,
         from: spec.revision.sourceAssetId,
@@ -712,7 +717,12 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         numColors: spec.revision.numColors,
         paletteImageSha256: spec.revision.paletteImageSha256,
         dithering: spec.revision.dithering,
-        ditheringStrength: spec.revision.ditheringStrength
+        ditheringStrength: spec.revision.ditheringStrength,
+        frames: spec.revision.frames,
+        fps: spec.revision.fps,
+        lastFrameSha256: spec.revision.lastFrameSha256,
+        direction: spec.revision.direction,
+        enhancePrompt: spec.revision.enhancePrompt
       } : void 0
     })
   );
@@ -732,7 +742,15 @@ import { z } from "zod";
 var MediaTypeSchema = z.enum(["image/png", "image/gif"]);
 var GeneratorSchema = z.enum(["1dir", "map", "pixflux", "tiles", "animation", "frames", "character", "terrain", "imagePro", "isometricTile", "objectPro"]);
 var GridConfidenceSchema = z.enum(["low", "medium", "high"]);
-var RevisionModeSchema = z.enum(["image-to-image", "inpaint", "outpaint", "reduce-colors", "correct-pixelart"]);
+var RevisionModeSchema = z.enum([
+  "image-to-image",
+  "inpaint",
+  "outpaint",
+  "reduce-colors",
+  "correct-pixelart",
+  "animate",
+  "animate-pixminimax"
+]);
 function tileVariationCount(descriptions) {
   return Math.max(1, descriptions) * 4;
 }
@@ -844,6 +862,12 @@ var CharacterProportionsSchema = z.union([
   }).strict()
 ]);
 var CharacterAnimationModeSchema = z.enum(["template", "v3", "pro"]);
+var AssetBatchSchema = z.object({
+  /** The batch leader: another `1dir` asset in the same style. */
+  of: z.string().min(1),
+  /** 1-based slot in the batch (the leader is implicitly slot 0). Unique and contiguous among siblings. */
+  index: z.number().int().min(1)
+}).strict();
 var CharacterStateSchema = z.object({
   /** The base character, or another state, in the same style. */
   of: z.string().min(1),
@@ -943,7 +967,21 @@ var RevisionSchema = z.object({
   /** `reduce-colors` only: ordered dithering matrix size. */
   dithering: RevisionDitheringSchema.optional(),
   /** `reduce-colors` only: dithering intensity; ignored when `dithering` is "none" or unset. */
-  ditheringStrength: z.number().min(0).max(10).optional()
+  ditheringStrength: z.number().min(0).max(10).optional(),
+  /**
+   * `animate`/`animate-pixminimax` only: frames to generate, even, 4 to 40
+   * (the provider-specific ceiling — 16 for `animate` — is enforced at
+   * the provider layer, since it differs by mode).
+   */
+  frames: z.number().int().min(4).max(40).optional(),
+  /** `animate`/`animate-pixminimax` only: playback rate recorded with the frames; PixelLab does not store one. */
+  fps: z.number().int().min(1).max(60).optional(),
+  /** `animate`/`animate-pixminimax` only: manifest-relative image pinning where the motion ends (interpolation instead of open-ended animation). */
+  lastFrame: z.string().min(1).optional(),
+  /** `animate-pixminimax` only: facing direction, used only alongside `enhancePrompt` to hold the sprite's facing. */
+  direction: CharacterDirectionSchema.optional(),
+  /** `animate`/`animate-pixminimax` only: let PixelLab expand the action into a fuller motion description first. */
+  enhancePrompt: z.boolean().optional()
 }).strict().superRefine((revision, context) => {
   if (revision.mode === "inpaint" && !revision.mask) {
     context.addIssue({
@@ -982,6 +1020,32 @@ var RevisionSchema = z.object({
       path: ["strength"]
     });
   }
+  if (revision.strength !== void 0 && (revision.mode === "animate" || revision.mode === "animate-pixminimax")) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `${revision.mode} revisions do not take a strength; use enhancePrompt`,
+      path: ["strength"]
+    });
+  }
+  for (const field of ["frames", "fps", "lastFrame", "enhancePrompt"]) {
+    if (revision[field] !== void 0 && revision.mode !== "animate" && revision.mode !== "animate-pixminimax") {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${field} applies to animate/animate-pixminimax revisions only`,
+        path: [field]
+      });
+    }
+  }
+  if (revision.direction !== void 0 && revision.mode !== "animate-pixminimax") {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "direction applies to animate-pixminimax revisions only",
+      path: ["direction"]
+    });
+  }
+  if (revision.frames !== void 0 && revision.frames % 2 !== 0) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
+  }
 });
 var StyleObjectSchema = z.object({
   /** Generation backend for this style. Omit to inherit the manifest default. */
@@ -1377,6 +1441,12 @@ var AssetSchema = z.object({
    * `prompt` instead.
    */
   animation: CharacterAnimationSchema.optional(),
+  /**
+   * `1dir` styles only: this asset rides along on another `1dir` asset's
+   * batch submission instead of generating on its own. See
+   * `AssetBatchSchema`.
+   */
+  batch: AssetBatchSchema.optional(),
   /** `character` styles, `standard` humanoid bases: this character's proportions, over the style's. */
   proportions: CharacterProportionsSchema.optional(),
   /**
@@ -1453,7 +1523,7 @@ var AssetSchema = z.object({
       path: ["revision"]
     });
   }
-  const shapes = [asset.revision && "revision", asset.state && "state", asset.animation && "animation", asset.mirror && "mirror"].filter(Boolean);
+  const shapes = [asset.revision && "revision", asset.state && "state", asset.animation && "animation", asset.mirror && "mirror", asset.batch && "batch"].filter(Boolean);
   if (shapes.length > 1) {
     context.addIssue({
       code: z.ZodIssueCode.custom,
@@ -1592,13 +1662,24 @@ var LockEntrySchema = z.object({
     numColors: z.number().int().min(2).max(256).optional(),
     paletteImageSha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
     dithering: RevisionDitheringSchema.optional(),
-    ditheringStrength: z.number().min(0).max(10).optional()
+    ditheringStrength: z.number().min(0).max(10).optional(),
+    frames: z.number().int().min(4).max(40).optional(),
+    fps: z.number().int().min(1).max(60).optional(),
+    lastFrameSha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    direction: CharacterDirectionSchema.optional(),
+    enhancePrompt: z.boolean().optional()
   }).strict().nullable().default(null),
   /** For a mirror: the asset it flips and a hash over that asset's output hashes when this was made. */
   mirror: z.object({
     sourceAssetId: z.string().min(1),
     sourceSha256: z.string().regex(/^[0-9a-f]{64}$/)
   }).strict().nullable().default(null),
+  /** For a `1dir` batch member: which leader and slot it rode along on. */
+  batch: z.object({
+    role: z.enum(["leader", "member"]),
+    leaderAssetId: z.string().min(1).optional(),
+    index: z.number().int().min(1).optional()
+  }).strict().nullable().default(null),
   /**
    * Output hashes owned by the previous generation while its replacement is
    * pending. They authorize replacing only unchanged PixelKiln-owned files.
@@ -4667,8 +4748,16 @@ var ComfyUIProvider = class _ComfyUIProvider {
   supports(generator) {
     return generator === "map" || generator === "frames";
   }
-  supportsRevision(_mode) {
-    return true;
+  /**
+   * Everything else resolves generically to whatever the user's own
+   * workflow does with `bindings.sourceImage`. `animate`/`animate-pixminimax`
+   * are the one exception: they produce an ordered frame set, and this
+   * adapter's revision path always writes a single output image (see
+   * `submit`/`fetch` below) — a real structural gap, not a missing binding,
+   * so it is rejected here rather than only failing once `validate` runs.
+   */
+  supportsRevision(mode2) {
+    return mode2 !== "animate" && mode2 !== "animate-pixminimax";
   }
   estimate(spec) {
     return {
@@ -6153,14 +6242,15 @@ var PixelLabClient = class {
   /**
    * `/reduce-colors`, PixelLab's "Cleanup" tier: quantize one image onto a
    * smaller palette, synchronously — no `background_job_id`, the result
-   * comes back in this same response, like `createImagePixflux`. Verified
-   * against the live OpenAPI schema, not exercised against a live account:
-   * the schema's own response example is `usage: {type: "usd", usd: 0.02}`,
-   * which — going by this codebase's own repeated experience with PixelLab's
-   * documented-vs-billed cost mismatches (`isometricTile`, `objectPro`) —
-   * should not be trusted over a real call. `numColors` and `paletteImage`
-   * are mutually exclusive upstream; the manifest schema already enforces
-   * that before this is ever called.
+   * comes back in this same response, like `createImagePixflux`. The
+   * schema's own response example is dollar-denominated (`usage: {type:
+   * "usd", usd: 0.02}`), which — matching this codebase's repeated
+   * experience with PixelLab's documented-vs-billed cost mismatches
+   * (`isometricTile`, `objectPro`) — did not hold: confirmed live against a
+   * Tier 2 account at exactly 0.1 generations for a 32x32 source
+   * (docs/REVISIONS.md). `numColors` and `paletteImage` are mutually
+   * exclusive upstream; the manifest schema already enforces that before
+   * this is ever called.
    */
   async reduceColors(args) {
     const body = { images: [args.image] };
@@ -6183,8 +6273,9 @@ var PixelLabClient = class {
   /**
    * `/correct-pixelart`, PixelLab's "Cleanup" tier: sharpen edges and drop
    * stray pixels without resizing, synchronously — same shape as
-   * `reduceColors` above, no background job. Cost is likewise unverified
-   * against a live account (schema example: `usage: {type: "usd", usd: 0.02}`).
+   * `reduceColors` above, no background job. Cost is likewise confirmed
+   * live at 0.1 generations for a 32x32 source, not the schema's own
+   * dollar-denominated example (`usage: {type: "usd", usd: 0.02}`).
    */
   async correctPixelart(args) {
     const body = { images: [args.image] };
@@ -6196,6 +6287,50 @@ var PixelLabClient = class {
     );
     return { png: Buffer.from(res.images[0].base64, "base64"), usage: res.usage };
   }
+  /**
+   * `/animate-with-text-v3`: animate a loose image from a text description,
+   * no PixelLab character/object resource required — unlike `animateCharacter`
+   * / `animateObject`, `firstFrame` is whatever bytes the caller has on hand.
+   * A plain background job, like every other PixelLab async submission;
+   * unlike `inpaintV3`/`editImagesV2`, its completed shape has not been
+   * exercised against a live account (request/response fields here come from
+   * the live OpenAPI document, not an observed call — `pollAnimateRevision`
+   * in pixellab.ts checks several plausible field names for the frame list
+   * defensively, the same as `pollRevision` already does for image edits).
+   */
+  async animateWithTextV3(args) {
+    const body = { first_frame: args.firstFrame, action: args.action };
+    if (args.lastFrame) body.last_frame = args.lastFrame;
+    if (args.frameCount != null) body.frame_count = args.frameCount;
+    if (args.seed != null) body.seed = args.seed;
+    if (args.noBackground != null) body.no_background = args.noBackground;
+    if (args.enhancePrompt != null) body.enhance_prompt = args.enhancePrompt;
+    return validateResponse(
+      RevisionJobSubmitSchema,
+      await this.request("/animate-with-text-v3", { method: "POST", body: JSON.stringify(body) }),
+      "animate-with-text-v3"
+    );
+  }
+  /**
+   * `/animate-pixminimax`, beta (tier 1 subscription or higher): PixMiniMax's
+   * richer take on the same idea — `direction` and `enhancePrompt` steer
+   * facing for aimed motions. Same unverified-completed-shape caveat as
+   * `animateWithTextV3` above.
+   */
+  async animatePixminimax(args) {
+    const body = { first_frame: args.firstFrame, description: args.description };
+    if (args.lastFrame) body.last_frame = args.lastFrame;
+    if (args.frameCount != null) body.frame_count = args.frameCount;
+    if (args.seed != null) body.seed = args.seed;
+    if (args.noBackground != null) body.no_background = args.noBackground;
+    if (args.enhancePrompt != null) body.enhance_prompt = args.enhancePrompt;
+    if (args.direction) body.direction = args.direction;
+    return validateResponse(
+      RevisionJobSubmitSchema,
+      await this.request("/animate-pixminimax", { method: "POST", body: JSON.stringify(body) }),
+      "animate-pixminimax"
+    );
+  }
   async getBackgroundJob(jobId) {
     const raw = await this.request(`/background-jobs/${encodeURIComponent(jobId)}`);
     return validateResponse(BackgroundJobSchema, raw, "background-jobs/{id}");
@@ -6378,12 +6513,15 @@ var PixelLabProvider = class _PixelLabProvider {
    * no mask) both exist on PixelLab, and so do `reduce-colors`
    * (`/reduce-colors`) and `correct-pixelart` (`/correct-pixelart`) — PixelLab's
    * "Cleanup" tier, a mechanical post-process on the source's own pixels
-   * rather than a described edit. `outpaint` does not: there is no
-   * canvas-expansion endpoint in the API, matching docs/REVISIONS.md's note
-   * that no provider ships a tested outpaint path yet.
+   * rather than a described edit — and `animate`/`animate-pixminimax`
+   * (`/animate-with-text-v3`, `/animate-pixminimax`), which animate any loose
+   * image from a text description with no character/object resource
+   * required. `outpaint` does not: there is no canvas-expansion endpoint in
+   * the API, matching docs/REVISIONS.md's note that no provider ships a
+   * tested outpaint path yet.
    */
   supportsRevision(mode2) {
-    return mode2 === "inpaint" || mode2 === "image-to-image" || mode2 === "reduce-colors" || mode2 === "correct-pixelart";
+    return mode2 === "inpaint" || mode2 === "image-to-image" || mode2 === "reduce-colors" || mode2 === "correct-pixelart" || mode2 === "animate" || mode2 === "animate-pixminimax";
   }
   /** PixelLab's own constraints: submissions must be >2s apart, and
    *  background jobs in flight are capped by subscription tier (Tier 1=8,
@@ -6405,9 +6543,19 @@ var PixelLabProvider = class _PixelLabProvider {
     return dir;
   }
   estimate(spec) {
+    if (spec.batch?.role === "member") {
+      return { unit: "generations", amount: 0, candidates: 1 };
+    }
     if (spec.revision?.mode === "reduce-colors" || spec.revision?.mode === "correct-pixelart") {
       return { unit: "generations", amount: 0.1, candidates: 1 };
     }
+    if (spec.revision?.mode === "animate" || spec.revision?.mode === "animate-pixminimax") {
+      const width = spec.revision.sourceWidth ?? spec.width;
+      const height = spec.revision.sourceHeight ?? spec.height;
+      const frames = spec.revision.frames ?? 8;
+      const base = Math.max(1, Math.ceil(width * height * frames / 65536));
+      return { unit: "generations", amount: spec.revision.enhancePrompt ? base + 0.05 : base, candidates: 1 };
+    }
     if (spec.revision) {
       const width = spec.revision.sourceWidth ?? spec.width;
       const height = spec.revision.sourceHeight ?? spec.height;
@@ -6449,6 +6597,20 @@ var PixelLabProvider = class _PixelLabProvider {
         throw new Error(`PixelLab correct-pixelart source is ${width}x${height}; the API takes at most 1024 pixels per side`);
       }
     }
+    if (spec.revision?.mode === "animate" || spec.revision?.mode === "animate-pixminimax") {
+      const { sourceWidth: width, sourceHeight: height, mode: mode2, frames, lastFrameWidth, lastFrameHeight } = spec.revision;
+      if (width != null && height != null && (width > 256 || height > 256)) {
+        throw new Error(`PixelLab ${mode2} source is ${width}x${height}; the API takes at most 256 pixels per side`);
+      }
+      if (mode2 === "animate" && frames != null && frames > 16) {
+        throw new Error(`PixelLab animate takes 4 to 16 frames; ${frames} is too many (use animate-pixminimax for up to 40)`);
+      }
+      if (lastFrameWidth != null && lastFrameHeight != null && width != null && height != null && (lastFrameWidth !== width || lastFrameHeight !== height)) {
+        throw new Error(
+          `PixelLab ${mode2} lastFrame is ${lastFrameWidth}x${lastFrameHeight}; source is ${width}x${height} \u2014 they must match`
+        );
+      }
+    }
     if (spec.generator === "1dir" && (spec.width < 32 || spec.width > 256)) {
       throw new Error("PixelLab 1dir dimensions must be between 32 and 256 pixels");
     }
@@ -7182,11 +7344,21 @@ var PixelLabProvider = class _PixelLabProvider {
       return { jobId: res2.background_job_id };
     }
     if (spec.generator === "1dir") {
+      if (spec.batch?.role === "member") {
+        throw new Error(`${spec.styleId}/${spec.assetId}: a batch member cannot submit on its own`);
+      }
       const res2 = await this.client.create1Direction({
         description: spec.prompt,
         size: spec.size,
         view: spec.view === "sidescroller" ? "sidescroller" : "top-down",
-        styleImages
+        styleImages,
+        // The leader's own subject is item_descriptions[0], so `description`
+        // matches it exactly. Confirmed live: item_descriptions[0] owns
+        // candidate slot 0 (a 3-item batch returned exactly the declared
+        // items at frames 0/1/2, in order; docs/GENERATORS.md#1dir), so
+        // sending the same text as `description` too is redundant but
+        // harmless, not a hedge against ambiguity.
+        itemDescriptions: spec.batch?.role === "leader" ? spec.batch.itemDescriptions : void 0
       });
       return { jobId: res2.object_id, metadata: { backgroundJobId: res2.background_job_id } };
     }
@@ -7270,6 +7442,42 @@ var PixelLabProvider = class _PixelLabProvider {
       writeFileSync(path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), res2.png);
       return { jobId, metadata: { revisionUsage: res2.usage } };
     }
+    if (revision.mode === "animate" || revision.mode === "animate-pixminimax") {
+      let lastFrame;
+      if (revision.lastFrameFile) {
+        if (!revision.lastFrameSha256 || !revision.lastFrameFormat) {
+          throw new Error(`${spec.styleId}/${spec.assetId}: revision last frame is not ready`);
+        }
+        const lastFrameBytes = readFileSync2(revision.lastFrameFile);
+        if (sha256(lastFrameBytes) !== revision.lastFrameSha256) {
+          throw new Error(`${spec.styleId}/${spec.assetId}: revision last frame changed after the manifest was resolved`);
+        }
+        lastFrame = { base64: lastFrameBytes.toString("base64"), format: revision.lastFrameFormat };
+      }
+      if (revision.mode === "animate") {
+        const res3 = await this.client.animateWithTextV3({
+          firstFrame: image,
+          lastFrame,
+          action: spec.prompt,
+          frameCount: revision.frames,
+          seed: spec.seed,
+          noBackground: spec.noBackground,
+          enhancePrompt: revision.enhancePrompt
+        });
+        return { jobId: res3.background_job_id };
+      }
+      const res2 = await this.client.animatePixminimax({
+        firstFrame: image,
+        lastFrame,
+        description: spec.prompt,
+        frameCount: revision.frames,
+        seed: spec.seed,
+        noBackground: spec.noBackground,
+        enhancePrompt: revision.enhancePrompt,
+        direction: revision.direction
+      });
+      return { jobId: res2.background_job_id };
+    }
     if (revision.strength != null) {
       throw new Error(
         `${spec.styleId}/${spec.assetId}: PixelLab image-to-image revisions take no strength; edit-images-v2 always applies the full instruction`
@@ -7305,6 +7513,9 @@ var PixelLabProvider = class _PixelLabProvider {
     if (revisionMode === "reduce-colors" || revisionMode === "correct-pixelart") {
       return this.pollCachedRevision(jobId, context);
     }
+    if (revisionMode === "animate" || revisionMode === "animate-pixminimax") {
+      return this.pollAnimateRevision(jobId, context);
+    }
     if (context?.spec?.revision) return this.pollRevision(jobId);
     if (generator === "pixflux") {
       const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
@@ -7361,6 +7572,71 @@ var PixelLabProvider = class _PixelLabProvider {
     const usage = context?.metadata?.revisionUsage;
     return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed: billedFromUsage(usage) };
   }
+  /**
+   * `animate`/`animate-pixminimax` revisions: a plain background job, like
+   * `pollRevision` above, but completing with an ORDERED FRAME LIST instead
+   * of a single image — the same `review-set` shape `pollCharacterAnimation`
+   * returns, minus any character/object resource to look the result up on
+   * (there is none; this operates on a loose image). Unlike every other
+   * PixelLab call this adapter makes, the completed shape for
+   * `/animate-with-text-v3`/`/animate-pixminimax` has never been exercised
+   * against a live account — the checks below are an informed guess (hosted
+   * URLs under a plausible key name, the same `storage_urls.frames` shape
+   * character animations use, or inline base64 per frame, decoded to a local
+   * cache file the same way `pollRevision`'s single-image case already is)
+   * rather than an observed shape, and fail loudly, naming the keys actually
+   * received, for whatever the real shape turns out to be.
+   */
+  async pollAnimateRevision(jobId, context) {
+    const job = await this.client.getBackgroundJob(jobId);
+    if (job.status === "failed") return { status: "failed", error: "animation job failed upstream" };
+    if (job.status !== "completed") return { status: "processing" };
+    const billed = billedFromUsage(job.usage);
+    const done = job.last_response ?? {};
+    const fps = context?.spec?.revision?.fps ?? 8;
+    const review = (frameUrls) => ({
+      status: "review-set",
+      objectId: jobId,
+      frameUrls,
+      sources: frameUrls.map((url, index) => ({ url, role: `frame-${String(index).padStart(2, "0")}` })),
+      fps,
+      metadata: { frameSet: { fps, count: frameUrls.length } },
+      billed
+    });
+    for (const key of ["frame_urls", "frames", "images"]) {
+      const list = done[key];
+      if (!Array.isArray(list) || !list.length) continue;
+      const urls = [];
+      for (const [index, item] of list.entries()) {
+        if (typeof item === "string" && item) {
+          urls.push(item);
+          continue;
+        }
+        const url = item?.url;
+        if (typeof url === "string" && url) {
+          urls.push(url);
+          continue;
+        }
+        const base64 = extractBase64(item);
+        if (base64) {
+          const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+          writeFileSync(file, Buffer.from(base64, "base64"));
+          urls.push(`file://${file}`);
+          continue;
+        }
+        break;
+      }
+      if (urls.length === list.length) return review(urls);
+    }
+    const storageFrames = done.storage_urls?.frames;
+    if (Array.isArray(storageFrames) && storageFrames.length && storageFrames.every((f) => typeof f === "string")) {
+      return review(storageFrames);
+    }
+    return {
+      status: "failed",
+      error: `Invalid PixelLab response for animate job ${jobId}: completed with no recognized frame list (got: ${Object.keys(done).join(", ") || "no keys"}); update pollAnimateRevision in src/providers/pixellab.ts with the real shape`
+    };
+  }
   /**
    * `/inpaint-v3` and `/edit-images-v2` both hand back a plain background
    * job with no resource of its own, polled generically at
@@ -9101,6 +9377,14 @@ async function resolveSpecs(loaded, filter) {
       };
       styleSpecs.set(assetId, resolved);
     }
+    const batchMembersByLeader = /* @__PURE__ */ new Map();
+    for (const id of styleSpecs.keys()) {
+      const batch = manifest.assets[id].batch;
+      if (!batch) continue;
+      const members = batchMembersByLeader.get(batch.of) ?? [];
+      members.push({ id, index: batch.index });
+      batchMembersByLeader.set(batch.of, members);
+    }
     const finalized = /* @__PURE__ */ new Set();
     const finalize = async (assetId) => {
       const resolved = styleSpecs.get(assetId);
@@ -9217,6 +9501,8 @@ async function resolveSpecs(loaded, filter) {
         }
         const paletteImageFile = asset.revision.paletteImage ? path13.resolve(root, asset.revision.paletteImage) : void 0;
         const paletteImage = paletteImageFile ? await optionalRevisionImage(paletteImageFile, "revision palette image", "png") : null;
+        const lastFrameFile = asset.revision.lastFrame ? path13.resolve(root, asset.revision.lastFrame) : void 0;
+        const lastFrame = lastFrameFile ? await optionalRevisionImage(lastFrameFile, "revision last frame") : null;
         resolved.revision = {
           mode: asset.revision.mode,
           sourceAssetId: asset.revision.from,
@@ -9243,9 +9529,70 @@ async function resolveSpecs(loaded, filter) {
             paletteImageFormat: paletteImage?.format ?? null
           } : {},
           ...asset.revision.dithering ? { dithering: asset.revision.dithering } : {},
-          ...asset.revision.ditheringStrength == null ? {} : { ditheringStrength: asset.revision.ditheringStrength }
+          ...asset.revision.ditheringStrength == null ? {} : { ditheringStrength: asset.revision.ditheringStrength },
+          ...asset.revision.frames == null ? {} : { frames: asset.revision.frames },
+          ...asset.revision.fps == null ? {} : { fps: asset.revision.fps },
+          ...lastFrameFile ? {
+            lastFrameFile,
+            lastFrameSha256: lastFrame?.hash ?? null,
+            lastFrameWidth: lastFrame?.width ?? null,
+            lastFrameHeight: lastFrame?.height ?? null,
+            lastFrameFormat: lastFrame?.format ?? null
+          } : {},
+          ...asset.revision.direction ? { direction: asset.revision.direction } : {},
+          ...asset.revision.enhancePrompt == null ? {} : { enhancePrompt: asset.revision.enhancePrompt }
         };
       }
+      if (asset.batch) {
+        if (asset.batch.of === assetId) throw new Error(`assets.${assetId}: a batch cannot name itself as its own leader`);
+        const leaderSpec = await finalize(asset.batch.of);
+        if (!leaderSpec.batch || leaderSpec.batch.role !== "leader") {
+          throw new Error(`assets.${assetId}: ${asset.batch.of} is not a 1dir batch leader`);
+        }
+        if (resolved.size !== leaderSpec.size) {
+          throw new Error(
+            `assets.${assetId}: batch members share the leader's canvas size; ${asset.batch.of} is ${leaderSpec.size}px, this is ${resolved.size}px`
+          );
+        }
+        resolved.batch = {
+          role: "member",
+          itemDescriptions: leaderSpec.batch.itemDescriptions,
+          index: asset.batch.index,
+          leaderAssetId: asset.batch.of,
+          leaderSpec
+        };
+      } else {
+        const members = batchMembersByLeader.get(assetId);
+        if (members) {
+          if (style.generator !== "1dir") {
+            throw new Error(`assets.${assetId}: only a 1dir asset can lead a batch`);
+          }
+          const sorted = [...members].sort((a, b) => a.index - b.index);
+          const seen = /* @__PURE__ */ new Set();
+          for (const { index } of sorted) {
+            if (seen.has(index)) throw new Error(`assets.${assetId}: two batch members both claim index ${index}`);
+            seen.add(index);
+          }
+          const expectedIndices = sorted.map((_, i) => i + 1).join(",");
+          if (sorted.map((m) => m.index).join(",") !== expectedIndices) {
+            throw new Error(
+              `assets.${assetId}: batch member indices must be 1..${sorted.length} with no gaps; got ${sorted.map((m) => m.index).join(",")}`
+            );
+          }
+          const total = 1 + sorted.length;
+          const limit = candidateCount(resolved.size);
+          if (total > limit) {
+            throw new Error(
+              `assets.${assetId}: a ${resolved.size}px batch holds at most ${limit} items (1 leader + ${limit - 1} members); this one declares ${total}`
+            );
+          }
+          resolved.batch = {
+            role: "leader",
+            itemDescriptions: [resolved.prompt, ...sorted.map(({ id }) => styleSpecs.get(id).prompt)],
+            memberAssetIds: sorted.map((m) => m.id)
+          };
+        }
+      }
       resolved.specHash = specHash(
         resolved,
         styleImageHashes,
@@ -13513,6 +13860,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
   for (const styleId of new Set(items.map((i) => i.spec.styleId))) {
     styleImages.set(styleId, await resolveStyleImages(loaded, styleId));
   }
+  const byKey = new Map(items.map((item) => [item.key, item]));
   let submitted = 0;
   let failed = 0;
   let spent = 0;
@@ -13542,8 +13890,62 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       await pruneInFlight();
     }
   }
+  function writeBatchMembers(leaderSpec, leaderKey, error) {
+    if (leaderSpec.batch?.role !== "leader") return;
+    const leaderEntry = lock.entries[leaderKey];
+    for (const memberAssetId of leaderSpec.batch.memberAssetIds ?? []) {
+      const memberKey = lockKey(leaderSpec.styleId, memberAssetId);
+      const memberItem = byKey.get(memberKey);
+      if (!memberItem) {
+        throw new Error(
+          `${leaderKey}: batch member "${memberAssetId}" must be submitted in the same run as its leader; run without --only, or include every sibling`
+        );
+      }
+      const memberSpec = memberItem.spec;
+      const memberEstimate = estimates.get(memberKey);
+      const previousMemberEntry = lock.entries[memberKey];
+      const memberSubmittedAt = leaderEntry.submittedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+      upsert(lock, memberKey, {
+        styleId: memberSpec.styleId,
+        assetId: memberSpec.assetId,
+        specHash: memberSpec.specHash,
+        generator: memberSpec.generator,
+        prompt: memberSpec.prompt,
+        width: memberSpec.width,
+        height: memberSpec.height,
+        batch: { role: "member", leaderAssetId: leaderSpec.assetId, index: memberSpec.batch.index },
+        status: error ? "failed" : "processing",
+        error,
+        jobId: error ? null : leaderEntry.jobId,
+        submissionComplete: error ? void 0 : true,
+        reviewObjectId: error ? null : leaderEntry.reviewObjectId,
+        objectId: null,
+        candidateIndex: null,
+        outputs: [],
+        supersededOutputs: previousMemberEntry?.outputs.length ? previousMemberEntry.outputs : previousMemberEntry?.supersededOutputs ?? [],
+        providerMetadata: leaderEntry.providerMetadata,
+        sourceUrl: null,
+        sourceUrls: [],
+        submittedAt: memberSubmittedAt,
+        history: historyAfterReplacing(previousMemberEntry, historyLimit(loaded.manifest), memberSubmittedAt),
+        cost: memberEstimate.amount,
+        costUnit: memberEstimate.unit,
+        provider: provider.id,
+        downloadedAt: null
+      });
+      if (error) failed++;
+      else {
+        submitted++;
+        spent += memberEstimate.amount;
+        log2(`  ${memberKey} \u2192 ${leaderEntry.jobId}  (rides on ${leaderKey}'s batch)`);
+      }
+    }
+  }
   for (const { spec, key } of items) {
     const estimate = estimates.get(key);
+    if (spec.batch?.role === "member") {
+      continue;
+    }
     if (spec.mirror) {
       try {
         await requireRevisionReady(spec, lock);
@@ -13576,6 +13978,14 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
     const since = Date.now() - lastSubmitAt;
     if (since < spacing) await sleep2(spacing - since);
     await requireRevisionReady(spec, lock);
+    if (spec.batch?.role === "leader") {
+      const missing = (spec.batch.memberAssetIds ?? []).filter((id) => !byKey.has(lockKey(spec.styleId, id)));
+      if (missing.length) {
+        throw new Error(
+          `${key}: batch member(s) ${missing.join(", ")} must be submitted in the same run as this leader; run without --only, or include every sibling`
+        );
+      }
+    }
     const previousEntry = lock.entries[key];
     const resumesCheckpoint = Boolean(
       previousEntry?.specHash === spec.specHash && previousEntry.provider === provider.id && previousEntry.generator === spec.generator && previousEntry.submissionComplete === false && previousEntry.jobId
@@ -13603,7 +14013,12 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         ...spec.revision.numColors == null ? {} : { numColors: spec.revision.numColors },
         ...spec.revision.paletteImageSha256 ? { paletteImageSha256: spec.revision.paletteImageSha256 } : {},
         ...spec.revision.dithering ? { dithering: spec.revision.dithering } : {},
-        ...spec.revision.ditheringStrength == null ? {} : { ditheringStrength: spec.revision.ditheringStrength }
+        ...spec.revision.ditheringStrength == null ? {} : { ditheringStrength: spec.revision.ditheringStrength },
+        ...spec.revision.frames == null ? {} : { frames: spec.revision.frames },
+        ...spec.revision.fps == null ? {} : { fps: spec.revision.fps },
+        ...spec.revision.lastFrameSha256 ? { lastFrameSha256: spec.revision.lastFrameSha256 } : {},
+        ...spec.revision.direction ? { direction: spec.revision.direction } : {},
+        ...spec.revision.enhancePrompt == null ? {} : { enhancePrompt: spec.revision.enhancePrompt }
       } : null,
       status: "pending",
       jobId: previousJobId ?? null,
@@ -13676,6 +14091,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       inFlight.set(jobId, spec);
       submitted++;
       spent += estimate.amount;
+      writeBatchMembers(spec, key, null);
       log2(
         `  ${key} \u2192 ${jobId}  (${spec.width}x${spec.height}` + (estimate.candidates > 1 ? `, ${estimate.candidates} ${spec.tileFeature ? "outputs" : "candidates"}` : "") + `, ${estimate.amount})`
       );
@@ -13687,6 +14103,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         inFlight.set(entry.jobId, spec);
         submitted++;
         spent += estimate.amount;
+        writeBatchMembers(spec, key, null);
         log2(`  ${key} \u2192 ${entry.jobId}  (recovered from completed checkpoint)`);
       } else {
         failed++;
@@ -13695,6 +14112,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
           error: message6,
           cost: entry.jobId ? estimate.amount : 0
         });
+        writeBatchMembers(spec, key, message6);
         log2(`  FAILED ${key}: ${message6}`);
       }
     }
@@ -13895,6 +14313,9 @@ function renderSheet(groups, options = {}) {
   .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.recommended:not(.sel) { border-color:var(--accent); }
+  .cand.recommended .badge { position:absolute; top:-1px; left:-1px; font-size:9.5px; font-weight:650;
+    text-transform:uppercase; letter-spacing:.03em; color:var(--bg); background:var(--accent); padding:1px 5px; }
   .cand img { image-rendering:pixelated; display:block;
     background-image:
       linear-gradient(45deg,#0000 25%,#7f7f7f22 25%,#7f7f7f22 75%,#0000 75%),
@@ -14052,14 +14473,17 @@ GROUPS.forEach((g, gi) => {
       }).observe(loop);
     }
   }
+  const recommended = g.recommendedIndex ?? 0;
   g.frameUrls.forEach((url, i) => {
     const c = document.createElement('button');
     c.type = 'button';
-    c.className = 'cand' + (g.mode === 'frame-set' ? ' set-frame' : '');
+    c.className = 'cand' + (g.mode === 'frame-set' ? ' set-frame' : '') +
+      (g.recommendedIndex != null && i === recommended ? ' recommended' : '');
     c.tabIndex = -1;
-    c.setAttribute('aria-label', g.mode === 'frame-set'
+    c.setAttribute('aria-label', (g.mode === 'frame-set'
       ? 'Accept ordered frame set from frame ' + (i + 1)
-      : 'Choose candidate ' + (i + 1) + ' of ' + g.frameUrls.length);
+      : 'Choose candidate ' + (i + 1) + ' of ' + g.frameUrls.length) +
+      (g.recommendedIndex != null && i === recommended ? ' (this asset\u2019s declared slot)' : ''));
 
     const preview = document.createElement('img');
     preview.className = 'preview';
@@ -14072,6 +14496,12 @@ GROUPS.forEach((g, gi) => {
     index.textContent = (g.frameLabels?.[i] || String(i + 1)) + ' \xB7 ' +
       g.width + '\xD7' + g.height + ' \xB7 ' + scaleLabel;
     c.append(preview, index);
+    if (g.recommendedIndex != null && i === recommended) {
+      const badge = document.createElement('span');
+      badge.className = 'badge';
+      badge.textContent = 'declared';
+      c.append(badge);
+    }
     if (displayScale > 1 && largestSide <= 96) {
       const actual = document.createElement('img');
       actual.className = 'actual';
@@ -14096,6 +14526,7 @@ GROUPS.forEach((g, gi) => {
   });
   frames.dataset.active = '0';
   frames.querySelector('.cand')?.classList.add('active');
+  if (recommended > 0) activate(recommended, frames);
   root.appendChild(el);
 });
 
@@ -14270,7 +14701,11 @@ async function prepareReview(provider, lock, opts = {}) {
             height: spec.revision.sourceHeight
           }
         } : {},
-        ...current && currentRoute ? { current: { url: currentRoute, width: current.width, height: current.height } } : {}
+        ...current && currentRoute ? { current: { url: currentRoute, width: current.width, height: current.height } } : {},
+        // A batch member's declared slot in the shared candidate set — the
+        // leader's own slot 0 is already the sheet's ordinary default, so
+        // only a member (whose slot is 1+) needs to say so explicitly.
+        ...entry.batch?.index != null ? { recommendedIndex: entry.batch.index } : {}
       });
     } catch (err) {
       log2(`  could not load candidates for ${key}: ${err instanceof Error ? err.message : String(err)}`);