pixelkiln 0.60.0 → 0.60.1

package/docs/CHARACTERS.md

@@ -159,7 +159,10 @@ suffix, since the character already carries the look.
 `paletteFromReference` snaps the result to the parent's colours; `canvas`
 asks for a larger frame when the edit adds something big. A state costs 20
 to 40 by canvas and keeps the parent's directions. A state may be a state
-of another state.
+of another state. A pose-only state edit (a mid-walk step, a hurt pose) can
+turn the character sideways or away from camera by default even when the
+prompt never mentions rotating; state the facing explicitly (e.g. add
+"front-facing") rather than assume the parent's camera angle carries over.
 
 ### Animations
 
@@ -167,7 +170,10 @@ A template loop moves a skeleton, so it wants a body the skeleton fits: a
 biped on `mannequin`, or one of the quadruped templates. A character that
 is neither (a round robot, a slime) gets a walk from text on the v3
 engine instead; a template on it either fails upstream (`custom`
-template) or redraws the character as the biped it expected.
+template) or redraws the character as the biped it expected. PixelLab's
+"Skeleton V3" model update markedly improved template-loop reliability;
+where earlier guidance favored a custom v3 loop over trusting a template,
+a named template is now the reasonable default for a body it fits.
 
 An animation is one loop of one character (`animation.of`, a base or a
 state) in one `direction`. With a `template` (PixelLab's `walk`,

package/docs/PIXELLAB.md

@@ -139,6 +139,11 @@ comparing notes with someone using a different one:
   MCP doesn't." Good for ad hoc, conversational generation; it has no concept
   of a project's state, a budget, or what has already been paid for.
   Complements PixelKiln rather than competing with it.
+- **PixelLab's editor plugins for Aseprite and Pixelorama**, which bring
+  PixelLab's create/edit/inpaint/animate/interpolate/reduce-colors tools into
+  an existing pixel-art editor's own canvas and layers. Good for a human
+  artist iterating by hand inside a familiar tool; like Game Builder, not
+  something PixelKiln talks to — no manifest, no budget, no lockfile.
 - **PixelKiln**, calling PixelLab's REST API directly. This is why: a
   manifest is a durable plan an agent can re-read and diff, `--budget` is an
   enforced ceiling instead of trusting an agent's per-call judgement, and the

package/docs/README.md

@@ -45,7 +45,6 @@ provider you are using. These Markdown files also render at
 
 - [Contributing](../CONTRIBUTING.md)
 - [Security](../SECURITY.md)
-- [Naming decision](../NAMING.md)
 
 The Markdown in this directory is the canonical documentation and ships in the
 npm package. The Next.js app in `website/` renders this source directly into

package/docs/REVISIONS.md

@@ -185,6 +185,18 @@ between two known poses, PixelLab's own "Animate Between 2 Frames" tool.
 Unlike a mask, no size relationship to the source is required at the manifest
 layer; PixelLab's own API is where a mismatch is caught.
 
+`direction` + `enhancePrompt` together have a real gotcha, demonstrated by
+PixelLab's own tutorial rather than inferred from the schema: `enhancePrompt`
+can expand the motion description with camera-relative language ("towards
+the camera") that fights the requested world-facing `direction`. The failure
+is direction-specific — cardinal directions generated fine in the same batch
+an off-cardinal one (north-east) did not — so a multi-directional
+`animate-pixminimax` set that breaks at one or two directions but not others
+is more likely the enhanced prompt's own wording than the model or the
+`direction` value itself. The same tutorial states PixMiniMax "allows up to
+40 frames," a second, independent (though still not live-billed)
+confirmation of the 40-frame ceiling below.
+
 The result is an **ordered frame set**, not a single image — the source's own
 `frames` PNGs, `<asset>-frame-00.png` onward, exactly the naming a `character`
 loop already uses. Like any generative animation, it lands in **candidate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.60.0",
+  "version": "0.60.1",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,
@@ -105,7 +105,6 @@
     "CONTRIBUTING.md",
     "SECURITY.md",
     "PROVIDERS.md",
-    "NAMING.md",
     "LICENSE"
   ]
 }

