pixelkiln 0.68.1 → 0.69.0

package/README.md

@@ -55,7 +55,7 @@ provenance and no long-lived npm token.
 | Hand edits | Touch-ups in your own editor or a pinned in-browser Pixelorama, kept beside the generated art with the generation still the record; frame and tile sets member by member. |
 | Controlled inputs | Hashed revision lineage (image-to-image and inpaint; on PixelLab also palette reduction, pixel cleanup, animation, skeleton posing, interpolation, and animation edits), fail-closed parent approval, source-versus-candidate review, and content-addressed per-asset ComfyUI bindings. |
 | Characters | A base in 4 or 8 directions from a prompt or your own sprite (four PixelLab engines), poses, loops, portraits, and outfit transfers as dependent assets generated in waves, free mirrored directions (one `directions` list declares a loop and mirrors the rest), account adoption and salvage, and SpriteFrames export. |
-| PixelLab utilities | `unzoom` returns upscaled reference art to its native grid, `font` generates a `.ttf` and glyph atlas, and `estimate-skeleton` starts a keypoints file for skeleton animation. |
+| PixelLab utilities | `unzoom` returns upscaled reference art to its native grid, `font` generates a `.ttf` and glyph atlas, `estimate-skeleton` starts a keypoints file for skeleton animation, and `skeleton-preview` draws its poses over the sprite for free. |
 | Existing-art onboarding | Manifest scaffolding, exact-hash account adoption, and prompt recovery. |
 | Recovery | Safe stale-output replacement, validated caches, durable references, resumable paid jobs, and per-asset generation history with free restores. |
 | Shared-account safety | Cross-project claim files or a registered workspace catalog, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |

package/dist/cli.js

@@ -67,7 +67,7 @@ function exitCodeFor(err) {
 }
 
 // src/cli/main.ts
-import { existsSync as existsSync33 } from "fs";
+import { existsSync as existsSync34 } from "fs";
 import { readFile as readFile31 } from "fs/promises";
 
 // src/cli/args.ts
