pixelkiln 0.87.0 → 0.89.0

package/docs/MANIFEST.md

@@ -64,13 +64,15 @@ not merely a label edit.
 | `source` | string | Manifest-relative committed art used instead of generation. For a set of PNG outputs (a `frames` animation, a `tiles` set) a path that is not a file is the stem of a hand edit laid beside the generated members (`<stem>-<role>.png` each); the set still generates. Mutually exclusive with `revision`. |
 | `sourceByStyle` | object | Per-style `source`, keyed by style id; wins over `source` for that style. Written by `pixelkiln edit` for a hand edit of an asset that is in several styles. |
 | `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 dependency on another asset: `image-to-image`, `inpaint`, or `outpaint`; on PixelLab also `reduce-colors`, `correct-pixelart`, `remove-background`, the animate modes (`animate`, `animate-pixminimax`, `animate-skeleton`), `interpolate`, and `edit-animation`. `engine: "pro-flash"` selects PixelLab's Pro Flash tier for `image-to-image`/`inpaint`. See [controlled revisions](REVISIONS.md). |
+| `revision` | object | Controlled dependency on another asset: `image-to-image`, `inpaint`, or `outpaint`; on PixelLab also `reduce-colors`, `correct-pixelart`, `remove-background`, `normal-map`, the animate modes (`animate`, `animate-pixminimax`, `animate-skeleton`), `interpolate`, and `edit-animation`. `engine: "pro-flash"` selects PixelLab's Pro Flash tier for `image-to-image`/`inpaint`. 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. `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). |
 | `portrait` | object | `character` styles: a bust of a base or state's south sprite, `{ "of": "<asset>", "size": 64 }`; `size` is 16, 32, 48, 64 (default), 128, or 160. See [Portraits](./CHARACTERS.md#portraits). |
 | `outfit` | object | `character` styles: an existing loop's frames re-clothed from an outfit image, `{ "of": "<loop asset>", "reference": "<image>" }`, with optional `additionalInstructions`. See [Outfit transfer](./CHARACTERS.md#outfit-transfer). |
 | `mirror` | string | Another asset of the same style flipped left to right, made locally at no cost. See [Mirrors](./CHARACTERS.md#mirrors). |
+| `vfx` | object | `vfx` styles, PixelLab only: the effect to render. `{ "preset": "explosion", "parts": [{ "name": "scorch_mark" }], "sprite": "art/chars/hero.png", "fps": 12 }`; start from one `preset` or one `recipe` (a recipe JSON or a `.vfx.json` record), with optional `parts`, `sprite`, `fps`, and `name`. Or give a `description` (with optional `artist`: `lite` or `pro`, a local PNG `sprite`, and `name`) for PixelLab's paid VFX artist instead; it excludes `preset`, `recipe`, `parts`, and `fps`. Replaces `prompt` as the required field. See [`vfx`](./GENERATORS.md#vfx) and [Described effects](./GENERATORS.md#described-effects-the-paid-vfx-artist). |
 | `scene` | object | `map` styles, PixelLab only: draw this object into a scene image, in its style. `{ "image": "scene.png", "placement": { "oval": 0.3 } }`; `placement` is `oval` or `rectangle` (a fraction, 0.05–0.95) or `mask` (a PNG the size of the scene). See [Drawing into a scene](./GENERATORS.md#drawing-into-a-scene). |
+| `connect` | object | `terrain` styles, PixelLab only: share a terrain with another set in the same style, keyed by this set's own side. `{ "lower": { "of": "coast", "terrain": "upper" } }` makes this set's lower terrain `coast`'s upper. The other set generates first; regenerating it makes this one stale. A sidescroller set connects only `lower`. Cycles are rejected. |
 | `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). |
 | `elements` | string array | `uiAsset` styles: named, auto-positioned UI scaffolds (`button`, `health_bar`, `window`, ...). Combine with `pieces`; omit both for a plain full-canvas panel. See [`uiAsset`](./GENERATORS.md#uiasset). |
@@ -79,7 +81,7 @@ not merely a label edit.
 | `concept` | string | `character` styles, `pro` bases: a manifest-relative concept image (up to 1024px) the design is seeded from. |
 | `styleCharacter` | string | `character` styles, `pro` bases: this base's style anchor, over the style's. |
 | `providerInputs` | JSON scalar/sequence map, `{}` | Named per-asset inputs consumed by the active provider. ComfyUI accepts scalars and, for `frames`, one ordered 2–64 value sequence. Image bindings upload PNG/JPEG inputs. |
-| `styles` | string array, `[]` | Restrict the asset to named styles; empty means every style. |
+| `styles` | string array, `[]` | Restrict the asset to named styles. Empty means every style of the asset's kind: `vfx` styles for an asset with a `vfx` block, every other style otherwise. |
 | `promptByStyle` | string map, `{}` | Replace only the asset prompt for a named style. |
 | `cell` | `[column,row]` | The grid cell this asset owns in a mounted sheet; see [stable-cell mounting](#stable-cell-mounting). |
 | `outputRole` | string | Select one structural output when a generator returns a set. |
@@ -119,7 +121,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`, `uiElement`, `imageProFlash`, or provider-specific `animation`/`frames`. See [GENERATORS.md](./GENERATORS.md). |
+| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, `terrain`, `isometricTile`, `imagePro`, `character`, `objectPro`, `uiAsset`, `uiElement`, `imageProFlash`, `vfx`, 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. |
@@ -130,7 +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`, Retro Diffusion, ComfyUI bindings). |
+| `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. |
 | `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. |
@@ -139,6 +143,19 @@ One asset using the fields most projects reach for:
 | `tileView` | enum | `top-down`, `high top-down`, `low top-down`, or `side`. |
 | `tileFeature` | enum | Connectable `roads`, `tileset`, or `building` structural set. |
 | `outlineMode` | enum | `outline` or `segmentation`; segmentation avoids quilted ground seams. |
+| `terrainOrientation` | `top-down` | `terrain` only. `sidescroller` makes a platform set: prompt `1). <platform body> 2). <top layer>`, 16 or 32px, no mode, view, or shape controls. |
+| `terrainMode` | `standard` | `terrain` only. `standard` or `pro`. |
+| `terrainTileSize` | `16` | `terrain` only. 16, 32, or 64 (`pro` only). |
+| `terrainTransitionSize` | `0` | `terrain` only. 0, 0.25, 0.5, or 1 (any 0–0.5 with `terrainShapeStyle`). Pro reads it as wall height; above 0.4 a Pro set has 25 tiles, standard only at 1. |
+| `terrainView` | `high top-down` | `terrain` only. `low top-down` or `high top-down`. |
+| `terrainShapeStyle` | | `terrain`, `standard` only. `square` or `round` procedural boundary. |
+| `terrainRaggedness` | `0` | `terrain`, `pro` only. Boundary noise, 0–1. |
+| `terrainRoundness` | 0.85 pro, 0.6 shape style | `terrain`, `pro` or `terrainShapeStyle`. Border corners: 0 square, 1 round, 2 cut at 45° (above 1 `pro` only). |
+| `terrainBoundaryAmplitude` | `0` | `terrain`, `pro` or `terrainShapeStyle`. How far the border meanders, 0–0.3. |
+| `terrainBoundarySeed` | `0` | `terrain`, with `terrainBoundaryAmplitude`. Which meander, an integer. |
+| `terrainStepSlope` | `0` | `terrain`, `pro` at `terrainTransitionSize` 0.25 only. 0 a cliff to 2 a gentle slope. |
+| `terrainConnectDiagonals` | `false` | `terrain`, `pro` only. Join the diagonal tiles' upper corners into one area. |
+| `terrainSpreadX` / `terrainSlopeSize` | | Deprecated: PixelLab ignores both. Still accepted. |
 | `mode` | `standard` | `character` only. `standard`, `v3`, `pro`, or `pro-flash`; see [Characters](./CHARACTERS.md). |
 | `directions` | `8` | `character` only. `4` or `8`; every engine but `standard` draws 8. |
 | `template` | `mannequin` | `character` only. Body template: `mannequin`, or `bear`, `cat`, `dog`, `horse`, `lion`; `custom` for `pro-flash`. |
@@ -242,6 +259,10 @@ Generator-specific fields are validated before planning. Important constraints:
   or style images. `enforcePalette` still holds its output to the palette.
 - `pixflux` accepts a forced `palette` and returns inline output; it has no
   style-image support.
+- `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.
 - `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`
