pixelkiln 0.86.0 → 0.86.1

package/PROVIDERS.md

@@ -114,13 +114,13 @@ 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 |
+| Best fit today | Large or illustrative art rendered big then reduced (render, Pixelate, cut out, refine), image-to-image edits of existing art, and a chain of models across styles, each with a hard CU ceiling. Poor for small native-size sprites. |
+| PixelKiln generator | `map` stills, with `styleImages` and `image-to-image` revisions as reference uploads, and `revision.fromStyle` to chain styles |
 | Output | One to four PNG candidates, 16–4096px; each model has its own bounds |
 | 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 |
+| Confidence | BFL Flux 2 Dev live-tested through quote, billing, single/two-output jobs, human selection, PNG download, and provider-backed restore. Ten generation models, six tool models, reference-image edits, a three-style chain, and a game's landmarks and cover have each been run once; see the [Scenario page](./docs/SCENARIO.md). 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
@@ -134,8 +134,8 @@ background. That distinction matters more than raw canvas size.
 
 | 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; both top out at 400×400. `imagePro` reaches 792 wide or 688 tall for a flat 40 generations. | `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. |
+| 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. | Raw model output is opaque and anti-aliased (the BFL smoke keep used 19,619 colors), but a chain of render at four times the size, Pixelate to the target grid, Birefnet, and `refine` took a 960 px render of an alpine lodge to a 240×208 native grid at high confidence with 63 colors, for 18 CU (a 1 CU render can be nearly as good). Details and the Pixelate grid caveat are in [Set up Scenario](./docs/SCENARIO.md#large-and-illustrative-art-render-big-pixelate-refine). One sample per subject. |
+| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene; both top out at 400×400. `imagePro` reaches 792 wide or 688 tall for a flat 40 generations. | `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. | GPT Image 2 at four times the target size, then Pixelate, turned a course-cover brief into a convincing pixel scene with 31 colors and legible title text. It has not been put through the shared benchmark. A large model canvas is not native pixel resolution: pixelate to the grid you need and check it with `refine`. |
 | 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. |
 

package/docs/SCENARIO.md

@@ -237,21 +237,107 @@ refined it, for 8 CU on the cheapest path and 18 CU with GPT Image 2, ending in
 a 64×64 transparent sprite that passed the `refine` gate. Three rules came out
 of it:
 
