pixelkiln 0.91.2 → 0.92.1

package/docs/ENDPOINTS.md

@@ -259,6 +259,42 @@ function `inpaint-v3` and `edit-images-v2` revisions use.
 
 ---
 
+## Target palette (`target_palette`)
+
+PixelLab 0.4.130 added a beta `target_palette` body field, then gave it to 27
+POST endpoints: `{ colors?: 2-256 hex, name?: string (≤100), max_colors?: 2-64,
+smart?: boolean }`. With `colors` every pixel is one of them; `max_colors` caps
+each image. The schema is documentation only so far: **cost with a palette is
+measured for `generate-image-v2` alone** (a 64×64 call billed 10, the same as
+without), and the rest are unmeasured. PixelKiln never sends `smart` (beta,
+"single images only", needs `colors`, adds 15 to 60 s).
+
+| Endpoint | PixelKiln wrapper | Sent |
+|---|---|---|
+| `/generate-image-v2` | `imagePro` | yes |
+| `/create-image-pro-flash` | `imageProFlash` | yes; the style image's colours give way to it |
+| `/create-object-pro-flash` | `objectPro` base | yes |
+| `/objects/{id}/states` | `objectPro` state | yes |
+| `/objects/{id}/animations` | `objectPro` animation | `pro` mode only (the field is documented for `mode='pro'`) |
+| `/create-1-direction-object` | `1dir` | yes |
+| `/create-tiles-pro` | `tiles` | yes |
+| `/create-tileset` | `terrain` top-down | `terrainMode: "pro"` only ("mode='pro' only"; `color_image` is documented as no effect on standard) |
+| `/create-ui-asset`, `/generate-ui-v2` | `uiAsset`, `uiElement` | yes |
+| `/create-character-pro`, `/create-character-pro-flash` | `character` Pro and Pro Flash bases | yes |
+| `/create-character-state`, `/portrait-character-pro`, `/transfer-outfit-v2` | `character` states, portraits, outfits | yes |
+| `/create-character-with-8-directions` | `character` standard base | no: keeps `color_image` + `force_colors`; the field is "mode='pro' only" and this wrapper sends standard |
+| `/animate-character`, `/characters/animations` | `character` animations | no: keep the same swatch on every mode; the schema does not say the two combine |
+| `/interpolation-v2`, `/edit-animation-v2` | `interpolate`, `edit-animation` revisions | yes |
+| `/create-8-direction-object`, `/generate-with-style-v2`, `/image-to-pixelart-pro`, `/animate-with-text-v2`, `/generate-8-rotations-v2`, `/tilesets` | not wrapped | no |
+| `/image-to-pixelart-pro-flash` | `pixelkiln pixelate` | no: a loose-file utility with no style, so no palette |
+
+`/create-tileset-sidescroller`, `/create-character-v3`, `/animate-with-text-v3`
+and `/animate-pixminimax` have no such field. Every request body is built by
+one helper (`targetPaletteBody` in `src/client.ts`), so the field is spelled
+once.
+
+---
+
 ## VFX workbench (MCP only), measured
 
 Create VFX shipped in PixelLab 0.4.128 as a web tool

package/docs/GENERATORS.md

