pixelkiln 0.28.0 → 0.30.0

package/dist/index.js

@@ -544,11 +544,11 @@ var PixelLabClient = class {
    * common than the failure mode of retrying (a duplicate object), and a
    * duplicate is visible and free to delete whereas a silent gap is neither.
    */
-  async request(path27, init, attempt = 0) {
+  async request(path29, init, attempt = 0) {
     const auth = this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`;
     let res;
     try {
-      res = await fetch(`${BASE}${path27}`, {
+      res = await fetch(`${BASE}${path29}`, {
         ...init,
         signal: init?.signal ?? AbortSignal.timeout(this.timeoutMs),
         headers: {
@@ -560,24 +560,24 @@ var PixelLabClient = class {
     } catch (err) {
       if (attempt < MAX_RETRIES) {
         await sleep(backoffMs(attempt));
-        return this.request(path27, init, attempt + 1);
+        return this.request(path29, init, attempt + 1);
       }
       throw err;
     }
     if (!res.ok && shouldRetry(res.status) && attempt < MAX_RETRIES) {
       const waitMs = retryAfterMs(res.headers.get("retry-after")) ?? backoffMs(attempt);
       await sleep(waitMs);
-      return this.request(path27, init, attempt + 1);
+      return this.request(path29, init, attempt + 1);
     }
     const text = await res.text();
     if (!res.ok) {
-      throw new PixelLabError(`${init?.method ?? "GET"} ${path27} \u2192 ${res.status}`, res.status, text);
+      throw new PixelLabError(`${init?.method ?? "GET"} ${path29} \u2192 ${res.status}`, res.status, text);
     }
     if (!text) return {};
     try {
       return JSON.parse(text);
     } catch {
-      throw new Error(`${init?.method ?? "GET"} ${path27} returned invalid JSON`);
+      throw new Error(`${init?.method ?? "GET"} ${path29} returned invalid JSON`);
     }
   }
   async balance() {
@@ -1628,9 +1628,9 @@ var RetroDiffusionClient = class {
     }
     return balance;
   }
-  async call(path27, init = {}) {
+  async call(path29, init = {}) {
     if (!this.token) throw new Error("RD_API_KEY is not set");
-    const response = await this.request(`${this.baseUrl}${path27}`, {
+    const response = await this.request(`${this.baseUrl}${path29}`, {
       ...init,
       headers: {
         "Content-Type": "application/json",
@@ -2433,10 +2433,10 @@ import { createReadStream } from "fs";
 function sha256(data) {
   return createHash("sha256").update(data).digest("hex");
 }
-async function sha256File(path27) {
+async function sha256File(path29) {
   return new Promise((resolve, reject) => {
     const hash = createHash("sha256");
-    const stream = createReadStream(path27);
+    const stream = createReadStream(path29);
     stream.on("data", (chunk2) => hash.update(chunk2));
     stream.on("error", reject);
     stream.on("end", () => resolve(hash.digest("hex")));
@@ -2729,12 +2729,7 @@ var ComfyUIProvider = class _ComfyUIProvider {
   }
   validate(spec, styleImages) {
     const options = resolvedOptions(spec);
-    if (spec.source && !spec.revision) {
-      if (spec.generator === "frames") {
-        throw new Error("ComfyUI frame sets require generated provider outputs, not asset.source");
-      }
-      return;
-    }
+    if (spec.source && !spec.revision && spec.generator !== "frames") return;
     if (spec.width < 16 || spec.height < 16 || spec.width > 4096 || spec.height > 4096) {
       throw new Error("ComfyUI output dimensions must be between 16 and 4096 pixels");
     }
@@ -3568,10 +3563,11 @@ registerProvider({
 
 // src/manifest.ts
 import { readFile as readFile3 } from "fs/promises";
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import path5 from "path";
 
 // src/outputs.ts
+import { existsSync as existsSync3 } from "fs";
 import path4 from "path";
 
 // src/lock.ts
@@ -3761,13 +3757,31 @@ function resolveOutputPath(recordedPath, manifestDir) {
   return path4.resolve(manifestDir, recordedPath.split(/[\\/]/).join(path4.sep));
 }
 function expectedOutputPath(spec, role, index, total, mediaType) {
-  const originalExt = path4.extname(spec.outFile);
+  return memberPath(spec.outFile, role, index, total, mediaType);
+}
+function memberPath(file, role, index, total, mediaType) {
+  const originalExt = path4.extname(file);
   const ext = mediaType ? mediaExtension(mediaType) : originalExt || ".png";
-  const stem = originalExt ? spec.outFile.slice(0, -originalExt.length) : spec.outFile;
+  const stem = originalExt ? file.slice(0, -originalExt.length) : file;
   if (total === 1) return `${stem}${ext}`;
   const safeRole = (role ?? fallbackOutputRole(index)).replace(/[^a-zA-Z0-9_-]+/g, "-");
   return `${stem}-${safeRole}${ext}`;
 }
+function isMemberSetEntry(entry) {
+  return entry.outputs.length > 1 && entry.outputs.every((output) => !output.mediaType || output.mediaType === "image/png");
+}
+function isFrameSetEntry(entry) {
+  return entry.generator === "frames" && isMemberSetEntry(entry);
+}
+function sourceIsStem(source, entry, manifestDir) {
+  return isMemberSetEntry(entry) && !existsSync3(path4.resolve(manifestDir, source));
+}
+function sourceOutputPath(source, entry, index, manifestDir) {
+  const absolute = path4.resolve(manifestDir, source);
+  if (!sourceIsStem(source, entry, manifestDir)) return absolute;
+  const output = entry.outputs[index];
+  return memberPath(absolute, output.role, index, entry.outputs.length, output.mediaType);
+}
 function currentOutputPath(output, spec, index, total) {
   return expectedOutputPath(spec, output.role, index, total, output.mediaType);
 }
@@ -3858,7 +3872,7 @@ function resolveSpecOutputs(spec, lock, manifestDir) {
 // src/manifest.ts
 async function loadManifest(manifestPath) {
   const abs = path5.resolve(manifestPath);
-  if (!existsSync3(abs)) throw new Error(`No manifest at ${abs}`);
+  if (!existsSync4(abs)) throw new Error(`No manifest at ${abs}`);
   const input = ManifestInputSchema.safeParse(JSON.parse(await readFile3(abs, "utf8")));
   if (!input.success) {
     const issues = formatManifestIssues(input.error.issues);
@@ -4030,7 +4044,7 @@ async function resolveSpecs(loaded, filter) {
     const abs = path5.resolve(root, rel);
     let hit = styleImageCache.get(abs);
     if (!hit) {
-      if (!existsSync3(abs)) throw new Error(`Style image not found: ${abs}`);
+      if (!existsSync4(abs)) throw new Error(`Style image not found: ${abs}`);
       const buf = await readFile3(abs);
       const metadata = imageMetadata(buf);
       if (!metadata) throw new Error(`Style image is not a readable PNG or JPEG: ${abs}`);
@@ -4271,7 +4285,7 @@ function pngPath(file) {
   return extension ? `${file.slice(0, -extension.length)}.png` : `${file}.png`;
 }
 async function optionalRevisionImage(file, label, requiredFormat) {
-  if (!existsSync3(file)) return null;
+  if (!existsSync4(file)) return null;
   const bytes = await readFile3(file);
   const metadata = imageMetadata(bytes);
   if (!metadata) throw new Error(`${label} is not a readable PNG or JPEG: ${file}`);
@@ -4823,7 +4837,7 @@ async function writeArtifactBundle(files, options = {}) {
 
 // src/recipes.ts
 import path7 from "path";
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 import { readdir, readFile as readFile5 } from "fs/promises";
 import { fileURLToPath } from "url";
 import { z as z3 } from "zod";
@@ -5026,7 +5040,7 @@ async function readRecipeFile(recipePath, bundled) {
   return { recipe: parsed.data, path: absolute, dir: path7.dirname(absolute), bundled };
 }
 async function walkRecipeFiles(root) {
-  if (!existsSync4(root)) return [];
+  if (!existsSync5(root)) return [];
   const out = [];
   for (const entry of await readdir(root, { withFileTypes: true })) {
     const resolved = path7.join(root, entry.name);
@@ -5064,7 +5078,7 @@ function parseSelector(selector) {
 }
 async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
   const local = path7.resolve(target);
-  if (existsSync4(local)) {
+  if (existsSync5(local)) {
     const recipePath = path7.basename(local) === RECIPE_FILE ? local : path7.join(local, RECIPE_FILE);
     return readRecipeFile(recipePath, false);
   }
@@ -5080,7 +5094,7 @@ async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
 }
 async function verifyFile(root, file) {
   const absolute = path7.resolve(root, ...file.path.split("/"));
-  if (!existsSync4(absolute)) {
+  if (!existsSync5(absolute)) {
     return { path: file.path, expectedSha256: file.sha256, actualSha256: null, status: "missing" };
   }
   const actualSha256 = await sha256File(absolute);
@@ -5158,7 +5172,7 @@ async function installRecipe(target, options = {}) {
   })));
   if (!options.force) {
     for (const file of files) {
-      if (!existsSync4(file.path)) continue;
+      if (!existsSync5(file.path)) continue;
       const current = await readFile5(file.path);
       if (!current.equals(file.data)) {
         throw new Error(
@@ -5182,11 +5196,11 @@ async function installRecipe(target, options = {}) {
 }
 
 // src/pipeline/plan.ts
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync9 } from "fs";
 import path12 from "path";
 
 // src/pipeline/quality-profile.ts
-import { existsSync as existsSync6 } from "fs";
+import { existsSync as existsSync7 } from "fs";
 import path10 from "path";
 
 // src/pipeline/refine.ts
@@ -5198,7 +5212,7 @@ import { promisify } from "util";
 
 // src/pipeline/audit.ts
 import { readFile as readFile6 } from "fs/promises";
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import path8 from "path";
 function colorDistance(a, b) {
   const rmean = (a.r + b.r) / 2;
@@ -5244,7 +5258,7 @@ async function auditStyle(loaded, specs, styleId, lock) {
   const unreadable = [];
   for (const spec of mine) {
     for (const output of resolveSpecOutputs(spec, lock, loaded.root)) {
-      if (!existsSync5(output.absolutePath)) {
+      if (!existsSync6(output.absolutePath)) {
         missing.push(output.id);
         continue;
       }
@@ -5274,7 +5288,7 @@ async function auditStyle(loaded, specs, styleId, lock) {
   const refPalettes = [];
   for (const img of style.styleImages) {
     const abs = path8.resolve(loaded.root, img.path);
-    if (!existsSync5(abs)) continue;
+    if (!existsSync6(abs)) continue;
     try {
       refPalettes.push(extractPalette(decodePng(await readFile6(abs)), 12));
     } catch {
@@ -5903,7 +5917,7 @@ async function qualitySource(spec, lock) {
       return { items: null, reason: "frame-set quality requires ordered downloaded provider outputs" };
     }
     const source = path10.resolve(spec.root, spec.source);
-    return existsSync6(source) ? { items: [{ role: "source", path: source }] } : { items: null, reason: `declared source is missing: ${spec.source}` };
+    return existsSync7(source) ? { items: [{ role: "source", path: source }] } : { items: null, reason: `declared source is missing: ${spec.source}` };
   }
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
   if (!entry) return { items: null, reason: "raw provider output is not in the lockfile" };
@@ -5932,7 +5946,7 @@ async function qualitySource(spec, lock) {
     }
     if (role) roles.add(role);
     const source = currentEntryOutputPath(entry, spec, index);
-    if (!existsSync6(source)) return { items: null, reason: `raw provider output is missing: ${source}` };
+    if (!existsSync7(source)) return { items: null, reason: `raw provider output is missing: ${source}` };
     if (await sha256File(source) !== output.sha256) {
       return { items: null, reason: "raw provider output was modified after download" };
     }
@@ -5951,7 +5965,7 @@ async function inspectQualityProfile(spec, lock) {
   }
   const sourcePaths = source.items.map((item) => item.path);
   const expectedOutputs = spec.generator === "frames" ? source.items.map((item, index) => qualityFrameOutputPath(output, item.role, index)) : [output];
-  if (!existsSync6(record)) {
+  if (!existsSync7(record)) {
     return {
       key,
       state: "needs-refinement",
@@ -6132,7 +6146,7 @@ async function requireApprovedQualitySources(specs, lock, assetIds, outputRoles)
 }
 
 // src/pipeline/revision.ts
-import { existsSync as existsSync7 } from "fs";
+import { existsSync as existsSync8 } from "fs";
 import path11 from "path";
 async function inspectRevisionReadiness(spec, lock) {
   if (!spec.revision) return null;
@@ -6148,14 +6162,14 @@ async function inspectRevision(spec, lock, seen) {
       reason: `revision source ${spec.styleId}/${revision.sourceAssetId} is not ready: ${dependency.reason}`
     };
   }
-  if (!revision.sourceSha256 || !existsSync7(revision.sourceFile)) {
+  if (!revision.sourceSha256 || !existsSync8(revision.sourceFile)) {
     return { ready: false, reason: `revision source is missing: ${revision.sourceFile}` };
   }
   if (await sha256File(revision.sourceFile) !== revision.sourceSha256) {
     return { ready: false, reason: "revision source changed after the manifest was resolved" };
   }
   if (revision.maskFile) {
-    if (!revision.maskSha256 || !existsSync7(revision.maskFile)) {
+    if (!revision.maskSha256 || !existsSync8(revision.maskFile)) {
       return { ready: false, reason: `revision mask is missing: ${revision.maskFile}` };
     }
     if (await sha256File(revision.maskFile) !== revision.maskSha256) {
@@ -6186,7 +6200,7 @@ async function inspectParent(spec, lock, seen) {
   }
   if (spec.source) {
     const source = path11.resolve(spec.root, spec.source);
-    return existsSync7(source) ? { ready: true, reason: "declared source is present" } : { ready: false, reason: `declared source is missing: ${spec.source}` };
+    return existsSync8(source) ? { ready: true, reason: "declared source is present" } : { ready: false, reason: `declared source is missing: ${spec.source}` };
   }
   const entry = lock.entries[key];
   if (!entry) return { ready: false, reason: "parent is not in the lockfile" };
@@ -6200,7 +6214,7 @@ async function inspectParent(spec, lock, seen) {
   for (let index = 0; index < entry.outputs.length; index++) {
     const output = entry.outputs[index];
     const file = currentEntryOutputPath(entry, spec, index);
-    if (!existsSync7(file)) return { ready: false, reason: `parent output is missing: ${file}` };
+    if (!existsSync8(file)) return { ready: false, reason: `parent output is missing: ${file}` };
     if (await sha256File(file) !== output.sha256) {
       return { ready: false, reason: `parent output was modified: ${file}` };
     }
@@ -6254,8 +6268,8 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (opts.force) {
       state = "missing";
       reason = "--force";
-    } else if (!entry && spec.source) {
-      if (existsSync8(path12.resolve(spec.root, spec.source))) {
+    } else if (!entry && spec.source && spec.generator !== "frames") {
+      if (existsSync9(path12.resolve(spec.root, spec.source))) {
         state = "ok";
         reason = `placed from ${spec.source}; not generated`;
       } else {
@@ -6263,7 +6277,7 @@ async function buildPlan(specs, lock, opts = {}) {
         reason = `declared source is missing: ${spec.source}`;
       }
     } else if (!entry) {
-      if (existsSync8(spec.outFile)) {
+      if (existsSync9(spec.outFile)) {
         state = "untracked";
         reason = "file on disk, no provenance recorded";
       } else {
@@ -6295,9 +6309,9 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (entry.status !== "downloaded") {
       state = "in-flight";
       reason = `awaiting ${entry.status}`;
-    } else if (entry.outputs.length === 0 || entry.outputs.some((_output, index) => !existsSync8(currentEntryOutputPath(entry, spec, index)))) {
+    } else if (entry.outputs.length === 0 || entry.outputs.some((_output, index) => !existsSync9(currentEntryOutputPath(entry, spec, index)))) {
       state = "orphaned";
-      reason = entry.outputs.length === 0 ? "no recorded output files" : `missing on disk: ${entry.outputs.filter((_output, index) => !existsSync8(currentEntryOutputPath(entry, spec, index))).map((o) => o.role ?? "asset").join(", ")}`;
+      reason = entry.outputs.length === 0 ? "no recorded output files" : `missing on disk: ${entry.outputs.filter((_output, index) => !existsSync9(currentEntryOutputPath(entry, spec, index))).map((o) => o.role ?? "asset").join(", ")}`;
     } else if (await anyOutputModified(entry, spec)) {
       state = "orphaned";
       reason = "output modified since download";
@@ -6363,7 +6377,7 @@ function summarize(plan) {
 
 // src/pipeline/quality-regression.ts
 import path13 from "path";
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync10 } from "fs";
 import { readFile as readFile8 } from "fs/promises";
 import { z as z4 } from "zod";
 var SHA256_RE2 = /^[0-9a-f]{64}$/;
@@ -6606,7 +6620,7 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
     cases
   });
   const data = Buffer.from(JSON.stringify(baseline, null, 2) + "\n");
-  if (existsSync9(absolute) && !options.force) {
+  if (existsSync10(absolute) && !options.force) {
     const current = await readFile8(absolute);
     if (!current.equals(data)) {
       throw new Error(`Quality baseline already exists with different content: ${absolute}. Pass --force to replace it.`);
@@ -6743,13 +6757,13 @@ async function checkQualityBaseline(baselinePath) {
 }
 
 // src/pipeline/cache-health.ts
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync12 } from "fs";
 import { readFile as readFile10, readdir as readdir2, rm as rm5 } from "fs/promises";
 import path14 from "path";
 
 // src/cache.ts
 import { mkdir as mkdir3, readFile as readFile9, rename as rename3, rm as rm4, writeFile as writeFile3 } from "fs/promises";
-import { existsSync as existsSync10 } from "fs";
+import { existsSync as existsSync11 } from "fs";
 import pathModule from "path";
 import { z as z5 } from "zod";
 var HashCacheSchema = z5.object({
@@ -6764,10 +6778,10 @@ function isSha256Hash(value) {
 function parseCache(value) {
   return HashCacheSchema.parse(value);
 }
-async function loadCache(path27) {
-  if (!existsSync10(path27)) return { version: 1, hashes: {} };
+async function loadCache(path29) {
+  if (!existsSync11(path29)) return { version: 1, hashes: {} };
   try {
-    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile9(path27, "utf8")));
+    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile9(path29, "utf8")));
     if (!parsed.success) return { version: 1, hashes: {} };
     return {
       version: 1,
@@ -6779,18 +6793,18 @@ async function loadCache(path27) {
     return { version: 1, hashes: {} };
   }
 }
-async function saveCache(path27, cache) {
+async function saveCache(path29, cache) {
   const sorted = {};
   for (const key of Object.keys(cache.hashes).sort()) {
     const hash = cache.hashes[key];
     if (!isSha256Hash(hash)) throw new Error(`Refusing to cache invalid SHA-256 for ${key}`);
     sorted[key] = hash;
   }
-  await mkdir3(pathModule.dirname(pathModule.resolve(path27)), { recursive: true });
-  const tmp = `${path27}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await mkdir3(pathModule.dirname(pathModule.resolve(path29)), { recursive: true });
+  const tmp = `${path29}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
     await writeFile3(tmp, JSON.stringify({ version: 1, hashes: sorted }, null, 2) + "\n");
-    await rename3(tmp, path27);
+    await rename3(tmp, path29);
   } finally {
     await rm4(tmp, { force: true });
   }
@@ -6812,7 +6826,7 @@ function cachePathFor(lockPath) {
 
 // src/pipeline/cache-health.ts
 async function inspectCaches(lock, lockPath, options = {}) {
-  if (options.prune && !existsSync11(lockPath)) {
+  if (options.prune && !existsSync12(lockPath)) {
     throw new Error(`Refusing to prune without an existing lockfile at ${path14.resolve(lockPath)}`);
   }
   const contentDir = path14.resolve(path14.dirname(lockPath), ".pixelkiln", "cache");
@@ -6857,7 +6871,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
 async function inspectContentCache(contentDir, referenced) {
   const report = {
     path: contentDir,
-    exists: existsSync11(contentDir),
+    exists: existsSync12(contentDir),
     files: 0,
     bytes: 0,
     valid: 0,
@@ -6921,7 +6935,7 @@ async function inspectContentCache(contentDir, referenced) {
 async function inspectRemoteHashCache(remotePath) {
   const report = {
     path: remotePath,
-    exists: existsSync11(remotePath),
+    exists: existsSync12(remotePath),
     entries: 0,
     valid: 0,
     invalidIds: [],
@@ -7049,12 +7063,15 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
   for (const [key, entry] of entries) {
     const id = key.slice(prefix.length);
     locked.add(id);
-    const outputs = resolveEntryOutputs(entry, id, manifestDir);
+    let outputs = resolveEntryOutputs(entry, id, manifestDir);
     const source = sources[id];
     if (source && outputs.length <= 1) {
       inputs.push({ id, path: path15.resolve(manifestDir, source) });
       continue;
     }
+    if (source && sourceIsStem(source, entry, manifestDir)) {
+      outputs = outputs.map((output) => ({ ...output, absolutePath: sourceOutputPath(source, entry, output.index, manifestDir) }));
+    }
     let selected = outputs;
     if (options.outputRoles?.length) {
       selected = outputs.filter(
@@ -7176,11 +7193,21 @@ function mountStyle(lock, styleId, manifestDir, mount, cells, sources = {}, outp
   for (const id of ids) {
     const cell = cells[id];
     const source = sources[id];
-    if (source) {
+    const entry = lock.entries[`${styleId}/${id}`];
+    if (source && !(entry && sourceIsStem(source, entry, manifestDir))) {
       placements.push({ id, path: path15.resolve(manifestDir, source), cell });
       continue;
     }
-    const entry = lock.entries[`${styleId}/${id}`];
+    if (source && entry) {
+      const selection2 = selectEntryOutput(entry, outputRoles[id]);
+      if (!selection2.ok) {
+        skipped.push({ id, reason: selection2.reason });
+        continue;
+      }
+      const index = entry.outputs.findIndex((output) => output.path === selection2.output.path);
+      placements.push({ id, path: sourceOutputPath(source, entry, Math.max(index, 0), manifestDir), cell });
+      continue;
+    }
     if (!entry) {
       skipped.push({
         id,
@@ -7247,8 +7274,11 @@ function normalizeTileRules(raw) {
   };
 }
 function exportTileset(entry, spec, options) {
-  const outputs = resolveSpecEntryOutputs(entry, spec);
+  let outputs = resolveSpecEntryOutputs(entry, spec);
   if (!outputs.length) throw new Error(`${spec.styleId}/${spec.assetId} has no downloaded outputs`);
+  if (spec.source && sourceIsStem(spec.source, entry, options.manifestDir)) {
+    outputs = outputs.map((output) => ({ ...output, absolutePath: sourceOutputPath(spec.source, entry, output.index, options.manifestDir) }));
+  }
   const packed = packSprites(
     outputs.map((output) => ({
       id: output.role ?? fallbackOutputRole(output.index),
@@ -7740,7 +7770,7 @@ async function poll(provider, lock, lockPath, opts = {}) {
 }
 
 // src/pipeline/fetch.ts
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync13 } from "fs";
 import { mkdir as mkdir4, readFile as readFile11, rename as rename4, rm as rm6, writeFile as writeFile4 } from "fs/promises";
 import path16 from "path";
 async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
@@ -7757,7 +7787,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
     if (opts.refresh) return e.outputs.length > 0 && Boolean(e.sourceUrls?.length || e.sourceUrl);
     if (!opts.repair) return false;
     const spec = specByKey.get(key);
-    return e.outputs.length === 0 || !spec || e.outputs.some((output) => !existsSync12(resolveOutputPath(output.path, spec.root)));
+    return e.outputs.length === 0 || !spec || e.outputs.some((output) => !existsSync13(resolveOutputPath(output.path, spec.root)));
   });
   const concurrency = Math.min(Math.max(1, opts.concurrency ?? 8), Math.max(1, pending.length));
   let cursor = 0;
@@ -7805,7 +7835,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
               continue;
             }
           }
-          if (existsSync12(target)) {
+          if (existsSync13(target)) {
             const currentHash = await sha256File(target);
             if (recorded && currentHash === recorded.sha256) {
               if (!fresh) {
@@ -7916,7 +7946,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
 }
 async function readCachedMedia(cacheDir, hash, mediaType) {
   const file = path16.join(cacheDir, cacheFileName(hash, mediaType));
-  if (!existsSync12(file)) return null;
+  if (!existsSync13(file)) return null;
   try {
     const buf = await readFile11(file);
     if (sha256(buf) !== hash) return null;
@@ -7937,7 +7967,7 @@ async function cacheMedia(cacheDir, buf, mediaType, knownHash) {
   try {
     await rename4(tmp, file);
   } catch (err) {
-    if (!existsSync12(file)) throw err;
+    if (!existsSync13(file)) throw err;
   } finally {
     await rm6(tmp, { force: true });
   }
@@ -7970,7 +8000,7 @@ async function pushTags(provider, specs, lock, opts = {}) {
 }
 
 // src/pipeline/doctor.ts
-import { constants, existsSync as existsSync13 } from "fs";
+import { constants, existsSync as existsSync14 } from "fs";
 import { access, stat as stat2 } from "fs/promises";
 import path17 from "path";
 async function doctor(loaded, specs, lock, lockPath, opts = {}) {
@@ -8042,7 +8072,7 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
         cacheDir,
         cacheFileName(output.sha256, output.mediaType ?? MediaType.PNG)
       );
-      if (existsSync13(cached) && await sha256File(cached) === output.sha256) {
+      if (existsSync14(cached) && await sha256File(cached) === output.sha256) {
         hasCache = true;
         break;
       }
@@ -8145,7 +8175,7 @@ async function nearestExistingDirectory(start) {
 }
 
 // src/pipeline/adopt.ts
-import { existsSync as existsSync14 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 import { readFile as readFile12, writeFile as writeFile5 } from "fs/promises";
 import path18 from "path";
 async function adopt(provider, specs, lock, lockPath, opts = {}) {
@@ -8158,7 +8188,7 @@ async function adopt(provider, specs, lock, lockPath, opts = {}) {
   const localByHash = /* @__PURE__ */ new Map();
   const unmatchedLocal = [];
   for (const spec of specs) {
-    if (!existsSync14(spec.outFile)) {
+    if (!existsSync15(spec.outFile)) {
       unmatchedLocal.push(`${spec.styleId}/${spec.assetId} (no file at ${spec.outFile})`);
       continue;
     }
@@ -8280,12 +8310,12 @@ async function tagAdopted(provider, specs, lock, opts = {}) {
 }
 
 // src/pick/server.ts
-import { existsSync as existsSync16 } from "fs";
+import { existsSync as existsSync17 } from "fs";
 import { readFile as readFile15 } from "fs/promises";
 
 // src/pipeline/init.ts
 import { readdir as readdir3, readFile as readFile13, writeFile as writeFile6 } from "fs/promises";
-import { existsSync as existsSync15 } from "fs";
+import { existsSync as existsSync16 } from "fs";
 import path19 from "path";
 function pngSize(buf) {
   if (buf.length < 24) return null;
@@ -8858,7 +8888,7 @@ async function currentArt(entry, spec) {
   const previous = primaryOutput({ ...entry, outputs: entry.supersededOutputs });
   if (!previous) return null;
   const file = resolveOutputPath(previous.path, spec.root);
-  if (!existsSync16(file)) return null;
+  if (!existsSync17(file)) return null;
   const contentType = previous.mediaType ?? mediaTypeFromExtension(file);
   if (!contentType) return null;
   let width = entry.width;
@@ -9029,13 +9059,13 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
 
 // src/gallery/snapshot.ts
 import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync19 } from "fs";
+import { existsSync as existsSync20 } from "fs";
 import { readFile as readFile19, stat as stat3 } from "fs/promises";
 import path24 from "path";
 
 // src/workspace.ts
 import { mkdir as mkdir5, readFile as readFile16, rename as rename5, rm as rm7, writeFile as writeFile7 } from "fs/promises";
-import { existsSync as existsSync17 } from "fs";
+import { existsSync as existsSync18 } from "fs";
 import path20 from "path";
 import { z as z6 } from "zod";
 var WorkspaceProjectSchema = z6.object({
@@ -9061,7 +9091,7 @@ ${parsed.error.issues.slice(0, 5).map((i) => `  ${i.path.join(".")}: ${i.message
   );
 }
 async function loadWorkspace(workspacePath) {
-  if (!existsSync17(workspacePath)) return { version: 1, projects: [] };
+  if (!existsSync18(workspacePath)) return { version: 1, projects: [] };
   let raw;
   try {
     raw = JSON.parse(await readFile16(workspacePath, "utf8"));
@@ -9113,14 +9143,14 @@ function validateWorkspace(ws, dir) {
         message: `project "${project.id}" stores an absolute path \u2014 the catalog will not resolve correctly if this tree is cloned or moved elsewhere`
       });
     }
-    if (!existsSync17(manifestPath)) {
+    if (!existsSync18(manifestPath)) {
       diagnostics.push({
         id: "missing-manifest",
         level: "error",
         message: `project "${project.id}" manifest not found: ${manifestPath}`
       });
     }
-    if (!existsSync17(lockPath)) {
+    if (!existsSync18(lockPath)) {
       diagnostics.push({
         id: "missing-lock",
         level: "error",
@@ -9421,7 +9451,7 @@ async function applyManifestEdit(manifestPath, edit) {
 
 // src/pipeline/hand-edit.ts
 import { spawn as spawn2 } from "child_process";
-import { existsSync as existsSync18 } from "fs";
+import { existsSync as existsSync19 } from "fs";
 import { copyFile, mkdir as mkdir6, readFile as readFile18, rename as rename7, rm as rm9, writeFile as writeFile9 } from "fs/promises";
 import path22 from "path";
 import { z as z8 } from "zod";
@@ -9434,36 +9464,63 @@ function handEditPath(loaded, spec) {
   const file = inside ? relative : path22.basename(spec.outFile);
   return path22.join(outDir, HAND_EDIT_DIR, file.replace(/\.gif$/i, ".png"));
 }
-function handEditBase(spec, lock) {
+function handEditBases(spec, lock) {
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
   if (entry) {
-    if (entry.outputs.length !== 1) return null;
-    const primary = primaryOutput(entry);
-    if (!primary || primary.mediaType && primary.mediaType !== "image/png") return null;
-    const file = currentEntryOutputPath(entry, spec, 0);
-    return existsSync18(file) ? file : null;
+    if (entry.outputs.length !== 1 && !isMemberSetEntry(entry)) return null;
+    const members = entry.outputs.map((output, index) => ({
+      role: entry.outputs.length === 1 ? null : output.role ?? null,
+      path: currentEntryOutputPath(entry, spec, index),
+      mediaType: output.mediaType
+    }));
+    if (members.some((member) => member.mediaType && member.mediaType !== "image/png")) return null;
+    if (entry.outputs.length === 1 && !primaryOutput(entry)) return null;
+    if (!members.every((member) => existsSync19(member.path))) return null;
+    return members.map(({ role, path: file }) => ({ role, path: file }));
+  }
+  return existsSync19(spec.outFile) ? [{ role: null, path: spec.outFile }] : null;
+}
+function handEditBase(spec, lock) {
+  const bases = handEditBases(spec, lock);
+  return bases && bases.length === 1 ? bases[0].path : null;
+}
+function handEditMembers(loaded, spec, lock, editPath) {
+  const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
+  const bases = handEditBases(spec, lock);
+  if (entry && isMemberSetEntry(entry)) {
+    return entry.outputs.map((output, index) => ({
+      role: output.role ?? null,
+      path: memberPath(editPath, output.role, index, entry.outputs.length, output.mediaType),
+      base: bases?.[index]?.path ?? null
+    }));
   }
-  return existsSync18(spec.outFile) ? spec.outFile : null;
+  return [{ role: null, path: editPath, base: bases?.[0]?.path ?? null }];
 }
 async function startHandEdit(loaded, lock, spec, opts = {}) {
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
-  if (entry && entry.outputs.length > 1) {
+  if (entry && entry.outputs.length > 1 && !isMemberSetEntry(entry)) {
     throw new ManifestEditError(
-      `${spec.styleId}/${spec.assetId} has ${entry.outputs.length} outputs; hand edits currently cover single-image assets`
+      `${spec.styleId}/${spec.assetId} is a set of ${entry.outputs.length} outputs that are not all PNG; hand edits cover PNG images and sets of them`
+    );
+  }
+  if (entry && spec.source && isMemberSetEntry(entry) && !sourceIsStem(spec.source, entry, loaded.root)) {
+    throw new ManifestEditError(
+      `${spec.styleId}/${spec.assetId} declares ${spec.source}, one committed file placed for the whole set; clear that source (pixelkiln edit detach) to hand-edit the members one by one`
     );
   }
   const existing = spec.source ? path22.resolve(loaded.root, spec.source) : null;
   const editPath = existing ?? handEditPath(loaded, spec);
+  const members = handEditMembers(loaded, spec, lock, editPath);
   let created = false;
-  if (!existsSync18(editPath)) {
-    const base = handEditBase(spec, lock);
-    if (!base) {
+  for (const member of members) {
+    if (existsSync19(member.path)) continue;
+    if (!member.base) {
       throw new ManifestEditError(
         `${spec.styleId}/${spec.assetId} has no generated PNG on disk to start from; generate or restore it first`
       );
     }
-    await mkdir6(path22.dirname(editPath), { recursive: true });
-    await copyFile(base, editPath);
+    await mkdir6(path22.dirname(member.path), { recursive: true });
+    await copyFile(member.base, member.path);
     created = true;
   }
   const source = portableOutputPath(editPath, loaded.root);
@@ -9480,7 +9537,7 @@ async function startHandEdit(loaded, lock, spec, opts = {}) {
     declared = result.changed;
     manifestSha256 = result.sha256;
   }
-  return { editPath, source, created, declared, manifestSha256 };
+  return { editPath, members, source, created, declared, manifestSha256 };
 }
 async function detachHandEdit(loaded, spec, opts = {}) {
   if (!spec.source) {
@@ -9494,19 +9551,44 @@ async function detachHandEdit(loaded, spec, opts = {}) {
   });
   return { manifestSha256: result.sha256, changed: result.changed };
 }
-var HandEditCompanionSchema = z8.object({
-  version: z8.literal(1),
-  /** sha256 of the generated art the edit started from; null when it started from untracked art. */
+var CompanionOutputSchema = z8.object({
+  /** Output role for a set member; null for a single image. */
+  role: z8.string().nullable(),
+  /** sha256 of the generated file this member started from; null when it started from untracked art. */
   basedOn: z8.string().regex(/^[0-9a-f]{64}$/).nullable(),
-  /** sha256 of the edit PNG as saved, so a later change by another tool is visible. */
-  sha256: z8.string().regex(/^[0-9a-f]{64}$/),
+  /** sha256 of the member as saved, so a later change by another tool is visible. */
+  sha256: z8.string().regex(/^[0-9a-f]{64}$/)
+}).strict();
+var CompanionV2Schema = z8.object({
+  version: z8.literal(2),
   /** Editor identity the bridge reported, e.g. `pixelorama@v1.2.2-stable`. */
   editor: z8.string().min(1),
   protocol: z8.number().int().positive(),
   savedAt: z8.string().datetime(),
   /** Basename of the layered project file beside the edit, when one was kept. */
+  project: z8.string().min(1).nullable(),
+  /** One entry per file, in output order. */
+  outputs: z8.array(CompanionOutputSchema).min(1)
+}).strict();
+var CompanionV1Schema = z8.object({
+  version: z8.literal(1),
+  basedOn: z8.string().regex(/^[0-9a-f]{64}$/).nullable(),
+  sha256: z8.string().regex(/^[0-9a-f]{64}$/),
+  editor: z8.string().min(1),
+  protocol: z8.number().int().positive(),
+  savedAt: z8.string().datetime(),
   project: z8.string().min(1).nullable()
 }).strict();
+var HandEditCompanionSchema = z8.union([CompanionV2Schema, CompanionV1Schema]).transform(
+  (value) => value.version === 2 ? value : {
+    version: 2,
+    editor: value.editor,
+    protocol: value.protocol,
+    savedAt: value.savedAt,
+    project: value.project,
+    outputs: [{ role: null, basedOn: value.basedOn, sha256: value.sha256 }]
+  }
+);
 function handEditCompanionPath(editPath) {
   return editPath.replace(/\.png$/i, "") + ".edit.json";
 }
@@ -9528,45 +9610,79 @@ async function readHandEditCompanion(editPath) {
 }
 var MAX_HAND_EDIT_BYTES = 16 * 1024 * 1024;
 async function saveHandEdit(loaded, lock, spec, input) {
-  if (input.png.length > MAX_HAND_EDIT_BYTES) {
-    throw new ManifestEditError(`the edit is ${input.png.length} bytes; the limit is ${MAX_HAND_EDIT_BYTES}`);
-  }
+  const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
+  const memberSet = entry ? isMemberSetEntry(entry) : false;
+  const incoming = input.frames ?? (input.png ? [{ role: null, png: input.png }] : []);
+  if (!incoming.length) throw new ManifestEditError("the save carried no image");
   if (input.project && input.project.length > MAX_HAND_EDIT_BYTES) {
     throw new ManifestEditError(`the project file is ${input.project.length} bytes; the limit is ${MAX_HAND_EDIT_BYTES}`);
   }
-  let decoded;
-  try {
-    validateMedia(input.png, MediaType.PNG);
-    decoded = decodePng(input.png);
-  } catch (error) {
-    throw new ManifestEditError(`the edit is not a valid PNG: ${error instanceof Error ? error.message : String(error)}`);
+  if (memberSet) {
+    const expected = entry.outputs.map((output) => output.role ?? null);
+    const got = incoming.map((frame) => frame.role);
+    if (got.length !== expected.length || expected.some((role, index) => got[index] !== role)) {
+      throw new ManifestEditError(
+        `${spec.styleId}/${spec.assetId} is a set of ${expected.length} members (${expected.join(", ")}); the editor returned ${got.length} (${got.map((role) => role ?? "new").join(", ")}) \u2014 keep the frames it opened with`
+      );
+    }
+  } else if (incoming.length !== 1) {
+    throw new ManifestEditError(`${spec.styleId}/${spec.assetId} is one image; the editor returned ${incoming.length} frames \u2014 keep a single frame`);
   }
-  const base = handEditBase(spec, lock);
-  const expected = base ? decodePng(await readFile18(base)) : { width: spec.width, height: spec.height };
-  if (decoded.width !== expected.width || decoded.height !== expected.height) {
-    throw new ManifestEditError(
-      `the edit is ${decoded.width}\xD7${decoded.height}; ${spec.styleId}/${spec.assetId} is ${expected.width}\xD7${expected.height}`
-    );
+  const decoded = incoming.map((frame, index) => {
+    if (frame.png.length > MAX_HAND_EDIT_BYTES) {
+      throw new ManifestEditError(`the edit is ${frame.png.length} bytes; the limit is ${MAX_HAND_EDIT_BYTES}`);
+    }
+    try {
+      validateMedia(frame.png, MediaType.PNG);
+      return decodePng(frame.png);
+    } catch (error) {
+      const which = memberSet ? `member ${frame.role ?? index}` : "the edit";
+      throw new ManifestEditError(`${which} is not a valid PNG: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  });
+  const bases = handEditBases(spec, lock);
+  const expectedSize = bases?.[0] ? decodePng(await readFile18(bases[0].path)) : { width: spec.width, height: spec.height };
+  for (const [index, image] of decoded.entries()) {
+    if (image.width !== expectedSize.width || image.height !== expectedSize.height) {
+      const which = memberSet ? `member ${incoming[index].role ?? index}` : "the edit";
+      throw new ManifestEditError(
+        `${which} is ${image.width}\xD7${image.height}; ${spec.styleId}/${spec.assetId} is ${expectedSize.width}\xD7${expectedSize.height}`
+      );
+    }
   }
   const started = await startHandEdit(loaded, lock, spec, { expectedSha256: input.expectedSha256 });
-  const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
-  const basedOn = entry ? primaryOutput(entry)?.sha256 ?? null : null;
-  const digest2 = sha256(input.png);
   const projectPath = input.project ? handEditProjectPath(started.editPath) : null;
   const companion = {
-    version: 1,
-    basedOn,
-    sha256: digest2,
+    version: 2,
     editor: input.editor,
     protocol: input.protocol,
     savedAt: (input.now ?? /* @__PURE__ */ new Date()).toISOString(),
-    project: projectPath ? path22.basename(projectPath) : null
+    project: projectPath ? path22.basename(projectPath) : null,
+    outputs: incoming.map((frame, index) => ({
+      role: frame.role,
+      basedOn: basedOnHash(entry, index),
+      sha256: sha256(frame.png)
+    }))
   };
-  await replaceFile(started.editPath, input.png);
+  for (const [index, member] of started.members.entries()) {
+    await replaceFile(member.path, incoming[index].png);
+  }
   if (projectPath && input.project) await replaceFile(projectPath, input.project);
   const companionPath = handEditCompanionPath(started.editPath);
   await replaceFile(companionPath, JSON.stringify(companion, null, 2) + "\n");
-  return { ...started, sha256: digest2, basedOn, companionPath, projectPath };
+  return {
+    ...started,
+    sha256: companion.outputs[0].sha256,
+    basedOn: companion.outputs[0].basedOn,
+    companion,
+    companionPath,
+    projectPath
+  };
+}
+function basedOnHash(entry, index) {
+  if (!entry) return null;
+  if (entry.outputs.length === 1) return primaryOutput(entry)?.sha256 ?? null;
+  return entry.outputs[index]?.sha256 ?? null;
 }
 async function replaceFile(file, bytes) {
   const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
@@ -9613,7 +9729,10 @@ var HandEditRequestSchema = z9.discriminatedUnion("action", [
     assetId: z9.string().min(1),
     styleId: z9.string().min(1),
     expectedSha256: z9.string().regex(/^[0-9a-f]{64}$/),
-    png: Base64.min(1),
+    /** The flattened image; for a frame set, `frames` instead. */
+    png: Base64.min(1).optional(),
+    /** Every frame of a set, tagged with the role it was opened under (null for one added in the editor). */
+    frames: z9.array(z9.object({ role: z9.string().min(1).nullable(), png: Base64.min(1) }).strict()).min(1).max(256).optional(),
     /** The editor's layered project file, kept beside the edit. */
     pxo: Base64.optional(),
     /** Editor identity from the bridge's ready message. */
@@ -9636,18 +9755,23 @@ function createGalleryEditHandler(opts) {
         const started = await startHandEdit(ctx.loaded, ctx.lock, spec, { expectedSha256: request.expectedSha256 });
         log(`  hand edit ${started.created ? "created" : "found"}: ${started.source}${started.declared ? " (declared in the manifest)" : ""}`);
         if (request.open) {
-          const command = (opts.openEditor ?? openInEditor)(started.editPath);
+          const command = (opts.openEditor ?? openInEditor)(started.members[0].path);
           log(`  opened with: ${command}`);
         }
       } else if (request.action === "save-edit") {
+        if (request.png !== void 0 === (request.frames !== void 0)) {
+          throw new ManifestEditError("invalid edit: send png for one image or frames for a set, not both");
+        }
         const saved = await saveHandEdit(ctx.loaded, ctx.lock, spec, {
-          png: Buffer.from(request.png, "base64"),
+          ...request.png !== void 0 ? { png: Buffer.from(request.png, "base64") } : {},
+          ...request.frames ? { frames: request.frames.map((frame) => ({ role: frame.role, png: Buffer.from(frame.png, "base64") })) } : {},
           ...request.pxo ? { project: Buffer.from(request.pxo, "base64") } : {},
           editor: request.editor,
           protocol: request.protocol,
           expectedSha256: request.expectedSha256
         });
-        log(`  hand edit saved from ${request.editor}: ${saved.source}${saved.declared ? " (declared in the manifest)" : ""}${saved.projectPath ? " + project file" : ""}`);
+        const what = saved.members.length > 1 ? `${saved.source} (${saved.members.length} frames)` : saved.source;
+        log(`  hand edit saved from ${request.editor}: ${what}${saved.declared ? " (declared in the manifest)" : ""}${saved.projectPath ? " + project file" : ""}`);
       } else {
         const result2 = await detachHandEdit(ctx.loaded, spec, { expectedSha256: request.expectedSha256 });
         if (result2.changed) log(`  hand edit detached: ${request.styleId}/${request.assetId} (file kept)`);
@@ -9695,6 +9819,18 @@ function matchesFilter(filter, styleId, assetId) {
   if (filter?.assets?.length && !filter.assets.includes(assetId)) return false;
   return true;
 }
+var MAX_COMPARED_BYTES = 8 * 1024 * 1024;
+async function samePixels(a, b) {
+  try {
+    const [left, right] = await Promise.all([readFile19(a), readFile19(b)]);
+    if (left.length > MAX_COMPARED_BYTES || right.length > MAX_COMPARED_BYTES) return false;
+    const x = decodePng(left);
+    const y = decodePng(right);
+    return x.width === y.width && x.height === y.height && x.pixels.equals(y.pixels);
+  } catch {
+    return false;
+  }
+}
 function metadataFps(entry) {
   if (!entry) return null;
   const namespace = entry.providerMetadata?.[entry.provider];
@@ -9742,7 +9878,7 @@ async function describeQuality(media, root, inspection) {
     outputPaths.map((file) => describeOutput(media, root, path24.resolve(root, file)))
   );
   const recordPath = path24.resolve(root, inspection.record);
-  const recordExists = existsSync19(recordPath);
+  const recordExists = existsSync20(recordPath);
   let options = null;
   let check = null;
   if (recordExists) {
@@ -9812,6 +9948,8 @@ async function buildGallerySnapshot(opts) {
     const asset = loaded.manifest.assets[spec.assetId] ?? null;
     let outputs;
     let edit = null;
+    let edits = [];
+    let editChanged = [];
     let editStatus = null;
     let editMeta = null;
     if (entry && entry.outputs.length) {
@@ -9822,13 +9960,19 @@ async function buildGallerySnapshot(opts) {
       );
       if (spec.source) {
         const editPath = path24.resolve(root, spec.source);
-        const editSha = existsSync19(editPath) ? await sha256File(editPath) : null;
-        edit = await describeOutput(media, root, editPath, { sha256: editSha });
-        const generated = outputs[0];
+        const memberCount = sourceIsStem(spec.source, entry, root) ? entry.outputs.length : 1;
+        const editShas = await Promise.all(
+          Array.from({ length: memberCount }, async (_, index) => {
+            const file = sourceOutputPath(spec.source, entry, index, root);
+            return { file, sha256: existsSync20(file) ? await sha256File(file) : null };
+          })
+        );
+        edits = await Promise.all(editShas.map(({ file, sha256: editSha }) => describeOutput(media, root, file, { sha256: editSha })));
+        edit = edits[0] ?? null;
         const companion = await readHandEditCompanion(editPath);
         if (companion) {
           const projectPath = handEditProjectPath(editPath);
-          const project = companion.project && existsSync19(projectPath) ? await fileInfo(projectPath) : null;
+          const project = companion.project && existsSync20(projectPath) ? await fileInfo(projectPath) : null;
           let projectUrl = null;
           if (project) {
             const id = galleryMediaId(projectPath);
@@ -9838,18 +9982,34 @@ async function buildGallerySnapshot(opts) {
           editMeta = {
             editor: companion.editor,
             savedAt: companion.savedAt,
-            basedOn: companion.basedOn,
-            changedSince: editSha !== null && editSha !== companion.sha256,
+            basedOn: companion.outputs[0]?.basedOn ?? null,
+            changedSince: editShas.some(({ sha256: editSha }, index) => {
+              const recorded = companion.outputs[index]?.sha256;
+              return editSha !== null && recorded !== void 0 && editSha !== recorded;
+            }),
             project: project ? portableOutputPath(projectPath, root) : null,
             projectUrl
           };
         }
-        const regenerated = companion ? generated?.sha256 !== void 0 && generated.sha256 !== null && companion.basedOn !== generated.sha256 : Boolean(generated?.modifiedAt && edit.modifiedAt && generated.modifiedAt > edit.modifiedAt && generated.exists);
-        editStatus = !edit.exists ? "missing" : generated && editSha === generated.sha256 ? "same" : regenerated ? "regenerated-since" : "edited";
+        const regenerated = edits.some((member, index) => {
+          const generated = outputs[index];
+          if (companion) {
+            const recorded = companion.outputs[index];
+            return recorded !== void 0 && generated.sha256 !== null && recorded.basedOn !== generated.sha256;
+          }
+          return Boolean(generated.modifiedAt && member.modifiedAt && generated.modifiedAt > member.modifiedAt && generated.exists);
+        });
+        editChanged = await Promise.all(edits.map(async (member, index) => {
+          const generated = outputs[index];
+          if (!member.exists || !generated.exists) return true;
+          if (member.sha256 === generated.sha256) return false;
+          return !await samePixels(member.absolutePath, generated.absolutePath);
+        }));
+        editStatus = edits.some((member) => !member.exists) ? "missing" : editChanged.every((changed) => !changed) ? "same" : regenerated ? "regenerated-since" : "edited";
       }
     } else if (spec.source) {
       outputs = [await describeOutput(media, root, path24.resolve(root, spec.source))];
-    } else if (!entry && existsSync19(spec.outFile)) {
+    } else if (!entry && existsSync20(spec.outFile)) {
       outputs = [await describeOutput(media, root, spec.outFile)];
     } else {
       outputs = [];
@@ -9894,6 +10054,8 @@ async function buildGallerySnapshot(opts) {
       asset,
       source: spec.source ?? null,
       edit,
+      edits,
+      editChanged,
       editStatus,
       editMeta,
       upstreamUrl: entry?.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
@@ -9951,6 +10113,8 @@ async function buildGallerySnapshot(opts) {
       asset: null,
       source: null,
       edit: null,
+      edits: [],
+      editChanged: [],
       editStatus: null,
       editMeta: null,
       upstreamUrl: entry.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
@@ -10879,10 +11043,15 @@ window.addEventListener('message', (e) => {
 // declares the file the same way pixelkiln edit does.
 
 let SHEET = null;
-const editorSource = (item) => item.edit && item.edit.exists ? item.edit
-  : item.outputs.length === 1 && item.outputs[0].exists && item.outputs[0].mediaType === 'image/png' ? item.outputs[0] : null;
-const canEditInBrowser = (item) => EDITOR && EDITABLE && item.declared && item.asset && projectOf(item)?.manifestSha256 && editorSource(item) &&
-  !(item.outputs.length > 1);
+// What the editor gets: the edit files when they are all there, else the
+// generated outputs (one PNG, or every frame of a set).
+const editorSources = (item) => {
+  if (item.edits.length && item.edits.every((e) => e.exists)) return { files: item.edits, fromEdit: true };
+  if (editableOutputs(item)) return { files: item.outputs, fromEdit: false };
+  return null;
+};
+const editorSource = (item) => { const s = editorSources(item); return s ? s.files[0] : null; };
+const canEditInBrowser = (item) => EDITOR && EDITABLE && item.declared && item.asset && projectOf(item)?.manifestSha256 && editorSources(item);
 const toBase64 = (buf) => new Promise((resolve, reject) => {
   const r = new FileReader();
   r.onload = () => resolve(String(r.result).slice(String(r.result).indexOf(',') + 1));
@@ -10911,7 +11080,7 @@ function openEditorSheet(item) {
   const bar = el('div', 'rbar');
   const close = el('button', null, 'Close'); close.type = 'button';
   close.onclick = () => closeEditorSheet();
-  const title = el('b', null, (item.project ? item.project + ':' : '') + item.styleId + '/' + item.assetId + ' \xB7 ' + item.width + '\xD7' + item.height);
+  const title = el('b', null, (item.project ? item.project + ':' : '') + item.styleId + '/' + item.assetId + ' \xB7 ' + item.width + '\xD7' + item.height + (item.outputs.length > 1 ? ' \xB7 ' + item.outputs.length + ' ' + memberNoun(item, item.outputs.length) : ''));
   const status = el('span', 'st');
   const acts = el('div', 'acts');
   const msg = el('span', 'msg');
@@ -10932,23 +11101,34 @@ function openEditorSheet(item) {
   stage.append(frame, loading);
   panel.append(bar, stage);
   host.append(scrim, panel);
-  SHEET = { item, frame, loading, status, msg, save, saveClose, dirty: false, opened: false, ready: null, pending: null, requests: 0, source: src, sentProject: false };
+  SHEET = { item, frame, loading, status, msg, save, saveClose, dirty: false, opened: false, ready: null, pending: null, requests: 0, source: src, sentProject: false, roles: null };
   sheetStatus('cool', 'loading');
   sheetButtons();
   close.focus({ preventScroll: true });
 }
-// The edit file is what the editor gets; when a browser save kept the layered
-// project beside it, that goes along too and the editor restores the layers,
-// falling back to the flattened PNG if the file cannot be read.
+// The edit files are what the editor gets; when a browser save kept the
+// layered project beside them, that goes along too and the editor restores
+// the layers, falling back to the flattened PNGs if the file cannot be read.
+// A frame set is sent as frames, one per member, and comes back the same way.
 async function sendOpen() {
-  const { item, source } = SHEET;
+  const { item } = SHEET;
+  const sources = editorSources(item);
   const style = snap.styles.find((s) => s.id === item.styleId && s.project === item.project);
-  const projectUrl = source === item.edit && item.editMeta && item.editMeta.projectUrl && SHEET.ready.version >= 2 ? item.editMeta.projectUrl : null;
-  let png, pxo = null;
+  const projectUrl = sources.fromEdit && item.editMeta && item.editMeta.projectUrl && SHEET.ready.version >= 2 ? item.editMeta.projectUrl : null;
+  const set = sources.files.length > 1;
+  if (set && SHEET.ready.version < 3) {
+    SHEET.msg.textContent = 'This editor build cannot open sets; reinstall it with pixelkiln tools install editor.';
+    sheetStatus('bad', 'unsupported');
+    return;
+  }
+  const pngs = [];
+  let pxo = null;
   try {
-    const res = await fetch(source.url, { cache: 'no-store' });
-    if (!res.ok) throw new Error(await res.text());
-    png = await res.arrayBuffer();
+    for (const file of sources.files) {
+      const res = await fetch(file.url, { cache: 'no-store' });
+      if (!res.ok) throw new Error(await res.text());
+      pngs.push(await res.arrayBuffer());
+    }
     if (projectUrl) {
       const p = await fetch(projectUrl, { cache: 'no-store' });
       if (p.ok) pxo = await p.arrayBuffer();
@@ -10960,12 +11140,22 @@ async function sendOpen() {
   if (!SHEET) return;
   const request = 'open-' + (++SHEET.requests);
   SHEET.sentProject = !!pxo;
+  SHEET.roles = set ? item.outputs.map((o) => o.role || null) : null;
   const message = {
     type: 'pixelkiln:open', request,
     asset: { key: item.styleId + '/' + item.assetId, id: item.id, name: item.assetId, width: item.width, height: item.height },
-    png, palette: style ? style.palette : [],
+    png: pngs[0], palette: style ? style.palette : [],
   };
-  const transfer = [png];
+  const transfer = [pngs[0]];
+  if (set) {
+    message.frames = pngs.map((png, i) => ({ role: SHEET.roles[i], png }));
+    // A tile set is not an animation; a slow rate keeps its timeline still-ish.
+    message.fps = isFrameSet(item) ? (item.fps || 12) : 1;
+    for (const png of pngs.slice(1)) transfer.push(png);
+    // The first frame is both png (older editors) and frames[0]; copy it so both transfer.
+    message.png = pngs[0].slice(0);
+    transfer.push(message.png);
+  }
   if (pxo) { message.pxo = pxo; transfer.push(pxo); }
   SHEET.frame.contentWindow.postMessage(message, location.origin, transfer);
   sheetStatus('cool', 'opening');
@@ -10993,8 +11183,9 @@ async function onEditorMessage(m) {
     case 'pixelkiln:opened':
       SHEET.opened = true;
       SHEET.loading.remove();
-      if (m.source === 'pxo') sheetStatus('ok', 'editing the edit file with its ' + (m.layers === 1 ? 'layer' : m.layers + ' layers') + ' restored');
-      else if (SHEET.sentProject) sheetStatus('warn', 'editing the flattened edit file; its layer file could not be opened');
+      if (m.source === 'pxo') sheetStatus('ok', 'editing the edit file' + (m.frames > 1 ? 's' : '') + ' with ' + (m.layers === 1 ? 'the layer' : m.layers + ' layers') + (m.frames > 1 ? ' and ' + m.frames + ' ' + memberNoun(SHEET.item, m.frames) : '') + ' restored');
+      else if (SHEET.sentProject) sheetStatus('warn', 'editing the flattened edit file' + (m.frames > 1 ? 's' : '') + '; the layer file could not be opened');
+      else if (m.source === 'frames') sheetStatus('ok', (SHEET.item.edits.length ? 'editing the edit files' : 'editing a copy of the generated ' + memberNoun(SHEET.item, m.frames)) + ' as ' + m.frames + ' frames' + (isFrameSet(SHEET.item) ? '' : ', one per ' + memberNoun(SHEET.item, 1)));
       else sheetStatus('ok', SHEET.item.edit && SHEET.item.edit.exists ? 'editing the edit file' : 'editing a copy of the generated art');
       sheetButtons();
       break;
@@ -11007,14 +11198,21 @@ async function onEditorMessage(m) {
       const pending = SHEET.pending;
       if (!pending || pending.request !== m.request) return;
       try {
-        const body = { png: await toBase64(m.png), editor: SHEET.ready.editor, protocol: SHEET.ready.version };
+        const body = { editor: SHEET.ready.editor, protocol: SHEET.ready.version };
+        if (SHEET.roles) {
+          if (!Array.isArray(m.frames)) throw new Error('the editor returned no frames');
+          body.frames = [];
+          for (const f of m.frames) body.frames.push({ role: f.role === undefined ? null : f.role, png: await toBase64(f.png) });
+        } else {
+          body.png = await toBase64(m.png);
+        }
         if (m.pxo && m.pxo.byteLength) body.pxo = await toBase64(m.pxo);
         await postHandEdit(SHEET.item, 'save-edit', body);
         const saved = snap.items.find((i) => i.id === SHEET.item.id);
         if (saved) SHEET.item = saved;
         SHEET.dirty = false;
         SHEET.pending = null;
-        ui.notice = { id: SHEET.item.id, text: 'Saved ' + (saved && saved.edit ? saved.edit.path : 'the edit') + '. mount and pack place it in place of the generated art.' };
+        ui.notice = { id: SHEET.item.id, text: 'Saved ' + (saved && saved.edits.length > 1 ? saved.edits.length + ' ' + memberNoun(saved, saved.edits.length) + ' to ' + saved.source : saved && saved.edit ? saved.edit.path : 'the edit') + '. mount and pack place ' + (saved && saved.edits.length > 1 ? 'them' : 'it') + ' in place of the generated art.' };
         render();
         if (pending.close) { closeEditorSheet(true); return; }
         sheetStatus('ok', 'saved');
@@ -11162,7 +11360,7 @@ function clearFilters() {
 function thumb(item) {
   const cell = el('div', 'cell');
   // A hand edit is what ships, so it is what the card shows.
-  const shown = item.edit && item.edit.url && item.editStatus === 'edited' ? [item.edit] : item.outputs.filter((o) => o.url);
+  const shown = item.edit && item.editStatus === 'edited' && item.edits.every((e) => e.url) ? item.edits : item.outputs.filter((o) => o.url);
   if (!shown.length) {
     cell.classList.add('none');
     cell.append(el('span', null, item.state === 'missing' ? 'not generated yet'
@@ -11576,7 +11774,7 @@ function openCompare() {
 // ---- hand edits -------------------------------------------------------------
 
 const EDIT_STATUS_TEXT = {
-  same: 'A copy of the generated art, not changed yet. Open it in your editor and save.',
+  same: 'The generated art\u2019s pixels, not changed yet. Open it in your editor and save.',
   edited: 'Differs from the generated art. mount and pack place this file; the generated file stays as the record.',
   'regenerated-since': 'The generated art changed after this edit was saved \u2014 the edit is based on an older generation.',
   missing: 'The declared file is not on disk.',
@@ -11587,12 +11785,18 @@ async function postHandEdit(item, action, extra) {
   if (item.project) body.project = item.project;
   snap = await postEdit(body);
 }
+// A single PNG or a set of them \u2014 frames, tiles \u2014 is hand-editable, one file
+// per member; a set with a GIF in it is not.
+const editableOutputs = (item) => item.outputs.length && item.outputs.every((o) => o.exists && o.mediaType === 'image/png');
+// What the members of a set are called: frames for an animation, tiles for a tile set.
+const memberNoun = (item, n) => isFrameSet(item) ? (n === 1 ? 'frame' : 'frames')
+  : item.outputs.every((o) => o.role && /^tile/i.test(o.role)) ? (n === 1 ? 'tile' : 'tiles') : (n === 1 ? 'member' : 'members');
 function handEditSection(item) {
-  const canStart = EDITABLE && item.declared && item.asset && projectOf(item)?.manifestSha256 &&
-    item.outputs.length === 1 && item.outputs[0].exists && item.outputs[0].mediaType === 'image/png';
+  const canStart = EDITABLE && item.declared && item.asset && projectOf(item)?.manifestSha256 && editableOutputs(item);
   if (!item.edit && !canStart) return null;
+  const set = item.edits.length > 1;
   const s = el('section', 'meta');
-  s.append(el('h3', null, 'Hand edit'));
+  s.append(el('h3', null, set ? 'Hand edit (' + item.edits.length + ' ' + memberNoun(item, item.edits.length) + ')' : 'Hand edit'));
   if (item.edit) {
     const pair = el('div', 'pair');
     const shared = displayScale(item.width, item.height, 200, 160);
@@ -11606,24 +11810,36 @@ function handEditSection(item) {
       f.append(el('figcaption', null, label));
       return f;
     };
-    pair.append(fig(item.outputs[0], 'generated'), fig(item.edit, 'edit'));
+    // For a set, the member the preview is on; the strip there steps through them.
+    const at = set ? Math.min(ui.member, item.edits.length - 1) : 0;
+    const which = set ? ' \xB7 ' + (item.outputs[at].role || memberNoun(item, 1) + ' ' + (at + 1)) : '';
+    pair.append(fig(item.outputs[at], 'generated' + which), fig(item.edits[at], 'edit' + which));
     s.append(pair);
     const dl = el('dl');
     const tone = item.editStatus === 'edited' ? 'ok' : item.editStatus === 'same' ? 'dim' : 'warn';
     const st = el('span', 'state-' + tone); st.append(el('i', 'dot ' + tone), document.createTextNode(' ' + item.editStatus));
     row(dl, 'status', st);
     row(dl, 'why', EDIT_STATUS_TEXT[item.editStatus] || '');
-    row(dl, 'file', item.edit.path, { mono: true, copy: item.edit.absolutePath });
-    if (item.edit.sha256) row(dl, 'sha256', item.edit.sha256.slice(0, 16) + '\u2026', { mono: true, copy: item.edit.sha256 });
-    row(dl, 'saved', fmtWhen(item.edit.modifiedAt));
+    if (set) {
+      row(dl, 'files', item.source + ' \u2014 one per ' + memberNoun(item, 1) + ': ' + item.edits.map((e) => e.path.split('/').pop()).join(', '), { mono: true, copy: item.edits.map((e) => e.absolutePath).join('\\n') });
+      const differing = item.editChanged.filter(Boolean).length;
+      row(dl, 'changed', differing + ' of ' + item.edits.length + ' ' + memberNoun(item, item.edits.length) + ' differ from the generated art' +
+        (differing ? ': ' + item.edits.filter((e, i) => item.editChanged[i]).map((e) => item.outputs[item.edits.indexOf(e)].role || e.path.split('/').pop()).join(', ') : ''));
+    } else {
+      row(dl, 'file', item.edit.path, { mono: true, copy: item.edit.absolutePath });
+      if (item.edit.sha256) row(dl, 'sha256', item.edit.sha256.slice(0, 16) + '\u2026', { mono: true, copy: item.edit.sha256 });
+    }
+    row(dl, 'saved', fmtWhen(item.edits.reduce((latest, e) => e.modifiedAt && (!latest || e.modifiedAt > latest) ? e.modifiedAt : latest, null)));
     if (item.editMeta) {
-      row(dl, 'editor', item.editMeta.editor + ', ' + fmtWhen(item.editMeta.savedAt) + (item.editMeta.changedSince ? ' \u2014 the file changed since' : ''));
-      if (item.editMeta.basedOn) row(dl, 'based on', item.editMeta.basedOn.slice(0, 16) + '\u2026', { mono: true, copy: item.editMeta.basedOn });
+      row(dl, 'editor', item.editMeta.editor + ', ' + fmtWhen(item.editMeta.savedAt) + (item.editMeta.changedSince ? ' \u2014 a file changed since' : ''));
+      if (item.editMeta.basedOn && !set) row(dl, 'based on', item.editMeta.basedOn.slice(0, 16) + '\u2026', { mono: true, copy: item.editMeta.basedOn });
       if (item.editMeta.project) row(dl, 'layers', item.editMeta.project, { mono: true });
     }
     s.append(dl);
   } else {
-    s.append(el('div', 'state-dim', 'Touch it up in your own editor. The generated file stays untouched; the edit is a sibling file the manifest points at, and mount and pack place that instead.'));
+    s.append(el('div', 'state-dim', item.outputs.length > 1
+      ? 'Touch the ' + memberNoun(item, 2) + ' up in your own editor or in the browser, where they open as ' + (isFrameSet(item) ? 'one animation' : 'the frames of one project') + '. The generated files stay untouched; the edit is one sibling file per ' + memberNoun(item, 1) + ' that the manifest points at, and mount, pack, and export place those instead.'
+      : 'Touch it up in your own editor. The generated file stays untouched; the edit is a sibling file the manifest points at, and mount and pack place that instead.'));
   }
   if (EDITABLE && item.declared && projectOf(item)?.manifestSha256) {
     const acts = el('div', 'hand-actions');
@@ -11651,10 +11867,11 @@ function handEditSection(item) {
     }
     if (item.edit) {
       go('Open in desktop editor', 'start-edit', { open: true }, 'Opened ' + item.edit.path + ' in your editor. Save there, then Refresh.');
-      go('Detach edit', 'detach-edit', {}, 'Detached. The file is still at ' + item.edit.path + '; the generated art is placed again.');
+      go('Detach edit', 'detach-edit', {}, 'Detached. The file' + (set ? 's are' : ' is') + ' still at ' + item.source + '; the generated art is placed again.');
     } else if (canStart) {
-      go('Edit by hand', 'start-edit', { open: true }, 'Created the edit file and opened it in your editor. Save there, then Refresh to see it here.');
-      go('Create edit file only', 'start-edit', { open: false }, 'Created the edit file and declared it in the manifest.');
+      const many = item.outputs.length > 1;
+      go('Edit by hand', 'start-edit', { open: true }, 'Created the edit file' + (many ? 's and opened the first ' + memberNoun(item, 1) : ' and opened it') + ' in your editor. Save there, then Refresh to see it here.');
+      go('Create edit file' + (many ? 's' : '') + ' only', 'start-edit', { open: false }, 'Created the edit file' + (many ? 's' : '') + ' and declared ' + (many ? 'them' : 'it') + ' in the manifest.');
     }
     acts.append(msg);
     s.append(acts);
@@ -12407,11 +12624,305 @@ if (ui.compare.length >= 2 && !ui.open) openCompare();
 }
 var escapeHtml2 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 
+// tools/pixelorama-bridge/pin.json
+var pin_default = {
+  pixelorama: "v1.2.2",
+  godot: "4.7.2",
+  extensionsApi: 9,
+  protocol: 3,
+  release: "editor-pixelorama-v1.2.2-pk.14",
+  files: {
+    "index.apple-touch-icon.png": {
+      sha256: "ee5434873e0fed91e9a888c3ea5a8b79beac25999308be7a6eb41bf4ce640d27",
+      bytes: 1036
+    },
+    "index.audio.position.worklet.js": {
+      sha256: "be33985bc7160d6bf9646f259cd86b259cd67b02ccb297ee5c44f8ac84327bc8",
+      bytes: 2973
+    },
+    "index.audio.worklet.js": {
+      sha256: "5b476a9c9ce642c0ee4256436d1bc31d9c38f868aca0f9a8e2a57c18d2dec2a3",
+      bytes: 7298
+    },
+    "index.html": {
+      sha256: "2974146c89f4df9f796e840947c334aaf3e4fa3dd18bcd7e08db2eabfd0f086e",
+      bytes: 5442
+    },
+    "index.icon.png": {
+      sha256: "42a327d23178ddc26cc97e3560ebca6bc7c575d2a1b12a4837f2462049ca5745",
+      bytes: 1070
+    },
+    "index.js": {
+      sha256: "33c94cb3175f3333b82e2a3be5e8e86f77986f0aa2042b1631f6367a4e5bb6ba",
+      bytes: 279815
+    },
+    "index.pck": {
+      sha256: "736bd383c82fdadf31cc894caf08490b99c5df572aa20db683972c35c7a0465b",
+      bytes: 6429628
+    },
+    "index.png": {
+      sha256: "6e3ca3eb4a99e4c07bdd89ebc873b440ec0ffd66ce1955160da9e7ed80d538d7",
+      bytes: 13558
+    },
+    "index.wasm": {
+      sha256: "fc74679e3b97f76878947fcd4fbe1268cbfa6188182a2e33bbc3f5dc9bfa57d0",
+      bytes: 39514754
+    }
+  }
+};
+
+// src/editor/pin.ts
+var EDITOR_PIN = pin_default;
+var EDITOR_RELEASE_BASE = "https://github.com/gfargo/pixelkiln/releases/download";
+
+// src/editor/install.ts
+import { createHash as createHash5 } from "crypto";
+import { existsSync as existsSync21 } from "fs";
+import { mkdir as mkdir7, readFile as readFile20, rename as rename8, rm as rm10, stat as stat4, writeFile as writeFile10 } from "fs/promises";
+import os2 from "os";
+import path25 from "path";
+var EditorInstallError = class extends Error {
+  constructor(message6, file) {
+    super(message6);
+    this.file = file;
+    this.name = "EditorInstallError";
+  }
+  file;
+};
+function editorToolsRoot() {
+  const override = process.env.PIXELKILN_TOOLS_DIR?.trim();
+  if (override) return path25.resolve(override);
+  if (process.platform === "darwin") return path25.join(os2.homedir(), "Library", "Caches", "pixelkiln", "tools");
+  if (process.platform === "win32") {
+    return path25.join(process.env.LOCALAPPDATA ?? path25.join(os2.homedir(), "AppData", "Local"), "pixelkiln", "tools");
+  }
+  return path25.join(process.env.XDG_CACHE_HOME ?? path25.join(os2.homedir(), ".cache"), "pixelkiln", "tools");
+}
+function editorDir(pin = EDITOR_PIN, root = editorToolsRoot()) {
+  return path25.join(root, "pixelorama", pin.release ?? "unpublished");
+}
+function editorBaseUrl(pin = EDITOR_PIN) {
+  const override = process.env.PIXELKILN_EDITOR_URL?.trim();
+  if (override) return override.replace(/\/+$/, "");
+  if (!pin.release) return null;
+  return `${EDITOR_RELEASE_BASE}/${encodeURIComponent(pin.release)}`;
+}
+async function sha256Of(file) {
+  try {
+    return createHash5("sha256").update(await readFile20(file)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+async function editorStatus(opts = {}) {
+  const pin = opts.pin ?? EDITOR_PIN;
+  const dir = opts.dir ?? editorDir(pin);
+  const missing = [];
+  let installedBytes = 0;
+  let totalBytes = 0;
+  for (const [name, expected] of Object.entries(pin.files)) {
+    totalBytes += expected.bytes;
+    const file = path25.join(dir, name);
+    const info = existsSync21(file) ? await stat4(file).catch(() => null) : null;
+    if (info && info.size === expected.bytes && await sha256Of(file) === expected.sha256) {
+      installedBytes += expected.bytes;
+    } else {
+      missing.push(name);
+    }
+  }
+  const pinned = Object.keys(pin.files).length > 0 && pin.release !== null;
+  return {
+    release: pin.release,
+    dir,
+    installed: pinned && missing.length === 0,
+    missing: pinned ? missing : Object.keys(pin.files),
+    totalBytes,
+    installedBytes
+  };
+}
+async function installEditor(opts = {}) {
+  const pin = opts.pin ?? EDITOR_PIN;
+  const dir = opts.dir ?? editorDir(pin);
+  const baseUrl = opts.baseUrl ?? editorBaseUrl(pin);
+  const doFetch = opts.fetch ?? fetch;
+  const before = await editorStatus({ pin, dir });
+  if (!pin.release || !Object.keys(pin.files).length) {
+    throw new EditorInstallError(
+      "this PixelKiln version pins no published editor build; upgrade, or set PIXELKILN_EDITOR_URL to a build you trust"
+    );
+  }
+  if (!baseUrl) throw new EditorInstallError("no download location for the editor build");
+  await mkdir7(dir, { recursive: true });
+  const downloaded = [];
+  const skipped = Object.keys(pin.files).filter((name) => !before.missing.includes(name));
+  let fetchedBytes = before.installedBytes;
+  const names = before.missing;
+  for (const [index, name] of names.entries()) {
+    const expected = pin.files[name];
+    const report = (phase, received) => opts.onProgress?.({
+      file: name,
+      index,
+      count: names.length,
+      bytes: expected.bytes,
+      totalBytes: before.totalBytes,
+      fetchedBytes: fetchedBytes + received,
+      phase
+    });
+    report("start", 0);
+    const url = `${baseUrl}/${encodeURIComponent(name)}`;
+    const response = await doFetch(url, { signal: opts.signal, redirect: "follow" });
+    if (!response.ok) throw new EditorInstallError(`${name}: ${response.status} ${response.statusText} from ${url}`, name);
+    const bytes = await readBody(response, expected.bytes, (received) => report("progress", received));
+    if (bytes.length !== expected.bytes) {
+      throw new EditorInstallError(`${name}: expected ${expected.bytes} bytes, got ${bytes.length}`, name);
+    }
+    const digest2 = createHash5("sha256").update(bytes).digest("hex");
+    if (digest2 !== expected.sha256) {
+      throw new EditorInstallError(`${name}: sha256 ${digest2.slice(0, 12)}\u2026 does not match the pinned ${expected.sha256.slice(0, 12)}\u2026`, name);
+    }
+    const final = path25.join(dir, name);
+    const tmp = `${final}.${process.pid}.part`;
+    try {
+      await writeFile10(tmp, bytes);
+      await rename8(tmp, final);
+    } finally {
+      await rm10(tmp, { force: true });
+    }
+    fetchedBytes += bytes.length;
+    downloaded.push(name);
+    report("done", 0);
+  }
+  const after = await editorStatus({ pin, dir });
+  if (!after.installed) {
+    throw new EditorInstallError(`editor install is incomplete: ${after.missing.join(", ")}`);
+  }
+  return { ...after, downloaded, skipped };
+}
+async function readBody(response, expectedBytes, onBytes) {
+  if (!response.body) return Buffer.from(await response.arrayBuffer());
+  const chunks = [];
+  let received = 0;
+  const reader = response.body.getReader();
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    received += value.length;
+    if (received > expectedBytes) {
+      await reader.cancel().catch(() => {
+      });
+      break;
+    }
+    onBytes(received);
+  }
+  return Buffer.concat(chunks);
+}
+var EDITOR_CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".wasm": "application/wasm",
+  ".pck": "application/octet-stream",
+  ".png": "image/png",
+  ".json": "application/json; charset=utf-8"
+};
+function editorContentType(name) {
+  return EDITOR_CONTENT_TYPES[path25.extname(name).toLowerCase()] ?? null;
+}
+
+// src/gallery/editor.ts
+import { readFile as readFile21 } from "fs/promises";
+import path26 from "path";
+function editorRoute(release, name = "index.html") {
+  return `/editor/${encodeURIComponent(release)}/${encodeURIComponent(name)}`;
+}
+function createGalleryEditorHandlers(opts = {}) {
+  const pin = opts.pin ?? EDITOR_PIN;
+  const dir = opts.dir ?? editorDir(pin);
+  const log = opts.onProgress ?? (() => {
+  });
+  let verified = null;
+  let checking = null;
+  let installing = null;
+  let running = null;
+  let error = null;
+  const check = () => {
+    if (!checking) {
+      checking = editorStatus({ pin, dir }).then((status) => {
+        verified = status;
+        return status;
+      }).finally(() => {
+        checking = null;
+      });
+    }
+    return checking;
+  };
+  const describe = (status) => ({
+    ...status,
+    pixelorama: pin.pixelorama,
+    protocol: pin.protocol,
+    url: status.installed && pin.release ? editorRoute(pin.release) : null,
+    installing,
+    error
+  });
+  return {
+    release: pin.release,
+    status: async () => describe(verified ?? await check()),
+    install: async () => {
+      if (!running) {
+        error = null;
+        installing = { file: "", index: 0, count: 0, bytes: 0, totalBytes: 0, fetchedBytes: 0, phase: "start" };
+        log(`  installing the editor (Pixelorama ${pin.pixelorama}) into ${dir}`);
+        running = installEditor({
+          pin,
+          dir,
+          baseUrl: opts.baseUrl ?? editorBaseUrl(pin) ?? void 0,
+          ...opts.fetch ? { fetch: opts.fetch } : {},
+          onProgress: (progress) => {
+            installing = progress;
+          }
+        }).then((result) => {
+          verified = result;
+          const mb = (result.totalBytes / 1e6).toFixed(1);
+          log(`  editor ready: ${result.downloaded.length} file(s) fetched, ${result.skipped.length} already present (${mb} MB)`);
+        }).catch((err) => {
+          error = err instanceof Error ? err.message : String(err);
+          verified = null;
+          log(`  editor install failed: ${error}`);
+        }).finally(() => {
+          installing = null;
+          running = null;
+        });
+      }
+      return describe(verified ?? await check());
+    },
+    file: async (release, name) => {
+      if (!pin.release || release !== pin.release) return null;
+      const expected = pin.files[name];
+      const contentType = editorContentType(name);
+      if (!expected || !contentType) return null;
+      const status = verified ?? await check();
+      if (!status.installed) return null;
+      let bytes;
+      try {
+        bytes = await readFile21(path26.join(dir, name));
+      } catch {
+        verified = null;
+        return null;
+      }
+      if (bytes.length !== expected.bytes) {
+        verified = null;
+        return null;
+      }
+      return { bytes, contentType };
+    }
+  };
+}
+
 // src/gallery/server.ts
 import { spawn as spawn3 } from "child_process";
 import { randomBytes } from "crypto";
 import { createServer as createServer2 } from "http";
-import { readFile as readFile20 } from "fs/promises";
+import { readFile as readFile22 } from "fs/promises";
 var MAX_EDIT_BYTES = 48 * 1024 * 1024;
 var EDITOR_CSP = [
   "default-src 'self'",
@@ -12570,7 +13081,7 @@ async function serveGallery(opts) {
         const asset = reviewAssets.get(jobId)?.get(url2.pathname);
         if (!asset) return fail(404, "no such review asset");
         try {
-          const bytes = await readFile20(asset.path);
+          const bytes = await readFile22(asset.path);
           res.writeHead(200, {
             "Content-Type": asset.contentType,
             "Cache-Control": "no-store",
@@ -12646,7 +13157,7 @@ async function serveGallery(opts) {
         if (!asset) return fail(404, "no such gallery media");
         let bytes;
         try {
-          bytes = await readFile20(asset.path);
+          bytes = await readFile22(asset.path);
         } catch {
           return fail(404, "gallery media is no longer on disk; refresh the page");
         }
@@ -12956,19 +13467,19 @@ function createGenerateHandlers(opts) {
 }
 
 // src/pipeline/salvage.ts
-import { readFile as readFile21 } from "fs/promises";
-import { existsSync as existsSync20 } from "fs";
-import path25 from "path";
+import { readFile as readFile23 } from "fs/promises";
+import { existsSync as existsSync22 } from "fs";
+import path27 from "path";
 function providerClaimId(provider, objectId) {
   return `${encodeURIComponent(provider)}:${encodeURIComponent(objectId)}`;
 }
 async function loadClaims(lockPaths, opts = {}) {
   const claimed = /* @__PURE__ */ new Set();
   for (const p of lockPaths) {
-    if (!existsSync20(p)) throw new Error(`Claim lockfile not found: ${p}`);
+    if (!existsSync22(p)) throw new Error(`Claim lockfile not found: ${p}`);
     let parsed;
     try {
-      parsed = parseLock(JSON.parse(await readFile21(p, "utf8")));
+      parsed = parseLock(JSON.parse(await readFile23(p, "utf8")));
     } catch {
       throw new Error(`Claim lockfile is malformed: ${p}`);
     }
@@ -13021,20 +13532,20 @@ function matchOrphanStyle(prompt, manifest) {
   return matchStyleByPattern(prompt, manifest);
 }
 async function loadSiblingManifests(ownManifestPath, workspaceManifestPaths, claimPaths) {
-  const own = path25.resolve(ownManifestPath);
+  const own = path27.resolve(ownManifestPath);
   const siblingManifestPaths = [
     .../* @__PURE__ */ new Set([
       ...workspaceManifestPaths,
-      ...claimPaths.map((c) => path25.join(path25.dirname(path25.resolve(c)), "pixelkiln.manifest.json"))
+      ...claimPaths.map((c) => path27.join(path27.dirname(path27.resolve(c)), "pixelkiln.manifest.json"))
     ])
   ];
   const siblings = [];
   for (const siblingManifestPath of siblingManifestPaths) {
-    if (path25.resolve(siblingManifestPath) === own) continue;
-    if (!existsSync20(siblingManifestPath)) continue;
+    if (path27.resolve(siblingManifestPath) === own) continue;
+    if (!existsSync22(siblingManifestPath)) continue;
     try {
       const { manifest } = await loadManifest(siblingManifestPath);
-      siblings.push({ label: path25.basename(path25.dirname(siblingManifestPath)), manifest });
+      siblings.push({ label: path27.basename(path27.dirname(siblingManifestPath)), manifest });
     } catch {
     }
   }
@@ -13150,8 +13661,8 @@ async function applyTags(provider, decisions, existing, opts = {}) {
 }
 
 // src/pick/salvage-server.ts
-import { mkdir as mkdir7, writeFile as writeFile10, readFile as readFile22 } from "fs/promises";
-import path26 from "path";
+import { mkdir as mkdir8, writeFile as writeFile11, readFile as readFile24 } from "fs/promises";
+import path28 from "path";
 
 // src/pick/salvage-sheet.ts
 var escapeHtml3 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -13316,7 +13827,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
   });
   const html = renderSalvageSheet(orphans, {
     styleId: ctx.styleId,
-    importDir: path26.relative(process.cwd(), ctx.importDir) || "."
+    importDir: path28.relative(process.cwd(), ctx.importDir) || "."
   });
   const byId = new Map(orphans.map((o) => [o.id, o]));
   const existingTags = new Map(orphans.map((o) => [o.id, o.tags]));
@@ -13345,10 +13856,10 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
             if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
             decodePng(buf);
             const assetId = idFromPrompt(orphan.prompt, taken);
-            const rel = path26.join("_salvaged", `${assetId}.png`);
-            const outFile = path26.resolve(ctx.importDir, rel);
-            await mkdir7(path26.dirname(outFile), { recursive: true });
-            await writeFile10(outFile, buf);
+            const rel = path28.join("_salvaged", `${assetId}.png`);
+            const outFile = path28.resolve(ctx.importDir, rel);
+            await mkdir8(path28.dirname(outFile), { recursive: true });
+            await writeFile11(outFile, buf);
             ctx.manifest.assets[assetId] = {
               prompt: orphan.prompt,
               promptByStyle: {},
@@ -13380,7 +13891,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               sourceUrl: durableSource,
               sourceUrls: durableSource ? [{ url: durableSource }] : [],
               outputs: [{
-                path: portableOutputPath(outFile, path26.dirname(ctx.manifestPath)),
+                path: portableOutputPath(outFile, path28.dirname(ctx.manifestPath)),
                 sha256: sha256(buf)
               }],
               submittedAt: orphan.createdAt,
@@ -13404,9 +13915,9 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
         }
       }
       await applyTags(provider, decisions, existingTags, { onProgress: log });
-      const raw = JSON.parse(await readFile22(ctx.manifestPath, "utf8"));
+      const raw = JSON.parse(await readFile24(ctx.manifestPath, "utf8"));
       for (const id of importedAssetIds) raw.assets[id] = ctx.manifest.assets[id];
-      await writeFile10(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
+      await writeFile11(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
       await saveLock(ctx.lockPath, ctx.lock);
       return result;
     }
@@ -13520,17 +14031,23 @@ export {
   ComfyUIProvider,
   DEFAULT_QUALITY_TOLERANCES,
   DEFAULT_RATE_LIMIT,
+  EDITOR_PIN,
+  EDITOR_RELEASE_BASE,
+  EditorInstallError,
   FAKE_PNG,
   FakeProvider,
   GenerateRequestError,
   GenerateRequestSchema,
   GeneratorSchema,
   GridConfidenceSchema,
+  HAND_EDIT_DIR,
+  HandEditCompanionSchema,
   ImageQualityMetricsSchema,
   InheritedStyleSchema,
   LockEntrySchema,
   LockSchema,
   MAX_DOWNLOAD_BYTES,
+  MAX_HAND_EDIT_BYTES,
   MAX_RETRIES,
   ManifestDriftError,
   ManifestEditError,
@@ -13577,12 +14094,19 @@ export {
   countNumberedDescriptions,
   createArtifactBundleManifest,
   createGalleryEditHandler,
+  createGalleryEditorHandlers,
   createGenerateHandlers,
   createProvider,
   currentEntryOutputPath,
   currentOutputPath,
+  detachHandEdit,
   detectMediaType,
   doctor,
+  editorBaseUrl,
+  editorDir,
+  editorRoute,
+  editorStatus,
+  editorToolsRoot,
   evaluateAudit,
   expectedOutputPath,
   exportTileset,
@@ -13594,13 +14118,22 @@ export {
   galleryMediaRoute,
   generationCost,
   groupOrphansByStyle,
+  handEditBase,
+  handEditBases,
+  handEditCompanionPath,
+  handEditMembers,
+  handEditPath,
+  handEditProjectPath,
   hex,
   idFromPrompt,
   imageMetadata,
   inspectCaches,
   inspectQualityProfile,
   inspectRevisionReadiness,
+  installEditor,
   installRecipe,
+  isFrameSetEntry,
+  isMemberSetEntry,
   isSensitiveSourceUrl,
   listBundledRecipes,
   loadClaims,
@@ -13615,12 +14148,14 @@ export {
   measureImageQuality,
   mediaExtension,
   mediaTypeFromExtension,
+  memberPath,
   mergePalettes,
   mountSprites,
   mountStyle,
   normalizeLockOutputPaths,
   normalizeRefinementPalette,
   normalizeTileRules,
+  openInEditor,
   outliers,
   outputId,
   packSprites,
@@ -13640,6 +14175,7 @@ export {
   qualityRecordPath,
   quantizeToPalette,
   readArtifactBundleManifest,
+  readHandEditCompanion,
   readQualityBaseline,
   recipeDigest,
   refineAsset,
@@ -13672,6 +14208,7 @@ export {
   retryAfterMs,
   runPicker,
   runSalvage,
+  saveHandEdit,
   saveLock,
   saveWorkspace,
   scanAssets,
@@ -13683,8 +14220,11 @@ export {
   shouldRetry,
   slugify,
   snapshotQualityBaseline,
+  sourceIsStem,
+  sourceOutputPath,
   specHash,
   spendByUnit,
+  startHandEdit,
   styleImagesBase64,
   submit,
   summarize,