pixelkiln 0.48.0 → 0.49.0

package/docs/ENDPOINTS.md

@@ -327,9 +327,14 @@ once a 1-generation re-roll exists: forty re-rolls cost one `1dir` call.
 
 Listed so the gaps are known rather than assumed away:
 
-- `inpaint`, `inpaint-v3`, `edit-image`, `edit-images-v2`, for targeted edits.
-  Both `inpaint` and `edit-image` accept `color_image`, but given that `resize`
-  accepts and ignores it, assume nothing until measured.
+- `inpaint-v3` and `edit-images-v2` back the `revision` asset shape's
+  `inpaint` and `image-to-image` modes as of this writing (see
+  [Controlled asset revisions](./REVISIONS.md)), but the wiring is built from
+  the OpenAPI spec, not a live account: no job has actually been run, so cost
+  is a borrowed estimate and a completed job's exact response shape is
+  unconfirmed. The older `inpaint` and `edit-image` (non-v2/v3) endpoints are
+  untouched by any of this. All four accept `color_image`, but given that
+  `resize` accepts and ignores it, assume nothing until measured.
 - `image-to-pixelart-pro` takes only `image` + `description`, no size fields.
   The non-Pro version is characterised above.
 - the tileset family, with schema documented above and costs unmeasured

package/docs/PIXELLAB.md

@@ -136,6 +136,8 @@ transfer, lip-sync, and skeleton-driven animation are not part of this
 adapter. Characters, their states, and their animations are the `character`
 generator, with all four creation engines (standard, v3, pro, pro-flash),
 reference sprites, concept images, style anchors, mirrors, and every
-`animate-character` control; see [Characters](./CHARACTERS.md). Use
+`animate-character` control; see [Characters](./CHARACTERS.md). Masked
+inpainting and whole-image editing are the `revision` asset shape, not the
+`character` generator; see [Controlled asset revisions](./REVISIONS.md). Use
 the [manifest reference](./MANIFEST.md) for the fields PixelKiln supports
 today.

package/docs/REVISIONS.md

@@ -5,8 +5,9 @@ The parent may be committed art, a downloaded generation, or an approved
 quality output. PixelKiln hashes the exact parent and mask bytes, blocks stale
 dependencies before submission, and records the lineage in the lockfile.
 
-The manifest and pipeline are provider-neutral. The current ComfyUI adapter is
-the first implementation. PixelLab, Retro Diffusion, and Scenario reject
+The manifest and pipeline are provider-neutral. ComfyUI and PixelLab implement
+it; PixelLab covers `image-to-image` and `inpaint`, not `outpaint` (its API
+has no canvas-expansion endpoint). Retro Diffusion and Scenario reject
 revision work during offline resolution instead of silently starting a fresh
 text-to-image job.
 
@@ -156,6 +157,34 @@ composition candidate and use the normal native-grid, palette, alpha, and human
 approval gate before shipping. See the
 [committed smoke](../benchmarks/provider-revisions/comfyui/README.md).
 
