pixelkiln 0.1.0

package/docs/LIBRARY.md

@@ -0,0 +1,157 @@
+# Library API
+
+Pixelkiln's public package entry point exposes the same provider-independent
+primitives used by the CLI. Use these when a build tool, editor integration, or
+game pipeline needs structured results instead of terminal output.
+
+## Load, resolve, and plan
+
+```ts
+import {
+  buildPlan,
+  loadLock,
+  loadManifest,
+  PixelLabProvider,
+  resolveSpecs,
+  summarize,
+} from "pixelkiln"
+
+const loaded = await loadManifest("pixelkiln.manifest.json")
+const provider = PixelLabProvider.forOffline()
+const specs = await resolveSpecs(loaded, { provider })
+const lock = await loadLock("pixelkiln.lock.json")
+const plan = await buildPlan(specs, lock)
+
+console.log(summarize(plan))
+if (plan.actionable.length) {
+  console.log(`${plan.cost} ${plan.costUnit} for ${plan.actionable.length} assets`)
+}
+```
+
+Planning performs no provider calls and spends nothing. Passing a provider lets
+its synchronous `supports()` and `estimate()` methods determine cost unit and
+candidate count; no credentials are required for those methods. A resolved
+spec has the fully inherited style and asset settings plus its deterministic
+spec hash.
+
+## Audit and gate generated art
+
+```ts
+import { auditStyle, evaluateAudit } from "pixelkiln"
+
+const audit = await auditStyle(loaded, specs, "neon", lock)
+const result = evaluateAudit(audit, {
+  maxDistance: 35,
+  minTransparency: 0.1,
+  maxColors: 128,
+  sigma: 1.5,
+})
+
+if (!result.safe) console.error(result.violations)
+```
+
+Audits evaluate every structural output separately. Missing and unreadable
+files make the result unsafe even when all measured assets pass. Standard
+non-interlaced greyscale, indexed, RGB, greyscale-alpha, and RGBA PNGs are
+normalized to RGBA before palette and transparency measurements.
+
+## Build sprite sheets
+
+Use `packStyle` for one lockfile style or `packSprites` for an explicit list:
+
+```ts
+import { packSprites, packStyle } from "pixelkiln"
+
+const sheet = packStyle(lock, "ground", loaded.root, {
+  outputRoles: ["tile-00", "tile-01"],
+})
+
+const shared = packSprites([
+  { id: "anvil", path: "/absolute/art/anvil.png" },
+  { id: "hammer", path: "/absolute/art/hammer.png" },
+])
+```
+
+Both return PNG bytes, a deterministic JSON-compatible atlas, and details for
+skipped files plus source hashes for provenance. Common non-interlaced PNG color
+modes and bit depths are accepted as inputs; packed output is always RGBA.
+Corrupt and interlaced inputs are skipped with a specific reason. `mountStyle`
+and `mountSprites` provide declared-cell placement when existing atlas
+coordinates must remain stable.
+
+The CLI adds a `.pixelkiln.json` companion, stages the three members together,
+restores the previous bundle after ordinary write failures, and leaves
+byte-identical members untouched. Library consumers can apply the same behavior
+with `writeManagedArtifactBundle()`, then use `verifyArtifactBundle()` to detect
+changed sources, outputs, or metadata without rendering again. The managed
+writer adopts pre-companion files only when byte-identical, refuses to replace
+unowned or manually modified output, and accepts `{ force: true }` as an
+explicit takeover. `writeArtifactBundle()` remains the lower-level transactional
+primitive for callers with their own ownership policy.
+
+Managed writes also keep a short-lived transaction journal beside the companion.
+The next invocation rolls back an interrupted pre-commit promotion or completes
+post-commit cleanup before checking ownership. Journal recovery is restricted to
+the current bundle's exact destinations and same-directory PixelKiln temp names;
+an unsafe journal or live concurrent writer is refused.
+
+## Export generated tiles
+
+```ts
+import { exportTileset } from "pixelkiln"
+
+const exported = exportTileset(lockEntry, spec, {
+  format: "tiled",
+  manifestDir: loaded.root,
+  imageName: "terrain.png",
+  columns: 8,
+})
+```
+
+The generic format preserves the complete provider rule object. Tiled and
+Godot exporters translate supported 4-edge and 4-corner rule sets and reject
+unknown semantics rather than emitting plausible but incorrect adjacency.
+See [TILES.md](./TILES.md) for file contracts and engine details.
+
+## Provider integrations
+
+`Provider` is the capability boundary. Generation pipelines accept that
+interface rather than importing PixelLab directly; `FakeProvider` implements it
+in memory for deterministic tests.
+
+```ts
+import { FakeProvider, fetchAssets, poll, submit } from "pixelkiln"
+
+const provider = new FakeProvider({ candidates: 4 })
+const lockPath = "pixelkiln.lock.json"
+await submit(provider, loaded, plan.actionable, lock, lockPath)
+await poll(provider, lock, lockPath, { specs })
+await fetchAssets(provider, specs, lock, lockPath)
+```
+
+Provider-backed operations mutate the supplied lock object; persist at the
+workflow boundary with `saveLock`. See [PROVIDERS.md](../PROVIDERS.md) before
+implementing another backend, especially its optional capabilities and cost
+units.
+
+`submit` validates adapter estimates again at the spending boundary and returns
+`{ spent, unit }` for successful submissions. Lock entries retain fractional
+costs with their unit; use `spendByUnit(lock)` for history. Use
+`measureBalanceChange(before, after)` when the provider exposes authoritative
+balance readings and keep that observed delta distinct from the estimate.
+
+## Stability and file paths
+
+- Public imports come from `pixelkiln`; internal `src/` paths are not part of
+  the package contract.
+- Manifest-relative outputs resolve from `loaded.root`, not the process's
+  current working directory.
+- New lock outputs are portable manifest-relative paths. `resolveOutputPath`
+  resolves one for file I/O; `normalizeLockOutputPaths` rebases absolute paths
+  from earlier v2 locks and marks them for persistence on the next `saveLock`.
+  Spec-aware operations derive the current destination from the manifest, so a
+  stale lock path cannot redirect a restore.
+- Lock keys use `styleId/assetId`. Structural members use stable output roles
+  such as `assetId/tile-03` in audits and atlases.
+- The lockfile is a paid-work record. Use its exported load/save/upsert helpers
+  instead of rewriting it piecemeal.

