pixelkiln 0.65.0 → 0.66.0

package/docs/CHARACTERS.md

@@ -120,6 +120,16 @@ is read again at submit time and refused if it changed since `plan`.
 States, animations, and mirrors take their look from their parent and
 cannot carry a reference.
 
+A `pro-flash` base's reference can be an image PixelKiln drew with the
+[`imageProFlash`](./GENERATORS.md#imageproflash) generator: point `reference`
+at that asset's downloaded file. When the file is byte-for-byte the output of
+an `imageProFlash` lock entry, submit sends PixelLab that image's
+`source_image_id` instead of uploading the same pixels, and the character is
+drawn from the exact image PixelLab already holds. The price is the same
+either way (the rotations only); the difference is that nothing is
+re-encoded. Generate and fetch the still before planning the character, so
+the file exists. An `objectPro` base's reference is handled the same way.
+
 ### Concept images and style anchors (pro)
 
 The pro engine has two more ways in. `concept` on a base names a concept

package/docs/GENERATORS.md

@@ -17,6 +17,7 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 | A character facing 4 or 8 directions, its poses, and its animations | `character` | 1 per base (standard), 20–40 per pose, 1 per template loop | one set of directions, or one ordered loop |
 | UI chrome — panels, buttons, health bars, toolbars | `uiAsset` | 20 generations (measured once, at 256x192) | 1 composited image |
 | One UI element from a description, 16px and up, optionally guided by a concept image | `uiElement` | 20–40 generations (unmeasured) | 1 image |
+| A styled still on the Pro Flash model, or the south sprite a Pro Flash character will rotate | `imageProFlash` | 5–9 generations (PixelLab's provisional quote) | 1 image |
 
 Start with `map` unless a required capability points elsewhere. Forty `map`
 re-rolls cost the same as one 64×64 `1dir` call.
@@ -404,6 +405,49 @@ price at an area well above where `1dir`/`tiles` would bill the ceiling.
 Left as an over-read for `--budget` until a second size is measured; see
 [ENDPOINTS.md](./ENDPOINTS.md) for the full writeup.
 
+## `imageProFlash`
+
+`imageProFlash` wraps PixelLab's `/create-image-pro-flash`: one native
+pixel-art image on the Pro Flash model, the same model the `character` and
+`objectPro` `pro-flash` engines draw with, as a plain still. It sits between
+`pixflux`/`map` (1 generation, no style reference) and `imagePro` (a flat 40):
+
+```jsonc
+{
+  "styles": {
+    "stills": {
+      "generator": "imageProFlash",
+      "styleImages": [{ "path": "refs/house-style.png" }],
+      "styleTraits": { "palette": true, "outline": true, "detail": false, "shading": true },
+      "outDir": "art/stills"
+    }
+  },
+  "assets": {
+    "knight": { "prompt": "a knight in blue armor, facing the viewer", "width": 64, "height": 64 }
+  }
+}
+```
+
+- Sizes run 16 to 256 per side in multiples of 4, and can be non-square.
+  PixelLab's native sizes (24, 32, 32×48, 64, 96×64, 96) are its most
+  reliable; other sizes are its "custom (beta)" range.
+- One `styleImages` entry is the style image, and `styleTraits` choose what
+  it lends (palette, outline, detail, shading; each on by default), the same
+  switches a `pro-flash` character base takes. Traits without a style image
+  are refused.
+- One call returns one image, recorded straight away. The lock also records
+  PixelLab's `image_id` and `source_image_id` for it: a Pro Flash `character`
+  or `objectPro` base whose `reference` is this image's downloaded file
+  reuses it by that id instead of uploading the same pixels again (see
+  [Characters](./CHARACTERS.md#starting-from-your-own-sprite)).
+- **Cost:** 5 generations up to 96px on the longer side, 6 up to 208px, 9
+  beyond, from PixelLab's own `/pro-flash/cost` quotes, which PixelLab calls
+  provisional. The billed amount on the finished job is what the lock keeps.
+
+The same model also edits and inpaints: `"engine": "pro-flash"` on an
+`image-to-image` or `inpaint` revision; see
+[Controlled asset revisions](./REVISIONS.md#pixellab).
+
 ## `uiElement`
 
 `uiElement` wraps PixelLab's `/generate-ui-v2` ("Generate UI (Pro)"): one UI

package/docs/MANIFEST.md

@@ -116,7 +116,7 @@ One asset using the fields most projects reach for:
 |---|---|---|
 | `extends` | style id | Optional parent style. The child inherits resolved settings but must declare its own `outDir`. |
 | `provider` | top-level default | Provider registry id for this style. Assets cannot override it. |
-| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, `terrain`, `isometricTile`, `imagePro`, `character`, `objectPro`, `uiAsset`, `uiElement`, or provider-specific `animation`/`frames`. See [GENERATORS.md](./GENERATORS.md). |
+| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, `terrain`, `isometricTile`, `imagePro`, `character`, `objectPro`, `uiAsset`, `uiElement`, `imageProFlash`, or provider-specific `animation`/`frames`. See [GENERATORS.md](./GENERATORS.md). |
 | `outDir` | string, required | Output directory relative to the manifest. |
 | `promptPrefix` | `""` | Prepended to every participating asset prompt. |
 | `promptSuffix` | `""` | Appended to every participating asset prompt. |
@@ -144,7 +144,7 @@ One asset using the fields most projects reach for:
 | `isometric` | `false` | `character` only. Draw `standard` bases and every loop in isometric view. |
 | `enhancePrompt` | `false` | `character` only, `v3` bases. Let PixelLab expand the prompt into a fuller one before drawing. |
 | `styleCharacter` | | `character` only, `pro` bases. The asset id of a generated 8-direction character in this style whose look bases drawn from text or a concept follow. An asset may override it. |
-| `styleTraits` | all true | `character` only, `pro-flash` bases with a style image. `{ palette, outline, detail, shading }` booleans: which traits the style image lends. |
+| `styleTraits` | all true | `character` `pro-flash` bases and `imageProFlash` styles, with a style image. `{ palette, outline, detail, shading }` booleans: which traits the style image lends. |
 | `mount` | object | Stable-cell sheet placement; documented below. |
 | `quality` | object | Optional native-grid, final-palette, and human-approval contract; documented below. |
 | `tags` | string array, `[]` | Tags inherited by every generated provider object in the style. |
@@ -481,6 +481,7 @@ their own page: [Characters](./CHARACTERS.md) and
 | `lastFrame` | string | `animate`/`animate-pixminimax`: manifest-relative image pinning where the motion ends, turning an open-ended animation into an interpolation. `interpolate`: required, the ending keyframe (the parent is the start); it must match the parent's size. |
 | `direction` | enum | `animate-pixminimax` only. The sprite's facing, used only alongside `enhancePrompt`. |
 | `enhancePrompt` | boolean | `animate`/`animate-pixminimax` only. Lets the provider expand the prompt into a fuller motion description first, for an extra documented +0.05-generation surcharge. |
+| `engine` | enum | `image-to-image`/`inpaint` only. `pro-flash` draws the edit with PixelLab's Pro Flash edit or inpaint endpoint instead of the default Pro one: 5–9 generations instead of 20–40, 32 to 256px per side in multiples of 4, no `strength`. Omit for the default. |
 
 The parent may use committed `source`, downloaded generated output, or a
 current approved quality output. Parent and mask hashes participate in the

package/docs/REVISIONS.md

@@ -399,6 +399,19 @@ approval gate before shipping. See the
 
 ## PixelLab
 
+`"engine": "pro-flash"` on an `image-to-image` or `inpaint` revision sends it to
+PixelLab's Pro Flash tier instead: `/edit-image-pro-flash` (a text edit at the
+source's own size; the canvas never grows) or `/inpaint-image-pro-flash`
+(replaces only the mask's white pixels and keeps the rest exactly). It is the
+same model the `imageProFlash` generator and the `pro-flash` character engine
+use, priced on the same provisional Pro Flash tier (5 generations up to 96px,
+6 up to 208px, 9 beyond) instead of the 20–40 of the default Pro endpoints.
+Sources must be 32 to 256px per side in multiples of 4; `strength` is refused,
+since neither endpoint has one. The finished job is read the same way as the
+default endpoints'. PixelLab also offers reference-image edits, a
+`context_image` around an inpaint, and inpaint output layers; none is modeled
+yet.
+
 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. `reduce-colors` calls `/reduce-colors`

package/package.json

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

package/schema/manifest.schema.json

@@ -46,7 +46,8 @@
                       "isometricTile",
                       "objectPro",
                       "uiAsset",
-                      "uiElement"
+                      "uiElement",
+                      "imageProFlash"
                     ],
                     "default": "map"
                   },
@@ -503,7 +504,8 @@
                       "isometricTile",
                       "objectPro",
                       "uiAsset",
-                      "uiElement"
+                      "uiElement",
+                      "imageProFlash"
                     ],
                     "default": "map"
                   },
@@ -1079,6 +1081,12 @@
                   },
                   "enhancePrompt": {
                     "type": "boolean"
+                  },
+                  "engine": {
+                    "type": "string",
+                    "enum": [
+                      "pro-flash"
+                    ]
                   }
                 },
                 "required": [

package/schema/recipe.schema.json

@@ -121,7 +121,8 @@
                 "isometricTile",
                 "objectPro",
                 "uiAsset",
-                "uiElement"
+                "uiElement",
+                "imageProFlash"
               ],
               "default": "map"
             },

