pixelkiln 0.28.0 → 0.29.0

package/dist/cli.js

@@ -872,12 +872,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");
     }
@@ -3673,13 +3668,25 @@ function resolveOutputPath(recordedPath, manifestDir) {
   return path5.resolve(manifestDir, recordedPath.split(/[\\/]/).join(path5.sep));
 }
 function expectedOutputPath(spec, role, index, total, mediaType) {
-  const originalExt = path5.extname(spec.outFile);
+  return memberPath(spec.outFile, role, index, total, mediaType);
+}
+function memberPath(file, role, index, total, mediaType) {
+  const originalExt = path5.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 isFrameSetEntry(entry) {
+  return entry.generator === "frames" && entry.outputs.length > 1;
+}
+function sourceOutputPath(source, entry, index, manifestDir) {
+  const absolute = path5.resolve(manifestDir, source);
+  if (!isFrameSetEntry(entry)) 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);
 }
@@ -4336,12 +4343,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: path7.resolve(manifestDir, source) });
       continue;
     }
+    if (source && isFrameSetEntry(entry)) {
+      outputs = outputs.map((output) => ({ ...output, absolutePath: sourceOutputPath(source, entry, output.index, manifestDir) }));
+    }
     let selected = outputs;
     if (options.outputRoles?.length) {
       selected = outputs.filter(
@@ -4463,11 +4473,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 && isFrameSetEntry(entry))) {
       placements.push({ id, path: path7.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,
@@ -6036,7 +6056,7 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (opts.force) {
       state = "missing";
       reason = "--force";
-    } else if (!entry && spec.source) {
+    } else if (!entry && spec.source && spec.generator !== "frames") {
       if (existsSync8(path13.resolve(spec.root, spec.source))) {
         state = "ok";
         reason = `placed from ${spec.source}; not generated`;
@@ -8246,36 +8266,54 @@ function handEditPath(loaded, spec) {
   const file = inside ? relative : path20.basename(spec.outFile);
   return path20.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 existsSync16(file) ? file : null;
+    if (entry.outputs.length !== 1 && !isFrameSetEntry(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) => existsSync16(member.path))) return null;
+    return members.map(({ role, path: file }) => ({ role, path: file }));
+  }
+  return existsSync16(spec.outFile) ? [{ role: null, path: spec.outFile }] : null;
+}
+function handEditMembers(loaded, spec, lock, editPath) {
+  const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
+  const bases = handEditBases(spec, lock);
+  if (entry && isFrameSetEntry(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 existsSync16(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 && !isFrameSetEntry(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 structural set of ${entry.outputs.length} outputs; hand edits cover single images and frame sets`
     );
   }
   const existing = spec.source ? path20.resolve(loaded.root, spec.source) : null;
   const editPath = existing ?? handEditPath(loaded, spec);
+  const members = handEditMembers(loaded, spec, lock, editPath);
   let created = false;
-  if (!existsSync16(editPath)) {
-    const base = handEditBase(spec, lock);
-    if (!base) {
+  for (const member of members) {
+    if (existsSync16(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(path20.dirname(editPath), { recursive: true });
-    await copyFile(base, editPath);
+    await mkdir6(path20.dirname(member.path), { recursive: true });
+    await copyFile(member.base, member.path);
     created = true;
   }
   const source = portableOutputPath(editPath, loaded.root);
@@ -8292,7 +8330,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) {
@@ -8306,19 +8344,44 @@ async function detachHandEdit(loaded, spec, opts = {}) {
   });
   return { manifestSha256: result.sha256, changed: result.changed };
 }
-var HandEditCompanionSchema = z6.object({
-  version: z6.literal(1),
-  /** sha256 of the generated art the edit started from; null when it started from untracked art. */
+var CompanionOutputSchema = z6.object({
+  /** Output role for a set member; null for a single image. */
+  role: z6.string().nullable(),
+  /** sha256 of the generated file this member started from; null when it started from untracked art. */
   basedOn: z6.string().regex(/^[0-9a-f]{64}$/).nullable(),
-  /** sha256 of the edit PNG as saved, so a later change by another tool is visible. */
-  sha256: z6.string().regex(/^[0-9a-f]{64}$/),
+  /** sha256 of the member as saved, so a later change by another tool is visible. */
+  sha256: z6.string().regex(/^[0-9a-f]{64}$/)
+}).strict();
+var CompanionV2Schema = z6.object({
+  version: z6.literal(2),
   /** Editor identity the bridge reported, e.g. `pixelorama@v1.2.2-stable`. */
   editor: z6.string().min(1),
   protocol: z6.number().int().positive(),
   savedAt: z6.string().datetime(),
   /** Basename of the layered project file beside the edit, when one was kept. */
+  project: z6.string().min(1).nullable(),
+  /** One entry per file, in output order. */
+  outputs: z6.array(CompanionOutputSchema).min(1)
+}).strict();
+var CompanionV1Schema = z6.object({
+  version: z6.literal(1),
+  basedOn: z6.string().regex(/^[0-9a-f]{64}$/).nullable(),
+  sha256: z6.string().regex(/^[0-9a-f]{64}$/),
+  editor: z6.string().min(1),
+  protocol: z6.number().int().positive(),
+  savedAt: z6.string().datetime(),
   project: z6.string().min(1).nullable()
 }).strict();
+var HandEditCompanionSchema = z6.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";
 }
@@ -8340,45 +8403,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 frameSet = entry ? isFrameSetEntry(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 (frameSet) {
+    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} frames (${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 readFile15(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 = frameSet ? `frame ${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 readFile15(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 = frameSet ? `frame ${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 ? path20.basename(projectPath) : null
+    project: projectPath ? path20.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`;
@@ -8425,7 +8522,10 @@ var HandEditRequestSchema = z7.discriminatedUnion("action", [
     assetId: z7.string().min(1),
     styleId: z7.string().min(1),
     expectedSha256: z7.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: z7.array(z7.object({ role: z7.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. */
@@ -8448,18 +8548,23 @@ function createGalleryEditHandler(opts) {
         const started = await startHandEdit(ctx.loaded, ctx.lock, spec, { expectedSha256: request.expectedSha256 });
         log2(`  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);
           log2(`  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
         });
-        log2(`  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;
+        log2(`  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) log2(`  hand edit detached: ${request.styleId}/${request.assetId} (file kept)`);
@@ -8507,6 +8612,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([readFile16(a), readFile16(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];
@@ -8624,6 +8741,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) {
@@ -8634,9 +8753,15 @@ async function buildGallerySnapshot(opts) {
       );
       if (spec.source) {
         const editPath = path22.resolve(root, spec.source);
-        const editSha = existsSync17(editPath) ? await sha256File(editPath) : null;
-        edit = await describeOutput(media, root, editPath, { sha256: editSha });
-        const generated = outputs[0];
+        const memberCount = isFrameSetEntry(entry) ? 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: existsSync17(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);
@@ -8650,14 +8775,30 @@ 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, path22.resolve(root, spec.source))];
@@ -8706,6 +8847,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,
@@ -8763,6 +8906,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,
@@ -9697,10 +9842,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));
@@ -9729,7 +9879,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 + ' frames' : ''));
   const status = el('span', 'st');
   const acts = el('div', 'acts');
   const msg = el('span', 'msg');
@@ -9750,23 +9900,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 frame 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();
@@ -9778,12 +9939,21 @@ 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 }));
+    message.fps = item.fps || 12;
+    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');
@@ -9811,8 +9981,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 + ' 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 frames') + ' as ' + m.frames + ' frames');
       else sheetStatus('ok', SHEET.item.edit && SHEET.item.edit.exists ? 'editing the edit file' : 'editing a copy of the generated art');
       sheetButtons();
       break;
@@ -9825,14 +9996,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 + ' frames 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');
@@ -9980,7 +10158,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'
@@ -10394,7 +10572,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.',
@@ -10405,12 +10583,16 @@ async function postHandEdit(item, action, extra) {
   if (item.project) body.project = item.project;
   snap = await postEdit(body);
 }
+// A single PNG, or an ordered frame set: both are hand-editable, one file per
+// member. Structural sets (tiles, characters) are not.
+const editableOutputs = (item) => item.outputs.length && (item.outputs.length === 1 || isFrameSet(item)) &&
+  item.outputs.every((o) => o.exists && o.mediaType === 'image/png');
 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 + ' frames)' : 'Hand edit'));
   if (item.edit) {
     const pair = el('div', 'pair');
     const shared = displayScale(item.width, item.height, 200, 160);
@@ -10424,24 +10606,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 || 'frame ' + (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 frame: ' + 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 + ' frames 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', isFrameSet(item)
+      ? 'Touch the frames up in your own editor or in the browser, where they open as one animation. The generated files stay untouched; the edit is one sibling file per frame that the manifest points at, and mount and pack 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');
@@ -10469,10 +10663,10 @@ 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.');
+      go('Edit by hand', 'start-edit', { open: true }, 'Created the edit file' + (isFrameSet(item) ? 's and opened the first frame' : ' and opened it') + ' in your editor. Save there, then Refresh to see it here.');
+      go('Create edit file' + (isFrameSet(item) ? 's' : '') + ' only', 'start-edit', { open: false }, 'Created the edit file' + (isFrameSet(item) ? 's' : '') + ' and declared ' + (isFrameSet(item) ? 'them' : 'it') + ' in the manifest.');
     }
     acts.append(msg);
     s.append(acts);
@@ -11785,8 +11979,8 @@ var pin_default = {
   pixelorama: "v1.2.2",
   godot: "4.7.2",
   extensionsApi: 9,
-  protocol: 2,
-  release: "editor-pixelorama-v1.2.2-pk.10",
+  protocol: 3,
+  release: "editor-pixelorama-v1.2.2-pk.14",
   files: {
     "index.apple-touch-icon.png": {
       sha256: "ee5434873e0fed91e9a888c3ea5a8b79beac25999308be7a6eb41bf4ce640d27",
@@ -11801,7 +11995,7 @@ var pin_default = {
       bytes: 7298
     },
     "index.html": {
-      sha256: "ad777659ca39a22872437d44595b749c1637f83994d5f82d50dca861f2186b9c",
+      sha256: "2974146c89f4df9f796e840947c334aaf3e4fa3dd18bcd7e08db2eabfd0f086e",
       bytes: 5442
     },
     "index.icon.png": {
@@ -11813,8 +12007,8 @@ var pin_default = {
       bytes: 279815
     },
     "index.pck": {
-      sha256: "546a3f9851df0854c9f6052f29f1e559de79deb53b936d44a72c3475234c26ff",
-      bytes: 6427868
+      sha256: "736bd383c82fdadf31cc894caf08490b99c5df572aa20db683972c35c7a0465b",
+      bytes: 6429628
     },
     "index.png": {
       sha256: "6e3ca3eb4a99e4c07bdd89ebc873b440ec0ffd66ce1955160da9e7ed80d538d7",
@@ -15121,12 +15315,14 @@ async function main() {
       return;
     }
     const started = await startHandEdit(loaded, lock, spec);
-    log(`  ${started.created ? "created" : "found"} ${started.source}${started.declared ? " and declared it as the asset's source" : ""}`);
+    const set = started.members.length > 1;
+    log(`  ${started.created ? "created" : "found"} ${started.source}${set ? ` (${started.members.length} frames)` : ""}${started.declared ? " and declared it as the asset's source" : ""}`);
+    if (set) for (const member of started.members) log(`    ${member.role ?? ""}  ${path30.relative(process.cwd(), member.path)}`);
     if (args.noOpen) {
-      log(`  edit it with your own tool, then run pixelkiln plan; mount and pack place it in place of the generated art`);
+      log(`  edit ${set ? "them" : "it"} with your own tool, then run pixelkiln plan; mount and pack place ${set ? "them" : "it"} in place of the generated art`);
     } else {
-      const command = openInEditor(started.editPath);
-      log(`  opened with: ${command}${process.env.PIXELKILN_EDITOR ? "" : " (set PIXELKILN_EDITOR to choose the program)"}`);
+      const command = openInEditor(started.members[0].path);
+      log(`  opened ${set ? "the first frame " : ""}with: ${command}${process.env.PIXELKILN_EDITOR ? "" : " (set PIXELKILN_EDITOR to choose the program)"}`);
     }
     return;
   }