pixelkiln 0.15.0 → 0.17.0

package/PROVIDERS.md

@@ -26,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 |
 
@@ -81,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 |
@@ -95,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

@@ -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
@@ -55,9 +55,10 @@ PixelKiln keeps the missing record:
 | Workflow | What PixelKiln provides |
 |---|---|
 | 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. |
+| Generate and review | Resumable submit/poll/pick/fetch pipeline, exact next-step hints, and 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. |
+| Recovery | Safe stale-output replacement, validated caches, durable references, and resumable paid 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 | 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. |
@@ -342,7 +343,8 @@ console.log(plan.groups, plan.actionable.length)
 ```
 
 The package also exports audit and image-regression gates, quality-profile
-inspection and refinement, lock/output helpers, provider contracts, sprite packing/mounting, tile
+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).
 
@@ -357,6 +359,7 @@ 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) | 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. |

package/dist/cli.d.ts

@@ -4,8 +4,23 @@ import { z } from 'zod';
 declare const GridConfidenceSchema: z.ZodEnum<["low", "medium", "high"]>;
 type GridConfidence = z.infer<typeof GridConfidenceSchema>;
 
+interface ReviewReadyInfo {
+    url: string;
+    keys: string[];
+}
+
 type TilesetFormat = "generic" | "tiled" | "godot";
 
+interface CliWritable {
+    isTTY?: boolean;
+    write(chunk: string): unknown;
+}
+/**
+ * Interactive readiness is progress, not command output. Keep it on stdout in
+ * a terminal, but use stderr when stdout is piped so consumers such as `tail`
+ * cannot hold the only copy of the live URL until the server exits.
+ */
+declare function announceReviewReady(info: ReviewReadyInfo, stdout?: CliWritable, stderr?: CliWritable): void;
 interface Args {
     command: string;
     manifest: string;
@@ -76,4 +91,4 @@ declare const COMMANDS: readonly ["init", "plan", "doctor", "gen", "submit", "po
  */
 declare function parseArgs(argv: string[]): Args;
 
-export { COMMANDS, parseArgs };
+export { COMMANDS, announceReviewReady, parseArgs };