bytecut 0.0.0-stage → 0.1.0

package/dist/chunk-P5PFI3AO.js

@@ -0,0 +1,2170 @@
+#!/usr/bin/env node
+import {
+  readVideoCodecString
+} from "./chunk-3DBJKHOD.js";
+import {
+  MANIFEST_FILE,
+  MANIFEST_VERSION,
+  parseManifest,
+  serializeManifest
+} from "./chunk-TCQFQ354.js";
+import {
+  ANIMATED_GIF_REASON,
+  DEFAULT_PUBLIC_PATH,
+  buildPlan,
+  buildVideoItems,
+  classify,
+  sha256,
+  sha256File
+} from "./chunk-XUBQWBWH.js";
+import {
+  AbortedError,
+  outputWidth
+} from "./chunk-QOG2F4SF.js";
+import {
+  BUILTIN_POLICY,
+  IMAGE_PRESETS,
+  getImagePreset,
+  pickAv1Encoder
+} from "./chunk-3PF6BBFK.js";
+import {
+  SafeFs
+} from "./chunk-IZ4JEL3Q.js";
+import {
+  BytecutError,
+  PROJECT_RULES,
+  checkCache,
+  checkVideoCache,
+  formatBytes,
+  percentChange,
+  plural,
+  recordedByPlannedPath
+} from "./chunk-FY53B4NB.js";
+
+// src/core/commands/optimize.ts
+import { stat as stat3 } from "fs/promises";
+import { resolve as resolve5 } from "path";
+
+// src/core/audit/run.ts
+function sortFindings(findings) {
+  const key = (f) => `${f.ruleId}\0${f.source ?? ""}\0${f.path ?? ""}\0${f.message}`;
+  return findings.sort((a, b) => key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0);
+}
+async function runProjectRules(ctx) {
+  const all = [];
+  for (const rule of PROJECT_RULES) all.push(...await rule.check(ctx));
+  return sortFindings(all);
+}
+
+// src/core/cache/store.ts
+var CACHE_DIR = ".bytecut-cache";
+var CACHE_FILE = `${CACHE_DIR}/cache.json`;
+var CACHE_IGNORE_FILE = `${CACHE_DIR}/.gitignore`;
+var SCHEMA = 1;
+var MAX_ANALYSES = 5e3;
+var MAX_ESTIMATES = 2e4;
+function trim(record, max) {
+  const keys = Object.keys(record);
+  for (const key of keys.slice(0, Math.max(0, keys.length - max))) delete record[key];
+}
+var AnalysisCache = class _AnalysisCache {
+  constructor(data) {
+    this.data = data;
+  }
+  data;
+  dirty = false;
+  static empty(fingerprint) {
+    return new _AnalysisCache({
+      schema: SCHEMA,
+      fingerprint,
+      analyses: {},
+      svgs: {},
+      videos: {},
+      estimates: {}
+    });
+  }
+  static async load(reader, fingerprint) {
+    try {
+      const raw = await reader.readOutput(CACHE_FILE);
+      if (raw) {
+        const parsed = JSON.parse(raw.toString("utf8"));
+        if (parsed.schema === SCHEMA && parsed.fingerprint === fingerprint && parsed.analyses && parsed.svgs && parsed.videos && parsed.estimates) {
+          return new _AnalysisCache(parsed);
+        }
+      }
+    } catch {
+    }
+    return _AnalysisCache.empty(fingerprint);
+  }
+  getAnalysis(sha) {
+    return this.data.analyses[sha];
+  }
+  setAnalysis(sha, analysis) {
+    this.data.analyses[sha] = analysis;
+    this.dirty = true;
+  }
+  getSvg(sha) {
+    return this.data.svgs[sha];
+  }
+  setSvg(sha, analysis) {
+    this.data.svgs[sha] = analysis;
+    this.dirty = true;
+  }
+  getVideoProbe(sha) {
+    return this.data.videos[sha];
+  }
+  setVideoProbe(sha, probe) {
+    this.data.videos[sha] = probe;
+    this.dirty = true;
+  }
+  getEstimate(key) {
+    return this.data.estimates[key];
+  }
+  setEstimate(key, entry) {
+    this.data.estimates[key] = entry;
+    this.dirty = true;
+  }
+  get isDirty() {
+    return this.dirty;
+  }
+  /** Writes only when something changed, so a warm run leaves the disk untouched. */
+  async save(writer) {
+    if (!this.dirty) return;
+    trim(this.data.analyses, MAX_ANALYSES);
+    trim(this.data.svgs, MAX_ANALYSES);
+    trim(this.data.videos, MAX_ANALYSES);
+    trim(this.data.estimates, MAX_ESTIMATES);
+    await writer.writeOutput(CACHE_IGNORE_FILE, Buffer.from("*\n"));
+    await writer.writeOutput(CACHE_FILE, Buffer.from(`${JSON.stringify(this.data)}
+`));
+    this.dirty = false;
+  }
+};
+
+// src/core/execute/run.ts
+import { resolve as resolve2 } from "path";
+
+// src/core/execute/video.ts
+import { stat } from "fs/promises";
+import { resolve } from "path";
+
+// src/core/quality/video-search.ts
+var CLIP_SECONDS = 2;
+var WHOLE_MAX_SECONDS = 6;
+var CLIP_POINTS = [0.2, 0.5, 0.8];
+var FRAMES_PER_CLIP = 4;
+var SCORE_WIDTH = 512;
+var CRF_RANGE = {
+  av1: { lo: 10, hi: 63 },
+  h264: { lo: 10, hi: 51 }
+};
+var MAX_CONFIRM_BUMPS = 3;
+var CONFIRM_STEP = 2;
+function clipsFor(durationSec) {
+  if (durationSec <= WHOLE_MAX_SECONDS) {
+    return { clips: [{ startSec: 0, durationSec }], whole: true };
+  }
+  const clips = CLIP_POINTS.map((p) => ({
+    startSec: Math.round(
+      Math.max(0, Math.min(durationSec - CLIP_SECONDS, durationSec * p - CLIP_SECONDS / 2)) * 1e3
+    ) / 1e3,
+    durationSec: CLIP_SECONDS
+  }));
+  return { clips, whole: false };
+}
+var evenDown = (n) => Math.max(2, Math.floor(n / 2) * 2);
+function scoreGeometry(probe, maxWidth) {
+  const out = outputWidth(probe.width, maxWidth);
+  const width = evenDown(Math.min(SCORE_WIDTH, out));
+  const height = evenDown(probe.height * width / Math.max(1, probe.width));
+  return { width, height };
+}
+async function findCrf(options) {
+  const { lo, hi, target } = options;
+  const scores = /* @__PURE__ */ new Map();
+  const measure = async (crf) => {
+    const known = scores.get(crf);
+    if (known !== void 0) return known;
+    const score = await options.measure(crf);
+    scores.set(crf, score);
+    return score;
+  };
+  const passes = async (crf) => await measure(crf) >= target;
+  const start = Math.min(hi, Math.max(lo, options.start));
+  let good;
+  let bad;
+  if (await passes(start)) {
+    good = start;
+    bad = hi + 1;
+    if (start < hi) {
+      if (await passes(hi)) good = hi;
+      else bad = hi;
+    }
+  } else {
+    bad = start;
+    if (start === lo || !await passes(lo)) {
+      return { ok: false, bestScore: scores.get(lo) ?? scores.get(start), probes: scores.size };
+    }
+    good = lo;
+  }
+  while (bad - good > 1) {
+    const mid = Math.floor((good + bad) / 2);
+    if (await passes(mid)) good = mid;
+    else bad = mid;
+  }
+  return { ok: true, crf: good, score: scores.get(good), probes: scores.size };
+}
+var mean = (values) => values.reduce((a, b) => a + b, 0) / values.length;
+function createVideoSearcher(request) {
+  const { clips, whole } = clipsFor(request.probe.durationSec);
+  const { width, height } = scoreGeometry(request.probe, request.maxWidth);
+  const references = /* @__PURE__ */ new Map();
+  const reference = (index) => {
+    let cached = references.get(index);
+    if (!cached) {
+      const clip = clips[index];
+      cached = request.engine.frames(
+        {
+          ...clip,
+          source: request.source,
+          count: FRAMES_PER_CLIP,
+          width,
+          height,
+          pipeline: { probe: request.probe, maxWidth: request.maxWidth, maxFps: request.maxFps }
+        },
+        request.signal
+      );
+      references.set(index, cached);
+    }
+    return cached;
+  };
+  async function scoreFrames(ref, got) {
+    const n = Math.min(ref.length, got.length);
+    if (n === 0 || Math.abs(ref.length - got.length) > 1) {
+      throw new Error(`compared ${ref.length} reference and ${got.length} encoded frames`);
+    }
+    const scorer = request.scorer;
+    if (!scorer) throw new Error("ssimulacra2 needs a scorer");
+    const scores = [];
+    for (let i = 0; i < n; i++) scores.push(await scorer.score(ref[i], got[i]));
+    return mean(scores);
+  }
+  const sample = (clip, crf) => ({
+    source: request.source,
+    encoder: request.encoder,
+    crf,
+    speed: request.speed,
+    maxWidth: request.maxWidth,
+    maxFps: request.maxFps,
+    ...clip,
+    probe: request.probe
+  });
+  async function measure(crf) {
+    const perClip = await Promise.all(
+      clips.map(async (clip, i) => {
+        if (request.metric === "vmaf") {
+          return request.engine.vmaf(sample(clip, crf), request.signal);
+        }
+        const got = await request.engine.encodedFrames(
+          { ...sample(clip, crf), count: FRAMES_PER_CLIP, width, height },
+          request.signal
+        );
+        return scoreFrames(await reference(i), got);
+      })
+    );
+    const score = Math.min(...perClip);
+    request.onProbe?.(crf, score);
+    return score;
+  }
+  return {
+    whole,
+    async find() {
+      const range = CRF_RANGE[request.codec];
+      return findCrf({
+        start: request.startCrf,
+        lo: range.lo,
+        hi: range.hi,
+        target: request.target,
+        measure
+      });
+    },
+    async confirm(outputPath, crf) {
+      const perClip = await Promise.all(
+        clips.map(async (clip, i) => {
+          if (request.metric === "vmaf") {
+            return request.engine.vmaf(
+              { ...sample(clip, crf), candidate: outputPath },
+              request.signal
+            );
+          }
+          const got = await request.engine.frames(
+            { ...clip, source: outputPath, count: FRAMES_PER_CLIP, width, height, pipeline: null },
+            request.signal
+          );
+          return scoreFrames(await reference(i), got);
+        })
+      );
+      return Math.min(...perClip);
+    }
+  };
+}
+
+// src/core/execute/video.ts
+var message = (error) => error instanceof Error ? error.message : String(error);
+function encoderFor(codec, caps) {
+  if (codec === "h264") return caps.libx264 ? "libx264" : null;
+  return pickAv1Encoder({ ...caps, libvpxVp9: false, libvmaf: false });
+}
+function probeFromItem(item) {
+  return {
+    durationSec: item.durationSec,
+    width: item.sourceWidth,
+    height: item.sourceHeight,
+    fps: item.fps,
+    videoCodec: item.videoCodec,
+    pixelFormat: null,
+    bitrate: null,
+    hasAudio: item.hasAudio,
+    audioCodec: null,
+    container: "unknown"
+  };
+}
+var evenHeight = (probe, width) => Math.max(2, Math.round(probe.height * width / Math.max(1, probe.width) / 2) * 2);
+function sameParams(planned, r) {
+  if (planned.role !== r.role || planned.width !== r.width) return false;
+  if (planned.role === "video") {
+    const search = planned.search;
+    const sameSearch = search === void 0 ? r.search === void 0 && r.crf === planned.crf : r.search?.metric === search.metric && r.search.target === search.target;
+    return sameSearch && r.codec === planned.codec && r.speed === planned.speed && r.maxWidth === planned.maxWidth && r.maxFps === planned.maxFps && r.audio === planned.audio;
+  }
+  return r.quality === planned.quality && r.effort === planned.effort && r.at === planned.at;
+}
+async function runVideoItem(item, ctx) {
+  const base = {
+    source: item.source,
+    sourceBytes: item.sourceBytes,
+    sourceSha256: item.sourceSha256,
+    sourceWidth: item.sourceWidth,
+    sourceHeight: item.sourceHeight,
+    durationSec: item.durationSec,
+    preset: item.preset
+  };
+  if (item.skip) return { ...base, status: "skipped", reason: item.skip.reason, outputs: [] };
+  const caps = await ctx.engine.capabilities();
+  if (!caps) {
+    return { ...base, status: "skipped", reason: "needs ffmpeg", outputs: [] };
+  }
+  const sourcePath = resolve(ctx.projectRoot, ...item.source.split("/"));
+  let digest;
+  try {
+    digest = await sha256File(sourcePath);
+  } catch (error) {
+    return { ...base, status: "failed", reason: message(error), outputs: [] };
+  }
+  if (digest !== item.sourceSha256) {
+    return {
+      ...base,
+      status: "failed",
+      reason: "source changed since the plan was created; re-run to build a fresh plan",
+      outputs: []
+    };
+  }
+  const hashOutput = async (path) => {
+    try {
+      return await sha256File(await ctx.fs.outputPath(path));
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+  };
+  const unavailable = /* @__PURE__ */ new Set();
+  for (const codec of ["av1", "h264"]) {
+    if (!encoderFor(codec, caps)) unavailable.add(codec);
+  }
+  const entry = ctx.manifest?.videos[item.source];
+  const recorded = new Map((entry?.outputs ?? []).map((o) => [o.path, o]));
+  const sameSource = entry?.sha256 === item.sourceSha256;
+  const probe = probeFromItem(item);
+  const versions = await ctx.engine.versions();
+  const encoderLabel = (name) => `${name} (ffmpeg ${versions.ffmpeg ?? "unknown"})`;
+  const outputs = [];
+  const record = (output) => {
+    outputs.push(output);
+    ctx.onOutputDone?.(item.source, output);
+  };
+  let encodedAny = false;
+  let failed = false;
+  const searchable = (metric) => metric === "vmaf" ? caps.libvmaf : ctx.quality !== void 0;
+  const retrySearch = /* @__PURE__ */ new Set();
+  for (const r of entry?.outputs ?? []) {
+    if (r.search && r.score === void 0 && searchable(r.search.metric)) retrySearch.add(r.path);
+  }
+  const noForce = !ctx.force;
+  if (noForce && retrySearch.size === 0) {
+    const state = await checkVideoCache(item, entry, hashOutput, unavailable);
+    if (state.kind === "hit") {
+      for (const planned of item.outputs) {
+        const r = recorded.get(planned.path);
+        if (!r) {
+          if (planned.role === "video") {
+            record(unavailableResult(planned, ctx));
+          }
+          continue;
+        }
+        record(fromRecorded(r));
+      }
+      return { ...base, status: "cached", outputs };
+    }
+  }
+  for (const planned of item.outputs) {
+    if (ctx.signal?.aborted) {
+      record(blank(planned, "cancelled"));
+      continue;
+    }
+    const prior = recorded.get(planned.path);
+    if (noForce && sameSource && prior && prior.status === "written" && !retrySearch.has(planned.path) && sameParams(planned, prior)) {
+      const actual = await hashOutput(planned.path);
+      if (actual !== null && actual === prior.sha256) {
+        record(fromRecorded(prior));
+        continue;
+      }
+    }
+    try {
+      if (planned.role === "poster") {
+        const result2 = await makePoster(planned, sourcePath, probe, ctx, encoderLabel);
+        record(result2.output);
+        if (result2.wrote) encodedAny = true;
+        continue;
+      }
+      const encoder = encoderFor(planned.codec, caps);
+      if (!encoder) {
+        record(unavailableResult(planned, ctx));
+        continue;
+      }
+      const result = await makeVideo(
+        planned,
+        item,
+        sourcePath,
+        probe,
+        encoder,
+        caps.libvmaf,
+        ctx,
+        encoderLabel
+      );
+      record(result.output);
+      if (result.wrote) encodedAny = true;
+      if (result.output.status === "failed" || result.output.status === "unmet") failed = true;
+    } catch (error) {
+      if (error instanceof AbortedError || ctx.signal?.aborted) {
+        record(blank(planned, "cancelled"));
+      } else {
+        failed = true;
+        record({ ...blank(planned, "failed"), error: message(error) });
+      }
+    }
+  }
+  const cancelled = outputs.some((o) => o.status === "cancelled");
+  const allReused = !encodedAny && !failed && !cancelled;
+  return {
+    ...base,
+    status: failed ? "failed" : cancelled ? "cancelled" : allReused ? "cached" : "done",
+    outputs
+  };
+}
+function unavailableResult(planned, ctx) {
+  const encoders = planned.codec === "av1" ? "libsvtav1 or libaom-av1" : "libx264";
+  ctx.warnings.add(
+    `${planned.codec === "av1" ? "AV1" : "H.264"} encoder not available (needs ${encoders}): ${planned.codec === "av1" ? "AV1" : "H.264"} outputs were skipped`
+  );
+  return { ...blank(planned, "unavailable"), codec: planned.codec };
+}
+function blank(planned, status) {
+  return {
+    path: planned.path,
+    role: planned.role,
+    format: planned.role === "video" ? "mp4" : "avif",
+    ...planned.role === "video" ? { codec: planned.codec } : {},
+    width: planned.width,
+    height: 0,
+    bytes: 0,
+    status
+  };
+}
+function fromRecorded(r) {
+  return {
+    path: r.path,
+    role: r.role,
+    format: r.format,
+    ...r.codec ? { codec: r.codec } : {},
+    width: r.width,
+    height: r.height,
+    ...r.fps !== void 0 ? { fps: r.fps } : {},
+    bytes: r.bytes,
+    ...r.sha256 ? { sha256: r.sha256 } : {},
+    ...r.crf !== void 0 ? { crf: r.crf } : {},
+    ...r.speed !== void 0 ? { speed: r.speed } : {},
+    ...r.maxWidth !== void 0 ? { maxWidth: r.maxWidth } : {},
+    ...r.maxFps !== void 0 ? { maxFps: r.maxFps } : {},
+    ...r.audio !== void 0 ? { audio: r.audio } : {},
+    ...r.quality !== void 0 ? { quality: r.quality } : {},
+    ...r.effort !== void 0 ? { effort: r.effort } : {},
+    ...r.at !== void 0 ? { at: r.at } : {},
+    ...r.codecs ? { codecs: r.codecs } : {},
+    ...r.search ? { search: r.search } : {},
+    ...r.score !== void 0 ? { score: r.score } : {},
+    ...r.scorer ? { scorer: r.scorer } : {},
+    encoder: r.encoder,
+    status: r.status === "already-optimal" ? "already-optimal" : "unchanged"
+  };
+}
+async function existingPolicy(path, newHash, ctx) {
+  let existing = null;
+  try {
+    existing = await sha256File(await ctx.fs.outputPath(path));
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (existing === null) return null;
+  if (existing === newHash) return "unchanged";
+  if (!ctx.force && ctx.owned.get(path) !== existing) {
+    ctx.warnings.add(
+      `${path}: a file is already there that bytecut did not write or that was edited; left alone (use --force to overwrite)`
+    );
+    return "protected";
+  }
+  return null;
+}
+var SEARCH_SHARE = 0.4;
+var EXPECTED_PROBES = 7;
+async function searchCrf(planned, item, sourcePath, probe, encoder, hasLibvmaf, ctx) {
+  const search = planned.search;
+  if (!search) return { kind: "fixed", skipped: false };
+  const skip = (why) => {
+    ctx.warnings.add(`${planned.path}: ${why}; used the fixed CRF ${planned.crf}`);
+    return { kind: "fixed", skipped: true };
+  };
+  let scorer;
+  if (search.metric === "vmaf") {
+    if (!hasLibvmaf) return skip("libvmaf is missing, so the VMAF search was skipped");
+  } else {
+    if (!ctx.quality) return skip("no quality scorer is available, so the search was skipped");
+    try {
+      scorer = await ctx.quality.scorer();
+    } catch (error) {
+      return skip(`the quality scorer could not start (${message(error)})`);
+    }
+  }
+  const { width, height } = scoreGeometry(probe, planned.maxWidth);
+  if (search.metric === "ssimulacra2" && (width < 8 || height < 8)) {
+    return skip("the video is too small to score");
+  }
+  const searcher = createVideoSearcher({
+    engine: ctx.engine,
+    metric: search.metric,
+    target: search.target,
+    scorer,
+    source: sourcePath,
+    probe,
+    codec: planned.codec,
+    encoder,
+    speed: planned.speed,
+    maxWidth: planned.maxWidth,
+    maxFps: planned.maxFps,
+    startCrf: planned.crf,
+    signal: ctx.signal,
+    onProbe: () => {
+      probes++;
+      ctx.onProgress?.(
+        item.source,
+        planned.path,
+        SEARCH_SHARE * Math.min(1, probes / EXPECTED_PROBES)
+      );
+    }
+  });
+  let probes = 0;
+  const outcome = await searcher.find();
+  if (!outcome.ok) {
+    return {
+      kind: "unmet",
+      reason: `${search.metric} reached only ${outcome.bestScore.toFixed(1)} at crf ${CRF_RANGE[planned.codec].lo}, below the target ${search.target}`
+    };
+  }
+  return {
+    kind: "found",
+    crf: outcome.crf,
+    score: outcome.score,
+    scorer: search.metric === "vmaf" ? "libvmaf" : scorer.kind,
+    searcher
+  };
+}
+async function makeVideo(planned, item, sourcePath, probe, encoder, hasLibvmaf, ctx, encoderLabel) {
+  const searched = await searchCrf(planned, item, sourcePath, probe, encoder, hasLibvmaf, ctx);
+  if (searched.kind === "unmet") {
+    ctx.warnings.add(`${planned.path}: ${searched.reason}; nothing was written`);
+    return {
+      output: {
+        ...blank(planned, "unmet"),
+        codec: planned.codec,
+        error: searched.reason
+      },
+      wrote: false
+    };
+  }
+  const found = searched.kind === "found" ? searched : null;
+  const range = CRF_RANGE[planned.codec];
+  let crf = found ? found.crf : planned.crf;
+  let score = found?.score;
+  const base = found ? SEARCH_SHARE : 0;
+  const temp = await ctx.fs.reserveTemp(planned.path);
+  try {
+    for (let bumps = 0; ; bumps++) {
+      await ctx.engine.encode(
+        {
+          source: sourcePath,
+          output: temp,
+          encoder,
+          crf,
+          speed: planned.speed,
+          maxWidth: planned.maxWidth,
+          maxFps: planned.maxFps,
+          audio: planned.audio,
+          audioBitrate: planned.audioBitrate,
+          probe
+        },
+        (fraction) => ctx.onProgress?.(item.source, planned.path, base + (1 - base) * fraction),
+        ctx.signal ?? new AbortController().signal
+      );
+      if (!found || found.searcher.whole) break;
+      const measured = await found.searcher.confirm(temp, crf);
+      if (measured >= planned.search.target) {
+        score = measured;
+        break;
+      }
+      if (bumps >= MAX_CONFIRM_BUMPS || crf - CONFIRM_STEP < range.lo) {
+        await ctx.fs.discardTemp(temp);
+        const reason = `${planned.search.metric} was ${measured.toFixed(1)} on the full encode at crf ${crf}, below the target ${planned.search.target}`;
+        ctx.warnings.add(`${planned.path}: ${reason}; nothing was written`);
+        return {
+          output: { ...blank(planned, "unmet"), codec: planned.codec, error: reason },
+          wrote: false
+        };
+      }
+      crf -= CONFIRM_STEP;
+    }
+    const { size } = await stat(temp);
+    const video = await readVideoCodecString(temp).catch(() => null);
+    const codecs = video ? planned.audio === "keep" && probe.hasAudio ? `${video}, mp4a.40.2` : video : void 0;
+    const fps = planned.maxFps !== null ? Math.min(probe.fps, planned.maxFps) : probe.fps;
+    const result = {
+      path: planned.path,
+      role: "video",
+      format: "mp4",
+      codec: planned.codec,
+      width: planned.width,
+      height: evenHeight(probe, planned.width),
+      fps: Math.round(fps * 100) / 100,
+      bytes: size,
+      crf,
+      speed: planned.speed,
+      maxWidth: planned.maxWidth,
+      maxFps: planned.maxFps,
+      audio: planned.audio,
+      ...codecs ? { codecs } : {},
+      // Recorded even when the search could not run, so the cache recognises the output; a
+      // missing score is what marks it as worth searching once the metric is available.
+      ...planned.search ? { search: planned.search } : {},
+      ...score !== void 0 && found ? { score: Math.round(score * 100) / 100, scorer: found.scorer } : {},
+      encoder: encoderLabel(encoder),
+      status: "written"
+    };
+    if (size >= item.sourceBytes) {
+      await ctx.fs.discardTemp(temp);
+      return { output: { ...result, status: "already-optimal" }, wrote: true };
+    }
+    const digest = await sha256File(temp);
+    const verdict = await existingPolicy(planned.path, digest, ctx);
+    if (verdict) {
+      await ctx.fs.discardTemp(temp);
+      return { output: { ...result, sha256: digest, status: verdict }, wrote: false };
+    }
+    await ctx.fs.commitTemp(temp, planned.path);
+    return { output: { ...result, sha256: digest }, wrote: true };
+  } catch (error) {
+    await ctx.fs.discardTemp(temp);
+    throw error;
+  }
+}
+async function makePoster(planned, sourcePath, probe, ctx, encoderLabel) {
+  const at = Math.max(0, probe.durationSec * planned.at);
+  const png = await ctx.engine.frame(sourcePath, at, planned.width);
+  const encoded = await ctx.imageEngine.encode(png, {
+    format: "avif",
+    width: planned.width,
+    lossless: false,
+    quality: planned.quality,
+    effort: planned.effort
+  });
+  const digest = sha256(encoded.data);
+  const output = {
+    path: planned.path,
+    role: "poster",
+    format: "avif",
+    width: encoded.width,
+    height: encoded.height,
+    bytes: encoded.data.byteLength,
+    sha256: digest,
+    quality: planned.quality,
+    effort: planned.effort,
+    at: planned.at,
+    encoder: encoded.encoder || encoderLabel("poster"),
+    status: "written"
+  };
+  const verdict = await existingPolicy(planned.path, digest, ctx);
+  if (verdict) return { output: { ...output, status: verdict }, wrote: false };
+  await ctx.fs.writeOutput(planned.path, encoded.data);
+  return { output, wrote: true };
+}
+
+// src/core/quality/pixels.ts
+function hasTransparency(image) {
+  if (image.channels !== 4) return false;
+  for (let i = 3; i < image.data.length; i += 4) if (image.data[i] < 255) return true;
+  return false;
+}
+function flatten(image, background) {
+  const { width, height, channels, data } = image;
+  const out = new Uint8Array(width * height * 3);
+  const base = background === "white" ? 255 : 0;
+  for (let p = 0, i = 0, o = 0; p < width * height; p++, i += channels, o += 3) {
+    const alpha = channels === 4 ? data[i + 3] : 255;
+    if (alpha === 255) {
+      out[o] = data[i];
+      out[o + 1] = data[i + 1];
+      out[o + 2] = data[i + 2];
+    } else {
+      const a = alpha / 255;
+      out[o] = Math.round(data[i] * a + base * (1 - a));
+      out[o + 1] = Math.round(data[i + 1] * a + base * (1 - a));
+      out[o + 2] = Math.round(data[i + 2] * a + base * (1 - a));
+    }
+  }
+  return { data: out, width, height };
+}
+function dropAlpha(image) {
+  if (image.channels === 3) return image;
+  const out = new Uint8Array(image.width * image.height * 3);
+  for (let p = 0, i = 0, o = 0; p < image.width * image.height; p++, i += 4, o += 3) {
+    out[o] = image.data[i];
+    out[o + 1] = image.data[i + 1];
+    out[o + 2] = image.data[i + 2];
+  }
+  return { data: out, width: image.width, height: image.height, channels: 3 };
+}
+function detail(image, w) {
+  const { channels, data } = image;
+  const luma = (x, y) => {
+    const i = (y * image.width + x) * channels;
+    return data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114;
+  };
+  let sum = 0;
+  let count = 0;
+  for (let y = w.y; y < w.y + w.height - 1; y += 2) {
+    for (let x = w.x; x < w.x + w.width - 1; x += 2) {
+      const l = luma(x, y);
+      sum += Math.abs(luma(x + 1, y) - l) + Math.abs(luma(x, y + 1) - l);
+      count++;
+    }
+  }
+  return count === 0 ? 0 : sum / count;
+}
+function pickWindow(image, size) {
+  const w = Math.min(size, image.width);
+  const h = Math.min(size, image.height);
+  const nx = Math.max(1, Math.floor(image.width / w));
+  const ny = Math.max(1, Math.floor(image.height / h));
+  const ox = Math.floor((image.width - nx * w) / 2);
+  const oy = Math.floor((image.height - ny * h) / 2);
+  const tiles = [];
+  for (let j = 0; j < ny; j++) {
+    for (let i = 0; i < nx; i++) {
+      const window = { x: ox + i * w, y: oy + j * h, width: w, height: h };
+      tiles.push({ window, detail: detail(image, window), index: j * nx + i });
+    }
+  }
+  tiles.sort((a, b) => a.detail - b.detail || a.index - b.index);
+  return tiles[Math.floor((tiles.length - 1) / 2)].window;
+}
+function crop(image, w) {
+  const { channels } = image;
+  const out = new Uint8Array(w.width * w.height * channels);
+  for (let y = 0; y < w.height; y++) {
+    const from = ((w.y + y) * image.width + w.x) * channels;
+    out.set(image.data.subarray(from, from + w.width * channels), y * w.width * channels);
+  }
+  return { data: out, width: w.width, height: w.height, channels };
+}
+
+// src/core/quality/search.ts
+var MAX_BUMPS = 8;
+var STEP = 0.9;
+var MIN_WIDTH_FRACTION = 0.5;
+var even = (n) => Math.max(2, Math.floor(n / 2) * 2);
+var kb = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;
+var Cancelled = class extends Error {
+};
+async function searchQuality(request) {
+  const { engine, scorer, search } = request;
+  if (!engine.decodeRaw || !engine.encodeRaw) {
+    return {
+      ok: false,
+      reason: "this image engine cannot decode raw pixels",
+      encodes: 0,
+      unsearchable: true
+    };
+  }
+  const decodeRaw = engine.decodeRaw.bind(engine);
+  const encodeRaw = engine.encodeRaw.bind(engine);
+  let encodes = 0;
+  const checkAbort = () => {
+    if (request.signal?.aborted) throw new Cancelled();
+  };
+  async function atWidth(width) {
+    const ref = await decodeRaw(request.input, { width });
+    if (Math.min(ref.width, ref.height) < 8) {
+      throw new Unsearchable(`a ${ref.width}x${ref.height} image is too small to score`);
+    }
+    const opaque = !hasTransparency(ref);
+    const backgrounds = opaque ? ["white"] : ["white", "black"];
+    const scoreAgainst = async (reference, candidate) => {
+      let worst = Infinity;
+      for (const bg of backgrounds) {
+        worst = Math.min(worst, await scorer.score(flatten(reference, bg), flatten(candidate, bg)));
+      }
+      return worst;
+    };
+    const window = pickWindow(ref, request.cropSize ?? 512);
+    const refCrop = crop(ref, window);
+    const cropInput = opaque ? dropAlpha(refCrop) : refCrop;
+    const cropScores = /* @__PURE__ */ new Map();
+    const cropScore = async (quality2) => {
+      const known = cropScores.get(quality2);
+      if (known !== void 0) return known;
+      checkAbort();
+      const encoded = await encodeRaw(cropInput, {
+        format: request.format,
+        quality: quality2,
+        effort: request.effort
+      });
+      encodes++;
+      const decoded = await decodeRaw(Buffer.from(encoded.data), {});
+      const score = await scoreAgainst(refCrop, decoded);
+      cropScores.set(quality2, score);
+      return score;
+    };
+    const smallestQuality = async (minScore) => {
+      if (await cropScore(100) < minScore) return { quality: 100, reached: false };
+      let lo2 = 1;
+      let hi2 = 100;
+      while (lo2 < hi2) {
+        const mid = lo2 + hi2 >> 1;
+        if (await cropScore(mid) >= minScore) hi2 = mid;
+        else lo2 = mid + 1;
+      }
+      return { quality: lo2, reached: true };
+    };
+    const full = async (quality2) => {
+      checkAbort();
+      const encoded = await engine.encode(request.input, {
+        format: request.format,
+        width,
+        lossless: false,
+        quality: quality2,
+        effort: request.effort
+      });
+      encodes++;
+      const decoded = await decodeRaw(Buffer.from(encoded.data), {});
+      if (decoded.width !== ref.width || decoded.height !== ref.height) {
+        throw new Error(
+          `the ${request.format} output is ${decoded.width}x${decoded.height}, expected ${ref.width}x${ref.height}`
+        );
+      }
+      return { encoded, score: await scoreAgainst(ref, decoded) };
+    };
+    const notes = [];
+    const target = await smallestQuality(search.target);
+    if (!target.reached) {
+      notes.push(
+        `the sampled region does not reach ${search.target} even at quality 100; confirming at full size`
+      );
+    }
+    let quality = target.quality;
+    let current = await full(quality);
+    let bumps = 0;
+    while (current.score < search.target && quality < 100 && bumps < MAX_BUMPS) {
+      const next = Math.min(100, quality + (bumps < 4 ? 1 : 2));
+      notes.push(
+        `quality ${quality} scored ${current.score.toFixed(2)} at full size (target ${search.target}); raised to ${next}`
+      );
+      quality = next;
+      current = await full(quality);
+      bumps++;
+    }
+    if (current.score < search.target) {
+      return {
+        ok: false,
+        kind: "score",
+        reason: `quality ${quality} scores ${current.score.toFixed(1)}, below the target ${search.target}`
+      };
+    }
+    const cap = search.maxBytes;
+    if (cap === void 0 || current.encoded.data.byteLength <= cap) {
+      return { ok: true, quality, encoded: current.encoded, score: current.score, notes };
+    }
+    const floor = search.floor ?? search.target;
+    let lowQuality = Math.min((await smallestQuality(floor)).quality, quality);
+    let low = lowQuality === quality ? current : await full(lowQuality);
+    let lowBumps = 0;
+    while (low.score < floor && lowQuality < quality && lowBumps < MAX_BUMPS) {
+      lowQuality++;
+      low = lowQuality === quality ? current : await full(lowQuality);
+      lowBumps++;
+    }
+    if (low.encoded.data.byteLength > cap) {
+      return {
+        ok: false,
+        kind: "size",
+        reason: `${kb(low.encoded.data.byteLength)} at the score floor ${floor} (quality ${lowQuality}) is over the ${kb(cap)} cap`
+      };
+    }
+    let best = { quality: lowQuality, ...low };
+    let lo = lowQuality;
+    let hi = quality;
+    while (hi - lo > 1) {
+      const mid = lo + hi >> 1;
+      const candidate = await full(mid);
+      if (candidate.encoded.data.byteLength <= cap && candidate.score >= floor) {
+        lo = mid;
+        best = { quality: mid, ...candidate };
+      } else hi = mid;
+    }
+    notes.push(
+      `${kb(current.encoded.data.byteLength)} at quality ${quality} is over ${kb(cap)}; lowered to ${best.quality} (score ${best.score.toFixed(1)}, floor ${floor})`
+    );
+    return { ok: true, quality: best.quality, encoded: best.encoded, score: best.score, notes };
+  }
+  try {
+    let width = request.width;
+    let last = await atWidth(width);
+    if (last.ok) return { ...last, width, encodes };
+    const widthNotes = [];
+    while (!last.ok && last.kind === "size") {
+      const next = even(width * STEP);
+      const halfWidth = Math.ceil(request.width * MIN_WIDTH_FRACTION);
+      if (next <= request.minWidth || next < halfWidth || next >= width) {
+        const stoppedAt = next <= request.minWidth ? `the next planned width (${request.minWidth}px)` : `half the planned width (${halfWidth}px)`;
+        return {
+          ok: false,
+          encodes,
+          reason: `${last.reason}; stepping down reached ${stoppedAt} without fitting`
+        };
+      }
+      widthNotes.push(`${width}px did not fit (${last.reason})`);
+      width = next;
+      last = await atWidth(width);
+    }
+    if (last.ok) {
+      return {
+        ok: true,
+        quality: last.quality,
+        width,
+        encoded: last.encoded,
+        score: last.score,
+        encodes,
+        notes: [
+          `stepped the width down from ${request.width}px to ${width}px to fit (${widthNotes.length} wider ${widthNotes.length === 1 ? "size" : "sizes"} did not)`,
+          ...last.notes
+        ]
+      };
+    }
+    return { ok: false, encodes, reason: last.reason };
+  } catch (error) {
+    if (error instanceof Cancelled)
+      return { ok: false, encodes, reason: "cancelled", cancelled: true };
+    if (error instanceof Unsearchable) {
+      return { ok: false, encodes, reason: error.message, unsearchable: true };
+    }
+    throw error;
+  }
+}
+var Unsearchable = class extends Error {
+};
+
+// src/core/execute/run.ts
+function message2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function header(item) {
+  return {
+    source: item.source,
+    sourceBytes: item.sourceBytes,
+    sourceSha256: item.sourceSha256,
+    sourceWidth: item.sourceWidth,
+    sourceHeight: item.sourceHeight,
+    preset: item.preset
+  };
+}
+async function runItem(item, options, owned, warnings) {
+  const base = header(item);
+  if (item.skip) return { ...base, status: "skipped", reason: item.skip.reason, outputs: [] };
+  let input;
+  try {
+    input = await options.fs.readSource(resolve2(options.projectRoot, ...item.source.split("/")));
+  } catch (error) {
+    return { ...base, status: "failed", reason: message2(error), outputs: [] };
+  }
+  if (sha256(input) !== item.sourceSha256) {
+    return {
+      ...base,
+      status: "failed",
+      reason: "source changed since the plan was created; re-run to build a fresh plan",
+      outputs: []
+    };
+  }
+  const hashOutput = async (path) => {
+    const data = await options.fs.readOutput(path);
+    return data ? sha256(data) : null;
+  };
+  const entry = options.manifest?.sources[item.source];
+  if (!options.force && entry) {
+    const state = await checkCache(item, entry, hashOutput);
+    if (state.kind === "hit") {
+      const recorded = recordedByPlannedPath(entry);
+      const outputs2 = item.outputs.map((planned) => {
+        const r = recorded.get(planned.path);
+        return {
+          path: r.path,
+          format: r.format,
+          width: r.width,
+          height: r.height,
+          bytes: r.bytes,
+          lossless: r.lossless,
+          quality: r.quality,
+          effort: r.effort,
+          ...r.sha256 ? { sha256: r.sha256 } : {},
+          encoder: r.encoder,
+          ...r.search ? { search: r.search } : {},
+          ...r.score !== void 0 ? { score: r.score } : {},
+          ...r.scorer ? { scorer: r.scorer } : {},
+          status: r.status === "already-optimal" ? "already-optimal" : "unchanged"
+        };
+      });
+      return { ...base, status: "cached", outputs: outputs2 };
+    }
+  }
+  const outputs = [];
+  const record = (output) => {
+    outputs.push(output);
+    options.onOutputDone?.(item.source, output);
+  };
+  let failed = false;
+  for (const planned of item.outputs) {
+    const shared = {
+      path: planned.path,
+      format: planned.format,
+      lossless: planned.lossless,
+      quality: planned.quality,
+      effort: planned.effort
+    };
+    if (options.signal?.aborted) {
+      record({ ...shared, width: planned.width, height: 0, bytes: 0, status: "cancelled" });
+      continue;
+    }
+    try {
+      let encoded;
+      let outPath = planned.path;
+      let quality = planned.quality;
+      let searched = {};
+      if (planned.search && !planned.lossless && options.quality) {
+        const biggerSibling = Math.max(
+          0,
+          ...item.outputs.filter((o) => o.format === planned.format && o.width < planned.width).map((o) => o.width)
+        );
+        const scorer = await options.quality.scorer();
+        const outcome = await searchQuality({
+          engine: options.engine,
+          scorer,
+          input,
+          format: planned.format,
+          width: planned.width,
+          effort: planned.effort,
+          search: planned.search,
+          minWidth: biggerSibling,
+          signal: options.signal
+        });
+        if (outcome.ok) {
+          encoded = outcome.encoded;
+          quality = outcome.quality;
+          const stepped = outcome.width !== planned.width;
+          if (stepped) {
+            outPath = planned.path.replace(
+              new RegExp(`-${planned.width}\\.${planned.format}$`),
+              `-${outcome.width}.${planned.format}`
+            );
+          }
+          searched = {
+            search: { ...planned.search, ...stepped ? { plannedPath: planned.path } : {} },
+            score: Math.round(outcome.score * 100) / 100,
+            scorer: scorer.kind
+          };
+          for (const note of outcome.notes) warnings.push(`${outPath}: ${note}`);
+        } else if (outcome.cancelled) {
+          record({ ...shared, width: planned.width, height: 0, bytes: 0, status: "cancelled" });
+          continue;
+        } else if (outcome.unsearchable) {
+          warnings.push(
+            `${planned.path}: perceptual search was not possible (${outcome.reason}); used quality ${planned.quality}`
+          );
+        } else {
+          record({
+            ...shared,
+            width: planned.width,
+            height: 0,
+            bytes: 0,
+            status: "unmet",
+            error: outcome.reason
+          });
+          failed = true;
+          continue;
+        }
+      } else if (planned.search && !planned.lossless) {
+        warnings.push(
+          `${planned.path}: no quality scorer available; used the fixed quality ${planned.quality} instead of the ssimulacra2 target`
+        );
+      }
+      encoded ??= await options.engine.encode(input, planned);
+      const result = {
+        ...shared,
+        path: outPath,
+        quality,
+        width: encoded.width,
+        height: encoded.height,
+        bytes: encoded.data.byteLength,
+        encoder: encoded.encoder,
+        ...searched
+      };
+      if (encoded.data.byteLength >= item.sourceBytes) {
+        record({ ...result, status: "already-optimal" });
+        continue;
+      }
+      const newHash = sha256(encoded.data);
+      const onDisk = await options.fs.readOutput(outPath);
+      if (onDisk) {
+        const diskHash = sha256(onDisk);
+        if (diskHash === newHash) {
+          record({ ...result, sha256: newHash, status: "unchanged" });
+          continue;
+        }
+        if (!options.force && owned.get(outPath) !== diskHash) {
+          warnings.push(
+            `${outPath}: a file is already there that bytecut did not write or that was edited; left alone (use --force to overwrite)`
+          );
+          record({ ...result, status: "protected" });
+          continue;
+        }
+      }
+      await options.fs.writeOutput(outPath, encoded.data);
+      record({ ...result, sha256: newHash, status: "written" });
+    } catch (error) {
+      failed = true;
+      record({
+        ...shared,
+        width: planned.width,
+        height: 0,
+        bytes: 0,
+        status: "failed",
+        error: message2(error)
+      });
+    }
+  }
+  const cancelled = outputs.some((o) => o.status === "cancelled");
+  return { ...base, status: failed ? "failed" : cancelled ? "cancelled" : "done", outputs };
+}
+async function runPlan(plan, options) {
+  const results = new Array(plan.items.length);
+  const warnings = [];
+  const owned = /* @__PURE__ */ new Map();
+  for (const source of Object.values(options.manifest?.sources ?? {})) {
+    for (const out of source.outputs) if (out.sha256) owned.set(out.path, out.sha256);
+  }
+  for (const source of Object.values(options.manifest?.videos ?? {})) {
+    for (const out of source.outputs) if (out.sha256) owned.set(out.path, out.sha256);
+  }
+  let next = 0;
+  let done = 0;
+  const workers = Math.max(1, Math.min(options.concurrency ?? 2, Math.max(1, plan.items.length)));
+  async function worker() {
+    for (; ; ) {
+      const index = next++;
+      const item = plan.items[index];
+      if (!item) return;
+      let result;
+      if (options.signal?.aborted) {
+        result = { ...header(item), status: "cancelled", outputs: [] };
+      } else {
+        options.onItemStart?.(item.source);
+        result = await runItem(item, options, owned, warnings);
+      }
+      results[index] = result;
+      options.onItemDone?.(result, ++done, plan.items.length);
+    }
+  }
+  const videoItems = plan.videos ?? [];
+  const videoResults = new Array(videoItems.length);
+  let videoNext = 0;
+  let videoDone = 0;
+  const videoWorkers = Math.max(
+    1,
+    Math.min(options.video?.concurrency ?? 1, Math.max(1, videoItems.length))
+  );
+  const videoWarnings = /* @__PURE__ */ new Set();
+  async function videoWorker() {
+    for (; ; ) {
+      const index = videoNext++;
+      const item = videoItems[index];
+      if (!item) return;
+      let result;
+      const lane = options.video;
+      const fs = options.fs;
+      if (options.signal?.aborted) {
+        result = videoHeader(item, "cancelled");
+      } else if (!lane || !fs.reserveTemp || !fs.commitTemp || !fs.discardTemp || !fs.outputPath) {
+        result = videoHeader(item, "skipped", `needs ffmpeg: ${lane?.needsFfmpeg ?? "not found"}`);
+      } else {
+        options.onVideoItemStart?.(item.source);
+        result = await runVideoItem(item, {
+          projectRoot: options.projectRoot,
+          engine: lane.engine,
+          imageEngine: options.engine,
+          fs,
+          manifest: options.manifest,
+          force: options.force ?? false,
+          signal: options.signal,
+          owned,
+          warnings: videoWarnings,
+          quality: options.quality,
+          onProgress: options.onVideoProgress,
+          onOutputDone: options.onVideoOutputDone
+        });
+      }
+      videoResults[index] = result;
+      options.onVideoItemDone?.(result, ++videoDone, videoItems.length);
+    }
+  }
+  await Promise.all([
+    ...Array.from({ length: workers }, worker),
+    ...videoItems.length > 0 ? Array.from({ length: videoWorkers }, videoWorker) : []
+  ]);
+  for (const w of videoWarnings) warnings.push(w);
+  return {
+    items: results,
+    ...videoItems.length > 0 ? { videos: videoResults } : {},
+    cancelled: options.signal?.aborted ?? false,
+    warnings: warnings.sort()
+  };
+}
+function videoHeader(item, status, reason) {
+  return {
+    source: item.source,
+    sourceBytes: item.sourceBytes,
+    sourceSha256: item.sourceSha256,
+    sourceWidth: item.sourceWidth,
+    sourceHeight: item.sourceHeight,
+    durationSec: item.durationSec,
+    preset: item.preset,
+    status,
+    ...reason ? { reason } : {},
+    outputs: []
+  };
+}
+
+// src/core/manifest/update.ts
+function outputUrl(publicPath, path) {
+  return `${publicPath.replace(/\/+$/, "")}/${path}`;
+}
+function toManifestOutput(out, publicPath) {
+  return {
+    path: out.path,
+    url: outputUrl(publicPath, out.path),
+    format: out.format,
+    width: out.width,
+    height: out.height,
+    bytes: out.bytes,
+    ...out.status === "already-optimal" ? {} : { sha256: out.sha256 },
+    lossless: out.lossless,
+    quality: out.quality,
+    effort: out.effort,
+    encoder: out.encoder ?? "unknown",
+    status: out.status === "already-optimal" ? "already-optimal" : "written",
+    ...out.search ? { search: out.search } : {},
+    ...out.score !== void 0 ? { score: out.score } : {},
+    ...out.scorer ? { scorer: out.scorer } : {}
+  };
+}
+function mergeItem(old, item, plannedPaths, publicPath, catalog) {
+  const produced = /* @__PURE__ */ new Map();
+  for (const out of item.outputs) {
+    if (out.status === "written" || out.status === "unchanged" || out.status === "already-optimal") {
+      produced.set(out.path, toManifestOutput(out, publicPath));
+    }
+  }
+  if (produced.size === 0) return null;
+  const sameSource = old?.sha256 === item.sourceSha256;
+  const merged = new Map(produced);
+  for (const previous of old?.outputs ?? []) {
+    if (merged.has(previous.path)) continue;
+    const standsFor = previous.search?.plannedPath;
+    if (standsFor !== void 0 && merged.has(standsFor)) {
+      const { plannedPath: _superseded, ...search } = previous.search;
+      void _superseded;
+      merged.set(previous.path, { ...previous, search });
+    } else if (plannedPaths.has(standsFor ?? previous.path) && !sameSource) {
+      merged.set(previous.path, { ...previous, status: "stale" });
+    } else {
+      merged.set(previous.path, previous);
+    }
+  }
+  const priority = (catalog?.image ?? IMAGE_PRESETS)[item.preset]?.priority === true;
+  return {
+    sha256: item.sourceSha256,
+    bytes: item.sourceBytes,
+    width: item.sourceWidth,
+    height: item.sourceHeight,
+    preset: item.preset,
+    ...priority ? { priority } : {},
+    // A placeholder describes the content it was made from, so it only survives an unchanged source.
+    ...sameSource && old?.placeholder ? { placeholder: old.placeholder } : {},
+    outputs: [...merged.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
+  };
+}
+function toManifestVideoOutput(out, publicPath) {
+  return {
+    path: out.path,
+    url: outputUrl(publicPath, out.path),
+    role: out.role,
+    format: out.format,
+    ...out.codec ? { codec: out.codec } : {},
+    width: out.width,
+    height: out.height,
+    ...out.fps !== void 0 ? { fps: out.fps } : {},
+    bytes: out.bytes,
+    ...out.status === "already-optimal" || !out.sha256 ? {} : { sha256: out.sha256 },
+    ...out.crf !== void 0 ? { crf: out.crf } : {},
+    ...out.speed !== void 0 ? { speed: out.speed } : {},
+    ...out.maxWidth !== void 0 ? { maxWidth: out.maxWidth } : {},
+    ...out.maxFps !== void 0 ? { maxFps: out.maxFps } : {},
+    ...out.audio !== void 0 ? { audio: out.audio } : {},
+    ...out.quality !== void 0 ? { quality: out.quality } : {},
+    ...out.effort !== void 0 ? { effort: out.effort } : {},
+    ...out.at !== void 0 ? { at: out.at } : {},
+    ...out.codecs ? { codecs: out.codecs } : {},
+    encoder: out.encoder ?? "unknown",
+    status: out.status === "already-optimal" ? "already-optimal" : "written",
+    ...out.search ? { search: out.search } : {},
+    ...out.score !== void 0 ? { score: out.score } : {},
+    ...out.scorer ? { scorer: out.scorer } : {}
+  };
+}
+function mergeVideoItem(old, item, plannedPaths, publicPath) {
+  const produced = /* @__PURE__ */ new Map();
+  for (const out of item.outputs) {
+    if (out.status === "written" || out.status === "unchanged" || out.status === "already-optimal") {
+      produced.set(out.path, toManifestVideoOutput(out, publicPath));
+    }
+  }
+  if (produced.size === 0) return null;
+  const sameSource = old?.sha256 === item.sourceSha256;
+  const merged = new Map(produced);
+  for (const previous of old?.outputs ?? []) {
+    if (merged.has(previous.path)) continue;
+    if (plannedPaths.has(previous.path) && !sameSource) {
+      merged.set(previous.path, { ...previous, status: "stale" });
+    } else {
+      merged.set(previous.path, previous);
+    }
+  }
+  return {
+    sha256: item.sourceSha256,
+    bytes: item.sourceBytes,
+    width: item.sourceWidth,
+    height: item.sourceHeight,
+    durationSec: item.durationSec,
+    preset: item.preset,
+    ...sameSource && old?.placeholder ? { placeholder: old.placeholder } : {},
+    outputs: [...merged.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
+  };
+}
+function updateManifest(previous, plan, result, tools, catalog) {
+  const sources = { ...previous?.sources };
+  const planned = new Map(plan.items.map((i) => [i.source, i]));
+  for (const item of result.items) {
+    if (item.status === "skipped" || item.status === "cached") continue;
+    const plannedPaths = new Set(planned.get(item.source)?.outputs.map((o) => o.path));
+    const merged = mergeItem(sources[item.source], item, plannedPaths, plan.publicPath, catalog);
+    if (merged) sources[item.source] = merged;
+  }
+  const videos = { ...previous?.videos };
+  const plannedVideos = new Map((plan.videos ?? []).map((v) => [v.source, v]));
+  for (const item of result.videos ?? []) {
+    if (item.status === "skipped" || item.status === "cached") continue;
+    const plannedPaths = new Set(plannedVideos.get(item.source)?.outputs.map((o) => o.path));
+    const merged = mergeVideoItem(videos[item.source], item, plannedPaths, plan.publicPath);
+    if (merged) videos[item.source] = merged;
+  }
+  for (const entry of Object.values(sources)) {
+    entry.outputs = entry.outputs.map((o) => ({ ...o, url: outputUrl(plan.publicPath, o.path) }));
+  }
+  for (const entry of Object.values(videos)) {
+    entry.outputs = entry.outputs.map((o) => ({ ...o, url: outputUrl(plan.publicPath, o.path) }));
+  }
+  return { version: MANIFEST_VERSION, tools, publicPath: plan.publicPath, sources, videos };
+}
+
+// src/core/commands/plan-media.ts
+import { resolve as resolve3 } from "path";
+async function withVideos(plan, options) {
+  const gifSources = new Set(
+    plan.items.filter((i) => i.skip?.reason.startsWith(ANIMATED_GIF_REASON)).map((i) => i.source)
+  );
+  const files = [
+    ...options.videoFiles,
+    ...[...gifSources].map((s) => resolve3(options.projectRoot, ...s.split("/")))
+  ];
+  const images = { ...plan, items: plan.items.filter((i) => !gifSources.has(i.source)) };
+  if (files.length === 0) return images;
+  const claimed = new Set(images.items.flatMap((i) => i.outputs.map((o) => o.path)));
+  const engine = options.videoEngine;
+  const videos = await buildVideoItems({
+    files,
+    projectRoot: options.projectRoot,
+    staticRoot: options.staticRoot,
+    engine,
+    needsFfmpeg: options.needsFfmpeg,
+    ...options.presetOverrides ? { presetOverrides: options.presetOverrides } : {},
+    ...options.policy ? { policy: options.policy } : {},
+    claimed,
+    async probe(path, digest) {
+      const cached = options.cache.getVideoProbe(digest);
+      if (cached) return cached;
+      const fresh = engine ? await engine.probe(path) : null;
+      if (fresh) options.cache.setVideoProbe(digest, fresh);
+      return fresh;
+    }
+  });
+  return videos.length > 0 ? { ...images, videos } : images;
+}
+
+// src/core/scan/collect.ts
+import { readFile, readdir, stat as stat2 } from "fs/promises";
+import { extname, join, relative, resolve as resolve4, sep } from "path";
+import ignore from "ignore";
+var RASTER = /* @__PURE__ */ new Set([".jpg", ".jpeg", ".png", ".webp", ".avif", ".gif"]);
+var VIDEO = /* @__PURE__ */ new Set([".mp4", ".webm", ".mov", ".m4v", ".mkv"]);
+var SVG = /* @__PURE__ */ new Set([".svg"]);
+var ALWAYS_SKIPPED = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+function isIgnored(scopes, absolute, isDir) {
+  for (let i = scopes.length - 1; i >= 0; i--) {
+    const scope = scopes[i];
+    const rel = relative(scope.base, absolute).split(sep).join("/");
+    if (rel === "" || rel.startsWith("..")) continue;
+    const verdict = scope.matcher.test(isDir ? `${rel}/` : rel);
+    if (verdict.ignored) return true;
+    if (verdict.unignored) return false;
+  }
+  return false;
+}
+async function loadScope(dir) {
+  try {
+    const text = await readFile(join(dir, ".gitignore"), "utf8");
+    return { base: dir, matcher: ignore().add(text) };
+  } catch {
+    return null;
+  }
+}
+async function walkFiles(startDir, options, visit) {
+  const excluded = options.exclude?.length ? ignore().add(options.exclude) : null;
+  const isExcluded = (path, isDir) => {
+    if (!excluded) return false;
+    const rel2 = relative(options.cwd, path).split(sep).join("/");
+    return rel2 !== "" && !rel2.startsWith("..") && excluded.ignores(isDir ? `${rel2}/` : rel2);
+  };
+  async function walk(dir, inherited) {
+    const own = await loadScope(dir);
+    const scopes = own ? [...inherited, own] : inherited;
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (ALWAYS_SKIPPED.has(entry.name) || path === options.outDir) continue;
+        if (isIgnored(scopes, path, true) || isExcluded(path, true)) continue;
+        await walk(path, scopes);
+      } else if (entry.isFile()) {
+        if (isIgnored(scopes, path, false) || isExcluded(path, false)) continue;
+        await visit(path);
+      }
+    }
+  }
+  const chain = [];
+  const rel = relative(options.cwd, startDir);
+  if (rel !== "" && !rel.startsWith("..")) {
+    const rootScope = await loadScope(options.cwd);
+    if (rootScope) chain.push(rootScope);
+    let current = options.cwd;
+    for (const part of rel.split(sep).slice(0, -1)) {
+      current = join(current, part);
+      const scope = await loadScope(current);
+      if (scope) chain.push(scope);
+    }
+  }
+  await walk(startDir, chain);
+}
+async function collectAssets(inputs, options) {
+  const files = /* @__PURE__ */ new Set();
+  const svgs = /* @__PURE__ */ new Set();
+  const videos = /* @__PURE__ */ new Set();
+  const sourceDirs = [];
+  const unsupported = [];
+  function classify2(path, explicit) {
+    const ext = extname(path).toLowerCase();
+    if (RASTER.has(ext)) files.add(path);
+    else if (SVG.has(ext)) svgs.add(path);
+    else if (VIDEO.has(ext)) videos.add(path);
+    else if (explicit) unsupported.push(path);
+  }
+  for (const input of inputs) {
+    const absolute = resolve4(options.cwd, input);
+    const info = await stat2(absolute).catch(() => null);
+    if (!info) throw new BytecutError("INPUT_NOT_FOUND", `No such file or folder: ${input}`);
+    if (info.isDirectory()) {
+      sourceDirs.push(absolute);
+      if (absolute !== options.outDir)
+        await walkFiles(absolute, options, (p) => classify2(p, false));
+    } else {
+      classify2(absolute, true);
+    }
+  }
+  const sorted = (s) => [...s].sort();
+  return {
+    files: sorted(files),
+    svgs: sorted(svgs),
+    videos: sorted(videos),
+    sourceDirs,
+    unsupported
+  };
+}
+
+// src/core/commands/optimize.ts
+function engineFingerprint(engine, extra = {}) {
+  const v = { ...engine.versions(), ...extra };
+  return Object.keys(v).sort().map((k) => `${k}=${v[k]}`).join(";");
+}
+async function optimize(options) {
+  const { projectRoot, engine } = options;
+  const outDir = resolve5(projectRoot, options.outDir);
+  let plan = options.savedPlan;
+  let sourceFiles;
+  let sourceDirs = [];
+  let unsupported = [];
+  let svgs = [];
+  let videos = [];
+  if (plan) {
+    sourceFiles = [...plan.items, ...plan.videos ?? []].map(
+      (i) => resolve5(projectRoot, ...i.source.split("/"))
+    );
+  } else {
+    const found = await collectAssets(options.inputs ?? [], {
+      cwd: projectRoot,
+      outDir,
+      ...options.exclude ? { exclude: options.exclude } : {}
+    });
+    sourceFiles = [...found.files, ...found.videos];
+    sourceDirs = found.sourceDirs;
+    unsupported = found.unsupported;
+    svgs = found.svgs;
+    videos = found.videos;
+    if (found.files.length === 0 && found.videos.length === 0) {
+      return {
+        plan: {
+          version: 1,
+          outDir: "",
+          publicPath: options.publicPath ?? DEFAULT_PUBLIC_PATH,
+          items: []
+        },
+        cache: /* @__PURE__ */ new Map(),
+        findings: [],
+        unsupported,
+        svgs,
+        videos,
+        notes: []
+      };
+    }
+  }
+  const fs = await SafeFs.create({ projectRoot, outDir, sourceFiles, sourceDirs });
+  const videoVersions = options.videoEngine ? await options.videoEngine.versions() : {};
+  const analysisCache = await AnalysisCache.load(fs, engineFingerprint(engine, videoVersions));
+  const analyze = async (data, digest) => {
+    const cached = analysisCache.getAnalysis(digest);
+    if (cached) return cached;
+    const fresh = await engine.analyze(data);
+    analysisCache.setAnalysis(digest, fresh);
+    return fresh;
+  };
+  const policy = options.policy ?? BUILTIN_POLICY;
+  const override = options.presetOverride ? getImagePreset(options.presetOverride, policy.catalog) : null;
+  const choosePreset = (source, analysis) => {
+    const perFile = options.presetOverrides?.[source];
+    if (perFile) {
+      return {
+        preset: getImagePreset(perFile, policy.catalog),
+        reason: `set to ${perFile} for this file`
+      };
+    }
+    if (override) {
+      return { preset: override, reason: `forced with --preset ${override.name}` };
+    }
+    const matched = policy.assetFor(source);
+    const assetPreset = matched ? policy.catalog.image[matched.preset] : void 0;
+    if (matched && assetPreset) {
+      return {
+        preset: assetPreset,
+        reason: `set to ${matched.preset} by assets "${matched.pattern}"`,
+        confidence: "high"
+      };
+    }
+    const verdict = classify(source, analysis);
+    return {
+      preset: getImagePreset(verdict.preset, policy.catalog),
+      reason: verdict.reason,
+      confidence: verdict.confidence
+    };
+  };
+  if (!plan) {
+    const rasterFiles = sourceFiles.filter((f) => !videos.includes(f));
+    plan = await buildPlan({
+      files: rasterFiles,
+      projectRoot,
+      outDir,
+      ...options.staticRoot !== void 0 ? { staticRoot: options.staticRoot } : {},
+      ...options.publicPath ? { publicPath: options.publicPath } : {},
+      choosePreset,
+      engine,
+      analyze,
+      readSource: (path) => fs.readSource(path)
+    });
+    plan = await withVideos(plan, {
+      projectRoot,
+      staticRoot: options.staticRoot ?? ".",
+      videoFiles: videos,
+      videoEngine: options.videoEngine ?? null,
+      needsFfmpeg: options.needsFfmpeg ?? "install ffmpeg",
+      presetOverrides: options.presetOverrides,
+      policy,
+      cache: analysisCache
+    });
+  }
+  const finalPlan = plan;
+  const manifest = await readManifest(fs);
+  const outputHash = async (path) => {
+    const data = await fs.readOutput(path);
+    return data ? sha256(data) : null;
+  };
+  const cache = /* @__PURE__ */ new Map();
+  for (const item of finalPlan.items) {
+    if (item.skip) continue;
+    cache.set(item.source, await checkCache(item, manifest?.sources[item.source], outputHash));
+  }
+  const caps = options.videoEngine ? await options.videoEngine.capabilities() : null;
+  const missingCodecs = /* @__PURE__ */ new Set();
+  if (caps) {
+    if (!caps.libsvtav1 && !caps.libaomAv1) missingCodecs.add("av1");
+    if (!caps.libx264) missingCodecs.add("h264");
+  }
+  const notes = videoNotes(finalPlan, caps, options.needsFfmpeg);
+  for (const item of finalPlan.videos ?? []) {
+    if (item.skip) continue;
+    cache.set(
+      item.source,
+      await checkVideoCache(item, manifest?.videos[item.source], outputHash, missingCodecs)
+    );
+  }
+  const ffmpegVersion = videoVersions.ffmpeg;
+  const videoEncoders = {};
+  if (caps && ffmpegVersion) {
+    const av1 = caps.libsvtav1 ? "libsvtav1" : caps.libaomAv1 ? "libaom-av1" : null;
+    if (av1) videoEncoders.av1 = `${av1} (ffmpeg ${ffmpegVersion})`;
+    if (caps.libx264) videoEncoders.h264 = `libx264 (ffmpeg ${ffmpegVersion})`;
+  }
+  const audit = (current) => runProjectRules({
+    plan: finalPlan,
+    manifest: current,
+    videoEncoders,
+    unavailableCodecs: missingCodecs,
+    encoders: engine.encoders(),
+    outputHash,
+    sourceExists: async (source) => (await stat3(resolve5(projectRoot, ...source.split("/"))).catch(() => null))?.isFile() ?? false
+  });
+  if (!options.execute) {
+    return {
+      plan: finalPlan,
+      cache,
+      findings: await audit(manifest),
+      unsupported,
+      svgs,
+      videos,
+      notes
+    };
+  }
+  let selected = null;
+  const scorerNotes = [];
+  const makeScorer = options.makeScorer;
+  const quality = makeScorer ? {
+    async scorer() {
+      selected ??= makeScorer(fs).then((s) => {
+        scorerNotes.push(...s.notes);
+        return s;
+      });
+      return (await selected).scorer;
+    }
+  } : void 0;
+  const runAll = () => runPlan(finalPlan, {
+    projectRoot,
+    engine,
+    fs,
+    manifest,
+    ...quality ? { quality } : {},
+    ...options.force !== void 0 ? { force: options.force } : {},
+    ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {},
+    ...options.signal ? { signal: options.signal } : {},
+    ...options.onItemStart ? { onItemStart: options.onItemStart } : {},
+    ...options.onOutputDone ? { onOutputDone: options.onOutputDone } : {},
+    ...options.onItemDone ? { onItemDone: options.onItemDone } : {},
+    ...options.videoEngine ? {
+      video: {
+        engine: options.videoEngine,
+        ...options.videoConcurrency !== void 0 ? { concurrency: options.videoConcurrency } : {},
+        ...options.needsFfmpeg ? { needsFfmpeg: options.needsFfmpeg } : {}
+      }
+    } : {},
+    ...options.onVideoItemStart ? { onVideoItemStart: options.onVideoItemStart } : {},
+    ...options.onVideoProgress ? { onVideoProgress: options.onVideoProgress } : {},
+    ...options.onVideoOutputDone ? { onVideoOutputDone: options.onVideoOutputDone } : {},
+    ...options.onVideoItemDone ? { onVideoItemDone: options.onVideoItemDone } : {}
+  });
+  let result;
+  try {
+    result = await runAll();
+  } finally {
+    const started = selected ? await selected.catch(() => null) : null;
+    await started?.scorer.close();
+  }
+  result.warnings.push(...scorerNotes);
+  const updated = updateManifest(
+    manifest,
+    finalPlan,
+    result,
+    { bytecut: options.toolVersion, ...engine.versions() },
+    policy.catalog
+  );
+  const placeholdersChanged = await refreshPlaceholders(updated, finalPlan, {
+    kind: options.placeholder ?? "dominant-color",
+    engine,
+    readSource: (path) => fs.readSource(path),
+    readOutput: (path) => fs.readOutput(path),
+    projectRoot
+  });
+  const touched = placeholdersChanged || result.items.some((i) => i.status !== "skipped") || (result.videos ?? []).some((v) => v.status !== "skipped");
+  if (touched) {
+    const next = serializeManifest(updated);
+    const previous = manifest ? serializeManifest({ ...manifest, tools: updated.tools }) : null;
+    if (next !== previous) await fs.writeOutput(MANIFEST_FILE, Buffer.from(next));
+  }
+  await analysisCache.save(fs);
+  return {
+    plan: finalPlan,
+    cache,
+    findings: await audit(updated),
+    unsupported,
+    svgs,
+    videos,
+    notes,
+    result
+  };
+}
+async function readManifest(fs) {
+  const data = await fs.readOutput(MANIFEST_FILE);
+  return data ? parseManifest(data.toString("utf8")) : null;
+}
+function videoNotes(plan, caps, needsFfmpeg) {
+  const videos = plan.videos ?? [];
+  if (videos.length === 0) return [];
+  const notes = [];
+  if (!caps) {
+    notes.push(
+      `ffmpeg not found: ${videos.length} video file${videos.length === 1 ? "" : "s"} cannot be processed (${needsFfmpeg ?? "install ffmpeg"}). Images are unaffected.`
+    );
+    return notes;
+  }
+  if (!caps.libsvtav1 && !caps.libaomAv1) {
+    notes.push(
+      "No AV1 encoder (libsvtav1 / libaom-av1): AV1 outputs will be skipped; H.264 and posters are still produced."
+    );
+  } else if (!caps.libsvtav1) {
+    notes.push("libsvtav1 not found: AV1 will be encoded with libaom-av1, which is much slower.");
+  }
+  if (!caps.libx264) {
+    notes.push("libx264 not found: H.264 fallback outputs will be skipped.");
+  }
+  if (!caps.libvmaf) {
+    notes.push("libvmaf not available: using the preset's fixed quality (no VMAF search).");
+  }
+  return notes;
+}
+async function refreshPlaceholders(manifest, plan, deps) {
+  const { kind, engine } = deps;
+  if (kind !== "none" && !engine.placeholder) return false;
+  let changed = false;
+  for (const item of plan.items) {
+    const entry = manifest.sources[item.source];
+    if (!entry || item.skip || entry.sha256 !== item.sourceSha256) continue;
+    if (kind === "none") {
+      if (entry.placeholder) {
+        const { placeholder: _gone, ...rest } = entry;
+        void _gone;
+        manifest.sources[item.source] = rest;
+        changed = true;
+      }
+      continue;
+    }
+    if (entry.placeholder?.kind === kind) continue;
+    const data = await deps.readSource(resolve5(deps.projectRoot, ...item.source.split("/")));
+    manifest.sources[item.source] = {
+      ...entry,
+      placeholder: await engine.placeholder(data, kind)
+    };
+    changed = true;
+  }
+  for (const item of plan.videos ?? []) {
+    const entry = manifest.videos[item.source];
+    if (!entry || item.skip || entry.sha256 !== item.sourceSha256) continue;
+    if (kind === "none") {
+      if (entry.placeholder) {
+        const { placeholder: _gone, ...rest } = entry;
+        void _gone;
+        manifest.videos[item.source] = rest;
+        changed = true;
+      }
+      continue;
+    }
+    if (entry.placeholder?.kind === kind) continue;
+    const poster = entry.outputs.find((o) => o.role === "poster" && o.status === "written");
+    const data = poster ? await deps.readOutput(poster.path) : null;
+    if (!data) continue;
+    manifest.videos[item.source] = { ...entry, placeholder: await engine.placeholder(data, kind) };
+    changed = true;
+  }
+  return changed;
+}
+
+// src/cli/format.ts
+function formatPlan(plan, cache) {
+  const lines = [];
+  const active = plan.items.filter((i) => !i.skip);
+  const videos = plan.videos ?? [];
+  const activeVideos = videos.filter((v) => !v.skip);
+  const unchanged = [...active, ...activeVideos].filter(
+    (i) => cache?.get(i.source)?.kind === "hit"
+  ).length;
+  const note = unchanged > 0 ? ` (${unchanged} unchanged, will be skipped)` : "";
+  const what = activeVideos.length > 0 ? `${plural(active.length, "image")}, ${plural(activeVideos.length, "video")}` : plural(active.length, "image");
+  lines.push(`Plan: ${what} \u2192 ${plan.outDir}${note}`);
+  for (const item of plan.items) {
+    lines.push("");
+    const dims = `${formatBytes(item.sourceBytes)}, ${item.sourceWidth}x${item.sourceHeight}`;
+    const preset = item.skip ? "" : `, ${item.preset}${item.classification ? `: ${item.classification.reason}` : ""}`;
+    lines.push(`${item.source} (${dims}${preset})`);
+    if (item.skip) {
+      lines.push(`  skipped: ${item.skip.reason}`);
+      continue;
+    }
+    if (cache?.get(item.source)?.kind === "hit") {
+      lines.push("  unchanged: outputs are up to date");
+      continue;
+    }
+    for (const out of item.outputs) {
+      const mode = out.lossless ? "lossless" : out.search ? `ssimulacra2 >= ${out.search.target}${out.search.maxBytes !== void 0 ? `, <= ${formatBytes(out.search.maxBytes)}` : ""}` : `q${out.quality}`;
+      lines.push(`  ${out.path}  (${out.format}, ${out.width}w, ${mode})`);
+    }
+  }
+  for (const video of videos) {
+    lines.push("");
+    if (video.skip) {
+      lines.push(`${video.source} (${formatBytes(video.sourceBytes)})`);
+      lines.push(`  skipped: ${video.skip.reason}`);
+      continue;
+    }
+    const facts = [
+      formatBytes(video.sourceBytes),
+      `${video.sourceWidth}x${video.sourceHeight}`,
+      `${video.durationSec.toFixed(1)}s`,
+      `${Math.round(video.fps * 100) / 100}fps`,
+      video.hasAudio ? "audio" : "silent"
+    ].join(", ");
+    const why = video.classification ? `: ${video.classification.reason}` : "";
+    lines.push(`${video.source} (${facts}, ${video.preset}${why})`);
+    if (cache?.get(video.source)?.kind === "hit") {
+      lines.push("  unchanged: outputs are up to date");
+      continue;
+    }
+    for (const out of video.outputs) {
+      if (out.role === "video") {
+        const audio = out.audio === "strip" ? "no audio" : `audio ${out.audioBitrate}`;
+        const mode = out.search ? `${out.search.metric} >= ${out.search.target} (starts at crf ${out.crf})` : `crf ${out.crf}`;
+        lines.push(`  ${out.path}  (${out.codec}, ${out.width}w, ${mode}, ${audio})`);
+      } else {
+        lines.push(`  ${out.path}  (poster, ${out.width}w)`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function itemLabel(item) {
+  switch (item.status) {
+    case "skipped":
+      return `skipped: ${item.reason}`;
+    case "cached":
+      return "unchanged";
+    case "failed":
+      return `failed${item.reason ? `: ${item.reason}` : ""}`;
+    case "cancelled":
+      return "cancelled";
+    default:
+      return "";
+  }
+}
+function outputLine(out, sourceBytes) {
+  const head = `  ${out.format.padEnd(4)} ${String(out.width).padStart(5)}w`;
+  const size = formatBytes(out.bytes);
+  switch (out.status) {
+    case "written":
+      return `${head}  ${size.padStart(9)}  ${percentChange(sourceBytes, out.bytes)}${searchNote(out)}`;
+    case "unchanged":
+      return `${head}  ${size.padStart(9)}  ${percentChange(sourceBytes, out.bytes)}  (already on disk)${searchNote(out)}`;
+    case "already-optimal":
+      return `${head}  already optimal (${size} \u2265 source), not written`;
+    case "protected":
+      return `${head}  left alone: existing file not owned by bytecut (use --force)`;
+    case "unavailable":
+      return `${head}  skipped: encoder not available`;
+    case "failed":
+      return `${head}  failed: ${out.error}`;
+    case "unmet":
+      return `${head}  not written: ${out.error}`;
+    case "cancelled":
+      return `${head}  cancelled`;
+  }
+}
+function searchNote(out) {
+  if (out.score === void 0) return "";
+  const stepped = out.search?.plannedPath ? " \xB7 width stepped down" : "";
+  return `  \xB7 q${out.quality} \xB7 ssimulacra2 ${out.score.toFixed(1)}${stepped}`;
+}
+function videoSearchNote(out) {
+  if (!out.search || out.score === void 0 || out.crf === void 0) return "";
+  return `  \xB7 crf ${out.crf} \xB7 ${out.search.metric} ${out.score.toFixed(1)}`;
+}
+function videoOutputLine(out, sourceBytes) {
+  const label = out.role === "poster" ? "poster" : out.codec ?? "mp4";
+  const head = `  ${label.padEnd(6)} ${String(out.width).padStart(5)}w`;
+  const size = formatBytes(out.bytes);
+  switch (out.status) {
+    case "written":
+      return out.role === "poster" ? `${head}  ${size.padStart(9)}` : `${head}  ${size.padStart(9)}  ${percentChange(sourceBytes, out.bytes)}${videoSearchNote(out)}`;
+    case "unchanged":
+      return `${head}  ${size.padStart(9)}  (already on disk)${videoSearchNote(out)}`;
+    case "already-optimal":
+      return `${head}  already optimal (${size} \u2265 source), not written`;
+    case "protected":
+      return `${head}  left alone: existing file not owned by bytecut (use --force)`;
+    case "unavailable":
+      return `${head}  skipped: ${out.codec === "av1" ? "no AV1 encoder installed" : "encoder not available"}`;
+    case "failed":
+      return `${head}  failed: ${out.error}`;
+    case "unmet":
+      return `${head}  not written: ${out.error}`;
+    case "cancelled":
+      return `${head}  cancelled`;
+  }
+}
+function videoItemLabel(item) {
+  switch (item.status) {
+    case "skipped":
+      return `skipped: ${item.reason}`;
+    case "cached":
+      return "unchanged";
+    case "failed":
+      return `failed${item.reason ? `: ${item.reason}` : ""}`;
+    case "cancelled":
+      return "cancelled";
+    default:
+      return `${item.preset}`;
+  }
+}
+function servedVideoBytes(item) {
+  const usable = item.outputs.filter(
+    (o) => o.role === "video" && (o.status === "written" || o.status === "unchanged")
+  );
+  if (usable.length === 0) return null;
+  return Math.min(item.sourceBytes, ...usable.map((o) => o.bytes));
+}
+function servedBytes(item) {
+  const usable = item.outputs.filter((o) => o.status === "written" || o.status === "unchanged");
+  if (usable.length === 0) return null;
+  const widest = Math.max(...usable.map((o) => o.width));
+  const best = Math.min(...usable.filter((o) => o.width === widest).map((o) => o.bytes));
+  return Math.min(best, item.sourceBytes);
+}
+function formatSummary(result) {
+  const lines = [];
+  let written = 0;
+  let writtenBytes = 0;
+  let unchangedItems = 0;
+  let servedSource = 0;
+  let served = 0;
+  for (const item of result.items) {
+    if (item.status === "cached") unchangedItems++;
+    lines.push(`${item.source}  ${formatBytes(item.sourceBytes)}  ${itemLabel(item)}`.trimEnd());
+    if (item.status !== "cached") {
+      for (const out of item.outputs) {
+        lines.push(outputLine(out, item.sourceBytes));
+        if (out.status === "written") {
+          written++;
+          writtenBytes += out.bytes;
+        }
+      }
+    }
+    const bytes = servedBytes(item);
+    if (bytes !== null) {
+      servedSource += item.sourceBytes;
+      served += bytes;
+    }
+  }
+  for (const item of result.videos ?? []) {
+    if (item.status === "cached") unchangedItems++;
+    lines.push(
+      `${item.source}  ${formatBytes(item.sourceBytes)}  ${videoItemLabel(item)}`.trimEnd()
+    );
+    if (item.status !== "cached") {
+      for (const out of item.outputs) {
+        lines.push(videoOutputLine(out, item.sourceBytes));
+        if (out.status === "written") {
+          written++;
+          writtenBytes += out.bytes;
+        }
+      }
+    }
+    const bytes = servedVideoBytes(item);
+    if (bytes !== null) {
+      servedSource += item.sourceBytes;
+      served += bytes;
+    }
+  }
+  lines.push("");
+  const parts = [`${plural(written, "file")} written`];
+  if (written > 0) parts[0] += ` (${formatBytes(writtenBytes)} across all widths)`;
+  if (unchangedItems > 0) parts.push(`${plural(unchangedItems, "image")} unchanged`);
+  lines.push(`Total: ${parts.join(", ")}`);
+  if (servedSource > 0) {
+    lines.push(
+      `Largest size per image: ${formatBytes(servedSource)} \u2192 ${formatBytes(served)} (${percentChange(servedSource, served)})`
+    );
+  }
+  if (result.cancelled) lines.push("Cancelled: no partial files were left behind.");
+  return lines.join("\n");
+}
+function formatFindings(findings) {
+  if (findings.length === 0) return "";
+  const lines = ["Project:"];
+  for (const f of findings) {
+    const where = f.path ? `${f.source ?? ""} \u2192 ${f.path}` : f.source ?? "";
+    lines.push(`  ${f.severity.padEnd(5)} ${f.ruleId}  ${where}: ${f.message}`);
+  }
+  return lines.join("\n");
+}
+var SEVERITY_ORDER = { error: 0, warn: 1, info: 2 };
+function formatAuditReport(report, options = {}) {
+  const limit = options.all ? Infinity : options.perRule ?? 10;
+  const groups = /* @__PURE__ */ new Map();
+  for (const f of report.findings) groups.set(f.ruleId, [...groups.get(f.ruleId) ?? [], f]);
+  const ordered = [...groups.entries()].sort(([ida, a], [idb, b]) => {
+    const sa = SEVERITY_ORDER[a[0].severity] ?? 9;
+    const sb = SEVERITY_ORDER[b[0].severity] ?? 9;
+    return sa - sb || (ida < idb ? -1 : 1);
+  });
+  const lines = [];
+  for (const [ruleId, findings] of ordered) {
+    const saved = findings.reduce((sum, f) => sum + (f.savingsBytes ?? 0), 0);
+    const head = `${ruleId}  ${findings[0].severity}  ${plural(findings.length, "file")}`;
+    lines.push(saved > 0 ? `${head} \xB7 est. save ${formatBytes(saved)}` : head);
+    for (const f of findings.slice(0, limit)) {
+      const where = f.path ? `${f.source} \u2192 ${f.path}` : f.source ?? "(project)";
+      const size = f.current !== void 0 && f.estimated !== void 0 ? `${formatBytes(f.current)} \u2192 ~${formatBytes(f.estimated)} (${percentChange(f.current, f.estimated)})` : f.current !== void 0 ? formatBytes(f.current) : "";
+      lines.push(`  ${where}${size ? `  ${size}` : ""}`);
+      lines.push(`    ${f.message}`);
+    }
+    if (findings.length > limit) {
+      lines.push(`  \u2026 and ${findings.length - limit} more (use --all)`);
+    }
+    lines.push("");
+  }
+  const { counts, totals } = report;
+  const assets = [
+    plural(counts.images + counts.skipped, "image"),
+    plural(counts.svgs, "SVG"),
+    plural(counts.videos, "video")
+  ].join(", ");
+  if (report.unprobed.length > 0) {
+    lines.push("Needs ffmpeg (not analysed):");
+    for (const u of report.unprobed.slice(0, 10)) {
+      lines.push(`  ${u.source}  ${formatBytes(u.bytes)}`);
+    }
+    if (report.unprobed.length > 10) lines.push(`  \u2026 and ${report.unprobed.length - 10} more`);
+    lines.push("");
+  }
+  lines.push(`Scanned ${assets} (${formatBytes(totals.sourceBytes)} of media).`);
+  const by = (s) => report.findings.filter((f) => f.severity === s).length;
+  lines.push(
+    `${plural(report.findings.length, "finding")}: ${plural(by("error"), "error")}, ${plural(by("warn"), "warning")}, ${by("info")} info.`
+  );
+  if (totals.optimizedImages > 0) {
+    lines.push(`${plural(totals.optimizedImages, "image")} already optimized.`);
+  }
+  if (totals.potentialSavingsBytes > 0) {
+    lines.push(
+      `Estimated savings from optimizing: ~${formatBytes(totals.potentialSavingsBytes)} of ${formatBytes(totals.sourceBytes)} (${percentChange(totals.sourceBytes, totals.sourceBytes - totals.potentialSavingsBytes)}). Run \`bytecut optimize -y\` to apply.`
+    );
+  }
+  for (const note of report.notes) lines.push(`Note: ${note}`);
+  return lines.join("\n");
+}
+
+export {
+  sortFindings,
+  AnalysisCache,
+  walkFiles,
+  collectAssets,
+  withVideos,
+  engineFingerprint,
+  optimize,
+  formatPlan,
+  formatSummary,
+  formatFindings,
+  formatAuditReport
+};