pixelkiln 0.22.0 → 0.24.0

package/dist/index.js

@@ -258,6 +258,15 @@ var AssetSchema = z.object({
    * that wasn't. `prompt` still records what was asked for.
    */
   source: z.string().optional(),
+  /**
+   * Per-style replacement for `source`, keyed by style id.
+   *
+   * A hand edit belongs to one generation: the same asset generated in two
+   * styles is two different pictures, so the touch-up of one must not be
+   * placed for the other. `pixelkiln edit` writes here when an asset is in
+   * more than one style, and to `source` when it is in exactly one.
+   */
+  sourceByStyle: z.record(z.string().min(1)).default({}),
   /** Controlled generation derived from another asset in the same style. */
   revision: RevisionSchema.optional(),
   /**
@@ -292,7 +301,7 @@ var AssetSchema = z.object({
     z.array(z.union([z.string(), z.number().finite(), z.boolean()])).min(2).max(64)
   ])).default({})
 }).strict().superRefine((asset, context) => {
-  if (asset.source && asset.revision) {
+  if ((asset.source || Object.keys(asset.sourceByStyle).length) && asset.revision) {
     context.addIssue({
       code: z.ZodIssueCode.custom,
       message: "source and revision are mutually exclusive",
@@ -535,11 +544,11 @@ var PixelLabClient = class {
    * common than the failure mode of retrying (a duplicate object), and a
    * duplicate is visible and free to delete whereas a silent gap is neither.
    */
-  async request(path25, init, attempt = 0) {
+  async request(path27, init, attempt = 0) {
     const auth = this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`;
     let res;
     try {
-      res = await fetch(`${BASE}${path25}`, {
+      res = await fetch(`${BASE}${path27}`, {
         ...init,
         signal: init?.signal ?? AbortSignal.timeout(this.timeoutMs),
         headers: {
@@ -551,24 +560,24 @@ var PixelLabClient = class {
     } catch (err) {
       if (attempt < MAX_RETRIES) {
         await sleep(backoffMs(attempt));
-        return this.request(path25, init, attempt + 1);
+        return this.request(path27, init, attempt + 1);
       }
       throw err;
     }
     if (!res.ok && shouldRetry(res.status) && attempt < MAX_RETRIES) {
       const waitMs = retryAfterMs(res.headers.get("retry-after")) ?? backoffMs(attempt);
       await sleep(waitMs);
-      return this.request(path25, init, attempt + 1);
+      return this.request(path27, init, attempt + 1);
     }
     const text = await res.text();
     if (!res.ok) {
-      throw new PixelLabError(`${init?.method ?? "GET"} ${path25} \u2192 ${res.status}`, res.status, text);
+      throw new PixelLabError(`${init?.method ?? "GET"} ${path27} \u2192 ${res.status}`, res.status, text);
     }
     if (!text) return {};
     try {
       return JSON.parse(text);
     } catch {
-      throw new Error(`${init?.method ?? "GET"} ${path25} returned invalid JSON`);
+      throw new Error(`${init?.method ?? "GET"} ${path27} returned invalid JSON`);
     }
   }
   async balance() {
@@ -1615,9 +1624,9 @@ var RetroDiffusionClient = class {
     }
     return balance;
   }
-  async call(path25, init = {}) {
+  async call(path27, init = {}) {
     if (!this.token) throw new Error("RD_API_KEY is not set");
-    const response = await this.request(`${this.baseUrl}${path25}`, {
+    const response = await this.request(`${this.baseUrl}${path27}`, {
       ...init,
       headers: {
         "Content-Type": "application/json",
@@ -2420,10 +2429,10 @@ import { createReadStream } from "fs";
 function sha256(data) {
   return createHash("sha256").update(data).digest("hex");
 }
-async function sha256File(path25) {
+async function sha256File(path27) {
   return new Promise((resolve, reject) => {
     const hash = createHash("sha256");
-    const stream = createReadStream(path25);
+    const stream = createReadStream(path27);
     stream.on("data", (chunk2) => hash.update(chunk2));
     stream.on("error", reject);
     stream.on("end", () => resolve(hash.digest("hex")));
@@ -3878,6 +3887,11 @@ ${issues}`);
         unknownReferences.push(`assets.${assetId}.promptByStyle: unknown style "${styleId}"`);
       }
     }
+    for (const styleId of Object.keys(asset.sourceByStyle)) {
+      if (!styleIds.has(styleId)) {
+        unknownReferences.push(`assets.${assetId}.sourceByStyle: unknown style "${styleId}"`);
+      }
+    }
     if (asset.revision) {
       if (!parsed.data.assets[asset.revision.from]) {
         unknownReferences.push(
@@ -4142,7 +4156,7 @@ async function resolveSpecs(loaded, filter) {
           }
         } : {},
         tags,
-        source: asset.source,
+        source: asset.sourceByStyle[styleId] ?? asset.source,
         // Revision identity is attached after every dependency in this style
         // has a concrete output target. Finalization below computes the hash.
         specHash: ""
@@ -6746,10 +6760,10 @@ function isSha256Hash(value) {
 function parseCache(value) {
   return HashCacheSchema.parse(value);
 }
-async function loadCache(path25) {
-  if (!existsSync10(path25)) return { version: 1, hashes: {} };
+async function loadCache(path27) {
+  if (!existsSync10(path27)) return { version: 1, hashes: {} };
   try {
-    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile9(path25, "utf8")));
+    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile9(path27, "utf8")));
     if (!parsed.success) return { version: 1, hashes: {} };
     return {
       version: 1,
@@ -6761,18 +6775,18 @@ async function loadCache(path25) {
     return { version: 1, hashes: {} };
   }
 }
-async function saveCache(path25, cache) {
+async function saveCache(path27, cache) {
   const sorted = {};
   for (const key of Object.keys(cache.hashes).sort()) {
     const hash = cache.hashes[key];
     if (!isSha256Hash(hash)) throw new Error(`Refusing to cache invalid SHA-256 for ${key}`);
     sorted[key] = hash;
   }
-  await mkdir3(pathModule.dirname(pathModule.resolve(path25)), { recursive: true });
-  const tmp = `${path25}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await mkdir3(pathModule.dirname(pathModule.resolve(path27)), { recursive: true });
+  const tmp = `${path27}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
     await writeFile3(tmp, JSON.stringify({ version: 1, hashes: sorted }, null, 2) + "\n");
-    await rename3(tmp, path25);
+    await rename3(tmp, path27);
   } finally {
     await rm4(tmp, { force: true });
   }
@@ -7019,16 +7033,24 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
   }
   const prefix = `${styleId}/`;
   const entries = Object.entries(lock.entries).filter(([key]) => key.startsWith(prefix));
-  if (!entries.length) {
+  const sources = options.sources ?? {};
+  if (!entries.length && !Object.keys(sources).length) {
     throw new Error(
       `No locked assets for style "${styleId}". Run \`pixelkiln gen --style ${styleId}\` first.`
     );
   }
   const inputs = [];
   const noOutput = [];
+  const locked = /* @__PURE__ */ new Set();
   for (const [key, entry] of entries) {
     const id = key.slice(prefix.length);
+    locked.add(id);
     const outputs = resolveEntryOutputs(entry, id, manifestDir);
+    const source = sources[id];
+    if (source && outputs.length <= 1) {
+      inputs.push({ id, path: path15.resolve(manifestDir, source) });
+      continue;
+    }
     let selected = outputs;
     if (options.outputRoles?.length) {
       selected = outputs.filter(
@@ -7045,6 +7067,9 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
     }
     for (const output of selected) inputs.push({ id: output.id, path: output.absolutePath });
   }
+  for (const [id, source] of Object.entries(sources)) {
+    if (!locked.has(id)) inputs.push({ id, path: path15.resolve(manifestDir, source) });
+  }
   if (!inputs.length) {
     throw new Error(`No readable sprites for style "${styleId}" \u2014 ${noOutput.length} skipped.`);
   }
@@ -8290,6 +8315,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
     assets[asset.id] = {
       prompt: "",
       promptByStyle: {},
+      sourceByStyle: {},
       category: asset.category || void 0,
       file: asset.file,
       tags: [],
@@ -8977,9 +9003,9 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
 
 // src/gallery/snapshot.ts
 import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync18 } from "fs";
+import { existsSync as existsSync19 } from "fs";
 import { readFile as readFile18, stat as stat3 } from "fs/promises";
-import path22 from "path";
+import path24 from "path";
 
 // src/workspace.ts
 import { mkdir as mkdir5, readFile as readFile16, rename as rename5, rm as rm7, writeFile as writeFile7 } from "fs/promises";
@@ -9115,6 +9141,10 @@ function validateWorkspace(ws, dir) {
 }
 
 // src/gallery/edit.ts
+import path23 from "path";
+import { z as z8 } from "zod";
+
+// src/manifest-edit.ts
 import { readFile as readFile17, rename as rename6, rm as rm8, writeFile as writeFile8 } from "fs/promises";
 import path21 from "path";
 import { z as z7 } from "zod";
@@ -9161,6 +9191,22 @@ var ManifestEditSchema = z7.discriminatedUnion("action", [
     expectedSha256: HexSha,
     asset: NewAssetSchema
   }).strict(),
+  z7.object({
+    action: z7.literal("set-source"),
+    project: z7.string().min(1).optional(),
+    assetId: z7.string().min(1),
+    styleId: z7.string().min(1),
+    /** Manifest-relative path of the art that stands in for this asset in this style. */
+    source: z7.string().min(1),
+    expectedSha256: HexSha
+  }).strict(),
+  z7.object({
+    action: z7.literal("clear-source"),
+    project: z7.string().min(1).optional(),
+    assetId: z7.string().min(1),
+    styleId: z7.string().min(1),
+    expectedSha256: HexSha
+  }).strict(),
   z7.object({
     action: z7.literal("patch-style"),
     project: z7.string().min(1).optional(),
@@ -9173,7 +9219,11 @@ var ManifestEditSchema = z7.discriminatedUnion("action", [
       promptPrefix: z7.string().optional(),
       promptSuffix: z7.string().optional(),
       /** `#rrggbb` values; null or empty clears the style's own palette. */
-      palette: z7.array(z7.string().regex(/^#?[0-9a-f]{6}$/i, "expected a six-digit hex colour")).max(256).nullable().optional()
+      palette: z7.array(z7.string().regex(/^#?[0-9a-f]{6}$/i, "expected a six-digit hex colour")).max(256).nullable().optional(),
+      /** Provider view name (PixelLab: low top-down, high top-down, side); empty clears. */
+      view: z7.string().max(64).nullable().optional(),
+      /** pixflux only; null clears the style's own value. */
+      noBackground: z7.boolean().nullable().optional()
     }).strict().refine((patch) => Object.keys(patch).length > 0, { message: "nothing to change" })
   }).strict()
 ]);
@@ -9207,8 +9257,38 @@ function setOrDelete(target, key, value) {
   if (value === null || value === void 0) delete target[key];
   else target[key] = value;
 }
+function assetStyles(raw, asset) {
+  const own = Array.isArray(asset.styles) ? asset.styles : [];
+  return own.length ? own : Object.keys(raw.styles ?? {});
+}
 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 (!raw.styles || !Object.hasOwn(raw.styles, edit.styleId)) {
+      throw new ManifestEditError(`unknown style "${edit.styleId}"`);
+    }
+    if (!assetStyles(raw, asset2).includes(edit.styleId)) {
+      throw new ManifestEditError(`asset "${edit.assetId}" is not in style "${edit.styleId}"`);
+    }
+    const single = assetStyles(raw, asset2).length === 1;
+    const byStyle = { ...asset2.sourceByStyle ?? {} };
+    if (edit.action === "set-source") {
+      if (single) {
+        asset2.source = edit.source;
+        delete byStyle[edit.styleId];
+      } else {
+        byStyle[edit.styleId] = edit.source;
+      }
+    } else {
+      delete byStyle[edit.styleId];
+      if (single) delete asset2.source;
+    }
+    if (Object.keys(byStyle).length) asset2.sourceByStyle = byStyle;
+    else delete asset2.sourceByStyle;
+    return;
+  }
   if (edit.action === "patch-style") {
     const style = raw.styles && Object.hasOwn(raw.styles, edit.styleId) ? raw.styles[edit.styleId] : void 0;
     if (!style) throw new ManifestEditError(`style "${edit.styleId}" is not declared by the manifest`);
@@ -9231,6 +9311,8 @@ function applyEdit(raw, edit) {
       const colors = (patch2.palette ?? []).map((color) => "#" + color.replace(/^#/, "").toLowerCase());
       setOrDelete(style, "palette", colors.length ? colors : null);
     }
+    if (patch2.view !== void 0) setOrDelete(style, "view", patch2.view?.trim() || null);
+    if (patch2.noBackground !== void 0) setOrDelete(style, "noBackground", patch2.noBackground);
     return;
   }
   if (edit.action === "add-asset") {
@@ -9310,10 +9392,134 @@ async function applyManifestEdit(manifestPath, edit) {
   }
   return { manifestPath: absolute, sha256: sha256(next), changed: true };
 }
+
+// src/pipeline/hand-edit.ts
+import { spawn as spawn2 } from "child_process";
+import { existsSync as existsSync18 } from "fs";
+import { copyFile, mkdir as mkdir6 } from "fs/promises";
+import path22 from "path";
+var HAND_EDIT_DIR = "edits";
+function handEditPath(loaded, spec) {
+  const style = loaded.manifest.styles[spec.styleId];
+  const outDir = path22.resolve(loaded.root, style?.outDir ?? ".");
+  const relative = path22.relative(outDir, spec.outFile);
+  const inside = relative && !relative.startsWith("..") && !path22.isAbsolute(relative);
+  const file = inside ? relative : path22.basename(spec.outFile);
+  return path22.join(outDir, HAND_EDIT_DIR, file.replace(/\.gif$/i, ".png"));
+}
+function handEditBase(spec, lock) {
+  const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
+  if (entry) {
+    if (entry.outputs.length !== 1) return null;
+    const primary = primaryOutput(entry);
+    if (!primary || primary.mediaType && primary.mediaType !== "image/png") return null;
+    const file = currentEntryOutputPath(entry, spec, 0);
+    return existsSync18(file) ? file : null;
+  }
+  return existsSync18(spec.outFile) ? spec.outFile : null;
+}
+async function startHandEdit(loaded, lock, spec, opts = {}) {
+  const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
+  if (entry && entry.outputs.length > 1) {
+    throw new ManifestEditError(
+      `${spec.styleId}/${spec.assetId} has ${entry.outputs.length} outputs; hand edits currently cover single-image assets`
+    );
+  }
+  const existing = spec.source ? path22.resolve(loaded.root, spec.source) : null;
+  const editPath = existing ?? handEditPath(loaded, spec);
+  let created = false;
+  if (!existsSync18(editPath)) {
+    const base = handEditBase(spec, lock);
+    if (!base) {
+      throw new ManifestEditError(
+        `${spec.styleId}/${spec.assetId} has no generated PNG on disk to start from; generate or restore it first`
+      );
+    }
+    await mkdir6(path22.dirname(editPath), { recursive: true });
+    await copyFile(base, editPath);
+    created = true;
+  }
+  const source = portableOutputPath(editPath, loaded.root);
+  let declared = false;
+  let manifestSha256 = opts.expectedSha256 ?? await sha256File(loaded.path);
+  if (spec.source !== source) {
+    const result = await applyManifestEdit(loaded.path, {
+      action: "set-source",
+      assetId: spec.assetId,
+      styleId: spec.styleId,
+      source,
+      expectedSha256: manifestSha256
+    });
+    declared = result.changed;
+    manifestSha256 = result.sha256;
+  }
+  return { editPath, source, created, declared, manifestSha256 };
+}
+async function detachHandEdit(loaded, spec, opts = {}) {
+  if (!spec.source) {
+    return { manifestSha256: opts.expectedSha256 ?? await sha256File(loaded.path), changed: false };
+  }
+  const result = await applyManifestEdit(loaded.path, {
+    action: "clear-source",
+    assetId: spec.assetId,
+    styleId: spec.styleId,
+    expectedSha256: opts.expectedSha256 ?? await sha256File(loaded.path)
+  });
+  return { manifestSha256: result.sha256, changed: result.changed };
+}
+function openInEditor(file, editor = process.env.PIXELKILN_EDITOR) {
+  const command = editor?.trim() ? editor.trim().split(/\s+/) : process.platform === "darwin" ? ["open"] : process.platform === "win32" ? ["cmd", "/c", "start", ""] : ["xdg-open"];
+  const [program, ...args] = command;
+  const child = spawn2(program, [...args, file], { stdio: "ignore", detached: true });
+  child.on("error", () => {
+  });
+  child.unref();
+  return command.join(" ");
+}
+
+// src/gallery/edit.ts
+var HandEditRequestSchema = z8.discriminatedUnion("action", [
+  z8.object({
+    action: z8.literal("start-edit"),
+    project: z8.string().min(1).optional(),
+    assetId: z8.string().min(1),
+    styleId: z8.string().min(1),
+    expectedSha256: z8.string().regex(/^[0-9a-f]{64}$/),
+    /** Also launch the author's editor on the file. */
+    open: z8.boolean().optional()
+  }).strict(),
+  z8.object({
+    action: z8.literal("detach-edit"),
+    project: z8.string().min(1).optional(),
+    assetId: z8.string().min(1),
+    styleId: z8.string().min(1),
+    expectedSha256: z8.string().regex(/^[0-9a-f]{64}$/)
+  }).strict()
+]);
 function createGalleryEditHandler(opts) {
   const log = opts.onProgress ?? (() => {
   });
   return async (body) => {
+    const handEdit = HandEditRequestSchema.safeParse(body);
+    if (handEdit.success) {
+      if (!opts.loadProject) throw new ManifestEditError("hand edits are not available in this gallery");
+      const request = handEdit.data;
+      const ctx = await opts.loadProject(request.project);
+      const spec = ctx.specs.find((candidate) => lockKey(candidate.styleId, candidate.assetId) === lockKey(request.styleId, request.assetId));
+      if (!spec) throw new ManifestEditError(`"${request.styleId}/${request.assetId}" is not declared by the manifest`);
+      if (request.action === "start-edit") {
+        const started = await startHandEdit(ctx.loaded, ctx.lock, spec, { expectedSha256: request.expectedSha256 });
+        log(`  hand edit ${started.created ? "created" : "found"}: ${started.source}${started.declared ? " (declared in the manifest)" : ""}`);
+        if (request.open) {
+          const command = (opts.openEditor ?? openInEditor)(started.editPath);
+          log(`  opened with: ${command}`);
+        }
+      } else {
+        const result2 = await detachHandEdit(ctx.loaded, spec, { expectedSha256: request.expectedSha256 });
+        if (result2.changed) log(`  hand edit detached: ${request.styleId}/${request.assetId} (file kept)`);
+      }
+      return opts.reload();
+    }
     const parsed = ManifestEditSchema.safeParse(body);
     if (!parsed.success) {
       throw new ManifestEditError(
@@ -9328,9 +9534,9 @@ function createGalleryEditHandler(opts) {
     }
     const result = await applyManifestEdit(manifestPath, parsed.data);
     if (result.changed) {
-      const relative = path21.relative(process.cwd(), result.manifestPath);
+      const relative = path23.relative(process.cwd(), result.manifestPath);
       const shown = !relative || relative.startsWith("..") ? result.manifestPath : relative;
-      const subject = parsed.data.action === "patch-style" ? `style ${parsed.data.styleId}` : parsed.data.assetId;
+      const subject = parsed.data.action === "patch-style" ? `style ${parsed.data.styleId}` : parsed.data.action === "set-source" || parsed.data.action === "clear-source" ? `${parsed.data.styleId}/${parsed.data.assetId} source` : parsed.data.assetId;
       log(`  manifest edited: ${parsed.data.action === "add-asset" ? "added" : "changed"} ${subject} in ${shown}`);
     }
     return opts.reload();
@@ -9339,7 +9545,7 @@ function createGalleryEditHandler(opts) {
 
 // src/gallery/snapshot.ts
 function galleryMediaId(absolutePath) {
-  return createHash4("sha256").update(path22.resolve(absolutePath)).digest("hex").slice(0, 24);
+  return createHash4("sha256").update(path24.resolve(absolutePath)).digest("hex").slice(0, 24);
 }
 function galleryMediaRoute(id) {
   return `/media/${id}`;
@@ -9364,23 +9570,24 @@ function metadataFps(entry) {
   }
   return null;
 }
-async function fileBytes(absolutePath) {
+async function fileInfo(absolutePath) {
   try {
     const info = await stat3(absolutePath);
-    return info.isFile() ? info.size : null;
+    return info.isFile() ? { bytes: info.size, modifiedAt: info.mtime.toISOString() } : null;
   } catch {
     return null;
   }
 }
 async function describeOutput(media, root, absolutePath, recorded = {}) {
-  const bytes = await fileBytes(absolutePath);
-  const exists = bytes !== null;
+  const info = await fileInfo(absolutePath);
+  const exists = info !== null;
   const mediaType = recorded.mediaType ?? mediaTypeFromExtension(absolutePath);
   let url = null;
   if (exists && mediaType) {
     const id = galleryMediaId(absolutePath);
     media.set(id, { path: absolutePath, contentType: mediaType });
-    url = `${galleryMediaRoute(id)}?v=${(recorded.sha256 ?? String(bytes)).slice(0, 16)}`;
+    const version = recorded.sha256 ?? `${info.bytes}-${Date.parse(info.modifiedAt).toString(36)}`;
+    url = `${galleryMediaRoute(id)}?v=${version.slice(0, 24)}`;
   }
   return {
     path: portableOutputPath(absolutePath, root),
@@ -9389,17 +9596,18 @@ async function describeOutput(media, root, absolutePath, recorded = {}) {
     role: recorded.role ?? null,
     mediaType,
     exists,
-    bytes,
+    bytes: info?.bytes ?? null,
+    modifiedAt: info?.modifiedAt ?? null,
     url
   };
 }
 async function describeQuality(media, root, inspection) {
   const outputPaths = inspection.outputs ?? [inspection.output];
   const outputs = await Promise.all(
-    outputPaths.map((file) => describeOutput(media, root, path22.resolve(root, file)))
+    outputPaths.map((file) => describeOutput(media, root, path24.resolve(root, file)))
   );
-  const recordPath = path22.resolve(root, inspection.record);
-  const recordExists = existsSync18(recordPath);
+  const recordPath = path24.resolve(root, inspection.record);
+  const recordExists = existsSync19(recordPath);
   let options = null;
   let check = null;
   if (recordExists) {
@@ -9418,7 +9626,7 @@ async function describeQuality(media, root, inspection) {
   return {
     state: inspection.state,
     reason: inspection.reason,
-    output: portableOutputPath(path22.resolve(root, inspection.output), root),
+    output: portableOutputPath(path24.resolve(root, inspection.output), root),
     record: portableOutputPath(recordPath, root),
     recordExists,
     outputs,
@@ -9468,15 +9676,24 @@ async function buildGallerySnapshot(opts) {
     const entry = lock.entries[key];
     const asset = loaded.manifest.assets[spec.assetId] ?? null;
     let outputs;
+    let edit = null;
+    let editStatus = null;
     if (entry && entry.outputs.length) {
       outputs = await Promise.all(
         entry.outputs.map(
           (output, index) => describeOutput(media, root, currentEntryOutputPath(entry, spec, index), output)
         )
       );
+      if (spec.source) {
+        const editPath = path24.resolve(root, spec.source);
+        const editSha = existsSync19(editPath) ? await sha256File(editPath) : null;
+        edit = await describeOutput(media, root, editPath, { sha256: editSha });
+        const generated = outputs[0];
+        editStatus = !edit.exists ? "missing" : generated && editSha === generated.sha256 ? "same" : generated?.modifiedAt && edit.modifiedAt && generated.modifiedAt > edit.modifiedAt && generated.exists ? "regenerated-since" : "edited";
+      }
     } else if (spec.source) {
-      outputs = [await describeOutput(media, root, path22.resolve(root, spec.source))];
-    } else if (!entry && existsSync18(spec.outFile)) {
+      outputs = [await describeOutput(media, root, path24.resolve(root, spec.source))];
+    } else if (!entry && existsSync19(spec.outFile)) {
       outputs = [await describeOutput(media, root, spec.outFile)];
     } else {
       outputs = [];
@@ -9520,6 +9737,8 @@ async function buildGallerySnapshot(opts) {
       providerMetadata: entry?.providerMetadata ?? {},
       asset,
       source: spec.source ?? null,
+      edit,
+      editStatus,
       tags: spec.tags,
       category: asset?.category ?? null
     });
@@ -9572,6 +9791,8 @@ async function buildGallerySnapshot(opts) {
       providerMetadata: entry.providerMetadata ?? {},
       asset: null,
       source: null,
+      edit: null,
+      editStatus: null,
       tags: [],
       category: null
     });
@@ -9610,6 +9831,8 @@ async function buildGallerySnapshot(opts) {
       promptPrefix: style?.promptPrefix ?? "",
       promptSuffix: style?.promptSuffix ?? "",
       palette: style?.palette ?? [],
+      view: style?.view ?? null,
+      noBackground: style?.noBackground ?? true,
       quality: Boolean(style?.quality),
       tags: style?.tags ?? [],
       extends: typeof rawStyle?.extends === "string" ? rawStyle.extends : null,
@@ -9637,7 +9860,7 @@ async function buildGallerySnapshot(opts) {
       id: loaded.manifest.name,
       name: loaded.manifest.name,
       manifest: loaded.path,
-      lock: path22.resolve(opts.lockPath),
+      lock: path24.resolve(opts.lockPath),
       root,
       provider: loaded.manifest.provider,
       account: null,
@@ -9662,7 +9885,7 @@ async function buildGallerySnapshot(opts) {
   return { snapshot, media };
 }
 async function buildWorkspaceGallerySnapshot(opts) {
-  const dir = path22.dirname(path22.resolve(opts.workspacePath));
+  const dir = path24.dirname(path24.resolve(opts.workspacePath));
   const media = /* @__PURE__ */ new Map();
   const projects = [];
   const items = [];
@@ -9705,7 +9928,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: loaded.manifest.name,
         manifest: manifestPath,
-        lock: path22.resolve(lockPath),
+        lock: path24.resolve(lockPath),
         root: loaded.root,
         provider: loaded.manifest.provider,
         account: project.account ?? null,
@@ -9720,8 +9943,8 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: project.id,
         manifest: manifestPath,
-        lock: path22.resolve(lockPath),
-        root: path22.dirname(manifestPath),
+        lock: path24.resolve(lockPath),
+        root: path24.dirname(manifestPath),
         provider: project.provider,
         account: project.account ?? null,
         manifestSha256: null,
@@ -9747,7 +9970,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
       version: 1,
       generatedAt: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
       project: null,
-      workspace: { path: path22.resolve(opts.workspacePath), dir, projects },
+      workspace: { path: path24.resolve(opts.workspacePath), dir, projects },
       filter,
       totals: {
         entries: projects.reduce((sum, project) => sum + project.entries, 0),
@@ -10034,6 +10257,14 @@ function renderGallery(snapshot, opts = {}) {
   .tray > button { padding:5px 11px; font-size:12.5px; }
   @media (max-width: 900px) { .sheet.review-host, .sheet.compare-host { width:100vw; } }
   .drawer .gen { display:flex; gap:8px; flex-wrap:wrap; margin-top:12px; }
+  .pair { display:grid; grid-template-columns:1fr 1fr; gap:8px; margin:8px 0 10px; }
+  .pair figure { margin:0; border:1px solid var(--line); background:var(--panel-deep); background-image:var(--checker);
+    background-size:12px 12px; background-position:0 0,6px 6px; display:grid; place-items:center; padding:8px; min-height:96px; }
+  .pair figure img { image-rendering:pixelated; display:block; max-width:100%; }
+  .pair figcaption { font:11px/1.4 var(--mono); color:var(--dim); background:var(--panel); padding:2px 6px; margin-top:6px; }
+  .card .pen { position:absolute; right:6px; top:6px; background:var(--panel); color:var(--accent-soft); border:1px solid var(--accent);
+    font:700 11px/1 var(--mono); padding:3px 5px; }
+  .hand-actions { display:flex; gap:8px; flex-wrap:wrap; margin-top:8px; }
   .drawer .gen button.primary { padding:7px 14px; }
   @media (max-width: 720px) {
     .bar, .totals, .chips, .style, footer { padding-inline:14px; }
@@ -10084,6 +10315,7 @@ function renderGallery(snapshot, opts = {}) {
 </footer>
 <div id="drawer-host"></div>
 <div id="dialog-host"></div>
+<datalist id="view-options"><option value="low top-down"><option value="high top-down"><option value="side"><option value="sidescroller"></datalist>
 <script>
 const INITIAL = ${data};
 const SESSION = ${session};
@@ -10479,7 +10711,8 @@ function clearFilters() {
 
 function thumb(item) {
   const cell = el('div', 'cell');
-  const shown = item.outputs.filter((o) => o.url);
+  // 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);
   if (!shown.length) {
     cell.classList.add('none');
     cell.append(el('span', null, item.state === 'missing' ? 'not generated yet'
@@ -10530,6 +10763,9 @@ function card(item) {
   body.append(meta);
   const cell = thumb(item);
   if (slot >= 0) cell.append(el('span', 'slot', String(slot + 1)));
+  if (item.editStatus === 'edited' || item.editStatus === 'regenerated-since') {
+    const pen = el('span', 'pen', '\u270E'); pen.title = 'hand-edited'; cell.append(pen);
+  }
   c.append(cell, body);
   c.onclick = (e) => { if (e.shiftKey) toggleCompare(item.id); else openItem(item.id); };
   return c;
@@ -10856,6 +11092,78 @@ function openCompare() {
   close.focus({ preventScroll: true });
 }
 
+// ---- hand edits -------------------------------------------------------------
+
+const EDIT_STATUS_TEXT = {
+  same: 'A copy of the generated art, 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.',
+};
+async function postHandEdit(item, action, extra) {
+  const pr = projectOf(item);
+  const body = { action, assetId: item.assetId, styleId: item.styleId, expectedSha256: pr.manifestSha256, ...extra };
+  if (item.project) body.project = item.project;
+  snap = await postEdit(body);
+}
+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';
+  if (!item.edit && !canStart) return null;
+  const s = el('section', 'meta');
+  s.append(el('h3', null, 'Hand edit'));
+  if (item.edit) {
+    const pair = el('div', 'pair');
+    const shared = displayScale(item.width, item.height, 200, 160);
+    const fig = (out, label) => {
+      const f = el('figure');
+      if (out && out.url) {
+        const img = el('img'); img.src = out.url; img.alt = label;
+        if (shared >= 1) { img.width = item.width * shared; img.height = item.height * shared; }
+        f.append(img);
+      } else f.append(el('span', 'state-dim', 'not on disk'));
+      f.append(el('figcaption', null, label));
+      return f;
+    };
+    pair.append(fig(item.outputs[0], 'generated'), fig(item.edit, 'edit'));
+    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));
+    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.'));
+  }
+  if (EDITABLE && item.declared && projectOf(item)?.manifestSha256) {
+    const acts = el('div', 'hand-actions');
+    const msg = el('span', 'msg');
+    const go = async (label, action, extra, done) => {
+      const b = el('button', label === 'Detach edit' ? null : 'primary', label); b.type = 'button';
+      b.onclick = async () => {
+        b.disabled = true; msg.className = 'msg'; msg.textContent = '\u2026';
+        try { await postHandEdit(item, action, extra); ui.notice = { id: item.id, text: done }; render(); }
+        catch (err) { b.disabled = false; msg.className = 'msg bad'; msg.textContent = err.message + (err.status === 409 ? ' \u2014 press Refresh.' : ''); }
+      };
+      acts.append(b);
+    };
+    if (item.edit) {
+      go('Open in 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.');
+    } 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.');
+    }
+    acts.append(msg);
+    s.append(acts);
+  }
+  return s;
+}
+
 // ---- editing (only when the server minted a session) ---------------------
 
 // Styles a parent edit reaches: every descendant (via extends) that does not
@@ -10875,9 +11183,18 @@ function inheritorsOf(style, field) {
   }
   return out;
 }
+// noBackground reaches the request only for pixflux and non-PixelLab
+// providers; elsewhere a change is recorded but alters nothing.
+const fieldReaches = (field, style) =>
+  field !== 'noBackground' || style.generator === 'pixflux' || style.provider !== 'pixellab';
 function blastRadius(style, fields) {
-  const styleIds = new Set([style.id]);
-  for (const field of fields) for (const id of inheritorsOf(style, field)) styleIds.add(id);
+  const byId = new Map(snap.styles.filter((x) => x.project === style.project).map((x) => [x.id, x]));
+  const styleIds = new Set();
+  for (const field of fields) {
+    for (const id of [style.id, ...inheritorsOf(style, field)]) {
+      if (fieldReaches(field, byId.get(id) || style)) styleIds.add(id);
+    }
+  }
   const affected = snap.items.filter((i) => i.project === style.project && i.declared && styleIds.has(i.styleId));
   const units = new Map();
   for (const i of affected) if (i.estimatedCost !== null) units.set(i.costUnit, (units.get(i.costUnit) || 0) + i.estimatedCost);
@@ -10902,6 +11219,11 @@ function styleForm(style) {
   const prefix = el('input'); prefix.type = 'text'; prefix.value = style.promptPrefix; prefix.placeholder = 'none';
   const suffix = el('input'); suffix.type = 'text'; suffix.value = style.promptSuffix; suffix.placeholder = 'none';
   const palette = el('input'); palette.type = 'text'; palette.value = style.palette.join(', '); palette.placeholder = '#rrggbb, #rrggbb \u2014 leave empty for no forced palette';
+  const view = el('input'); view.type = 'text'; view.value = style.view || ''; view.placeholder = 'provider default';
+  view.setAttribute('list', 'view-options');
+  const noBg = el('select');
+  noBg.append(new Option(style.extends ? 'inherit from ' + style.extends : 'default (on)', 'default'), new Option('on \u2014 strip the generated background', 'on'), new Option('off \u2014 keep the background (scenes, banners)', 'off'));
+  noBg.value = own('noBackground') ? (style.noBackground ? 'on' : 'off') : 'default';
   const swatches = el('div', 'pal');
   const drawSwatches = () => {
     swatches.textContent = '';
@@ -10914,12 +11236,21 @@ function styleForm(style) {
     field('palette', palette, 'Forced colours where the provider supports them (pixflux). ' + provenance('palette')),
     swatches,
   );
+  const row = el('div', 'row');
+  row.append(
+    field('view', view, 'PixelLab accepts low top-down, high top-down, side; Retro Diffusion reads sidescroller. ' + provenance('view')),
+    field('background', noBg, (fieldReaches('noBackground', style) ? 'Sent for this style. ' : 'Not sent for ' + style.provider + ' ' + style.generator + '; recorded only. ') + provenance('noBackground')),
+  );
+  form.append(row);
   const blast = el('div', 'blast');
   const changed = () => {
     const out = [];
     if (prefix.value !== style.promptPrefix) out.push('promptPrefix');
     if (suffix.value !== style.promptSuffix) out.push('promptSuffix');
     if (parsePalette(palette.value).join(',') !== style.palette.map((c) => c.toLowerCase()).join(',')) out.push('palette');
+    if (view.value.trim() !== (style.view || '')) out.push('view');
+    const bgNow = own('noBackground') ? (style.noBackground ? 'on' : 'off') : 'default';
+    if (noBg.value !== bgNow) out.push('noBackground');
     return out;
   };
   const updateBlast = () => {
@@ -10927,6 +11258,11 @@ function styleForm(style) {
     drawSwatches();
     if (!fields.length) { blast.className = 'blast'; blast.textContent = 'No changes yet. A style change alters the request for every asset that uses it.'; return; }
     const r = blastRadius(style, fields);
+    if (!r.assets) {
+      blast.className = 'blast';
+      blast.textContent = 'Recorded in the manifest only: nothing in ' + style.id + ' sends this field, so no request changes.';
+      return;
+    }
     blast.className = 'blast hot';
     blast.textContent = '';
     const others = r.styles.filter((id) => id !== style.id);
@@ -10936,7 +11272,8 @@ function styleForm(style) {
       : ' in ' + style.id + '.'));
     blast.append(document.createTextNode(' Generated ones become stale; regenerating all of them is about ' + (r.cost || 'nothing') + '. Nothing is spent until you generate.'));
   };
-  for (const input of [prefix, suffix, palette]) input.addEventListener('input', updateBlast);
+  for (const input of [prefix, suffix, palette, view]) input.addEventListener('input', updateBlast);
+  noBg.addEventListener('change', updateBlast);
   updateBlast();
   form.append(blast);
   const actions = el('div', 'actions');
@@ -10955,6 +11292,8 @@ function styleForm(style) {
     if (fields.includes('promptPrefix')) patch.promptPrefix = prefix.value;
     if (fields.includes('promptSuffix')) patch.promptSuffix = suffix.value;
     if (fields.includes('palette')) patch.palette = colors;
+    if (fields.includes('view')) patch.view = view.value.trim();
+    if (fields.includes('noBackground')) patch.noBackground = noBg.value === 'default' ? null : noBg.value === 'on';
     save.disabled = true; msg.className = 'msg'; msg.textContent = 'saving\u2026';
     const r = blastRadius(style, fields);
     try {
@@ -10963,7 +11302,9 @@ function styleForm(style) {
       snap = await postEdit(body);
       ui.editing = null;
       ui.notice = { id: 'style:' + (style.project || '') + ':' + style.id,
-        text: 'Saved. The request for ' + r.assets + (r.assets === 1 ? ' asset' : ' assets') + ' changed' + (r.cost ? ' \u2014 about ' + r.cost + ' to regenerate.' : '.') + ' Nothing is spent until you generate.' };
+        text: r.assets
+          ? 'Saved. The request for ' + r.assets + (r.assets === 1 ? ' asset' : ' assets') + ' changed' + (r.cost ? ' \u2014 about ' + r.cost + ' to regenerate.' : '.') + ' Nothing is spent until you generate.'
+          : 'Saved. Recorded in the manifest; no request changed.' };
       render();
     } catch (err) {
       save.disabled = false;
@@ -11314,6 +11655,9 @@ function renderDrawer() {
     body.append(s);
   }
 
+  const hand = handEditSection(item);
+  if (hand) body.append(hand);
+
   if (item.revision || item.revisionParentKey) {
     const { s, dl } = section('Lineage');
     row(dl, 'mode', item.revision ? item.revision.mode : (item.asset && item.asset.revision && item.asset.revision.mode));
@@ -11562,7 +11906,7 @@ if (ui.compare.length >= 2 && !ui.open) openCompare();
 var escapeHtml2 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 
 // src/gallery/server.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import { randomBytes } from "crypto";
 import { createServer as createServer2 } from "http";
 import { readFile as readFile19 } from "fs/promises";
@@ -11785,7 +12129,7 @@ async function serveGallery(opts) {
   });
   opts.onReady?.(url);
   if (opts.open !== false && process.platform === "darwin") {
-    spawn2("open", [url], { stdio: "ignore", detached: true }).unref();
+    spawn3("open", [url], { stdio: "ignore", detached: true }).unref();
   }
   return {
     url,
@@ -11799,14 +12143,14 @@ async function serveGallery(opts) {
 
 // src/gallery/generate.ts
 import { randomBytes as randomBytes2 } from "crypto";
-import { z as z8 } from "zod";
-var GenerateRequestSchema = z8.object({
-  project: z8.string().min(1).optional(),
-  keys: z8.array(z8.string().min(1)).min(1).max(500),
+import { z as z9 } from "zod";
+var GenerateRequestSchema = z9.object({
+  project: z9.string().min(1).optional(),
+  keys: z9.array(z9.string().min(1)).min(1).max(500),
   /** Regenerate work that is up to date, as `gen --force` does. */
-  force: z8.boolean().optional(),
+  force: z9.boolean().optional(),
   /** Advance in-flight, review, or selected work without submitting anything. */
-  resume: z8.boolean().optional()
+  resume: z9.boolean().optional()
 }).strict();
 var GenerateRequestError = class extends Error {
   constructor(message6, status = 400) {
@@ -12044,15 +12388,15 @@ function createGenerateHandlers(opts) {
 
 // src/pipeline/salvage.ts
 import { readFile as readFile20 } from "fs/promises";
-import { existsSync as existsSync19 } from "fs";
-import path23 from "path";
+import { existsSync as existsSync20 } from "fs";
+import path25 from "path";
 function providerClaimId(provider, objectId) {
   return `${encodeURIComponent(provider)}:${encodeURIComponent(objectId)}`;
 }
 async function loadClaims(lockPaths, opts = {}) {
   const claimed = /* @__PURE__ */ new Set();
   for (const p of lockPaths) {
-    if (!existsSync19(p)) throw new Error(`Claim lockfile not found: ${p}`);
+    if (!existsSync20(p)) throw new Error(`Claim lockfile not found: ${p}`);
     let parsed;
     try {
       parsed = parseLock(JSON.parse(await readFile20(p, "utf8")));
@@ -12108,20 +12452,20 @@ function matchOrphanStyle(prompt, manifest) {
   return matchStyleByPattern(prompt, manifest);
 }
 async function loadSiblingManifests(ownManifestPath, workspaceManifestPaths, claimPaths) {
-  const own = path23.resolve(ownManifestPath);
+  const own = path25.resolve(ownManifestPath);
   const siblingManifestPaths = [
     .../* @__PURE__ */ new Set([
       ...workspaceManifestPaths,
-      ...claimPaths.map((c) => path23.join(path23.dirname(path23.resolve(c)), "pixelkiln.manifest.json"))
+      ...claimPaths.map((c) => path25.join(path25.dirname(path25.resolve(c)), "pixelkiln.manifest.json"))
     ])
   ];
   const siblings = [];
   for (const siblingManifestPath of siblingManifestPaths) {
-    if (path23.resolve(siblingManifestPath) === own) continue;
-    if (!existsSync19(siblingManifestPath)) continue;
+    if (path25.resolve(siblingManifestPath) === own) continue;
+    if (!existsSync20(siblingManifestPath)) continue;
     try {
       const { manifest } = await loadManifest(siblingManifestPath);
-      siblings.push({ label: path23.basename(path23.dirname(siblingManifestPath)), manifest });
+      siblings.push({ label: path25.basename(path25.dirname(siblingManifestPath)), manifest });
     } catch {
     }
   }
@@ -12237,8 +12581,8 @@ async function applyTags(provider, decisions, existing, opts = {}) {
 }
 
 // src/pick/salvage-server.ts
-import { mkdir as mkdir6, writeFile as writeFile9, readFile as readFile21 } from "fs/promises";
-import path24 from "path";
+import { mkdir as mkdir7, writeFile as writeFile9, readFile as readFile21 } from "fs/promises";
+import path26 from "path";
 
 // src/pick/salvage-sheet.ts
 var escapeHtml3 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -12403,7 +12747,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
   });
   const html = renderSalvageSheet(orphans, {
     styleId: ctx.styleId,
-    importDir: path24.relative(process.cwd(), ctx.importDir) || "."
+    importDir: path26.relative(process.cwd(), ctx.importDir) || "."
   });
   const byId = new Map(orphans.map((o) => [o.id, o]));
   const existingTags = new Map(orphans.map((o) => [o.id, o.tags]));
@@ -12432,13 +12776,14 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
             if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
             decodePng(buf);
             const assetId = idFromPrompt(orphan.prompt, taken);
-            const rel = path24.join("_salvaged", `${assetId}.png`);
-            const outFile = path24.resolve(ctx.importDir, rel);
-            await mkdir6(path24.dirname(outFile), { recursive: true });
+            const rel = path26.join("_salvaged", `${assetId}.png`);
+            const outFile = path26.resolve(ctx.importDir, rel);
+            await mkdir7(path26.dirname(outFile), { recursive: true });
             await writeFile9(outFile, buf);
             ctx.manifest.assets[assetId] = {
               prompt: orphan.prompt,
               promptByStyle: {},
+              sourceByStyle: {},
               category: "_salvaged",
               file: rel,
               tags: ["salvaged"],
@@ -12466,7 +12811,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               sourceUrl: durableSource,
               sourceUrls: durableSource ? [{ url: durableSource }] : [],
               outputs: [{
-                path: portableOutputPath(outFile, path24.dirname(ctx.manifestPath)),
+                path: portableOutputPath(outFile, path26.dirname(ctx.manifestPath)),
                 sha256: sha256(buf)
               }],
               submittedAt: orphan.createdAt,