pixelkiln 0.68.0 → 0.69.0

package/PROVIDERS.md

@@ -57,19 +57,20 @@ the providers offer directly.
 | Decision | PixelLab | Retro Diffusion |
 |---|---|---|
 | Best fit today | Existing PixelKiln projects, account reconciliation, and live-tested generation | Native pixel-art styles, USD budgets, animation, and alternate tileset workflows |
-| PixelKiln generators | `map`, `pixflux`, `1dir`, `tiles`, `character` | `map` and `pixflux` stills, `tiles`, `animation` |
-| Output | PNG stills, candidates, and structural tile members | PNG stills/tiles/spritesheets or animated GIF |
+| PixelKiln generators | `map`, `pixflux`, `1dir`, `imagePro`, `imageProFlash`, `tiles`, `terrain`, `isometricTile`, `character`, `objectPro`, `uiAsset`, `uiElement` | `map` and `pixflux` stills, `tiles`, `animation` |
+| Output | PNG stills, candidates, structural tile members, and ordered frame sets | PNG stills/tiles/spritesheets or animated GIF |
 | Candidate review | Yes; count varies by generator and size | Yes for 1–16 still candidates; animations and tilesets currently use one result |
-| References | `1dir` and tile style modes | Up to nine for supported RD Pro/user still styles; constrained inputs for animation and tiles |
+| References | `1dir` and tile style modes; a character or `objectPro` reference sprite; a `pro` character concept image; one `imageProFlash` style image; one `uiElement` concept image | Up to nine for supported RD Pro/user still styles; constrained inputs for animation and tiles |
 | Cost model | Subscription generations | Prepaid USD balance |
 | Cost safety | Offline estimate plus hard generation budget | Offline estimate, hard USD budget, then a free authoritative quote before submission |
 | Account lifecycle | Balance, list, adopt, salvage, tag, and confirmed purge | Balance only in the current adapter |
 | Live confidence | Full paid generation workflows exercised | RD Fast and RD Plus single-candidate stills exercised end to end; multi-candidate, tileset, GIF, and spritesheet runs pending |
 
 Choose PixelLab when mature account-object recovery and reconciliation matter,
-or when the measured one-generation `map`/`pixflux` routes fit the work. Choose
-Retro Diffusion when a native animation or spritesheet is required, an RD style
-is the desired look, or a USD quote is easier to budget. For a production batch,
+when the measured one-generation `map`/`pixflux` routes fit the work, or when an
+animation belongs to a character, an object, or an existing image. Choose
+Retro Diffusion when a GIF or spritesheet from one prompt fits, an RD style is
+the desired look, or a USD quote is easier to budget. For a production batch,
 run one representative asset through the selected provider before expanding the
 scope.
 
@@ -96,9 +97,12 @@ the same graph and still differ because their checkpoint bytes, custom nodes,
 or sampler settings differ. Commit the workflow and record the model stack used
 to test it.
 
-The revision manifest and dependency gate are provider-neutral, but ComfyUI is
-the only built-in adapter that currently opts in. PixelLab, Retro Diffusion,
-and Scenario reject revision assets offline. See
+The revision manifest and dependency gate are provider-neutral. ComfyUI and
+PixelLab opt in; Retro Diffusion and Scenario reject revision assets offline.
+PixelLab covers `image-to-image`, `inpaint`, `reduce-colors`,
+`correct-pixelart`, `animate`, `animate-pixminimax`, `animate-skeleton`,
+`interpolate`, and `edit-animation`, but not `outpaint`. ComfyUI covers the
+single-image modes through its workflow bindings. See
 [Controlled asset revisions](./docs/REVISIONS.md) before using the bundled
 square image-to-image graph.
 
@@ -131,7 +135,7 @@ background. That distinction matters more than raw canvas size.
 | Asset type | PixelLab | Retro Diffusion | ComfyUI | Scenario |
 |---|---|---|---|---|
 | Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. | The live BFL smoke produced a readable 512px keep, but it was opaque and used 19,619 colors. Use that profile for concepts or refinement input, not a finished limited-palette asset. A project-specific model may improve consistency but needs its own smoke. |
-| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene. Current PixelKiln routes top out at 400×400. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | The BFL profile accepts canvases up to 2048px, but no Scenario scenic brief has passed the shared benchmark. Treat that as model-canvas capacity, not native pixel resolution. Start with one 512px concept before raising size or steps. |
+| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene; both top out at 400×400. `imagePro` reaches 792 wide or 688 tall for a flat 40 generations. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | The BFL profile accepts canvases up to 2048px, but no Scenario scenic brief has passed the shared benchmark. Treat that as model-canvas capacity, not native pixel resolution. Start with one 512px concept before raising size or steps. |
 | Style consistency across a set | `1dir` accepts a style reference and returns size-dependent candidates, but it is more expensive and capped at the square-object range. | RD Pro accepts up to nine references and has stronger prompt following, but its common styles top out at 256×256 and cost $0.18 per image. Environment-specific RD Plus styles trade references for a larger 384px canvas. | LoRAs, reference adapters, ControlNet, and shared latent settings can live in the committed workflow. Reproducibility also depends on external model and custom-node versions. | Scenario's project models and LoRAs are the main reason to use it for a set. PixelKiln can pin the model ID and parameters, but its first live run covers only the public BFL profile. |
 | Very large final scene | Generate reusable objects, terrain, and background layers separately; assemble them deterministically and integer-upscale the result. | Use the same layered approach. The API has a 512px overall ceiling, but the useful environment and scene-object styles currently cap at 384px. | The graph can tile, upscale, or composite beyond hosted-provider limits, but memory and seam quality become workflow concerns. Prefer reusable layers unless the scene truly needs one render. | Scenario can request a larger raster from a compatible model, but the same rule applies: generate reusable layers at their useful native detail, compose at 1×, and integer-upscale only the final scene. |
 
@@ -194,18 +198,29 @@ not share one runtime.
 The services use different billing units, so PixelKiln never adds their costs
 together.
 
-PixelLab figures below are measurements from the endpoints PixelKiln currently
-uses; they are not a conversion to dollars:
+PixelLab figures below come from the endpoints PixelKiln currently uses. Rows
+marked unmeasured or quoted are `plan` estimates, not bills. None is a
+conversion to dollars:
 
-| PixelLab route | Measured cost |
+| PixelLab route | Cost |
 |---|---:|
 | `map` | 1 generation |
 | `pixflux` | 1 generation |
 | `1dir` | 20–40 generations |
+| `imagePro` | 40 generations |
+| `imageProFlash` | 5–9 generations (provisional quote) |
 | `tiles` | 20–40 generations |
-| `character` base | 1 (standard), 2–9 (v3), 20–40 (pro) |
-| `character` state | 20–40 generations |
+| `terrain` | 20–40 generations (unmeasured) |
+| `isometricTile` | 1 generation (measured once) |
+| `character` base | 1 (standard), 2–9 (v3), 20–40 (pro), 6–17 (pro-flash; rotations only from a reference) |
+| `character` state or portrait | 20–40 generations |
 | `character` animation | 1 (template), 1 at 64px from text, 20–40 (pro) |
+| `character` outfit | 20 generations (one 2-frame, 92×92 job) |
+| `objectPro` base | 6 at 64px (unmeasured) |
+| `uiAsset` | 20 generations (measured once, at 256×192) |
+| `uiElement` | 20–40 generations (unmeasured) |
+| `image-to-image` / `inpaint` revision | 20–40 generations; 5–9 with `engine: "pro-flash"` (provisional quote) |
+| `reduce-colors` / `correct-pixelart` revision | 0.1 generations (measured at 32×32) |
 
 Retro Diffusion publishes USD formulas and fixed prices. Examples relevant to
 PixelKiln include RD Fast from about $0.015 per image, RD Plus from about $0.025,

package/README.md

@@ -53,8 +53,9 @@ provenance and no long-lived npm token.
 | Plan and budget | Offline manifest/lock/disk diff, provider-grouped estimates, keyed mixed-provider budget ceilings, JSON/CI gate. |
 | Generate and review | Resumable submit/poll/pick/fetch pipeline, exact next-step hints, candidate or atomic frame-set review, and a provenance gallery that can edit intent, generate under a budget, and compare records. |
 | 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 image-to-image/inpaint lineage, 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 and loops as dependent assets generated in waves, free mirrored directions, account adoption, and SpriteFrames export. |
