pixelkiln 0.50.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()
@@ -1019,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.
    *
@@ -1132,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",
@@ -5157,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),
@@ -5167,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")
@@ -5198,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),
@@ -5418,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;
@@ -5856,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`,
@@ -5892,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") {
@@ -5936,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(
@@ -6302,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,
@@ -6407,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);
@@ -6545,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);
@@ -7895,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;
@@ -7907,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,
@@ -7949,10 +8192,21 @@ async function resolveSpecs(loaded, filter) {
         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([
@@ -8000,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") {