pixelkiln 0.3.0 → 0.4.0

package/CONTRIBUTING.md

@@ -46,7 +46,8 @@ npm run pixelkiln -- plan --manifest examples/minimal/pixelkiln.manifest.json
 ```
 
 Tests must not require a live provider account or API key. Use `FakeProvider`
-for pipeline behavior and mocked HTTP responses for PixelLab wire contracts.
+for pipeline behavior and mocked HTTP responses for PixelLab or Retro Diffusion
+wire contracts.
 
 ## Change guidelines
 

package/PROVIDERS.md

@@ -1,96 +1,134 @@
-# Multi-provider status and notes
+# PixelLab and Retro Diffusion
 
-**The seam is built.** `src/provider.ts` defines the interface;
-`src/providers/pixellab.ts` is the reference implementation and
-`src/providers/fake.ts` is the in-memory test double. Nothing above the
-interface knows about PixelLab.
+PixelKiln can route one manifest through either PixelLab or Retro Diffusion.
+The project model keeps planning, hard budgets, lockfile provenance, human
+review, recovery, and packaging. Each adapter owns its service's
+authentication, pricing, validation, request lifecycle, and output formats.
 
-That is an architectural guarantee, not a compatibility claim: PixelLab is the
-only production adapter and the only backend exercised against a live account
-today. `FakeProvider` verifies the contract without network access. Until a
-second production adapter ships, describe PixelKiln as **provider-neutral by
-design and proven with PixelLab**, not as already multi-provider.
+PixelLab remains the default so existing manifests and spec hashes remain
+compatible. Select Retro Diffusion with the manifest's top-level `provider`
+field and keep its settings under `providerOptions.retrodiffusion`.
 
-Both concerns this file previously flagged as blockers are resolved:
+Ready to configure a project? Use [Set up PixelLab](./docs/PIXELLAB.md) for the
+production provider or
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md) for the experimental
+adapter. This page focuses on choosing between them.
 
-- **Cost is no longer assumed to be "generations."** `CostEstimate` carries a
-  `unit` of `generations | usd | free`, `plan` prints it, and `--budget` is
-  interpreted in it. `resolveSpecs(..., { provider })` asks the adapter for its
-  offline estimate, submission validates it again, and lock/status accounting
-  keeps fractional values separated by unit.
-- **Free multi-candidate returns are no longer assumed universal.**
-  `estimate().candidates` is a provider property; `candidateCount()` moved
-  behind the interface.
+## Support status
 
-What remains is writing a second adapter. This file records which one and why.
-
-## Midjourney is the wrong first target
-
-Verified 2026-07-29: **Midjourney has no public developer API.** API keys are
-restricted to the Enterprise dashboard and require applying for access. Every
-third-party "Midjourney API" works by automating the Discord or web interface,
-which violates Midjourney's terms of service and risks the underlying account
-being banned.
-
-Building that adapter would mean shipping something fragile, unsupported, and
-capable of getting a user's account terminated. Not worth it.
-
-## The right first target: Retro Diffusion
-
-[Retro Diffusion](https://retrodiffusion.ai/) is PixelLab's closest competitor
-and the natural second provider:
-
-- A real, documented developer API, with
-  [published examples](https://github.com/Retro-Diffusion/api-examples).
-- Purpose-built for pixel art, with grid-aligned output and no blur or
-  anti-aliasing, so it shares this tool's domain model rather than needing a
-  downscale and quantize pass bolted on.
-- Supports seamless tiles, sprite-sheet animation, and free cost estimates,
-  which map onto `plan` almost directly.
-
-Other candidates, in rough order of fit:
-
-| Provider | API | Pixel-native | Notes |
+| Provider | PixelKiln status | Credential | Cost unit |
 |---|---|---|---|
-| Retro Diffusion | yes | yes | Recommended first adapter |
-| [Scenario](https://www.scenario.com/) | yes | partly | Game-asset focused, hosts Retro Diffusion models |
-| OpenAI `gpt-image-1` | yes | no | Raster; needs downscale + palette quantization |
-| Google Gemini image | yes | no | Same caveat |
-| Local ComfyUI + pixel LoRA | n/a | yes | No per-call cost, but a GPU dependency |
-| Midjourney | **no** | no | See above |
-
-## Resolved: the two economic assumptions
-
-Both were global assumptions baked into `plan`; both are now provider-owned.
-Kept here as the rationale, since a second adapter has to honour them.
-
-1. **Cost is not universally "generations".** `Plan.cost` used to be a bare
-   number meaning PixelLab subscription generations. It now carries a unit: USD
-   for OpenAI, generations for PixelLab, free for local. `plan` prints an honest
-   figure and `--budget` means something in every backend.
-
-2. **Free candidates were a PixelLab quirk.** The core loop is to generate
-   small, get 16 candidates for one fixed price, and pick the best. It works
-   because PixelLab charges per *call* and scales candidates inversely with canvas
-   size. OpenAI charges per *image*, so 16 candidates costs 16×. The picker
-   still works either way, but the strategy advice in the README does not
-   generalise, which is why `candidateCount()` moved behind the interface.
-
-See `src/provider.ts` for the shipped interface. Lock entries carry a
-`provider` field plus `costUnit`, defaulted to `pixellab` and `generations` so
-pre-provider/pre-unit v2 lockfiles stay readable. The CLI reports both the
-successful-submission estimate and the provider balance delta observed across
-the run; those are deliberately separate because provider balances may settle
-asynchronously.
-
-## Done: the integration tests it unblocked
-
-`FakeProvider` turned out to be exactly the better test double predicted here.
-17 integration tests now cover `submit → poll → fetch`, `pushTags` and `adopt`.
-Those are the stages that spend money and previously had zero coverage, where
-four of the five real bugs in this project lived. Verified non-vacuous by mutation:
-breaking the output hashes, the budget check, or the v1 lock rejection each
-fails tests.
-
-The contact-sheet request paths are covered through the picker and salvage
-integration tests as well as their HTML unit tests.
+| PixelLab | Production; paid generation and account workflows live-tested | `PIXELLAB_API_KEY` | generations |
+| Retro Diffusion | Experimental; authenticated paid still generation, download, provenance, and recovery live-tested; advanced workflows pending | `RD_API_KEY` | USD |
+| FakeProvider | Test-only deterministic lifecycle | none | free |
+
+Live tests now cover single-candidate RD Fast and RD Plus stills from cost quote
+through submit, poll, PNG download, lockfile provenance, and cache validation.
+The RD Plus run covered isometric-asset, top-down-asset, and environment styles.
+Retro Diffusion's multi-candidate review, tileset, GIF, and spritesheet paths
+have mocked integration coverage but still need representative paid live runs.
+
+## PixelLab vs. Retro Diffusion
+
+This comparison describes the adapters PixelKiln ships today, not every feature
+the providers offer directly.
+
+| Decision | PixelLab | Retro Diffusion |
+|---|---|---|
+| Best fit today | Established PixelKiln projects, account reconciliation, and fully live-tested generation | Native pixel-art styles, cash-denominated cost control, animation, and alternate tileset workflows |
+| PixelKiln generators | `map`, `pixflux`, `1dir`, `tiles` | `map` and `pixflux` stills, `tiles`, `animation` |
+| Output | PNG stills, candidates, and structural tile members | PNG stills/tiles/spritesheets or animated GIF |
+| Candidate review | Yes; count varies by generator and size | Yes for 1–16 still candidates; animations and tilesets currently use one result |
+| References | `1dir` and tile style modes | Up to nine for supported RD Pro/user still styles; constrained inputs for animation and tiles |
+| Cost model | Subscription generations | Prepaid USD balance |
+| Cost safety | Offline estimate plus hard generation budget | Offline estimate, hard USD budget, then a free authoritative quote before submission |
+| Account lifecycle | Balance, list, adopt, salvage, tag, and confirmed purge | Balance only in the current adapter |
+| Live confidence | Full paid generation workflows exercised | RD Fast and RD Plus single-candidate stills exercised end to end; multi-candidate, tileset, GIF, and spritesheet runs pending |
+
+Choose PixelLab when mature account-object recovery and reconciliation matter,
+or when the measured one-generation `map`/`pixflux` routes fit the work. Choose
+Retro Diffusion when a native animation or spritesheet is required, an RD style
+is the desired look, or a USD quote is easier to budget. For a production batch,
+run one representative asset through the selected provider before expanding the
+scope.
+
+## Large environments, mountains, and buildings
+
+Start by deciding whether the result is an isolated map object or a complete
+background. That distinction matters more than raw canvas size.
+
+| Asset type | PixelLab through PixelKiln | Retro Diffusion through PixelKiln |
+|---|---|---|
+| Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is specifically intended for 64–384px objects placed on tile maps. |
+| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene. Current PixelKiln routes top out at 400×400. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. |
+| Style consistency across a set | `1dir` accepts a style reference and returns size-dependent candidates, but it is more expensive and capped at the square-object range. | RD Pro accepts up to nine references and has stronger prompt following, but its common styles top out at 256×256 and cost $0.18 per image. Environment-specific RD Plus styles trade references for a larger 384px canvas. |
+| Very large final scene | Generate reusable objects, terrain, and background layers separately; assemble them deterministically and integer-upscale the result. | Use the same layered approach. The API has a 512px overall ceiling, but the useful environment and scene-object styles currently cap at 384px. |
+
+For production environments, prefer a kit over a monolith: seamless terrain,
+separate landmarks/buildings, foreground occluders, and a distant backdrop.
+This produces reusable assets, cleaner parallax, easier collision/lighting, and
+cheaper targeted re-rolls. Generate at the intended native pixel resolution,
+then scale by an integer with nearest-neighbor filtering.
+
+A visual benchmark should use the same briefs for an isolated building, a
+top-down landmark, and a full scenic background. Use the same intended native
+size and review count. Score silhouette readability, perspective, palette,
+edge cleanliness, tiling/layerability, prompt adherence, and usable results per
+provider unit. Seeds are provider-specific, so equal seed numbers do not make
+the outputs directly reproducible across services.
+
+See the [environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) for the
+twelve generated images, prompts, manifests, measured costs, and review.
+
+## Cost comparison
+
+The services use different billing units, so PixelKiln never adds their costs
+together.
+
+PixelLab figures below are measurements from the endpoints PixelKiln currently
+uses; they are not a conversion to dollars:
+
+| PixelLab route | Measured cost |
+|---|---:|
+| `map` | 1 generation |
+| `pixflux` | 1 generation |
+| `1dir` | 20–40 generations |
+| `tiles` | 20–40 generations |
+
+Retro Diffusion publishes USD formulas and fixed prices. Examples relevant to
+PixelKiln include RD Fast from about $0.015 per image, RD Plus from about $0.025,
+RD Pro at $0.18, animations from $0.07–$0.25, and tilesets at $0.10. Pixel count,
+style, and candidate count affect the exact still-image quote. Treat
+`pixelkiln plan` as the offline ceiling and the provider's free preflight quote
+as the authoritative submit-time check. See Retro Diffusion's
+[official API examples and pricing formulas](https://github.com/Retro-Diffusion/api-examples#pricing).
+
+## Capability boundary
+
+The provider boundary owns behavior that differs between services:
+
+- supported generators and provider-specific validation;
+- offline estimates, arbitrary non-empty cost units, and candidate counts;
+- submit/poll response schemas and candidate selection when applicable;
+- downloads and optional account capabilities such as balance, listing,
+  tagging, and deletion.
+
+Planning groups costs by unit instead of adding incompatible values. A budget
+is interpreted in the active provider's unit. Providers without a balance or
+account-management endpoint can still generate safely because the offline
+estimate and hard budget remain enforced.
+
+## Next validation and expansion
+
+1. Complete representative paid Retro Diffusion multi-candidate, tileset, GIF,
+   and spritesheet smoke tests without logging credentials. Single-candidate RD
+   Fast and RD Plus still paths have passed end to end.
+2. Promote only the workflows proven against the live service; keep unsupported
+   account operations explicit capability errors.
+3. Evaluate Scenario as another hosted game-asset provider.
+4. Add a local ComfyUI adapter for GPU-backed, no-per-call-cost generation.
+5. Consider general raster providers only with explicit nearest-neighbor,
+   palette, transparency, and reproducibility checks.
+
+Midjourney is not an adapter target without an official public API. Automating
+its consumer UI would be fragile and could violate provider terms.

package/README.md

@@ -15,10 +15,15 @@ local contact sheet, and commit exact provenance beside the files. No LLM is in
 the orchestration loop; provider calls, polling, hashing, downloads, and filing
 are deterministic software mechanics.
 
-The orchestration layer is provider-neutral by design. PixelLab is currently
-the only production adapter and the only live-tested generation backend;
-`FakeProvider` exercises the same contract deterministically in tests. A second
-production adapter is roadmap work, not current compatibility.
+The orchestration layer is provider-neutral. PixelLab is the production,
+live-tested backend. An experimental Retro Diffusion adapter supports native
+pixel-art stills, candidate batches, tileset sheets, animated GIFs, and PNG
+spritesheets. Authenticated RD Fast and RD Plus single-candidate still paths
+have passed from quote through validated output and recovery. Multi-candidate,
+tileset, GIF, and spritesheet live runs remain. See
+[PixelLab vs. Retro Diffusion](./PROVIDERS.md) for the trade-offs, including
+large environment and building workflows.
+`FakeProvider` exercises the same contract deterministically in tests.
 
 > **Release status:** the package is pre-1.0 and the first npm publication is
 > tracked in [issue #1](https://github.com/gfargo/pixelkiln/issues/1). Until it
@@ -99,7 +104,11 @@ cd ../my-game
 Put the provider credential in `.env.local` beside the manifest:
 
 ```dotenv
