pixelkiln 0.43.0 → 0.44.0

package/dist/index.cjs

@@ -427,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,
@@ -569,6 +603,8 @@ var StyleObjectSchema = import_zod.z.object({
   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(),
   /**
@@ -1493,7 +1529,8 @@ var PixelLabClient = class {
         ...args.outline ? { outline: args.outline } : {},
         ...args.detail ? { detail: args.detail } : {},
         ...args.seed != null ? { seed: args.seed } : {},
-        ...south ? { reference_image: encode(south) } : {}
+        ...south ? { reference_image: encode(south) } : {},
+        ...args.enhancePrompt ? { enhance_prompt: true } : {}
       };
     } else if (args.mode === "pro") {
       path33 = "/create-character-pro";
@@ -1550,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({
@@ -1559,10 +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 } : {}
       })
     });
@@ -2159,6 +2205,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/providers/pixellab.ts
 var import_node_fs2 = require("fs");
@@ -2219,11 +2293,17 @@ 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
@@ -2392,6 +2472,25 @@ var PixelLabProvider = class _PixelLabProvider {
         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`);
@@ -2492,7 +2591,8 @@ var PixelLabProvider = class _PixelLabProvider {
         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
+        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 } } };
     }
@@ -2536,7 +2636,15 @@ var PixelLabProvider = class _PixelLabProvider {
       directions: [animation.direction],
       seed: spec.seed,
       textGuidanceScale: character.textGuidanceScale,
-      isometric: character.isometric
+      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 {
@@ -2904,6 +3012,13 @@ function readReference(spec, reference) {
   }
   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 = [];
@@ -5734,34 +5849,6 @@ 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;
-}
 async function resolveCharacterShape(asset, style, kind, files) {
   const mode2 = style.mode ?? "standard";
   const directions = mode2 === "standard" ? style.directions ?? 8 : 8;
@@ -5773,7 +5860,8 @@ async function resolveCharacterShape(asset, style, kind, files) {
     template: style.template ?? "mannequin",
     ...proportions !== void 0 ? { proportions } : {},
     ...style.textGuidanceScale !== void 0 ? { textGuidanceScale: style.textGuidanceScale } : {},
-    ...style.isometric !== void 0 ? { isometric: style.isometric } : {}
+    ...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;
@@ -5797,13 +5885,24 @@ async function resolveCharacterShape(asset, style, kind, files) {
   }
   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;