pixelkiln 0.49.0 → 0.51.0

package/dist/cli.js

@@ -707,7 +707,7 @@ import path2 from "path";
 // src/types.ts
 import { z } from "zod";
 var MediaTypeSchema = z.enum(["image/png", "image/gif"]);
-var GeneratorSchema = z.enum(["1dir", "map", "pixflux", "tiles", "animation", "frames", "character"]);
+var GeneratorSchema = z.enum(["1dir", "map", "pixflux", "tiles", "animation", "frames", "character", "terrain"]);
 var GridConfidenceSchema = z.enum(["low", "medium", "high"]);
 var RevisionModeSchema = z.enum(["image-to-image", "inpaint", "outpaint"]);
 function tileVariationCount(descriptions) {
@@ -740,6 +740,14 @@ function tilesCost(tileSize, variations) {
   if (px <= 2048) return 25;
   return 40;
 }
+function terrainTileCount(transitionSize) {
+  return transitionSize === 1 ? 25 : 16;
+}
+function parseTerrainDescriptions(prompt) {
+  const parts = prompt.split(/\d+\s*\)\s*\./).map((part) => part.trim()).filter(Boolean);
+  if (parts.length < 2) return null;
+  return { lower: parts[0], upper: parts[1], transition: parts[2] };
+}
 var StyleImageSchema = z.object({
   /** Path to a PNG/JPEG, relative to the manifest; the active provider validates limits. */
   path: z.string()
@@ -938,17 +946,37 @@ var StyleObjectSchema = z.object({
   shading: z.string().optional(),
   detail: z.string().optional(),
   /**
-   * `tiles` generator only. Edge length of one tile, 16-256.
+   * `tiles` generator only. Edge length of one tile, 16-128 (the API's own
+   * range; connectable sets narrow it further per shape, e.g. square
+   * top-down roads are fixed at 32).
    *
    * Ignored when `styleImages` is set: style mode takes the tile's shape
    * and dimensions from the reference image, which is the whole reason to
    * use it against an existing sheet.
    */
-  tileSize: z.number().int().min(16).max(256).optional(),
+  tileSize: z.number().int().min(16).max(128).optional(),
+  /** `tiles` generator only. Height in pixels (16-256) for a non-square
+   *  tile (e.g. a tall building wall); omit to compute it from `tileType`
+   *  geometry and the view angle. */
+  tileHeight: z.number().int().min(16).max(256).optional(),
   /** `tiles` generator only. Defaults to the API's `isometric`. */
   tileType: z.enum(["hex", "hex_pointy", "isometric", "oblique", "octagon", "square_topdown"]).optional(),
   /** `tiles` generator only. Defaults to the API's `low top-down`. */
   tileView: z.enum(["top-down", "high top-down", "low top-down", "side"]).optional(),
+  /** `tiles` generator only. Continuous view angle in degrees (0 = side,
+   *  90 = top-down), overriding `tileView` when set. */
+  tileViewAngle: z.number().min(0).max(90).optional(),
+  /** `tiles` generator only. Tile depth/thickness as a ratio (0-1) of the
+   *  tile's height, overriding the default the API computes from the
+   *  view. This is the tutorials' "thickness" control. */
+  tileDepthRatio: z.number().min(0).max(1).optional(),
+  /** `tiles` generator only, `tileType: "isometric"`. Top/bottom cap
+   *  width in pixels: 2 for the classic look, 4 for a more modern one. */
+  tileFlatTopPx: z.number().int().min(2).max(8).optional(),
+  /** `tiles` generator only, `tileType: "oblique"` (ground tiles or
+   *  building walls). Horizontal shear per pixel of height (0-1); 0.5 is
+   *  a classic cabinet projection (~27°), 1.0 a full 45° diagonal. */
+  obliqueLean: z.number().min(0).max(1).optional(),
   /**
    * `tiles` generator only. Asks for a connectable set instead of
    * independent variations:
@@ -963,6 +991,28 @@ var StyleObjectSchema = z.object({
    * is load-bearing; do not sort a connectable set by anything else.
    */
   tileFeature: z.enum(["roads", "tileset", "building"]).optional(),
+  /** `tileFeature: "building"` only. Wall height in tiles (1-3); the API
+   *  defaults to 2. */
+  buildingWallTiles: z.number().int().min(1).max(3).optional(),
+  /** `tileFeature: "building"` only. `"grid"` paints each shaped piece
+   *  individually (richer, the isometric default); `"materials"` paints
+   *  flat swatches and renders pieces from them (more consistent for
+   *  square top-down building kits). */
+  buildingLayout: z.enum(["grid", "materials"]).optional(),
+  /** `tileFeature: "building"` only. Wall material, e.g. "stone brick
+   *  walls" — more reliable than relying on the main `prompt` being split
+   *  into wall/floor parts. */
+  buildingWallDescription: z.string().min(1).max(500).optional(),
+  /** `tileFeature: "building"` only. Floor material, e.g. "wooden plank
+   *  floor". */
+  buildingFloorDescription: z.string().min(1).max(500).optional(),
+  /** `tileFeature: "building"` only. Upper-storey or roof surface;
+   *  defaults to the wall material when omitted. */
+  buildingFloor2Description: z.string().min(1).max(500).optional(),
+  /** `tileFeature: "building"` with `tileType: "square_topdown"` only.
+   *  Wall storey height as its own camera angle in degrees (5-90),
+   *  decoupled from the ground's pitch. */
+  buildingWallAngle: z.number().min(5).max(90).optional(),
   /**
    * `tiles` generator only. How tile edges are drawn.
    *
@@ -977,6 +1027,48 @@ var StyleObjectSchema = z.object({
    * rather than inheriting.
    */
   outlineMode: z.enum(["outline", "segmentation"]).optional(),
+  /**
+   * `terrain` generator only. Edge length of one tile in pixels. 16 or 32
+   * work in both modes; 64 needs `terrainMode: "pro"`. The API default is
+   * 16. See `parseTerrainDescriptions` for how an asset's `prompt` becomes
+   * the lower/upper/transition terrain descriptions this endpoint wants.
+   */
+  terrainTileSize: z.union([z.literal(16), z.literal(32), 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`.
+   */
+  terrainMode: z.enum(["standard", "pro"]).optional(),
+  /**
+   * `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`.
+   */
+  terrainShapeStyle: z.enum(["square", "round"]).optional(),
+  /** `terrain` generator only, `terrainMode: "pro"`. Boundary spread
+   *  between terrains (0 = steep, 1 = gradual). API default 0.5. */
+  terrainSpreadX: 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. */
+  terrainSlopeSize: z.number().min(0).max(1).optional(),
+  /** `terrain` generator only, `terrainMode: "pro"`. Terrain boundary
+   *  noise (0 = smooth, 1 = rough). API default 0. */
+  terrainRaggedness: z.number().min(0).max(1).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.
+   */
+  terrainTransitionSize: z.number().min(0).max(1).optional(),
+  /** `terrain` generator only. Camera angle; the API default is `high
+   *  top-down`. */
+  terrainView: z.enum(["low top-down", "high top-down"]).optional(),
   /**
    * `pixflux` only. Whether to strip the generated background.
    *
@@ -1090,7 +1182,7 @@ var StyleSchema = StyleObjectSchema.refine((s) => !(s.tileFeature && s.styleImag
   message: "tileFeature and styleImages cannot be combined; a connectable set derives its own tile geometry, so remove one or the other",
   path: ["tileFeature"]
 }).superRefine((style, ctx) => {
-  if (style.quality && (style.generator === "tiles" || style.generator === "animation")) {
+  if (style.quality && (style.generator === "tiles" || style.generator === "terrain" || style.generator === "animation")) {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
       message: "quality profiles currently support single-image generators only",
@@ -5115,6 +5207,11 @@ var MapSubmitSchema = z2.object({
   object_id: z2.string().min(1),
   status: z2.string().default("processing")
 }).passthrough();
+var UsageSchema = z2.object({
+  type: z2.string().optional(),
+  usd: z2.number().nullable().optional(),
+  generations: z2.number().nullable().optional()
+}).passthrough().nullable().optional();
 var TilesSubmitSchema = z2.object({
   tile_id: z2.string().min(1),
   background_job_id: z2.string().min(1),
@@ -5125,6 +5222,32 @@ var TilesProSchema = z2.object({
   kind: z2.string().nullable().default(null),
   tile_rules: z2.record(z2.unknown()).nullable().optional()
 }).passthrough();
+var TilesetSubmitSchema = z2.object({
+  tileset_id: z2.string().min(1),
+  background_job_id: z2.string().min(1),
+  status: z2.literal("processing").default("processing")
+}).passthrough();
+var TilesetTileSchema = z2.object({
+  id: z2.string().min(1),
+  name: z2.string(),
+  image: z2.object({ base64: z2.string().min(1), format: z2.string().default("png") }).passthrough(),
+  corners: z2.object({ NW: z2.string(), NE: z2.string(), SW: z2.string(), SE: z2.string() }).passthrough(),
+  pattern_4x4: z2.object({
+    row_0: z2.array(z2.number()),
+    row_1: z2.array(z2.number()),
+    row_2: z2.array(z2.number()),
+    row_3: z2.array(z2.number())
+  }).passthrough()
+}).passthrough();
+var TilesetGetSchema = z2.object({
+  tileset: z2.object({
+    total_tiles: z2.number().int().min(1),
+    tile_size: z2.object({ width: z2.number().int().positive(), height: z2.number().int().positive() }).passthrough(),
+    terrain_types: z2.array(z2.string()),
+    tiles: z2.array(TilesetTileSchema).min(1)
+  }).passthrough(),
+  usage: UsageSchema
+}).passthrough();
 var RevisionJobSubmitSchema = z2.object({
   background_job_id: z2.string().min(1),
   status: z2.string().default("processing")
@@ -5156,11 +5279,6 @@ var MapObjectSchema = z2.object({
 var ObjectListSchema = z2.object({ objects: z2.array(PixelLabObjectSchema), total: z2.number().int().min(0) }).passthrough();
 var PixfluxResponseSchema = z2.object({ image: z2.object({ base64: z2.string().min(1) }).passthrough(), usage: z2.unknown().optional() }).passthrough();
 var SelectFramesSchema = z2.object({ created_object_ids: z2.array(z2.string()) }).passthrough();
-var UsageSchema = z2.object({
-  type: z2.string().optional(),
-  usd: z2.number().nullable().optional(),
-  generations: z2.number().nullable().optional()
-}).passthrough().nullable().optional();
 var CharacterSubmitSchema = z2.object({
   background_job_id: z2.string().min(1),
   character_id: z2.string().min(1),
@@ -5345,9 +5463,20 @@ var PixelLabClient = class {
   async createTilesPro(args) {
     const body = { description: args.description };
     if (args.tileSize != null) body.tile_size = args.tileSize;
+    if (args.tileHeight != null) body.tile_height = args.tileHeight;
     if (args.tileType) body.tile_type = args.tileType;
     if (args.tileView) body.tile_view = args.tileView;
+    if (args.tileViewAngle != null) body.tile_view_angle = args.tileViewAngle;
+    if (args.tileDepthRatio != null) body.tile_depth_ratio = args.tileDepthRatio;
+    if (args.tileFlatTopPx != null) body.tile_flat_top_px = args.tileFlatTopPx;
+    if (args.obliqueLean != null) body.oblique_lean = args.obliqueLean;
     if (args.tileFeature) body.tile_feature = args.tileFeature;
+    if (args.buildingWallTiles != null) body.building_wall_tiles = args.buildingWallTiles;
+    if (args.buildingLayout) body.building_layout = args.buildingLayout;
+    if (args.buildingWallDescription) body.building_wall_description = args.buildingWallDescription;
+    if (args.buildingFloorDescription) body.building_floor_description = args.buildingFloorDescription;
+    if (args.buildingFloor2Description) body.building_floor2_description = args.buildingFloor2Description;
+    if (args.buildingWallAngle != null) body.building_wall_angle = args.buildingWallAngle;
     if (args.outlineMode) body.outline_mode = args.outlineMode;
     if (args.seed != null) body.seed = args.seed;
     if (args.styleImages?.length) body.style_images = args.styleImages;
@@ -5365,6 +5494,45 @@ var PixelLabClient = class {
       "get tiles"
     );
   }
+  /**
+   * `/create-tileset`: two named terrain levels (`lower`/`upper`) and the
+   * transition between them, laid out as a Wang corner set. Unlike
+   * `/create-tiles-pro`, the descriptions are separate fields the API itself
+   * places on the terrain vertex grid, not one prompt it splits by number.
+   */
+  async createTileset(args) {
+    const body = {
+      lower_description: args.lowerDescription,
+      upper_description: args.upperDescription
+    };
+    if (args.transitionDescription) body.transition_description = args.transitionDescription;
+    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.transitionSize != null) body.transition_size = args.transitionSize;
+    if (args.view) body.view = args.view;
+    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", { method: "POST", body: JSON.stringify(body) }),
+      "create tileset"
+    );
+  }
+  /** Throws PixelLabError(423) while the set is still drawing; see Tileset. */
+  async getTileset(tilesetId) {
+    const res = await validateResponse(
+      TilesetGetSchema,
+      await this.request(`/tilesets/${tilesetId}`),
+      "get tileset"
+    );
+    return { tileset: res.tileset, usage: res.usage ?? null };
+  }
   /**
    * Synchronous single-image generation. Returns the PNG inline rather than a
    * job id, and is the only endpoint that honours a forced palette;
@@ -5603,13 +5771,21 @@ var PixelLabClient = class {
   /**
    * Masked inpaint, PixelLab's `/inpaint-v3` (the endpoint its own docs list
    * first in the Inpaint section, its convention for "reach for this by
-   * default"). Unlike the rest of this client, this method's shape is taken
-   * from the OpenAPI spec, not exercised against a live account: the request
-   * side is exact (`InpaintV3Request`), but a completed job's `last_response`
-   * has no documented example for this endpoint (the spec's only worked
-   * example is a character job's shape). `pollRevision` in pixellab.ts reads
-   * it defensively and fails loudly on an unrecognized shape rather than
-   * guessing.
+   * default"). Exercised live at nine sizes, all returning `last_response.
+   * image` as a single `{type, base64, width, height}` (the first shape
+   * `pollRevision` in pixellab.ts checks, so no change was ever needed):
+   * 32x32 (1024px², billed 20, this adapter's tiering floor) through
+   * 256x256 (65536px²) all billed 20 (the tiering wrongly predicts 25 from
+   * 1024px² up, see estimate() in pixellab.ts); 288x288 (82944px²) and
+   * 320x320 (102400px²) billed 25 — the middle tier is real, just starting
+   * far higher than this tiering assumes; 352x352 (123904px²), 384x384
+   * (147456px²), and 512x512 (262144px², the tiering ceiling) all billed
+   * 40. Both breakpoints are now tightly bracketed: 20->25 in
+   * (65536px², 82944px²], 25->40 in (102400px², 123904px²].
+   * `editImagesV2` below returns the same fields under `images`, plural
+   * and array-wrapped, not `image` — do not assume the two endpoints share
+   * one response shape. See docs/ENDPOINTS.md and docs/REVISIONS.md for
+   * the full shape and cost picture, including what is still unconfirmed.
    *
    * `crop_to_mask` defaults true upstream (confirmed in the schema): PixelLab
    * otherwise blends generated pixels outside the mask edge to "fit
@@ -5632,11 +5808,15 @@ var PixelLabClient = class {
     );
   }
   /**
-   * Whole-image edit with no mask, PixelLab's `/edit-images-v2`. Same
-   * not-yet-live-verified caveat as `inpaintV3` above. `edit_images` takes an
-   * array (the endpoint supports editing several images with one
+   * Whole-image edit with no mask, PixelLab's `/edit-images-v2`. `edit_images`
+   * takes an array (the endpoint supports editing several images with one
    * instruction); pixelkiln's `revision` model is one parent per child, so
-   * this always sends exactly one.
+   * this always sends exactly one. Exercised live at its floor size (32x32):
+   * billed exactly the 20-generation estimate this adapter borrows from
+   * `1dir`, matching `inpaintV3`'s floor exactly. The completed response is
+   * `last_response.images`, an *array* of `{type, base64, width, height}` —
+   * plural and array-wrapped, unlike `inpaintV3`'s singular `image` above,
+   * even though exactly one image is ever sent or expected here.
    */
   async editImagesV2(args) {
     const body = {
@@ -5791,7 +5971,7 @@ var PixelLabProvider = class _PixelLabProvider {
     return new _PixelLabProvider(new PixelLabClient("download-only"));
   }
   supports(generator) {
-    return generator === "1dir" || generator === "map" || generator === "pixflux" || generator === "tiles" || generator === "character";
+    return generator === "1dir" || generator === "map" || generator === "pixflux" || generator === "tiles" || generator === "terrain" || generator === "character";
   }
   /**
    * `inpaint` (`/inpaint-v3`, a mask) and `image-to-image` (`/edit-images-v2`,
@@ -5827,7 +6007,7 @@ var PixelLabProvider = class _PixelLabProvider {
       const height = spec.revision.sourceHeight ?? spec.height;
       return { unit: "generations", amount: generationCost(width, height, "1dir"), candidates: 1 };
     }
-    if (spec.generator === "tiles") {
+    if (spec.generator === "tiles" || spec.generator === "terrain") {
       return { unit: "generations", amount: spec.cost, candidates: spec.candidates };
     }
     if (spec.generator === "character") {
@@ -5871,10 +6051,55 @@ var PixelLabProvider = class _PixelLabProvider {
         "high detail"
       ]);
     }
+    if (spec.generator === "terrain") {
+      if (spec.outline) {
+        requirePixelLabOption("outline", spec.outline, [
+          "single color black outline",
+          "single color outline",
+          "selective outline",
+          "lineless"
+        ]);
+      }
+      if (spec.shading) {
+        requirePixelLabOption("shading", spec.shading, [
+          "flat shading",
+          "basic shading",
+          "medium shading",
+          "detailed shading",
+          "highly detailed shading"
+        ]);
+      }
+      if (spec.detail) {
+        requirePixelLabOption("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.generator === "character") this.validateCharacter(spec, styleImages);
     if ((spec.generator === "map" || spec.generator === "pixflux") && styleImages.length) {
       throw new Error(`PixelLab ${spec.generator} does not support style images`);
     }
+    if (spec.generator === "terrain" && styleImages.length) {
+      throw new Error(
+        "PixelLab terrain does not support style images yet; use color_image/reference images directly against /create-tileset if this becomes a real need"
+      );
+    }
     for (const image of styleImages) {
       if (image.width > 256 || image.height > 256) {
         throw new Error(
@@ -6215,9 +6440,20 @@ var PixelLabProvider = class _PixelLabProvider {
       const res2 = await this.client.createTilesPro({
         description: spec.prompt,
         tileSize: spec.tileSize,
+        tileHeight: spec.tileHeight,
         tileType: spec.tileType,
         tileView: spec.tileView,
+        tileViewAngle: spec.tileViewAngle,
+        tileDepthRatio: spec.tileDepthRatio,
+        tileFlatTopPx: spec.tileFlatTopPx,
+        obliqueLean: spec.obliqueLean,
         tileFeature: spec.tileFeature,
+        buildingWallTiles: spec.buildingWallTiles,
+        buildingLayout: spec.buildingLayout,
+        buildingWallDescription: spec.buildingWallDescription,
+        buildingFloorDescription: spec.buildingFloorDescription,
+        buildingFloor2Description: spec.buildingFloor2Description,
+        buildingWallAngle: spec.buildingWallAngle,
         outlineMode: spec.outlineMode,
         seed: spec.seed,
         // TilesProStyleImage is flat and wants the reference's real dimensions,
@@ -6226,6 +6462,26 @@ var PixelLabProvider = class _PixelLabProvider {
       });
       return { jobId: res2.tile_id, metadata: { backgroundJobId: res2.background_job_id } };
     }
+    if (spec.generator === "terrain") {
+      const res2 = await this.client.createTileset({
+        lowerDescription: spec.terrainLowerDescription,
+        upperDescription: spec.terrainUpperDescription,
+        transitionDescription: spec.terrainTransitionDescription,
+        tileSize: spec.terrainTileSize,
+        mode: spec.terrainMode,
+        shapeStyle: spec.terrainShapeStyle,
+        spreadX: spec.terrainSpreadX,
+        slopeSize: spec.terrainSlopeSize,
+        raggedness: spec.terrainRaggedness,
+        transitionSize: spec.terrainTransitionSize,
+        view: spec.terrainView,
+        outline: spec.outline,
+        shading: spec.shading,
+        detail: spec.detail,
+        seed: spec.seed
+      });
+      return { jobId: res2.tileset_id, metadata: { backgroundJobId: res2.background_job_id } };
+    }
     if (spec.generator === "1dir") {
       const res2 = await this.client.create1Direction({
         description: spec.prompt,
@@ -6331,6 +6587,7 @@ var PixelLabProvider = class _PixelLabProvider {
     }
     if (generator === "map") return this.pollMap(jobId, context);
     if (generator === "tiles") return this.pollTiles(jobId, Boolean(context?.tileFeature), context);
+    if (generator === "terrain") return this.pollTerrain(jobId, context);
     if (generator === "character") return this.pollCharacter(jobId, context);
     const backgroundJobId = context?.metadata?.backgroundJobId;
     const obj = await this.client.getObject(jobId);
@@ -6351,16 +6608,17 @@ var PixelLabProvider = class _PixelLabProvider {
   /**
    * `/inpaint-v3` and `/edit-images-v2` both hand back a plain background
    * job with no resource of its own, polled generically at
-   * `GET /background-jobs/{id}`. What a *completed* job's `last_response`
-   * actually contains is not documented for either endpoint: the OpenAPI
-   * spec's only worked example of that field is a character job's shape
-   * (`character_id`, `uploaded_directions`, ...), not an inpaint or edit
-   * job's. This reads every image shape seen elsewhere in this client
-   * (a nested `{image: {base64, format}}`, a bare `{base64, format}`, or a
-   * hosted URL under a handful of plausible keys) and fails loudly, naming
-   * the keys it actually got, rather than guess wrong silently. Fixing a
-   * real completed response into this list is a one-line change once one is
-   * seen live.
+   * `GET /background-jobs/{id}`. Confirmed live for both, and the two do not
+   * match: a completed `inpaint-v3` job's `last_response.image` is a single
+   * `{type: "base64", base64, width, height}`, matched by the `imageKeys`
+   * branch below; a completed `edit-images-v2` job's is `last_response.images`,
+   * an *array* of that same shape, matched by the `done.images` branch below
+   * instead — exactly why both branches exist rather than just the first one
+   * (docs/ENDPOINTS.md, docs/REVISIONS.md). Beyond these two confirmed
+   * shapes, this also checks a nested `{image: {base64, format}}` and a
+   * hosted URL under a handful of plausible keys, and fails loudly, naming
+   * the keys it actually got, rather than guess wrong silently, for whatever
+   * shape still isn't covered.
    */
   async pollRevision(jobId) {
     const job = await this.client.getBackgroundJob(jobId);
@@ -6468,6 +6726,43 @@ var PixelLabProvider = class _PixelLabProvider {
       throw err;
     }
   }
+  /**
+   * `/create-tileset` reports progress the same way `tiles` does (423 while
+   * drawing, 200 once finished), but each tile's image comes back embedded
+   * as base64 rather than a `storage_urls` link, so it is decoded straight
+   * to a cache file the same way a revision result is (`pollRevision`). A
+   * terrain set is always a connectable Wang tileset, never independent
+   * candidates to review, so this goes straight to "ready" like a connectable
+   * `tiles` set does.
+   */
+  async pollTerrain(tilesetId, context) {
+    try {
+      const { tileset, usage } = await this.client.getTileset(tilesetId);
+      const backgroundJobId = context?.metadata?.backgroundJobId;
+      const billed = billedFromUsage(usage) ?? await this.billedForJob(backgroundJobId);
+      const sources = [];
+      const terrainTiles = [];
+      for (const [index, tile] of tileset.tiles.entries()) {
+        const slug = tile.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "tile";
+        const role = `tile-${String(index).padStart(2, "0")}-${slug}`;
+        const file = path12.join(_PixelLabProvider.cacheDir(), `${tilesetId}-${index}.png`);
+        writeFileSync(file, Buffer.from(tile.image.base64, "base64"));
+        sources.push({ url: `file://${file}`, role });
+        terrainTiles.push({ role, corners: tile.corners, pattern4x4: tile.pattern_4x4 });
+      }
+      return {
+        status: "ready",
+        objectId: tilesetId,
+        sourceUrl: sources[0]?.url ?? null,
+        sources,
+        metadata: { terrainTypes: tileset.terrain_types, terrainTiles },
+        billed
+      };
+    } catch (err) {
+      if (err instanceof PixelLabError && err.status === 423) return { status: "processing" };
+      throw err;
+    }
+  }
   async selectCandidate(jobId, index, commonTag, generator) {
     if (generator === "tiles") {
       const set = await this.client.getTilesPro(jobId);
@@ -7818,6 +8113,10 @@ async function resolveSpecs(loaded, filter) {
         size = asset.state?.canvas ? Math.max(asset.state.canvas.width, asset.state.canvas.height) : asset.size ?? style.size ?? 64;
         width = asset.state?.canvas?.width ?? size;
         height = asset.state?.canvas?.height ?? size;
+      } else if (generator === "terrain") {
+        size = style.terrainTileSize ?? 16;
+        width = size;
+        height = size;
       } else {
         width = asset.width ?? style.size ?? 64;
         height = asset.height ?? style.size ?? 64;
@@ -7830,12 +8129,33 @@ async function resolveSpecs(loaded, filter) {
       }
       const characterKind = asset.animation ? "animation" : asset.state ? "state" : "base";
       const subject = asset.promptByStyle[styleId] ?? asset.prompt ?? "";
-      const prompt = generator === "character" && characterKind !== "base" ? subject.trim() : [style.promptPrefix, subject, style.promptSuffix].map((p) => p.trim()).filter(Boolean).join(", ");
+      let terrainLowerDescription;
+      let terrainUpperDescription;
+      let terrainTransitionDescription;
+      let prompt;
+      if (generator === "terrain") {
+        const parsed = parseTerrainDescriptions(subject);
+        if (!parsed) {
+          throw new Error(
+            `assets.${assetId}: terrain needs "1). <lower terrain> 2). <upper terrain>" in its prompt, optionally followed by "3). <transition>"`
+          );
+        }
+        const wrap = (text) => [style.promptPrefix, text, style.promptSuffix].map((p) => p.trim()).filter(Boolean).join(", ");
+        terrainLowerDescription = wrap(parsed.lower);
+        terrainUpperDescription = wrap(parsed.upper);
+        terrainTransitionDescription = parsed.transition ? wrap(parsed.transition) : void 0;
+        prompt = subject.trim();
+      } else if (generator === "character" && characterKind !== "base") {
+        prompt = subject.trim();
+      } else {
+        prompt = [style.promptPrefix, subject, style.promptSuffix].map((p) => p.trim()).filter(Boolean).join(", ");
+      }
       const relFile = asset.file ?? path13.join(asset.category ?? "", `${assetId}.png`);
       const outFile = path13.resolve(root, style.outDir, relFile);
       const qualityOutFile = style.quality ? path13.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 base = {
         styleId,
         assetId,
@@ -7857,14 +8177,36 @@ async function resolveSpecs(loaded, filter) {
         enforcePalette: style.enforcePalette,
         noBackground: style.noBackground,
         tileSize: generator === "tiles" ? tileSize : void 0,
+        tileHeight: generator === "tiles" ? style.tileHeight : void 0,
         tileType: generator === "tiles" ? style.tileType : void 0,
         tileView: generator === "tiles" ? style.tileView : void 0,
+        tileViewAngle: generator === "tiles" ? style.tileViewAngle : void 0,
+        tileDepthRatio: generator === "tiles" ? style.tileDepthRatio : void 0,
+        tileFlatTopPx: generator === "tiles" ? style.tileFlatTopPx : void 0,
+        obliqueLean: generator === "tiles" ? style.obliqueLean : void 0,
         tileFeature: generator === "tiles" ? style.tileFeature : void 0,
+        buildingWallTiles: generator === "tiles" ? style.buildingWallTiles : void 0,
+        buildingLayout: generator === "tiles" ? style.buildingLayout : void 0,
+        buildingWallDescription: generator === "tiles" ? style.buildingWallDescription : void 0,
+        buildingFloorDescription: generator === "tiles" ? style.buildingFloorDescription : void 0,
+        buildingFloor2Description: generator === "tiles" ? style.buildingFloor2Description : void 0,
+        buildingWallAngle: generator === "tiles" ? style.buildingWallAngle : void 0,
         outlineMode: generator === "tiles" ? style.outlineMode : void 0,
+        terrainLowerDescription: generator === "terrain" ? terrainLowerDescription : void 0,
+        terrainUpperDescription: generator === "terrain" ? terrainUpperDescription : void 0,
+        terrainTransitionDescription: generator === "terrain" ? terrainTransitionDescription : void 0,
+        terrainTileSize: generator === "terrain" ? size : void 0,
+        terrainMode: generator === "terrain" ? style.terrainMode : void 0,
+        terrainShapeStyle: generator === "terrain" ? style.terrainShapeStyle : void 0,
+        terrainSpreadX: generator === "terrain" ? style.terrainSpreadX : void 0,
+        terrainSlopeSize: generator === "terrain" ? style.terrainSlopeSize : void 0,
+        terrainRaggedness: generator === "terrain" ? style.terrainRaggedness : void 0,
+        terrainTransitionSize: generator === "terrain" ? style.terrainTransitionSize : void 0,
+        terrainView: generator === "terrain" ? style.terrainView : void 0,
         ...generator === "character" ? { character: await resolveCharacterShape(asset, style, characterKind, { root, load: loadStyleImage }) } : {},
-        cost: generator === "tiles" ? tilesCost(tileSize, tileVariations) : generationCost(width, height, generator),
+        cost: generator === "tiles" ? tilesCost(tileSize, tileVariations) : generator === "terrain" ? tilesCost(size, terrainTiles) : generationCost(width, height, generator),
         costUnit: "generations",
-        candidates: generator === "tiles" ? tileVariations : generator === "1dir" ? candidateCount(size) : 1
+        candidates: generator === "tiles" ? tileVariations : generator === "terrain" ? terrainTiles : generator === "1dir" ? candidateCount(size) : 1
       };
       const tags = [
         .../* @__PURE__ */ new Set([
@@ -7912,7 +8254,7 @@ async function resolveSpecs(loaded, filter) {
       if (asset.mirror) {
         if (asset.mirror === assetId) throw new Error(`assets.${assetId}: an asset cannot mirror itself`);
         const sourceSpec = await finalize(asset.mirror);
-        if (sourceSpec.generator === "tiles") {
+        if (sourceSpec.generator === "tiles" || sourceSpec.generator === "terrain") {
           throw new Error(`assets.${assetId}: a tile set cannot be mirrored; its edges carry meaning`);
         }
         if (sourceSpec.character?.kind === "animation") {