pixelkiln 0.2.0 → 0.4.0

package/docs/MANIFEST.md

@@ -9,6 +9,7 @@ directory. The canonical machine-readable contract is
 {
   "$schema": "./node_modules/pixelkiln/schema/manifest.schema.json",
   "name": "my-game",
+  "provider": "pixellab",
   "styles": {
     "base": {
       "generator": "map",
@@ -31,6 +32,7 @@ Unknown properties are rejected at every level.
 |---|---|---|
 | `$schema` | no | Editor schema URL/path. It does not affect generation identity. |
 | `name` | yes | Project/account tag namespace. |
+| `provider` | no | Provider registry id. Defaults to `pixellab`; `retrodiffusion` is experimental. |
 | `styles` | yes | Map of style id to inherited generation/output settings. |
 | `assets` | yes | Map of stable asset id to subject and per-asset overrides. |
 
@@ -42,19 +44,20 @@ not merely a label edit.
 
 | Field | Type/default | Meaning |
 |---|---|---|
-| `generator` | `map` | `map`, `1dir`, `pixflux`, or `tiles`. |
+| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, or provider-specific `animation`. |
 | `outDir` | string, required | Output directory relative to the manifest. |
 | `promptPrefix` | `""` | Prepended to every participating asset prompt. |
 | `promptSuffix` | `""` | Appended to every participating asset prompt. |
 | `styleImages` | `[]` | `{ "path": "..." }` reference images. Paths are manifest-relative. |
 | `size` | integer 32–256 | Square size for `1dir`; a style reference's dimensions take precedence when present. |
-| `view` | string | Provider-facing view/direction description. |
-| `outline` | string | PixelLab `map` outline setting. |
-| `shading` | string | PixelLab shading setting. |
-| `detail` | string | PixelLab detail setting. |
+| `view` | string | PixelLab `map`: `low top-down`, `high top-down`, or `side`. Other generators interpret this separately. |
+| `outline` | string | PixelLab `map`: `single color outline`, `selective outline`, or `lineless`. |
+| `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, `[]` | Forced palette for `pixflux`; `#` is optional. |
 | `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. |
 | `tileSize` | integer 16–256 | Edge length for `tiles` when no style reference supplies geometry. |
 | `tileType` | enum | `hex`, `hex_pointy`, `isometric`, `oblique`, `octagon`, or `square_topdown`. |
 | `tileView` | enum | `top-down`, `high top-down`, `low top-down`, or `side`. |
@@ -77,6 +80,101 @@ Generator-specific fields are validated before planning. Important constraints:
 
 See [generator selection](./GENERATORS.md) for costs and trade-offs.
 
+## Experimental Retro Diffusion
+
+Retro Diffusion maps `map` and `pixflux` to still generation, `tiles` to its
+tileset family, and `animation` to GIF or PNG-spritesheet generation. Durable
+sources and lock outputs record `image/png` or `image/gif`, so recovery retains
+the correct extension and validates the correct structure.
+
+```jsonc
+{
+  "name": "my-game",
+  "provider": "retrodiffusion",
+  "styles": {
+    "base": {
+      "generator": "map",
+      "outDir": "assets/generated/base",
+      "providerOptions": {
+        "retrodiffusion": {
+          "promptStyle": "rd_plus__default",
+          "numImages": 4,
+          "removeBg": true
+        }
+      }
+    }
+  },
+  "assets": {
+    "anvil": { "prompt": "a compact blacksmith anvil" }
+  }
+}
+```
+
+`promptStyle` accepts a live Retro Diffusion still-style selector,
+`numImages` accepts 1–16 candidates, and `removeBg` overrides
+`noBackground`. The Retro Diffusion API accepts 16–512px output, while the
+shared PixelKiln manifest currently limits arbitrary width and height to
+16–400px and square `size` to 32–256px. Selected styles can impose smaller
+limits. RD Pro and user styles accept up to nine reference images. Costs are
+planned in USD and checked again with Retro Diffusion's free authoritative
+quote endpoint before the paid request is sent. Authenticated single-candidate
+RD Fast and RD Plus paths have passed from quote through validated output and
+recovery.
+Multi-candidate, tileset, GIF, and spritesheet paths remain mock-tested, so the
+adapter is still experimental.
+
+Additional Retro Diffusion options are:
+
+| Option | Meaning |
+|---|---|
+| `framesDuration` | Animation duration: `4`, `6`, `8`, `10`, `12`, or `16`. |
+| `returnSpritesheet` | Return a PNG spritesheet instead of an animated GIF. |
+| `extraPrompt` | Outside texture description for `rd_tile__tileset_advanced`. |
+| `tileX` / `tileY` | Make supported still styles seamless on either axis. |
+
+An animation style is declared explicitly:
+
+```jsonc
+{
+  "generator": "animation",
+  "size": 64,
+  "outDir": "assets/generated/animations",
+  "providerOptions": {
+    "retrodiffusion": {
+      "promptStyle": "rd_animation__any_animation",
+      "numImages": 1,
+      "framesDuration": 8,
+      "returnSpritesheet": false
+    }
+  }
+}
+```
+
+The default output is `<assetId>.gif`; `returnSpritesheet: true` produces
+`<assetId>.png`. Advanced animation styles require exactly one `styleImages`
+input. PixelKiln currently limits animation batches to one so selection never
+loses the output media type.
+
+For a Wang-style tileset sheet:
+
+```jsonc
+{
+  "generator": "tiles",
+  "tileSize": 32,
+  "outDir": "assets/generated/tiles",
+  "providerOptions": {
+    "retrodiffusion": {
+      "promptStyle": "rd_tile__tileset",
+      "numImages": 1
+    }
+  }
+}
+```
+
+`rd_tile__tileset_advanced` accepts `extraPrompt` and up to two style images;
+`rd_tile__tile_variation` requires one style image. Provider-specific size and
+input constraints are checked during the free planning phase.
+
 ## Asset fields
 
 | Field | Type/default | Meaning |

package/docs/PIXELLAB.md

@@ -0,0 +1,100 @@
+# Set up PixelLab
+
+PixelLab is PixelKiln's default provider and the production choice for current
+projects. Its generation and account-management paths have been exercised
+against a live account.
+
+[Visit PixelLab](https://www.pixellab.ai/) or open the
+[official API reference](https://api.pixellab.ai/v2/docs).
+
+## Add the credential
+
+Create `.env.local` beside `pixelkiln.manifest.json`:
+
+```dotenv
+PIXELLAB_API_KEY=...
+```
+
+Keep this file out of Git. PixelKiln also reads the variable from the current
+process environment.
+
+## Select PixelLab
+
+The `provider` field is optional because `pixellab` is the default. Declaring it
+makes the choice clear:
+
+```jsonc
+{
+  "name": "my-game",
+  "provider": "pixellab",
+  "styles": {
+    "props": {
+      "generator": "map",
+      "outDir": "assets/generated/props",
+      "promptSuffix": ", isolated pixel-art game asset"
+    }
+  },
+  "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 1
+```
+
+Copy the exact estimate from `plan` into `--budget`. PixelLab budgets use
+subscription generations.
+
+## Choose a generator
+
+| Generator | Start here when | Measured cost |
+|---|---|---:|
+| `map` | You need one prop, icon, building, or landmark at arbitrary dimensions | 1 generation |
+| `pixflux` | You need a closed palette or a full-bleed background | 1 generation |
+| `1dir` | You need references or several candidates for human review | 20 to 40 generations |
+| `tiles` | You need ground variations or a connected structural set | 20 to 40 generations |
+
+`map` accepts these values:
+
+- `view`: `low top-down`, `high top-down`, or `side`
+- `outline`: `single color outline`, `selective outline`, or `lineless`
+- `shading`: `flat shading`, `basic shading`, `medium shading`, or `detailed shading`
+- `detail`: `low detail`, `medium detail`, or `high detail`
+
+PixelLab describes map objects as transparent, but the 256px map objects in our
+[environment benchmark](./PROVIDER_BENCHMARK.md) were opaque. Check the alpha
+channel before building a production batch. For a scenic background, use
+`pixflux` with `noBackground: false`.
+
+Read [Generator selection](./GENERATORS.md) for the full constraints and
+measured economics.
+
+## Account workflows
+
+The PixelLab adapter supports `balance`, `adopt`, `salvage`, `tag`, and the
+separate confirmed `purge` flow. These are useful when several projects share
+one provider account or when existing local art needs its original provenance.
+Read [Recovery and account safety](./RECOVERY.md) before changing remote
+objects.
+
+PixelLab's official
+[MCP server](https://github.com/pixellab-code/pixellab-mcp) gives agents direct
+access to PixelLab generation tools. It complements PixelKiln: the MCP handles
+creation, while PixelKiln owns project state, budgets, review, recovery, and
+packaging.
+
+## What is outside this adapter
+
+PixelLab offers more than PixelKiln currently exposes. Character generation,
+multi-direction rotation, and animation are not part of this adapter. Use the
+[manifest reference](./MANIFEST.md) for the fields PixelKiln supports today.

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
@@ -86,6 +87,50 @@ array to stdout and human diagnostics to stderr for piping into `jq`.
 Imported ids are derived from prompts and land under `_salvaged/`; review and
 rename them before treating them as stable application ids.
 
+## Shared workspace catalog
+
+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
+art look unclaimed. `workspace` fixes that by registering every sibling once,
+outside any one manifest:
+
+```bash
+pixelkiln workspace add ../other-game/pixelkiln.manifest.json
+pixelkiln workspace add ../another-game/pixelkiln.manifest.json --name another
+pixelkiln workspace status
+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. 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 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:
+
+```bash
+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. 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
+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.
+
 ## Confirmed purge
 
 Deletion is a separate command:

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/docs/TILES.md

@@ -53,7 +53,7 @@ The companion record is engine-neutral: it stores portable source paths and
 SHA-256s, export options (including raw provider rules), output hashes, and a
 canonical fingerprint. `verifyArtifactBundle()` can detect changed inputs,
 edited/missing outputs, or altered provenance offline without rebuilding the
-atlas. The project manifest and lockfile are conservative inputs, ensuring that
+atlas. The project manifest and lockfile are conservative inputs, so
 newly declared or recorded tiles also make an older export stale. The TSJ/TRES
 contracts therefore remain free of PixelKiln-only fields.
 

package/examples/minimal/README.md

@@ -22,5 +22,5 @@ Add a second entry under `styles` with a different `outDir`, then:
 pixelkiln gen --style neon
 ```
 
-Every asset re-derives under the new style. The original files are untouched —
-styles are separate namespaces in both the output tree and the lockfile.
+Every asset re-derives under the new style. The original files are untouched.
+Styles are separate namespaces in both the output tree and the lockfile.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.2.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": [