pixelkiln 0.14.0 → 0.16.0

package/PROVIDERS.md

@@ -9,6 +9,11 @@ PixelLab remains the default so existing manifests and spec hashes remain
 compatible. The manifest's top-level `provider` is the default; a style may
 override it. Keep service settings under the matching `providerOptions` key.
 
+Provider choice and release quality are separate. Any supported single-image
+style can declare one `quality` profile for native-grid recovery, a closed
+palette, measurable checks, and named approval. The profile does not change the
+provider request or its cost. Pack and mount use only approved derived PNGs.
+
 To configure a project, use [Set up PixelLab](./docs/PIXELLAB.md),
 [Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md),
 [Set up ComfyUI](./docs/COMFYUI.md), or
@@ -21,7 +26,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 |
+| ComfyUI | Experimental; local generation, review, recovery, and image-to-image revision smoke live-tested on Apple MPS; inpaint/outpaint remain mock-tested | 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 |
 
@@ -76,9 +81,10 @@ prompt, size, batch, and optional seed inputs PixelKiln may replace.
 
 | Decision | ComfyUI through PixelKiln |
 |---|---|
-| Best fit today | Local composition experiments, private inputs, and teams prepared to maintain and manually validate custom graphs |
+| Best fit today | Local composition experiments, private inputs, controlled revisions, and teams prepared to maintain and manually validate custom graphs |
 | PixelKiln generator | `map` stills |
 | Output | One PNG output node, with 1–16 review candidates |
+| Revision input | `image-to-image`, `inpaint`, and user-authored `outpaint` graphs; hashed parent/mask uploads and source comparison are covered. The bundled img2img graph passed a three-strength live smoke but missed the requested winter treatment and lost alpha. |
 | Cost model | `0 free`; local compute and hosting are outside PixelKiln's estimate |
 | Reproducibility | Workflow content is hashed; model files, custom-node versions, and runtime settings must still be managed outside PixelKiln |
 | Account lifecycle | Read-only connectivity check; no balance, remote object listing, tagging, or purge |
@@ -90,6 +96,12 @@ 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.
 
+The revision manifest and dependency gate are provider-neutral, but ComfyUI is
+the only built-in adapter that currently opts in. PixelLab, Retro Diffusion,
+and Scenario reject revision assets offline. See
+[Controlled asset revisions](./docs/REVISIONS.md) before using the bundled
+square image-to-image graph.
+
 ## Where Scenario fits
 
 Scenario adds hosted third-party models and reusable project-specific models

package/README.md

@@ -14,16 +14,16 @@ 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, 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.
+Scenario are experimental. Retro Diffusion has live coverage for RD Fast and
+RD Plus stills; its other paths still need paid live runs. ComfyUI has passed
+local generation, candidate review, recovery, and native-grid refinement on
+Apple MPS. Its tested SDXL workflow finds compositions, not finished pixel art.
+Scenario has passed CU preflight, generation, human review, and durable restore
+with BFL Flux 2 Dev.
+
+Styles may use different providers with separate budget ceilings. The
+[provider comparison](./PROVIDERS.md) lists the tested limits and best routes.
+`FakeProvider` covers the shared contract in automated tests.
 
 ## Release
 
@@ -42,7 +42,7 @@ PixelKiln keeps the missing record:
 - a committed manifest defines assets, styles, generators, budgets, and output;
 - a committed lockfile maps each style/asset to paid provider work and exact
   output hashes;
-- planning distinguishes missing, stale, recoverable, in-flight, untracked, and
+- planning distinguishes blocked, missing, stale, recoverable, in-flight, untracked, and
   manually changed files before money is spent;
 - local review keeps human judgment where it matters, choosing artwork;
 - content-addressed recovery prevents a transient URL failure from buying the
@@ -56,10 +56,11 @@ PixelKiln keeps the missing record:
 |---|---|
 | Plan and budget | Offline manifest/lock/disk diff, provider-grouped estimates, keyed mixed-provider budget ceilings, JSON/CI gate. |
 | Generate and review | Resumable submit/poll/pick/fetch pipeline with a fast local candidate sheet. |
+| Controlled revisions | Hashed image-to-image/inpaint lineage, fail-closed parent approval, and source-versus-candidate review; ComfyUI is the first adapter. |
 | Existing-art onboarding | Manifest scaffolding, exact-hash account adoption, and prompt recovery. |
 | Recovery | Validated local content cache, durable provider-reference restore, account object-hash cache, and resumable jobs. |
 | Shared-account safety | Cross-project claim files or a registered workspace catalog, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |
-| Quality control | Palette distance, transparency, color-count, relative outlier, cache-integrity, and doctor gates. |
+| Quality control | Manifest-native grid recovery, closed palettes, named approval, regression baselines, and fail-closed packaging. |
 | Sprite packaging | Deterministic RGBA packing, stable-cell mounting, explicit external input lists, structural output roles. |
 | Engine export | Lossless generic tile contract, Tiled Wang sets, and Godot 4 terrain sets. |
 | Artifact integrity | Portable source/output hashes, canonical fingerprints, manual-edit protection, transactional promotion, crash journal recovery. |