package/skills/pixelkiln/references/pixellab-roadmap.md

@@ -1,10 +1,17 @@
 # PixelLab surface this adapter does not cover
 
 A catalog of PixelLab capabilities confirmed absent from PixelKiln, built by
-reading all 26 tutorials on PixelLab's official YouTube channel (the 12
-featured on pixellab.ai plus 14 more from the channel's "PixelLab Tutorial"
-playlist, filtered to the last ~12 months) against this adapter's actual
-source. Read this when scoping new PixelLab work, so effort goes toward a
+reading all 29 tutorials on PixelLab's official YouTube channel (the original
+26 — the 12 featured on pixellab.ai plus 14 more from the channel's "PixelLab
+Tutorial" playlist, filtered to ~12 months back from that pass — plus 3 more
+published since: "Level Up Your Game: Custom Sprite Animation Tutorial,"
+"Pixel Art Animation Tutorial: Images Pro Flash, Skeleton V3 & PixMiniMax,"
+and "How to Reduce Colors Like a Pro!") against this adapter's actual source
+— and, for the newest pass, against PixelLab's own MCP tool schemas
+(`create_image_pro_flash`, `edit_image_pro_flash`, `inpaint_image_pro_flash`,
+`get_pro_flash_capabilities`) where a tutorial's framing needed checking
+against the live surface, the same standard the original pass held itself to.
+Read this when scoping new PixelLab work, so effort goes toward a
 confirmed gap with real demand rather than a guess. Nothing here is a
 commitment to build it — it is what is missing, with the evidence for why it
 might matter, so that decision can be made deliberately.
@@ -109,7 +116,18 @@ which tutorial(s) demonstrated real (not hypothetical) demand for it.
   an animation or a character's eight directions share one consistent
   palette/cleanup pass, which is the actual differentiator the tutorials
   demonstrate — PixelKiln only ever sends one frame per revision today, the
-  same limit `image-to-image`/`inpaint` already have.
+  same limit `image-to-image`/`inpaint` already have. Freshly confirmed by
+  "How to Reduce Colors Like a Pro!": the real-world shape of this gap is
+  project-wide, not per-asset — the tutorial applies one palette across a
+  character's full 8-direction set, its states, each animation (per-frame,
+  "apply to all frames" in one operation), a generated UI pack, a tileset,
+  and a placed map object, in that order, specifically to keep an entire
+  project visually consistent. `numColors`/`paletteImage` already cover the
+  tutorial's other two reduction modes ("auto reduce colors" is pixelkiln's
+  own omit-both default; "use palette" is `paletteImage`, including one
+  imported from Lospec into the source editor's palette list before use) —
+  the batch/multi-frame gap above is the only piece still missing, and this
+  tutorial is stronger evidence that it is the one that matters.
 - **Generic (non-character) animation and interpolation** (`/animate-with-text-v3`,
   `/animate-pixminimax`) — PixelLab's **Animate with text** tools work on
   *any* image, not just a `character`/`objectPro` asset. Demonstrated
@@ -130,7 +148,29 @@ which tutorial(s) demonstrated real (not hypothetical) demand for it.
   `pollRevision` already handles `image-to-image`/`inpaint`. The dedicated
   **Interpolate** endpoint (`/interpolation-v2`, a separate "Pro" two-keyframe
   tool distinct from `last_frame` pinning on the animate endpoints above)
