pixelkiln 0.20.0 → 0.20.2

package/docs/AGENTS.md

@@ -29,7 +29,8 @@ With the skill loaded, an agent should:
 5. Pass an explicit `--budget` within the amount the user authorized; use one
    `provider=amount` ceiling for every paid provider in a mixed run.
 6. Leave artwork selection in the local `pick` page unless the user gives a
-   specific selection rule.
+   specific selection rule. Treat a ComfyUI frame set as one choice. Never keep
+   only its best-looking members.
 7. When a style declares `quality`, run manifest-mode `pixelkiln refine`; its
    `fixerPython` can pin the project-local interpreter. Leave
    approval to a named human reviewing the exact PNG, and require `refine check`

package/docs/ARCHITECTURE.md

@@ -111,9 +111,15 @@ plan → submit → poll → pick (when needed) → fetch
                     └──────── structural/inline outputs ────────┘
 ```
 
-Remote ids are saved immediately after submission. Generation and download
-failures remain separate, so paid work with a temporary CDN failure is
-recoverable at zero generation cost. Each stage can be rerun independently;
+Remote ids are saved immediately after submission. Providers that need several
+requests for one asset receive a checkpoint callback. Each accepted remote id
+is written before the next request begins. An incomplete checkpoint remains
+submit-actionable; a complete checkpoint is safe to poll even if the provider
+is interrupted before returning. Checkpoints are reused only when provider,
+generator, and resolved spec hash still match.
+
+Generation and download failures remain separate, so paid work with a temporary
+CDN failure is recoverable at zero generation cost. Each stage can be rerun independently;
 `gen` is only their everyday orchestration. Planning maps current `processing`,
 `review`, and `selected`/`download-failed` entries to `poll`, `pick`, and
 `fetch`, respectively.
@@ -200,6 +206,8 @@ uploads manifest-owned PNG/JPEG inputs by content hash, submits an input-bound
 clone, polls local history, and stores portable `comfyui://` output references
 so a lockfile does not retain a workstation hostname or input path. It supports
 `map` candidates and atomic `frames` sets from one still-image output node.
+Each accepted frame prompt is checkpointed in the lockfile, so a retry resumes
+at the first unsubmitted frame instead of queuing the whole set again.
 Frame-set transport, ordered review/fetch, shared-palette refinement,
 step/phase verification, approval, and packing have deterministic integration
 coverage. Live Apple MPS runs cover a small Stable

package/docs/CLI.md

@@ -83,13 +83,17 @@ step. It does not run or approve that step on the user's behalf.
 Queue selected missing/stale generation work without polling it. Enforces the
 provider spacing and concurrency limits, validates estimates at the spending
 boundary, and saves each remote id immediately. Revision inputs are rechecked
-after any queue wait and before a provider request begins.
+after any queue wait and before a provider request begins. For a provider that
+needs several requests per asset, an unchanged incomplete checkpoint resumes
+without repeating requests the provider already accepted.
 
 ### `poll`
 
 Advance submitted jobs to completed, failed, or selection-ready states. It can
 be rerun safely after an interrupted session. When work settles in another
 stage, the command prints the exact next command instead of ending silently.
+An incomplete multi-request checkpoint stays blocked here; rerun `submit` to
+finish it before polling.
 
 ### `pick`
 
@@ -97,8 +101,10 @@ Open the local candidate-review UI for jobs with alternatives. The page keeps
 native aspect ratios, uses exact integer zoom for small art, fits large work,
 and centers the decision surface on wide displays. A revision row shows its
 parent source beside the new candidates. A ComfyUI frame set appears as an