@@ -687,6 +687,53 @@ change price, use `pixelkiln vfx --description "<what to change>" --effect
 repeatable recipe, export it with `pixelkiln vfx --effect <id> --out
 fx/zap` and point a workbench `recipe` at the record.
 
+## Target palette
+
+PixelLab 0.4.130 added the beta `target_palette` (`colors`, `name`,
+`max_colors`) to `imagePro` and, since, 27 POST endpoints. A style's `palette`
+(2 to 256 colours; one colour is refused), `paletteName` and `maxColors` (2 to
+64, an optional cap per image) are sent as it wherever the endpoint takes it,
+so PixelLab draws with the palette instead of leaving it all to local
+`enforcePalette` snapping. `paletteName` and `maxColors` are accepted on the
+styles of `imagePro`, `imageProFlash`, `objectPro`, `1dir`, `character`,
+`tiles`, `terrain`, `uiAsset` and `uiElement`, and enter `specHash` only when
+set. PixelLab's `smart` flag is not sent (beta, "single images only"). The
+full endpoint list is in [ENDPOINTS.md](./ENDPOINTS.md#target-palette-target_palette).
+
+What goes out per asset shape:
+
+| Shape | Sent | Not sent, and why |
+|---|---|---|
+| `imagePro`, `imageProFlash`, `1dir`, `tiles`, `uiAsset`, `uiElement` | `target_palette` | `pixflux` keeps its `color_image` swatch |
+| `objectPro` | base, state, and `pro`-mode animation | `v3` animation: the endpoint documents the field for `mode='pro'` only |
+| `character` | `pro` and `pro-flash` bases, states, portraits, outfits | `standard` bases keep the `color_image` + `force_colors` swatch; `v3` has no field; animations (every mode) keep the same swatch |
+| `terrain` | top-down `terrainMode: "pro"` | standard sets (documented "mode='pro' only"), and sidescroller sets (the endpoint has none) |
+| `revision` | `interpolate`, `edit-animation` | `animate`, `animate-pixminimax`, `animate-skeleton` (their endpoints have none), `reduce-colors` (it takes `paletteImage`), and the other modes |
+
+Where an endpoint takes both a swatch and the new field (standard characters,
+animations), the existing, verified swatch stays and `target_palette` is not
+added, because the schema does not say they combine. On `imageProFlash`,
+a style image's own colours "give way" to the palette, per PixelLab, so
+`styleTraits.palette` is left as authored. `uiColorPalette` (a prose hint) is
+still sent next to the hex palette on UI assets and elements; the hex palette
+is what PixelLab enforces.
+
+A style whose `palette` was already set keeps its hash, so `plan` does not
+call it stale, but regenerating it will now send that palette on the routes
+above (it was already true for `imagePro`). **Costs are unchanged by
+PixelLab's documentation**, and two more routes are now measured with a
+palette: `imagePro` (a 64×64 call billed exactly 10), `imageProFlash` (a
+32×32 still billed exactly 5, in only the four palette colours) and `tiles`
+(one numbered description, 4 tiles at 16px, billed exactly 10, every
+candidate in the palette's greens). The other routes are tested against mocked
+requests only. `maxColors` without a `palette` on a multi-direction asset
+caps each direction separately, so the directions may pick different colours;
+give `colors` for those. Not done: `/create-character-v3` and the 4-direction
+standard character endpoint (no field), `/create-8-direction-object`,
+`/generate-with-style-v2`, `/image-to-pixelart-pro`, `/animate-with-text-v2`
+and `/tilesets` (not wrapped), and `pixelkiln pixelate` (a loose-file
+utility with no style, so no palette).
+
 ## Style variants
 
 Styles are namespaces. Add another style to re-derive the same asset ids into a

package/docs/MANIFEST.md

@@ -132,9 +132,9 @@ One asset using the fields most projects reach for:
 | `shading` | string | PixelLab `map`: `flat shading`, `basic shading`, `medium shading`, or `detailed shading`. |
 | `detail` | string | PixelLab `map`: `low detail`, `medium detail`, or `high detail`. |
 | `seed` | integer | Deterministic provider seed where supported. |
-| `palette` | hex array, `[]` | The style's palette; `#` is optional. Sent to providers that take one (`pixflux`, `imagePro` as its target palette, Retro Diffusion, ComfyUI bindings). |
-| `paletteName` | string ≤100 | `imagePro` only, needs `palette`: the palette's name (`Game Boy`, `PICO-8`), which PixelLab uses to help the look. |
-| `maxColors` | integer 2–64 | `imagePro` only: at most this many colours in each candidate, drawn from `palette` when one is set. |
+| `palette` | hex array, `[]` | The style's palette; `#` is optional. Sent to providers that take one: `pixflux` and standard characters as a swatch, PixelLab's `target_palette` for `imagePro`, `imageProFlash`, `objectPro`, `1dir`, `tiles`, `uiAsset`, `uiElement`, Pro and Pro Flash characters (and their states, portraits, outfits), Pro `terrain`, and `interpolate`/`edit-animation` revisions (2–256 colours there), Retro Diffusion, ComfyUI bindings. See [Target palette](./GENERATORS.md#target-palette). |
+| `paletteName` | string ≤100 | Generators that send `target_palette` (`imagePro`, `imageProFlash`, `objectPro`, `1dir`, `character`, `tiles`, `terrain`, `uiAsset`, `uiElement`); needs `palette`: the palette's name (`Game Boy`, `PICO-8`), which PixelLab uses to help the look. |
+| `maxColors` | integer 2–64 | The same generators: at most this many colours in each image, drawn from `palette` when one is set. |
 | `enforcePalette` | boolean, `false` | Snap every downloaded PNG to the nearest `palette` colour, no dithering. Needs at least two colours. See [Palette enforcement](#palette-enforcement). |
 | `noBackground` | boolean, `true` | `pixflux` background removal. Set false for scenes/backdrops. |
 | `providerOptions` | object, `{}` | Options grouped by provider id. Only the active provider's object is resolved and hashed. |
@@ -262,7 +262,9 @@ Generator-specific fields are validated before planning. Important constraints:
 - `imagePro` sends `palette` (2 to 256 colours) as PixelLab's beta target
   palette: every pixel of every candidate is one of those colours. Add
   `paletteName` to name it and `maxColors` to cap each candidate's colours.
-  The cost is unchanged.
+  PixelLab 0.4.130's target palette now reaches more tools the same way; see
+  [Target palette](./GENERATORS.md#target-palette) for which asset shapes and
+  modes send it. Cost is unchanged by it, but unmeasured outside `imagePro`.
 - `tiles` cannot combine `tileFeature` with `styleImages` because the provider
   rejects connectable features in style-tile mode.
 - ComfyUI `frames` derives its count from one 2–64 item `providerInputs`

package/docs/PIXELLAB.md

@@ -158,7 +158,10 @@ PixelLab 0.4.130 (October 2026) added four things. PixelKiln covers each:
   sidescrollers yet.
 - **A target palette for Create Image Pro.** An `imagePro` style's `palette`
   now reaches PixelLab, which draws every pixel from it. `maxColors` caps
-  each image and `paletteName` names the palette.
+  each image and `paletteName` names the palette. PixelLab then added the
+  field to 26 more endpoints, and PixelKiln sends it to the ones it wraps
+  where no verified palette mechanism exists; see
+  [Target palette](./GENERATORS.md#target-palette).
 - **VFX in the API.** A `vfx` block with a `description` asks PixelLab's
   effects artist for the effect, at 1 generation and up. Presets, parts, and
   recipes still render free on the workbench. See
@@ -174,6 +177,16 @@ call with the Game Boy palette (10, every pixel one of its four colours), a
 lite described effect (1), and normal maps (0.5 each). The home page's latest
 updates section shows the results.
 
+**The palette now reaches more tools.** `imageProFlash`, `objectPro`, `1dir`,
+`tiles`, `uiAsset`, `uiElement`, Pro and Pro Flash characters (with their
+states, portraits and outfits), Pro `terrain`, and the `interpolate` and
+`edit-animation` revisions send a style's `palette`, `paletteName` and
+`maxColors` as `target_palette`. Standard characters and every character
+animation keep their `color_image` swatch, and `pixflux` keeps its own. Costs
+with a palette are measured for `imagePro` (10), `imageProFlash` (a 32×32
+still, 5, in only the four palette colours), and `tiles` (4 tiles at 16px,
+10), and unverified elsewhere. The other routes are covered by mocked tests only.
+
 ## Learn from PixelLab's tutorials
 
 PixelLab's YouTube channel teaches its web app, not PixelKiln, but most of

package/package.json

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

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

@@ -401,6 +401,21 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   candidates below 171px. **Measured once**: a 64×64 call with the Game Boy
   palette billed exactly 10, and the picked candidate used only those four
   colours.
+  **Rolled out** to the other wrapped tools that take it: `imageProFlash`,
+  `objectPro` bases, states and `pro` animations, `1dir`, `tiles`, `uiAsset`,
+  `uiElement`, Pro and Pro Flash character bases, states, portraits and
+  outfits, top-down Pro `terrain`, and `interpolate`/`edit-animation`
+  revisions, through one helper (`targetPaletteBody`). `paletteName` and
+  `maxColors` are style fields on those generators, hashed only when set; an
+  existing style `palette` keeps its hash and is simply sent on regeneration.
+  **Measured live** with a Game Boy palette: `imageProFlash` (a 32×32 still, 5, only the four colours) and `tiles` (4 tiles at 16px, 10, every candidate in the palette), matching the plan, as `imagePro` did (10). **The other routes are mocked tests only, costs unmeasured.** **Not done**:
+  standard character bases and every character animation (their verified
+  `color_image` + `force_colors` swatch stays, and the schema does not say it
+  combines), the standard terrain set (the field is "mode='pro' only"), the
+  `v3` object animation (`pro` only), `/create-tileset-sidescroller` and the
+  `animate*` revisions (no field), `pixelkiln pixelate` (no style), and the
+  unwrapped `/create-8-direction-object`, `/generate-with-style-v2`,
+  `/image-to-pixelart-pro`, `/animate-with-text-v2`, `/tilesets`.
 - **October 2026 Pro price cut** — PixelLab 0.4.128 moved every Pro tool from
   20/25/40 to 10/15/25 generations. Cost estimates now use the new prices,
   and `imagePro` (`generate-image-v2`) is tiered instead of a flat 40: a

package/skills/pixelkiln/references/pixellab.md

@@ -208,7 +208,15 @@ generic background-job endpoint the same way a `revision` is. The style's
 `palette` goes out as the beta `target_palette` (PixelLab 0.4.130): every
 pixel of every candidate lands on those 2–256 colours, at no extra cost.
 `paletteName` (needs `palette`) names it, and `maxColors` (2–64) caps each
-candidate's colours, with or without a palette. PixelLab's `smart` palette
+candidate's colours, with or without a palette. The same `target_palette`
+now also goes out for `imageProFlash`, `objectPro` (bases, states, `pro`
+animations), `1dir`, `tiles`, `uiAsset`, `uiElement`, Pro and Pro Flash
+characters (bases, states, portraits, outfits), top-down Pro `terrain`, and
+`interpolate`/`edit-animation` revisions, with `paletteName`/`maxColors`
+accepted on those generators' styles. Standard characters and character
+animations keep their `color_image` swatch, `pixflux` its own, and the
+costs with a palette are measured for `imagePro`, `imageProFlash`, and `tiles`, and unmeasured elsewhere (see `docs/GENERATORS.md#target-palette`).
+PixelLab's `smart` palette
 mapping is not wrapped: it is "single images only", and this endpoint
 returns a grid of candidates below 171px. Reference
 images and a style image (`reference_images`, `style_image` +