pixelkiln 0.13.0 → 0.14.0

package/PROVIDERS.md

@@ -1,8 +1,8 @@
 # Provider comparison
 
-PixelKiln can route one manifest through PixelLab, Retro Diffusion, and a
-self-hosted ComfyUI server. Planning, review, recovery, and packaging stay the
-same. Each adapter handles its service's authentication, prices, request
+PixelKiln can route one manifest through PixelLab, Retro Diffusion, Scenario,
+and a self-hosted ComfyUI server. Planning, review, recovery, and packaging stay
+the same. Each adapter handles its service's authentication, prices, request
 lifecycle, and file formats.
 
 PixelLab remains the default so existing manifests and spec hashes remain
@@ -10,8 +10,9 @@ compatible. The manifest's top-level `provider` is the default; a style may
 override it. Keep service settings under the matching `providerOptions` key.
 
 To configure a project, use [Set up PixelLab](./docs/PIXELLAB.md),
-[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), or
-[Set up ComfyUI](./docs/COMFYUI.md). This page focuses on choosing between
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md),
+[Set up ComfyUI](./docs/COMFYUI.md), or
+[Set up Scenario](./docs/SCENARIO.md). This page focuses on choosing between
 them.
 
 ## Support status
@@ -21,6 +22,7 @@ them.
 | 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 |
 | ComfyUI | Experimental; local single-image generation, four-candidate queue, provenance, and cache-only recovery live-tested on Apple MPS | none; optional `COMFYUI_BASE_URL` | free |
+| Scenario | Experimental; BFL Flux 2 Dev authentication, CU preflight, paid single/two-output generation, review, download, and durable recovery live-tested | `SCENARIO_SDK_API_KEY` and `SCENARIO_SDK_API_SECRET` | compute-units |
 | FakeProvider | Test-only deterministic lifecycle | none | free |
 
 Live tests now cover single-candidate RD Fast and RD Plus stills from cost quote
@@ -35,6 +37,13 @@ ComfyUI's `free` unit means PixelKiln cannot identify a metered provider
 charge. It does not count hardware, hosting, electricity, or model-license
 costs.
 
+Scenario planning uses the manifest's conservative `maxComputeUnits` value.
+Immediately before paid work, the adapter asks Scenario for a free live quote
+using the identical request. The first live smoke quoted and billed 16 CU for
+one image and 32 CU for two. Human selection and a forced provider restore both
+passed. The smoke is separate from the visual comparison because it uses a
+different brief.
+
 ## PixelLab vs. Retro Diffusion
 
 This comparison describes the adapters PixelKiln ships today, not every feature
@@ -81,17 +90,38 @@ the same graph and still differ because their checkpoint bytes, custom nodes,
 or sampler settings differ. Commit the workflow and record the model stack used
 to test it.
 
+## Where Scenario fits
+
+Scenario adds hosted third-party models and reusable project-specific models
+without requiring a local GPU. PixelKiln's first adapter intentionally covers
+only the part that fits its existing still-image pipeline.
+
+| Decision | Scenario through PixelKiln |
+|---|---|
+| Best fit today | A controlled one-asset spike using a hosted model or project LoRA with a hard CU ceiling |
+| PixelKiln generator | `map` stills |
+| Output | One to four PNG candidates, 128–2048px in multiples of 16 |
+| Cost model | Manifest `maxComputeUnits`, command budget, then free authoritative preflight before each paid request |
+| Recovery | Durable job and asset IDs refresh temporary signed original-file URLs |
+| Account lifecycle | Read-only connectivity check; no balance, list, adopt, salvage, tag, or purge yet |
+| Confidence | BFL Flux 2 Dev live-tested through quote, billing, single/two-output jobs, human selection, PNG download, and provider-backed restore; other model schemas remain unverified |
+
+Scenario model schemas differ. The current adapter sends prompt, width, height,
+output count, optional seed, and explicitly declared JSON parameters. Verify
+the chosen model accepts that shape before spending. Use
+[Set up Scenario](./docs/SCENARIO.md) for the safe first-run sequence.
+
 ## 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 | Retro Diffusion | ComfyUI |
