pixelkiln 0.42.0 → 0.44.0

package/dist/index.cjs

@@ -34,10 +34,12 @@ __export(index_exports, {
   BudgetError: () => BudgetError,
   CHARACTER_DIRECTIONS_4: () => CHARACTER_DIRECTIONS_4,
   CHARACTER_DIRECTIONS_8: () => CHARACTER_DIRECTIONS_8,
+  CHARACTER_PROPORTION_PRESETS: () => CHARACTER_PROPORTION_PRESETS,
   CharacterAnimationModeSchema: () => CharacterAnimationModeSchema,
   CharacterAnimationSchema: () => CharacterAnimationSchema,
   CharacterDirectionSchema: () => CharacterDirectionSchema,
   CharacterModeSchema: () => CharacterModeSchema,
+  CharacterProportionsSchema: () => CharacterProportionsSchema,
   CharacterStateSchema: () => CharacterStateSchema,
   ComfyUIProvider: () => ComfyUIProvider,
   DEFAULT_HISTORY_LIMIT: () => DEFAULT_HISTORY_LIMIT,
@@ -204,6 +206,7 @@ __export(index_exports, {
   portableOutputPath: () => portableOutputPath,
   prepareReview: () => prepareReview,
   primaryOutput: () => primaryOutput,
+  proportionsPayload: () => proportionsPayload,
   providerCredentialEnvs: () => providerCredentialEnvs,
   providerFactory: () => providerFactory,
   pushTags: () => pushTags,
@@ -387,6 +390,17 @@ var MIRRORED_DIRECTION = {
   "south-west": "south-east"
 };
 var CharacterModeSchema = import_zod.z.enum(["standard", "v3", "pro"]);
+var CHARACTER_PROPORTION_PRESETS = ["default", "chibi", "cartoon", "stylized", "realistic_male", "realistic_female", "heroic"];
+var CharacterProportionsSchema = import_zod.z.union([
+  import_zod.z.enum(CHARACTER_PROPORTION_PRESETS),
+  import_zod.z.object({
+    headSize: import_zod.z.number().min(0.5).max(2).optional(),
+    armsLength: import_zod.z.number().min(0.5).max(2).optional(),
+    legsLength: import_zod.z.number().min(0.5).max(2).optional(),
+    shoulderWidth: import_zod.z.number().min(0.5).max(2).optional(),
+    hipWidth: import_zod.z.number().min(0.5).max(2).optional()
+  }).strict()
+]);
 var CharacterAnimationModeSchema = import_zod.z.enum(["template", "v3", "pro"]);
 var CharacterStateSchema = import_zod.z.object({
   /** The base character, or another state, in the same style. */
@@ -413,11 +427,45 @@ var CharacterAnimationSchema = import_zod.z.object({
   /** v3 only: keep the resting pose as frame 0, so `frames` generated frames land as `frames + 1` files. */
   keepFirstFrame: import_zod.z.boolean().default(true),
   /** `template` when a template is named, otherwise `v3`; `pro` for the sequential high-quality engine. */
-  mode: CharacterAnimationModeSchema.optional()
+  mode: CharacterAnimationModeSchema.optional(),
+  /**
+   * v3 only: a manifest-relative image of the pose to start from, instead
+   * of the character's rotation for this direction. Up to 256px.
+   */
+  startFrame: import_zod.z.string().min(1).optional(),
+  /**
+   * v3 only: a pose to animate toward. The loop then interpolates from the
+   * start frame (the rotation, or `startFrame`) to this image, which must
+   * be the same size as the start frame.
+   */
+  endFrame: import_zod.z.string().min(1).optional(),
+  /** What is being animated, when the character's own description would mislead the model. */
+  subject: import_zod.z.string().min(1).optional(),
+  /** Template mode only: style hints for this loop, over the character's own. */
+  outline: import_zod.z.string().min(1).optional(),
+  shading: import_zod.z.string().min(1).optional(),
+  detail: import_zod.z.string().min(1).optional(),
+  /** v3 text loops only: let PixelLab expand the action into a fuller motion description first. */
+  enhancePrompt: import_zod.z.boolean().optional()
 }).strict().superRefine((animation, context) => {
   if (animation.frames !== void 0 && animation.frames % 2 !== 0) {
     context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
   }
+  const mode2 = animation.mode ?? (animation.template ? "template" : "v3");
+  for (const key of ["startFrame", "endFrame", "enhancePrompt"]) {
+    if (animation[key] !== void 0 && mode2 !== "v3") {
+      context.addIssue({
+        code: import_zod.z.ZodIssueCode.custom,
+        message: `${key} is for v3 loops; a ${mode2} loop ${mode2 === "template" ? "starts from the character's rotation and follows its template" : "takes neither"}`,
+        path: [key]
+      });
+    }
+  }
+  for (const key of ["outline", "shading", "detail"]) {
+    if (animation[key] !== void 0 && mode2 !== "template") {
+      context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: `${key} overrides apply to template loops only`, path: [key] });
+    }
+  }
   if (animation.template && animation.mode && animation.mode !== "template") {
     context.addIssue({
       code: import_zod.z.ZodIssueCode.custom,
@@ -545,6 +593,18 @@ var StyleObjectSchema = import_zod.z.object({
   directions: import_zod.z.union([import_zod.z.literal(4), import_zod.z.literal(8)]).optional(),
   /** `character` only. Body template: `mannequin` (default) or a quadruped (`bear`, `cat`, `dog`, `horse`, `lion`). */
   template: import_zod.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: import_zod.z.number().min(1).max(20).optional(),
+  /** `character` only. Draw `standard` bases and every loop in isometric view. */
+  isometric: import_zod.z.boolean().optional(),
+  /** `character` only, `v3` bases: let PixelLab expand the prompt into a fuller one before drawing. */
+  enhancePrompt: import_zod.z.boolean().optional(),
   /** Fixed seed for reproducibility where the endpoint supports it. */
   seed: import_zod.z.number().int().optional(),
   /**
@@ -704,6 +764,19 @@ var AssetSchema = import_zod.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: import_zod.z.union([import_zod.z.string().min(1), import_zod.z.record(CharacterDirectionSchema, import_zod.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.
@@ -778,6 +851,16 @@ var AssetSchema = import_zod.z.object({
       path: ["prompt"]
     });
   }
+  if (asset.reference && (asset.state || asset.animation || asset.mirror)) {
+    context.addIssue({
+      code: import_zod.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: import_zod.z.ZodIssueCode.custom, message: "a reference needs at least a south image", path: ["reference"] });
+  }
 });
 var DEFAULT_HISTORY_LIMIT = 5;
 var HistoryLimitSchema = import_zod.z.number().int().min(0).max(100);
@@ -1203,6 +1286,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;
@@ -1411,10 +1505,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 path33;
     let body;
     if (args.mode === "v3") {
@@ -1427,7 +1528,9 @@ 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) } : {},
+        ...args.enhancePrompt ? { enhance_prompt: true } : {}
       };
     } else if (args.mode === "pro") {
       path33 = "/create-character-pro";
@@ -1436,8 +1539,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 {
       path33 = args.directions === 4 ? "/create-character-with-4-directions" : "/create-character-with-8-directions";
@@ -1450,6 +1555,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
       };
     }
@@ -1478,6 +1587,7 @@ var PixelLabClient = class {
    * the action text; pro is the sequential engine. One job per direction.
    */
   async animateCharacter(args) {
+    const encode = (image) => ({ type: "base64", base64: image.base64, format: image.format });
     const raw = await this.request("/animate-character", {
       method: "POST",
       body: JSON.stringify({
@@ -1487,8 +1597,18 @@ var PixelLabClient = class {
         directions: args.directions,
         ...args.template ? { template_animation_id: args.template } : {},
         ...args.actionDescription ? { action_description: args.actionDescription } : {},
+        ...args.description ? { description: args.description } : {},
         ...args.mode === "v3" && args.frameCount ? { frame_count: args.frameCount } : {},
         ...args.mode === "v3" && args.keepFirstFrame === false ? { keep_first_frame: false } : {},
+        ...args.mode === "v3" && args.startFrame ? { custom_start_frame: encode(args.startFrame) } : {},
+        ...args.mode === "v3" && args.endFrame ? { end_frame: encode(args.endFrame) } : {},
+        ...args.mode === "v3" && args.enhancePrompt ? { enhance_prompt: true } : {},
+        ...args.mode === "template" && args.textGuidanceScale !== void 0 ? { text_guidance_scale: args.textGuidanceScale } : {},
+        ...args.mode === "template" && args.outline ? { outline: args.outline } : {},
+        ...args.mode === "template" && args.shading ? { shading: args.shading } : {},
+        ...args.mode === "template" && args.detail ? { detail: args.detail } : {},
+        ...args.isometric !== void 0 ? { isometric: args.isometric } : {},
+        ...args.paletteSwatchBase64 ? { color_image: { type: "base64", base64: args.paletteSwatchBase64, format: "png" }, force_colors: true } : {},
         ...args.seed != null ? { seed: args.seed } : {}
       })
     });
@@ -2085,12 +2205,122 @@ function skipSubBlocks(bytes, start) {
 function cacheFileName(hash, mediaType = MediaType.PNG) {
   return `${hash}${mediaExtension(mediaType)}`;
 }
+function imageMetadata(buf) {
+  if (buf.length >= 24 && buf.readUInt32BE(0) === 2303741511 && buf.readUInt32BE(4) === 218765834 && buf.toString("ascii", 12, 16) === "IHDR") {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20), format: "png" };
+  }
+  if (buf.length < 4 || buf[0] !== 255 || buf[1] !== 216) return null;
+  let offset = 2;
+  while (offset + 3 < buf.length) {
+    if (buf[offset] !== 255) return null;
+    while (buf[offset] === 255) offset++;
+    const marker = buf[offset++];
+    if (marker == null || marker === 217 || marker === 218) break;
+    if (marker === 1 || marker >= 208 && marker <= 215) continue;
+    if (offset + 2 > buf.length) return null;
+    const length = buf.readUInt16BE(offset);
+    if (length < 2 || offset + length > buf.length) return null;
+    const isStartOfFrame = marker >= 192 && marker <= 207 && ![196, 200, 204].includes(marker);
+    if (isStartOfFrame) {
+      if (length < 7) return null;
+      return {
+        width: buf.readUInt16BE(offset + 5),
+        height: buf.readUInt16BE(offset + 3),
+        format: "jpeg"
+      };
+    }
+    offset += length;
+  }
+  return null;
+}
 
 // src/providers/pixellab.ts
-var import_node_fs = require("fs");
-var import_node_crypto = require("crypto");
+var import_node_fs2 = require("fs");
+var import_node_crypto2 = require("crypto");
 var import_node_os = __toESM(require("os"), 1);
 var import_node_path = __toESM(require("path"), 1);
+
+// src/hash.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+function sha256(data) {
+  return (0, import_node_crypto.createHash)("sha256").update(data).digest("hex");
+}
+async function sha256File(path33) {
+  return new Promise((resolve, reject) => {
+    const hash = (0, import_node_crypto.createHash)("sha256");
+    const stream = (0, import_node_fs.createReadStream)(path33);
+    stream.on("data", (chunk2) => hash.update(chunk2));
+    stream.on("error", reject);
+    stream.on("end", () => resolve(hash.digest("hex")));
+  });
+}
+function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions, providerInputIdentity = spec.providerInputs ?? {}) {
+  return sha256(
+    JSON.stringify({
+      // Preserve every existing PixelLab hash while making a provider switch
+      // invalidate the spec. Older manifests implicitly mean pixellab.
+      provider: spec.provider === "pixellab" ? void 0 : spec.provider,
+      providerOptions: providerOptionIdentity && (typeof providerOptionIdentity !== "object" || Object.keys(providerOptionIdentity).length > 0) ? providerOptionIdentity : void 0,
+      providerInputs: providerInputIdentity && (typeof providerInputIdentity !== "object" || Object.keys(providerInputIdentity).length > 0) ? providerInputIdentity : void 0,
+      generator: spec.generator,
+      prompt: spec.prompt,
+      width: spec.width,
+      height: spec.height,
+      view: spec.view,
+      outline: spec.outline ?? null,
+      shading: spec.shading ?? null,
+      detail: spec.detail ?? null,
+      seed: spec.seed ?? null,
+      palette: spec.palette,
+      // `noBackground` only reaches the wire for pixflux; the tile fields are
+      // undefined for every other generator. `tileSize` is intentionally
+      // absent; width/height are derived from it, so it is already covered.
+      noBackground: spec.generator === "pixflux" || spec.provider !== "pixellab" ? spec.noBackground : void 0,
+      tileType: spec.tileType,
+      tileView: spec.tileView,
+      tileFeature: spec.tileFeature,
+      outlineMode: spec.outlineMode,
+      styleImages: styleImageHashes,
+      // A character family: the engine and rotations of a base, the parent's
+      // generated bytes for a state or animation (so a regenerated parent
+      // makes its children stale), and each shape's own settings.
+      character: spec.character ? {
+        kind: spec.character.kind,
+        mode: spec.character.mode,
+        directions: spec.character.directions,
+        template: spec.character.template,
+        parent: spec.character.parentAssetId,
+        parentSha256: spec.character.parentSha256 ?? null,
+        state: spec.character.state,
+        // Pose images enter as their hashes, never their paths.
+        animation: spec.character.animation ? {
+          ...spec.character.animation,
+          startFrame: spec.character.animation.startFrame?.sha256,
+          endFrame: spec.character.animation.endFrame?.sha256
+        } : void 0,
+        // Absent keys keep the hashes of manifests that never set these.
+        proportions: spec.character.proportions,
+        textGuidanceScale: spec.character.textGuidanceScale,
+        isometric: spec.character.isometric,
+        enhancePrompt: spec.character.enhancePrompt,
+        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.
+      mirror: spec.mirror ? { of: spec.mirror.sourceAssetId } : void 0,
+      revision: spec.revision ? {
+        mode: spec.revision.mode,
+        from: spec.revision.sourceAssetId,
+        sourceSha256: spec.revision.sourceSha256,
+        maskSha256: spec.revision.maskSha256,
+        strength: spec.revision.strength
+      } : void 0
+    })
+  );
+}
+
+// src/providers/pixellab.ts
 function pixelLabObjectUrl(generator, objectId) {
   if (!objectId) return null;
   if (generator === "map" || generator === "1dir") {
@@ -2171,7 +2401,7 @@ var PixelLabProvider = class _PixelLabProvider {
    */
   static cacheDir() {
     const dir = import_node_path.default.join(import_node_os.default.tmpdir(), "pixelkiln-pixflux");
-    (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+    (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
     return dir;
   }
   estimate(spec) {
@@ -2213,8 +2443,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) {
@@ -2230,9 +2460,80 @@ 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.kind === "base" && character.enhancePrompt !== void 0 && character.mode !== "v3") {
+      throw new Error(`${label}: enhancePrompt applies to v3 bases; the ${character.mode} engine does not take it`);
+    }
+    if (character.animation) {
+      const { startFrame, endFrame } = character.animation;
+      for (const [name, image] of [["start frame", startFrame], ["end frame", endFrame]]) {
+        if (image && (image.width > 256 || image.height > 256)) {
+          throw new Error(`${label}: ${name} is ${image.width}x${image.height}; PixelLab v3 takes up to 256px`);
+        }
+      }
+      if (endFrame) {
+        const start = startFrame ?? (character.parentFile && (0, import_node_fs2.existsSync)(character.parentFile) ? imageMetadata((0, import_node_fs2.readFileSync)(character.parentFile)) : null);
+        if (start && (start.width !== endFrame.width || start.height !== endFrame.height)) {
+          throw new Error(
+            `${label}: end frame is ${endFrame.width}x${endFrame.height} but the ${startFrame ? "start frame" : "character's rotation"} is ${start.width}x${start.height}; PixelLab interpolates between frames of one size`
+          );
+        }
+      }
+    }
+    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`);
@@ -2268,10 +2569,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,
@@ -2284,7 +2586,13 @@ 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,
+        enhancePrompt: character.enhancePrompt
       });
       return { jobId: res2.character_id, metadata: { character: { kind: "base", characterId: res2.character_id, mode: character.mode, directions: character.directions, backgroundJobId: res2.background_job_id } } };
     }
@@ -2326,7 +2634,17 @@ 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,
+      startFrame: animation.startFrame ? readPose(spec, "start frame", animation.startFrame) : void 0,
+      endFrame: animation.endFrame ? readPose(spec, "end frame", animation.endFrame) : void 0,
+      description: animation.subject,
+      outline: animation.outline,
+      shading: animation.shading,
+      detail: animation.detail,
+      enhancePrompt: animation.enhancePrompt,
+      paletteSwatchBase64: spec.palette.length ? paletteSwatch(spec.palette).toString("base64") : void 0
     });
     const job = { characterId: parentId, name, direction: animation.direction, jobIds: res.background_job_ids };
     return {
@@ -2416,7 +2734,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({
@@ -2427,8 +2745,8 @@ var PixelLabProvider = class _PixelLabProvider {
         paletteSwatchBase64: swatch,
         seed: spec.seed
       });
-      const jobId = (0, import_node_crypto.randomUUID)();
-      (0, import_node_fs.writeFileSync)(import_node_path.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), png);
+      const jobId = (0, import_node_crypto2.randomUUID)();
+      (0, import_node_fs2.writeFileSync)(import_node_path.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), png);
       return { jobId };
     }
     if (spec.generator === "tiles") {
@@ -2470,7 +2788,7 @@ var PixelLabProvider = class _PixelLabProvider {
   async poll(jobId, generator, context) {
     if (generator === "pixflux") {
       const file = import_node_path.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
-      if ((0, import_node_fs.existsSync)(file)) {
+      if ((0, import_node_fs2.existsSync)(file)) {
         const sourceUrl = `file://${file}`;
         return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }] };
       }
@@ -2576,7 +2894,7 @@ var PixelLabProvider = class _PixelLabProvider {
     return { objectId, sourceUrl: firstUrl(obj?.rotation_urls) ?? obj?.preview_url ?? null };
   }
   async download(url) {
-    if (url.startsWith("file://")) return (0, import_node_fs.readFileSync)(url.slice("file://".length));
+    if (url.startsWith("file://")) return (0, import_node_fs2.readFileSync)(url.slice("file://".length));
     return this.client.download(url);
   }
   async balance() {
@@ -2683,6 +3001,24 @@ 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 = (0, import_node_fs2.readFileSync)(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 readPose(spec, what, image) {
+  const bytes = (0, import_node_fs2.readFileSync)(image.path);
+  if (sha256(bytes) !== image.sha256) {
+    throw new Error(`${spec.styleId}/${spec.assetId}: ${what} changed after the manifest was resolved: ${image.path}`);
+  }
+  return { base64: bytes.toString("base64"), format: image.format };
+}
 function rotationSources(character) {
   const order = character.directions === 4 ? CHARACTER_DIRECTIONS_4 : CHARACTER_DIRECTIONS_8;
   const sources = [];
@@ -3554,77 +3890,6 @@ function redactScenarioError(value, secrets) {
 var import_node_crypto3 = require("crypto");
 var import_promises = require("fs/promises");
 var import_node_path2 = __toESM(require("path"), 1);
-
-// src/hash.ts
-var import_node_crypto2 = require("crypto");
-var import_node_fs2 = require("fs");
-function sha256(data) {
-  return (0, import_node_crypto2.createHash)("sha256").update(data).digest("hex");
-}
-async function sha256File(path33) {
-  return new Promise((resolve, reject) => {
-    const hash = (0, import_node_crypto2.createHash)("sha256");
-    const stream = (0, import_node_fs2.createReadStream)(path33);
-    stream.on("data", (chunk2) => hash.update(chunk2));
-    stream.on("error", reject);
-    stream.on("end", () => resolve(hash.digest("hex")));
-  });
-}
-function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions, providerInputIdentity = spec.providerInputs ?? {}) {
-  return sha256(
-    JSON.stringify({
-      // Preserve every existing PixelLab hash while making a provider switch
-      // invalidate the spec. Older manifests implicitly mean pixellab.
-      provider: spec.provider === "pixellab" ? void 0 : spec.provider,
-      providerOptions: providerOptionIdentity && (typeof providerOptionIdentity !== "object" || Object.keys(providerOptionIdentity).length > 0) ? providerOptionIdentity : void 0,
-      providerInputs: providerInputIdentity && (typeof providerInputIdentity !== "object" || Object.keys(providerInputIdentity).length > 0) ? providerInputIdentity : void 0,
-      generator: spec.generator,
-      prompt: spec.prompt,
-      width: spec.width,
-      height: spec.height,
-      view: spec.view,
-      outline: spec.outline ?? null,
-      shading: spec.shading ?? null,
-      detail: spec.detail ?? null,
-      seed: spec.seed ?? null,
-      palette: spec.palette,
-      // `noBackground` only reaches the wire for pixflux; the tile fields are
-      // undefined for every other generator. `tileSize` is intentionally
-      // absent; width/height are derived from it, so it is already covered.
-      noBackground: spec.generator === "pixflux" || spec.provider !== "pixellab" ? spec.noBackground : void 0,
-      tileType: spec.tileType,
-      tileView: spec.tileView,
-      tileFeature: spec.tileFeature,
-      outlineMode: spec.outlineMode,
-      styleImages: styleImageHashes,
-      // A character family: the engine and rotations of a base, the parent's
-      // generated bytes for a state or animation (so a regenerated parent
-      // makes its children stale), and each shape's own settings.
-      character: spec.character ? {
-        kind: spec.character.kind,
-        mode: spec.character.mode,
-        directions: spec.character.directions,
-        template: spec.character.template,
-        parent: spec.character.parentAssetId,
-        parentSha256: spec.character.parentSha256 ?? null,
-        state: spec.character.state,
-        animation: spec.character.animation
-      } : 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.
-      mirror: spec.mirror ? { of: spec.mirror.sourceAssetId } : void 0,
-      revision: spec.revision ? {
-        mode: spec.revision.mode,
-        from: spec.revision.sourceAssetId,
-        sourceSha256: spec.revision.sourceSha256,
-        maskSha256: spec.revision.maskSha256,
-        strength: spec.revision.strength
-      } : void 0
-    })
-  );
-}
-
-// src/providers/comfyui.ts
 var DEFAULT_BASE_URL3 = "http://127.0.0.1:8188";
 var BUILTIN_BINDINGS = /* @__PURE__ */ new Set([
   "prompt",
@@ -5251,16 +5516,16 @@ async function resolveSpecs(loaded, filter) {
     }
   }
   const styleImageCache = /* @__PURE__ */ new Map();
-  async function loadStyleImage(rel) {
+  async function loadStyleImage(rel, what = "Style image") {
     const abs = import_node_path5.default.resolve(root, rel);
     let hit = styleImageCache.get(abs);
     if (!hit) {
-      if (!(0, import_node_fs5.existsSync)(abs)) throw new Error(`Style image not found: ${abs}`);
+      if (!(0, import_node_fs5.existsSync)(abs)) throw new Error(`${what} not found: ${abs}`);
       const buf = await (0, import_promises3.readFile)(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);
@@ -5367,7 +5632,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
@@ -5584,43 +5849,34 @@ async function resolveStyleImages(loaded, styleId) {
 async function styleImagesBase64(loaded, styleId) {
   return (await resolveStyleImages(loaded, styleId)).map((img) => img.base64);
 }
-function imageMetadata(buf) {
-  if (buf.length >= 24 && buf.readUInt32BE(0) === 2303741511 && buf.readUInt32BE(4) === 218765834 && buf.toString("ascii", 12, 16) === "IHDR") {
-    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20), format: "png" };
-  }
-  if (buf.length < 4 || buf[0] !== 255 || buf[1] !== 216) return null;
-  let offset = 2;
-  while (offset + 3 < buf.length) {
-    if (buf[offset] !== 255) return null;
-    while (buf[offset] === 255) offset++;
-    const marker = buf[offset++];
-    if (marker == null || marker === 217 || marker === 218) break;
-    if (marker === 1 || marker >= 208 && marker <= 215) continue;
-    if (offset + 2 > buf.length) return null;
-    const length = buf.readUInt16BE(offset);
-    if (length < 2 || offset + length > buf.length) return null;
-    const isStartOfFrame = marker >= 192 && marker <= 207 && ![196, 200, 204].includes(marker);
-    if (isStartOfFrame) {
-      if (length < 7) return null;
-      return {
-        width: buf.readUInt16BE(offset + 5),
-        height: buf.readUInt16BE(offset + 3),
-        format: "jpeg"
-      };
-    }
-    offset += length;
-  }
-  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 } : {},
+    ...style.enhancePrompt !== void 0 ? { enhancePrompt: style.enhancePrompt } : {}
   };
+  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: import_node_path5.default.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,
@@ -5629,13 +5885,24 @@ function resolveCharacterShape(asset, style, kind) {
   }
   if (asset.animation) {
     const animationMode = asset.animation.mode ?? (asset.animation.template ? "template" : "v3");
+    const pose = async (rel, what) => {
+      const image = await files.load(rel, what);
+      return { path: import_node_path5.default.resolve(files.root, rel), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+    };
     shape.animation = {
       mode: animationMode,
       ...asset.animation.template ? { template: asset.animation.template } : {},
       direction: asset.animation.direction,
       frames: asset.animation.frames ?? 8,
       fps: asset.animation.fps,
-      keepFirstFrame: asset.animation.keepFirstFrame
+      keepFirstFrame: asset.animation.keepFirstFrame,
+      ...asset.animation.startFrame ? { startFrame: await pose(asset.animation.startFrame, "Animation start frame") } : {},
+      ...asset.animation.endFrame ? { endFrame: await pose(asset.animation.endFrame, "Animation end frame") } : {},
+      ...asset.animation.subject ? { subject: asset.animation.subject } : {},
+      ...asset.animation.outline ? { outline: asset.animation.outline } : {},
+      ...asset.animation.shading ? { shading: asset.animation.shading } : {},
+      ...asset.animation.detail ? { detail: asset.animation.detail } : {},
+      ...asset.animation.enhancePrompt !== void 0 ? { enhancePrompt: asset.animation.enhancePrompt } : {}
     };
   }
   return shape;
@@ -13898,10 +14165,12 @@ async function workspaceStatus(ws, dir) {
   BudgetError,
   CHARACTER_DIRECTIONS_4,
   CHARACTER_DIRECTIONS_8,
+  CHARACTER_PROPORTION_PRESETS,
   CharacterAnimationModeSchema,
   CharacterAnimationSchema,
   CharacterDirectionSchema,
   CharacterModeSchema,
+  CharacterProportionsSchema,
   CharacterStateSchema,
   ComfyUIProvider,
   DEFAULT_HISTORY_LIMIT,
@@ -14068,6 +14337,7 @@ async function workspaceStatus(ws, dir) {
   portableOutputPath,
   prepareReview,
   primaryOutput,
+  proportionsPayload,
   providerCredentialEnvs,
   providerFactory,
   pushTags,