pixelkiln 0.89.0 → 0.89.2

package/docs/ARCHITECTURE.md

@@ -112,6 +112,14 @@ retain:
   same output bytes, which is what lets a restore reproduce a recorded hash.
   It is compared against the manifest on every `plan`: a difference is
   `recoverable`, never `stale`, because no provider work is involved;
+- `terrainSettings`, `terrain` entries only: the settings the request was
+  sent with that `specHash` leaves out (the older mode, transition size,
+  view, shape, and raggedness knobs, and each terrain's description as
+  sent). Hashing them would have made every existing terrain entry stale,
+  so `plan` compares this record instead and reports `stale` naming each
+  changed setting. An entry from before it was recorded has none and is
+  taken as current. A history entry keeps its own, so a restore is
+  compared against the generation it brought back;
 - temporary `supersededOutputs[]` ownership hashes while a stale generation is
   being replaced;
 - provider-specific metadata under a provider-id namespace;

package/docs/ENDPOINTS.md

@@ -401,13 +401,13 @@ normal-map` ([REVISIONS.md](./REVISIONS.md#normal-maps)).
 
 ---
 
-## Tilesets: mostly schema, one sidescroller measured
+## Tilesets: measured once per kind
 
 Called out separately because these are the most capable endpoints for level art
-and they are relevant to the disc-golf game. **Top-down costs are unmeasured**:
-pixelkiln plans a top-down set at PixelLab's own quote (Pro 15 for tiles up to
-32px, 25 at 64px; standard 4, the top of its quoted 1 to 4). The sidescroller
-cost below is measured.
+and they are relevant to the disc-golf game. pixelkiln plans a top-down set
+at PixelLab's own quote (Pro 15 for tiles up to 32px, 25 at 64px; standard 4,
+the top of its quoted 1 to 4). Pro at 32px and the sidescroller are measured
+below; Pro at 64px and standard are not.
 
 `POST /tilesets` (top-down) and `/tilesets-sidescroller` are the current
 versions; `/create-tileset*` are the older aliases with identical schemas.
@@ -437,6 +437,24 @@ are the base tile ids, so set A's `upper` id sent as set B's
 `lower_base_tile_id` makes the two share that terrain. pixelkiln records them
 as `terrainIds` when it polls a set.
 
+### Pro top-down and a connected pair, measured
+
+October 2026, through `pixelkiln gen` on the website's showcase project
+(`website/art/pixellab-0.4.130`). Two Pro sets at 32px with
+`terrainRoundness: 2` and `terrainConnectDiagonals: true`:
+
+- `ocean-sand` ("deep ocean water texture" to "plain smooth sand texture")
+  billed **exactly 15 generations**, 16 tiles. Its `metadata.terrain_ids`
+  held both a `lower` and an `upper` id, recorded as `terrainIds`.
+- `sand-grass` ("plain smooth sand texture" to "plain short grass texture")
+  with `connect: { lower: { of: "ocean-sand", terrain: "upper" } }` stayed
+  blocked until `ocean-sand` was downloaded, then sent `ocean-sand`'s upper
+  id as `lower_base_tile_id` and billed **exactly 15**.
+- Painted together on one vertex grid, the two sets join at the shared sand
+  with matching colour. The second set's sand carries fewer pebbles, so the
+  ring where it meets the first set's sand is visible up close. "plain smooth
+  sand texture" still came back with pebbles in the first set.
+
 ### Sidescroller, measured
 
 One `POST /create-tileset-sidescroller` call, 16px tiles,

package/docs/GENERATORS.md

@@ -12,7 +12,7 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 | Exact fixed palette | `pixflux`, or `imagePro` for a larger or non-square canvas | 1 generation (`imagePro`: 10–25) | 1 inline image (`imagePro`: 1–64 by size) |
 | Candidate variety, richer rendering, future rotation/animation | `1dir` | 10–25 generations | 4–64 by size |
 | Ground tiles or connectable structural sets | `tiles` | 10–25 generations | variations or complete set |
-| Two-terrain Wang tileset for elevation (grass to water, floor to cliff), or a sidescroller platform set | `terrain` | Pro 15, or 25 at 64px; standard plans at 4 (PixelLab's quotes); sidescroller 3 (measured) | 16 or 25 tiles |
+| Two-terrain Wang tileset for elevation (grass to water, floor to cliff), or a sidescroller platform set | `terrain` | Pro 15 at 32px and sidescroller 3 (measured); Pro 25 at 64px, standard plans at 4 (PixelLab's quotes) | 16 or 25 tiles |
 | Platform tileset for a sidescroller (stone body, grass top) | `terrain`, `terrainOrientation: "sidescroller"` | 3 generations | 16 tiles |
 | A single elevation tile — a raised mesa, a cliff block | `isometricTile` | 1 generation | 1 |
 | Larger or non-square scene or background, up to 792 wide and 688 tall | `imagePro` | 10–25 generations by canvas | 1–64 by size |

package/docs/MANIFEST.md

@@ -155,7 +155,7 @@ One asset using the fields most projects reach for:
 | `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. |
