pixelkiln 0.20.2 → 0.22.0

package/docs/CLI.md

@@ -100,7 +100,10 @@ finish it before polling.
 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
+parent source beside the new candidates, and a regeneration (`gen --force`)
+shows the art it would replace beside them while that file is still on disk,
+so the question is "is this better?" rather than "is this good?". A ComfyUI
+frame set appears as an
 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
@@ -207,6 +210,126 @@ when an installed provider, such as local ComfyUI, has no balance endpoint.
 Summarize lock entries by state and successful submission spend by cost unit.
 Supports `--json`; unlike units are never added together.
 
+### `gallery`
+
+Open a local, read-only gallery of everything the project has generated. Each
+lock entry is shown at integer zoom on a transparency checkerboard, grouped by
+style, with its provenance one click away: the prompt actually sent, provider
+and generator, dimensions, recorded cost, lock status and plan state, submit
+and download times, job and object ids, every output with its path, SHA-256,
+size, and on-disk status, revision lineage, the quality record (palette,
+native-grid detection, audit, named approval), the manifest asset as declared,
+and raw provider metadata.
+
+```bash
+pixelkiln gallery
+pixelkiln gallery --style environment --port 4180 --no-open
+pixelkiln gallery --json > generations.json
+```
+
+The gallery is lock-first. A lock entry the manifest no longer declares still
+appears, marked `undeclared`, so paid work is never hidden; a declared asset
+with no entry appears as a placeholder so the page also shows what has not
+been made. Search matches asset ids, prompts, job and object ids, hashes, and
+paths; chips filter by plan state, provider, and generator. Filters and sort
+live in the URL query (`?state=failed,orphaned&group=none`) and the open record
+in the hash (`#style/asset`), so a link lands on the same view. A render shows
+up to 600 cards before offering the rest, which keeps very large projects
+responsive. **Refresh** re-reads the manifest, lockfile, and disk, so the page
+can stay open while `gen` runs in another terminal. The server binds to
+localhost, serves only the files the current snapshot names, never contacts a
+provider, and never writes anything. Stop it with Ctrl+C. See the
+[Getting started guide](GETTING_STARTED.md#start-a-new-project) for a
+screenshot.
+
+`--json` prints the same snapshot to stdout without starting a server. It is
+the offline, machine-readable answer to "what has this project generated?" for
+scripts and agents; `--style` and `--only` narrow it the same way.
+
+`--edit` lets the page change *intent*: an asset's prompt (for every style or
+only the one being viewed), width, height, size, category, and tags; a style's
+prompt prefix, prompt suffix, and forced palette; and a form under each style
+to add a new asset. A style edit shows its blast radius before you save —
+how many assets it changes the request for, including assets in styles that
+`extends` this one and do not override the field themselves, and what
+regenerating all of them would cost. Editing a child style sets a value on the
+child only; clearing a field there makes it inherit again. Saving rewrites the manifest and
+nothing else — the same edit you would make in an editor — so `plan` and the
+page immediately report the asset `stale` or `missing` with its estimate, and
+generation still goes through `pixelkiln gen` with its budget and confirmation.
+The write is refused when the manifest changed on disk since the page loaded,
+and a result the manifest loader would reject never lands. Edits are accepted
+only from the page itself: the request must come from the gallery's own origin
+and carry a session token minted when the server started. Without `--edit`
+the gallery has no write route at all.
+
+```bash
+pixelkiln gallery --edit
+pixelkiln gallery --edit --workspace pixelkiln.workspace.json
+```
+
+`--budget <n|provider=n>` enables generation from the page under that session
+ceiling. It is the same `--budget` `gen` takes: one unkeyed amount when a run
+involves a single provider, or one keyed amount per provider for a mixed run,
+and nothing is queued without it. Each asset record and each style header
+gains **Generate** (for `missing`, `stale`, and `failed` work), **Regenerate**
+(for up-to-date work, as `gen --force`), and **Resume** (poll, review, and
+fetch existing provider work at no cost). Before anything is submitted a
+dialog lists every asset with its candidate count and estimate, the total per
+provider, and what the session budget still allows — the page's version of
+`gen`'s "Spend … on N asset(s)?" question. A run is then the same `submit`,
+`poll`, and `fetch` library calls `gen` makes, writing the same lockfile, so a
+terminal `plan` in another window agrees at every step. Progress appears in a
+job strip under the filters; each job keeps the log lines the CLI would have
+printed. Candidate sets stop in `review`: **Review** slides the `pick` sheet
+out over the gallery, **Apply selections** writes the lockfile and downloads
+the chosen art, and unchosen rows stay in review exactly as with `pick`. A
+regeneration's sheet shows the current art beside the candidates.
+
+**Compare** puts two to four records side by side at one shared zoom with
+their fields in rows — provider, generator, candidates, size, cost, prompt,
+dates, quality, hashes — and tints every row whose values differ. Shift-click
+cards (or use **Compare +** in a record) to build the set; the tray at the
+bottom opens it. The set lives in the URL (`?compare=a,b`), so a comparison
+can be linked like any other view. It works in the read-only gallery too.
+
+Two ceilings guard spend. The session budget is charged with each job's
+estimate up front, so two quick clicks cannot both fit under the same
+remainder, and each submission also carries the remaining ceiling as its own
+`budget`, so a provider estimate that grows between plan and submit is refused
+rather than paid. The balance preflight is the same as `gen`'s. Provider
+credentials are loaded from the project's own `.env` files and never reach the
+page; in a workspace whose projects name the same credential with different
+values, the gallery refuses to generate for the second project rather than run
+it on the first project's account — start a separate gallery for it.
+
+"How many candidates" is a style setting, because it is part of the request
+identity: Retro Diffusion, ComfyUI, and Scenario expose it as a provider option
+(`numImages`/`numOutputs`), which each style header shows and, with `--edit`,
+lets you change — every asset in the style becomes `stale`, and the header
+says how many. PixelLab's count follows the generator and size (`map` and
+`pixflux` return one image; a `1dir` style returns 4–64), so the header
+explains that instead of offering a number.
+
+```bash
+pixelkiln gallery --edit --budget 80
+pixelkiln gallery --budget pixellab=40 --budget retrodiffusion=1.25 --workspace pixelkiln.workspace.json
+```
+
+`--workspace <catalog>` shows every project the catalog registers in one
+gallery, the way `workspace status` reads them: no manifest is needed in the
+current directory, each project gets its own section and filter chip, and a
+project whose manifest or lock cannot be read is listed with its error instead
+of hiding the rest. Lock keys repeat across projects, so records are identified
+as `project:style/asset` in links and search. `--style` and `--only` apply per
+project; a project without the named ids simply shows nothing. `--json` prints
+the combined snapshot with a `workspace.projects` summary.
+
+```bash
+pixelkiln gallery --workspace pixelkiln.workspace.json
+pixelkiln gallery --workspace pixelkiln.workspace.json --style base --json
+```
+
 ### `workspace`
 
 Register sibling projects in a schema-versioned catalog file, outside any one