-|---|---|---|---|
-| 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 intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. |
-| 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. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. |
-| 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. | LoRAs, reference adapters, ControlNet, and shared latent settings can live in the committed workflow. Reproducibility also depends on external model and custom-node versions. |
-| 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. | The graph can tile, upscale, or composite beyond hosted-provider limits, but memory and seam quality become workflow concerns. Prefer reusable layers unless the scene truly needs one render. |
+| Asset type | PixelLab | Retro Diffusion | ComfyUI | Scenario |
+|---|---|---|---|---|
+| 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 intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. | The live BFL smoke produced a readable 512px keep, but it was opaque and used 19,619 colors. Use that profile for concepts or refinement input, not a finished limited-palette asset. A project-specific model may improve consistency but needs its own smoke. |
+| 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. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | The BFL profile accepts canvases up to 2048px, but no Scenario scenic brief has passed the shared benchmark. Treat that as model-canvas capacity, not native pixel resolution. Start with one 512px concept before raising size or steps. |
+| 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. | LoRAs, reference adapters, ControlNet, and shared latent settings can live in the committed workflow. Reproducibility also depends on external model and custom-node versions. | Scenario's project models and LoRAs are the main reason to use it for a set. PixelKiln can pin the model ID and parameters, but its first live run covers only the public BFL profile. |
+| 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. | The graph can tile, upscale, or composite beyond hosted-provider limits, but memory and seam quality become workflow concerns. Prefer reusable layers unless the scene truly needs one render. | Scenario can request a larger raster from a compatible model, but the same rule applies: generate reusable layers at their useful native detail, compose at 1×, and integer-upscale only the final scene. |
 
 For a production environment, build a kit: seamless terrain, separate
 landmarks and buildings, foreground occluders, and a distant backdrop. You can
@@ -116,15 +146,16 @@ repeatable.
 ## Use multiple providers in one project
 
 Set a provider on any style that differs from the manifest default. Planning
-and confirmations remain grouped by provider and unit, so PixelLab generations
-and Retro Diffusion dollars are never added together. A mixed run takes a
-separate named ceiling for each paid provider; the free group may be explicit:
+and confirmations remain grouped by provider and unit, so PixelLab generations,
+Retro Diffusion dollars, Scenario Compute Units, and local free work are never
+added together. A mixed run takes a separate named ceiling for each paid
+provider; the free group may be explicit:
 
 ```bash
 pixelkiln plan
 pixelkiln gen \
   --budget pixellab=12 \
-  --budget retrodiffusion=0.20 \
+  --budget scenario=60 \
   --budget comfyui=0
 ```
 
