pixelkiln 0.3.0 → 0.4.0

package/docs/PROVIDER_BENCHMARK.md

@@ -0,0 +1,134 @@
+# Environment provider benchmark
+
+This benchmark compares PixelLab and Retro Diffusion on three 256×256 game-art
+briefs. Each brief has two attempts. The test uses the same prompt text and seed
+numbers for both providers, but seeds are not portable between models.
+
+The benchmark tests the adapters that PixelKiln ships. It does not rank every
+model or endpoint sold by either provider.
+
+## Setup
+
+| Brief | PixelLab route | Retro Diffusion style | Intended output |
+|---|---|---|---|
+| Mountain observatory | `map`, high top-down view | `rd_plus__isometric_asset` | Isolated building on a snowy ridge |
+| River gate | `map`, low top-down view | `rd_plus__topdown_asset` | Isolated landmark spanning water |
+| Alpine valley | `pixflux`, background kept | `rd_plus__environment` | Full scenic background |
+
+Both manifests request 256×256 output with seeds `31415` and `27182`. The
+provider-specific route or style is allowed to do its job. No image was picked,
+edited, cropped, or post-processed.
+
+PixelLab rejected `view: "isometric"` on the `map` endpoint with HTTP 422. The
+successful observatory attempts use the supported `high top-down` view while
+the shared prompt still asks for an isometric three-quarter view. This is a
+real adapter constraint, so the benchmark records it instead of hiding it.
+
+The committed manifests and lockfiles are here:
+
+- [PixelLab manifest](../benchmarks/provider-environments/pixellab/pixelkiln.manifest.json)
+- [PixelLab lockfile](../benchmarks/provider-environments/pixellab/pixelkiln.lock.json)
+- [Retro Diffusion manifest](../benchmarks/provider-environments/retrodiffusion/pixelkiln.manifest.json)
+- [Retro Diffusion lockfile](../benchmarks/provider-environments/retrodiffusion/pixelkiln.lock.json)
+
+## Mountain observatory
+
+Prompt: `a compact stone observatory built into a snowy mountain ridge,
+isometric three-quarter view, cedar roof, warm windows, isolated with no
+scenery`
+
+| PixelLab A | PixelLab B | Retro Diffusion A | Retro Diffusion B |
+|---|---|---|---|
+| ![PixelLab mountain observatory attempt A](../website/public/benchmarks/provider-environments/pixellab/isolated/a/mountain-observatory.png) | ![PixelLab mountain observatory attempt B](../website/public/benchmarks/provider-environments/pixellab/isolated/b/mountain-observatory.png) | ![Retro Diffusion mountain observatory attempt A](../website/public/benchmarks/provider-environments/retrodiffusion/isolated/a/mountain-observatory.png) | ![Retro Diffusion mountain observatory attempt B](../website/public/benchmarks/provider-environments/retrodiffusion/isolated/b/mountain-observatory.png) |
+
+PixelLab followed more of the brief. Both attempts place a substantial stone
+building on a snowy ridge, and the first reads as an observatory. Retro
+Diffusion produced tidy cutouts, but both are small cabins on snow-covered
+rocks. The observatory and mountain-ridge ideas mostly disappeared.
+
+The trade-off is file readiness. Retro Diffusion removed the background and
+used 35 and 36 colors. PixelLab returned opaque pale backgrounds and used 264
+and 266 colors. PixelLab wins prompt coverage. Retro Diffusion needs less
+cleanup before placement in a game map.
+
+## River gate
+
+Prompt: `a fortified village gate spanning a narrow river, three-quarter
+top-down view, stone towers, timber bridge, isolated with no scenery`
+
+| PixelLab A | PixelLab B | Retro Diffusion A | Retro Diffusion B |
+|---|---|---|---|
+| ![PixelLab river gate attempt A](../website/public/benchmarks/provider-environments/pixellab/topdown/a/river-gate.png) | ![PixelLab river gate attempt B](../website/public/benchmarks/provider-environments/pixellab/topdown/b/river-gate.png) | ![Retro Diffusion river gate attempt A](../website/public/benchmarks/provider-environments/retrodiffusion/topdown/a/river-gate.png) | ![Retro Diffusion river gate attempt B](../website/public/benchmarks/provider-environments/retrodiffusion/topdown/b/river-gate.png) |
+
+All four results are usable concepts. PixelLab shows more of the surrounding
+riverbank and makes the bridge-water relationship obvious. Its outputs are
+opaque scene patches. Retro Diffusion gives cleaner standalone fortifications.
+Attempt B carries water through the gate; attempt A reads more like a drawbridge
+than a river crossing.
+
+PixelLab again follows the whole brief more reliably. Retro Diffusion is easier
+to drop onto an existing map because its outputs have 56% to 64% transparent
+pixels. The Retro Diffusion files also stay between 43 and 47 colors, compared
+with PixelLab's 226 to 240.
+
+## Alpine valley background
+
+Prompt: `a wide alpine valley at dusk, layered mountains, pine forest, winding
+river, small warm-lit village, full-bleed scenic background`
+
+| PixelLab A | PixelLab B | Retro Diffusion A | Retro Diffusion B |
+|---|---|---|---|
+| ![PixelLab alpine valley attempt A](../website/public/benchmarks/provider-environments/pixellab/background/a/alpine-valley.png) | ![PixelLab alpine valley attempt B](../website/public/benchmarks/provider-environments/pixellab/background/b/alpine-valley.png) | ![Retro Diffusion alpine valley attempt A](../website/public/benchmarks/provider-environments/retrodiffusion/background/a/alpine-valley.png) | ![Retro Diffusion alpine valley attempt B](../website/public/benchmarks/provider-environments/retrodiffusion/background/b/alpine-valley.png) |
+
+PixelLab's Pixflux route is the surprise here. Both results preserve the wide
+valley, layered mountains, dusk light, winding river, and tiny settlement. They
+also use only 22 and 38 colors. The shapes read cleanly at native size.
+
+Retro Diffusion produced attractive scenes with stronger foreground framing
+and more conventional depth. They feel like places the player could enter, but
+the framing narrows the valley and pushes the result toward illustration rather
+than a reusable background layer. They use 37 and 46 colors.
+
+For this brief, PixelLab wins on prompt coverage, graphic clarity, consistency,
+and cost. Retro Diffusion wins if the desired result is a closer, more cinematic
+scene.
+
+## Cost and operational results
+
+| Provider | Successful images | Charged amount | Final balance |
+|---|---:|---:|---:|
+| PixelLab | 6 | 6 generations | 4,415 generations |
+| Retro Diffusion | 6 | $0.348 | $0.135 |
+
+PixelLab charged one generation per image. Retro Diffusion quoted and charged
+$0.058 per RD Plus image.
+
+The run also caught two integration details:
+
+- PixelLab's `map` endpoint rejected the literal `isometric` view. PixelKiln
+  should document or validate the accepted values before submission.
+- Retro Diffusion rounded its live quote up from PixelKiln's formula result of
+  $0.057768 to $0.058. PixelKiln now rounds offline estimates up to the live
+  quote precision, so planning remains a safe ceiling.
+
+Both manifests now pass `doctor`, report a current plan, and have six healthy
+PNG cache entries.
+
+## Recommendation
+
+For large isolated buildings or landmarks, start with PixelLab when prompt
+coverage matters most. Budget for background cleanup. Start with Retro
+Diffusion when a transparent, compact, low-color asset matters more than
+capturing every noun in a complex prompt.
+
+For full scenic backgrounds, start with PixelLab Pixflux. These two attempts
+were cheaper and more faithful to the brief. Try Retro Diffusion when you want
+foreground framing and a closer illustrated scene.
+
+Do not ask either provider for one giant finished level. Generate terrain,
+background, buildings, landmarks, and foreground pieces separately. Compose
+them in the engine, then use integer nearest-neighbor scaling for display.
+
+This sample is useful, not definitive. Two attempts expose obvious tendencies,
+but they do not measure every style, prompt family, or model update. Rerun the
+committed manifests when either provider changes its models.