-  remains unwrapped — a narrower, real gap, not yet investigated.
+  remains unwrapped — a narrower, real gap, with real demonstrated demand
+  now: "Level Up Your Game: Custom Sprite Animation Tutorial" used it
+  repeatedly, in Aseprite via PixelLab's own extension, as the fix for an
+  animation a single `animate-with-text` attempt couldn't produce directly —
+  a character knocked backward by a hit. One `animate-with-text` pass from
+  the idle pose gave motion but no clean launched-backward pose; the fix was
+  to stop asking for the whole animation at once, build the two key poses
+  first with a plain single-image edit (an airborne "just hit" frame, then a
+  "landed on the floor" frame, each edited from the previous one), and let
+  Interpolate fill the motion between them (8 frames for the fall, 11 for the
+  recovery back to idle, both with `enhancePrompt` on) — a "key poses first,
+  then interpolate the gap" pattern worth carrying into any future wrapper,
+  not just the raw endpoint. Also newly confirmed, from "Pixel Art Animation
+  Tutorial: Images Pro Flash, Skeleton V3 & PixMiniMax": PixelLab states
+  outright that PixMiniMax allows "up to 40 frames," a second, independent
+  (though still not live-billed) confirmation of the schema's 40-frame
+  ceiling already assumed here. The same tutorial surfaces a real gotcha for
+  `animate-pixminimax` + `direction` + `enhancePrompt`: the expanded prompt
+  can add camera-relative language ("towards the camera") that fights the
+  requested world-facing `direction`, breaking off-cardinal generations (a
+  north-east loop came out wrong, cardinal ones did not) even though neither
+  the model nor the `direction` value was at fault — worth a caveat wherever
+  `enhancePrompt` is documented alongside `direction`.
 - **Object Creator's "pack" generation** (one call → N *distinct* objects,
   each with its own per-item description, instead of N variations of one
   prompt) — demonstrated in "Object Creator" and used throughout
@@ -199,6 +239,73 @@ which tutorial(s) demonstrated real (not hypothetical) demand for it.
 batch demonstrated it in depth, so demand is unconfirmed beyond the tool's
 existence. Not modeled at all.
 
