pixelkiln 0.1.0

package/docs/TILES.md

@@ -0,0 +1,118 @@
+# Tiles and engine exports
+
+PixelLab connectable output is not merely a directory of images. The response
+contains ordered `storage_urls` plus `tile_rules` describing which adjacency
+mask belongs to which image. PixelKiln preserves both pieces so downstream
+tools never have to reconstruct semantics from filenames.
+
+## Stored state
+
+A completed lock entry has role-qualified outputs in provider order and raw
+metadata under the provider id:
+
+```jsonc
+{
+  "outputs": [
+    { "path": "terrain-tile-00.png", "sha256": "…", "role": "tile-00" },
+    { "path": "terrain-tile-01.png", "sha256": "…", "role": "tile-01" }
+  ],
+  "providerMetadata": {
+    "pixellab": {
+      "tileKind": "tileset",
+      "tileRules": {
+        "rule_type": "corner",
+        "arity": 4,
+        "connectivity": "other",
+        "terrains": ["feature", "background"],
+        "tiles": { "tile_0": 0, "tile_1": 1 }
+      }
+    }
+  }
+}
+```
+
+Provider keys can contain gaps when a set includes stamp-only images. Output
+roles therefore retain the original numeric key (`tile-07`) rather than being
+renumbered by array position.
+
+## Command
+
+```bash
+pixelkiln export --style ground --only terrain --format generic
+pixelkiln export --style ground --only terrain --format tiled
+pixelkiln export --style ground --only terrain --format godot
+```
+
+`--format` defaults to `generic`. `--out dist/terrain` overrides the output
+base when exactly one entry is selected. `--columns` controls atlas columns.
+Without `--out`, files land in the style's `outDir` as
+`<asset>-tileset.<extension>`, `<asset>-tileset.png`, and
+`<asset>-tileset.pixelkiln.json`.
+
+The companion record is engine-neutral: it stores portable source paths and
+SHA-256s, export options (including raw provider rules), output hashes, and a
+canonical fingerprint. `verifyArtifactBundle()` can detect changed inputs,
+edited/missing outputs, or altered provenance offline without rebuilding the
+atlas. The project manifest and lockfile are conservative inputs, ensuring that
+newly declared or recorded tiles also make an older export stale. The TSJ/TRES
+contracts therefore remain free of PixelKiln-only fields.
+
+An existing export without a companion is adopted only when its bytes already
+match. Once tracked, a changing output must still match its recorded hash;
+manual edits stop the whole export rather than being silently replaced. Use
+`--force` only after reviewing the difference to take ownership and re-baseline
+the complete bundle.
+
+An immutable transaction journal exists only while the three files are being
+replaced. Following abrupt termination, the next export restores the old set if
+commit was incomplete, or retains the fully committed new set and removes its
+backups. Recovery will not follow journal paths outside the current bundle or
+interrupt a live writer.
+
+## Generic JSON
+
+The generic format is the lossless interchange contract:
+
+- `format: "pixelkiln-tileset"` and `version: 1`
+- atlas image, cell size, sheet size, and columns
+- one ordered tile record with atlas id, original provider `sourceIndex`, role,
+  rectangle, optional bitmask, and `stampOnly`
+- normalized rule type, arity, connectivity, terrain names, and masks
+- the complete raw provider rule object in `providerRules`, including rule
+  families a current exporter does not yet normalize
+
+Use it for custom engines, unsupported rule families, or as the input to a
+project-specific importer.
+
+## Tiled
+
+The `.tsj` export creates an image tileset and a Wang set. Tiled Wang ids are
+written in its documented order: top edge, northeast corner, right edge,
+southeast corner, bottom edge, southwest corner, left edge, northwest corner.
+
+For PixelLab corner masks, bits NW/NE/SW/SE = 3/2/1/0 are placed into the four
+corner positions. For edge masks, bits N/E/S/W = 0/1/2/3 are placed into the
+four edge positions. Terrain names come from the provider metadata; editor
+colors are deterministic display colors and do not alter the artwork.
+
+## Godot 4
+
+The `.tres` export creates a `TileSet` containing one `TileSetAtlasSource`.
+Four-corner masks use `TERRAIN_MODE_MATCH_CORNERS`; four-edge masks use
+`TERRAIN_MODE_MATCH_SIDES`. Each mask becomes the corresponding terrain peering
+bits on its atlas tile. Isometric and hex tile shapes are carried from the
+resolved manifest spec.
+
+The texture path is relative to the `.tres`, so the generated PNG and resource
+can move together inside a Godot project.
+
+## Deliberate limits
+
+- Tiled and Godot exports require every image to match the atlas cell size.
+- Six-edge hex masks remain generic-only. Their engine layouts depend on hex
+  orientation and offset conventions that the current manifest does not yet
+  declare.
+- `outline` and building-kit images absent from the rule map are stamp-only.
+  Generic export retains them; engine exporters reject a rule family whose
+  placement semantics would have to be invented.
+- Export never changes source PNGs or the lockfile.