package/docs/README.md

@@ -10,6 +10,8 @@ This source also renders at
 | Guide | Use it for |
 |---|---|
 | [Getting started](./GETTING_STARTED.md) | Install from a checkout, create or adopt a project, run the everyday workflow, and decide what belongs in Git. |
+| [Set up PixelLab](./PIXELLAB.md) | Configure the production provider, choose a generator, and use its account workflows. |
+| [Set up Retro Diffusion](./RETRO_DIFFUSION.md) | Configure the experimental provider, choose a style, and understand its live-tested boundary. |
 | [CLI reference](./CLI.md) | Every command and flag, offline/provider requirements, JSON output, and exit behavior. |
 | [Manifest reference](./MANIFEST.md) | Every style and asset field, inheritance, generator-specific constraints, mounting, and schema validation. |
 | [Agent workflows](./AGENTS.md) | Install the official skill and pair agent guidance with the deterministic CLI. |
@@ -19,6 +21,7 @@ This source also renders at
 | Guide | Use it for |
 |---|---|
 | [Generators](./GENERATORS.md) | Choose between `map`, `1dir`, `pixflux`, and `tiles`; understand measured costs and capability trade-offs. |
+| [Environment provider benchmark](./PROVIDER_BENCHMARK.md) | Compare PixelLab and Retro Diffusion on buildings, landmarks, backgrounds, cost, transparency, and prompt coverage. |
 | [Derived artifacts](./ARTIFACTS.md) | Pack, mount, and export; provenance companions; ownership; force takeover; transactional and crash recovery. |
 | [Recovery and account safety](./RECOVERY.md) | Restore, caches, adopt, salvage, cross-project claims, tagging, and confirmed purge. |
 | [Quality gates](./QUALITY.md) | Plan, doctor, audit, cache checks, JSON contracts, and CI usage. |