@@ -452,16 +575,17 @@ Print the package version. `-v` is an alias.
 | `--lock <path>` | manifest commands | Lock path; defaults beside the manifest. |
 | `--style a,b` | most workflows | Restrict styles; repeatable. |
 | `--only id1,id2` | most workflows | Restrict asset ids; repeatable. |
-| `--budget <n\|provider=n>` | submit/gen | Refuse work above this cost. Repeat `provider=n` for every provider in a mixed run; do not mix keyed and unkeyed forms. |
+| `--budget <n\|provider=n>` | submit/gen/gallery | Refuse work above this cost. Repeat `provider=n` for every provider in a mixed run; do not mix keyed and unkeyed forms. For `gallery`, the session ceiling that enables generation from the page. |
 | `--force` | gen/fetch/derived commands/recipe install/quality snapshot | Regenerate current work, replace a changed or untracked fetch destination, rebuild current quality-profile output, take ownership of modified/unowned derived output, replace changed recipe files, or replace a changed quality baseline. A refinement rebuild resets approval. |
 | `--dry-run` | supported mutating commands | Inspect without spending or mutating provider state. |
-| `--json` | plan/doctor/audit/cache/status/salvage/refine/recipe/quality | Machine-readable stdout where supported. |
+| `--json` | plan/doctor/audit/cache/status/gallery/salvage/refine/recipe/quality | Machine-readable stdout where supported. For `gallery`, prints the snapshot instead of serving it. |
 | `--check` | plan/audit/cache | Exit nonzero when selected state is unsafe. |
 | `--yes`, `-y` | confirmed operations | Skip an interactive confirmation. For `refine approve`, it records an already-completed human review; it does not replace one. |
