pixelkiln 0.67.0 → 0.68.1

package/PROVIDERS.md

@@ -57,19 +57,20 @@ the providers offer directly.
 | Decision | PixelLab | Retro Diffusion |
 |---|---|---|
 | Best fit today | Existing PixelKiln projects, account reconciliation, and live-tested generation | Native pixel-art styles, USD budgets, animation, and alternate tileset workflows |
-| PixelKiln generators | `map`, `pixflux`, `1dir`, `tiles`, `character` | `map` and `pixflux` stills, `tiles`, `animation` |
-| Output | PNG stills, candidates, and structural tile members | PNG stills/tiles/spritesheets or animated GIF |
+| PixelKiln generators | `map`, `pixflux`, `1dir`, `imagePro`, `imageProFlash`, `tiles`, `terrain`, `isometricTile`, `character`, `objectPro`, `uiAsset`, `uiElement` | `map` and `pixflux` stills, `tiles`, `animation` |
+| Output | PNG stills, candidates, structural tile members, and ordered frame sets | PNG stills/tiles/spritesheets or animated GIF |
 | Candidate review | Yes; count varies by generator and size | Yes for 1–16 still candidates; animations and tilesets currently use one result |
-| References | `1dir` and tile style modes | Up to nine for supported RD Pro/user still styles; constrained inputs for animation and tiles |
+| References | `1dir` and tile style modes; a character or `objectPro` reference sprite; a `pro` character concept image; one `imageProFlash` style image; one `uiElement` concept image | Up to nine for supported RD Pro/user still styles; constrained inputs for animation and tiles |
 | Cost model | Subscription generations | Prepaid USD balance |
 | Cost safety | Offline estimate plus hard generation budget | Offline estimate, hard USD budget, then a free authoritative quote before submission |
 | Account lifecycle | Balance, list, adopt, salvage, tag, and confirmed purge | Balance only in the current adapter |
 | Live confidence | Full paid generation workflows exercised | RD Fast and RD Plus single-candidate stills exercised end to end; multi-candidate, tileset, GIF, and spritesheet runs pending |
 
 Choose PixelLab when mature account-object recovery and reconciliation matter,
-or when the measured one-generation `map`/`pixflux` routes fit the work. Choose
-Retro Diffusion when a native animation or spritesheet is required, an RD style
-is the desired look, or a USD quote is easier to budget. For a production batch,
+when the measured one-generation `map`/`pixflux` routes fit the work, or when an
+animation belongs to a character, an object, or an existing image. Choose
+Retro Diffusion when a GIF or spritesheet from one prompt fits, an RD style is
+the desired look, or a USD quote is easier to budget. For a production batch,
 run one representative asset through the selected provider before expanding the
 scope.
 
@@ -96,9 +97,12 @@ the same graph and still differ because their checkpoint bytes, custom nodes,
 or sampler settings differ. Commit the workflow and record the model stack used
 to test it.
 
-The revision manifest and dependency gate are provider-neutral, but ComfyUI is
-the only built-in adapter that currently opts in. PixelLab, Retro Diffusion,
-and Scenario reject revision assets offline. See
+The revision manifest and dependency gate are provider-neutral. ComfyUI and
+PixelLab opt in; Retro Diffusion and Scenario reject revision assets offline.
+PixelLab covers `image-to-image`, `inpaint`, `reduce-colors`,
+`correct-pixelart`, `animate`, `animate-pixminimax`, `animate-skeleton`,
+`interpolate`, and `edit-animation`, but not `outpaint`. ComfyUI covers the
+single-image modes through its workflow bindings. See
 [Controlled asset revisions](./docs/REVISIONS.md) before using the bundled
 square image-to-image graph.
 
@@ -131,7 +135,7 @@ background. That distinction matters more than raw canvas size.
 | Asset type | PixelLab | Retro Diffusion | ComfyUI | Scenario |
 |---|---|---|---|---|
 | Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. | The live BFL smoke produced a readable 512px keep, but it was opaque and used 19,619 colors. Use that profile for concepts or refinement input, not a finished limited-palette asset. A project-specific model may improve consistency but needs its own smoke. |
-| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene. Current PixelKiln routes top out at 400×400. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | The BFL profile accepts canvases up to 2048px, but no Scenario scenic brief has passed the shared benchmark. Treat that as model-canvas capacity, not native pixel resolution. Start with one 512px concept before raising size or steps. |
+| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene; both top out at 400×400. `imagePro` reaches 792 wide or 688 tall for a flat 40 generations. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | The BFL profile accepts canvases up to 2048px, but no Scenario scenic brief has passed the shared benchmark. Treat that as model-canvas capacity, not native pixel resolution. Start with one 512px concept before raising size or steps. |
 | Style consistency across a set | `1dir` accepts a style reference and returns size-dependent candidates, but it is more expensive and capped at the square-object range. | RD Pro accepts up to nine references and has stronger prompt following, but its common styles top out at 256×256 and cost $0.18 per image. Environment-specific RD Plus styles trade references for a larger 384px canvas. | LoRAs, reference adapters, ControlNet, and shared latent settings can live in the committed workflow. Reproducibility also depends on external model and custom-node versions. | Scenario's project models and LoRAs are the main reason to use it for a set. PixelKiln can pin the model ID and parameters, but its first live run covers only the public BFL profile. |
 | Very large final scene | Generate reusable objects, terrain, and background layers separately; assemble them deterministically and integer-upscale the result. | Use the same layered approach. The API has a 512px overall ceiling, but the useful environment and scene-object styles currently cap at 384px. | The graph can tile, upscale, or composite beyond hosted-provider limits, but memory and seam quality become workflow concerns. Prefer reusable layers unless the scene truly needs one render. | Scenario can request a larger raster from a compatible model, but the same rule applies: generate reusable layers at their useful native detail, compose at 1×, and integer-upscale only the final scene. |
 
@@ -194,18 +198,29 @@ not share one runtime.
 The services use different billing units, so PixelKiln never adds their costs
 together.
 
-PixelLab figures below are measurements from the endpoints PixelKiln currently
-uses; they are not a conversion to dollars:
+PixelLab figures below come from the endpoints PixelKiln currently uses. Rows
+marked unmeasured or quoted are `plan` estimates, not bills. None is a
+conversion to dollars:
 
-| PixelLab route | Measured cost |
+| PixelLab route | Cost |
 |---|---:|
 | `map` | 1 generation |
 | `pixflux` | 1 generation |
 | `1dir` | 20–40 generations |
+| `imagePro` | 40 generations |
+| `imageProFlash` | 5–9 generations (provisional quote) |
 | `tiles` | 20–40 generations |
-| `character` base | 1 (standard), 2–9 (v3), 20–40 (pro) |
-| `character` state | 20–40 generations |
+| `terrain` | 20–40 generations (unmeasured) |
+| `isometricTile` | 1 generation (measured once) |
+| `character` base | 1 (standard), 2–9 (v3), 20–40 (pro), 6–17 (pro-flash; rotations only from a reference) |
+| `character` state or portrait | 20–40 generations |
 | `character` animation | 1 (template), 1 at 64px from text, 20–40 (pro) |
+| `character` outfit | 20 generations (one 2-frame, 92×92 job) |
+| `objectPro` base | 6 at 64px (unmeasured) |
+| `uiAsset` | 20 generations (measured once, at 256×192) |
+| `uiElement` | 20–40 generations (unmeasured) |
+| `image-to-image` / `inpaint` revision | 20–40 generations; 5–9 with `engine: "pro-flash"` (provisional quote) |
+| `reduce-colors` / `correct-pixelart` revision | 0.1 generations (measured at 32×32) |
 
 Retro Diffusion publishes USD formulas and fixed prices. Examples relevant to
 PixelKiln include RD Fast from about $0.015 per image, RD Plus from about $0.025,

package/README.md