+## PixelLab
+
+PixelLab needs no bindings: `image-to-image` calls `/edit-images-v2`,
+`inpaint` calls `/inpaint-v3`, both as a plain background job polled the same
+way as every other PixelLab submission.
+
+- The mask convention is fixed, not graph-defined like ComfyUI's: white marks
+  the area to generate, black the area to preserve. There is no way to flip it.
+- `strength` has nowhere to go on `image-to-image`. PixelLab's edit endpoint
+  applies the instruction in full; declaring a strength fails the submission
+  rather than silently ignoring it.
+- The source image is sent at its own actual dimensions (`revision.sourceWidth`
+  / `sourceHeight`), not the child asset's declared `width`/`height`. Neither
+  endpoint resizes; they edit the pixels that exist.
+- `/inpaint-v3` takes 32 to 512 pixels per side; a smaller or larger source
+  is refused before any request is sent.
+- Cost is **not yet measured**. Both endpoints are documented as PixelLab's
+  "Pro" tier, so pixelkiln prices them on the same canvas-area tiers already
+  measured for `1dir` and `create-tiles-pro` (20/25/40 generations) rather than
+  guess a number — the safe direction to be wrong in, per `generationCost`'s
+  own contract. Treat this as a placeholder until a live job's `usage` is read.
+- A completed job's exact response shape is not documented for either
+  endpoint (the API's own worked example of that field is a character job's
+  shape, not an edit or inpaint job's). `pollRevision` in
+  `src/providers/pixellab.ts` reads it defensively and fails the job with a
+  named error rather than crash or guess wrong; if a live job's shape differs
+  from what it checks, that function is a one-line fix.
+
 ## Provenance and invalidation
 
 The lock entry records revision mode, parent id, parent hash, optional mask

package/package.json

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

package/skills/pixelkiln/SKILL.md

@@ -12,6 +12,10 @@ hashes.
 ## Working rules
 
 - Locate `pixelkiln.manifest.json` first. Paths are manifest-relative.
+- Give every new asset a descriptive `id` (`oak_tree`, `iron_sword`, not
+  `asset_3` or `object1`). A vague id is cheap to write and expensive the
+  moment another asset needs to reference it (`state.of`, `animation.of`,
+  `revision.from`, `mirror`) or a person asks which one it was.
 - Treat `style.extends` as a source-level variant, not a reason to copy the
   parent. Keep every child `outDir` explicit, inspect the resolved plan, and
   remember that a pixel-affecting parent edit intentionally makes children stale.

package/skills/pixelkiln/references/pixellab.md

@@ -24,6 +24,29 @@ providers, or before any PixelLab account operation.
 | `tiles` | Ground variations or connected structures | 20–40 generations |
 | `character` | A character in 4 or 8 directions, its poses (`state`), and its loops (`animation`) | 1 per standard base, 6 per pro-flash base at 64px (1 from a `reference`), 20–40 per pose, 1 per template loop per direction |
 
+`tiles` is not limited to top-down ground: `tileType` selects the projection
+(`isometric` — the API default —, `oblique`, `hex`, `hex_pointy`, `octagon`,
+or `square_topdown`), `tileSize` sets one tile's edge in pixels (16–256), and
+`tileView` sets the camera (`top-down`, `high top-down`, `low top-down`, or
+`side`). `outlineMode` chooses `outline` (a dark border per tile — right for
+tiles meant to read as discrete objects) or `segmentation` (no border, so a
+ground set tiles seamlessly instead of quilting at every cell edge — this
+alone decided whether a measured terrain set was usable). `tileFeature` asks
+for a connectable set instead of independent variations: `roads` for an
+18-configuration path set, `tileset` for a 16-tile Wang corner set — describe
+the transition itself in the prompt ("fairway grass to rough meadow"), not
+one terrain — or `building` for a floor/wall/doorway construction kit.
+Passing `styleImages` overrides `tileType`/`tileView` entirely and copies
+tile shape and size from the reference instead, the only way to land new
+tiles on an existing sheet's ground plane.
+
+Do not confuse pixelkiln's `map` generator with PixelLab's own "Map
+Workshop": `map` returns one static prop, icon, or building in a single
+generation with no scene, canvas, or placement concept. Map Workshop (scene
+composition — laying out a tile floor, placing characters and movable
+objects, inpainting sections in place, exporting the result) is a distinct
+PixelLab product surface this adapter does not model at all.
+
 A base can start from the author's own south-facing sprite (`reference` on
 the asset; standard wants it at the style's size, v3 up to 256px, pro up
 to 168px), and a standard humanoid base takes `proportions` (`chibi`,
@@ -32,16 +55,53 @@ designed from a `concept` image (up to 1024px) and follow the look of
 another generated character in the style (`styleCharacter`), which makes
 that character a dependency the way a loop's parent is.
 
+A `reference`, `concept`, or `styleCharacter` image's own canvas size sets
+the output's apparent scale, not just its content: a reference cropped or
+padded to a canvas larger than the target size reliably produces an
+oversized character next to everything else at the intended size. Match the
+reference's canvas to the base's `size` (or the other way around) before
+submitting, not after a mismatched result comes back.
+
 A v3 loop can start from a pose image (`startFrame`) or interpolate to one
 (`endFrame`), take a `subject` when the character's own description would
 mislead, and ask PixelLab to `enhancePrompt`; a template loop takes
-`outline`, `shading`, and `detail` overrides instead.
+`outline`, `shading`, and `detail` overrides instead. `keepFirstFrame`
+defaults to `true` on a v3 loop: the parent's resting pose (or `startFrame`,
+when set) becomes frame 0 for free, so a requested `frames: 6` delivers 7
+files, not 6. Account for the `+1` when checking a loop's output count or
+estimating its budget; set it `false` only when the caller will supply its
+own first frame downstream.
 
