pixelkiln 0.91.2 → 0.92.0

package/dist/index.js

@@ -2,6 +2,17 @@
 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", "uiAsset", "uiElement", "imageProFlash", "vfx"]);
+var TARGET_PALETTE_GENERATORS = [
+  "imagePro",
+  "imageProFlash",
+  "objectPro",
+  "1dir",
+  "character",
+  "tiles",
+  "terrain",
+  "uiAsset",
+  "uiElement"
+];
 var GridConfidenceSchema = z.enum(["low", "medium", "high"]);
 var RevisionModeSchema = z.enum([
   "image-to-image",
@@ -958,8 +969,8 @@ var StyleObjectSchema = z.object({
   seed: z.number().int().optional(),
   /**
    * Forced palette, as `#rrggbb` values. Sent as a swatch to `pixflux`
-   * and the generators that take one, and to `imagePro` as its
-   * `target_palette.colors` (2 to 256 colours).
+   * and the generators that take one, and as `target_palette.colors` (2 to
+   * 256 colours) to every PixelLab call that takes it (`TARGET_PALETTE_GENERATORS`).
    *
    * Unlike prose, this is a hard constraint. The API is handed a swatch
    * image and the output is limited to those colours. Verified: a four-colour
@@ -969,9 +980,9 @@ var StyleObjectSchema = z.object({
    * chocolate bar.
    */
   palette: z.array(HexColorSchema).default([]),
-  /** `imagePro` only: the palette's name ("Game Boy", "PICO-8"), which PixelLab uses to help the look. Needs `palette`. */
+  /** `target_palette.name` ("Game Boy", "PICO-8"), which PixelLab uses to help the look. Needs `palette`; generators in `TARGET_PALETTE_GENERATORS` only. */
   paletteName: z.string().min(1).max(100).optional(),
-  /** `imagePro` only: at most this many colours in each candidate, 2 to 64 (drawn from `palette` when one is set). */
+  /** `target_palette.max_colors`: at most this many colours in each image, 2 to 64 (drawn from `palette` when one is set). Generators in `TARGET_PALETTE_GENERATORS` only. */
   maxColors: z.number().int().min(2).max(64).optional(),
   /**
    * Snap every visible pixel of the downloaded art to the nearest `palette`
@@ -1027,10 +1038,10 @@ var StyleSchema = StyleObjectSchema.refine((s) => !(s.tileFeature && s.styleImag
     });
   }
   for (const field of ["paletteName", "maxColors"]) {
-    if (style[field] !== void 0 && style.generator !== "imagePro") {
+    if (style[field] !== void 0 && !TARGET_PALETTE_GENERATORS.includes(style.generator)) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `${field} applies to the imagePro generator only`,
+        message: `${field} applies to the ${TARGET_PALETTE_GENERATORS.join(", ")} generators only`,
         path: [field]
       });
     }
@@ -2078,6 +2089,16 @@ function proportionsPayload(proportions) {
     ...proportions.hipWidth !== void 0 ? { hip_width: proportions.hipWidth } : {}
   };
 }
+function targetPaletteBody(palette) {
+  if (!palette || !(palette.colors?.length || palette.maxColors != null)) return {};
+  return {
+    target_palette: {
+      ...palette.colors?.length ? { colors: palette.colors } : {},
+      ...palette.name ? { name: palette.name } : {},
+      ...palette.maxColors != null ? { max_colors: palette.maxColors } : {}
+    }
+  };
+}
 var PixelLabClient = class {
   constructor(apiKey, timeoutMs = 12e4) {
     this.apiKey = apiKey;
@@ -2152,6 +2173,7 @@ var PixelLabClient = class {
     }
     if (args.view) body.view = args.view;
     if (args.itemDescriptions?.length) body.item_descriptions = args.itemDescriptions;
+    Object.assign(body, targetPaletteBody(args.targetPalette));
     const raw = await this.request("/create-1-direction-object", {
       method: "POST",
       body: JSON.stringify(body)
@@ -2219,6 +2241,7 @@ var PixelLabClient = class {
     if (args.outlineMode) body.outline_mode = args.outlineMode;
     if (args.seed != null) body.seed = args.seed;
     if (args.styleImages?.length) body.style_images = args.styleImages;
+    Object.assign(body, targetPaletteBody(args.targetPalette));
     return validateResponse(
       TilesSubmitSchema,
       await this.request("/create-tiles-pro", { method: "POST", body: JSON.stringify(body) }),
@@ -2264,6 +2287,7 @@ var PixelLabClient = class {
     if (args.shading) body.shading = args.shading;
     if (args.detail) body.detail = args.detail;
     if (args.seed != null) body.seed = args.seed;
+    if (args.mode === "pro") Object.assign(body, targetPaletteBody(args.targetPalette));
     return validateResponse(
       TilesetSubmitSchema,
       await this.request("/create-tileset", { method: "POST", body: JSON.stringify(body) }),
@@ -2362,6 +2386,7 @@ var PixelLabClient = class {
     if (args.colorPalette) body.color_palette = args.colorPalette;
     if (args.noBackground != null) body.no_background = args.noBackground;
     if (args.seed != null) body.seed = args.seed;
+    Object.assign(body, targetPaletteBody(args.targetPalette));
     const res = await validateResponse(
       UiAssetSubmitSchema,
       await this.request("/create-ui-asset", { method: "POST", body: JSON.stringify(body) }),
@@ -2441,7 +2466,8 @@ var PixelLabClient = class {
             ...traits.shading !== void 0 ? { shading: traits.shading } : {}
           }
         } : {}
-      } : {}
+      } : {},
+      ...targetPaletteBody(args.targetPalette)
     };
     return validateResponse(
       ObjectProSubmitSchema,
@@ -2456,7 +2482,8 @@ var PixelLabClient = class {
       body: JSON.stringify({
         edit_description: args.editDescription,
         ...args.stateName ? { state_name: args.stateName } : {},
-        ...args.seed != null ? { seed: args.seed } : {}
+        ...args.seed != null ? { seed: args.seed } : {},
+        ...targetPaletteBody(args.targetPalette)
       })
     });
     return validateResponse(ObjectProSubmitSchema, raw, "create object state");
@@ -2482,7 +2509,8 @@ var PixelLabClient = class {
       ...args.startFrame ? { custom_start_frame: encode(args.startFrame) } : {},
       ...args.endFrame ? { end_frame: encode(args.endFrame) } : {},
       ...args.enhancePrompt ? { enhance_prompt: true } : {},
-      ...args.replaceExisting ? { replace_existing: true } : {}
+      ...args.replaceExisting ? { replace_existing: true } : {},
+      ...args.mode === "pro" ? targetPaletteBody(args.targetPalette) : {}
     };
     const raw = await this.request(`/objects/${encodeURIComponent(args.objectId)}/animations`, {
       method: "POST",
@@ -2624,6 +2652,7 @@ var PixelLabClient = class {
         ...palette
       };
     }
+    if (args.mode === "pro" || args.mode === "pro-flash") Object.assign(body, targetPaletteBody(args.targetPalette));
     const raw = await this.request(path39, { method: "POST", body: JSON.stringify(body) });
     return validateResponse(CharacterSubmitSchema, raw, path39.slice(1));
   }
@@ -2638,7 +2667,8 @@ var PixelLabClient = class {
         use_color_palette_from_reference: args.paletteFromReference ?? false,
         ...args.stateName ? { state_name: args.stateName } : {},
         ...args.canvas ? { override_frame_size: args.canvas } : {},
-        ...args.seed != null ? { seed: args.seed } : {}
+        ...args.seed != null ? { seed: args.seed } : {},
+        ...targetPaletteBody(args.targetPalette)
       })
     });
     return validateResponse(CharacterSubmitSchema, raw, "create-character-state");
@@ -2707,7 +2737,8 @@ var PixelLabClient = class {
         image: { type: "base64", base64: args.image.base64, format: args.image.format },
         ...args.view ? { view: args.view } : {},
         ...args.resultSize != null ? { result_size: args.resultSize } : {},
-        ...args.seed != null ? { seed: args.seed } : {}
+        ...args.seed != null ? { seed: args.seed } : {},
+        ...targetPaletteBody(args.targetPalette)
       })
     });
     return validateResponse(PortraitSubmitSchema, raw, "portrait-character-pro");
@@ -2752,7 +2783,8 @@ var PixelLabClient = class {
         image_size: args.imageSize,
         ...args.seed != null ? { seed: args.seed } : {},
         ...args.noBackground !== void 0 ? { no_background: args.noBackground } : {},
-        ...args.additionalInstructions ? { additional_instructions: args.additionalInstructions } : {}
+        ...args.additionalInstructions ? { additional_instructions: args.additionalInstructions } : {},
+        ...targetPaletteBody(args.targetPalette)
       })
     });
     return validateResponse(TransferOutfitSubmitSchema, raw, "transfer-outfit-v2");
@@ -2871,14 +2903,7 @@ var PixelLabClient = class {
     };
     if (args.noBackground != null) body.no_background = args.noBackground;
     if (args.seed != null) body.seed = args.seed;
-    const palette = args.targetPalette;
-    if (palette && (palette.colors?.length || palette.maxColors != null)) {
-      body.target_palette = {
-        ...palette.colors?.length ? { colors: palette.colors } : {},
-        ...palette.name ? { name: palette.name } : {},
-        ...palette.maxColors != null ? { max_colors: palette.maxColors } : {}
-      };
-    }
+    Object.assign(body, targetPaletteBody(args.targetPalette));
     return validateResponse(
       RevisionJobSubmitSchema,
       await this.request("/generate-image-v2", { method: "POST", body: JSON.stringify(body) }),
@@ -2913,6 +2938,7 @@ var PixelLabClient = class {
         };
       }
     }
+    Object.assign(body, targetPaletteBody(args.targetPalette));
     return validateResponse(
       ProFlashImageSubmitSchema,
       await this.request("/create-image-pro-flash", { method: "POST", body: JSON.stringify(body) }),
@@ -2986,6 +3012,7 @@ var PixelLabClient = class {
     if (args.colorPalette) body.color_palette = args.colorPalette;
     if (args.noBackground != null) body.no_background = args.noBackground;
     if (args.seed != null) body.seed = args.seed;
+    Object.assign(body, targetPaletteBody(args.targetPalette));
     return validateResponse(
       RevisionJobSubmitSchema,
       await this.request("/generate-ui-v2", { method: "POST", body: JSON.stringify(body) }),
@@ -3135,6 +3162,7 @@ var PixelLabClient = class {
     };
     if (args.seed != null) body.seed = args.seed;
     if (args.noBackground != null) body.no_background = args.noBackground;
+    Object.assign(body, targetPaletteBody(args.targetPalette));
     return validateResponse(
       RevisionJobSubmitSchema,
       await this.request("/interpolation-v2", { method: "POST", body: JSON.stringify(body) }),
@@ -3157,6 +3185,7 @@ var PixelLabClient = class {
     };
     if (args.seed != null) body.seed = args.seed;
     if (args.noBackground != null) body.no_background = args.noBackground;
+    Object.assign(body, targetPaletteBody(args.targetPalette));
     return validateResponse(
       RevisionJobSubmitSchema,
       await this.request("/edit-animation-v2", { method: "POST", body: JSON.stringify(body) }),
@@ -5407,8 +5436,8 @@ var PixelLabProvider = class _PixelLabProvider {
         `PixelLab imagePro is ${spec.width}x${spec.height}; the API takes 16 to 792 wide and 16 to 688 tall (the exact ceiling also depends on aspect ratio)`
       );
     }
-    if (spec.generator === "imagePro" && !spec.revision && spec.palette.length && (spec.palette.length < 2 || spec.palette.length > 256)) {
-      throw new Error(`PixelLab imagePro's target palette takes 2 to 256 colours; the style's palette has ${spec.palette.length}`);
+    if (spec.palette.length && (spec.palette.length < 2 || spec.palette.length > 256) && sendsTargetPalette(spec)) {
+      throw new Error(`PixelLab ${spec.generator}'s target palette takes 2 to 256 colours; the style's palette has ${spec.palette.length}`);
     }
     if (spec.generator === "uiAsset" && (spec.width < 192 || spec.height < 192 || spec.width > 688 || spec.height > 688)) {
       throw new Error(
@@ -5858,7 +5887,8 @@ var PixelLabProvider = class _PixelLabProvider {
         styleCharacterId: character.styleAnchor ? requireStyleObjectId(spec, context) : void 0,
         styleReferenceSize: styleImage ? { width: styleImage.width, height: styleImage.height } : void 0,
         styleTraits: character.styleTraits,
-        sourceImageId: character.mode === "pro-flash" ? context?.referenceSourceImageId : void 0
+        sourceImageId: character.mode === "pro-flash" ? context?.referenceSourceImageId : void 0,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.character_id, metadata: { character: { kind: "base", characterId: res2.character_id, mode: character.mode, directions: character.directions, backgroundJobId: res2.background_job_id } } };
     }
@@ -5886,7 +5916,8 @@ var PixelLabProvider = class _PixelLabProvider {
         imageSize: { width: spec.width, height: spec.height },
         seed: spec.seed,
         noBackground: spec.noBackground,
-        additionalInstructions: outfit.additionalInstructions
+        additionalInstructions: outfit.additionalInstructions,
+        targetPalette: targetPaletteFor(spec)
       });
       return {
         jobId: res2.background_job_id,
@@ -5913,7 +5944,8 @@ var PixelLabProvider = class _PixelLabProvider {
         paletteFromReference: character.state?.paletteFromReference,
         canvas: character.state?.canvas,
         seed: spec.seed,
-        noBackground: spec.noBackground
+        noBackground: spec.noBackground,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.character_id, metadata: { character: { kind: "state", characterId: res2.character_id, parentCharacterId: parentId, mode: character.mode, directions: character.directions, backgroundJobId: res2.background_job_id } } };
     }
@@ -5928,7 +5960,8 @@ var PixelLabProvider = class _PixelLabProvider {
         image: { base64: bytes.toString("base64"), format: "png" },
         view: spec.view,
         resultSize: character.portrait.size,
-        seed: spec.seed
+        seed: spec.seed,
+        targetPalette: targetPaletteFor(spec)
       });
       return {
         jobId: res2.background_job_id,
@@ -6003,7 +6036,8 @@ var PixelLabProvider = class _PixelLabProvider {
         styleReference: styleImage ? { base64: styleImage.base64, format: styleImage.format } : void 0,
         styleReferenceSize: styleImage ? { width: styleImage.width, height: styleImage.height } : void 0,
         styleTraits: object.styleTraits,
-        sourceImageId: context?.referenceSourceImageId
+        sourceImageId: context?.referenceSourceImageId,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.object_id, metadata: { objectPro: { kind: "base", objectId: res2.object_id, directions: object.directions, backgroundJobId: res2.background_job_id } } };
     }
@@ -6018,7 +6052,8 @@ var PixelLabProvider = class _PixelLabProvider {
         objectId: parentId,
         editDescription: spec.prompt,
         stateName: spec.assetId.slice(0, 50),
-        seed: spec.seed
+        seed: spec.seed,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.object_id, metadata: { objectPro: { kind: "state", objectId: res2.object_id, parentObjectId: parentId, directions: object.directions, backgroundJobId: res2.background_job_id } } };
     }
@@ -6036,7 +6071,8 @@ var PixelLabProvider = class _PixelLabProvider {
       startFrame: animation.startFrame ? readPose(spec, "start frame", animation.startFrame) : void 0,
       endFrame: animation.endFrame ? readPose(spec, "end frame", animation.endFrame) : void 0,
       enhancePrompt: animation.enhancePrompt,
-      replaceExisting: true
+      replaceExisting: true,
+      targetPalette: targetPaletteFor(spec)
     });
     const submission = res.submissions.find((s) => s.direction === animation.direction) ?? res.submissions[0];
     const job = { objectId: parentId, name, direction: animation.direction, jobId: submission?.background_job_id ?? null };
@@ -6302,7 +6338,8 @@ var PixelLabProvider = class _PixelLabProvider {
         styleImage: styleImages[0] ? { base64: styleImages[0].base64, format: styleImages[0].format } : void 0,
         colorPalette: spec.uiColorPalette,
         noBackground: spec.noBackground,
-        seed: spec.seed
+        seed: spec.seed,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.ui_asset_id, metadata: { backgroundJobId: res2.background_job_id } };
     }
@@ -6315,7 +6352,8 @@ var PixelLabProvider = class _PixelLabProvider {
         noBackground: spec.noBackground,
         seed: spec.seed,
         styleImage: style ? { image: { base64: style.base64, format: style.format }, width: style.width, height: style.height } : void 0,
-        styleTraits: spec.styleTraits
+        styleTraits: spec.styleTraits,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.background_job_id, metadata: { imageProFlash: proFlashRecord(res2) } };
     }
@@ -6328,7 +6366,8 @@ var PixelLabProvider = class _PixelLabProvider {
         conceptImage: concept ? { image: { base64: concept.base64, format: concept.format }, width: concept.width, height: concept.height } : void 0,
         colorPalette: spec.uiColorPalette,
         noBackground: spec.noBackground,
-        seed: spec.seed
+        seed: spec.seed,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.background_job_id };
     }
@@ -6368,7 +6407,8 @@ var PixelLabProvider = class _PixelLabProvider {
         seed: spec.seed,
         // TilesProStyleImage is flat and wants the reference's real dimensions,
         // unlike 1dir's {type, base64, format} payload.
-        styleImages: styleImages.map(({ base64, width, height }) => ({ base64, width, height }))
+        styleImages: styleImages.map(({ base64, width, height }) => ({ base64, width, height })),
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.tile_id, metadata: { backgroundJobId: res2.background_job_id } };
     }
@@ -6417,7 +6457,8 @@ var PixelLabProvider = class _PixelLabProvider {
         outline: spec.outline,
         shading: spec.shading,
         detail: spec.detail,
-        seed: spec.seed
+        seed: spec.seed,
+        targetPalette: targetPaletteFor(spec)
       });
       return {
         jobId: res2.tileset_id,
@@ -6448,7 +6489,7 @@ var PixelLabProvider = class _PixelLabProvider {
         height: spec.height,
         noBackground: spec.noBackground,
         seed: spec.seed,
-        targetPalette: { colors: spec.palette, name: spec.paletteName, maxColors: spec.maxColors }
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.background_job_id };
     }
@@ -6467,7 +6508,8 @@ var PixelLabProvider = class _PixelLabProvider {
         // 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
+        itemDescriptions: spec.batch?.role === "leader" ? spec.batch.itemDescriptions : void 0,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.object_id, metadata: { backgroundJobId: res2.background_job_id } };
     }
@@ -6609,7 +6651,8 @@ var PixelLabProvider = class _PixelLabProvider {
         height,
         action: spec.prompt,
         seed: spec.seed,
-        noBackground: spec.noBackground
+        noBackground: spec.noBackground,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.background_job_id };
     }
@@ -6620,7 +6663,8 @@ var PixelLabProvider = class _PixelLabProvider {
         height,
         description: spec.prompt,
         seed: spec.seed,
-        noBackground: spec.noBackground
+        noBackground: spec.noBackground,
+        targetPalette: targetPaletteFor(spec)
       });
       return { jobId: res2.background_job_id };
     }
@@ -7565,6 +7609,39 @@ function remoteCharacter(character) {
     animationCount: character.animation_count
   };
 }
+function sendsTargetPalette(spec) {
+  if (spec.revision) return spec.revision.mode === "interpolate" || spec.revision.mode === "edit-animation";
+  if (spec.vfx) return false;
+  switch (spec.generator) {
+    case "imagePro":
+    case "imageProFlash":
+    case "1dir":
+    case "tiles":
+    case "uiAsset":
+    case "uiElement":
+      return true;
+    case "terrain":
+      return spec.terrainOrientation !== "sidescroller" && spec.terrainMode === "pro";
+    case "character": {
+      const character = spec.character;
+      if (!character) return false;
+      if (character.kind === "base") return character.mode === "pro" || character.mode === "pro-flash";
+      return character.kind !== "animation";
+    }
+    case "objectPro": {
+      const object = spec.objectPro;
+      if (!object) return false;
+      return object.kind !== "animation" || object.animation?.mode === "pro";
+    }
+    default:
+      return false;
+  }
+}
+function targetPaletteFor(spec) {
+  if (!sendsTargetPalette(spec)) return void 0;
+  if (!spec.palette.length && spec.maxColors == null) return void 0;
+  return { colors: spec.palette, name: spec.paletteName, maxColors: spec.maxColors };
+}
 function requirePixelLabOption(generator, name, value, allowed) {
   if (value != null && !allowed.includes(value)) {
     throw new Error(`PixelLab ${generator} ${name} must be one of: ${allowed.join(", ")}`);
@@ -10696,8 +10773,8 @@ async function resolveSpecs(loaded, filter) {
         uiColorPalette: generator === "uiAsset" || generator === "uiElement" ? style.uiColorPalette : void 0,
         ...generator === "imageProFlash" && style.styleTraits ? { styleTraits: style.styleTraits } : {},
         palette: style.palette,
-        ...generator === "imagePro" && style.paletteName ? { paletteName: style.paletteName } : {},
-        ...generator === "imagePro" && style.maxColors != null ? { maxColors: style.maxColors } : {},
+        ...style.paletteName ? { paletteName: style.paletteName } : {},
+        ...style.maxColors != null ? { maxColors: style.maxColors } : {},
         enforcePalette: style.enforcePalette,
         noBackground: style.noBackground,
         tileSize: generator === "tiles" ? tileSize : void 0,
@@ -21013,6 +21090,7 @@ export {
   ScenarioProvider,
   StyleInputSchema,
   StyleSchema,
+  TARGET_PALETTE_GENERATORS,
   TerrainConnectSchema,
   TerrainLinkSchema,
   TerrainSideSchema,
@@ -21238,6 +21316,7 @@ export {
   submit,
   summarize,
   tagAdopted,
+  targetPaletteBody,
   terrainCost,
   terrainSettings,
   terrainTileCount,