pixelkiln 0.7.0 → 0.8.0

package/README.md

@@ -24,7 +24,7 @@ tileset, GIF, and spritesheet live runs remain. An experimental ComfyUI adapter
 runs committed API-format still-image workflows on a self-hosted server. Its
 core-node smoke project has passed live generation, candidate queueing, and
 cache-only recovery on Apple MPS. An SDXL plus Pixel Art XL workflow also has
-four committed building and environment samples. See
+four baseline samples and four refined transparency and palette samples. See
 [provider comparison](./PROVIDERS.md) for the trade-offs, including large
 environment and building workflows.
 `FakeProvider` exercises the same contract deterministically in tests.
@@ -347,7 +347,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) | Twenty-four outputs comparing buildings, landmarks, large backgrounds, cost, and file readiness. |
+| [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Twenty-eight outputs comparing providers, large scenes, transparency, palette size, 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/COMFYUI.md

@@ -7,6 +7,8 @@ Diffusion 1.5 workflow has passed single-image generation and a four-candidate
 review queue on Apple MPS. A higher-quality SDXL workflow has also passed four
 building and environment renders. ComfyUI Cloud is not part of this release.
 
+[Visit ComfyUI](https://www.comfy.org/) or continue with the local setup below.
+
 ## Start ComfyUI
 
 Install and start ComfyUI using its
@@ -55,17 +57,19 @@ pixel-art quality.
 
 ## Install the tested quality stack
 
-The committed quality benchmark uses two public model files:
+The committed quality and post-processing benchmarks use three public model
+files:
 
 | File | ComfyUI folder | SHA-256 | License named by the model card |
 |---|---|---|---|
 | [`sd_xl_base_1.0.safetensors`](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors) | `models/checkpoints` | `31e35c80fc4829d14f90153f4c74cd59c90b779f6afe05a74cd6120b893f7e5b` | CreativeML Open RAIL++-M |
 | [`pixel-art-xl.safetensors`](https://huggingface.co/nerijs/pixel-art-xl/blob/main/pixel-art-xl.safetensors) | `models/loras` | `4234637cb80c998f41e348e6a6cb6bc20d8d038b2b0f256b6129b3b5e353eef7` | CreativeML OpenRAIL-M |
+| [`birefnet.safetensors`](https://huggingface.co/Comfy-Org/BiRefNet/blob/main/background_removal/birefnet.safetensors) | `models/background_removal` | `9ab37426bf4de0567af6b5d21b16151357149139362e6e8992021b8ce356a154` | MIT |
 
 Download each file into the named folder, verify its checksum, then confirm the
-checkpoint and LoRA appear in ComfyUI. The files are about 6.9 GB and 171 MB.
-They are not bundled with PixelKiln. Read both model cards before distributing
-the models or their outputs.
+checkpoint, LoRA, and background-removal model appear in ComfyUI. The files are
+about 6.9 GB, 171 MB, and 444 MB. They are not bundled with PixelKiln. Read the
+model cards before distributing the models or their outputs.
 
 The benchmark renders at 1024×1024, where SDXL has enough room to compose the
 scene, then uses ComfyUI's core `ImageScale` node with `nearest-exact` to write
@@ -77,6 +81,40 @@ output dimensions.
 You can reproduce the four samples with the committed
 [ComfyUI benchmark project](../benchmarks/provider-environments/comfyui/README.md).
 
+## Remove backgrounds and control the palette
+
+ComfyUI 0.34.3 has the required nodes in core. No custom-node package is needed.
+The tested isolated-asset graph runs these nodes in this order:
+
+1. Decode the 1024×1024 SDXL image.
+2. Run `RemoveBackground` with the loaded BiRefNet model.
+3. Invert the returned background mask for use as foreground alpha.
+4. Run `ImageQuantize` on the RGB image with 64 colors and no dithering.
+5. Join the quantized RGB image with the alpha mask.
+6. Reduce the RGBA result with `ImageScale` set to `nearest-exact`.
+
+The order is deliberate. BiRefNet sees the full-resolution, full-color image,
+while quantization cannot damage the mask. Scenic backgrounds skip BiRefNet
+and use only 64-color quantization before the final scale.
+
+The [post-processing benchmark](../benchmarks/provider-postprocessing/comfyui/README.md)
+reuses the same prompts, seeds, SDXL settings, and LoRA strengths as the first
+ComfyUI run. Its two isolated assets have 60% and 62% transparent pixels and 55
+and 58 RGB colors. The two backgrounds use 64 and 60 colors. The original
+files ranged from 16,811 to 50,985 colors.
+
+Use PixelKiln to keep those requirements enforceable:
+
+```bash
+pixelkiln audit --style isolated-refined --min-transparency 0.5 --max-colors 64 --check
+pixelkiln audit --style background-refined --max-colors 64 --check
+```
+
+Start without dithering for compact game art. Floyd-Steinberg can soften bands,
+but it adds noisy pixel patterns. Ordered Bayer dithering is easier to art-direct
+when a project needs deliberate texture. Whichever mode you choose becomes part
+of the committed workflow hash.
+
 ## Configure the manifest
 
 Put dimensions on each asset. Put workflow configuration under
@@ -167,10 +205,9 @@ the portable reference against the current `COMFYUI_BASE_URL`.
 For large mountains, buildings, and backgrounds, model choice and working
 resolution matter more than the provider label. The SDXL benchmark produced a
 coherent 384px cliff fortress and two layered environments where the starter
-SD1.5 workflow did not. It still returned opaque isolated assets and thousands
-of source colors, so transparency and palette reduction remain separate art
-pipeline steps. Benchmark the exact committed workflow before assigning it a
-production batch.
+SD1.5 workflow did not. Core post-processing then turned the isolated images
+into transparent 64-color assets without changing their composition. Benchmark
+the exact committed workflow before assigning it a production batch.
 
 ## Troubleshooting
 

package/docs/PROVIDER_BENCHMARK.md

@@ -4,8 +4,8 @@ This benchmark compares PixelLab and Retro Diffusion on five game-art briefs,
 with a four-brief ComfyUI extension using a named SDXL stack. Three briefs use
 256×256 output; two use 384×384 to test larger buildings and environment
 backgrounds. The hosted providers have two attempts per brief. ComfyUI has one
-attempt on each supported brief. Prompt text and seed numbers match, but seeds
-are not portable between models.
+baseline and one post-processed attempt on each supported brief. Prompt text
+and seed numbers match, 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.
@@ -178,13 +178,33 @@ reduction, but they are not indexed, low-palette sprites. Add explicit
 background removal and palette quantization when the target art direction
 requires them.
 
+### ComfyUI post-processing result
+
+The follow-up graph keeps the generation settings fixed and changes only the
+cleanup nodes. BiRefNet removes the isolated backgrounds, and ComfyUI's core
+quantizer limits every image to 64 colors without dithering.
+
+| Original observatory | Refined observatory | Original fortress | Refined fortress |
+|---|---|---|---|
+| ![Original opaque ComfyUI mountain observatory](../website/public/benchmarks/provider-environments/comfyui/isolated/a/mountain-observatory.png) | ![Transparent 64-color ComfyUI mountain observatory](../website/public/benchmarks/provider-postprocessing/comfyui/isolated/mountain-observatory.png) | ![Original opaque ComfyUI cliffside fortress](../website/public/benchmarks/provider-environments/comfyui/isolated/a/cliffside-fortress.png) | ![Transparent 64-color ComfyUI cliffside fortress](../website/public/benchmarks/provider-postprocessing/comfyui/isolated/cliffside-fortress.png) |
+
+| Original alpine valley | 64-color alpine valley | Original volcanic pass | 64-color volcanic pass |
+|---|---|---|---|
+| ![Original ComfyUI alpine valley](../website/public/benchmarks/provider-environments/comfyui/background/a/alpine-valley.png) | ![64-color ComfyUI alpine valley](../website/public/benchmarks/provider-postprocessing/comfyui/background/alpine-valley.png) | ![Original ComfyUI volcanic pass](../website/public/benchmarks/provider-environments/comfyui/background/a/volcanic-pass.png) | ![64-color ComfyUI volcanic pass](../website/public/benchmarks/provider-postprocessing/comfyui/background/volcanic-pass.png) |
+
+The cutouts retained their silhouettes while reaching 60% and 62% transparent
+pixels. They use 55 and 58 RGB colors instead of 16,811 and 31,572. The scenic
+images fell to 64 and 60 colors without losing their main depth bands. The
+committed [post-processing project](../benchmarks/provider-postprocessing/comfyui/README.md)
+contains the workflows, manifest, audit commands, and provenance.
+
 ## Cost and operational results
 
 | Provider | Successful images | Charged amount | Final balance |
 |---|---:|---:|---:|
 | PixelLab | 10 | 10 generations | 4,411 generations |
 | Retro Diffusion | 10 | $0.744 | $9.73 |
-| ComfyUI | 4 | 0 `free` PixelKiln units | No account balance |
+| ComfyUI | 8 | 0 `free` PixelKiln units | No account balance |
 
 PixelLab charged one generation per image. Retro Diffusion quoted and charged
 $0.058 for each 256px RD Plus image and $0.099 for each 384px RD Plus image;
@@ -200,7 +220,7 @@ The run also caught two integration details:
 
 All three manifests now pass `doctor` and report a current plan. The hosted
 projects have ten healthy PNG cache entries each; the ComfyUI extension has
-four.
+four baseline and four refined entries.
 
 ## Recommendation
 
@@ -215,10 +235,10 @@ were cheaper and more faithful to the brief. Try Retro Diffusion when you want
 foreground framing and a closer illustrated scene.
 
 Try the tested ComfyUI SDXL stack when local control and larger compositions
-matter more than ready-to-place transparency. It produced the best large
-building in this run and a strong layered valley, with no provider charge. It
-also took roughly 90 seconds per 1024px render on the tested Apple MPS machine,
-and every output still needs palette review.
+matter most. It produced the best large building in this run and a strong
+layered valley, with no provider charge. The refined core-node graph also makes
+transparent, 64-color cutouts. A 1024px render took roughly 60 to 90 seconds on
+the tested Apple MPS machine.
 
 Do not ask any provider for one giant finished level. Generate terrain,
 background, buildings, landmarks, and foreground pieces separately. Compose
@@ -227,5 +247,5 @@ 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. 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.
+all providers lost the requested fortress. Rerun the committed manifests when
+a provider or local model changes.

package/docs/README.md

@@ -12,7 +12,7 @@ This source also renders at
 | [Getting started](./GETTING_STARTED.md) | Install from a checkout, create or adopt a project, run the everyday workflow, and decide what belongs in Git. |
 | [Set up PixelLab](./PIXELLAB.md) | Configure the production provider, choose a generator, and use its account workflows. |
 | [Set up Retro Diffusion](./RETRO_DIFFUSION.md) | Configure the experimental provider, choose a style, and understand its live-tested boundary. |
-| [Set up ComfyUI](./COMFYUI.md) | Connect a self-hosted server, install the tested SDXL pixel-art stack, and bind a committed workflow. |
+| [Set up ComfyUI](./COMFYUI.md) | Install the tested SDXL and BiRefNet stack, then bind generation and cleanup workflows. |
 | [CLI reference](./CLI.md) | Every command and flag, offline/provider requirements, JSON output, and exit behavior. |
 | [Manifest reference](./MANIFEST.md) | Every style and asset field, inheritance, generator-specific constraints, mounting, and schema validation. |
 | [Agent workflows](./AGENTS.md) | Install the official skill and pair agent guidance with the deterministic CLI. |

package/package.json

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

package/skills/pixelkiln/references/comfyui.md

@@ -32,6 +32,14 @@ PNG still matches the manifest dimensions. The isolated workflow uses LoRA
 strength 1.0, while the environment workflow uses 0.85. Read
 `docs/COMFYUI.md` for download links, checksums, licenses, and measured limits.
 
+For production-oriented stills, prefer the core-node refinement graph in
+`benchmarks/provider-postprocessing/comfyui/`. It runs BiRefNet on the decoded
+full-resolution image, quantizes RGB separately, joins the inverted background
+mask as alpha, and scales last. Do not quantize before background removal or
+feed a scenic background through the removal model. Use `pixelkiln audit` with
+both `--min-transparency` and `--max-colors` so the cleanup requirements fail in
+CI when a workflow or model changes.
+
 The plan reports `0 free` and generation uses `--budget 0`. Explain that this
 means no metered API charge. Hardware, electricity, hosting, and model licenses
 can still cost money.