pixelkiln 0.58.0 → 0.59.0

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AssetBatchSchema: () => AssetBatchSchema,
   AssetSchema: () => AssetSchema,
   BudgetError: () => BudgetError,
   CHARACTER_DIRECTIONS_4: () => CHARACTER_DIRECTIONS_4,
@@ -427,6 +428,12 @@ var CharacterProportionsSchema = import_zod.z.union([
   }).strict()
 ]);
 var CharacterAnimationModeSchema = import_zod.z.enum(["template", "v3", "pro"]);
+var AssetBatchSchema = import_zod.z.object({
+  /** The batch leader: another `1dir` asset in the same style. */
+  of: import_zod.z.string().min(1),
+  /** 1-based slot in the batch (the leader is implicitly slot 0). Unique and contiguous among siblings. */
+  index: import_zod.z.number().int().min(1)
+}).strict();
 var CharacterStateSchema = import_zod.z.object({
   /** The base character, or another state, in the same style. */
   of: import_zod.z.string().min(1),
@@ -1000,6 +1007,12 @@ var AssetSchema = import_zod.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(),
   /** `character` styles, `standard` humanoid bases: this character's proportions, over the style's. */
   proportions: CharacterProportionsSchema.optional(),
   /**
@@ -1076,7 +1089,7 @@ var AssetSchema = import_zod.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: import_zod.z.ZodIssueCode.custom,
@@ -1227,6 +1240,12 @@ var LockEntrySchema = import_zod.z.object({
     sourceAssetId: import_zod.z.string().min(1),
     sourceSha256: import_zod.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: import_zod.z.object({
+    role: import_zod.z.enum(["leader", "member"]),
+    leaderAssetId: import_zod.z.string().min(1).optional(),
+    index: import_zod.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.
@@ -2277,14 +2296,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] };
@@ -2307,8 +2327,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] };
@@ -3064,6 +3085,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,
@@ -3245,6 +3271,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 };
     }
@@ -4043,11 +4072,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 } };
     }
@@ -7457,6 +7496,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);
@@ -7615,6 +7662,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,
@@ -12000,6 +12097,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;
@@ -12029,8 +12127,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);
@@ -12063,6 +12215,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
@@ -12168,6 +12328,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})`
       );
@@ -12179,6 +12340,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++;
@@ -12187,6 +12349,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}`);
       }
     }
@@ -12778,6 +12941,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%),
@@ -12935,14 +13101,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';
@@ -12955,6 +13124,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';
@@ -12979,6 +13154,7 @@ GROUPS.forEach((g, gi) => {
   });
   frames.dataset.active = '0';
   frames.querySelector('.cand')?.classList.add('active');
+  if (recommended > 0) activate(recommended, frames);
   root.appendChild(el);
 });
 
@@ -13234,7 +13410,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)}`);
@@ -16282,6 +16462,7 @@ async function workspaceStatus(ws, dir) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AssetBatchSchema,
   AssetSchema,
   BudgetError,
   CHARACTER_DIRECTIONS_4,