-- A revision's parent must be in the same style, and a style has one model. To
-  chain steps, restate the previous output in the next style as a placed
-  `source`: `"source": "outputs/gen-klein/knight.png"`. Run each step with
-  `gen --style <id>`; nothing orders them yet.
+- A style has one model, so a chain spans styles. Name the parent's style with
+  `revision.fromStyle` (see [Across styles](./REVISIONS.md#across-styles)); the
+  child is blocked until the parent is generated, and `gen` runs the whole chain
+  in one invocation, one wave per link. The
+  [chain run](../benchmarks/provider-scenario-chain/README.md) did this live in
+  8 CU. (The pipeline benchmark was run before `fromStyle` existed, so it
+  restates each output as a placed `source` and runs `gen --style` per step.)
 - A `quality` profile gates every asset in its style, parents included, so a raw
-  parent blocks its own child. Put `quality` only on a final style whose asset is
-  the last output placed as a `source`, then run `pixelkiln refine --style`.
+  parent in the same style blocks its own child. Put `quality` on the last style
+  of the chain, whose parents are in other styles, then run
+  `pixelkiln refine --style`.
 - Pass the same palette to the tool (Pixelate's `colorPalette`) and to
-  `quality.palette`. The output then stays inside it. Pixelate's
-  `pixelGridSize` also set the detected native grid closely (48, 64 and 128
-  asked, 46, 64 and 128 found).
+  `quality.palette`. The output then stays inside it.
 
 A palette that is too small for the art costs fidelity (a bright blue cape
 became navy under a 32-colour palette), so passing the gate is not approval.
 
+### Large and illustrative art: render big, pixelate, refine
+
+A [game pilot](../benchmarks/provider-scenario-game-pilot/README.md) ran the
+chain on a real game's large landmarks (240 px wide, 176 to 224 px tall) and on a
+course cover, and it is where Scenario earned a place: a strong model renders the
+art at four times its final size, Pixelate reduces it to the target grid on a
+bounded palette, Birefnet removes the background, and `refine` confirms the
+grid. It is poor at the opposite end: 32 px props lose their shape.
+
+| Step | Setting that worked |
+|---|---|
+| Render | GPT Image 2 (`quality: medium`, flat 11 CU at any canvas size; `high` is 44), or FLUX.2 Klein 9b (1 CU). Ask for the subject isolated on a plain white background, with no ground or shadow. Canvas four times the target. |
+| Pixelate | `pixelGridSize` and `colorPaletteSize` 64. **On an input wider than about 512 px the grid is not literal:** 240 asked on a 960 px image gave 2 px blocks (480 cells), 120 gave 4 px blocks (240 cells). Test one image and read the blocks before a batch. |
+| Cut out | Birefnet, 2 CU. |
+| Refine | `pixelkiln refine` with the image's own 64 most common colours. |
+
+With the right grid, a 960×832 render of a ski lodge came back as a **240×208**
+native grid at **high** confidence, the same size as the game's existing
+sprite, and visibly more detailed. At twice the grid the detector reported
+medium confidence and a doubled grid, so a result that is not high is a sign the
+grid was mis-set, not that the art is bad. The 1 CU Klein render of a temple was
+about as good as the 11 CU GPT one. One chain costs 8 CU (Klein) or 18 CU (GPT
+Image 2).
+
+For a **cover or key art**, GPT Image 2 at four times the size, then Pixelate at a
+grid giving the target width, produced a convincing pixel scene with 31 colours.
+It renders legible title text, which PixelLab does not, and the text survives
+Pixelate. Before pixelating it is a painterly illustration, not pixel art.
+
+Do not use this for small native-size props. A winter pine and an autumn tree at
+32 px came back as different trees, and Birefnet left holes in the canopy. A
+free recolour of the original, or a PixelLab generation at the native size, is
+the better tool there.
+
+### Sound effects and other non-image models
+
+The adapter handles still images only, but Scenario's audio models are reachable
+through the same account. A call outside PixelKiln (`POST /generate/custom/{model}`,
+then poll `/jobs/{id}` and fetch the asset) produced a sound effect for 1 CU;
+nothing about it is recorded in a lockfile. Measured on October 5, 2026:
+
+| Model | CU | Output |
+|---|---:|---|
+| `model_mm-audio-2-t2a` (MM Audio SFX) | 1, flat at any duration | Mono MP3, 44.1 kHz, 64 kbps |
+| `model_elevenlabs-sound-effects-v2` | 30, flat at any duration | Stereo MP3, 44.1 kHz, 128 kbps |
+
+Both ignore the duration for pricing, so ask for the length the game needs. A
+prompt that narrates a sequence ("chains rattle, then the disc drops into the
+tray") came back at the full requested length with the events spread out;
+asking for one fast sound and a duration of 1.0 to 1.4 seconds, then trimming
+leading and trailing silence, helps, but it was not enough on its own.
+
+**What finally worked for a two-part impact** (a disc hitting a basket's chains,
+then landing on its bars), judged by the game's owner by ear:
+
+- **Generate each event as its own sound and layer them.** One prompt cannot carry
+  two events. MM Audio returned ambience for an impact prompt (its "drop" came
+  back at -50 dB, near silence) and ElevenLabs was the only model that made
+  distinct hits; an envelope check (the share of time within 20 dB of the peak,
+  and the count of sharp onsets) caught the ambience before anyone listened.
+- **Describe the physical object, not a word that implies a cavity.** "Hollow
+  steel basket" produced a bucket-like clank with echo. What worked was "a plastic
+  disc landing on a ring of thin steel bars: a dry plastic-on-metal clack followed
+  by a quick tinny rattle against the metal rods, outdoors in open air,
+  completely dry, no echo, no reverb, no hollow resonance, no bucket sound."
+  The chain layer used "loose steel chain links rattling and jangling ... close up,
+  dry, no room reverb, no background noise."
+- **Expect big variation between takes.** Re-running the same ElevenLabs prompt
+  gave drops of 65 ms, 114 ms, 166 ms and 274 ms; the owner picked the second of
+  three re-runs. There is no seed, so keep the chosen file and note the prompt.
+- **Layer with ffmpeg:** trim silence below -50 dB at both ends, high-pass at
+  60 Hz, `loudnorm` each part to -18 LUFS, delay the second part about 260 ms,
+  `amix` without normalisation, limit at 0.89, then `loudnorm` the mix to -16 LUFS.
+
+One finished two-part effect cost about 210 CU of ElevenLabs generations here (a
+chain layer and six drop attempts at 30 CU each), after about 70 CU of cheaper
+attempts that did not work, so budget for several takes of each part. Because a game's sounds should share one tone, fix the prompt
+wording ("close up, dry, no room reverb, no background noise"), the model, and
+the post chain above for every effect, and record each effect's prompts, model
+and post steps beside the file.
+
+Music models (ACE-Step, MusicGen, ElevenLabs Music, Lyria 3.5) quoted 10 to 30
+CU; Sonilo and Lyria 3 Pro need the `cu-pro-q3-25` plan. Music was not generated.
+
 ## Plan before spending
 
 Scenario prices depend on model, size, steps, and output count, so PixelKiln

package/package.json

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

package/skills/pixelkiln/references/scenario.md

@@ -32,6 +32,16 @@ Scenario model parameters vary. The MVP supplies prompt, 16–4096px dimensions
 model inputs in `parameters`; PixelKiln rejects attempts to override its prompt,
 dimensions, seed, output count, project routing, or CU ceiling.
 
+Chain models across styles with `revision.fromStyle`; put any `quality` profile
+on the last style. For large or illustrative art, render at four times the
+target size (GPT Image 2 `quality: medium` is a flat 11 CU, FLUX.2 Klein 9b
+1 CU), then Pixelate, Birefnet cutout, and `pixelkiln refine`. Pixelate's
+`pixelGridSize` is not literal on inputs wider than about 512 px (120 asked gave
+a 240-cell grid on a 960 px image): check one image's blocks first. Do not use
+the chain for small native-size sprites. The adapter handles images only;
+sound effects (MM Audio 1 CU, ElevenLabs 30 CU) go through the API directly.
+See `docs/SCENARIO.md` for settings and measurements.
+
 PixelKiln validates the job, bytes, hashes, and recovery path. It does not prove
 the output is good pixel art. Inspect one result at 1× before approving a batch.