pixelkiln 0.5.0 → 0.6.0

package/PROVIDERS.md

@@ -78,7 +78,9 @@ 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.
+twenty generated images, prompts, manifests, measured costs, and review. The
+384×384 additions test a larger cliffside building and a full volcanic
+background.
 
 ## Use both providers in one project
 
@@ -167,19 +169,57 @@ 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,
+## What to build next
+
+The highest-value next feature is native per-style provider routing, not a third
+adapter. The benchmark now shows a useful split: PixelLab follows dense
+building briefs more reliably, while Retro Diffusion returns cleaner cutouts
+and strong close environment framing. Two manifests make that combination
+possible, but awkward. One manifest should be able to send a building style to
+PixelLab and a background or animation style to Retro Diffusion.
+
+This needs provider-keyed budgets and confirmations, not a provider field added
+in isolation. A safe plan must keep `4 generations` and `$0.40` separate,
+construct and rate-limit each adapter independently, and require an explicit
+provider for account-wide commands. The lockfile already records the provider
+on each entry, so its identity model is ready for the change.
+
+After that, Scenario is the best next hosted provider candidate.
+
+| Candidate | What it adds | Fit with PixelKiln | Main cost or risk | Priority |
+|---|---|---|---|---:|
+| Scenario | Custom-trained style models, references, image editing, background removal, upscaling, and managed assets | Async jobs, asset IDs, and free `dryRun` cost estimates map closely to PixelKiln's plan/submit/poll/download lifecycle | API access requires a paid plan; auth uses both an API key and secret, so the provider factory must describe more than one credential | 1 |
+| ComfyUI local/cloud | Reproducible workflow graphs, broad model choice, local GPU execution, and a cloud path using a compatible API | Workflow JSON could become a durable provenance input; jobs and output downloads already resemble the current provider boundary | Local cost has no universal provider unit; the cloud API is marked experimental and requires a subscription | 2 |
+| fal | A large hosted model catalog, including pixel-art style controls, LoRAs, editing, upscaling, and background removal | Queue-based requests and model schemas are accessible through one client | Model-specific schemas and prices move the adapter toward a marketplace abstraction rather than one stable art workflow | 3 |
+
+Scenario deserves the first spike because its [custom generation API](https://docs.scenario.com/get-started/generation/third-party-model-generation)
+returns an asynchronous job ID, its [generation surface](https://docs.scenario.com/get-started/documentation/key-capabilities-at-a-glance)
+supports custom models and image references, and its
+[Compute Unit guidance](https://help.scenario.com/articles/7934059476-api-usage-and-credits-compute-units)
+documents free cost preflights. That combination adds something the current
+providers do not: a project-specific visual model with a cost check that can be
+captured before submission.
+
+ComfyUI should follow. Its [local server API](https://docs.comfy.org/development/overview)
+would cover private or offline GPU workflows, while the
+[cloud API](https://docs.comfy.org/development/cloud/overview) accepts the same
+workflow-shaped requests and exposes asynchronous jobs. The adapter needs an
+explicit budget policy before implementation. A local run could report planned
+image count and measured execution time, but it must not pretend those values
+are a portable dollar estimate.
+
+Recommended order:
+
+1. Add per-style provider selection, provider-keyed budgets, and mixed-provider
+   integration tests.
+2. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
+   smoke tests.
+3. Build a narrow Scenario still-image spike with dry-run cost, submit, poll,
+   download, and one custom-model or reference-image benchmark.
+4. Define local and cloud budget semantics for ComfyUI, then prototype one
+   versioned workflow.
+5. Consider general raster marketplaces only with explicit nearest-neighbor,
    palette, transparency, and reproducibility checks.
-6. Evaluate per-style provider selection with provider-keyed budgets; do not
-   overload the current scalar `--budget` or silently sum incompatible units.
 
 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

@@ -336,7 +336,7 @@ writes, and offline provenance verification. See [Library API](./docs/LIBRARY.md
 | [Manifest reference](./docs/MANIFEST.md) | Every style/asset field and generator constraint. |
 | [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. |
+| [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Twenty matched outputs comparing buildings, landmarks, large 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. |

package/docs/PROVIDER_BENCHMARK.md

@@ -1,8 +1,10 @@
 # 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.
+This benchmark compares PixelLab and Retro Diffusion on five game-art briefs.
+Three briefs use 256×256 output; two use 384×384 to test larger buildings and
+environment backgrounds. 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.
@@ -14,10 +16,12 @@ model or endpoint sold by either provider.
 | 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 |
+| Cliffside fortress | `map`, high top-down view | `rd_plus__isometric_asset` | Large isolated building complex |
+| Volcanic pass | `pixflux`, background kept | `rd_plus__environment` | Full scenic background with reusable depth planes |
 
-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.
+Both manifests use 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
@@ -93,15 +97,67 @@ 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.
 
+## Cliffside fortress at 384×384
+
+Prompt: `a large fortified monastery built into a sheer mountain cliff,
+isometric three-quarter view, central stone keep, two side towers, terraced
+stairs, copper roofs, isolated with no scenery`
+
+| PixelLab A | PixelLab B | Retro Diffusion A | Retro Diffusion B |
+|---|---|---|---|
+| ![PixelLab cliffside fortress attempt A](../website/public/benchmarks/provider-environments/pixellab/isolated/a/cliffside-fortress.png) | ![PixelLab cliffside fortress attempt B](../website/public/benchmarks/provider-environments/pixellab/isolated/b/cliffside-fortress.png) | ![Retro Diffusion cliffside fortress attempt A](../website/public/benchmarks/provider-environments/retrodiffusion/isolated/a/cliffside-fortress.png) | ![Retro Diffusion cliffside fortress attempt B](../website/public/benchmarks/provider-environments/retrodiffusion/isolated/b/cliffside-fortress.png) |
+
+The larger canvas helped both providers. PixelLab used most of the frame and
+kept the cliff, stairs, central keep, and tower structure legible. Attempt B is
+the clearest match for a fortified monastery. Both outputs still include an
+opaque gray field, and their 246 and 249 colors would need deliberate cleanup
+for a tightly controlled palette.
+
+Retro Diffusion improved markedly over its 256×256 observatory attempts. Both
+results read as substantial cliffside compounds, and attempt B makes good use
+of the full canvas. They are ready-to-place transparent cutouts with 75% and
+52% transparent pixels and only 55 and 49 colors. PixelLab is more reliable on
+the exact architectural brief. Retro Diffusion is closer to a finished modular
+map asset.
+
+## Volcanic pass at 384×384
+
+Prompt: `a wide volcanic mountain pass at dawn, layered black peaks, glowing
+lava river, basalt fortress in the middle distance, smoke plumes, full-bleed
+parallax background with open sky`
+
+| PixelLab A | PixelLab B | Retro Diffusion A | Retro Diffusion B |
+|---|---|---|---|
+| ![PixelLab volcanic pass attempt A](../website/public/benchmarks/provider-environments/pixellab/background/a/volcanic-pass.png) | ![PixelLab volcanic pass attempt B](../website/public/benchmarks/provider-environments/pixellab/background/b/volcanic-pass.png) | ![Retro Diffusion volcanic pass attempt A](../website/public/benchmarks/provider-environments/retrodiffusion/background/a/volcanic-pass.png) | ![Retro Diffusion volcanic pass attempt B](../website/public/benchmarks/provider-environments/retrodiffusion/background/b/volcanic-pass.png) |
+
+PixelLab produced broader compositions with open sky and visibly separated
+mountain planes. Attempt A includes the smoke plume and a clear volcano; attempt
+B simplifies the scene into a graphic basin. Neither attempt includes a
+recognizable fortress. Attempt A also contains a generated signature-like mark
+in the lower-right corner, so it is not usable without cleanup. The files use
+44 and 26 colors.
+
+Retro Diffusion made the pass and lava river unmistakable in both attempts. Its
+narrow canyon framing is strong for a scene the player enters, but it leaves
+less open sky and fewer obvious planes for a distant backdrop. It also dropped
+the fortress and most of the smoke detail. The files use 26 and 25 colors.
+
+None of these four files is a finished parallax package. They are flattened,
+opaque scenes. PixelLab gives an artist clearer depth bands to cut apart; Retro
+Diffusion gives the stronger single-frame canyon. A production workflow should
+generate or extract the sky, distant peaks, middle ground, and foreground as
+separate assets.
+
 ## 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 | 10 | 10 generations | 4,411 generations |
+| Retro Diffusion | 10 | $0.744 | $9.73 |
 
 PixelLab charged one generation per image. Retro Diffusion quoted and charged
-$0.058 per RD Plus image.
+$0.058 for each 256px RD Plus image and $0.099 for each 384px RD Plus image;
+PixelKiln's hard ceiling rounds the latter to $0.10 per image.
 
 The run also caught two integration details:
 
@@ -111,15 +167,16 @@ The run also caught two integration details:
   $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
+Both manifests now pass `doctor`, report a current plan, and have ten 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.
+Diffusion when a transparent, low-color asset matters more than capturing every
+noun in a complex prompt. At 384×384, Retro Diffusion can fill the frame with a
+substantial structure rather than the compact cutouts seen in the first brief.
 
 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
@@ -130,5 +187,7 @@ 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.
+but they do not measure every style, prompt family, or model update. The new
+volcanic brief also shows why prompt coverage needs review at the object level:
+all four images lost the requested fortress. Rerun the committed manifests when
+either provider changes its models.

package/package.json

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

package/skills/pixelkiln/references/pixellab.md

@@ -24,9 +24,11 @@ providers, or before any PixelLab account operation.
 | `tiles` | Ground variations or connected structures | 20–40 generations |
 
 In the committed environment benchmark, PixelLab followed complex building
-prompts more closely and produced the stronger scenic background. Its 256px map
-objects were opaque despite the route's transparency claim, so inspect alpha on
-one representative result before a batch.
+prompts more closely and produced broader, more separable depth bands in scenic
+backgrounds. Its 256px and 384px map objects were opaque despite the route's
+transparency claim, so inspect alpha on one representative result before a
+batch. Inspect scenic outputs for stray marks too: one untouched 384px attempt
+contained a generated signature-like glyph.
 
 For setup and current field constraints, use
 <https://pixelkiln.griffen.codes/docs/pixellab>. When working in the PixelKiln

package/skills/pixelkiln/references/retro-diffusion.md

@@ -31,6 +31,13 @@ cutouts, smaller palettes, cinematic framing, or native animation. Build truly
 large scenes from separately generated terrain, backdrop, landmark, building,
 and foreground layers, then integer-upscale with nearest-neighbor filtering.
 
+The committed 384px benchmark produced substantially larger isometric
+buildings than the earlier 256px brief while retaining 52% to 75%
+transparency and 49 to 55 colors. Its volcanic backgrounds made the pass and
+lava path clear, but dropped a requested fortress and favored close canyon
+framing over separable distant planes. Use a representative large asset before
+assuming prompt details or layerability will survive a batch.
+
 For setup, selectors, and option constraints, use
 <https://pixelkiln.griffen.codes/docs/retro-diffusion>. The matched visual
 evidence is at <https://pixelkiln.griffen.codes/docs/provider-benchmark>. When