@@ -471,13 +492,14 @@ their own page: [Characters](./CHARACTERS.md) and
 
 | Revision field | Type | Meaning |
 |---|---|---|
-| `mode` | enum, required | `image-to-image`, `inpaint`, `outpaint`, `reduce-colors`, `correct-pixelart`, `remove-background`, `animate`, `animate-pixminimax`, `animate-skeleton`, `interpolate`, or `edit-animation`. The selected provider must opt into the mode. |
-| `from` | asset id, required | Parent asset, in this asset's style unless `fromStyle` names another. 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). |
+| `mode` | enum, required | `image-to-image`, `inpaint`, `outpaint`, `reduce-colors`, `correct-pixelart`, `remove-background`, `normal-map`, `animate`, `animate-pixminimax`, `animate-skeleton`, `interpolate`, or `edit-animation`. The selected provider must opt into the mode. |
+| `from` | asset id, required | Parent asset, in this asset's style unless `fromStyle` names another. 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, and `normal-map` takes an animation's frames as one strip but refuses a set of directions; the other modes refuse it. See [Revising a whole set at once](./REVISIONS.md#revising-a-whole-set-at-once). |
 | `fromStyle` | style id | The style the parent lives in, when it is not this asset's own. The parent must be an asset in that style, and styles may depend on one another but not in a cycle. See [Across styles](./REVISIONS.md#across-styles). |
 | `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`, `remove-background`, `animate`, `animate-pixminimax`, `interpolate`, and `edit-animation`. Interpretation is provider- and model-specific. |
+| `strength` | number 0–1 | Workflow edit/denoise strength (`image-to-image`, `correct-pixelart`); rejected for `reduce-colors`, `remove-background`, `normal-map`, `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`. |
 | `removalTask` | `simple` or `complex` | `remove-background` only. `simple` (PixelLab's default) is faster for flat backgrounds; `complex` handles detailed edges. |
+| `convention` | `opengl` or `directx` | `normal-map` only. `opengl` (PixelLab's default) is green up, for Godot, Unity, and Phaser; `directx` is green down, for Unreal. A `normal-map` revision is refused in a style with `enforcePalette` or `quality`; see [Normal maps](./REVISIONS.md#normal-maps). |
 | `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`. |

package/docs/PIXELLAB.md

@@ -71,10 +71,11 @@ unapproved files. See [Manifest quality profiles](./MANIFEST.md#quality-profiles
 | `pixflux` | You need a closed palette or a full-bleed background | 1 generation |
 | `1dir` | You need references or several candidates for human review | 10 to 25 generations |
 | `tiles` | You need ground variations or a connected structural set | 10 to 25 generations |
-| `terrain` | You need a two-terrain Wang tileset (grass to water, floor to cliff) | 10 to 25 generations (unmeasured) |
+| `terrain` | You need a two-terrain Wang tileset (grass to water, floor to cliff), sets that share a terrain, or a sidescroller platform set | sidescroller 3 (measured); top-down Pro 15 or 25, standard up to 4 (PixelLab's quote) |
 | `isometricTile` | You need one standalone isometric tile, 16 to 64px | 1 generation (measured once) |
-| `imagePro` | You need a larger or non-square scene, up to 792 wide and 688 tall | 10 to 25 generations |
+| `imagePro` | You need a larger or non-square scene, up to 792 wide and 688 tall, optionally held to the style's `palette` | 10 to 25 generations |
 | `imageProFlash` | You need a still on the Pro Flash model, optionally styled from one image, 16 to 256px | 5 to 9 generations (provisional quote) |
+| `vfx` | You need an animated effect (spell, hit, explosion, aura), on its own or around a sprite | free from presets and parts; 1 to 28 when described to PixelLab's artist (lite measured at 1) |
 | `character` | You need a character in 4 or 8 directions, with states, loops, portraits, or outfits | See [Characters](./CHARACTERS.md) |
 | `objectPro` | You need a prop or creature with rotations, states, or loops but no character rig | about 6 at 64px (unmeasured) |
 | `uiAsset` | You need a UI panel composited from pieces and named elements, 192px and up | 20 generations (measured once) |
@@ -99,6 +100,91 @@ beside the submit-time `cost` estimate a wave budget spends against;
 `pixelkiln history`, `plan --json`, and the gallery show both when they
 differ (docs/ENDPOINTS.md, "Limits and billing").
 
+## What changed in PixelLab 0.4.130
+
+PixelLab 0.4.130 (October 2026) added four things. PixelKiln covers each:
+
+- **Tileset Pro.** Top-down Pro sets take roundness, connected diagonals, an
+  uneven boundary, and edge slope, and sets can share a terrain. These are
+  `terrain` style fields plus an asset's `connect`; see the
+  [manifest reference](./MANIFEST.md). Sidescroller sets use
+  `terrainOrientation: "sidescroller"`. The public API has no Pro mode for
+  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.
+- **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
+  [Generator selection](./GENERATORS.md#described-effects-the-paid-vfx-artist).
+- **Normal maps.** A `normal-map` revision makes one for a sprite or a whole
+  loop at 0.5 generations, and `pixelkiln normal-map` does it for a loose
+  file. See [Controlled asset revisions](./REVISIONS.md#normal-maps).
+
+Three have been billed live once each: a sidescroller set (3 generations),
+a lite described effect (1, its quote), and an 8-frame normal map strip
+(0.5). Top-down Pro prices and the palette use PixelLab's published
+prices.
+
+## Learn from PixelLab's tutorials
+
+PixelLab's YouTube channel teaches its web app, not PixelKiln, but most of
+its advice carries over. Two recent videos changed what we recommend.
+
+### Pro tilesets
+
+[PixelLab Pro Tilesets: Full Guide](https://www.youtube.com/watch?v=MbkqpDUFkEg)
+covers the `terrain` generator's endpoint.
+
+- End each terrain on the word "texture": `1). deep ocean water texture 2).
+  plain smooth sand texture`. Without it, Pro sometimes scatters rocks,
+  shells, or plants over the sand.
+- Keep terrain prompts short and put style words in the style's
+  `promptPrefix` or `promptSuffix`. Color, season, and outline words
+  ("autumn", "frosty", "bold black outlines") change a set more than mood
+  words do.
+- On Pro, `terrainTransitionSize` is wall height. 0 is flat ground, 0.25 a
+  low bank, and 0.5 or 1 a full wall in a 25-tile set.
+- `terrainRaggedness` roughens the border; 0.8 gives a marsh edge.
+  `terrainSpreadX` and `terrainSlopeSize` no longer change anything, because
+  PixelLab's Pro pipeline stopped reading them.
+- For clean 45° paths and coastlines, set `terrainConnectDiagonals: true`
+  and `terrainRoundness: 2`. That is the video's "Connect diagonal corners"
+  checkbox with roundness at 45°.
+- To paint ocean, sand, and grass on one map, chain sets with `connect`:
+  the sand-to-grass set's lower terrain is the ocean-to-sand set's upper.
+  Every pair of terrains that touch needs its own set, or they meet with a
+  hard edge.
+- `terrainOrientation: "sidescroller"` makes platform sets: `1). mossy stone
+  bricks texture 2). green grass texture`. The video's Pro sidescroller, at
+  64px with a taller top layer, is only in PixelLab's web app.
+
+### Animated effects
+
+[How to Make Animated Pixel Art VFX in PixelLab](https://www.youtube.com/watch?v=t8FIMv-8QpI)
+generates effects instead of rendering them. The `vfx` generator is free and
+renders the same pixels every time, so try it first. Generate when the
+effect is a drawn thing or a character's own motion, like a water hammer
+that bursts into a splash or a sword that turns into lightning.
+
+1. Draw a sheet of effects with one `imagePro` call. List one effect per
+   frame in the prompt; a 64×64 canvas returns 16 candidates to pick from.
+2. Animate the pick with an `animate-pixminimax` revision. Describe the
+   motion, not the look, and ask a loop to return to its first state.
+3. Pin an ending with `lastFrame` when the motion should land somewhere. An
+   ice crystal can grow from a few blue pixels, or a `"engine": "pro-flash"`
+   edit of the same sprite can be the ending it transforms into.
+4. Clean up. `driftThreshold` or a `reduce-colors` revision fixes
+   frame-to-frame color flicker, and `correct-pixelart` or `pixelkiln edit`
+   removes stray pixels. Check whether a loop's last frame repeats its
+   first.
+
+Pad a growing effect onto a larger canvas before animating it, since a
+revision animates its parent at the parent's own size. Long PixMiniMax clips
+can also cost more than `plan` says: PixelLab prices a 40-frame 64×64 clip
+at 6 generations, and PixelKiln estimates 3. Set `--budget` with that gap in
+mind.
+
 ## Account workflows
 
 The PixelLab adapter supports `balance`, `adopt`, `salvage`, `tag`, and the
@@ -182,14 +268,15 @@ inpainting, whole-image editing, and skeleton-driven animation (posing a
 reference image frame-by-frame from a supplied keypoint skeleton, not a text
 description) are the `revision` asset shape, not the `character` generator;
 see [Controlled asset revisions](./REVISIONS.md). 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; `pixelkiln estimate-skeleton`
+animates, interpolates, recolors, cleans up, and makes normal maps for any
+asset, a whole character or loop at once where the endpoint takes a set; `pixelkiln estimate-skeleton`
 starts a skeleton file from an image. Pro Flash stills are the
 `imageProFlash` generator, and Pro Flash edit and inpaint are a revision's
 `"engine": "pro-flash"`. 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
+and fonts, unzooming reference art, and normal maps for loose files are the
+standalone `pixelkiln font`, `pixelkiln unzoom`, and `pixelkiln normal-map`
+commands. Map Workshop
 scene composition (placing objects and characters into a map, in-scene
 inpainting, export) is a separate PixelLab product surface this adapter does
 not model at all — including PixelKiln's own `map` generator, which is

package/docs/REVISIONS.md

@@ -7,8 +7,9 @@ dependencies before submission, and records the lineage in the lockfile.
 
 The manifest and pipeline are provider-neutral. ComfyUI, PixelLab and Scenario implement
 it; PixelLab covers `image-to-image`, `inpaint`, `reduce-colors`,
-`correct-pixelart`, `remove-background`, `animate`, `animate-pixminimax`,
-`animate-skeleton`, `interpolate`, and `edit-animation`, not `outpaint` (its API has no
+`correct-pixelart`, `remove-background`, `normal-map`, `animate`,
+`animate-pixminimax`, `animate-skeleton`, `interpolate`, and `edit-animation`,
+not `outpaint` (its API has no
 canvas-expansion endpoint). ComfyUI covers every mode generically except the
 five frame-set modes (`animate`, `animate-pixminimax`, `animate-skeleton`,
 `interpolate`, `edit-animation`), which need an ordered frame set its
@@ -57,9 +58,11 @@ input to the provider workflow, not a cross-model quality guarantee.
 committed asset's drawer and use "+ New revision" under "Revisions from this
 asset" to create a child of it. On a PixelLab sprite the mode picker offers
 `image-to-image`, `inpaint`, `animate`, `animate-pixminimax`, `interpolate`,
-`reduce-colors`, `correct-pixelart`, and `remove-background`; on a PixelLab
-frame set (or a character's directions) it offers `edit-animation`,
-`reduce-colors`, and `correct-pixelart`, which take the whole set. ComfyUI
+`reduce-colors`, `correct-pixelart`, `remove-background`, and `normal-map`;
+on a PixelLab frame set (or a character's directions) it offers
+`edit-animation`, `reduce-colors`, and `correct-pixelart`, which take the whole
+set, plus `normal-map` on an animation loop. `normal-map` is hidden in a style
+that sets `enforcePalette` or `quality`. ComfyUI
 sprites get `image-to-image` and `inpaint`; other providers get
 `image-to-image`. The form asks only for the new asset id, the instruction or
 motion, and the mode's own options (strength, frames, fps, colours,
@@ -233,6 +236,59 @@ generation.
 or `complex` (slower, for detailed edges). `description` is an optional hint
 naming the foreground. Both are rejected on other modes, as is `strength`.
 
+### Normal maps
+
+`normal-map` calls PixelLab's `/normal-map` and returns the parent's normal
+map, so a game engine can light the sprite. The map is the parent's size: RGB
+is the way each pixel faces, and alpha is 255 where the sprite shows and 0
+elsewhere. It is a background job, and costs 0.5 generation per call,
+charged only when the map is delivered (PixelLab's documented price; not yet
+measured here).
+
+```jsonc
+{
+  "styles": {
+    "lit": { "generator": "map", "outDir": "art/normals" }
+  },
+  "assets": {
+    "hero-walk-east-normals": {
+      "prompt": "normal map",
+      "styles": ["lit"],
+      "revision": { "mode": "normal-map", "from": "hero-walk-east", "fromStyle": "chars", "convention": "opengl" }
+    }
+  }
+}
+```
+
+- `convention` is `opengl` (PixelLab's default: green up, for Godot, Unity,
+  and Phaser) or `directx` (green down, for Unreal). It is rejected on other
+  modes and enters the spec hash only when set. `strength` is refused.
+- The parent must be a PNG, 8 to 512 pixels per side; both are checked at
+  plan time.
+- **A loop goes as one strip.** When the parent is an animation (its
+  `-frame-NN.png` members), every frame is laid left to right in one image
+  and sent with `frames: N`, up to 32. PixelLab shapes the first frame and
+  carries it to the rest, so the light holds steady across the loop instead
+  of flickering. The returned strip is cut back into `-frame-NN.png` files
+  under the parent's roles, keeping its playback rate. A whole loop is one
+  call, so it costs 0.5 too.
+- **A character's directions are refused.** They are separate views, not
+  frames of one motion: sent as a strip, each would be shaped from the first
+  direction, and one call per direction would put several paid jobs behind
+  one lock entry with no way to recover half of them. Make one `normal-map`
+  revision per direction, each from an asset whose `source` is that
+  direction's file.
+- **A normal map is lighting data, not art.** Its colours are directions, so
+  palette snapping or the quality gate's grid repair would wreck it. A
+  `normal-map` revision in a style that sets `enforcePalette` or `quality` is
+  refused at plan time; put it in a style without either (as `lit` above) and
+  name the parent's style with `fromStyle`. A `mirror` of a normal map is
+  refused too: flipping the pixels leaves every red channel pointing the old
+  way.
+
+For a loose file outside the manifest, `pixelkiln normal-map` does the same
+job (see [CLI](./CLI.md#normal-map)).
+
 ### Revising a whole set at once
 
 Both modes also take a parent that is a **set** rather than one image: a
@@ -272,6 +328,8 @@ its playback rate.
   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.
+- `normal-map` takes an animation loop as one strip but refuses a set of
+  directions (see [Normal maps](#normal-maps)).
 - 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.
 
@@ -660,6 +718,13 @@ further — there is nothing to ask.
   CLI-only-and-never-in-the-submission-path decision. Same unverified-live
   caveat as `animate`/`animate-pixminimax`, sourced from the live
   `animate_with_skeleton_v3` MCP tool schema rather than an observed call.
+- `normal-map` calls `/normal-map` (PixelLab 0.4.130), a background job whose
+  map is `last_response.image`; a loop's frames go and come back as one
+  horizontal strip, cut into per-frame files on poll. See
+  [Normal maps](#normal-maps). Measured once through `pixelkiln normal-map`:
+  an 8-frame strip billed exactly 0.5 generations and came back the same
+  size with matching alpha (docs/ENDPOINTS.md). The revision mode shares
+  that request but has not run live itself.
 
 - The mask convention is fixed, not graph-defined like ComfyUI's: white marks
   the area to generate, black the area to preserve. There is no way to flip it.

package/docs/TILES.md

@@ -37,9 +37,10 @@ renumbered by array position.
 
 ### The `terrain` generator's shape
 
-`terrain` (`/create-tileset`, [`docs/GENERATORS.md`](GENERATORS.md)) is a
-different PixelLab endpoint from `tiles`' `tileFeature: "tileset"` above, and
-its response carries no `tile_rules` bitmask at all. Instead each tile names
+`terrain` (`/create-tileset`, or `/create-tileset-sidescroller` for a
+sidescroller set; [`docs/GENERATORS.md`](GENERATORS.md)) is a different
+PixelLab endpoint from `tiles`' `tileFeature: "tileset"` above, and its
+response carries no `tile_rules` bitmask at all. Instead each tile names
 which terrain occupies its four corners directly:
 
 ```jsonc
@@ -50,12 +51,21 @@ which terrain occupies its four corners directly:
       "terrainTiles": [
         { "role": "tile-00-none", "corners": { "NW": "upper", "NE": "upper", "SW": "upper", "SE": "upper" } },
         { "role": "tile-01-nw-ne-sw-se", "corners": { "NW": "lower", "NE": "lower", "SW": "lower", "SE": "lower" } }
-      ]
+      ],
+      // Each terrain's base tile id; a connected set sends one of these.
+      "terrainIds": { "lower": "<uuid>", "upper": "<uuid>" }
     }
   }
 }
 ```
 
+A sidescroller set names its terrains `["central", "background"]` while its
+corners still say `lower` (the platform) and `upper` (empty air; the
+all-`upper` tile is blank). PixelKiln records the corner vocabulary,
+`["lower", "upper"]`, as `terrainTypes` so masks match, and keeps
+PixelLab's names as `providerTerrainTypes` beside `view: "side"`. In Tiled
+and Godot the platform is terrain 0.
+
 `normalizeTerrainTiles()` (`src/pipeline/tileset-export.ts`) turns this into
 the same `NormalizedTileRules` shape `tileRules` would have produced directly:
 `ruleType: "corner"`, `arity: 4`, `terrains` from `terrainTypes`, and a mask
@@ -70,9 +80,15 @@ role — correct here because `terrainTiles` and the output list are pushed in
 the same loop, but worth knowing if either is ever reordered independently.
 
 A tile whose corner is `"transition"` (the extra ring PixelLab adds at
-`terrainTransitionSize: 1`) has no bit of its own in a two-terrain corner
+`terrainTransitionSize: 1`, or 0.5 on Pro) has no bit of its own in a two-terrain corner
 mask; it is folded into whichever of `terrains[0]`/`terrains[1]` it isn't.
 
+That 25-tile layout covers 21 distinct corner combinations. Four
+wall-continuation tiles share their corners with a twin and differ only in
+`pattern_4x4`, which PixelLab says is the field to match on. PixelKiln
+stores each tile's `pattern4x4` but builds masks from `corners`, so each
+twin pair gets the same mask.
+
 ## Command
 
 ```bash
@@ -205,7 +221,15 @@ isometric-corner-names bug; the counts alone did not.
   placement semantics would have to be invented.
 - A `terrain` asset's `"transition"` corners collapse into a two-color mask
   (see above); the cliff-tier 25-tile set exports, but its middle transition
-  ring is not distinguished from the two named terrains in Tiled/Godot.
+  ring is not distinguished from the two named terrains in Tiled/Godot, and
+  its four wall-continuation twins export with duplicate masks.
+- A `terrain` set exports alone. A connected set (`connect` in the
+  manifest, `lower_base_tile_id`/`upper_base_tile_id` in the API) shares a
+  terrain with another set, the way PixelLab's
+  [Pro tilesets guide](https://www.youtube.com/watch?v=MbkqpDUFkEg) paints
+  ocean, sand, grass, path, and cliffs on one map, but each set still
+  exports as its own two-terrain Tiled Wang set or Godot terrain set.
+  PixelKiln does not merge connected sets into one engine terrain set yet.
 - Godot edge/side masks on an isometric or oblique tile remain generic- or
   Tiled-only; see Godot 4 above.
 - Export never changes source PNGs or the lockfile.

package/package.json

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