package/examples/minimal/README.md

@@ -0,0 +1,26 @@
+# Minimal example
+
+```bash
+export PIXELLAB_API_KEY=...
+
+# Free — shows exactly what a run would cost.
+pixelkiln plan --manifest pixelkiln.manifest.json
+
+# 3 assets x 40 generations = 120, returning 16 candidates each.
+pixelkiln gen --manifest pixelkiln.manifest.json --budget 120
+```
+
+`gen` opens a contact sheet in your browser to pick among the candidates, then
+writes `out/base/tools/anvil.png` and friends, recording provenance in
+`pixelkiln.lock.json`.
+
+## Adding a variant style
+
+Add a second entry under `styles` with a different `outDir`, then:
+
+```bash
+pixelkiln gen --style neon
+```
+
+Every asset re-derives under the new style. The original files are untouched —
+styles are separate namespaces in both the output tree and the lockfile.

package/examples/minimal/pixelkiln.manifest.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "../../schema/manifest.schema.json",
+  "name": "minimal-example",
+  "styles": {
+    "base": {
+      "generator": "1dir",
+      "size": 64,
+      "view": "top-down",
+      "promptPrefix": "Game achievement icon: one centered",
+      "promptSuffix": "bold dark outline, crisp chunky pixel clusters, readable silhouette at 32px, isolated single subject, no ground plane, transparent background, no letters, no numbers",
+      "styleImages": [],
+      "outDir": "out/base",
+      "tags": ["minimal-example"]
+    }
+  },
+  "assets": {
+    "anvil": { "prompt": "a blacksmith anvil with a single bright spark", "category": "tools" },
+    "potion": { "prompt": "a round glass potion bottle with a glowing liquid", "category": "items" },
+    "compass": { "prompt": "a brass compass with a red needle", "category": "items" }
+  }
+}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "pixelkiln",
+  "version": "0.1.0",
+  "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "pixelkiln": "./bin/pixelkiln.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "pixelkiln": "tsx src/cli.ts",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --sourcemap && tsup src/cli.ts --format esm --dts --sourcemap",
+    "prepack": "npm run build",
+    "release": "semantic-release",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:docs": "node scripts/check-docs.mjs",
+    "test:package": "node scripts/smoke-package.mjs",
+    "test:watch": "vitest",
+    "schema": "tsx scripts/gen-schema.ts",
+    "website:dev": "npm run dev --prefix website",
+    "website:check": "npm run check:content --prefix website",
+    "website:lint": "npm run lint --prefix website",
+    "website:build": "npm run build --prefix website"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gfargo/pixelkiln.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gfargo/pixelkiln/issues"
+  },
+  "homepage": "https://pixelkiln.griffen.codes",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/node": "^22.10.0",
+    "semantic-release": "^25.0.9",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.10",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
+  },
+  "license": "MIT",
+  "keywords": [
+    "pixel-art",
+    "sprites",
+    "game-assets",
+    "pixellab",
+    "asset-pipeline",
+    "generative",
+    "lockfile",
+    "cli"
+  ],
+  "files": [
+    "dist",
+    "bin",
+    "schema",
+    "skills",
+    "docs",
+    "examples",
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "PROVIDERS.md",
+    "NAMING.md",
+    "LICENSE"
+  ]
+}

package/schema/manifest.schema.json

