pixelkiln 0.87.0 → 0.88.0

package/dist/cli.js

@@ -67,8 +67,8 @@ function exitCodeFor(err) {
 }
 
 // src/cli/main.ts
-import { existsSync as existsSync38 } from "fs";
-import { readFile as readFile34 } from "fs/promises";
+import { existsSync as existsSync39 } from "fs";
+import { readFile as readFile35 } from "fs/promises";
 
 // src/cli/args.ts
 import path from "path";
@@ -109,7 +109,13 @@ var VALUE_FLAGS = [
   "--weight",
   "--glyph-px",
   "--frames",
-  "--estimate-limit"
+  "--estimate-limit",
+  "--preset",
+  "--recipe",
+  "--effect",
+  "--part",
+  "--sprite",
+  "--fps"
 ];
 var BOOL_FLAGS = [
   "--force",
@@ -126,7 +132,8 @@ var BOOL_FLAGS = [
   "--prune",
   "--edit",
   "--refresh",
-  "--no-editor"
+  "--no-editor",
+  "--game-pack"
 ];
 var COMMANDS = [
   "init",
@@ -163,6 +170,7 @@ var COMMANDS = [
   "skeleton-preview",
   "unzoom",
   "pixelate",
+  "vfx",
   "font",
   "help",
   "--help",
@@ -177,6 +185,7 @@ var QUALITY_SUBCOMMANDS = ["snapshot", "check"];
 var EDIT_SUBCOMMANDS = ["start", "detach"];
 var TOOLS_SUBCOMMANDS = ["status", "install"];
 var TOOLS = ["editor"];
+var VFX_SUBCOMMANDS = ["make", "presets", "parts"];
 function parseArgs(argv) {
   const [command = "help"] = argv;
   if (!COMMANDS.includes(command)) {
@@ -266,6 +275,12 @@ function parseArgs(argv) {
       throw new UsageError("skeleton-preview needs a keypoints file or an animate-skeleton asset id");
     }
     rest = rest.slice(1);
+  } else if (command === "vfx") {
+    subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "make" : rest[0];
+    if (!VFX_SUBCOMMANDS.includes(subcommand)) {
+      throw new UsageError(`Unknown vfx subcommand "${subcommand}". Known: ${VFX_SUBCOMMANDS.join(", ")}`);
+    }
+    if (rest[0] === subcommand) rest = rest.slice(1);
   } else if (command === "refine") {
     subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "run" : rest[0];
     if (!REFINE_SUBCOMMANDS.includes(subcommand)) {
@@ -433,7 +448,14 @@ function parseArgs(argv) {
     weight: get("--weight"),
     glyphPx: numberOption("--glyph-px", { min: 8, max: 64, integer: true }),
     frames: numberOption("--frames", { min: 3, max: 15, integer: true }),
-    estimateLimit: numberOption("--estimate-limit", { min: 0, max: 1e3, integer: true })
+    estimateLimit: numberOption("--estimate-limit", { min: 0, max: 1e3, integer: true }),
+    preset: get("--preset"),
+    recipe: get("--recipe"),
+    effect: get("--effect"),
+    parts: list("--part"),
+    sprite: get("--sprite"),
+    fps: numberOption("--fps", { min: 1, max: 60, integer: true }),
+    gamePack: rest.includes("--game-pack")
   };
 }
 
@@ -504,6 +526,10 @@ Commands
             pixel art with Image to Pixel Art Pro Flash; PixelLab picks the
             output size. Optional --description steers the style. 6
             generations; asks first.
+  vfx       PixelLab: build an animated pixel-art effect with the VFX
+            workbench (free) from a --preset, a --recipe file, a saved
+            --effect, and/or --part; writes <out>.png/.gif/.json and a
+            .vfx.json recipe record. vfx presets / vfx parts list options.
   font      PixelLab: generate a pixel font (--description, --out); writes a
             .ttf and a glyph atlas PNG. 15 generations; asks first.
 
@@ -531,6 +557,13 @@ Options
   --description <text>  font: the style to draw, e.g. "warm orange arcade font";
                       pixelate: an optional style steer, e.g. "light dithering"
   --weight <w>        font: Bold or Regular (default)
+  --preset <name>     vfx: start from a whole-effect preset (vfx presets lists them)
+  --recipe <file>     vfx: render a recipe or an earlier run's .vfx.json record
+  --effect <id>       vfx: start from a saved My effects id and export over it
+  --part <name>       vfx: add a part (repeatable; vfx parts lists them)
+  --sprite <ref>      vfx: build around a sprite: a file, a URL, or character:<id>:<dir>
+  --fps <n>           vfx: frames per second, 1-60
+  --game-pack         vfx: also download the game-pack ZIP
   --glyph-px <n>      font: native glyph size, 8, 16 (default), 32, or 64
   --prune             cache: remove invalid/unreferenced local cache data
   --manifest <path>   Default: pixelkiln.manifest.json
@@ -590,6 +623,7 @@ Examples
   pixelkiln quality check --from pixelkiln.quality.json
   pixelkiln unzoom --from refs/knight-512.png --out refs/knight.png
   pixelkiln pixelate --from renders/lodge.png --out art/lodge.png
+  pixelkiln vfx --preset explosion --part scorch_mark --out fx/explosion --game-pack
   pixelkiln font --description "warm orange arcade font" --weight Bold --out fonts/arcade
   pixelkiln workspace add ../other-game/pixelkiln.manifest.json
   pixelkiln workspace status --json
@@ -672,16 +706,17 @@ import { createReadStream } from "fs";
 function sha256(data) {
   return createHash("sha256").update(data).digest("hex");
 }
-async function sha256File(path52) {
+async function sha256File(path53) {
   return new Promise((resolve, reject) => {
     const hash = createHash("sha256");
-    const stream = createReadStream(path52);
+    const stream = createReadStream(path53);
     stream.on("data", (chunk2) => hash.update(chunk2));
     stream.on("error", reject);
     stream.on("end", () => resolve(hash.digest("hex")));
   });
 }
 function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions, providerInputIdentity = spec.providerInputs ?? {}) {
+  const effect = Boolean(spec.vfx);
   return sha256(
     JSON.stringify({
       // Preserve every existing PixelLab hash while making a provider switch
@@ -690,15 +725,15 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
       providerOptions: providerOptionIdentity && (typeof providerOptionIdentity !== "object" || Object.keys(providerOptionIdentity).length > 0) ? providerOptionIdentity : void 0,
       providerInputs: providerInputIdentity && (typeof providerInputIdentity !== "object" || Object.keys(providerInputIdentity).length > 0) ? providerInputIdentity : void 0,
       generator: spec.generator,
-      prompt: spec.prompt,
-      width: spec.width,
-      height: spec.height,
-      view: spec.view,
-      outline: spec.outline ?? null,
-      shading: spec.shading ?? null,
-      detail: spec.detail ?? null,
-      seed: spec.seed ?? null,
-      palette: spec.palette,
+      prompt: effect ? void 0 : spec.prompt,
+      width: effect ? void 0 : spec.width,
+      height: effect ? void 0 : spec.height,
+      view: effect ? void 0 : spec.view,
+      outline: effect ? void 0 : spec.outline ?? null,
+      shading: effect ? void 0 : spec.shading ?? null,
+      detail: effect ? void 0 : spec.detail ?? null,
+      seed: effect ? void 0 : spec.seed ?? null,
+      palette: effect ? void 0 : spec.palette,
       // `noBackground` only reaches the wire for pixflux and uiAsset; the
       // tile fields are undefined for every other generator. `tileSize` is
       // intentionally absent; width/height are derived from it, so it is
@@ -773,6 +808,15 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         styleTraits: spec.objectPro.styleTraits,
         reference: spec.objectPro.reference?.sha256
       } : void 0,
+      // A recipe and a local sprite enter as their contents' hashes, never
+      // their paths; the My effects name is not identity.
+      vfx: spec.vfx ? {
+        preset: spec.vfx.preset,
+        recipe: spec.vfx.recipe?.sha256,
+        parts: spec.vfx.parts,
+        fps: spec.vfx.fps,
+        sprite: spec.vfx.sprite ? "reference" in spec.vfx.sprite ? spec.vfx.sprite.reference : spec.vfx.sprite.sha256 : void 0
+      } : void 0,
       // A mirror's bytes come from its source's recorded outputs; the plan
       // compares those directly, so only the choice of source is identity.
       mirror: spec.mirror ? { of: spec.mirror.sourceAssetId } : void 0,
@@ -822,7 +866,7 @@ import path2 from "path";
 // src/types.ts
 import { z } from "zod";
 var MediaTypeSchema = z.enum(["image/png", "image/gif"]);
-var GeneratorSchema = z.enum(["1dir", "map", "pixflux", "tiles", "animation", "frames", "character", "terrain", "imagePro", "isometricTile", "objectPro", "uiAsset", "uiElement", "imageProFlash"]);
+var GeneratorSchema = z.enum(["1dir", "map", "pixflux", "tiles", "animation", "frames", "character", "terrain", "imagePro", "isometricTile", "objectPro", "uiAsset", "uiElement", "imageProFlash", "vfx"]);
 var GridConfidenceSchema = z.enum(["low", "medium", "high"]);
 var RevisionModeSchema = z.enum([
   "image-to-image",
@@ -855,6 +899,7 @@ function candidateCount(size) {
   return 1;
 }
 function generationCost(width, height, generator = "map") {
+  if (generator === "vfx") return 0;
   if (generator === "map" || generator === "pixflux") return 1;
   if (generator === "imagePro") return proTierCost(width, height);
   const px = width * height;
@@ -1039,6 +1084,29 @@ var MapSceneSchema = z.object({
   image: z.string().min(1),
   placement: MapScenePlacementSchema.default({ oval: 0.3 })
 }).strict();
+var VfxPartSchema = z.object({ name: z.string().min(1) }).catchall(z.unknown());
+var AssetVfxSchema = z.object({
+  preset: z.string().min(1).optional(),
+  recipe: z.string().min(1).optional(),
+  parts: z.array(VfxPartSchema).optional(),
+  sprite: z.string().min(1).optional(),
+  fps: z.number().int().min(1).max(60).optional(),
+  name: z.string().min(1).optional()
+}).strict().superRefine((vfx, context) => {
+  if (vfx.preset && vfx.recipe) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "start a vfx from a preset or a recipe, not both", path: ["recipe"] });
+  }
+  if (!vfx.preset && !vfx.recipe && !vfx.parts?.length) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "a vfx needs a preset, a recipe, or at least one part", path: ["preset"] });
+  }
+  if (vfx.sprite && /^(https?|data):/i.test(vfx.sprite)) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "a vfx sprite is a manifest-relative image or a character:/object:/gallery: reference; a URL has no content to track",
+      path: ["sprite"]
+    });
+  }
+});
 var CharacterOutfitSchema = z.object({
   /** The loop (a character animation asset) to re-clothe, in the same style. */
   of: z.string().min(1),
@@ -1672,7 +1740,7 @@ var StyleSchema = StyleObjectSchema.refine((s) => !(s.tileFeature && s.styleImag
   message: "tileFeature and styleImages cannot be combined; a connectable set derives its own tile geometry, so remove one or the other",
   path: ["tileFeature"]
 }).superRefine((style, ctx) => {
-  if (style.quality && (style.generator === "tiles" || style.generator === "terrain" || style.generator === "animation")) {
+  if (style.quality && (style.generator === "tiles" || style.generator === "terrain" || style.generator === "animation" || style.generator === "vfx")) {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
       message: "quality profiles currently support single-image generators only",
@@ -1802,6 +1870,8 @@ var AssetSchema = z.object({
   outfit: CharacterOutfitSchema.optional(),
   /** `map` styles only: draw this object in the style of a scene image. See `MapSceneSchema`. */
   scene: MapSceneSchema.optional(),
+  /** `vfx` styles only: the effect to render. See `AssetVfxSchema`. */
+  vfx: AssetVfxSchema.optional(),
   /** `character` styles, `standard` humanoid bases: this character's proportions, over the style's. */
   proportions: CharacterProportionsSchema.optional(),
   /**
@@ -1878,7 +1948,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", asset.scene && "scene"].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", asset.vfx && "vfx"].filter(Boolean);
   if (shapes.length > 1) {
     context.addIssue({
       code: z.ZodIssueCode.custom,
@@ -1893,7 +1963,7 @@ var AssetSchema = z.object({
       path: ["mirror"]
     });
   }
-  if (asset.prompt === void 0 && !asset.mirror && !asset.portrait && !asset.outfit && !asset.animation?.template) {
+  if (asset.prompt === void 0 && !asset.mirror && !asset.portrait && !asset.outfit && !asset.animation?.template && !asset.vfx) {
     context.addIssue({
       code: z.ZodIssueCode.custom,
       message: "Required",
@@ -2918,6 +2988,11 @@ function frameSetFps(entry) {
   }
   return null;
 }
+function frameSetLoop(entry) {
+  const frameSet = entry.providerMetadata?.[entry.provider]?.frameSet;
+  const loop = frameSet && typeof frameSet === "object" ? frameSet.loop : void 0;
+  return typeof loop === "boolean" ? loop : null;
+}
 
 // src/palette.ts
 function normalizePalette(values) {
@@ -4339,6 +4414,7 @@ async function inspectRevisionReadiness(spec, lock) {
   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.vfx?.sprite && "file" in spec.vfx.sprite) return inspectVfxSprite(spec);
   if (!spec.revision) return null;
   return inspectRevision(spec, lock, /* @__PURE__ */ new Set());
 }
@@ -4366,6 +4442,12 @@ async function inspectScene(spec) {
   }
   return { ready: true, reason: "scene is current" };
 }
+async function inspectVfxSprite(spec) {
+  const sprite = spec.vfx.sprite;
+  if (!sprite.sha256 || !existsSync4(sprite.file)) return { ready: false, reason: `vfx sprite does not exist yet: ${sprite.file}` };
+  if (await sha256File(sprite.file) !== sprite.sha256) return { ready: false, reason: "vfx sprite changed after the manifest was resolved" };
+  return { ready: true, reason: "vfx sprite is current" };
+}
 async function inspectMirror(spec, lock, seen) {
   const source = spec.mirror.sourceSpec;
   const label = `mirror source ${spec.styleId}/${spec.mirror.sourceAssetId}`;
@@ -4602,7 +4684,7 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (opts.force) {
       state = "missing";
       reason = "--force";
-    } else if (!entry && spec.source && spec.generator !== "frames") {
+    } else if (!entry && spec.source && spec.generator !== "frames" && spec.generator !== "vfx") {
       if (existsSync5(path9.resolve(spec.root, spec.source))) {
         state = "ok";
         reason = `placed from ${spec.source}; not generated`;
@@ -4842,8 +4924,8 @@ async function confirm(question, auto) {
 }
 
 // src/cli/commands/account.ts
-import path23 from "path";
-import { existsSync as existsSync16 } from "fs";
+import path24 from "path";
+import { existsSync as existsSync17 } from "fs";
 
 // src/env.ts
 import { readFileSync, existsSync as existsSync6 } from "fs";
@@ -5855,10 +5937,10 @@ function canonical2(value) {
 }
 
 // src/providers/pixellab.ts
-import { mkdirSync, existsSync as existsSync7, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { mkdirSync, existsSync as existsSync8, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { randomUUID as randomUUID3 } from "crypto";
 import os from "os";
-import path12 from "path";
+import path13 from "path";
 
 // src/client.ts
 import { z as z3 } from "zod";
@@ -6275,9 +6357,9 @@ var PixelLabClient = class {
   apiKey;
   http;
   /** Retries transport failures, 429, and 5xx; see http.ts for the policy. */
-  async request(path52, init) {
+  async request(path53, init) {
     const auth = this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`;
-    const res = await this.http(`${BASE}${path52}`, {
+    const res = await this.http(`${BASE}${path53}`, {
       ...init,
       headers: {
         Authorization: auth,
@@ -6287,13 +6369,13 @@ var PixelLabClient = class {
     });
     const text = await res.text();
     if (!res.ok) {
-      throw new PixelLabError(`${init?.method ?? "GET"} ${path52} \u2192 ${res.status}`, res.status, text);
+      throw new PixelLabError(`${init?.method ?? "GET"} ${path53} \u2192 ${res.status}`, res.status, text);
     }
     if (!text) return {};
     try {
       return JSON.parse(text);
     } catch {
-      throw new Error(`${init?.method ?? "GET"} ${path52} returned invalid JSON`);
+      throw new Error(`${init?.method ?? "GET"} ${path53} returned invalid JSON`);
     }
   }
   async balance() {
@@ -6698,10 +6780,10 @@ var PixelLabClient = class {
     const palette = args.paletteSwatchBase64 ? { color_image: { type: "base64", base64: args.paletteSwatchBase64, format: "png" }, force_colors: true } : {};
     const encode = (image) => ({ type: "base64", base64: image.base64, format: image.format });
     const south = args.reference?.south;
-    let path52;
+    let path53;
     let body;
     if (args.mode === "v3") {
-      path52 = "/create-character-v3";
+      path53 = "/create-character-v3";
       body = {
         description: args.description,
         image_size: imageSize,
@@ -6715,7 +6797,7 @@ var PixelLabClient = class {
         ...args.enhancePrompt ? { enhance_prompt: true } : {}
       };
     } else if (args.mode === "pro-flash") {
-      path52 = "/create-character-pro-flash";
+      path53 = "/create-character-pro-flash";
       const traits = args.styleTraits;
       body = {
         description: args.description,
@@ -6739,7 +6821,7 @@ var PixelLabClient = class {
         } : {}
       };
     } else if (args.mode === "pro") {
-      path52 = "/create-character-pro";
+      path53 = "/create-character-pro";
       body = {
         description: args.description,
         image_size: imageSize,
@@ -6753,7 +6835,7 @@ var PixelLabClient = class {
         ...!south && args.styleCharacterId ? { style_character_id: args.styleCharacterId } : {}
       };
     } else {
-      path52 = args.directions === 4 ? "/create-character-with-4-directions" : "/create-character-with-8-directions";
+      path53 = args.directions === 4 ? "/create-character-with-4-directions" : "/create-character-with-8-directions";
       body = {
         description: args.description,
         image_size: imageSize,
@@ -6770,8 +6852,8 @@ var PixelLabClient = class {
         ...palette
       };
     }
-    const raw = await this.request(path52, { method: "POST", body: JSON.stringify(body) });
-    return validateResponse(CharacterSubmitSchema, raw, path52.slice(1));
+    const raw = await this.request(path53, { method: "POST", body: JSON.stringify(body) });
+    return validateResponse(CharacterSubmitSchema, raw, path53.slice(1));
   }
   /** A text edit of an existing character, applied to every direction and stored as a sibling. */
   async createCharacterState(args) {
@@ -7071,8 +7153,8 @@ var PixelLabClient = class {
   /**
    * `/image-to-pixelart-pro-flash`: a photo, painting, or render in, pixel
    * art out, with no size to pass: PixelLab detects the native pixel scale
-   * and picks the output size (a 256x256 render came back 108x109, on a
-   * transparent background). A flat 6 generations, billed exactly that live
+   * and picks the output size (a 256x256 render came back 108x109). The
+   * result is opaque, on a near-white background. A flat 6 generations, billed exactly that live
    * in October 2026. Sources over 2048px on the longer side are scaled down
    * upstream. The finished job carries the image at `last_response.images[0]`.
    */
@@ -7443,6 +7525,337 @@ function clientFromEnv() {
   return new PixelLabClient(key);
 }
 
+// src/pixellab-mcp.ts
+var PIXELLAB_MCP_URL = "https://api.pixellab.ai/mcp";
+var PROTOCOL_VERSION = "2025-06-18";
+function parseMcpBody(body) {
+  const trimmed = body.trim();
+  if (trimmed.startsWith("{")) return JSON.parse(trimmed);
+  let last;
+  for (const line of body.split(/\r?\n/)) {
+    if (!line.startsWith("data:")) continue;
+    const payload = line.slice(5).trim();
+    if (!payload) continue;
+    const message6 = JSON.parse(payload);
+    if ("id" in message6) last = message6;
+  }
+  if (!last) throw new Error(`PixelLab MCP reply had no JSON-RPC response: ${body.slice(0, 200)}`);
+  return last;
+}
+function isBusyReply(text) {
+  return /\bbusy\b.*\bretry\b/i.test(text);
+}
+var PixelLabMcpClient = class {
+  constructor(apiKey, opts = {}) {
+    this.apiKey = apiKey;
+    if (!apiKey) throw new Error("PIXELLAB_API_KEY is required");
+    this.url = opts.url ?? PIXELLAB_MCP_URL;
+    this.http = fetchWithRetry(opts.fetch, { timeoutMs: opts.timeoutMs ?? 18e4 });
+    this.busyRetries = opts.busyRetries ?? 4;
+    this.sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  }
+  apiKey;
+  http;
+  url;
+  busyRetries;
+  sleep;
+  nextId = 1;
+  /**
+   * Call one tool and return its text and images. A tool-level error
+   * (`isError`) throws with the tool's own message, after a few spaced
+   * retries when the tool only said it was busy.
+   */
+  async callTool(name, args) {
+    for (let attempt = 0; ; attempt++) {
+      const reply = await this.callOnce(name, args);
+      if (!reply.isError) return { text: reply.text, images: reply.images };
+      if (attempt < this.busyRetries && isBusyReply(reply.text)) {
+        await this.sleep(2e3 * 2 ** attempt);
+        continue;
+      }
+      throw new Error(`PixelLab ${name}: ${reply.text || "the tool reported an error"}`);
+    }
+  }
+  async callOnce(name, args) {
+    const auth = this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`;
+    const id = this.nextId++;
+    const res = await this.http(this.url, {
+      method: "POST",
+      headers: {
+        Authorization: auth,
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        "MCP-Protocol-Version": PROTOCOL_VERSION
+      },
+      body: JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } })
+    });
+    const body = await res.text();
+    if (!res.ok) throw new PixelLabError(`MCP ${name} \u2192 ${res.status}`, res.status, body);
+    const message6 = parseMcpBody(body);
+    const error = message6.error;
+    if (error) throw new Error(`PixelLab MCP ${name} failed: ${error.message ?? JSON.stringify(error)}`);
+    const result = message6.result ?? {};
+    const text = (result.content ?? []).filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n");
+    const images = (result.content ?? []).filter((block) => block.type === "image" && typeof block.data === "string").map((block) => ({ mimeType: String(block.mimeType ?? "image/png"), data: block.data }));
+    return { text, images, isError: Boolean(result.isError) };
+  }
+};
+function mcpClientFromEnv() {
+  const key = process.env.PIXELLAB_API_KEY;
+  if (!key) {
+    throw new Error(
+      "PIXELLAB_API_KEY is not set.\nLooked in the environment, and in .env.local / .env beside the manifest and in the current directory."
+    );
+  }
+  return new PixelLabMcpClient(key);
+}
+
+// src/pixellab-vfx.ts
+import { existsSync as existsSync7 } from "fs";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
+import path12 from "path";
+var VFX_TOOL = "vfx_workbench";
+var UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+function parseVfxStep(text) {
+  const match = new RegExp(`effect step: (${UUID})`).exec(text);
+  if (!match) throw new Error(`PixelLab vfx_workbench returned no step id:
+${text.slice(0, 600)}`);
+  return match[1];
+}
+function parseVfxRecipe(text) {
+  const lines = text.split(/\r?\n/);
+  const at = lines.findIndex((line) => line.trim() === "working recipe:");
+  const json = at >= 0 ? lines[at + 1]?.trim() : void 0;
+  if (!json?.startsWith("{")) return null;
+  return JSON.parse(json);
+}
+function parseVfxExport(text) {
+  const effectId = new RegExp(`effect id (${UUID})`).exec(text)?.[1];
+  const download = /download (https:\/\/\S+\/): (.+)$/m.exec(text);
+  const size = /(\d+)x(\d+), (\d+) frames @ ([\d.]+) fps, ([^;\n]+)/.exec(text);
+  if (!effectId || !download || !size) {
+    throw new Error(`PixelLab vfx_workbench export reply was not understood:
+${text.slice(0, 600)}`);
+  }
+  const anchor = /anchor[^\n]*? at (-?\d+),\s*(-?\d+)/.exec(text);
+  return {
+    effectId,
+    editUrl: /(https:\/\/pixellab\.ai\/create-vfx\?effect=[0-9a-f-]+)/.exec(text)?.[1] ?? null,
+    width: Number(size[1]),
+    height: Number(size[2]),
+    frames: Number(size[3]),
+    fps: Number(size[4]),
+    loop: !/plays once/.test(size[5]),
+    anchor: anchor ? { x: Number(anchor[1]), y: Number(anchor[2]) } : null,
+    downloadBase: download[1],
+    files: download[2].split(",").map((file) => file.trim()).filter(Boolean),
+    imageId: new RegExp(`image id: (${UUID})`).exec(text)?.[1] ?? null
+  };
+}
+async function describeVfx(client2, topic) {
+  return (await client2.callTool(VFX_TOOL, { argv: ["describe", topic] })).text;
+}
+function vfxOutputPaths(out) {
+  const base = path12.resolve(out.replace(/\.(png|gif|json|zip)$/i, "").replace(/\.vfx$/i, ""));
+  return {
+    sheet: `${base}.png`,
+    gif: `${base}.gif`,
+    atlas: `${base}.json`,
+    provenance: `${base}.vfx.json`,
+    gamePack: `${base}-game.zip`
+  };
+}
+function isVfxReference(sprite) {
+  return /^(character|object|gallery):/.test(sprite) || /^(https?|data):/.test(sprite);
+}
+async function resolveVfxSprite(sprite) {
+  if (isVfxReference(sprite)) return sprite;
+  const bytes = await readFile6(sprite);
+  const metadata = imageMetadata(bytes);
+  if (!metadata) throw new Error(`${sprite} is not a readable PNG or JPEG`);
+  return `data:image/${metadata.format};base64,${bytes.toString("base64")}`;
+}
+async function readVfxRecipe(file) {
+  const parsed = JSON.parse(await readFile6(file, "utf8"));
+  const record = parsed.tool === VFX_TOOL && parsed.recipe && typeof parsed.recipe === "object";
+  const recipe = record ? parsed.recipe : parsed;
+  if (!Array.isArray(recipe.layers)) throw new Error(`${file} is not a VFX recipe: it has no "layers" list`);
+  const recorded = record ? parsed.source?.sprite : void 0;
+  if (typeof recorded !== "string") return { recipe };
+  const sprite = isVfxReference(recorded) ? recorded : path12.resolve(path12.dirname(path12.resolve(file)), recorded);
+  return { recipe, sprite };
+}
+async function defaultDownload(url) {
+  const http = fetchWithRetry();
+  const res = await http(url);
+  if (!res.ok) throw new Error(`download ${url} \u2192 ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length > MAX_DOWNLOAD_BYTES) throw new Error(`download ${url} exceeds the ${MAX_DOWNLOAD_BYTES}-byte safety limit`);
+  return buf;
+}
+function localPathFor(file, paths) {
+  if (/-game\.zip$/i.test(file)) return paths.gamePack;
+  if (/\.gif$/i.test(file)) return paths.gif;
+  if (/\.json$/i.test(file)) return paths.atlas;
+  if (/\.png$/i.test(file)) return paths.sheet;
+  return null;
+}
+async function runVfxWorkbench(client2, opts) {
+  const starts = [opts.preset, opts.recipe, opts.effect].filter((value) => value !== void 0).length;
+  if (starts > 1) throw new Error("Start a VFX from one of a preset, a recipe, or a saved effect, not several");
+  if (starts === 0 && !opts.parts?.length) {
+    throw new Error("A VFX needs something to start from: a preset, a recipe, a saved effect, or at least one part");
+  }
+  const progress = opts.onProgress ?? (() => {
+  });
+  const call = async (argv) => (await client2.callTool(VFX_TOOL, { argv, ...opts.notes ? { notes: opts.notes } : {} })).text;
+  const startArgv = ["start"];
+  if (opts.sprite) startArgv.push("--sprite", opts.sprite);
+  if (opts.preset) startArgv.push("--preset", opts.preset);
+  if (opts.effect) startArgv.push("--effect", opts.effect);
+  progress(opts.preset ? `starting from preset ${opts.preset}` : opts.effect ? `starting from saved effect ${opts.effect}` : "starting");
+  const started = await call(startArgv);
+  let step = parseVfxStep(started);
+  const savedName = opts.effect ? parseVfxRecipe(started)?.name : opts.recipe?.name;
+  const name = opts.name ?? (typeof savedName === "string" ? savedName : void 0) ?? opts.defaultName;
+  if (opts.recipe) {
+    progress("rendering the recipe");
+    step = parseVfxStep(await call([step, "render", JSON.stringify({ recipe: opts.recipe })]));
+  }
+  if (opts.parts?.length) {
+    progress(`adding ${opts.parts.map((part) => part.name).join(", ")}`);
+    step = parseVfxStep(await call([step, "add_part", JSON.stringify({ parts: opts.parts })]));
+  }
+  if (opts.fps !== void 0) {
+    progress(`setting ${opts.fps} fps`);
+    step = parseVfxStep(await call([step, "render", JSON.stringify({ patch: [{ op: "set", path: "fps", value: opts.fps }] })]));
+  }
+  const exportArgv = [step, "export", "--name", name];
+  if (opts.replace) exportArgv.push("--replace", opts.replace);
+  if (opts.gamePack) exportArgv.push("--game-pack");
+  progress(opts.gamePack ? "exporting with a game pack" : "exporting");
+  const exported = parseVfxExport(await call(exportArgv));
+  await opts.onExported?.(exported, name);
+  progress("reading the saved recipe");
+  const recipe = parseVfxRecipe(await call(["start", "--effect", exported.effectId]));
+  return { exported, recipe, name };
+}
+async function readSavedVfxRecipe(client2, effectId) {
+  try {
+    return parseVfxRecipe((await client2.callTool(VFX_TOOL, { argv: ["start", "--effect", effectId] })).text);
+  } catch (error) {
+    if (error instanceof Error && /no saved effect/i.test(error.message)) return null;
+    throw error;
+  }
+}
+function vfxRecipeSha256(recipe) {
+  const { name: _name, notes: _notes, ...rest } = recipe;
+  return sha256(JSON.stringify(rest));
+}
+function sliceVfxSheet(sheet, facts, atlas) {
+  const image = decodePng(sheet);
+  const listed = atlas?.frames;
+  const rects = Array.isArray(listed) && listed.length === facts.frames ? listed.map((entry) => entry.frame) : Array.from({ length: facts.frames }, (_, index) => {
+    const columns = Math.max(1, Math.floor(image.width / facts.width));
+    return { x: index % columns * facts.width, y: Math.floor(index / columns) * facts.height, w: facts.width, h: facts.height };
+  });
+  return rects.map((rect, index) => {
+    if (rect.x < 0 || rect.y < 0 || rect.x + rect.w > image.width || rect.y + rect.h > image.height) {
+      throw new Error(
+        `VFX frame ${index + 1} (${rect.w}x${rect.h} at ${rect.x},${rect.y}) falls outside the ${image.width}x${image.height} sheet`
+      );
+    }
+    const out = Buffer.alloc(rect.w * rect.h * 4);
+    for (let y = 0; y < rect.h; y++) {
+      const from = ((rect.y + y) * image.width + rect.x) * 4;
+      image.pixels.copy(out, y * rect.w * 4, from, from + rect.w * 4);
+    }
+    return encodeRgbaPng(rect.w, rect.h, out);
+  });
+}
+async function makeVfx(client2, opts) {
+  const starts = [opts.preset, opts.recipe, opts.effect].filter((value) => value !== void 0).length;
+  if (starts > 1) throw new Error("Start a VFX from one of a preset, a recipe, or a saved effect, not several");
+  if (starts === 0 && !opts.parts?.length) {
+    throw new Error("A VFX needs something to start from: a preset, a recipe, a saved effect, or at least one part");
+  }
+  const paths = vfxOutputPaths(opts.out);
+  const wanted = [paths.sheet, paths.gif, paths.atlas, paths.provenance, ...opts.gamePack ? [paths.gamePack] : []];
+  if (!opts.force) {
+    for (const file of wanted) {
+      if (existsSync7(file)) throw new Error(`${file} already exists; pass --force to replace it`);
+    }
+  }
+  const progress = opts.onProgress ?? (() => {
+  });
+  const { exported, recipe, name } = await runVfxWorkbench(client2, {
+    preset: opts.preset,
+    recipe: opts.recipe,
+    effect: opts.effect,
+    parts: opts.parts,
+    sprite: opts.sprite ? await resolveVfxSprite(opts.sprite) : void 0,
+    fps: opts.fps,
+    name: opts.name,
+    defaultName: opts.preset ?? path12.basename(paths.sheet, ".png"),
+    replace: opts.replace ?? opts.effect,
+    gamePack: opts.gamePack,
+    notes: "pixelkiln vfx",
+    onProgress: progress
+  });
+  const download = opts.download ?? defaultDownload;
+  const written = { sheet: paths.sheet, gif: paths.gif, atlas: paths.atlas, provenance: paths.provenance };
+  await mkdir4(path12.dirname(paths.sheet), { recursive: true });
+  for (const file of exported.files) {
+    const target = localPathFor(file, paths);
+    if (!target) continue;
+    let bytes = await download(`${exported.downloadBase}${encodeURIComponent(file)}`);
+    if (target === paths.atlas) {
+      const atlas = JSON.parse(bytes.toString("utf8"));
+      if (atlas.meta) atlas.meta.image = path12.basename(paths.sheet);
+      bytes = Buffer.from(`${JSON.stringify(atlas, null, 2)}
+`);
+    }
+    await writeFile4(target, bytes);
+    if (target === paths.gamePack) written.gamePack = target;
+  }
+  for (const file of [paths.sheet, paths.gif, paths.atlas]) {
+    if (!existsSync7(file)) throw new Error(`PixelLab's export listed no file for ${path12.basename(file)}: ${exported.files.join(", ")}`);
+  }
+  const spriteRecord = !opts.sprite || /^data:/.test(opts.sprite) ? void 0 : isVfxReference(opts.sprite) ? opts.sprite : path12.relative(path12.dirname(paths.provenance), path12.resolve(opts.sprite)).split(path12.sep).join("/");
+  const provenance = {
+    version: 1,
+    provider: "pixellab",
+    tool: VFX_TOOL,
+    name,
+    effectId: exported.effectId,
+    editUrl: exported.editUrl,
+    source: {
+      ...opts.preset ? { preset: opts.preset } : {},
+      ...opts.effect ? { effect: opts.effect } : {},
+      ...opts.recipe ? { recipeFile: true } : {},
+      ...opts.parts?.length ? { parts: opts.parts } : {},
+      ...spriteRecord ? { sprite: spriteRecord } : {}
+    },
+    width: exported.width,
+    height: exported.height,
+    frames: exported.frames,
+    fps: exported.fps,
+    loop: exported.loop,
+    anchor: exported.anchor,
+    files: {
+      sheet: path12.basename(paths.sheet),
+      gif: path12.basename(paths.gif),
+      atlas: path12.basename(paths.atlas),
+      ...written.gamePack ? { gamePack: path12.basename(written.gamePack) } : {}
+    },
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    recipe
+  };
+  await writeFile4(paths.provenance, `${JSON.stringify(provenance, null, 2)}
+`);
+  return { ...exported, paths: written, recipe };
+}
+
 // src/providers/pixellab.ts
 function pixelLabObjectUrl(generator, objectId) {
   if (!objectId) return null;
@@ -7457,6 +7870,7 @@ function pixelLabObjectUrl(generator, objectId) {
     const characterId = objectId.split("#")[0];
     return characterId ? `https://www.pixellab.ai/create-character/${encodeURIComponent(characterId)}` : null;
   }
+  if (generator === "vfx") return `https://pixellab.ai/create-vfx?effect=${encodeURIComponent(objectId)}`;
   return null;
 }
 function billedFromUsage(usage) {
@@ -7632,13 +8046,20 @@ function decodeObjectAnimationJob(jobId) {
   return null;
 }
 var PixelLabProvider = class _PixelLabProvider {
-  constructor(client2) {
+  /**
+   * `mcp` reaches the tools PixelLab offers only over MCP (the VFX
+   * workbench). Offline and download-only providers have none, and a `vfx`
+   * submission through one says so.
+   */
+  constructor(client2, mcp) {
     this.client = client2;
+    this.mcp = mcp;
   }
   client;
+  mcp;
   id = "pixellab";
   static fromEnv() {
-    return new _PixelLabProvider(clientFromEnv());
+    return new _PixelLabProvider(clientFromEnv(), mcpClientFromEnv());
   }
   /** Public storage URLs and the local content cache do not require API auth. */
   static forDownloads() {
@@ -7649,7 +8070,7 @@ var PixelLabProvider = class _PixelLabProvider {
     return new _PixelLabProvider(new PixelLabClient("download-only"));
   }
   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";
+    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" || generator === "vfx";
   }
   /** `/map-objects` style matching: `background_image` plus `inpainting`. */
   supportsMapScene = true;
@@ -7691,11 +8112,12 @@ var PixelLabProvider = class _PixelLabProvider {
    * is a file read.
    */
   static cacheDir(namespace = "pixflux") {
-    const dir = path12.join(os.tmpdir(), `pixelkiln-${namespace}`);
+    const dir = path13.join(os.tmpdir(), `pixelkiln-${namespace}`);
     mkdirSync(dir, { recursive: true });
     return dir;
   }
   estimate(spec) {
+    if (spec.vfx) return { unit: "generations", amount: 0, candidates: 1 };
     if (spec.batch?.role === "member") {
       return { unit: "generations", amount: 0, candidates: 1 };
     }
@@ -7753,6 +8175,9 @@ var PixelLabProvider = class _PixelLabProvider {
     };
   }
   validate(spec, styleImages) {
+    if (spec.generator === "vfx" && styleImages.length) {
+      throw new Error("PixelLab vfx takes no style images; an effect's look comes from its preset, parts, or recipe");
+    }
     const members = spec.revision?.sourceMembers;
     if (spec.revision && members && !MEMBER_SET_REVISION_MODES.includes(spec.revision.mode)) {
       throw new Error(
@@ -8037,7 +8462,7 @@ var PixelLabProvider = class _PixelLabProvider {
         }
       }
       if (endFrame) {
-        const start = startFrame ?? (character.parentFile && existsSync7(character.parentFile) ? imageMetadata(readFileSync2(character.parentFile)) : null);
+        const start = startFrame ?? (character.parentFile && existsSync8(character.parentFile) ? imageMetadata(readFileSync2(character.parentFile)) : null);
         if (start && (start.width !== endFrame.width || start.height !== endFrame.height)) {
           throw new Error(
             `${label}: end frame is ${endFrame.width}x${endFrame.height} but the ${startFrame ? "start frame" : "character's rotation"} is ${start.width}x${start.height}; PixelLab interpolates between frames of one size`
@@ -8195,7 +8620,7 @@ var PixelLabProvider = class _PixelLabProvider {
         }
       }
       if (endFrame) {
-        const start = startFrame ?? (object.parentFile && existsSync7(object.parentFile) ? imageMetadata(readFileSync2(object.parentFile)) : null);
+        const start = startFrame ?? (object.parentFile && existsSync8(object.parentFile) ? imageMetadata(readFileSync2(object.parentFile)) : null);
         if (start && (start.width !== endFrame.width || start.height !== endFrame.height)) {
           throw new Error(
             `${label}: end frame is ${endFrame.width}x${endFrame.height} but the ${startFrame ? "start frame" : "object's rotation"} is ${start.width}x${start.height}; PixelLab interpolates between frames of one size`
@@ -8505,7 +8930,7 @@ var PixelLabProvider = class _PixelLabProvider {
     const sources = images.map((image, index) => {
       if (!image.base64) throw new Error(`outfit transfer frame ${index} has no image data`);
       const role = meta?.frameRoles?.[index] ?? void 0;
-      const file = path12.join(dir, `${jobId}-${index}.png`);
+      const file = path13.join(dir, `${jobId}-${index}.png`);
       writeFileSync(file, Buffer.from(image.base64, "base64"));
       return { url: `file://${file}`, ...role ? { role } : {} };
     });
@@ -8657,6 +9082,7 @@ var PixelLabProvider = class _PixelLabProvider {
   async submit(spec, styleImages, context) {
     this.validate(spec, styleImages);
     if (spec.revision) return this.submitRevision(spec);
+    if (spec.vfx) return this.submitVfx(spec, context);
     if (spec.generator === "character") return this.submitCharacter(spec, styleImages, context);
     if (spec.generator === "objectPro") return this.submitObjectPro(spec, styleImages, context);
     if (spec.generator === "uiAsset") {
@@ -8710,7 +9136,7 @@ var PixelLabProvider = class _PixelLabProvider {
         seed: spec.seed
       });
       const jobId = randomUUID3();
-      writeFileSync(path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), png);
+      writeFileSync(path13.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), png);
       return { jobId };
     }
     if (spec.generator === "tiles") {
@@ -9039,11 +9465,11 @@ var PixelLabProvider = class _PixelLabProvider {
   cacheCleanupResult(pngs, usage, roles, fps) {
     const jobId = randomUUID3();
     if (!roles) {
-      writeFileSync(path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), pngs[0]);
+      writeFileSync(path13.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), pngs[0]);
       return { jobId, metadata: { revisionUsage: usage } };
     }
     for (const [index, png] of pngs.entries()) {
-      writeFileSync(path12.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`), png);
+      writeFileSync(path13.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`), png);
     }
     return { jobId, metadata: { revisionUsage: usage, revisionMembers: roles, ...fps != null ? { revisionFps: fps } : {} } };
   }
@@ -9071,10 +9497,11 @@ var PixelLabProvider = class _PixelLabProvider {
       return this.pollAnimateRevision(jobId, context);
     }
     if (context?.spec?.revision) return this.pollRevision(jobId);
+    if (generator === "vfx") return this.pollVfx(jobId, context);
     if (generator === "imageProFlash") return this.pollRevision(jobId);
     if (generator === "pixflux") {
-      const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
-      if (existsSync7(file)) {
+      const file = path13.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+      if (existsSync8(file)) {
         const sourceUrl = `file://${file}`;
         return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }] };
       }
@@ -9117,6 +9544,120 @@ var PixelLabProvider = class _PixelLabProvider {
    * background job to ask afterwards the way `billedForJob` does for async
    * work.
    */
+  /**
+   * Render a `vfx` asset with the VFX workbench, which is synchronous and
+   * free. The frames are cut from the exported sheet and parked in the
+   * cache like pixflux's bytes; the export's download folder is recorded so
+   * `poll` can cut them again if the cache is cleared.
+   *
+   * A regeneration exports over the effect this asset rendered last time, so
+   * My effects keeps one entry per asset, unless that effect has changed on
+   * pixellab.ai since (someone moved its sliders) or is gone. Then a new
+   * effect is saved and the edited one is left alone.
+   */
+  async submitVfx(spec, context) {
+    const vfx = spec.vfx;
+    if (!this.mcp) throw new Error("PixelLab vfx renders over PixelLab's MCP server, which this provider was built without");
+    let sprite;
+    if (vfx.sprite && "reference" in vfx.sprite) {
+      sprite = vfx.sprite.reference;
+    } else if (vfx.sprite) {
+      const { file } = vfx.sprite;
+      if (!existsSync8(file)) throw new Error(`vfx sprite does not exist yet: ${file}`);
+      const bytes = readFileSync2(file);
+      if (sha256(bytes) !== vfx.sprite.sha256) {
+        throw new Error(`vfx sprite changed after the manifest was resolved: ${file}; run the command again`);
+      }
+      const format = imageMetadata(bytes)?.format ?? "png";
+      sprite = `data:image/${format};base64,${bytes.toString("base64")}`;
+    }
+    const previous = context?.replacedMetadata?.vfx ?? context?.lastGenerationMetadata?.vfx;
+    let replace;
+    let newEffect;
+    if (previous?.effectId) {
+      const upstream = await readSavedVfxRecipe(this.mcp, previous.effectId);
+      if (!upstream) newEffect = `effect ${previous.effectId} is no longer in My effects`;
+      else if (!previous.recipe || vfxRecipeSha256(upstream) !== vfxRecipeSha256(previous.recipe)) {
+        newEffect = `effect ${previous.effectId} changed on pixellab.ai since it was rendered; it was kept`;
+      } else replace = previous.effectId;
+    }
+    const jobId = randomUUID3();
+    const facts = (exported2, name2) => ({
+      effectId: exported2.effectId,
+      editUrl: exported2.editUrl,
+      name: name2,
+      imageId: exported2.imageId,
+      width: exported2.width,
+      height: exported2.height,
+      frames: exported2.frames,
+      fps: exported2.fps,
+      loop: exported2.loop,
+      anchor: exported2.anchor,
+      downloadBase: exported2.downloadBase,
+      files: exported2.files,
+      replaced: replace ?? null,
+      ...newEffect ? { newEffect } : {}
+    });
+    const { exported, recipe, name } = await runVfxWorkbench(this.mcp, {
+      preset: vfx.preset,
+      recipe: vfx.recipe?.recipe,
+      parts: vfx.parts,
+      sprite,
+      fps: vfx.fps,
+      name: vfx.name,
+      defaultName: vfx.name,
+      replace,
+      notes: `pixelkiln ${spec.styleId}/${spec.assetId}`,
+      // The effect exists from here on; record it before anything else can fail.
+      onExported: (done, effectName) => context?.checkpoint({ jobId, complete: true, metadata: { vfx: facts(done, effectName) } })
+    });
+    await this.cacheVfxFrames(jobId, exported);
+    return { jobId, metadata: { vfx: { ...facts(exported, name), recipe } } };
+  }
+  /** Cut an export's sheet into frames, with a sidecar `poll` reads without any lock metadata. */
+  async cacheVfxFrames(jobId, exported) {
+    const sheetFile = exported.files.find((file) => /\.png$/i.test(file));
+    const atlasFile = exported.files.find((file) => /\.json$/i.test(file));
+    if (!sheetFile) throw new Error(`PixelLab's vfx export listed no spritesheet: ${exported.files.join(", ")}`);
+    const sheet = await this.client.download(`${exported.downloadBase}${encodeURIComponent(sheetFile)}`);
+    const atlas = atlasFile ? JSON.parse((await this.client.download(`${exported.downloadBase}${encodeURIComponent(atlasFile)}`)).toString("utf8")) : void 0;
+    const frames = sliceVfxSheet(sheet, exported, atlas);
+    const dir = _PixelLabProvider.cacheDir("vfx");
+    frames.forEach((frame, index) => writeFileSync(path13.join(dir, `${jobId}-${index}.png`), frame));
+    writeFileSync(
+      path13.join(dir, `${jobId}.json`),
+      JSON.stringify({ effectId: exported.effectId, count: frames.length, fps: exported.fps, loop: exported.loop })
+    );
+  }
+  async pollVfx(jobId, context) {
+    const dir = _PixelLabProvider.cacheDir("vfx");
+    const sidecar = path13.join(dir, `${jobId}.json`);
+    const cached = () => {
+      if (!existsSync8(sidecar)) return null;
+      const facts2 = JSON.parse(readFileSync2(sidecar, "utf8"));
+      const files2 = Array.from({ length: facts2.count }, (_, index) => path13.join(dir, `${jobId}-${index}.png`));
+      return files2.every((file) => existsSync8(file)) ? { facts: facts2, files: files2 } : null;
+    };
+    let found = cached();
+    const recorded = context?.metadata?.vfx;
+    if (!found && recorded?.downloadBase && Array.isArray(recorded.files)) {
+      await this.cacheVfxFrames(jobId, recorded);
+      found = cached();
+    }
+    if (!found) {
+      return { status: "failed", error: "vfx frames are no longer cached locally; re-run submit for this asset (free)" };
+    }
+    const { facts, files } = found;
+    const sources = files.length === 1 ? [{ url: `file://${files[0]}` }] : files.map((file, index) => ({ url: `file://${file}`, role: `frame-${String(index).padStart(2, "0")}` }));
+    return {
+      status: "ready",
+      objectId: facts.effectId,
+      sourceUrl: sources[0].url,
+      sources,
+      ...files.length > 1 ? { metadata: { frameSet: { fps: facts.fps, count: files.length, loop: facts.loop } } } : {},
+      billed: null
+    };
+  }
   async pollCachedRevision(jobId, context) {
     const usage = context?.metadata?.revisionUsage;
     const roles = context?.metadata?.revisionMembers;
@@ -9126,10 +9667,10 @@ var PixelLabProvider = class _PixelLabProvider {
     };
     if (Array.isArray(roles) && roles.length) {
       const sources = roles.map((role, index) => ({
-        url: `file://${path12.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`)}`,
+        url: `file://${path13.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`)}`,
         role: String(role)
       }));
-      if (sources.some((source) => !existsSync7(source.url.slice("file://".length)))) return gone;
+      if (sources.some((source) => !existsSync8(source.url.slice("file://".length)))) return gone;
       const fps = context?.metadata?.revisionFps;
       const frames = sources.every((source) => source.role.startsWith("frame-"));
       return {
@@ -9141,8 +9682,8 @@ var PixelLabProvider = class _PixelLabProvider {
         billed: billedFromUsage(usage)
       };
     }
-    const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
-    if (!existsSync7(file)) return gone;
+    const file = path13.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+    if (!existsSync8(file)) return gone;
     const sourceUrl = `file://${file}`;
     return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed: billedFromUsage(usage) };
   }
@@ -9198,7 +9739,7 @@ var PixelLabProvider = class _PixelLabProvider {
         }
         const base64 = extractBase64(item);
         if (base64) {
-          const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+          const file = path13.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
           writeFileSync(file, Buffer.from(base64, "base64"));
           urls.push(`file://${file}`);
           continue;
@@ -9249,7 +9790,7 @@ var PixelLabProvider = class _PixelLabProvider {
       const candidate = done[key];
       const base64 = extractBase64(candidate);
       if (base64) {
-        const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+        const file = path13.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
         writeFileSync(file, Buffer.from(base64, "base64"));
         const sourceUrl = `file://${file}`;
         return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed };
@@ -9258,7 +9799,7 @@ var PixelLabProvider = class _PixelLabProvider {
     if (Array.isArray(done.images) && done.images.length) {
       const base64 = extractBase64(done.images[0]);
       if (base64) {
-        const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+        const file = path13.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
         writeFileSync(file, Buffer.from(base64, "base64"));
         const sourceUrl = `file://${file}`;
         return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed };
@@ -9292,7 +9833,7 @@ var PixelLabProvider = class _PixelLabProvider {
       for (const [index, candidate] of done.images.entries()) {
         const base64 = extractBase64(candidate);
         if (!base64) continue;
-        const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+        const file = path13.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
         writeFileSync(file, Buffer.from(base64, "base64"));
         urls.push(`file://${file}`);
       }
@@ -9322,7 +9863,7 @@ var PixelLabProvider = class _PixelLabProvider {
     for (const [index, candidate] of images.entries()) {
       const base64 = extractBase64(candidate);
       if (!base64) continue;
-      const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+      const file = path13.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
       writeFileSync(file, Buffer.from(base64, "base64"));
       urls.push(`file://${file}`);
     }
@@ -9420,7 +9961,7 @@ var PixelLabProvider = class _PixelLabProvider {
       for (const [index, tile] of tileset.tiles.entries()) {
         const slug2 = tile.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "tile";
         const role = `tile-${String(index).padStart(2, "0")}-${slug2}`;
-        const file = path12.join(_PixelLabProvider.cacheDir(), `${tilesetId}-${index}.png`);
+        const file = path13.join(_PixelLabProvider.cacheDir(), `${tilesetId}-${index}.png`);
         writeFileSync(file, Buffer.from(tile.image.base64, "base64"));
         sources.push({ url: `file://${file}`, role });
         terrainTiles.push({ role, corners: tile.corners, pattern4x4: tile.pattern_4x4 });
@@ -9450,7 +9991,7 @@ var PixelLabProvider = class _PixelLabProvider {
       const { image, usage } = await this.client.getIsometricTile(tileId);
       const backgroundJobId = context?.metadata?.backgroundJobId;
       const billed = billedFromUsage(usage) ?? await this.billedForJob(backgroundJobId);
-      const file = path12.join(_PixelLabProvider.cacheDir(), `${tileId}.png`);
+      const file = path13.join(_PixelLabProvider.cacheDir(), `${tileId}.png`);
       writeFileSync(file, Buffer.from(image.base64, "base64"));
       return {
         status: "ready",
@@ -9494,8 +10035,8 @@ var PixelLabProvider = class _PixelLabProvider {
       return { objectId: `${jobId}#${index}`, sourceUrl: url };
     }
     if (generator === "imagePro" || generator === "uiElement") {
-      const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
-      if (!existsSync7(file)) throw new Error(`${generator} job ${jobId} has no cached candidate at index ${index}`);
+      const file = path13.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+      if (!existsSync8(file)) throw new Error(`${generator} job ${jobId} has no cached candidate at index ${index}`);
       return { objectId: `${jobId}#${index}`, sourceUrl: `file://${file}` };
     }
     const promoted = await this.client.selectFrames(jobId, [index], commonTag);
@@ -9772,9 +10313,9 @@ var RetroDiffusionClient = class {
     if (!response.ok) throw new ProviderError("retrodiffusion", `Retro Diffusion download failed (${response.status})`, { status: response.status });
     return Buffer.from(await response.arrayBuffer());
   }
-  async call(path52, init = {}) {
+  async call(path53, init = {}) {
     if (!this.token) throw new Error("RD_API_KEY is not set");
-    const response = await this.request(`${this.baseUrl}${path52}`, {
+    const response = await this.request(`${this.baseUrl}${path53}`, {
       ...init,
       headers: {
         "Content-Type": "application/json",
@@ -10086,7 +10627,7 @@ function retroError(value) {
 import { createHash as createHash3 } from "crypto";
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync, writeFileSync as writeFileSync2 } from "fs";
 import os2 from "os";
-import path13 from "path";
+import path14 from "path";
 var DEFAULT_BASE_URL3 = "https://api.cloud.scenario.com/v1";
 var SOURCE_PROTOCOL2 = "scenario:";
 var SUBMIT_RETRIES = 8;
@@ -10469,7 +11010,7 @@ var ScenarioProvider = class _ScenarioProvider {
   }
 };
 function uploadCachePath() {
-  return process.env.SCENARIO_UPLOAD_CACHE ?? path13.join(os2.tmpdir(), "pixelkiln-scenario", "uploads.json");
+  return process.env.SCENARIO_UPLOAD_CACHE ?? path14.join(os2.tmpdir(), "pixelkiln-scenario", "uploads.json");
 }
 function uploadCacheKey(baseUrl, projectId, digest2) {
   return createHash3("sha256").update(`${baseUrl}
@@ -10487,7 +11028,7 @@ function readUploadCache() {
 function writeUploadCache(key, assetId) {
   try {
     const file = uploadCachePath();
-    mkdirSync2(path13.dirname(file), { recursive: true });
+    mkdirSync2(path14.dirname(file), { recursive: true });
     const tmp = `${file}.${process.pid}.tmp`;
     writeFileSync2(tmp, JSON.stringify({ ...readUploadCache(), [key]: assetId }));
     renameSync(tmp, file);
@@ -10747,9 +11288,9 @@ registerProvider({
 });
 
 // src/manifest.ts
-import { readFile as readFile6 } from "fs/promises";
-import { existsSync as existsSync8 } from "fs";
-import path14 from "path";
+import { readFile as readFile7 } from "fs/promises";
+import { existsSync as existsSync9 } from "fs";
+import path15 from "path";
 
 // src/loop-directions.ts
 var SINGLE_OUTPUT_FIELDS = ["file", "cell", "remoteId", "source", "sourceByStyle", "outputRole"];
@@ -10838,9 +11379,9 @@ function isObject2(value) {
 
 // src/manifest.ts
 async function loadManifest(manifestPath) {
-  const abs = path14.resolve(manifestPath);
-  if (!existsSync8(abs)) throw new ProjectError(`No manifest at ${abs}`);
-  const expansion = expandLoopDirections(JSON.parse(await readFile6(abs, "utf8")));
+  const abs = path15.resolve(manifestPath);
+  if (!existsSync9(abs)) throw new ProjectError(`No manifest at ${abs}`);
+  const expansion = expandLoopDirections(JSON.parse(await readFile7(abs, "utf8")));
   if (expansion.issues.length) {
     throw new ProjectError(`Manifest at ${abs} is invalid:
 ${expansion.issues.map((i) => `  ${i}`).join("\n")}`);
@@ -10895,7 +11436,7 @@ ${issues}`);
       if (fromStyle) {
         if (!styleIds.has(fromStyle)) {
           unknownReferences.push(`assets.${assetId}.revision.fromStyle: unknown style "${fromStyle}"`);
-        } else if (parent && parent.styles.length && !parent.styles.includes(fromStyle)) {
+        } else if (parent && !assetInStyle(parent, fromStyle, parsed.data.styles[fromStyle])) {
           unknownReferences.push(
             `assets.${assetId}.revision.fromStyle: "${asset.revision.from}" is not in style "${fromStyle}"`
           );
@@ -10942,7 +11483,11 @@ ${issues}`);
 ${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
   }
   const loopFamilies = Object.keys(expansion.families).length ? { loopFamilies: expansion.families } : {};
-  return { manifest: parsed.data, root: path14.dirname(abs), path: abs, ...loopFamilies };
+  return { manifest: parsed.data, root: path15.dirname(abs), path: abs, ...loopFamilies };
+}
+function assetInStyle(asset, styleId, style) {
+  if (asset.styles.length) return asset.styles.includes(styleId);
+  return style?.generator === "vfx" === Boolean(asset.vfx);
 }
 function parentAssetId(asset) {
   return asset?.revision?.from ?? asset?.state?.of ?? asset?.animation?.of ?? asset?.portrait?.of ?? asset?.outfit?.of;
@@ -11046,8 +11591,8 @@ async function resolveSpecs(loaded, filter) {
     const needed = /* @__PURE__ */ new Set();
     for (const assetId of resolutionAssetIds) {
       const asset = manifest.assets[assetId];
-      if (asset?.styles.length && !asset.styles.includes(styleId)) continue;
-      const fromStyle = asset?.revision?.fromStyle;
+      if (!asset || !assetInStyle(asset, styleId, manifest.styles[styleId])) continue;
+      const fromStyle = asset.revision?.fromStyle;
       if (fromStyle && fromStyle !== styleId) needed.add(fromStyle);
     }
     styleDependencies.set(styleId, needed);
@@ -11076,11 +11621,11 @@ async function resolveSpecs(loaded, filter) {
   const styleFinalizers = /* @__PURE__ */ new Map();
   const styleImageCache = /* @__PURE__ */ new Map();
   async function loadStyleImage(rel, what = "Style image") {
-    const abs = path14.resolve(root, rel);
+    const abs = path15.resolve(root, rel);
     let hit = styleImageCache.get(abs);
     if (!hit) {
-      if (!existsSync8(abs)) throw new Error(`${what} not found: ${abs}`);
-      const buf = await readFile6(abs);
+      if (!existsSync9(abs)) throw new Error(`${what} not found: ${abs}`);
+      const buf = await readFile7(abs);
       const metadata = imageMetadata(buf);
       if (!metadata) throw new Error(`${what} is not a readable PNG or JPEG: ${abs}`);
       if (metadata.width < 1 || metadata.height < 1) {
@@ -11106,14 +11651,14 @@ async function resolveSpecs(loaded, filter) {
       styleImageDimensions.push(loadedImage);
     }
     const resolvedImages = style.styleImages.map((image) => {
-      const hit = styleImageCache.get(path14.resolve(root, image.path));
+      const hit = styleImageCache.get(path15.resolve(root, image.path));
       return { base64: hit.base64, width: hit.width, height: hit.height, format: hit.format };
     });
     const styleSpecs = /* @__PURE__ */ new Map();
     const providerInputIdentities = /* @__PURE__ */ new Map();
     for (const [assetId, asset] of Object.entries(manifest.assets)) {
       if (!resolutionAssetIds.has(assetId)) continue;
-      if (asset.styles.length && !asset.styles.includes(styleId)) continue;
+      if (!assetInStyle(asset, styleId, style)) continue;
       const generator = style.generator;
       if (!activeProvider.supports(generator)) {
         throw new Error(`Provider "${activeProvider.id}" does not support generator "${generator}"`);
@@ -11133,6 +11678,15 @@ async function resolveSpecs(loaded, filter) {
       const providerInputs = inputResolution.inputs;
       const providerInputIdentity = inputResolution.identity ?? providerInputs;
       providerInputIdentities.set(assetId, providerInputIdentity);
+      if (asset.vfx && generator !== "vfx") {
+        throw new Error(`assets.${assetId}: vfx needs a vfx style; "${styleId}" generates ${generator}`);
+      }
+      if (generator === "vfx" && !asset.vfx && !asset.mirror && !asset.revision) {
+        throw new Error(
+          `assets.${assetId}: style "${styleId}" renders effects; give the asset a vfx block, or make it a mirror or revision of one`
+        );
+      }
+      const vfx = generator === "vfx" && asset.vfx ? await resolveVfxShape(root, assetId, asset.vfx, `pixelkiln:${styleId}/${assetId}`) : void 0;
       let width;
       let height;
       let size;
@@ -11160,6 +11714,11 @@ async function resolveSpecs(loaded, filter) {
         size = asset.size ?? style.size ?? 64;
         width = size;
         height = size;
+      } else if (generator === "vfx") {
+        const canvas = vfx?.recipe?.recipe.canvas;
+        width = typeof canvas?.w === "number" ? canvas.w : asset.width ?? style.size ?? 64;
+        height = typeof canvas?.h === "number" ? canvas.h : asset.height ?? style.size ?? 64;
+        size = Math.max(width, height);
       } else if (generator === "uiAsset" || generator === "uiElement") {
         width = asset.width ?? style.size ?? 256;
         height = asset.height ?? style.size ?? 256;
@@ -11202,14 +11761,14 @@ async function resolveSpecs(loaded, filter) {
         terrainUpperDescription = wrap(parsed.upper);
         terrainTransitionDescription = parsed.transition ? wrap(parsed.transition) : void 0;
         prompt = subject.trim();
-      } else if ((generator === "character" || generator === "objectPro") && characterKind !== "base") {
+      } else if ((generator === "character" || generator === "objectPro") && characterKind !== "base" || vfx) {
         prompt = subject.trim();
       } else {
         prompt = [style.promptPrefix, subject, style.promptSuffix].map((p) => p.trim()).filter(Boolean).join(", ");
       }
-      const relFile = asset.file ?? path14.join(asset.category ?? "", `${assetId}.png`);
-      const outFile = path14.resolve(root, style.outDir, relFile);
-      const qualityOutFile = style.quality ? path14.resolve(root, style.quality.outDir, pngPath(relFile)) : void 0;
+      const relFile = asset.file ?? path15.join(asset.category ?? "", `${assetId}.png`);
+      const outFile = path15.resolve(root, style.outDir, relFile);
+      const qualityOutFile = style.quality ? path15.resolve(root, style.quality.outDir, pngPath(relFile)) : void 0;
       const tileSize = generator === "tiles" ? size : style.tileSize ?? 32;
       const tileVariations = tileFeatureOutputCount(generator === "tiles" ? style.tileFeature : void 0) ?? tileVariationCount(countNumberedDescriptions(prompt));
       const terrainTiles = generator === "terrain" ? terrainTileCount(style.terrainTransitionSize) : 0;
@@ -11280,6 +11839,7 @@ async function resolveSpecs(loaded, filter) {
         // A portrait needs a character style (refused above), so an
         // objectPro asset is only ever a base, state, or animation.
         ...generator === "objectPro" && !asset.revision && characterKind !== "portrait" ? { objectPro: await resolveObjectProShape(assetId, asset, style, characterKind, { root, load: loadStyleImage }) } : {},
+        ...vfx ? { vfx } : {},
         cost: generator === "tiles" ? tilesCost(tileSize, tileVariations) : generator === "terrain" ? tilesCost(size, terrainTiles) : generator === "isometricTile" ? isometricTileCost() : generationCost(width, height, generator),
         costUnit: "generations",
         candidates: generator === "tiles" ? tileVariations : generator === "terrain" ? terrainTiles : generator === "1dir" || generator === "imagePro" ? candidateCount(size) : 1
@@ -11304,7 +11864,7 @@ async function resolveSpecs(loaded, filter) {
             minGridConfidence: style.quality.minGridConfidence,
             ...style.quality.minTransparency == null ? {} : { minTransparency: style.quality.minTransparency },
             ...style.quality.fixerRevision ? { fixerRevision: style.quality.fixerRevision } : {},
-            ...style.quality.fixerPython ? { fixerPython: path14.resolve(root, style.quality.fixerPython) } : {},
+            ...style.quality.fixerPython ? { fixerPython: path15.resolve(root, style.quality.fixerPython) } : {},
             ...style.quality.fps == null ? {} : { fps: style.quality.fps }
           }
         } : {},
@@ -11387,7 +11947,7 @@ async function resolveSpecs(loaded, filter) {
         const file = memberPath(anchorSpec.outFile, "south", 0, anchorSpec.character.directions, MediaType.PNG);
         resolved.character = {
           ...resolved.character,
-          styleAnchor: { assetId: anchorId, spec: anchorSpec, file, sha256: existsSync8(file) ? await sha256File(file) : null }
+          styleAnchor: { assetId: anchorId, spec: anchorSpec, file, sha256: existsSync9(file) ? await sha256File(file) : null }
         };
       }
       const characterParent = asset.state?.of ?? asset.animation?.of ?? asset.portrait?.of;
@@ -11400,7 +11960,7 @@ async function resolveSpecs(loaded, filter) {
           parentAssetId: characterParent,
           parentSpec,
           parentFile,
-          parentSha256: existsSync8(parentFile) ? await sha256File(parentFile) : null,
+          parentSha256: existsSync9(parentFile) ? await sha256File(parentFile) : null,
           // A state and its animations keep the engine and rotations of the base.
           mode: resolved.character.kind === "base" ? resolved.character.mode : parentSpec.character?.mode ?? resolved.character.mode,
           directions: resolved.character.kind === "base" ? resolved.character.directions : parentSpec.character?.directions ?? resolved.character.directions
@@ -11418,7 +11978,7 @@ async function resolveSpecs(loaded, filter) {
           parentAssetId: characterParent,
           parentSpec,
           parentFile,
-          parentSha256: existsSync8(parentFile) ? await sha256File(parentFile) : null,
+          parentSha256: existsSync9(parentFile) ? await sha256File(parentFile) : null,
           // A state and its animations keep the base's own rotation count.
           directions: resolved.objectPro.kind === "base" ? resolved.objectPro.directions : parentSpec.objectPro.directions
         };
@@ -11440,7 +12000,7 @@ async function resolveSpecs(loaded, filter) {
           animation: sourceSpec.character.animation,
           outfit: {
             reference: {
-              path: path14.resolve(root, asset.outfit.reference),
+              path: path15.resolve(root, asset.outfit.reference),
               sha256: referenceImage.hash,
               width: referenceImage.width,
               height: referenceImage.height,
@@ -11463,23 +12023,23 @@ async function resolveSpecs(loaded, filter) {
         }
         const sourceStyleId = asset.revision.fromStyle && asset.revision.fromStyle !== styleId ? asset.revision.fromStyle : void 0;
         const sourceSpec = sourceStyleId ? await styleFinalizers.get(sourceStyleId)(asset.revision.from) : await finalize(asset.revision.from);
-        const sourceStem = sourceSpec.quality?.outFile ?? (sourceSpec.source ? path14.resolve(root, sourceSpec.source) : sourceSpec.outFile);
+        const sourceStem = sourceSpec.quality?.outFile ?? (sourceSpec.source ? path15.resolve(root, sourceSpec.source) : sourceSpec.outFile);
         const sourceMembers = await revisionSourceMembers(sourceStem, `revision source ${asset.revision.from}`);
         const sourceFile = sourceMembers?.[0]?.file ?? sourceStem;
         const sourceImage = sourceMembers ? { ...sourceMembers[0], hash: sha256(JSON.stringify(sourceMembers.map((member) => member.sha256))) } : await optionalRevisionImage(sourceFile, "revision source");
         const sourceFps = sourceSpec.character?.animation?.fps ?? sourceSpec.objectPro?.animation?.fps ?? sourceSpec.revision?.fps ?? sourceSpec.revision?.sourceFps;
-        const maskFile = asset.revision.mask ? path14.resolve(root, asset.revision.mask) : void 0;
+        const maskFile = asset.revision.mask ? path15.resolve(root, asset.revision.mask) : void 0;
         const maskImage = maskFile ? await optionalRevisionImage(maskFile, "revision mask", "png") : null;
         if (sourceImage && maskImage && (sourceImage.width !== maskImage.width || sourceImage.height !== maskImage.height)) {
           throw new Error(
             `Revision mask for ${styleId}/${assetId} is ${maskImage.width}x${maskImage.height}; source ${asset.revision.from} is ${sourceImage.width}x${sourceImage.height}`
           );
         }
-        const paletteImageFile = asset.revision.paletteImage ? path14.resolve(root, asset.revision.paletteImage) : void 0;
+        const paletteImageFile = asset.revision.paletteImage ? path15.resolve(root, asset.revision.paletteImage) : void 0;
         const paletteImage = paletteImageFile ? await optionalRevisionImage(paletteImageFile, "revision palette image", "png") : null;
-        const lastFrameFile = asset.revision.lastFrame ? path14.resolve(root, asset.revision.lastFrame) : void 0;
+        const lastFrameFile = asset.revision.lastFrame ? path15.resolve(root, asset.revision.lastFrame) : void 0;
         const lastFrame = lastFrameFile ? await optionalRevisionImage(lastFrameFile, "revision last frame") : null;
-        const keypointsFile = asset.revision.keypointsFile ? path14.resolve(root, asset.revision.keypointsFile) : void 0;
+        const keypointsFile = asset.revision.keypointsFile ? path15.resolve(root, asset.revision.keypointsFile) : void 0;
         const keypoints = keypointsFile ? await optionalSkeletonSet(keypointsFile) : null;
         resolved.revision = {
           mode: asset.revision.mode,
@@ -11649,7 +12209,7 @@ async function resolveSpecs(loaded, filter) {
   return specs;
 }
 function pngPath(file) {
-  const extension = path14.extname(file);
+  const extension = path15.extname(file);
   return extension ? `${file.slice(0, -extension.length)}.png` : `${file}.png`;
 }
 async function resolveMapScene(root, styleId, assetId, generator, scene, provider) {
@@ -11659,12 +12219,12 @@ async function resolveMapScene(root, styleId, assetId, generator, scene, provide
   if (!provider.supportsMapScene) {
     throw new Error(`assets.${assetId}.scene: provider "${provider.id}" cannot draw into a scene; PixelLab's /map-objects can`);
   }
-  const file = path14.resolve(root, scene.image);
+  const file = path15.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 = path14.resolve(root, placement.mask);
+    const maskFile = path15.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(
@@ -11678,9 +12238,38 @@ async function resolveMapScene(root, styleId, assetId, generator, scene, provide
   }
   return "oval" in placement ? { ...base, placement: { type: "oval", fraction: placement.oval } } : { ...base, placement: { type: "rectangle", fraction: placement.rectangle } };
 }
+async function resolveVfxShape(root, assetId, vfx, defaultName) {
+  let recipe;
+  let recordedSprite;
+  if (vfx.recipe) {
+    const file = path15.resolve(root, vfx.recipe);
+    if (!existsSync9(file)) throw new Error(`assets.${assetId}.vfx.recipe: VFX recipe not found: ${file}`);
+    const read = await readVfxRecipe(file).catch((error) => {
+      throw new Error(`assets.${assetId}.vfx.recipe: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    recipe = { file, sha256: vfxRecipeSha256(read.recipe), recipe: read.recipe };
+    recordedSprite = read.sprite;
+  }
+  const spriteRef = vfx.sprite ? isVfxReference(vfx.sprite) ? vfx.sprite : path15.resolve(root, vfx.sprite) : recordedSprite;
+  let sprite;
+  if (spriteRef && isVfxReference(spriteRef)) {
+    sprite = { reference: spriteRef };
+  } else if (spriteRef) {
+    const image = await optionalRevisionImage(spriteRef, `assets.${assetId}.vfx.sprite`);
+    sprite = { file: spriteRef, sha256: image?.hash ?? null, width: image?.width ?? null, height: image?.height ?? null, format: image?.format ?? null };
+  }
+  return {
+    ...vfx.preset ? { preset: vfx.preset } : {},
+    ...recipe ? { recipe } : {},
+    ...vfx.parts?.length ? { parts: vfx.parts } : {},
+    ...sprite ? { sprite } : {},
+    ...vfx.fps !== void 0 ? { fps: vfx.fps } : {},
+    name: vfx.name ?? defaultName
+  };
+}
 async function optionalRevisionImage(file, label, requiredFormat) {
-  if (!existsSync8(file)) return null;
-  const bytes = await readFile6(file);
+  if (!existsSync9(file)) return null;
+  const bytes = await readFile7(file);
   const metadata = imageMetadata(bytes);
   if (!metadata) throw new Error(`${label} is not a readable PNG or JPEG: ${file}`);
   if (requiredFormat && metadata.format !== requiredFormat) {
@@ -11689,8 +12278,8 @@ async function optionalRevisionImage(file, label, requiredFormat) {
   return { hash: sha256(bytes), ...metadata };
 }
 async function optionalSkeletonSet(file) {
-  if (!existsSync8(file)) return null;
-  const bytes = await readFile6(file);
+  if (!existsSync9(file)) return null;
+  const bytes = await readFile7(file);
   let json;
   try {
     json = JSON.parse(bytes.toString("utf8"));
@@ -11700,17 +12289,17 @@ async function optionalSkeletonSet(file) {
   return { hash: sha256(bytes), skeleton: parseSkeletonSet(json, file) };
 }
 async function revisionSourceMembers(stem, label) {
-  if (existsSync8(stem)) return null;
+  if (existsSync9(stem)) return null;
   const at = (role) => memberPath(stem, role, 0, 2, MediaType.PNG);
   let roles = [];
   for (const set of [CHARACTER_DIRECTIONS_8, CHARACTER_DIRECTIONS_4]) {
-    if (set.every((direction) => existsSync8(at(direction)))) {
+    if (set.every((direction) => existsSync9(at(direction)))) {
       roles = [...set];
       break;
     }
   }
   if (!roles.length) {
-    for (let index = 0; existsSync8(at(`frame-${String(index).padStart(2, "0")}`)); index++) {
+    for (let index = 0; existsSync9(at(`frame-${String(index).padStart(2, "0")}`)); index++) {
       roles.push(`frame-${String(index).padStart(2, "0")}`);
     }
   }
@@ -11736,8 +12325,8 @@ async function resolveStyleImages(loaded, styleId) {
   if (!style) throw new Error(`Unknown style "${styleId}"`);
   const out = [];
   for (const img of style.styleImages) {
-    const file = path14.resolve(loaded.root, img.path);
-    const buf = await readFile6(file);
+    const file = path15.resolve(loaded.root, img.path);
+    const buf = await readFile7(file);
     const metadata = imageMetadata(buf);
     if (!metadata) throw new Error(`Style image is not a readable PNG or JPEG: ${file}`);
     if (metadata.width < 1 || metadata.height < 1) {
@@ -11764,7 +12353,7 @@ async function resolveCharacterShape(asset, style, kind, files) {
   };
   if (asset.concept) {
     const image = await files.load(asset.concept, "Concept image");
-    shape.concept = { path: path14.resolve(files.root, asset.concept), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+    shape.concept = { path: path15.resolve(files.root, asset.concept), sha256: image.hash, width: image.width, height: image.height, format: image.format };
   }
   if (asset.reference) {
     const byDirection = typeof asset.reference === "string" ? { south: asset.reference } : asset.reference;
@@ -11772,7 +12361,7 @@ async function resolveCharacterShape(asset, style, kind, files) {
     for (const [direction, rel] of Object.entries(byDirection)) {
       const image = await files.load(rel, `Reference sprite (${direction})`);
       shape.reference[direction] = {
-        path: path14.resolve(files.root, rel),
+        path: path15.resolve(files.root, rel),
         sha256: image.hash,
         width: image.width,
         height: image.height,
@@ -11793,7 +12382,7 @@ async function resolveCharacterShape(asset, style, kind, files) {
     const animationMode = asset.animation.mode ?? (asset.animation.template ? "template" : "v3");
     const pose = async (rel, what) => {
       const image = await files.load(rel, what);
-      return { path: path14.resolve(files.root, rel), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+      return { path: path15.resolve(files.root, rel), sha256: image.hash, width: image.width, height: image.height, format: image.format };
     };
     shape.animation = {
       mode: animationMode,
@@ -11824,7 +12413,7 @@ async function resolveObjectProShape(assetId, asset, style, kind, files) {
     const south = typeof asset.reference === "string" ? asset.reference : asset.reference.south;
     if (south) {
       const image = await files.load(south, "Reference sprite");
-      shape.reference = { path: path14.resolve(files.root, south), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+      shape.reference = { path: path15.resolve(files.root, south), sha256: image.hash, width: image.width, height: image.height, format: image.format };
     }
   }
   if (asset.state) {
@@ -11852,7 +12441,7 @@ async function resolveObjectProShape(assetId, asset, style, kind, files) {
     }
     const pose = async (rel, what) => {
       const image = await files.load(rel, what);
-      return { path: path14.resolve(files.root, rel), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+      return { path: path15.resolve(files.root, rel), sha256: image.hash, width: image.width, height: image.height, format: image.format };
     };
     shape.animation = {
       mode: asset.animation.mode ?? "v3",
@@ -11869,9 +12458,9 @@ async function resolveObjectProShape(assetId, asset, style, kind, files) {
 }
 
 // src/pipeline/fetch.ts
-import { existsSync as existsSync9, readFileSync as readFileSync4 } from "fs";
-import { mkdir as mkdir4, readFile as readFile7, rename as rename4, rm as rm4, writeFile as writeFile4 } from "fs/promises";
-import path15 from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync4 } from "fs";
+import { mkdir as mkdir5, readFile as readFile8, rename as rename4, rm as rm4, writeFile as writeFile5 } from "fs/promises";
+import path16 from "path";
 
 // src/source-url.ts
 var SENSITIVE_QUERY_KEYS = /* @__PURE__ */ new Set([
@@ -11917,7 +12506,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   const result = { downloaded: 0, skipped: 0, failed: 0, ...opts.refresh ? { unchanged: 0 } : {} };
   const specByKey = new Map(specs.map((s) => [lockKey(s.styleId, s.assetId), s]));
   normalizeLockOutputPaths(lock, specs);
-  const cacheDir = opts.cacheDir === false ? null : path15.resolve(opts.cacheDir ?? path15.join(path15.dirname(lockPath), ".pixelkiln", "cache"));
+  const cacheDir = opts.cacheDir === false ? null : path16.resolve(opts.cacheDir ?? path16.join(path16.dirname(lockPath), ".pixelkiln", "cache"));
   const pending = Object.entries(lock.entries).filter(([key, e]) => {
     if (e.provider !== provider.id || !specByKey.has(key)) return false;
     if (specByKey.get(key)?.mirror) return false;
@@ -11928,14 +12517,14 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
     if (spec && e.specHash === spec.specHash && e.outputs.length && !postprocessCurrent(e, spec)) {
       return Boolean(opts.force) || e.outputs.every((output) => {
         const file = resolveOutputPath(output.path, spec.root);
-        return existsSync9(file) && sha256(readFileSync4(file)) === output.sha256;
+        return existsSync10(file) && sha256(readFileSync4(file)) === output.sha256;
       });
     }
     if (!opts.repair) return false;
     if (e.outputs.length === 0 || !spec) return true;
     return e.outputs.some((output) => {
       const file = resolveOutputPath(output.path, spec.root);
-      if (!existsSync9(file)) return true;
+      if (!existsSync10(file)) return true;
       const current = sha256(readFileSync4(file));
       if (current === output.sha256) return false;
       return Boolean(opts.force) || (e.supersededOutputs ?? []).some((old) => old.sha256 === current);
@@ -12019,21 +12608,21 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             if (!source.url) throw new Error(`no durable source URL to refresh ${source.role ?? "asset"} from`);
             fresh = await provider.download(source.url);
             if (recorded && sha256(fresh) === recordedRaw && !reapply) {
-              log2(`  current ${path15.relative(process.cwd(), target)}`);
+              log2(`  current ${path16.relative(process.cwd(), target)}`);
               outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
               continue;
             }
           }
           let raw = null;
           let final = null;
-          if (existsSync9(target)) {
+          if (existsSync10(target)) {
             const currentHash = await sha256File(target);
             if (recorded && currentHash === recorded.sha256) {
               if (!fresh && !reapply) {
                 if (cacheDir) {
                   await cacheMedia(
                     cacheDir,
-                    await readFile7(target),
+                    await readFile8(target),
                     recorded.mediaType ?? MediaType.PNG,
                     recorded.sha256
                   );
@@ -12042,10 +12631,10 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
                 continue;
               }
               if (reapply && !fresh) {
-                if (!recorded.raw) raw = await readFile7(target);
-                log2(`  reapply ${path15.relative(process.cwd(), target)}`);
+                if (!recorded.raw) raw = await readFile8(target);
+                log2(`  reapply ${path16.relative(process.cwd(), target)}`);
               } else {
-                log2(`  changed ${path15.relative(process.cwd(), target)} (upstream)`);
+                log2(`  changed ${path16.relative(process.cwd(), target)} (upstream)`);
               }
             } else {
               const superseded = (entry.supersededOutputs ?? []).find(
@@ -12066,14 +12655,14 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
               }
               if (outgoing && cacheDir) {
                 try {
-                  const oldBytes = await readFile7(target);
+                  const oldBytes = await readFile8(target);
                   const oldMediaType = detectMediaType(oldBytes);
                   if (oldMediaType) await cacheMedia(cacheDir, oldBytes, oldMediaType, currentHash);
                 } catch {
                 }
               }
               log2(
-                `  replace ${path15.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
+                `  replace ${path16.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
               );
             }
           }
@@ -12082,7 +12671,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           } else if (!raw && recorded && cacheDir) {
             if (!reapply) final = await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType);
             if (!final && recordedRaw) raw = await readCachedMedia(cacheDir, recordedRaw, expectedMediaType);
-            if (final || raw) log2(`  cached  ${path15.relative(process.cwd(), target)}`);
+            if (final || raw) log2(`  cached  ${path16.relative(process.cwd(), target)}`);
           }
           if (!final && !raw) {
             if (!source.url) {
@@ -12109,13 +12698,13 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             buf = processed.bytes;
             if (processed.changed) {
               rawHash = sha256(raw);
-              log2(`  snapped ${path15.relative(process.cwd(), target)} to ${wanted.palette.colors.length} colours`);
+              log2(`  snapped ${path16.relative(process.cwd(), target)} to ${wanted.palette.colors.length} colours`);
             }
           }
           if (cacheDir) await cacheMedia(cacheDir, buf, mediaType);
-          await mkdir4(path15.dirname(target), { recursive: true });
+          await mkdir5(path16.dirname(target), { recursive: true });
           const tmp = `${target}.pixelkiln.tmp`;
-          await writeFile4(tmp, buf);
+          await writeFile5(tmp, buf);
           outputs.push({
             path: portableOutputPath(target, spec.root),
             sha256: sha256(buf),
@@ -12127,7 +12716,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           await saveLock(lockPath, lock);
           await rename4(tmp, target);
           wrote = true;
-          log2(`  wrote   ${path15.relative(process.cwd(), target)}`);
+          log2(`  wrote   ${path16.relative(process.cwd(), target)}`);
         }
         if (opts.refresh && !wrote) {
           if (rotated) {
@@ -12171,10 +12760,10 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   return result;
 }
 async function readCachedMedia(cacheDir, hash, mediaType) {
-  const file = path15.join(cacheDir, cacheFileName(hash, mediaType));
-  if (!existsSync9(file)) return null;
+  const file = path16.join(cacheDir, cacheFileName(hash, mediaType));
+  if (!existsSync10(file)) return null;
   try {
-    const buf = await readFile7(file);
+    const buf = await readFile8(file);
     if (sha256(buf) !== hash) return null;
     validateMedia(buf, mediaType);
     return buf;
@@ -12185,15 +12774,15 @@ async function readCachedMedia(cacheDir, hash, mediaType) {
 async function cacheMedia(cacheDir, buf, mediaType, knownHash) {
   const hash = knownHash ?? sha256(buf);
   validateMedia(buf, mediaType);
-  const file = path15.join(cacheDir, cacheFileName(hash, mediaType));
+  const file = path16.join(cacheDir, cacheFileName(hash, mediaType));
   if (await readCachedMedia(cacheDir, hash, mediaType)) return;
-  await mkdir4(cacheDir, { recursive: true });
+  await mkdir5(cacheDir, { recursive: true });
   const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
-  await writeFile4(tmp, buf);
+  await writeFile5(tmp, buf);
   try {
     await rename4(tmp, file);
   } catch (err) {
-    if (!existsSync9(file)) throw err;
+    if (!existsSync10(file)) throw err;
   } finally {
     await rm4(tmp, { force: true });
   }
@@ -12213,7 +12802,7 @@ async function pushTags(provider, specs, lock, opts = {}) {
   for (const [key, entry] of Object.entries(lock.entries)) {
     const spec = specByKey.get(key);
     if (!spec || entry.provider !== provider.id || !entry.objectId) continue;
-    if (entry.generator === "pixflux") continue;
+    if (entry.generator === "pixflux" || entry.generator === "vfx") continue;
     if (!provider.setTags) return tagged;
     try {
       await provider.setTags(entry.objectId, spec.tags, entry.generator);
@@ -12226,13 +12815,13 @@ async function pushTags(provider, specs, lock, opts = {}) {
 }
 
 // src/pipeline/adopt.ts
-import { existsSync as existsSync11 } from "fs";
-import { readFile as readFile9, writeFile as writeFile6 } from "fs/promises";
-import path16 from "path";
+import { existsSync as existsSync12 } from "fs";
+import { readFile as readFile10, writeFile as writeFile7 } from "fs/promises";
+import path17 from "path";
 
 // src/cache.ts
-import { mkdir as mkdir5, readFile as readFile8, rename as rename5, rm as rm5, writeFile as writeFile5 } from "fs/promises";
-import { existsSync as existsSync10 } from "fs";
+import { mkdir as mkdir6, readFile as readFile9, rename as rename5, rm as rm5, writeFile as writeFile6 } from "fs/promises";
+import { existsSync as existsSync11 } from "fs";
 import pathModule from "path";
 import { z as z4 } from "zod";
 var HashCacheSchema = z4.object({
@@ -12247,10 +12836,10 @@ function isSha256Hash(value) {
 function parseCache(value) {
   return HashCacheSchema.parse(value);
 }
-async function loadCache(path52) {
-  if (!existsSync10(path52)) return { version: 1, hashes: {} };
+async function loadCache(path53) {
+  if (!existsSync11(path53)) return { version: 1, hashes: {} };
   try {
-    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile8(path52, "utf8")));
+    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile9(path53, "utf8")));
     if (!parsed.success) return { version: 1, hashes: {} };
     return {
       version: 1,
@@ -12262,18 +12851,18 @@ async function loadCache(path52) {
     return { version: 1, hashes: {} };
   }
 }
-async function saveCache(path52, cache) {
+async function saveCache(path53, cache) {
   const sorted = {};
   for (const key of Object.keys(cache.hashes).sort()) {
     const hash = cache.hashes[key];
     if (!isSha256Hash(hash)) throw new Error(`Refusing to cache invalid SHA-256 for ${key}`);
     sorted[key] = hash;
   }
-  await mkdir5(pathModule.dirname(pathModule.resolve(path52)), { recursive: true });
-  const tmp = `${path52}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await mkdir6(pathModule.dirname(pathModule.resolve(path53)), { recursive: true });
+  const tmp = `${path53}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
-    await writeFile5(tmp, JSON.stringify({ version: 1, hashes: sorted }, null, 2) + "\n");
-    await rename5(tmp, path52);
+    await writeFile6(tmp, JSON.stringify({ version: 1, hashes: sorted }, null, 2) + "\n");
+    await rename5(tmp, path53);
   } finally {
     await rm5(tmp, { force: true });
   }
@@ -12307,11 +12896,11 @@ async function adopt(provider, specs, lock, lockPath, opts = {}) {
   const localByHash = /* @__PURE__ */ new Map();
   const unmatchedLocal = [];
   for (const spec of specs) {
-    if (!existsSync11(spec.outFile)) {
+    if (!existsSync12(spec.outFile)) {
       unmatchedLocal.push(`${spec.styleId}/${spec.assetId} (no file at ${spec.outFile})`);
       continue;
     }
-    const bytes = await readFile9(spec.outFile);
+    const bytes = await readFile10(spec.outFile);
     try {
       decodePng(bytes);
     } catch (err) {
@@ -12431,7 +13020,7 @@ async function writePromptsBack(manifestPath, lock, opts = {}) {
   const log2 = opts.onProgress ?? (() => {
   });
   const selectedAssets = opts.assetIds ? new Set(opts.assetIds) : null;
-  const raw = JSON.parse(await readFile9(manifestPath, "utf8"));
+  const raw = JSON.parse(await readFile10(manifestPath, "utf8"));
   const best = /* @__PURE__ */ new Map();
   for (const entry of Object.values(lock.entries)) {
     if (opts.provider && entry.provider !== opts.provider) continue;
@@ -12453,7 +13042,7 @@ async function writePromptsBack(manifestPath, lock, opts = {}) {
       stillEmpty.push(id);
     }
   }
-  await writeFile6(manifestPath, JSON.stringify(raw, null, 2) + "\n");
+  await writeFile7(manifestPath, JSON.stringify(raw, null, 2) + "\n");
   log2(`  filled ${filled} prompt(s) from adopted objects`);
   return { filled, stillEmpty };
 }
@@ -12464,9 +13053,9 @@ function formatUnmatchedRemote(objects, limit = 15) {
 }
 
 // src/pipeline/adopt-characters.ts
-import { existsSync as existsSync12 } from "fs";
-import { mkdir as mkdir6, readFile as readFile10, writeFile as writeFile7 } from "fs/promises";
-import path17 from "path";
+import { existsSync as existsSync13 } from "fs";
+import { mkdir as mkdir7, readFile as readFile11, writeFile as writeFile8 } from "fs/promises";
+import path18 from "path";
 async function adoptCharacters(provider, specs, lock, lockPath, opts) {
   const log2 = opts.onProgress ?? (() => {
   });
@@ -12517,12 +13106,12 @@ async function adoptCharacters(provider, specs, lock, lockPath, opts) {
       const bytes = await download(source.url);
       const hash = sha256(bytes);
       const file = expectedOutputPath(spec, source.role, index, sources.length);
-      if (existsSync12(file)) {
-        if (sha256(await readFile10(file)) !== hash) result.differing.push(path17.relative(process.cwd(), file));
+      if (existsSync13(file)) {
+        if (sha256(await readFile11(file)) !== hash) result.differing.push(path18.relative(process.cwd(), file));
       } else {
-        await mkdir6(path17.dirname(file), { recursive: true });
-        await writeFile7(file, bytes);
-        result.written.push(path17.relative(process.cwd(), file));
+        await mkdir7(path18.dirname(file), { recursive: true });
+        await writeFile8(file, bytes);
+        result.written.push(path18.relative(process.cwd(), file));
       }
       outputs.push({ path: portableOutputPath(file, spec.root), sha256: hash, ...source.role ? { role: source.role } : {} });
     }
@@ -12560,11 +13149,11 @@ async function adoptCharacters(provider, specs, lock, lockPath, opts) {
       if (!match) throw new Error(`remoteId ${spec.remoteId} is not a character on this account`);
     } else {
       const south = expectedOutputPath(spec, "south", 0, spec.character.directions);
-      if (!existsSync12(south)) {
-        result.unmatched.push(`${key}: no remoteId and no ${path17.relative(process.cwd(), south)} to match by`);
+      if (!existsSync13(south)) {
+        result.unmatched.push(`${key}: no remoteId and no ${path18.relative(process.cwd(), south)} to match by`);
         return false;
       }
-      const localHash = sha256(await readFile10(south));
+      const localHash = sha256(await readFile11(south));
       for (const candidate of remote) {
         if (claimed.has(candidate.id)) continue;
         if (await southHash(candidate) === localHash) {
@@ -12573,7 +13162,7 @@ async function adoptCharacters(provider, specs, lock, lockPath, opts) {
         }
       }
       if (!match) {
-        result.unmatched.push(`${key}: no character's south rotation has the bytes of ${path17.relative(process.cwd(), south)}`);
+        result.unmatched.push(`${key}: no character's south rotation has the bytes of ${path18.relative(process.cwd(), south)}`);
         return false;
       }
     }
@@ -12640,15 +13229,15 @@ async function adoptCharacters(provider, specs, lock, lockPath, opts) {
       if (!match) throw new Error(`remoteId ${spec.remoteId} names no ${animation.direction} animation of character ${parentId}`);
     } else {
       const first = expectedOutputPath(spec, "frame-00", 0, 2);
-      if (!existsSync12(first)) {
+      if (!existsSync13(first)) {
         const byName = candidates.find((a) => a.name === characterAnimationName(spec));
         if (!byName) {
-          result.unmatched.push(`${key}: no remoteId and no ${path17.relative(process.cwd(), first)} to match by`);
+          result.unmatched.push(`${key}: no remoteId and no ${path18.relative(process.cwd(), first)} to match by`);
           return false;
         }
         match = byName;
       } else {
-        const localHash = sha256(await readFile10(first));
+        const localHash = sha256(await readFile11(first));
         for (const candidate of candidates) {
           if (sha256(await download(candidate.frames[0])) === localHash) {
             match = candidate;
@@ -12656,7 +13245,7 @@ async function adoptCharacters(provider, specs, lock, lockPath, opts) {
           }
         }
         if (!match) {
-          result.unmatched.push(`${key}: no ${animation.direction} animation of character ${parentId} starts with the bytes of ${path17.relative(process.cwd(), first)}`);
+          result.unmatched.push(`${key}: no ${animation.direction} animation of character ${parentId} starts with the bytes of ${path18.relative(process.cwd(), first)}`);
           return false;
         }
       }
@@ -12716,19 +13305,19 @@ async function adoptCharacters(provider, specs, lock, lockPath, opts) {
 }
 
 // src/pipeline/salvage.ts
-import { readFile as readFile11 } from "fs/promises";
-import { existsSync as existsSync13 } from "fs";
-import path18 from "path";
+import { readFile as readFile12 } from "fs/promises";
+import { existsSync as existsSync14 } from "fs";
+import path19 from "path";
 function providerClaimId(provider, objectId) {
   return `${encodeURIComponent(provider)}:${encodeURIComponent(objectId)}`;
 }
 async function loadClaims(lockPaths, opts = {}) {
   const claimed = /* @__PURE__ */ new Set();
   for (const p of lockPaths) {
-    if (!existsSync13(p)) throw new Error(`Claim lockfile not found: ${p}`);
+    if (!existsSync14(p)) throw new Error(`Claim lockfile not found: ${p}`);
     let parsed;
     try {
-      parsed = parseLock(JSON.parse(await readFile11(p, "utf8")));
+      parsed = parseLock(JSON.parse(await readFile12(p, "utf8")));
     } catch {
       throw new Error(`Claim lockfile is malformed: ${p}`);
     }
@@ -12895,20 +13484,20 @@ function matchStyleByPattern(prompt, manifest) {
   return null;
 }
 async function loadSiblingManifests(ownManifestPath, workspaceManifestPaths, claimPaths) {
-  const own = path18.resolve(ownManifestPath);
+  const own = path19.resolve(ownManifestPath);
   const siblingManifestPaths = [
     .../* @__PURE__ */ new Set([
       ...workspaceManifestPaths,
-      ...claimPaths.map((c) => path18.join(path18.dirname(path18.resolve(c)), "pixelkiln.manifest.json"))
+      ...claimPaths.map((c) => path19.join(path19.dirname(path19.resolve(c)), "pixelkiln.manifest.json"))
     ])
   ];
   const siblings = [];
   for (const siblingManifestPath of siblingManifestPaths) {
-    if (path18.resolve(siblingManifestPath) === own) continue;
-    if (!existsSync13(siblingManifestPath)) continue;
+    if (path19.resolve(siblingManifestPath) === own) continue;
+    if (!existsSync14(siblingManifestPath)) continue;
     try {
       const { manifest } = await loadManifest(siblingManifestPath);
-      siblings.push({ label: path18.basename(path18.dirname(siblingManifestPath)), manifest });
+      siblings.push({ label: path19.basename(path19.dirname(siblingManifestPath)), manifest });
     } catch {
     }
   }
@@ -13028,9 +13617,9 @@ async function applyTags(provider, decisions, existing, opts = {}) {
 }
 
 // src/workspace.ts
-import { mkdir as mkdir7, readFile as readFile12, rename as rename6, rm as rm6, writeFile as writeFile8 } from "fs/promises";
-import { existsSync as existsSync14 } from "fs";
-import path19 from "path";
+import { mkdir as mkdir8, readFile as readFile13, rename as rename6, rm as rm6, writeFile as writeFile9 } from "fs/promises";
+import { existsSync as existsSync15 } from "fs";
+import path20 from "path";
 import { z as z5 } from "zod";
 var WorkspaceProjectSchema = z5.object({
   id: z5.string().min(1),
@@ -13055,10 +13644,10 @@ ${parsed.error.issues.slice(0, 5).map((i) => `  ${i.path.join(".")}: ${i.message
   );
 }
 async function loadWorkspace(workspacePath) {
-  if (!existsSync14(workspacePath)) return { version: 1, projects: [] };
+  if (!existsSync15(workspacePath)) return { version: 1, projects: [] };
   let raw;
   try {
-    raw = JSON.parse(await readFile12(workspacePath, "utf8"));
+    raw = JSON.parse(await readFile13(workspacePath, "utf8"));
   } catch (err) {
     throw new ProjectError(
       `Workspace catalog at ${workspacePath} is malformed:
@@ -13072,22 +13661,22 @@ async function saveWorkspace(workspacePath, ws) {
     version: 1,
     projects: [...ws.projects].sort((a, b) => a.id.localeCompare(b.id))
   };
-  await mkdir7(path19.dirname(path19.resolve(workspacePath)), { recursive: true });
+  await mkdir8(path20.dirname(path20.resolve(workspacePath)), { recursive: true });
   const tmp = `${workspacePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
-    await writeFile8(tmp, JSON.stringify(sorted, null, 2) + "\n");
+    await writeFile9(tmp, JSON.stringify(sorted, null, 2) + "\n");
     await rename6(tmp, workspacePath);
   } finally {
     await rm6(tmp, { force: true });
   }
 }
 function toPortablePath(dir, absolute) {
-  return path19.relative(dir, absolute).split(path19.sep).join("/");
+  return path20.relative(dir, absolute).split(path20.sep).join("/");
 }
 function resolveProject(dir, project) {
   return {
-    manifestPath: path19.resolve(dir, project.manifest.split("/").join(path19.sep)),
-    lockPath: path19.resolve(dir, project.lock.split("/").join(path19.sep))
+    manifestPath: path20.resolve(dir, project.manifest.split("/").join(path20.sep)),
+    lockPath: path20.resolve(dir, project.lock.split("/").join(path20.sep))
   };
 }
 function validateWorkspace(ws, dir) {
@@ -13100,21 +13689,21 @@ function validateWorkspace(ws, dir) {
     const { manifestPath, lockPath } = resolveProject(dir, project);
     lockOwners.set(lockPath, [...lockOwners.get(lockPath) ?? [], project.id]);
     manifestOwners.set(manifestPath, [...manifestOwners.get(manifestPath) ?? [], project.id]);
-    if (path19.isAbsolute(project.manifest) || path19.isAbsolute(project.lock)) {
+    if (path20.isAbsolute(project.manifest) || path20.isAbsolute(project.lock)) {
       diagnostics.push({
         id: "absolute-path",
         level: "warning",
         message: `project "${project.id}" stores an absolute path; the catalog will not resolve correctly if this tree is cloned or moved elsewhere`
       });
     }
-    if (!existsSync14(manifestPath)) {
+    if (!existsSync15(manifestPath)) {
       diagnostics.push({
         id: "missing-manifest",
         level: "error",
         message: `project "${project.id}" manifest not found: ${manifestPath}`
       });
     }
-    if (!existsSync14(lockPath)) {
+    if (!existsSync15(lockPath)) {
       diagnostics.push({
         id: "missing-lock",
         level: "error",
@@ -13161,8 +13750,8 @@ function validateWorkspace(ws, dir) {
 }
 
 // src/pick/salvage-server.ts
-import { mkdir as mkdir8, writeFile as writeFile9, readFile as readFile14 } from "fs/promises";
-import path20 from "path";
+import { mkdir as mkdir9, writeFile as writeFile10, readFile as readFile15 } from "fs/promises";
+import path21 from "path";
 
 // src/pick/salvage-sheet.ts
 var escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -13323,7 +13912,7 @@ refresh();
 
 // src/pick/review-server.ts
 import { createServer } from "http";
-import { readFile as readFile13 } from "fs/promises";
+import { readFile as readFile14 } from "fs/promises";
 
 // src/open.ts
 import { spawn } from "child_process";
@@ -13350,7 +13939,7 @@ function serveReviewPage(opts) {
       if (req.method === "GET" && req.url && opts.assets?.has(req.url)) {
         try {
           const asset = opts.assets.get(req.url);
-          const bytes = await readFile13(asset.path);
+          const bytes = await readFile14(asset.path);
           res.writeHead(200, {
             "Content-Type": asset.contentType,
             "Cache-Control": "no-store",
@@ -13427,7 +14016,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
   });
   const html = renderSalvageSheet(orphans, {
     styleId: ctx.styleId,
-    importDir: path20.relative(process.cwd(), ctx.importDir) || "."
+    importDir: path21.relative(process.cwd(), ctx.importDir) || "."
   });
   const byId = new Map(orphans.map((o) => [o.id, o]));
   const existingTags = new Map(orphans.map((o) => [o.id, o.tags]));
@@ -13483,10 +14072,10 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
             if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
             decodePng(buf);
             const assetId = idFromPrompt(orphan.prompt, taken);
-            const rel = path20.join("_salvaged", `${assetId}.png`);
-            const outFile = path20.resolve(ctx.importDir, rel);
-            await mkdir8(path20.dirname(outFile), { recursive: true });
-            await writeFile9(outFile, buf);
+            const rel = path21.join("_salvaged", `${assetId}.png`);
+            const outFile = path21.resolve(ctx.importDir, rel);
+            await mkdir9(path21.dirname(outFile), { recursive: true });
+            await writeFile10(outFile, buf);
             ctx.manifest.assets[assetId] = {
               prompt: orphan.prompt,
               promptByStyle: {},
@@ -13518,7 +14107,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               sourceUrl: durableSource,
               sourceUrls: durableSource ? [{ url: durableSource }] : [],
               outputs: [{
-                path: portableOutputPath(outFile, path20.dirname(ctx.manifestPath)),
+                path: portableOutputPath(outFile, path21.dirname(ctx.manifestPath)),
                 sha256: sha256(buf)
               }],
               submittedAt: orphan.createdAt,
@@ -13542,9 +14131,9 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
         }
       }
       await applyTags(provider, decisions, existingTags, { onProgress: log2, characters: characterMembers });
-      const raw = JSON.parse(await readFile14(ctx.manifestPath, "utf8"));
+      const raw = JSON.parse(await readFile15(ctx.manifestPath, "utf8"));
       for (const id of importedAssetIds) raw.assets[id] = ctx.manifest.assets[id];
-      await writeFile9(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
+      await writeFile10(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
       await saveLock(ctx.lockPath, ctx.lock);
       if (characterAssetIds.length) result.characterAssetIds = characterAssetIds;
       return result;
@@ -13553,19 +14142,19 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
 }
 
 // src/cli/project.ts
-import path22 from "path";
-import { existsSync as existsSync15 } from "fs";
+import path23 from "path";
+import { existsSync as existsSync16 } from "fs";
 
 // src/project.ts
-import path21 from "path";
+import path22 from "path";
 async function openProject(manifestPath = "pixelkiln.manifest.json", opts = {}) {
-  const absolute = path21.resolve(manifestPath);
-  const root = path21.dirname(absolute);
+  const absolute = path22.resolve(manifestPath);
+  const root = path22.dirname(absolute);
   if (opts.env !== false) {
     loadEnvFiles(root);
-    if (path21.resolve(process.cwd()) !== root) loadEnvFiles(process.cwd());
+    if (path22.resolve(process.cwd()) !== root) loadEnvFiles(process.cwd());
   }
-  const lockPath = path21.resolve(opts.lockPath ?? path21.join(root, "pixelkiln.lock.json"));
+  const lockPath = path22.resolve(opts.lockPath ?? path22.join(root, "pixelkiln.lock.json"));
   const loaded = await loadManifest(absolute);
   const specs = await resolveSpecs(loaded, { styles: opts.styles ?? [], assets: opts.assets ?? [] });
   const lock = await loadLock(lockPath);
@@ -13696,18 +14285,18 @@ async function workspaceStatus(ws, dir) {
 
 // src/cli/project.ts
 async function provenanceFile(id, file) {
-  const absolute = path22.resolve(file);
+  const absolute = path23.resolve(file);
   return {
     id,
     path: absolute,
-    sha256: existsSync15(absolute) ? await sha256File(absolute) : null,
+    sha256: existsSync16(absolute) ? await sha256File(absolute) : null,
     included: true
   };
 }
 function manifestSources(manifest, styleId) {
   const sources = {};
   for (const [assetId, asset] of Object.entries(manifest.assets)) {
-    if (asset.styles.length && !asset.styles.includes(styleId)) continue;
+    if (!assetInStyle(asset, styleId, manifest.styles[styleId])) continue;
     const source = asset.sourceByStyle[styleId] ?? asset.source;
     if (source) sources[assetId] = source;
   }
@@ -13772,10 +14361,10 @@ function budgetsForPlan(plan, args) {
   return out;
 }
 async function requireCompleteWorkspaceClaims(workspacePath) {
-  if (!existsSync15(workspacePath)) {
+  if (!existsSync16(workspacePath)) {
     throw new ProjectError(`Workspace catalog not found: ${workspacePath}`);
   }
-  const dir = path22.dirname(path22.resolve(workspacePath));
+  const dir = path23.dirname(path23.resolve(workspacePath));
   const ws = await loadWorkspace(workspacePath);
   const diagnostics = validateWorkspace(ws, dir);
   const errors = diagnostics.filter((d) => d.level === "error");
@@ -13798,9 +14387,9 @@ async function openAccountProject(args) {
   return project;
 }
 async function open(args) {
-  if (!existsSync15(path22.resolve(args.manifest))) {
+  if (!existsSync16(path23.resolve(args.manifest))) {
     throw new ProjectError(
-      `No manifest at ${path22.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
+      `No manifest at ${path23.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
     );
   }
   const project = await openProject(args.manifest, { lockPath: args.lock, styles: args.styles, assets: args.assets });
@@ -13842,7 +14431,7 @@ function providerCache(mode2) {
 
 // src/cli/commands/account.ts
 async function runBalance(args) {
-  loadEnvFiles(path23.dirname(path23.resolve(args.manifest)));
+  loadEnvFiles(path24.dirname(path24.resolve(args.manifest)));
   loadEnvFiles(process.cwd());
   const loaded = await loadManifest(args.manifest);
   const selectedProvider = accountProviderId(loaded.manifest, args.provider, "balance");
@@ -13915,12 +14504,12 @@ async function runAdopt(args) {
   tagged ${n} object(s) upstream`);
   }
   if (args.writePrompts) {
-    const { filled, stillEmpty } = await writePromptsBack(path23.resolve(args.manifest), lock, {
+    const { filled, stillEmpty } = await writePromptsBack(path24.resolve(args.manifest), lock, {
       onProgress: log,
       provider: provider.id,
       assetIds: specs.map((spec) => spec.assetId)
     });
-    log(`  recovered ${filled} prompt(s) into ${path23.relative(process.cwd(), args.manifest)}`);
+    log(`  recovered ${filled} prompt(s) into ${path24.relative(process.cwd(), args.manifest)}`);
     const reloaded = await loadManifest(args.manifest);
     const rebased = (await resolveSpecs(reloaded, {
       styles: args.styles,
@@ -13950,12 +14539,12 @@ async function runSalvage2(args) {
   const provider = providerFor(accountProvider);
   const jsonMode = args.dryRun && args.json;
   const diag = jsonMode ? (msg = "") => console.error(msg) : log;
-  const ownLock = path23.resolve(args.lock);
+  const ownLock = path24.resolve(args.lock);
   let workspaceProjects = [];
   let workspaceDir = "";
   if (args.workspace) {
-    const workspacePath = path23.resolve(args.workspace);
-    workspaceDir = path23.dirname(workspacePath);
+    const workspacePath = path24.resolve(args.workspace);
+    workspaceDir = path24.dirname(workspacePath);
     const complete = await requireCompleteWorkspaceClaims(workspacePath);
     workspaceProjects = complete.ws.projects;
     for (const d of complete.diagnostics) diag(`  WARN  ${d.id}: ${d.message}`);
@@ -13964,12 +14553,12 @@ async function runSalvage2(args) {
   const lockPaths = [
     .../* @__PURE__ */ new Set([
       ...workspaceLockPaths,
-      ...existsSync16(ownLock) ? [ownLock] : [],
-      ...args.claims.map((c) => path23.resolve(c))
+      ...existsSync17(ownLock) ? [ownLock] : [],
+      ...args.claims.map((c) => path24.resolve(c))
     ])
   ];
   diag(`  claim set (${lockPaths.length} lockfile(s)):`);
-  for (const p of lockPaths) diag(`    ${path23.relative(process.cwd(), p)}`);
+  for (const p of lockPaths) diag(`    ${path24.relative(process.cwd(), p)}`);
   if (!args.claims.length && !args.workspace) {
     diag(
       `
@@ -13977,7 +14566,7 @@ async function runSalvage2(args) {
   pass every other project's lockfile via --claims a.json,b.json, or
   register every project in a workspace catalog and pass --workspace.`
     );
-  } else if (args.workspace && !workspaceProjects.some((p) => resolveProject(workspaceDir, p).manifestPath === path23.resolve(args.manifest))) {
+  } else if (args.workspace && !workspaceProjects.some((p) => resolveProject(workspaceDir, p).manifestPath === path24.resolve(args.manifest))) {
     diag(
       `
   This project's manifest is not registered in the workspace catalog. Its own
@@ -14096,7 +14685,7 @@ async function runSalvage2(args) {
         manifestPath: loaded.path,
         manifest: accountManifest,
         styleId,
-        importDir: path23.resolve(loaded.root, style.outDir),
+        importDir: path24.resolve(loaded.root, style.outDir),
         lock,
         lockPath: args.lock
       },
@@ -14223,20 +14812,20 @@ async function runTag(args) {
 }
 
 // src/cli/commands/edit.ts
-import path26 from "path";
+import path27 from "path";
 
 // src/pipeline/hand-edit.ts
-import { existsSync as existsSync17 } from "fs";
-import { copyFile, mkdir as mkdir9, readFile as readFile16, rename as rename8, rm as rm8, writeFile as writeFile11 } from "fs/promises";
-import path25 from "path";
+import { existsSync as existsSync18 } from "fs";
+import { copyFile, mkdir as mkdir10, readFile as readFile17, rename as rename8, rm as rm8, writeFile as writeFile12 } from "fs/promises";
+import path26 from "path";
 import { z as z7 } from "zod";
 
 // src/manifest-edit.ts
-import { readFile as readFile15, rename as rename7, rm as rm7, writeFile as writeFile10 } from "fs/promises";
-import path24 from "path";
+import { readFile as readFile16, rename as rename7, rm as rm7, writeFile as writeFile11 } from "fs/promises";
+import path25 from "path";
 import { z as z6 } from "zod";
 var HexSha = z6.string().regex(/^[0-9a-f]{64}$/);
-var ProjectFileSchema = z6.string().min(1).refine((file) => !path24.isAbsolute(file) && !file.split(/[\\/]/).includes(".."), "must be a path inside the project");
+var ProjectFileSchema = z6.string().min(1).refine((file) => !path25.isAbsolute(file) && !file.split(/[\\/]/).includes(".."), "must be a path inside the project");
 var AssetPatchSchema = z6.object({
   prompt: z6.string().optional(),
   /** Per-style override for the style being viewed; null removes it. */
@@ -14655,8 +15244,8 @@ function applyEdit(raw, edit) {
   }
 }
 async function withCandidate(manifestPath, edit, use, unchanged) {
-  const absolute = path24.resolve(manifestPath);
-  const original = await readFile15(absolute, "utf8");
+  const absolute = path25.resolve(manifestPath);
+  const original = await readFile16(absolute, "utf8");
   if (sha256(original) !== edit.expectedSha256) throw new ManifestDriftError(absolute);
   let raw;
   try {
@@ -14669,12 +15258,12 @@ async function withCandidate(manifestPath, edit, use, unchanged) {
   applyEdit(raw, edit);
   const next = serializeLike(original, raw);
   if (next === original) return unchanged(absolute, original);
-  const tmp = path24.join(
-    path24.dirname(absolute),
-    `.${path24.basename(absolute)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
+  const tmp = path25.join(
+    path25.dirname(absolute),
+    `.${path25.basename(absolute)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
   );
   try {
-    await writeFile10(tmp, next);
+    await writeFile11(tmp, next);
     let specs;
     try {
       specs = await resolveSpecs(await loadManifest(tmp));
@@ -14744,11 +15333,11 @@ async function priceManifestEdit(manifestPath, edit, opts = {}) {
 var HAND_EDIT_DIR = "edits";
 function handEditPath(loaded, spec) {
   const style = loaded.manifest.styles[spec.styleId];
-  const outDir = path25.resolve(loaded.root, style?.outDir ?? ".");
-  const relative = path25.relative(outDir, spec.outFile);
-  const inside = relative && !relative.startsWith("..") && !path25.isAbsolute(relative);
-  const file = inside ? relative : path25.basename(spec.outFile);
-  return path25.join(outDir, HAND_EDIT_DIR, file.replace(/\.gif$/i, ".png"));
+  const outDir = path26.resolve(loaded.root, style?.outDir ?? ".");
+  const relative = path26.relative(outDir, spec.outFile);
+  const inside = relative && !relative.startsWith("..") && !path26.isAbsolute(relative);
+  const file = inside ? relative : path26.basename(spec.outFile);
+  return path26.join(outDir, HAND_EDIT_DIR, file.replace(/\.gif$/i, ".png"));
 }
 function handEditBases(spec, lock) {
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
@@ -14761,10 +15350,10 @@ function handEditBases(spec, lock) {
     }));
     if (members.some((member) => member.mediaType && member.mediaType !== "image/png")) return null;
     if (entry.outputs.length === 1 && !primaryOutput(entry)) return null;
-    if (!members.every((member) => existsSync17(member.path))) return null;
+    if (!members.every((member) => existsSync18(member.path))) return null;
     return members.map(({ role, path: file }) => ({ role, path: file }));
   }
-  return existsSync17(spec.outFile) ? [{ role: null, path: spec.outFile }] : null;
+  return existsSync18(spec.outFile) ? [{ role: null, path: spec.outFile }] : null;
 }
 function handEditMembers(loaded, spec, lock, editPath) {
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
@@ -14790,18 +15379,18 @@ async function startHandEdit(loaded, lock, spec, opts = {}) {
       `${spec.styleId}/${spec.assetId} declares ${spec.source}, one committed file placed for the whole set; clear that source (pixelkiln edit detach) to hand-edit the members one by one`
     );
   }
-  const existing = spec.source ? path25.resolve(loaded.root, spec.source) : null;
+  const existing = spec.source ? path26.resolve(loaded.root, spec.source) : null;
   const editPath = existing ?? handEditPath(loaded, spec);
   const members = handEditMembers(loaded, spec, lock, editPath);
   let created = false;
   for (const member of members) {
-    if (existsSync17(member.path)) continue;
+    if (existsSync18(member.path)) continue;
     if (!member.base) {
       throw new ManifestEditError(
         `${spec.styleId}/${spec.assetId} has no generated PNG on disk to start from; generate or restore it first`
       );
     }
-    await mkdir9(path25.dirname(member.path), { recursive: true });
+    await mkdir10(path26.dirname(member.path), { recursive: true });
     await copyFile(member.base, member.path);
     created = true;
   }
@@ -14880,7 +15469,7 @@ function handEditProjectPath(editPath) {
 async function readHandEditCompanion(editPath) {
   let text;
   try {
-    text = await readFile16(handEditCompanionPath(editPath), "utf8");
+    text = await readFile17(handEditCompanionPath(editPath), "utf8");
   } catch {
     return null;
   }
@@ -14923,7 +15512,7 @@ async function saveHandEdit(loaded, lock, spec, input) {
     }
   });
   const bases = handEditBases(spec, lock);
-  const expectedSize = bases?.[0] ? decodePng(await readFile16(bases[0].path)) : { width: spec.width, height: spec.height };
+  const expectedSize = bases?.[0] ? decodePng(await readFile17(bases[0].path)) : { width: spec.width, height: spec.height };
   for (const [index, image] of decoded.entries()) {
     if (image.width !== expectedSize.width || image.height !== expectedSize.height) {
       const which = memberSet ? `member ${incoming[index].role ?? index}` : "the edit";
@@ -14939,7 +15528,7 @@ async function saveHandEdit(loaded, lock, spec, input) {
     editor: input.editor,
     protocol: input.protocol,
     savedAt: (input.now ?? /* @__PURE__ */ new Date()).toISOString(),
-    project: projectPath ? path25.basename(projectPath) : null,
+    project: projectPath ? path26.basename(projectPath) : null,
     outputs: incoming.map((frame, index) => ({
       role: frame.role,
       basedOn: basedOnHash(entry, index),
@@ -14969,7 +15558,7 @@ function basedOnHash(entry, index) {
 async function replaceFile(file, bytes) {
   const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
-    await writeFile11(tmp, bytes);
+    await writeFile12(tmp, bytes);
     await rename8(tmp, file);
   } finally {
     await rm8(tmp, { force: true });
@@ -14999,7 +15588,7 @@ async function runEdit(args) {
   const set = started.members.length > 1;
   const kind = spec.generator === "frames" ? "frames" : "members";
   log(`  ${started.created ? "created" : "found"} ${started.source}${set ? ` (${started.members.length} ${kind})` : ""}${started.declared ? " and declared it as the asset's source" : ""}`);
-  if (set) for (const member of started.members) log(`    ${member.role ?? ""}  ${path26.relative(process.cwd(), member.path)}`);
+  if (set) for (const member of started.members) log(`    ${member.role ?? ""}  ${path27.relative(process.cwd(), member.path)}`);
   if (args.noOpen) {
     log(`  edit ${set ? "them" : "it"} with your own tool, then run pixelkiln plan; mount and pack place ${set ? "them" : "it"} in place of the generated art`);
   } else {
@@ -15009,24 +15598,24 @@ async function runEdit(args) {
 }
 
 // src/cli/commands/gallery.ts
-import path36 from "path";
-import { existsSync as existsSync27 } from "fs";
+import path37 from "path";
+import { existsSync as existsSync28 } from "fs";
 
 // src/gallery/snapshot.ts
 import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync22 } from "fs";
-import { readFile as readFile20, stat as stat2 } from "fs/promises";
-import path32 from "path";
+import { existsSync as existsSync23 } from "fs";
+import { readFile as readFile21, stat as stat2 } from "fs/promises";
+import path33 from "path";
 
 // src/gallery/edit.ts
-import { readFile as readFile19, rename as rename9, writeFile as writeFile15 } from "fs/promises";
-import path30 from "path";
+import { readFile as readFile20, rename as rename9, writeFile as writeFile16 } from "fs/promises";
+import path31 from "path";
 import { z as z11 } from "zod";
 
 // src/gallery/upload.ts
-import { existsSync as existsSync18 } from "fs";
-import { mkdir as mkdir10, writeFile as writeFile12 } from "fs/promises";
-import path27 from "path";
+import { existsSync as existsSync19 } from "fs";
+import { mkdir as mkdir11, writeFile as writeFile13 } from "fs/promises";
+import path28 from "path";
 import { z as z8 } from "zod";
 var MAX_UPLOAD_BYTES = 8 * 1024 * 1024;
 var UploadImageSchema = z8.object({
@@ -15039,12 +15628,12 @@ var UploadImageSchema = z8.object({
   overwrite: z8.boolean().optional()
 }).strict();
 async function saveProjectImage(root, request) {
-  const file = path27.resolve(root, request.path);
-  const relative = path27.relative(root, file);
-  if (relative.startsWith("..") || path27.isAbsolute(relative)) {
+  const file = path28.resolve(root, request.path);
+  const relative = path28.relative(root, file);
+  if (relative.startsWith("..") || path28.isAbsolute(relative)) {
     throw new ManifestEditError("an upload must stay inside the project");
   }
-  const extension = path27.extname(file).toLowerCase();
+  const extension = path28.extname(file).toLowerCase();
   const expected = extension === ".png" ? "png" : extension === ".jpg" || extension === ".jpeg" ? "jpeg" : null;
   if (!expected) throw new ManifestEditError("an upload must be a .png, .jpg, or .jpeg path");
   const bytes = Buffer.from(request.base64, "base64");
@@ -15056,18 +15645,18 @@ async function saveProjectImage(root, request) {
   if (metadata.format !== expected) {
     throw new ManifestEditError(`the upload is a ${metadata.format.toUpperCase()}; name it ${metadata.format === "png" ? ".png" : ".jpg"}`);
   }
-  if (existsSync18(file) && !request.overwrite) {
-    throw new ManifestEditError(`${relative.split(path27.sep).join("/")} already exists; choose another name, or replace it`);
+  if (existsSync19(file) && !request.overwrite) {
+    throw new ManifestEditError(`${relative.split(path28.sep).join("/")} already exists; choose another name, or replace it`);
   }
-  await mkdir10(path27.dirname(file), { recursive: true });
-  await writeFile12(file, bytes);
-  return relative.split(path27.sep).join("/");
+  await mkdir11(path28.dirname(file), { recursive: true });
+  await writeFile13(file, bytes);
+  return relative.split(path28.sep).join("/");
 }
 
 // src/gallery/image-revision.ts
-import { existsSync as existsSync19 } from "fs";
-import { readFile as readFile17, rm as rm9, writeFile as writeFile13 } from "fs/promises";
-import path28 from "path";
+import { existsSync as existsSync20 } from "fs";
+import { readFile as readFile18, rm as rm9, writeFile as writeFile14 } from "fs/promises";
+import path29 from "path";
 import { z as z9 } from "zod";
 var InpaintRevisionRequestSchema = z9.object({
   action: z9.literal("create-inpaint-revision"),
@@ -15086,15 +15675,15 @@ var InpaintRevisionRequestSchema = z9.object({
   overwrite: z9.boolean().optional()
 }).strict();
 async function createInpaintRevision(manifestPath, request) {
-  const root = path28.dirname(path28.resolve(manifestPath));
-  if (path28.extname(request.maskPath).toLowerCase() !== ".png") {
+  const root = path29.dirname(path29.resolve(manifestPath));
+  if (path29.extname(request.maskPath).toLowerCase() !== ".png") {
     throw new ManifestEditError("the mask must be a .png path inside the project");
   }
   const bytes = Buffer.from(request.maskBase64, "base64");
   const metadata = imageMetadata(bytes);
   if (!metadata || metadata.format !== "png") throw new ManifestEditError("the mask is not a readable PNG");
-  const file = path28.resolve(root, request.maskPath);
-  const previous = existsSync19(file) ? await readFile17(file) : null;
+  const file = path29.resolve(root, request.maskPath);
+  const previous = existsSync20(file) ? await readFile18(file) : null;
   const mask = await saveProjectImage(root, {
     action: "upload-image",
     path: request.maskPath,
@@ -15113,7 +15702,7 @@ async function createInpaintRevision(manifestPath, request) {
       }
     });
   } catch (error) {
-    if (previous) await writeFile13(file, previous);
+    if (previous) await writeFile14(file, previous);
     else await rm9(file, { force: true });
     throw error;
   }
@@ -15121,9 +15710,9 @@ async function createInpaintRevision(manifestPath, request) {
 }
 
 // src/gallery/skeleton.ts
-import { existsSync as existsSync20 } from "fs";
-import { mkdir as mkdir11, readFile as readFile18, rm as rm10, writeFile as writeFile14 } from "fs/promises";
-import path29 from "path";
+import { existsSync as existsSync21 } from "fs";
+import { mkdir as mkdir12, readFile as readFile19, rm as rm10, writeFile as writeFile15 } from "fs/promises";
+import path30 from "path";
 import { z as z10 } from "zod";
 var SkeletonEstimateRequestSchema = z10.object({
   project: z10.string().min(1).optional(),
@@ -15162,8 +15751,8 @@ var SkeletonKeypointsUpdateSchema = z10.object({
 }).strict();
 var DEFAULT_ESTIMATE_LIMIT = 10;
 function skeletonSourceFile(spec) {
-  if (spec.source) return path29.resolve(spec.root, spec.source);
-  if (spec.quality && existsSync20(spec.quality.outFile)) return spec.quality.outFile;
+  if (spec.source) return path30.resolve(spec.root, spec.source);
+  if (spec.quality && existsSync21(spec.quality.outFile)) return spec.quality.outFile;
   return spec.outFile;
 }
 function createGallerySkeletonHandlers(opts) {
@@ -15184,10 +15773,10 @@ function createGallerySkeletonHandlers(opts) {
       const spec = ctx.specs.find((candidate) => lockKey(candidate.styleId, candidate.assetId) === key);
       if (!spec) throw new ManifestEditError(`"${key}" is not declared by the manifest`);
       const file = skeletonSourceFile(spec);
-      if (!existsSync20(file)) throw new ManifestEditError(`${key} has no image on disk to estimate from`);
-      const bytes = await readFile18(file);
+      if (!existsSync21(file)) throw new ManifestEditError(`${key} has no image on disk to estimate from`);
+      const bytes = await readFile19(file);
       const metadata = imageMetadata(bytes);
-      if (!metadata) throw new ManifestEditError(`${path29.basename(file)} is not a readable PNG or JPEG`);
+      if (!metadata) throw new ManifestEditError(`${path30.basename(file)} is not a readable PNG or JPEG`);
       const problem = estimateSkeletonSizeProblem(metadata.width, metadata.height);
       if (problem) throw new ManifestEditError(`${key} is ${problem}`);
       if (used >= limit) {
@@ -15204,7 +15793,7 @@ function createGallerySkeletonHandlers(opts) {
       log2(`  estimated a skeleton for ${key} (PixelLab estimate-skeleton, ${used}/${limit} this session${billed ? `, billed ${billed.amount} ${billed.unit}` : ""})`);
       return {
         set: scaffoldSkeletonSet(res.keypoints, request.frames ?? DEFAULT_SCAFFOLD_FRAMES),
-        source: path29.relative(ctx.loaded.root, file).split(path29.sep).join("/"),
+        source: path30.relative(ctx.loaded.root, file).split(path30.sep).join("/"),
         session: status()
       };
     }
@@ -15218,21 +15807,21 @@ function billedAmount(usage) {
   return typeof amount === "number" && Number.isFinite(amount) ? { unit: type, amount } : null;
 }
 async function createSkeletonAnimation(manifestPath, request) {
-  const root = path29.dirname(path29.resolve(manifestPath));
-  const file = path29.resolve(root, request.keypointsFile);
-  const relative = path29.relative(root, file);
-  if (!request.keypointsFile.endsWith(".json") || relative.startsWith("..") || path29.isAbsolute(relative)) {
+  const root = path30.dirname(path30.resolve(manifestPath));
+  const file = path30.resolve(root, request.keypointsFile);
+  const relative = path30.relative(root, file);
+  if (!request.keypointsFile.endsWith(".json") || relative.startsWith("..") || path30.isAbsolute(relative)) {
     throw new ManifestEditError("the keypoints file must be a .json path inside the project");
   }
-  const existed = existsSync20(file);
+  const existed = existsSync21(file);
   let previous = null;
   if (request.set) {
     if (existed && !request.overwrite) {
       throw new ManifestEditError(`${request.keypointsFile} already exists; choose another path, or replace it`);
     }
-    if (existed) previous = await readFile18(file);
-    await mkdir11(path29.dirname(file), { recursive: true });
-    await writeFile14(file, JSON.stringify(request.set, null, 2) + "\n");
+    if (existed) previous = await readFile19(file);
+    await mkdir12(path30.dirname(file), { recursive: true });
+    await writeFile15(file, JSON.stringify(request.set, null, 2) + "\n");
   } else if (!existed) {
     throw new ManifestEditError(`${request.keypointsFile} does not exist; paste poses or estimate them from the sprite`);
   }
@@ -15247,7 +15836,7 @@ async function createSkeletonAnimation(manifestPath, request) {
         revision: {
           mode: "animate-skeleton",
           from: request.from,
-          keypointsFile: relative.split(path29.sep).join("/"),
+          keypointsFile: relative.split(path30.sep).join("/"),
           direction: request.direction,
           ...request.description ? { description: request.description } : {},
           ...request.skeletonTemplate ? { skeletonTemplate: request.skeletonTemplate } : {}
@@ -15256,7 +15845,7 @@ async function createSkeletonAnimation(manifestPath, request) {
     });
   } catch (error) {
     if (request.set) {
-      if (previous) await writeFile14(file, previous);
+      if (previous) await writeFile15(file, previous);
       else await rm10(file, { force: true });
     }
     throw error;
@@ -15268,19 +15857,19 @@ async function updateSkeletonKeypoints(ctx, request) {
   if (!spec) throw new ManifestEditError(`"${key}" is not declared by the manifest`);
   const file = spec.revision?.mode === "animate-skeleton" ? spec.revision.keypointsFile : void 0;
   if (!file) throw new ManifestEditError(`${key} is not an animate-skeleton revision`);
-  const relative = path29.relative(ctx.loaded.root, file);
-  if (relative.startsWith("..") || path29.isAbsolute(relative)) {
+  const relative = path30.relative(ctx.loaded.root, file);
+  if (relative.startsWith("..") || path30.isAbsolute(relative)) {
     throw new ManifestEditError(`${key}'s keypoints file is outside the project; edit it by hand`);
   }
-  const current = existsSync20(file) ? sha256(await readFile18(file)) : null;
+  const current = existsSync21(file) ? sha256(await readFile19(file)) : null;
   if (current !== request.expectedSha256) {
     throw Object.assign(
-      new Error(`${relative.split(path29.sep).join("/")} changed on disk since this page loaded it; press Refresh and edit again`),
+      new Error(`${relative.split(path30.sep).join("/")} changed on disk since this page loaded it; press Refresh and edit again`),
       { status: 409 }
     );
   }
-  await writeFile14(file, JSON.stringify(request.set, null, 2) + "\n");
-  return relative.split(path29.sep).join("/");
+  await writeFile15(file, JSON.stringify(request.set, null, 2) + "\n");
+  return relative.split(path30.sep).join("/");
 }
 
 // src/gallery/edit.ts
@@ -15334,7 +15923,7 @@ function createGalleryEditHandler(opts) {
   const history = /* @__PURE__ */ new Map();
   const manifestOf = async (project) => {
     try {
-      return path30.resolve(await opts.manifestFor(typeof project === "string" ? project : void 0));
+      return path31.resolve(await opts.manifestFor(typeof project === "string" ? project : void 0));
     } catch {
       return null;
     }
@@ -15344,7 +15933,7 @@ function createGalleryEditHandler(opts) {
     if (undo.success) {
       const manifestPath2 = await manifestOf(undo.data.project);
       if (!manifestPath2) throw new ManifestEditError("no manifest to undo an edit in");
-      const current = await readFile19(manifestPath2, "utf8");
+      const current = await readFile20(manifestPath2, "utf8");
       if (sha256(current) !== undo.data.expectedSha256) throw new ManifestDriftError(manifestPath2);
       const stack = history.get(manifestPath2) ?? [];
       const last = stack[stack.length - 1];
@@ -15354,17 +15943,17 @@ function createGalleryEditHandler(opts) {
         throw Object.assign(new Error("the manifest changed outside the gallery since its last edit; undo would discard that change"), { status: 409 });
       }
       const tmp = manifestPath2 + ".pixelkiln-undo";
-      await writeFile15(tmp, last.before);
+      await writeFile16(tmp, last.before);
       await rename9(tmp, manifestPath2);
       stack.pop();
-      log2(`  manifest edit undone in ${path30.relative(process.cwd(), manifestPath2) || manifestPath2}`);
+      log2(`  manifest edit undone in ${path31.relative(process.cwd(), manifestPath2) || manifestPath2}`);
       return opts.reload();
     }
     const manifestPath = await manifestOf(body?.project);
-    const before = manifestPath ? await readFile19(manifestPath, "utf8").catch(() => null) : null;
+    const before = manifestPath ? await readFile20(manifestPath, "utf8").catch(() => null) : null;
     const build = await apply(body);
     if (manifestPath && before !== null) {
-      const after = await readFile19(manifestPath, "utf8").catch(() => null);
+      const after = await readFile20(manifestPath, "utf8").catch(() => null);
       if (after !== null && after !== before) {
         const stack = history.get(manifestPath) ?? [];
         stack.push({ before, afterSha: sha256(after) });
@@ -15419,7 +16008,7 @@ function createEditApplier(opts, log2) {
       } catch (error) {
         throw new ManifestEditError(error instanceof Error ? error.message : String(error));
       }
-      const written = await saveProjectImage(path30.dirname(path30.resolve(manifestPath2)), upload.data);
+      const written = await saveProjectImage(path31.dirname(path31.resolve(manifestPath2)), upload.data);
       log2(`  image added: ${written}`);
       return opts.reload();
     }
@@ -15486,7 +16075,7 @@ function createEditApplier(opts, log2) {
     }
     const result = await applyManifestEdit(manifestPath, parsed.data);
     if (result.changed) {
-      const relative = path30.relative(process.cwd(), result.manifestPath);
+      const relative = path31.relative(process.cwd(), result.manifestPath);
       const shown = !relative || relative.startsWith("..") ? result.manifestPath : relative;
       log2(`  manifest edited: ${describeEdit(parsed.data)} in ${shown}`);
     }
@@ -15537,8 +16126,8 @@ function createGalleryPriceHandler(opts) {
 }
 
 // src/pipeline/history.ts
-import { existsSync as existsSync21 } from "fs";
-import path31 from "path";
+import { existsSync as existsSync22 } from "fs";
+import path32 from "path";
 var HISTORY_ENV = "PIXELKILN_HISTORY";
 function historyLimit(manifest, env = process.env) {
   if (manifest?.history !== void 0) return manifest.history;
@@ -15625,10 +16214,10 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
   }
   for (let i = 0; i < entry.outputs.length; i++) {
     const file = currentEntryOutputPath(entry, spec, i);
-    if (!existsSync21(file)) continue;
+    if (!existsSync22(file)) continue;
     if (await sha256File(file) !== entry.outputs[i].sha256 && !opts.force) {
       throw new OverwriteRefusedError(
-        `${path31.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`,
+        `${path32.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`,
         [file]
       );
     }
@@ -15681,15 +16270,20 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
 // src/gallery/snapshot.ts
 var PROJECT_FILE_TYPE = "application/octet-stream";
 function galleryMediaId(absolutePath) {
-  return createHash4("sha256").update(path32.resolve(absolutePath)).digest("hex").slice(0, 24);
+  return createHash4("sha256").update(path33.resolve(absolutePath)).digest("hex").slice(0, 24);
 }
 function galleryMediaRoute(id) {
   return `/media/${id}`;
 }
+function renderedSize(entry) {
+  const vfx = entry?.providerMetadata?.[entry.provider]?.vfx;
+  return typeof vfx?.width === "number" && typeof vfx.height === "number" ? { width: vfx.width, height: vfx.height } : null;
+}
 function isDeclared(loaded, styleId, assetId) {
   const asset = loaded.manifest.assets[assetId];
-  if (!asset || !loaded.manifest.styles[styleId]) return false;
-  return asset.styles.length === 0 || asset.styles.includes(styleId);
+  const style = loaded.manifest.styles[styleId];
+  if (!asset || !style) return false;
+  return assetInStyle(asset, styleId, style);
 }
 function matchesFilter(filter, styleId, assetId) {
   if (filter?.styles?.length && !filter.styles.includes(styleId)) return false;
@@ -15700,9 +16294,9 @@ function describeHistory(media, entry, cacheDir) {
   return (entry.history ?? []).map((generation, i) => {
     const outputs = generation.outputs.map((output) => {
       const mediaType = output.mediaType ?? MediaType.PNG;
-      const file = path32.join(cacheDir, cacheFileName(output.sha256, mediaType));
+      const file = path33.join(cacheDir, cacheFileName(output.sha256, mediaType));
       let url = null;
-      if (existsSync22(file)) {
+      if (existsSync23(file)) {
         const id = galleryMediaId(file);
         media.set(id, { path: file, contentType: mediaType });
         url = `${galleryMediaRoute(id)}?v=${output.sha256.slice(0, 24)}`;
@@ -15734,7 +16328,7 @@ function describeHistory(media, entry, cacheDir) {
 var MAX_COMPARED_BYTES = 8 * 1024 * 1024;
 async function samePixels(a, b) {
   try {
-    const [left, right] = await Promise.all([readFile20(a), readFile20(b)]);
+    const [left, right] = await Promise.all([readFile21(a), readFile21(b)]);
     if (left.length > MAX_COMPARED_BYTES || right.length > MAX_COMPARED_BYTES) return false;
     const x = decodePng(left);
     const y = decodePng(right);
@@ -15832,10 +16426,10 @@ async function describeOutput(media, root, absolutePath, recorded = {}) {
 async function describeQuality(media, root, inspection) {
   const outputPaths = inspection.outputs ?? [inspection.output];
   const outputs = await Promise.all(
-    outputPaths.map((file) => describeOutput(media, root, path32.resolve(root, file)))
+    outputPaths.map((file) => describeOutput(media, root, path33.resolve(root, file)))
   );
-  const recordPath = path32.resolve(root, inspection.record);
-  const recordExists = existsSync22(recordPath);
+  const recordPath = path33.resolve(root, inspection.record);
+  const recordExists = existsSync23(recordPath);
   let options = null;
   let check = null;
   if (recordExists) {
@@ -15854,7 +16448,7 @@ async function describeQuality(media, root, inspection) {
   return {
     state: inspection.state,
     reason: inspection.reason,
-    output: portableOutputPath(path32.resolve(root, inspection.output), root),
+    output: portableOutputPath(path33.resolve(root, inspection.output), root),
     record: portableOutputPath(recordPath, root),
     recordExists,
     outputs,
@@ -15892,9 +16486,9 @@ async function buildGallerySnapshot(opts) {
   const media = /* @__PURE__ */ new Map();
   const plan = await buildPlan(specs, lock);
   const items = [];
-  const manifestText = await readFile20(loaded.path, "utf8");
+  const manifestText = await readFile21(loaded.path, "utf8");
   const manifestSha256 = sha256(manifestText);
-  const cacheDir = path32.resolve(path32.dirname(opts.lockPath), ".pixelkiln", "cache");
+  const cacheDir = path33.resolve(path33.dirname(opts.lockPath), ".pixelkiln", "cache");
   let rawStyles = {};
   try {
     const raw = JSON.parse(manifestText);
@@ -15918,12 +16512,12 @@ async function buildGallerySnapshot(opts) {
         )
       );
       if (spec.source) {
-        const editPath = path32.resolve(root, spec.source);
+        const editPath = path33.resolve(root, spec.source);
         const memberCount = sourceIsStem(spec.source, entry, root) ? entry.outputs.length : 1;
         const editShas = await Promise.all(
           Array.from({ length: memberCount }, async (_, index) => {
             const file = sourceOutputPath(spec.source, entry, index, root);
-            return { file, sha256: existsSync22(file) ? await sha256File(file) : null };
+            return { file, sha256: existsSync23(file) ? await sha256File(file) : null };
           })
         );
         edits = await Promise.all(editShas.map(({ file, sha256: editSha }) => describeOutput(media, root, file, { sha256: editSha })));
@@ -15931,7 +16525,7 @@ async function buildGallerySnapshot(opts) {
         const companion = await readHandEditCompanion(editPath);
         if (companion) {
           const projectPath = handEditProjectPath(editPath);
-          const project = companion.project && existsSync22(projectPath) ? await fileInfo(projectPath) : null;
+          const project = companion.project && existsSync23(projectPath) ? await fileInfo(projectPath) : null;
           let projectUrl = null;
           if (project) {
             const id = galleryMediaId(projectPath);
@@ -15967,8 +16561,8 @@ async function buildGallerySnapshot(opts) {
         editStatus = edits.some((member) => !member.exists) ? "missing" : editChanged.every((changed) => !changed) ? "same" : regenerated ? "regenerated-since" : "edited";
       }
     } else if (spec.source) {
-      outputs = [await describeOutput(media, root, path32.resolve(root, spec.source))];
-    } else if (!entry && existsSync22(spec.outFile)) {
+      outputs = [await describeOutput(media, root, path33.resolve(root, spec.source))];
+    } else if (!entry && existsSync23(spec.outFile)) {
       outputs = [await describeOutput(media, root, spec.outFile)];
     } else {
       outputs = [];
@@ -15989,8 +16583,8 @@ async function buildGallerySnapshot(opts) {
       generator: entry?.generator ?? spec.generator,
       prompt: entry?.prompt ?? spec.prompt,
       currentPrompt: entry && entry.prompt !== spec.prompt ? spec.prompt : null,
-      width: entry?.width ?? spec.width,
-      height: entry?.height ?? spec.height,
+      width: renderedSize(entry)?.width ?? entry?.width ?? spec.width,
+      height: renderedSize(entry)?.height ?? entry?.height ?? spec.height,
       tileFeature: entry?.tileFeature ?? spec.tileFeature ?? null,
       fps: quality?.frameSet?.fps ?? metadataFps(entry) ?? spec.quality?.fps ?? null,
       cost: entry?.cost ?? 0,
@@ -16171,7 +16765,7 @@ async function buildGallerySnapshot(opts) {
       id: loaded.manifest.name,
       name: loaded.manifest.name,
       manifest: loaded.path,
-      lock: path32.resolve(opts.lockPath),
+      lock: path33.resolve(opts.lockPath),
       root,
       provider: loaded.manifest.provider,
       account: null,
@@ -16197,7 +16791,7 @@ async function buildGallerySnapshot(opts) {
   return { snapshot, media };
 }
 async function buildWorkspaceGallerySnapshot(opts) {
-  const dir = path32.dirname(path32.resolve(opts.workspacePath));
+  const dir = path33.dirname(path33.resolve(opts.workspacePath));
   const media = /* @__PURE__ */ new Map();
   const projects = [];
   const items = [];
@@ -16240,11 +16834,11 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: loaded.manifest.name,
         manifest: manifestPath,
-        lock: path32.resolve(lockPath),
+        lock: path33.resolve(lockPath),
         root: loaded.root,
         provider: loaded.manifest.provider,
         account: project.account ?? null,
-        manifestSha256: manifestSha256 ?? sha256(await readFile20(manifestPath, "utf8")),
+        manifestSha256: manifestSha256 ?? sha256(await readFile21(manifestPath, "utf8")),
         historyLimit: historyLimit(loaded.manifest),
         entries: Object.keys(lock.entries).length,
         items: projectItems.length,
@@ -16256,8 +16850,8 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: project.id,
         manifest: manifestPath,
-        lock: path32.resolve(lockPath),
-        root: path32.dirname(manifestPath),
+        lock: path33.resolve(lockPath),
+        root: path33.dirname(manifestPath),
         provider: project.provider,
         account: project.account ?? null,
         manifestSha256: null,
@@ -16284,7 +16878,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
       version: 1,
       generatedAt: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
       project: null,
-      workspace: { path: path32.resolve(opts.workspacePath), dir, projects },
+      workspace: { path: path33.resolve(opts.workspacePath), dir, projects },
       filter,
       totals: {
         entries: projects.reduce((sum, project) => sum + project.entries, 0),
@@ -16303,10 +16897,10 @@ async function buildWorkspaceGallerySnapshot(opts) {
 // src/gallery/server.ts
 import { randomBytes } from "crypto";
 import { createServer as createServer2 } from "http";
-import { readFile as readFile21 } from "fs/promises";
+import { readFile as readFile22 } from "fs/promises";
 
 // src/gallery/page.ts
-import { existsSync as existsSync23, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync24, readFileSync as readFileSync5 } from "fs";
 
 // src/gallery/client-bundle.ts
 import { createRequire } from "module";
@@ -16347,7 +16941,7 @@ function clientAssets() {
   const prebuilt = new URL("gallery.js", CLIENT_DIR);
   client ??= {
     css: readFileSync5(new URL("gallery.css", CLIENT_DIR), "utf8"),
-    js: existsSync23(prebuilt) ? readFileSync5(prebuilt, "utf8") : bundleGalleryClient()
+    js: existsSync24(prebuilt) ? readFileSync5(prebuilt, "utf8") : bundleGalleryClient()
   };
   return client;
 }
@@ -16618,7 +17212,7 @@ async function serveGallery(opts) {
         const asset = reviewAssets.get(jobId)?.get(url2.pathname);
         if (!asset) return fail(404, "no such review asset");
         try {
-          const bytes = await readFile21(asset.path);
+          const bytes = await readFile22(asset.path);
           res.writeHead(200, {
             "Content-Type": asset.contentType,
             "Cache-Control": "no-store",
@@ -16701,7 +17295,7 @@ async function serveGallery(opts) {
         if (!asset) return fail(404, "no such gallery media");
         let bytes;
         try {
-          bytes = await readFile21(asset.path);
+          bytes = await readFile22(asset.path);
         } catch {
           return fail(404, "gallery media is no longer on disk; refresh the page");
         }
@@ -17074,6 +17668,8 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       const anchor = spec.character?.styleAnchor;
       const anchorEntry = anchor ? lock.entries[lockKey(anchor.spec.styleId, anchor.spec.assetId)] : void 0;
       const replacedMetadata = previousEntry?.providerMetadata?.[provider.id];
+      const lastGeneration = previousEntry?.status === "downloaded" ? previousEntry : previousEntry?.history?.[0];
+      const lastGenerationMetadata = lastGeneration?.providerMetadata?.[provider.id];
       const parentOutputs = spec.character?.kind === "outfit" && parentEntry ? parentEntry.outputs.map((output, index) => ({
         path: currentEntryOutputPath(parentEntry, spec.character.parentSpec, index),
         role: output.role
@@ -17086,6 +17682,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         ...anchorEntry?.objectId ? { styleObjectId: anchorEntry.objectId } : {},
         ...parentOutputs ? { parentOutputs } : {},
         ...replacedMetadata ? { replacedMetadata } : {},
+        ...lastGenerationMetadata ? { lastGenerationMetadata } : {},
         ...previousMetadata ? { previousMetadata } : {},
         checkpoint: async (checkpoint) => {
           if (!checkpoint.jobId) throw new Error("Provider checkpoint returned an empty job id");
@@ -17161,13 +17758,13 @@ function ownedReferenceImageId(spec, lock, providerId) {
 }
 
 // src/pick/server.ts
-import { existsSync as existsSync25 } from "fs";
-import { readFile as readFile23 } from "fs/promises";
+import { existsSync as existsSync26 } from "fs";
+import { readFile as readFile24 } from "fs/promises";
 
 // src/pipeline/init.ts
-import { readdir, readFile as readFile22, writeFile as writeFile16 } from "fs/promises";
-import { existsSync as existsSync24 } from "fs";
-import path33 from "path";
+import { readdir, readFile as readFile23, writeFile as writeFile17 } from "fs/promises";
+import { existsSync as existsSync25 } from "fs";
+import path34 from "path";
 function pngSize(buf) {
   if (buf.length < 24) return null;
   const isPng = buf.readUInt32BE(0) === 2303741511 && buf.readUInt32BE(4) === 218765834;
@@ -17181,7 +17778,7 @@ function slugify(value) {
 async function walk(dir, exclude) {
   const out = [];
   for (const entry of await readdir(dir, { withFileTypes: true })) {
-    const full = path33.join(dir, entry.name);
+    const full = path34.join(dir, entry.name);
     if (exclude.some((x) => full.includes(x))) continue;
     if (entry.isDirectory()) out.push(...await walk(full, exclude));
     else if (entry.name.toLowerCase().endsWith(".png")) out.push(full);
@@ -17195,14 +17792,14 @@ async function scanAssets(root, opts = {}) {
   const skipped = [];
   const seen = /* @__PURE__ */ new Map();
   for (const file of files.sort()) {
-    const size = pngSize(await readFile22(file));
+    const size = pngSize(await readFile23(file));
     if (!size) {
       skipped.push(`${file} (not a readable PNG)`);
       continue;
     }
-    const rel = path33.relative(root, file);
-    const category = path33.dirname(rel) === "." ? "" : path33.dirname(rel);
-    let id = slugify(path33.basename(rel));
+    const rel = path34.relative(root, file);
+    const category = path34.dirname(rel) === "." ? "" : path34.dirname(rel);
+    let id = slugify(path34.basename(rel));
     if (seen.has(id)) {
       const n = seen.get(id) + 1;
       seen.set(id, n);
@@ -17260,10 +17857,10 @@ function mode(values) {
   return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? 64;
 }
 async function writeManifestFile(target, manifest) {
-  if (existsSync24(target)) {
+  if (existsSync25(target)) {
     throw new Error(`${target} already exists; refusing to overwrite an existing manifest.`);
   }
-  await writeFile16(target, JSON.stringify(manifest, null, 2) + "\n");
+  await writeFile17(target, JSON.stringify(manifest, null, 2) + "\n");
 }
 
 // src/pick/sheet.ts
@@ -17676,13 +18273,13 @@ async function currentArt(entry, spec) {
   const previous = primaryOutput({ ...entry, outputs: entry.supersededOutputs });
   if (!previous) return null;
   const file = resolveOutputPath(previous.path, spec.root);
-  if (!existsSync25(file)) return null;
+  if (!existsSync26(file)) return null;
   const contentType = previous.mediaType ?? mediaTypeFromExtension(file);
   if (!contentType) return null;
   let width = entry.width;
   let height = entry.height;
   if (contentType === "image/png") {
-    const size = pngSize(await readFile23(file));
+    const size = pngSize(await readFile24(file));
     if (size) ({ width, height } = size);
   }
   return { path: file, contentType, width, height };
@@ -17690,7 +18287,7 @@ async function currentArt(entry, spec) {
 async function cachedFrame(url) {
   if (!url.startsWith("file://")) return null;
   const file = url.slice("file://".length);
-  const contentType = mediaTypeFromExtension(file) ?? detectMediaType(await readFile23(file).catch(() => Buffer.alloc(0))) ?? "application/octet-stream";
+  const contentType = mediaTypeFromExtension(file) ?? detectMediaType(await readFile24(file).catch(() => Buffer.alloc(0))) ?? "application/octet-stream";
   return { path: file, contentType };
 }
 async function prepareReview(provider, lock, opts = {}) {
@@ -18236,15 +18833,15 @@ function createGenerateHandlers(opts) {
 }
 
 // src/gallery/editor.ts
-import { readFile as readFile25 } from "fs/promises";
-import path35 from "path";
+import { readFile as readFile26 } from "fs/promises";
+import path36 from "path";
 
 // src/editor/install.ts
 import { createHash as createHash5 } from "crypto";
-import { existsSync as existsSync26 } from "fs";
-import { mkdir as mkdir12, readFile as readFile24, rename as rename10, rm as rm11, stat as stat3, writeFile as writeFile17 } from "fs/promises";
+import { existsSync as existsSync27 } from "fs";
+import { mkdir as mkdir13, readFile as readFile25, rename as rename10, rm as rm11, stat as stat3, writeFile as writeFile18 } from "fs/promises";
 import os3 from "os";
-import path34 from "path";
+import path35 from "path";
 
 // tools/pixelorama-bridge/pin.json
 var pin_default = {
@@ -18308,15 +18905,15 @@ var EditorInstallError = class extends Error {
 };
 function editorToolsRoot() {
   const override = process.env.PIXELKILN_TOOLS_DIR?.trim();
-  if (override) return path34.resolve(override);
-  if (process.platform === "darwin") return path34.join(os3.homedir(), "Library", "Caches", "pixelkiln", "tools");
+  if (override) return path35.resolve(override);
+  if (process.platform === "darwin") return path35.join(os3.homedir(), "Library", "Caches", "pixelkiln", "tools");
   if (process.platform === "win32") {
-    return path34.join(process.env.LOCALAPPDATA ?? path34.join(os3.homedir(), "AppData", "Local"), "pixelkiln", "tools");
+    return path35.join(process.env.LOCALAPPDATA ?? path35.join(os3.homedir(), "AppData", "Local"), "pixelkiln", "tools");
   }
-  return path34.join(process.env.XDG_CACHE_HOME ?? path34.join(os3.homedir(), ".cache"), "pixelkiln", "tools");
+  return path35.join(process.env.XDG_CACHE_HOME ?? path35.join(os3.homedir(), ".cache"), "pixelkiln", "tools");
 }
 function editorDir(pin = EDITOR_PIN, root = editorToolsRoot()) {
-  return path34.join(root, "pixelorama", pin.release ?? "unpublished");
+  return path35.join(root, "pixelorama", pin.release ?? "unpublished");
 }
 function editorBaseUrl(pin = EDITOR_PIN) {
   const override = process.env.PIXELKILN_EDITOR_URL?.trim();
@@ -18326,7 +18923,7 @@ function editorBaseUrl(pin = EDITOR_PIN) {
 }
 async function sha256Of(file) {
   try {
-    return createHash5("sha256").update(await readFile24(file)).digest("hex");
+    return createHash5("sha256").update(await readFile25(file)).digest("hex");
   } catch {
     return null;
   }
@@ -18339,8 +18936,8 @@ async function editorStatus(opts = {}) {
   let totalBytes = 0;
   for (const [name, expected] of Object.entries(pin.files)) {
     totalBytes += expected.bytes;
-    const file = path34.join(dir, name);
-    const info = existsSync26(file) ? await stat3(file).catch(() => null) : null;
+    const file = path35.join(dir, name);
+    const info = existsSync27(file) ? await stat3(file).catch(() => null) : null;
     if (info && info.size === expected.bytes && await sha256Of(file) === expected.sha256) {
       installedBytes += expected.bytes;
     } else {
@@ -18369,7 +18966,7 @@ async function installEditor(opts = {}) {
     );
   }
   if (!baseUrl) throw new EditorInstallError("no download location for the editor build");
-  await mkdir12(dir, { recursive: true });
+  await mkdir13(dir, { recursive: true });
   const downloaded = [];
   const skipped = Object.keys(pin.files).filter((name) => !before.missing.includes(name));
   let fetchedBytes = before.installedBytes;
@@ -18397,10 +18994,10 @@ async function installEditor(opts = {}) {
     if (digest2 !== expected.sha256) {
       throw new EditorInstallError(`${name}: sha256 ${digest2.slice(0, 12)}\u2026 does not match the pinned ${expected.sha256.slice(0, 12)}\u2026`, name);
     }
-    const final = path34.join(dir, name);
+    const final = path35.join(dir, name);
     const tmp = `${final}.${process.pid}.part`;
     try {
-      await writeFile17(tmp, bytes);
+      await writeFile18(tmp, bytes);
       await rename10(tmp, final);
     } finally {
       await rm11(tmp, { force: true });
@@ -18443,7 +19040,7 @@ var EDITOR_CONTENT_TYPES = {
   ".json": "application/json; charset=utf-8"
 };
 function editorContentType(name) {
-  return EDITOR_CONTENT_TYPES[path34.extname(name).toLowerCase()] ?? null;
+  return EDITOR_CONTENT_TYPES[path35.extname(name).toLowerCase()] ?? null;
 }
 
 // src/gallery/editor.ts
@@ -18519,7 +19116,7 @@ function createGalleryEditorHandlers(opts = {}) {
       if (!status.installed) return null;
       let bytes;
       try {
-        bytes = await readFile25(path35.join(dir, name));
+        bytes = await readFile26(path36.join(dir, name));
       } catch {
         verified = null;
         return null;
@@ -18559,7 +19156,7 @@ async function serveUntilStopped(initial, reload, args, access2) {
   };
   const loadProject = async (project) => {
     const ctx = await access2.loadProject(project);
-    loadProjectEnv(path36.dirname(ctx.loaded.path));
+    loadProjectEnv(path37.dirname(ctx.loaded.path));
     return ctx;
   };
   const loadProjectEnv = (dir) => {
@@ -18568,7 +19165,7 @@ async function serveUntilStopped(initial, reload, args, access2) {
     for (const [name, value] of Object.entries(declared)) {
       if (credentialNames.has(name) && name in process.env && process.env[name] !== value) {
         throw new Error(
-          `${path36.relative(process.cwd(), dir) || "."} sets ${name} to a different value than the one this gallery already loaded; run a separate gallery for that project so its work uses its own account.`
+          `${path37.relative(process.cwd(), dir) || "."} sets ${name} to a different value than the one this gallery already loaded; run a separate gallery for that project so its work uses its own account.`
         );
       }
     }
@@ -18576,7 +19173,7 @@ async function serveUntilStopped(initial, reload, args, access2) {
   };
   const quoters = /* @__PURE__ */ new Map();
   const quoteFor = async (project) => {
-    loadProjectEnv(path36.dirname(path36.resolve(await access2.manifestFor(project))));
+    loadProjectEnv(path37.dirname(path37.resolve(await access2.manifestFor(project))));
     const key = process.env.PIXELLAB_API_KEY;
     if (!key) return null;
     let quoter = quoters.get(key);
@@ -18627,8 +19224,8 @@ async function serveUntilStopped(initial, reload, args, access2) {
 }
 async function runGallery(args) {
   if (args.workspace) {
-    const workspacePath = path36.resolve(args.workspace);
-    if (!existsSync27(workspacePath)) {
+    const workspacePath = path37.resolve(args.workspace);
+    if (!existsSync28(workspacePath)) {
       throw new Error(`Workspace catalog not found: ${workspacePath}`);
     }
     const filter2 = { styles: args.styles, assets: args.assets };
@@ -18648,7 +19245,7 @@ async function runGallery(args) {
     const registered = async (projectId) => {
       const project = (await loadWorkspace(workspacePath)).projects.find((candidate) => candidate.id === projectId);
       if (!projectId || !project) throw new Error(`unknown workspace project "${projectId ?? ""}"`);
-      return resolveProject(path36.dirname(workspacePath), project);
+      return resolveProject(path37.dirname(workspacePath), project);
     };
     await serveUntilStopped(initial, build2, args, {
       manifestFor: async (projectId) => (await registered(projectId)).manifestPath,
@@ -18673,7 +19270,7 @@ async function runGallery(args) {
     return buildGallerySnapshot({ ...fresh, filter });
   };
   await serveUntilStopped(await build(), reload, args, {
-    manifestFor: () => path36.resolve(args.manifest),
+    manifestFor: () => path37.resolve(args.manifest),
     loadProject: () => openProject(args.manifest, { lockPath: args.lock, env: false })
   });
 }
@@ -18916,7 +19513,7 @@ async function runLifecycle(args, wave, spent) {
         log(`  Packaging stays blocked until each refined PNG has a current human approval.`);
       }
     }
-    return args.command === "gen" && submitted > 0 && total.downloaded > 0 && !total.failed && specs.some((spec) => spec.character?.parentSpec || spec.character?.styleAnchor || spec.revision || spec.mirror);
+    return args.command === "gen" && submitted > 0 && total.downloaded > 0 && !total.failed && specs.some((spec) => spec.character?.parentSpec || spec.character?.styleAnchor || spec.revision || spec.mirror || spec.scene || spec.vfx?.sprite && "file" in spec.vfx.sprite);
   }
   return false;
 }
@@ -18982,18 +19579,18 @@ async function runRestoreGeneration(args) {
 }
 
 // src/cli/commands/housekeeping.ts
-import { existsSync as existsSync29 } from "fs";
+import { existsSync as existsSync30 } from "fs";
 
 // src/pipeline/cache-health.ts
-import { existsSync as existsSync28 } from "fs";
-import { readFile as readFile26, readdir as readdir2, rm as rm12 } from "fs/promises";
-import path37 from "path";
+import { existsSync as existsSync29 } from "fs";
+import { readFile as readFile27, readdir as readdir2, rm as rm12 } from "fs/promises";
+import path38 from "path";
 async function inspectCaches(lock, lockPath, options = {}) {
-  if (options.prune && !existsSync28(lockPath)) {
-    throw new Error(`Refusing to prune without an existing lockfile at ${path37.resolve(lockPath)}`);
+  if (options.prune && !existsSync29(lockPath)) {
+    throw new Error(`Refusing to prune without an existing lockfile at ${path38.resolve(lockPath)}`);
   }
-  const contentDir = path37.resolve(path37.dirname(lockPath), ".pixelkiln", "cache");
-  const remotePath = path37.resolve(cachePathFor(lockPath));
+  const contentDir = path38.resolve(path38.dirname(lockPath), ".pixelkiln", "cache");
+  const remotePath = path38.resolve(cachePathFor(lockPath));
   const referenced = referencedHashes(lock);
   let content = await inspectContentCache(contentDir, referenced);
   let remoteHashes = await inspectRemoteHashCache(remotePath);
@@ -19005,7 +19602,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
     ]);
     for (const name of names) {
       try {
-        await rm12(path37.join(contentDir, name), { force: true });
+        await rm12(path38.join(contentDir, name), { force: true });
         removed.contentFiles++;
       } catch {
       }
@@ -19014,7 +19611,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
       await saveCache(remotePath, { version: 1, hashes: {} });
       removed.resetRemoteHashCache = true;
     } else if (remoteHashes.invalidIds.length) {
-      const cache = parseCache(JSON.parse(await readFile26(remotePath, "utf8")));
+      const cache = parseCache(JSON.parse(await readFile27(remotePath, "utf8")));
       for (const id of remoteHashes.invalidIds) delete cache.hashes[id];
       removed.remoteHashEntries = remoteHashes.invalidIds.length;
       await saveCache(remotePath, cache);
@@ -19032,7 +19629,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
 async function inspectContentCache(contentDir, referenced) {
   const report = {
     path: contentDir,
-    exists: existsSync28(contentDir),
+    exists: existsSync29(contentDir),
     files: 0,
     bytes: 0,
     valid: 0,
@@ -19053,12 +19650,12 @@ async function inspectContentCache(contentDir, referenced) {
       continue;
     }
     report.files++;
-    const file = path37.join(contentDir, entry.name);
+    const file = path38.join(contentDir, entry.name);
     const mediaType = mediaTypeFromExtension(entry.name);
     const expected = mediaType ? entry.name.slice(0, -4) : "";
     let bytes;
     try {
-      bytes = await readFile26(file);
+      bytes = await readFile27(file);
       report.bytes += bytes.length;
     } catch (err) {
       report.invalid.push({
@@ -19096,7 +19693,7 @@ async function inspectContentCache(contentDir, referenced) {
 async function inspectRemoteHashCache(remotePath) {
   const report = {
     path: remotePath,
-    exists: existsSync28(remotePath),
+    exists: existsSync29(remotePath),
     entries: 0,
     valid: 0,
     invalidIds: [],
@@ -19105,7 +19702,7 @@ async function inspectRemoteHashCache(remotePath) {
   if (!report.exists) return report;
   let cache;
   try {
-    cache = parseCache(JSON.parse(await readFile26(remotePath, "utf8")));
+    cache = parseCache(JSON.parse(await readFile27(remotePath, "utf8")));
   } catch (err) {
     report.error = err instanceof Error ? err.message : String(err);
     return report;
@@ -19169,7 +19766,7 @@ async function runAccept(args) {
     let intact = true;
     for (const output of entry.outputs) {
       const file = resolveOutputPath(output.path, item.spec.root);
-      if (!existsSync29(file) || await sha256File(file) !== output.sha256) {
+      if (!existsSync30(file) || await sha256File(file) !== output.sha256) {
         intact = false;
         break;
       }
@@ -19224,42 +19821,42 @@ This drops their provenance from the lockfile. The art on disk is`);
 }
 
 // src/cli/commands/init.ts
-import path38 from "path";
-import { existsSync as existsSync30 } from "fs";
+import path39 from "path";
+import { existsSync as existsSync31 } from "fs";
 async function runInit(args) {
   if (!args.from) throw new Error("init needs --from <dir> pointing at your existing PNGs.");
-  const root = path38.resolve(args.from);
-  if (!existsSync30(root)) throw new Error(`No directory at ${root}`);
+  const root = path39.resolve(args.from);
+  if (!existsSync31(root)) throw new Error(`No directory at ${root}`);
   const generator = args.generator ?? "map";
   if (generator !== "1dir" && generator !== "map") {
     throw new Error(`--generator must be "1dir" or "map", got "${args.generator}".`);
   }
-  const target = path38.resolve(args.out ?? "pixelkiln.manifest.json");
+  const target = path39.resolve(args.out ?? "pixelkiln.manifest.json");
   const { assets, skipped } = await scanAssets(root, { exclude: args.exclude });
   if (!assets.length) throw new Error(`No PNGs found under ${root}`);
   const manifest = buildManifest(
-    args.name ?? path38.basename(path38.dirname(target)),
+    args.name ?? path39.basename(path39.dirname(target)),
     args.styles[0] ?? "base",
     generator,
-    path38.relative(path38.dirname(target), root) || ".",
+    path39.relative(path39.dirname(target), root) || ".",
     assets
   );
   await writeManifestFile(target, manifest);
-  log(`  scanned ${assets.length} PNG(s) under ${path38.relative(process.cwd(), root)}`);
+  log(`  scanned ${assets.length} PNG(s) under ${path39.relative(process.cwd(), root)}`);
   if (skipped.length) log(`  skipped ${skipped.length} unreadable file(s)`);
-  log(`  wrote ${path38.relative(process.cwd(), target)}`);
+  log(`  wrote ${path39.relative(process.cwd(), target)}`);
   log(`
   Prompts are intentionally empty. To recover the real ones from your`);
   log(`  PixelLab account instead of inventing them:`);
   log(`
-    pixelkiln adopt --manifest ${path38.relative(process.cwd(), target)} --write-prompts
+    pixelkiln adopt --manifest ${path39.relative(process.cwd(), target)} --write-prompts
 `);
 }
 
 // src/pipeline/doctor.ts
-import { constants, existsSync as existsSync31 } from "fs";
+import { constants, existsSync as existsSync32 } from "fs";
 import { access, stat as stat4 } from "fs/promises";
-import path39 from "path";
+import path40 from "path";
 async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   const checks = [];
   const add = (id, level, message6) => checks.push({ id, level, message: message6 });
@@ -19270,8 +19867,8 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   );
   add("lock", "ok", `${Object.keys(lock.entries).length} valid v2 lock entr(ies)`);
   const dirs = [...new Set(specs.flatMap((spec) => [
-    path39.dirname(spec.outFile),
-    ...spec.quality ? [path39.dirname(spec.quality.outFile)] : []
+    path40.dirname(spec.outFile),
+    ...spec.quality ? [path40.dirname(spec.quality.outFile)] : []
   ]))];
   const unwritable = [];
   for (const dir of dirs) {
@@ -19294,7 +19891,7 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     for (let index = 0; index < entry.outputs.length; index++) {
       const output = entry.outputs[index];
       const spec = specByKey.get(key);
-      const absolute = spec ? currentEntryOutputPath(entry, spec, index) : resolveOutputPath(output.path, path39.dirname(lockPath));
+      const absolute = spec ? currentEntryOutputPath(entry, spec, index) : resolveOutputPath(output.path, path40.dirname(lockPath));
       const owner = outputOwners.get(absolute);
       if (owner && owner !== key) duplicateOutputs.push(`${output.path} (${owner}, ${key})`);
       outputOwners.set(absolute, key);
@@ -19309,7 +19906,7 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   } else {
     add("lock-outputs", "ok", `${outputOwners.size} recorded output path(s) are uniquely owned`);
   }
-  const cacheDir = path39.join(path39.dirname(lockPath), ".pixelkiln", "cache");
+  const cacheDir = path40.join(path40.dirname(lockPath), ".pixelkiln", "cache");
   const stranded = [];
   const invalidState = [];
   const staleMapUrls = [];
@@ -19325,11 +19922,11 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     const hasSource = Boolean(entry.sourceUrl || entry.sourceUrls?.length);
     let hasCache = false;
     for (const output of entry.outputs) {
-      const cached = path39.join(
+      const cached = path40.join(
         cacheDir,
         cacheFileName(output.sha256, output.mediaType ?? MediaType.PNG)
       );
-      if (existsSync31(cached) && await sha256File(cached) === output.sha256) {
+      if (existsSync32(cached) && await sha256File(cached) === output.sha256) {
         hasCache = true;
         break;
       }
@@ -19425,16 +20022,16 @@ async function nearestExistingDirectory(start) {
       if ((await stat4(current)).isDirectory()) return current;
     } catch {
     }
-    const parent = path39.dirname(current);
+    const parent = path40.dirname(current);
     if (parent === current) return current;
     current = parent;
   }
 }
 
 // src/pipeline/audit.ts
-import { readFile as readFile27 } from "fs/promises";
-import { existsSync as existsSync32 } from "fs";
-import path40 from "path";
+import { readFile as readFile28 } from "fs/promises";
+import { existsSync as existsSync33 } from "fs";
+import path41 from "path";
 function paletteDistance(asset, reference) {
   if (!asset.length || !reference.length) return 0;
   let total = 0;
@@ -19470,12 +20067,12 @@ async function auditStyle(loaded, specs, styleId, lock) {
   const unreadable = [];
   for (const spec of mine) {
     for (const output of resolveSpecOutputs(spec, lock, loaded.root)) {
-      if (!existsSync32(output.absolutePath)) {
+      if (!existsSync33(output.absolutePath)) {
         missing.push(output.id);
         continue;
       }
       try {
-        const png = decodePng(await readFile27(output.absolutePath));
+        const png = decodePng(await readFile28(output.absolutePath));
         const palette = extractPalette(png, 12);
         assets.push({
           assetId: spec.assetId,
@@ -19499,10 +20096,10 @@ async function auditStyle(loaded, specs, styleId, lock) {
   let referenceFromStyleImages = false;
   const refPalettes = [];
   for (const img of style.styleImages) {
-    const abs = path40.resolve(loaded.root, img.path);
-    if (!existsSync32(abs)) continue;
+    const abs = path41.resolve(loaded.root, img.path);
+    if (!existsSync33(abs)) continue;
     try {
-      refPalettes.push(extractPalette(decodePng(await readFile27(abs)), 12));
+      refPalettes.push(extractPalette(decodePng(await readFile28(abs)), 12));
     } catch {
     }
   }
@@ -19730,24 +20327,24 @@ async function runAudit(args) {
 }
 
 // src/cli/commands/pack.ts
-import path42 from "path";
-import { readFile as readFile28 } from "fs/promises";
+import path43 from "path";
+import { readFile as readFile29 } from "fs/promises";
 
 // src/pipeline/pack.ts
 import { readFileSync as readFileSync6 } from "fs";
-import path41 from "path";
+import path42 from "path";
 var DEFAULT_FRAME_SET_FPS = 12;
 function resolvePackInputs(raw, inputsFilePath) {
   if (!Array.isArray(raw) || !raw.length) {
     throw new Error("--inputs must be a non-empty JSON array of { id, path }");
   }
-  const baseDir = path41.dirname(path41.resolve(inputsFilePath));
+  const baseDir = path42.dirname(path42.resolve(inputsFilePath));
   return raw.map((entry, i) => {
     const e = entry;
     if (typeof e.id !== "string" || typeof e.path !== "string") {
       throw new Error(`--inputs[${i}] needs string "id" and "path"`);
     }
-    return { id: e.id, path: path41.resolve(baseDir, e.path) };
+    return { id: e.id, path: path42.resolve(baseDir, e.path) };
   });
 }
 function packSprites(inputs, options = {}) {
@@ -19831,7 +20428,7 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
     }
     const inputs2 = Object.entries(options.sourceOverrides).map(([id, source]) => ({
       id,
-      path: path41.resolve(source)
+      path: path42.resolve(source)
     }));
     if (!inputs2.length) throw new Error(`No approved quality outputs for style "${styleId}".`);
     const packed2 = packSprites(inputs2, options);
@@ -19855,7 +20452,7 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
     let outputs = resolveEntryOutputs(entry, id, manifestDir);
     const source = sources[id];
     if (source && outputs.length <= 1) {
-      inputs.push({ id, path: path41.resolve(manifestDir, source) });
+      inputs.push({ id, path: path42.resolve(manifestDir, source) });
       continue;
     }
     if (source && sourceIsStem(source, entry, manifestDir)) {
@@ -19884,12 +20481,13 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
         id,
         kind: isFrames ? "frames" : "members",
         ...fps ? { fps } : {},
+        ...isFrames && frameSetLoop(entry) === false ? { loop: false } : {},
         frames: selected.map((output) => output.id)
       });
     }
   }
   for (const [id, source] of Object.entries(sources)) {
-    if (!locked.has(id)) inputs.push({ id, path: path41.resolve(manifestDir, source) });
+    if (!locked.has(id)) inputs.push({ id, path: path42.resolve(manifestDir, source) });
   }
   if (!inputs.length) {
     throw new Error(`No readable sprites for style "${styleId}"; ${noOutput.length} skipped.`);
@@ -19997,7 +20595,7 @@ function mountStyle(lock, styleId, manifestDir, mount, cells, sources = {}, outp
     const source = sources[id];
     const entry = lock.entries[`${styleId}/${id}`];
     if (source && !(entry && sourceIsStem(source, entry, manifestDir))) {
-      placements.push({ id, path: path41.resolve(manifestDir, source), cell });
+      placements.push({ id, path: path42.resolve(manifestDir, source), cell });
       continue;
     }
     if (source && entry) {
@@ -20030,7 +20628,7 @@ function mountStyle(lock, styleId, manifestDir, mount, cells, sources = {}, outp
       `Nothing to mount for style "${styleId}": ${ids.length} asset(s) declare a cell, but none has generated output or a \`source\`. Run \`pixelkiln gen --style ${styleId}\`, or point each at a file.${detail}`
     );
   }
-  const basePng = mount.base ? readFileSync6(path41.resolve(manifestDir, mount.base)) : void 0;
+  const basePng = mount.base ? readFileSync6(path42.resolve(manifestDir, mount.base)) : void 0;
   const mounted = mountSprites(placements, {
     cellWidth: mount.cellWidth,
     cellHeight: mount.cellHeight,
@@ -20040,7 +20638,7 @@ function mountStyle(lock, styleId, manifestDir, mount, cells, sources = {}, outp
     ...mounted,
     sources: mount.base ? [{
       id: "$base",
-      path: path41.resolve(manifestDir, mount.base),
+      path: path42.resolve(manifestDir, mount.base),
       sha256: sha256(basePng),
       included: true
     }, ...mounted.sources] : mounted.sources,
@@ -20422,7 +21020,7 @@ function renderGodotSpriteFrames(atlas, opts) {
     );
   };
   for (const set of atlas.sets ?? []) {
-    if (set.kind === "frames") animation(set.id, set.frames, set.fps ?? GODOT_DEFAULT_SPEED, true);
+    if (set.kind === "frames") animation(set.id, set.frames, set.fps ?? GODOT_DEFAULT_SPEED, set.loop ?? true);
     else for (const id of set.frames) animation(id, [id], GODOT_DEFAULT_SPEED, false);
   }
   for (const frame of atlas.frames) {
@@ -20444,12 +21042,12 @@ async function runPack(args) {
     if (args.primaryOnly || args.outputRoles.length) {
       throw new Error("--primary-only and --output-role require manifest-driven pack");
     }
-    const raw = JSON.parse(await readFile28(path42.resolve(args.inputs), "utf8"));
+    const raw = JSON.parse(await readFile29(path43.resolve(args.inputs), "utf8"));
     const inputs = resolvePackInputs(raw, args.inputs);
     const { png, atlas, skipped, sources } = packSprites(inputs, { columns: args.columns });
     const format = sheetFormat(args);
-    const base = path42.resolve(args.out.replace(/\.(?:png|json|tres)$/i, ""));
-    const { extension, document } = renderSheetDocument(format, atlas, { imageName: path42.basename(`${base}.png`) });
+    const base = path43.resolve(args.out.replace(/\.(?:png|json|tres)$/i, ""));
+    const { extension, document } = renderSheetDocument(format, atlas, { imageName: path43.basename(`${base}.png`) });
     const outputs = [
       { path: `${base}.png`, data: png },
       { path: `${base}${extension}`, data: document }
@@ -20462,7 +21060,7 @@ async function runPack(args) {
     log(
       `  ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s), ${(png.length / 1024).toFixed(1)} KB (${format})`
     );
-    log(`    ${path42.relative(process.cwd(), base)}.png + ${extension} + .pixelkiln.json`);
+    log(`    ${path43.relative(process.cwd(), base)}.png + ${extension} + .pixelkiln.json`);
     for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     return;
   }
@@ -20470,7 +21068,7 @@ async function runPack(args) {
   if (args.primaryOnly && args.outputRoles.length) {
     throw new Error("pack accepts either --primary-only or --output-role, not both");
   }
-  const manifestDir = path42.dirname(path42.resolve(args.manifest));
+  const manifestDir = path43.dirname(path43.resolve(args.manifest));
   const styleIds = args.styles.length ? args.styles : Object.keys(loaded.manifest.styles);
   for (const styleId of styleIds) {
     const style = loaded.manifest.styles[styleId];
@@ -20485,9 +21083,9 @@ async function runPack(args) {
       sourceOverrides: qualitySources,
       sources: manifestSources(loaded.manifest, styleId)
     });
-    const base = args.out ? path42.resolve(args.out.replace(/\.(?:png|json|tres)$/i, "")) : path42.resolve(manifestDir, style.outDir, `${styleId}-sheet`);
+    const base = args.out ? path43.resolve(args.out.replace(/\.(?:png|json|tres)$/i, "")) : path43.resolve(manifestDir, style.outDir, `${styleId}-sheet`);
     const format = sheetFormat(args);
-    const { extension, document } = renderSheetDocument(format, atlas, { imageName: path42.basename(`${base}.png`) });
+    const { extension, document } = renderSheetDocument(format, atlas, { imageName: path43.basename(`${base}.png`) });
     const outputs = [
       { path: `${base}.png`, data: png },
       { path: `${base}${extension}`, data: document }
@@ -20519,13 +21117,13 @@ async function runPack(args) {
     log(
       `  ${styleId}: ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s)` + (atlas.sets?.length ? `, ${atlas.sets.length} set(s)` : "") + ` (${format})`
     );
-    log(`    ${path42.relative(process.cwd(), base)}.png + ${extension} + .pixelkiln.json`);
+    log(`    ${path43.relative(process.cwd(), base)}.png + ${extension} + .pixelkiln.json`);
     for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
   }
 }
 async function runMount(args) {
   const { loaded, lock } = await openProject2(args);
-  const manifestDir = path42.dirname(path42.resolve(args.manifest));
+  const manifestDir = path43.dirname(path43.resolve(args.manifest));
   const styleIds = args.styles.length ? args.styles : Object.keys(loaded.manifest.styles);
   for (const styleId of styleIds) {
     const style = loaded.manifest.styles[styleId];
@@ -20564,9 +21162,9 @@ async function runMount(args) {
       sources,
       outputRoles
     );
-    const out = path42.resolve(manifestDir, style.mount.out);
+    const out = path43.resolve(manifestDir, style.mount.out);
     const format = sheetFormat(args);
-    const { extension, document } = renderSheetDocument(format, atlas, { imageName: path42.basename(out) });
+    const { extension, document } = renderSheetDocument(format, atlas, { imageName: path43.basename(out) });
     const metadata = out.replace(/\.png$/, "") + extension;
     const companion = out.replace(/\.png$/, "") + ".pixelkiln.json";
     const outputs = [
@@ -20586,7 +21184,7 @@ async function runMount(args) {
         await provenanceFile("$lock", args.lock),
         ...qualityRecords,
         ...artifactSources.filter(
-          (source) => source.id !== "$base" || path42.resolve(source.path) !== out
+          (source) => source.id !== "$base" || path43.resolve(source.path) !== out
         )
       ],
       options: {
@@ -20600,14 +21198,14 @@ async function runMount(args) {
     log(
       `  ${styleId}: ${atlas.frames.length} cell(s) into ${atlas.sheet.width}x${atlas.sheet.height}` + (overBase ? ` over ${style.mount.base}` : " (new sheet)")
     );
-    log(`    ${path42.relative(process.cwd(), out)} + atlas/provenance JSON`);
+    log(`    ${path43.relative(process.cwd(), out)} + atlas/provenance JSON`);
     for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
   }
 }
 async function runExport(args) {
   const { loaded, specs, lock } = await openProject2(args);
   const format = args.format ?? "generic";
-  const manifestDir = path42.dirname(path42.resolve(args.manifest));
+  const manifestDir = path43.dirname(path43.resolve(args.manifest));
   const selected = specs.filter((spec) => {
     if (spec.generator !== "tiles" && spec.generator !== "terrain") return false;
     if (args.styles.length && !args.styles.includes(spec.styleId)) return false;
@@ -20623,12 +21221,12 @@ async function runExport(args) {
   for (const spec of selected) {
     const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
     const style = loaded.manifest.styles[spec.styleId];
-    const defaultBase = path42.resolve(manifestDir, style.outDir, `${spec.assetId}-tileset`);
-    const base = args.out ? path42.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
+    const defaultBase = path43.resolve(manifestDir, style.outDir, `${spec.assetId}-tileset`);
+    const base = args.out ? path43.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
     const result = exportTileset(entry, spec, {
       format,
       manifestDir,
-      imageName: path42.basename(`${base}.png`),
+      imageName: path43.basename(`${base}.png`),
       columns: args.columns
     });
     const outputs = [
@@ -20646,7 +21244,7 @@ async function runExport(args) {
         asset: spec.assetId,
         columns: args.columns ?? null,
         format,
-        image: path42.basename(`${base}.png`),
+        image: path43.basename(`${base}.png`),
         providerRules: result.generic.providerRules,
         style: spec.styleId,
         tileType: spec.tileType ?? null
@@ -20656,7 +21254,7 @@ async function runExport(args) {
       `  ${spec.styleId}/${spec.assetId}: ${result.generic.tiles.length} tile(s), ${result.generic.sheet.width}x${result.generic.sheet.height} (${format})`
     );
     log(
-      `    ${path42.relative(process.cwd(), base)}.png + ${path42.basename(base)}${result.extension} + .pixelkiln.json`
+      `    ${path43.relative(process.cwd(), base)}.png + ${path43.basename(base)}${result.extension} + .pixelkiln.json`
     );
   }
 }
@@ -20669,23 +21267,23 @@ function sheetFormat(args) {
 }
 
 // src/cli/commands/pixellab-utils.ts
-import path44 from "path";
+import path45 from "path";
 
 // src/pixellab-utils.ts
-import { existsSync as existsSync33 } from "fs";
-import { mkdir as mkdir13, readFile as readFile29, writeFile as writeFile18 } from "fs/promises";
-import path43 from "path";
+import { existsSync as existsSync34 } from "fs";
+import { mkdir as mkdir14, readFile as readFile30, writeFile as writeFile19 } from "fs/promises";
+import path44 from "path";
 var UNZOOM_MIN_SIDE = 256;
 var UNZOOM_MAX_AREA = 2048 * 2048;
 function defaultUnzoomOut(input) {
-  const ext = path43.extname(input);
+  const ext = path44.extname(input);
   return `${ext ? input.slice(0, -ext.length) : input}.unzoomed.png`;
 }
 async function unzoomFile(client2, input, opts = {}) {
-  const out = path43.resolve(opts.out ?? defaultUnzoomOut(input));
-  if (path43.resolve(input) === out) throw new Error("unzoom will not overwrite its own input; pass a different --out");
-  if (existsSync33(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
-  const bytes = await readFile29(input);
+  const out = path44.resolve(opts.out ?? defaultUnzoomOut(input));
+  if (path44.resolve(input) === out) throw new Error("unzoom will not overwrite its own input; pass a different --out");
+  if (existsSync34(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
+  const bytes = await readFile30(input);
   const metadata = imageMetadata(bytes);
   if (!metadata) throw new Error(`${input} is not a readable PNG or JPEG`);
   const { width, height, format } = metadata;
@@ -20698,22 +21296,22 @@ async function unzoomFile(client2, input, opts = {}) {
     throw new Error(`${input} is ${width}x${height}; PixelLab's unzoom takes at most 2048x2048 worth of pixels`);
   }
   const res = await client2.unzoom({ image: { base64: bytes.toString("base64"), format }, quantize: opts.quantize });
-  await mkdir13(path43.dirname(out), { recursive: true });
-  await writeFile18(out, res.png);
+  await mkdir14(path44.dirname(out), { recursive: true });
+  await writeFile19(out, res.png);
   return { out, original: res.originalSize, unzoomed: res.unzoomedSize, zoomFactor: res.zoomFactor, usage: res.usage };
 }
 var FONT_WEIGHTS = ["Bold", "Regular"];
 var FONT_GLYPH_SIZES = [8, 16, 32, 64];
 var FONT_COST_GENERATIONS = 15;
 function fontOutputPaths(out) {
-  const base = path43.resolve(out.replace(/\.(ttf|png)$/i, ""));
+  const base = path44.resolve(out.replace(/\.(ttf|png)$/i, ""));
   return { ttf: `${base}.ttf`, atlas: `${base}.png` };
 }
 async function generateFont(client2, opts) {
   const { ttf, atlas } = fontOutputPaths(opts.out);
   if (!opts.force) {
     for (const file of [ttf, atlas]) {
-      if (existsSync33(file)) throw new Error(`${file} already exists; pass --force to replace it`);
+      if (existsSync34(file)) throw new Error(`${file} already exists; pass --force to replace it`);
     }
   }
   const sleep3 = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
@@ -20740,9 +21338,9 @@ async function generateFont(client2, opts) {
         client2.download(job.download_ttf_url),
         client2.download(job.download_atlas_url)
       ]);
-      await mkdir13(path43.dirname(ttf), { recursive: true });
-      await writeFile18(ttf, ttfBytes);
-      await writeFile18(atlas, atlasBytes);
+      await mkdir14(path44.dirname(ttf), { recursive: true });
+      await writeFile19(ttf, ttfBytes);
+      await writeFile19(atlas, atlasBytes);
       return { jobId, ttf, atlas, glyphPx: job.glyph_px ?? null, usage: job.usage };
     }
     if (Date.now() - started > timeout) {
@@ -20756,14 +21354,14 @@ async function generateFont(client2, opts) {
 var PIXELATE_COST_GENERATIONS = 6;
 var PIXELATE_MAX_SIDE = 2048;
 function defaultPixelateOut(input) {
-  const ext = path43.extname(input);
+  const ext = path44.extname(input);
   return `${ext ? input.slice(0, -ext.length) : input}.pixel.png`;
 }
 async function pixelateFile(client2, input, opts = {}) {
-  const out = path43.resolve(opts.out ?? defaultPixelateOut(input));
-  if (path43.resolve(input) === out) throw new Error("pixelate will not overwrite its own input; pass a different --out");
-  if (existsSync33(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
-  const bytes = await readFile29(input);
+  const out = path44.resolve(opts.out ?? defaultPixelateOut(input));
+  if (path44.resolve(input) === out) throw new Error("pixelate will not overwrite its own input; pass a different --out");
+  if (existsSync34(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
+  const bytes = await readFile30(input);
   const metadata = imageMetadata(bytes);
   if (!metadata) throw new Error(`${input} is not a readable PNG or JPEG`);
   const { width, height, format } = metadata;
@@ -20789,8 +21387,8 @@ async function pixelateFile(client2, input, opts = {}) {
       }
       const png = Buffer.from(first.base64, "base64");
       const size = imageMetadata(png);
-      await mkdir13(path43.dirname(out), { recursive: true });
-      await writeFile18(out, png);
+      await mkdir14(path44.dirname(out), { recursive: true });
+      await writeFile19(out, png);
       return {
         jobId,
         out,
@@ -20811,7 +21409,7 @@ async function pixelateFile(client2, input, opts = {}) {
 
 // src/cli/commands/pixellab-utils.ts
 function loadKeys(args) {
-  loadEnvFiles(path44.dirname(path44.resolve(args.manifest)));
+  loadEnvFiles(path45.dirname(path45.resolve(args.manifest)));
   loadEnvFiles(process.cwd());
 }
 async function runUnzoom(args) {
@@ -20908,21 +21506,76 @@ async function runPixelate(args) {
     `  ${res.original.width}x${res.original.height}${scaled} \u2192 ${res.pixelated.width}x${res.pixelated.height}; wrote ${res.out}`
   );
 }
+async function runVfx(args) {
+  if (args.subcommand === "presets" || args.subcommand === "parts") {
+    if (args.dryRun) {
+      log(`  would list PixelLab's VFX ${args.subcommand}; nothing sent`);
+      return;
+    }
+    loadKeys(args);
+    log(await describeVfx(mcpClientFromEnv(), args.subcommand));
+    return;
+  }
+  if (!args.out) throw new UsageError("vfx needs --out <base>: <base>.png, .gif, .json, and .vfx.json are written");
+  const starts = [args.preset, args.recipe, args.effect].filter(Boolean);
+  if (starts.length > 1) throw new UsageError("vfx takes one of --preset, --recipe, or --effect, not several");
+  if (starts.length === 0 && args.parts.length === 0) {
+    throw new UsageError("vfx needs something to start from: --preset <name>, --recipe <file>, --effect <id>, or --part <name>");
+  }
+  const paths = vfxOutputPaths(args.out);
+  const fromRecipe = args.recipe ? await readVfxRecipe(args.recipe) : void 0;
+  const sprite = args.sprite ?? fromRecipe?.sprite;
+  const recipeName = typeof fromRecipe?.recipe.name === "string" ? fromRecipe.recipe.name : void 0;
+  const name = args.name ?? (args.effect ? void 0 : recipeName ?? args.preset ?? path45.basename(paths.sheet, ".png"));
+  const from = args.preset ? `preset ${args.preset}` : args.recipe ? `recipe ${args.recipe}` : args.effect ? `saved effect ${args.effect}` : "nothing";
+  log(
+    `  vfx ${name ? `"${name}"` : "(keeping its saved name)"} from ${from}${args.parts.length ? ` + ${args.parts.join(", ")}` : ""}${sprite ? ` around ${sprite}` : ""} \u2192 ${paths.sheet} (+ .gif, .json, .vfx.json${args.gamePack ? ", -game.zip" : ""})`
+  );
+  log("  cost: free on a PixelLab subscription (a renderer, not a generation); saved to your My effects");
+  if (args.dryRun) {
+    log("  dry run: nothing sent");
+    return;
+  }
+  if (fromRecipe?.sprite && !args.sprite) log(`  using the sprite the record names: ${fromRecipe.sprite}`);
+  loadKeys(args);
+  const res = await makeVfx(mcpClientFromEnv(), {
+    preset: args.preset,
+    recipe: fromRecipe?.recipe,
+    effect: args.effect,
+    parts: args.parts.map((part) => ({ name: part })),
+    sprite,
+    fps: args.fps,
+    name: args.name,
+    out: args.out,
+    gamePack: args.gamePack,
+    force: args.force,
+    onProgress: (message6) => log(`  ${message6}\u2026`)
+  });
+  if (args.json) {
+    log(JSON.stringify({ version: 1, ...res }, null, 2));
+    return;
+  }
+  log(`  ${res.width}x${res.height}, ${res.frames} frames @ ${res.fps} fps, ${res.loop ? "loops" : "plays once"}`);
+  for (const file of [res.paths.sheet, res.paths.gif, res.paths.atlas, res.paths.gamePack, res.paths.provenance]) {
+    if (file) log(`  wrote ${file}`);
+  }
+  if (res.editUrl) log(`  tweak it with sliders: ${res.editUrl} (then: pixelkiln vfx --effect ${res.effectId} --out ${args.out} --force)`);
+}
 
 // src/cli/commands/quality.ts
-import path46 from "path";
-import { readFile as readFile31 } from "fs/promises";
+import path47 from "path";
+import { readFile as readFile32 } from "fs/promises";
 
 // src/pipeline/quality-regression.ts
-import path45 from "path";
-import { existsSync as existsSync34 } from "fs";
-import { readFile as readFile30 } from "fs/promises";
+import path46 from "path";
+import { existsSync as existsSync35 } from "fs";
+import { readFile as readFile31 } from "fs/promises";
 import { z as z13 } from "zod";
 var SHA256_RE = /^[0-9a-f]{64}$/;
 var HEX_RE = /^#[0-9a-f]{6}$/;
 var MAX_REDMEAN_DISTANCE = 765;
 var QualityPathSchema = z13.string().min(1).refine(
-  (value) => !path45.posix.isAbsolute(value) && !value.includes("\\"),
+  (value) => !path46.posix.isAbsolute(value) && !value.includes("\\"),
   "expected a portable relative path"
 );
 var DEFAULT_QUALITY_TOLERANCES = {
@@ -21069,10 +21722,10 @@ function measureDecodedImageQuality(png, digest2) {
   };
 }
 async function measureImageQuality(file) {
-  const absolute = path45.resolve(file);
+  const absolute = path46.resolve(file);
   let bytes;
   try {
-    bytes = await readFile30(absolute);
+    bytes = await readFile31(absolute);
   } catch (error) {
     throw new Error(`Cannot read quality image ${absolute}: ${message4(error)}`, { cause: error });
   }
@@ -21091,11 +21744,11 @@ function resolveQualityInputs(raw, inputsFilePath) {
   }
   const ids = parsed.data.map((entry) => entry.id);
   if (new Set(ids).size !== ids.length) throw new Error("--inputs contains a duplicate quality case id.");
-  const root = path45.dirname(path45.resolve(inputsFilePath));
+  const root = path46.dirname(path46.resolve(inputsFilePath));
   return parsed.data.map((entry) => ({
     id: entry.id,
-    file: path45.resolve(root, entry.path),
-    ...entry.record ? { record: path45.resolve(root, entry.record) } : {},
+    file: path46.resolve(root, entry.path),
+    ...entry.record ? { record: path46.resolve(root, entry.record) } : {},
     tolerances: QualityToleranceSchema.parse({
       ...DEFAULT_QUALITY_TOLERANCES,
       ...entry.tolerances
@@ -21103,7 +21756,7 @@ function resolveQualityInputs(raw, inputsFilePath) {
   }));
 }
 function portableRelative2(from, to) {
-  return path45.relative(from, path45.resolve(to)).split(path45.sep).join("/") || ".";
+  return path46.relative(from, path46.resolve(to)).split(path46.sep).join("/") || ".";
 }
 async function verifyRecordForImage(recordPath, imagePath) {
   const verification = await verifyArtifactBundle(recordPath);
@@ -21118,20 +21771,20 @@ async function verifyRecordForImage(recordPath, imagePath) {
   if (record.kind !== "refine" || options === null || typeof options !== "object" || options.schema !== "pixelkiln-quality") {
     throw new Error(`Quality record ${recordPath} is not a PixelKiln refinement record.`);
   }
-  const outputs = record.outputs.map((output) => path45.resolve(path45.dirname(recordPath), output.path));
-  if (!outputs.includes(path45.resolve(imagePath))) {
+  const outputs = record.outputs.map((output) => path46.resolve(path46.dirname(recordPath), output.path));
+  if (!outputs.includes(path46.resolve(imagePath))) {
     throw new Error(`Quality record ${recordPath} does not own ${imagePath}.`);
   }
 }
 async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   if (!inputs.length) throw new Error("Cannot snapshot an empty quality baseline.");
-  const absolute = path45.resolve(baselinePath);
+  const absolute = path46.resolve(baselinePath);
   for (const input of inputs) {
-    if (path45.resolve(input.file) === absolute || input.record && path45.resolve(input.record) === absolute) {
+    if (path46.resolve(input.file) === absolute || input.record && path46.resolve(input.record) === absolute) {
       throw new Error(`Quality baseline output would overwrite an input: ${absolute}.`);
     }
   }
-  const root = path45.dirname(absolute);
+  const root = path46.dirname(absolute);
   const cases = [];
   for (const input of [...inputs].sort((a, b) => a.id.localeCompare(b.id))) {
     const expected = await measureImageQuality(input.file);
@@ -21158,8 +21811,8 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
     cases
   });
   const data = Buffer.from(JSON.stringify(baseline, null, 2) + "\n");
-  if (existsSync34(absolute) && !options.force) {
-    const current = await readFile30(absolute);
+  if (existsSync35(absolute) && !options.force) {
+    const current = await readFile31(absolute);
     if (!current.equals(data)) {
       throw new OverwriteRefusedError(
         `Quality baseline already exists with different content: ${absolute}. Pass --force to replace it.`,
@@ -21171,10 +21824,10 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   return { baseline, path: absolute, changed: result.changed.length > 0 };
 }
 async function readQualityBaseline(baselinePath) {
-  const absolute = path45.resolve(baselinePath);
+  const absolute = path46.resolve(baselinePath);
   let raw;
   try {
-    raw = JSON.parse(await readFile30(absolute, "utf8"));
+    raw = JSON.parse(await readFile31(absolute, "utf8"));
   } catch (error) {
     throw new Error(`Could not read quality baseline ${absolute}: ${message4(error)}`, { cause: error });
   }
@@ -21244,12 +21897,12 @@ function regressionViolations(expected, actual, tolerances) {
   return { violations, warnings };
 }
 async function checkQualityBaseline(baselinePath) {
-  const absolute = path45.resolve(baselinePath);
+  const absolute = path46.resolve(baselinePath);
   const baseline = await readQualityBaseline(absolute);
-  const root = path45.dirname(absolute);
+  const root = path46.dirname(absolute);
   const cases = [];
   for (const entry of baseline.cases) {
-    const file = path45.resolve(root, entry.file);
+    const file = path46.resolve(root, entry.file);
     let actual = null;
     const violations = [];
     const warnings = [];
@@ -21262,7 +21915,7 @@ async function checkQualityBaseline(baselinePath) {
       violations.push(message4(error));
     }
     if (entry.record) {
-      const recordPath = path45.resolve(root, entry.record.path);
+      const recordPath = path46.resolve(root, entry.record.path);
       try {
         const recordHash = await sha256File(recordPath);
         if (recordHash !== entry.record.sha256) violations.push("quality record hash changed");
@@ -21304,15 +21957,15 @@ async function runQuality(args) {
     if (!args.out) throw new Error("quality snapshot needs --out <pixelkiln.quality.json>.");
     let raw;
     try {
-      raw = JSON.parse(await readFile31(path46.resolve(args.inputs), "utf8"));
+      raw = JSON.parse(await readFile32(path47.resolve(args.inputs), "utf8"));
     } catch (error) {
       throw new Error(
-        `Could not read quality inputs ${path46.resolve(args.inputs)}: ${error instanceof Error ? error.message : String(error)}`,
+        `Could not read quality inputs ${path47.resolve(args.inputs)}: ${error instanceof Error ? error.message : String(error)}`,
         { cause: error }
       );
     }
     const inputs = resolveQualityInputs(raw, args.inputs);
-    if (path46.resolve(args.inputs) === path46.resolve(args.out)) {
+    if (path47.resolve(args.inputs) === path47.resolve(args.out)) {
       throw new Error("quality snapshot --out must not overwrite its --inputs file.");
     }
     const result = await snapshotQualityBaseline(inputs, args.out, { force: args.force });
@@ -21325,7 +21978,7 @@ async function runQuality(args) {
       }, null, 2));
     } else {
       log(
-        `  ${result.changed ? "wrote" : "unchanged"} ${path46.relative(process.cwd(), result.path)} (${result.baseline.cases.length} case(s))`
+        `  ${result.changed ? "wrote" : "unchanged"} ${path47.relative(process.cwd(), result.path)} (${result.baseline.cases.length} case(s))`
       );
       log(`  Review the tolerances, commit the baseline, then run quality check in CI.`);
     }
@@ -21351,12 +22004,12 @@ async function runQuality(args) {
 }
 
 // src/cli/commands/recipe.ts
-import path48 from "path";
+import path49 from "path";
 
 // src/recipes.ts
-import path47 from "path";
-import { existsSync as existsSync35 } from "fs";
-import { readdir as readdir3, readFile as readFile32 } from "fs/promises";
+import path48 from "path";
+import { existsSync as existsSync36 } from "fs";
+import { readdir as readdir3, readFile as readFile33 } from "fs/promises";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { z as z14 } from "zod";
 var SHA256_RE2 = /^[0-9a-f]{64}$/;
@@ -21365,7 +22018,7 @@ var VERSION_RE = /^\d+\.\d+\.\d+$/;
 var RECIPE_FILE = "pixelkiln.recipe.json";
 var RECIPE_DIR_TOKEN = "{{recipeDir}}";
 var PortablePathSchema = z14.string().min(1).refine((value) => {
-  if (value.includes("\\") || path47.posix.isAbsolute(value)) return false;
+  if (value.includes("\\") || path48.posix.isAbsolute(value)) return false;
   const parts = value.split("/");
   return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
 }, "expected a portable relative path without '.', '..', or backslashes");
@@ -21541,10 +22194,10 @@ function message5(error) {
   return error instanceof Error ? error.message : String(error);
 }
 async function readRecipeFile(recipePath, bundled) {
-  const absolute = path47.resolve(recipePath);
+  const absolute = path48.resolve(recipePath);
   let raw;
   try {
-    raw = JSON.parse(await readFile32(absolute, "utf8"));
+    raw = JSON.parse(await readFile33(absolute, "utf8"));
   } catch (error) {
     throw new Error(`Could not read recipe ${absolute}: ${message5(error)}`, { cause: error });
   }
@@ -21555,13 +22208,13 @@ async function readRecipeFile(recipePath, bundled) {
 ` + parsed.error.issues.map((issue) => `  ${issue.path.join(".") || "$"}: ${issue.message}`).join("\n")
     );
   }
-  return { recipe: parsed.data, authored: raw, path: absolute, dir: path47.dirname(absolute), bundled };
+  return { recipe: parsed.data, authored: raw, path: absolute, dir: path48.dirname(absolute), bundled };
 }
 async function walkRecipeFiles(root) {
-  if (!existsSync35(root)) return [];
+  if (!existsSync36(root)) return [];
   const out = [];
   for (const entry of await readdir3(root, { withFileTypes: true })) {
-    const resolved = path47.join(root, entry.name);
+    const resolved = path48.join(root, entry.name);
     if (entry.isDirectory()) out.push(...await walkRecipeFiles(resolved));
     else if (entry.isFile() && entry.name === RECIPE_FILE) out.push(resolved);
   }
@@ -21572,7 +22225,7 @@ function bundledRecipeRoot() {
 }
 async function listBundledRecipes(root = bundledRecipeRoot()) {
   const recipes = await Promise.all(
-    (await walkRecipeFiles(path47.resolve(root))).map((file) => readRecipeFile(file, true))
+    (await walkRecipeFiles(path48.resolve(root))).map((file) => readRecipeFile(file, true))
   );
   return recipes.sort(
     (a, b) => a.recipe.id.localeCompare(b.recipe.id) || compareVersions(b.recipe.version, a.recipe.version)
@@ -21595,9 +22248,9 @@ function parseSelector(selector) {
   return { id: match[1], version: match[2] };
 }
 async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
-  const local = path47.resolve(target);
-  if (existsSync35(local)) {
-    const recipePath = path47.basename(local) === RECIPE_FILE ? local : path47.join(local, RECIPE_FILE);
+  const local = path48.resolve(target);
+  if (existsSync36(local)) {
+    const recipePath = path48.basename(local) === RECIPE_FILE ? local : path48.join(local, RECIPE_FILE);
     return readRecipeFile(recipePath, false);
   }
   if (target.startsWith(".") || target.startsWith("/") || target.includes("\\")) {
@@ -21611,8 +22264,8 @@ async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
   return matches[0];
 }
 async function verifyFile(root, file) {
-  const absolute = path47.resolve(root, ...file.path.split("/"));
-  if (!existsSync35(absolute)) {
+  const absolute = path48.resolve(root, ...file.path.split("/"));
+  if (!existsSync36(absolute)) {
     return { path: file.path, expectedSha256: file.sha256, actualSha256: null, status: "missing" };
   }
   const actualSha256 = await sha256File(absolute);
@@ -21627,7 +22280,7 @@ async function verifyRecipe(target, options = {}) {
   const loaded = await resolveRecipe(target, options.bundledRoot);
   const actualIntegrity = recipeDigest(loaded.authored);
   const files = await Promise.all(loaded.recipe.files.map((file) => verifyFile(loaded.dir, file)));
-  const modelRoot = options.modelRoot ? path47.resolve(options.modelRoot) : null;
+  const modelRoot = options.modelRoot ? path48.resolve(options.modelRoot) : null;
   const models = modelRoot ? await Promise.all(loaded.recipe.models.map(async (model) => ({
     ...await verifyFile(modelRoot, model),
     source: model.source,
@@ -21661,7 +22314,7 @@ async function verifyRecipe(target, options = {}) {
   };
 }
 function renderStyle(style, destination, cwd) {
-  const portableDir = path47.relative(cwd, destination).split(path47.sep).join("/") || ".";
+  const portableDir = path48.relative(cwd, destination).split(path48.sep).join("/") || ".";
   const replace = (value) => {
     if (typeof value === "string") return value.replaceAll(RECIPE_DIR_TOKEN, portableDir);
     if (Array.isArray(value)) return value.map(replace);
@@ -21673,25 +22326,25 @@ function renderStyle(style, destination, cwd) {
   return replace(style);
 }
 async function installRecipe(target, options = {}) {
-  const cwd = path47.resolve(options.cwd ?? process.cwd());
+  const cwd = path48.resolve(options.cwd ?? process.cwd());
   const loaded = await resolveRecipe(target, options.bundledRoot);
   const verification = await verifyRecipe(loaded.path);
   if (!verification.ok) {
     throw new Error(`Recipe ${loaded.recipe.id}@${loaded.recipe.version} failed integrity verification.`);
   }
-  const destination = options.out ? path47.resolve(cwd, options.out) : path47.join(cwd, "pixelkiln-recipes", ...loaded.recipe.id.split("/"), loaded.recipe.version);
+  const destination = options.out ? path48.resolve(cwd, options.out) : path48.join(cwd, "pixelkiln-recipes", ...loaded.recipe.id.split("/"), loaded.recipe.version);
   const sources = [
     { path: RECIPE_FILE, source: loaded.path },
-    ...loaded.recipe.files.map((file) => ({ path: file.path, source: path47.join(loaded.dir, ...file.path.split("/")) }))
+    ...loaded.recipe.files.map((file) => ({ path: file.path, source: path48.join(loaded.dir, ...file.path.split("/")) }))
   ];
   const files = await Promise.all(sources.map(async (file) => ({
-    path: path47.join(destination, ...file.path.split("/")),
-    data: await readFile32(file.source)
+    path: path48.join(destination, ...file.path.split("/")),
+    data: await readFile33(file.source)
   })));
   if (!options.force) {
     for (const file of files) {
-      if (!existsSync35(file.path)) continue;
-      const current = await readFile32(file.path);
+      if (!existsSync36(file.path)) continue;
+      const current = await readFile33(file.path);
       if (!current.equals(file.data)) {
         throw new OverwriteRefusedError(
           `Recipe destination has local changes: ${file.path}. Choose another --out or pass --force to replace declared recipe files.`,
@@ -21785,14 +22438,14 @@ async function runRecipe(args) {
       }, null, 2));
     } else {
       log(`  installed ${result.recipe.id}@${result.recipe.version}`);
-      log(`  ${path48.relative(process.cwd(), result.destination) || "."}`);
+      log(`  ${path49.relative(process.cwd(), result.destination) || "."}`);
       log(`
   Add this entry under your manifest's styles object:`);
       log(JSON.stringify({ [result.styleId]: result.style }, null, 2));
       if (result.recipe.models.length) {
         log(`
   Models are not downloaded automatically. Verify them with:`);
-        log(`  pixelkiln recipe verify ${path48.relative(process.cwd(), result.destination)} --model-root <ComfyUI/models>`);
+        log(`  pixelkiln recipe verify ${path49.relative(process.cwd(), result.destination)} --model-root <ComfyUI/models>`);
       }
     }
     return;
@@ -21800,7 +22453,7 @@ async function runRecipe(args) {
 }
 
 // src/cli/commands/refine.ts
-import path49 from "path";
+import path50 from "path";
 async function runRefine(args) {
   if (args.from || args.subcommand === "approve") {
     if (!args.from) {
@@ -21830,12 +22483,12 @@ async function runRefine(args) {
           `  recovered ${result3.detection.columns}x${result3.detection.rows} native grid (${result3.detection.confidence}: ${result3.detection.consensus})`
         );
         log(`  enforced ${result3.palette.length}-color palette without dithering`);
-        log(`  wrote ${path49.relative(process.cwd(), result3.output)}`);
-        log(`  quality record: ${path49.relative(process.cwd(), result3.record)}`);
+        log(`  wrote ${path50.relative(process.cwd(), result3.output)}`);
+        log(`  quality record: ${path50.relative(process.cwd(), result3.record)}`);
         log(`
   Automated checks passed. Human 1\xD7 review is still required:`);
         log(
-          `    pixelkiln refine approve --from ${path49.relative(process.cwd(), result3.record)} --reviewer "Your Name"`
+          `    pixelkiln refine approve --from ${path50.relative(process.cwd(), result3.record)} --reviewer "Your Name"`
         );
       }
       return;
@@ -21863,7 +22516,7 @@ async function runRefine(args) {
       if (args.json) log(JSON.stringify(result3, null, 2));
       else {
         log(
-          result3.options.frameSet ? `  approved ${result3.outputs.length} frames in ${path49.relative(process.cwd(), result3.record)} by ${args.reviewer.trim()}` : `  approved ${path49.relative(process.cwd(), result3.output)} by ${args.reviewer.trim()}`
+          result3.options.frameSet ? `  approved ${result3.outputs.length} frames in ${path50.relative(process.cwd(), result3.record)} by ${args.reviewer.trim()}` : `  approved ${path50.relative(process.cwd(), result3.output)} by ${args.reviewer.trim()}`
         );
       }
       return;
@@ -21872,7 +22525,7 @@ async function runRefine(args) {
     if (args.json) {
       log(JSON.stringify(result2, null, 2));
     } else {
-      log(`  ${result2.safe ? "release-ready" : "not release-ready"}: ${path49.relative(process.cwd(), result2.output || result2.record)}`);
+      log(`  ${result2.safe ? "release-ready" : "not release-ready"}: ${path50.relative(process.cwd(), result2.output || result2.record)}`);
       for (const reason of result2.reasons) log(`    ${reason}`);
     }
     if (!result2.safe) process.exitCode = 1;
@@ -21918,7 +22571,7 @@ async function runRefine(args) {
       log(`  ${item.state.padEnd(16)} ${item.key}  ${item.reason}`);
       if (item.state === "needs-approval") {
         log(
-          `    pixelkiln refine approve --from ${path49.relative(process.cwd(), item.record)} --reviewer "Your Name"`
+          `    pixelkiln refine approve --from ${path50.relative(process.cwd(), item.record)} --reviewer "Your Name"`
         );
       }
     }
@@ -21929,9 +22582,9 @@ async function runRefine(args) {
 }
 
 // src/cli/commands/skeleton.ts
-import path50 from "path";
-import { existsSync as existsSync36 } from "fs";
-import { readFile as readFile33, writeFile as writeFile19 } from "fs/promises";
+import path51 from "path";
+import { existsSync as existsSync37 } from "fs";
+import { readFile as readFile34, writeFile as writeFile20 } from "fs/promises";
 
 // src/skeleton-preview.ts
 var RIGHT = [255, 140, 40, 255];
@@ -22042,12 +22695,12 @@ var Canvas = class {
 async function runEstimateSkeleton(args) {
   const image = args.target;
   if (!image) throw new UsageError("estimate-skeleton needs an image path: pixelkiln estimate-skeleton <image> [--out keypoints.json]");
-  if (args.out && existsSync36(path50.resolve(args.out)) && !args.force) {
+  if (args.out && existsSync37(path51.resolve(args.out)) && !args.force) {
     throw new UsageError(`${args.out} already exists; pass --force to replace it`);
   }
-  loadEnvFiles(path50.dirname(path50.resolve(args.manifest)));
+  loadEnvFiles(path51.dirname(path51.resolve(args.manifest)));
   loadEnvFiles(process.cwd());
-  const bytes = await readFile33(path50.resolve(image));
+  const bytes = await readFile34(path51.resolve(image));
   const metadata = imageMetadata(bytes);
   if (!metadata) throw new UsageError(`${image} is not a readable PNG or JPEG`);
   const sizeProblem = estimateSkeletonSizeProblem(metadata.width, metadata.height);
@@ -22059,7 +22712,7 @@ async function runEstimateSkeleton(args) {
   const frames = args.frames ?? DEFAULT_SCAFFOLD_FRAMES;
   const json = JSON.stringify(scaffoldSkeletonSet(res.keypoints, frames), null, 2);
   if (args.out) {
-    await writeFile19(path50.resolve(args.out), json + "\n");
+    await writeFile20(path51.resolve(args.out), json + "\n");
     log(`  wrote ${args.out}: the estimated pose and ${frames} frames to edit`);
     log(`  preview it with: pixelkiln skeleton-preview ${args.out} --from ${image}`);
   } else {
@@ -22072,8 +22725,8 @@ async function runSkeletonPreview(args) {
   let sourceFile;
   let label;
   if (target.endsWith(".json")) {
-    keypointsFile = path50.resolve(target);
-    sourceFile = args.from ? path50.resolve(args.from) : void 0;
+    keypointsFile = path51.resolve(target);
+    sourceFile = args.from ? path51.resolve(args.from) : void 0;
     label = target;
   } else {
     const loaded = await loadManifest(args.manifest);
@@ -22085,31 +22738,31 @@ async function runSkeletonPreview(args) {
       );
     }
     keypointsFile = spec.revision.keypointsFile;
-    sourceFile = args.from ? path50.resolve(args.from) : spec.revision.sourceFile;
+    sourceFile = args.from ? path51.resolve(args.from) : spec.revision.sourceFile;
     label = `${spec.styleId}/${spec.assetId}`;
   }
-  if (!existsSync36(keypointsFile)) throw new UsageError(`Keypoints file does not exist yet: ${keypointsFile}`);
+  if (!existsSync37(keypointsFile)) throw new UsageError(`Keypoints file does not exist yet: ${keypointsFile}`);
   let json;
   try {
-    json = JSON.parse(await readFile33(keypointsFile, "utf8"));
+    json = JSON.parse(await readFile34(keypointsFile, "utf8"));
   } catch (error) {
     throw new UsageError(`${keypointsFile} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
   }
   const set = parseSkeletonSet(json, keypointsFile);
   let source;
   if (sourceFile) {
-    if (!existsSync36(sourceFile)) {
+    if (!existsSync37(sourceFile)) {
       log(`  source image does not exist yet, drawing on a plain ground: ${sourceFile}`);
     } else {
-      const bytes = await readFile33(sourceFile);
+      const bytes = await readFile34(sourceFile);
       if (imageMetadata(bytes)?.format !== "png") throw new UsageError(`${sourceFile} must be a PNG to preview over`);
       source = decodePng(bytes);
     }
   }
-  const out = path50.resolve(args.out ?? keypointsFile.replace(/\.json$/, "") + ".preview.png");
-  await writeFile19(out, renderSkeletonSheet(set, { source }));
+  const out = path51.resolve(args.out ?? keypointsFile.replace(/\.json$/, "") + ".preview.png");
+  await writeFile20(out, renderSkeletonSheet(set, { source }));
   log(`  ${label}: ${set.frames.length} frames after the starting pose`);
-  const shown = path50.relative(process.cwd(), out);
+  const shown = path51.relative(process.cwd(), out);
   log(`  wrote ${shown.startsWith("..") ? out : shown}`);
 }
 
@@ -22155,15 +22808,15 @@ async function runTools(args) {
 }
 
 // src/cli/commands/workspace.ts
-import path51 from "path";
-import { existsSync as existsSync37 } from "fs";
+import path52 from "path";
+import { existsSync as existsSync38 } from "fs";
 async function runWorkspace(args) {
-  const workspacePath = path51.resolve(args.workspace ?? "pixelkiln.workspace.json");
-  const dir = path51.dirname(workspacePath);
+  const workspacePath = path52.resolve(args.workspace ?? "pixelkiln.workspace.json");
+  const dir = path52.dirname(workspacePath);
   if (args.subcommand === "add") {
-    const manifestPath = path51.resolve(args.target);
+    const manifestPath = path52.resolve(args.target);
     const loadedTarget = await loadManifest(manifestPath);
-    const lockPath = args.explicitLock ? path51.resolve(args.explicitLock) : path51.join(path51.dirname(manifestPath), "pixelkiln.lock.json");
+    const lockPath = args.explicitLock ? path52.resolve(args.explicitLock) : path52.join(path52.dirname(manifestPath), "pixelkiln.lock.json");
     const ws = await loadWorkspace(workspacePath);
     const id = args.name ?? loadedTarget.manifest.name;
     if (ws.projects.some((p) => p.id === id)) {
@@ -22183,10 +22836,10 @@ async function runWorkspace(args) {
       ...args.account ? { account: args.account } : {}
     };
     await saveWorkspace(workspacePath, { version: 1, projects: [...ws.projects, project] });
-    log(`  registered "${id}" in ${path51.relative(process.cwd(), workspacePath)}`);
+    log(`  registered "${id}" in ${path52.relative(process.cwd(), workspacePath)}`);
     log(`    manifest: ${project.manifest}`);
     log(`    lock:     ${project.lock}`);
-    if (!existsSync37(lockPath)) {
+    if (!existsSync38(lockPath)) {
       log(
         `  warning: no lockfile there yet; this project contributes no claims until one is generated`
       );
@@ -22195,7 +22848,7 @@ async function runWorkspace(args) {
   }
   if (args.subcommand === "remove") {
     const ws = await loadWorkspace(workspacePath);
-    const resolvedTarget = path51.resolve(args.target);
+    const resolvedTarget = path52.resolve(args.target);
     const match = ws.projects.find(
       (p) => p.id === args.target || resolveProject(dir, p).manifestPath === resolvedTarget
     );
@@ -22206,11 +22859,11 @@ async function runWorkspace(args) {
       version: 1,
       projects: ws.projects.filter((p) => p !== match)
     });
-    log(`  removed "${match.id}" from ${path51.relative(process.cwd(), workspacePath)}`);
+    log(`  removed "${match.id}" from ${path52.relative(process.cwd(), workspacePath)}`);
     return;
   }
   if (args.subcommand === "list") {
-    if (!existsSync37(workspacePath)) {
+    if (!existsSync38(workspacePath)) {
       throw new Error(`Workspace catalog not found: ${workspacePath}`);
     }
     const ws = await loadWorkspace(workspacePath);
@@ -22218,9 +22871,9 @@ async function runWorkspace(args) {
     if (args.json) {
       log(JSON.stringify({ version: 1, workspace: workspacePath, projects: ws.projects, diagnostics }, null, 2));
     } else if (!ws.projects.length) {
-      log(`  no projects registered in ${path51.relative(process.cwd(), workspacePath)}`);
+      log(`  no projects registered in ${path52.relative(process.cwd(), workspacePath)}`);
     } else {
-      log(`  ${ws.projects.length} project(s) in ${path51.relative(process.cwd(), workspacePath)}:`);
+      log(`  ${ws.projects.length} project(s) in ${path52.relative(process.cwd(), workspacePath)}:`);
       for (const p of ws.projects) {
         log(`    ${p.id.padEnd(24)} ${p.manifest.padEnd(40)} (${p.provider}${p.account ? `, ${p.account}` : ""})`);
       }
@@ -22230,7 +22883,7 @@ async function runWorkspace(args) {
     return;
   }
   if (args.subcommand === "status") {
-    if (!existsSync37(workspacePath)) {
+    if (!existsSync38(workspacePath)) {
       throw new Error(`Workspace catalog not found: ${workspacePath}`);
     }
     const ws = await loadWorkspace(workspacePath);
@@ -22238,7 +22891,7 @@ async function runWorkspace(args) {
     if (args.json) {
       log(JSON.stringify({ ...report, workspace: workspacePath }, null, 2));
     } else {
-      log(`  workspace: ${path51.relative(process.cwd(), workspacePath)}`);
+      log(`  workspace: ${path52.relative(process.cwd(), workspacePath)}`);
       for (const p of report.projects) {
         if (p.error) {
           log(`
@@ -22292,8 +22945,8 @@ async function runHelp() {
 async function runVersion() {
   for (const up of ["../package.json", "../../package.json"]) {
     const url = new URL(up, import.meta.url);
-    if (!existsSync38(url)) continue;
-    const pkg = JSON.parse(await readFile34(url, "utf8"));
+    if (!existsSync39(url)) continue;
+    const pkg = JSON.parse(await readFile35(url, "utf8"));
     if (pkg.name === "pixelkiln") {
       log(`${pkg.name} ${pkg.version}`);
       return;
@@ -22341,6 +22994,7 @@ var RUNNERS = {
   "skeleton-preview": runSkeletonPreview,
   unzoom: runUnzoom,
   pixelate: runPixelate,
+  vfx: runVfx,
   font: runFont
 };
 async function main(argv = process.argv.slice(2)) {