+## Pro Flash for plain image create, edit, and inpaint
+
+PixelLab ships a **third image-generation tier**, distinct from both
+pixelkiln's already-modeled ones — `pixflux`/`map`'s cheap 1-generation
+non-Pro endpoints, and `imagePro`'s Pro tier (`generate-image-v2`, flat 40
+generations) — confirmed directly against PixelLab's own MCP tool schemas
+(`create_image_pro_flash`, `edit_image_pro_flash`, `inpaint_image_pro_flash`,
+`get_pro_flash_capabilities`), not just a tutorial's framing, the same
+standard this catalog holds itself to elsewhere. It is the **same underlying
+model** `character`/`objectPro` already use for their `pro-flash` engine
+(`gpt-image-2.5-flare`, "medium" provider quality per
+`get_pro_flash_capabilities`), but exposed here for **plain images** — create,
+edit, and inpaint — with no character or object involved. Demonstrated at
+length in "Pixel Art Animation Tutorial: Images Pro Flash, Skeleton V3 &
+PixMiniMax": creating a styled character from a reference-image "style
+image," then repeatedly re-editing the same asset ("give him a winter
+outfit," then, from *that* result, "a thicker royal winter outfit with a
+bigger sword" — evolving the previous edit rather than restarting from the
+original each time), then inpainting new hair, a shirt, and pants as separate
+masked passes, each isolated onto its own layer.
+
+**Confirmed shape, via `get_pro_flash_capabilities` (a free, no-generation
+quote/identity lookup — not billed):**
+
+- **`create`**: native sizes 16×16 (experimental, always pixel-grid-corrected
+  by `image-to-pixel-art`'s own fixer), 24×24, 32×32, 32×48, 64×64, 96×64,
+  96×96; custom sizes (beta) 16–256 in steps of 4 on both sides. Takes a
+  `style_image` (URL/base64/owned image id) with `style_options`
+  (`color_palette`/`outline`/`detail`/`shading` toggles) — the same
+  style-copying mechanic as `character` pro-flash's `styleTraits`, just not
+  yet exposed for a plain image. One output, no reference images.
+- **`edit`**: native sizes 32×32 up to **128×128** (a larger ceiling than
+  `create`'s 96×96), custom 32–256 step 4. Two distinct `edit_methods`:
+  `"text"` (a description) or `"reference"` (a `reference_image`, max 1,
+  which must fit the edit canvas natively — no resizing). No style options.
+  Canvas never grows. An optional `use_color_palette_correction` flag snaps
+  the edited result back to the source's own palette.
+- **`inpaint`**: same size range as `edit`. Mask is a rectangle
+  (`mask_x`/`y`/`width`/`height`) or a same-size mask PNG, white = generate /
+  black = preserve / alpha ignored — the same convention `inpaint-v3` already
+  uses. Always crops to the mask. Three `output_methods`: `"New layer with
+  changes"`, `"Modify current layer, only changes"`, `"Modify current
+  layer"` — matching exactly what the tutorial's Aseprite/Pixelorama UI
+  offers, and a real choice the already-modeled `inpaint-v3` does not expose
+  at all today (pixelkiln's `inpaint` revision always gets one behavior). A
+  new, genuinely unmodeled mechanic: `context_image` + a required
+  `bounding_box` lets the model see up to **3×** the native canvas in either
+  dimension of surrounding context beyond the masked region itself — for
+  inpainting a sub-region of a larger scene coherently, the same problem
+  `docs/REVISIONS.md`'s existing "select a sub-region" workaround for
+  `inpaint-v3`'s 512px ceiling solves by hand today.
+- **Cost, from live (but not billed — `get_pro_flash_capabilities`'s quotes
+  are provisional) queries**: `create` 32×32 and 64×64 both quote 5
+  generations flat; 256×256 quotes 9. `edit`/`inpaint` at 64×64 quote 5;
+  `inpaint` at 128×128 quotes 6. `character` and `object` at 64×64 (8
+  directions) both quote `image: 5, rotations: 1, total: 6` — matching
+  pixelkiln's own already-measured `proFlashCharacterCost` (6 at 64px)
+  exactly, reassuring cross-validation of the quote endpoint even though it
+  is a quote, not a bill.
+
+Not modeled at all today: pixelkiln's `imagePro` generator and the `revision`
+asset shape's `image-to-image`/`inpaint` modes only ever call the non-Flash
+endpoints (`generate-image-v2`, `edit-images-v2`, `inpaint-v3`). Adding Pro
+Flash would mean a new generator (or a model/engine choice on the existing
+ones) plus a new inpaint `outputMethod` field and the `context_image`
+mechanism — real, scoped work, not a docs fix.
+
 ## Map Workshop (scene composition)
 
 PixelLab's actual scene-building surface: lay out a tile floor, place

package/skills/pixelkiln/references/pixellab.md

@@ -294,6 +294,22 @@ held-item character, skip the template and write a custom v3 loop with an
 explicit prompt naming the held item and the motion (e.g. "knight holding a
 sword, walking loop") instead of expecting the template to carry it.
 
+PixelLab's own tutorials describe a recent quality jump for named templates
+("Skeleton V3"): the same idle/walking/running/full-sprint-style templates
+existed before, but PixelLab did not recommend relying on them because
+result quality was inconsistent; with the updated model backing them, it now
+does — "the movement is much more usable... much more stable." Prefer a
+named template over a custom v3 loop by default for a body it fits, rather
+than defaulting to a custom loop out of habit; the held-item caveat above is
+the one case that still argues for skipping the template.
+
+A pose-only `state` edit (a walk mid-step, a hurt pose) can turn the
+character sideways or away from the camera by default, even on a prompt that
+never mentions rotating — PixelLab's own tutorial hits this on a plain
+"mid-walk state" prompt. State the facing explicitly (e.g. add "front-facing"
+to the prompt) rather than assuming the parent's own camera angle carries
+over automatically.
+
 A loop costs per direction, and a sprite facing one way is the sprite facing
 the opposite way flipped — this holds for the east/west pair and for both
 diagonal pairs, south-east/south-west and north-east/north-west. Declare the
@@ -367,7 +383,28 @@ using any of these. `reduce-colors`/`correct-pixelart` cost is **confirmed
 live**: a flat 0.1 generations each (not the schema's dollar-denominated
 example), at least at a 32×32 source — `animate`/`animate-pixminimax` remain
 schema-only and unexercised, taken from PixelLab's live OpenAPI document
-rather than an observed call. For a style aimed at a specific look (a
+rather than an observed call.
+
+`animate-pixminimax`'s `direction` + `enhancePrompt` combination has a
+measured-in-practice gotcha, not just a schema quirk: PixelLab's own tutorial
+states plainly that `enhancePrompt` can expand the motion description with
+camera-relative language ("towards the camera") that fights the requested
+world-facing `direction`, and the failure is direction-specific — cardinal
+directions came out fine, an off-cardinal one (north-east) did not. When a
+multi-directional PixMiniMax animation goes wrong at one or two directions
+but not others, suspect the enhanced prompt's own wording before the model or
+the `direction` value. The same tutorial states outright that PixMiniMax
+"allows up to 40 frames," a second, independent (though still not
+live-billed) confirmation of the ceiling above.
+
+PixelLab ships a further image-generation tier beyond what this adapter
+models: "Pro Flash" for plain image create/edit/inpaint, the same
+`gpt-image-2.5-flare` model `character`/`objectPro` pro-flash already use,
+now exposed for images with no character or object involved — see
+[pixellab-roadmap.md](./pixellab-roadmap.md) for the confirmed shape and
+cost.
+
+For a style aimed at a specific look (a
 retro/console feel or a
 high-fidelity showcase asset) rather than a default, read
 [pixellab-fidelity.md](./pixellab-fidelity.md) before choosing `size`,

package/skills/pixelkiln/references/revisions.md

@@ -27,7 +27,12 @@ Read this reference when an asset declares `revision`.
   animation's final frame into the next). `animate` caps at 16 frames;
   `animate-pixminimax` (beta, tier 1+) allows up to 40 and adds `direction`.
   Neither endpoint's cost or completed-response shape is measured against a
-  live account.
+  live account. `direction` + `enhancePrompt` together have a real gotcha:
+  the enhanced prompt can add camera-relative language that fights the
+  requested world-facing `direction`, breaking an off-cardinal direction
+  while cardinal ones in the same batch generate fine — suspect the enhanced
+  prompt's wording, not the model, when only some directions of a
+  multi-directional set come out wrong.
 - Both PixelLab and ComfyUI can back a `revision`, not just ComfyUI.
   PixelLab's `reduce-colors`/`correct-pixelart` calls its own
   `/reduce-colors`/`/correct-pixelart` endpoints synchronously (no background

package/NAMING.md

@@ -1,87 +0,0 @@
-# Naming resolved: `pixelkiln`
-
-**The name is settled.** The project ships as `pixelkiln`. `package.json` is
-no longer `private`.
-
-## The original blocker was a factual error
-
-The prior version of this file claimed `pixelkiln` "is an established npm
-package (v3.5.1, the CSS spritesheet builder) and `pixelsmith` is its
-engine," and blocked the name on that basis. Re-verified directly against
-the npm registry (2026-08-18):
-
-```
-GET https://registry.npmjs.org/pixelkiln    → 404 "Not found"
-GET https://registry.npmjs.org/spritesmith  → 200, latest 3.5.1, "Utility that
-                                                takes images and creates a
-                                                spritesheet with JSON sprite data"
-GET https://registry.npmjs.org/pixelsmith   → 200, latest 2.6.0, "Node based
-                                                engine for spritesmith"
-```
-
-`pixelkiln` was never published. The "v3.5.1 CSS spritesheet builder" is
-**`spritesmith`**, a real and long-established package. `pixelsmith` really
-is its engine, exactly as claimed, but neither of them is `pixelkiln`. The
-original research conflated the two real packages into a collision that
-didn't exist. (`pixelsmith` also appears, separately and correctly, in the
-rejected-candidates list below. It is a real name in a different, adjacent
-project, which should have been the tell.)
-
-A GitHub search for `pixelkiln` returns nothing but this repository, and a
-general web search turns up no product, tool, or project by that name
-anywhere. Nothing else needs to change: `bin/pixelkiln.js`, `package.json`'s
-`name`/`bin`, the README, `scripts/gen-schema.ts`'s schema title, and
-heybud-admin's `package.json` badge scripts already all say `pixelkiln`.
-There is no rename to do, only the `private: true` flag to drop, which is
-done.
-
-## What the space already looks like
-
-The "manifest-driven AI asset generation CLI" idea is not novel. Prior art found:
-
-| Project | Overlap | Backend |
-|---|---|---|
-| [pickbitsai/sprite-generator](https://github.com/pickbitsai/sprite-generator) | Closest. JSON manifest, `assets[]` with id/category/description, `defaultStyle`, `--dry-run`, `--category`, `--concurrency` | OpenAI `gpt-image-1` |
-| [mcp-tool-shop-org/sprite-foundry](https://github.com/mcp-tool-shop-org/sprite-foundry) | SQLite lifecycle tracking, review/accept/reject, provenance, deterministic export with manifest + checksums | ComfyUI (local GPU) |
-| [lx-0/restyle-sprites](https://github.com/lx-0/restyle-sprites) | Restyle a whole pack from source + style reference | Gemini / OpenAI |
-| [trebeljahr/sprite-tools](https://github.com/trebeljahr/sprite-tools) | Post-processing toolkit for atlas, collision, and palette | n/a |
-| [dt-pirate/openrender](https://github.com/dt-pirate/openrender) | Installs generated assets into engines, manifests, rollback | n/a |
-| [freema/pixelforge-mcp](https://github.com/freema/pixelforge-mcp) | MCP server for pixel art | Gemini |
-| [ralphy](https://ralphy.mintlify.app/advanced/asset-manifest) | `asset-manifest.json` slot pointers + `generations.jsonl` audit log | multi |
-
-**Implication for naming:** the `sprite-*` namespace is crowded. `sprite-generator`,
-`sprite-foundry`, `sprite-tools`, and `restyle-sprites` all exist. Avoid it.
-
-## What is actually differentiated here
-
-Worth knowing, because the name should point at it:
-
-1. **PixelLab-native.** Everything above wraps a general image model and
-   downscales. PixelLab generates on a real pixel grid. Nothing found targets it.
-2. **Exploits the candidate economics.** Cost is fixed per call while candidates
-   returned scale inversely with canvas size. Nothing found treats "generate
-   small, pick from 16" as the core loop.
-3. **`adopt`.** Retroactively reconciling an existing account and repo by image
-   hash. Not found anywhere.
-4. **A true lockfile.** `sprite-foundry` uses SQLite, `ralphy` uses a pointer
-   table plus a log. A committed, sorted, hash-on-both-sides lockfile in the npm
-   sense was not found.
-
-## Shortlist (historical, kept for context)
-
-All verified free on npm, zero GitHub repos by that name, no web presence
-(checked 2026-07-29 for the alternates; `pixelkiln` itself re-verified
-2026-08-18 per the resolution above).
-
-| Candidate | Note |
-|---|---|
-| **pixelkiln** ✅ **chosen** | Firing/baking metaphor fits pixel art, avoids the crowded `sprite-*` space. The npm collision this was shelved for turned out not to exist. See Resolution. |
-| pixelquarry | Extraction metaphor, since you quarry many candidates and keep the good ones. Still free, not needed. |
-| pixelcrate | Packaging/inventory feel; leans toward the lockfile idea. Still free, not needed. |
-| dithermill | Most pixel-art-native word available; "mill" carries batch production. Still free, not needed. |
-| spriteledger | Points hardest at provenance, but inherits the crowded `sprite-` prefix. Still free, not needed. |
-
-Rejected after checking: `pixelwright` (three live businesses use it: an AI app
-builder, an iOS audit firm, and a UI developer's brand), `spritefoundry` (taken by a
-real project), `pixelsmith` (real package, `spritesmith`'s engine, see
-Resolution), `spritemill`, `pixelloom`, `bitforge`, `spritelab`.