pixelkiln 0.68.1 → 0.69.0

package/docs/CLI.md

@@ -6,8 +6,8 @@ pixelkiln <command> [options]
 
 Unknown commands, positional arguments, and flags are errors. The only
 positional words accepted are a command's own subcommands (`refine approve`,
-`workspace add <manifest>`, and the like) and `estimate-skeleton`'s one image
-path. Repeated `--style`, `--only`, `--claims`, and `--output-role` values
+`workspace add <manifest>`, and the like), `estimate-skeleton`'s one image
+path, and `skeleton-preview`'s keypoints file or asset id. Repeated `--style`, `--only`, `--claims`, and `--output-role` values
 accumulate; comma-separated values work too. This strict parsing prevents a misspelled filter
 from widening a paid run.
 
@@ -55,6 +55,7 @@ Which command:
 | shrink upscaled outside art to its native grid before using it as a reference | `pixelkiln unzoom --from refs/knight-512.png --out refs/knight.png` |
 | generate a pixel font (`.ttf` plus glyph atlas) | `pixelkiln font --description "warm orange arcade font" --out fonts/arcade` |
 | start an `animate-skeleton` keypoints file from an image | `pixelkiln estimate-skeleton poses/hero.png --out poses/hero-swing.json` |
+| see a keypoints file's poses over the source before paying | `pixelkiln skeleton-preview hero-swing` |
 | work across several projects | `pixelkiln workspace add ../other/pixelkiln.manifest.json`, then `--workspace` on `gallery` and `salvage` |
 
 Every command takes `--manifest <file>` when the manifest is not in the
@@ -875,7 +876,8 @@ See [derived artifacts](./ARTIFACTS.md) and [tiles](./TILES.md).
 Three commands call PixelLab on loose files rather than manifest assets. None
 reads the manifest or touches the lockfile; all three load `PIXELLAB_API_KEY`
 from the environment or a `.env.local`/`.env` beside `--manifest` or in the
-working directory, the same as every other command.
+working directory, the same as every other command. A fourth,
+`skeleton-preview`, is their local companion and calls nothing.
 
 ### `unzoom`
 
@@ -929,19 +931,44 @@ an image, so there is nothing for the lockfile's provenance model to hold.
 ### `estimate-skeleton`
 
 ```bash
-pixelkiln estimate-skeleton <image> [--out keypoints.json]
+pixelkiln estimate-skeleton <image> [--out keypoints.json] [--frames 4] [--force]
 ```
 
 PixelLab only. Derives an 18-joint skeleton from an image via