@@ -31,7 +34,7 @@ This source also renders at
 | [Library API](./LIBRARY.md) | Public TypeScript imports for planning, auditing, providers, packing, exporting, and managed artifact writes. |
 | [Tiles and engine exports](./TILES.md) | Structural tile roles, provider rule preservation, generic JSON, Tiled Wang sets, and Godot terrain sets. |
 | [Measured PixelLab endpoints](./ENDPOINTS.md) | Live-account cost and payload research, endpoint recipes, limits, and unresolved API behavior. |
-| [Provider notes](../PROVIDERS.md) | Current provider seam and the next adapter work. |
+| [PixelLab vs. Retro Diffusion](../PROVIDERS.md) | Provider selection, costs, adapter capabilities, confidence, and next work. Start with the provider-specific setup guides above when you are ready to configure a project. |
 
 ## Project policies
 

package/docs/RECOVERY.md

@@ -23,7 +23,8 @@ retries at zero generation cost.
 
 Two ignored caches accelerate recovery:
 
-- `.pixelkiln/cache/<sha256>.png`: content-addressed generated PNG bytes;
+- `.pixelkiln/cache/<sha256>.png` or `<sha256>.gif`: content-addressed,
+  structurally validated generated media bytes;
 - `pixelkiln.cache.json`: provider object id → remote image hash.
 
 ```bash
@@ -90,7 +91,7 @@ rename them before treating them as stable application ids.
 
 For a single project, its own lockfile is the whole claim set. On a shared
 account with several sibling projects, repeating `--claims` on every salvage
-run is easy to get wrong — a forgotten lockfile makes another project's paid
+run is easy to get wrong. A forgotten lockfile makes another project's paid
 art look unclaimed. `workspace` fixes that by registering every sibling once,
 outside any one manifest:
 
@@ -104,13 +105,13 @@ pixelkiln workspace claims
 `workspace status` reports aggregate provider, spend-by-unit, and plan state
 per project, offline. `workspace claims` validates the catalog and emits the
 exact union of `objectId`/`reviewObjectId`/`jobId` across every registered
-lock — the same union rule `--claims` uses, so the two paths cannot drift.
+lock. This is the same union rule `--claims` uses, so the two paths cannot drift.
 
 A registered lockfile that is missing or unreadable is a hard error for
 `claims`, never a silent skip: an incomplete claim set is precisely what makes
 another project's shipped art look orphaned. `workspace add` still lets you
-register a brand-new project before its first `gen` — it warns rather than
-refusing, since the project genuinely has no lock yet — but `claims` and
+register a brand-new project before its first `gen`. It warns rather than
+refusing because the project has no lock yet, but `claims` and
 `salvage --workspace` both refuse until every registered project has one.
 
 Salvage accepts the catalog directly instead of a repeated `--claims` list:
@@ -120,12 +121,12 @@ pixelkiln salvage --workspace pixelkiln.workspace.json --dry-run
 pixelkiln salvage --workspace pixelkiln.workspace.json
 ```
 