package/docs/MANIFEST.md

@@ -0,0 +1,162 @@
+# Manifest reference
+
+`pixelkiln.manifest.json` is the hand-authored, committed declaration of styles
+and assets. Paths resolve relative to the manifest file, not the current shell
+directory. The canonical machine-readable contract is
+[`schema/manifest.schema.json`](../schema/manifest.schema.json).
+
+```jsonc
+{
+  "$schema": "./node_modules/pixelkiln/schema/manifest.schema.json",
+  "name": "my-game",
+  "styles": {
+    "base": {
+      "generator": "map",
+      "promptPrefix": "Pixel-art game prop: ",
+      "promptSuffix": ", isolated, transparent background",
+      "outDir": "assets/generated/base"
+    }
+  },
+  "assets": {
+    "anvil": { "prompt": "a compact blacksmith anvil" }
+  }
+}
+```
+
+Unknown properties are rejected at every level.
+
+## Top level
+
+| Field | Required | Meaning |
+|---|---|---|
+| `$schema` | no | Editor schema URL/path. It does not affect generation identity. |
+| `name` | yes | Project/account tag namespace. |
+| `styles` | yes | Map of style id to inherited generation/output settings. |
+| `assets` | yes | Map of stable asset id to subject and per-asset overrides. |
+
+A resolved unit of work is one `styleId/assetId`. Asset ids are stable lookup
+keys, atlas frame ids, and default filenames; changing one is a data migration,
+not merely a label edit.
+
+## Style fields
+
+| Field | Type/default | Meaning |
+|---|---|---|
+| `generator` | `map` | `map`, `1dir`, `pixflux`, or `tiles`. |
+| `outDir` | string, required | Output directory relative to the manifest. |
+| `promptPrefix` | `""` | Prepended to every participating asset prompt. |
+| `promptSuffix` | `""` | Appended to every participating asset prompt. |
+| `styleImages` | `[]` | `{ "path": "..." }` reference images. Paths are manifest-relative. |
+| `size` | integer 32–256 | Square size for `1dir`; a style reference's dimensions take precedence when present. |
+| `view` | string | Provider-facing view/direction description. |
+| `outline` | string | PixelLab `map` outline setting. |
+| `shading` | string | PixelLab shading setting. |
+| `detail` | string | PixelLab detail setting. |
+| `seed` | integer | Deterministic provider seed where supported. |
+| `palette` | hex array, `[]` | Forced palette for `pixflux`; `#` is optional. |
+| `noBackground` | boolean, `true` | `pixflux` background removal. Set false for scenes/backdrops. |
+| `tileSize` | integer 16–256 | Edge length for `tiles` when no style reference supplies geometry. |
+| `tileType` | enum | `hex`, `hex_pointy`, `isometric`, `oblique`, `octagon`, or `square_topdown`. |
+| `tileView` | enum | `top-down`, `high top-down`, `low top-down`, or `side`. |
+| `tileFeature` | enum | Connectable `roads`, `tileset`, or `building` structural set. |
+| `outlineMode` | enum | `outline` or `segmentation`; segmentation avoids quilted ground seams. |
+| `mount` | object | Stable-cell sheet placement; documented below. |
+| `tags` | string array, `[]` | Tags inherited by every generated provider object in the style. |
+
+Generator-specific fields are validated before planning. Important constraints:
+
+- `1dir` is square; use style/asset `size` rather than width/height.
+- When `size` and `styleImages` are both present, PixelLab derives size from
+  the largest reference image and the declared size is advisory.
+- `map` supports arbitrary asset `width` and `height` but not forced palettes
+  or style images.
+- `pixflux` accepts a forced `palette` and returns inline output; it has no
+  style-image support.
+- `tiles` cannot combine `tileFeature` with `styleImages` because the provider
+  rejects connectable features in style-tile mode.
+
+See [generator selection](./GENERATORS.md) for costs and trade-offs.
+
+## Asset fields
+
+| Field | Type/default | Meaning |
+|---|---|---|
+| `prompt` | string, required | Subject-specific prompt. It may be empty only during existing-art onboarding. |
+| `category` | string | Human grouping metadata. |
+| `width` | integer 16–400 | Per-asset width override for arbitrary-size generators. |
+| `height` | integer 16–400 | Per-asset height override. |
+| `size` | integer 32–256 | Per-asset square size override. |
+| `file` | string | Filename/path override beneath the style output root. |
+| `styles` | string array, `[]` | If non-empty, generate this asset only in the named styles. |
+| `promptByStyle` | object, `{}` | Replace the asset prompt for specific style ids. |
+| `tags` | string array, `[]` | Asset tags combined with style tags. |
+| `cell` | `[column,row]` | Non-negative stable grid cell used by `mount`. |
+| `source` | string | Manifest-relative post-processed/hand-drawn source used by `mount` instead of lock output. |
+| `outputRole` | string | Select one member of a structural output set for mounting. |
+
+## Prompt and override resolution
+
+For each participating style/asset pair:
+
+1. Choose `promptByStyle[styleId]` when present, otherwise `prompt`.
+2. Apply the style prefix and suffix.
+3. Apply generator dimensions and generator-specific settings.
+4. Merge style and asset tags.
+5. Derive a deterministic spec hash from every setting that changes generated
+   pixels, including style-image hashes.
+
+Project root, output path, and tags are excluded from the pixel identity, so
+moving a checkout or retagging does not buy new art. Prompt, size, palette,
+seed, view, and reference-image bytes do change identity.
+
+## Stable-cell mounting
+
+```jsonc
+{
+  "styles": {
+    "ground": {
+      "generator": "tiles",
+      "outDir": "assets/tiles/src",
+      "mount": {
+        "base": "assets/tiles/spritesheet.png",
+        "cellWidth": 32,
+        "cellHeight": 32,
+        "out": "assets/tiles/spritesheet.png"
+      }
+    }
+  },
+  "assets": {
+    "rough_grass": {
+      "prompt": "unmown dark grass",
+      "cell": [6, 2],
+      "outputRole": "tile-03"
+    }
+  }
+}
+```
+
+`base` is optional; omission starts from transparency. `out` may equal `base`.
+Assets without `cell` are not mounted. Two assets cannot own one cell. A
+sprite larger than its cell is reported and skipped rather than cropped.
+`source` lets a remapped or hand-edited committed file replace generated input
+without losing the declarative placement.
+
+## Filenames and output roles
+
+The default output is `<outDir>/<category>/<assetId>.png` when `category` is
+set, otherwise `<outDir>/<assetId>.png`; `file` overrides it. Structural sets
+expand one asset into `outputs[]` with stable roles such as `tile-00` and
+filenames such as `terrain-tile-00.png`. Consumers should use roles rather than
+assuming array position. See [tiles](./TILES.md).
+
+## Validation and editor setup
+
+Regenerate the checked-in schema after changing the Zod manifest types:
+
+```bash
+npm run schema
+git diff -- schema/manifest.schema.json
+```
+
+Run `pixelkiln doctor --dry-run` for local references and project-state checks,
+then `pixelkiln plan` to see the resolved work and cost before spending.

