pixelkiln 0.61.0 → 0.63.0

package/docs/CHARACTERS.md

@@ -296,6 +296,45 @@ who holds a sword in the right hand holds it in the left when facing the
 mirrored way. Most games accept that; if yours does not, generate both
 sides. `adopt` skips mirrors, since there is nothing upstream to adopt.
 
+### One loop, several directions
+
+Writing each direction out is five near-identical loops and three mirrors
+for a full walk. `directions` on an animation says the same thing once:
+
+```json
+"bot.walk": {
+  "prompt": "walking forward in place, short legs stepping, body bobbing slightly",
+  "animation": { "of": "bot", "frames": 12, "fps": 12, "directions": ["south", "west", "north", "south-west", "north-west"] }
+}
+```
+
+When the manifest loads, this becomes exactly the assets it stands for: one
+loop per named direction (`bot.walk.south`, `bot.walk.west`, ...), each with
+every field of the shorthand and its own `direction`, plus a mirror for each
+direction whose flip is not named (`bot.walk.east` mirrors `bot.walk.west`,
+`bot.walk.south-east` mirrors `bot.walk.south-west`, `bot.walk.north-east`
+mirrors `bot.walk.north-west`). Eight directions for five generations. Name
+both sides of a pair (`["west", "east"]`) to generate both instead of
+mirroring, which is the fix for a character whose handedness matters. The
+mirrors carry the shorthand's `category`, `tags`, and `styles`.
+
+- The expanded ids are ordinary assets: `plan`, the gallery, the lockfile,
+  and `pack` all see `bot.walk.west` and `bot.walk.east`, never `bot.walk`.
+  Rewriting the shorthand into explicit assets by hand changes no identity
+  and regenerates nothing.
+- `--only bot.walk` selects the whole family; `--only bot.walk.west` one
+  member of it.
+- `direction` and `directions` are mutually exclusive, and fields that name
+  one output (`file`, `cell`, `remoteId`, `source`, `sourceByStyle`,
+  `outputRole`) are refused on a shorthand, since every direction would
+  claim them. An expanded id that is already declared is an error, not an
+  override.
+- The gallery's `--edit` changes the shorthand, not one direction: editing
+  `bot.walk.west` there is refused with a pointer to `bot.walk`. A revision,
+  state, or new loop can still name an expanded asset as its parent. To
+  change one direction alone, write it out as its own asset and drop it
+  from `directions`.
+
 Engines that flip sprites at draw time (Godot's `flip_h`, Unity's
 `flipX`) do not need mirrored files at all. Declare only the directions
 you generate and flip in the engine; mirrors are for pipelines that want

package/docs/CLI.md

@@ -860,6 +860,62 @@ pixelkiln export --style ground --only terrain --format tiled --columns 8
 
 See [derived artifacts](./ARTIFACTS.md) and [tiles](./TILES.md).
 
+## PixelLab utilities
+
+Two commands call PixelLab on loose files rather than manifest assets. Neither
+reads the manifest or touches the lockfile; both 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.
+
+### `unzoom`
+
+```bash
+pixelkiln unzoom --from refs/knight-512.png --out refs/knight.png
+```
+
+Shrinks an upscaled piece of pixel art (a 32x32 sprite saved at 512x512, every
+art pixel a 16x16 block) back onto its native grid with PixelLab's `/unzoom`.
+Run it on outside art before listing it in `styleImages` or as a
+`reference`: PixelLab's own API guide names upscaled reference art as the most
+common cause of disappointing output from every endpoint that takes one.
+
+- `--out` defaults to `<input>.unzoomed.png` beside the input, and the input
+  is never overwritten. An existing `--out` is replaced only with `--force`.
+- `--quantize <n>`: `0` (default) auto-detects a palette, `-1` keeps every
+  color the downsample produces, `2`-`256` quantizes to exactly that many.
+- The input must be at least 256x256 (the grid detector needs room) and at
+  most 2048x2048 worth of pixels; both are checked before anything is sent.
+- **The result is opaque**: PixelLab composites transparency onto white before
+  it detects the grid, so a cut-out sprite needs its background removed again.
+- `--json` prints the detected zoom factor and both sizes; `--dry-run` sends
+  nothing.
+
+### `font`
+
+```bash
+pixelkiln font --description "warm orange arcade font" --weight Bold --glyph-px 16 --out fonts/arcade
+```
+
+Generates a pixel font with PixelLab's `/generate-font-pro` and writes two
+files: `<out>.ttf`, ready to load in an engine, and `<out>.png`, the 80-glyph
+atlas (A-Z, a-z, 0-9, and common game-UI punctuation). A trailing `.ttf` or
+`.png` on `--out` is treated as part of the base, so `--out fonts/arcade.ttf`
+writes the same two files.
+
+- `--weight` is `Bold` or `Regular` (default); `--glyph-px` is the native glyph
+  size, `8`, `16` (default), `32`, or `64`; `--name` sets the font family name
+  (PixelLab otherwise uses the description plus the weight).
+- Costs PixelLab's documented 25 generations, not yet confirmed against a
+  live bill. The command prints that and asks first; `--yes` skips the
+  question, `--budget <n>` refuses when `n` is below it, and `--dry-run` sends
+  nothing.
+- It waits for the job (PixelLab documents 30-80 s) and then downloads both
+  files. Existing files are replaced only with `--force`.
+
+A font is deliberately not a manifest generator: it has no style suffix to
+share, no prompt-per-asset, no candidates to pick, and its main output is not
+an image, so there is nothing for the lockfile's provenance model to hold.
+
 ## Utility commands
 
 ### `help`