package/skills/pixelkiln/references/pixellab-roadmap.md

@@ -326,12 +326,15 @@ quote/identity lookup — not billed):**
   exactly, reassuring cross-validation of the quote endpoint even though it
   is a quote, not a bill.
 
-Not modeled at all today: pixelkiln's `imagePro` generator and the `revision`
-asset shape's `image-to-image`/`inpaint` modes only ever call the non-Flash
-endpoints (`generate-image-v2`, `edit-images-v2`, `inpaint-v3`). Adding Pro
-Flash would mean a new generator (or a model/engine choice on the existing
-ones) plus a new inpaint `outputMethod` field and the `context_image`
-mechanism — real, scoped work, not a docs fix.
+**Now modeled, in part:** the `imageProFlash` generator wraps `create`
+(style image + `styleTraits`, 16–256px in multiples of 4), and a revision's
+`"engine": "pro-flash"` sends `image-to-image` to `edit` (text method) and
+`inpaint` to `inpaint`. A still's `source_image_id` is recorded and reused
+when a Pro Flash character or object base's `reference` is that still's exact
+file (issue #145). Still unmodeled: `edit`'s `"reference"` method, the
+`use_color_palette_correction` flag, inpaint's `output_method` choice and the
+`context_image` + `bounding_box` mechanism. Costs use the provisional quotes
+above; none has been billed live yet.
 
 ## Map Workshop (scene composition)
 

package/skills/pixelkiln/references/pixellab.md

@@ -27,6 +27,7 @@ providers, or before any PixelLab account operation.
 | `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 |
 | `uiAsset` | A UI panel, button, health bar, or other chrome, from precise `pieces` and/or named `elements` | **20 generations, measured once** (256×192); the borrowed canvas-tier estimate still predicts 40 |
 | `uiElement` | One UI element (button, slot, bar, dialogue box) from the prompt, 16px and up, with an optional concept image | 20–40 generations, **unmeasured** |
+| `imageProFlash` | A styled still on the Pro Flash model (style image + `styleTraits`), 16–256px in multiples of 4; also the natural source for a Pro Flash character's south sprite | 5–9 generations, PixelLab's provisional quote |
 
 `tiles` is not limited to top-down ground: `tileType` selects the projection
 (`isometric` — the API default —, `oblique`, `hex`, `hex_pointy`, `octagon`,
@@ -258,6 +259,15 @@ widgets under `uiAsset`'s 192px floor. Unmeasured: the plan borrows the
 20/25/40 canvas tiers, and the completed job's shape has not been observed
 live.
 
+`imageProFlash` wraps `/create-image-pro-flash`, the Pro Flash model as a plain
+still: priced 5 up to 96px, 6 up to 208px, 9 beyond (PixelLab's own
+provisional `/pro-flash/cost` quotes). Its lock entry keeps PixelLab's
+`source_image_id`; a Pro Flash character or object base whose `reference` is
+byte-for-byte that still's file is sent the id instead of the upload (same
+price, no re-encode). The same model edits and inpaints through a revision's
+`"engine": "pro-flash"` (`image-to-image`/`inpaint` only, 32–256px in multiples
+of 4, no `strength`), at the Pro Flash tier instead of the Pro endpoints' 20–40.
+
 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