+| `terrainSpreadX` / `terrainSlopeSize` | | Deprecated: PixelLab ignores both. Still accepted. Changing any `terrain*` field marks the set stale: the older ones (mode, transition size, view, shape style, raggedness, these two) and the descriptions as sent are recorded per lock entry as `terrainSettings` rather than hashed, compared as written (an explicit default counts as a change), and absent on sets generated before that record existed, which stay current. |
 | `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`. |

package/docs/PIXELLAB.md

@@ -71,7 +71,7 @@ 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), 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) |
+| `terrain` | You need a two-terrain Wang tileset (grass to water, floor to cliff), sets that share a terrain, or a sidescroller platform set | Pro 15 at 32px and sidescroller 3 (measured); Pro 25 at 64px and 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, 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) |
@@ -121,10 +121,11 @@ PixelLab 0.4.130 (October 2026) added four things. PixelKiln covers each:
   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.
+Each has been billed live and matched the plan: a Pro 32px set (15) and a
+second set connected to it (15), a sidescroller set (3), a 64×64 `imagePro`
+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 shows
+the results.
 
 ## Learn from PixelLab's tutorials
 

package/docs/REVISIONS.md

@@ -242,8 +242,8 @@ naming the foreground. Both are rejected on other modes, as is `strength`.
 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).
