pixelkiln 0.59.0 → 0.60.1

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/types.ts
 import { z } from "zod";
 var MediaTypeSchema = z.enum(["image/png", "image/gif"]);
-var GeneratorSchema = z.enum(["1dir", "map", "pixflux", "tiles", "animation", "frames", "character", "terrain", "imagePro", "isometricTile", "objectPro"]);
+var GeneratorSchema = z.enum(["1dir", "map", "pixflux", "tiles", "animation", "frames", "character", "terrain", "imagePro", "isometricTile", "objectPro", "uiAsset"]);
 var GridConfidenceSchema = z.enum(["low", "medium", "high"]);
 var RevisionModeSchema = z.enum([
   "image-to-image",
@@ -123,6 +123,50 @@ var CharacterProportionsSchema = z.union([
   }).strict()
 ]);
 var CharacterAnimationModeSchema = z.enum(["template", "v3", "pro"]);
+var UiPieceSchema = z.discriminatedUnion("kind", [
+  z.object({
+    id: z.string().min(1),
+    kind: z.literal("rounded_rect"),
+    label: z.string().optional(),
+    x: z.number(),
+    y: z.number(),
+    w: z.number(),
+    h: z.number(),
+    radius: z.number().min(0).optional()
+  }).strict(),
+  z.object({
+    id: z.string().min(1),
+    kind: z.literal("circle"),
+    label: z.string().optional(),
+    x: z.number(),
+    y: z.number(),
+    r: z.number()
+  }).strict(),
+  z.object({
+    id: z.string().min(1),
+    kind: z.literal("polygon"),
+    label: z.string().optional(),
+    x: z.number(),
+    y: z.number(),
+    r: z.number(),
+    sides: z.number().int().min(3),
+    phase: z.number().optional()
+  }).strict()
+]);
+var UiElementSchema = z.enum([
+  "button",
+  "icon_button",
+  "toolbar",
+  "tab",
+  "panel",
+  "window",
+  "health_bar",
+  "avatar",
+  "triangle",
+  "pentagon",
+  "hexagon",
+  "octagon"
+]);
 var AssetBatchSchema = z.object({
   /** The batch leader: another `1dir` asset in the same style. */
   of: z.string().min(1),
@@ -425,6 +469,12 @@ var StyleObjectSchema = z.object({
    * in place of `terrainShapeStyle`. The API default is `standard`.
    */
   terrainMode: z.enum(["standard", "pro"]).optional(),
+  /**
+   * `uiAsset` generator only. A natural-language palette hint sent as-is
+   * (e.g. "brown and gold"), distinct from `palette`'s hex-color array —
+   * this is a prompt-level steer, not a local quantization target.
+   */
+  uiColorPalette: z.string().max(200).optional(),
   /**
    * `terrain` generator only, `terrainMode: "standard"`. Procedural
    * boundary geometry: `square` or `round`, 16px or 32px tiles only.
@@ -708,6 +758,10 @@ var AssetSchema = z.object({
    * `AssetBatchSchema`.
    */
   batch: AssetBatchSchema.optional(),
+  /** `uiAsset` styles: precise shape regions the panel is composited from. Combine with `elements`; omit both for a default full-canvas panel. */
+  pieces: z.array(UiPieceSchema).min(1).optional(),
+  /** `uiAsset` styles: named, auto-positioned UI element scaffolds. Combine with `pieces`; omit both for a default full-canvas panel. */
+  elements: z.array(UiElementSchema).min(1).optional(),
   /** `character` styles, `standard` humanoid bases: this character's proportions, over the style's. */
   proportions: CharacterProportionsSchema.optional(),
   /**
@@ -1225,6 +1279,19 @@ var IsometricTileGetSchema = z2.object({
   image: z2.object({ base64: z2.string().min(1), format: z2.string().default("png") }).passthrough(),
   usage: UsageSchema
 }).passthrough();
+var UiAssetSubmitSchema = z2.object({
+  ui_asset_id: z2.string().min(1),
+  background_job_id: z2.string().min(1),
+  status: z2.string().default("processing"),
+  usage: UsageSchema
+}).passthrough();
+var UiAssetGetSchema = z2.object({
+  id: z2.string().min(1),
+  status: z2.string().nullable().default(null),
+  image_url: z2.string().nullable().optional(),
+  progress_percent: z2.number().nullable().optional(),
+  eta_seconds: z2.number().nullable().optional()
+}).passthrough();
 var RevisionJobSubmitSchema = z2.object({
   background_job_id: z2.string().min(1),
   status: z2.string().default("processing")
@@ -1585,6 +1652,48 @@ var PixelLabClient = class {
     );
     return { image: res.image, usage: res.usage ?? null };
   }
+  /**
+   * `/create-ui-asset`: one composited panel image from a shape template —
+   * `pieces` (precise rect/circle/polygon regions on a virtual 0–512
+   * editor canvas) and/or named `elements` (auto-positioned scaffolds:
+   * button, icon_button, toolbar, tab, panel, window, health_bar, avatar,
+   * triangle, pentagon, hexagon, octagon), or neither for a default
+   * full-canvas rounded-rect panel. Unlike every other generator here, the
+   * result is one flat image with no per-piece sub-regions or nine-slice
+   * metadata returned — cropping a `pieces` layout into separate files
+   * would be pixelkiln's own local work, not modeled yet.
+   */
+  async createUiAsset(args) {
+    const body = {
+      description: args.description,
+      image_size: { width: args.width, height: args.height }
+    };
+    if (args.pieces?.length) body.pieces = args.pieces;
+    if (args.elements?.length) body.elements = args.elements;
+    if (args.styleImage) body.style_image = args.styleImage;
+    if (args.colorPalette) body.color_palette = args.colorPalette;
+    if (args.noBackground != null) body.no_background = args.noBackground;
+    if (args.seed != null) body.seed = args.seed;
+    const res = await validateResponse(
+      UiAssetSubmitSchema,
+      await this.request("/create-ui-asset", { method: "POST", body: JSON.stringify(body) }),
+      "create ui asset"
+    );
+    return { ui_asset_id: res.ui_asset_id, background_job_id: res.background_job_id, usage: res.usage };
+  }
+  async getUiAsset(uiAssetId) {
+    const res = await validateResponse(
+      UiAssetGetSchema,
+      await this.request(`/ui-assets/${encodeURIComponent(uiAssetId)}`),
+      "get ui asset"
+    );
+    return {
+      status: res.status,
+      imageUrl: res.image_url ?? null,
+      progressPercent: res.progress_percent ?? null,
+      etaSeconds: res.eta_seconds ?? null
+    };
+  }
   /**
    * Synchronous single-image generation. Returns the PNG inline rather than a
    * job id, and is the only endpoint that honours a forced palette;
@@ -2722,16 +2831,20 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
       detail: spec.detail ?? null,
       seed: spec.seed ?? null,
       palette: spec.palette,
-      // `noBackground` only reaches the wire for pixflux; the tile fields are
-      // undefined for every other generator. `tileSize` is intentionally
-      // absent; width/height are derived from it, so it is already covered.
-      noBackground: spec.generator === "pixflux" || spec.provider !== "pixellab" ? spec.noBackground : void 0,
+      // `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
+      // already covered.
+      noBackground: spec.generator === "pixflux" || spec.generator === "uiAsset" || spec.provider !== "pixellab" ? spec.noBackground : void 0,
       tileType: spec.tileType,
       tileView: spec.tileView,
       tileFeature: spec.tileFeature,
       outlineMode: spec.outlineMode,
       isometricTileSize: spec.isometricTileSize,
       isometricTileShape: spec.isometricTileShape,
+      uiPieces: spec.uiPieces,
+      uiElements: spec.uiElements,
+      uiColorPalette: spec.uiColorPalette,
       styleImages: styleImageHashes,
       // A character family: the engine and rotations of a base, the parent's
       // generated bytes for a state or animation (so a regenerated parent
@@ -2929,7 +3042,7 @@ var PixelLabProvider = class _PixelLabProvider {
     return new _PixelLabProvider(new PixelLabClient("download-only"));
   }
   supports(generator) {
-    return generator === "1dir" || generator === "map" || generator === "pixflux" || generator === "tiles" || generator === "terrain" || generator === "imagePro" || generator === "character" || generator === "isometricTile" || generator === "objectPro";
+    return generator === "1dir" || generator === "map" || generator === "pixflux" || generator === "tiles" || generator === "terrain" || generator === "imagePro" || generator === "character" || generator === "isometricTile" || generator === "objectPro" || generator === "uiAsset";
   }
   /**
    * `inpaint` (`/inpaint-v3`, a mask) and `image-to-image` (`/edit-images-v2`,
@@ -3045,6 +3158,11 @@ 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 === "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)`
+      );
+    }
     if (spec.generator === "map") {
       requirePixelLabOption("map", "view", spec.view, ["low top-down", "high top-down", "side"]);
       requirePixelLabOption("map", "outline", spec.outline, [
@@ -3682,6 +3800,20 @@ var PixelLabProvider = class _PixelLabProvider {
     if (spec.revision) return this.submitRevision(spec);
     if (spec.generator === "character") return this.submitCharacter(spec, styleImages, context);
     if (spec.generator === "objectPro") return this.submitObjectPro(spec, styleImages, context);
+    if (spec.generator === "uiAsset") {
+      const res2 = await this.client.createUiAsset({
+        description: spec.prompt,
+        width: spec.width,
+        height: spec.height,
+        pieces: spec.uiPieces,
+        elements: spec.uiElements,
+        styleImage: styleImages[0] ? { base64: styleImages[0].base64, format: styleImages[0].format } : void 0,
+        colorPalette: spec.uiColorPalette,
+        noBackground: spec.noBackground,
+        seed: spec.seed
+      });
+      return { jobId: res2.ui_asset_id, metadata: { backgroundJobId: res2.background_job_id } };
+    }
     if (spec.generator === "pixflux") {
       const swatch = spec.palette.length ? paletteSwatch(spec.palette).toString("base64") : void 0;
       const { png } = await this.client.createImagePixflux({
@@ -3958,6 +4090,7 @@ var PixelLabProvider = class _PixelLabProvider {
     if (generator === "imagePro") return this.pollImagePro(jobId);
     if (generator === "character") return this.pollCharacter(jobId, context);
     if (generator === "objectPro") return this.pollObjectPro(jobId, context);
+    if (generator === "uiAsset") return this.pollUiAsset(jobId, context);
     const backgroundJobId = context?.metadata?.backgroundJobId;
     const obj = await this.client.getObject(jobId);
     if (obj.status === "review") {
@@ -4277,6 +4410,29 @@ var PixelLabProvider = class _PixelLabProvider {
       throw err;
     }
   }
+  /**
+   * `/ui-assets/{id}` reports progress with its own `status` field
+   * ("processing"/"completed"/"failed") rather than a 423, and its result is
+   * one flat composited image at a hosted `image_url` — no per-piece
+   * sub-images, no nine-slice metadata, confirmed absent from the response
+   * schema. There is nothing to review: one job is one ready image, like
+   * `isometricTile`.
+   */
+  async pollUiAsset(uiAssetId, context) {
+    const asset = await this.client.getUiAsset(uiAssetId);
+    if (asset.status === "failed") return { status: "failed", error: "UI asset generation failed upstream" };
+    if (asset.status !== "completed" || !asset.imageUrl) {
+      return { status: "processing", progressPercent: asset.progressPercent, etaSeconds: asset.etaSeconds };
+    }
+    const backgroundJobId = context?.metadata?.backgroundJobId;
+    return {
+      status: "ready",
+      objectId: uiAssetId,
+      sourceUrl: asset.imageUrl,
+      sources: [{ url: asset.imageUrl }],
+      billed: await this.billedForJob(backgroundJobId)
+    };
+  }
   async selectCandidate(jobId, index, commonTag, generator) {
     if (generator === "tiles") {
       const set = await this.client.getTilesPro(jobId);
@@ -7057,6 +7213,10 @@ async function resolveSpecs(loaded, filter) {
         size = asset.size ?? style.size ?? 64;
         width = size;
         height = size;
+      } else if (generator === "uiAsset") {
+        width = asset.width ?? style.size ?? 256;
+        height = asset.height ?? style.size ?? 256;
+        size = Math.max(width, height);
       } else {
         width = asset.width ?? style.size ?? 64;
         height = asset.height ?? style.size ?? 64;
@@ -7067,6 +7227,11 @@ async function resolveSpecs(loaded, filter) {
           `assets.${assetId}: ${asset.state ? "state" : "animation"} needs a character or objectPro 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}`
+        );
+      }
       const characterKind = asset.animation ? "animation" : asset.state ? "state" : "base";
       const subject = asset.promptByStyle[styleId] ?? asset.prompt ?? "";
       let terrainLowerDescription;
@@ -7113,6 +7278,9 @@ async function resolveSpecs(loaded, filter) {
         shading: style.shading,
         detail: style.detail,
         seed: style.seed,
+        uiPieces: generator === "uiAsset" ? asset.pieces : void 0,
+        uiElements: generator === "uiAsset" ? asset.elements : void 0,
+        uiColorPalette: generator === "uiAsset" ? style.uiColorPalette : void 0,
         palette: style.palette,
         enforcePalette: style.enforcePalette,
         noBackground: style.noBackground,
@@ -16223,6 +16391,8 @@ export {
   ScenarioProvider,
   StyleInputSchema,
   StyleSchema,
+  UiElementSchema,
+  UiPieceSchema,
   UnsupportedCapabilityError,
   UsageError,
   WorkspaceProjectSchema,