+# PixelLab (the default provider)
 PIXELLAB_API_KEY=...
+
+# Or Retro Diffusion when `provider` is `retrodiffusion`
+RD_API_KEY=...
 ```
 
 Validate locally, inspect exact work/cost, then generate with a hard ceiling:
@@ -127,6 +136,9 @@ pixelkiln plan
 ```
 
 See [Getting started](./docs/GETTING_STARTED.md) for new and existing projects.
+Use [Set up PixelLab](./docs/PIXELLAB.md) or
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md) for provider-specific
+credentials, manifest examples, and current limits.
 
 ## Agent skill
 
@@ -149,6 +161,7 @@ packaging layer.
 {
   "$schema": "./node_modules/pixelkiln/schema/manifest.schema.json",
   "name": "my-game",
+  "provider": "pixellab",
   "styles": {
     "base": {
       "generator": "map",
@@ -168,7 +181,12 @@ packaging layer.
 Styles are namespaces. Adding a second style re-derives the same asset ids into
 a separate output directory and separate lock keys without clobbering the first
 set. Generator choice, reference-image bytes, dimensions, palette, seed, and
-prompt settings participate in deterministic spec identity.
+prompt settings participate in deterministic spec identity. A manifest may
+select `retrodiffusion` instead and pass namespaced `providerOptions`; see
+[Set up PixelLab](./docs/PIXELLAB.md),
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), and
+[PixelLab vs. Retro Diffusion](./PROVIDERS.md) for configuration, costs,
+current confidence, and limitations.
 
 The schema rejects unknown fields and invalid generator combinations before
 planning. See the [Manifest reference](./docs/MANIFEST.md).
@@ -212,6 +230,11 @@ replace a hard palette or reference-image constraint. See
 [Generator selection](./docs/GENERATORS.md) and the
 [measured endpoint reference](./docs/ENDPOINTS.md).
 
+Generator names describe PixelKiln workflows; their exact capabilities and
+prices depend on the selected provider. Retro Diffusion also supports the
+provider-specific `animation` generator. Compare the adapters in
+[PixelLab vs. Retro Diffusion](./PROVIDERS.md).
+
 ## Derived artifacts
 
 ```bash
@@ -264,8 +287,9 @@ pixelkiln salvage --workspace pixelkiln.workspace.json
 ```
 
 A registered project's missing or unreadable lockfile is a hard error for
-`workspace claims` and `salvage --workspace` — never a silent skip. Purge only
-targets objects already tagged discard and requires an explicit confirmation.
+`workspace claims` and `salvage --workspace`. Missing claims are never skipped.
+Purge only targets objects already tagged discard and requires an explicit
+confirmation.
 See [Recovery and account safety](./docs/RECOVERY.md).
 
 ## Automation
@@ -312,10 +336,13 @@ writes, and offline provenance verification. See [Library API](./docs/LIBRARY.md
 |---|---|
 | [Documentation index](./docs/README.md) | All user, workflow, reference, and architecture guides. |
 | [Getting started](./docs/GETTING_STARTED.md) | First project, existing-art onboarding, everyday workflow, and what to commit. |
+| [Set up PixelLab](./docs/PIXELLAB.md) | Production-provider credentials, manifest, generators, and account workflows. |
+| [Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md) | Experimental-provider credentials, styles, formats, cost checks, and limits. |
 | [CLI reference](./docs/CLI.md) | Every command, flag, JSON mode, and exit contract. |
 | [Manifest reference](./docs/MANIFEST.md) | Every style/asset field and generator constraint. |
-| [Agent workflows](./docs/AGENTS.md) | Official skill install, operating model, and PixelLab MCP pairing. |
+| [Agent workflows](./docs/AGENTS.md) | Official skill install, operating model, and provider-aware safety. |
 | [Generators](./docs/GENERATORS.md) | Capability choice, measured costs, palettes, style references, and tiles. |
+| [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Twelve matched outputs comparing buildings, landmarks, backgrounds, cost, and file readiness. |
 | [Derived artifacts](./docs/ARTIFACTS.md) | Pack, mount, export, provenance, ownership, transactions, and recovery. |
 | [Recovery](./docs/RECOVERY.md) | Restore, caches, adopt, salvage, claims, and purge safety. |
 | [Quality gates](./docs/QUALITY.md) | Plan, doctor, audit, cache, JSON, and CI. |
@@ -323,6 +350,7 @@ writes, and offline provenance verification. See [Library API](./docs/LIBRARY.md
 | [Library API](./docs/LIBRARY.md) | Public TypeScript contracts and examples. |
 | [Tiles](./docs/TILES.md) | Structural outputs and generic/Tiled/Godot formats. |
 | [Endpoint research](./docs/ENDPOINTS.md) | Measured PixelLab API behavior and recipes. |
+| [PixelLab vs. Retro Diffusion](./PROVIDERS.md) | Provider selection, costs, supported workflows, confidence, and limitations. |
 
 The [public documentation site](https://pixelkiln.griffen.codes/docs) is built by
 the application in [`website/`](./website/README.md). It reads these Markdown
@@ -330,7 +358,7 @@ files directly at build time, so the website and published package share one
 documentation source.
 
 Project policies: [Contributing](./CONTRIBUTING.md),
-[Security](./SECURITY.md), and [provider notes](./PROVIDERS.md).
+[Security](./SECURITY.md), and [provider comparison](./PROVIDERS.md).
 
 ## Scope
 

package/SECURITY.md

@@ -28,11 +28,12 @@ reporter.
 
 ## Sensitive areas
 
-Pixelkiln handles provider credentials, paid API actions, remote object deletion,
+PixelKiln handles provider credentials, paid API actions, remote object deletion,
 local output paths, a localhost review server, and generated HTML containing
 provider data. Reports involving authentication leakage, path traversal,
 cross-origin review actions, HTML/script injection, unsafe overwrite/delete
 behavior, lockfile corruption, or budget bypass are security relevant.
 
-Never attach a real `PIXELLAB_API_KEY`, `.env` file, private provider URL, or
-unredacted lockfile from a confidential project to a public report.
+Never attach a real `PIXELLAB_API_KEY`, `RD_API_KEY`, `.env` file, private
+provider URL, or unredacted lockfile from a confidential project to a public
+report.