@@ -169,6 +200,12 @@ style, and candidate count affect the exact still-image quote. Treat
 as the authoritative submit-time check. See Retro Diffusion's
 [official API examples and pricing formulas](https://github.com/Retro-Diffusion/api-examples#pricing).
 
+Scenario uses Compute Units rather than USD in the API contract. Costs vary by
+model and inputs, so the manifest records a conservative per-asset ceiling
+instead of a stale formula. PixelKiln records Scenario's live dry-run quote and
+final job billing separately. The first BFL Flux 2 Dev smoke measured 16 CU for
+one 512px output and 32 CU for two with 28 inference steps.
+
 ## Capability boundary
 
 The provider boundary owns behavior that differs between services:
@@ -197,30 +234,29 @@ PixelLab, an animation style to Retro Diffusion, and a private model workflow
 to ComfyUI. Provider-keyed budgets, independent orchestration, lock-authoritative
 recovery, and explicit account-provider selection ship with it.
 
-Scenario remains the best next hosted provider candidate. The implementation
-scope and acceptance criteria are tracked in
-[GitHub issue #52](https://github.com/gfargo/pixelkiln/issues/52).
+The Scenario still-image adapter from
+[GitHub issue #52](https://github.com/gfargo/pixelkiln/issues/52) now has mocked
+edge coverage and a paid BFL Flux 2 Dev lifecycle smoke. It remains
+experimental until more model schemas and representative art briefs pass.
 
 | 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 |
+| Scenario comparable benchmark | Custom-trained style models and hosted third-party generation | Tests the same environment briefs now that CU accounting, review, PNG output, and signed-URL recovery are proven | Model schemas differ, and the first live smoke is not directly comparable to the existing provider set | 1 |
 | ComfyUI Cloud | Managed execution of workflow graphs without running a local GPU | Could reuse part of the workflow model, but authentication, endpoints, billing, and lifecycle must remain separate from the local adapter | Treating cloud as a base-URL swap would hide real security and cost differences | 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 is the next hosted 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
+Scenario's [custom generation API](https://docs.scenario.com/get-started/generation/third-party-model-generation)
+returns asynchronous jobs, while 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.
+documents free cost preflights. PixelKiln now maps those mechanics into its
+normal plan, submit, poll, review, fetch, and restore lifecycle.
 
 Recommended order from here:
 
 1. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
    smoke tests.
-2. Build the Scenario still-image spike from issue #52 with dry-run cost, submit, poll,
-   download, and one custom-model or reference-image benchmark.
+2. Run the shared environment briefs through Scenario, then add one custom-model
+   or project-LoRA benchmark.
 3. Benchmark another pinned ComfyUI model and prompt pattern across at least two
    scene families. Reject any improvement that helps only one subject.
 4. Design ComfyUI Cloud as a separate authenticated and billable adapter.

package/README.md

@@ -2,9 +2,7 @@
 
 ![PixelKiln](https://wp.griffen.codes/wp-content/uploads/2026/08/download.png)
 
-[Website](https://pixelkiln.griffen.codes) ·
-[Documentation](https://pixelkiln.griffen.codes/docs) ·
-[GitHub](https://github.com/gfargo/pixelkiln)
+[Website](https://pixelkiln.griffen.codes) · [Documentation](https://pixelkiln.griffen.codes/docs) · [GitHub](https://github.com/gfargo/pixelkiln)
 
 Generate pixel art from a manifest, review it locally, recover paid work, and
 package the accepted files for a game engine.
@@ -15,16 +13,17 @@ local contact sheet, and commit the source and output hashes. No LLM chooses
 what to run or which image wins. The CLI handles provider calls, polling,
 hashing, downloads, and file placement.
 
-PixelLab is the production backend. Retro Diffusion and self-hosted ComfyUI are
-experimental. The Retro Diffusion adapter has live coverage for RD Fast and RD
-Plus stills; its multi-candidate, tileset, GIF, and spritesheet paths are tested
-with fixtures but still need paid live runs. ComfyUI has passed local generation,
-four-candidate review, cache recovery, and native-grid refinement on Apple MPS.
-Its tested SDXL workflow can find a composition, but it is not a finished
-pixel-art preset. Styles in one manifest may use different providers with
-separate budget ceilings. The [provider comparison](./PROVIDERS.md) lists the tested
-limits and the best route for buildings and environments. `FakeProvider` covers
-the same contract in automated tests.
+PixelLab is the production backend. Retro Diffusion, self-hosted ComfyUI, and
+Scenario are experimental. The Retro Diffusion adapter has live coverage for
+RD Fast and RD Plus stills; its multi-candidate, tileset, GIF, and spritesheet
+paths are tested with fixtures but still need paid live runs. ComfyUI has passed
+local generation, four-candidate review, cache recovery, and native-grid
+refinement on Apple MPS. Its tested SDXL workflow can find a composition, but
+it is not a finished pixel-art preset. Scenario has live-tested authentication,
+CU preflight, single- and two-output generation, human review, and durable
+restore with BFL Flux 2 Dev. It remains experimental. Styles may use different providers with separate
+budget ceilings. The [provider comparison](./PROVIDERS.md) lists the tested limits
+and best routes. `FakeProvider` covers the same contract in automated tests.
 
 ## Release
 
@@ -106,10 +105,11 @@ Put a hosted provider's 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=...
-
+# Scenario needs both values when `provider` is `scenario`
+SCENARIO_SDK_API_KEY=...
+SCENARIO_SDK_API_SECRET=...
 # Self-hosted ComfyUI needs no key; override its local URL only when needed
 COMFYUI_BASE_URL=http://127.0.0.1:8188
 ```
@@ -137,8 +137,9 @@ pixelkiln plan
 
 See [Getting started](./docs/GETTING_STARTED.md) for new and existing projects.
 Use [Set up PixelLab](./docs/PIXELLAB.md),
-[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), or
-[Set up ComfyUI](./docs/COMFYUI.md) for provider-specific configuration,
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md),
+[Set up ComfyUI](./docs/COMFYUI.md), or
+[Set up Scenario](./docs/SCENARIO.md) for provider-specific configuration,
 manifest examples, and current limits. See [Mixed-provider projects](./docs/MIXED_PROVIDERS.md)
 when styles in one manifest need different backends.
 
@@ -186,8 +187,9 @@ set. Generator choice, reference-image bytes, dimensions, palette, seed, and
 prompt settings participate in deterministic spec identity. A manifest may
 select another provider and pass namespaced `providerOptions`; see
 [Set up PixelLab](./docs/PIXELLAB.md),
-[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), and
-[Set up ComfyUI](./docs/COMFYUI.md). The
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md),
+[Set up ComfyUI](./docs/COMFYUI.md), and
+[Set up Scenario](./docs/SCENARIO.md). The
 [provider comparison](./PROVIDERS.md) covers costs,
 current confidence, and limitations. The committed ComfyUI projects now include
 transparent cutouts, palette-controlled backgrounds, wide environment canvases,
@@ -255,18 +257,17 @@ replace a hard palette or reference-image constraint. See
 Generator names describe PixelKiln workflows; their exact capabilities and
 prices depend on the selected provider. Retro Diffusion also supports the
 provider-specific `animation` generator. ComfyUI currently supports `map`
-through an operator-supplied workflow. Compare the adapters in the
-[provider comparison](./PROVIDERS.md).
+through an operator-supplied workflow. Scenario currently supports `map`
+with a required offline CU ceiling and a live quote before each paid call.
+Compare the adapters in the [provider comparison](./PROVIDERS.md).
 
 ## Derived artifacts
 
 ```bash
 # Deterministic sheet + atlas + provenance.
 pixelkiln pack --style base
-
 # Stable declared cells in an existing sheet.
 pixelkiln mount --style ground
-
 # Structural atlas + engine metadata + provenance.
 pixelkiln export --style ground --only terrain --format tiled
 ```
@@ -339,11 +340,9 @@ import {
   loadManifest,
   resolveSpecs,
 } from "pixelkiln"
-
 const loaded = await loadManifest("pixelkiln.manifest.json")
 const specs = await resolveSpecs(loaded)
 const plan = await buildPlan(specs, await loadLock("pixelkiln.lock.json"))
-
 console.log(plan.groups, plan.actionable.length)
 ```
 
@@ -361,6 +360,7 @@ exporters, managed artifact writes, and offline provenance verification. See
 | [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. |
 | [Set up ComfyUI](./docs/COMFYUI.md) | Experimental self-hosted server, workflow bindings, local cost semantics, and limits. |
+| [Set up Scenario](./docs/SCENARIO.md) | Experimental hosted models, two-part credentials, CU preflight, review, and durable downloads. |
 | [Versioned recipes](./docs/RECIPES.md) | Pinned workflow packs, model hashes, manifest templates, and quality contracts. |
 | [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. |

package/SECURITY.md

@@ -34,7 +34,8 @@ credentials in their query string. Reports involving authentication leakage, pat
 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`, `RD_API_KEY`, `.env` file, private
+Never attach a real `PIXELLAB_API_KEY`, `RD_API_KEY`, `SCENARIO_SDK_API_KEY`,
+`SCENARIO_SDK_API_SECRET`, `.env` file, private
 provider URL, or unredacted lockfile from a confidential project to a public
 report.