pixelkiln 0.57.0 → 0.58.0

package/dist/cli.js

@@ -712,7 +712,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 +737,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;
 }
@@ -943,7 +956,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 +1009,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. */
@@ -1592,7 +1645,12 @@ 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({
@@ -4667,8 +4725,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 {
@@ -6196,6 +6262,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 +6488,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,
@@ -6408,6 +6521,13 @@ var PixelLabProvider = class _PixelLabProvider {
     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 +6569,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");
     }
@@ -7270,6 +7404,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 +7475,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 +7534,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
@@ -9217,6 +9455,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,7 +9483,18 @@ 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 }
         };
       }
       resolved.specHash = specHash(
@@ -13603,7 +13854,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,