@@ -894,13 +950,13 @@ Print the package version. `-v` is an alias.
 | `--provider <id>` | balance/adopt/salvage/purge/workspace add | Select the account provider for a mixed manifest, or set the workspace catalog's default provider hint. |
 | `--account <label>` | workspace add | Free-form account label, e.g. distinguishing sandboxes. |
 | `--all` | salvage dry run | List every unclaimed object rather than the first 30. |
-| `--from <path>` | init/refine/quality check | Existing source tree for init; source PNG or quality record for one-file refine mode; baseline for quality check. Omit it to use manifest `style.quality`. |
+| `--from <path>` | init/refine/quality check/unzoom | Existing source tree for init; source PNG or quality record for one-file refine mode; baseline for quality check; the upscaled image for unzoom. Omit it to use manifest `style.quality`. |
 | `--exclude <names>` | init | Directory/name fragments to exclude; repeatable. |
 | `--generator <name>` | init | Generator assigned to the scaffolded style. |
-| `--name <name>` | init | Project name for the scaffolded manifest. |
+| `--name <name>` | init/font | Project name for the scaffolded manifest, or the generated font's family name. |
 | `--write-prompts` | adopt | Recover provider prompts into the manifest. |
 | `--port <n>` | pick/salvage/gallery | Local review or gallery server port; otherwise chooses a free port. |
-| `--out <path>` | pack/export/refine/recipe install/quality snapshot | Output base override, final native PNG for path-mode refine, exact recipe destination, or quality baseline path. Export requires one selected tileset. |
+| `--out <path>` | pack/export/refine/recipe install/quality snapshot/unzoom/font | Output base override, final native PNG for path-mode refine, exact recipe destination, quality baseline path, the unzoomed PNG, or the font's `<base>.ttf`/`<base>.png`. Export requires one selected tileset. |
 | `--inputs <path>` | pack/quality snapshot | JSON input array; requires `--out`. Quality cases use `{ id, path, record?, tolerances? }`. |
 | `--columns <n>` | pack/export | Grid columns, 1–1024; default is near-square. |
 | `--format <name>` | export, pack, mount | `export`: `generic` (default), `tiled`, or `godot` (TileSet). `pack` and `mount`: `generic` (default), `aseprite` (sheet JSON), or `godot` (SpriteFrames). |
@@ -918,6 +974,10 @@ Print the package version. `-v` is an alias.
 | `--reviewer <name>` | refine approve | Human reviewer stored in the quality companion. |
 | `--note <text>` | refine approve | Optional review note stored in the quality companion. |
 | `--model-root <path>` | recipe verify | ComfyUI `models` directory. Enables streamed hash checks for every external model declared by the recipe. |
+| `--quantize <n>` | unzoom | `0` auto-detects a palette (default), `-1` keeps every color, `2`-`256` quantizes to exactly that many. |
+| `--description <text>` | font | The font's style, e.g. `"warm orange arcade font"`. |
+| `--weight <w>` | font | `Bold` or `Regular` (default). |
+| `--glyph-px <n>` | font | Native glyph size: `8`, `16` (default), `32`, or `64`. |
 | `--generation <n\|hash>` | restore | Bring a replaced generation back: `1` is the most recently replaced, or a prefix of one of its output hashes. One asset at a time. |
 
 ## Exit and output contract

