pixelkiln 0.56.0 → 0.57.0

package/dist/cli.js

@@ -708,7 +708,11 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         from: spec.revision.sourceAssetId,
         sourceSha256: spec.revision.sourceSha256,
         maskSha256: spec.revision.maskSha256,
-        strength: spec.revision.strength
+        strength: spec.revision.strength,
+        numColors: spec.revision.numColors,
+        paletteImageSha256: spec.revision.paletteImageSha256,
+        dithering: spec.revision.dithering,
+        ditheringStrength: spec.revision.ditheringStrength
       } : void 0
     })
   );
@@ -728,7 +732,7 @@ 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"]);
+var RevisionModeSchema = z.enum(["image-to-image", "inpaint", "outpaint", "reduce-colors", "correct-pixelart"]);
 function tileVariationCount(descriptions) {
   return Math.max(1, descriptions) * 4;
 }
@@ -922,6 +926,7 @@ var CharacterAnimationSchema = z.object({
     context.addIssue({ code: z.ZodIssueCode.custom, message: "template mode needs a template", path: ["template"] });
   }
 });
+var RevisionDitheringSchema = z.enum(["none", "2x2", "4x4", "8x8"]);
 var RevisionSchema = z.object({
   /** What kind of controlled change the provider workflow performs. */
   mode: RevisionModeSchema,
@@ -930,7 +935,15 @@ var RevisionSchema = z.object({
   /** Manifest-relative black/white PNG. Required only for masked inpainting. */
   mask: z.string().min(1).optional(),
   /** Provider-neutral edit strength. The active adapter must bind it explicitly. */
-  strength: z.number().min(0).max(1).optional()
+  strength: z.number().min(0).max(1).optional(),
+  /** `reduce-colors` only: target color count. Mutually exclusive with `paletteImage`. */
+  numColors: z.number().int().min(2).max(256).optional(),
+  /** `reduce-colors` only: manifest-relative image whose colors become the palette. Mutually exclusive with `numColors`. */
+  paletteImage: z.string().min(1).optional(),
+  /** `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()
 }).strict().superRefine((revision, context) => {
   if (revision.mode === "inpaint" && !revision.mask) {
     context.addIssue({
@@ -946,6 +959,29 @@ var RevisionSchema = z.object({
       path: ["mask"]
     });
   }
+  if (revision.numColors !== void 0 && revision.paletteImage !== void 0) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "numColors and paletteImage are mutually exclusive",
+      path: ["numColors"]
+    });
+  }
+  for (const field of ["numColors", "paletteImage", "dithering", "ditheringStrength"]) {
+    if (revision[field] !== void 0 && revision.mode !== "reduce-colors") {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${field} applies to reduce-colors revisions only`,
+        path: [field]
+      });
+    }
+  }
+  if (revision.strength !== void 0 && revision.mode === "reduce-colors") {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "reduce-colors revisions do not take a strength; use dithering/ditheringStrength",
+      path: ["strength"]
+    });
+  }
 });
 var StyleObjectSchema = z.object({
   /** Generation backend for this style. Omit to inherit the manifest default. */
@@ -1552,7 +1588,11 @@ var LockEntrySchema = z.object({
     sourceAssetId: z.string().min(1),
     sourceSha256: z.string().regex(/^[0-9a-f]{64}$/),
     maskSha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
-    strength: z.number().min(0).max(1).optional()
+    strength: z.number().min(0).max(1).optional(),
+    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()
   }).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({
@@ -4690,6 +4730,11 @@ var ComfyUIProvider = class _ComfyUIProvider {
       if (spec.revision.strength != null && !options.bindings.strength) {
         throw new Error("ComfyUI revision strength requires bindings.strength");
       }
+      if (spec.revision.numColors != null || spec.revision.paletteImageFile || spec.revision.dithering) {
+        throw new Error(
+          "ComfyUI has no binding for numColors/paletteImage/dithering \u2014 those are PixelLab's /reduce-colors parameters. A reduce-colors revision on ComfyUI is whatever your own workflow does with bindings.sourceImage; write that behavior into the graph directly."
+        );
+      }
       if ((!options.bindings.width || !options.bindings.height) && spec.revision.sourceWidth != null && spec.revision.sourceHeight != null && (spec.width !== spec.revision.sourceWidth || spec.height !== spec.revision.sourceHeight)) {
         throw new Error(
           "ComfyUI revisions without width/height bindings must keep the source dimensions"
@@ -5388,6 +5433,16 @@ var MapObjectSchema = z2.object({
 }).passthrough();
 var ObjectListSchema = z2.object({ objects: z2.array(PixelLabObjectSchema), total: z2.number().int().min(0) }).passthrough();
 var PixfluxResponseSchema = z2.object({ image: z2.object({ base64: z2.string().min(1) }).passthrough(), usage: z2.unknown().optional() }).passthrough();
+var ReduceColorsResponseSchema = z2.object({
+  images: z2.array(z2.object({ base64: z2.string().min(1) }).passthrough()).min(1),
+  palette: z2.object({ base64: z2.string().min(1) }).passthrough(),
+  n_colors: z2.number().int(),
+  usage: z2.unknown().optional()
+}).passthrough();
+var CorrectPixelartResponseSchema = z2.object({
+  images: z2.array(z2.object({ base64: z2.string().min(1) }).passthrough()).min(1),
+  usage: z2.unknown().optional()
+}).passthrough();
 var SelectFramesSchema = z2.object({ created_object_ids: z2.array(z2.string()) }).passthrough();
 var CharacterSubmitSchema = z2.object({
   background_job_id: z2.string().min(1),
@@ -6095,6 +6150,52 @@ var PixelLabClient = class {
       "generate-image-v2"
     );
   }
+  /**
+   * `/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.
+   */
+  async reduceColors(args) {
+    const body = { images: [args.image] };
+    if (args.numColors != null) body.num_colors = args.numColors;
+    if (args.paletteImage) body.palette_image = args.paletteImage;
+    if (args.dithering) body.dithering = args.dithering;
+    if (args.ditheringStrength != null) body.dithering_strength = args.ditheringStrength;
+    const res = validateResponse(
+      ReduceColorsResponseSchema,
+      await this.request("/reduce-colors", { method: "POST", body: JSON.stringify(body) }),
+      "reduce-colors"
+    );
+    return {
+      png: Buffer.from(res.images[0].base64, "base64"),
+      paletteStripPng: Buffer.from(res.palette.base64, "base64"),
+      nColors: res.n_colors,
+      usage: res.usage
+    };
+  }
+  /**
+   * `/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}`).
+   */
+  async correctPixelart(args) {
+    const body = { images: [args.image] };
+    if (args.strength != null) body.strength = args.strength;
+    const res = validateResponse(
+      CorrectPixelartResponseSchema,
+      await this.request("/correct-pixelart", { method: "POST", body: JSON.stringify(body) }),
+      "correct-pixelart"
+    );
+    return { png: Buffer.from(res.images[0].base64, "base64"), usage: res.usage };
+  }
   async getBackgroundJob(jobId) {
     const raw = await this.request(`/background-jobs/${encodeURIComponent(jobId)}`);
     return validateResponse(BackgroundJobSchema, raw, "background-jobs/{id}");
@@ -6274,12 +6375,15 @@ var PixelLabProvider = class _PixelLabProvider {
   }
   /**
    * `inpaint` (`/inpaint-v3`, a mask) and `image-to-image` (`/edit-images-v2`,
-   * no mask) both exist on PixelLab. `outpaint` does not: there is no
+   * 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.
    */
   supportsRevision(mode2) {
-    return mode2 === "inpaint" || mode2 === "image-to-image";
+    return mode2 === "inpaint" || mode2 === "image-to-image" || mode2 === "reduce-colors" || mode2 === "correct-pixelart";
   }
   /** PixelLab's own constraints: submissions must be >2s apart, and
    *  background jobs in flight are capped by subscription tier (Tier 1=8,
@@ -6301,6 +6405,9 @@ var PixelLabProvider = class _PixelLabProvider {
     return dir;
   }
   estimate(spec) {
+    if (spec.revision?.mode === "reduce-colors" || spec.revision?.mode === "correct-pixelart") {
+      return { unit: "generations", amount: 0.1, candidates: 1 };
+    }
     if (spec.revision) {
       const width = spec.revision.sourceWidth ?? spec.width;
       const height = spec.revision.sourceHeight ?? spec.height;
@@ -6328,6 +6435,20 @@ var PixelLabProvider = class _PixelLabProvider {
         throw new Error(`PixelLab inpaint source is ${width}x${height}; the API takes 32 to 512 pixels per side`);
       }
     }
+    if (spec.revision?.mode === "reduce-colors") {
+      const { sourceWidth: width, sourceHeight: height } = spec.revision;
+      if (width != null && height != null && width * height > 512 * 512) {
+        throw new Error(
+          `PixelLab reduce-colors source is ${width}x${height} (${width * height}px\xB2); the API takes at most 512x512 worth of pixels per call`
+        );
+      }
+    }
+    if (spec.revision?.mode === "correct-pixelart") {
+      const { sourceWidth: width, sourceHeight: height } = spec.revision;
+      if (width != null && height != null && (width > 1024 || height > 1024)) {
+        throw new Error(`PixelLab correct-pixelart source is ${width}x${height}; the API takes at most 1024 pixels per side`);
+      }
+    }
     if (spec.generator === "1dir" && (spec.width < 32 || spec.width > 256)) {
       throw new Error("PixelLab 1dir dimensions must be between 32 and 256 pixels");
     }
@@ -7120,6 +7241,35 @@ var PixelLabProvider = class _PixelLabProvider {
       });
       return { jobId: res2.background_job_id };
     }
+    if (revision.mode === "reduce-colors") {
+      let paletteImage;
+      if (revision.paletteImageFile) {
+        if (!revision.paletteImageSha256 || !revision.paletteImageFormat) {
+          throw new Error(`${spec.styleId}/${spec.assetId}: revision palette image is not ready`);
+        }
+        const paletteBytes = readFileSync2(revision.paletteImageFile);
+        if (sha256(paletteBytes) !== revision.paletteImageSha256) {
+          throw new Error(`${spec.styleId}/${spec.assetId}: revision palette image changed after the manifest was resolved`);
+        }
+        paletteImage = { base64: paletteBytes.toString("base64"), format: revision.paletteImageFormat };
+      }
+      const res2 = await this.client.reduceColors({
+        image,
+        numColors: revision.numColors,
+        paletteImage,
+        dithering: revision.dithering,
+        ditheringStrength: revision.ditheringStrength
+      });
+      const jobId = randomUUID3();
+      writeFileSync(path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), res2.png);
+      return { jobId, metadata: { revisionUsage: res2.usage } };
+    }
+    if (revision.mode === "correct-pixelart") {
+      const res2 = await this.client.correctPixelart({ image, strength: revision.strength });
+      const jobId = randomUUID3();
+      writeFileSync(path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), res2.png);
+      return { jobId, metadata: { revisionUsage: res2.usage } };
+    }
     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`
@@ -7151,6 +7301,10 @@ var PixelLabProvider = class _PixelLabProvider {
     }
   }
   async poll(jobId, generator, context) {
+    const revisionMode = context?.spec?.revision?.mode;
+    if (revisionMode === "reduce-colors" || revisionMode === "correct-pixelart") {
+      return this.pollCachedRevision(jobId, context);
+    }
     if (context?.spec?.revision) return this.pollRevision(jobId);
     if (generator === "pixflux") {
       const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
@@ -7186,6 +7340,27 @@ var PixelLabProvider = class _PixelLabProvider {
       etaSeconds: obj.eta_seconds ?? null
     };
   }
+  /**
+   * `reduce-colors` and `correct-pixelart` results are already on disk by
+   * the time `poll` is first called — `submitRevision` wrote them
+   * synchronously, the same way `pixflux`'s poll branch above checks its own
+   * cache file rather than a provider resource. The billed amount, if any,
+   * travels through `context.metadata.revisionUsage` since there is no
+   * background job to ask afterwards the way `billedForJob` does for async
+   * work.
+   */
+  async pollCachedRevision(jobId, context) {
+    const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+    if (!existsSync7(file)) {
+      return {
+        status: "failed",
+        error: "revision result is no longer cached locally; re-run submit for this asset"
+      };
+    }
+    const sourceUrl = `file://${file}`;
+    const usage = context?.metadata?.revisionUsage;
+    return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed: billedFromUsage(usage) };
+  }
   /**
    * `/inpaint-v3` and `/edit-images-v2` both hand back a plain background
    * job with no resource of its own, polled generically at
@@ -9040,6 +9215,8 @@ async function resolveSpecs(loaded, filter) {
             `Revision mask for ${styleId}/${assetId} is ${maskImage.width}x${maskImage.height}; source ${asset.revision.from} is ${sourceImage.width}x${sourceImage.height}`
           );
         }
+        const paletteImageFile = asset.revision.paletteImage ? path13.resolve(root, asset.revision.paletteImage) : void 0;
+        const paletteImage = paletteImageFile ? await optionalRevisionImage(paletteImageFile, "revision palette image", "png") : null;
         resolved.revision = {
           mode: asset.revision.mode,
           sourceAssetId: asset.revision.from,
@@ -9056,7 +9233,17 @@ async function resolveSpecs(loaded, filter) {
             maskHeight: maskImage?.height ?? null,
             maskFormat: maskImage?.format ?? null
           } : {},
-          ...asset.revision.strength == null ? {} : { strength: asset.revision.strength }
+          ...asset.revision.strength == null ? {} : { strength: asset.revision.strength },
+          ...asset.revision.numColors == null ? {} : { numColors: asset.revision.numColors },
+          ...paletteImageFile ? {
+            paletteImageFile,
+            paletteImageSha256: paletteImage?.hash ?? null,
+            paletteImageWidth: paletteImage?.width ?? null,
+            paletteImageHeight: paletteImage?.height ?? null,
+            paletteImageFormat: paletteImage?.format ?? null
+          } : {},
+          ...asset.revision.dithering ? { dithering: asset.revision.dithering } : {},
+          ...asset.revision.ditheringStrength == null ? {} : { ditheringStrength: asset.revision.ditheringStrength }
         };
       }
       resolved.specHash = specHash(
@@ -13412,7 +13599,11 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         sourceAssetId: spec.revision.sourceAssetId,
         sourceSha256: spec.revision.sourceSha256,
         ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {},
-        ...spec.revision.strength == null ? {} : { strength: spec.revision.strength }
+        ...spec.revision.strength == null ? {} : { strength: spec.revision.strength },
+        ...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 }
       } : null,
       status: "pending",
       jobId: previousJobId ?? null,