+| 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, `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. |
@@ -258,18 +259,17 @@ Measured PixelLab economics vary by 40×:
 | Independent or connectable ground tiles | `tiles` | 20–40 generations |
 | A character in 4 or 8 directions, its poses, its loops | `character` | 1 per base, 20–40 per pose, 1 per template loop per direction; a `mirror` of a loop is free |
 
-Start with the required capability, not the most expensive endpoint. Forty
-`map` re-rolls cost the same as one 64×64 `1dir` call; conversely, `map` cannot
-replace a hard palette or reference-image constraint. See
-[Generator selection](./docs/GENERATORS.md) and the
-[measured endpoint reference](./docs/ENDPOINTS.md).
+Start with the required capability, not the most expensive endpoint. Forty `map`
+re-rolls cost the same as one 64×64 `1dir` call; conversely, `map` cannot replace a
+hard palette or reference-image constraint. PixelLab has seven more generators
+(`imagePro`, `imageProFlash`, `terrain`, `isometricTile`, `objectPro`, `uiAsset`,
+`uiElement`); see [Generator selection](./docs/GENERATORS.md) and the [measured endpoint reference](./docs/ENDPOINTS.md).
 
-Generator names describe PixelKiln workflows; their exact capabilities and
-prices depend on the selected provider. Retro Diffusion also supports the
-provider-specific `animation` generator. ComfyUI supports `map` plus atomic
-still-image `frames` through an operator-supplied workflow. Scenario supports `map`
-with a required offline CU ceiling and a live quote before each paid call.
-Compare the adapters in the [provider comparison](./PROVIDERS.md).
+Generator names describe PixelKiln workflows; their exact capabilities and prices
+depend on the selected provider. Retro Diffusion also supports the provider-specific
+`animation` generator. ComfyUI supports `map` plus atomic still-image `frames` through
+an operator-supplied workflow. Scenario supports `map` with a required offline CU
+ceiling and a live quote before each paid call. Compare the adapters in the [provider comparison](./PROVIDERS.md).
 
 ## Derived artifacts
 
@@ -368,12 +368,13 @@ verification. See [Library API](./docs/LIBRARY.md).
 | [Set up ComfyUI](./docs/COMFYUI.md) | Self-hosted stills, revisions, ordered frame sets, per-asset inputs, and quality limits. |
 | [Set up Scenario](./docs/SCENARIO.md) | Experimental hosted models, two-part credentials, CU preflight, review, and durable downloads. |
 | [Versioned recipes](./docs/RECIPES.md) | Pinned workflow packs, model hashes, manifest templates, and quality contracts. |
-| [Controlled revisions](./docs/REVISIONS.md) | Image-to-image/inpaint parents, masks, fail-closed readiness, provenance, and ComfyUI bindings. |
+| [Controlled revisions](./docs/REVISIONS.md) | Image-to-image, inpaint, palette cleanup, animation, and interpolation from a parent; masks, fail-closed readiness, provenance, and ComfyUI bindings. |
 | [CLI reference](./docs/CLI.md) | Every command, flag, JSON mode, and exit contract. |
 | [Manifest reference](./docs/MANIFEST.md) | Style/asset fields, quality profiles, and generator constraints. |
 | [Mixed-provider projects](./docs/MIXED_PROVIDERS.md) | Per-style routing, provider-keyed budgets, recovery, and account commands. |
 | [Agent workflows](./docs/AGENTS.md) | Official skill install, operating model, and provider-aware safety. |
 | [Generators](./docs/GENERATORS.md) | Capability choice, measured costs, palettes, style references, and tiles. |
+| [Characters](./docs/CHARACTERS.md) | Bases, states, loops, mirrors, portraits, outfits, the `directions` shorthand, and per-engine costs. |
 | [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Thirty provider outputs plus native-grid and final-palette results comparing large scenes, transparency, palette size, and file readiness. |
 | [Derived artifacts](./docs/ARTIFACTS.md) | Refine, pack, mount, export, provenance, ownership, transactions, and recovery. |
 | [Recovery](./docs/RECOVERY.md) | Restore, caches, adopt, salvage, claims, and purge safety. |
@@ -384,10 +385,9 @@ verification. See [Library API](./docs/LIBRARY.md).
 | [Endpoint research](./docs/ENDPOINTS.md) | Measured PixelLab API behavior and recipes. |
 | [Provider comparison](./PROVIDERS.md) | Provider selection, costs, supported workflows, confidence, and limitations. |
 
-The [public documentation site](https://pixelkiln.griffen.codes/docs) is built from
-these Markdown files by [`website/`](./website/README.md), so the site and the
-package share one source. Policies: [Contributing](./CONTRIBUTING.md),
-[Security](./SECURITY.md), [provider comparison](./PROVIDERS.md).
+The [public documentation site](https://pixelkiln.griffen.codes/docs) is built from these Markdown
+files by [`website/`](./website/README.md), so the site and the package share one source.
+Policies: [Contributing](./CONTRIBUTING.md), [Security](./SECURITY.md).
 
 ## Scope
 

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
 };