package/docs/ENDPOINTS.md

@@ -169,9 +169,22 @@ were the correct source instead. Wired up as the `revision` asset shape's
 `reduce-colors`/`correct-pixelart` modes; see [Controlled asset
 revisions](./REVISIONS.md#cleanup-reduce-colors-and-correct-pixelart). Only
 confirmed at this one size — whether it stays flat at larger canvases (unlike
-`inpaint`'s canvas-tiered cost) is not yet known, and multi-frame batch input
-(both endpoints are built to quantize/clean several frames in one call) is
-unmeasured and unmodeled.
+`inpaint`'s canvas-tiered cost) is not yet known. Multi-frame input (both
+endpoints quantize/clean several same-size frames in one call, onto one
+shared palette) is now modeled: a revision whose parent is a set sends every
+member together; see [Revising a whole set at
+once](./REVISIONS.md#revising-a-whole-set-at-once). Its price per call is
+unmeasured.
+
+`/unzoom` (same `Cleanup` tag, also synchronous) recovers native-resolution
+pixel art from an upscaled image: at least 256×256 in, at most 2048×2048 in
+area, and the result is opaque (transparency is composited onto white before
+grid detection). PixelLab's own API overview tells integrators to run it on
+any user-supplied reference art first. Wired up as `pixelkiln unzoom`, a
+standalone command on a loose file rather than a revision mode, since the
+art it is for (a reference pulled from outside) is not a manifest asset; see
+[the CLI reference](./CLI.md#unzoom). Cost unmeasured; PixelLab's MCP tool
+description claims 0.1 generations, the same as the rest of the tier.
 
 ---
 
@@ -533,13 +546,25 @@ Listed so the gaps are known rather than assumed away:
   required — are now wired up as the `revision` asset shape's `animate` and
   `animate-pixminimax` modes; see
   [Animation and interpolation](./REVISIONS.md#animation-and-interpolation).
-  Both are schema-only for the *request* (live OpenAPI document, not an
+  `/interpolation-v2` ("Interpolate (Pro)", in-betweens from one keyframe to
+  another) and `/edit-animation-v2` ("Edit animation (Pro)", one text edit
+  across every frame of a set) are wired the same way, as the `interpolate`
+  and `edit-animation` modes; see
+  [Interpolate between two keyframes](./REVISIONS.md#interpolate-between-two-keyframes).
+  All four are schema-only for the *request* (live OpenAPI document, not an
   observed call); the *completed job* response shape is a genuine unknown —
   no usage example exists for either endpoint at all, only the generic
   background-job one — so `pollAnimateRevision` checks several plausible
   field names defensively rather than assume one. Cost borrows `character`'s
   own measured v3-loop formula as a placeholder, for the same reason
-  `objectPro` borrowed `character` pro-flash's.
+  `objectPro` borrowed `character` pro-flash's; `interpolate` and
+  `edit-animation` borrow the 20/25/40 Pro canvas tiers instead, since
+  neither schema carries a usage example.
+- `/generate-font-pro` (+ `GET /generate-font-pro/{job_id}`) — an 80-glyph
+  atlas PNG plus a `.ttf` from a style description, `weight`
+  (`Bold`/`Regular`), and `glyph_px` (8/16/32/64). Documented at 25
+  generations, unmeasured. Wired up as `pixelkiln font`, outside the
+  manifest; see [the CLI reference](./CLI.md#font).
 - Everything else PixelLab's own tutorials demonstrate that this file has no
   entry for at all — "animation to animation" motion transfer,
   skeleton-animation's rig/template-style controls, Object Creator, and Map
@@ -555,7 +580,8 @@ Listed so the gaps are known rather than assumed away:
   (the standalone isometric tile endpoint alongside it now has one real
   measured data point — see above)
 - `generate-font-pro`, job-based, with a response shape not in the simple
-  `{usage, image}` form
+  `{usage, image}` form (wrapped by `pixelkiln font`, but its cost is not
+  yet measured)
 - the character family beyond what the `character` generator uses: portraits
   (`portrait-character-pro` both ways, `/characters/{id}/portrait`), outfit
   transfer (`transfer-outfit-v2`), lip-sync, skeleton animation, and

package/docs/GENERATORS.md

@@ -16,6 +16,7 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 | Controlled pose/expression sequence in ComfyUI | `frames` | 0 `free` provider units | one atomic ordered set |
 | A character facing 4 or 8 directions, its poses, and its animations | `character` | 1 per base (standard), 20–40 per pose, 1 per template loop | one set of directions, or one ordered loop |
 | UI chrome — panels, buttons, health bars, toolbars | `uiAsset` | 20 generations (measured once, at 256x192) | 1 composited image |
+| One UI element from a description, 16px and up, optionally guided by a concept image | `uiElement` | 20–40 generations (unmeasured) | 1 image |
 
 Start with `map` unless a required capability points elsewhere. Forty `map`
 re-rolls cost the same as one 64×64 `1dir` call.
@@ -399,6 +400,50 @@ price at an area well above where `1dir`/`tiles` would bill the ceiling.
 Left as an over-read for `--budget` until a second size is measured; see
 [ENDPOINTS.md](./ENDPOINTS.md) for the full writeup.
 
+## `uiElement`
+
+`uiElement` wraps PixelLab's `/generate-ui-v2` ("Generate UI (Pro)"): one UI
+element — a button, a health bar, an inventory slot, a dialogue box — from
+the prompt alone. Where `uiAsset` lays a panel out from `pieces`/`elements`
+on a 192px-and-up canvas, `uiElement` has no layout vocabulary and goes down
+to 16×16, which suits icons and small widgets:
+
+```jsonc
+{
+  "styles": {
+    "hud": {
+      "generator": "uiElement",
+      "uiColorPalette": "brown and gold",
+      "styleImages": [{ "path": "refs/hud-concept.png" }],
+      "outDir": "art/ui"
+    }
+  },
+  "assets": {
+    "slot": { "prompt": "wooden inventory slot with metal corners", "width": 32, "height": 32 },
+    "hp-bar": { "prompt": "health bar with a red fill", "width": 96, "height": 16 }
+  }
+}
+```
+
+- `width`/`height` default to 256×256 and can be non-square: 16 up to 792
+  wide and 688 tall, with the exact ceiling set by aspect ratio upstream
+  (square tops out at 512×512, 16:9 at 688×384).
+- The style's single `styleImages` entry, if any, is sent as the endpoint's
+  `concept_image`: design guidance for the element, not a strict style
+  transfer. More than one is refused.
+- `uiColorPalette` is sent as `color_palette`, the same free-text hint
+  `uiAsset` takes. PixelLab removes the background by default; set
+  `noBackground: false` on the style to keep it.
+- One call is expected to return one image, recorded straight away. If the
+  endpoint ever returns several, they go to candidate review like
+  `imagePro`'s.
+
+**Unmeasured.** The schema carries no usage example and no call has been
+billed yet. The plan prices it on the same 20/25/40 canvas tiers as
+`1dir`/`tiles`, the safe over-read for a Pro endpoint, and the completed
+job's shape is read defensively (`pollUiElement` names the keys it got if
+the shape is not the documented `images` list).
+
 ## Style variants
 
 Styles are namespaces. Add another style to re-derive the same asset ids into a

package/docs/MANIFEST.md

@@ -66,7 +66,7 @@ not merely a label edit.
 | `remoteId` | string | The provider's own id for art that already exists on the account, so `adopt` maps it without matching bytes: an object id, a character id, or `<character id>#<animation group id>`. Not part of the spec's identity. |
 | `revision` | object | Controlled image-to-image or inpaint dependency. See [controlled revisions](REVISIONS.md). |
 | `state` | object | `character` styles: a pose or outfit of another character asset. See [Characters](./CHARACTERS.md). |
-| `animation` | object | `character` styles: a loop of another character asset in one direction. See [Characters](./CHARACTERS.md). |
+| `animation` | object | `character` styles: a loop of another character asset in one direction. `directions` (a list, instead of `direction`) declares the loop for several directions at once and fills the unnamed flips with mirrors; see [One loop, several directions](./CHARACTERS.md#one-loop-several-directions). |
 | `mirror` | string | Another asset of the same style flipped left to right, made locally at no cost. See [Mirrors](./CHARACTERS.md#mirrors). |
 | `batch` | object | `1dir` styles: rides along on another `1dir` asset's `item_descriptions` submission instead of generating on its own — `{ "of": "<leader asset id>", "index": <1-based slot> }`. See [`1dir`](./GENERATORS.md#1dir). |
 | `pieces` | array | `uiAsset` styles: exact shape regions (`rounded_rect`/`circle`/`polygon`) the panel is composited from, each with a unique `id`. See [`uiAsset`](./GENERATORS.md#uiasset). |
@@ -116,7 +116,7 @@ One asset using the fields most projects reach for:
 |---|---|---|
 | `extends` | style id | Optional parent style. The child inherits resolved settings but must declare its own `outDir`. |
 | `provider` | top-level default | Provider registry id for this style. Assets cannot override it. |
-| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, `terrain`, `isometricTile`, `imagePro`, `character`, `objectPro`, `uiAsset`, or provider-specific `animation`/`frames`. See [GENERATORS.md](./GENERATORS.md). |
+| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, `terrain`, `isometricTile`, `imagePro`, `character`, `objectPro`, `uiAsset`, `uiElement`, or provider-specific `animation`/`frames`. See [GENERATORS.md](./GENERATORS.md). |
 | `outDir` | string, required | Output directory relative to the manifest. |
 | `promptPrefix` | `""` | Prepended to every participating asset prompt. |
 | `promptSuffix` | `""` | Appended to every participating asset prompt. |
@@ -466,17 +466,17 @@ their own page: [Characters](./CHARACTERS.md) and
 
 | Revision field | Type | Meaning |
 |---|---|---|
-| `mode` | enum, required | `image-to-image`, `inpaint`, `outpaint`, `reduce-colors`, `correct-pixelart`, `animate`, or `animate-pixminimax`. The selected provider must opt into the mode. |
-| `from` | asset id, required | Parent asset in the same style. Self-references, unknown ids, and cycles are rejected. |
+| `mode` | enum, required | `image-to-image`, `inpaint`, `outpaint`, `reduce-colors`, `correct-pixelart`, `animate`, `animate-pixminimax`, `interpolate`, or `edit-animation`. The selected provider must opt into the mode. |
+| `from` | asset id, required | Parent asset in the same style. Self-references, unknown ids, and cycles are rejected. A parent written as a set (a character's directions, an animation's frames) is read as every member: `reduce-colors`, `correct-pixelart`, and `edit-animation` take the whole set in one call; the other modes refuse it. See [Revising a whole set at once](./REVISIONS.md#revising-a-whole-set-at-once). |
 | `mask` | string | Manifest-relative PNG required for `inpaint`; rejected for the other modes. Its dimensions must match an available source. |
-| `strength` | number 0–1 | Workflow edit/denoise strength (`image-to-image`, `correct-pixelart`); rejected for `reduce-colors`, `animate`, and `animate-pixminimax`. Interpretation is provider- and model-specific. |
+| `strength` | number 0–1 | Workflow edit/denoise strength (`image-to-image`, `correct-pixelart`); rejected for `reduce-colors`, `animate`, `animate-pixminimax`, `interpolate`, and `edit-animation`. Interpretation is provider- and model-specific. |
 | `numColors` | integer 2–256 | `reduce-colors` only. Target palette size; mutually exclusive with `paletteImage`. |
 | `paletteImage` | string | `reduce-colors` only. Manifest-relative image whose colors become the palette; unlike `mask`, no size relationship to the source is required. |
 | `dithering` | enum | `reduce-colors` only. `none` (default), `2x2`, `4x4`, or `8x8`. |
 | `ditheringStrength` | number 0–10 | `reduce-colors` only. Ignored when `dithering` is `none`. |
 | `frames` | integer 4–40, even | `animate`/`animate-pixminimax` only. `animate` caps at 16; `animate-pixminimax` allows up to 40. |
-| `fps` | integer 1–60 | `animate`/`animate-pixminimax` only. Playback rate recorded with the frames; the provider does not store one. |
-| `lastFrame` | string | `animate`/`animate-pixminimax` only. Manifest-relative image pinning where the motion ends, turning an open-ended animation into an interpolation. |
+| `fps` | integer 1–60 | `animate`/`animate-pixminimax`/`interpolate`/`edit-animation` only. Playback rate recorded with the frames; the provider does not store one. Defaults to the parent's own rate when it is a loop, else 8. |
+| `lastFrame` | string | `animate`/`animate-pixminimax`: manifest-relative image pinning where the motion ends, turning an open-ended animation into an interpolation. `interpolate`: required, the ending keyframe (the parent is the start); it must match the parent's size. |
 | `direction` | enum | `animate-pixminimax` only. The sprite's facing, used only alongside `enhancePrompt`. |
 | `enhancePrompt` | boolean | `animate`/`animate-pixminimax` only. Lets the provider expand the prompt into a fuller motion description first, for an extra documented +0.05-generation surcharge. |
 

package/docs/PIXELLAB.md

@@ -164,10 +164,13 @@ reference sprites, concept images, style anchors, mirrors, and every
 `animate-character` control; see [Characters](./CHARACTERS.md). Masked
 inpainting and whole-image editing are the `revision` asset shape, not the
 `character` generator; see [Controlled asset revisions](./REVISIONS.md).
-Object Creator (generic 8-direction object rotation, object states and
-animation), UI element and RPG UI-kit generation, fonts, and Map Workshop
+The same revision shape animates, interpolates, recolors, and cleans up any
+asset, a whole character or loop at once where the endpoint takes a set.
+Object Creator is the `objectPro` generator, UI panels and elements are
+`uiAsset` and `uiElement`, and fonts and unzooming reference art are the
+standalone `pixelkiln font` and `pixelkiln unzoom` commands. Map Workshop
 scene composition (placing objects and characters into a map, in-scene
-inpainting, export) are separate PixelLab product surfaces this adapter does
+inpainting, export) is a separate PixelLab product surface this adapter does
 not model at all — including PixelKiln's own `map` generator, which is
 unrelated to PixelLab's "Map Workshop" despite the shared name: `map` returns
 one static prop in one generation, with no scene or canvas concept. Use the

package/docs/REVISIONS.md

@@ -7,10 +7,11 @@ dependencies before submission, and records the lineage in the lockfile.
 
 The manifest and pipeline are provider-neutral. ComfyUI and PixelLab implement
 it; PixelLab covers `image-to-image`, `inpaint`, `reduce-colors`,
-`correct-pixelart`, `animate`, and `animate-pixminimax`, not `outpaint` (its
-API has no canvas-expansion endpoint). ComfyUI covers every mode generically
-except `animate`/`animate-pixminimax`, which need an ordered frame set its
-revision path cannot produce. Retro Diffusion and Scenario reject revision
+`correct-pixelart`, `animate`, `animate-pixminimax`, `interpolate`, and
+`edit-animation`, not `outpaint` (its API has no canvas-expansion endpoint).
+ComfyUI covers every mode generically except the four frame-set modes
+(`animate`, `animate-pixminimax`, `interpolate`, `edit-animation`), which need
+an ordered frame set its revision path cannot produce. Retro Diffusion and Scenario reject revision
 work during offline resolution instead of silently starting a fresh
 text-to-image job.
 
@@ -138,14 +139,47 @@ photographs and 3-D renders, not for reprocessing" pixel art):
 `strength` (0–1, PixelLab's own default 0.1) is how far the model may move
 from the source; start low and only raise it for real repair.
 
-Neither mode supports the source being a frame set (a character animation, an
-`objectPro` loop) yet — each processes exactly one image per revision, the
-same as `image-to-image`. PixelLab's own `/reduce-colors` and
-`/correct-pixelart` endpoints are built to take several frames in one call
-specifically so an animation's frames (or a character's eight directions)
-share one consistent palette/cleanup pass instead of drifting frame by frame;
-pixelkiln does not expose that yet — revise each frame as its own asset for
-now, and expect some frame-to-frame drift from doing so independently.
+### Revising a whole set at once
+
+Both modes also take a parent that is a **set** rather than one image: a
+character's or object's directions, an animation loop, or another frame-set
+revision. Every member goes to PixelLab in one call, which is the point of
+both endpoints: an animation's frames (or a character's eight directions) come
+back on one shared palette, or through one consistent cleanup pass, instead of
+drifting frame by frame the way revising each member separately would.
+
+```jsonc
+{
+  "assets": {
+    "hero-walk-east": { "prompt": "walking", "animation": { "of": "hero", "direction": "east" } },
+    "hero-walk-east-16c": {
+      "prompt": "16-color walk",
+      "revision": { "mode": "reduce-colors", "from": "hero-walk-east", "numColors": 16 }
+    }
+  }
+}
+```
+
+Nothing new is declared: when the parent has no file at its own path but has
+`<stem>-<role>.png` members beside it, those members are the source. Two role
+vocabularies are recognized: a full 8- or 4-direction rotation (`-south.png`,
+`-south-east.png`, ...), or numbered frames (`-frame-00.png` upward). The
+child's output keeps the parent's roles, so `hero-walk-east-16c-frame-03.png`
+is the reduced version of `hero-walk-east-frame-03.png`, and a frame set keeps
+its playback rate.
+
+- Every member's hash goes into the child's identity, so a change to any one
+  frame (not only the first) makes the child stale. The lock records one
+  `sourceSha256` over every member hash in order, the same formula a mirror
+  records over its source.
+- Before spending, the member files found on disk are checked against the
+  parent's own lock entry. A `-frame-11.png` left over from an older, longer
+  generation blocks the revision with a message naming the count mismatch
+  rather than being sent as if it belonged.
+- Members must all be the same size. `reduce-colors`' 512×512 limit is for the
+  whole call: sixteen 64×64 frames fit, five 256×256 do not.
+- Every other mode except `edit-animation` (below) reads exactly one image and
+  refuses a set parent at plan time, naming the modes that take one.
 
 ## Animation and interpolation
 
@@ -216,9 +250,70 @@ already takes for `image-to-image`/`inpaint`. Cost is likewise unmeasured:
 near-identical) as a placeholder, plus `enhancePrompt`'s own documented
 +0.05-generation surcharge, which is a real schema number rather than a guess.
 
-ComfyUI does not support either mode: its revision path always writes a
-single output image, and an animation is a frame set — a structural gap
-rather than a missing binding, so `supportsRevision` refuses it up front
+### Interpolate between two keyframes
+
+`interpolate` calls `/interpolation-v2`, PixelLab's dedicated "Interpolate
+(Pro)" tool: the parent is the start keyframe, `lastFrame` (required here) is
+the end keyframe, and the asset's `prompt` describes the transition. Unlike
+`lastFrame` on `animate`, the frame count is the model's own choice (PixelLab
+documents "typically 4-8"); there is no `frames` field.
+
+```jsonc
+{
+  "assets": {
+    "knight-hit-fall": {
+      "prompt": "knocked backward off his feet by a heavy blow",
+      "revision": {
+        "mode": "interpolate",
+        "from": "knight-hit-airborne",
+        "lastFrame": "art/knight-hit-landed.png",
+        "fps": 12
+      }
+    }
+  }
+}
+```
+
+This is the "key poses first, then interpolate the gap" pattern from
+PixelLab's own tutorials, for motion one `animate` pass cannot produce
+cleanly: build each key pose as a plain `image-to-image` revision (an
+airborne "just hit" frame, then a "landed" frame edited from it), then let
+`interpolate` fill the motion between them. `lastFrame` can be any earlier
+asset's own generated output file, and the plan holds the revision as
+`blocked` until that file exists. Both keyframes must be the same size, 16 to
+128 pixels per side.
+
+### Edit every frame of an animation at once
+
+`edit-animation` calls `/edit-animation-v2`: one text edit ("add a red cape")
+applied across a whole frame set in a single call, so the change stays
+consistent from frame to frame. It is `image-to-image` for an entire
+animation. The parent must be a set (see
+[Revising a whole set at once](#revising-a-whole-set-at-once)); a
+single-image parent is refused. The result keeps the parent's roles, so a
+character's eight directions edited together stay eight directions.
+
+```jsonc
+{
+  "revision": { "mode": "edit-animation", "from": "hero-walk-east" }
+}
+```
+
+Frames are 16 to 256 pixels per side, and because PixelLab packs every frame
+into one grid before editing, the frame ceiling falls as frames grow: 16
+frames up to 64px, 9 up to 80px, 4 up to 256px. Both are checked at plan
+time.
+
+`interpolate` and `edit-animation` land in candidate review like `animate`,
+take `fps` (defaulting to the parent's own rate when it has one, else 8), and
+reject `strength`. Neither has been exercised against a live account: request
+fields come from PixelLab's live OpenAPI document, the completed job is read
+by the same defensive frame-list lookup `animate` uses, and cost is an
+estimate (see [PixelLab](#pixellab) below).
+
+ComfyUI supports none of the four frame-set modes: its revision path always
+writes a single output image, and an animation is a frame set — a structural
+gap rather than a missing binding, so `supportsRevision` refuses it up front
 rather than failing partway through submission.
 
 ## Dependency gate
@@ -330,9 +425,20 @@ further — there is nothing to ask.
   recorded as `billed` on every call regardless
   (`context.metadata.revisionUsage`, since there is no later background job
   to ask the way `billedForJob` asks for every other adapter call).
-- `reduce-colors`'s total size limit is 512×512 worth of pixels (262144px²);
-  `correct-pixelart`'s is 1024 pixels per side. Both are checked before a
-  request is sent, the same as `inpaint`'s 32–512px floor/ceiling.
+- `reduce-colors`'s total size limit is 512×512 worth of pixels (262144px²)
+  across every member sent; `correct-pixelart`'s is 1024 pixels per side.
+  Both are checked before a request is sent, the same as `inpaint`'s
+  32–512px floor/ceiling. The 0.1-generation cost above was measured on one
+  image; a whole member set is still one call, but whether its price stays
+  flat is unmeasured.
+- `interpolate` (`/interpolation-v2`) and `edit-animation`
+  (`/edit-animation-v2`) are both documented "Pro" endpoints with no usage
+  example in the schema and no live measurement. `estimate()` borrows the
+  same 20/25/40 canvas tiers the other unmeasured Pro edits use, sized on the
+  keyframe for `interpolate` and on the packed frame grid for
+  `edit-animation` (four 32×32 frames price as a 64×64 canvas, the 40 tier).
+  Over-reading is the safe direction for `--budget`; expect a live bill at or
+  below the plan.
 - `animate` calls `/animate-with-text-v3`, `animate-pixminimax` calls
   `/animate-pixminimax` — both real async background jobs, unlike the two
   Cleanup-tier modes above, since they generate new frames rather than
@@ -414,7 +520,10 @@ further — there is nothing to ask.
 The lock entry records revision mode, parent id, parent hash, optional mask
 hash, strength, and — for `reduce-colors` — `numColors`, the palette image's
 hash, and the dithering settings, or — for `animate`/`animate-pixminimax` —
-`frames`, `fps`, the last frame's hash, `direction`, and `enhancePrompt`.
+`frames`, `fps`, the last frame's hash, `direction`, and `enhancePrompt`
+(`interpolate` records `fps` and the end keyframe's hash; `edit-animation`
+records `fps`). For a set parent, the parent hash is one hash over every
+member's hash in order.
 ComfyUI provider metadata also retains the same lineage beside the workflow
 hash.
 

package/package.json

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

package/schema/manifest.schema.json

@@ -45,7 +45,8 @@
                       "imagePro",
                       "isometricTile",
                       "objectPro",
-                      "uiAsset"
+                      "uiAsset",
+                      "uiElement"
                     ],
                     "default": "map"
                   },
@@ -501,7 +502,8 @@
                       "imagePro",
                       "isometricTile",
                       "objectPro",
-                      "uiAsset"
+                      "uiAsset",
+                      "uiElement"
                     ],
                     "default": "map"
                   },
@@ -1007,7 +1009,9 @@
                       "reduce-colors",
                       "correct-pixelart",
                       "animate",
-                      "animate-pixminimax"
+                      "animate-pixminimax",
+                      "interpolate",
+                      "edit-animation"
                     ]
                   },
                   "from": {
@@ -1149,6 +1153,23 @@
                     ],
                     "default": "south"
                   },
+                  "directions": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "south",
+                        "south-east",
+                        "east",
+                        "north-east",
+                        "north",
+                        "north-west",
+                        "west",
+                        "south-west"
+                      ]
+                    },
+                    "minItems": 1
+                  },
                   "frames": {
                     "type": "integer",
                     "minimum": 4,

package/schema/recipe.schema.json

@@ -120,7 +120,8 @@
                 "imagePro",
                 "isometricTile",
                 "objectPro",
-                "uiAsset"
+                "uiAsset",
+                "uiElement"
               ],
               "default": "map"
             },

package/skills/pixelkiln/SKILL.md

@@ -48,7 +48,9 @@ hashes.
   dependent asset the same way: one `pixelkiln gen` runs the waves in order
   and stops when the budget cannot cover the next one. Before declaring the
   east-facing loop of a character, check whether a `mirror` of the west one
-  does the job for nothing; before drawing a base from text, ask whether the
+  does the job for nothing (an animation's `directions` list declares the
+  generated sides once and mirrors the rest; `--only <shorthand id>`
+  selects the whole family); before drawing a base from text, ask whether the
   user has a south-facing sprite to `reference` instead (1 generation on
   `pro-flash` at 64px). Mirrors swap handedness.
 - Treat every ComfyUI output as source material until it passes the native-grid,