pixelkiln 0.62.0 → 0.64.0

package/dist/cli.js

@@ -956,6 +956,14 @@ var CharacterAnimationSchema = z.object({
   template: z.string().min(1).optional(),
   /** Direction to animate. */
   direction: CharacterDirectionSchema.default("south"),
+  /**
+   * Shorthand for one loop in several directions, instead of `direction`.
+   * Expanded when the manifest loads into one loop per named direction
+   * (`<id>.<direction>`) plus a mirror for each direction whose flip is
+   * not named, exactly as if each had been written out. See
+   * `src/loop-directions.ts`.
+   */
+  directions: z.array(CharacterDirectionSchema).min(1).optional(),
   /** Frames to generate without a template (v3). Even, 4 to 16. */
   frames: z.number().int().min(4).max(16).optional(),
   /** Playback rate recorded with the frames; PixelLab does not store one. */
@@ -984,6 +992,13 @@ var CharacterAnimationSchema = z.object({
   /** v3 text loops only: let PixelLab expand the action into a fuller motion description first. */
   enhancePrompt: z.boolean().optional()
 }).strict().superRefine((animation, context) => {
+  if (animation.directions !== void 0) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "directions is expanded when the manifest loads; validate the loaded manifest, not the raw file",
+      path: ["directions"]
+    });
+  }
   if (animation.frames !== void 0 && animation.frames % 2 !== 0) {
     context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
   }
@@ -8358,8 +8373,8 @@ var PixelLabProvider = class _PixelLabProvider {
       const sources = [];
       const terrainTiles = [];
       for (const [index, tile] of tileset.tiles.entries()) {
-        const slug = tile.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "tile";
-        const role = `tile-${String(index).padStart(2, "0")}-${slug}`;
+        const slug2 = tile.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "tile";
+        const role = `tile-${String(index).padStart(2, "0")}-${slug2}`;
         const file = path12.join(_PixelLabProvider.cacheDir(), `${tilesetId}-${index}.png`);
         writeFileSync(file, Buffer.from(tile.image.base64, "base64"));
         sources.push({ url: `file://${file}`, role });
@@ -8478,6 +8493,9 @@ var PixelLabProvider = class _PixelLabProvider {
   async delete(assetId) {
     await this.client.deleteObject(assetId);
   }
+  async deleteCharacter(id) {
+    await this.client.deleteCharacter(id);
+  }
   async *listCharacters() {
     for await (const character of this.client.iterateCharacters(100)) {
       yield remoteCharacter(character);
@@ -9549,10 +9567,102 @@ registerProvider({
 import { readFile as readFile6 } from "fs/promises";
 import { existsSync as existsSync8 } from "fs";
 import path13 from "path";
+
+// src/loop-directions.ts
+var SINGLE_OUTPUT_FIELDS = ["file", "cell", "remoteId", "source", "sourceByStyle", "outputRole"];
+var MIRROR_FIELDS = ["category", "tags", "styles"];
+function loopDirectionId(shorthandId, direction) {
+  return `${shorthandId}.${direction}`;
+}
+function expandLoopDirections(raw) {
+  const families = {};
+  const issues = [];
+  if (!isObject2(raw) || !isObject2(raw.assets)) return { raw, families, issues };
+  const assets = raw.assets;
+  if (!Object.values(assets).some((asset) => isObject2(asset) && isObject2(asset.animation) && "directions" in asset.animation)) {
+    return { raw, families, issues };
+  }
+  const expanded = {};
+  const claimed = new Set(Object.keys(assets));
+  for (const [id, asset] of Object.entries(assets)) {
+    if (!isObject2(asset) || !isObject2(asset.animation) || !("directions" in asset.animation)) {
+      expanded[id] = asset;
+      continue;
+    }
+    const where = `assets.${id}.animation.directions`;
+    const { directions: rawDirections, ...animation } = asset.animation;
+    const parsed = CharacterDirectionSchema.array().min(1).safeParse(rawDirections);
+    if (!parsed.success) {
+      issues.push(`${where}: expected a non-empty list of directions (${CharacterDirectionSchema.options.join(", ")})`);
+      continue;
+    }
+    const directions = parsed.data;
+    const duplicate = directions.find((direction, index) => directions.indexOf(direction) !== index);
+    if (duplicate) {
+      issues.push(`${where}: "${duplicate}" is listed twice`);
+      continue;
+    }
+    if ("direction" in animation) {
+      issues.push(`assets.${id}.animation: direction and directions are mutually exclusive; directions names every loop to make`);
+      continue;
+    }
+    const single = SINGLE_OUTPUT_FIELDS.filter((field) => field in asset);
+    if (single.length) {
+      issues.push(
+        `assets.${id}: ${single.join(", ")} name${single.length === 1 ? "s" : ""} one output, but directions makes ${directions.length} loops; declare the loops explicitly to set ${single.length === 1 ? "it" : "them"} per direction`
+      );
+      continue;
+    }
+    const loops = directions.map((direction) => ({ id: loopDirectionId(id, direction), direction }));
+    const named = new Set(directions);
+    const mirrors = [];
+    for (const { id: loopId, direction } of loops) {
+      const flipped = MIRRORED_DIRECTION[direction];
+      if (flipped === direction || named.has(flipped)) continue;
+      named.add(flipped);
+      mirrors.push({ id: loopDirectionId(id, flipped), of: loopId });
+    }
+    const ids = [...loops.map((loop) => loop.id), ...mirrors.map((mirror) => mirror.id)];
+    const collision = ids.find((expandedId) => claimed.has(expandedId));
+    if (collision) {
+      issues.push(`${where}: expands to "${collision}", which is already declared`);
+      continue;
+    }
+    for (const expandedId of ids) claimed.add(expandedId);
+    for (const loop of loops) {
+      expanded[loop.id] = { ...asset, animation: { ...animation, direction: loop.direction } };
+    }
+    for (const mirror of mirrors) {
+      const inherited = {};
+      for (const field of MIRROR_FIELDS) if (field in asset) inherited[field] = asset[field];
+      expanded[mirror.id] = { mirror: mirror.of, ...inherited };
+    }
+    families[id] = ids;
+  }
+  return { raw: { ...raw, assets: expanded }, families, issues };
+}
+function expandAssetFilter(ids, families) {
+  if (!families) return [...ids];
+  return [...new Set(ids.flatMap((id) => families[id] ?? [id]))];
+}
+function loopShorthandOf(assetId, families) {
+  if (!families) return void 0;
+  return Object.keys(families).find((id) => families[id].includes(assetId));
+}
+function isObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/manifest.ts
 async function loadManifest(manifestPath) {
   const abs = path13.resolve(manifestPath);
   if (!existsSync8(abs)) throw new ProjectError(`No manifest at ${abs}`);
-  const input = ManifestInputSchema.safeParse(JSON.parse(await readFile6(abs, "utf8")));
+  const expansion = expandLoopDirections(JSON.parse(await readFile6(abs, "utf8")));
+  if (expansion.issues.length) {
+    throw new ProjectError(`Manifest at ${abs} is invalid:
+${expansion.issues.map((i) => `  ${i}`).join("\n")}`);
+  }
+  const input = ManifestInputSchema.safeParse(expansion.raw);
   if (!input.success) {
     const issues = formatManifestIssues(input.error.issues);
     throw new ProjectError(`Manifest at ${abs} is invalid:
@@ -9637,7 +9747,8 @@ ${issues}`);
     throw new ProjectError(`Manifest at ${abs} is invalid:
 ${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
   }
-  return { manifest: parsed.data, root: path13.dirname(abs), path: abs };
+  const loopFamilies = Object.keys(expansion.families).length ? { loopFamilies: expansion.families } : {};
+  return { manifest: parsed.data, root: path13.dirname(abs), path: abs, ...loopFamilies };
 }
 function parentAssetId(asset) {
   return asset?.revision?.from ?? asset?.state?.of ?? asset?.animation?.of;
@@ -9721,12 +9832,13 @@ async function resolveSpecs(loaded, filter) {
       );
     }
   }
-  for (const unknownAsset of filter?.assets ?? []) {
+  const assetFilter = expandAssetFilter(filter?.assets ?? [], loaded.loopFamilies);
+  for (const unknownAsset of assetFilter) {
     if (!manifest.assets[unknownAsset]) {
       throw new UsageError(`Unknown asset "${unknownAsset}".`);
     }
   }
-  const requestedAssetIds = new Set(filter?.assets?.length ? filter.assets : Object.keys(manifest.assets));
+  const requestedAssetIds = new Set(assetFilter.length ? assetFilter : Object.keys(manifest.assets));
   const resolutionAssetIds = new Set(requestedAssetIds);
   for (const assetId of [...requestedAssetIds]) {
     let current = parentAssetId(manifest.assets[assetId]);
@@ -11297,6 +11409,9 @@ async function loadClaims(lockPaths, opts = {}) {
       add(entry.objectId);
       add(entry.reviewObjectId);
       add(entry.jobId);
+      for (const id of [entry.objectId, entry.jobId]) {
+        if (id?.includes("#")) add(id.split("#")[0]);
+      }
     }
   }
   return claimed;
@@ -11320,6 +11435,122 @@ async function findOrphans(provider, claimed, opts = {}) {
   })).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
   return { orphans, total: all.length };
 }
+async function findOrphanCharacters(provider, claimed, opts = {}) {
+  const log2 = opts.onProgress ?? (() => {
+  });
+  if (!provider.listCharacters) return { orphans: [], total: 0, partlyClaimed: 0 };
+  const all = [];
+  for await (const character of provider.listCharacters()) all.push(character);
+  log2(`  scanned ${all.length} character(s) on the account`);
+  const isClaimed = (id) => claimed.has(id) || claimed.has(providerClaimId(provider.id, id));
+  const groups = /* @__PURE__ */ new Map();
+  for (const character of all) {
+    const key = character.groupId ?? character.id;
+    groups.set(key, [...groups.get(key) ?? [], character]);
+  }
+  let partlyClaimed = 0;
+  const orphans = [];
+  for (const members of groups.values()) {
+    const unclaimed = members.filter((character) => !isClaimed(character.id));
+    if (!unclaimed.length) continue;
+    if (unclaimed.length < members.length) {
+      partlyClaimed++;
+      continue;
+    }
+    const ordered = [...members].sort((a, b) => Number(isState(a)) - Number(isState(b)) || a.createdAt.localeCompare(b.createdAt));
+    const base = ordered[0];
+    if (base.status !== "completed" || !base.previewUrl) continue;
+    const states = ordered.length - 1;
+    const loops = ordered.reduce((sum, character) => sum + character.animationCount, 0);
+    orphans.push({
+      id: base.id,
+      prompt: base.prompt || base.name || "(no prompt recorded)",
+      width: base.width,
+      height: base.height,
+      createdAt: base.createdAt,
+      previewUrl: base.previewUrl,
+      tags: base.tags ?? [],
+      kind: "character",
+      note: `character \xB7 ${base.directions} directions \xB7 ${states} state${states === 1 ? "" : "s"} \xB7 ${loops} loop${loops === 1 ? "" : "s"}`,
+      members: ordered.map((character) => ({ id: character.id, tags: character.tags ?? [] }))
+    });
+  }
+  orphans.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  return { orphans, total: all.length, partlyClaimed };
+}
+function isState(character) {
+  return Boolean(character.stateName && character.stateName !== "Idle");
+}
+function characterStyleIds(manifest) {
+  return Object.keys(manifest.styles).filter((id) => manifest.styles[id].generator === "character");
+}
+function withoutCharacterStyles(manifest) {
+  const characters = new Set(characterStyleIds(manifest));
+  return {
+    ...manifest,
+    styles: Object.fromEntries(Object.entries(manifest.styles).filter(([id]) => !characters.has(id)))
+  };
+}
+function routeCharacterOrphans(orphans, manifest) {
+  const styleIds = characterStyleIds(manifest);
+  const matched = /* @__PURE__ */ new Map();
+  const unmatched = [];
+  const only = { ...manifest, styles: Object.fromEntries(styleIds.map((id) => [id, manifest.styles[id]])) };
+  for (const orphan of orphans) {
+    const styleId = styleIds.length === 1 ? styleIds[0] : styleIds.length ? matchStyleByPattern(orphan.prompt, only) : null;
+    if (!styleId) {
+      unmatched.push(orphan);
+      continue;
+    }
+    matched.set(styleId, [...matched.get(styleId) ?? [], orphan]);
+  }
+  return { matched, unmatched };
+}
+function characterSalvageAssets(characters, ctx) {
+  const ordered = [...characters].sort((a, b) => Number(isState(a)) - Number(isState(b)) || a.createdAt.localeCompare(b.createdAt));
+  const base = ordered[0];
+  const common = { styles: [ctx.styleId], tags: ["salvaged"] };
+  const assets = {};
+  const skipped = [];
+  const baseId = idFromPrompt(base.name || base.prompt, ctx.taken);
+  const size = base.width === base.height && base.width >= 32 && base.width <= 256 && base.width !== ctx.styleSize ? { size: base.width } : {};
+  assets[baseId] = { prompt: base.prompt || base.name || baseId, remoteId: base.id, ...size, ...common };
+  const assetIdOf = /* @__PURE__ */ new Map([[base.id, baseId]]);
+  for (const state of ordered.slice(1)) {
+    const stateId = uniqueId(`${baseId}_${slug(state.stateName ?? "state")}`, ctx.taken);
+    assetIdOf.set(state.id, stateId);
+    assets[stateId] = { prompt: state.prompt || state.stateName || stateId, state: { of: baseId }, remoteId: state.id, ...common };
+  }
+  for (const character of ordered) {
+    const parentId = assetIdOf.get(character.id);
+    for (const animation of character.animations) {
+      if (!animation.frames.length) continue;
+      const label = animation.name || animation.type;
+      if (!animation.groupId) {
+        skipped.push(`${parentId}: "${label}" ${animation.direction} loop has no animation group id to adopt it by`);
+        continue;
+      }
+      const loopId = uniqueId(`${parentId}.${slug(label)}.${animation.direction}`, ctx.taken);
+      assets[loopId] = {
+        prompt: label,
+        animation: { of: parentId, direction: animation.direction },
+        remoteId: `${character.id}#${animation.groupId}`,
+        ...common
+      };
+    }
+  }
+  return { assets, skipped };
+}
+function slug(text) {
+  return text.toLowerCase().replace(/^pixelkiln:.*\//, "").replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "loop";
+}
+function uniqueId(base, taken) {
+  let id = base;
+  let n = 2;
+  while (taken.has(id)) id = `${base}_${n++}`;
+  taken.add(id);
+  return id;
+}
 var MIN_STYLE_FRAGMENT_LENGTH = 12;
 function matchStyleByPattern(prompt, manifest) {
   const p = prompt.toLowerCase();
@@ -11444,18 +11675,22 @@ async function applyTags(provider, decisions, existing, opts = {}) {
   let tagged = 0;
   let failed = 0;
   for (const { id, action } of decisions) {
-    const current = (existing.get(id) ?? []).filter(
-      (t) => t !== "pixelkiln:keep" && t !== "pixelkiln:discard" && t !== "pixelkiln:imported"
-    );
-    const decisionTag = `pixelkiln:${action === "import" ? "imported" : action}`;
-    const next = [...current.slice(0, 19), decisionTag];
-    if (!provider.setTags) return { tagged, failed };
-    try {
-      await provider.setTags(id, next);
-      tagged++;
-    } catch (err) {
-      failed++;
-      log2(`  tag failed ${id}: ${err instanceof Error ? err.message : String(err)}`);
+    const group = opts.characters?.get(id);
+    const targets = group ?? [{ id, tags: existing.get(id) ?? [] }];
+    for (const target of targets) {
+      const current = target.tags.filter(
+        (t) => t !== "pixelkiln:keep" && t !== "pixelkiln:discard" && t !== "pixelkiln:imported"
+      );
+      const decisionTag = `pixelkiln:${action === "import" ? "imported" : action}`;
+      const next = [...current.slice(0, 19), decisionTag];
+      if (!provider.setTags) return { tagged, failed };
+      try {
+        await provider.setTags(target.id, next, group ? "character" : void 0);
+        tagged++;
+      } catch (err) {
+        failed++;
+        log2(`  tag failed ${target.id}: ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
   }
   return { tagged, failed };
@@ -11601,7 +11836,7 @@ import path19 from "path";
 // src/pick/salvage-sheet.ts
 var escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 function renderSalvageSheet(orphans, ctx) {
-  const safe = orphans.map((o) => ({ ...o, prompt: escapeHtml(o.prompt) }));
+  const safe = orphans.map((o) => ({ ...o, prompt: escapeHtml(o.prompt), ...o.note ? { note: escapeHtml(o.note) } : {} }));
   const data = JSON.stringify(safe).replace(/<\//g, "<\\/");
   const styleId = ctx ? escapeHtml(ctx.styleId) : null;
   const importDir = ctx ? escapeHtml(ctx.importDir) : null;
@@ -11687,6 +11922,7 @@ ITEMS.forEach((o, i) => {
   el.innerHTML =
     '<div class="thumb"><img src="' + o.previewUrl + '" loading="lazy"></div>' +
     '<div class="meta">' + o.width + '\xD7' + o.height + ' \xB7 ' + o.createdAt.slice(0,10) + '</div>' +
+    (o.note ? '<div class="meta">' + o.note + '</div>' : '') +
     '<div class="prompt">' + o.prompt + '</div>' +
     '<div class="acts">' +
       '<button data-a="import">import</button>' +
@@ -11864,6 +12100,9 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
   });
   const byId = new Map(orphans.map((o) => [o.id, o]));
   const existingTags = new Map(orphans.map((o) => [o.id, o.tags]));
+  const characterMembers = new Map(
+    orphans.flatMap((o) => o.kind === "character" && o.members ? [[o.id, o.members]] : [])
+  );
   return serveReviewPage({
     html,
     port: opts.port,
@@ -11880,10 +12119,34 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
       const result = { imported: 0, kept: 0, discarded: 0, failed: 0 };
       const taken = new Set(Object.keys(ctx.manifest.assets));
       const importedAssetIds = [];
+      const characterAssetIds = [];
       for (const decision of decisions) {
         const orphan = byId.get(decision.id);
         if (!orphan) continue;
-        if (decision.action === "import") {
+        if (decision.action === "import" && orphan.kind === "character") {
+          try {
+            if (!provider.getCharacter) throw new Error(`provider ${provider.id} cannot read characters`);
+            const details = [];
+            for (const member of orphan.members ?? [{ id: orphan.id }]) details.push(await provider.getCharacter(member.id));
+            const style = ctx.manifest.styles[ctx.styleId];
+            const { assets, skipped } = characterSalvageAssets(details, {
+              styleId: ctx.styleId,
+              styleSize: style?.size,
+              taken
+            });
+            for (const [assetId, asset] of Object.entries(assets)) {
+              ctx.manifest.assets[assetId] = asset;
+              importedAssetIds.push(assetId);
+              characterAssetIds.push(assetId);
+            }
+            for (const line of skipped) log2(`  not imported: ${line}`);
+            result.imported++;
+            log2(`  imported character ${orphan.id} as ${Object.keys(assets).length} asset(s)`);
+          } catch (err) {
+            result.failed++;
+            log2(`  import failed ${orphan.id}: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        } else if (decision.action === "import") {
           try {
             const buf = await provider.download(orphan.previewUrl);
             if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
@@ -11947,11 +12210,12 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
           result.discarded++;
         }
       }
-      await applyTags(provider, decisions, existingTags, { onProgress: log2 });
+      await applyTags(provider, decisions, existingTags, { onProgress: log2, characters: characterMembers });
       const raw = JSON.parse(await readFile14(ctx.manifestPath, "utf8"));
       for (const id of importedAssetIds) raw.assets[id] = ctx.manifest.assets[id];
       await writeFile9(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
       await saveLock(ctx.lockPath, ctx.lock);
+      if (characterAssetIds.length) result.characterAssetIds = characterAssetIds;
       return result;
     }
   });
@@ -12393,7 +12657,18 @@ async function runSalvage2(args) {
   const claimed = await loadClaims(lockPaths, { provider: provider.id });
   const { orphans, total } = await findOrphans(provider, claimed, { onProgress: diag });
   diag(`  ${claimed.size} claimed \xB7 ${orphans.length} unclaimed of ${total}`);
-  if (!orphans.length) {
+  const characterScan = await findOrphanCharacters(provider, claimed, { onProgress: diag });
+  const characterOrphans = characterScan.orphans;
+  if (characterScan.total) {
+    diag(`  ${characterOrphans.length} unclaimed character group(s) of ${characterScan.total} character(s)`);
+  }
+  if (characterScan.partlyClaimed) {
+    diag(
+      `  ${characterScan.partlyClaimed} character group(s) are partly claimed (a base or state some project uses);
+  they are left out here. Declare their other states and run \`pixelkiln adopt\` instead.`
+    );
+  }
+  if (!orphans.length && !characterOrphans.length) {
     if (jsonMode) log("[]");
     else log(`
   nothing to triage`);
@@ -12404,9 +12679,10 @@ async function runSalvage2(args) {
     workspaceProjects.map((p) => resolveProject(workspaceDir, p).manifestPath),
     args.claims
   );
-  const { matched, unmatched, elsewhere } = groupOrphansByStyle(orphans, accountManifest, siblings);
-  const multiStyle = Object.keys(accountManifest.styles).length > 1;
-  if (multiStyle) {
+  const objectManifest = withoutCharacterStyles(accountManifest);
+  const { matched, unmatched, elsewhere } = groupOrphansByStyle(orphans, objectManifest, siblings);
+  const multiStyle = Object.keys(objectManifest.styles).length > 1;
+  if (multiStyle && orphans.length) {
     diag(`
   by style (matched against each style's prompt prefix/suffix):`);
     for (const [id, list] of matched) diag(`    ${id.padEnd(24)} ${list.length}`);
@@ -12427,16 +12703,33 @@ async function runSalvage2(args) {
   out of the sessions below; force them into one style with --style <id>.`
     );
   }
+  const characterRoutes = routeCharacterOrphans(characterOrphans, accountManifest);
+  if (characterOrphans.length && !characterStyleIds(accountManifest).length) {
+    diag(
+      `
+  ${characterOrphans.length} unclaimed character group(s), but this manifest has no character style
+  to import them into. Add a style with "generator": "character" to triage them.`
+    );
+  } else if (characterRoutes.unmatched.length) {
+    diag(
+      `
+  ${characterRoutes.unmatched.length} character group(s) don't match any character style's pattern;
+  force them into one with --style <character style id>.`
+    );
+  }
   if (args.dryRun) {
+    const listed = [...orphans, ...characterOrphans];
     if (args.json) {
-      log(JSON.stringify(orphans, null, 2));
+      log(JSON.stringify(listed, null, 2));
     } else {
-      const shown = args.all ? orphans : orphans.slice(0, 30);
+      const shown = args.all ? listed : listed.slice(0, 30);
       for (const o of shown) {
-        log(`    ${o.id}  ${o.width}x${o.height}  ${o.createdAt.slice(0, 10)}  ${o.prompt.slice(0, 50)}`);
+        log(
+          `    ${o.id}  ${o.width}x${o.height}  ${o.createdAt.slice(0, 10)}  ` + (o.kind === "character" ? `[${o.note}]  ` : "") + o.prompt.slice(0, 50)
+        );
       }
-      if (!args.all && orphans.length > 30) {
-        log(`    \u2026 and ${orphans.length - 30} more (--all for the full list, --json for machine-readable)`);
+      if (!args.all && listed.length > 30) {
+        log(`    \u2026 and ${listed.length - 30} more (--all for the full list, --json for machine-readable)`);
       }
     }
     diag(`
@@ -12457,6 +12750,12 @@ async function runSalvage2(args) {
     await saveLock(args.lock, lock);
     if (n) log(`  baselined ${n} imported asset(s) against the manifest`);
   };
+  const adoptImported = async (assetIds) => {
+    const resolve = async () => (await resolveSpecs(await loadManifest(args.manifest), { assets: assetIds })).filter((spec) => spec.provider === provider.id);
+    const adopted = await adoptCharacters(provider, await resolve(), lock, args.lock, { onProgress: log, resolve });
+    log(`  adopted ${adopted.matched} of ${assetIds.length} imported character asset(s)`);
+    for (const line of adopted.unmatched) log(`    not adopted: ${line}`);
+  };
   const runOne = async (styleId, list) => {
     const style = accountManifest.styles[styleId];
     const res = await runSalvage(
@@ -12476,10 +12775,19 @@ async function runSalvage2(args) {
       `  imported ${res.imported} \xB7 kept ${res.kept} \xB7 tagged-discard ${res.discarded}` + (res.failed ? ` \xB7 failed ${res.failed}` : "")
     );
     if (res.imported > 0) await rebaseline();
+    if (res.characterAssetIds?.length) await adoptImported(res.characterAssetIds);
     return res;
   };
   if (args.styles.length) {
-    const res = await runOne(args.styles[0], orphans);
+    const styleId = args.styles[0];
+    const isCharacterStyle = characterStyleIds(accountManifest).includes(styleId);
+    const list = isCharacterStyle ? characterOrphans : orphans;
+    if (!list.length) {
+      log(`
+  nothing unclaimed to triage into ${styleId}`);
+      return;
+    }
+    const res = await runOne(styleId, list);
     if (res.discarded) {
       log(`
   Nothing was deleted. To actually remove the discarded objects:`);
@@ -12488,17 +12796,18 @@ async function runSalvage2(args) {
     }
     return;
   }
-  if (!matched.size) {
+  const sessions = [...matched, ...characterRoutes.matched];
+  if (!sessions.length) {
     log(`
   nothing matched a known style; nothing to triage`);
     return;
   }
   log(`
-  ${matched.size} session(s), one style at a time:`);
+  ${sessions.length} session(s), one style at a time:`);
   let totalDiscarded = 0;
-  for (const [styleId, list] of matched) {
+  for (const [styleId, list] of sessions) {
     log(`
-  ${styleId} (${list.length})`);
+  ${styleId} (${list.length}${list[0]?.kind === "character" ? " character group(s)" : ""})`);
     const res = await runOne(styleId, list);
     totalDiscarded += res.discarded;
   }
@@ -12516,16 +12825,30 @@ async function runPurge(args) {
   const doomed = [];
   for await (const obj of requireList(provider)()) {
     if (obj.tags.includes("pixelkiln:discard")) {
-      doomed.push({ id: obj.id, prompt: obj.prompt });
+      doomed.push({ id: obj.id, prompt: obj.prompt, kind: "object" });
+    }
+  }
+  if (provider.listCharacters && provider.deleteCharacter) {
+    for await (const character of provider.listCharacters()) {
+      if (character.tags.includes("pixelkiln:discard")) {
+        const label = character.stateName && character.stateName !== "Idle" ? ` (${character.stateName})` : "";
+        doomed.push({ id: character.id, prompt: `${character.prompt || character.name}${label}`, kind: "character" });
+      }
     }
   }
   if (!doomed.length) {
     log(`  nothing tagged pixelkiln:discard; run \`pixelkiln salvage\` first`);
     return;
   }
+  const characters = doomed.filter((d) => d.kind === "character").length;
+  const objects = doomed.length - characters;
+  const counted = [
+    objects ? `${objects} object(s)` : "",
+    characters ? `${characters} character(s)` : ""
+  ].filter(Boolean).join(" and ");
   log(`
-  ${doomed.length} object(s) tagged for discard:`);
-  for (const d of doomed.slice(0, 20)) log(`    ${d.id}  ${d.prompt.slice(0, 60)}`);
+  ${counted} tagged for discard:`);
+  for (const d of doomed.slice(0, 20)) log(`    ${d.id}  ${d.kind === "character" ? "[character] " : ""}${d.prompt.slice(0, 60)}`);
   if (doomed.length > 20) log(`    \u2026 and ${doomed.length - 20} more`);
   if (args.dryRun) {
     log(`
@@ -12536,7 +12859,8 @@ async function runPurge(args) {
   This permanently deletes them from your ${provider.id} account.`);
   log(`  Any local files already downloaded are untouched, but the objects`);
   log(`  and their URLs are gone and cannot be re-downloaded.`);
-  if (!await confirm(`  Delete ${doomed.length} object(s)?`, args.yes)) {
+  if (characters) log(`  A deleted character takes its animations with it.`);
+  if (!await confirm(`  Delete ${counted}?`, args.yes)) {
     log(`  aborted`);
     return;
   }
@@ -12544,7 +12868,8 @@ async function runPurge(args) {
   let failed = 0;
   for (const d of doomed) {
     try {
-      await requireDelete(provider)(d.id);
+      if (d.kind === "character") await provider.deleteCharacter(d.id);
+      else await requireDelete(provider)(d.id);
       deleted++;
     } catch (err) {
       failed++;
@@ -12733,11 +13058,21 @@ function assetStyles(raw, asset) {
   const own = Array.isArray(asset.styles) ? asset.styles : [];
   return own.length ? own : Object.keys(raw.styles ?? {});
 }
+function declaredAssets(raw) {
+  const expanded = expandLoopDirections(raw).raw;
+  return new Set(Object.keys(expanded.assets ?? {}));
+}
+function undeclaredAsset(raw, assetId) {
+  const shorthand = loopShorthandOf(assetId, expandLoopDirections(raw).families);
+  return new ManifestEditError(
+    shorthand ? `asset "${assetId}" is expanded from "${shorthand}"'s animation.directions; edit "${shorthand}" (it applies to every direction), or write this direction out as its own asset to change it alone` : `asset "${assetId}" is not declared by the manifest`
+  );
+}
 function applyEdit(raw, edit) {
   raw.assets ??= {};
   if (edit.action === "set-source" || edit.action === "clear-source") {
     const asset2 = Object.hasOwn(raw.assets, edit.assetId) ? raw.assets[edit.assetId] : void 0;
-    if (!asset2) throw new ManifestEditError(`asset "${edit.assetId}" is not declared by the manifest`);
+    if (!asset2) throw undeclaredAsset(raw, edit.assetId);
     if (!raw.styles || !Object.hasOwn(raw.styles, edit.styleId)) {
       throw new ManifestEditError(`unknown style "${edit.styleId}"`);
     }
@@ -12789,7 +13124,7 @@ function applyEdit(raw, edit) {
     return;
   }
   if (edit.action === "add-asset") {
-    if (Object.hasOwn(raw.assets, edit.assetId)) {
+    if (declaredAssets(raw).has(edit.assetId)) {
       throw new ManifestEditError(`asset "${edit.assetId}" already exists`);
     }
     const { styles, tags, ...rest } = edit.asset;
@@ -12803,20 +13138,20 @@ function applyEdit(raw, edit) {
       }
       asset2.styles = styles;
     }
-    if (edit.asset.revision && !Object.hasOwn(raw.assets, edit.asset.revision.from)) {
+    if (edit.asset.revision && !declaredAssets(raw).has(edit.asset.revision.from)) {
       throw new ManifestEditError(`revision parent "${edit.asset.revision.from}" is not declared by the manifest`);
     }
-    if (edit.asset.state && !Object.hasOwn(raw.assets, edit.asset.state.of)) {
+    if (edit.asset.state && !declaredAssets(raw).has(edit.asset.state.of)) {
       throw new ManifestEditError(`state parent "${edit.asset.state.of}" is not declared by the manifest`);
     }
-    if (edit.asset.animation && !Object.hasOwn(raw.assets, edit.asset.animation.of)) {
+    if (edit.asset.animation && !declaredAssets(raw).has(edit.asset.animation.of)) {
       throw new ManifestEditError(`animation parent "${edit.asset.animation.of}" is not declared by the manifest`);
     }
     raw.assets[edit.assetId] = asset2;
     return;
   }
   const asset = Object.hasOwn(raw.assets, edit.assetId) ? raw.assets[edit.assetId] : void 0;
-  if (!asset) throw new ManifestEditError(`asset "${edit.assetId}" is not declared by the manifest`);
+  if (!asset) throw undeclaredAsset(raw, edit.assetId);
   const { patch } = edit;
   if (patch.prompt !== void 0) asset.prompt = patch.prompt;
   if (patch.promptForStyle) {
@@ -13604,6 +13939,7 @@ async function describeQuality(media, root, inspection) {
 }
 async function buildGallerySnapshot(opts) {
   const { loaded, specs, lock } = opts;
+  const filter = opts.filter?.assets?.length ? { ...opts.filter, assets: expandAssetFilter(opts.filter.assets, loaded.loopFamilies) } : opts.filter;
   const root = loaded.root;
   const media = /* @__PURE__ */ new Map();
   const plan = await buildPlan(specs, lock);
@@ -13748,7 +14084,7 @@ async function buildGallerySnapshot(opts) {
   for (const [key, entry] of Object.entries(lock.entries)) {
     if (shown.has(key)) continue;
     if (isDeclared(loaded, entry.styleId, entry.assetId)) continue;
-    if (!matchesFilter(opts.filter, entry.styleId, entry.assetId)) continue;
+    if (!matchesFilter(filter, entry.styleId, entry.assetId)) continue;
     const outputs = await Promise.all(
       entry.outputs.map(
         (output) => describeOutput(media, root, resolveOutputPath(output.path, root), output)
@@ -13914,7 +14250,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
     try {
       const loaded = await loadManifest(manifestPath);
       const styleFilter = filter.styles.filter((id) => loaded.manifest.styles[id]);
-      const assetFilter = filter.assets.filter((id) => loaded.manifest.assets[id]);
+      const assetFilter = expandAssetFilter(filter.assets, loaded.loopFamilies).filter((id) => loaded.manifest.assets[id]);
       const excluded = filter.styles.length > 0 && styleFilter.length === 0 || filter.assets.length > 0 && assetFilter.length === 0;
       const lock = await loadLock(lockPath);
       let projectItems = [];