@@ -53,8 +53,9 @@ provenance and no long-lived npm token.
 | Plan and budget | Offline manifest/lock/disk diff, provider-grouped estimates, keyed mixed-provider budget ceilings, JSON/CI gate. |
 | Generate and review | Resumable submit/poll/pick/fetch pipeline, exact next-step hints, candidate or atomic frame-set review, and a provenance gallery that can edit intent, generate under a budget, and compare records. |
 | Hand edits | Touch-ups in your own editor or a pinned in-browser Pixelorama, kept beside the generated art with the generation still the record; frame and tile sets member by member. |
-| Controlled inputs | Hashed image-to-image/inpaint lineage, fail-closed parent approval, source-versus-candidate review, and content-addressed per-asset ComfyUI bindings. |
-| Characters | A base in 4 or 8 directions from a prompt or your own sprite (four PixelLab engines), poses and loops as dependent assets generated in waves, free mirrored directions, account adoption, and SpriteFrames export. |
+| Controlled inputs | Hashed revision lineage (image-to-image and inpaint; on PixelLab also palette reduction, pixel cleanup, animation, skeleton posing, interpolation, and animation edits), fail-closed parent approval, source-versus-candidate review, and content-addressed per-asset ComfyUI bindings. |
+| Characters | A base in 4 or 8 directions from a prompt or your own sprite (four PixelLab engines), poses, loops, portraits, and outfit transfers as dependent assets generated in waves, free mirrored directions (one `directions` list declares a loop and mirrors the rest), account adoption and salvage, and SpriteFrames export. |
+| PixelLab utilities | `unzoom` returns upscaled reference art to its native grid, `font` generates a `.ttf` and glyph atlas, and `estimate-skeleton` starts a keypoints file for skeleton animation. |
 | Existing-art onboarding | Manifest scaffolding, exact-hash account adoption, and prompt recovery. |
 | Recovery | Safe stale-output replacement, validated caches, durable references, resumable paid jobs, and per-asset generation history with free restores. |
 | Shared-account safety | Cross-project claim files or a registered workspace catalog, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |
@@ -258,18 +259,17 @@ Measured PixelLab economics vary by 40×:
 | Independent or connectable ground tiles | `tiles` | 20–40 generations |
 | A character in 4 or 8 directions, its poses, its loops | `character` | 1 per base, 20–40 per pose, 1 per template loop per direction; a `mirror` of a loop is free |
 
-Start with the required capability, not the most expensive endpoint. Forty
-`map` re-rolls cost the same as one 64×64 `1dir` call; conversely, `map` cannot
-replace a hard palette or reference-image constraint. See
-[Generator selection](./docs/GENERATORS.md) and the
-[measured endpoint reference](./docs/ENDPOINTS.md).
+Start with the required capability, not the most expensive endpoint. Forty `map`
+re-rolls cost the same as one 64×64 `1dir` call; conversely, `map` cannot replace a
+hard palette or reference-image constraint. PixelLab has seven more generators
+(`imagePro`, `imageProFlash`, `terrain`, `isometricTile`, `objectPro`, `uiAsset`,
+`uiElement`); see [Generator selection](./docs/GENERATORS.md) and the [measured endpoint reference](./docs/ENDPOINTS.md).
 
-Generator names describe PixelKiln workflows; their exact capabilities and
-prices depend on the selected provider. Retro Diffusion also supports the
-provider-specific `animation` generator. ComfyUI supports `map` plus atomic
-still-image `frames` through an operator-supplied workflow. Scenario supports `map`
-with a required offline CU ceiling and a live quote before each paid call.
-Compare the adapters in the [provider comparison](./PROVIDERS.md).
+Generator names describe PixelKiln workflows; their exact capabilities and prices
+depend on the selected provider. Retro Diffusion also supports the provider-specific
+`animation` generator. ComfyUI supports `map` plus atomic still-image `frames` through
+an operator-supplied workflow. Scenario supports `map` with a required offline CU
+ceiling and a live quote before each paid call. Compare the adapters in the [provider comparison](./PROVIDERS.md).
 
 ## Derived artifacts
 
