pixelkiln 0.42.0 → 0.44.0

package/dist/cli.js

@@ -665,7 +665,18 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         parent: spec.character.parentAssetId,
         parentSha256: spec.character.parentSha256 ?? null,
         state: spec.character.state,
-        animation: spec.character.animation
+        // 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.
@@ -783,6 +794,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. */
@@ -809,11 +831,45 @@ var CharacterAnimationSchema = z.object({
   /** v3 only: keep the resting pose as frame 0, so `frames` generated frames land as `frames + 1` files. */
   keepFirstFrame: 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: 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: z.string().min(1).optional(),
+  /** What is being animated, when the character's own description would mislead the model. */
+  subject: z.string().min(1).optional(),
+  /** Template mode only: style hints for this loop, over the character's own. */
+  outline: z.string().min(1).optional(),
+  shading: z.string().min(1).optional(),
+  detail: z.string().min(1).optional(),
+  /** v3 text loops only: let PixelLab expand the action into a fuller motion description first. */
+  enhancePrompt: z.boolean().optional()
 }).strict().superRefine((animation, context) => {
   if (animation.frames !== void 0 && animation.frames % 2 !== 0) {
     context.addIssue({ code: 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: 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: z.ZodIssueCode.custom, message: `${key} overrides apply to template loops only`, path: [key] });
+    }
+  }
   if (animation.template && animation.mode && animation.mode !== "template") {
     context.addIssue({
       code: z.ZodIssueCode.custom,
@@ -941,6 +997,18 @@ 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(),
+  /** `character` only, `v3` bases: let PixelLab expand the prompt into a fuller one before drawing. */
+  enhancePrompt: z.boolean().optional(),
   /** Fixed seed for reproducibility where the endpoint supports it. */
   seed: z.number().int().optional(),
   /**
@@ -1100,6 +1168,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 +1255,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);
@@ -1965,6 +2056,34 @@ 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/outputs.ts
 import { existsSync as existsSync2 } from "fs";
@@ -5016,6 +5135,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 +5354,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 +5377,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") {
       path45 = "/create-character-pro";
@@ -5249,8 +5388,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 +5404,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
       };
     }
@@ -5291,6 +5436,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({
@@ -5300,8 +5446,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 } : {}
       })
     });
@@ -5498,8 +5654,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 +5671,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 && existsSync7(character.parentFile) ? imageMetadata(readFileSync2(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`);
@@ -5553,10 +5780,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 +5797,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 } } };
     }
@@ -5611,7 +5845,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 {
@@ -5701,7 +5945,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 +6212,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 = 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 readPose(spec, what, image) {
+  const bytes = readFileSync2(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 = [];
@@ -7087,16 +7349,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 +7465,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
@@ -7417,43 +7679,34 @@ async function resolveStyleImages(loaded, styleId) {
   }
   return out;
 }
-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: 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,
@@ -7462,13 +7715,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: path13.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;