-| `--no-open` | pick/salvage | Do not automatically open the browser. |
+| `--no-open` | pick/salvage/gallery | Do not automatically open the browser. |
+| `--edit` | gallery | Let the page change asset prompts, sizes, category, and tags, and add assets. Rewrites the manifest only; never contacts a provider or spends. |
 | `--tag` | fetch/adopt | Also push tags after the command's primary work. |
 | `--claims <paths>` | salvage | Other project lockfiles; repeatable and comma-separated. |
-| `--workspace <path>` | workspace/salvage | Workspace catalog path; defaults to `pixelkiln.workspace.json`. On salvage, derives the claim set instead of repeated `--claims`. |
+| `--workspace <path>` | workspace/salvage/gallery | Workspace catalog path; defaults to `pixelkiln.workspace.json` for `workspace`. On salvage, derives the claim set instead of repeated `--claims`; on gallery, shows every registered project. |
 | `--provider <id>` | balance/adopt/salvage/purge/workspace add | Select the account provider for a mixed manifest, or set the workspace catalog's default provider hint. |
 | `--account <label>` | workspace add | Free-form account label, e.g. distinguishing sandboxes. |
 | `--all` | salvage dry run | List every unclaimed object rather than the first 30. |
@@ -470,7 +594,7 @@ Print the package version. `-v` is an alias.
 | `--generator <name>` | init | Generator assigned to the scaffolded style. |
 | `--name <name>` | init | Project name for the scaffolded manifest. |
 | `--write-prompts` | adopt | Recover provider prompts into the manifest. |
-| `--port <n>` | pick/salvage | Local review server port; otherwise chooses a free port. |
+| `--port <n>` | pick/salvage/gallery | Local review or gallery server port; otherwise chooses a free port. |
 | `--out <path>` | pack/export/refine/recipe install/quality snapshot | Output base override, final native PNG for path-mode refine, exact recipe destination, or quality baseline path. Export requires one selected tileset. |
 | `--inputs <path>` | pack/quality snapshot | JSON input array; requires `--out`. Quality cases use `{ id, path, record?, tolerances? }`. |
 | `--columns <n>` | pack/export | Grid columns, 1–1024; default is near-square. |

package/docs/GETTING_STARTED.md

@@ -156,6 +156,15 @@ If a run stops between stages, rerun `plan`. It points `processing` work to
 `poll`, `review` work to `pick`, and `selected` or `download-failed` work to
 `fetch`; these resume existing paid work without another submission.
 