-`/estimate-skeleton` and prints the keypoints JSON, or writes it with `--out`.
-Same category as `balance`: a direct, un-budgeted account call outside the
-manifest/plan/lock pipeline — no manifest is read beyond locating
-`.env.local`, and nothing is written to a lockfile. This is how to bootstrap
-an `animate-skeleton` revision's `keypointsFile` (see
-[Controlled asset revisions](./REVISIONS.md#skeleton-driven-animation)):
-estimate once, sanity-check the result, hand-tweak a few joints for
-in-between frames, rather than hand-authoring 18 joints of
-`{label, x, y, z_index}` from scratch.
+`/estimate-skeleton`. The image must be square at 16, 32, 64, 128, or 256
+pixels, the sizes the endpoint takes; anything else is refused before the
+call. Same category as `balance`: a direct, un-budgeted account call outside
+the manifest/plan/lock pipeline — no manifest is read beyond locating
+`.env.local`, and nothing is written to a lockfile.
+
+The output is a whole keypoints file, the shape an `animate-skeleton`
+revision's `keypointsFile` must be (see
+[Controlled asset revisions](./REVISIONS.md#skeleton-driven-animation)): the
+estimated pose as `firstFrameKeypoints`, and `--frames` copies of it (3–15,
+default 4) as the frames to move into the motion. It prints, or writes to
+`--out`; `--out` refuses to replace an existing file, which is usually hand
+edits, unless `--force` is given.
+
+### `skeleton-preview`
+
+```bash
+pixelkiln skeleton-preview <keypoints.json> [--from image.png] [--out sheet.png]
+pixelkiln skeleton-preview <asset> [--style <id>] [--out sheet.png]
+```
+
+Draws every pose of a keypoints file over its source image as one PNG, the
+starting pose first at full strength and each frame after it over a dimmed
+copy. Right-side bones are orange, left-side blue, the head and spine white.
+Local and free: nothing is sent anywhere. Given an `animate-skeleton` asset
+id, it reads the revision's `keypointsFile` and source image from the
+manifest; given a file, `--from` names the image (without one, poses are drawn
+on a plain ground). The sheet is written beside the keypoints file as
+`<name>.preview.png` unless `--out` says otherwise. A file that does not parse
+fails with the same message `plan` would give.
+
+Use it after `estimate-skeleton` and after every hand edit: PixelKiln cannot
+check that the starting pose matches what the image shows, and a mismatch
+degrades every generated frame without an error.
 
 ## Utility commands
 
@@ -958,6 +985,7 @@ Print the package version. `-v` is an alias.
 | Option | Applies to | Meaning |
 |---|---|---|
 | `--manifest <path>` | manifest commands | Manifest path; defaults to `pixelkiln.manifest.json`. |
+| `--frames <n>` | `estimate-skeleton` | Frames to scaffold after the estimated pose, 3–15; default 4. |
 | `--lock <path>` | manifest commands | Lock path; defaults beside the manifest. |
 | `--style a,b` | most workflows | Restrict styles; repeatable. |
 | `--only id1,id2` | most workflows | Restrict asset ids; repeatable. An `animation.directions` shorthand id selects every loop and mirror it expands into. |

package/docs/REVISIONS.md

@@ -344,10 +344,16 @@ inline pixels. It must match the shape `src/skeleton.ts`'s `SkeletonSetSchema`
 validates: `{"firstFrameKeypoints": [...18 joints], "frames": [[...18
 joints], ...3 to 15 of them]}`, each joint `{"label": "RIGHT KNEE", "x": 0.52,
 "y": 0.71, "z_index": 9, "depth": 4}` (`depth` optional — PixelLab fills it
-from `skeletonTemplate`, default `mannequin`, when omitted). Bootstrap this
-file with `pixelkiln estimate-skeleton <image> --out poses/hero-swing.json`
-(see [CLI reference](./CLI.md#estimate-skeleton)) rather than hand-typing 18
-joints from scratch, then hand-tweak individual joints for in-between frames.
+from `skeletonTemplate`, default `mannequin`, when omitted). `label` is one
+of PixelLab's 18 joints (`NOSE`, `NECK`, `RIGHT`/`LEFT` `SHOULDER`, `ELBOW`,
+`ARM` for the wrist, `HIP`, `KNEE`, `LEG` for the ankle, `EYE`, `EAR`), each
+exactly once per pose; a misspelled or repeated joint fails when the manifest
+loads. Bootstrap this file with
+`pixelkiln estimate-skeleton <image> --out poses/hero-swing.json` (see
+[CLI reference](./CLI.md#estimate-skeleton)), which writes the estimated pose
+and four copies of it as frames, then move joints frame by frame. Check each
+edit with `pixelkiln skeleton-preview hero-swing`, which draws every pose
+over the source image, locally and for free.
 
 `direction` is **required** for this mode (unlike `animate-pixminimax`,
 where it is optional). `frames`/`fps`/`lastFrame`/`enhancePrompt` are all

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.68.1",
+  "version": "0.69.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,

package/skills/pixelkiln/SKILL.md

@@ -111,8 +111,8 @@ Read only the reference needed for the current decision:
 
 - For PixelLab configuration, generators (including `uiElement` for single UI
   pieces and `imageProFlash` for styled stills), costs, alpha behavior,
-  account operations, or the `unzoom`, `font`, and `estimate-skeleton`
-  utilities, read [references/pixellab.md](references/pixellab.md). For a
+  account operations, or the `unzoom`, `font`, `estimate-skeleton`, and
+  `skeleton-preview` utilities, read [references/pixellab.md](references/pixellab.md). For a
   PixelLab style aimed at a specific resolution or fidelity tier (retro,
   high-detail, or matching an existing set's look), read
   [references/pixellab-fidelity.md](references/pixellab-fidelity.md) first.

package/skills/pixelkiln/references/pixellab.md

@@ -460,7 +460,8 @@ pixel art to its native grid; run it before outside art becomes a
 cost unmeasured). `pixelkiln font --description <text> --out <base>` writes a
 `.ttf` and an 80-glyph atlas for PixelLab's documented 25 generations, and
 asks first. `pixelkiln estimate-skeleton <image> --out <file>` starts an
-`animate-skeleton` keypoints file. See `docs/CLI.md`, "PixelLab utilities".
+`animate-skeleton` keypoints file, and `pixelkiln skeleton-preview <asset>`
+draws its poses over the source for free. See `docs/CLI.md`, "PixelLab utilities".
 
 For a style aimed at a specific look (a
 retro/console feel or a

package/skills/pixelkiln/references/revisions.md

@@ -50,7 +50,11 @@ Read this reference when an asset declares `revision`.
   poses. It needs `direction`; `prompt` names the motion and the optional
   `description` says what the subject looks like. Bootstrap the file with
   `pixelkiln estimate-skeleton <image> --out <file>` (a direct call, outside
-  any budget, like `balance`), then edit the frame poses by hand. Plan cost
+  any budget, like `balance`; square 16–256px images only), which writes the
+  estimated pose plus `--frames` copies (default 4) to edit. Joint labels are
+  PixelLab's 18 names, each once per pose. After every edit, run
+  `pixelkiln skeleton-preview <asset>` (local, free) and look at the sheet:
+  the starting pose must match the sprite, or every frame degrades silently. Plan cost
   interpolates PixelLab's documented anchors (3 frames = 2, 8 = 3, 15 = 4);
   like the other animate modes it lands in candidate review and is
   unmeasured live.