pixelkiln 0.42.0 → 0.43.0

package/dist/cli.js

@@ -665,7 +665,12 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         parent: spec.character.parentAssetId,
         parentSha256: spec.character.parentSha256 ?? null,
         state: spec.character.state,
-        animation: spec.character.animation
+        animation: spec.character.animation,
+        // Absent keys keep the hashes of manifests that never set these.
+        proportions: spec.character.proportions,
+        textGuidanceScale: spec.character.textGuidanceScale,
+        isometric: spec.character.isometric,
+        reference: spec.character.reference ? Object.fromEntries(Object.entries(spec.character.reference).map(([direction, image]) => [direction, image.sha256])) : void 0
       } : void 0,
       // A mirror's bytes come from its source's recorded outputs; the plan
       // compares those directly, so only the choice of source is identity.
@@ -783,6 +788,17 @@ var MIRRORED_DIRECTION = {
   "south-west": "south-east"
 };
 var CharacterModeSchema = z.enum(["standard", "v3", "pro"]);
+var CHARACTER_PROPORTION_PRESETS = ["default", "chibi", "cartoon", "stylized", "realistic_male", "realistic_female", "heroic"];
+var CharacterProportionsSchema = z.union([
+  z.enum(CHARACTER_PROPORTION_PRESETS),
+  z.object({
+    headSize: z.number().min(0.5).max(2).optional(),
+    armsLength: z.number().min(0.5).max(2).optional(),
+    legsLength: z.number().min(0.5).max(2).optional(),
+    shoulderWidth: z.number().min(0.5).max(2).optional(),
+    hipWidth: z.number().min(0.5).max(2).optional()
+  }).strict()
+]);
 var CharacterAnimationModeSchema = z.enum(["template", "v3", "pro"]);
 var CharacterStateSchema = z.object({
   /** The base character, or another state, in the same style. */
@@ -941,6 +957,16 @@ var StyleObjectSchema = z.object({
   directions: z.union([z.literal(4), z.literal(8)]).optional(),
   /** `character` only. Body template: `mannequin` (default) or a quadruped (`bear`, `cat`, `dog`, `horse`, `lion`). */
   template: z.string().min(1).optional(),
+  /** `character` only, `standard` humanoid bases. A preset or multipliers; an asset may override it. */
+  proportions: CharacterProportionsSchema.optional(),
+  /**
+   * `character` only. How closely a `standard` base and a template loop
+   * follow their text, 1 to 20; PixelLab's default is 8. The v3 and pro
+   * engines do not take it.
+   */
+  textGuidanceScale: z.number().min(1).max(20).optional(),
+  /** `character` only. Draw `standard` bases and every loop in isometric view. */
+  isometric: z.boolean().optional(),
   /** Fixed seed for reproducibility where the endpoint supports it. */
   seed: z.number().int().optional(),
   /**
@@ -1100,6 +1126,19 @@ var AssetSchema = z.object({
   state: CharacterStateSchema.optional(),
   /** `character` styles: this asset is a loop of another character asset in one direction. */
   animation: CharacterAnimationSchema.optional(),
+  /** `character` styles, `standard` humanoid bases: this character's proportions, over the style's. */
+  proportions: CharacterProportionsSchema.optional(),
+  /**
+   * `character` styles, bases only: the character's own sprite, which
+   * PixelLab rotates into the other directions instead of drawing from
+   * the prompt. A manifest-relative PNG or JPEG of the south-facing
+   * sprite, or an object keyed by direction (`{ "south": ..., "east":
+   * ... }`); quadrupeds in `standard` mode need south and east, and only
+   * `standard` takes more than south. `standard` wants each image at the
+   * style's size; v3 accepts up to 256px, pro up to 168px. The prompt
+   * still guides the result.
+   */
+  reference: z.union([z.string().min(1), z.record(CharacterDirectionSchema, z.string().min(1))]).optional(),
   /**
    * Another asset of the same style flipped left to right, made locally
    * from that asset's downloaded files at no generation cost.
@@ -1174,6 +1213,16 @@ var AssetSchema = z.object({
       path: ["prompt"]
     });
   }
+  if (asset.reference && (asset.state || asset.animation || asset.mirror)) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "a reference sprite belongs on a base; a state, animation, or mirror takes its look from its parent",
+      path: ["reference"]
+    });
+  }
+  if (typeof asset.reference === "object" && !Object.keys(asset.reference).length) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "a reference needs at least a south image", path: ["reference"] });
+  }
 });
 var DEFAULT_HISTORY_LIMIT = 5;
 var HistoryLimitSchema = z.number().int().min(0).max(100);
@@ -5016,6 +5065,17 @@ var PixelLabError = class extends ProviderError {
   }
   body;
 };
+function proportionsPayload(proportions) {
+  if (typeof proportions === "string") return { type: "preset", name: proportions };
+  return {
+    type: "custom",
+    ...proportions.headSize !== void 0 ? { head_size: proportions.headSize } : {},
+    ...proportions.armsLength !== void 0 ? { arms_length: proportions.armsLength } : {},
+    ...proportions.legsLength !== void 0 ? { legs_length: proportions.legsLength } : {},
+    ...proportions.shoulderWidth !== void 0 ? { shoulder_width: proportions.shoulderWidth } : {},
+    ...proportions.hipWidth !== void 0 ? { hip_width: proportions.hipWidth } : {}
+  };
+}
 var PixelLabClient = class {
   constructor(apiKey, timeoutMs = 12e4) {
     this.apiKey = apiKey;
@@ -5224,10 +5284,17 @@ var PixelLabClient = class {
    * A base character. Standard mode picks the 4- or 8-direction template
    * endpoint; v3 and pro have their own and always draw 8. Every one answers
    * at once with the character id and a background job.
+   *
+   * A `reference` is the author's own sprite: standard takes one per
+   * direction and draws the rest, v3 rotates the south one, and pro
+   * switches to its rotate method for it. A `styleReference` is pro's style
+   * anchor; the other engines have no such input.
    */
   async createCharacter(args) {
     const imageSize = { width: args.size, height: args.size };
     const palette = args.paletteSwatchBase64 ? { color_image: { type: "base64", base64: args.paletteSwatchBase64, format: "png" }, force_colors: true } : {};
+    const encode = (image) => ({ type: "base64", base64: image.base64, format: image.format });
+    const south = args.reference?.south;
     let path45;
     let body;
     if (args.mode === "v3") {
@@ -5240,7 +5307,8 @@ var PixelLabClient = class {
         ...args.view ? { view: args.view } : {},
         ...args.outline ? { outline: args.outline } : {},
         ...args.detail ? { detail: args.detail } : {},
-        ...args.seed != null ? { seed: args.seed } : {}
+        ...args.seed != null ? { seed: args.seed } : {},
+        ...south ? { reference_image: encode(south) } : {}
       };
     } else if (args.mode === "pro") {
       path45 = "/create-character-pro";
@@ -5249,8 +5317,10 @@ var PixelLabClient = class {
         image_size: imageSize,
         template_id: args.template,
         no_background: args.noBackground ?? true,
+        method: south ? "rotate_character" : "create_with_style",
         ...args.view ? { view: args.view } : {},
-        ...args.seed != null ? { seed: args.seed } : {}
+        ...args.seed != null ? { seed: args.seed } : {},
+        ...south ? { reference_image: encode(south) } : args.styleReference ? { reference_image: encode(args.styleReference) } : {}
       };
     } else {
       path45 = args.directions === 4 ? "/create-character-with-4-directions" : "/create-character-with-8-directions";
@@ -5263,6 +5333,10 @@ var PixelLabClient = class {
         ...args.shading ? { shading: args.shading } : {},
         ...args.detail ? { detail: args.detail } : {},
         ...args.seed != null ? { seed: args.seed } : {},
+        ...args.proportions !== void 0 ? { proportions: proportionsPayload(args.proportions) } : {},
+        ...args.textGuidanceScale !== void 0 ? { text_guidance_scale: args.textGuidanceScale } : {},
+        ...args.isometric !== void 0 ? { isometric: args.isometric } : {},
+        ...args.reference && Object.keys(args.reference).length ? { directions: Object.fromEntries(Object.entries(args.reference).flatMap(([direction, image]) => image ? [[direction, encode(image)]] : [])) } : {},
         ...palette
       };
     }
@@ -5302,6 +5376,8 @@ var PixelLabClient = class {
         ...args.actionDescription ? { action_description: args.actionDescription } : {},
         ...args.mode === "v3" && args.frameCount ? { frame_count: args.frameCount } : {},
         ...args.mode === "v3" && args.keepFirstFrame === false ? { keep_first_frame: false } : {},
+        ...args.mode === "template" && args.textGuidanceScale !== void 0 ? { text_guidance_scale: args.textGuidanceScale } : {},
+        ...args.isometric !== void 0 ? { isometric: args.isometric } : {},
         ...args.seed != null ? { seed: args.seed } : {}
       })
     });
@@ -5498,8 +5574,8 @@ var PixelLabProvider = class _PixelLabProvider {
         "high detail"
       ]);
     }