+To browse what the project has made so far, run
+[`pixelkiln gallery`](CLI.md#gallery). It serves a read-only page of every
+generation with its full record — prompt, provider, cost, hashes, lineage, and
+quality state — and can stay open while `gen` runs. With several registered
+projects, `pixelkiln gallery --workspace pixelkiln.workspace.json` shows them
+all in one page.
+
+![PixelKiln local generation gallery](../website/public/gallery-ui-showcase.jpg)
+
 ## Start from existing art
 
 Scaffold the manifest from PNGs, then reconcile exact file hashes with the

package/docs/LIBRARY.md

@@ -77,6 +77,64 @@ await requireRevisionReady(spec, lock)
 accepted modes with optional `supportsRevision(mode)`. Omission means no
 revision support and makes resolution fail offline.
 
+## Inspect every generation
+
+`buildGallerySnapshot` is the offline, serializable view behind
+`pixelkiln gallery`: every lock entry with its plan state, outputs, quality
+record, lineage, and manifest intent, plus lock entries the manifest no longer
+declares. It is built from the same sources as `buildPlan` and contacts no
+provider.
+
+```ts
+import {
+  buildGallerySnapshot,
+  loadLock,
+  loadManifest,
+  renderGallery,
+  resolveSpecs,
+  serveGallery,
+} from "pixelkiln"
+
+const loaded = await loadManifest("pixelkiln.manifest.json")
+const specs = await resolveSpecs(loaded)
+const lock = await loadLock("pixelkiln.lock.json")
+const { snapshot, media } = await buildGallerySnapshot({
+  loaded, specs, lock, lockPath: "pixelkiln.lock.json",
+})
+
+for (const item of snapshot.items) {
+  console.log(item.key, item.state, item.cost, item.costUnit, item.outputs.map((o) => o.sha256))
+}
+```
+
+`buildWorkspaceGallerySnapshot({ workspace, workspacePath })` does the same
+for every project a workspace catalog registers, namespacing item ids as
+`project:style/asset` and listing an unreadable project's error under
+`snapshot.workspace.projects` instead of throwing.
+
+`renderGallery(snapshot)` returns the self-contained HTML page, and
+`serveGallery({ load })` runs the localhost server; `load` is called again for
+every page load and `/api/gallery.json` request, and `media` is the exact
+allowlist of files the server will read. Output URLs inside the snapshot are
+only meaningful while that server runs.
+
+Passing `edit: createGalleryEditHandler({ manifestFor, reload })` adds the one
+write route behind `pixelkiln gallery --edit`. `applyManifestEdit(path, edit)`
+is the underlying primitive: it patches the raw manifest JSON, preserves the
+file's indentation, refuses to write when the file's hash no longer matches
+`expectedSha256` (`ManifestDriftError`), and validates the result through
+`loadManifest` and `resolveSpecs` before the rename (`ManifestEditError`).
+It never touches the lockfile or a provider.
+
+`createGenerateHandlers({ loadProject, providerFor, budget, reload })` is the
+generation side of `pixelkiln gallery --budget`: `start` validates a request
+against `buildPlan` and the session budget and runs `submit`, `poll`, and
+`fetchAssets` as a background job; `status` reports jobs and spend; `review`
+and `applyReview` host the `pick` sheet for a job's waiting keys. The sheet
+itself comes from `prepareReview`, which `runPicker` also uses: it gathers the
+candidate groups, the local files the sheet may load, and the apply step,
+without an HTTP server of its own.
+
 ## Audit and gate generated art
 
 ```ts

package/package.json

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

package/skills/pixelkiln/SKILL.md

@@ -27,6 +27,11 @@ hashes.
   pass one `--budget provider=amount` ceiling for every paid provider in the plan.
 - Leave visual selection to the local `pixelkiln pick` review page unless the
   user explicitly provides a selection rule. Closing it applies nothing.
+- To answer "what has this project generated?", use `pixelkiln gallery --json`
+  for the offline provenance snapshot, or open `pixelkiln gallery` for the
+  person to browse it. Both are read-only and contact no provider. Leave
+  `gallery --edit` and `gallery --budget` to the person: an agent changes the
+  manifest directly and spends only through `gen` with an explicit `--budget`.
 - When a selected style declares `quality`, run manifest-mode `pixelkiln refine`
   after its source is accepted and downloaded. Read the quality reference below.
   Do not copy manifest-owned palette, path, interpreter, or threshold settings