pixelkiln 0.63.0 → 0.64.0

package/dist/index.d.cts

@@ -363,6 +363,12 @@ interface Provider {
     listCharacters?(): AsyncGenerator<RemoteCharacter>;
     /** One character with its rotations and animations. */
     getCharacter?(id: string): Promise<RemoteCharacterDetail>;
+    /**
+     * Irreversible: the character and its animations. A state is its own
+     * character record and is deleted on its own. Only reached via `purge`,
+     * behind explicit confirmation.
+     */
+    deleteCharacter?(id: string): Promise<void>;
     /**
      * The object's source URLs as the service hands them out now, for
      * `fetch --refresh` when recorded URLs go stale (PixelLab stamps a
@@ -12502,6 +12508,7 @@ declare class PixelLabProvider implements Provider {
     setTags(objectId: string, tags: string[], generator?: Generator): Promise<void>;
     list(): AsyncGenerator<RemoteAsset>;
     delete(assetId: string): Promise<void>;
+    deleteCharacter(id: string): Promise<void>;
     listCharacters(): AsyncGenerator<RemoteCharacter>;
     getCharacter(id: string): Promise<RemoteCharacterDetail>;
     /**
@@ -12835,6 +12842,7 @@ declare class FakeProvider implements Provider {
     /** Characters answer with whatever the store holds now; other objects keep their URLs. */
     refreshSources(objectId: string, context: RefreshContext): Promise<OutputSource[] | null | undefined>;
     delete(assetId: string): Promise<void>;
+    deleteCharacter(id: string): Promise<void>;
     /** Seed a pre-existing remote asset, for adopt / salvage tests. */
     seed(asset: Partial<RemoteAsset> & {
         id: string;
@@ -18234,6 +18242,18 @@ interface Orphan {
     createdAt: string;
     previewUrl: string;
     tags: string[];
+    /**
+     * `character` for a character group (a base and its states), triaged as
+     * one card; absent for an ordinary account object.
+     */
+    kind?: "character";
+    /** One line the triage sheet shows under the size, e.g. a character's direction/state/loop counts. */
+    note?: string;
+    /** A character group's every character id, base first, with its current tags; a decision applies to all of them. */
+    members?: {
+        id: string;
+        tags: string[];
+    }[];
 }
 declare function findOrphans(provider: Provider, claimed: Set<string>, opts?: {
     onProgress?: (msg: string) => void;
@@ -18318,6 +18338,11 @@ interface SalvageDecision {
  */
 declare function applyTags(provider: Provider, decisions: SalvageDecision[], existing: Map<string, string[]>, opts?: {
     onProgress?: (msg: string) => void;
+    /** Character groups by their card id: the member ids and current tags a decision applies to. */
+    characters?: Map<string, {
+        id: string;
+        tags: string[];
+    }[]>;
 }): Promise<{
     tagged: number;
     failed: number;
@@ -18328,14 +18353,22 @@ interface SalvageResult {
     kept: number;
     discarded: number;
     failed: number;
+    /**
+     * Manifest assets written for imported character groups. They have no
+     * lock entries yet: the caller adopts them (`adoptCharacters`) once the
+     * manifest is saved, which downloads every rotation and frame.
+     */
+    characterAssetIds?: string[];
 }
 /**
  * Serves the triage sheet and applies decisions.
  *
  * `import` is the only action that touches local state: it downloads the image,
  * writes a manifest asset and a lock entry, so a recovered sprite becomes a
- * first-class tracked asset rather than a loose file. `keep` and `discard` only
- * write tags upstream; no object is ever deleted here.
+ * first-class tracked asset rather than a loose file. A character group's
+ * import writes its base, states, and loops as manifest assets only; the
+ * caller adopts them. `keep` and `discard` only write tags upstream (on every
+ * member of a character group); nothing is ever deleted here.
  */
 declare function runSalvage(provider: Provider, orphans: Orphan[], ctx: {
     manifestPath: string;

package/dist/index.d.ts

@@ -363,6 +363,12 @@ interface Provider {
     listCharacters?(): AsyncGenerator<RemoteCharacter>;
     /** One character with its rotations and animations. */
     getCharacter?(id: string): Promise<RemoteCharacterDetail>;
+    /**
+     * Irreversible: the character and its animations. A state is its own
+     * character record and is deleted on its own. Only reached via `purge`,
+     * behind explicit confirmation.
+     */
+    deleteCharacter?(id: string): Promise<void>;
     /**
      * The object's source URLs as the service hands them out now, for
      * `fetch --refresh` when recorded URLs go stale (PixelLab stamps a
@@ -12502,6 +12508,7 @@ declare class PixelLabProvider implements Provider {
     setTags(objectId: string, tags: string[], generator?: Generator): Promise<void>;
     list(): AsyncGenerator<RemoteAsset>;
     delete(assetId: string): Promise<void>;
+    deleteCharacter(id: string): Promise<void>;
     listCharacters(): AsyncGenerator<RemoteCharacter>;
     getCharacter(id: string): Promise<RemoteCharacterDetail>;
     /**
@@ -12835,6 +12842,7 @@ declare class FakeProvider implements Provider {
     /** Characters answer with whatever the store holds now; other objects keep their URLs. */
     refreshSources(objectId: string, context: RefreshContext): Promise<OutputSource[] | null | undefined>;
     delete(assetId: string): Promise<void>;
+    deleteCharacter(id: string): Promise<void>;
     /** Seed a pre-existing remote asset, for adopt / salvage tests. */
     seed(asset: Partial<RemoteAsset> & {
         id: string;
@@ -18234,6 +18242,18 @@ interface Orphan {
     createdAt: string;
     previewUrl: string;
     tags: string[];
+    /**
+     * `character` for a character group (a base and its states), triaged as
+     * one card; absent for an ordinary account object.
+     */
+    kind?: "character";
+    /** One line the triage sheet shows under the size, e.g. a character's direction/state/loop counts. */
+    note?: string;
+    /** A character group's every character id, base first, with its current tags; a decision applies to all of them. */
+    members?: {
+        id: string;
+        tags: string[];
+    }[];
 }
 declare function findOrphans(provider: Provider, claimed: Set<string>, opts?: {
     onProgress?: (msg: string) => void;
@@ -18318,6 +18338,11 @@ interface SalvageDecision {
  */
 declare function applyTags(provider: Provider, decisions: SalvageDecision[], existing: Map<string, string[]>, opts?: {
     onProgress?: (msg: string) => void;
+    /** Character groups by their card id: the member ids and current tags a decision applies to. */
+    characters?: Map<string, {
+        id: string;
+        tags: string[];
+    }[]>;
 }): Promise<{
     tagged: number;
     failed: number;
@@ -18328,14 +18353,22 @@ interface SalvageResult {
     kept: number;
     discarded: number;
     failed: number;
+    /**
+     * Manifest assets written for imported character groups. They have no
+     * lock entries yet: the caller adopts them (`adoptCharacters`) once the
+     * manifest is saved, which downloads every rotation and frame.
+     */
+    characterAssetIds?: string[];
 }
 /**
  * Serves the triage sheet and applies decisions.
  *
  * `import` is the only action that touches local state: it downloads the image,
  * writes a manifest asset and a lock entry, so a recovered sprite becomes a
- * first-class tracked asset rather than a loose file. `keep` and `discard` only
- * write tags upstream; no object is ever deleted here.
+ * first-class tracked asset rather than a loose file. A character group's
+ * import writes its base, states, and loops as manifest assets only; the
+ * caller adopts them. `keep` and `discard` only write tags upstream (on every
+ * member of a character group); nothing is ever deleted here.
  */
 declare function runSalvage(provider: Provider, orphans: Orphan[], ctx: {
     manifestPath: string;

package/dist/index.js

@@ -4734,8 +4734,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 = path.join(_PixelLabProvider.cacheDir(), `${tilesetId}-${index}.png`);
         writeFileSync(file, Buffer.from(tile.image.base64, "base64"));
         sources.push({ url: `file://${file}`, role });
@@ -4854,6 +4854,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);
@@ -6877,6 +6880,8 @@ var FakeProvider = class {
     this.tags.set(objectId, [...tags]);
     const asset = this.assets.get(objectId);
     if (asset) asset.tags = [...tags];
+    const character = this.characters.get(objectId.split("#")[0]);
+    if (character) character.tags = [...tags];
   }
   /**
    * Assigned in the constructor rather than declared as a method, so a test can
@@ -6911,6 +6916,10 @@ var FakeProvider = class {
     this.deleted.push(assetId);
     this.assets.delete(assetId);
   }
+  async deleteCharacter(id) {
+    this.deleted.push(id);
+    this.characters.delete(id);
+  }
   /** Seed a pre-existing remote asset, for adopt / salvage tests. */
   seed(asset) {
     const full = {
@@ -16435,6 +16444,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;
@@ -16458,6 +16470,54 @@ async function findOrphans(provider, claimed, opts = {}) {
   })).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
   return { orphans, total: all.length };
 }
+function isState(character) {
+  return Boolean(character.stateName && character.stateName !== "Idle");
+}
+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();
@@ -16587,18 +16647,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++;
-      log(`  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++;
+        log(`  tag failed ${target.id}: ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
   }
   return { tagged, failed };
@@ -16611,7 +16675,7 @@ import path33 from "path";
 // src/pick/salvage-sheet.ts
 var escapeHtml3 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 function renderSalvageSheet(orphans, ctx) {
-  const safe = orphans.map((o) => ({ ...o, prompt: escapeHtml3(o.prompt) }));
+  const safe = orphans.map((o) => ({ ...o, prompt: escapeHtml3(o.prompt), ...o.note ? { note: escapeHtml3(o.note) } : {} }));
   const data = JSON.stringify(safe).replace(/<\//g, "<\\/");
   const styleId = ctx ? escapeHtml3(ctx.styleId) : null;
   const importDir = ctx ? escapeHtml3(ctx.importDir) : null;
@@ -16697,6 +16761,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>' +
@@ -16775,6 +16840,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,
@@ -16791,10 +16859,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) log(`  not imported: ${line}`);
+            result.imported++;
+            log(`  imported character ${orphan.id} as ${Object.keys(assets).length} asset(s)`);
+          } catch (err) {
+            result.failed++;
+            log(`  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");
@@ -16858,11 +16950,12 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
           result.discarded++;
         }
       }
-      await applyTags(provider, decisions, existingTags, { onProgress: log });
+      await applyTags(provider, decisions, existingTags, { onProgress: log, characters: characterMembers });
       const raw = JSON.parse(await readFile26(ctx.manifestPath, "utf8"));
       for (const id of importedAssetIds) raw.assets[id] = ctx.manifest.assets[id];
       await writeFile13(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
       await saveLock(ctx.lockPath, ctx.lock);
+      if (characterAssetIds.length) result.characterAssetIds = characterAssetIds;
       return result;
     }
   });