@@ -67,8 +68,9 @@ PixelKiln keeps the missing record:
 
 ### Local human review
 
-`pixelkiln pick` opens an actual local candidate sheet; the orchestration layer
-never asks a model to choose artwork for you.
+`pixelkiln pick` opens a local candidate sheet. It preserves each image's aspect
+ratio, fits large work without blurring small sprites, and never asks a model to
+choose artwork for you.
 
 ![PixelKiln candidate review UI](./website/public/review-ui-showcase.jpg)
 
@@ -191,16 +193,12 @@ select another provider and pass namespaced `providerOptions`; see
 [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,
-and native-grid recovery for model output that only looks like pixel art. The
-ComfyUI guidance is quality-first: start with 48–128px native components,
-apply the final palette after grid recovery, require prompt-coverage and human
-cluster-and-silhouette review, and compose larger scenes from accepted parts
-instead of chasing a larger raster. Background removal and the art decision
-still need the graph and a person. `pixelkiln refine` now handles grid recovery,
-final palette enforcement, measurable checks, and the hash-bound approval
-record.
+current confidence, and limitations. ComfyUI works best as a composition tool:
+start with 48–128px native components and build larger scenes from accepted
+parts. Any single-image style can declare a `quality` profile for grid recovery,
+a closed palette, measurable checks, and named human approval. `plan --check`,
+`pack`, and `mount` then fail closed when that derived output is missing or
+stale. Changing the profile never schedules another provider generation.
 
 Versioned recipes capture tested workflows, model hashes, license links, and
 manifest-ready styles with quality boundaries. Start with `pixelkiln recipe install comfyui/pixel-art-xl-environment@1.0.0`.
@@ -226,11 +224,10 @@ pixelkiln restore
 pixelkiln audit --check --max-distance 35 --min-transparency 0.1
 pixelkiln cache --check
 
-# Provider-neutral pixel cleanup after selecting a generated candidate.
-pixelkiln refine --from candidate.png --out art/native.png \
-  --palette "#141b1e,#23312a,#384d4f,#526a8d,#709fcf,#865c45,#c6a766,#f1bb70"
-pixelkiln refine approve --from art/native.pixelkiln.json --reviewer "Your Name"
-pixelkiln refine check --from art/native.pixelkiln.json
+# Build and verify the quality output declared by style.quality.
+pixelkiln refine --style base
+pixelkiln refine approve --from assets/final/anvil.pixelkiln.json --reviewer "Your Name"
+pixelkiln refine check --style base
 ```
 
 Repeated `--style`, `--only`, `--claims`, and `--output-role` filters
@@ -272,11 +269,10 @@ pixelkiln mount --style ground
 pixelkiln export --style ground --only terrain --format tiled
 ```
 
-Pack, mount, and export write managed bundles. A `.pixelkiln.json` companion
-records portable source paths/hashes, layout/export options, output hashes, and
-a canonical fingerprint. Existing unowned output is adopted only when already
-byte-identical; manual edits stop the whole write unless `--force` explicitly
-takes ownership.
+Pack, mount, and export write managed bundles. When a style has a quality
+profile, pack and mount consume only its current approved PNGs and include their
+records in provenance. Existing unowned output is adopted only when already
+byte-identical; manual edits stop the whole write unless `--force` takes ownership.
 
 All changing members stage before promotion. Ordinary failures roll back.
 Abrupt termination leaves a validated transaction journal: the next invocation
@@ -346,8 +342,9 @@ const plan = await buildPlan(specs, await loadLock("pixelkiln.lock.json"))
 console.log(plan.groups, plan.actionable.length)
 ```
 
-The package also exports audit and image-regression gates, provider-neutral refinement, lock/output
-helpers, provider contracts, pipeline stages, sprite packing/mounting, tile
+The package also exports audit and image-regression gates, quality-profile
+inspection and refinement, revision-readiness checks, lock/output helpers,
+provider contracts, sprite packing/mounting, tile
 exporters, managed artifact writes, and offline provenance verification. See
 [Library API](./docs/LIBRARY.md).
 
@@ -362,8 +359,9 @@ exporters, managed artifact writes, and offline provenance verification. See
 | [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. |
+| [Controlled revisions](./docs/REVISIONS.md) | Image-to-image/inpaint parents, masks, fail-closed readiness, provenance, and ComfyUI bindings. |
 | [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. |
+| [Manifest reference](./docs/MANIFEST.md) | Style/asset fields, quality profiles, and generator constraints. |
 | [Mixed-provider projects](./docs/MIXED_PROVIDERS.md) | Per-style routing, provider-keyed budgets, recovery, and account commands. |
 | [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. |

package/dist/cli.d.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
-type GridConfidence = "low" | "medium" | "high";
+import { z } from 'zod';
+
+declare const GridConfidenceSchema: z.ZodEnum<["low", "medium", "high"]>;
+type GridConfidence = z.infer<typeof GridConfidenceSchema>;
 
 type TilesetFormat = "generic" | "tiled" | "godot";