pixelkiln 0.44.0 → 0.46.0

package/dist/index.js

@@ -90,7 +90,7 @@ var MIRRORED_DIRECTION = {
   west: "east",
   "south-west": "south-east"
 };
-var CharacterModeSchema = z.enum(["standard", "v3", "pro"]);
+var CharacterModeSchema = z.enum(["standard", "v3", "pro", "pro-flash"]);
 var CHARACTER_PROPORTION_PRESETS = ["default", "chibi", "cartoon", "stylized", "realistic_male", "realistic_female", "heroic"];
 var CharacterProportionsSchema = z.union([
   z.enum(CHARACTER_PROPORTION_PRESETS),
@@ -286,14 +286,27 @@ var StyleObjectSchema = z.object({
   /**
    * `character` only. `standard` draws from a skeleton template for 1
    * generation; `v3` is the highest quality at 2 to 9 by size; `pro` is a
-   * reference-based engine at 20 to 40 by size. States inherit the
-   * parent's engine; animations choose their own.
+   * reference-based engine at 20 to 40 by size; `pro-flash` draws a
+   * south sprite with PixelLab's newest image model and rotates it with
+   * v3, 6 to 17 by size, or the rotations alone (1 at 64px) from a
+   * `reference`. States inherit the parent's engine; animations choose
+   * their own.
    */
   mode: CharacterModeSchema.optional(),
-  /** `character` only. Rotations per base or state. `v3` and `pro` always draw 8. */
+  /** `character` only. Rotations per base or state. Every engine but `standard` draws 8. */
   directions: z.union([z.literal(4), z.literal(8)]).optional(),
-  /** `character` only. Body template: `mannequin` (default) or a quadruped (`bear`, `cat`, `dog`, `horse`, `lion`). */
+  /** `character` only. Body template: `mannequin` (default), a quadruped (`bear`, `cat`, `dog`, `horse`, `lion`), or `custom` for `pro-flash`. */
   template: z.string().min(1).optional(),
+  /**
+   * `character` only, `pro-flash` bases with a style image: which traits
+   * the style image lends. Each defaults to true.
+   */
+  styleTraits: z.object({
+    palette: z.boolean().optional(),
+    outline: z.boolean().optional(),
+    detail: z.boolean().optional(),
+    shading: z.boolean().optional()
+  }).strict().optional(),
   /** `character` only, `standard` humanoid bases. A preset or multipliers; an asset may override it. */
   proportions: CharacterProportionsSchema.optional(),
   /**
@@ -306,6 +319,12 @@ var StyleObjectSchema = z.object({
   isometric: z.boolean().optional(),
   /** `character` only, `v3` bases: let PixelLab expand the prompt into a fuller one before drawing. */
   enhancePrompt: z.boolean().optional(),
+  /**
+   * `character` only, `pro` bases: the asset id of a generated 8-direction
+   * character in this style whose look every base drawn from text or a
+   * concept follows. An asset may override it; the anchor itself ignores it.
+   */
+  styleCharacter: z.string().min(1).optional(),
   /** Fixed seed for reproducibility where the endpoint supports it. */
   seed: z.number().int().optional(),
   /**
@@ -478,6 +497,15 @@ var AssetSchema = z.object({
    * still guides the result.
    */
   reference: z.union([z.string().min(1), z.record(CharacterDirectionSchema, z.string().min(1))]).optional(),
+  /**
+   * `character` styles, `pro` bases only: a manifest-relative concept
+   * image (a painting, a photo, a sketch; up to 1024px) that seeds the
+   * design instead of the prompt alone. A style image or `styleCharacter`
+   * may still anchor the look.
+   */
+  concept: z.string().min(1).optional(),
+  /** `character` styles, `pro` bases: this base's style anchor, over the style's. */
+  styleCharacter: 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.
@@ -559,6 +587,20 @@ var AssetSchema = z.object({
       path: ["reference"]
     });
   }
+  if (asset.concept && (asset.state || asset.animation || asset.mirror)) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "a concept image belongs on a base; a state, animation, or mirror takes its look from its parent",
+      path: ["concept"]
+    });
+  }
+  if (asset.concept && asset.reference) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "concept and reference are mutually exclusive: a concept seeds a new design, a reference is the sprite to rotate",
+      path: ["concept"]
+    });
+  }
   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"] });
   }
@@ -1233,6 +1275,29 @@ var PixelLabClient = class {
         ...south ? { reference_image: encode(south) } : {},
         ...args.enhancePrompt ? { enhance_prompt: true } : {}
       };