@@ -107,7 +107,8 @@ var VALUE_FLAGS = [
   "--quantize",
   "--description",
   "--weight",
-  "--glyph-px"
+  "--glyph-px",
+  "--frames"
 ];
 var BOOL_FLAGS = [
   "--force",
@@ -158,6 +159,7 @@ var COMMANDS = [
   "recipe",
   "workspace",
   "estimate-skeleton",
+  "skeleton-preview",
   "unzoom",
   "font",
   "help",
@@ -256,6 +258,12 @@ function parseArgs(argv) {
     target = rest[0]?.startsWith("-") ? void 0 : rest[0];
     if (target === void 0) throw new UsageError("estimate-skeleton needs an image path");
     rest = rest.slice(1);
+  } else if (command === "skeleton-preview") {
+    target = rest[0]?.startsWith("-") ? void 0 : rest[0];
+    if (target === void 0) {
+      throw new UsageError("skeleton-preview needs a keypoints file or an animate-skeleton asset id");
+    }
+    rest = rest.slice(1);
   } else if (command === "refine") {
     subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "run" : rest[0];
     if (!REFINE_SUBCOMMANDS.includes(subcommand)) {
@@ -421,7 +429,8 @@ function parseArgs(argv) {
     quantize: numberOption("--quantize", { min: -1, max: 256, integer: true }),
     description: get("--description"),
     weight: get("--weight"),
-    glyphPx: numberOption("--glyph-px", { min: 8, max: 64, integer: true })
+    glyphPx: numberOption("--glyph-px", { min: 8, max: 64, integer: true }),
+    frames: numberOption("--frames", { min: 3, max: 15, integer: true })
   };
 }
 
@@ -461,11 +470,16 @@ Commands
             first. Local art is untouched.
   tag       Push manifest tags to the objects upstream (free).
   balance   Show the provider's remaining balance.
-  estimate-skeleton <image> [--out <file>]
-            PixelLab only: derive an 18-joint skeleton from an image, direct
-            and un-budgeted (like balance, not a generation). Prints the
-            keypoints JSON, or writes it with --out \u2014 the way to bootstrap
-            an animate-skeleton revision's keypointsFile.
+  estimate-skeleton <image> [--out <file>] [--frames <n>] [--force]
+            PixelLab only: derive an 18-joint skeleton from a square 16-256px
+            image, direct and un-budgeted (like balance, not a generation).
+            Prints, or writes with --out, a ready keypoints file for an
+            animate-skeleton revision: the estimated pose plus --frames copies
+            (default 4) to edit. --out refuses to replace a file without --force.
+  skeleton-preview <keypoints.json | asset> [--from <image>] [--out <file>]
+            Draw every pose of a keypoints file over its source image as one
+            PNG, locally and free. Given an animate-skeleton asset id, reads
+            its keypointsFile and source from the manifest.
   status    Summarise the lockfile.
   edit      Hand-edit an asset in your own editor: copies the generated PNG to
             <outDir>/edits/, declares it as the asset's source, and opens it.
@@ -5756,14 +5770,61 @@ import { z as z3 } from "zod";
 
 // src/skeleton.ts
 import { z as z2 } from "zod";
+var SKELETON_LABELS = [
+  "NOSE",
+  "NECK",
+  "RIGHT SHOULDER",
+  "RIGHT ELBOW",
+  "RIGHT ARM",
+  "LEFT SHOULDER",
+  "LEFT ELBOW",
+  "LEFT ARM",
+  "RIGHT HIP",
+  "RIGHT KNEE",
+  "RIGHT LEG",
+  "LEFT HIP",
+  "LEFT KNEE",
+  "LEFT LEG",
+  "RIGHT EYE",
+  "LEFT EYE",
+  "RIGHT EAR",
+  "LEFT EAR"
+];
+var SKELETON_BONES = [
+  ["NOSE", "NECK"],
+  ["NECK", "RIGHT SHOULDER"],
+  ["RIGHT SHOULDER", "RIGHT ELBOW"],
+  ["RIGHT ELBOW", "RIGHT ARM"],
+  ["NECK", "LEFT SHOULDER"],
+  ["LEFT SHOULDER", "LEFT ELBOW"],
+  ["LEFT ELBOW", "LEFT ARM"],
+  ["NECK", "RIGHT HIP"],
+  ["RIGHT HIP", "RIGHT KNEE"],
+  ["RIGHT KNEE", "RIGHT LEG"],
+  ["NECK", "LEFT HIP"],
+  ["LEFT HIP", "LEFT KNEE"],
+  ["LEFT KNEE", "LEFT LEG"],
+  ["NOSE", "RIGHT EYE"],
+  ["RIGHT EYE", "RIGHT EAR"],
+  ["NOSE", "LEFT EYE"],
+  ["LEFT EYE", "LEFT EAR"]
+];
 var SkeletonKeypointSchema = z2.object({
-  label: z2.string().min(1),
+  label: z2.enum(SKELETON_LABELS),
   x: z2.number().min(0).max(1),
   y: z2.number().min(0).max(1),
   z_index: z2.number(),
   depth: z2.number().optional()
 }).strict();
-var SkeletonFrameSchema = z2.array(SkeletonKeypointSchema).length(18);
+var SkeletonFrameSchema = z2.array(SkeletonKeypointSchema).length(18).superRefine((frame, context) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, joint] of frame.entries()) {
+    if (seen.has(joint.label)) {
+      context.addIssue({ code: z2.ZodIssueCode.custom, message: `"${joint.label}" appears twice`, path: [index, "label"] });
+    }
+    seen.add(joint.label);
+  }
+});
 var SkeletonSetSchema = z2.object({
   firstFrameKeypoints: SkeletonFrameSchema,
   frames: z2.array(SkeletonFrameSchema).min(3).max(15)
@@ -5776,6 +5837,11 @@ function parseSkeletonSet(json, file) {
   }
   return result.data;
 }
+var DEFAULT_SCAFFOLD_FRAMES = 4;
+function scaffoldSkeletonSet(keypoints, frames = DEFAULT_SCAFFOLD_FRAMES) {
+  const copy = () => keypoints.map((joint) => ({ ...joint }));
+  return { firstFrameKeypoints: copy(), frames: Array.from({ length: frames }, copy) };
+}
 
 // src/client.ts
 var BASE = process.env.PIXELLAB_API_BASE ?? "https://api.pixellab.ai/v2";
@@ -7128,7 +7194,7 @@ var PixelLabClient = class {
    * account (see `EstimateSkeletonResponseSchema`'s own caveat).
    */
   async estimateSkeleton(args) {
-    const body = { image: args.image };
+    const body = { image: { type: "base64", base64: args.image.base64, format: args.image.format } };
     const res = validateResponse(
       EstimateSkeletonResponseSchema,
       await this.request("/estimate-skeleton", { method: "POST", body: JSON.stringify(body) }),
@@ -20537,27 +20603,192 @@ async function runRefine(args) {
 
 // src/cli/commands/skeleton.ts
 import path46 from "path";
+import { existsSync as existsSync32 } from "fs";
 import { readFile as readFile30, writeFile as writeFile15 } from "fs/promises";
+
+// src/skeleton-preview.ts
+var RIGHT = [255, 140, 40, 255];
+var LEFT = [60, 150, 255, 255];
+var CENTER = [240, 240, 240, 255];
+var GROUND = [28, 28, 34, 255];
+var OUTLINE = [0, 0, 0, 255];
+var GUTTER = 4;
+var MIN_CELL = 192;
+function renderSkeletonSheet(set, options = {}) {
+  const poses = [set.firstFrameKeypoints, ...set.frames];
+  const source = options.source;
+  const scale = source ? Math.max(1, Math.ceil(MIN_CELL / Math.max(source.width, source.height))) : 1;
+  const cellW = source ? source.width * scale : options.cellSize ?? MIN_CELL;
+  const cellH = source ? source.height * scale : options.cellSize ?? MIN_CELL;
+  const columns = Math.min(options.columns ?? 8, poses.length);
+  const rows = Math.ceil(poses.length / columns);
+  const width = columns * cellW + (columns + 1) * GUTTER;
+  const height = rows * cellH + (rows + 1) * GUTTER;
+  const canvas = new Canvas(width, height);
+  canvas.fill(0, 0, width, height, [12, 12, 16, 255]);
+  poses.forEach((pose, index) => {
+    const left = GUTTER + index % columns * (cellW + GUTTER);
+    const top = GUTTER + Math.floor(index / columns) * (cellH + GUTTER);
+    canvas.fill(left, top, cellW, cellH, GROUND);
+    if (source) canvas.drawImage(source, left, top, scale, index === 0 ? 1 : 0.45);
+    drawPose(canvas, pose, left, top, cellW, cellH, Math.max(1, Math.round(Math.min(cellW, cellH) / 128)));
+  });
+  return encodeRgbaPng(width, height, canvas.data);
+}
+function drawPose(canvas, pose, left, top, w, h, stroke) {
+  const at = new Map(pose.map((joint) => [joint.label, joint]));
+  const point = (joint) => [left + joint.x * (w - 1), top + joint.y * (h - 1)];
+  for (const outline of [true, false]) {
+    for (const [from, to] of SKELETON_BONES) {
+      const a = at.get(from);
+      const b = at.get(to);
+      if (!a || !b) continue;
+      const [x0, y0] = point(a);
+      const [x1, y1] = point(b);
+      canvas.line(x0, y0, x1, y1, outline ? OUTLINE : colorOf(to), outline ? stroke + 2 : stroke);
+    }
+    for (const joint of pose) {
+      const [x, y] = point(joint);
+      canvas.dot(x, y, outline ? stroke + 3 : stroke + 1, outline ? OUTLINE : colorOf(joint.label));
+    }
+  }
+}
+function colorOf(label) {
+  if (label.startsWith("RIGHT")) return RIGHT;
+  if (label.startsWith("LEFT")) return LEFT;
+  return CENTER;
+}
+var Canvas = class {
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+    this.data = Buffer.alloc(width * height * 4);
+  }
+  width;
+  height;
+  data;
+  set(x, y, [r, g, b, a]) {
+    const px = Math.round(x);
+    const py = Math.round(y);
+    if (px < 0 || py < 0 || px >= this.width || py >= this.height) return;
+    const i = (py * this.width + px) * 4;
+    this.data[i] = r;
+    this.data[i + 1] = g;
+    this.data[i + 2] = b;
+    this.data[i + 3] = a;
+  }
+  fill(x, y, w, h, color) {
+    for (let dy = 0; dy < h; dy++) for (let dx = 0; dx < w; dx++) this.set(x + dx, y + dy, color);
+  }
+  /** Nearest-neighbour upscale, composited over what is there, at `strength`. */
+  drawImage(image, left, top, scale, strength) {
+    for (let y = 0; y < image.height; y++) {
+      for (let x = 0; x < image.width; x++) {
+        const i = (y * image.width + x) * 4;
+        const alpha = image.pixels[i + 3] / 255 * strength;
+        if (alpha === 0) continue;
+        const src = [image.pixels[i], image.pixels[i + 1], image.pixels[i + 2]];
+        for (let dy = 0; dy < scale; dy++) {
+          for (let dx = 0; dx < scale; dx++) {
+            const o = ((top + y * scale + dy) * this.width + left + x * scale + dx) * 4;
+            for (let c = 0; c < 3; c++) this.data[o + c] = Math.round(src[c] * alpha + this.data[o + c] * (1 - alpha));
+          }
+        }
+      }
+    }
+  }
+  line(x0, y0, x1, y1, color, stroke) {
+    const steps = Math.max(1, Math.ceil(Math.max(Math.abs(x1 - x0), Math.abs(y1 - y0))));
+    for (let step = 0; step <= steps; step++) {
+      const t = step / steps;
+      this.dot(x0 + (x1 - x0) * t, y0 + (y1 - y0) * t, stroke, color);
+    }
+  }
+  /** A filled square `size` wide centred on (x, y): crisp at pixel-art scale. */
+  dot(x, y, size, color) {
+    const half = Math.floor(size / 2);
+    for (let dy = -half; dy < size - half; dy++) for (let dx = -half; dx < size - half; dx++) this.set(x + dx, y + dy, color);
+  }
+};
+
+// src/cli/commands/skeleton.ts
+var ESTIMATE_SKELETON_SIZES = [16, 32, 64, 128, 256];
 async function runEstimateSkeleton(args) {
   const image = args.target;
   if (!image) throw new UsageError("estimate-skeleton needs an image path: pixelkiln estimate-skeleton <image> [--out keypoints.json]");
+  if (args.out && existsSync32(path46.resolve(args.out)) && !args.force) {
+    throw new UsageError(`${args.out} already exists; pass --force to replace it`);
+  }
   loadEnvFiles(path46.dirname(path46.resolve(args.manifest)));
   loadEnvFiles(process.cwd());
   const bytes = await readFile30(path46.resolve(image));
   const metadata = imageMetadata(bytes);
   if (!metadata) throw new UsageError(`${image} is not a readable PNG or JPEG`);
+  if (metadata.width !== metadata.height || !ESTIMATE_SKELETON_SIZES.includes(metadata.width)) {
+    throw new UsageError(
+      `${image} is ${metadata.width}x${metadata.height}; estimate-skeleton takes a square image of ${ESTIMATE_SKELETON_SIZES.join(", ")} pixels`
+    );
+  }
   const client2 = clientFromEnv();
   const res = await client2.estimateSkeleton({
     image: { base64: bytes.toString("base64"), format: metadata.format }
   });
-  const json = JSON.stringify(res.keypoints, null, 2);
+  const frames = args.frames ?? DEFAULT_SCAFFOLD_FRAMES;
+  const json = JSON.stringify(scaffoldSkeletonSet(res.keypoints, frames), null, 2);
   if (args.out) {
     await writeFile15(path46.resolve(args.out), json + "\n");
-    log(`  wrote ${res.keypoints.length} keypoints to ${args.out}`);
+    log(`  wrote ${args.out}: the estimated pose and ${frames} frames to edit`);
+    log(`  preview it with: pixelkiln skeleton-preview ${args.out} --from ${image}`);
   } else {
     log(json);
   }
 }
+async function runSkeletonPreview(args) {
+  const target = args.target;
+  let keypointsFile;
+  let sourceFile;
+  let label;
+  if (target.endsWith(".json")) {
+    keypointsFile = path46.resolve(target);
+    sourceFile = args.from ? path46.resolve(args.from) : void 0;
+    label = target;
+  } else {
+    const loaded = await loadManifest(args.manifest);
+    const specs = (await resolveSpecs(loaded, { styles: args.styles, assets: [target] })).filter((spec2) => spec2.assetId === target);
+    const spec = specs.find((candidate) => candidate.revision?.mode === "animate-skeleton");
+    if (!spec) {
+      throw new UsageError(
+        specs.length ? `${target} is not an animate-skeleton revision; pass a keypoints file instead` : `No asset "${target}" in ${args.manifest}`
+      );
+    }
+    keypointsFile = spec.revision.keypointsFile;
+    sourceFile = args.from ? path46.resolve(args.from) : spec.revision.sourceFile;
+    label = `${spec.styleId}/${spec.assetId}`;
+  }
+  if (!existsSync32(keypointsFile)) throw new UsageError(`Keypoints file does not exist yet: ${keypointsFile}`);
+  let json;
+  try {
+    json = JSON.parse(await readFile30(keypointsFile, "utf8"));
+  } catch (error) {
+    throw new UsageError(`${keypointsFile} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const set = parseSkeletonSet(json, keypointsFile);
+  let source;
+  if (sourceFile) {
+    if (!existsSync32(sourceFile)) {
+      log(`  source image does not exist yet, drawing on a plain ground: ${sourceFile}`);
+    } else {
+      const bytes = await readFile30(sourceFile);
+      if (imageMetadata(bytes)?.format !== "png") throw new UsageError(`${sourceFile} must be a PNG to preview over`);
+      source = decodePng(bytes);
+    }
+  }
+  const out = path46.resolve(args.out ?? keypointsFile.replace(/\.json$/, "") + ".preview.png");
+  await writeFile15(out, renderSkeletonSheet(set, { source }));
+  log(`  ${label}: ${set.frames.length} frames after the starting pose`);
+  const shown = path46.relative(process.cwd(), out);
+  log(`  wrote ${shown.startsWith("..") ? out : shown}`);
+}
 
 // src/cli/commands/tools.ts
 async function runTools(args) {
@@ -20602,7 +20833,7 @@ async function runTools(args) {
 
 // src/cli/commands/workspace.ts
 import path47 from "path";
-import { existsSync as existsSync32 } from "fs";
+import { existsSync as existsSync33 } from "fs";
 async function runWorkspace(args) {
   const workspacePath = path47.resolve(args.workspace ?? "pixelkiln.workspace.json");
   const dir = path47.dirname(workspacePath);
@@ -20632,7 +20863,7 @@ async function runWorkspace(args) {
     log(`  registered "${id}" in ${path47.relative(process.cwd(), workspacePath)}`);
     log(`    manifest: ${project.manifest}`);
     log(`    lock:     ${project.lock}`);
-    if (!existsSync32(lockPath)) {
+    if (!existsSync33(lockPath)) {
       log(
         `  warning: no lockfile there yet; this project contributes no claims until one is generated`
       );
@@ -20656,7 +20887,7 @@ async function runWorkspace(args) {
     return;
   }
   if (args.subcommand === "list") {
-    if (!existsSync32(workspacePath)) {
+    if (!existsSync33(workspacePath)) {
       throw new Error(`Workspace catalog not found: ${workspacePath}`);
     }
     const ws = await loadWorkspace(workspacePath);
@@ -20676,7 +20907,7 @@ async function runWorkspace(args) {
     return;
   }
   if (args.subcommand === "status") {
-    if (!existsSync32(workspacePath)) {
+    if (!existsSync33(workspacePath)) {
       throw new Error(`Workspace catalog not found: ${workspacePath}`);
     }
     const ws = await loadWorkspace(workspacePath);
@@ -20738,7 +20969,7 @@ async function runHelp() {
 async function runVersion() {
   for (const up of ["../package.json", "../../package.json"]) {
     const url = new URL(up, import.meta.url);
-    if (!existsSync33(url)) continue;
+    if (!existsSync34(url)) continue;
     const pkg = JSON.parse(await readFile31(url, "utf8"));
     if (pkg.name === "pixelkiln") {
       log(`${pkg.name} ${pkg.version}`);
@@ -20784,6 +21015,7 @@ var RUNNERS = {
   recipe: runRecipe,
   workspace: runWorkspace,
   "estimate-skeleton": runEstimateSkeleton,
+  "skeleton-preview": runSkeletonPreview,
   unzoom: runUnzoom,
   font: runFont
 };