pixelkiln 0.85.0 → 0.86.1

package/docs/MANIFEST.md

@@ -472,7 +472,8 @@ their own page: [Characters](./CHARACTERS.md) and
 | Revision field | Type | Meaning |
 |---|---|---|
 | `mode` | enum, required | `image-to-image`, `inpaint`, `outpaint`, `reduce-colors`, `correct-pixelart`, `remove-background`, `animate`, `animate-pixminimax`, `animate-skeleton`, `interpolate`, or `edit-animation`. The selected provider must opt into the mode. |
-| `from` | asset id, required | Parent asset in the same style. Self-references, unknown ids, and cycles are rejected. A parent written as a set (a character's directions, an animation's frames) is read as every member: `reduce-colors`, `correct-pixelart`, and `edit-animation` take the whole set in one call; the other modes refuse it. See [Revising a whole set at once](./REVISIONS.md#revising-a-whole-set-at-once). |
+| `from` | asset id, required | Parent asset, in this asset's style unless `fromStyle` names another. Self-references, unknown ids, and cycles are rejected. A parent written as a set (a character's directions, an animation's frames) is read as every member: `reduce-colors`, `correct-pixelart`, and `edit-animation` take the whole set in one call; the other modes refuse it. See [Revising a whole set at once](./REVISIONS.md#revising-a-whole-set-at-once). |
+| `fromStyle` | style id | The style the parent lives in, when it is not this asset's own. The parent must be an asset in that style, and styles may depend on one another but not in a cycle. See [Across styles](./REVISIONS.md#across-styles). |
 | `mask` | string | Manifest-relative PNG required for `inpaint`; rejected for the other modes. Its dimensions must match an available source. |
 | `strength` | number 0–1 | Workflow edit/denoise strength (`image-to-image`, `correct-pixelart`); rejected for `reduce-colors`, `remove-background`, `animate`, `animate-pixminimax`, `interpolate`, and `edit-animation`. Interpretation is provider- and model-specific. |
 | `numColors` | integer 2–256 | `reduce-colors` only. Target palette size; mutually exclusive with `paletteImage`. |

package/docs/REVISIONS.md

@@ -43,15 +43,10 @@ Keep the parent as its own asset and point the child at its stable asset id:
 }
 ```
 
-`from` names another asset in the same style. A source and its revision cannot
-be the same asset, and revision chains cannot contain a cycle. `source` and
-`revision` are mutually exclusive on one asset.
-
-Revision edges do not cross styles or providers in this version. To use output
-from another provider, commit or retain that PNG and declare it as a separate
-`source` asset in the ComfyUI revision style. The child still records the exact
-source hash, but the cross-provider handoff is a file boundary rather than one
-automatic lock dependency.
+`from` names another asset. It lives in the child's own style unless
+`fromStyle` names another (see [Across styles](#across-styles)). A source and its
+revision cannot be the same asset, and revision chains cannot contain a cycle.
+`source` and `revision` are mutually exclusive on one asset.
 
 Start with a low strength. Values around `0.2`–`0.4` give the workflow room to
 change texture and lighting while retaining more of the source. Higher values
@@ -104,6 +99,41 @@ poses" opens the same editor on its keypoints file. Saving rewrites the file
 only if it still holds what the page loaded (an edit made elsewhere since is
 refused, not overwritten), and the animation is stale until generated again.
 
+### Across styles
+
+A style has one provider and one model, so a chain that generates with one model
+and cleans up with another spans styles. Name the parent's style:
+
+```jsonc
+{
+  "styles": {
+    "gen": { "generator": "map", "outDir": "art/gen", "providerOptions": { "scenario": { "modelId": "model_bfl-flux-2-klein-9b", "maxComputeUnits": 1 } } },
+    "pixelate": { "generator": "map", "outDir": "art/pixelate", "providerOptions": { "scenario": { "modelId": "model_sc-pixelate", "maxComputeUnits": 5, "referenceParameter": "image", "referenceArray": false } } }
+  },
+  "assets": {
+    "knight": { "prompt": "a knight, isolated on white", "styles": ["gen"] },
+    "knight-px": {
+      "prompt": "pixelate",
+      "styles": ["pixelate"],
+      "revision": { "mode": "image-to-image", "from": "knight", "fromStyle": "gen" }
+    }
+  }
+}
+```
+
+The child starts from the parent's output file, however that style produced it
+(any provider, or a placed `source`), and the dependency gate is unchanged: the
+child is `blocked` until the parent is downloaded, current, and untouched, and
+`gen` takes the whole chain to the end in one run, one wave per link. The parent
+must be an asset in the named style. Styles may depend on one another but not
+in a cycle, and `fromStyle` naming the asset's own style is the ordinary case.
+`--style` still selects which specs a run returns; a parent style it excludes is
+resolved, not generated.
+
+A `quality` profile gates the style it is on. Put it on the last style of a
+chain, whose parents are in other styles, and only that style's output is gated.
+A profile on a style that also holds the raw parent would block the child.
+
 ## Inpainting
 
 An inpaint revision also declares a manifest-relative mask:

package/docs/SCENARIO.md

@@ -186,7 +186,13 @@ quoted and billed identically; see the
 [tool-model smoke](../benchmarks/provider-scenario-tools/README.md)). Pixel
 Snapper returned an 83×83, exactly-16-colour native-grid version of a 512×512
 image, a different size than the manifest's canvas, and Birefnet's cutout kept
-its subject at alpha 254 rather than 255. The other tools were only quoted. They overlap PixelKiln's own offline work: `pixelkiln refine` snaps
+its subject at alpha 254 rather than 255. Pixelate (5 CU) was run too and returned a 23-colour, crisp pixel version at the
+source's size; of the upscalers, Topaz smoothed the art, Upscale V3 repainted it
+as a photoreal castle, and Recraft Crisp returned WebP, which the adapter refuses,
+so none of them suits pixel art. Pixelate's output also passed `pixelkiln refine`'s
+high-confidence grid gate as a 102×102, 23-colour asset, where the raw image
+(low confidence) and Pixel Snapper's output (medium) did not: GPT Image 2,
+then Pixelate, then free refinement made one gate-passing asset for 16 CU. They overlap PixelKiln's own offline work: `pixelkiln refine` snaps
 the grid and palette for free, and PixelLab's `remove-background` revision costs
 one generation. Reach for these when the art is already on Scenario.
 
@@ -223,6 +229,115 @@ upgrading should be one `model_retrodiffusion-plus` still at 64×64 with the
 default style: quote, billed amount, dimensions, and whether it comes back as
 PNG.
 
+### Chaining models and tools
+
+The [pipeline run](../benchmarks/provider-scenario-pipeline/README.md)
+generated a character, pixelated it to a palette, cut out its background, and
+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 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 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.
+
+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.85.0",
+  "version": "0.86.1",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,

package/schema/manifest.schema.json

@@ -1022,6 +1022,10 @@
                     "type": "string",
                     "minLength": 1
                   },
+                  "fromStyle": {
+                    "type": "string",
+                    "minLength": 1
+                  },
                   "mask": {
                     "type": "string",
                     "minLength": 1

package/skills/pixelkiln/references/revisions.md

@@ -2,8 +2,10 @@
 
 Read this reference when an asset declares `revision`.
 
-- Treat the parent and child as separate assets. `revision.from` must name a
-  parent in the same style.
+- Treat the parent and child as separate assets. `revision.from` names the
+  parent, in the child's own style unless `revision.fromStyle` names another, so
+  a chain can generate with one provider and refine with another. A `quality`
+  profile gates its own style; put it on the last style of a chain.
 - Run `pixelkiln plan --only <child>` first. If it reports `blocked`, do not try
   to submit the child or work around the gate.
 - A generated parent must be current and downloaded. When the parent has a

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.