+    } else if (args.mode === "pro-flash") {
+      path33 = "/create-character-pro-flash";
+      const traits = args.styleTraits;
+      body = {
+        description: args.description,
+        template_id: args.template,
+        n_directions: 8,
+        // The author's sprite sets the canvas; a size only applies to text creation.
+        ...south ? { first_frame: encode(south) } : { image_size: imageSize },
+        ...args.view ? { view: args.view } : {},
+        ...args.seed != null ? { seed: args.seed } : {},
+        ...args.styleReference && args.styleReferenceSize ? {
+          style_image: { image: encode(args.styleReference), size: args.styleReferenceSize },
+          ...traits ? {
+            style_options: {
+              ...traits.palette !== void 0 ? { color_palette: traits.palette } : {},
+              ...traits.outline !== void 0 ? { outline: traits.outline } : {},
+              ...traits.detail !== void 0 ? { detail: traits.detail } : {},
+              ...traits.shading !== void 0 ? { shading: traits.shading } : {}
+            }
+          } : {}
+        } : {}
+      };
     } else if (args.mode === "pro") {
       path33 = "/create-character-pro";
       body = {
@@ -1240,10 +1305,12 @@ var PixelLabClient = class {
         image_size: imageSize,
         template_id: args.template,
         no_background: args.noBackground ?? true,
-        method: south ? "rotate_character" : "create_with_style",
+        method: south ? "rotate_character" : args.concept ? "create_from_concept" : "create_with_style",
         ...args.view ? { view: args.view } : {},
         ...args.seed != null ? { seed: args.seed } : {},
-        ...south ? { reference_image: encode(south) } : args.styleReference ? { reference_image: encode(args.styleReference) } : {}
+        ...south ? { reference_image: encode(south) } : args.styleReference ? { reference_image: encode(args.styleReference) } : {},
+        ...!south && args.concept ? { concept_image: encode(args.concept) } : {},
+        ...!south && args.styleCharacterId ? { style_character_id: args.styleCharacterId } : {}
       };
     } else {
       path33 = args.directions === 4 ? "/create-character-with-4-directions" : "/create-character-with-8-directions";
@@ -2005,7 +2072,10 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         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
+        styleTraits: spec.character.styleTraits,
+        reference: spec.character.reference ? Object.fromEntries(Object.entries(spec.character.reference).map(([direction, image]) => [direction, image.sha256])) : void 0,
+        concept: spec.character.concept?.sha256,
+        styleAnchor: spec.character.styleAnchor ? { of: spec.character.styleAnchor.assetId, sha256: spec.character.styleAnchor.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.
@@ -2046,12 +2116,24 @@ function characterCost(spec) {
   if (character.kind === "state") return generationCost(spec.width, spec.height, "1dir");
   if (character.mode === "standard") return 1;
   if (character.mode === "v3") return 1 + Math.max(1, Math.ceil(px * 8 / 65536));
+  if (character.mode === "pro-flash") {
+    const south = character.reference?.south;
+    return south ? proFlashCharacterCost(south.width, south.height, true) : proFlashCharacterCost(spec.width, spec.height, false);
+  }
   return generationCost(spec.width, spec.height, "1dir");
 }
+function proFlashCharacterCost(width, height, fromReference) {
+  const side = Math.max(32, Math.ceil(Math.max(width, height) / 4) * 4);
+  const rotations = Math.max(1, Math.ceil(side * side * 8 / 65536));
+  if (fromReference) return rotations;
+  const image = side <= 96 ? 5 : side <= 208 ? 6 : 9;
+  return image + rotations;
+}
 function characterAnimationName(spec) {
   return `pixelkiln:${spec.styleId}/${spec.assetId}`;
 }
 var CHARACTER_TEMPLATES = ["mannequin", "bear", "cat", "dog", "horse", "lion"];
+var PRO_FLASH_TEMPLATES = [...CHARACTER_TEMPLATES, "custom"];
 function encodeAnimationJob(job) {
   return `character-animation:${Buffer.from(JSON.stringify(job)).toString("base64url")}`;
 }
@@ -2192,12 +2274,25 @@ var PixelLabProvider = class _PixelLabProvider {
         }
       }
     }
+    if (character.concept) {
+      if (character.mode !== "pro") throw new Error(`${label}: a concept image is a pro input; the ${character.mode} engine draws from text or a reference`);
+      if (character.concept.width > 1024 || character.concept.height > 1024) {
+        throw new Error(`${label}: concept image is ${character.concept.width}x${character.concept.height}; PixelLab pro takes up to 1024px`);
+      }
+    }
+    if (character.styleAnchor) {
+      if (character.mode !== "pro") throw new Error(`${label}: styleCharacter is a pro input; the ${character.mode} engine has no style anchor`);
+      if (character.reference) throw new Error(`${label}: a pro base rotating its own reference takes no styleCharacter`);
+      if (character.styleAnchor.spec.character?.directions !== 8) {
+        throw new Error(`${label}: styleCharacter ${character.styleAnchor.assetId} has ${character.styleAnchor.spec.character?.directions} directions; PixelLab wants an 8-direction anchor`);
+      }
+    }
     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 limit = character.mode === "pro" ? 168 : 256;
         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`);
@@ -2221,26 +2316,39 @@ var PixelLabProvider = class _PixelLabProvider {
       }
     }
     if (styleImages.length) {
-      if (character.mode !== "pro") {
+      if (character.mode !== "pro" && character.mode !== "pro-flash") {
         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`
+          `PixelLab ${character.mode} characters take no style images; give a base its own sprite with \`reference\`, or use mode pro or pro-flash for a style anchor`
         );
       }
