pixelkiln 0.58.0 → 0.60.0

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,56 @@ 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),
+  /** 1-based slot in the batch (the leader is implicitly slot 0). Unique and contiguous among siblings. */
+  index: z.number().int().min(1)
+}).strict();
 var CharacterStateSchema = z.object({
   /** The base character, or another state, in the same style. */
   of: z.string().min(1),
@@ -419,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.
@@ -696,6 +752,16 @@ var AssetSchema = z.object({
    * `prompt` instead.
    */
   animation: CharacterAnimationSchema.optional(),
+  /**
+   * `1dir` styles only: this asset rides along on another `1dir` asset's
+   * batch submission instead of generating on its own. See
+   * `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(),
   /**
@@ -772,7 +838,7 @@ var AssetSchema = z.object({
       path: ["revision"]
     });
   }
-  const shapes = [asset.revision && "revision", asset.state && "state", asset.animation && "animation", asset.mirror && "mirror"].filter(Boolean);
+  const shapes = [asset.revision && "revision", asset.state && "state", asset.animation && "animation", asset.mirror && "mirror", asset.batch && "batch"].filter(Boolean);
   if (shapes.length > 1) {
     context.addIssue({
       code: z.ZodIssueCode.custom,
@@ -923,6 +989,12 @@ var LockEntrySchema = z.object({
     sourceAssetId: z.string().min(1),
     sourceSha256: z.string().regex(/^[0-9a-f]{64}$/)
   }).strict().nullable().default(null),
+  /** For a `1dir` batch member: which leader and slot it rode along on. */
+  batch: z.object({
+    role: z.enum(["leader", "member"]),
+    leaderAssetId: z.string().min(1).optional(),
+    index: z.number().int().min(1).optional()
+  }).strict().nullable().default(null),
   /**
    * Output hashes owned by the previous generation while its replacement is
    * pending. They authorize replacing only unchanged PixelKiln-owned files.
@@ -1207,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")
@@ -1567,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;
@@ -1973,14 +2100,15 @@ var PixelLabClient = class {
   /**
    * `/reduce-colors`, PixelLab's "Cleanup" tier: quantize one image onto a
    * smaller palette, synchronously — no `background_job_id`, the result
-   * comes back in this same response, like `createImagePixflux`. Verified
-   * against the live OpenAPI schema, not exercised against a live account:
-   * the schema's own response example is `usage: {type: "usd", usd: 0.02}`,
-   * which — going by this codebase's own repeated experience with PixelLab's
-   * documented-vs-billed cost mismatches (`isometricTile`, `objectPro`) —
-   * should not be trusted over a real call. `numColors` and `paletteImage`
-   * are mutually exclusive upstream; the manifest schema already enforces
-   * that before this is ever called.
+   * comes back in this same response, like `createImagePixflux`. The
+   * schema's own response example is dollar-denominated (`usage: {type:
+   * "usd", usd: 0.02}`), which — matching this codebase's repeated
+   * experience with PixelLab's documented-vs-billed cost mismatches
+   * (`isometricTile`, `objectPro`) — did not hold: confirmed live against a
+   * Tier 2 account at exactly 0.1 generations for a 32x32 source
+   * (docs/REVISIONS.md). `numColors` and `paletteImage` are mutually
+   * exclusive upstream; the manifest schema already enforces that before
+   * this is ever called.
    */
   async reduceColors(args) {
     const body = { images: [args.image] };
@@ -2003,8 +2131,9 @@ var PixelLabClient = class {
   /**
    * `/correct-pixelart`, PixelLab's "Cleanup" tier: sharpen edges and drop
    * stray pixels without resizing, synchronously — same shape as
-   * `reduceColors` above, no background job. Cost is likewise unverified
-   * against a live account (schema example: `usage: {type: "usd", usd: 0.02}`).
+   * `reduceColors` above, no background job. Cost is likewise confirmed
+   * live at 0.1 generations for a 32x32 source, not the schema's own
+   * dollar-denominated example (`usage: {type: "usd", usd: 0.02}`).
    */
   async correctPixelart(args) {
     const body = { images: [args.image] };
@@ -2702,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
@@ -2760,6 +2893,11 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
       // A mirror's bytes come from its source's recorded outputs; the plan
       // compares those directly, so only the choice of source is identity.
       mirror: spec.mirror ? { of: spec.mirror.sourceAssetId } : void 0,
+      // The whole group's ordered descriptions, not just this asset's own —
+      // any sibling's prompt changing, or a member being added or removed,
+      // must mark every member stale together, since they all ride on one
+      // submitted job with no way to amend it after the fact.
+      batch: spec.batch ? { role: spec.batch.role, itemDescriptions: spec.batch.itemDescriptions, index: spec.batch.index } : void 0,
       revision: spec.revision ? {
         mode: spec.revision.mode,
         from: spec.revision.sourceAssetId,
@@ -2904,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`,
@@ -2941,6 +3079,9 @@ var PixelLabProvider = class _PixelLabProvider {
     return dir;
   }
   estimate(spec) {
+    if (spec.batch?.role === "member") {
+      return { unit: "generations", amount: 0, candidates: 1 };
+    }
     if (spec.revision?.mode === "reduce-colors" || spec.revision?.mode === "correct-pixelart") {
       return { unit: "generations", amount: 0.1, candidates: 1 };
     }
@@ -3017,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, [
@@ -3654,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({
@@ -3739,11 +3899,21 @@ var PixelLabProvider = class _PixelLabProvider {
       return { jobId: res2.background_job_id };
     }
     if (spec.generator === "1dir") {
+      if (spec.batch?.role === "member") {
+        throw new Error(`${spec.styleId}/${spec.assetId}: a batch member cannot submit on its own`);
+      }
       const res2 = await this.client.create1Direction({
         description: spec.prompt,
         size: spec.size,
         view: spec.view === "sidescroller" ? "sidescroller" : "top-down",
-        styleImages
+        styleImages,
+        // The leader's own subject is item_descriptions[0], so `description`
+        // matches it exactly. Confirmed live: item_descriptions[0] owns
+        // candidate slot 0 (a 3-item batch returned exactly the declared
+        // items at frames 0/1/2, in order; docs/GENERATORS.md#1dir), so
+        // sending the same text as `description` too is redundant but
+        // harmless, not a hedge against ambiguity.
+        itemDescriptions: spec.batch?.role === "leader" ? spec.batch.itemDescriptions : void 0
       });
       return { jobId: res2.object_id, metadata: { backgroundJobId: res2.background_job_id } };
     }
@@ -3920,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") {
@@ -4239,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);
@@ -7019,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;
@@ -7029,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;
@@ -7075,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,
@@ -7153,6 +7359,14 @@ async function resolveSpecs(loaded, filter) {
       };
       styleSpecs.set(assetId, resolved);
     }
+    const batchMembersByLeader = /* @__PURE__ */ new Map();
+    for (const id of styleSpecs.keys()) {
+      const batch = manifest.assets[id].batch;
+      if (!batch) continue;
+      const members = batchMembersByLeader.get(batch.of) ?? [];
+      members.push({ id, index: batch.index });
+      batchMembersByLeader.set(batch.of, members);
+    }
     const finalized = /* @__PURE__ */ new Set();
     const finalize = async (assetId) => {
       const resolved = styleSpecs.get(assetId);
@@ -7311,6 +7525,56 @@ async function resolveSpecs(loaded, filter) {
           ...asset.revision.enhancePrompt == null ? {} : { enhancePrompt: asset.revision.enhancePrompt }
         };
       }
+      if (asset.batch) {
+        if (asset.batch.of === assetId) throw new Error(`assets.${assetId}: a batch cannot name itself as its own leader`);
+        const leaderSpec = await finalize(asset.batch.of);
+        if (!leaderSpec.batch || leaderSpec.batch.role !== "leader") {
+          throw new Error(`assets.${assetId}: ${asset.batch.of} is not a 1dir batch leader`);
+        }
+        if (resolved.size !== leaderSpec.size) {
+          throw new Error(
+            `assets.${assetId}: batch members share the leader's canvas size; ${asset.batch.of} is ${leaderSpec.size}px, this is ${resolved.size}px`
+          );
+        }
+        resolved.batch = {
+          role: "member",
+          itemDescriptions: leaderSpec.batch.itemDescriptions,
+          index: asset.batch.index,
+          leaderAssetId: asset.batch.of,
+          leaderSpec
+        };
+      } else {
+        const members = batchMembersByLeader.get(assetId);
+        if (members) {
+          if (style.generator !== "1dir") {
+            throw new Error(`assets.${assetId}: only a 1dir asset can lead a batch`);
+          }
+          const sorted = [...members].sort((a, b) => a.index - b.index);
+          const seen = /* @__PURE__ */ new Set();
+          for (const { index } of sorted) {
+            if (seen.has(index)) throw new Error(`assets.${assetId}: two batch members both claim index ${index}`);
+            seen.add(index);
+          }
+          const expectedIndices = sorted.map((_, i) => i + 1).join(",");
+          if (sorted.map((m) => m.index).join(",") !== expectedIndices) {
+            throw new Error(
+              `assets.${assetId}: batch member indices must be 1..${sorted.length} with no gaps; got ${sorted.map((m) => m.index).join(",")}`
+            );
+          }
+          const total = 1 + sorted.length;
+          const limit = candidateCount(resolved.size);
+          if (total > limit) {
+            throw new Error(
+              `assets.${assetId}: a ${resolved.size}px batch holds at most ${limit} items (1 leader + ${limit - 1} members); this one declares ${total}`
+            );
+          }
+          resolved.batch = {
+            role: "leader",
+            itemDescriptions: [resolved.prompt, ...sorted.map(({ id }) => styleSpecs.get(id).prompt)],
+            memberAssetIds: sorted.map((m) => m.id)
+          };
+        }
+      }
       resolved.specHash = specHash(
         resolved,
         styleImageHashes,
@@ -11696,6 +11960,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
   for (const styleId of new Set(items.map((i) => i.spec.styleId))) {
     styleImages.set(styleId, await resolveStyleImages(loaded, styleId));
   }
+  const byKey = new Map(items.map((item) => [item.key, item]));
   let submitted = 0;
   let failed = 0;
   let spent = 0;
@@ -11725,8 +11990,62 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       await pruneInFlight();
     }
   }
+  function writeBatchMembers(leaderSpec, leaderKey, error) {
+    if (leaderSpec.batch?.role !== "leader") return;
+    const leaderEntry = lock.entries[leaderKey];
+    for (const memberAssetId of leaderSpec.batch.memberAssetIds ?? []) {
+      const memberKey = lockKey(leaderSpec.styleId, memberAssetId);
+      const memberItem = byKey.get(memberKey);
+      if (!memberItem) {
+        throw new Error(
+          `${leaderKey}: batch member "${memberAssetId}" must be submitted in the same run as its leader; run without --only, or include every sibling`
+        );
+      }
+      const memberSpec = memberItem.spec;
+      const memberEstimate = estimates.get(memberKey);
+      const previousMemberEntry = lock.entries[memberKey];
+      const memberSubmittedAt = leaderEntry.submittedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+      upsert(lock, memberKey, {
+        styleId: memberSpec.styleId,
+        assetId: memberSpec.assetId,
+        specHash: memberSpec.specHash,
+        generator: memberSpec.generator,
+        prompt: memberSpec.prompt,
+        width: memberSpec.width,
+        height: memberSpec.height,
+        batch: { role: "member", leaderAssetId: leaderSpec.assetId, index: memberSpec.batch.index },
+        status: error ? "failed" : "processing",
+        error,
+        jobId: error ? null : leaderEntry.jobId,
+        submissionComplete: error ? void 0 : true,
+        reviewObjectId: error ? null : leaderEntry.reviewObjectId,
+        objectId: null,
+        candidateIndex: null,
+        outputs: [],
+        supersededOutputs: previousMemberEntry?.outputs.length ? previousMemberEntry.outputs : previousMemberEntry?.supersededOutputs ?? [],
+        providerMetadata: leaderEntry.providerMetadata,
+        sourceUrl: null,
+        sourceUrls: [],
+        submittedAt: memberSubmittedAt,
+        history: historyAfterReplacing(previousMemberEntry, historyLimit(loaded.manifest), memberSubmittedAt),
+        cost: memberEstimate.amount,
+        costUnit: memberEstimate.unit,
+        provider: provider.id,
+        downloadedAt: null
+      });
+      if (error) failed++;
+      else {
+        submitted++;
+        spent += memberEstimate.amount;
+        log(`  ${memberKey} \u2192 ${leaderEntry.jobId}  (rides on ${leaderKey}'s batch)`);
+      }
+    }
+  }
   for (const { spec, key } of items) {
     const estimate = estimates.get(key);
+    if (spec.batch?.role === "member") {
+      continue;
+    }
     if (spec.mirror) {
       try {
         await requireRevisionReady(spec, lock);
@@ -11759,6 +12078,14 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
     const since = Date.now() - lastSubmitAt;
     if (since < spacing) await sleep(spacing - since);
     await requireRevisionReady(spec, lock);
+    if (spec.batch?.role === "leader") {
+      const missing = (spec.batch.memberAssetIds ?? []).filter((id) => !byKey.has(lockKey(spec.styleId, id)));
+      if (missing.length) {
+        throw new Error(
+          `${key}: batch member(s) ${missing.join(", ")} must be submitted in the same run as this leader; run without --only, or include every sibling`
+        );
+      }
+    }
     const previousEntry = lock.entries[key];
     const resumesCheckpoint = Boolean(
       previousEntry?.specHash === spec.specHash && previousEntry.provider === provider.id && previousEntry.generator === spec.generator && previousEntry.submissionComplete === false && previousEntry.jobId
@@ -11864,6 +12191,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       inFlight.set(jobId, spec);
       submitted++;
       spent += estimate.amount;
+      writeBatchMembers(spec, key, null);
       log(
         `  ${key} \u2192 ${jobId}  (${spec.width}x${spec.height}` + (estimate.candidates > 1 ? `, ${estimate.candidates} ${spec.tileFeature ? "outputs" : "candidates"}` : "") + `, ${estimate.amount})`
       );
@@ -11875,6 +12203,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         inFlight.set(entry.jobId, spec);
         submitted++;
         spent += estimate.amount;
+        writeBatchMembers(spec, key, null);
         log(`  ${key} \u2192 ${entry.jobId}  (recovered from completed checkpoint)`);
       } else {
         failed++;
@@ -11883,6 +12212,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
           error: message6,
           cost: entry.jobId ? estimate.amount : 0
         });
+        writeBatchMembers(spec, key, message6);
         log(`  FAILED ${key}: ${message6}`);
       }
     }
@@ -12474,6 +12804,9 @@ function renderSheet(groups, options = {}) {
   .cand.active { border-color:var(--dim); box-shadow:0 0 0 2px color-mix(in srgb, var(--dim) 20%, transparent); }
   .cand.sel { border-color:var(--ok); box-shadow:0 0 0 3px color-mix(in srgb, var(--ok) 22%, transparent); }
   .cand.set-frame { cursor:pointer; }
+  .cand.recommended:not(.sel) { border-color:var(--accent); }
+  .cand.recommended .badge { position:absolute; top:-1px; left:-1px; font-size:9.5px; font-weight:650;
+    text-transform:uppercase; letter-spacing:.03em; color:var(--bg); background:var(--accent); padding:1px 5px; }
   .cand img { image-rendering:pixelated; display:block;
     background-image:
       linear-gradient(45deg,#0000 25%,#7f7f7f22 25%,#7f7f7f22 75%,#0000 75%),
@@ -12631,14 +12964,17 @@ GROUPS.forEach((g, gi) => {
       }).observe(loop);
     }
   }
+  const recommended = g.recommendedIndex ?? 0;
   g.frameUrls.forEach((url, i) => {
     const c = document.createElement('button');
     c.type = 'button';
-    c.className = 'cand' + (g.mode === 'frame-set' ? ' set-frame' : '');
+    c.className = 'cand' + (g.mode === 'frame-set' ? ' set-frame' : '') +
+      (g.recommendedIndex != null && i === recommended ? ' recommended' : '');
     c.tabIndex = -1;
-    c.setAttribute('aria-label', g.mode === 'frame-set'
+    c.setAttribute('aria-label', (g.mode === 'frame-set'
       ? 'Accept ordered frame set from frame ' + (i + 1)
-      : 'Choose candidate ' + (i + 1) + ' of ' + g.frameUrls.length);
+      : 'Choose candidate ' + (i + 1) + ' of ' + g.frameUrls.length) +
+      (g.recommendedIndex != null && i === recommended ? ' (this asset\u2019s declared slot)' : ''));
 
     const preview = document.createElement('img');
     preview.className = 'preview';
@@ -12651,6 +12987,12 @@ GROUPS.forEach((g, gi) => {
     index.textContent = (g.frameLabels?.[i] || String(i + 1)) + ' \xB7 ' +
       g.width + '\xD7' + g.height + ' \xB7 ' + scaleLabel;
     c.append(preview, index);
+    if (g.recommendedIndex != null && i === recommended) {
+      const badge = document.createElement('span');
+      badge.className = 'badge';
+      badge.textContent = 'declared';
+      c.append(badge);
+    }
     if (displayScale > 1 && largestSide <= 96) {
       const actual = document.createElement('img');
       actual.className = 'actual';
@@ -12675,6 +13017,7 @@ GROUPS.forEach((g, gi) => {
   });
   frames.dataset.active = '0';
   frames.querySelector('.cand')?.classList.add('active');
+  if (recommended > 0) activate(recommended, frames);
   root.appendChild(el);
 });
 
@@ -12930,7 +13273,11 @@ async function prepareReview(provider, lock, opts = {}) {
             height: spec.revision.sourceHeight
           }
         } : {},
-        ...current && currentRoute ? { current: { url: currentRoute, width: current.width, height: current.height } } : {}
+        ...current && currentRoute ? { current: { url: currentRoute, width: current.width, height: current.height } } : {},
+        // A batch member's declared slot in the shared candidate set — the
+        // leader's own slot 0 is already the sheet's ordinary default, so
+        // only a member (whose slot is 1+) needs to say so explicitly.
+        ...entry.batch?.index != null ? { recommendedIndex: entry.batch.index } : {}
       });
     } catch (err) {
       log(`  could not load candidates for ${key}: ${err instanceof Error ? err.message : String(err)}`);
@@ -15977,6 +16324,7 @@ async function workspaceStatus(ws, dir) {
   };
 }
 export {
+  AssetBatchSchema,
   AssetSchema,
   BudgetError,
   CHARACTER_DIRECTIONS_4,
@@ -16043,6 +16391,8 @@ export {
   ScenarioProvider,
   StyleInputSchema,
   StyleSchema,
+  UiElementSchema,
+  UiPieceSchema,
   UnsupportedCapabilityError,
   UsageError,
   WorkspaceProjectSchema,