@@ -0,0 +1,255 @@
+{
+  "$ref": "#/definitions/PixelkilnManifest",
+  "definitions": {
+    "PixelkilnManifest": {
+      "type": "object",
+      "properties": {
+        "$schema": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "styles": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "generator": {
+                "type": "string",
+                "enum": [
+                  "1dir",
+                  "map",
+                  "pixflux",
+                  "tiles"
+                ],
+                "default": "map"
+              },
+              "size": {
+                "type": "integer",
+                "minimum": 32,
+                "maximum": 256
+              },
+              "view": {
+                "type": "string"
+              },
+              "promptSuffix": {
+                "type": "string",
+                "default": ""
+              },
+              "promptPrefix": {
+                "type": "string",
+                "default": ""
+              },
+              "styleImages": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "path": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "path"
+                  ],
+                  "additionalProperties": false
+                },
+                "default": []
+              },
+              "outDir": {
+                "type": "string"
+              },
+              "outline": {
+                "type": "string"
+              },
+              "shading": {
+                "type": "string"
+              },
+              "detail": {
+                "type": "string"
+              },
+              "tileSize": {
+                "type": "integer",
+                "minimum": 16,
+                "maximum": 256
+              },
+              "tileType": {
+                "type": "string",
+                "enum": [
+                  "hex",
+                  "hex_pointy",
+                  "isometric",
+                  "oblique",
+                  "octagon",
+                  "square_topdown"
+                ]
+              },
+              "tileView": {
+                "type": "string",
+                "enum": [
+                  "top-down",
+                  "high top-down",
+                  "low top-down",
+                  "side"
+                ]
+              },
+              "tileFeature": {
+                "type": "string",
+                "enum": [
+                  "roads",
+                  "tileset",
+                  "building"
+                ]
+              },
+              "outlineMode": {
+                "type": "string",
+                "enum": [
+                  "outline",
+                  "segmentation"
+                ]
+              },
+              "noBackground": {
+                "type": "boolean",
+                "default": true
+              },
+              "seed": {
+                "type": "integer"
+              },
+              "palette": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^#?[0-9a-f]{6}$"
+                },
+                "default": []
+              },
+              "mount": {
+                "type": "object",
+                "properties": {
+                  "base": {
+                    "type": "string"
+                  },
+                  "cellWidth": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  },
+                  "cellHeight": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  },
+                  "out": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "cellWidth",
+                  "cellHeight",
+                  "out"
+                ],
+                "additionalProperties": false
+              },
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "default": []
+              }
+            },
+            "required": [
+              "outDir"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "assets": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "prompt": {
+                "type": "string"
+              },
+              "category": {
+                "type": "string"
+              },
+              "width": {
+                "type": "integer",
+                "minimum": 16,
+                "maximum": 400
+              },
+              "height": {
+                "type": "integer",
+                "minimum": 16,
+                "maximum": 400
+              },
+              "size": {
+                "type": "integer",
+                "minimum": 32,
+                "maximum": 256
+              },
+              "file": {
+                "type": "string"
+              },
+              "cell": {
+                "type": "array",
+                "minItems": 2,
+                "maxItems": 2,
+                "items": [
+                  {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  {
+                    "type": "integer",
+                    "minimum": 0
+                  }
+                ]
+              },
+              "source": {
+                "type": "string"
+              },
+              "outputRole": {
+                "type": "string",
+                "minLength": 1
+              },
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "default": []
+              },
+              "styles": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "default": []
+              },
+              "promptByStyle": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "default": {}
+              }
+            },
+            "required": [
+              "prompt"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "name",
+        "styles",
+        "assets"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/skills/pixelkiln/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: pixelkiln
+description: Use PixelKiln to plan, generate, review, recover, audit, pack, and export manifest-driven pixel-art projects. Apply when a task uses the PixelKiln CLI, manifest, lockfile, or generated asset workflow; do not use for unrelated one-off image generation.
+---
+
+# PixelKiln
+
+Treat generated pixel art as build state: declared in a manifest, costed before
+submission, reviewed by a human, and recorded with exact provenance.
+
+## Working rules
+
+- Locate `pixelkiln.manifest.json` first. Paths are manifest-relative.
+- Never inspect, print, or commit provider credentials. PixelKiln can load
+  `PIXELLAB_API_KEY` from `.env.local` beside the manifest or from the current
+  working directory.
+- Run `pixelkiln doctor --dry-run` and `pixelkiln plan` before paid work. Report
+  actionable, recoverable, and estimated cost figures with their provider unit.
+- Do not regenerate recoverable work. Use `pixelkiln restore` first.
+- Submit paid work only when the user has authorized generation. Always pass an
+  explicit `--budget` no higher than the authorized estimate.
+- Leave visual selection to the local `pixelkiln pick` review page unless the
+  user explicitly provides a selection rule. Closing it applies nothing.
+- Preserve manual edits and ownership errors. Inspect the difference before any
+  `--force` operation.
+- Commit the manifest, lockfile, generated outputs, and derived artifact
+  companions. Never commit `.env.local` or `.pixelkiln/` cache data.
+
+## Choose the smallest workflow
+
+For ordinary work, prefer:
+
+```bash
+pixelkiln doctor --dry-run
+pixelkiln plan
+pixelkiln gen --budget <approved-provider-units>
+pixelkiln audit --check
+```
+
+Use the staged `submit` → `poll` → `pick` → `fetch` commands when resuming or
+debugging one phase. Use `restore` for missing bytes, `adopt` for exact matches
+already in the provider account, and `salvage` for reviewed unclaimed objects.
+Use `pack`, `mount`, or `export` only for the artifact format the project needs.
+
+PixelKiln's orchestration is provider-neutral. PixelLab is currently its only
+production and live-tested adapter; `FakeProvider` is the deterministic test
+adapter. Do not imply that other production providers already work.
+
+When working in the PixelKiln repository, consult `docs/GETTING_STARTED.md` for
+the full workflow, `docs/CLI.md` for flags, `docs/MANIFEST.md` for the schema,
+and `docs/RECOVERY.md` before account adoption, salvage, discard, or purge.

package/skills/pixelkiln/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "PixelKiln"
+  short_description: "Plan and ship provenance-safe pixel art"
+  brand_color: "#FF6B35"
+  default_prompt: "Use $pixelkiln to plan and safely produce this project's pixel-art assets."