@@ -368,12 +368,13 @@ verification. See [Library API](./docs/LIBRARY.md).
 | [Set up ComfyUI](./docs/COMFYUI.md) | Self-hosted stills, revisions, ordered frame sets, per-asset inputs, and quality limits. |
 | [Set up Scenario](./docs/SCENARIO.md) | Experimental hosted models, two-part credentials, CU preflight, review, and durable downloads. |
 | [Versioned recipes](./docs/RECIPES.md) | Pinned workflow packs, model hashes, manifest templates, and quality contracts. |
-| [Controlled revisions](./docs/REVISIONS.md) | Image-to-image/inpaint parents, masks, fail-closed readiness, provenance, and ComfyUI bindings. |
+| [Controlled revisions](./docs/REVISIONS.md) | Image-to-image, inpaint, palette cleanup, animation, and interpolation from a parent; masks, fail-closed readiness, provenance, and ComfyUI bindings. |
 | [CLI reference](./docs/CLI.md) | Every command, flag, JSON mode, and exit contract. |
 | [Manifest reference](./docs/MANIFEST.md) | Style/asset fields, quality profiles, and generator constraints. |
 | [Mixed-provider projects](./docs/MIXED_PROVIDERS.md) | Per-style routing, provider-keyed budgets, recovery, and account commands. |
 | [Agent workflows](./docs/AGENTS.md) | Official skill install, operating model, and provider-aware safety. |
 | [Generators](./docs/GENERATORS.md) | Capability choice, measured costs, palettes, style references, and tiles. |