-      if (styleImages.length > 1) throw new Error("PixelLab pro characters take one style image");
+      if (styleImages.length > 1) throw new Error(`PixelLab ${character.mode} 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`);
+        throw new Error(`${label}: a ${character.mode} 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 limit = character.mode === "pro" ? 168 : 256;
+      if (image.width > limit || image.height > limit) {
+        throw new Error(`PixelLab ${character.mode} character style image is ${image.width}x${image.height}; the limit is ${limit}px`);
+      }
+      if (character.mode === "pro-flash" && (image.width > spec.width || image.height > spec.height)) {
+        throw new Error(
+          `PixelLab pro-flash style image is ${image.width}x${image.height} but the character is ${spec.width}x${spec.height}; crop the image to its subject or raise the style's size`
+        );
       }
     }
-    const maxSize = character.mode === "v3" ? 256 : 128;
+    if (character.styleTraits && character.mode !== "pro-flash") {
+      throw new Error(`${label}: styleTraits choose what a pro-flash style image lends; the ${character.mode} engine does not take them`);
+    }
+    const maxSize = character.mode === "v3" || character.mode === "pro-flash" ? 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`);
     }
-    if (!CHARACTER_TEMPLATES.includes(character.template)) {
-      throw new Error(`PixelLab character template must be one of: ${CHARACTER_TEMPLATES.join(", ")}`);
+    if (character.mode === "pro-flash" && character.kind === "base" && (spec.width % 4 || spec.height % 4)) {
+      throw new Error(`PixelLab pro-flash characters are sized in multiples of 4 pixels; ${spec.width}x${spec.height} is not`);
+    }
+    const templates = character.mode === "pro-flash" ? PRO_FLASH_TEMPLATES : CHARACTER_TEMPLATES;
+    if (!templates.includes(character.template)) {
+      throw new Error(`PixelLab ${character.mode} character template must be one of: ${templates.join(", ")}`);
     }
     const views = character.mode === "standard" ? ["low top-down", "high top-down", "side", "perspective", "oblique"] : ["low top-down", "high top-down", "side"];
     if (!views.includes(spec.view)) {
@@ -2293,7 +2401,11 @@ var PixelLabProvider = class _PixelLabProvider {
         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
+        enhancePrompt: character.enhancePrompt,
+        concept: character.concept ? readPose(spec, "concept image", character.concept) : void 0,
+        styleCharacterId: character.styleAnchor ? requireStyleObjectId(spec, context) : void 0,
+        styleReferenceSize: styleImage ? { width: styleImage.width, height: styleImage.height } : void 0,
+        styleTraits: character.styleTraits
       });
       return { jobId: res2.character_id, metadata: { character: { kind: "base", characterId: res2.character_id, mode: character.mode, directions: character.directions, backgroundJobId: res2.background_job_id } } };
     }
@@ -2713,6 +2825,14 @@ function readReference(spec, reference) {
   }
   return images;
 }
+function requireStyleObjectId(spec, context) {
+  if (!context?.styleObjectId) {
+    throw new Error(
+      `${spec.styleId}/${spec.assetId} anchors its style on ${spec.character.styleAnchor.assetId}, which has no PixelLab character id in the lockfile yet; generate the anchor first`
+    );
+  }
+  return context.styleObjectId;
+}
 function readPose(spec, what, image) {
   const bytes = readFileSync(image.path);
   if (sha256(bytes) !== image.sha256) {
@@ -5412,6 +5532,18 @@ async function resolveSpecs(loaded, filter) {
         finalized.add(assetId);
         return resolved;
       }
+      const anchorId = asset.styleCharacter ?? style.styleCharacter;
+      if (resolved.character?.kind === "base" && anchorId && anchorId !== assetId) {
+        const anchorSpec = await finalize(anchorId);
+        if (!anchorSpec.character || anchorSpec.character.kind === "animation") {
+          throw new Error(`assets.${assetId}: styleCharacter ${anchorId} is not a character base or state`);
+        }
+        const file = memberPath(anchorSpec.outFile, "south", 0, anchorSpec.character.directions, MediaType.PNG);
+        resolved.character = {
+          ...resolved.character,
+          styleAnchor: { assetId: anchorId, spec: anchorSpec, file, sha256: existsSync4(file) ? await sha256File(file) : null }
+        };
+      }
       const characterParent = asset.state?.of ?? asset.animation?.of;
       if (resolved.character && characterParent) {
         const parentSpec = await finalize(characterParent);
@@ -5562,8 +5694,13 @@ async function resolveCharacterShape(asset, style, kind, files) {
     ...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 } : {}
+    ...style.enhancePrompt !== void 0 ? { enhancePrompt: style.enhancePrompt } : {},
+    ...style.styleTraits ? { styleTraits: style.styleTraits } : {}
   };
+  if (asset.concept) {
+    const image = await files.load(asset.concept, "Concept image");
+    shape.concept = { path: path5.resolve(files.root, asset.concept), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+  }
   if (asset.reference) {
     const byDirection = typeof asset.reference === "string" ? { south: asset.reference } : asset.reference;
     shape.reference = {};
@@ -7083,9 +7220,24 @@ import path11 from "path";
 async function inspectRevisionReadiness(spec, lock) {
   if (spec.mirror) return inspectMirror(spec, lock, /* @__PURE__ */ new Set());
   if (spec.character?.parentSpec) return inspectCharacterParent(spec, lock, /* @__PURE__ */ new Set());
+  if (spec.character?.styleAnchor) return inspectStyleAnchor(spec, lock, /* @__PURE__ */ new Set());
   if (!spec.revision) return null;
   return inspectRevision(spec, lock, /* @__PURE__ */ new Set());
 }
+async function inspectStyleAnchor(spec, lock, seen) {
+  const anchor = spec.character.styleAnchor;
+  const label = `style anchor ${spec.styleId}/${anchor.assetId}`;
+  const dependency = await inspectParent(anchor.spec, lock, seen);
+  if (!dependency.ready) return { ready: false, reason: `${label} is not ready: ${dependency.reason}` };
+  if (!anchor.sha256 || !existsSync7(anchor.file)) return { ready: false, reason: `${label} has no generated south-facing file yet` };
+  if (await sha256File(anchor.file) !== anchor.sha256) {
+    return { ready: false, reason: `${label} changed after the manifest was resolved` };
+  }
+  if (!lock.entries[lockKey(anchor.spec.styleId, anchor.spec.assetId)]?.objectId) {
+    return { ready: false, reason: `${label} has no PixelLab character id recorded` };
+  }
+  return { ready: true, reason: `${label} is current` };
+}
 async function inspectMirror(spec, lock, seen) {
   const source = spec.mirror.sourceSpec;
   const label = `mirror source ${spec.styleId}/${spec.mirror.sourceAssetId}`;
@@ -7157,6 +7309,10 @@ async function inspectParent(spec, lock, seen) {
     const inputs = await inspectCharacterParent(spec, lock, nextSeen);
     if (!inputs.ready) return inputs;
   }
+  if (spec.character?.styleAnchor) {
+    const inputs = await inspectStyleAnchor(spec, lock, nextSeen);
+    if (!inputs.ready) return inputs;
+  }
   if (spec.quality) {
     const quality = await inspectQualityProfile(spec, lock);
     return quality?.state === "approved" ? { ready: true, reason: "approved quality output is current" } : {
@@ -7196,6 +7352,14 @@ async function anyOutputModified(entry, spec) {
   }
   return false;
 }
+function dependencies(spec) {
+  return [
+    spec.mirror?.sourceSpec,
+    spec.revision?.sourceSpec,
+    spec.character?.parentSpec,
+    spec.character?.styleAnchor?.spec
+  ].filter((parent) => Boolean(parent));
+}
 function resumeCommandForStatus(status) {
   if (status === "pending" || status === "processing") return "poll";
   if (status === "review") return "pick";
@@ -7304,16 +7468,19 @@ async function buildPlan(specs, lock, opts = {}) {
   const stateOf = new Map(items.map((i) => [i.key, i.state]));
   for (const item of items) {
     if (!isActionable(item)) continue;
-    const parent = item.spec.mirror?.sourceSpec ?? item.spec.revision?.sourceSpec ?? item.spec.character?.parentSpec;
-    if (!parent) continue;
-    const parentKey = lockKey(parent.styleId, parent.assetId);
-    const parentState = stateOf.get(parentKey);
-    if (parentState && isActionable({ state: parentState })) {
-      item.state = "blocked";
-      item.reason = `parent ${parentKey} is being generated in this run; this follows in the next wave`;
-    } else if (item.spec.mirror && (parentState === "recoverable" || parentState === "in-flight")) {
-      item.state = "blocked";
-      item.reason = `mirror source ${parentKey} is ${parentState}; this follows in the next wave`;
+    for (const parent of dependencies(item.spec)) {
+      const parentKey = lockKey(parent.styleId, parent.assetId);
+      const parentState = stateOf.get(parentKey);
+      if (parentState && isActionable({ state: parentState })) {
+        item.state = "blocked";
+        item.reason = `parent ${parentKey} is being generated in this run; this follows in the next wave`;
+        break;
+      }
+      if (item.spec.mirror && (parentState === "recoverable" || parentState === "in-flight")) {
+        item.state = "blocked";
+        item.reason = `mirror source ${parentKey} is ${parentState}; this follows in the next wave`;
+        break;
+      }
     }
   }
   const actionable = items.filter(isActionable);
@@ -9792,10 +9959,13 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
     try {
       const refs = styleImages.get(spec.styleId) ?? [];
       const parentEntry = spec.character?.parentSpec ? lock.entries[lockKey(spec.character.parentSpec.styleId, spec.character.parentSpec.assetId)] : void 0;
+      const anchor = spec.character?.styleAnchor;
+      const anchorEntry = anchor ? lock.entries[lockKey(anchor.spec.styleId, anchor.spec.assetId)] : void 0;
       const replacedMetadata = previousEntry?.providerMetadata?.[provider.id];
       const { jobId, metadata } = await provider.submit(spec, refs, {
         ...previousJobId ? { previousJobId } : {},
         ...parentEntry?.objectId ? { parentObjectId: parentEntry.objectId } : {},
+        ...anchorEntry?.objectId ? { styleObjectId: anchorEntry.objectId } : {},
         ...replacedMetadata ? { replacedMetadata } : {},
         ...previousMetadata ? { previousMetadata } : {},
         checkpoint: async (checkpoint) => {
@@ -12404,7 +12574,7 @@ var pin_default = {
   godot: "4.7.2",
   extensionsApi: 9,
   protocol: 4,
-  release: "editor-pixelorama-v1.2.2-pk.18",
+  release: "editor-pixelorama-v1.2.2-pk.26",
   files: {
     "index.apple-touch-icon.png": {
       sha256: "ee5434873e0fed91e9a888c3ea5a8b79beac25999308be7a6eb41bf4ce640d27",
@@ -12419,7 +12589,7 @@ var pin_default = {
       bytes: 7298
     },
     "index.html": {
-      sha256: "d9adf06036660c4b76ef5386e872bc03dc0d5b0628fd6ac660d480893ee1f47a",
+      sha256: "326101ab02bb4a29a7964214c9307c7dff26e9d66b8ebaaf6e7a3987e84a05b2",
       bytes: 5442
     },
     "index.icon.png": {
@@ -12431,8 +12601,8 @@ var pin_default = {
       bytes: 279815
     },
     "index.pck": {
-      sha256: "a41d9c3a39aa99ea5ee49ddcedfeb8b092006aa75c0de67139f13297c17f42e4",
-      bytes: 6431692
+      sha256: "e26292650bb996965acd1ba70e74d2b4020b063d14f1276701312c1d34cb0a83",
+      bytes: 6431932
     },
     "index.png": {
       sha256: "6e3ca3eb4a99e4c07bdd89ebc873b440ec0ffd66ce1955160da9e7ed80d538d7",