-animated ordered strip and is accepted or left unresolved as a unit. Arrow keys navigate, Enter
-selects, 1–9 choose directly, and 0 leaves a row unresolved. Only rows submitted
+animated ordered strip and is accepted or left unresolved as a unit. Its preview
+can be paused, starts paused when reduced motion is enabled, and stops while it
+is offscreen. Arrow keys navigate, Enter selects, 1–9 choose directly, and 0
+leaves a row unresolved. Only rows submitted
 with **Apply selections** are written to the lockfile. Closing the window applies
 nothing. See the [Getting started guide](GETTING_STARTED.md#start-a-new-project)
 for a screenshot of the interface.

package/docs/COMFYUI.md

@@ -219,8 +219,12 @@ The frame count comes from the array, so it cannot disagree with a separate
 count field.
 
 PixelKiln submits one still workflow per value but tracks the result as one
-asset. A partial completion remains in progress. The review page shows an
-animated loop and ordered strip; accepting any frame accepts the whole set.
+asset. After ComfyUI accepts a prompt, PixelKiln saves its id before submitting
+the next frame. An interrupted retry continues at the first missing frame. A
+changed spec starts a fresh set. Incomplete sets cannot be polled into review,
+and one failed render rejects the complete set while retaining every submitted
+prompt id for diagnosis. The review page shows an animated loop and ordered
+strip; accepting any frame accepts the whole set.
 Fetch writes `hero-idle-frame-00.png`, `hero-idle-frame-01.png`, and so on.
 `pack` already turns those role-stable files into a sprite sheet and atlas.
 
@@ -627,8 +631,8 @@ that GPU time, electricity, hosted hardware, or model licenses are free.
 
 When `numImages` is greater than one, `pixelkiln pick` opens the same local
 candidate review used by hosted providers. A `frames` job always opens an
-ordered, animated whole-set review. The lockfile stores the ComfyUI
-prompt ID, output node, workflow hash, and selected output. Durable source
+ordered, animated whole-set review. The lockfile stores every accepted ComfyUI
+prompt id, the expected frame count, output node, workflow hash, and selected output. Durable source
 references use `comfyui://` rather than embedding a workstation hostname.
 `pixelkiln restore` first uses the validated local content cache, then resolves
 the portable reference against the current `COMFYUI_BASE_URL`.

package/docs/ENDPOINTS.md

@@ -121,7 +121,7 @@ Measured on one 64×64 riso badge with an exact 4-colour palette
 | `resize` → 32px | 38 | 0.57 | cream+rust came back **gold** |
 | `image-to-pixelart` → 32px | **455** | **0.00** | opaque grey background |
 
-**`remove-background` is a de-fringe pass, not just a matte.** It removed the
+**`remove-background` also de-fringes.** It removed the
 scattered sage-green speckles around the badge outline and left the three real
 inks untouched. Colour count went *down*, transparency went *up*. It is the one
 utility safe to run on palette-locked art.

package/docs/GENERATORS.md

@@ -148,8 +148,10 @@ packaging input.
 
 Keep a fixed seed for identity, or opt into a deterministic `seedStep`. Use a
 quality profile so every frame shares one palette and must agree on detected
-native grid step and phase. The review page animates the sequence and shows the
-ordered strip. After approval, `pack` emits the sprite sheet and stable
+native grid step and phase. The review page animates the sequence, shows the
+ordered strip, and lets the reviewer pause playback. It starts paused when the
+system requests reduced motion and stops while it is offscreen. After approval,
+`pack` emits the sprite sheet and stable
 `asset/frame-XX` atlas ids. See
 [Set up ComfyUI](./COMFYUI.md#generate-an-ordered-frame-set).
 

package/docs/LIBRARY.md

@@ -57,8 +57,8 @@ and optional strength. Paths are excluded from the hash; input bytes are not.
 
 `resumeActions` groups current paid-work states into `poll`, `pick`, and
 `fetch`. It ignores stale specs and entries missing the remote id needed by
-their stage, so integrations can offer safe continuation without implying that
-a new submission is required.
+their stage. It also excludes incomplete multi-request checkpoints; those
+remain actionable in `buildPlan` and must return through `submit`.
 
 For custom orchestration, inspect the dependency gate directly:
 
@@ -284,6 +284,14 @@ every byte or scalar that can change provider output and must exclude
 machine-local paths or credentials. Providers that omit the hook fail closed
 when an asset declares non-empty `providerInputs`.
 
+`Provider.submit` receives an optional third `SubmitContext` argument. A custom
+provider that needs several remote mutations for one asset should call
+`await context.checkpoint({ jobId, metadata, complete })` after each accepted
+mutation and before starting the next one. PixelKiln persists that checkpoint
+atomically. On an unchanged retry, `previousJobId` and `previousMetadata` let
+the provider continue from the first missing request. Set `complete: true` only
+when the returned job id is safe to poll as the complete asset.
+
 These low-level operations intentionally accept one provider. A mixed-provider
 caller should partition specs and plan items by `spec.provider`, instantiate
 each adapter independently, and preserve the provider recorded on a lock entry

package/docs/RECOVERY.md

@@ -23,7 +23,8 @@ Use the lock state rather than guessing which stage to rerun:
 
 | State | Safe next command |
 |---|---|
-| `pending` or `processing` | `pixelkiln poll` |
+| incomplete submission checkpoint | `pixelkiln submit` |
+| complete `pending` or `processing` submission | `pixelkiln poll` |
 | `review` | `pixelkiln pick` |
 | `selected` or `download-failed` | `pixelkiln fetch` |
 | downloaded output is missing | `pixelkiln restore` |
@@ -36,6 +37,14 @@ still refused; after inspecting it, `pixelkiln fetch --force` explicitly lets
 the new result take ownership. This also recovers interrupted jobs created by
 older PixelKiln versions that could not retain the prior output hash.
 
+ComfyUI frame sets submit one prompt per frame. PixelKiln saves the compound
+job after every accepted prompt, before asking ComfyUI to queue the next one.
+If submission stops halfway through, `plan` reports the saved checkpoint and
+`pixelkiln submit` continues at the first missing frame. `poll` will not advance
+an incomplete set into review. A changed prompt, workflow, input image, seed
+schedule, or other spec identity starts a fresh set instead of appending to old
+prompt ids.
+
 Provider adapters should keep expiring signed result URLs transient and store a
 provider-neutral reference that can refresh them. Once ingestion succeeds,
 PixelKiln removes credential-bearing URLs, inline data URLs, and local file URLs

package/docs/REVISIONS.md

@@ -66,8 +66,8 @@ An inpaint revision also declares a manifest-relative mask:
 ```
 
 The mask must be a readable PNG. When the parent exists during planning, the
-mask must have the same dimensions. Mask meaning—white edits or black
-edits—belongs to the ComfyUI graph, so test the graph in ComfyUI before running
+mask must have the same dimensions. The ComfyUI graph decides whether white or
+black pixels mark edits, so test the graph in ComfyUI before running
 it through PixelKiln. The mask bytes and parent bytes both participate in the
 child spec hash.
 

package/package.json

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