pixelkiln 0.36.0 → 0.37.0

package/dist/index.cjs

@@ -71,6 +71,7 @@ __export(index_exports, {
   PixelLabClient: () => PixelLabClient,
   PixelLabError: () => PixelLabError,
   PixelLabProvider: () => PixelLabProvider,
+  PostprocessSchema: () => PostprocessSchema,
   ProjectError: () => ProjectError,
   ProviderError: () => ProviderError,
   QualityBaselineSchema: () => QualityBaselineSchema,
@@ -450,6 +451,18 @@ var StyleObjectSchema = import_zod.z.object({
    * chocolate bar.
    */
   palette: import_zod.z.array(HexColorSchema).default([]),
+  /**
+   * Snap every visible pixel of the downloaded art to the nearest `palette`
+   * colour, without dithering. The palette is sent to providers that take
+   * one, and most honour it most of the time; this makes it a guarantee
+   * for every generator, including the ones with no palette parameter.
+   * Applied by `fetch` as the file is written and recorded on the lock
+   * entry, so a restore reproduces the same bytes. Turning it on or off
+   * does not change the spec hash: `plan` reports the entry as recoverable
+   * and the next `fetch` or `restore` re-applies it from the art already
+   * on disk or in the cache, spending nothing.
+   */
+  enforcePalette: import_zod.z.boolean().default(false),
   /** Fail-closed native-grid, palette, and human-approval policy for derived art. */
   quality: QualityProfileSchema.optional(),
   /**
@@ -491,6 +504,13 @@ var StyleSchema = StyleObjectSchema.refine((s) => !(s.tileFeature && s.styleImag
       path: ["quality"]
     });
   }
+  if (style.enforcePalette && style.palette.length < 2) {
+    ctx.addIssue({
+      code: import_zod.z.ZodIssueCode.custom,
+      message: "enforcePalette needs a palette of at least two colours to snap to",
+      path: ["enforcePalette"]
+    });
+  }
 });
 var InheritedStyleSchema = StyleObjectSchema.partial().extend({
   extends: import_zod.z.string().min(1),
@@ -613,7 +633,21 @@ var LockOutputSchema = import_zod.z.object({
   path: import_zod.z.string(),
   sha256: import_zod.z.string(),
   role: import_zod.z.string().optional(),
-  mediaType: MediaTypeSchema.optional()
+  mediaType: MediaTypeSchema.optional(),
+  /**
+   * Hash of the provider's bytes before post-processing changed them, when
+   * it did. The content cache keeps both, so the post-processing can be
+   * undone or redone without contacting the provider.
+   */
+  raw: import_zod.z.string().optional()
+});
+var PostprocessSchema = import_zod.z.object({
+  palette: import_zod.z.object({
+    /** Canonical lowercase `#rrggbb` values, in manifest order. */
+    colors: import_zod.z.array(import_zod.z.string()).min(2).max(256),
+    dither: import_zod.z.literal("none"),
+    distance: import_zod.z.literal("redmean")
+  }).optional()
 });
 var LockSourceSchema = import_zod.z.object({
   url: import_zod.z.string(),
@@ -639,6 +673,7 @@ var LockHistoryEntrySchema = import_zod.z.object({
   cost: import_zod.z.number().finite().nonnegative().default(0),
   costUnit: import_zod.z.string().min(1).default("generations"),
   provider: import_zod.z.string().default("pixellab"),
+  postprocess: PostprocessSchema.optional(),
   /** When the replacement was submitted. */
   retiredAt: import_zod.z.string()
 });
@@ -710,14 +745,7 @@ var LockEntrySchema = import_zod.z.object({
    * `role` labels non-primary artifacts (e.g. "portrait", "spriteframes") so a
    * consumer can find the one it wants without pattern-matching on paths.
    */
-  outputs: import_zod.z.array(
-    import_zod.z.object({
-      path: import_zod.z.string(),
-      sha256: import_zod.z.string(),
-      role: import_zod.z.string().optional(),
-      mediaType: MediaTypeSchema.optional()
-    })
-  ).default([]),
+  outputs: import_zod.z.array(LockOutputSchema).default([]),
   /**
    * Provider-owned data retained for downstream consumers, namespaced by
    * provider id. PixelLab connectable sets keep their exact `tileRules` here
@@ -733,7 +761,9 @@ var LockEntrySchema = import_zod.z.object({
   /** Which provider produced this. Absent on entries written before providers. */
   provider: import_zod.z.string().default("pixellab"),
   /** Generations this entry replaced, newest first; see LockHistoryEntrySchema. */
-  history: import_zod.z.array(LockHistoryEntrySchema).optional()
+  history: import_zod.z.array(LockHistoryEntrySchema).optional(),
+  /** Post-processing applied to the recorded outputs; absent when the bytes are the provider's. */
+  postprocess: PostprocessSchema.optional()
 });
 var LockSchema = import_zod.z.object({
   version: import_zod.z.literal(2),
@@ -4574,6 +4604,7 @@ async function resolveSpecs(loaded, filter) {
         detail: style.detail,
         seed: style.seed,
         palette: style.palette,
+        enforcePalette: style.enforcePalette,
         noBackground: style.noBackground,
         tileSize: generator === "tiles" ? tileSize : void 0,
         tileType: generator === "tiles" ? style.tileType : void 0,
@@ -4778,7 +4809,7 @@ function imageMetadata(buf) {
 }
 
 // src/project.ts
-var import_node_path13 = __toESM(require("path"), 1);
+var import_node_path12 = __toESM(require("path"), 1);
 
 // src/env.ts
 var import_node_fs6 = require("fs");
@@ -4825,17 +4856,17 @@ function parseEnv(contents) {
 }
 
 // src/pipeline/plan.ts
-var import_node_fs10 = require("fs");
-var import_node_path12 = __toESM(require("path"), 1);
+var import_node_fs9 = require("fs");
+var import_node_path11 = __toESM(require("path"), 1);
 
 // src/pipeline/quality-profile.ts
-var import_node_fs8 = require("fs");
-var import_node_path10 = __toESM(require("path"), 1);
+var import_node_fs7 = require("fs");
+var import_node_path9 = __toESM(require("path"), 1);
 
 // src/pipeline/refine.ts
-var import_node_path9 = __toESM(require("path"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
 var import_node_child_process2 = require("child_process");
-var import_promises6 = require("fs/promises");
+var import_promises5 = require("fs/promises");
 var import_node_os2 = require("os");
 var import_node_util = require("util");
 
@@ -5296,10 +5327,19 @@ async function writeArtifactBundle(files, options = {}) {
   };
 }
 
-// src/pipeline/audit.ts
-var import_promises5 = require("fs/promises");
-var import_node_fs7 = require("fs");
-var import_node_path8 = __toESM(require("path"), 1);
+// src/palette.ts
+function normalizePalette(values) {
+  const colors = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const rgb = parseHex(value);
+    const hex2 = `#${rgb.r.toString(16).padStart(2, "0")}${rgb.g.toString(16).padStart(2, "0")}${rgb.b.toString(16).padStart(2, "0")}`;
+    if (!colors.has(hex2)) colors.set(hex2, { hex: hex2, ...rgb });
+  }
+  if (colors.size < 2 || colors.size > 256) {
+    throw new Error(`A palette must contain 2\u2013256 unique colors; got ${colors.size}.`);
+  }
+  return [...colors.values()];
+}
 function colorDistance(a, b) {
   const rmean = (a.r + b.r) / 2;
   const dr = a.r - b.r;
@@ -5309,146 +5349,45 @@ function colorDistance(a, b) {
     (512 + rmean) * dr * dr / 256 + 4 * dg * dg + (767 - rmean) * db * db / 256
   );
 }
-function paletteDistance(asset, reference) {
-  if (!asset.length || !reference.length) return 0;
-  let total = 0;
-  let weight = 0;
-  for (const color of asset) {
-    let nearest = Infinity;
-    for (const ref of reference) nearest = Math.min(nearest, colorDistance(color, ref));
-    total += nearest * color.weight;
-    weight += color.weight;
-  }
-  return weight === 0 ? 0 : total / weight;
-}
-function mergePalettes(palettes, topN = 24) {
-  const totals = /* @__PURE__ */ new Map();
-  for (const palette of palettes) {
-    for (const color of palette) {
-      const key = `${color.r},${color.g},${color.b}`;
-      const existing = totals.get(key);
-      if (existing) existing.weight += color.weight;
-      else totals.set(key, { ...color });
+function quantize(png, palette) {
+  const colors = normalizePalette(palette);
+  const pixels = Buffer.from(png.pixels);
+  const nearestOf = /* @__PURE__ */ new Map();
+  let changed = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const alpha = pixels[i + 3];
+    if (alpha === 0) {
+      if (pixels[i] || pixels[i + 1] || pixels[i + 2]) changed++;
+      pixels[i] = 0;
+      pixels[i + 1] = 0;
+      pixels[i + 2] = 0;
+      continue;
     }
-  }
-  const merged = [...totals.values()].sort((a, b) => b.weight - a.weight).slice(0, topN);
-  const sum = merged.reduce((s, c) => s + c.weight, 0) || 1;
-  return merged.map((c) => ({ ...c, weight: c.weight / sum }));
-}
-async function auditStyle(loaded, specs, styleId, lock) {
-  const style = loaded.manifest.styles[styleId];
-  if (!style) throw new Error(`Unknown style "${styleId}"`);
-  const mine = specs.filter((s) => s.styleId === styleId);
-  const assets = [];
-  const missing = [];
-  const unreadable = [];
-  for (const spec of mine) {
-    for (const output of resolveSpecOutputs(spec, lock, loaded.root)) {
-      if (!(0, import_node_fs7.existsSync)(output.absolutePath)) {
-        missing.push(output.id);
-        continue;
-      }
-      try {
-        const png = decodePng(await (0, import_promises5.readFile)(output.absolutePath));
-        const palette = extractPalette(png, 12);
-        assets.push({
-          assetId: spec.assetId,
-          ...output.role ? { outputRole: output.role } : {},
-          id: output.id,
-          file: output.absolutePath,
-          width: png.width,
-          height: png.height,
-          paletteDistance: 0,
-          // filled once the reference is known
-          transparency: transparencyRatio(png),
-          colorCount: countColors(png),
-          palette
-        });
-      } catch (err) {
-        unreadable.push(`${output.id}: ${err instanceof Error ? err.message : String(err)}`);
+    const key = pixels[i] << 16 | pixels[i + 1] << 8 | pixels[i + 2];
+    let nearest = nearestOf.get(key);
+    if (!nearest) {
+      const pixel = { r: pixels[i], g: pixels[i + 1], b: pixels[i + 2] };
+      nearest = colors[0];
+      let distance = colorDistance(pixel, nearest);
+      for (let j = 1; j < colors.length; j++) {
+        const candidate = colors[j];
+        const candidateDistance = colorDistance(pixel, candidate);
+        if (candidateDistance < distance) {
+          nearest = candidate;
+          distance = candidateDistance;
+        }
       }
+      nearestOf.set(key, nearest);
     }
+    if (pixels[i] !== nearest.r || pixels[i + 1] !== nearest.g || pixels[i + 2] !== nearest.b) changed++;
+    pixels[i] = nearest.r;
+    pixels[i + 1] = nearest.g;
+    pixels[i + 2] = nearest.b;
   }
-  let reference = [];
-  let referenceFromStyleImages = false;
-  const refPalettes = [];
-  for (const img of style.styleImages) {
-    const abs = import_node_path8.default.resolve(loaded.root, img.path);
-    if (!(0, import_node_fs7.existsSync)(abs)) continue;
-    try {
-      refPalettes.push(extractPalette(decodePng(await (0, import_promises5.readFile)(abs)), 12));
-    } catch {
-    }
-  }
-  if (refPalettes.length) {
-    reference = mergePalettes(refPalettes);
-    referenceFromStyleImages = true;
-    for (const asset of assets) {
-      asset.paletteDistance = paletteDistance(asset.palette, reference);
-    }
-  } else {
-    reference = mergePalettes(assets.map((a) => a.palette));
-    for (const asset of assets) {
-      const others = assets.filter((a) => a !== asset).map((a) => a.palette);
-      asset.paletteDistance = others.length ? paletteDistance(asset.palette, mergePalettes(others)) : 0;
-    }
-  }
-  assets.sort((a, b) => b.paletteDistance - a.paletteDistance);
-  return { styleId, referenceFromStyleImages, reference, assets, missing, unreadable };
-}
-function countColors(png) {
-  const seen = /* @__PURE__ */ new Set();
-  for (let i = 0; i < png.pixels.length; i += 4) {
-    if (png.pixels[i + 3] < 128) continue;
-    seen.add(png.pixels[i] << 16 | png.pixels[i + 1] << 8 | png.pixels[i + 2]);
-  }
-  return seen.size;
-}
-function outliers(audit, sigma = 1.5) {
-  const n = audit.assets.length;
-  if (n < 3) return [];
-  const mean = audit.assets.reduce((s, a) => s + a.paletteDistance, 0) / n;
-  const variance = audit.assets.reduce((s, a) => s + (a.paletteDistance - mean) ** 2, 0) / n;
-  const sd = Math.sqrt(variance);
-  if (sd === 0) return [];
-  return audit.assets.filter((a) => a.paletteDistance > mean + sigma * sd);
-}
-function evaluateAudit(audit, thresholds = {}) {
-  const resolved = { ...thresholds, sigma: thresholds.sigma ?? 1.5 };
-  const relative = outliers(audit, resolved.sigma);
-  const relativeIds = new Set(relative.map((asset) => asset.id));
-  const violations = [];
-  for (const asset of audit.assets) {
-    const reasons = [];
-    if (relativeIds.has(asset.id)) {
-      reasons.push(`palette outlier beyond ${resolved.sigma} standard deviations`);
-    }
-    if (resolved.maxDistance !== void 0 && asset.paletteDistance > resolved.maxDistance) {
-      reasons.push(
-        `palette distance ${asset.paletteDistance.toFixed(1)} exceeds ${resolved.maxDistance}`
-      );
-    }
-    if (resolved.minTransparency !== void 0 && asset.transparency < resolved.minTransparency) {
-      reasons.push(
-        `transparency ${(asset.transparency * 100).toFixed(1)}% is below ${(resolved.minTransparency * 100).toFixed(1)}%`
-      );
-    }
-    if (resolved.maxColors !== void 0 && asset.colorCount > resolved.maxColors) {
-      reasons.push(`color count ${asset.colorCount} exceeds ${resolved.maxColors}`);
-    }
-    if (reasons.length) violations.push({ id: asset.id, reasons });
-  }
-  return {
-    safe: violations.length === 0 && audit.missing.length === 0 && audit.unreadable.length === 0,
-    thresholds: resolved,
-    outliers: [...relativeIds],
-    violations,
-    missing: [...audit.missing],
-    unreadable: [...audit.unreadable]
-  };
+  return { png: { width: png.width, height: png.height, pixels }, changed };
 }
-function hex(c) {
-  return `#${[c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+function quantizeToPalette(png, palette) {
+  return quantize(png, palette).png;
 }
 
 // src/pipeline/refine.ts
@@ -5535,48 +5474,12 @@ function parseDetection(raw) {
     confidence: confidenceFor(consensus)
   };
 }
-function normalizePalette(values) {
-  const colors = /* @__PURE__ */ new Map();
-  for (const value of values) {
-    const rgb = parseHex(value);
-    const hex2 = `#${rgb.r.toString(16).padStart(2, "0")}${rgb.g.toString(16).padStart(2, "0")}${rgb.b.toString(16).padStart(2, "0")}`;
-    colors.set(hex2, { hex: hex2, ...rgb });
-  }
-  if (colors.size < 2 || colors.size > 256) {
-    throw new Error(`A refinement palette must contain 2\u2013256 unique colors; got ${colors.size}.`);
-  }
-  return [...colors.values()];
-}
 function normalizeRefinementPalette(values) {
-  return normalizePalette(values).map((color) => color.hex);
-}
-function quantizeToPalette(png, palette) {
-  const colors = normalizePalette(palette);
-  const pixels = Buffer.from(png.pixels);
-  for (let i = 0; i < pixels.length; i += 4) {
-    const alpha = pixels[i + 3];
-    if (alpha === 0) {
-      pixels[i] = 0;
-      pixels[i + 1] = 0;
-      pixels[i + 2] = 0;
-      continue;
-    }
-    const pixel = { r: pixels[i], g: pixels[i + 1], b: pixels[i + 2] };
-    let nearest = colors[0];
-    let distance = colorDistance(pixel, nearest);
-    for (let j = 1; j < colors.length; j++) {
-      const candidate = colors[j];
-      const candidateDistance = colorDistance(pixel, candidate);
-      if (candidateDistance < distance) {
-        nearest = candidate;
-        distance = candidateDistance;
-      }
-    }
-    pixels[i] = nearest.r;
-    pixels[i + 1] = nearest.g;
-    pixels[i + 2] = nearest.b;
+  try {
+    return normalizePalette(values).map((color) => color.hex);
+  } catch (err) {
+    throw new Error(`A refinement palette must contain 2\u2013256 unique colors; got ${new Set(values.map((v) => v.toLowerCase())).size}.`, { cause: err });
   }
-  return { width: png.width, height: png.height, pixels };
 }
 function colorCount(png) {
   const colors = /* @__PURE__ */ new Set();
@@ -5686,16 +5589,16 @@ function sameFrameGrid(first, next) {
   return next.detection.stepX === first.detection.stepX && next.detection.stepY === first.detection.stepY && next.detection.columns === first.detection.columns && next.detection.rows === first.detection.rows && phaseMatches(next.detection.phaseX, first.detection.phaseX, first.detection.stepX) && phaseMatches(next.detection.phaseY, first.detection.phaseY, first.detection.stepY) && next.audit.width === first.audit.width && next.audit.height === first.audit.height && next.sourceWidth === first.sourceWidth && next.sourceHeight === first.sourceHeight;
 }
 async function refineAsset(options) {
-  const source = import_node_path9.default.resolve(options.source);
-  const output = import_node_path9.default.resolve(options.output);
+  const source = import_node_path8.default.resolve(options.source);
+  const output = import_node_path8.default.resolve(options.output);
   if (source === output) throw new Error("Refinement source and output must be different files.");
-  const record = import_node_path9.default.resolve(qualityRecordPath(output));
+  const record = import_node_path8.default.resolve(qualityRecordPath(output));
   const palette = normalizePalette(options.palette).map((color) => color.hex);
   const minGridConfidence = requireConfidence(options.minGridConfidence ?? "high");
   if (options.minTransparency !== void 0 && (!Number.isFinite(options.minTransparency) || options.minTransparency < 0 || options.minTransparency > 1)) throw new Error("minTransparency must be between 0 and 1.");
   let sourcePng;
   try {
-    sourcePng = decodePng(await (0, import_promises6.readFile)(source));
+    sourcePng = decodePng(await (0, import_promises5.readFile)(source));
   } catch (error) {
     throw new Error(`Cannot read refinement source ${source}: ${message2(error)}`, { cause: error });
   }
@@ -5712,8 +5615,8 @@ async function refineAsset(options) {
       );
     }
   }
-  const temp = await (0, import_promises6.mkdtemp)(import_node_path9.default.join((0, import_node_os2.tmpdir)(), "pixelkiln-refine-"));
-  const recovered = import_node_path9.default.join(temp, "native.png");
+  const temp = await (0, import_promises5.mkdtemp)(import_node_path8.default.join((0, import_node_os2.tmpdir)(), "pixelkiln-refine-"));
+  const recovered = import_node_path8.default.join(temp, "native.png");
   const fixerCommand = compatibilityCommand ?? options.fixerPython ?? process.env.PIXELKILN_PIXEL_FIXER_PYTHON ?? "python3";
   const args = compatibilityCommand ? [...options.fixerArgsPrefix ?? [], source, "--extract", recovered] : ["-c", PYTHON_FIXER_BRIDGE, source, recovered];
   try {
@@ -5734,7 +5637,7 @@ async function refineAsset(options) {
       );
     }
     const detection = parseDetection(firstJsonObject(stdout));
-    const native = decodePng(await (0, import_promises6.readFile)(recovered));
+    const native = decodePng(await (0, import_promises5.readFile)(recovered));
     const quantized = quantizeToPalette(native, palette);
     const png = encodeRgbaPng(quantized.width, quantized.height, quantized.pixels);
     const audit = auditRefinement(
@@ -5784,7 +5687,7 @@ async function refineAsset(options) {
     );
     return { source, output, record, detection, palette, audit };
   } finally {
-    await (0, import_promises6.rm)(temp, { recursive: true, force: true });
+    await (0, import_promises5.rm)(temp, { recursive: true, force: true });
   }
 }
 async function refineFrameSet(options) {
@@ -5798,18 +5701,18 @@ async function refineFrameSet(options) {
   if (roles.some((role) => !role.trim()) || new Set(roles).size !== roles.length) {
     throw new Error("Frame-set roles must be non-empty and unique.");
   }
-  const output = import_node_path9.default.resolve(options.output);
-  const record = import_node_path9.default.resolve(qualityRecordPath(output));
+  const output = import_node_path8.default.resolve(options.output);
+  const record = import_node_path8.default.resolve(qualityRecordPath(output));
   const palette = normalizeRefinementPalette(options.palette);
   const finalOutputs = options.sources.map((source, index) => qualityFrameOutputPath(output, source.role, index));
   if (new Set(finalOutputs).size !== finalOutputs.length) {
     throw new Error("Frame-set roles resolve to duplicate output filenames.");
   }
-  const sourceSet = new Set(options.sources.map((source) => import_node_path9.default.resolve(source.path)));
+  const sourceSet = new Set(options.sources.map((source) => import_node_path8.default.resolve(source.path)));
   if (finalOutputs.some((file) => sourceSet.has(file))) {
     throw new Error("Frame-set refinement sources and outputs must be different files.");
   }
-  const temp = await (0, import_promises6.mkdtemp)(import_node_path9.default.join((0, import_node_os2.tmpdir)(), "pixelkiln-refine-frames-"));
+  const temp = await (0, import_promises5.mkdtemp)(import_node_path8.default.join((0, import_node_os2.tmpdir)(), "pixelkiln-refine-frames-"));
   try {
     const frames = [];
     const outputs = [];
@@ -5817,8 +5720,8 @@ async function refineFrameSet(options) {
     const sourcePaths = [];
     let firstOptions = null;
     for (const [index, sourceEntry] of options.sources.entries()) {
-      const source = import_node_path9.default.resolve(sourceEntry.path);
-      const temporaryOutput = import_node_path9.default.join(temp, `${String(index).padStart(2, "0")}.png`);
+      const source = import_node_path8.default.resolve(sourceEntry.path);
+      const temporaryOutput = import_node_path8.default.join(temp, `${String(index).padStart(2, "0")}.png`);
       const refined = await refineAsset({
         source,
         output: temporaryOutput,
@@ -5850,7 +5753,7 @@ async function refineFrameSet(options) {
       });
       outputs.push({
         path: finalOutputs[index],
-        data: await (0, import_promises6.readFile)(temporaryOutput)
+        data: await (0, import_promises5.readFile)(temporaryOutput)
       });
     }
     const first = frames[0];
@@ -5893,23 +5796,23 @@ async function refineFrameSet(options) {
     );
     return {
       sources: sourcePaths,
-      outputs: outputs.map((item) => import_node_path9.default.resolve(item.path)),
+      outputs: outputs.map((item) => import_node_path8.default.resolve(item.path)),
       record,
       frames,
       palette,
       audit
     };
   } finally {
-    await (0, import_promises6.rm)(temp, { recursive: true, force: true });
+    await (0, import_promises5.rm)(temp, { recursive: true, force: true });
   }
 }
 async function checkQualityRecord(recordPath) {
-  const record = import_node_path9.default.resolve(recordPath);
+  const record = import_node_path8.default.resolve(recordPath);
   const manifest = await readArtifactBundleManifest(record);
   const options = parseRecordOptions(manifest, record);
   const verification = await verifyArtifactBundle(record);
-  const sources = manifest.sources.map((source2) => import_node_path9.default.resolve(import_node_path9.default.dirname(record), source2.path));
-  const outputs = manifest.outputs.map((output2) => import_node_path9.default.resolve(import_node_path9.default.dirname(record), output2.path));
+  const sources = manifest.sources.map((source2) => import_node_path8.default.resolve(import_node_path8.default.dirname(record), source2.path));
+  const outputs = manifest.outputs.map((output2) => import_node_path8.default.resolve(import_node_path8.default.dirname(record), output2.path));
   const source = sources[0] ?? "";
   const output = outputs[0] ?? "";
   const expectedCount = options.frameSet?.count ?? 1;
@@ -5942,7 +5845,7 @@ async function checkQualityRecord(recordPath) {
 async function approveQualityRecord(recordPath, approval) {
   const reviewer = approval.reviewer.trim();
   if (!reviewer) throw new Error("A human reviewer name is required.");
-  const record = import_node_path9.default.resolve(recordPath);
+  const record = import_node_path8.default.resolve(recordPath);
   const manifest = await readArtifactBundleManifest(record);
   const options = parseRecordOptions(manifest, record);
   const verification = await verifyArtifactBundle(record);
@@ -5963,14 +5866,14 @@ async function approveQualityRecord(recordPath, approval) {
       `A refinement record must contain exactly ${expectedCount} source(s) and output(s).`
     );
   }
-  const root = import_node_path9.default.dirname(record);
+  const root = import_node_path8.default.dirname(record);
   const outputs = await Promise.all(manifest.outputs.map(async (entry) => {
-    const outputPath = import_node_path9.default.resolve(root, entry.path);
-    return { path: outputPath, data: await (0, import_promises6.readFile)(outputPath) };
+    const outputPath = import_node_path8.default.resolve(root, entry.path);
+    return { path: outputPath, data: await (0, import_promises5.readFile)(outputPath) };
   }));
   const sources = manifest.sources.map((source) => ({
     ...source,
-    path: import_node_path9.default.resolve(root, source.path)
+    path: import_node_path8.default.resolve(root, source.path)
   }));
   const approved = {
     ...options,
@@ -6002,8 +5905,8 @@ async function qualitySource(spec, lock) {
     if (spec.generator === "frames") {
       return { items: null, reason: "frame-set quality requires ordered downloaded provider outputs" };
     }
-    const source = import_node_path10.default.resolve(spec.root, spec.source);
-    return (0, import_node_fs8.existsSync)(source) ? { items: [{ role: "source", path: source }] } : { items: null, reason: `declared source is missing: ${spec.source}` };
+    const source = import_node_path9.default.resolve(spec.root, spec.source);
+    return (0, import_node_fs7.existsSync)(source) ? { items: [{ role: "source", path: source }] } : { items: null, reason: `declared source is missing: ${spec.source}` };
   }
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
   if (!entry) return { items: null, reason: "raw provider output is not in the lockfile" };
@@ -6032,7 +5935,7 @@ async function qualitySource(spec, lock) {
     }
     if (role) roles.add(role);
     const source = currentEntryOutputPath(entry, spec, index);
-    if (!(0, import_node_fs8.existsSync)(source)) return { items: null, reason: `raw provider output is missing: ${source}` };
+    if (!(0, import_node_fs7.existsSync)(source)) return { items: null, reason: `raw provider output is missing: ${source}` };
     if (await sha256File(source) !== output.sha256) {
       return { items: null, reason: "raw provider output was modified after download" };
     }
@@ -6051,7 +5954,7 @@ async function inspectQualityProfile(spec, lock) {
   }
   const sourcePaths = source.items.map((item) => item.path);
   const expectedOutputs = spec.generator === "frames" ? source.items.map((item, index) => qualityFrameOutputPath(output, item.role, index)) : [output];
-  if (!(0, import_node_fs8.existsSync)(record)) {
+  if (!(0, import_node_fs7.existsSync)(record)) {
     return {
       key,
       state: "needs-refinement",
@@ -6069,7 +5972,7 @@ async function inspectQualityProfile(spec, lock) {
     const expectedRevision = spec.quality.fixerRevision ?? PIXEL_ART_FIXER_REVISION;
     const expectedTransparency = spec.quality.minTransparency ?? null;
     const expectedFrameSet = spec.generator === "frames" ? { fps: spec.quality.fps ?? 12, count: source.items.length, roles: source.items.map((item) => item.role) } : null;
-    const contractChanged = JSON.stringify(check.sources.map((item) => import_node_path10.default.resolve(item))) !== JSON.stringify(sourcePaths.map((item) => import_node_path10.default.resolve(item))) || JSON.stringify(check.outputs.map((item) => import_node_path10.default.resolve(item))) !== JSON.stringify(expectedOutputs.map((item) => import_node_path10.default.resolve(item))) || JSON.stringify(check.options.palette.colors) !== JSON.stringify(expectedPalette) || check.options.nativeGrid.revision !== expectedRevision || check.options.audit.thresholds.minGridConfidence !== spec.quality.minGridConfidence || check.options.audit.thresholds.minTransparency !== expectedTransparency || (expectedFrameSet ? !check.options.frameSet || check.options.frameSet.fps !== expectedFrameSet.fps || check.options.frameSet.count !== expectedFrameSet.count || JSON.stringify(check.options.frameSet.roles) !== JSON.stringify(expectedFrameSet.roles) : check.options.frameSet !== void 0);
+    const contractChanged = JSON.stringify(check.sources.map((item) => import_node_path9.default.resolve(item))) !== JSON.stringify(sourcePaths.map((item) => import_node_path9.default.resolve(item))) || JSON.stringify(check.outputs.map((item) => import_node_path9.default.resolve(item))) !== JSON.stringify(expectedOutputs.map((item) => import_node_path9.default.resolve(item))) || JSON.stringify(check.options.palette.colors) !== JSON.stringify(expectedPalette) || check.options.nativeGrid.revision !== expectedRevision || check.options.audit.thresholds.minGridConfidence !== spec.quality.minGridConfidence || check.options.audit.thresholds.minTransparency !== expectedTransparency || (expectedFrameSet ? !check.options.frameSet || check.options.frameSet.fps !== expectedFrameSet.fps || check.options.frameSet.count !== expectedFrameSet.count || JSON.stringify(check.options.frameSet.roles) !== JSON.stringify(expectedFrameSet.roles) : check.options.frameSet !== void 0);
     if (contractChanged) {
       return {
         key,
@@ -6231,9 +6134,38 @@ async function requireApprovedQualitySources(specs, lock, assetIds, outputRoles)
   return sources;
 }
 
+// src/pipeline/postprocess.ts
+function postprocessFor(spec) {
+  if (!spec.enforcePalette || spec.palette.length < 2) return void 0;
+  return {
+    palette: {
+      colors: normalizePalette(spec.palette).map((color) => color.hex),
+      dither: "none",
+      distance: "redmean"
+    }
+  };
+}
+function samePostprocess(a, b) {
+  const pa = a?.palette;
+  const pb = b?.palette;
+  if (!pa && !pb) return true;
+  if (!pa || !pb) return false;
+  return pa.dither === pb.dither && pa.distance === pb.distance && pa.colors.length === pb.colors.length && pa.colors.every((color, i) => color === pb.colors[i]);
+}
+function postprocessCurrent(entry, spec) {
+  return samePostprocess(entry.postprocess, postprocessFor(spec));
+}
+function applyPostprocess(bytes, mediaType, record) {
+  if (!record?.palette || mediaType !== MediaType.PNG) return { bytes, changed: false };
+  const png = decodePng(bytes);
+  const { png: snapped, changed } = quantize(png, record.palette.colors);
+  if (!changed) return { bytes, changed: false };
+  return { bytes: encodeRgbaPng(snapped.width, snapped.height, snapped.pixels), changed: true };
+}
+
 // src/pipeline/revision.ts
-var import_node_fs9 = require("fs");
-var import_node_path11 = __toESM(require("path"), 1);
+var import_node_fs8 = require("fs");
+var import_node_path10 = __toESM(require("path"), 1);
 async function inspectRevisionReadiness(spec, lock) {
   if (!spec.revision) return null;
   return inspectRevision(spec, lock, /* @__PURE__ */ new Set());
@@ -6248,14 +6180,14 @@ async function inspectRevision(spec, lock, seen) {
       reason: `revision source ${spec.styleId}/${revision.sourceAssetId} is not ready: ${dependency.reason}`
     };
   }
-  if (!revision.sourceSha256 || !(0, import_node_fs9.existsSync)(revision.sourceFile)) {
+  if (!revision.sourceSha256 || !(0, import_node_fs8.existsSync)(revision.sourceFile)) {
     return { ready: false, reason: `revision source is missing: ${revision.sourceFile}` };
   }
   if (await sha256File(revision.sourceFile) !== revision.sourceSha256) {
     return { ready: false, reason: "revision source changed after the manifest was resolved" };
   }
   if (revision.maskFile) {
-    if (!revision.maskSha256 || !(0, import_node_fs9.existsSync)(revision.maskFile)) {
+    if (!revision.maskSha256 || !(0, import_node_fs8.existsSync)(revision.maskFile)) {
       return { ready: false, reason: `revision mask is missing: ${revision.maskFile}` };
     }
     if (await sha256File(revision.maskFile) !== revision.maskSha256) {
@@ -6285,8 +6217,8 @@ async function inspectParent(spec, lock, seen) {
     };
   }
   if (spec.source) {
-    const source = import_node_path11.default.resolve(spec.root, spec.source);
-    return (0, import_node_fs9.existsSync)(source) ? { ready: true, reason: "declared source is present" } : { ready: false, reason: `declared source is missing: ${spec.source}` };
+    const source = import_node_path10.default.resolve(spec.root, spec.source);
+    return (0, import_node_fs8.existsSync)(source) ? { ready: true, reason: "declared source is present" } : { ready: false, reason: `declared source is missing: ${spec.source}` };
   }
   const entry = lock.entries[key];
   if (!entry) return { ready: false, reason: "parent is not in the lockfile" };
@@ -6300,7 +6232,7 @@ async function inspectParent(spec, lock, seen) {
   for (let index = 0; index < entry.outputs.length; index++) {
     const output = entry.outputs[index];
     const file = currentEntryOutputPath(entry, spec, index);
-    if (!(0, import_node_fs9.existsSync)(file)) return { ready: false, reason: `parent output is missing: ${file}` };
+    if (!(0, import_node_fs8.existsSync)(file)) return { ready: false, reason: `parent output is missing: ${file}` };
     if (await sha256File(file) !== output.sha256) {
       return { ready: false, reason: `parent output was modified: ${file}` };
     }
@@ -6329,7 +6261,7 @@ function resumeActions(specs, lock) {
     const entry = lock.entries[key];
     if (!entry || entry.specHash !== spec.specHash) continue;
     if (entry.submissionComplete === false) continue;
-    const command = resumeCommandForStatus(entry.status);
+    const command = resumeCommandForStatus(entry.status) ?? (entry.status === "downloaded" && entry.outputs.length && !postprocessCurrent(entry, spec) ? "fetch" : null);
     if (!command) continue;
     if (command === "poll" && !entry.jobId) continue;
     if (command === "pick" && !entry.reviewObjectId) continue;
@@ -6355,7 +6287,7 @@ async function buildPlan(specs, lock, opts = {}) {
       state = "missing";
       reason = "--force";
     } else if (!entry && spec.source && spec.generator !== "frames") {
-      if ((0, import_node_fs10.existsSync)(import_node_path12.default.resolve(spec.root, spec.source))) {
+      if ((0, import_node_fs9.existsSync)(import_node_path11.default.resolve(spec.root, spec.source))) {
         state = "ok";
         reason = `placed from ${spec.source}; not generated`;
       } else {
@@ -6363,7 +6295,7 @@ async function buildPlan(specs, lock, opts = {}) {
         reason = `declared source is missing: ${spec.source}`;
       }
     } else if (!entry) {
-      if ((0, import_node_fs10.existsSync)(spec.outFile)) {
+      if ((0, import_node_fs9.existsSync)(spec.outFile)) {
         state = "untracked";
         reason = "file on disk, no provenance recorded";
       } else {
@@ -6395,12 +6327,15 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (entry.status !== "downloaded") {
       state = "in-flight";
       reason = `awaiting ${entry.status}`;
-    } else if (entry.outputs.length === 0 || entry.outputs.some((_output, index) => !(0, import_node_fs10.existsSync)(currentEntryOutputPath(entry, spec, index)))) {
+    } else if (entry.outputs.length === 0 || entry.outputs.some((_output, index) => !(0, import_node_fs9.existsSync)(currentEntryOutputPath(entry, spec, index)))) {
       state = "orphaned";
-      reason = entry.outputs.length === 0 ? "no recorded output files" : `missing on disk: ${entry.outputs.filter((_output, index) => !(0, import_node_fs10.existsSync)(currentEntryOutputPath(entry, spec, index))).map((o) => o.role ?? "asset").join(", ")}`;
+      reason = entry.outputs.length === 0 ? "no recorded output files" : `missing on disk: ${entry.outputs.filter((_output, index) => !(0, import_node_fs9.existsSync)(currentEntryOutputPath(entry, spec, index))).map((o) => o.role ?? "asset").join(", ")}`;
     } else if (await anyOutputModified(entry, spec)) {
       state = "orphaned";
       reason = "output modified since download";
+    } else if (!postprocessCurrent(entry, spec)) {
+      state = "recoverable";
+      reason = spec.enforcePalette ? "palette enforcement turned on; run pixelkiln fetch to snap the file (no generation cost)" : "palette enforcement turned off; run pixelkiln fetch to restore the provider's bytes (no generation cost)";
     } else {
       state = "ok";
       reason = "up to date";
@@ -6463,13 +6398,13 @@ function summarize(plan) {
 
 // src/project.ts
 async function openProject(manifestPath = "pixelkiln.manifest.json", opts = {}) {
-  const absolute = import_node_path13.default.resolve(manifestPath);
-  const root = import_node_path13.default.dirname(absolute);
+  const absolute = import_node_path12.default.resolve(manifestPath);
+  const root = import_node_path12.default.dirname(absolute);
   if (opts.env !== false) {
     loadEnvFiles(root);
-    if (import_node_path13.default.resolve(process.cwd()) !== root) loadEnvFiles(process.cwd());
+    if (import_node_path12.default.resolve(process.cwd()) !== root) loadEnvFiles(process.cwd());
   }
-  const lockPath = import_node_path13.default.resolve(opts.lockPath ?? import_node_path13.default.join(root, "pixelkiln.lock.json"));
+  const lockPath = import_node_path12.default.resolve(opts.lockPath ?? import_node_path12.default.join(root, "pixelkiln.lock.json"));
   const loaded = await loadManifest(absolute);
   const specs = await resolveSpecs(loaded, { styles: opts.styles ?? [], assets: opts.assets ?? [] });
   const lock = await loadLock(lockPath);
@@ -6536,9 +6471,9 @@ function shouldPersistSourceUrl(value) {
 }
 
 // src/recipes.ts
-var import_node_path14 = __toESM(require("path"), 1);
-var import_node_fs11 = require("fs");
-var import_promises7 = require("fs/promises");
+var import_node_path13 = __toESM(require("path"), 1);
+var import_node_fs10 = require("fs");
+var import_promises6 = require("fs/promises");
 var import_node_url = require("url");
 var import_zod3 = require("zod");
 var SHA256_RE = /^[0-9a-f]{64}$/;
@@ -6547,7 +6482,7 @@ var VERSION_RE = /^\d+\.\d+\.\d+$/;
 var RECIPE_FILE = "pixelkiln.recipe.json";
 var RECIPE_DIR_TOKEN = "{{recipeDir}}";
 var PortablePathSchema = import_zod3.z.string().min(1).refine((value) => {
-  if (value.includes("\\") || import_node_path14.default.posix.isAbsolute(value)) return false;
+  if (value.includes("\\") || import_node_path13.default.posix.isAbsolute(value)) return false;
   const parts = value.split("/");
   return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
 }, "expected a portable relative path without '.', '..', or backslashes");
@@ -6723,10 +6658,10 @@ function message3(error) {
   return error instanceof Error ? error.message : String(error);
 }
 async function readRecipeFile(recipePath, bundled) {
-  const absolute = import_node_path14.default.resolve(recipePath);
+  const absolute = import_node_path13.default.resolve(recipePath);
   let raw;
   try {
-    raw = JSON.parse(await (0, import_promises7.readFile)(absolute, "utf8"));
+    raw = JSON.parse(await (0, import_promises6.readFile)(absolute, "utf8"));
   } catch (error) {
     throw new Error(`Could not read recipe ${absolute}: ${message3(error)}`, { cause: error });
   }
@@ -6737,13 +6672,13 @@ async function readRecipeFile(recipePath, bundled) {
 ` + parsed.error.issues.map((issue) => `  ${issue.path.join(".") || "$"}: ${issue.message}`).join("\n")
     );
   }
-  return { recipe: parsed.data, path: absolute, dir: import_node_path14.default.dirname(absolute), bundled };
+  return { recipe: parsed.data, authored: raw, path: absolute, dir: import_node_path13.default.dirname(absolute), bundled };
 }
 async function walkRecipeFiles(root) {
-  if (!(0, import_node_fs11.existsSync)(root)) return [];
+  if (!(0, import_node_fs10.existsSync)(root)) return [];
   const out = [];
-  for (const entry of await (0, import_promises7.readdir)(root, { withFileTypes: true })) {
-    const resolved = import_node_path14.default.join(root, entry.name);
+  for (const entry of await (0, import_promises6.readdir)(root, { withFileTypes: true })) {
+    const resolved = import_node_path13.default.join(root, entry.name);
     if (entry.isDirectory()) out.push(...await walkRecipeFiles(resolved));
     else if (entry.isFile() && entry.name === RECIPE_FILE) out.push(resolved);
   }
@@ -6754,7 +6689,7 @@ function bundledRecipeRoot() {
 }
 async function listBundledRecipes(root = bundledRecipeRoot()) {
   const recipes = await Promise.all(
-    (await walkRecipeFiles(import_node_path14.default.resolve(root))).map((file) => readRecipeFile(file, true))
+    (await walkRecipeFiles(import_node_path13.default.resolve(root))).map((file) => readRecipeFile(file, true))
   );
   return recipes.sort(
     (a, b) => a.recipe.id.localeCompare(b.recipe.id) || compareVersions(b.recipe.version, a.recipe.version)
@@ -6777,9 +6712,9 @@ function parseSelector(selector) {
   return { id: match[1], version: match[2] };
 }
 async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
-  const local = import_node_path14.default.resolve(target);
-  if ((0, import_node_fs11.existsSync)(local)) {
-    const recipePath = import_node_path14.default.basename(local) === RECIPE_FILE ? local : import_node_path14.default.join(local, RECIPE_FILE);
+  const local = import_node_path13.default.resolve(target);
+  if ((0, import_node_fs10.existsSync)(local)) {
+    const recipePath = import_node_path13.default.basename(local) === RECIPE_FILE ? local : import_node_path13.default.join(local, RECIPE_FILE);
     return readRecipeFile(recipePath, false);
   }
   if (target.startsWith(".") || target.startsWith("/") || target.includes("\\")) {
@@ -6793,8 +6728,8 @@ async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
   return matches[0];
 }
 async function verifyFile(root, file) {
-  const absolute = import_node_path14.default.resolve(root, ...file.path.split("/"));
-  if (!(0, import_node_fs11.existsSync)(absolute)) {
+  const absolute = import_node_path13.default.resolve(root, ...file.path.split("/"));
+  if (!(0, import_node_fs10.existsSync)(absolute)) {
     return { path: file.path, expectedSha256: file.sha256, actualSha256: null, status: "missing" };
   }
   const actualSha256 = await sha256File(absolute);
@@ -6807,9 +6742,9 @@ async function verifyFile(root, file) {
 }
 async function verifyRecipe(target, options = {}) {
   const loaded = await resolveRecipe(target, options.bundledRoot);
-  const actualIntegrity = recipeDigest(loaded.recipe);
+  const actualIntegrity = recipeDigest(loaded.authored);
   const files = await Promise.all(loaded.recipe.files.map((file) => verifyFile(loaded.dir, file)));
-  const modelRoot = options.modelRoot ? import_node_path14.default.resolve(options.modelRoot) : null;
+  const modelRoot = options.modelRoot ? import_node_path13.default.resolve(options.modelRoot) : null;
   const models = modelRoot ? await Promise.all(loaded.recipe.models.map(async (model) => ({
     ...await verifyFile(modelRoot, model),
     source: model.source,
@@ -6843,7 +6778,7 @@ async function verifyRecipe(target, options = {}) {
   };
 }
 function renderStyle(style, destination, cwd) {
-  const portableDir = import_node_path14.default.relative(cwd, destination).split(import_node_path14.default.sep).join("/") || ".";
+  const portableDir = import_node_path13.default.relative(cwd, destination).split(import_node_path13.default.sep).join("/") || ".";
   const replace = (value) => {
     if (typeof value === "string") return value.replaceAll(RECIPE_DIR_TOKEN, portableDir);
     if (Array.isArray(value)) return value.map(replace);
@@ -6855,25 +6790,25 @@ function renderStyle(style, destination, cwd) {
   return replace(style);
 }
 async function installRecipe(target, options = {}) {
-  const cwd = import_node_path14.default.resolve(options.cwd ?? process.cwd());
+  const cwd = import_node_path13.default.resolve(options.cwd ?? process.cwd());
   const loaded = await resolveRecipe(target, options.bundledRoot);
   const verification = await verifyRecipe(loaded.path);
   if (!verification.ok) {
     throw new Error(`Recipe ${loaded.recipe.id}@${loaded.recipe.version} failed integrity verification.`);
   }
-  const destination = options.out ? import_node_path14.default.resolve(cwd, options.out) : import_node_path14.default.join(cwd, "pixelkiln-recipes", ...loaded.recipe.id.split("/"), loaded.recipe.version);
+  const destination = options.out ? import_node_path13.default.resolve(cwd, options.out) : import_node_path13.default.join(cwd, "pixelkiln-recipes", ...loaded.recipe.id.split("/"), loaded.recipe.version);
   const sources = [
     { path: RECIPE_FILE, source: loaded.path },
-    ...loaded.recipe.files.map((file) => ({ path: file.path, source: import_node_path14.default.join(loaded.dir, ...file.path.split("/")) }))
+    ...loaded.recipe.files.map((file) => ({ path: file.path, source: import_node_path13.default.join(loaded.dir, ...file.path.split("/")) }))
   ];
   const files = await Promise.all(sources.map(async (file) => ({
-    path: import_node_path14.default.join(destination, ...file.path.split("/")),
-    data: await (0, import_promises7.readFile)(file.source)
+    path: import_node_path13.default.join(destination, ...file.path.split("/")),
+    data: await (0, import_promises6.readFile)(file.source)
   })));
   if (!options.force) {
     for (const file of files) {
-      if (!(0, import_node_fs11.existsSync)(file.path)) continue;
-      const current = await (0, import_promises7.readFile)(file.path);
+      if (!(0, import_node_fs10.existsSync)(file.path)) continue;
+      const current = await (0, import_promises6.readFile)(file.path);
       if (!current.equals(file.data)) {
         throw new OverwriteRefusedError(
           `Recipe destination has local changes: ${file.path}. Choose another --out or pass --force to replace declared recipe files.`,
@@ -6896,6 +6831,152 @@ async function installRecipe(target, options = {}) {
   };
 }
 
+// src/pipeline/audit.ts
+var import_promises7 = require("fs/promises");
+var import_node_fs11 = require("fs");
+var import_node_path14 = __toESM(require("path"), 1);
+function paletteDistance(asset, reference) {
+  if (!asset.length || !reference.length) return 0;
+  let total = 0;
+  let weight = 0;
+  for (const color of asset) {
+    let nearest = Infinity;
+    for (const ref of reference) nearest = Math.min(nearest, colorDistance(color, ref));
+    total += nearest * color.weight;
+    weight += color.weight;
+  }
+  return weight === 0 ? 0 : total / weight;
+}
+function mergePalettes(palettes, topN = 24) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const palette of palettes) {
+    for (const color of palette) {
+      const key = `${color.r},${color.g},${color.b}`;
+      const existing = totals.get(key);
+      if (existing) existing.weight += color.weight;
+      else totals.set(key, { ...color });
+    }
+  }
+  const merged = [...totals.values()].sort((a, b) => b.weight - a.weight).slice(0, topN);
+  const sum = merged.reduce((s, c) => s + c.weight, 0) || 1;
+  return merged.map((c) => ({ ...c, weight: c.weight / sum }));
+}
+async function auditStyle(loaded, specs, styleId, lock) {
+  const style = loaded.manifest.styles[styleId];
+  if (!style) throw new Error(`Unknown style "${styleId}"`);
+  const mine = specs.filter((s) => s.styleId === styleId);
+  const assets = [];
+  const missing = [];
+  const unreadable = [];
+  for (const spec of mine) {
+    for (const output of resolveSpecOutputs(spec, lock, loaded.root)) {
+      if (!(0, import_node_fs11.existsSync)(output.absolutePath)) {
+        missing.push(output.id);
+        continue;
+      }
+      try {
+        const png = decodePng(await (0, import_promises7.readFile)(output.absolutePath));
+        const palette = extractPalette(png, 12);
+        assets.push({
+          assetId: spec.assetId,
+          ...output.role ? { outputRole: output.role } : {},
+          id: output.id,
+          file: output.absolutePath,
+          width: png.width,
+          height: png.height,
+          paletteDistance: 0,
+          // filled once the reference is known
+          transparency: transparencyRatio(png),
+          colorCount: countColors(png),
+          palette
+        });
+      } catch (err) {
+        unreadable.push(`${output.id}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  }
+  let reference = [];
+  let referenceFromStyleImages = false;
+  const refPalettes = [];
+  for (const img of style.styleImages) {
+    const abs = import_node_path14.default.resolve(loaded.root, img.path);
+    if (!(0, import_node_fs11.existsSync)(abs)) continue;
+    try {
+      refPalettes.push(extractPalette(decodePng(await (0, import_promises7.readFile)(abs)), 12));
+    } catch {
+    }
+  }
+  if (refPalettes.length) {
+    reference = mergePalettes(refPalettes);
+    referenceFromStyleImages = true;
+    for (const asset of assets) {
+      asset.paletteDistance = paletteDistance(asset.palette, reference);
+    }
+  } else {
+    reference = mergePalettes(assets.map((a) => a.palette));
+    for (const asset of assets) {
+      const others = assets.filter((a) => a !== asset).map((a) => a.palette);
+      asset.paletteDistance = others.length ? paletteDistance(asset.palette, mergePalettes(others)) : 0;
+    }
+  }
+  assets.sort((a, b) => b.paletteDistance - a.paletteDistance);
+  return { styleId, referenceFromStyleImages, reference, assets, missing, unreadable };
+}
+function countColors(png) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < png.pixels.length; i += 4) {
+    if (png.pixels[i + 3] < 128) continue;
+    seen.add(png.pixels[i] << 16 | png.pixels[i + 1] << 8 | png.pixels[i + 2]);
+  }
+  return seen.size;
+}
+function outliers(audit, sigma = 1.5) {
+  const n = audit.assets.length;
+  if (n < 3) return [];
+  const mean = audit.assets.reduce((s, a) => s + a.paletteDistance, 0) / n;
+  const variance = audit.assets.reduce((s, a) => s + (a.paletteDistance - mean) ** 2, 0) / n;
+  const sd = Math.sqrt(variance);
+  if (sd === 0) return [];
+  return audit.assets.filter((a) => a.paletteDistance > mean + sigma * sd);
+}
+function evaluateAudit(audit, thresholds = {}) {
+  const resolved = { ...thresholds, sigma: thresholds.sigma ?? 1.5 };
+  const relative = outliers(audit, resolved.sigma);
+  const relativeIds = new Set(relative.map((asset) => asset.id));
+  const violations = [];
+  for (const asset of audit.assets) {
+    const reasons = [];
+    if (relativeIds.has(asset.id)) {
+      reasons.push(`palette outlier beyond ${resolved.sigma} standard deviations`);
+    }
+    if (resolved.maxDistance !== void 0 && asset.paletteDistance > resolved.maxDistance) {
+      reasons.push(
+        `palette distance ${asset.paletteDistance.toFixed(1)} exceeds ${resolved.maxDistance}`
+      );
+    }
+    if (resolved.minTransparency !== void 0 && asset.transparency < resolved.minTransparency) {
+      reasons.push(
+        `transparency ${(asset.transparency * 100).toFixed(1)}% is below ${(resolved.minTransparency * 100).toFixed(1)}%`
+      );
+    }
+    if (resolved.maxColors !== void 0 && asset.colorCount > resolved.maxColors) {
+      reasons.push(`color count ${asset.colorCount} exceeds ${resolved.maxColors}`);
+    }
+    if (reasons.length) violations.push({ id: asset.id, reasons });
+  }
+  return {
+    safe: violations.length === 0 && audit.missing.length === 0 && audit.unreadable.length === 0,
+    thresholds: resolved,
+    outliers: [...relativeIds],
+    violations,
+    missing: [...audit.missing],
+    unreadable: [...audit.unreadable]
+  };
+}
+function hex(c) {
+  return `#${[c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+}
+
 // src/pipeline/quality-regression.ts
 var import_node_path15 = __toESM(require("path"), 1);
 var import_node_fs12 = require("fs");
@@ -7368,8 +7449,14 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
     if (e.status === "selected" || e.status === "download-failed") return true;
     if (e.status !== "downloaded") return false;
     if (opts.refresh) return e.outputs.length > 0 && Boolean(e.sourceUrls?.length || e.sourceUrl);
-    if (!opts.repair) return false;
     const spec = specByKey.get(key);
+    if (spec && e.specHash === spec.specHash && e.outputs.length && !postprocessCurrent(e, spec)) {
+      return Boolean(opts.force) || e.outputs.every((output) => {
+        const file = resolveOutputPath(output.path, spec.root);
+        return (0, import_node_fs14.existsSync)(file) && sha256((0, import_node_fs14.readFileSync)(file)) === output.sha256;
+      });
+    }
+    if (!opts.repair) return false;
     if (e.outputs.length === 0 || !spec) return true;
     return e.outputs.some((output) => {
       const file = resolveOutputPath(output.path, spec.root);
@@ -7408,6 +7495,8 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
       }
       const outputs = [];
       let wrote = false;
+      const wanted = postprocessFor(spec);
+      const reapply = entry.status === "downloaded" && !postprocessCurrent(entry, spec);
       try {
         for (let index = 0; index < sources.length; index++) {
           const source = sources[index];
@@ -7415,20 +7504,24 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             (o) => source.role ? o.role === source.role : !o.role && sources.length === 1
           );
           const target = recorded ? resolveOutputPath(recorded.path, spec.root) : expectedOutputPath(spec, source.role, index, sources.length, source.mediaType);
+          const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
+          const recordedRaw = recorded?.raw ?? recorded?.sha256;
           let fresh = null;
           if (opts.refresh) {
             if (!source.url) throw new Error(`no durable source URL to refresh ${source.role ?? "asset"} from`);
             fresh = await provider.download(source.url);
-            if (recorded && sha256(fresh) === recorded.sha256) {
+            if (recorded && sha256(fresh) === recordedRaw && !reapply) {
               log(`  current ${import_node_path17.default.relative(process.cwd(), target)}`);
               outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
               continue;
             }
           }
+          let raw = null;
+          let final = null;
           if ((0, import_node_fs14.existsSync)(target)) {
             const currentHash = await sha256File(target);
             if (recorded && currentHash === recorded.sha256) {
-              if (!fresh) {
+              if (!fresh && !reapply) {
                 if (cacheDir) {
                   await cacheMedia(
                     cacheDir,
@@ -7440,7 +7533,12 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
                 outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
                 continue;
               }
-              log(`  changed ${import_node_path17.default.relative(process.cwd(), target)} (upstream)`);
+              if (reapply && !fresh) {
+                if (!recorded.raw) raw = await (0, import_promises10.readFile)(target);
+                log(`  reapply ${import_node_path17.default.relative(process.cwd(), target)}`);
+              } else {
+                log(`  changed ${import_node_path17.default.relative(process.cwd(), target)} (upstream)`);
+              }
             } else {
               const superseded = (entry.supersededOutputs ?? []).find(
                 (output, oldIndex, all) => currentOutputPath(output, spec, oldIndex, all.length) === target
@@ -7462,26 +7560,41 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
               );
             }
           }
-          const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
-          let buf = fresh ?? (recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null);
-          if (buf) {
-            log(`  cached  ${import_node_path17.default.relative(process.cwd(), target)}`);
-          } else {
+          if (fresh) {
+            raw = fresh;
+          } else if (!raw && recorded && cacheDir) {
+            if (!reapply) final = await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType);
+            if (!final && recordedRaw) raw = await readCachedMedia(cacheDir, recordedRaw, expectedMediaType);
+            if (final || raw) log(`  cached  ${import_node_path17.default.relative(process.cwd(), target)}`);
+          }
+          if (!final && !raw) {
             if (!source.url) {
               throw new Error(`no source URL or cached bytes remain for ${source.role ?? "asset"}`);
             }
-            buf = await provider.download(source.url);
+            raw = await provider.download(source.url);
           }
           let mediaType;
+          const bytes = final ?? raw;
           try {
-            mediaType = validateMedia(buf, expectedMediaType);
+            mediaType = validateMedia(bytes, expectedMediaType);
           } catch (err) {
             const label = expectedMediaType === MediaType.GIF ? "GIF" : "PNG";
-            const mismatch = detectMediaType(buf) !== expectedMediaType;
+            const mismatch = detectMediaType(bytes) !== expectedMediaType;
             throw new Error(
-              `response for ${source.role ?? "asset"} was not ${mismatch ? "a" : "a valid"} ${label}` + (mismatch ? ` (${buf.length} bytes)` : `: ${err instanceof Error ? err.message : String(err)}`)
+              `response for ${source.role ?? "asset"} was not ${mismatch ? "a" : "a valid"} ${label}` + (mismatch ? ` (${bytes.length} bytes)` : `: ${err instanceof Error ? err.message : String(err)}`)
             );
           }
+          let rawHash = final ? recorded?.raw : void 0;
+          let buf = bytes;
+          if (!final) {
+            if (cacheDir) await cacheMedia(cacheDir, raw, mediaType);
+            const processed = applyPostprocess(raw, mediaType, wanted);
+            buf = processed.bytes;
+            if (processed.changed) {
+              rawHash = sha256(raw);
+              log(`  snapped ${import_node_path17.default.relative(process.cwd(), target)} to ${wanted.palette.colors.length} colours`);
+            }
+          }
           if (cacheDir) await cacheMedia(cacheDir, buf, mediaType);
           await (0, import_promises10.mkdir)(import_node_path17.default.dirname(target), { recursive: true });
           const tmp = `${target}.pixelkiln.tmp`;
@@ -7490,7 +7603,8 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             path: portableOutputPath(target, spec.root),
             sha256: sha256(buf),
             ...source.role ? { role: source.role } : {},
-            mediaType
+            mediaType,
+            ...rawHash ? { raw: rawHash } : {}
           });
           upsert(lock, key, { outputs: mergeOutputs(entry.outputs, outputs) });
           await saveLock(lockPath, lock);
@@ -7514,7 +7628,8 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           sourceUrls: persistentSources,
           downloadedAt: (/* @__PURE__ */ new Date()).toISOString(),
           error: null,
-          supersededOutputs: []
+          supersededOutputs: [],
+          postprocess: wanted
         });
         result.downloaded++;
       } catch (err) {
@@ -7621,6 +7736,7 @@ function retireGeneration(entry, retiredAt) {
     cost: entry.cost,
     costUnit: entry.costUnit,
     provider: entry.provider,
+    postprocess: entry.postprocess,
     retiredAt
   };
 }
@@ -7633,9 +7749,13 @@ function historyAfterReplacing(previous, limit, retiredAt) {
 }
 function referencedHashes(lock) {
   const hashes = /* @__PURE__ */ new Set();
+  const add = (output) => {
+    hashes.add(output.sha256);
+    if (output.raw) hashes.add(output.raw);
+  };
   for (const entry of Object.values(lock.entries)) {
-    for (const output of entry.outputs) hashes.add(output.sha256);
-    for (const generation of entry.history ?? []) for (const output of generation.outputs) hashes.add(output.sha256);
+    for (const output of entry.outputs) add(output);
+    for (const generation of entry.history ?? []) for (const output of generation.outputs) add(output);
   }
   return hashes;
 }
@@ -7706,6 +7826,7 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
     cost: generation.cost,
     costUnit: generation.costUnit,
     provider: generation.provider,
+    postprocess: generation.postprocess,
     history
   });
   await saveLock(lockPath, lock);
@@ -9062,6 +9183,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
         promptSuffix: "",
         styleImages: [],
         palette: [],
+        enforcePalette: false,
         outDir,
         tags: [name],
         providerOptions: {}
@@ -9942,6 +10064,8 @@ var ManifestEditSchema = import_zod7.z.discriminatedUnion("action", [
       promptSuffix: import_zod7.z.string().optional(),
       /** `#rrggbb` values; null or empty clears the style's own palette. */
       palette: import_zod7.z.array(import_zod7.z.string().regex(/^#?[0-9a-f]{6}$/i, "expected a six-digit hex colour")).max(256).nullable().optional(),
+      /** Snap downloaded art to the palette; false clears the style's own value. */
+      enforcePalette: import_zod7.z.boolean().optional(),
       /** Provider view name (PixelLab: low top-down, high top-down, side); empty clears. */
       view: import_zod7.z.string().max(64).nullable().optional(),
       /** pixflux only; null clears the style's own value. */
@@ -10033,6 +10157,7 @@ function applyEdit(raw, edit) {
       const colors = (patch2.palette ?? []).map((color) => "#" + color.replace(/^#/, "").toLowerCase());
       setOrDelete(style, "palette", colors.length ? colors : null);
     }
+    if (patch2.enforcePalette !== void 0) setOrDelete(style, "enforcePalette", patch2.enforcePalette || null);
     if (patch2.view !== void 0) setOrDelete(style, "view", patch2.view?.trim() || null);
     if (patch2.noBackground !== void 0) setOrDelete(style, "noBackground", patch2.noBackground);
     return;
@@ -10744,6 +10869,7 @@ async function buildGallerySnapshot(opts) {
       outputs,
       quality,
       providerMetadata: entry?.providerMetadata ?? {},
+      postprocess: entry?.postprocess ?? null,
       asset,
       source: spec.source ?? null,
       edit,
@@ -10804,6 +10930,7 @@ async function buildGallerySnapshot(opts) {
       outputs,
       quality: null,
       providerMetadata: entry.providerMetadata ?? {},
+      postprocess: entry.postprocess ?? null,
       asset: null,
       source: null,
       edit: null,
@@ -10852,6 +10979,7 @@ async function buildGallerySnapshot(opts) {
       promptPrefix: style?.promptPrefix ?? "",
       promptSuffix: style?.promptSuffix ?? "",
       palette: style?.palette ?? [],
+      enforcePalette: style?.enforcePalette ?? false,
       view: style?.view ?? null,
       noBackground: style?.noBackground ?? true,
       quality: Boolean(style?.quality),
@@ -12595,6 +12723,7 @@ async function workspaceStatus(ws, dir) {
   PixelLabClient,
   PixelLabError,
   PixelLabProvider,
+  PostprocessSchema,
   ProjectError,
   ProviderError,
   QualityBaselineSchema,