-    if (spec.generator === "character") this.validateCharacter(spec);
-    if ((spec.generator === "map" || spec.generator === "pixflux" || spec.generator === "character") && styleImages.length) {
+    if (spec.generator === "character") this.validateCharacter(spec, styleImages);
+    if ((spec.generator === "map" || spec.generator === "pixflux") && styleImages.length) {
       throw new Error(`PixelLab ${spec.generator} does not support style images`);
     }
     for (const image of styleImages) {
@@ -5515,9 +5591,61 @@ var PixelLabProvider = class _PixelLabProvider {
       );
     }
   }
-  validateCharacter(spec) {
+  validateCharacter(spec, styleImages = []) {
     const character = spec.character;
     if (!character) throw new Error(`${spec.styleId}/${spec.assetId} has no character shape`);
+    const label = `${spec.styleId}/${spec.assetId}`;
+    if (character.kind === "base" && character.proportions !== void 0) {
+      if (character.mode !== "standard") {
+        throw new Error(`${label}: proportions apply to standard bases; the ${character.mode} engine has none to set`);
+      }
+      if (character.template !== "mannequin") {
+        throw new Error(`${label}: proportions apply to the mannequin template; ${character.template} is a quadruped`);
+      }
+    }
+    if (character.reference) {
+      const given = Object.keys(character.reference);
+      if (!character.reference.south) throw new Error(`${label}: a reference needs a south-facing sprite`);
+      if (character.mode !== "standard") {
+        if (given.length > 1) throw new Error(`${label}: PixelLab ${character.mode} rotates one south-facing reference; drop the other directions`);
+        const limit = character.mode === "v3" ? 256 : 168;
+        const south = character.reference.south;
+        if (south.width > limit || south.height > limit) {
+          throw new Error(`${label}: reference is ${south.width}x${south.height}; PixelLab ${character.mode} takes up to ${limit}px`);
+        }
+      } else {
+        const allowed = character.directions === 4 ? CHARACTER_DIRECTIONS_4 : CHARACTER_DIRECTIONS_8;
+        for (const direction of given) {
+          if (!allowed.includes(direction)) {
+            throw new Error(`${label}: reference "${direction}" is not one of this character's ${character.directions} directions`);
+          }
+          const image = character.reference[direction];
+          if (image.width !== spec.width || image.height !== spec.height) {
+            throw new Error(
+              `${label}: reference (${direction}) is ${image.width}x${image.height}; standard mode wants each image at the style's size, ${spec.width}x${spec.height}`
+            );
+          }
+        }
+        if (character.template !== "mannequin" && !character.reference.east) {
+          throw new Error(`${label}: a ${character.template} reference needs south and east images`);
+        }
+      }
+    }
+    if (styleImages.length) {
+      if (character.mode !== "pro") {
+        throw new Error(
+          `PixelLab ${character.mode} characters take no style images; give a base its own sprite with \`reference\`, or use mode pro for a style anchor`
+        );
+      }
+      if (styleImages.length > 1) throw new Error("PixelLab pro characters take one style image");
+      if (character.kind === "base" && character.reference) {
+        throw new Error(`${label}: a pro base rotating its own reference takes no style image`);
+      }
+      const image = styleImages[0];
+      if (image.width > 168 || image.height > 168) {
+        throw new Error(`PixelLab pro character style image is ${image.width}x${image.height}; the limit is 168px`);
+      }
+    }
     const maxSize = character.mode === "v3" ? 256 : 128;
     if (spec.width < 16 || spec.height < 16 || spec.width > maxSize || spec.height > maxSize) {
       throw new Error(`PixelLab ${character.mode} characters must be between 16 and ${maxSize} pixels`);
@@ -5553,10 +5681,11 @@ var PixelLabProvider = class _PixelLabProvider {
    * asset so a later run can find it, and clears its own earlier take for
    * that direction first, since PixelLab skips a direction that exists.
    */
-  async submitCharacter(spec, context) {
+  async submitCharacter(spec, styleImages, context) {
     const character = spec.character;
     if (character.kind === "base") {
       const swatch = spec.palette.length && character.mode === "standard" ? paletteSwatch(spec.palette).toString("base64") : void 0;
+      const styleImage = styleImages[0];
       const res2 = await this.client.createCharacter({
         mode: character.mode,
         description: spec.prompt,
@@ -5569,7 +5698,12 @@ var PixelLabProvider = class _PixelLabProvider {
         detail: spec.detail,
         seed: spec.seed,
         noBackground: spec.noBackground,
-        paletteSwatchBase64: swatch
+        paletteSwatchBase64: swatch,
+        proportions: character.proportions,
+        textGuidanceScale: character.textGuidanceScale,
+        isometric: character.isometric,
+        reference: character.reference ? readReference(spec, character.reference) : void 0,
+        styleReference: styleImage ? { base64: styleImage.base64, format: styleImage.format } : void 0
       });
       return { jobId: res2.character_id, metadata: { character: { kind: "base", characterId: res2.character_id, mode: character.mode, directions: character.directions, backgroundJobId: res2.background_job_id } } };
     }
@@ -5611,7 +5745,9 @@ var PixelLabProvider = class _PixelLabProvider {
       frameCount: animation.frames,
       keepFirstFrame: animation.keepFirstFrame,
       directions: [animation.direction],
-      seed: spec.seed
+      seed: spec.seed,
+      textGuidanceScale: character.textGuidanceScale,
+      isometric: character.isometric
     });
     const job = { characterId: parentId, name, direction: animation.direction, jobIds: res.background_job_ids };
     return {
@@ -5701,7 +5837,7 @@ var PixelLabProvider = class _PixelLabProvider {
   }
   async submit(spec, styleImages, context) {
     this.validate(spec, styleImages);
-    if (spec.generator === "character") return this.submitCharacter(spec, context);
+    if (spec.generator === "character") return this.submitCharacter(spec, styleImages, context);
     if (spec.generator === "pixflux") {
       const swatch = spec.palette.length ? paletteSwatch(spec.palette).toString("base64") : void 0;
       const { png } = await this.client.createImagePixflux({
@@ -5968,6 +6104,17 @@ function firstUrl(urls) {
   if (!urls) return null;
   return Object.values(urls).find((u) => typeof u === "string") ?? null;
 }
+function readReference(spec, reference) {
+  const images = {};
+  for (const [direction, image] of Object.entries(reference)) {
+    const bytes = readFileSync2(image.path);
+    if (sha256(bytes) !== image.sha256) {
+      throw new Error(`${spec.styleId}/${spec.assetId}: reference (${direction}) changed after the manifest was resolved: ${image.path}`);
+    }
+    images[direction] = { base64: bytes.toString("base64"), format: image.format };
+  }
+  return images;
+}
 function rotationSources(character) {
   const order = character.directions === 4 ? CHARACTER_DIRECTIONS_4 : CHARACTER_DIRECTIONS_8;
   const sources = [];
@@ -7087,16 +7234,16 @@ async function resolveSpecs(loaded, filter) {
     }
   }
   const styleImageCache = /* @__PURE__ */ new Map();
-  async function loadStyleImage(rel) {
+  async function loadStyleImage(rel, what = "Style image") {
     const abs = path13.resolve(root, rel);
     let hit = styleImageCache.get(abs);
     if (!hit) {
-      if (!existsSync8(abs)) throw new Error(`Style image not found: ${abs}`);
+      if (!existsSync8(abs)) throw new Error(`${what} not found: ${abs}`);
       const buf = await readFile6(abs);
       const metadata = imageMetadata(buf);
-      if (!metadata) throw new Error(`Style image is not a readable PNG or JPEG: ${abs}`);
+      if (!metadata) throw new Error(`${what} is not a readable PNG or JPEG: ${abs}`);
       if (metadata.width < 1 || metadata.height < 1) {
-        throw new Error(`Style image has invalid dimensions: ${abs}`);
+        throw new Error(`${what} has invalid dimensions: ${abs}`);
       }
       hit = { base64: buf.toString("base64"), hash: sha256(buf), ...metadata };
       styleImageCache.set(abs, hit);
@@ -7203,7 +7350,7 @@ async function resolveSpecs(loaded, filter) {
         tileView: generator === "tiles" ? style.tileView : void 0,
         tileFeature: generator === "tiles" ? style.tileFeature : void 0,
         outlineMode: generator === "tiles" ? style.outlineMode : void 0,
-        ...generator === "character" ? { character: resolveCharacterShape(asset, style, characterKind) } : {},
+        ...generator === "character" ? { character: await resolveCharacterShape(asset, style, characterKind, { root, load: loadStyleImage }) } : {},
         cost: generator === "tiles" ? tilesCost(tileSize, tileVariations) : generationCost(width, height, generator),
         costUnit: "generations",
         candidates: generator === "tiles" ? tileVariations : generator === "1dir" ? candidateCount(size) : 1
@@ -7445,15 +7592,33 @@ function imageMetadata(buf) {
   }
   return null;
 }
-function resolveCharacterShape(asset, style, kind) {
+async function resolveCharacterShape(asset, style, kind, files) {
   const mode2 = style.mode ?? "standard";
   const directions = mode2 === "standard" ? style.directions ?? 8 : 8;
+  const proportions = asset.proportions ?? style.proportions;
   const shape = {
     kind,
     mode: mode2,
     directions,
-    template: style.template ?? "mannequin"
+    template: style.template ?? "mannequin",
+    ...proportions !== void 0 ? { proportions } : {},
+    ...style.textGuidanceScale !== void 0 ? { textGuidanceScale: style.textGuidanceScale } : {},
+    ...style.isometric !== void 0 ? { isometric: style.isometric } : {}
   };
+  if (asset.reference) {
+    const byDirection = typeof asset.reference === "string" ? { south: asset.reference } : asset.reference;
+    shape.reference = {};
+    for (const [direction, rel] of Object.entries(byDirection)) {
+      const image = await files.load(rel, `Reference sprite (${direction})`);
+      shape.reference[direction] = {
+        path: path13.resolve(files.root, rel),
+        sha256: image.hash,
+        width: image.width,
+        height: image.height,
+        format: image.format
+      };
+    }
+  }
   if (asset.state) {
     shape.state = {
       paletteFromReference: asset.state.paletteFromReference,