pixelkiln 0.88.0 → 0.89.0

package/dist/index.cjs

@@ -86,6 +86,12 @@ __export(index_exports, {
   MapScenePlacementSchema: () => MapScenePlacementSchema,
   MapSceneSchema: () => MapSceneSchema,
   MediaType: () => MediaType,
+  NORMAL_MAP_CONVENTIONS: () => NORMAL_MAP_CONVENTIONS,
+  NORMAL_MAP_COST_GENERATIONS: () => NORMAL_MAP_COST_GENERATIONS,
+  NORMAL_MAP_MAX_FRAMES: () => NORMAL_MAP_MAX_FRAMES,
+  NORMAL_MAP_MAX_SIDE: () => NORMAL_MAP_MAX_SIDE,
+  NORMAL_MAP_MIN_SIDE: () => NORMAL_MAP_MIN_SIDE,
+  NormalMapConventionSchema: () => NormalMapConventionSchema,
   OverwriteRefusedError: () => OverwriteRefusedError,
   PIXELATE_COST_GENERATIONS: () => PIXELATE_COST_GENERATIONS,
   PIXELATE_MAX_SIDE: () => PIXELATE_MAX_SIDE,
@@ -113,12 +119,17 @@ __export(index_exports, {
   ScenarioProvider: () => ScenarioProvider,
   StyleInputSchema: () => StyleInputSchema,
   StyleSchema: () => StyleSchema,
+  TerrainConnectSchema: () => TerrainConnectSchema,
+  TerrainLinkSchema: () => TerrainLinkSchema,
+  TerrainSideSchema: () => TerrainSideSchema,
   UNZOOM_MAX_AREA: () => UNZOOM_MAX_AREA,
   UNZOOM_MIN_SIDE: () => UNZOOM_MIN_SIDE,
   UiElementSchema: () => UiElementSchema,
   UiPieceSchema: () => UiPieceSchema,
   UnsupportedCapabilityError: () => UnsupportedCapabilityError,
   UsageError: () => UsageError,
+  VFX_ARTISTS: () => VFX_ARTISTS,
+  VFX_ARTIST_MAX_SPRITE: () => VFX_ARTIST_MAX_SPRITE,
   VFX_TOOL: () => VFX_TOOL,
   VfxPartSchema: () => VfxPartSchema,
   WorkspaceProjectSchema: () => WorkspaceProjectSchema,
@@ -151,6 +162,7 @@ __export(index_exports, {
   createProvider: () => createProvider,
   currentEntryOutputPath: () => currentEntryOutputPath,
   currentOutputPath: () => currentOutputPath,
+  defaultNormalMapOut: () => defaultNormalMapOut,
   defaultOpenCommand: () => defaultOpenCommand,
   defaultPixelateOut: () => defaultPixelateOut,
   defaultUnzoomOut: () => defaultUnzoomOut,
@@ -212,6 +224,7 @@ __export(index_exports, {
   loadWorkspace: () => loadWorkspace,
   lockKey: () => lockKey,
   makeVfx: () => makeVfx,
+  makeVfxWithArtist: () => makeVfxWithArtist,
   matchOrphanStyle: () => matchOrphanStyle,
   mcpClientFromEnv: () => mcpClientFromEnv,
   measureBalanceChange: () => measureBalanceChange,
@@ -223,6 +236,9 @@ __export(index_exports, {
   mergePalettes: () => mergePalettes,
   mountSprites: () => mountSprites,
   mountStyle: () => mountStyle,
+  normalMapFile: () => normalMapFile,
+  normalMapResultPng: () => normalMapResultPng,
+  normalMapSizeProblem: () => normalMapSizeProblem,
   normalizeLockOutputPaths: () => normalizeLockOutputPaths,
   normalizeRefinementPalette: () => normalizeRefinementPalette,
   normalizeTerrainTiles: () => normalizeTerrainTiles,
@@ -240,6 +256,7 @@ __export(index_exports, {
   parseMcpBody: () => parseMcpBody,
   parseProFlashQuote: () => parseProFlashQuote,
   parseTerrainDescriptions: () => parseTerrainDescriptions,
+  parseVfxArtistResult: () => parseVfxArtistResult,
   parseVfxExport: () => parseVfxExport,
   parseVfxRecipe: () => parseVfxRecipe,
   parseVfxStep: () => parseVfxStep,
@@ -263,6 +280,7 @@ __export(index_exports, {
   readHandEditCompanion: () => readHandEditCompanion,
   readQualityBaseline: () => readQualityBaseline,
   readSavedVfxRecipe: () => readSavedVfxRecipe,
+  readVfxConversation: () => readVfxConversation,
   readVfxRecipe: () => readVfxRecipe,
   recipeDigest: () => recipeDigest,
   referencedHashes: () => referencedHashes,
@@ -325,6 +343,7 @@ __export(index_exports, {
   submit: () => submit,
   summarize: () => summarize,
   tagAdopted: () => tagAdopted,
+  terrainCost: () => terrainCost,
   terrainTileCount: () => terrainTileCount,
   tileFeatureOutputCount: () => tileFeatureOutputCount,
   tileVariationCount: () => tileVariationCount,
@@ -338,6 +357,13 @@ __export(index_exports, {
   validateWorkspace: () => validateWorkspace,
   verifyArtifactBundle: () => verifyArtifactBundle,
   verifyRecipe: () => verifyRecipe,
+  vfxArtistCeiling: () => vfxArtistCeiling,
+  vfxArtistFiles: () => vfxArtistFiles,
+  vfxArtistFrameFacts: () => vfxArtistFrameFacts,
+  vfxArtistQuote: () => vfxArtistQuote,
+  vfxArtistSprite: () => vfxArtistSprite,
+  vfxAtlasFrames: () => vfxAtlasFrames,
+  vfxJobFailure: () => vfxJobFailure,
   vfxOutputPaths: () => vfxOutputPaths,
   vfxRecipeSha256: () => vfxRecipeSha256,
   withArtifactManifest: () => withArtifactManifest,
@@ -368,8 +394,10 @@ var RevisionModeSchema = import_zod.z.enum([
   "animate-pixminimax",
   "animate-skeleton",
   "interpolate",
-  "edit-animation"
+  "edit-animation",
+  "normal-map"
 ]);
+var NormalMapConventionSchema = import_zod.z.enum(["opengl", "directx"]);
 function tileVariationCount(descriptions) {
   return Math.max(1, descriptions) * 4;
 }
@@ -412,9 +440,16 @@ function tilesCost(tileSize, variations) {
 function isometricTileCost() {
   return 1;
 }
-function terrainTileCount(transitionSize) {
+function terrainTileCount(transitionSize, mode2, orientation) {
+  if (orientation === "sidescroller") return 16;
+  if (mode2 === "pro") return transitionSize != null && transitionSize > 0.4 ? 25 : 16;
   return transitionSize === 1 ? 25 : 16;
 }
+function terrainCost(mode2, tileSize, orientation) {
+  if (orientation === "sidescroller") return 3;
+  if (mode2 === "pro") return tileSize <= 32 ? 15 : 25;
+  return 4;
+}
 function parseTerrainDescriptions(prompt) {
   const parts = prompt.split(/\d+\s*\)\s*\./).map((part) => part.trim()).filter(Boolean);
   if (parts.length < 2) return null;
@@ -550,6 +585,17 @@ var CharacterStateSchema = import_zod.z.object({
     height: import_zod.z.number().int().min(16).max(256)
   }).strict().optional()
 }).strict();
+var TerrainSideSchema = import_zod.z.enum(["lower", "upper"]);
+var TerrainLinkSchema = import_zod.z.object({
+  /** A terrain asset in the same style. */
+  of: import_zod.z.string().min(1),
+  /** Which of that set's terrains: its `lower` or its `upper`. */
+  terrain: TerrainSideSchema
+}).strict();
+var TerrainConnectSchema = import_zod.z.object({
+  lower: TerrainLinkSchema.optional(),
+  upper: TerrainLinkSchema.optional()
+}).strict().refine((connect) => connect.lower || connect.upper, { message: "connect needs lower, upper, or both" });
 var CharacterPortraitSizeSchema = import_zod.z.union([
   import_zod.z.literal(16),
   import_zod.z.literal(32),
@@ -580,13 +626,38 @@ var AssetVfxSchema = import_zod.z.object({
   parts: import_zod.z.array(VfxPartSchema).optional(),
   sprite: import_zod.z.string().min(1).optional(),
   fps: import_zod.z.number().int().min(1).max(60).optional(),
-  name: import_zod.z.string().min(1).optional()
+  name: import_zod.z.string().min(1).optional(),
+  description: import_zod.z.string().trim().min(1).max(8e3).optional(),
+  artist: import_zod.z.enum(["lite", "pro"]).optional()
 }).strict().superRefine((vfx, context) => {
+  if (vfx.description !== void 0) {
+    for (const key of ["preset", "recipe", "parts", "fps"]) {
+      if (vfx[key] !== void 0) {
+        context.addIssue({
+          code: import_zod.z.ZodIssueCode.custom,
+          message: `a vfx description goes to PixelLab's VFX artist, which takes no ${key}; use a description or the workbench's preset/recipe/parts/fps, not both`,
+          path: [key]
+        });
+      }
+    }
+    if (vfx.sprite && /^(character|object|gallery):/.test(vfx.sprite)) {
+      context.addIssue({
+        code: import_zod.z.ZodIssueCode.custom,
+        message: "the VFX artist takes a sprite's pixels, not a PixelLab reference; point sprite at a PNG file (another asset's output works)",
+        path: ["sprite"]
+      });
+    }
+    if (vfx.name && vfx.name.length > 80) {
+      context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "the VFX artist takes a name of at most 80 characters", path: ["name"] });
+    }
+  } else if (vfx.artist) {
+    context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "artist picks who draws a vfx description; add a description", path: ["artist"] });
+  }
   if (vfx.preset && vfx.recipe) {
     context.addIssue({ code: import_zod.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: import_zod.z.ZodIssueCode.custom, message: "a vfx needs a preset, a recipe, or at least one part", path: ["preset"] });
+  if (vfx.description === void 0 && !vfx.preset && !vfx.recipe && !vfx.parts?.length) {
+    context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "a vfx needs a preset, a recipe, or at least one part, or a description", path: ["preset"] });
   }
   if (vfx.sprite && /^(https?|data):/i.test(vfx.sprite)) {
     context.addIssue({
@@ -771,6 +842,8 @@ var RevisionSchema = import_zod.z.object({
   skeletonTemplate: import_zod.z.string().min(1).optional(),
   /** `remove-background` only: `simple` is faster and suits flat backgrounds; `complex` handles detailed edges. PixelLab defaults to `simple`. */
   removalTask: import_zod.z.enum(["simple", "complex"]).optional(),
+  /** `normal-map` only: `opengl` (green up; PixelLab's default) or `directx` (green down, for Unreal). */
+  convention: NormalMapConventionSchema.optional(),
   /**
    * `animate-skeleton`: what the character *looks like*, a noun
    * phrase (colours, clothing, held items) — distinct from the asset's
@@ -917,13 +990,20 @@ var RevisionSchema = import_zod.z.object({
       path: ["removalTask"]
     });
   }
-  if (revision.strength !== void 0 && revision.mode === "remove-background") {
+  if (revision.strength !== void 0 && (revision.mode === "remove-background" || revision.mode === "normal-map")) {
     context.addIssue({
       code: import_zod.z.ZodIssueCode.custom,
-      message: "remove-background revisions do not take a strength",
+      message: `${revision.mode} revisions do not take a strength`,
       path: ["strength"]
     });
   }
+  if (revision.convention !== void 0 && revision.mode !== "normal-map") {
+    context.addIssue({
+      code: import_zod.z.ZodIssueCode.custom,
+      message: "convention applies to normal-map revisions only",
+      path: ["convention"]
+    });
+  }
   if (revision.description !== void 0 && revision.mode !== "animate-skeleton" && revision.mode !== "remove-background") {
     context.addIssue({
       code: import_zod.z.ZodIssueCode.custom,
@@ -942,7 +1022,7 @@ var RevisionSchema = import_zod.z.object({
   }
 });
 var FRAME_SET_REVISION_MODES = ["animate", "animate-pixminimax", "animate-skeleton", "interpolate", "edit-animation"];
-var MEMBER_SET_REVISION_MODES = ["reduce-colors", "correct-pixelart", "edit-animation"];
+var MEMBER_SET_REVISION_MODES = ["reduce-colors", "correct-pixelart", "edit-animation", "normal-map"];
 var StyleObjectSchema = import_zod.z.object({
   /** Generation backend for this style. Omit to inherit the manifest default. */
   provider: import_zod.z.string().min(1).optional(),
@@ -1055,9 +1135,10 @@ var StyleObjectSchema = import_zod.z.object({
   terrainTileSize: import_zod.z.union([import_zod.z.literal(16), import_zod.z.literal(32), import_zod.z.literal(64)]).optional(),
   /**
    * `terrain` generator only. `standard` is the classic Wang tileset
-   * pipeline; `pro` is a newer corner-pair pipeline with its own shape
-   * controls (`terrainSpreadX`, `terrainSlopeSize`, `terrainRaggedness`)
-   * in place of `terrainShapeStyle`. The API default is `standard`.
+   * pipeline; `pro` is a newer pipeline with its own shape controls
+   * (`terrainRaggedness`, `terrainRoundness`, `terrainBoundaryAmplitude`,
+   * `terrainStepSlope`, `terrainConnectDiagonals`) in place of
+   * `terrainShapeStyle`. The API default is `standard`.
    */
   terrainMode: import_zod.z.enum(["standard", "pro"]).optional(),
   /**
@@ -1069,31 +1150,86 @@ var StyleObjectSchema = import_zod.z.object({
   /**
    * `terrain` generator only, `terrainMode: "standard"`. Procedural
    * boundary geometry: `square` or `round`, 16px or 32px tiles only.
-   * Rejected together with `terrainMode: "pro"`, whose own shape controls
-   * are `terrainSpreadX`/`terrainSlopeSize`/`terrainRaggedness`.
+   * Rejected together with `terrainMode: "pro"`, which has its own shape
+   * controls.
    */
   terrainShapeStyle: import_zod.z.enum(["square", "round"]).optional(),
-  /** `terrain` generator only, `terrainMode: "pro"`. Boundary spread
-   *  between terrains (0 = steep, 1 = gradual). API default 0.5. */
+  /**
+   * Deprecated: no effect. PixelLab's Pro pipeline no longer reads
+   * `spread_x`; the API keeps accepting it so existing calls work, and so
+   * does pixelkiln. Use `terrainBoundaryAmplitude` or `terrainStepSlope`.
+   */
   terrainSpreadX: import_zod.z.number().min(0).max(1).optional(),
-  /** `terrain` generator only, `terrainMode: "pro"`. Slope on the N/W/E
-   *  sides as a fraction of wall height. API default 0. */
+  /**
+   * Deprecated: no effect. PixelLab's Pro pipeline no longer reads
+   * `slope_size`; the API keeps accepting it so existing calls work, and
+   * so does pixelkiln. `terrainStepSlope` is the slope control now.
+   */
   terrainSlopeSize: import_zod.z.number().min(0).max(1).optional(),
   /** `terrain` generator only, `terrainMode: "pro"`. Terrain boundary
-   *  noise (0 = smooth, 1 = rough). API default 0. */
+   *  noise (0 = smooth, 1 = rough), half strength on tall sets
+   *  (`terrainTransitionSize` above 0.4). API default 0. */
   terrainRaggedness: import_zod.z.number().min(0).max(1).optional(),
+  /**
+   * `terrain` generator only, `terrainMode: "pro"` or `terrainShapeStyle`.
+   * Corner shape of the border between the terrains: 0 square, 1 round,
+   * 2 corners cut at 45° (values between blend). Above 1 needs pro. The API
+   * default is 0.85 on pro and 0.6 with a shape style. With
+   * `terrainConnectDiagonals`, 2 is the fix for 45° paths and coastlines
+   * that otherwise break into one island per step.
+   */
+  terrainRoundness: import_zod.z.number().min(0).max(2).optional(),
+  /**
+   * `terrain` generator only, `terrainMode: "pro"` (any transition size)
+   * or `terrainShapeStyle` (transition size up to 0.5). How far the border
+   * meanders instead of running straight: 0 straight (the default) to 0.3.
+   * Tiles still connect seamlessly.
+   */
+  terrainBoundaryAmplitude: import_zod.z.number().min(0).max(0.3).optional(),
+  /**
+   * `terrain` generator only, with `terrainBoundaryAmplitude`. Picks the
+   * meander's shape: another number gives a different border at the same
+   * amplitude, the same number the same border. API default 0.
+   */
+  terrainBoundarySeed: import_zod.z.number().int().min(0).optional(),
+  /**
+   * `terrain` generator only, `terrainMode: "pro"` with
+   * `terrainTransitionSize: 0.25`. How the bank between the terrains
+   * falls: 0 a straight cliff (the default) to 2 a gentle slope spread
+   * over more ground.
+   */
+  terrainStepSlope: import_zod.z.number().min(0).max(2).optional(),
+  /**
+   * `terrain` generator only, `terrainMode: "pro"`. On the two diagonal
+   * tiles (upper terrain in opposite corners), true joins the upper
+   * corners through the middle into one area; false (the default) runs the
+   * lower terrain between them.
+   */
+  terrainConnectDiagonals: import_zod.z.boolean().optional(),
   /**
    * `terrain` generator only. Visual height of the step between lower and
    * upper terrain. Without `terrainShapeStyle`, only 0, 0.25, 0.5, or 1 are
-   * accepted (1 switches to the 25-tile cliff layout, where corners take a
-   * third "transition" value); with it, any value from 0 to 1 works, but
-   * above 0.5 switches to an extended 32-tile layout this adapter does not
-   * model. API default 0.
+   * accepted. Standard switches to the 25-tile cliff layout at 1, where
+   * corners take a third "transition" value; Pro reads it as wall height
+   * and switches to the 25-tile tall-wall layout above 0.4, so 0.5 is
+   * already 25 tiles there. With `terrainShapeStyle`, any value from 0 to 1
+   * works, but above 0.5 switches to an extended 32-tile layout this
+   * adapter does not model. API default 0.
    */
   terrainTransitionSize: import_zod.z.number().min(0).max(1).optional(),
   /** `terrain` generator only. Camera angle; the API default is `high
    *  top-down`. */
   terrainView: import_zod.z.enum(["low top-down", "high top-down"]).optional(),
+  /**
+   * `terrain` generator only. `top-down` (the default) is a two-terrain
+   * map set from `/create-tileset`; `sidescroller` is a platform set from
+   * `/create-tileset-sidescroller`, seen from the side: the prompt's 1).
+   * is the platform body and 2). the top layer on it (grass, snow, moss),
+   * and the set's other terrain is empty air. 16 or 32px tiles,
+   * `terrainTransitionSize` 0, 0.25, 0.5, or 1 (the top layer's height),
+   * and none of the top-down mode, view, or shape controls.
+   */
+  terrainOrientation: import_zod.z.enum(["top-down", "sidescroller"]).optional(),
   /**
    * `isometricTile` generator only. `/create-isometric-tile`'s own tile
    * grid size, distinct from `size` (the generation canvas, 16-64px — the
@@ -1173,7 +1309,9 @@ var StyleObjectSchema = import_zod.z.object({
   /** Fixed seed for reproducibility where the endpoint supports it. */
   seed: import_zod.z.number().int().optional(),
   /**
-   * Forced palette, as `#rrggbb` values. `pixflux` only.
+   * Forced palette, as `#rrggbb` values. Sent as a swatch to `pixflux`
+   * and the generators that take one, and to `imagePro` as its
+   * `target_palette.colors` (2 to 256 colours).
    *
    * Unlike prose, this is a hard constraint. The API is handed a swatch
    * image and the output is limited to those colours. Verified: a four-colour
@@ -1183,6 +1321,10 @@ var StyleObjectSchema = import_zod.z.object({
    * chocolate bar.
    */
   palette: import_zod.z.array(HexColorSchema).default([]),
+  /** `imagePro` only: the palette's name ("Game Boy", "PICO-8"), which PixelLab uses to help the look. Needs `palette`. */
+  paletteName: import_zod.z.string().min(1).max(100).optional(),
+  /** `imagePro` only: at most this many colours in each candidate, 2 to 64 (drawn from `palette` when one is set). */
+  maxColors: import_zod.z.number().int().min(2).max(64).optional(),
   /**
    * Snap every visible pixel of the downloaded art to the nearest `palette`
    * colour, without dithering. The palette is sent to providers that take
@@ -1236,6 +1378,22 @@ var StyleSchema = StyleObjectSchema.refine((s) => !(s.tileFeature && s.styleImag
       path: ["quality"]
     });
   }
+  for (const field of ["paletteName", "maxColors"]) {
+    if (style[field] !== void 0 && style.generator !== "imagePro") {
+      ctx.addIssue({
+        code: import_zod.z.ZodIssueCode.custom,
+        message: `${field} applies to the imagePro generator only`,
+        path: [field]
+      });
+    }
+  }
+  if (style.paletteName !== void 0 && style.palette.length === 0) {
+    ctx.addIssue({
+      code: import_zod.z.ZodIssueCode.custom,
+      message: "paletteName names the palette's colours; set palette too",
+      path: ["paletteName"]
+    });
+  }
   if (style.enforcePalette && style.palette.length < 2) {
     ctx.addIssue({
       code: import_zod.z.ZodIssueCode.custom,
@@ -1361,6 +1519,8 @@ var AssetSchema = import_zod.z.object({
   scene: MapSceneSchema.optional(),
   /** `vfx` styles only: the effect to render. See `AssetVfxSchema`. */
   vfx: AssetVfxSchema.optional(),
+  /** `terrain` styles only: share a terrain with another set. See `TerrainConnectSchema`. */
+  connect: TerrainConnectSchema.optional(),
   /** `character` styles, `standard` humanoid bases: this character's proportions, over the style's. */
   proportions: CharacterProportionsSchema.optional(),
   /**
@@ -1437,7 +1597,7 @@ var AssetSchema = import_zod.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", asset.vfx && "vfx"].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", asset.connect && "connect"].filter(Boolean);
   if (shapes.length > 1) {
     context.addIssue({
       code: import_zod.z.ZodIssueCode.custom,
@@ -1529,6 +1689,10 @@ var LockSourceSchema = import_zod.z.object({
   role: import_zod.z.string().optional(),
   mediaType: MediaTypeSchema.optional()
 });
+var LockTerrainConnectSchema = import_zod.z.record(
+  TerrainSideSchema,
+  import_zod.z.object({ sourceAssetId: import_zod.z.string().min(1), sourceObjectId: import_zod.z.string().min(1) }).strict()
+);
 var LockHistoryEntrySchema = import_zod.z.object({
   specHash: import_zod.z.string(),
   generator: GeneratorSchema,
@@ -1551,6 +1715,8 @@ var LockHistoryEntrySchema = import_zod.z.object({
   billed: import_zod.z.object({ amount: import_zod.z.number(), unit: import_zod.z.string() }).nullable().default(null),
   provider: import_zod.z.string().default("pixellab"),
   postprocess: PostprocessSchema.optional(),
+  /** A connected terrain set's other sets; see LockEntrySchema.terrainConnect. */
+  terrainConnect: LockTerrainConnectSchema.optional(),
   /** When the replacement was submitted. */
   retiredAt: import_zod.z.string()
 });
@@ -1589,6 +1755,7 @@ var LockEntrySchema = import_zod.z.object({
     skeletonTemplate: import_zod.z.string().min(1).optional(),
     description: import_zod.z.string().min(1).optional(),
     removalTask: import_zod.z.enum(["simple", "complex"]).optional(),
+    convention: NormalMapConventionSchema.optional(),
     driftThreshold: import_zod.z.number().min(0).optional(),
     subjectDescription: import_zod.z.string().min(1).max(300).optional(),
     initialPose: import_zod.z.string().min(1).max(300).optional(),
@@ -1616,6 +1783,14 @@ var LockEntrySchema = import_zod.z.object({
     sourceSha256: import_zod.z.string().regex(/^[0-9a-f]{64}$/),
     referenceSha256: import_zod.z.string().regex(/^[0-9a-f]{64}$/)
   }).strict().nullable().default(null),
+  /**
+   * For a connected terrain set: per side of this set, the set it shares
+   * that terrain with and that set's provider id when this was submitted.
+   * Tracked the way `outfit` is, not through `specHash`: the other set's
+   * id lives in the lockfile, which manifest resolution does not read.
+   * Absent (not null) otherwise, so other entries do not grow the key.
+   */
+  terrainConnect: LockTerrainConnectSchema.optional(),
   /**
    * Output hashes owned by the previous generation while its replacement is
    * pending. They authorize replacing only unchanged PixelKiln-owned files.
@@ -1940,7 +2115,16 @@ var TilesetGetSchema = import_zod3.z.object({
     terrain_types: import_zod3.z.array(import_zod3.z.string()),
     tiles: import_zod3.z.array(TilesetTileSchema).min(1)
   }).passthrough(),
-  usage: UsageSchema
+  usage: UsageSchema,
+  /**
+   * `terrain_ids` names each terrain's base tile id: the id another set
+   * sends as `lower_base_tile_id`/`upper_base_tile_id` to share that
+   * terrain. A sidescroller set has only `lower` (its upper is empty air).
+   */
+  metadata: import_zod3.z.object({
+    terrain_ids: import_zod3.z.record(import_zod3.z.string()).nullable().optional(),
+    view: import_zod3.z.string().nullable().optional()
+  }).passthrough().nullable().optional()
 }).passthrough();
 var IsometricTileSubmitSchema = import_zod3.z.object({
   tile_id: import_zod3.z.string().min(1),
@@ -2029,6 +2213,12 @@ var ProFlashImageSubmitSchema = import_zod3.z.object({
   estimated_generations: import_zod3.z.number().nullable().optional(),
   usage: import_zod3.z.unknown().optional()
 }).passthrough();
+var VfxSubmitSchema = import_zod3.z.object({
+  background_job_id: import_zod3.z.string().min(1),
+  status: import_zod3.z.string().default("processing"),
+  quoted_generations: import_zod3.z.number().nullable().optional(),
+  usage: import_zod3.z.unknown().optional()
+}).passthrough();
 var UnzoomResponseSchema = import_zod3.z.object({
   image: import_zod3.z.object({ base64: import_zod3.z.string().min(1) }).passthrough(),
   original_size: import_zod3.z.object({ width: import_zod3.z.number().int(), height: import_zod3.z.number().int() }).passthrough(),
@@ -2369,12 +2559,19 @@ var PixelLabClient = class {
       upper_description: args.upperDescription
     };
     if (args.transitionDescription) body.transition_description = args.transitionDescription;
+    if (args.lowerBaseTileId) body.lower_base_tile_id = args.lowerBaseTileId;
+    if (args.upperBaseTileId) body.upper_base_tile_id = args.upperBaseTileId;
     if (args.tileSize != null) body.tile_size = { width: args.tileSize, height: args.tileSize };
     if (args.mode) body.mode = args.mode;
     if (args.shapeStyle) body.shape_style = args.shapeStyle;
     if (args.spreadX != null) body.spread_x = args.spreadX;
     if (args.slopeSize != null) body.slope_size = args.slopeSize;
     if (args.raggedness != null) body.raggedness = args.raggedness;
+    if (args.roundness != null) body.roundness = args.roundness;
+    if (args.boundaryAmplitude != null) body.boundary_amplitude = args.boundaryAmplitude;
+    if (args.boundarySeed != null) body.boundary_seed = args.boundarySeed;
+    if (args.stepSlope != null) body.step_slope = args.stepSlope;
+    if (args.connectDiagonals != null) body.connect_diagonals = args.connectDiagonals;
     if (args.transitionSize != null) body.transition_size = args.transitionSize;
     if (args.view) body.view = args.view;
     if (args.outline) body.outline = args.outline;
@@ -2387,14 +2584,48 @@ var PixelLabClient = class {
       "create tileset"
     );
   }
-  /** Throws PixelLabError(423) while the set is still drawing; see Tileset. */
+  /**
+   * `/create-tileset-sidescroller`: a platform set seen from the side. One
+   * terrain (`lower_description`, the platform body) and the decorative
+   * layer on top of it (`transition_description`); the other side of every
+   * edge is empty air, so there is no upper description, mode, view, or
+   * shape control. 16 or 32px tiles only. The result is read through
+   * `getTileset` like a top-down set.
+   */
+  async createTilesetSidescroller(args) {
+    const body = { lower_description: args.lowerDescription };
+    if (args.transitionDescription) body.transition_description = args.transitionDescription;
+    if (args.lowerBaseTileId) body.lower_base_tile_id = args.lowerBaseTileId;
+    if (args.tileSize != null) body.tile_size = { width: args.tileSize, height: args.tileSize };
+    if (args.transitionSize != null) body.transition_size = args.transitionSize;
+    if (args.outline) body.outline = args.outline;
+    if (args.shading) body.shading = args.shading;
+    if (args.detail) body.detail = args.detail;
+    if (args.seed != null) body.seed = args.seed;
+    return validateResponse(
+      TilesetSubmitSchema,
+      await this.request("/create-tileset-sidescroller", { method: "POST", body: JSON.stringify(body) }),
+      "create sidescroller tileset"
+    );
+  }
+  /**
+   * Throws PixelLabError(423) while the set is still drawing; see Tileset.
+   * Serves top-down and sidescroller sets alike.
+   */
   async getTileset(tilesetId) {
     const res = await validateResponse(
       TilesetGetSchema,
       await this.request(`/tilesets/${tilesetId}`),
       "get tileset"
     );
-    return { tileset: res.tileset, usage: res.usage ?? null };
+    return {
+      tileset: res.tileset,
+      usage: res.usage ?? null,
+      metadata: {
+        terrainIds: res.metadata?.terrain_ids ?? {},
+        view: res.metadata?.view ?? null
+      }
+    };
   }
   /** A single standalone isometric tile — no connectable set, no candidates. */
   async createIsometricTile(args) {
@@ -2931,6 +3162,13 @@ var PixelLabClient = class {
    *
    * Reference images and a style image (`reference_images`, `style_image` +
    * `style_options`) exist on this endpoint but are not modeled here yet.
+   *
+   * `targetPalette` is the beta `target_palette` (PixelLab 0.4.130): with
+   * `colors`, the image is drawn for them and every result pixel is one of
+   * them; `name` ("PICO-8") helps the look; `maxColors` caps the colours in
+   * each candidate. Its `smart` flag is not modeled: it is documented as
+   * "single images only", and this endpoint returns a grid of candidates
+   * below 171px.
    */
   async createImagePro(args) {
     const body = {
@@ -2939,6 +3177,14 @@ var PixelLabClient = class {
     };
     if (args.noBackground != null) body.no_background = args.noBackground;
     if (args.seed != null) body.seed = args.seed;
+    const palette = args.targetPalette;
+    if (palette && (palette.colors?.length || palette.maxColors != null)) {
+      body.target_palette = {
+        ...palette.colors?.length ? { colors: palette.colors } : {},
+        ...palette.name ? { name: palette.name } : {},
+        ...palette.maxColors != null ? { max_colors: palette.maxColors } : {}
+      };
+    }
     return validateResponse(
       RevisionJobSubmitSchema,
       await this.request("/generate-image-v2", { method: "POST", body: JSON.stringify(body) }),
@@ -3129,6 +3375,27 @@ var PixelLabClient = class {
     );
     return { png: Buffer.from(res.image.base64, "base64"), usage: res.usage };
   }
+  /**
+   * `/normal-map` (PixelLab 0.4.130): the normal map of a sprite, so a game
+   * engine can light it. RGB is the way each pixel faces, alpha is 255 where
+   * the sprite shows and 0 elsewhere, at the input's size. An animation goes
+   * as one horizontal strip of `frames` equal frames (up to 32, each 8 to 512
+   * px per side) and comes back as a strip, planned once on the first frame
+   * so the light stays steady. `opengl` (the default) is green up, for
+   * Godot, Unity, and Phaser; `directx` is green down, for Unreal. A
+   * background job whose map is `last_response.image`; 0.5 generation,
+   * charged only when the map is delivered.
+   */
+  async normalMap(args) {
+    const body = { image: args.image };
+    if (args.frames != null && args.frames !== 1) body.frames = args.frames;
+    if (args.convention) body.convention = args.convention;
+    return validateResponse(
+      RevisionJobSubmitSchema,
+      await this.request("/normal-map", { method: "POST", body: JSON.stringify(body) }),
+      "normal-map"
+    );
+  }
   /**
    * `/unzoom`: recover native-resolution pixel art from an upscaled image (a
    * 32x32 sprite saved at 512x512). Synchronous like the Cleanup tier.
@@ -3219,6 +3486,28 @@ var PixelLabClient = class {
       "generate-font-pro"
     );
   }
+  /**
+   * `POST /vfx`: PixelLab's effects artist builds an animated effect from a
+   * description, around an optional sprite, and saves it to My effects. With
+   * `effectId` it changes that saved effect in place; adding the effect's
+   * `conversation` prices the change as a change. A background job whose
+   * 202 carries `quoted_generations`; PixelLab bills on delivery, up to
+   * twice the quote. A 503 (renderer busy) is retried by the shared policy.
+   */
+  async createVfx(args) {
+    const body = { description: args.description };
+    if (args.artist) body.artist = args.artist;
+    if (args.sprite) body.sprite = { type: "base64", base64: args.sprite.base64, format: args.sprite.format };
+    if (args.effectId) body.effect_id = args.effectId;
+    if (args.conversation) body.conversation = args.conversation;
+    if (args.name) body.name = args.name;
+    if (args.gamePack) body.game_pack = true;
+    return validateResponse(
+      VfxSubmitSchema,
+      await this.request("/vfx", { method: "POST", body: JSON.stringify(body) }),
+      "vfx"
+    );
+  }
   /** `GET /generate-font-pro/{job_id}`: status, then no-auth atlas and `.ttf` URLs once completed. */
   async getFontJob(jobId) {
     const raw = await this.request(`/generate-font-pro/${encodeURIComponent(jobId)}`);
@@ -3818,6 +4107,41 @@ function parseHex(hex2) {
   const n = parseInt(m[1], 16);
   return { r: n >> 16 & 255, g: n >> 8 & 255, b: n & 255 };
 }
+function joinStripPng(frames) {
+  const decoded = frames.map((frame) => decodePng(frame));
+  const first = decoded[0];
+  if (!first) throw new Error("a strip needs at least one frame");
+  const { width, height } = first;
+  for (const [index, frame] of decoded.entries()) {
+    if (frame.width !== width || frame.height !== height) {
+      throw new Error(`strip frame ${index} is ${frame.width}x${frame.height}; frame 0 is ${width}x${height}`);
+    }
+  }
+  const stride = width * 4;
+  const out = Buffer.alloc(stride * decoded.length * height);
+  for (let y = 0; y < height; y++) {
+    for (const [index, frame] of decoded.entries()) {
+      frame.pixels.copy(out, (y * decoded.length + index) * stride, y * stride, (y + 1) * stride);
+    }
+  }
+  return encodeRgbaPng(width * decoded.length, height, out);
+}
+function splitStripPng(strip, frames) {
+  const image = decodePng(strip);
+  if (frames < 1 || image.width % frames !== 0) {
+    throw new Error(`a ${image.width}x${image.height} strip does not split into ${frames} equal frames`);
+  }
+  const width = image.width / frames;
+  const stride = width * 4;
+  return Array.from({ length: frames }, (_, index) => {
+    const out = Buffer.alloc(stride * image.height);
+    for (let y = 0; y < image.height; y++) {
+      const from = (y * image.width + index * width) * 4;
+      image.pixels.copy(out, y * stride, from, from + stride);
+    }
+    return encodeRgbaPng(width, image.height, out);
+  });
+}
 
 // src/media.ts
 var MediaType = {
@@ -3933,10 +4257,10 @@ function imageMetadata(buf) {
 }
 
 // src/providers/pixellab.ts
-var import_node_fs3 = require("fs");
+var import_node_fs4 = require("fs");
 var import_node_crypto2 = require("crypto");
 var import_node_os = __toESM(require("os"), 1);
-var import_node_path2 = __toESM(require("path"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
 
 // src/hash.ts
 var import_node_crypto = require("crypto");
@@ -3972,6 +4296,9 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
       detail: effect ? void 0 : spec.detail ?? null,
       seed: effect ? void 0 : spec.seed ?? null,
       palette: effect ? void 0 : spec.palette,
+      // `imagePro` only, and absent unless the style sets them.
+      paletteName: spec.paletteName,
+      maxColors: spec.maxColors,
       // `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
@@ -3986,6 +4313,25 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
       uiPieces: spec.uiPieces,
       uiElements: spec.uiElements,
       uiColorPalette: spec.uiColorPalette,
+      // The older terrain knobs (terrainMode, terrainTransitionSize, and the
+      // rest) were never part of this hash, and adding them now would make
+      // every existing terrain entry stale. The Pro shape controls added
+      // after them are identity, each only when set.
+      terrainRoundness: spec.terrainRoundness,
+      terrainBoundaryAmplitude: spec.terrainBoundaryAmplitude,
+      terrainBoundarySeed: spec.terrainBoundarySeed,
+      terrainStepSlope: spec.terrainStepSlope,
+      terrainConnectDiagonals: spec.terrainConnectDiagonals,
+      // "top-down" is the default and draws the same set as leaving it out.
+      terrainOrientation: spec.terrainOrientation === "sidescroller" ? spec.terrainOrientation : void 0,
+      // Which set and which of its terrains, not that terrain's id: the id
+      // is in the lockfile, and the plan compares it there (like a mirror).
+      terrainConnect: spec.terrainConnect ? Object.fromEntries(
+        ["lower", "upper"].flatMap((side) => {
+          const link = spec.terrainConnect[side];
+          return link ? [[side, { of: link.assetId, terrain: link.terrain }]] : [];
+        })
+      ) : void 0,
       // Scene and mask enter as their bytes' hashes, never their paths.
       scene: spec.scene ? {
         image: spec.scene.sha256,
@@ -4047,13 +4393,17 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         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.
+      // their paths; the My effects name is not identity. `description` and
+      // `artist` exist only for the paid VFX artist and stay absent for a
+      // workbench effect, so its hash is the one it always had.
       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
+        sprite: spec.vfx.sprite ? "reference" in spec.vfx.sprite ? spec.vfx.sprite.reference : spec.vfx.sprite.sha256 : void 0,
+        description: spec.vfx.description,
+        artist: spec.vfx.description ? spec.vfx.artist : 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.
@@ -4083,6 +4433,7 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         skeletonTemplate: spec.revision.skeletonTemplate,
         description: spec.revision.description,
         removalTask: spec.revision.removalTask,
+        convention: spec.revision.convention,
         driftThreshold: spec.revision.driftThreshold,
         subjectDescription: spec.revision.subjectDescription,
         initialPose: spec.revision.initialPose,
@@ -4229,7 +4580,8 @@ function vfxOutputPaths(out) {
     gif: `${base}.gif`,
     atlas: `${base}.json`,
     provenance: `${base}.vfx.json`,
-    gamePack: `${base}-game.zip`
+    gamePack: `${base}-game.zip`,
+    normals: `${base}-normals.png`
   };
 }
 function isVfxReference(sprite) {
@@ -4319,10 +4671,17 @@ function vfxRecipeSha256(recipe) {
   const { name: _name, notes: _notes, ...rest } = recipe;
   return sha256(JSON.stringify(rest));
 }
+function vfxAtlasFrames(atlas) {
+  const listed = atlas?.frames;
+  const entries = Array.isArray(listed) ? listed : listed && typeof listed === "object" ? Object.values(listed) : null;
+  if (!entries?.length) return null;
+  const rects = entries.map((entry) => entry?.frame);
+  return rects.every((rect) => rect && [rect.x, rect.y, rect.w, rect.h].every((n) => typeof n === "number")) ? rects : null;
+}
 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 listed = vfxAtlasFrames(atlas);
+  const rects = listed && listed.length === facts.frames ? listed : 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 };
   });
@@ -4382,45 +4741,516 @@ async function makeVfx(client2, opts) {
       bytes = Buffer.from(`${JSON.stringify(atlas, null, 2)}
 `);
     }
-    await (0, import_promises.writeFile)(target, bytes);
-    if (target === paths.gamePack) written.gamePack = target;
+    await (0, import_promises.writeFile)(target, bytes);
+    if (target === paths.gamePack) written.gamePack = target;
+  }
+  for (const file of [paths.sheet, paths.gif, paths.atlas]) {
+    if (!(0, import_node_fs2.existsSync)(file)) throw new Error(`PixelLab's export listed no file for ${import_node_path.default.basename(file)}: ${exported.files.join(", ")}`);
+  }
+  const spriteRecord = !opts.sprite || /^data:/.test(opts.sprite) ? void 0 : isVfxReference(opts.sprite) ? opts.sprite : import_node_path.default.relative(import_node_path.default.dirname(paths.provenance), import_node_path.default.resolve(opts.sprite)).split(import_node_path.default.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: import_node_path.default.basename(paths.sheet),
+      gif: import_node_path.default.basename(paths.gif),
+      atlas: import_node_path.default.basename(paths.atlas),
+      ...written.gamePack ? { gamePack: import_node_path.default.basename(written.gamePack) } : {}
+    },
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    recipe
+  };
+  await (0, import_promises.writeFile)(paths.provenance, `${JSON.stringify(provenance, null, 2)}
+`);
+  return { ...exported, paths: written, recipe };
+}
+var VFX_ARTISTS = ["lite", "pro"];
+var VFX_ARTIST_MAX_SPRITE = 512;
+function vfxArtistQuote(artist, sprite, change = false) {
+  const table = {
+    lite: { new: [1, 1, 3, 5], change: [1, 1, 2, 2] },
+    pro: { new: [6, 8, 14, 28], change: [4, 4, 5, 8] }
+  };
+  const tier = sprite === "none" ? 0 : sprite === "unknown" ? 3 : sprite <= 128 ? 1 : sprite <= 256 ? 2 : 3;
+  return table[artist][change ? "change" : "new"][tier];
+}
+function vfxArtistCeiling(quote) {
+  return quote * 2;
+}
+function vfxArtistSprite(bytes, label) {
+  const metadata = imageMetadata(bytes);
+  if (metadata?.format !== "png") throw new Error(`${label}: PixelLab's VFX artist takes a PNG sprite`);
+  const side = Math.max(metadata.width, metadata.height);
+  if (side > VFX_ARTIST_MAX_SPRITE) {
+    throw new Error(
+      `${label} is ${metadata.width}x${metadata.height}; PixelLab's VFX artist takes up to ${VFX_ARTIST_MAX_SPRITE}x${VFX_ARTIST_MAX_SPRITE} (crop or pad it; never rescale pixel art)`
+    );
+  }
+  return { image: { base64: bytes.toString("base64"), format: "png" }, side };
+}
+function vfxArtistFiles(raw) {
+  const urlOf = (value) => {
+    if (typeof value === "string") return /^https?:\/\//i.test(value) ? value : null;
+    if (!value || typeof value !== "object") return null;
+    for (const key of ["url", "download_url", "href"]) {
+      const url = value[key];
+      if (typeof url === "string" && /^https?:\/\//i.test(url)) return url;
+    }
+    return null;
+  };
+  const nameOf = (value, url, key) => {
+    if (value && typeof value === "object") {
+      for (const field of ["name", "filename", "file"]) {
+        const name = value[field];
+        if (typeof name === "string" && name) return name;
+      }
+    }
+    if (key && /\.[a-z0-9]+$/i.test(key)) return key;
+    return decodeURIComponent(new URL(url).pathname.split("/").pop() ?? "");
+  };
+  const entries = Array.isArray(raw) ? raw.map((value) => [void 0, value]) : raw && typeof raw === "object" ? Object.entries(raw) : [];
+  const files = [];
+  for (const [key, value] of entries) {
+    const url = urlOf(value);
+    if (url) files.push({ name: nameOf(value, url, key), url });
+  }
+  return files;
+}
+function parseVfxArtistResult(done, jobId) {
+  const files = vfxArtistFiles(done.files);
+  const pick = (test, skip) => files.find((file) => test.test(file.name) && !skip?.test(file.name)) ?? null;
+  const normals = /-normals?\.png$/i;
+  const sheet = pick(/\.png$/i, normals);
+  const effectId = typeof done.effect_id === "string" && done.effect_id ? done.effect_id : null;
+  if (!effectId || !sheet) {
+    throw new Error(
+      `Invalid PixelLab response for vfx job ${jobId}: completed without ${effectId ? "a spritesheet among its files" : "an effect_id"} (last_response keys: ${Object.keys(done).join(", ") || "none"}; files: ${JSON.stringify(done.files ?? null).slice(0, 400)}); update parseVfxArtistResult in src/pixellab-vfx.ts with the real shape`
+    );
+  }
+  const number = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+  const text = (value) => typeof value === "string" && value ? value : null;
+  const canvas = done.canvas ?? {};
+  const anchor = done.anchor;
+  return {
+    effectId,
+    name: text(done.name),
+    editUrl: text(done.edit_url),
+    message: text(done.message),
+    width: number(canvas.w),
+    height: number(canvas.h),
+    frames: number(done.frames),
+    fps: number(done.fps),
+    loop: typeof done.loop === "boolean" ? done.loop : null,
+    anchor: anchor && number(anchor.x) !== null && number(anchor.y) !== null ? { kind: text(anchor.kind), x: anchor.x, y: anchor.y } : null,
+    parts: done.parts ?? null,
+    conversation: text(done.conversation),
+    files,
+    sheet,
+    atlas: pick(/\.json$/i),
+    gif: pick(/\.gif$/i),
+    gamePack: pick(/\.zip$/i),
+    normals: pick(normals)
+  };
+}
+function vfxArtistFrameFacts(result, atlas) {
+  const rects = vfxAtlasFrames(atlas);
+  const frames = result.frames ?? rects?.length ?? null;
+  const width = result.width ?? rects?.[0]?.w ?? null;
+  const height = result.height ?? rects?.[0]?.h ?? null;
+  if (!frames || !width || !height) {
+    throw new Error(`PixelLab vfx effect ${result.effectId} came back with no frame size or count, in the result or its atlas`);
+  }
+  return { width, height, frames };
+}
+async function makeVfxWithArtist(client2, opts) {
+  const paths = vfxOutputPaths(opts.out);
+  if (!opts.force) {
+    for (const file of [paths.sheet, paths.gif, paths.atlas, paths.provenance, ...opts.gamePack ? [paths.gamePack] : []]) {
+      if ((0, import_node_fs2.existsSync)(file)) throw new Error(`${file} already exists; pass --force to replace it`);
+    }
+  }
+  const progress = opts.onProgress ?? (() => {
+  });
+  const sprite = opts.sprite ? vfxArtistSprite(await (0, import_promises.readFile)(opts.sprite), opts.sprite).image : void 0;
+  const sleep3 = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const interval = opts.intervalMs ?? 6e3;
+  const timeout = opts.timeoutMs ?? 10 * 6e4;
+  const submitted = await client2.createVfx({
+    description: opts.description,
+    artist: opts.artist,
+    sprite,
+    effectId: opts.effect,
+    conversation: opts.effect ? opts.conversation : void 0,
+    name: opts.name,
+    gamePack: opts.gamePack
+  });
+  const jobId = submitted.background_job_id;
+  progress(`submitted job ${jobId}, quoted ${submitted.quoted_generations ?? "?"} generations`);
+  const started = Date.now();
+  let job;
+  for (; ; ) {
+    job = await client2.getBackgroundJob(jobId);
+    if (job.status === "completed") break;
+    if (job.status === "failed") throw new Error(`PixelLab vfx job ${jobId} failed upstream${vfxJobFailure(job.last_response)}`);
+    if (Date.now() - started > timeout) {
+      throw new Error(
+        `PixelLab vfx job ${jobId} is still ${job.status} after ${Math.round(timeout / 1e3)} s; it keeps running upstream (and bills when delivered), but this command has stopped waiting`
+      );
+    }
+    progress(job.status);
+    await sleep3(interval);
+  }
+  const result = parseVfxArtistResult(job.last_response ?? {}, jobId);
+  await (0, import_promises.mkdir)(import_node_path.default.dirname(paths.sheet), { recursive: true });
+  const written = { sheet: paths.sheet, provenance: paths.provenance };
+  await (0, import_promises.writeFile)(paths.sheet, await client2.download(result.sheet.url));
+  let atlas;
+  if (result.atlas) {
+    atlas = JSON.parse((await client2.download(result.atlas.url)).toString("utf8"));
+    const meta = atlas.meta;
+    if (meta) meta.image = import_node_path.default.basename(paths.sheet);
+    await (0, import_promises.writeFile)(paths.atlas, `${JSON.stringify(atlas, null, 2)}
+`);
+    written.atlas = paths.atlas;
+  }
+  for (const [file, target, key] of [
+    [result.gif, paths.gif, "gif"],
+    [result.gamePack, paths.gamePack, "gamePack"],
+    [result.normals, paths.normals, "normals"]
+  ]) {
+    if (!file) continue;
+    await (0, import_promises.writeFile)(target, await client2.download(file.url));
+    written[key] = target;
+  }
+  const facts = vfxArtistFrameFacts(result, atlas);
+  const usage = job.usage ?? null;
+  const provenance = {
+    version: 1,
+    provider: "pixellab",
+    tool: "vfx",
+    artist: opts.artist ?? "lite",
+    description: opts.description,
+    name: result.name,
+    effectId: result.effectId,
+    editUrl: result.editUrl,
+    message: result.message,
+    source: {
+      ...opts.sprite ? { sprite: import_node_path.default.relative(import_node_path.default.dirname(paths.provenance), import_node_path.default.resolve(opts.sprite)).split(import_node_path.default.sep).join("/") } : {},
+      ...opts.effect ? { changed: opts.effect } : {}
+    },
+    ...facts,
+    fps: result.fps,
+    loop: result.loop,
+    anchor: result.anchor,
+    parts: result.parts,
+    files: Object.fromEntries(
+      ["sheet", "gif", "atlas", "gamePack", "normals"].filter((key) => written[key]).map((key) => [key, import_node_path.default.basename(written[key])])
+    ),
+    quotedGenerations: submitted.quoted_generations ?? null,
+    usage,
+    conversation: result.conversation,
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await (0, import_promises.writeFile)(paths.provenance, `${JSON.stringify(provenance, null, 2)}
+`);
+  return {
+    jobId,
+    effectId: result.effectId,
+    editUrl: result.editUrl,
+    name: result.name,
+    message: result.message,
+    ...facts,
+    fps: result.fps,
+    loop: result.loop,
+    anchor: result.anchor,
+    quotedGenerations: submitted.quoted_generations ?? null,
+    usage,
+    paths: written
+  };
+}
+function vfxJobFailure(done) {
+  for (const key of ["error", "detail", "message"]) {
+    const value = done?.[key];
+    if (typeof value === "string" && value) return `: ${value}`;
+  }
+  return "";
+}
+async function readVfxConversation(file, effectId) {
+  if (!(0, import_node_fs2.existsSync)(file)) return void 0;
+  try {
+    const record = JSON.parse(await (0, import_promises.readFile)(file, "utf8"));
+    return record.effectId === effectId && typeof record.conversation === "string" ? record.conversation : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/source-url.ts
+var SENSITIVE_QUERY_KEYS = /* @__PURE__ */ new Set([
+  "access_token",
+  "apikey",
+  "api_key",
+  "auth",
+  "authorization",
+  "awsaccesskeyid",
+  "googleaccessid",
+  "key",
+  "sig"
+]);
+function isSensitiveSourceUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
+  }
+  if (parsed.username || parsed.password) return true;
+  for (const key of parsed.searchParams.keys()) {
+    const normalized = key.toLowerCase();
+    if (SENSITIVE_QUERY_KEYS.has(normalized) || normalized.includes("credential") || normalized.includes("signature") || normalized.includes("security-token") || normalized.includes("token")) return true;
+  }
+  return false;
+}
+function shouldPersistSourceUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return true;
+  }
+  if (parsed.protocol === "data:" || parsed.protocol === "file:") return false;
+  return !isSensitiveSourceUrl(value);
+}
+
+// src/pixellab-utils.ts
+var import_node_fs3 = require("fs");
+var import_promises2 = require("fs/promises");
+var import_node_path2 = __toESM(require("path"), 1);
+var UNZOOM_MIN_SIDE = 256;
+var UNZOOM_MAX_AREA = 2048 * 2048;
+function defaultUnzoomOut(input) {
+  const ext = import_node_path2.default.extname(input);
+  return `${ext ? input.slice(0, -ext.length) : input}.unzoomed.png`;
+}
+async function unzoomFile(client2, input, opts = {}) {
+  const out = import_node_path2.default.resolve(opts.out ?? defaultUnzoomOut(input));
+  if (import_node_path2.default.resolve(input) === out) throw new Error("unzoom will not overwrite its own input; pass a different --out");
+  if ((0, import_node_fs3.existsSync)(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
+  const bytes = await (0, import_promises2.readFile)(input);
+  const metadata = imageMetadata(bytes);
+  if (!metadata) throw new Error(`${input} is not a readable PNG or JPEG`);
+  const { width, height, format } = metadata;
+  if (width < UNZOOM_MIN_SIDE || height < UNZOOM_MIN_SIDE) {
+    throw new Error(
+      `${input} is ${width}x${height}; PixelLab's unzoom needs at least ${UNZOOM_MIN_SIDE}x${UNZOOM_MIN_SIDE} to find the pixel grid, so this is probably already at its native size`
+    );
+  }
+  if (width * height > UNZOOM_MAX_AREA) {
+    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 (0, import_promises2.mkdir)(import_node_path2.default.dirname(out), { recursive: true });
+  await (0, import_promises2.writeFile)(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 = import_node_path2.default.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 ((0, import_node_fs3.existsSync)(file)) throw new Error(`${file} already exists; pass --force to replace it`);
+    }
+  }
+  const sleep3 = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const interval = opts.intervalMs ?? 5e3;
+  const timeout = opts.timeoutMs ?? 10 * 6e4;
+  const submitted = await client2.generateFontPro({
+    description: opts.description,
+    weight: opts.weight,
+    glyphPx: opts.glyphPx,
+    seed: opts.seed,
+    fontName: opts.fontName
+  });
+  const jobId = submitted.background_job_id;
+  const started = Date.now();
+  for (; ; ) {
+    const job = await client2.getFontJob(jobId);
+    opts.onProgress?.(job.status);
+    if (job.status === "failed") throw new Error(`PixelLab font job ${jobId} failed upstream`);
+    if (job.status === "completed") {
+      if (!job.download_ttf_url || !job.download_atlas_url) {
+        throw new Error(`PixelLab font job ${jobId} completed without both download URLs`);
+      }
+      const [ttfBytes, atlasBytes] = await Promise.all([
+        client2.download(job.download_ttf_url),
+        client2.download(job.download_atlas_url)
+      ]);
+      await (0, import_promises2.mkdir)(import_node_path2.default.dirname(ttf), { recursive: true });
+      await (0, import_promises2.writeFile)(ttf, ttfBytes);
+      await (0, import_promises2.writeFile)(atlas, atlasBytes);
+      return { jobId, ttf, atlas, glyphPx: job.glyph_px ?? null, usage: job.usage };
+    }
+    if (Date.now() - started > timeout) {
+      throw new Error(
+        `PixelLab font job ${jobId} is still ${job.status} after ${Math.round(timeout / 1e3)} s; it keeps running upstream, but this command has stopped waiting`
+      );
+    }
+    await sleep3(interval);
+  }
+}
+var PIXELATE_COST_GENERATIONS = 6;
+var PIXELATE_MAX_SIDE = 2048;
+function defaultPixelateOut(input) {
+  const ext = import_node_path2.default.extname(input);
+  return `${ext ? input.slice(0, -ext.length) : input}.pixel.png`;
+}
+async function pixelateFile(client2, input, opts = {}) {
+  const out = import_node_path2.default.resolve(opts.out ?? defaultPixelateOut(input));
+  if (import_node_path2.default.resolve(input) === out) throw new Error("pixelate will not overwrite its own input; pass a different --out");
+  if ((0, import_node_fs3.existsSync)(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
+  const bytes = await (0, import_promises2.readFile)(input);
+  const metadata = imageMetadata(bytes);
+  if (!metadata) throw new Error(`${input} is not a readable PNG or JPEG`);
+  const { width, height, format } = metadata;
+  const sleep3 = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const interval = opts.intervalMs ?? 5e3;
+  const timeout = opts.timeoutMs ?? 10 * 6e4;
+  const submitted = await client2.imageToPixelartProFlash({
+    image: { base64: bytes.toString("base64"), format },
+    description: opts.description,
+    seed: opts.seed
+  });
+  const jobId = submitted.background_job_id;
+  const started = Date.now();
+  for (; ; ) {
+    const job = await client2.getBackgroundJob(jobId);
+    opts.onProgress?.(job.status);
+    if (job.status === "failed") throw new Error(`PixelLab pixelate job ${jobId} failed upstream`);
+    if (job.status === "completed") {
+      const images = job.last_response?.images;
+      const first = Array.isArray(images) ? images[0] : void 0;
+      if (!first || typeof first.base64 !== "string" || !first.base64) {
+        throw new Error(`PixelLab pixelate job ${jobId} completed without an image at last_response.images[0]`);
+      }
+      const png = Buffer.from(first.base64, "base64");
+      const size = imageMetadata(png);
+      await (0, import_promises2.mkdir)(import_node_path2.default.dirname(out), { recursive: true });
+      await (0, import_promises2.writeFile)(out, png);
+      return {
+        jobId,
+        out,
+        original: { width, height },
+        pixelated: { width: size?.width ?? Number(first.width), height: size?.height ?? Number(first.height) },
+        imageId: submitted.image_id,
+        usage: job.usage ?? null
+      };
+    }
+    if (Date.now() - started > timeout) {
+      throw new Error(
+        `PixelLab pixelate job ${jobId} is still ${job.status} after ${Math.round(timeout / 1e3)} s; it keeps running upstream, but this command has stopped waiting`
+      );
+    }
+    await sleep3(interval);
   }
-  for (const file of [paths.sheet, paths.gif, paths.atlas]) {
-    if (!(0, import_node_fs2.existsSync)(file)) throw new Error(`PixelLab's export listed no file for ${import_node_path.default.basename(file)}: ${exported.files.join(", ")}`);
+}
+var NORMAL_MAP_COST_GENERATIONS = 0.5;
+var NORMAL_MAP_MIN_SIDE = 8;
+var NORMAL_MAP_MAX_SIDE = 512;
+var NORMAL_MAP_MAX_FRAMES = 32;
+var NORMAL_MAP_CONVENTIONS = ["opengl", "directx"];
+function normalMapSizeProblem(width, height, frames = 1) {
+  if (!Number.isInteger(frames) || frames < 1 || frames > NORMAL_MAP_MAX_FRAMES) {
+    return `PixelLab's normal map takes 1 to ${NORMAL_MAP_MAX_FRAMES} frames, not ${frames}`;
+  }
+  if (width % frames !== 0) return `a ${width}px-wide strip does not split into ${frames} equal frames`;
+  const frameWidth = width / frames;
+  if (frameWidth < NORMAL_MAP_MIN_SIDE || height < NORMAL_MAP_MIN_SIDE || frameWidth > NORMAL_MAP_MAX_SIDE || height > NORMAL_MAP_MAX_SIDE) {
+    return `${frames > 1 ? "each frame is " : "it is "}${frameWidth}x${height}; PixelLab's normal map takes ${NORMAL_MAP_MIN_SIDE} to ${NORMAL_MAP_MAX_SIDE} px per side`;
+  }
+  return null;
+}
+function defaultNormalMapOut(input) {
+  const ext = import_node_path2.default.extname(input);
+  return `${ext ? input.slice(0, -ext.length) : input}.normal.png`;
+}
+function normalMapResultPng(lastResponse) {
+  const image = lastResponse?.image;
+  const base64 = typeof image === "string" ? image : image?.base64;
+  if (typeof base64 !== "string" || !base64) return null;
+  return Buffer.from(base64.replace(/^data:image\/\w+;base64,/, ""), "base64");
+}
+async function normalMapFile(client2, input, opts = {}) {
+  const out = import_node_path2.default.resolve(opts.out ?? defaultNormalMapOut(input));
+  if (import_node_path2.default.resolve(input) === out) throw new Error("normal-map will not overwrite its own input; pass a different --out");
+  if ((0, import_node_fs3.existsSync)(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
+  const bytes = await (0, import_promises2.readFile)(input);
+  const metadata = imageMetadata(bytes);
+  if (!metadata) throw new Error(`${input} is not a readable PNG or JPEG`);
+  if (metadata.format !== "png") throw new Error(`${input} is a JPEG; normal-map reads a PNG, whose alpha marks where the sprite is`);
+  const { width, height } = metadata;
+  const frames = opts.frames ?? 1;
+  const problem = normalMapSizeProblem(width, height, frames);
+  if (problem) throw new Error(`${input}: ${problem}`);
+  const sleep3 = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const interval = opts.intervalMs ?? 5e3;
+  const timeout = opts.timeoutMs ?? 10 * 6e4;
+  const submitted = await client2.normalMap({
+    image: { base64: bytes.toString("base64"), format: "png" },
+    frames,
+    convention: opts.convention
+  });
+  const jobId = submitted.background_job_id;
+  const started = Date.now();
+  for (; ; ) {
+    const job = await client2.getBackgroundJob(jobId);
+    opts.onProgress?.(job.status);
+    if (job.status === "failed") throw new Error(`PixelLab normal-map job ${jobId} failed upstream`);
+    if (job.status === "completed") {
+      const png = normalMapResultPng(job.last_response);
+      if (!png) throw new Error(`PixelLab normal-map job ${jobId} completed without an image at last_response.image`);
+      await (0, import_promises2.mkdir)(import_node_path2.default.dirname(out), { recursive: true });
+      await (0, import_promises2.writeFile)(out, png);
+      const size = imageMetadata(png);
+      return {
+        jobId,
+        out,
+        width: size?.width ?? width,
+        height: size?.height ?? height,
+        frames,
+        convention: opts.convention ?? "opengl",
+        usage: job.usage ?? null
+      };
+    }
+    if (Date.now() - started > timeout) {
+      throw new Error(
+        `PixelLab normal-map job ${jobId} is still ${job.status} after ${Math.round(timeout / 1e3)} s; it keeps running upstream, but this command has stopped waiting`
+      );
+    }
+    await sleep3(interval);
   }
-  const spriteRecord = !opts.sprite || /^data:/.test(opts.sprite) ? void 0 : isVfxReference(opts.sprite) ? opts.sprite : import_node_path.default.relative(import_node_path.default.dirname(paths.provenance), import_node_path.default.resolve(opts.sprite)).split(import_node_path.default.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: import_node_path.default.basename(paths.sheet),
-      gif: import_node_path.default.basename(paths.gif),
-      atlas: import_node_path.default.basename(paths.atlas),
-      ...written.gamePack ? { gamePack: import_node_path.default.basename(written.gamePack) } : {}
-    },
-    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    recipe
-  };
-  await (0, import_promises.writeFile)(paths.provenance, `${JSON.stringify(provenance, null, 2)}
-`);
-  return { ...exported, paths: written, recipe };
 }
 
 // src/providers/pixellab.ts
@@ -4440,6 +5270,20 @@ function pixelLabObjectUrl(generator, objectId) {
   if (generator === "vfx") return `https://pixellab.ai/create-vfx?effect=${encodeURIComponent(objectId)}`;
   return null;
 }
+function vfxArtistSpecQuote(spec) {
+  const sprite = spec.vfx?.sprite;
+  const side = !sprite ? "none" : "file" in sprite && sprite.width != null && sprite.height != null ? Math.max(sprite.width, sprite.height) : "unknown";
+  return vfxArtistQuote(spec.vfx?.artist ?? "lite", side);
+}
+function workbenchVfxUrls(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(", ")}`);
+  return {
+    sheet: `${exported.downloadBase}${encodeURIComponent(sheetFile)}`,
+    ...atlasFile ? { atlas: `${exported.downloadBase}${encodeURIComponent(atlasFile)}` } : {}
+  };
+}
 function billedFromUsage(usage) {
   if (!usage) return null;
   if (usage.type === "usd" || usage.type === void 0 && typeof usage.usd === "number") {
@@ -4594,13 +5438,14 @@ var PixelLabProvider = class _PixelLabProvider {
    * source from a supplied per-frame skeleton instead of a text description)
    * — and `interpolate` (`/interpolation-v2`, the in-betweens
    * from one keyframe to another) and `edit-animation`
-   * (`/edit-animation-v2`, one text edit applied across a whole frame set).
+   * (`/edit-animation-v2`, one text edit applied across a whole frame set),
+   * and `normal-map` (`/normal-map`, lighting data for a sprite or a loop).
    * `outpaint` does not: there is no canvas-expansion endpoint in the API,
    * matching docs/REVISIONS.md's note that no provider ships a tested
    * outpaint path yet.
    */
   supportsRevision(mode2) {
-    return mode2 === "inpaint" || mode2 === "image-to-image" || mode2 === "reduce-colors" || mode2 === "correct-pixelart" || mode2 === "remove-background" || mode2 === "animate" || mode2 === "animate-pixminimax" || mode2 === "animate-skeleton" || mode2 === "interpolate" || mode2 === "edit-animation";
+    return mode2 === "inpaint" || mode2 === "image-to-image" || mode2 === "reduce-colors" || mode2 === "correct-pixelart" || mode2 === "remove-background" || mode2 === "normal-map" || mode2 === "animate" || mode2 === "animate-pixminimax" || mode2 === "animate-skeleton" || mode2 === "interpolate" || mode2 === "edit-animation";
   }
   /** PixelLab's own constraints: submissions must be >2s apart, and
    *  background jobs in flight are capped by subscription tier (Tier 1=8,
@@ -4620,11 +5465,12 @@ var PixelLabProvider = class _PixelLabProvider {
    * is a file read.
    */
   static cacheDir(namespace = "pixflux") {
-    const dir = import_node_path2.default.join(import_node_os.default.tmpdir(), `pixelkiln-${namespace}`);
-    (0, import_node_fs3.mkdirSync)(dir, { recursive: true });
+    const dir = import_node_path3.default.join(import_node_os.default.tmpdir(), `pixelkiln-${namespace}`);
+    (0, import_node_fs4.mkdirSync)(dir, { recursive: true });
     return dir;
   }
   estimate(spec) {
+    if (spec.vfx?.description) return { unit: "generations", amount: vfxArtistCeiling(vfxArtistSpecQuote(spec)), candidates: 1 };
     if (spec.vfx) return { unit: "generations", amount: 0, candidates: 1 };
     if (spec.batch?.role === "member") {
       return { unit: "generations", amount: 0, candidates: 1 };
@@ -4632,6 +5478,9 @@ var PixelLabProvider = class _PixelLabProvider {
     if (spec.revision?.mode === "remove-background") {
       return { unit: "generations", amount: 1, candidates: 1 };
     }
+    if (spec.revision?.mode === "normal-map") {
+      return { unit: "generations", amount: NORMAL_MAP_COST_GENERATIONS, candidates: 1 };
+    }
     if (spec.revision?.mode === "reduce-colors" || spec.revision?.mode === "correct-pixelart") {
       return { unit: "generations", amount: 0.1, candidates: 1 };
     }
@@ -4686,12 +5535,40 @@ var PixelLabProvider = class _PixelLabProvider {
     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 sprite = spec.vfx?.description ? spec.vfx.sprite : void 0;
+    if (sprite && "reference" in sprite) {
+      throw new Error("PixelLab's VFX artist takes a sprite's pixels, not a PixelLab reference; point vfx.sprite at a PNG file");
+    }
+    if (sprite?.width != null && sprite.height != null && Math.max(sprite.width, sprite.height) > VFX_ARTIST_MAX_SPRITE) {
+      throw new Error(
+        `vfx sprite ${sprite.file} is ${sprite.width}x${sprite.height}; PixelLab's VFX artist takes up to ${VFX_ARTIST_MAX_SPRITE}x${VFX_ARTIST_MAX_SPRITE} (crop or pad it; never rescale pixel art)`
+      );
+    }
     const members = spec.revision?.sourceMembers;
     if (spec.revision && members && !MEMBER_SET_REVISION_MODES.includes(spec.revision.mode)) {
       throw new Error(
-        `PixelLab ${spec.revision.mode} reads one source image; ${spec.revision.sourceAssetId} is a ${members.length}-member set (${members[0].role}, ...). Revise one member through a declared source, or use reduce-colors, correct-pixelart, or edit-animation, which take the whole set`
+        `PixelLab ${spec.revision.mode} reads one source image; ${spec.revision.sourceAssetId} is a ${members.length}-member set (${members[0].role}, ...). Revise one member through a declared source, or use reduce-colors, correct-pixelart, edit-animation, or normal-map, which take the whole set`
       );
     }
+    if (spec.revision?.mode === "normal-map") {
+      const { sourceWidth: width, sourceHeight: height, sourceFormat, sourceAssetId } = spec.revision;
+      if (members && !members.every((member) => member.role.startsWith("frame-"))) {
+        throw new Error(
+          `PixelLab normal-map reads one sprite or one animation loop; ${sourceAssetId} is a set of directions (${members.map((member) => member.role).join(", ")}). Make one normal-map revision per direction, each from an asset whose \`source\` is that direction's file`
+        );
+      }
+      if (members && members.length > NORMAL_MAP_MAX_FRAMES) {
+        throw new Error(
+          `PixelLab normal-map takes at most ${NORMAL_MAP_MAX_FRAMES} frames in one strip; ${sourceAssetId} has ${members.length}`
+        );
+      }
+      if (sourceFormat === "jpeg") {
+        throw new Error(`PixelLab normal-map reads a PNG, whose alpha marks where the sprite is; ${sourceAssetId} is a JPEG`);
+      }
+      const frames = members?.length ?? 1;
+      const problem = width != null && height != null ? normalMapSizeProblem(width * frames, height, frames) : null;
+      if (problem) throw new Error(`PixelLab normal-map source ${sourceAssetId}: ${problem}`);
+    }
     if (spec.revision?.engine === "pro-flash") {
       const { sourceWidth: width, sourceHeight: height, mode: mode2 } = spec.revision;
       if (width != null && height != null && (width < 32 || height < 32 || width > 256 || height > 256 || width % 4 || height % 4)) {
@@ -4799,6 +5676,9 @@ var PixelLabProvider = class _PixelLabProvider {
         `PixelLab imagePro is ${spec.width}x${spec.height}; the API takes 16 to 792 wide and 16 to 688 tall (the exact ceiling also depends on aspect ratio)`
       );
     }
+    if (spec.generator === "imagePro" && !spec.revision && spec.palette.length && (spec.palette.length < 2 || spec.palette.length > 256)) {
+      throw new Error(`PixelLab imagePro's target palette takes 2 to 256 colours; the style's palette has ${spec.palette.length}`);
+    }
     if (spec.generator === "uiAsset" && (spec.width < 192 || spec.height < 192 || spec.width > 688 || spec.height > 688)) {
       throw new Error(
         `PixelLab uiAsset is ${spec.width}x${spec.height}; the API takes 192 to 688 pixels per side (the exact ceiling also depends on aspect ratio \u2014 square tops out at 512, 16:9 at 688x384, 9:16 at 384x688, 4:3 at 600x448, 3:4 at 448x600)`
@@ -4865,24 +5745,8 @@ var PixelLabProvider = class _PixelLabProvider {
       if (spec.detail) {
         requirePixelLabOption("terrain", "detail", spec.detail, ["low detail", "medium detail", "highly detailed"]);
       }
-      if (spec.terrainShapeStyle && spec.terrainMode === "pro") {
-        throw new Error(
-          "PixelLab terrain: terrainShapeStyle is standard-mode only; pro's own shape controls are terrainSpreadX/terrainSlopeSize/terrainRaggedness"
-        );
-      }
-      if (spec.terrainTileSize === 64 && spec.terrainMode !== "pro") {
-        throw new Error('PixelLab terrain: a 64px tile needs terrainMode: "pro"');
-      }
-      if (spec.terrainShapeStyle && spec.terrainTransitionSize != null && spec.terrainTransitionSize > 0.5) {
-        throw new Error(
-          "PixelLab terrain: terrainShapeStyle with terrainTransitionSize above 0.5 uses an extended 32-tile layout pixelkiln does not model; use 0, 0.25, or 0.5"
-        );
-      }
-      if (!spec.terrainShapeStyle && spec.terrainTransitionSize != null && ![0, 0.25, 0.5, 1].includes(spec.terrainTransitionSize)) {
-        throw new Error(
-          "PixelLab terrain: terrainTransitionSize must be 0, 0.25, 0.5, or 1 unless terrainShapeStyle is set"
-        );
-      }
+      if (spec.terrainOrientation === "sidescroller") this.validateSidescrollerTerrain(spec);
+      else this.validateTopDownTerrain(spec);
     }
     if (spec.generator === "isometricTile") {
       if (spec.outline) {
@@ -4941,6 +5805,87 @@ var PixelLabProvider = class _PixelLabProvider {
       );
     }
   }
+  /** `/create-tileset`'s own rules, beyond the enums both terrain endpoints share. */
+  validateTopDownTerrain(spec) {
+    if (spec.terrainShapeStyle && spec.terrainMode === "pro") {
+      throw new Error(
+        "PixelLab terrain: terrainShapeStyle is standard-mode only; pro's own shape controls are terrainRaggedness/terrainRoundness/terrainBoundaryAmplitude/terrainStepSlope"
+      );
+    }
+    const pro = spec.terrainMode === "pro";
+    if (spec.terrainRoundness != null && !pro && !spec.terrainShapeStyle) {
+      throw new Error('PixelLab terrain: terrainRoundness needs terrainMode: "pro" or a terrainShapeStyle');
+    }
+    if (spec.terrainRoundness != null && spec.terrainRoundness > 1 && !pro) {
+      throw new Error('PixelLab terrain: terrainRoundness above 1 (corners cut toward 45\xB0) needs terrainMode: "pro"');
+    }
+    if (spec.terrainBoundaryAmplitude != null && !pro && !spec.terrainShapeStyle) {
+      throw new Error('PixelLab terrain: terrainBoundaryAmplitude needs terrainMode: "pro" or a terrainShapeStyle');
+    }
+    if (spec.terrainBoundarySeed != null && spec.terrainBoundaryAmplitude == null) {
+      throw new Error("PixelLab terrain: terrainBoundarySeed shapes terrainBoundaryAmplitude's border; set both or neither");
+    }
+    if (spec.terrainStepSlope != null && !(pro && spec.terrainTransitionSize === 0.25)) {
+      throw new Error('PixelLab terrain: terrainStepSlope needs terrainMode: "pro" with terrainTransitionSize 0.25');
+    }
+    if (spec.terrainConnectDiagonals != null && !pro) {
+      throw new Error('PixelLab terrain: terrainConnectDiagonals needs terrainMode: "pro"');
+    }
+    if (spec.terrainTileSize === 64 && spec.terrainMode !== "pro") {
+      throw new Error('PixelLab terrain: a 64px tile needs terrainMode: "pro"');
+    }
+    if (spec.terrainShapeStyle && spec.terrainTransitionSize != null && spec.terrainTransitionSize > 0.5) {
+      throw new Error(
+        "PixelLab terrain: terrainShapeStyle with terrainTransitionSize above 0.5 uses an extended 32-tile layout pixelkiln does not model; use 0, 0.25, or 0.5"
+      );
+    }
+    if (!spec.terrainShapeStyle && spec.terrainTransitionSize != null && ![0, 0.25, 0.5, 1].includes(spec.terrainTransitionSize)) {
+      throw new Error(
+        "PixelLab terrain: terrainTransitionSize must be 0, 0.25, 0.5, or 1 unless terrainShapeStyle is set"
+      );
+    }
+  }
+  /**
+   * `/create-tileset-sidescroller` takes a platform, its top layer, and the
+   * layer's height, and nothing of the top-down endpoint's mode, camera, or
+   * shape controls; sending one would be silently dropped, so it is refused.
+   */
+  validateSidescrollerTerrain(spec) {
+    const topDownOnly = {
+      terrainMode: spec.terrainMode,
+      terrainShapeStyle: spec.terrainShapeStyle,
+      terrainView: spec.terrainView,
+      terrainSpreadX: spec.terrainSpreadX,
+      terrainSlopeSize: spec.terrainSlopeSize,
+      terrainRaggedness: spec.terrainRaggedness,
+      terrainRoundness: spec.terrainRoundness,
+      terrainBoundaryAmplitude: spec.terrainBoundaryAmplitude,
+      terrainBoundarySeed: spec.terrainBoundarySeed,
+      terrainStepSlope: spec.terrainStepSlope,
+      terrainConnectDiagonals: spec.terrainConnectDiagonals
+    };
+    const set = Object.entries(topDownOnly).filter(([, value]) => value != null).map(([field]) => field);
+    if (set.length) {
+      throw new Error(`PixelLab terrain: a sidescroller set takes no ${set.join(", ")}; those are top-down controls`);
+    }
+    if (spec.terrainTileSize !== 16 && spec.terrainTileSize !== 32) {
+      throw new Error(`PixelLab terrain: a sidescroller set's tiles are 16 or 32px, got ${spec.terrainTileSize}`);
+    }
+    if (spec.terrainTransitionSize != null && ![0, 0.25, 0.5, 1].includes(spec.terrainTransitionSize)) {
+      throw new Error("PixelLab terrain: a sidescroller set's terrainTransitionSize must be 0, 0.25, 0.5, or 1");
+    }
+    if (spec.terrainConnect?.upper) {
+      throw new Error(
+        "PixelLab terrain: a sidescroller set's upper terrain is empty air; only its lower (platform) terrain can connect"
+      );
+    }
+    const link = spec.terrainConnect?.lower;
+    if (link?.terrain === "upper") {
+      throw new Error(
+        `PixelLab terrain: ${link.assetId}'s upper terrain is empty air; connect to its lower (platform) terrain`
+      );
+    }
+  }
   validateCharacter(spec, styleImages = []) {
     const character = spec.character;
     if (!character) throw new Error(`${spec.styleId}/${spec.assetId} has no character shape`);
@@ -4970,7 +5915,7 @@ var PixelLabProvider = class _PixelLabProvider {
         }
       }
       if (endFrame) {
-        const start = startFrame ?? (character.parentFile && (0, import_node_fs3.existsSync)(character.parentFile) ? imageMetadata((0, import_node_fs3.readFileSync)(character.parentFile)) : null);
+        const start = startFrame ?? (character.parentFile && (0, import_node_fs4.existsSync)(character.parentFile) ? imageMetadata((0, import_node_fs4.readFileSync)(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`
@@ -5128,7 +6073,7 @@ var PixelLabProvider = class _PixelLabProvider {
         }
       }
       if (endFrame) {
-        const start = startFrame ?? (object.parentFile && (0, import_node_fs3.existsSync)(object.parentFile) ? imageMetadata((0, import_node_fs3.readFileSync)(object.parentFile)) : null);
+        const start = startFrame ?? (object.parentFile && (0, import_node_fs4.existsSync)(object.parentFile) ? imageMetadata((0, import_node_fs4.readFileSync)(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`
@@ -5183,13 +6128,13 @@ var PixelLabProvider = class _PixelLabProvider {
         );
       }
       const frames = parentOutputs.slice(0, 16).map((output) => {
-        const bytes = (0, import_node_fs3.readFileSync)(output.path);
+        const bytes = (0, import_node_fs4.readFileSync)(output.path);
         const dims = imageMetadata(bytes);
         if (!dims) throw new Error(`${spec.styleId}/${spec.assetId}: outfit source frame is not a readable PNG: ${output.path}`);
         return { base64: bytes.toString("base64"), format: "png", width: dims.width, height: dims.height };
       });
       const outfit = character.outfit;
-      const referenceBytes = (0, import_node_fs3.readFileSync)(outfit.reference.path);
+      const referenceBytes = (0, import_node_fs4.readFileSync)(outfit.reference.path);
       if (sha256(referenceBytes) !== outfit.reference.sha256) {
         throw new Error(`${spec.styleId}/${spec.assetId}: outfit reference changed after the manifest was resolved: ${outfit.reference.path}`);
       }
@@ -5232,7 +6177,7 @@ var PixelLabProvider = class _PixelLabProvider {
     }
     if (character.kind === "portrait") {
       const parentFile = character.parentFile;
-      const bytes = (0, import_node_fs3.readFileSync)(parentFile);
+      const bytes = (0, import_node_fs4.readFileSync)(parentFile);
       if (character.parentSha256 && sha256(bytes) !== character.parentSha256) {
         throw new Error(`${spec.styleId}/${spec.assetId}: portrait source changed after the manifest was resolved: ${parentFile}`);
       }
@@ -5438,8 +6383,8 @@ 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 = import_node_path2.default.join(dir, `${jobId}-${index}.png`);
-      (0, import_node_fs3.writeFileSync)(file, Buffer.from(image.base64, "base64"));
+      const file = import_node_path3.default.join(dir, `${jobId}-${index}.png`);
+      (0, import_node_fs4.writeFileSync)(file, Buffer.from(image.base64, "base64"));
       return { url: `file://${file}`, ...role ? { role } : {} };
     });
     return {
@@ -5644,7 +6589,7 @@ var PixelLabProvider = class _PixelLabProvider {
         seed: spec.seed
       });
       const jobId = (0, import_node_crypto2.randomUUID)();
-      (0, import_node_fs3.writeFileSync)(import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), png);
+      (0, import_node_fs4.writeFileSync)(import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), png);
       return { jobId };
     }
     if (spec.generator === "tiles") {
@@ -5673,17 +6618,46 @@ var PixelLabProvider = class _PixelLabProvider {
       });
       return { jobId: res2.tile_id, metadata: { backgroundJobId: res2.background_job_id } };
     }
+    if (spec.generator === "terrain" && spec.terrainOrientation === "sidescroller") {
+      const baseTileIds = await this.terrainBaseTileIds(context?.terrainLinks);
+      const res2 = await this.client.createTilesetSidescroller({
+        lowerDescription: spec.terrainLowerDescription,
+        transitionDescription: spec.terrainTransitionDescription,
+        lowerBaseTileId: baseTileIds.lower,
+        tileSize: spec.terrainTileSize,
+        transitionSize: spec.terrainTransitionSize,
+        outline: spec.outline,
+        shading: spec.shading,
+        detail: spec.detail,
+        seed: spec.seed
+      });
+      return {
+        jobId: res2.tileset_id,
+        metadata: {
+          backgroundJobId: res2.background_job_id,
+          ...Object.keys(baseTileIds).length ? { baseTileIds } : {}
+        }
+      };
+    }
     if (spec.generator === "terrain") {
+      const baseTileIds = await this.terrainBaseTileIds(context?.terrainLinks);
       const res2 = await this.client.createTileset({
         lowerDescription: spec.terrainLowerDescription,
         upperDescription: spec.terrainUpperDescription,
         transitionDescription: spec.terrainTransitionDescription,
+        lowerBaseTileId: baseTileIds.lower,
+        upperBaseTileId: baseTileIds.upper,
         tileSize: spec.terrainTileSize,
         mode: spec.terrainMode,
         shapeStyle: spec.terrainShapeStyle,
         spreadX: spec.terrainSpreadX,
         slopeSize: spec.terrainSlopeSize,
         raggedness: spec.terrainRaggedness,
+        roundness: spec.terrainRoundness,
+        boundaryAmplitude: spec.terrainBoundaryAmplitude,
+        boundarySeed: spec.terrainBoundarySeed,
+        stepSlope: spec.terrainStepSlope,
+        connectDiagonals: spec.terrainConnectDiagonals,
         transitionSize: spec.terrainTransitionSize,
         view: spec.terrainView,
         outline: spec.outline,
@@ -5691,7 +6665,13 @@ var PixelLabProvider = class _PixelLabProvider {
         detail: spec.detail,
         seed: spec.seed
       });
-      return { jobId: res2.tileset_id, metadata: { backgroundJobId: res2.background_job_id } };
+      return {
+        jobId: res2.tileset_id,
+        metadata: {
+          backgroundJobId: res2.background_job_id,
+          ...Object.keys(baseTileIds).length ? { baseTileIds } : {}
+        }
+      };
     }
     if (spec.generator === "isometricTile") {
       const res2 = await this.client.createIsometricTile({
@@ -5713,7 +6693,8 @@ var PixelLabProvider = class _PixelLabProvider {
         width: spec.width,
         height: spec.height,
         noBackground: spec.noBackground,
-        seed: spec.seed
+        seed: spec.seed,
+        targetPalette: { colors: spec.palette, name: spec.paletteName, maxColors: spec.maxColors }
       });
       return { jobId: res2.background_job_id };
     }
@@ -5764,7 +6745,7 @@ var PixelLabProvider = class _PixelLabProvider {
     }
     const sourceFiles = revision.sourceMembers ?? [{ file: revision.sourceFile, sha256: revision.sourceSha256, format: revision.sourceFormat }];
     const images = sourceFiles.map((member) => {
-      const bytes = (0, import_node_fs3.readFileSync)(member.file);
+      const bytes = (0, import_node_fs4.readFileSync)(member.file);
       if (sha256(bytes) !== member.sha256) {
         throw new Error(`${spec.styleId}/${spec.assetId}: revision source changed after the manifest was resolved`);
       }
@@ -5779,7 +6760,7 @@ var PixelLabProvider = class _PixelLabProvider {
         if (!revision.maskFile || !revision.maskSha256 || !revision.maskFormat) {
           throw new Error(`${spec.styleId}/${spec.assetId}: revision mask is not ready`);
         }
-        const maskBytes = (0, import_node_fs3.readFileSync)(revision.maskFile);
+        const maskBytes = (0, import_node_fs4.readFileSync)(revision.maskFile);
         if (sha256(maskBytes) !== revision.maskSha256) {
           throw new Error(`${spec.styleId}/${spec.assetId}: revision mask changed after the manifest was resolved`);
         }
@@ -5804,7 +6785,7 @@ var PixelLabProvider = class _PixelLabProvider {
       if (!revision.maskFile || !revision.maskSha256 || !revision.maskFormat) {
         throw new Error(`${spec.styleId}/${spec.assetId}: revision mask is not ready`);
       }
-      const maskBytes = (0, import_node_fs3.readFileSync)(revision.maskFile);
+      const maskBytes = (0, import_node_fs4.readFileSync)(revision.maskFile);
       if (sha256(maskBytes) !== revision.maskSha256) {
         throw new Error(`${spec.styleId}/${spec.assetId}: revision mask changed after the manifest was resolved`);
       }
@@ -5825,7 +6806,7 @@ var PixelLabProvider = class _PixelLabProvider {
         if (!revision.paletteImageSha256 || !revision.paletteImageFormat) {
           throw new Error(`${spec.styleId}/${spec.assetId}: revision palette image is not ready`);
         }
-        const paletteBytes = (0, import_node_fs3.readFileSync)(revision.paletteImageFile);
+        const paletteBytes = (0, import_node_fs4.readFileSync)(revision.paletteImageFile);
         if (sha256(paletteBytes) !== revision.paletteImageSha256) {
           throw new Error(`${spec.styleId}/${spec.assetId}: revision palette image changed after the manifest was resolved`);
         }
@@ -5856,6 +6837,14 @@ var PixelLabProvider = class _PixelLabProvider {
       });
       return this.cacheCleanupResult([res2.png], res2.usage, roles, revision.sourceFps);
     }
+    if (revision.mode === "normal-map") {
+      const strip = roles ? { base64: joinStripPng(images.map((member) => Buffer.from(member.base64, "base64"))).toString("base64"), format: "png" } : image;
+      const res2 = await this.client.normalMap({ image: strip, frames: roles?.length ?? 1, convention: revision.convention });
+      return {
+        jobId: res2.background_job_id,
+        metadata: roles ? { revisionMembers: roles, ...revision.sourceFps != null ? { revisionFps: revision.sourceFps } : {} } : {}
+      };
+    }
     if (revision.mode === "interpolate") {
       const lastFrame = this.readLastFrame(spec);
       if (!lastFrame) throw new Error(`${spec.styleId}/${spec.assetId}: interpolate needs lastFrame, the ending keyframe`);
@@ -5916,7 +6905,7 @@ var PixelLabProvider = class _PixelLabProvider {
       if (!revision.keypointsFile || !revision.keypointsSha256 || !revision.skeleton) {
         throw new Error(`${spec.styleId}/${spec.assetId}: revision keypoints are not ready`);
       }
-      const keypointsBytes = (0, import_node_fs3.readFileSync)(revision.keypointsFile);
+      const keypointsBytes = (0, import_node_fs4.readFileSync)(revision.keypointsFile);
       if (sha256(keypointsBytes) !== revision.keypointsSha256) {
         throw new Error(`${spec.styleId}/${spec.assetId}: revision keypoints changed after the manifest was resolved`);
       }
@@ -5958,7 +6947,7 @@ var PixelLabProvider = class _PixelLabProvider {
     if (!revision.lastFrameSha256 || !revision.lastFrameFormat) {
       throw new Error(`${spec.styleId}/${spec.assetId}: revision last frame is not ready`);
     }
-    const bytes = (0, import_node_fs3.readFileSync)(revision.lastFrameFile);
+    const bytes = (0, import_node_fs4.readFileSync)(revision.lastFrameFile);
     if (sha256(bytes) !== revision.lastFrameSha256) {
       throw new Error(`${spec.styleId}/${spec.assetId}: revision last frame changed after the manifest was resolved`);
     }
@@ -5973,11 +6962,11 @@ var PixelLabProvider = class _PixelLabProvider {
   cacheCleanupResult(pngs, usage, roles, fps) {
     const jobId = (0, import_node_crypto2.randomUUID)();
     if (!roles) {
-      (0, import_node_fs3.writeFileSync)(import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), pngs[0]);
+      (0, import_node_fs4.writeFileSync)(import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), pngs[0]);
       return { jobId, metadata: { revisionUsage: usage } };
     }
     for (const [index, png] of pngs.entries()) {
-      (0, import_node_fs3.writeFileSync)(import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`), png);
+      (0, import_node_fs4.writeFileSync)(import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`), png);
     }
     return { jobId, metadata: { revisionUsage: usage, revisionMembers: roles, ...fps != null ? { revisionFps: fps } : {} } };
   }
@@ -6001,6 +6990,7 @@ var PixelLabProvider = class _PixelLabProvider {
     if (revisionMode === "reduce-colors" || revisionMode === "correct-pixelart" || revisionMode === "remove-background") {
       return this.pollCachedRevision(jobId, context);
     }
+    if (revisionMode === "normal-map") return this.pollNormalMap(jobId, context);
     if (revisionMode === "animate" || revisionMode === "animate-pixminimax" || revisionMode === "animate-skeleton" || revisionMode === "interpolate" || revisionMode === "edit-animation") {
       return this.pollAnimateRevision(jobId, context);
     }
@@ -6008,8 +6998,8 @@ var PixelLabProvider = class _PixelLabProvider {
     if (generator === "vfx") return this.pollVfx(jobId, context);
     if (generator === "imageProFlash") return this.pollRevision(jobId);
     if (generator === "pixflux") {
-      const file = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
-      if ((0, import_node_fs3.existsSync)(file)) {
+      const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+      if ((0, import_node_fs4.existsSync)(file)) {
         const sourceUrl = `file://${file}`;
         return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }] };
       }
@@ -6065,14 +7055,15 @@ var PixelLabProvider = class _PixelLabProvider {
    */
   async submitVfx(spec, context) {
     const vfx = spec.vfx;
+    if (vfx.description) return this.submitVfxArtist(spec, context);
     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 (!(0, import_node_fs3.existsSync)(file)) throw new Error(`vfx sprite does not exist yet: ${file}`);
-      const bytes = (0, import_node_fs3.readFileSync)(file);
+      if (!(0, import_node_fs4.existsSync)(file)) throw new Error(`vfx sprite does not exist yet: ${file}`);
+      const bytes = (0, import_node_fs4.readFileSync)(file);
       if (sha256(bytes) !== vfx.sprite.sha256) {
         throw new Error(`vfx sprite changed after the manifest was resolved: ${file}; run the command again`);
       }
@@ -6119,50 +7110,137 @@ var PixelLabProvider = class _PixelLabProvider {
       // 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);
+    await this.cacheVfxFrames(jobId, exported, workbenchVfxUrls(exported));
     return { jobId, metadata: { vfx: { ...facts(exported, name), recipe } } };
   }
+  /**
+   * Ask PixelLab's VFX artist (`POST /vfx`) for a `vfx` description: a
+   * plain background job, polled by `pollVfxArtist`. Every submission is a
+   * new effect. The manifest's description is the whole effect, not a change
+   * to an earlier one, so it is never sent with `effect_id`; the effect this
+   * asset made last time stays in My effects and its id is recorded here.
+   */
+  async submitVfxArtist(spec, context) {
+    const vfx = spec.vfx;
+    let sprite;
+    if (vfx.sprite && "reference" in vfx.sprite) {
+      throw new Error("PixelLab's VFX artist takes a sprite's pixels, not a PixelLab reference; point vfx.sprite at a PNG file");
+    } else if (vfx.sprite) {
+      const { file } = vfx.sprite;
+      if (!(0, import_node_fs4.existsSync)(file)) throw new Error(`vfx sprite does not exist yet: ${file}`);
+      const bytes = (0, import_node_fs4.readFileSync)(file);
+      if (sha256(bytes) !== vfx.sprite.sha256) {
+        throw new Error(`vfx sprite changed after the manifest was resolved: ${file}; run the command again`);
+      }
+      sprite = vfxArtistSprite(bytes, `vfx sprite ${file}`).image;
+    }
+    const previous = context?.replacedMetadata?.vfx ?? context?.lastGenerationMetadata?.vfx;
+    const artist = vfx.artist ?? "lite";
+    const submitted = await this.client.createVfx({ description: vfx.description, artist, sprite, name: vfx.name });
+    return {
+      jobId: submitted.background_job_id,
+      metadata: {
+        vfx: {
+          artist,
+          quotedGenerations: submitted.quoted_generations ?? null,
+          ...typeof previous?.effectId === "string" ? { previousEffect: previous.effectId } : {}
+        }
+      }
+    };
+  }
   /** 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);
+  async cacheVfxFrames(jobId, facts, urls, atlas) {
+    const sheet = await this.client.download(urls.sheet);
+    const frameAtlas = atlas ?? (urls.atlas ? JSON.parse((await this.client.download(urls.atlas)).toString("utf8")) : void 0);
+    const frames = sliceVfxSheet(sheet, facts, frameAtlas);
     const dir = _PixelLabProvider.cacheDir("vfx");
-    frames.forEach((frame, index) => (0, import_node_fs3.writeFileSync)(import_node_path2.default.join(dir, `${jobId}-${index}.png`), frame));
-    (0, import_node_fs3.writeFileSync)(
-      import_node_path2.default.join(dir, `${jobId}.json`),
-      JSON.stringify({ effectId: exported.effectId, count: frames.length, fps: exported.fps, loop: exported.loop })
+    frames.forEach((frame, index) => (0, import_node_fs4.writeFileSync)(import_node_path3.default.join(dir, `${jobId}-${index}.png`), frame));
+    (0, import_node_fs4.writeFileSync)(
+      import_node_path3.default.join(dir, `${jobId}.json`),
+      JSON.stringify({ effectId: facts.effectId, count: frames.length, fps: facts.fps, loop: facts.loop })
     );
   }
   async pollVfx(jobId, context) {
     const dir = _PixelLabProvider.cacheDir("vfx");
-    const sidecar = import_node_path2.default.join(dir, `${jobId}.json`);
+    const sidecar = import_node_path3.default.join(dir, `${jobId}.json`);
     const cached = () => {
-      if (!(0, import_node_fs3.existsSync)(sidecar)) return null;
-      const facts2 = JSON.parse((0, import_node_fs3.readFileSync)(sidecar, "utf8"));
-      const files2 = Array.from({ length: facts2.count }, (_, index) => import_node_path2.default.join(dir, `${jobId}-${index}.png`));
-      return files2.every((file) => (0, import_node_fs3.existsSync)(file)) ? { facts: facts2, files: files2 } : null;
+      if (!(0, import_node_fs4.existsSync)(sidecar)) return null;
+      const facts2 = JSON.parse((0, import_node_fs4.readFileSync)(sidecar, "utf8"));
+      const files2 = Array.from({ length: facts2.count }, (_, index) => import_node_path3.default.join(dir, `${jobId}-${index}.png`));
+      return files2.every((file) => (0, import_node_fs4.existsSync)(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);
+    let artistDone;
+    if (!found && recorded?.artist) {
+      if (recorded.fileUrls?.sheet && recorded.effectId) {
+        await this.cacheVfxFrames(jobId, recorded, {
+          sheet: recorded.fileUrls.sheet,
+          atlas: recorded.fileUrls.atlas
+        });
+      } else {
+        const job = await this.client.getBackgroundJob(jobId);
+        if (job.status === "failed") return { status: "failed", error: `vfx job failed upstream${vfxJobFailure(job.last_response)}` };
+        if (job.status !== "completed") return { status: "processing" };
+        try {
+          artistDone = await this.cacheVfxArtistResult(jobId, job.last_response ?? {}, recorded);
+        } catch (error) {
+          return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+        }
+        artistDone.billed = billedFromUsage(job.usage);
+      }
+      found = cached();
+    } else if (!found && recorded?.downloadBase && Array.isArray(recorded.files)) {
+      const exported = recorded;
+      await this.cacheVfxFrames(jobId, exported, workbenchVfxUrls(exported));
       found = cached();
     }
     if (!found) {
-      return { status: "failed", error: "vfx frames are no longer cached locally; re-run submit for this asset (free)" };
+      return {
+        status: "failed",
+        error: recorded?.artist ? "vfx frames are no longer cached locally and their download links were not recorded; re-run submit for this asset (paid)" : "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")}` }));
+    const metadata = {
+      ...files.length > 1 ? { frameSet: { fps: facts.fps, count: files.length, loop: facts.loop } } : {},
+      ...artistDone ? { vfx: artistDone.vfx } : {}
+    };
     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 } } } : {},
+      ...Object.keys(metadata).length ? { metadata } : {},
+      billed: artistDone?.billed ?? null
+    };
+  }
+  /**
+   * A delivered VFX artist job: cut its sheet into the cache and return the
+   * effect's facts, merged over what submit recorded (poll replaces the
+   * whole `vfx` key). Download links are kept only when they carry no
+   * credential, so a committed lockfile never holds a signed URL.
+   */
+  async cacheVfxArtistResult(jobId, done, recorded) {
+    const result = parseVfxArtistResult(done, jobId);
+    const atlas = result.atlas ? JSON.parse((await this.client.download(result.atlas.url)).toString("utf8")) : void 0;
+    const size = vfxArtistFrameFacts(result, atlas);
+    const facts = { effectId: result.effectId, ...size, fps: result.fps ?? 12, loop: result.loop ?? false };
+    await this.cacheVfxFrames(jobId, facts, { sheet: result.sheet.url }, atlas);
+    const urls = [result.sheet.url, ...result.atlas ? [result.atlas.url] : []];
+    return {
+      vfx: {
+        ...recorded,
+        ...facts,
+        editUrl: result.editUrl,
+        name: result.name,
+        message: result.message,
+        anchor: result.anchor,
+        parts: result.parts,
+        files: result.files.map((file) => file.name),
+        ...urls.every(shouldPersistSourceUrl) ? { fileUrls: { sheet: result.sheet.url, ...result.atlas ? { atlas: result.atlas.url } : {} } } : {}
+      },
       billed: null
     };
   }
@@ -6175,10 +7253,10 @@ var PixelLabProvider = class _PixelLabProvider {
     };
     if (Array.isArray(roles) && roles.length) {
       const sources = roles.map((role, index) => ({
-        url: `file://${import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`)}`,
+        url: `file://${import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`)}`,
         role: String(role)
       }));
-      if (sources.some((source) => !(0, import_node_fs3.existsSync)(source.url.slice("file://".length)))) return gone;
+      if (sources.some((source) => !(0, import_node_fs4.existsSync)(source.url.slice("file://".length)))) return gone;
       const fps = context?.metadata?.revisionFps;
       const frames = sources.every((source) => source.role.startsWith("frame-"));
       return {
@@ -6190,11 +7268,58 @@ var PixelLabProvider = class _PixelLabProvider {
         billed: billedFromUsage(usage)
       };
     }
-    const file = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
-    if (!(0, import_node_fs3.existsSync)(file)) return gone;
+    const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+    if (!(0, import_node_fs4.existsSync)(file)) return gone;
     const sourceUrl = `file://${file}`;
     return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed: billedFromUsage(usage) };
   }
+  /**
+   * A `normal-map` revision: a background job whose map is
+   * `last_response.image`. A loop's map comes back as the strip it was sent
+   * as, and is cut into one file per frame under the parent's roles. Nothing
+   * downstream palette-snaps it: the manifest refuses a normal map in a
+   * style with `enforcePalette` or `quality`.
+   */
+  async pollNormalMap(jobId, context) {
+    const job = await this.client.getBackgroundJob(jobId);
+    if (job.status === "failed") return { status: "failed", error: "normal-map job failed upstream" };
+    if (job.status !== "completed") return { status: "processing" };
+    const billed = billedFromUsage(job.usage);
+    const png = normalMapResultPng(job.last_response);
+    if (!png) {
+      return {
+        status: "failed",
+        error: `Invalid PixelLab response for normal-map job ${jobId}: completed with no image at last_response.image (got: ${Object.keys(job.last_response ?? {}).join(", ") || "no keys"})`
+      };
+    }
+    const roles = context?.metadata?.revisionMembers;
+    if (Array.isArray(roles) && roles.length) {
+      let frames;
+      try {
+        frames = splitStripPng(png, roles.length);
+      } catch (error) {
+        return { status: "failed", error: `normal-map job ${jobId}: ${error.message}` };
+      }
+      const sources = frames.map((frame, index) => {
+        const file2 = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+        (0, import_node_fs4.writeFileSync)(file2, frame);
+        return { url: `file://${file2}`, role: String(roles[index]) };
+      });
+      const fps = context?.metadata?.revisionFps;
+      return {
+        status: "ready",
+        objectId: jobId,
+        sourceUrl: sources[0].url,
+        sources,
+        ...typeof fps === "number" ? { metadata: { frameSet: { fps, count: sources.length } } } : {},
+        billed
+      };
+    }
+    const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+    (0, import_node_fs4.writeFileSync)(file, png);
+    const sourceUrl = `file://${file}`;
+    return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed };
+  }
   /**
    * `animate`/`animate-pixminimax` revisions: a plain background job, like
    * `pollRevision` above, but completing with an ORDERED FRAME LIST instead
@@ -6247,8 +7372,8 @@ var PixelLabProvider = class _PixelLabProvider {
         }
         const base64 = extractBase64(item);
         if (base64) {
-          const file = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
-          (0, import_node_fs3.writeFileSync)(file, Buffer.from(base64, "base64"));
+          const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+          (0, import_node_fs4.writeFileSync)(file, Buffer.from(base64, "base64"));
           urls.push(`file://${file}`);
           continue;
         }
@@ -6298,8 +7423,8 @@ var PixelLabProvider = class _PixelLabProvider {
       const candidate = done[key];
       const base64 = extractBase64(candidate);
       if (base64) {
-        const file = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
-        (0, import_node_fs3.writeFileSync)(file, Buffer.from(base64, "base64"));
+        const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+        (0, import_node_fs4.writeFileSync)(file, Buffer.from(base64, "base64"));
         const sourceUrl = `file://${file}`;
         return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed };
       }
@@ -6307,8 +7432,8 @@ var PixelLabProvider = class _PixelLabProvider {
     if (Array.isArray(done.images) && done.images.length) {
       const base64 = extractBase64(done.images[0]);
       if (base64) {
-        const file = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
-        (0, import_node_fs3.writeFileSync)(file, Buffer.from(base64, "base64"));
+        const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+        (0, import_node_fs4.writeFileSync)(file, Buffer.from(base64, "base64"));
         const sourceUrl = `file://${file}`;
         return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed };
       }
@@ -6341,8 +7466,8 @@ var PixelLabProvider = class _PixelLabProvider {
       for (const [index, candidate] of done.images.entries()) {
         const base64 = extractBase64(candidate);
         if (!base64) continue;
-        const file = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
-        (0, import_node_fs3.writeFileSync)(file, Buffer.from(base64, "base64"));
+        const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+        (0, import_node_fs4.writeFileSync)(file, Buffer.from(base64, "base64"));
         urls.push(`file://${file}`);
       }
       if (urls.length) return { status: "review", candidateUrls: urls, billed };
@@ -6371,8 +7496,8 @@ var PixelLabProvider = class _PixelLabProvider {
     for (const [index, candidate] of images.entries()) {
       const base64 = extractBase64(candidate);
       if (!base64) continue;
-      const file = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
-      (0, import_node_fs3.writeFileSync)(file, Buffer.from(base64, "base64"));
+      const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+      (0, import_node_fs4.writeFileSync)(file, Buffer.from(base64, "base64"));
       urls.push(`file://${file}`);
     }
     if (urls.length === 1) return { status: "ready", objectId: jobId, sourceUrl: urls[0], sources: [{ url: urls[0] }], billed };
@@ -6450,6 +7575,26 @@ var PixelLabProvider = class _PixelLabProvider {
       throw err;
     }
   }
+  /**
+   * The base tile id of each terrain a connected set shares: the other
+   * set's recorded `terrainIds`, or, for a set downloaded before pixelkiln
+   * recorded them, read from PixelLab's own record of it (a free GET).
+   */
+  async terrainBaseTileIds(links) {
+    const ids = {};
+    for (const side of ["lower", "upper"]) {
+      const link = links?.[side];
+      if (!link) continue;
+      const id = link.terrainId ?? (await this.client.getTileset(link.objectId)).metadata.terrainIds[link.terrain];
+      if (!id) {
+        throw new Error(
+          `PixelLab terrain: tileset ${link.objectId} has no ${link.terrain} terrain id to connect this set's ${side} terrain to`
+        );
+      }
+      ids[side] = id;
+    }
+    return ids;
+  }
   /**
    * `/create-tileset` reports progress the same way `tiles` does (423 while
    * drawing, 200 once finished), but each tile's image comes back embedded
@@ -6461,7 +7606,8 @@ var PixelLabProvider = class _PixelLabProvider {
    */
   async pollTerrain(tilesetId, context) {
     try {
-      const { tileset, usage } = await this.client.getTileset(tilesetId);
+      const { tileset, usage, metadata } = await this.client.getTileset(tilesetId);
+      const sidescroller = metadata.view === "side" || context?.spec?.terrainOrientation === "sidescroller";
       const backgroundJobId = context?.metadata?.backgroundJobId;
       const billed = billedFromUsage(usage) ?? await this.billedForJob(backgroundJobId);
       const sources = [];
@@ -6469,8 +7615,8 @@ 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 = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${tilesetId}-${index}.png`);
-        (0, import_node_fs3.writeFileSync)(file, Buffer.from(tile.image.base64, "base64"));
+        const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${tilesetId}-${index}.png`);
+        (0, import_node_fs4.writeFileSync)(file, Buffer.from(tile.image.base64, "base64"));
         sources.push({ url: `file://${file}`, role });
         terrainTiles.push({ role, corners: tile.corners, pattern4x4: tile.pattern_4x4 });
       }
@@ -6479,7 +7625,13 @@ var PixelLabProvider = class _PixelLabProvider {
         objectId: tilesetId,
         sourceUrl: sources[0]?.url ?? null,
         sources,
-        metadata: { terrainTypes: tileset.terrain_types, terrainTiles },
+        metadata: {
+          terrainTypes: sidescroller ? ["lower", "upper"] : tileset.terrain_types,
+          ...sidescroller ? { providerTerrainTypes: tileset.terrain_types, view: "side" } : {},
+          terrainTiles,
+          // Each terrain's base tile id, which a connected set sends.
+          ...Object.keys(metadata.terrainIds).length ? { terrainIds: metadata.terrainIds } : {}
+        },
         billed
       };
     } catch (err) {
@@ -6499,8 +7651,8 @@ 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 = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${tileId}.png`);
-      (0, import_node_fs3.writeFileSync)(file, Buffer.from(image.base64, "base64"));
+      const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${tileId}.png`);
+      (0, import_node_fs4.writeFileSync)(file, Buffer.from(image.base64, "base64"));
       return {
         status: "ready",
         objectId: tileId,
@@ -6543,8 +7695,8 @@ var PixelLabProvider = class _PixelLabProvider {
       return { objectId: `${jobId}#${index}`, sourceUrl: url };
     }
     if (generator === "imagePro" || generator === "uiElement") {
-      const file = import_node_path2.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
-      if (!(0, import_node_fs3.existsSync)(file)) throw new Error(`${generator} job ${jobId} has no cached candidate at index ${index}`);
+      const file = import_node_path3.default.join(_PixelLabProvider.cacheDir(), `${jobId}-${index}.png`);
+      if (!(0, import_node_fs4.existsSync)(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);
@@ -6556,7 +7708,7 @@ var PixelLabProvider = class _PixelLabProvider {
     return { objectId, sourceUrl: firstUrl(obj?.rotation_urls) ?? obj?.preview_url ?? null };
   }
   async download(url) {
-    if (url.startsWith("file://")) return (0, import_node_fs3.readFileSync)(url.slice("file://".length));
+    if (url.startsWith("file://")) return (0, import_node_fs4.readFileSync)(url.slice("file://".length));
     return this.client.download(url);
   }
   async balance() {
@@ -6678,7 +7830,7 @@ function extractBase64(value) {
 function readReference(spec, reference) {
   const images = {};
   for (const [direction, image] of Object.entries(reference)) {
-    const bytes = (0, import_node_fs3.readFileSync)(image.path);
+    const bytes = (0, import_node_fs4.readFileSync)(image.path);
     if (sha256(bytes) !== image.sha256) {
       throw new Error(`${spec.styleId}/${spec.assetId}: reference (${direction}) changed after the manifest was resolved: ${image.path}`);
     }
@@ -6695,7 +7847,7 @@ function requireStyleObjectId(spec, context) {
   return context.styleObjectId;
 }
 function readPose(spec, what, image) {
-  const bytes = (0, import_node_fs3.readFileSync)(image.path);
+  const bytes = (0, import_node_fs4.readFileSync)(image.path);
   if (sha256(bytes) !== image.sha256) {
     throw new Error(`${spec.styleId}/${spec.assetId}: ${what} changed after the manifest was resolved: ${image.path}`);
   }
@@ -6760,7 +7912,7 @@ function findObjectAnimation(object, name, direction, animationId) {
 function mapScenePayload(spec) {
   const scene = spec.scene;
   const read = (file, hash, label) => {
-    const bytes = (0, import_node_fs3.readFileSync)(file);
+    const bytes = (0, import_node_fs4.readFileSync)(file);
     if (!hash || sha256(bytes) !== hash) {
       throw new Error(`${spec.styleId}/${spec.assetId}: ${label} changed after the manifest was resolved`);
     }
@@ -7133,9 +8285,9 @@ function retroError(value) {
 
 // src/providers/scenario.ts
 var import_node_crypto3 = require("crypto");
-var import_node_fs4 = require("fs");
+var import_node_fs5 = require("fs");
 var import_node_os2 = __toESM(require("os"), 1);
-var import_node_path3 = __toESM(require("path"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
 var DEFAULT_BASE_URL2 = "https://api.cloud.scenario.com/v1";
 var SOURCE_PROTOCOL2 = "scenario:";
 var SUBMIT_RETRIES = 8;
@@ -7518,7 +8670,7 @@ var ScenarioProvider = class _ScenarioProvider {
   }
 };
 function uploadCachePath() {
-  return process.env.SCENARIO_UPLOAD_CACHE ?? import_node_path3.default.join(import_node_os2.default.tmpdir(), "pixelkiln-scenario", "uploads.json");
+  return process.env.SCENARIO_UPLOAD_CACHE ?? import_node_path4.default.join(import_node_os2.default.tmpdir(), "pixelkiln-scenario", "uploads.json");
 }
 function uploadCacheKey(baseUrl, projectId, digest2) {
   return (0, import_node_crypto3.createHash)("sha256").update(`${baseUrl}
@@ -7527,7 +8679,7 @@ ${digest2}`).digest("hex");
 }
 function readUploadCache() {
   try {
-    const value = JSON.parse((0, import_node_fs4.readFileSync)(uploadCachePath(), "utf8"));
+    const value = JSON.parse((0, import_node_fs5.readFileSync)(uploadCachePath(), "utf8"));
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
   } catch {
     return {};
@@ -7536,10 +8688,10 @@ function readUploadCache() {
 function writeUploadCache(key, assetId) {
   try {
     const file = uploadCachePath();
-    (0, import_node_fs4.mkdirSync)(import_node_path3.default.dirname(file), { recursive: true });
+    (0, import_node_fs5.mkdirSync)(import_node_path4.default.dirname(file), { recursive: true });
     const tmp = `${file}.${process.pid}.tmp`;
-    (0, import_node_fs4.writeFileSync)(tmp, JSON.stringify({ ...readUploadCache(), [key]: assetId }));
-    (0, import_node_fs4.renameSync)(tmp, file);
+    (0, import_node_fs5.writeFileSync)(tmp, JSON.stringify({ ...readUploadCache(), [key]: assetId }));
+    (0, import_node_fs5.renameSync)(tmp, file);
   } catch {
   }
 }
@@ -7566,7 +8718,7 @@ function readRevisionSource(spec) {
   if (!revision.sourceFile || !revision.sourceSha256 || !revision.sourceFormat) {
     throw new Error(`${spec.styleId}/${spec.assetId}: revision source is not ready`);
   }
-  const bytes = (0, import_node_fs4.readFileSync)(revision.sourceFile);
+  const bytes = (0, import_node_fs5.readFileSync)(revision.sourceFile);
   if (sha256(bytes) !== revision.sourceSha256) {
     throw new Error(`${spec.styleId}/${spec.assetId}: revision source changed after the manifest was resolved`);
   }
@@ -7736,8 +8888,8 @@ function redactScenarioError(value, secrets) {
 
 // src/providers/comfyui.ts
 var import_node_crypto4 = require("crypto");
-var import_promises2 = require("fs/promises");
-var import_node_path4 = __toESM(require("path"), 1);
+var import_promises3 = require("fs/promises");
+var import_node_path5 = __toESM(require("path"), 1);
 var DEFAULT_BASE_URL3 = "http://127.0.0.1:8188";
 var BUILTIN_BINDINGS = /* @__PURE__ */ new Set([
   "prompt",
@@ -7874,10 +9026,10 @@ var ComfyUIProvider = class _ComfyUIProvider {
   }
   async resolveOptions(value, context) {
     const options = parseOptions(value);
-    const workflowPath = import_node_path4.default.resolve(context.root, options.workflowFile);
+    const workflowPath = import_node_path5.default.resolve(context.root, options.workflowFile);
     let raw;
     try {
-      raw = await (0, import_promises2.readFile)(workflowPath, "utf8");
+      raw = await (0, import_promises3.readFile)(workflowPath, "utf8");
     } catch (err) {
       throw new Error(
         `ComfyUI workflow for style "${context.styleId}" could not be read at ${workflowPath}: ${err instanceof Error ? err.message : String(err)}`
@@ -7929,10 +9081,10 @@ var ComfyUIProvider = class _ComfyUIProvider {
           if (typeof item !== "string") {
             throw new Error(`ComfyUI ${label} must be a manifest-relative PNG or JPEG path`);
           }
-          const file = import_node_path4.default.resolve(context.root, item);
+          const file = import_node_path5.default.resolve(context.root, item);
           let bytes;
           try {
-            bytes = await (0, import_promises2.readFile)(file);
+            bytes = await (0, import_promises3.readFile)(file);
           } catch (error) {
             throw new Error(
               `ComfyUI ${label} could not be read at ${file}: ${error instanceof Error ? error.message : String(error)}`
@@ -8067,6 +9219,11 @@ var ComfyUIProvider = class _ComfyUIProvider {
           "ComfyUI has no binding for numColors/paletteImage/dithering \u2014 those are PixelLab's /reduce-colors parameters. A reduce-colors revision on ComfyUI is whatever your own workflow does with bindings.sourceImage; write that behavior into the graph directly."
         );
       }
+      if (spec.revision.convention) {
+        throw new Error(
+          "ComfyUI has no binding for convention \u2014 that is PixelLab's /normal-map parameter. A normal-map revision on ComfyUI is whatever your own workflow does; build the green-channel convention into the graph."
+        );
+      }
       if ((!options.bindings.width || !options.bindings.height) && spec.revision.sourceWidth != null && spec.revision.sourceHeight != null && (spec.width !== spec.revision.sourceWidth || spec.height !== spec.revision.sourceHeight)) {
         throw new Error(
           "ComfyUI revisions without width/height bindings must keep the source dimensions"
@@ -8089,7 +9246,7 @@ var ComfyUIProvider = class _ComfyUIProvider {
         setBinding(workflow2, binding, input);
         return;
       }
-      const bytes = await (0, import_promises2.readFile)(input.path);
+      const bytes = await (0, import_promises3.readFile)(input.path);
       if (sha256(bytes) !== input.sha256) {
         throw new Error(`ComfyUI provider input "${name}" changed before upload`);
       }
@@ -8156,7 +9313,7 @@ var ComfyUIProvider = class _ComfyUIProvider {
       if (!spec.revision.sourceSha256 || !spec.revision.sourceFormat) {
         throw new Error("ComfyUI revision source is not ready");
       }
-      const sourceBytes = await (0, import_promises2.readFile)(spec.revision.sourceFile);
+      const sourceBytes = await (0, import_promises3.readFile)(spec.revision.sourceFile);
       if (sha256(sourceBytes) !== spec.revision.sourceSha256) {
         throw new Error("ComfyUI revision source changed before upload");
       }
@@ -8170,7 +9327,7 @@ var ComfyUIProvider = class _ComfyUIProvider {
         if (!spec.revision.maskSha256 || !spec.revision.maskFormat) {
           throw new Error("ComfyUI revision mask is not ready");
         }
-        const maskBytes = await (0, import_promises2.readFile)(spec.revision.maskFile);
+        const maskBytes = await (0, import_promises3.readFile)(spec.revision.maskFile);
         if (sha256(maskBytes) !== spec.revision.maskSha256) {
           throw new Error("ComfyUI revision mask changed before upload");
         }
@@ -8890,9 +10047,9 @@ registerProvider({
 });
 
 // src/manifest.ts
-var import_promises4 = require("fs/promises");
-var import_node_fs7 = require("fs");
-var import_node_path7 = __toESM(require("path"), 1);
+var import_promises5 = require("fs/promises");
+var import_node_fs8 = require("fs");
+var import_node_path8 = __toESM(require("path"), 1);
 
 // src/loop-directions.ts
 var SINGLE_OUTPUT_FIELDS = ["file", "cell", "remoteId", "source", "sourceByStyle", "outputRole"];
@@ -8980,17 +10137,17 @@ function isObject2(value) {
 }
 
 // src/outputs.ts
-var import_node_fs6 = require("fs");
-var import_node_path6 = __toESM(require("path"), 1);
+var import_node_fs7 = require("fs");
+var import_node_path7 = __toESM(require("path"), 1);
 
 // src/lock.ts
-var import_promises3 = require("fs/promises");
-var import_node_fs5 = require("fs");
-var import_node_path5 = __toESM(require("path"), 1);
+var import_promises4 = require("fs/promises");
+var import_node_fs6 = require("fs");
+var import_node_path6 = __toESM(require("path"), 1);
 async function loadLock(lockPath) {
-  if (!(0, import_node_fs5.existsSync)(lockPath)) return { version: 2, entries: {} };
+  if (!(0, import_node_fs6.existsSync)(lockPath)) return { version: 2, entries: {} };
   try {
-    return parseLock(JSON.parse(await (0, import_promises3.readFile)(lockPath, "utf8")));
+    return parseLock(JSON.parse(await (0, import_promises4.readFile)(lockPath, "utf8")));
   } catch (err) {
     throw new ProjectError(
       `Lockfile at ${lockPath} is malformed:
@@ -9003,7 +10160,7 @@ var saveQueues = /* @__PURE__ */ new Map();
 var dirtyPatches = /* @__PURE__ */ new WeakMap();
 var dirtyDeletes = /* @__PURE__ */ new WeakMap();
 function saveLock(lockPath, lock) {
-  const queueKey = import_node_path5.default.resolve(lockPath);
+  const queueKey = import_node_path6.default.resolve(lockPath);
   const previous = saveQueues.get(queueKey) ?? Promise.resolve();
   const next = previous.catch(() => {
   }).then(() => writeLockNow(lockPath, lock));
@@ -9015,7 +10172,7 @@ function saveLock(lockPath, lock) {
   return next;
 }
 async function writeLockNow(lockPath, lock) {
-  await (0, import_promises3.mkdir)(import_node_path5.default.dirname(import_node_path5.default.resolve(lockPath)), { recursive: true });
+  await (0, import_promises4.mkdir)(import_node_path6.default.dirname(import_node_path6.default.resolve(lockPath)), { recursive: true });
   const release = await acquireFileLock(lockPath);
   try {
     await writeLockWhileHeld(lockPath, lock);
@@ -9025,9 +10182,9 @@ async function writeLockNow(lockPath, lock) {
 }
 async function writeLockWhileHeld(file, lock) {
   let disk = { version: 2, entries: {} };
-  if ((0, import_node_fs5.existsSync)(file)) {
+  if ((0, import_node_fs6.existsSync)(file)) {
     try {
-      disk = parseLock(JSON.parse(await (0, import_promises3.readFile)(file, "utf8")));
+      disk = parseLock(JSON.parse(await (0, import_promises4.readFile)(file, "utf8")));
     } catch (err) {
       throw new ProjectError(
         `Refusing to overwrite malformed lockfile at ${file}: ${err instanceof Error ? err.message : String(err)}`,
@@ -9056,10 +10213,10 @@ async function writeLockWhileHeld(file, lock) {
   }
   const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
-    await (0, import_promises3.writeFile)(tmp, JSON.stringify({ version: 2, entries: sorted }, null, 2) + "\n");
-    await (0, import_promises3.rename)(tmp, file);
+    await (0, import_promises4.writeFile)(tmp, JSON.stringify({ version: 2, entries: sorted }, null, 2) + "\n");
+    await (0, import_promises4.rename)(tmp, file);
   } finally {
-    await (0, import_promises3.rm)(tmp, { force: true });
+    await (0, import_promises4.rm)(tmp, { force: true });
   }
   const currentDirty = dirtyPatches.get(lock);
   if (currentDirty) {
@@ -9122,18 +10279,18 @@ async function acquireFileLock(file) {
   const deadline = Date.now() + FILE_LOCK_TIMEOUT_MS;
   for (; ; ) {
     try {
-      await (0, import_promises3.mkdir)(lockDir);
+      await (0, import_promises4.mkdir)(lockDir);
       return async () => {
-        await (0, import_promises3.rmdir)(lockDir).catch(() => {
+        await (0, import_promises4.rmdir)(lockDir).catch(() => {
         });
       };
     } catch (err) {
       const code = err.code;
       if (code !== "EEXIST") throw err;
       try {
-        const age = Date.now() - (await (0, import_promises3.stat)(lockDir)).mtimeMs;
+        const age = Date.now() - (await (0, import_promises4.stat)(lockDir)).mtimeMs;
         if (age > STALE_FILE_LOCK_MS) {
-          await (0, import_promises3.rmdir)(lockDir);
+          await (0, import_promises4.rmdir)(lockDir);
           continue;
         }
       } catch (lockErr) {
@@ -9160,22 +10317,22 @@ function totalSpend(lock, unit = "generations") {
 
 // src/outputs.ts
 function portableOutputPath(file, manifestDir) {
-  const root = import_node_path6.default.resolve(manifestDir);
-  const absolute = import_node_path6.default.isAbsolute(file) ? import_node_path6.default.normalize(file) : import_node_path6.default.resolve(root, file);
-  const relative = import_node_path6.default.relative(root, absolute);
-  const value = import_node_path6.default.isAbsolute(relative) ? absolute : relative;
-  return value.split(import_node_path6.default.sep).join("/");
+  const root = import_node_path7.default.resolve(manifestDir);
+  const absolute = import_node_path7.default.isAbsolute(file) ? import_node_path7.default.normalize(file) : import_node_path7.default.resolve(root, file);
+  const relative = import_node_path7.default.relative(root, absolute);
+  const value = import_node_path7.default.isAbsolute(relative) ? absolute : relative;
+  return value.split(import_node_path7.default.sep).join("/");
 }
 function resolveOutputPath(recordedPath, manifestDir) {
-  if (import_node_path6.default.isAbsolute(recordedPath)) return import_node_path6.default.normalize(recordedPath);
-  if (import_node_path6.default.win32.isAbsolute(recordedPath)) return recordedPath;
-  return import_node_path6.default.resolve(manifestDir, recordedPath.split(/[\\/]/).join(import_node_path6.default.sep));
+  if (import_node_path7.default.isAbsolute(recordedPath)) return import_node_path7.default.normalize(recordedPath);
+  if (import_node_path7.default.win32.isAbsolute(recordedPath)) return recordedPath;
+  return import_node_path7.default.resolve(manifestDir, recordedPath.split(/[\\/]/).join(import_node_path7.default.sep));
 }
 function expectedOutputPath(spec, role, index, total, mediaType) {
   return memberPath(spec.outFile, role, index, total, mediaType);
 }
 function memberPath(file, role, index, total, mediaType) {
-  const originalExt = import_node_path6.default.extname(file);
+  const originalExt = import_node_path7.default.extname(file);
   const ext = mediaType ? mediaExtension(mediaType) : originalExt || ".png";
   const stem = originalExt ? file.slice(0, -originalExt.length) : file;
   if (total === 1) return `${stem}${ext}`;
@@ -9189,10 +10346,10 @@ function isFrameSetEntry(entry) {
   return entry.generator === "frames" && isMemberSetEntry(entry);
 }
 function sourceIsStem(source, entry, manifestDir) {
-  return isMemberSetEntry(entry) && !(0, import_node_fs6.existsSync)(import_node_path6.default.resolve(manifestDir, source));
+  return isMemberSetEntry(entry) && !(0, import_node_fs7.existsSync)(import_node_path7.default.resolve(manifestDir, source));
 }
 function sourceOutputPath(source, entry, index, manifestDir) {
-  const absolute = import_node_path6.default.resolve(manifestDir, source);
+  const absolute = import_node_path7.default.resolve(manifestDir, source);
   if (!sourceIsStem(source, entry, manifestDir)) return absolute;
   const output = entry.outputs[index];
   return memberPath(absolute, output.role, index, entry.outputs.length, output.mediaType);
@@ -9279,7 +10436,7 @@ function resolveSpecOutputs(spec, lock, manifestDir) {
     id: spec.assetId,
     index: 0,
     path: spec.outFile,
-    absolutePath: import_node_path6.default.resolve(spec.outFile),
+    absolutePath: import_node_path7.default.resolve(spec.outFile),
     sha256: ""
   }];
 }
@@ -9300,9 +10457,9 @@ function frameSetLoop(entry) {
 
 // src/manifest.ts
 async function loadManifest(manifestPath) {
-  const abs = import_node_path7.default.resolve(manifestPath);
-  if (!(0, import_node_fs7.existsSync)(abs)) throw new ProjectError(`No manifest at ${abs}`);
-  const expansion = expandLoopDirections(JSON.parse(await (0, import_promises4.readFile)(abs, "utf8")));
+  const abs = import_node_path8.default.resolve(manifestPath);
+  if (!(0, import_node_fs8.existsSync)(abs)) throw new ProjectError(`No manifest at ${abs}`);
+  const expansion = expandLoopDirections(JSON.parse(await (0, import_promises5.readFile)(abs, "utf8")));
   if (expansion.issues.length) {
     throw new ProjectError(`Manifest at ${abs} is invalid:
 ${expansion.issues.map((i) => `  ${i}`).join("\n")}`);
@@ -9399,12 +10556,38 @@ ${issues}`);
     visited.add(assetId);
   };
   for (const assetId of Object.keys(parsed.data.assets)) visitParents(assetId, []);
+  const connectVisiting = [];
+  const connectVisited = /* @__PURE__ */ new Set();
+  const visitConnections = (assetId) => {
+    if (connectVisited.has(assetId)) return;
+    const cycleStart = connectVisiting.indexOf(assetId);
+    if (cycleStart >= 0) {
+      unknownReferences.push(
+        `assets.${assetId}.connect: connection cycle ${[...connectVisiting.slice(cycleStart), assetId].join(" -> ")}`
+      );
+      return;
+    }
+    connectVisiting.push(assetId);
+    for (const [side, link] of Object.entries(parsed.data.assets[assetId]?.connect ?? {})) {
+      if (!link) continue;
+      if (!parsed.data.assets[link.of]) {
+        unknownReferences.push(`assets.${assetId}.connect.${side}.of: unknown asset "${link.of}"`);
+      } else if (link.of === assetId) {
+        unknownReferences.push(`assets.${assetId}.connect.${side}.of: a set cannot connect to itself`);
+      } else {
+        visitConnections(link.of);
+      }
+    }
+    connectVisiting.pop();
+    connectVisited.add(assetId);
+  };
+  for (const assetId of Object.keys(parsed.data.assets)) visitConnections(assetId);
   if (unknownReferences.length) {
     throw new ProjectError(`Manifest at ${abs} is invalid:
 ${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
   }
   const loopFamilies = Object.keys(expansion.families).length ? { loopFamilies: expansion.families } : {};
-  return { manifest: parsed.data, root: import_node_path7.default.dirname(abs), path: abs, ...loopFamilies };
+  return { manifest: parsed.data, root: import_node_path8.default.dirname(abs), path: abs, ...loopFamilies };
 }
 function assetInStyle(asset, styleId, style) {
   if (asset.styles.length) return asset.styles.includes(styleId);
@@ -9413,6 +10596,13 @@ function assetInStyle(asset, styleId, style) {
 function parentAssetId(asset) {
   return asset?.revision?.from ?? asset?.state?.of ?? asset?.animation?.of ?? asset?.portrait?.of ?? asset?.outfit?.of;
 }
+function dependencyAssetIds(asset) {
+  const parent = parentAssetId(asset);
+  return [
+    ...parent ? [parent] : [],
+    ...[asset?.connect?.lower?.of, asset?.connect?.upper?.of].filter((id) => Boolean(id))
+  ];
+}
 function formatManifestIssues(issues) {
   return issues.flatMap((issue) => {
     if (issue.code === "invalid_union") {
@@ -9500,11 +10690,12 @@ async function resolveSpecs(loaded, filter) {
   }
   const requestedAssetIds = new Set(assetFilter.length ? assetFilter : Object.keys(manifest.assets));
   const resolutionAssetIds = new Set(requestedAssetIds);
-  for (const assetId of [...requestedAssetIds]) {
-    let current = parentAssetId(manifest.assets[assetId]);
-    while (current && !resolutionAssetIds.has(current)) {
-      resolutionAssetIds.add(current);
-      current = parentAssetId(manifest.assets[current]);
+  const pending = [...requestedAssetIds];
+  while (pending.length) {
+    for (const dependency of dependencyAssetIds(manifest.assets[pending.pop()])) {
+      if (resolutionAssetIds.has(dependency) || !manifest.assets[dependency]) continue;
+      resolutionAssetIds.add(dependency);
+      pending.push(dependency);
     }
   }
   const styleDependencies = /* @__PURE__ */ new Map();
@@ -9542,11 +10733,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 = import_node_path7.default.resolve(root, rel);
+    const abs = import_node_path8.default.resolve(root, rel);
     let hit = styleImageCache.get(abs);
     if (!hit) {
-      if (!(0, import_node_fs7.existsSync)(abs)) throw new Error(`${what} not found: ${abs}`);
-      const buf = await (0, import_promises4.readFile)(abs);
+      if (!(0, import_node_fs8.existsSync)(abs)) throw new Error(`${what} not found: ${abs}`);
+      const buf = await (0, import_promises5.readFile)(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) {
@@ -9572,7 +10763,7 @@ async function resolveSpecs(loaded, filter) {
       styleImageDimensions.push(loadedImage);
     }
     const resolvedImages = style.styleImages.map((image) => {
-      const hit = styleImageCache.get(import_node_path7.default.resolve(root, image.path));
+      const hit = styleImageCache.get(import_node_path8.default.resolve(root, image.path));
       return { base64: hit.base64, width: hit.width, height: hit.height, format: hit.format };
     });
     const styleSpecs = /* @__PURE__ */ new Map();
@@ -9659,6 +10850,9 @@ async function resolveSpecs(loaded, filter) {
           `assets.${assetId}: ${asset.portrait ? "portrait" : "outfit"} needs a character style; "${styleId}" generates ${generator}`
         );
       }
+      if (asset.connect && generator !== "terrain") {
+        throw new Error(`assets.${assetId}: connect needs a terrain style; "${styleId}" generates ${generator}`);
+      }
       if ((asset.pieces || asset.elements) && generator !== "uiAsset") {
         throw new Error(
           `assets.${assetId}: ${asset.pieces ? "pieces" : "elements"} needs a uiAsset style; "${styleId}" generates ${generator}`
@@ -9670,7 +10864,18 @@ async function resolveSpecs(loaded, filter) {
       let terrainUpperDescription;
       let terrainTransitionDescription;
       let prompt;
-      if (generator === "terrain") {
+      if (generator === "terrain" && style.terrainOrientation === "sidescroller") {
+        const parsed = parseTerrainDescriptions(subject);
+        if (!parsed || parsed.transition) {
+          throw new Error(
+            `assets.${assetId}: a sidescroller terrain needs exactly "1). <platform body> 2). <top layer>" in its prompt (e.g. 1). stone brick texture 2). green grass texture)`
+          );
+        }
+        const wrap = (text) => [style.promptPrefix, text, style.promptSuffix].map((p) => p.trim()).filter(Boolean).join(", ");
+        terrainLowerDescription = wrap(parsed.lower);
+        terrainTransitionDescription = wrap(parsed.upper);
+        prompt = subject.trim();
+      } else if (generator === "terrain") {
         const parsed = parseTerrainDescriptions(subject);
         if (!parsed) {
           throw new Error(
@@ -9687,12 +10892,12 @@ async function resolveSpecs(loaded, filter) {
       } else {
         prompt = [style.promptPrefix, subject, style.promptSuffix].map((p) => p.trim()).filter(Boolean).join(", ");
       }
-      const relFile = asset.file ?? import_node_path7.default.join(asset.category ?? "", `${assetId}.png`);
-      const outFile = import_node_path7.default.resolve(root, style.outDir, relFile);
-      const qualityOutFile = style.quality ? import_node_path7.default.resolve(root, style.quality.outDir, pngPath(relFile)) : void 0;
+      const relFile = asset.file ?? import_node_path8.default.join(asset.category ?? "", `${assetId}.png`);
+      const outFile = import_node_path8.default.resolve(root, style.outDir, relFile);
+      const qualityOutFile = style.quality ? import_node_path8.default.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;
+      const terrainTiles = generator === "terrain" ? terrainTileCount(style.terrainTransitionSize, style.terrainMode, style.terrainOrientation) : 0;
       const base = {
         styleId,
         assetId,
@@ -9715,6 +10920,8 @@ async function resolveSpecs(loaded, filter) {
         uiColorPalette: generator === "uiAsset" || generator === "uiElement" ? style.uiColorPalette : void 0,
         ...generator === "imageProFlash" && style.styleTraits ? { styleTraits: style.styleTraits } : {},
         palette: style.palette,
+        ...generator === "imagePro" && style.paletteName ? { paletteName: style.paletteName } : {},
+        ...generator === "imagePro" && style.maxColors != null ? { maxColors: style.maxColors } : {},
         enforcePalette: style.enforcePalette,
         noBackground: style.noBackground,
         tileSize: generator === "tiles" ? tileSize : void 0,
@@ -9749,8 +10956,14 @@ async function resolveSpecs(loaded, filter) {
         terrainSpreadX: generator === "terrain" ? style.terrainSpreadX : void 0,
         terrainSlopeSize: generator === "terrain" ? style.terrainSlopeSize : void 0,
         terrainRaggedness: generator === "terrain" ? style.terrainRaggedness : void 0,
+        terrainRoundness: generator === "terrain" ? style.terrainRoundness : void 0,
+        terrainBoundaryAmplitude: generator === "terrain" ? style.terrainBoundaryAmplitude : void 0,
+        terrainBoundarySeed: generator === "terrain" ? style.terrainBoundarySeed : void 0,
+        terrainStepSlope: generator === "terrain" ? style.terrainStepSlope : void 0,
+        terrainConnectDiagonals: generator === "terrain" ? style.terrainConnectDiagonals : void 0,
         terrainTransitionSize: generator === "terrain" ? style.terrainTransitionSize : void 0,
         terrainView: generator === "terrain" ? style.terrainView : void 0,
+        terrainOrientation: generator === "terrain" ? style.terrainOrientation : void 0,
         isometricTileSize: generator === "isometricTile" ? style.isometricTileSize : void 0,
         isometricTileShape: generator === "isometricTile" ? style.isometricTileShape : void 0,
         // A revision in a character or objectPro style is a provider edit of
@@ -9761,7 +10974,7 @@ async function resolveSpecs(loaded, filter) {
         // 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),
+        cost: generator === "tiles" ? tilesCost(tileSize, tileVariations) : generator === "terrain" ? terrainCost(style.terrainMode, size, style.terrainOrientation) : generator === "isometricTile" ? isometricTileCost() : generationCost(width, height, generator),
         costUnit: "generations",
         candidates: generator === "tiles" ? tileVariations : generator === "terrain" ? terrainTiles : generator === "1dir" || generator === "imagePro" ? candidateCount(size) : 1
       };
@@ -9785,7 +10998,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: import_node_path7.default.resolve(root, style.quality.fixerPython) } : {},
+            ...style.quality.fixerPython ? { fixerPython: import_node_path8.default.resolve(root, style.quality.fixerPython) } : {},
             ...style.quality.fps == null ? {} : { fps: style.quality.fps }
           }
         } : {},
@@ -9822,6 +11035,11 @@ async function resolveSpecs(loaded, filter) {
         if (sourceSpec.generator === "tiles" || sourceSpec.generator === "terrain") {
           throw new Error(`assets.${assetId}: a tile set cannot be mirrored; its edges carry meaning`);
         }
+        if (sourceSpec.revision?.mode === "normal-map") {
+          throw new Error(
+            `assets.${assetId}: a normal map cannot be mirrored by flipping its pixels; every red channel would still point the old way. Make a normal-map revision of the mirrored art instead`
+          );
+        }
         if (sourceSpec.character?.kind === "animation") {
           const facing = sourceSpec.character.animation.direction;
           const mirrored = MIRRORED_DIRECTION[facing];
@@ -9868,7 +11086,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: (0, import_node_fs7.existsSync)(file) ? await sha256File(file) : null }
+          styleAnchor: { assetId: anchorId, spec: anchorSpec, file, sha256: (0, import_node_fs8.existsSync)(file) ? await sha256File(file) : null }
         };
       }
       const characterParent = asset.state?.of ?? asset.animation?.of ?? asset.portrait?.of;
@@ -9881,7 +11099,7 @@ async function resolveSpecs(loaded, filter) {
           parentAssetId: characterParent,
           parentSpec,
           parentFile,
-          parentSha256: (0, import_node_fs7.existsSync)(parentFile) ? await sha256File(parentFile) : null,
+          parentSha256: (0, import_node_fs8.existsSync)(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
@@ -9899,7 +11117,7 @@ async function resolveSpecs(loaded, filter) {
           parentAssetId: characterParent,
           parentSpec,
           parentFile,
-          parentSha256: (0, import_node_fs7.existsSync)(parentFile) ? await sha256File(parentFile) : null,
+          parentSha256: (0, import_node_fs8.existsSync)(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
         };
@@ -9921,7 +11139,7 @@ async function resolveSpecs(loaded, filter) {
           animation: sourceSpec.character.animation,
           outfit: {
             reference: {
-              path: import_node_path7.default.resolve(root, asset.outfit.reference),
+              path: import_node_path8.default.resolve(root, asset.outfit.reference),
               sha256: referenceImage.hash,
               width: referenceImage.width,
               height: referenceImage.height,
@@ -9942,25 +11160,30 @@ async function resolveSpecs(loaded, filter) {
             `Provider "${activeProvider.id}" does not support ${asset.revision.mode} revisions`
           );
         }
+        if (asset.revision.mode === "normal-map" && (style.enforcePalette || style.quality)) {
+          throw new Error(
+            `assets.${assetId}: a normal-map revision is lighting data, not art, and style "${styleId}" sets ${style.enforcePalette ? "enforcePalette" : "quality"}, which would recolour it. Put it in a style without enforcePalette or quality, and name the parent's style with revision.fromStyle`
+          );
+        }
         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 ? import_node_path7.default.resolve(root, sourceSpec.source) : sourceSpec.outFile);
+        const sourceStem = sourceSpec.quality?.outFile ?? (sourceSpec.source ? import_node_path8.default.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 ? import_node_path7.default.resolve(root, asset.revision.mask) : void 0;
+        const maskFile = asset.revision.mask ? import_node_path8.default.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 ? import_node_path7.default.resolve(root, asset.revision.paletteImage) : void 0;
+        const paletteImageFile = asset.revision.paletteImage ? import_node_path8.default.resolve(root, asset.revision.paletteImage) : void 0;
         const paletteImage = paletteImageFile ? await optionalRevisionImage(paletteImageFile, "revision palette image", "png") : null;
-        const lastFrameFile = asset.revision.lastFrame ? import_node_path7.default.resolve(root, asset.revision.lastFrame) : void 0;
+        const lastFrameFile = asset.revision.lastFrame ? import_node_path8.default.resolve(root, asset.revision.lastFrame) : void 0;
         const lastFrame = lastFrameFile ? await optionalRevisionImage(lastFrameFile, "revision last frame") : null;
-        const keypointsFile = asset.revision.keypointsFile ? import_node_path7.default.resolve(root, asset.revision.keypointsFile) : void 0;
+        const keypointsFile = asset.revision.keypointsFile ? import_node_path8.default.resolve(root, asset.revision.keypointsFile) : void 0;
         const keypoints = keypointsFile ? await optionalSkeletonSet(keypointsFile) : null;
         resolved.revision = {
           mode: asset.revision.mode,
@@ -10016,6 +11239,7 @@ async function resolveSpecs(loaded, filter) {
           ...asset.revision.skeletonTemplate ? { skeletonTemplate: asset.revision.skeletonTemplate } : {},
           ...asset.revision.description ? { description: asset.revision.description } : {},
           ...asset.revision.removalTask ? { removalTask: asset.revision.removalTask } : {},
+          ...asset.revision.convention ? { convention: asset.revision.convention } : {},
           ...asset.revision.driftThreshold == null ? {} : { driftThreshold: asset.revision.driftThreshold },
           ...asset.revision.subjectDescription ? { subjectDescription: asset.revision.subjectDescription } : {},
           ...asset.revision.initialPose ? { initialPose: asset.revision.initialPose } : {},
@@ -10072,6 +11296,24 @@ async function resolveSpecs(loaded, filter) {
           };
         }
       }
+      if (asset.connect) {
+        const links = {};
+        for (const side of ["lower", "upper"]) {
+          const link = asset.connect[side];
+          if (!link) continue;
+          if (!styleSpecs.has(link.of)) {
+            throw new Error(
+              `assets.${assetId}.connect.${side}.of: "${link.of}" is not in style "${styleId}"; connected terrain sets share one style`
+            );
+          }
+          const linkedSpec = await finalize(link.of);
+          if (linkedSpec.generator !== "terrain") {
+            throw new Error(`assets.${assetId}.connect.${side}.of: "${link.of}" is not a terrain set`);
+          }
+          links[side] = { assetId: link.of, terrain: link.terrain, spec: linkedSpec };
+        }
+        resolved.terrainConnect = links;
+      }
       if (asset.scene) resolved.scene = await resolveMapScene(root, styleId, assetId, resolved.generator, asset.scene, activeProvider);
       resolved.specHash = specHash(
         resolved,
@@ -10130,7 +11372,7 @@ async function resolveSpecs(loaded, filter) {
   return specs;
 }
 function pngPath(file) {
-  const extension = import_node_path7.default.extname(file);
+  const extension = import_node_path8.default.extname(file);
   return extension ? `${file.slice(0, -extension.length)}.png` : `${file}.png`;
 }
 async function resolveMapScene(root, styleId, assetId, generator, scene, provider) {
@@ -10140,12 +11382,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 = import_node_path7.default.resolve(root, scene.image);
+  const file = import_node_path8.default.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 = import_node_path7.default.resolve(root, placement.mask);
+    const maskFile = import_node_path8.default.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(
@@ -10163,20 +11405,20 @@ async function resolveVfxShape(root, assetId, vfx, defaultName) {
   let recipe;
   let recordedSprite;
   if (vfx.recipe) {
-    const file = import_node_path7.default.resolve(root, vfx.recipe);
-    if (!(0, import_node_fs7.existsSync)(file)) throw new Error(`assets.${assetId}.vfx.recipe: VFX recipe not found: ${file}`);
+    const file = import_node_path8.default.resolve(root, vfx.recipe);
+    if (!(0, import_node_fs8.existsSync)(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 : import_node_path7.default.resolve(root, vfx.sprite) : recordedSprite;
+  const spriteRef = vfx.sprite ? isVfxReference(vfx.sprite) ? vfx.sprite : import_node_path8.default.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`);
+    const image = await optionalRevisionImage(spriteRef, `assets.${assetId}.vfx.sprite`, vfx.description ? "png" : void 0);
     sprite = { file: spriteRef, sha256: image?.hash ?? null, width: image?.width ?? null, height: image?.height ?? null, format: image?.format ?? null };
   }
   return {
@@ -10185,12 +11427,14 @@ async function resolveVfxShape(root, assetId, vfx, defaultName) {
     ...vfx.parts?.length ? { parts: vfx.parts } : {},
     ...sprite ? { sprite } : {},
     ...vfx.fps !== void 0 ? { fps: vfx.fps } : {},
-    name: vfx.name ?? defaultName
+    // The artist caps a name at 80 characters; a long default is cut, not refused.
+    name: vfx.name ?? (vfx.description ? defaultName.slice(0, 80) : defaultName),
+    ...vfx.description ? { description: vfx.description, artist: vfx.artist ?? "lite" } : {}
   };
 }
 async function optionalRevisionImage(file, label, requiredFormat) {
-  if (!(0, import_node_fs7.existsSync)(file)) return null;
-  const bytes = await (0, import_promises4.readFile)(file);
+  if (!(0, import_node_fs8.existsSync)(file)) return null;
+  const bytes = await (0, import_promises5.readFile)(file);
   const metadata = imageMetadata(bytes);
   if (!metadata) throw new Error(`${label} is not a readable PNG or JPEG: ${file}`);
   if (requiredFormat && metadata.format !== requiredFormat) {
@@ -10199,8 +11443,8 @@ async function optionalRevisionImage(file, label, requiredFormat) {
   return { hash: sha256(bytes), ...metadata };
 }
 async function optionalSkeletonSet(file) {
-  if (!(0, import_node_fs7.existsSync)(file)) return null;
-  const bytes = await (0, import_promises4.readFile)(file);
+  if (!(0, import_node_fs8.existsSync)(file)) return null;
+  const bytes = await (0, import_promises5.readFile)(file);
   let json;
   try {
     json = JSON.parse(bytes.toString("utf8"));
@@ -10210,17 +11454,17 @@ async function optionalSkeletonSet(file) {
   return { hash: sha256(bytes), skeleton: parseSkeletonSet(json, file) };
 }
 async function revisionSourceMembers(stem, label) {
-  if ((0, import_node_fs7.existsSync)(stem)) return null;
+  if ((0, import_node_fs8.existsSync)(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) => (0, import_node_fs7.existsSync)(at(direction)))) {
+    if (set.every((direction) => (0, import_node_fs8.existsSync)(at(direction)))) {
       roles = [...set];
       break;
     }
   }
   if (!roles.length) {
-    for (let index = 0; (0, import_node_fs7.existsSync)(at(`frame-${String(index).padStart(2, "0")}`)); index++) {
+    for (let index = 0; (0, import_node_fs8.existsSync)(at(`frame-${String(index).padStart(2, "0")}`)); index++) {
       roles.push(`frame-${String(index).padStart(2, "0")}`);
     }
   }
@@ -10246,8 +11490,8 @@ async function resolveStyleImages(loaded, styleId) {
   if (!style) throw new Error(`Unknown style "${styleId}"`);
   const out = [];
   for (const img of style.styleImages) {
-    const file = import_node_path7.default.resolve(loaded.root, img.path);
-    const buf = await (0, import_promises4.readFile)(file);
+    const file = import_node_path8.default.resolve(loaded.root, img.path);
+    const buf = await (0, import_promises5.readFile)(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) {
@@ -10277,7 +11521,7 @@ async function resolveCharacterShape(asset, style, kind, files) {
   };
   if (asset.concept) {
     const image = await files.load(asset.concept, "Concept image");
-    shape.concept = { path: import_node_path7.default.resolve(files.root, asset.concept), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+    shape.concept = { path: import_node_path8.default.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;
@@ -10285,7 +11529,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: import_node_path7.default.resolve(files.root, rel),
+        path: import_node_path8.default.resolve(files.root, rel),
         sha256: image.hash,
         width: image.width,
         height: image.height,
@@ -10306,7 +11550,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: import_node_path7.default.resolve(files.root, rel), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+      return { path: import_node_path8.default.resolve(files.root, rel), sha256: image.hash, width: image.width, height: image.height, format: image.format };
     };
     shape.animation = {
       mode: animationMode,
@@ -10337,7 +11581,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: import_node_path7.default.resolve(files.root, south), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+      shape.reference = { path: import_node_path8.default.resolve(files.root, south), sha256: image.hash, width: image.width, height: image.height, format: image.format };
     }
   }
   if (asset.state) {
@@ -10365,7 +11609,7 @@ async function resolveObjectProShape(assetId, asset, style, kind, files) {
     }
     const pose = async (rel, what) => {
       const image = await files.load(rel, what);
-      return { path: import_node_path7.default.resolve(files.root, rel), sha256: image.hash, width: image.width, height: image.height, format: image.format };
+      return { path: import_node_path8.default.resolve(files.root, rel), sha256: image.hash, width: image.width, height: image.height, format: image.format };
     };
     shape.animation = {
       mode: asset.animation.mode ?? "v3",
@@ -10385,11 +11629,11 @@ function characterDirections(directions) {
 }
 
 // src/project.ts
-var import_node_path15 = __toESM(require("path"), 1);
+var import_node_path16 = __toESM(require("path"), 1);
 
 // src/env.ts
-var import_node_fs8 = require("fs");
-var import_node_path8 = __toESM(require("path"), 1);
+var import_node_fs9 = require("fs");
+var import_node_path9 = __toESM(require("path"), 1);
 function loadEnvFiles(dir) {
   const loaded = [];
   for (const [file, vars] of envFiles(dir)) {
@@ -10403,10 +11647,10 @@ function loadEnvFiles(dir) {
 function envFiles(dir) {
   const out = [];
   for (const name of [".env.local", ".env"]) {
-    const file = import_node_path8.default.join(dir, name);
-    if (!(0, import_node_fs8.existsSync)(file)) continue;
+    const file = import_node_path9.default.join(dir, name);
+    if (!(0, import_node_fs9.existsSync)(file)) continue;
     try {
-      out.push([file, parseEnv((0, import_node_fs8.readFileSync)(file, "utf8"))]);
+      out.push([file, parseEnv((0, import_node_fs9.readFileSync)(file, "utf8"))]);
     } catch {
     }
   }
@@ -10432,12 +11676,12 @@ function parseEnv(contents) {
 }
 
 // src/pipeline/plan.ts
-var import_node_fs11 = require("fs");
-var import_node_path14 = __toESM(require("path"), 1);
+var import_node_fs12 = require("fs");
+var import_node_path15 = __toESM(require("path"), 1);
 
 // src/pipeline/mirror.ts
-var import_promises5 = require("fs/promises");
-var import_node_path9 = __toESM(require("path"), 1);
+var import_promises6 = require("fs/promises");
+var import_node_path10 = __toESM(require("path"), 1);
 
 // src/palette.ts
 function normalizePalette(values) {
@@ -10574,12 +11818,12 @@ async function deriveMirror(spec, lock, lockPath, opts = {}) {
   const outputs = [];
   const written = [];
   for (const [index, member] of members.entries()) {
-    const bytes = flipHorizontal(await (0, import_promises5.readFile)(member.file));
+    const bytes = flipHorizontal(await (0, import_promises6.readFile)(member.file));
     const target = expectedOutputPath(spec, member.role, index, members.length, MediaType.PNG);
-    await (0, import_promises5.mkdir)(import_node_path9.default.dirname(target), { recursive: true });
+    await (0, import_promises6.mkdir)(import_node_path10.default.dirname(target), { recursive: true });
     const tmp = `${target}.pixelkiln.tmp`;
-    await (0, import_promises5.writeFile)(tmp, bytes);
-    await (0, import_promises5.rename)(tmp, target);
+    await (0, import_promises6.writeFile)(tmp, bytes);
+    await (0, import_promises6.rename)(tmp, target);
     written.push(target);
     outputs.push({
       path: portableOutputPath(target, spec.root),
@@ -10638,20 +11882,20 @@ async function deriveMirror(spec, lock, lockPath, opts = {}) {
 }
 
 // src/pipeline/quality-profile.ts
-var import_node_fs9 = require("fs");
-var import_node_path12 = __toESM(require("path"), 1);
+var import_node_fs10 = require("fs");
+var import_node_path13 = __toESM(require("path"), 1);
 
 // src/pipeline/refine.ts
-var import_node_path11 = __toESM(require("path"), 1);
+var import_node_path12 = __toESM(require("path"), 1);
 var import_node_child_process2 = require("child_process");
-var import_promises7 = require("fs/promises");
+var import_promises8 = require("fs/promises");
 var import_node_os3 = require("os");
 var import_node_util = require("util");
 
 // src/artifacts.ts
-var import_node_path10 = __toESM(require("path"), 1);
+var import_node_path11 = __toESM(require("path"), 1);
 var import_node_crypto6 = require("crypto");
-var import_promises6 = require("fs/promises");
+var import_promises7 = require("fs/promises");
 var activeTransactions = /* @__PURE__ */ new Set();
 function message(error) {
   return error instanceof Error ? error.message : String(error);
@@ -10660,7 +11904,7 @@ function digest(data) {
   return (0, import_node_crypto6.createHash)("sha256").update(data).digest("hex");
 }
 function portableRelative(from, to) {
-  return import_node_path10.default.relative(from, import_node_path10.default.resolve(to)).split(import_node_path10.default.sep).join("/") || ".";
+  return import_node_path11.default.relative(from, import_node_path11.default.resolve(to)).split(import_node_path11.default.sep).join("/") || ".";
 }
 function canonical2(value) {
   if (value === null || typeof value === "string" || typeof value === "boolean") return value;
@@ -10710,12 +11954,12 @@ function parseArtifactManifest(absolute, data) {
   return raw;
 }
 async function readArtifactBundleManifest(manifestPath) {
-  const absolute = import_node_path10.default.resolve(manifestPath);
-  return parseArtifactManifest(absolute, await (0, import_promises6.readFile)(absolute, "utf8"));
+  const absolute = import_node_path11.default.resolve(manifestPath);
+  return parseArtifactManifest(absolute, await (0, import_promises7.readFile)(absolute, "utf8"));
 }
 async function readOptional(file) {
   try {
-    return await (0, import_promises6.readFile)(file);
+    return await (0, import_promises7.readFile)(file);
   } catch (error) {
     if (isCode(error, "ENOENT")) return null;
     throw error;
@@ -10734,8 +11978,8 @@ function processIsAlive(pid) {
   }
 }
 function validTemporaryPath(candidate, destination, type) {
-  return import_node_path10.default.dirname(candidate) === import_node_path10.default.dirname(destination) && import_node_path10.default.basename(candidate).startsWith(
-    `.${import_node_path10.default.basename(destination)}.pixelkiln-${type}-`
+  return import_node_path11.default.dirname(candidate) === import_node_path11.default.dirname(destination) && import_node_path11.default.basename(candidate).startsWith(
+    `.${import_node_path11.default.basename(destination)}.pixelkiln-${type}-`
   );
 }
 function parseTransaction(journal, data) {
@@ -10751,14 +11995,14 @@ function parseTransaction(journal, data) {
   return raw;
 }
 async function removeTransactionFiles(journal) {
-  await (0, import_promises6.rm)(journal, { force: true });
-  await (0, import_promises6.rm)(transactionMarker(journal), { force: true });
+  await (0, import_promises7.rm)(journal, { force: true });
+  await (0, import_promises7.rm)(transactionMarker(journal), { force: true });
 }
 async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
-  const journal = import_node_path10.default.resolve(recoveryFile);
+  const journal = import_node_path11.default.resolve(recoveryFile);
   const bytes = await readOptional(journal);
   if (!bytes) {
-    await (0, import_promises6.rm)(transactionMarker(journal), { force: true });
+    await (0, import_promises7.rm)(transactionMarker(journal), { force: true });
     return;
   }
   if (activeTransactions.has(journal)) {
@@ -10771,7 +12015,7 @@ async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
     );
   }
   for (const entry of transaction.entries) {
-    if (typeof entry.destination !== "string" || typeof entry.stage !== "string" || typeof entry.sha256 !== "string" || entry.backup !== void 0 && typeof entry.backup !== "string" || !allowedDestinations.has(import_node_path10.default.resolve(entry.destination)) || !validTemporaryPath(entry.stage, entry.destination, "stage") || entry.backup !== void 0 && !validTemporaryPath(entry.backup, entry.destination, "backup")) {
+    if (typeof entry.destination !== "string" || typeof entry.stage !== "string" || typeof entry.sha256 !== "string" || entry.backup !== void 0 && typeof entry.backup !== "string" || !allowedDestinations.has(import_node_path11.default.resolve(entry.destination)) || !validTemporaryPath(entry.stage, entry.destination, "stage") || entry.backup !== void 0 && !validTemporaryPath(entry.backup, entry.destination, "backup")) {
       throw new Error(
         `Refusing unsafe artifact recovery from ${journal}; its destinations or temporary paths do not match the current bundle.`
       );
@@ -10797,7 +12041,7 @@ async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
         }
         await remove2(entry.destination, errors);
         try {
-          await (0, import_promises6.rename)(entry.backup, entry.destination);
+          await (0, import_promises7.rename)(entry.backup, entry.destination);
         } catch (error) {
           errors.push(
             `could not restore ${entry.destination}; previous file remains at ${entry.backup}: ${message(error)}`
@@ -10817,7 +12061,7 @@ async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
   await removeTransactionFiles(journal);
 }
 function createArtifactBundleManifest(manifestPath, outputs, provenance) {
-  const root = import_node_path10.default.dirname(import_node_path10.default.resolve(manifestPath));
+  const root = import_node_path11.default.dirname(import_node_path11.default.resolve(manifestPath));
   const sources = provenance.sources.map((source) => ({
     ...source,
     path: portableRelative(root, source.path)
@@ -10847,11 +12091,11 @@ function withArtifactManifest(manifestPath, outputs, provenance) {
   ];
 }
 async function writeManagedArtifactBundle(manifestPath, outputs, provenance, options = {}) {
-  const absoluteManifest = import_node_path10.default.resolve(manifestPath);
+  const absoluteManifest = import_node_path11.default.resolve(manifestPath);
   const recoveryFile = `${absoluteManifest}.transaction`;
   const allowedDestinations = /* @__PURE__ */ new Set([
     absoluteManifest,
-    ...outputs.map((output) => import_node_path10.default.resolve(output.path))
+    ...outputs.map((output) => import_node_path11.default.resolve(output.path))
   ]);
   await recoverArtifactTransaction(recoveryFile, allowedDestinations);
   const existingManifestBytes = await readOptional(absoluteManifest);
@@ -10869,13 +12113,13 @@ async function writeManagedArtifactBundle(manifestPath, outputs, provenance, opt
     }
   }
   if (!options.force) {
-    const root = import_node_path10.default.dirname(absoluteManifest);
+    const root = import_node_path11.default.dirname(absoluteManifest);
     const recorded = new Map(
-      previous?.outputs.map((output) => [import_node_path10.default.resolve(root, output.path), output.sha256]) ?? []
+      previous?.outputs.map((output) => [import_node_path11.default.resolve(root, output.path), output.sha256]) ?? []
     );
     const conflicts = [];
     for (const output of outputs) {
-      const destination = import_node_path10.default.resolve(output.path);
+      const destination = import_node_path11.default.resolve(output.path);
       const current = await readOptional(destination);
       if (!current || digest(current) === digest(output.data)) continue;
       const expected = recorded.get(destination);
@@ -10897,15 +12141,15 @@ Pass { force: true } (CLI: --force) to take ownership and replace the complete b
   );
 }
 async function verifyArtifactBundle(manifestPath) {
-  const absolute = import_node_path10.default.resolve(manifestPath);
+  const absolute = import_node_path11.default.resolve(manifestPath);
   const raw = await readArtifactBundleManifest(absolute);
-  const root = import_node_path10.default.dirname(absolute);
+  const root = import_node_path11.default.dirname(absolute);
   const changedSources = [];
   const changedOutputs = [];
   for (const source of raw.sources) {
     let actual = null;
     try {
-      actual = digest(await (0, import_promises6.readFile)(import_node_path10.default.resolve(root, source.path)));
+      actual = digest(await (0, import_promises7.readFile)(import_node_path11.default.resolve(root, source.path)));
     } catch (error) {
       if (!isCode(error, "ENOENT")) throw error;
     }
@@ -10913,7 +12157,7 @@ async function verifyArtifactBundle(manifestPath) {
   }
   for (const output of raw.outputs) {
     try {
-      if (digest(await (0, import_promises6.readFile)(import_node_path10.default.resolve(root, output.path))) !== output.sha256) {
+      if (digest(await (0, import_promises7.readFile)(import_node_path11.default.resolve(root, output.path))) !== output.sha256) {
         changedOutputs.push(output.path);
       }
     } catch (error) {
@@ -10939,7 +12183,7 @@ function isCode(error, code) {
 }
 async function remove2(file, errors) {
   try {
-    await (0, import_promises6.rm)(file, { force: true });
+    await (0, import_promises7.rm)(file, { force: true });
   } catch (error) {
     errors?.push(`could not remove ${file}: ${message(error)}`);
   }
@@ -10952,7 +12196,7 @@ async function rollback(prepared) {
   for (const artifact of [...prepared].reverse()) {
     if (!artifact.backup || !artifact.backedUp) continue;
     try {
-      await (0, import_promises6.rename)(artifact.backup, artifact.destination);
+      await (0, import_promises7.rename)(artifact.backup, artifact.destination);
       artifact.backedUp = false;
     } catch (error) {
       errors.push(
@@ -10969,7 +12213,7 @@ async function writeArtifactBundle(files, options = {}) {
   if (!files.length) throw new Error("An artifact bundle must contain at least one file.");
   const normalized = files.map((file) => {
     if (!file.path.trim()) throw new Error("Artifact paths cannot be empty.");
-    return { destination: import_node_path10.default.resolve(file.path), data: Buffer.from(file.data) };
+    return { destination: import_node_path11.default.resolve(file.path), data: Buffer.from(file.data) };
   });
   const destinations = /* @__PURE__ */ new Set();
   for (const artifact of normalized) {
@@ -10985,7 +12229,7 @@ async function writeArtifactBundle(files, options = {}) {
   const unchanged = [];
   for (const artifact of normalized) {
     try {
-      const current = await (0, import_promises6.readFile)(artifact.destination);
+      const current = await (0, import_promises7.readFile)(artifact.destination);
       if (current.equals(artifact.data)) {
         unchanged.push(artifact.destination);
       } else {
@@ -10999,21 +12243,21 @@ async function writeArtifactBundle(files, options = {}) {
   if (!changed.length) return { changed: [], unchanged };
   const token = (0, import_node_crypto6.randomUUID)();
   for (const [index, artifact] of changed.entries()) {
-    const basename = import_node_path10.default.basename(artifact.destination);
-    artifact.stage = import_node_path10.default.join(
-      import_node_path10.default.dirname(artifact.destination),
+    const basename = import_node_path11.default.basename(artifact.destination);
+    artifact.stage = import_node_path11.default.join(
+      import_node_path11.default.dirname(artifact.destination),
       `.${basename}.pixelkiln-stage-${token}-${index}`
     );
     if (artifact.existed) {
-      artifact.backup = import_node_path10.default.join(
-        import_node_path10.default.dirname(artifact.destination),
+      artifact.backup = import_node_path11.default.join(
+        import_node_path11.default.dirname(artifact.destination),
         `.${basename}.pixelkiln-backup-${token}-${index}`
       );
     }
   }
-  const journal = options.recoveryFile ? import_node_path10.default.resolve(options.recoveryFile) : null;
+  const journal = options.recoveryFile ? import_node_path11.default.resolve(options.recoveryFile) : null;
   if (journal) {
-    await (0, import_promises6.mkdir)(import_node_path10.default.dirname(journal), { recursive: true });
+    await (0, import_promises7.mkdir)(import_node_path11.default.dirname(journal), { recursive: true });
     const transaction = {
       format: "pixelkiln-artifact-transaction",
       version: 1,
@@ -11027,7 +12271,7 @@ async function writeArtifactBundle(files, options = {}) {
       }))
     };
     try {
-      await (0, import_promises6.writeFile)(journal, JSON.stringify(transaction, null, 2) + "\n", { flag: "wx" });
+      await (0, import_promises7.writeFile)(journal, JSON.stringify(transaction, null, 2) + "\n", { flag: "wx" });
       activeTransactions.add(journal);
     } catch (error) {
       throw new Error(
@@ -11038,9 +12282,9 @@ async function writeArtifactBundle(files, options = {}) {
   }
   try {
     for (const [index, artifact] of changed.entries()) {
-      await (0, import_promises6.mkdir)(import_node_path10.default.dirname(artifact.destination), { recursive: true });
+      await (0, import_promises7.mkdir)(import_node_path11.default.dirname(artifact.destination), { recursive: true });
       await options.beforeStage?.(artifact.destination, index);
-      await (0, import_promises6.writeFile)(artifact.stage, artifact.data, { flag: "wx" });
+      await (0, import_promises7.writeFile)(artifact.stage, artifact.data, { flag: "wx" });
     }
   } catch (error) {
     const cleanupErrors2 = await rollback(changed);
@@ -11053,17 +12297,17 @@ async function writeArtifactBundle(files, options = {}) {
   try {
     for (const artifact of changed) {
       if (!artifact.existed) continue;
-      await (0, import_promises6.rename)(artifact.destination, artifact.backup);
+      await (0, import_promises7.rename)(artifact.destination, artifact.backup);
       artifact.backedUp = true;
     }
     for (const [index, artifact] of changed.entries()) {
       await options.beforePromote?.(artifact.destination, index);
-      await (0, import_promises6.rename)(artifact.stage, artifact.destination);
+      await (0, import_promises7.rename)(artifact.stage, artifact.destination);
       artifact.stage = void 0;
       artifact.promoted = true;
     }
     if (journal) {
-      await (0, import_promises6.writeFile)(transactionMarker(journal), `${token}
+      await (0, import_promises7.writeFile)(transactionMarker(journal), `${token}
 `, { flag: "wx" });
       durableCommit = true;
       await options.afterCommit?.();
@@ -11304,16 +12548,16 @@ function sameFrameGrid(first, next) {
   return next.detection.stepX === first.detection.stepX && next.detection.stepY === first.detection.stepY && next.detection.columns === first.detection.columns && next.detection.rows === first.detection.rows && phaseMatches(next.detection.phaseX, first.detection.phaseX, first.detection.stepX) && phaseMatches(next.detection.phaseY, first.detection.phaseY, first.detection.stepY) && next.audit.width === first.audit.width && next.audit.height === first.audit.height && next.sourceWidth === first.sourceWidth && next.sourceHeight === first.sourceHeight;
 }
 async function refineAsset(options) {
-  const source = import_node_path11.default.resolve(options.source);
-  const output = import_node_path11.default.resolve(options.output);
+  const source = import_node_path12.default.resolve(options.source);
+  const output = import_node_path12.default.resolve(options.output);
   if (source === output) throw new Error("Refinement source and output must be different files.");
-  const record = import_node_path11.default.resolve(qualityRecordPath(output));
+  const record = import_node_path12.default.resolve(qualityRecordPath(output));
   const palette = normalizePalette(options.palette).map((color) => color.hex);
   const minGridConfidence = requireConfidence(options.minGridConfidence ?? "high");
   if (options.minTransparency !== void 0 && (!Number.isFinite(options.minTransparency) || options.minTransparency < 0 || options.minTransparency > 1)) throw new Error("minTransparency must be between 0 and 1.");
   let sourcePng;
   try {
-    sourcePng = decodePng(await (0, import_promises7.readFile)(source));
+    sourcePng = decodePng(await (0, import_promises8.readFile)(source));
   } catch (error) {
     throw new Error(`Cannot read refinement source ${source}: ${message2(error)}`, { cause: error });
   }
@@ -11330,8 +12574,8 @@ async function refineAsset(options) {
       );
     }
   }
-  const temp = await (0, import_promises7.mkdtemp)(import_node_path11.default.join((0, import_node_os3.tmpdir)(), "pixelkiln-refine-"));
-  const recovered = import_node_path11.default.join(temp, "native.png");
+  const temp = await (0, import_promises8.mkdtemp)(import_node_path12.default.join((0, import_node_os3.tmpdir)(), "pixelkiln-refine-"));
+  const recovered = import_node_path12.default.join(temp, "native.png");
   const fixerCommand = compatibilityCommand ?? options.fixerPython ?? process.env.PIXELKILN_PIXEL_FIXER_PYTHON ?? "python3";
   const args = compatibilityCommand ? [...options.fixerArgsPrefix ?? [], source, "--extract", recovered] : ["-c", PYTHON_FIXER_BRIDGE, source, recovered];
   try {
@@ -11352,7 +12596,7 @@ async function refineAsset(options) {
       );
     }
     const detection = parseDetection(firstJsonObject(stdout));
-    const native = decodePng(await (0, import_promises7.readFile)(recovered));
+    const native = decodePng(await (0, import_promises8.readFile)(recovered));
     const quantized = quantizeToPalette(native, palette);
     const png = encodeRgbaPng(quantized.width, quantized.height, quantized.pixels);
     const audit = auditRefinement(
@@ -11402,7 +12646,7 @@ async function refineAsset(options) {
     );
     return { source, output, record, detection, palette, audit };
   } finally {
-    await (0, import_promises7.rm)(temp, { recursive: true, force: true });
+    await (0, import_promises8.rm)(temp, { recursive: true, force: true });
   }
 }
 async function refineFrameSet(options) {
@@ -11416,18 +12660,18 @@ async function refineFrameSet(options) {
   if (roles.some((role) => !role.trim()) || new Set(roles).size !== roles.length) {
     throw new Error("Frame-set roles must be non-empty and unique.");
   }
-  const output = import_node_path11.default.resolve(options.output);
-  const record = import_node_path11.default.resolve(qualityRecordPath(output));
+  const output = import_node_path12.default.resolve(options.output);
+  const record = import_node_path12.default.resolve(qualityRecordPath(output));
   const palette = normalizeRefinementPalette(options.palette);
   const finalOutputs = options.sources.map((source, index) => qualityFrameOutputPath(output, source.role, index));
   if (new Set(finalOutputs).size !== finalOutputs.length) {
     throw new Error("Frame-set roles resolve to duplicate output filenames.");
   }
-  const sourceSet = new Set(options.sources.map((source) => import_node_path11.default.resolve(source.path)));
+  const sourceSet = new Set(options.sources.map((source) => import_node_path12.default.resolve(source.path)));
   if (finalOutputs.some((file) => sourceSet.has(file))) {
     throw new Error("Frame-set refinement sources and outputs must be different files.");
   }
-  const temp = await (0, import_promises7.mkdtemp)(import_node_path11.default.join((0, import_node_os3.tmpdir)(), "pixelkiln-refine-frames-"));
+  const temp = await (0, import_promises8.mkdtemp)(import_node_path12.default.join((0, import_node_os3.tmpdir)(), "pixelkiln-refine-frames-"));
   try {
     const frames = [];
     const outputs = [];
@@ -11435,8 +12679,8 @@ async function refineFrameSet(options) {
     const sourcePaths = [];
     let firstOptions = null;
     for (const [index, sourceEntry] of options.sources.entries()) {
-      const source = import_node_path11.default.resolve(sourceEntry.path);
-      const temporaryOutput = import_node_path11.default.join(temp, `${String(index).padStart(2, "0")}.png`);
+      const source = import_node_path12.default.resolve(sourceEntry.path);
+      const temporaryOutput = import_node_path12.default.join(temp, `${String(index).padStart(2, "0")}.png`);
       const refined = await refineAsset({
         source,
         output: temporaryOutput,
@@ -11468,7 +12712,7 @@ async function refineFrameSet(options) {
       });
       outputs.push({
         path: finalOutputs[index],
-        data: await (0, import_promises7.readFile)(temporaryOutput)
+        data: await (0, import_promises8.readFile)(temporaryOutput)
       });
     }
     const first = frames[0];
@@ -11511,23 +12755,23 @@ async function refineFrameSet(options) {
     );
     return {
       sources: sourcePaths,
-      outputs: outputs.map((item) => import_node_path11.default.resolve(item.path)),
+      outputs: outputs.map((item) => import_node_path12.default.resolve(item.path)),
       record,
       frames,
       palette,
       audit
     };
   } finally {
-    await (0, import_promises7.rm)(temp, { recursive: true, force: true });
+    await (0, import_promises8.rm)(temp, { recursive: true, force: true });
   }
 }
 async function checkQualityRecord(recordPath) {
-  const record = import_node_path11.default.resolve(recordPath);
+  const record = import_node_path12.default.resolve(recordPath);
   const manifest = await readArtifactBundleManifest(record);
   const options = parseRecordOptions(manifest, record);
   const verification = await verifyArtifactBundle(record);
-  const sources = manifest.sources.map((source2) => import_node_path11.default.resolve(import_node_path11.default.dirname(record), source2.path));
-  const outputs = manifest.outputs.map((output2) => import_node_path11.default.resolve(import_node_path11.default.dirname(record), output2.path));
+  const sources = manifest.sources.map((source2) => import_node_path12.default.resolve(import_node_path12.default.dirname(record), source2.path));
+  const outputs = manifest.outputs.map((output2) => import_node_path12.default.resolve(import_node_path12.default.dirname(record), output2.path));
   const source = sources[0] ?? "";
   const output = outputs[0] ?? "";
   const expectedCount = options.frameSet?.count ?? 1;
@@ -11560,7 +12804,7 @@ async function checkQualityRecord(recordPath) {
 async function approveQualityRecord(recordPath, approval) {
   const reviewer = approval.reviewer.trim();
   if (!reviewer) throw new Error("A human reviewer name is required.");
-  const record = import_node_path11.default.resolve(recordPath);
+  const record = import_node_path12.default.resolve(recordPath);
   const manifest = await readArtifactBundleManifest(record);
   const options = parseRecordOptions(manifest, record);
   const verification = await verifyArtifactBundle(record);
@@ -11581,14 +12825,14 @@ async function approveQualityRecord(recordPath, approval) {
       `A refinement record must contain exactly ${expectedCount} source(s) and output(s).`
     );
   }
-  const root = import_node_path11.default.dirname(record);
+  const root = import_node_path12.default.dirname(record);
   const outputs = await Promise.all(manifest.outputs.map(async (entry) => {
-    const outputPath = import_node_path11.default.resolve(root, entry.path);
-    return { path: outputPath, data: await (0, import_promises7.readFile)(outputPath) };
+    const outputPath = import_node_path12.default.resolve(root, entry.path);
+    return { path: outputPath, data: await (0, import_promises8.readFile)(outputPath) };
   }));
   const sources = manifest.sources.map((source) => ({
     ...source,
-    path: import_node_path11.default.resolve(root, source.path)
+    path: import_node_path12.default.resolve(root, source.path)
   }));
   const approved = {
     ...options,
@@ -11620,8 +12864,8 @@ async function qualitySource(spec, lock) {
     if (spec.generator === "frames") {
       return { items: null, reason: "frame-set quality requires ordered downloaded provider outputs" };
     }
-    const source = import_node_path12.default.resolve(spec.root, spec.source);
-    return (0, import_node_fs9.existsSync)(source) ? { items: [{ role: "source", path: source }] } : { items: null, reason: `declared source is missing: ${spec.source}` };
+    const source = import_node_path13.default.resolve(spec.root, spec.source);
+    return (0, import_node_fs10.existsSync)(source) ? { items: [{ role: "source", path: source }] } : { items: null, reason: `declared source is missing: ${spec.source}` };
   }
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
   if (!entry) return { items: null, reason: "raw provider output is not in the lockfile" };
@@ -11650,7 +12894,7 @@ async function qualitySource(spec, lock) {
     }
     if (role) roles.add(role);
     const source = currentEntryOutputPath(entry, spec, index);
-    if (!(0, import_node_fs9.existsSync)(source)) return { items: null, reason: `raw provider output is missing: ${source}` };
+    if (!(0, import_node_fs10.existsSync)(source)) return { items: null, reason: `raw provider output is missing: ${source}` };
     if (await sha256File(source) !== output.sha256) {
       return { items: null, reason: "raw provider output was modified after download" };
     }
@@ -11669,7 +12913,7 @@ async function inspectQualityProfile(spec, lock) {
   }
   const sourcePaths = source.items.map((item) => item.path);
   const expectedOutputs = spec.generator === "frames" ? source.items.map((item, index) => qualityFrameOutputPath(output, item.role, index)) : [output];
-  if (!(0, import_node_fs9.existsSync)(record)) {
+  if (!(0, import_node_fs10.existsSync)(record)) {
     return {
       key,
       state: "needs-refinement",
@@ -11687,7 +12931,7 @@ async function inspectQualityProfile(spec, lock) {
     const expectedRevision = spec.quality.fixerRevision ?? PIXEL_ART_FIXER_REVISION;
     const expectedTransparency = spec.quality.minTransparency ?? null;
     const expectedFrameSet = spec.generator === "frames" ? { fps: spec.quality.fps ?? 12, count: source.items.length, roles: source.items.map((item) => item.role) } : null;
-    const contractChanged = JSON.stringify(check.sources.map((item) => import_node_path12.default.resolve(item))) !== JSON.stringify(sourcePaths.map((item) => import_node_path12.default.resolve(item))) || JSON.stringify(check.outputs.map((item) => import_node_path12.default.resolve(item))) !== JSON.stringify(expectedOutputs.map((item) => import_node_path12.default.resolve(item))) || JSON.stringify(check.options.palette.colors) !== JSON.stringify(expectedPalette) || check.options.nativeGrid.revision !== expectedRevision || check.options.audit.thresholds.minGridConfidence !== spec.quality.minGridConfidence || check.options.audit.thresholds.minTransparency !== expectedTransparency || (expectedFrameSet ? !check.options.frameSet || check.options.frameSet.fps !== expectedFrameSet.fps || check.options.frameSet.count !== expectedFrameSet.count || JSON.stringify(check.options.frameSet.roles) !== JSON.stringify(expectedFrameSet.roles) : check.options.frameSet !== void 0);
+    const contractChanged = JSON.stringify(check.sources.map((item) => import_node_path13.default.resolve(item))) !== JSON.stringify(sourcePaths.map((item) => import_node_path13.default.resolve(item))) || JSON.stringify(check.outputs.map((item) => import_node_path13.default.resolve(item))) !== JSON.stringify(expectedOutputs.map((item) => import_node_path13.default.resolve(item))) || JSON.stringify(check.options.palette.colors) !== JSON.stringify(expectedPalette) || check.options.nativeGrid.revision !== expectedRevision || check.options.audit.thresholds.minGridConfidence !== spec.quality.minGridConfidence || check.options.audit.thresholds.minTransparency !== expectedTransparency || (expectedFrameSet ? !check.options.frameSet || check.options.frameSet.fps !== expectedFrameSet.fps || check.options.frameSet.count !== expectedFrameSet.count || JSON.stringify(check.options.frameSet.roles) !== JSON.stringify(expectedFrameSet.roles) : check.options.frameSet !== void 0);
     if (contractChanged) {
       return {
         key,
@@ -11850,8 +13094,8 @@ async function requireApprovedQualitySources(specs, lock, assetIds, outputRoles)
 }
 
 // src/pipeline/revision.ts
-var import_node_fs10 = require("fs");
-var import_node_path13 = __toESM(require("path"), 1);
+var import_node_fs11 = require("fs");
+var import_node_path14 = __toESM(require("path"), 1);
 async function inspectRevisionReadiness(spec, lock) {
   if (spec.mirror) return inspectMirror(spec, lock, /* @__PURE__ */ new Set());
   if (spec.character?.kind === "outfit") return inspectOutfit(spec, lock, /* @__PURE__ */ new Set());
@@ -11860,6 +13104,7 @@ async function inspectRevisionReadiness(spec, lock) {
   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.terrainConnect) return inspectTerrainConnect(spec, lock, /* @__PURE__ */ new Set());
   if (!spec.revision) return null;
   return inspectRevision(spec, lock, /* @__PURE__ */ new Set());
 }
@@ -11868,7 +13113,7 @@ async function inspectStyleAnchor(spec, lock, seen) {
   const label = `style anchor ${spec.styleId}/${anchor.assetId}`;
   const dependency = await inspectParent(anchor.spec, lock, seen);
   if (!dependency.ready) return { ready: false, reason: `${label} is not ready: ${dependency.reason}` };
-  if (!anchor.sha256 || !(0, import_node_fs10.existsSync)(anchor.file)) return { ready: false, reason: `${label} has no generated south-facing file yet` };
+  if (!anchor.sha256 || !(0, import_node_fs11.existsSync)(anchor.file)) return { ready: false, reason: `${label} has no generated south-facing file yet` };
   if (await sha256File(anchor.file) !== anchor.sha256) {
     return { ready: false, reason: `${label} changed after the manifest was resolved` };
   }
@@ -11877,19 +13122,31 @@ async function inspectStyleAnchor(spec, lock, seen) {
   }
   return { ready: true, reason: `${label} is current` };
 }
+async function inspectTerrainConnect(spec, lock, seen) {
+  for (const link of [spec.terrainConnect.lower, spec.terrainConnect.upper]) {
+    if (!link) continue;
+    const label = `connected set ${spec.styleId}/${link.assetId}`;
+    const dependency = await inspectParent(link.spec, lock, seen);
+    if (!dependency.ready) return { ready: false, reason: `${label} is not ready: ${dependency.reason}` };
+    if (!lock.entries[lockKey(link.spec.styleId, link.spec.assetId)]?.objectId) {
+      return { ready: false, reason: `${label} has no PixelLab tileset id recorded` };
+    }
+  }
+  return { ready: true, reason: "connected sets are current" };
+}
 async function inspectScene(spec) {
   const scene = spec.scene;
   const files = [{ label: "scene image", file: scene.file, sha256: scene.sha256 }];
   if (scene.placement.type === "mask") files.push({ label: "scene mask", file: scene.placement.file, sha256: scene.placement.sha256 });
   for (const { label, file, sha256: sha2562 } of files) {
-    if (!sha2562 || !(0, import_node_fs10.existsSync)(file)) return { ready: false, reason: `${label} does not exist yet: ${file}` };
+    if (!sha2562 || !(0, import_node_fs11.existsSync)(file)) return { ready: false, reason: `${label} does not exist yet: ${file}` };
     if (await sha256File(file) !== sha2562) return { ready: false, reason: `${label} changed after the manifest was resolved` };
   }
   return { ready: true, reason: "scene is current" };
 }
 async function inspectVfxSprite(spec) {
   const sprite = spec.vfx.sprite;
-  if (!sprite.sha256 || !(0, import_node_fs10.existsSync)(sprite.file)) return { ready: false, reason: `vfx sprite does not exist yet: ${sprite.file}` };
+  if (!sprite.sha256 || !(0, import_node_fs11.existsSync)(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" };
 }
@@ -11905,7 +13162,7 @@ async function inspectOutfit(spec, lock, seen) {
   const label = `outfit source ${spec.styleId}/${character.parentAssetId}`;
   const dependency = await inspectParent(character.parentSpec, lock, seen);
   if (!dependency.ready) return { ready: false, reason: `${label} is not ready: ${dependency.reason}` };
-  if (!(0, import_node_fs10.existsSync)(outfit.reference.path)) {
+  if (!(0, import_node_fs11.existsSync)(outfit.reference.path)) {
     return { ready: false, reason: `outfit reference is missing: ${outfit.reference.path}` };
   }
   if (await sha256File(outfit.reference.path) !== outfit.reference.sha256) {
@@ -11919,7 +13176,7 @@ async function inspectCharacterParent(spec, lock, seen) {
   const label = `${character.kind} parent ${spec.styleId}/${character.parentAssetId}`;
   const dependency = await inspectParent(parentSpec, lock, seen);
   if (!dependency.ready) return { ready: false, reason: `${label} is not ready: ${dependency.reason}` };
-  if (!character.parentSha256 || !character.parentFile || !(0, import_node_fs10.existsSync)(character.parentFile)) {
+  if (!character.parentSha256 || !character.parentFile || !(0, import_node_fs11.existsSync)(character.parentFile)) {
     return { ready: false, reason: `${label} has no generated south-facing file yet` };
   }
   if (await sha256File(character.parentFile) !== character.parentSha256) {
@@ -11937,7 +13194,7 @@ async function inspectObjectProParent(spec, lock, seen) {
   const label = `${object.kind} parent ${spec.styleId}/${object.parentAssetId}`;
   const dependency = await inspectParent(parentSpec, lock, seen);
   if (!dependency.ready) return { ready: false, reason: `${label} is not ready: ${dependency.reason}` };
-  if (!object.parentSha256 || !object.parentFile || !(0, import_node_fs10.existsSync)(object.parentFile)) {
+  if (!object.parentSha256 || !object.parentFile || !(0, import_node_fs11.existsSync)(object.parentFile)) {
     return { ready: false, reason: `${label} has no generated south-facing file yet` };
   }
   if (await sha256File(object.parentFile) !== object.parentSha256) {
@@ -11963,7 +13220,7 @@ async function inspectRevision(spec, lock, seen) {
     const members = await inspectSourceMembers(spec, lock);
     if (!members.ready) return members;
   } else {
-    if (!revision.sourceSha256 || !(0, import_node_fs10.existsSync)(revision.sourceFile)) {
+    if (!revision.sourceSha256 || !(0, import_node_fs11.existsSync)(revision.sourceFile)) {
       return { ready: false, reason: `revision source is missing: ${revision.sourceFile}` };
     }
     if (await sha256File(revision.sourceFile) !== revision.sourceSha256) {
@@ -11971,7 +13228,7 @@ async function inspectRevision(spec, lock, seen) {
     }
   }
   if (revision.maskFile) {
-    if (!revision.maskSha256 || !(0, import_node_fs10.existsSync)(revision.maskFile)) {
+    if (!revision.maskSha256 || !(0, import_node_fs11.existsSync)(revision.maskFile)) {
       return { ready: false, reason: `revision mask is missing: ${revision.maskFile}` };
     }
     if (await sha256File(revision.maskFile) !== revision.maskSha256) {
@@ -11979,7 +13236,7 @@ async function inspectRevision(spec, lock, seen) {
     }
   }
   if (revision.lastFrameFile) {
-    if (!revision.lastFrameSha256 || !(0, import_node_fs10.existsSync)(revision.lastFrameFile)) {
+    if (!revision.lastFrameSha256 || !(0, import_node_fs11.existsSync)(revision.lastFrameFile)) {
       return { ready: false, reason: `revision last frame is missing: ${revision.lastFrameFile}` };
     }
     if (await sha256File(revision.lastFrameFile) !== revision.lastFrameSha256) {
@@ -11992,7 +13249,7 @@ async function inspectSourceMembers(spec, lock) {
   const revision = spec.revision;
   const members = revision.sourceMembers;
   for (const member of members) {
-    if (!(0, import_node_fs10.existsSync)(member.file)) return { ready: false, reason: `revision source member is missing: ${member.file}` };
+    if (!(0, import_node_fs11.existsSync)(member.file)) return { ready: false, reason: `revision source member is missing: ${member.file}` };
     if (await sha256File(member.file) !== member.sha256) {
       return { ready: false, reason: `revision source member changed after the manifest was resolved: ${member.file}` };
     }
@@ -12001,8 +13258,8 @@ async function inspectSourceMembers(spec, lock) {
   if (parent.source) return { ready: true, reason: "declared source set is present" };
   const entry = lock.entries[lockKey(parent.styleId, parent.assetId)];
   if (!entry) return { ready: false, reason: "revision source is not in the lockfile" };
-  const recorded = entry.outputs.map((_, index) => import_node_path13.default.resolve(currentEntryOutputPath(entry, parent, index))).sort();
-  const found = members.map((member) => import_node_path13.default.resolve(member.file)).sort();
+  const recorded = entry.outputs.map((_, index) => import_node_path14.default.resolve(currentEntryOutputPath(entry, parent, index))).sort();
+  const found = members.map((member) => import_node_path14.default.resolve(member.file)).sort();
   if (recorded.length !== found.length || recorded.some((file, index) => file !== found[index])) {
     return {
       ready: false,
@@ -12043,6 +13300,10 @@ async function inspectParent(spec, lock, seen) {
     const inputs = await inspectObjectProParent(spec, lock, nextSeen);
     if (!inputs.ready) return inputs;
   }
+  if (spec.terrainConnect) {
+    const inputs = await inspectTerrainConnect(spec, lock, nextSeen);
+    if (!inputs.ready) return inputs;
+  }
   if (spec.quality) {
     const quality = await inspectQualityProfile(spec, lock);
     return quality?.state === "approved" ? { ready: true, reason: "approved quality output is current" } : {
@@ -12051,8 +13312,8 @@ async function inspectParent(spec, lock, seen) {
     };
   }
   if (spec.source) {
-    const source = import_node_path13.default.resolve(spec.root, spec.source);
-    return (0, import_node_fs10.existsSync)(source) ? { ready: true, reason: "declared source is present" } : { ready: false, reason: `declared source is missing: ${spec.source}` };
+    const source = import_node_path14.default.resolve(spec.root, spec.source);
+    return (0, import_node_fs11.existsSync)(source) ? { ready: true, reason: "declared source is present" } : { ready: false, reason: `declared source is missing: ${spec.source}` };
   }
   const entry = lock.entries[key];
   if (!entry) return { ready: false, reason: "parent is not in the lockfile" };
@@ -12066,7 +13327,7 @@ async function inspectParent(spec, lock, seen) {
   for (let index = 0; index < entry.outputs.length; index++) {
     const output = entry.outputs[index];
     const file = currentEntryOutputPath(entry, spec, index);
-    if (!(0, import_node_fs10.existsSync)(file)) return { ready: false, reason: `parent output is missing: ${file}` };
+    if (!(0, import_node_fs11.existsSync)(file)) return { ready: false, reason: `parent output is missing: ${file}` };
     if (await sha256File(file) !== output.sha256) {
       return { ready: false, reason: `parent output was modified: ${file}` };
     }
@@ -12088,9 +13349,21 @@ function dependencies(spec) {
     spec.revision?.sourceSpec,
     spec.character?.parentSpec,
     spec.character?.styleAnchor?.spec,
-    spec.objectPro?.parentSpec
+    spec.objectPro?.parentSpec,
+    spec.terrainConnect?.lower?.spec,
+    spec.terrainConnect?.upper?.spec
   ].filter((parent) => Boolean(parent));
 }
+function changedTerrainConnection(spec, entry, lock) {
+  for (const side of ["lower", "upper"]) {
+    const link = spec.terrainConnect?.[side];
+    if (!link) continue;
+    const other = lock.entries[lockKey(link.spec.styleId, link.spec.assetId)];
+    const recorded = entry.terrainConnect?.[side];
+    if (!recorded || recorded.sourceObjectId !== other?.objectId) return link.assetId;
+  }
+  return null;
+}
 function resumeCommandForStatus(status) {
   if (status === "pending" || status === "processing") return "poll";
   if (status === "review") return "pick";
@@ -12122,6 +13395,7 @@ async function buildPlan(specs, lock, opts = {}) {
     const entry = lock.entries[key];
     let state;
     let reason;
+    const changedConnection = entry ? changedTerrainConnection(spec, entry, lock) : null;
     const revision = await inspectRevisionReadiness(spec, lock);
     if (revision && !revision.ready) {
       state = "blocked";
@@ -12130,7 +13404,7 @@ async function buildPlan(specs, lock, opts = {}) {
       state = "missing";
       reason = "--force";
     } else if (!entry && spec.source && spec.generator !== "frames" && spec.generator !== "vfx") {
-      if ((0, import_node_fs11.existsSync)(import_node_path14.default.resolve(spec.root, spec.source))) {
+      if ((0, import_node_fs12.existsSync)(import_node_path15.default.resolve(spec.root, spec.source))) {
         state = "ok";
         reason = `placed from ${spec.source}; not generated`;
       } else {
@@ -12138,7 +13412,7 @@ async function buildPlan(specs, lock, opts = {}) {
         reason = `declared source is missing: ${spec.source}`;
       }
     } else if (!entry) {
-      if ((0, import_node_fs11.existsSync)(spec.outFile)) {
+      if ((0, import_node_fs12.existsSync)(spec.outFile)) {
         state = "untracked";
         reason = "file on disk, no provenance recorded";
       } else {
@@ -12151,12 +13425,15 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (spec.mirror && !mirrorCurrent(entry, lock.entries[lockKey(spec.styleId, spec.mirror.sourceAssetId)])) {
       state = "stale";
       reason = `mirror source ${spec.mirror.sourceAssetId} changed; flip it again (no generation cost)`;
-    } else if (spec.mirror && entry.status === "downloaded" && entry.outputs.some((_output, index) => !(0, import_node_fs11.existsSync)(currentEntryOutputPath(entry, spec, index)))) {
+    } else if (spec.mirror && entry.status === "downloaded" && entry.outputs.some((_output, index) => !(0, import_node_fs12.existsSync)(currentEntryOutputPath(entry, spec, index)))) {
       state = "stale";
       reason = "mirror output missing on disk; flip it again (no generation cost)";
     } else if (spec.character?.kind === "outfit" && entry.outfit?.sourceSha256 !== mirrorSourceHash(lock.entries[lockKey(spec.styleId, spec.character.parentAssetId)] ?? { outputs: [] })) {
       state = "stale";
       reason = `outfit source ${spec.character.parentAssetId} changed; re-clothe the loop again`;
+    } else if (changedConnection) {
+      state = "stale";
+      reason = `connected set ${changedConnection} was regenerated; draw this set from its new terrain`;
     } else if (entry.status === "download-failed") {
       state = "recoverable";
       const force = entry.error?.includes("pass --force") ? " --force" : "";
@@ -12179,9 +13456,9 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (entry.status !== "downloaded") {
       state = "in-flight";
       reason = `awaiting ${entry.status}`;
-    } else if (entry.outputs.length === 0 || entry.outputs.some((_output, index) => !(0, import_node_fs11.existsSync)(currentEntryOutputPath(entry, spec, index)))) {
+    } else if (entry.outputs.length === 0 || entry.outputs.some((_output, index) => !(0, import_node_fs12.existsSync)(currentEntryOutputPath(entry, spec, index)))) {
       state = "orphaned";
-      reason = entry.outputs.length === 0 ? "no recorded output files" : `missing on disk: ${entry.outputs.filter((_output, index) => !(0, import_node_fs11.existsSync)(currentEntryOutputPath(entry, spec, index))).map((o) => o.role ?? "asset").join(", ")}`;
+      reason = entry.outputs.length === 0 ? "no recorded output files" : `missing on disk: ${entry.outputs.filter((_output, index) => !(0, import_node_fs12.existsSync)(currentEntryOutputPath(entry, spec, index))).map((o) => o.role ?? "asset").join(", ")}`;
     } else if (await anyOutputModified(entry, spec)) {
       state = "orphaned";
       reason = "output modified since download";
@@ -12272,13 +13549,13 @@ function summarize(plan) {
 
 // src/project.ts
 async function openProject(manifestPath = "pixelkiln.manifest.json", opts = {}) {
-  const absolute = import_node_path15.default.resolve(manifestPath);
-  const root = import_node_path15.default.dirname(absolute);
+  const absolute = import_node_path16.default.resolve(manifestPath);
+  const root = import_node_path16.default.dirname(absolute);
   if (opts.env !== false) {
     loadEnvFiles(root);
-    if (import_node_path15.default.resolve(process.cwd()) !== root) loadEnvFiles(process.cwd());
+    if (import_node_path16.default.resolve(process.cwd()) !== root) loadEnvFiles(process.cwd());
   }
-  const lockPath = import_node_path15.default.resolve(opts.lockPath ?? import_node_path15.default.join(root, "pixelkiln.lock.json"));
+  const lockPath = import_node_path16.default.resolve(opts.lockPath ?? import_node_path16.default.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);
@@ -12307,47 +13584,10 @@ async function openProject(manifestPath = "pixelkiln.manifest.json", opts = {})
   };
 }
 
-// src/source-url.ts
-var SENSITIVE_QUERY_KEYS = /* @__PURE__ */ new Set([
-  "access_token",
-  "apikey",
-  "api_key",
-  "auth",
-  "authorization",
-  "awsaccesskeyid",
-  "googleaccessid",
-  "key",
-  "sig"
-]);
-function isSensitiveSourceUrl(value) {
-  let parsed;
-  try {
-    parsed = new URL(value);
-  } catch {
-    return false;
-  }
-  if (parsed.username || parsed.password) return true;
-  for (const key of parsed.searchParams.keys()) {
-    const normalized = key.toLowerCase();
-    if (SENSITIVE_QUERY_KEYS.has(normalized) || normalized.includes("credential") || normalized.includes("signature") || normalized.includes("security-token") || normalized.includes("token")) return true;
-  }
-  return false;
-}
-function shouldPersistSourceUrl(value) {
-  let parsed;
-  try {
-    parsed = new URL(value);
-  } catch {
-    return true;
-  }
-  if (parsed.protocol === "data:" || parsed.protocol === "file:") return false;
-  return !isSensitiveSourceUrl(value);
-}
-
 // src/recipes.ts
-var import_node_path16 = __toESM(require("path"), 1);
-var import_node_fs12 = require("fs");
-var import_promises8 = require("fs/promises");
+var import_node_path17 = __toESM(require("path"), 1);
+var import_node_fs13 = require("fs");
+var import_promises9 = require("fs/promises");
 var import_node_url = require("url");
 var import_zod4 = require("zod");
 var SHA256_RE = /^[0-9a-f]{64}$/;
@@ -12356,7 +13596,7 @@ var VERSION_RE = /^\d+\.\d+\.\d+$/;
 var RECIPE_FILE = "pixelkiln.recipe.json";
 var RECIPE_DIR_TOKEN = "{{recipeDir}}";
 var PortablePathSchema = import_zod4.z.string().min(1).refine((value) => {
-  if (value.includes("\\") || import_node_path16.default.posix.isAbsolute(value)) return false;
+  if (value.includes("\\") || import_node_path17.default.posix.isAbsolute(value)) return false;
   const parts = value.split("/");
   return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
 }, "expected a portable relative path without '.', '..', or backslashes");
@@ -12532,10 +13772,10 @@ function message3(error) {
   return error instanceof Error ? error.message : String(error);
 }
 async function readRecipeFile(recipePath, bundled) {
-  const absolute = import_node_path16.default.resolve(recipePath);
+  const absolute = import_node_path17.default.resolve(recipePath);
   let raw;
   try {
-    raw = JSON.parse(await (0, import_promises8.readFile)(absolute, "utf8"));
+    raw = JSON.parse(await (0, import_promises9.readFile)(absolute, "utf8"));
   } catch (error) {
     throw new Error(`Could not read recipe ${absolute}: ${message3(error)}`, { cause: error });
   }
@@ -12546,13 +13786,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: import_node_path16.default.dirname(absolute), bundled };
+  return { recipe: parsed.data, authored: raw, path: absolute, dir: import_node_path17.default.dirname(absolute), bundled };
 }
 async function walkRecipeFiles(root) {
-  if (!(0, import_node_fs12.existsSync)(root)) return [];
+  if (!(0, import_node_fs13.existsSync)(root)) return [];
   const out = [];
-  for (const entry of await (0, import_promises8.readdir)(root, { withFileTypes: true })) {
-    const resolved = import_node_path16.default.join(root, entry.name);
+  for (const entry of await (0, import_promises9.readdir)(root, { withFileTypes: true })) {
+    const resolved = import_node_path17.default.join(root, entry.name);
     if (entry.isDirectory()) out.push(...await walkRecipeFiles(resolved));
     else if (entry.isFile() && entry.name === RECIPE_FILE) out.push(resolved);
   }
@@ -12563,7 +13803,7 @@ function bundledRecipeRoot() {
 }
 async function listBundledRecipes(root = bundledRecipeRoot()) {
   const recipes = await Promise.all(
-    (await walkRecipeFiles(import_node_path16.default.resolve(root))).map((file) => readRecipeFile(file, true))
+    (await walkRecipeFiles(import_node_path17.default.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)
@@ -12586,9 +13826,9 @@ function parseSelector(selector) {
   return { id: match[1], version: match[2] };
 }
 async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
-  const local = import_node_path16.default.resolve(target);
-  if ((0, import_node_fs12.existsSync)(local)) {
-    const recipePath = import_node_path16.default.basename(local) === RECIPE_FILE ? local : import_node_path16.default.join(local, RECIPE_FILE);
+  const local = import_node_path17.default.resolve(target);
+  if ((0, import_node_fs13.existsSync)(local)) {
+    const recipePath = import_node_path17.default.basename(local) === RECIPE_FILE ? local : import_node_path17.default.join(local, RECIPE_FILE);
     return readRecipeFile(recipePath, false);
   }
   if (target.startsWith(".") || target.startsWith("/") || target.includes("\\")) {
@@ -12602,8 +13842,8 @@ async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
   return matches[0];
 }
 async function verifyFile(root, file) {
-  const absolute = import_node_path16.default.resolve(root, ...file.path.split("/"));
-  if (!(0, import_node_fs12.existsSync)(absolute)) {
+  const absolute = import_node_path17.default.resolve(root, ...file.path.split("/"));
+  if (!(0, import_node_fs13.existsSync)(absolute)) {
     return { path: file.path, expectedSha256: file.sha256, actualSha256: null, status: "missing" };
   }
   const actualSha256 = await sha256File(absolute);
@@ -12618,7 +13858,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 ? import_node_path16.default.resolve(options.modelRoot) : null;
+  const modelRoot = options.modelRoot ? import_node_path17.default.resolve(options.modelRoot) : null;
   const models = modelRoot ? await Promise.all(loaded.recipe.models.map(async (model) => ({
     ...await verifyFile(modelRoot, model),
     source: model.source,
@@ -12652,7 +13892,7 @@ async function verifyRecipe(target, options = {}) {
   };
 }
 function renderStyle(style, destination, cwd) {
-  const portableDir = import_node_path16.default.relative(cwd, destination).split(import_node_path16.default.sep).join("/") || ".";
+  const portableDir = import_node_path17.default.relative(cwd, destination).split(import_node_path17.default.sep).join("/") || ".";
   const replace = (value) => {
     if (typeof value === "string") return value.replaceAll(RECIPE_DIR_TOKEN, portableDir);
     if (Array.isArray(value)) return value.map(replace);
@@ -12664,25 +13904,25 @@ function renderStyle(style, destination, cwd) {
   return replace(style);
 }
 async function installRecipe(target, options = {}) {
-  const cwd = import_node_path16.default.resolve(options.cwd ?? process.cwd());
+  const cwd = import_node_path17.default.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 ? import_node_path16.default.resolve(cwd, options.out) : import_node_path16.default.join(cwd, "pixelkiln-recipes", ...loaded.recipe.id.split("/"), loaded.recipe.version);
+  const destination = options.out ? import_node_path17.default.resolve(cwd, options.out) : import_node_path17.default.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: import_node_path16.default.join(loaded.dir, ...file.path.split("/")) }))
+    ...loaded.recipe.files.map((file) => ({ path: file.path, source: import_node_path17.default.join(loaded.dir, ...file.path.split("/")) }))
   ];
   const files = await Promise.all(sources.map(async (file) => ({
-    path: import_node_path16.default.join(destination, ...file.path.split("/")),
-    data: await (0, import_promises8.readFile)(file.source)
+    path: import_node_path17.default.join(destination, ...file.path.split("/")),
+    data: await (0, import_promises9.readFile)(file.source)
   })));
   if (!options.force) {
     for (const file of files) {
-      if (!(0, import_node_fs12.existsSync)(file.path)) continue;
-      const current = await (0, import_promises8.readFile)(file.path);
+      if (!(0, import_node_fs13.existsSync)(file.path)) continue;
+      const current = await (0, import_promises9.readFile)(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.`,
@@ -12706,9 +13946,9 @@ async function installRecipe(target, options = {}) {
 }
 
 // src/pipeline/audit.ts
-var import_promises9 = require("fs/promises");
-var import_node_fs13 = require("fs");
-var import_node_path17 = __toESM(require("path"), 1);
+var import_promises10 = require("fs/promises");
+var import_node_fs14 = require("fs");
+var import_node_path18 = __toESM(require("path"), 1);
 function paletteDistance(asset, reference) {
   if (!asset.length || !reference.length) return 0;
   let total = 0;
@@ -12744,12 +13984,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 (!(0, import_node_fs13.existsSync)(output.absolutePath)) {
+      if (!(0, import_node_fs14.existsSync)(output.absolutePath)) {
         missing.push(output.id);
         continue;
       }
       try {
-        const png = decodePng(await (0, import_promises9.readFile)(output.absolutePath));
+        const png = decodePng(await (0, import_promises10.readFile)(output.absolutePath));
         const palette = extractPalette(png, 12);
         assets.push({
           assetId: spec.assetId,
@@ -12773,10 +14013,10 @@ async function auditStyle(loaded, specs, styleId, lock) {
   let referenceFromStyleImages = false;
   const refPalettes = [];
   for (const img of style.styleImages) {
-    const abs = import_node_path17.default.resolve(loaded.root, img.path);
-    if (!(0, import_node_fs13.existsSync)(abs)) continue;
+    const abs = import_node_path18.default.resolve(loaded.root, img.path);
+    if (!(0, import_node_fs14.existsSync)(abs)) continue;
     try {
-      refPalettes.push(extractPalette(decodePng(await (0, import_promises9.readFile)(abs)), 12));
+      refPalettes.push(extractPalette(decodePng(await (0, import_promises10.readFile)(abs)), 12));
     } catch {
     }
   }
@@ -12851,144 +14091,6 @@ function hex(c) {
   return `#${[c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
 }
 
-// src/pixellab-utils.ts
-var import_node_fs14 = require("fs");
-var import_promises10 = require("fs/promises");
-var import_node_path18 = __toESM(require("path"), 1);
-var UNZOOM_MIN_SIDE = 256;
-var UNZOOM_MAX_AREA = 2048 * 2048;
-function defaultUnzoomOut(input) {
-  const ext = import_node_path18.default.extname(input);
-  return `${ext ? input.slice(0, -ext.length) : input}.unzoomed.png`;
-}
-async function unzoomFile(client2, input, opts = {}) {
-  const out = import_node_path18.default.resolve(opts.out ?? defaultUnzoomOut(input));
-  if (import_node_path18.default.resolve(input) === out) throw new Error("unzoom will not overwrite its own input; pass a different --out");
-  if ((0, import_node_fs14.existsSync)(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
-  const bytes = await (0, import_promises10.readFile)(input);
-  const metadata = imageMetadata(bytes);
-  if (!metadata) throw new Error(`${input} is not a readable PNG or JPEG`);
-  const { width, height, format } = metadata;
-  if (width < UNZOOM_MIN_SIDE || height < UNZOOM_MIN_SIDE) {
-    throw new Error(
-      `${input} is ${width}x${height}; PixelLab's unzoom needs at least ${UNZOOM_MIN_SIDE}x${UNZOOM_MIN_SIDE} to find the pixel grid, so this is probably already at its native size`
-    );
-  }
-  if (width * height > UNZOOM_MAX_AREA) {
-    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 (0, import_promises10.mkdir)(import_node_path18.default.dirname(out), { recursive: true });
-  await (0, import_promises10.writeFile)(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 = import_node_path18.default.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 ((0, import_node_fs14.existsSync)(file)) throw new Error(`${file} already exists; pass --force to replace it`);
-    }
-  }
-  const sleep3 = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-  const interval = opts.intervalMs ?? 5e3;
-  const timeout = opts.timeoutMs ?? 10 * 6e4;
-  const submitted = await client2.generateFontPro({
-    description: opts.description,
-    weight: opts.weight,
-    glyphPx: opts.glyphPx,
-    seed: opts.seed,
-    fontName: opts.fontName
-  });
-  const jobId = submitted.background_job_id;
-  const started = Date.now();
-  for (; ; ) {
-    const job = await client2.getFontJob(jobId);
-    opts.onProgress?.(job.status);
-    if (job.status === "failed") throw new Error(`PixelLab font job ${jobId} failed upstream`);
-    if (job.status === "completed") {
-      if (!job.download_ttf_url || !job.download_atlas_url) {
-        throw new Error(`PixelLab font job ${jobId} completed without both download URLs`);
-      }
-      const [ttfBytes, atlasBytes] = await Promise.all([
-        client2.download(job.download_ttf_url),
-        client2.download(job.download_atlas_url)
-      ]);
-      await (0, import_promises10.mkdir)(import_node_path18.default.dirname(ttf), { recursive: true });
-      await (0, import_promises10.writeFile)(ttf, ttfBytes);
-      await (0, import_promises10.writeFile)(atlas, atlasBytes);
-      return { jobId, ttf, atlas, glyphPx: job.glyph_px ?? null, usage: job.usage };
-    }
-    if (Date.now() - started > timeout) {
-      throw new Error(
-        `PixelLab font job ${jobId} is still ${job.status} after ${Math.round(timeout / 1e3)} s; it keeps running upstream, but this command has stopped waiting`
-      );
-    }
-    await sleep3(interval);
-  }
-}
-var PIXELATE_COST_GENERATIONS = 6;
-var PIXELATE_MAX_SIDE = 2048;
-function defaultPixelateOut(input) {
-  const ext = import_node_path18.default.extname(input);
-  return `${ext ? input.slice(0, -ext.length) : input}.pixel.png`;
-}
-async function pixelateFile(client2, input, opts = {}) {
-  const out = import_node_path18.default.resolve(opts.out ?? defaultPixelateOut(input));
-  if (import_node_path18.default.resolve(input) === out) throw new Error("pixelate will not overwrite its own input; pass a different --out");
-  if ((0, import_node_fs14.existsSync)(out) && !opts.force) throw new Error(`${out} already exists; pass --force to replace it`);
-  const bytes = await (0, import_promises10.readFile)(input);
-  const metadata = imageMetadata(bytes);
-  if (!metadata) throw new Error(`${input} is not a readable PNG or JPEG`);
-  const { width, height, format } = metadata;
-  const sleep3 = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-  const interval = opts.intervalMs ?? 5e3;
-  const timeout = opts.timeoutMs ?? 10 * 6e4;
-  const submitted = await client2.imageToPixelartProFlash({
-    image: { base64: bytes.toString("base64"), format },
-    description: opts.description,
-    seed: opts.seed
-  });
-  const jobId = submitted.background_job_id;
-  const started = Date.now();
-  for (; ; ) {
-    const job = await client2.getBackgroundJob(jobId);
-    opts.onProgress?.(job.status);
-    if (job.status === "failed") throw new Error(`PixelLab pixelate job ${jobId} failed upstream`);
-    if (job.status === "completed") {
-      const images = job.last_response?.images;
-      const first = Array.isArray(images) ? images[0] : void 0;
-      if (!first || typeof first.base64 !== "string" || !first.base64) {
-        throw new Error(`PixelLab pixelate job ${jobId} completed without an image at last_response.images[0]`);
-      }
-      const png = Buffer.from(first.base64, "base64");
-      const size = imageMetadata(png);
-      await (0, import_promises10.mkdir)(import_node_path18.default.dirname(out), { recursive: true });
-      await (0, import_promises10.writeFile)(out, png);
-      return {
-        jobId,
-        out,
-        original: { width, height },
-        pixelated: { width: size?.width ?? Number(first.width), height: size?.height ?? Number(first.height) },
-        imageId: submitted.image_id,
-        usage: job.usage ?? null
-      };
-    }
-    if (Date.now() - started > timeout) {
-      throw new Error(
-        `PixelLab pixelate job ${jobId} is still ${job.status} after ${Math.round(timeout / 1e3)} s; it keeps running upstream, but this command has stopped waiting`
-      );
-    }
-    await sleep3(interval);
-  }
-}
-
 // src/pipeline/quality-regression.ts
 var import_node_path19 = __toESM(require("path"), 1);
 var import_node_fs15 = require("fs");
@@ -13800,6 +14902,7 @@ function retireGeneration(entry, retiredAt) {
     billed: entry.billed,
     provider: entry.provider,
     postprocess: entry.postprocess,
+    ...entry.terrainConnect ? { terrainConnect: entry.terrainConnect } : {},
     retiredAt
   };
 }
@@ -13891,6 +14994,9 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
     billed: generation.billed,
     provider: generation.provider,
     postprocess: generation.postprocess,
+    // A connected set comes back with the connection it was drawn from, so
+    // the plan compares the restored generation, not the one it replaced.
+    terrainConnect: generation.terrainConnect,
     history
   });
   await saveLock(lockPath, lock);
@@ -14911,6 +16017,22 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
     const submittedAt = resumesCheckpoint ? previousEntry.submittedAt : (/* @__PURE__ */ new Date()).toISOString();
     const history = historyAfterReplacing(previousEntry, historyLimit(loaded.manifest), submittedAt ?? (/* @__PURE__ */ new Date()).toISOString());
     const outfitParentEntry = spec.character?.kind === "outfit" && spec.character.parentSpec ? lock.entries[lockKey(spec.character.parentSpec.styleId, spec.character.parentSpec.assetId)] : void 0;
+    const terrainLinks = {};
+    const terrainConnect = {};
+    for (const side of ["lower", "upper"]) {
+      const link = spec.terrainConnect?.[side];
+      if (!link) continue;
+      const other = lock.entries[lockKey(link.spec.styleId, link.spec.assetId)];
+      const objectId = other.objectId;
+      const terrainIds = other.providerMetadata?.[provider.id]?.terrainIds;
+      const terrainId = terrainIds?.[link.terrain];
+      terrainLinks[side] = {
+        objectId,
+        terrain: link.terrain,
+        ...typeof terrainId === "string" && terrainId ? { terrainId } : {}
+      };
+      terrainConnect[side] = { sourceAssetId: link.assetId, sourceObjectId: objectId };
+    }
     upsert(lock, key, {
       styleId: spec.styleId,
       assetId: spec.assetId,
@@ -14940,6 +16062,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         ...spec.revision.skeletonTemplate ? { skeletonTemplate: spec.revision.skeletonTemplate } : {},
         ...spec.revision.description ? { description: spec.revision.description } : {},
         ...spec.revision.removalTask ? { removalTask: spec.revision.removalTask } : {},
+        ...spec.revision.convention ? { convention: spec.revision.convention } : {},
         ...spec.revision.driftThreshold == null ? {} : { driftThreshold: spec.revision.driftThreshold },
         ...spec.revision.subjectDescription ? { subjectDescription: spec.revision.subjectDescription } : {},
         ...spec.revision.initialPose ? { initialPose: spec.revision.initialPose } : {},
@@ -14950,6 +16073,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         sourceSha256: mirrorSourceHash(outfitParentEntry),
         referenceSha256: spec.character.outfit.reference.sha256
       } : null,
+      terrainConnect: spec.terrainConnect ? terrainConnect : void 0,
       status: "pending",
       jobId: previousJobId ?? null,
       ...previousJobId ? { submissionComplete: false } : { submissionComplete: void 0 },
@@ -14996,6 +16120,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         ...parentEntry?.objectId ? { parentObjectId: parentEntry.objectId } : {},
         ...anchorEntry?.objectId ? { styleObjectId: anchorEntry.objectId } : {},
         ...parentOutputs ? { parentOutputs } : {},
+        ...spec.terrainConnect ? { terrainLinks } : {},
         ...replacedMetadata ? { replacedMetadata } : {},
         ...lastGenerationMetadata ? { lastGenerationMetadata } : {},
         ...previousMetadata ? { previousMetadata } : {},
@@ -16494,6 +17619,7 @@ var NewAssetSchema = import_zod8.z.object({
       /** A short description of the foreground, sent as PixelLab's text hint. */
       description: import_zod8.z.string().min(1).optional()
     }).strict(),
+    import_zod8.z.object({ mode: import_zod8.z.literal("normal-map"), from: import_zod8.z.string().min(1), convention: NormalMapConventionSchema.optional() }).strict(),
     import_zod8.z.object({
       mode: import_zod8.z.enum(["animate", "animate-pixminimax"]),
       from: import_zod8.z.string().min(1),
@@ -19973,6 +21099,12 @@ async function workspaceStatus(ws, dir) {
   MapScenePlacementSchema,
   MapSceneSchema,
   MediaType,
+  NORMAL_MAP_CONVENTIONS,
+  NORMAL_MAP_COST_GENERATIONS,
+  NORMAL_MAP_MAX_FRAMES,
+  NORMAL_MAP_MAX_SIDE,
+  NORMAL_MAP_MIN_SIDE,
+  NormalMapConventionSchema,
   OverwriteRefusedError,
   PIXELATE_COST_GENERATIONS,
   PIXELATE_MAX_SIDE,
@@ -20000,12 +21132,17 @@ async function workspaceStatus(ws, dir) {
   ScenarioProvider,
   StyleInputSchema,
   StyleSchema,
+  TerrainConnectSchema,
+  TerrainLinkSchema,
+  TerrainSideSchema,
   UNZOOM_MAX_AREA,
   UNZOOM_MIN_SIDE,
   UiElementSchema,
   UiPieceSchema,
   UnsupportedCapabilityError,
   UsageError,
+  VFX_ARTISTS,
+  VFX_ARTIST_MAX_SPRITE,
   VFX_TOOL,
   VfxPartSchema,
   WorkspaceProjectSchema,
@@ -20038,6 +21175,7 @@ async function workspaceStatus(ws, dir) {
   createProvider,
   currentEntryOutputPath,
   currentOutputPath,
+  defaultNormalMapOut,
   defaultOpenCommand,
   defaultPixelateOut,
   defaultUnzoomOut,
@@ -20099,6 +21237,7 @@ async function workspaceStatus(ws, dir) {
   loadWorkspace,
   lockKey,
   makeVfx,
+  makeVfxWithArtist,
   matchOrphanStyle,
   mcpClientFromEnv,
   measureBalanceChange,
@@ -20110,6 +21249,9 @@ async function workspaceStatus(ws, dir) {
   mergePalettes,
   mountSprites,
   mountStyle,
+  normalMapFile,
+  normalMapResultPng,
+  normalMapSizeProblem,
   normalizeLockOutputPaths,
   normalizeRefinementPalette,
   normalizeTerrainTiles,
@@ -20127,6 +21269,7 @@ async function workspaceStatus(ws, dir) {
   parseMcpBody,
   parseProFlashQuote,
   parseTerrainDescriptions,
+  parseVfxArtistResult,
   parseVfxExport,
   parseVfxRecipe,
   parseVfxStep,
@@ -20150,6 +21293,7 @@ async function workspaceStatus(ws, dir) {
   readHandEditCompanion,
   readQualityBaseline,
   readSavedVfxRecipe,
+  readVfxConversation,
   readVfxRecipe,
   recipeDigest,
   referencedHashes,
@@ -20212,6 +21356,7 @@ async function workspaceStatus(ws, dir) {
   submit,
   summarize,
   tagAdopted,
+  terrainCost,
   terrainTileCount,
   tileFeatureOutputCount,
   tileVariationCount,
@@ -20225,6 +21370,13 @@ async function workspaceStatus(ws, dir) {
   validateWorkspace,
   verifyArtifactBundle,
   verifyRecipe,
+  vfxArtistCeiling,
+  vfxArtistFiles,
+  vfxArtistFrameFacts,
+  vfxArtistQuote,
+  vfxArtistSprite,
+  vfxAtlasFrames,
+  vfxJobFailure,
   vfxOutputPaths,
   vfxRecipeSha256,
   withArtifactManifest,