pixelkiln 0.89.1 → 0.89.3

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

@@ -406,8 +406,8 @@ normal-map` ([REVISIONS.md](./REVISIONS.md#normal-maps)).
 Called out separately because these are the most capable endpoints for level art
 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.
+the top of its quoted 1 to 4). Every kind is measured below: Pro billed
+exactly its quote at 32px and 64px, and standard billed 3, under the plan.
 
 `POST /tilesets` (top-down) and `/tilesets-sidescroller` are the current
 versions; `/create-tileset*` are the older aliases with identical schemas.
@@ -437,6 +437,32 @@ 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 at 64px, edge slope, and standard sets, measured
+
+A second round on the same showcase project billed 46 generations in all
+(balance 5055 to 5009), each set exactly as below:
+
+- `lava-floor`: Pro, 64px, `terrainTransitionSize: 0.5`,
+  `terrainRaggedness: 0.4`, `terrainBoundaryAmplitude: 0.15`,
+  `terrainBoundarySeed: 3`, prompt `1). glowing lava texture 2). dark dungeon
+  stone floor texture 3). crumbling dungeon brick wall`. Billed **exactly
+  25** and returned **25 tiles** covering **21** distinct corner
+  combinations, which confirms that Pro switches to the tall-wall layout at
+  0.5, not only at 1, and that four tiles are corner twins. The third
+  description became the brick wall dropping into the lava.
+- `swamp-marsh`: Pro, 32px, `terrainTransitionSize: 0.25`,
+  `terrainStepSlope: 1.5`, `terrainRaggedness: 0.8`. Billed **exactly 15**,
+  16 tiles, with a ragged bank between the water and the marsh grass.
+- `lake-grass` and `path-grass`: standard, 32px. Each billed **3**, under the
+  planned 4. `path-grass` used `connect: { upper: { of: "lake-grass",
+  terrain: "upper" } }`, sent `upper_base_tile_id`, and its recorded
+  `terrain_ids.upper` came back identical to `lake-grass`'s upper id. The
+  standard sets look flatter, with a hard edge, as PixelLab's tilesets
+  tutorial describes.
+
+pixelkiln keeps connected sets in one style, and a style fixes
+`terrainMode`, so a standard set cannot connect to a Pro set.
+
 ### Pro top-down and a connected pair, measured
 
 October 2026, through `pixelkiln gen` on the website's showcase project

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 at 32px and sidescroller 3 (measured); Pro 25 at 64px, standard plans at 4 (PixelLab's quotes) | 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, Pro 25 at 64px, standard 3 (all measured; standard plans at 4) | 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 | Pro 15 at 32px and sidescroller 3 (measured); Pro 25 at 64px and 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, 25 at 64px, standard 3, sidescroller 3 (all measured; standard plans at 4) |
 | `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,8 +121,9 @@ 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).
 
-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`
+Each has been billed live and matched the plan: Pro sets at 32px (15) and
+64px (25, 25 tiles at transition 0.5), a second set connected to the first
+(15), standard sets (3 each), 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.89.1",
+  "version": "0.89.3",
   "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`
@@ -444,11 +454,6 @@ 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
@@ -456,9 +461,12 @@ connecting different tilesets") are now mostly covered; see the closed
 - **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
+  `terrainConnectDiagonals` gave clean 45° edges. A second round confirmed
+  Pro at 64px (exactly 25, and 25 tiles at transition 0.5), edge slope and
+  an uneven boundary (15 at 32px), standard sets (3 each, under the planned
+  4), and connecting through `upper_base_tile_id`. **Still open:** a
+  standard set cannot connect to a Pro set, because connected sets share a
+  style and a style fixes the mode. 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. 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 |
+| `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 **3** measured too; standard plans at 4, the top of PixelLab's quoted 1–4 |
 | `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
@@ -136,7 +146,8 @@ the next wave), PixelLab draws the shared terrain from its base tile, and
 regenerating the other set makes this one stale. Sharing a terrain makes it
 available, not blendable: two terrains with no set of their own between
 them still meet with a hard (in PixelLab's map tool, black) edge, so plan a
-set for every pair that touches.
+set for every pair that touches. Connected sets share one style, and a style
+fixes `terrainMode`, so a standard set cannot connect to a Pro one.
 
 **Sidescroller sets.** `terrainOrientation: "sidescroller"` switches to
 `/create-tileset-sidescroller`: a platform seen from the side. The prompt is