package/docs/QUALITY.md

@@ -0,0 +1,107 @@
+# Quality and automation gates
+
+PixelKiln exposes local, deterministic checks separately from paid provider
+work. Run them before generation and in CI.
+
+## Plan gate
+
+```bash
+pixelkiln plan
+pixelkiln plan --json --check
+```
+
+Planning compares resolved specs with lock state and on-disk hashes. It calls no
+provider and reports estimated spend before work starts. `--check` succeeds only
+when every selected entry is current.
+
+Plan states include:
+
+| State | Meaning |
+|---|---|
+| `ok` | Current spec, lock, and output bytes agree. |
+| `missing` | No satisfying generation is recorded. |
+| `untracked` | Local art exists without known provider provenance. |
+| `stale` | Generation identity changed. |
+| `failed` | Provider generation failed. |
+| `recoverable` | Paid output can be fetched/restored without regeneration. |
+| `in-flight` | Submitted work has not settled. |
+| `orphaned` | Recorded output exists but current bytes differ. |
+
+## Doctor gate
+
+```bash
+pixelkiln doctor
+pixelkiln doctor --dry-run --json
+```
+
+Doctor validates schema and references, output authority/writability, lock
+recovery sources, stale jobs, plan state, API-key configuration, and live
+connectivity. `--dry-run` skips only provider connectivity. It changes nothing
+and exits nonzero for unsafe state.
+
+## Visual consistency audit
+
+```bash
+pixelkiln audit --style neon
+pixelkiln audit --style neon --json --check \
+  --max-distance 35 \
+  --min-transparency 0.10 \
+  --max-colors 128 \
+  --sigma 1.5
+```
+
+Audit measures:
+
+- palette distance from style reference images (or the set average when no
+  references exist);
+- transparent canvas share;
+- distinct opaque color count;
+- relative palette outliers by standard-deviation cutoff.
+
+Missing and unreadable files are always unsafe. Structural output sets are
+measured member-by-member with stable role-qualified ids. Standard
+non-interlaced greyscale, indexed, RGB, greyscale-alpha, and RGBA PNGs are
+normalized to RGBA before measurement.
+
+## Cache integrity gate
+
+```bash
+pixelkiln cache --check
+```
+
+This validates both local caches, including complete PNG decoding. Add
+`--prune` only in a maintenance workflow because it mutates disposable cache
+state, though it never deletes provider objects or generated destinations.
+
+## Recommended CI
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run test:docs
+npm run build
+npm run test:package
+npm audit
+
+pixelkiln doctor --dry-run
+pixelkiln plan --json --check
+pixelkiln audit --json --check --max-distance 35 --max-colors 128
+pixelkiln cache --check
+```
+
+Choose audit thresholds per project; do not copy a palette distance or color
+ceiling without checking representative art. The repository's core test suite
+uses `FakeProvider`, so money-spending stages are deterministic and offline.
+
+## JSON and exit behavior
+
+- JSON contracts are versioned/stable enough for automation where documented.
+- Partial provider pipeline failures and timeouts exit nonzero.
+- `salvage --dry-run --json` reserves stdout for JSON and sends diagnostics to
+  stderr.
+- A failed CI job should distinguish provider/output drift from repository test
+  failures rather than regenerating automatically.
+
+Generation should remain an explicit, budgeted human action; CI is for proving
+that committed declarations, state, and artifacts still agree.

package/docs/README.md

@@ -0,0 +1,44 @@
+# PixelKiln documentation
+
+PixelKiln is a manifest-driven pixel-art pipeline. Start with the workflow
+guide, then use the references for the part of the pipeline you are changing.
+This source also renders at
+[pixelkiln.griffen.codes/docs](https://pixelkiln.griffen.codes/docs).
+
+## Start here
+
+| Guide | Use it for |
+|---|---|
+| [Getting started](./GETTING_STARTED.md) | Install from a checkout, create or adopt a project, run the everyday workflow, and decide what belongs in Git. |
+| [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. |
+
+## Workflows
+
+| Guide | Use it for |
+|---|---|
+| [Generators](./GENERATORS.md) | Choose between `map`, `1dir`, `pixflux`, and `tiles`; understand measured costs and capability trade-offs. |
+| [Derived artifacts](./ARTIFACTS.md) | Pack, mount, and export; provenance companions; ownership; force takeover; transactional and crash recovery. |
+| [Recovery and account safety](./RECOVERY.md) | Restore, caches, adopt, salvage, cross-project claims, tagging, and confirmed purge. |
+| [Quality gates](./QUALITY.md) | Plan, doctor, audit, cache checks, JSON contracts, and CI usage. |
+
+## Internals and extension
+
+| Guide | Use it for |
+|---|---|
+| [Architecture](./ARCHITECTURE.md) | Manifest/lock state, provider boundary, output identity, concurrency, and durable writes. |
+| [Library API](./LIBRARY.md) | Public TypeScript imports for planning, auditing, providers, packing, exporting, and managed artifact writes. |
+| [Tiles and engine exports](./TILES.md) | Structural tile roles, provider rule preservation, generic JSON, Tiled Wang sets, and Godot terrain sets. |
+| [Measured PixelLab endpoints](./ENDPOINTS.md) | Live-account cost and payload research, endpoint recipes, limits, and unresolved API behavior. |
+| [Provider notes](../PROVIDERS.md) | Current provider seam and the next adapter work. |
+
+## Project policies
+
+- [Contributing](../CONTRIBUTING.md)
+- [Security](../SECURITY.md)
+- [Naming decision](../NAMING.md)
+
+The Markdown in this directory is the canonical documentation and ships in the
+npm package. The Next.js app in `website/` renders this source directly into
+the public documentation routes rather than maintaining a second copy.

package/docs/RECOVERY.md

@@ -0,0 +1,124 @@
+# Recovery and account safety
+
+PixelKiln separates local file recovery, account reconciliation, unclaimed-work
+review, and irreversible deletion. A failed download never needs to become a
+new paid generation, and salvage never deletes by implication.
+
+## Restore missing output
+
+```bash
+pixelkiln restore
+pixelkiln restore --style neon --only anvil
+```
+
+`restore` repairs a missing lock output from validated content-cache bytes or
+the provider URL. It does not submit generation and refuses to replace a file
+whose current bytes differ from the recorded hash.
+
+Generation and download failures are separate lock states. A CDN failure after
+successful generation becomes `download-failed`; the next `fetch` or `restore`
+retries at zero generation cost.
+
+## Local caches
+
+Two ignored caches accelerate recovery:
+
+- `.pixelkiln/cache/<sha256>.png`: content-addressed generated PNG bytes;
+- `pixelkiln.cache.json`: provider object id → remote image hash.
+
+```bash
+pixelkiln cache
+pixelkiln cache --check
+pixelkiln cache --prune
+```
+
+Cache checks verify filenames/hashes and fully decode PNG chunks, checksums,
+palettes, scanlines, and decompressed size. Pruning removes corrupt/partial and
+unreferenced content plus malformed object-hash entries. Caches are disposable
+and should not be committed.
+
+## Adopt existing art
+
+```bash
+pixelkiln init --from assets/sprites --generator map
+pixelkiln adopt --write-prompts
+```
+
+`adopt` hashes local files and provider objects, then maps exact matches into
+the lockfile. `--write-prompts` recovers the real upstream prompts. Retouched
+files remain `untracked`: provenance is unknown, but the art is not overwritten
+or automatically scheduled for paid regeneration.
+
+The account object-hash cache avoids repeated full downloads. It is pruned for
+deleted remote ids only after `adopt` has seen the provider's complete object
+list.
+
+## Salvage unclaimed work
+
+An account can contain paid objects that no current project lockfile claims.
+Inventory them before generating replacements:
+
+```bash
+pixelkiln salvage --claims ../other-project/pixelkiln.lock.json --dry-run
+pixelkiln salvage --claims ../other-project/pixelkiln.lock.json
+```
+
+On shared accounts, supply every other project lockfile with repeatable
+`--claims`. Missing claim files are errors. PixelKiln loads sibling manifests
+where available to recognize another project's style patterns; incomplete
+claims could otherwise make shipped art look unowned.
+
+Multi-style manifests group matching objects into one review session per style.
+Unmatched objects are listed separately. `--style` deliberately overrides
+grouping when a human wants to force one destination.
+
+Review verdicts:
+
+| Verdict | Effect |
+|---|---|
+| import | Download, add a manifest asset and lock entry, and recover its prompt. |
+| keep | Add `pixelkiln:keep` upstream; no local change. |
+| discard | Add `pixelkiln:discard`; does not delete. |
+
+`--dry-run --all` lists the full inventory. `--dry-run --json` writes the JSON
+array to stdout and human diagnostics to stderr for piping into `jq`.
+
+Imported ids are derived from prompts and land under `_salvaged/`; review and
+rename them before treating them as stable application ids.
+
+## Confirmed purge
+
+Deletion is a separate command:
+
+```bash
+pixelkiln purge --dry-run
+pixelkiln purge
+pixelkiln purge --yes
+```
+
+Only objects already tagged `pixelkiln:discard` are eligible. The command lists
+targets, asks interactively, and refuses non-interactive deletion without
+`--yes`. A shared account should be fully adopted/salvaged before purge.
+
+## Accept intentional spec prose changes
+
+```bash
+pixelkiln accept --style base --only anvil
+```
+
+`accept` re-baselines an intact output against the current spec hash when prose
+changed but the existing pixels are intentionally retained. It does not modify
+art and skips missing or hash-mismatched files.
+
+## Derived output recovery
+
+Pack, mount, and export bundles have a separate ownership and crash-recovery
+system based on `.pixelkiln.json` companions and transaction journals. See
+[derived artifacts](./ARTIFACTS.md).
+
+## What to commit
+
+Commit manifests, lockfiles, generated art, derived output used by the
+application, and its `.pixelkiln.json` companions. Do not commit credentials,
+`.pixelkiln/`, `pixelkiln.cache.json`, or short-lived transaction/stage/backup
+files.