pixelkiln 0.48.0 → 0.50.0

package/dist/cli.js

@@ -938,17 +938,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 +983,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.
    *
@@ -5125,6 +5167,10 @@ var TilesProSchema = z2.object({
   kind: z2.string().nullable().default(null),
   tile_rules: z2.record(z2.unknown()).nullable().optional()
 }).passthrough();
+var RevisionJobSubmitSchema = z2.object({
+  background_job_id: z2.string().min(1),
+  status: z2.string().default("processing")
+}).passthrough();
 var PixelLabObjectSchema = z2.object({
   id: z2.string().min(1),
   name: z2.string().nullable().default(null),
@@ -5341,9 +5387,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;
@@ -5596,6 +5653,71 @@ var PixelLabClient = class {
       if (page.characters.length === 0 || offset >= page.total) return;
     }
   }
+  /**
+   * 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"). 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
+   * naturally," which is the opposite of what a mask boundary is for.
+   */
+  async inpaintV3(args) {
+    const size = { width: args.width, height: args.height };
+    const body = {
+      description: args.description,
+      inpainting_image: { image: args.image, size },
+      mask_image: { image: args.maskImage, size }
+    };
+    if (args.noBackground != null) body.no_background = args.noBackground;
+    if (args.cropToMask != null) body.crop_to_mask = args.cropToMask;
+    if (args.seed != null) body.seed = args.seed;
+    return validateResponse(
+      RevisionJobSubmitSchema,
+      await this.request("/inpaint-v3", { method: "POST", body: JSON.stringify(body) }),
+      "inpaint-v3"
+    );
+  }
+  /**
+   * 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. 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 = {
+      method: "edit_with_text",
+      description: args.description,
+      edit_images: [{ image: args.image, width: args.width, height: args.height }],
+      image_size: { width: args.width, height: args.height }
+    };
+    if (args.noBackground != null) body.no_background = args.noBackground;
+    if (args.seed != null) body.seed = args.seed;
+    return validateResponse(
+      RevisionJobSubmitSchema,
+      await this.request("/edit-images-v2", { method: "POST", body: JSON.stringify(body) }),
+      "edit-images-v2"
+    );
+  }
   async getBackgroundJob(jobId) {
     const raw = await this.request(`/background-jobs/${encodeURIComponent(jobId)}`);
     return validateResponse(BackgroundJobSchema, raw, "background-jobs/{id}");
@@ -5736,6 +5858,15 @@ var PixelLabProvider = class _PixelLabProvider {
   supports(generator) {
     return generator === "1dir" || generator === "map" || generator === "pixflux" || generator === "tiles" || generator === "character";
   }
+  /**
+   * `inpaint` (`/inpaint-v3`, a mask) and `image-to-image` (`/edit-images-v2`,
+   * no mask) both exist on PixelLab. `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";
+  }
   /** PixelLab's own constraints: submissions must be >2s apart, and
    *  background jobs in flight are capped by subscription tier (Tier 1=8,
    *  Tier 2=10, Tier 3=20); 8 is the safe floor across every tier. */
@@ -5756,6 +5887,11 @@ var PixelLabProvider = class _PixelLabProvider {
     return dir;
   }
   estimate(spec) {
+    if (spec.revision) {
+      const width = spec.revision.sourceWidth ?? spec.width;
+      const height = spec.revision.sourceHeight ?? spec.height;
+      return { unit: "generations", amount: generationCost(width, height, "1dir"), candidates: 1 };
+    }
     if (spec.generator === "tiles") {
       return { unit: "generations", amount: spec.cost, candidates: spec.candidates };
     }
@@ -5769,6 +5905,12 @@ var PixelLabProvider = class _PixelLabProvider {
     };
   }
   validate(spec, styleImages) {
+    if (spec.revision?.mode === "inpaint") {
+      const { sourceWidth: width, sourceHeight: height } = spec.revision;
+      if (width != null && height != null && (width < 32 || height < 32 || width > 512 || height > 512)) {
+        throw new Error(`PixelLab inpaint source is ${width}x${height}; the API takes 32 to 512 pixels per side`);
+      }
+    }
     if (spec.generator === "1dir" && (spec.width < 32 || spec.width > 256)) {
       throw new Error("PixelLab 1dir dimensions must be between 32 and 256 pixels");
     }
@@ -6118,6 +6260,7 @@ var PixelLabProvider = class _PixelLabProvider {
   }
   async submit(spec, styleImages, context) {
     this.validate(spec, styleImages);
+    if (spec.revision) return this.submitRevision(spec);
     if (spec.generator === "character") return this.submitCharacter(spec, styleImages, context);
     if (spec.generator === "pixflux") {
       const swatch = spec.palette.length ? paletteSwatch(spec.palette).toString("base64") : void 0;
@@ -6137,9 +6280,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,
@@ -6169,6 +6323,60 @@ var PixelLabProvider = class _PixelLabProvider {
     });
     return { jobId: res.object_id, metadata: { backgroundJobId: res.background_job_id } };
   }
+  /**
+   * `inpaint` reads the mask as PixelLab's own convention: white marks the
+   * area to generate, black the area to preserve (`InpaintV3Request`'s own
+   * field description). Unlike ComfyUI's revision graph, there is no
+   * configurable side to this — document it as fixed rather than leave an
+   * agent to guess, the way docs/REVISIONS.md tells a ComfyUI author to test
+   * their own graph.
+   */
+  async submitRevision(spec) {
+    const revision = spec.revision;
+    if (!revision.sourceSha256 || !revision.sourceFormat || revision.sourceWidth == null || revision.sourceHeight == null) {
+      throw new Error(`${spec.styleId}/${spec.assetId}: revision source is not ready`);
+    }
+    const sourceBytes = readFileSync2(revision.sourceFile);
+    if (sha256(sourceBytes) !== revision.sourceSha256) {
+      throw new Error(`${spec.styleId}/${spec.assetId}: revision source changed after the manifest was resolved`);
+    }
+    const image = { base64: sourceBytes.toString("base64"), format: revision.sourceFormat };
+    const width = revision.sourceWidth;
+    const height = revision.sourceHeight;
+    if (revision.mode === "inpaint") {
+      if (!revision.maskFile || !revision.maskSha256 || !revision.maskFormat) {
+        throw new Error(`${spec.styleId}/${spec.assetId}: revision mask is not ready`);
+      }
+      const maskBytes = readFileSync2(revision.maskFile);
+      if (sha256(maskBytes) !== revision.maskSha256) {
+        throw new Error(`${spec.styleId}/${spec.assetId}: revision mask changed after the manifest was resolved`);
+      }
+      const res2 = await this.client.inpaintV3({
+        description: spec.prompt,
+        image,
+        width,
+        height,
+        maskImage: { base64: maskBytes.toString("base64"), format: revision.maskFormat },
+        noBackground: spec.noBackground,
+        seed: spec.seed
+      });
+      return { jobId: res2.background_job_id };
+    }
+    if (revision.strength != null) {
+      throw new Error(
+        `${spec.styleId}/${spec.assetId}: PixelLab image-to-image revisions take no strength; edit-images-v2 always applies the full instruction`
+      );
+    }
+    const res = await this.client.editImagesV2({
+      description: spec.prompt,
+      image,
+      width,
+      height,
+      noBackground: spec.noBackground,
+      seed: spec.seed
+    });
+    return { jobId: res.background_job_id };
+  }
   /**
    * What a background job actually billed, once its own record is still
    * around to ask; see `billedFromUsage`. A stale or already-cleaned-up job
@@ -6185,6 +6393,7 @@ var PixelLabProvider = class _PixelLabProvider {
     }
   }
   async poll(jobId, generator, context) {
+    if (context?.spec?.revision) return this.pollRevision(jobId);
     if (generator === "pixflux") {
       const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
       if (existsSync7(file)) {
@@ -6215,6 +6424,59 @@ var PixelLabProvider = class _PixelLabProvider {
       etaSeconds: obj.eta_seconds ?? null
     };
   }
+  /**
+   * `/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}`. 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);
+    if (job.status === "failed") return { status: "failed", error: "revision job failed upstream" };
+    if (job.status !== "completed") return { status: "processing" };
+    const billed = billedFromUsage(job.usage);
+    const done = job.last_response ?? {};
+    const urlKeys = ["image_url", "download_url", "url", "output_url"];
+    for (const key of urlKeys) {
+      const url = done[key];
+      if (typeof url === "string" && url) {
+        return { status: "ready", objectId: jobId, sourceUrl: url, sources: [{ url }], billed };
+      }
+    }
+    const imageKeys = ["image", "output_image", "result_image", "edited_image"];
+    for (const key of imageKeys) {
+      const candidate = done[key];
+      const base64 = extractBase64(candidate);
+      if (base64) {
+        const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+        writeFileSync(file, Buffer.from(base64, "base64"));
+        const sourceUrl = `file://${file}`;
+        return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed };
+      }
+    }
+    if (Array.isArray(done.images) && done.images.length) {
+      const base64 = extractBase64(done.images[0]);
+      if (base64) {
+        const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+        writeFileSync(file, Buffer.from(base64, "base64"));
+        const sourceUrl = `file://${file}`;
+        return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed };
+      }
+    }
+    return {
+      status: "failed",
+      error: `Invalid PixelLab response for revision job ${jobId}: completed with no recognized image field (got: ${Object.keys(done).join(", ") || "no keys"}); update pollRevision in src/providers/pixellab.ts with the real shape`
+    };
+  }
   /**
    * Map objects need their own path because the `/map-objects/{id}` record is
    * deleted upstream roughly 8 hours after creation while the image survives in
@@ -6406,6 +6668,15 @@ function firstUrl(urls) {
   if (!urls) return null;
   return Object.values(urls).find((u) => typeof u === "string") ?? null;
 }
+function extractBase64(value) {
+  if (typeof value === "string" && value) return value;
+  if (value && typeof value === "object") {
+    const obj = value;
+    if (typeof obj.base64 === "string" && obj.base64) return obj.base64;
+    if (obj.image) return extractBase64(obj.image);
+  }
+  return null;
+}
 function readReference(spec, reference) {
   const images = {};
   for (const [direction, image] of Object.entries(reference)) {
@@ -7663,9 +7934,20 @@ 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,
         ...generator === "character" ? { character: await resolveCharacterShape(asset, style, characterKind, { root, load: loadStyleImage }) } : {},
         cost: generator === "tiles" ? tilesCost(tileSize, tileVariations) : generationCost(width, height, generator),
@@ -10926,7 +11208,9 @@ function describeHistory(media, entry, cacheDir) {
       retiredAt: generation.retiredAt,
       outputs,
       cached: outputs.length > 0 && outputs.every((output) => output.url !== null),
-      upstreamUrl: generation.provider === "pixellab" ? pixelLabObjectUrl(generation.generator, generation.objectId) : null
+      // A revision's jobId is a plain background job id, not a PixelLab
+      // account object: there is no `/create-object` page to point at.
+      upstreamUrl: generation.provider === "pixellab" && !entry.revision ? pixelLabObjectUrl(generation.generator, generation.objectId) : null
     };
   });
 }
@@ -11191,7 +11475,7 @@ async function buildGallerySnapshot(opts) {
       editChanged,
       editStatus,
       editMeta,
-      upstreamUrl: entry?.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
+      upstreamUrl: entry?.provider === "pixellab" && !spec.revision ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
       refreshable: Boolean(entry && entry.status === "downloaded" && entry.outputs.length && (entry.sourceUrls?.length || entry.sourceUrl)),
       history: entry ? describeHistory(media, entry, cacheDir) : [],
       tags: spec.tags,
@@ -11255,7 +11539,7 @@ async function buildGallerySnapshot(opts) {
       editChanged: [],
       editStatus: null,
       editMeta: null,
-      upstreamUrl: entry.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
+      upstreamUrl: entry.provider === "pixellab" && !entry.revision ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
       refreshable: false,
       history: describeHistory(media, entry, cacheDir),
       tags: [],