+| [Characters](./docs/CHARACTERS.md) | Bases, states, loops, mirrors, portraits, outfits, the `directions` shorthand, and per-engine costs. |
 | [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Thirty provider outputs plus native-grid and final-palette results comparing large scenes, transparency, palette size, and file readiness. |
 | [Derived artifacts](./docs/ARTIFACTS.md) | Refine, pack, mount, export, provenance, ownership, transactions, and recovery. |
 | [Recovery](./docs/RECOVERY.md) | Restore, caches, adopt, salvage, claims, and purge safety. |
@@ -384,10 +385,9 @@ verification. See [Library API](./docs/LIBRARY.md).
 | [Endpoint research](./docs/ENDPOINTS.md) | Measured PixelLab API behavior and recipes. |
 | [Provider comparison](./PROVIDERS.md) | Provider selection, costs, supported workflows, confidence, and limitations. |
 
-The [public documentation site](https://pixelkiln.griffen.codes/docs) is built from
-these Markdown files by [`website/`](./website/README.md), so the site and the
-package share one source. Policies: [Contributing](./CONTRIBUTING.md),
-[Security](./SECURITY.md), [provider comparison](./PROVIDERS.md).
+The [public documentation site](https://pixelkiln.griffen.codes/docs) is built from these Markdown
+files by [`website/`](./website/README.md), so the site and the package share one source.
+Policies: [Contributing](./CONTRIBUTING.md), [Security](./SECURITY.md).
 
 ## Scope
 

package/dist/cli.js

@@ -689,6 +689,11 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
       uiPieces: spec.uiPieces,
       uiElements: spec.uiElements,
       uiColorPalette: spec.uiColorPalette,
+      // Scene and mask enter as their bytes' hashes, never their paths.
+      scene: spec.scene ? {
+        image: spec.scene.sha256,
+        placement: spec.scene.placement.type === "mask" ? { type: "mask", mask: spec.scene.placement.sha256 } : spec.scene.placement
+      } : void 0,
       styleTraits: spec.styleTraits,
       styleImages: styleImageHashes,
       // A character family: the engine and rotations of a base, the parent's
@@ -987,6 +992,16 @@ var CharacterPortraitSchema = z.object({
   of: z.string().min(1),
   size: CharacterPortraitSizeSchema.default(64)
 }).strict();
+var MapScenePlacementSchema = z.union([
+  z.object({ oval: z.number().min(0.05).max(0.95) }).strict(),
+  z.object({ rectangle: z.number().min(0.05).max(0.95) }).strict(),
+  z.object({ mask: z.string().min(1) }).strict()
+]);
+var MapSceneSchema = z.object({
+  /** Manifest-relative PNG of the scene. Any earlier asset's output file works. */
+  image: z.string().min(1),
+  placement: MapScenePlacementSchema.default({ oval: 0.3 })
+}).strict();
 var CharacterOutfitSchema = z.object({
   /** The loop (a character animation asset) to re-clothe, in the same style. */
   of: z.string().min(1),
@@ -1681,6 +1696,8 @@ var AssetSchema = z.object({
   portrait: CharacterPortraitSchema.optional(),
   /** `character` styles: this asset re-clothes an existing loop's frames with a reference outfit. */
   outfit: CharacterOutfitSchema.optional(),
+  /** `map` styles only: draw this object in the style of a scene image. See `MapSceneSchema`. */
+  scene: MapSceneSchema.optional(),
   /** `character` styles, `standard` humanoid bases: this character's proportions, over the style's. */
   proportions: CharacterProportionsSchema.optional(),
   /**
@@ -1757,7 +1774,7 @@ var AssetSchema = z.object({
       path: ["revision"]
     });
   }
-  const shapes = [asset.revision && "revision", asset.state && "state", asset.animation && "animation", asset.mirror && "mirror", asset.batch && "batch", asset.portrait && "portrait", asset.outfit && "outfit"].filter(Boolean);
+  const shapes = [asset.revision && "revision", asset.state && "state", asset.animation && "animation", asset.mirror && "mirror", asset.batch && "batch", asset.portrait && "portrait", asset.outfit && "outfit", asset.scene && "scene"].filter(Boolean);
   if (shapes.length > 1) {
     context.addIssue({
       code: z.ZodIssueCode.custom,
@@ -4212,6 +4229,7 @@ async function inspectRevisionReadiness(spec, lock) {
   if (spec.character?.parentSpec) return inspectCharacterParent(spec, lock, /* @__PURE__ */ new Set());
   if (spec.character?.styleAnchor) return inspectStyleAnchor(spec, lock, /* @__PURE__ */ new Set());
   if (spec.objectPro?.parentSpec) return inspectObjectProParent(spec, lock, /* @__PURE__ */ new Set());
+  if (spec.scene) return inspectScene(spec);
   if (!spec.revision) return null;
   return inspectRevision(spec, lock, /* @__PURE__ */ new Set());
 }
@@ -4229,6 +4247,16 @@ async function inspectStyleAnchor(spec, lock, seen) {
   }
   return { ready: true, reason: `${label} is current` };
 }
+async function inspectScene(spec) {
+  const scene = spec.scene;
+  const files = [{ label: "scene image", file: scene.file, sha256: scene.sha256 }];
+  if (scene.placement.type === "mask") files.push({ label: "scene mask", file: scene.placement.file, sha256: scene.placement.sha256 });
+  for (const { label, file, sha256: sha2562 } of files) {
+    if (!sha2562 || !existsSync4(file)) return { ready: false, reason: `${label} does not exist yet: ${file}` };
+    if (await sha256File(file) !== sha2562) return { ready: false, reason: `${label} changed after the manifest was resolved` };
+  }
+  return { ready: true, reason: "scene is current" };
+}
 async function inspectMirror(spec, lock, seen) {
   const source = spec.mirror.sourceSpec;
   const label = `mirror source ${spec.styleId}/${spec.mirror.sourceAssetId}`;
@@ -6136,6 +6164,12 @@ var PixelLabClient = class {
     if (args.shading) body.shading = args.shading;
     if (args.detail) body.detail = args.detail;
     if (args.seed != null) body.seed = args.seed;
+    if (args.scene) {
+      const encode = (image) => ({ type: "base64", base64: image.base64, format: image.format });
+      const placement = args.scene.placement;
+      body.background_image = encode(args.scene.image);
+      body.inpainting = placement.type === "mask" ? { type: "mask", mask_image: encode(placement.mask) } : { type: placement.type, fraction: placement.fraction };
+    }
     return validateResponse(
       MapSubmitSchema,
       await this.request("/map-objects", { method: "POST", body: JSON.stringify(body) }),
@@ -7297,6 +7331,8 @@ var PixelLabProvider = class _PixelLabProvider {
   supports(generator) {
     return generator === "1dir" || generator === "map" || generator === "pixflux" || generator === "tiles" || generator === "terrain" || generator === "imagePro" || generator === "character" || generator === "isometricTile" || generator === "objectPro" || generator === "uiAsset" || generator === "uiElement" || generator === "imageProFlash";
   }
+  /** `/map-objects` style matching: `background_image` plus `inpainting`. */
+  supportsMapScene = true;
   /**
    * `inpaint` (`/inpaint-v3`, a mask) and `image-to-image` (`/edit-images-v2`,
    * no mask) both exist on PixelLab, and so do `reduce-colors`
@@ -8442,7 +8478,8 @@ var PixelLabProvider = class _PixelLabProvider {
       outline: spec.outline,
       shading: spec.shading,
       detail: spec.detail,
-      seed: spec.seed
+      seed: spec.seed,
+      scene: spec.scene ? mapScenePayload(spec) : void 0
     });
     return { jobId: res.object_id, metadata: { backgroundJobId: res.background_job_id } };
   }
@@ -9319,6 +9356,21 @@ function findObjectAnimation(object, name, direction, animationId) {
   }
   return null;
 }
+function mapScenePayload(spec) {
+  const scene = spec.scene;
+  const read = (file, hash, label) => {
+    const bytes = readFileSync2(file);
+    if (!hash || sha256(bytes) !== hash) {
+      throw new Error(`${spec.styleId}/${spec.assetId}: ${label} changed after the manifest was resolved`);
+    }
+    return { base64: bytes.toString("base64"), format: "png" };
+  };
+  const placement = scene.placement;
+  return {
+    image: read(scene.file, scene.sha256, "scene image"),
+    placement: placement.type === "mask" ? { type: "mask", mask: read(placement.file, placement.sha256, "scene mask") } : placement
+  };
+}
 
 // src/providers/retrodiffusion.ts
 var DEFAULT_BASE_URL2 = "https://api.retrodiffusion.ai/v1";
@@ -11021,6 +11073,7 @@ async function resolveSpecs(loaded, filter) {
           };
         }
       }
+      if (asset.scene) resolved.scene = await resolveMapScene(root, styleId, assetId, resolved.generator, asset.scene, activeProvider);
       resolved.specHash = specHash(
         resolved,
         styleImageHashes,
@@ -11079,6 +11132,32 @@ function pngPath(file) {
   const extension = path13.extname(file);
   return extension ? `${file.slice(0, -extension.length)}.png` : `${file}.png`;
 }
+async function resolveMapScene(root, styleId, assetId, generator, scene, provider) {
+  if (generator !== "map") {
+    throw new Error(`assets.${assetId}.scene: only a map object can be drawn into a scene; style "${styleId}" uses "${generator}"`);
+  }
+  if (!provider.supportsMapScene) {
+    throw new Error(`assets.${assetId}.scene: provider "${provider.id}" cannot draw into a scene; PixelLab's /map-objects can`);
+  }
+  const file = path13.resolve(root, scene.image);
+  const image = await optionalRevisionImage(file, "scene image", "png");
+  const base = { file, sha256: image?.hash ?? null, width: image?.width ?? null, height: image?.height ?? null };
+  const placement = scene.placement;
+  if ("mask" in placement) {
+    const maskFile = path13.resolve(root, placement.mask);
+    const mask = await optionalRevisionImage(maskFile, "scene mask", "png");
+    if (image && mask && (image.width !== mask.width || image.height !== mask.height)) {
+      throw new Error(
+        `assets.${assetId}.scene: the mask is ${mask.width}x${mask.height}; the scene ${scene.image} is ${image.width}x${image.height}`
+      );
+    }
+    return {
+      ...base,
+      placement: { type: "mask", file: maskFile, sha256: mask?.hash ?? null, width: mask?.width ?? null, height: mask?.height ?? null }
+    };
+  }
+  return "oval" in placement ? { ...base, placement: { type: "oval", fraction: placement.oval } } : { ...base, placement: { type: "rectangle", fraction: placement.rectangle } };
+}
 async function optionalRevisionImage(file, label, requiredFormat) {
   if (!existsSync8(file)) return null;
   const bytes = await readFile6(file);