+charged only when the map is delivered (measured: a sprite and an 8-frame
+strip each billed exactly 0.5).
 
 ```jsonc
 {
@@ -723,8 +723,8 @@ further — there is nothing to ask.
   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.
+  size with matching alpha (docs/ENDPOINTS.md). The revision mode billed
+  0.5 on a 64×64 sprite too.
 
 - 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/package.json

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

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

@@ -84,6 +84,16 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   15 up to 32px and 25 at 64px, standard 4 (the top of its quoted 1 to 4),
   sidescroller 3. What is still open is in
   [Pro tilesets](#pro-tilesets-what-is-left-after-04130) below.
+- **Older terrain fields as identity.** `terrainMode`,
+  `terrainTransitionSize`, `terrainRaggedness`, `terrainShapeStyle`,
+  `terrainView`, the deprecated `terrainSpreadX`/`terrainSlopeSize`, and
+  the descriptions as sent (the prompt wrapped in the style's prefix and
+  suffix) never entered `specHash`, and hashing them would have made every
+  existing terrain entry stale at once. Closed without a migration: submit
+  records them on the entry as `terrainSettings` (kept through history and
+  `restore --generation`), and the plan marks a set stale naming each one
+  that changed. An entry from before the record has none and stays current
+  until it is next regenerated. The 0.4.130 fields stay hashed (when set).
 - **Pro-tier full-bleed background generation** (`generate-image-v2`, PixelLab's
   Pro image tier) at arbitrary custom aspect ratios (not just square) —
   already measured at 40 generations in `docs/ENDPOINTS.md`, but `pixflux`
@@ -363,13 +373,16 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   standalone `pixelkiln normal-map` command. Styles with `enforcePalette` or
   `quality` refuse it so nothing palette-snaps a normal map. **Measured
   once**: an 8-frame 1304×26 strip billed exactly 0.5 and came back the same
-  size with matching alpha.
+  size with matching alpha. The revision mode then billed 0.5 on a 64×64
+  sprite through `pixelkiln gen`.
 - **Target palette for Create Image Pro** (`target_palette` on
   `/generate-image-v2`, PixelLab 0.4.130) — an `imagePro` style's `palette`
   is now sent as the colors every pixel must use, with `maxColors` (2 to 64
   per image) and `paletteName`. The beta `smart` mapping is left out because
   PixelLab documents it as single-image only and `imagePro` returns a grid of
-  candidates below 171px. Cost unchanged and unmeasured with a palette.
+  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.
 - **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
@@ -441,18 +454,16 @@ connecting different tilesets") are now mostly covered; see the closed
   `/create-tileset-sidescroller` has no `mode` field, and its tile size is
   16 or 32. pixelkiln's sidescroller sets use whatever model that endpoint
   runs.
-- **Older terrain fields are not identity.** `terrainMode`,
-  `terrainTransitionSize`, `terrainRaggedness`, `terrainShapeStyle`, and
-  `terrainView` never entered `specHash`, so changing one does not mark a set stale. The 0.4.130 fields
-  are hashed (when set). Hashing the older ones would make every existing
-  terrain lock entry stale at once, so it needs a deliberate migration.
 - **Wall-continuation twins export as duplicates.** The 25-tile layout has
   21 distinct corner combinations. Four tiles share corners with a twin and
   differ only in `pattern_4x4`, which pixelkiln records but cannot express in
   a four-bit Tiled/Godot corner mask.
-- **Unexercised live:** `lower_base_tile_id`/`upper_base_tile_id`, every
-  new shape control, and the top-down prices (Pro 15 or 25, standard planned
-  at 4 from PixelLab's quoted 1 to 4). Sidescroller tile counts at transition
+- **Measured once:** a Pro 32px set billed exactly 15, and a second set
+  connected to it through `lower_base_tile_id` billed exactly 15 and shared
+  its sand (docs/ENDPOINTS.md). `terrainRoundness: 2` with
+  `terrainConnectDiagonals` gave clean 45° edges. **Unexercised live:**
+  Pro at 64px, standard sets, `upper_base_tile_id`, and the other shape
+  controls. Sidescroller tile counts at transition
   sizes other than 0.25 are assumed to be 16. The one sidescroller call
   returned `metadata.transition_size: 0.0` although 0.25 was sent.
 - **Prompting advice** lives in the skill reference: end each terrain on

package/skills/pixelkiln/references/pixellab.md

@@ -24,7 +24,7 @@ providers, or before any PixelLab account operation.
 | `pixflux` | Closed palettes or full-bleed backgrounds up to 400×400 | 1 generation |
 | `1dir` | Reference-guided work or several candidates | 10–25 generations |
 | `tiles` | Ground variations or connected structures | 10–25 generations |
-| `terrain` | A two-terrain Wang tileset for elevation (grass-to-water, floor-to-cliff), or a sidescroller platform set | Sidescroller **3**, measured. Top-down plans at PixelLab's quote: Pro 15 (up to 32px) or 25 (64px), standard 4 (quoted 1–4) |
+| `terrain` | A two-terrain Wang tileset for elevation (grass-to-water, floor-to-cliff), or a sidescroller platform set | Sidescroller **3**, measured. Pro **15** at 32px, measured (a connected second set also billed 15). Pro 25 at 64px and standard 4 (quoted 1–4) are PixelLab's quotes |
 | `imagePro` | A larger or non-square background/scene, or real style transfer; takes the style `palette` as a hard constraint | **10–25 generations** by canvas (64px billed 10; a flat 40 before October 2026) |
 | `character` | A character in 4 or 8 directions, its poses (`state`), its loops (`animation`), bust `portrait`s, and `outfit` transfers onto a loop | 1 per standard base, 6 per pro-flash base at 64px (1 from a `reference`), 20–40 per pose or portrait, 1 per template loop per direction (2–4 as `skeleton-v3`), 20 per outfit (measured once) |
 | `objectPro` | A prop, creature, or vehicle that needs rotations, states, or loops but has no character rig | 6 per base at 64px (1 from a `reference`), **unmeasured**; assumed to match `character` pro-flash |
@@ -127,6 +127,16 @@ reads it:
 both now, so leave them out. Reference images, a forced palette, and the
 remaining tunables (`tileStrength`, `tilesetAdherence`) are not modeled.
 
+Changing any terrain setting marks the set stale. The Pro shape controls
+are in `specHash`; the older ones (`terrainMode`, `terrainTransitionSize`,
+`terrainRaggedness`, `terrainShapeStyle`, `terrainView`, the deprecated
+pair) and the style's `promptPrefix`/`promptSuffix` are recorded on the
+lock entry as `terrainSettings` instead, and `plan` names the one that
+changed ("terrainTransitionSize changed from 0.25 to 0.5"). A setting is
+compared as written: adding `terrainMode: "standard"` to a style that left
+it out is a change, even though it is the default. A set generated before
+this record existed has none and stays current until it is regenerated.
+
 **Connected sets.** An asset's `connect` makes one of its terrains the very
 terrain of another set in the same style, so ocean, sand, and grass paint on
 one map: `"connect": { "lower": { "of": "coast", "terrain": "upper" } }` is