-A loop costs per direction, and a sprite facing east is the sprite facing
-west flipped. Declare the west loop and make the east one `{ "mirror":
-"bot.walk.west" }`: PixelKiln flips it locally for nothing, in the wave
-after the source lands. South and north cannot be mirrored. Eight directions
-of one loop are then 5 generations, not 8.
+A loop costs per direction, and a sprite facing one way is the sprite facing
+the opposite way flipped — this holds for the east/west pair and for both
+diagonal pairs, south-east/south-west and north-east/north-west. Declare the
+west loop and make the east one `{ "mirror": "bot.walk.west" }`: PixelKiln
+flips it locally for nothing, in the wave after the source lands. South and
+north sit on the mirror line itself, so flipping either just relabels the
+same asset, not a new one — generate those two directly. Generate south,
+south-east, east, north-east, and north, then mirror the other three: eight
+directions of one loop are then 5 generations, not 8.
+
+A loop that needs headroom for an effect — recoil, a muzzle flash, a
+projectile, anything that extends past the subject's silhouette — needs
+empty canvas space near the subject before generating; a composition with no
+margin is a common cause of a failed or clipped loop, and is worth ruling
+out before rewriting the prompt. Bigger pose changes want more frames: a
+simple loop (a walk, a static idle) reads fine at 6; a transition that
+rotates or drops the subject (a fall, a knockdown) wants 8 or more. A
+multi-stage action (windup, then attack, then recovery) is a chain of
+loops, not one long one: take the final frame of one loop as the next
+loop's `startFrame` and link them as separate manifest assets.
+
+Write the loop `prompt` (and any `subject` override) as a full descriptive
+sentence of the motion — pace, energy, what leads and what follows — rather
+than a terse label like "attack": PixelLab's own tutorials treat this as the
+single biggest lever on animation quality, on par with frame count. If an
+agent drafts the prompt from a reference image, strip any technical framing
+it invents (frame rates, frame-count ranges, export terms) before
+submitting — PixelLab is never told the target frame rate, only the frame
+count, and a stray "24fps" or "60 to 90 frames" fragment in the prompt does
+not help.
 
 In the committed environment benchmark, PixelLab followed complex building
 prompts more closely and produced broader, more separable depth bands in scenic
@@ -50,6 +110,12 @@ transparency claim, so inspect alpha on one representative result before a
 batch. Inspect scenic outputs for stray marks too: one untouched 384px attempt
 contained a generated signature-like glyph.
 
+An asset that declares `revision` against a PixelLab style calls `inpaint`
+(masked) or `image-to-image` (whole-image, no mask); `outpaint` is refused,
+since PixelLab has no canvas-expansion endpoint. Read `docs/REVISIONS.md`'s
+PixelLab section before using either — its cost is an estimate, not yet
+measured.
+
 For setup and current field constraints, use
 <https://pixelkiln.griffen.codes/docs/pixellab>. When working in the PixelKiln
 repository, `docs/PIXELLAB.md` and `docs/ENDPOINTS.md` are the canonical local