-`--claims` still works and unions with a workspace's claim set — useful for a
+`--claims` still works and unions with a workspace's claim set. This helps a
 one-off lockfile that isn't part of the catalog. Choose one workflow per
 account: `--claims` for an occasional cross-project check, `workspace` once
 sibling projects are a standing arrangement worth registering once.
 
-The catalog stores paths and project identity, never a credential — each
+The catalog stores paths and project identity, never a credential. Each
 project still loads its own provider key from its own `.env`. `workspace
 remove` only edits the catalog file; it never touches art, a lock, or the
 provider account.

package/docs/RETRO_DIFFUSION.md

@@ -0,0 +1,110 @@
+# Set up Retro Diffusion
+
+Retro Diffusion support is experimental. Authenticated RD Fast and RD Plus
+single-candidate stills have passed from the provider's cost quote through
+validated download, provenance, and recovery. Multi-candidate, tileset, GIF,
+and PNG spritesheet paths have integration tests but still need representative
+paid live runs.
+
+[Visit Retro Diffusion](https://www.retrodiffusion.ai/) or open the
+[official API guide](https://www.retrodiffusion.ai/app/guide/api).
+
+## Add the credential
+
+Create `.env.local` beside `pixelkiln.manifest.json`:
+
+```dotenv
+RD_API_KEY=...
+```
+
+Keep this file out of Git. PixelKiln also reads the variable from the current
+process environment.
+
+## Select Retro Diffusion
+
+Set the top-level provider and keep service-specific choices under the provider
+namespace:
+
+```jsonc
+{
+  "name": "my-game",
+  "provider": "retrodiffusion",
+  "styles": {
+    "props": {
+      "generator": "map",
+      "outDir": "assets/generated/props",
+      "providerOptions": {
+        "retrodiffusion": {
+          "promptStyle": "rd_plus__default",
+          "numImages": 4,
+          "removeBg": true
+        }
+      }
+    }
+  },
+  "assets": {
+    "anvil": {
+      "prompt": "a compact blacksmith anvil",
+      "width": 64,
+      "height": 64
+    }
+  }
+}
+```
+
+Run the free checks before a paid request:
+
+```bash
+pixelkiln doctor --dry-run
+pixelkiln plan
+pixelkiln gen --budget 0.1
+```
+
+Copy the exact USD estimate from `plan` into `--budget`. Before PixelKiln sends
+the paid request, it asks Retro Diffusion for a free authoritative quote and
+stops if that quote exceeds the remaining budget.
+
+## Match the style to the workflow
+
+| PixelKiln generator | Retro Diffusion selector | Output |
+|---|---|---|
+| `map` or `pixflux` | A normal RD still style such as `rd_fast__default`, `rd_plus__default`, or an environment style | 1 to 16 PNG candidates |
+| `tiles` | `rd_tile__*` | One PNG tileset or tile asset |
+| `animation` | `rd_animation__*` or `rd_advanced_animation__*` | Animated GIF or PNG spritesheet |
+
+The provider's style catalog can change. Use its live catalog when choosing a
+selector instead of assuming an example name will remain available.
+
+Useful options under `providerOptions.retrodiffusion` include:
+
+- `numImages`: 1 to 16 still candidates
+- `removeBg`: background removal for stills
+- `framesDuration`: 4, 6, 8, 10, 12, or 16 for animation
+- `returnSpritesheet`: PNG spritesheet instead of the default GIF
+- `tileX` and `tileY`: seamless axes for supported still styles
+- `extraPrompt`: outside texture for `rd_tile__tileset_advanced`
+
+RD Pro and user still styles accept up to nine reference images. Advanced
+animation and tile modes have narrower input rules. PixelKiln validates those
+rules during planning. See the [manifest reference](./MANIFEST.md#experimental-retro-diffusion)
+for complete examples.
+
+## Current operational limits
+
+The adapter can report `balance`, but it does not yet expose Retro Diffusion
+account listing, adoption, salvage, tagging, or deletion. Paid output still has
+PixelKiln lockfile provenance and local cache recovery.
+
+The shared PixelKiln manifest currently allows arbitrary width and height from
+16 to 400 pixels, while Retro Diffusion styles can impose smaller limits. In
+the current service catalog, the useful environment and scene-object styles
+top out at 384px. Build very large scenes from separate terrain, background,
+building, landmark, and foreground layers.
+
+The [environment benchmark](./PROVIDER_BENCHMARK.md) found clean transparent,
+low-color Retro Diffusion cutouts, while PixelLab followed the more complex
+building prompts more closely. Read [PixelLab vs. Retro Diffusion](../PROVIDERS.md)
+before committing to a large batch.
+
+Retro Diffusion publishes its API examples and pricing formulas in the
+[official API repository](https://github.com/Retro-Diffusion/api-examples).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,
@@ -78,6 +78,8 @@
     "sprites",
     "game-assets",
     "pixellab",
+    "retro-diffusion",
+    "image-generation",
     "asset-pipeline",
     "generative",
     "lockfile",

package/schema/manifest.schema.json

@@ -10,6 +10,11 @@
         "name": {
           "type": "string"
         },
+        "provider": {
+          "type": "string",
+          "minLength": 1,
+          "default": "pixellab"
+        },
         "styles": {
           "type": "object",
           "additionalProperties": {
@@ -21,7 +26,8 @@
                   "1dir",
                   "map",
                   "pixflux",
-                  "tiles"
+                  "tiles",
+                  "animation"
                 ],
                 "default": "map"
               },
@@ -155,6 +161,14 @@
                   "type": "string"
                 },
                 "default": []
+              },
+              "providerOptions": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "object",
+                  "additionalProperties": {}
+                },
+                "default": {}
               }
             },
             "required": [

package/skills/pixelkiln/SKILL.md

@@ -11,9 +11,10 @@ submission, reviewed by a human, and recorded with exact provenance.
 ## Working rules
 
 - Locate `pixelkiln.manifest.json` first. Paths are manifest-relative.
-- Never inspect, print, or commit provider credentials. PixelKiln can load
-  `PIXELLAB_API_KEY` from `.env.local` beside the manifest or from the current
-  working directory.
+- Never inspect, print, or commit provider credentials. Read the manifest's
+  top-level `provider`: PixelKiln loads `PIXELLAB_API_KEY` for `pixellab` and
+  `RD_API_KEY` for experimental `retrodiffusion` from `.env.local` beside the
+  manifest or from the current working directory.
 - Run `pixelkiln doctor --dry-run` and `pixelkiln plan` before paid work. Report
   actionable, recoverable, and estimated cost figures with their provider unit.
 - Do not regenerate recoverable work. Use `pixelkiln restore` first.
@@ -42,10 +43,16 @@ debugging one phase. Use `restore` for missing bytes, `adopt` for exact matches
 already in the provider account, and `salvage` for reviewed unclaimed objects.
 Use `pack`, `mount`, or `export` only for the artifact format the project needs.
 
-PixelKiln's orchestration is provider-neutral. PixelLab is currently its only
-production and live-tested adapter; `FakeProvider` is the deterministic test
-adapter. Do not imply that other production providers already work.
+PixelKiln's orchestration is provider-neutral. PixelLab is its production and
+paid-generation-tested adapter. Retro Diffusion stills, tileset sheets,
+animated GIFs, and PNG spritesheets are experimental. Authenticated RD Fast and
+RD Plus single-candidate stills have passed from quote through validated output
+and recovery. Advanced workflows remain mock-tested.
+`FakeProvider` is the deterministic test adapter. Do not describe Retro
+Diffusion as production-ready until representative multi-candidate, tileset,
+GIF, and spritesheet live smoke tests pass.
 
 When working in the PixelKiln repository, consult `docs/GETTING_STARTED.md` for
-the full workflow, `docs/CLI.md` for flags, `docs/MANIFEST.md` for the schema,
-and `docs/RECOVERY.md` before account adoption, salvage, discard, or purge.
+the full workflow, `docs/PIXELLAB.md` or `docs/RETRO_DIFFUSION.md` for provider
+setup, `docs/CLI.md` for flags, `docs/MANIFEST.md` for the schema, and
+`docs/RECOVERY.md` before account adoption, salvage, discard, or purge.