imgtune 0.1.0 → 0.3.0

package/dist/media-file.js

@@ -0,0 +1,284 @@
+// Single-file media for `imgtune image`: an animated GIF, animated WebP or APNG, or a video (MP4, MOV, WebM), read from a
+// local file. Two modes. Without a reference, an animated file gets the candidates of the three animated codecs (animated
+// AVIF, animated WebP and AV1 MP4) at a width, each the lowest-bytes quality that meets the bars. With a reference, a
+// candidate (a re-encode an agent made) is compared with the original at a width, and passes or fails the same bars.
+// Both measure from 2-second samples, so every byte figure is an estimate. The files are read, never written, except the
+// lossless copy of an animated WebP (ffmpeg cannot read one) in a scratch folder the caller removes.
+import { join } from "node:path";
+import { animationOf } from "./animated.js";
+import { prepareMedia } from "./media-prepare.js";
+import { compareToReference, cutSamples, effectiveStillBar, searchQuality, } from "./media-encode.js";
+import { reasonText } from "./media-model.js";
+import { pixelSize, safeText } from "./remote.js";
+import { IMGTUNE_VERSION } from "./version.js";
+/** The animated codecs a single animated file is searched for, in report order. */
+export const ANIMATED_CODECS = ["animated-avif", "animated-webp", "av1-mp4"];
+/** Time one codec's search may take, in ms. */
+export const CODEC_BUDGET_MS = 180_000;
+/** Time a reference check may take, in ms. */
+export const REFERENCE_BUDGET_MS = 300_000;
+/** A candidate may end this much before the reference and still be compared (encoders trim a fraction of a second). */
+const LENGTH_TOLERANCE_S = 0.5;
+/** The note printed when ffmpeg is missing: the bytes are still measured, the encodes are not made. */
+export const NO_FFMPEG_NOTE = "ffmpeg is not on PATH: the candidates and the reference check need it (ffmpeg enables the full hints)";
+/** Brands of an ISO box file that are still images (AVIF, HEIC), not video. */
+const STILL_BRANDS = new Set(["avif", "avis", "heic", "heix", "heim", "heis", "mif1", "msf1"]);
+export { prepareMedia };
+/** Whether an MP4, MOV or WebM (or Matroska) file: an ISO box file with a video brand, or an EBML header. */
+export function isVideoContainer(buffer) {
+    if (buffer.length >= 12 && buffer.toString("latin1", 4, 8) === "ftyp")
+        return !STILL_BRANDS.has(buffer.toString("latin1", 8, 12));
+    return buffer.length >= 4 && buffer[0] === 0x1a && buffer[1] === 0x45 && buffer[2] === 0xdf && buffer[3] === 0xa3;
+}
+/** The kind of media a file is, from its bytes: animated (GIF, WebP, APNG with more than one frame), video, or undefined. */
+export function mediaKindOf(buffer) {
+    if (animationOf(buffer))
+        return "animated";
+    if (isVideoContainer(buffer))
+        return "video";
+    return undefined;
+}
+const base = (label, kind) => ({ label, evidence: "media-file", imgtuneVersion: IMGTUNE_VERSION, kind });
+/** The current size of a file: its bytes, its pixel size from the header, and the animation's length and frames. */
+async function currentOf(buffer, format, animation, probe) {
+    const size = probe ? { width: probe.width, height: probe.height } : await pixelSize(buffer);
+    const current = { format, width: size?.width ?? 0, height: size?.height ?? 0, bytes: buffer.length };
+    if (animation) {
+        current.seconds = animation.durationMs / 1000;
+        current.frames = animation.frames;
+    }
+    else if (probe && probe.durationS > 0)
+        current.seconds = probe.durationS;
+    return current;
+}
+/** The formats a file's probe or animation names, for the report. */
+function formatOf(animation, probe) {
+    return probe?.videoCodec ?? animation?.format ?? "?";
+}
+/**
+ * One animated file without a reference: the candidates of each animated codec at `width` (the file's own width when not
+ * given), each the lowest-bytes quality that meets the bars. Never throws: a failure is the result's error.
+ */
+export async function measureAnimated(input, width, ctx, dir) {
+    const animation = animationOf(input.buffer);
+    const bars = { vmaf: ctx.videoBar, stillRequested: ctx.videoStillBar };
+    const current = await currentOf(input.buffer, formatOf(animation, undefined), animation);
+    const widthOf = (px) => ({ source: width === undefined ? "file" : "user", px });
+    const result = (extra) => ({
+        ...base(input.label, "animated"),
+        current,
+        width: widthOf(width ?? current.width),
+        bars,
+        candidates: [],
+        ...extra,
+    });
+    if (!ctx.caps.ffmpeg)
+        return result({ note: NO_FFMPEG_NOTE });
+    try {
+        const prepared = await prepareMedia(input.path, input.buffer, join(dir, "prepared"), undefined, ctx.signal);
+        current.format = formatOf(animation, prepared.probe);
+        current.width = prepared.probe.width;
+        current.height = prepared.probe.height;
+        const px = width ?? prepared.probe.width;
+        const samples = await cutSamples(prepared.source, prepared.probe, join(dir, "samples"), Date.now() + CODEC_BUDGET_MS, undefined, ctx.signal);
+        const candidates = [];
+        for (const codec of ANIMATED_CODECS) {
+            const outcome = await searchQuality(samples, prepared.probe, codec, px, {
+                vmafBar: ctx.videoBar,
+                stillBar: ctx.videoStillBar,
+                deadline: Date.now() + CODEC_BUDGET_MS,
+                caps: ctx.caps,
+                gpu: ctx.gpu,
+                score: ctx.score,
+                workDir: join(dir, codec),
+                signal: ctx.signal,
+            });
+            candidates.push({ codec, outcome });
+        }
+        return result({ width: widthOf(px), candidates });
+    }
+    catch (err) {
+        return result({ error: err.message });
+    }
+}
+/** One video file without a reference: its size and length, and what to do with it. */
+export async function describeVideo(input, ctx, dir) {
+    const note = "a video: give --reference <original> to check a re-encode of it against the bars";
+    if (!ctx.caps.ffmpeg)
+        return { ...base(input.label, "video"), current: await currentOf(input.buffer, "video"), note: NO_FFMPEG_NOTE };
+    try {
+        const prepared = await prepareMedia(input.path, input.buffer, join(dir, "prepared"), undefined, ctx.signal);
+        return { ...base(input.label, "video"), current: await currentOf(input.buffer, formatOf(undefined, prepared.probe), undefined, prepared.probe), note };
+    }
+    catch (err) {
+        return { ...base(input.label, "video"), current: await currentOf(input.buffer, "video"), error: err.message };
+    }
+}
+/**
+ * The codec a candidate is judged in: its own (animated WebP, H.264 or AV1), so its still ceiling is the best its codec can
+ * reach. Any other format is judged against AV1, as the search does.
+ */
+export function candidateCodecOf(cand) {
+    if (cand.animation?.format === "webp")
+        return "animated-webp";
+    if (cand.probe.videoCodec === "h264")
+        return "h264-mp4";
+    return "av1-mp4";
+}
+/**
+ * A candidate compared with its reference at `width` (the candidate's own width when not given). The still bar is made
+ * relative to the reference's ceiling (its own AV1 CRF 20 encode's still guard) as the search does; without an AV1 encoder
+ * the bar stays absolute. Never throws: a failure is the result's error, and the verdict is a fail.
+ */
+export async function compareReferenceFile(candidate, reference, width, ctx, dir) {
+    const requested = ctx.videoStillBar;
+    const fail = (error, extra = {}) => ({
+        label: candidate.label,
+        evidence: "media-reference",
+        imgtuneVersion: IMGTUNE_VERSION,
+        current: { format: "?", width: 0, height: 0, bytes: candidate.buffer.length },
+        reference: { label: reference.label, width: 0, height: 0, seconds: 0 },
+        width: width ?? 0,
+        vmaf: 0,
+        vmafBar: ctx.videoBar,
+        still: 0,
+        stillBar: requested,
+        stillBarRequested: requested,
+        samples: 0,
+        pass: false,
+        error,
+        ...extra,
+    });
+    try {
+        const cand = await prepareMedia(candidate.path, candidate.buffer, join(dir, "candidate"), undefined, ctx.signal);
+        const ref = await prepareMedia(reference.path, reference.buffer, join(dir, "reference"), undefined, ctx.signal);
+        // The samples are cut at the reference's moments, so a candidate that ends before the reference cannot be compared.
+        if (cand.probe.durationS + LENGTH_TOLERANCE_S < ref.probe.durationS) {
+            return fail(`the candidate is ${cand.probe.durationS.toFixed(1)} s but the reference is ${ref.probe.durationS.toFixed(1)} s: give a candidate of the same length (the samples are cut at the same moments)`);
+        }
+        const px = width ?? cand.probe.width;
+        const score = await compareToReference(cand.source, ref.source, ref.probe, px, {
+            vmafBar: ctx.videoBar,
+            stillBar: requested,
+            deadline: Date.now() + REFERENCE_BUDGET_MS,
+            caps: ctx.caps,
+            gpu: ctx.gpu,
+            score: ctx.score,
+            workDir: join(dir, "compare"),
+            signal: ctx.signal,
+        }, candidateCodecOf(cand));
+        const stillBar = score.ceiling === undefined ? requested : effectiveStillBar(requested, score.ceiling);
+        const current = await currentOf(candidate.buffer, formatOf(cand.animation, cand.probe), cand.animation, cand.probe);
+        return {
+            label: candidate.label,
+            evidence: "media-reference",
+            imgtuneVersion: IMGTUNE_VERSION,
+            current,
+            reference: { label: reference.label, width: ref.probe.width, height: ref.probe.height, seconds: ref.probe.durationS },
+            width: px,
+            vmaf: score.vmaf,
+            vmafBar: ctx.videoBar,
+            still: score.still,
+            stillBar,
+            stillBarRequested: requested,
+            ...(score.ceiling !== undefined ? { ceiling: score.ceiling } : {}),
+            ...(score.ceilingCodec !== undefined ? { ceilingCodec: score.ceilingCodec } : {}),
+            samples: score.samples,
+            pass: score.vmaf >= ctx.videoBar && score.still >= stillBar,
+        };
+    }
+    catch (err) {
+        return fail(err.message);
+    }
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// Text
+// ---------------------------------------------------------------------------------------------------------------------
+const kb = (bytes) => `${(bytes / 1024).toFixed(0)} KB`;
+/** How a candidate's quality reads: a CRF for AV1 and AVIF, a q for WebP. */
+function qualityText(codec, quality) {
+    return codec === "animated-webp" ? `q ${quality}` : `CRF ${quality}`;
+}
+/** The text of one candidate line: its quality, width, estimated bytes and scores against the bars. */
+function candidateLine(codec, best) {
+    return `  ${codec.padEnd(14)} ${qualityText(codec, best.quality)} at ${best.width} px: ${kb(best.bytes)} est. (VMAF ${best.vmaf.toFixed(1)} bar ${best.vmafBar}, still p10 ${best.still.toFixed(1)} bar ${best.stillBar.toFixed(1)})`;
+}
+/** The text of one animated file: its size, the bars, one line per codec, and the best saving. */
+export function renderAnimated(result) {
+    const label = safeText(result.label);
+    const c = result.current;
+    const span = c.seconds !== undefined ? `, ${c.seconds.toFixed(1)} s${c.frames !== undefined ? `, ${c.frames} frames` : ""}` : "";
+    const head = `${label}  ${safeText(c.format)} ${c.width}x${c.height}  ${kb(c.bytes)} now  animated${span}`;
+    if (result.error)
+        return `${head}\n  ${safeText(result.error)}\n`;
+    const lines = [head];
+    const widthNote = result.width.source === "user" ? "from --width" : "the file's own width; --width sets another";
+    lines.push(`  width ${result.width.px} px (${widthNote})`);
+    // The note only when a candidate's still bar was lowered below the requested one (its own ceiling is low).
+    const lowered = result.candidates.some(({ outcome }) => outcome.ok && outcome.best.stillBar < result.bars.stillRequested);
+    lines.push(`  bars VMAF ${result.bars.vmaf}, still p10 ${result.bars.stillRequested}${lowered ? " (lowered for a source whose own best encode scores low)" : ""}`);
+    if (result.note)
+        lines.push(`  ${safeText(result.note)}`);
+    let best;
+    for (const { codec, outcome } of result.candidates) {
+        if (outcome.ok) {
+            lines.push(candidateLine(codec, outcome.best));
+            if (best === undefined || outcome.best.bytes < best.bytes)
+                best = { codec, bytes: outcome.best.bytes };
+        }
+        else {
+            const why = reasonText(outcome.reason);
+            lines.push(`  ${codec.padEnd(14)} no quality meets the bars (${why})`);
+        }
+    }
+    if (best) {
+        const saves = c.bytes - best.bytes;
+        lines.push(`  best ${best.codec} ${kb(best.bytes)} est.${saves >= 0 ? ` (saves ${kb(saves)} est.)` : ""}`);
+    }
+    if (result.candidates.length > 0)
+        lines.push("  estimates from 2 s samples; the full length is not encoded");
+    return `${lines.join("\n")}\n`;
+}
+/** How each codec's best-quality ceiling is named in a report. */
+const CEILING_NAME = {
+    "av1-mp4": "AV1 CRF 20",
+    "animated-avif": "AVIF CRF 20",
+    "h264-mp4": "H.264 CRF 18",
+    "animated-webp": "WebP q 90",
+};
+/** The text of one video file without a reference. */
+export function renderVideo(result) {
+    const c = result.current;
+    const span = c.seconds !== undefined ? `, ${c.seconds.toFixed(1)} s` : "";
+    const lines = [`${safeText(result.label)}  ${safeText(c.format)} ${c.width}x${c.height}  ${kb(c.bytes)} now  video${span}`];
+    if (result.error)
+        lines.push(`  ${safeText(result.error)}`);
+    if (result.note)
+        lines.push(`  ${safeText(result.note)}`);
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * The text of a reference check: the candidate's size, the reference, and the verdict line
+ * `VMAF <v> (bar <b>) still p10 <s> (bar <sb>): pass|fail`. The still bar line says when the bar was lowered.
+ */
+export function renderReference(result) {
+    const c = result.current;
+    const head = `${safeText(result.label)}  ${safeText(c.format)} ${c.width}x${c.height}  ${kb(c.bytes)} now`;
+    if (result.error)
+        return `${head}\n  ${safeText(result.error)}\n`;
+    const lines = [head];
+    const ref = result.reference;
+    lines.push(`  reference ${safeText(ref.label)} (${ref.width}x${ref.height}, ${ref.seconds.toFixed(1)} s); compared at ${result.width} px`);
+    if (result.ceiling === undefined)
+        lines.push("  still bar is absolute: no AV1 encoder, so the reference's own ceiling is not measured");
+    else {
+        if (result.stillBar < result.stillBarRequested) {
+            lines.push(`  still bar lowered from ${result.stillBarRequested} to ${result.stillBar.toFixed(1)}: the reference's own best encode scores ${result.ceiling.toFixed(1)}`);
+        }
+        // The ceiling is the reference's best encode in the candidate's codec (AV1 when that codec has no encoder), named here.
+        lines.push(`  still bar ceiling: the reference's best ${CEILING_NAME[result.ceilingCodec ?? "av1-mp4"]} encode (candidate ${safeText(c.format)})`);
+    }
+    const verdict = `VMAF ${result.vmaf.toFixed(1)} (bar ${result.vmafBar}) still p10 ${result.still.toFixed(1)} (bar ${result.stillBar.toFixed(1)}): ${result.pass ? "pass" : "fail"}`;
+    lines.push(verdict);
+    return `${lines.join("\n")}\n`;
+}

package/dist/media-limits.js

@@ -0,0 +1,31 @@
+// The size limits of the media pipeline, and the errors a refused input raises. Kept apart from media-encode.ts so the
+// WebP reader (webp-animation.ts) can use them without importing the encoder.
+/**
+ * The most pixels a frame may have before ffmpeg or the decoder is asked to read it (8K is about 33 Mpx): above this the input
+ * is refused before any decode or encode, since ffmpeg would allocate frames of several GB. Reported as "too-large".
+ */
+export const MAX_INPUT_PIXELS_FFMPEG = 40_000_000;
+/** The most frames one 2-second sample window may hold (a sanity cap: at 30 fps a window is 60 frames). */
+export const MAX_WINDOW_FRAMES = 2000;
+/** A frame over the pixel limit: refused before any decode or encode. Its message starts "too large to score". */
+export class PixelsTooLarge extends Error {
+    width;
+    height;
+    constructor(width, height, limit = MAX_INPUT_PIXELS_FFMPEG) {
+        super(`too large to score: a frame of ${width}x${height} has ${(width * height / 1_000_000).toFixed(1)} Mpx, above the ${limit / 1_000_000} Mpx limit`);
+        this.name = "PixelsTooLarge";
+        this.width = width;
+        this.height = height;
+    }
+}
+/** A sample window with more frames than MAX_WINDOW_FRAMES. Its message starts "too large to score". */
+export class WindowTooLarge extends Error {
+    constructor(frames) {
+        super(`too large to score: a 2 s sample window holds ${frames} frames (the cap is ${MAX_WINDOW_FRAMES})`);
+        this.name = "WindowTooLarge";
+    }
+}
+/** True for the refusals above: the input is too large to score, so the search reports "too-large". */
+export function isTooLarge(err) {
+    return err instanceof PixelsTooLarge || err instanceof WindowTooLarge;
+}

package/dist/media-model.js

@@ -0,0 +1,251 @@
+/**
+ * Pure rules for animated media and `<video>`: which widths to encode at, how many bytes a view or a play costs,
+ * which target to recommend for a GIF, how to split a saving across levers, how to sample a clip, and which assets
+ * fit the encode budget. No I/O and no ffmpeg here, so every rule can be tested without a browser or an encoder.
+ */
+/**
+ * How a not-encoded reason code reads in a report. Codes that a report prints as words (the agent reads them): a code with
+ * no entry passes through unchanged, as it is already a sentence (for example "ffmpeg not found").
+ */
+const REASON_TEXT = {
+    "time-limit": "time limit reached",
+    "no-passing-quality": "no setting passed the quality bar",
+    "too-large": "too large to score",
+    "no-encoder": "ffmpeg has no encoder for this codec",
+    "no-vmaf": "ffmpeg has no libvmaf",
+    "no-ffmpeg": "ffmpeg not found",
+    "probe-failed": "ffprobe could not read the file",
+    "score-failed": "the quality scorer failed",
+    aborted: "aborted",
+    "never-shown": "never shown on load",
+};
+/** The text of a not-encoded reason (see REASON_TEXT). */
+export function reasonText(reason) {
+    return REASON_TEXT[reason] ?? reason;
+}
+/** Widths a video rendition can be snapped to. Few buckets keep the encode count and the cache keys small. */
+export const WIDTH_BUCKETS = [320, 480, 640, 720, 854, 960, 1080, 1280, 1440, 1920, 2560, 3840];
+/**
+ * Snaps a needed pixel width to the smallest bucket at or above it, never above the source width. A need the source
+ * cannot reach returns the source width, since encoding wider than the source adds bytes and no detail.
+ */
+export function snapWidth(need, sourceWidth) {
+    if (need >= sourceWidth)
+        return sourceWidth;
+    const bucket = WIDTH_BUCKETS.find((b) => b >= need);
+    return bucket === undefined ? sourceWidth : Math.min(bucket, sourceWidth);
+}
+/**
+ * Applies the per-view rules. A video that is not visible (0×0 or `display:none`) costs nothing per view, because the
+ * browser does not fetch it for the page. Autoplay fetches the whole file once it plays, so it counts the full file;
+ * before that it counts what the scan saw. preload="auto" and the default fetch whatever the browser chooses, so they
+ * count the observed bytes. metadata and none fetch no media on load.
+ */
+export function videoBytes(input) {
+    const perPlay = input.fullBytes;
+    const bounded = (view) => ({ ...view, perView: Math.min(view.perView, perPlay) });
+    if (!input.visible)
+        return { perView: 0, perPlay, perViewBasis: "none", browserDependent: false };
+    switch (input.kind) {
+        case "autoplay":
+            return input.playing
+                ? bounded({ perView: input.fullBytes, perPlay, perViewBasis: "full-file", browserDependent: false })
+                : bounded({ perView: input.observedBytes, perPlay, perViewBasis: "observed", browserDependent: false });
+        case "auto":
+            return bounded({ perView: input.observedBytes, perPlay, perViewBasis: "observed", browserDependent: true });
+        case "default":
+            return bounded({ perView: input.observedBytes, perPlay, perViewBasis: "observed", browserDependent: false });
+        case "metadata":
+        case "none":
+            return { perView: 0, perPlay, perViewBasis: "none", browserDependent: false };
+    }
+}
+/**
+ * The bytes of a video once its full file length is known (from a Range probe): the per-play figure is the length, and the
+ * per-view figure is the length when the view counts the full file (autoplay), else the observed bytes, never above the
+ * length. Keeps perView ≤ perPlay.
+ */
+export function withFileLength(bytes, length) {
+    return {
+        ...bytes,
+        perPlay: length,
+        perView: Math.min(bytes.perViewBasis === "full-file" ? length : bytes.perView, length),
+    };
+}
+/** Ignores floating-point noise such as 1080.0000000002 before taking the ceiling. */
+function pixelNeed(boxWidth, dpr) {
+    return Math.ceil(boxWidth * dpr - 1e-9);
+}
+/** True when a larger viewport never gets a smaller box, so the widths can be picked by viewport. */
+function isMonotonic(needs) {
+    for (const a of needs) {
+        for (const b of needs) {
+            if (a.viewportWidth < b.viewportWidth && a.boxWidth > b.boxWidth)
+                return false;
+        }
+    }
+    return true;
+}
+/** The contiguous ranges [first, last] (inclusive indexes) that a list of cut positions makes. */
+function rangesFrom(count, cuts) {
+    const ranges = [];
+    let start = 0;
+    for (const cut of cuts) {
+        ranges.push([start, cut]);
+        start = cut + 1;
+    }
+    ranges.push([start, count - 1]);
+    return ranges;
+}
+/**
+ * Picks at most `max` widths for a video so that the browser serves each viewport a width that covers its need.
+ *
+ * The browser chooses a `<source>` by CSS viewport width, not by DPR, so the plan is built the same way. The viewports
+ * are sorted by CSS width (ties keep input order) and cut into at most `max` contiguous ranges. A cut is allowed only
+ * where the CSS width grows, because two viewports of one width always get the same source. Each range gets the
+ * largest snapped need in it, so every viewport in the range is covered. Every set of cuts is tried (at most six
+ * viewports, so brute force is cheap). The set with the smallest sum of per-viewport widths wins; ties go to fewer
+ * ranges, then to the smaller sum of distinct widths. Adjacent ranges that end at the same width are merged.
+ *
+ * `sources` is the `<source>` list in browser order: the largest range first, each with `(min-width: N)` where N is the
+ * CSS width of the range's first viewport, and the first range as the final source with no media. The browser takes
+ * the first source whose media matches the viewport, so it serves each viewport exactly `perViewport[i].width`.
+ */
+export function clusterVideoWidths(needs, max, sourceWidth) {
+    const containerDriven = !isMonotonic(needs);
+    if (needs.length === 0)
+        return { widths: [], perViewport: [], sources: [], conditions: [], containerDriven };
+    const snapped = needs.map((n, order) => ({ ...n, order, need: snapWidth(pixelNeed(n.boxWidth, n.dpr), sourceWidth) }));
+    const byCssWidth = [...snapped].sort((a, b) => a.viewportWidth - b.viewportWidth || a.order - b.order);
+    const count = byCssWidth.length;
+    const cuts = [];
+    for (let j = 0; j < count - 1; j++) {
+        if (byCssWidth[j].viewportWidth < byCssWidth[j + 1].viewportWidth)
+            cuts.push(j);
+    }
+    const limit = Math.max(1, Math.floor(max));
+    let best;
+    for (let mask = 0; mask < 1 << cuts.length; mask++) {
+        const picked = cuts.filter((_, i) => (mask >> i) & 1);
+        if (picked.length + 1 > limit)
+            continue;
+        const ranges = rangesFrom(count, picked);
+        const widths = ranges.map(([first, last]) => Math.max(...byCssWidth.slice(first, last + 1).map((s) => s.need)));
+        let cost = 0;
+        ranges.forEach(([first, last], i) => {
+            cost += widths[i] * (last - first + 1);
+        });
+        const distinctSum = [...new Set(widths)].reduce((acc, w) => acc + w, 0);
+        if (!best ||
+            cost < best.cost ||
+            (cost === best.cost &&
+                (ranges.length < best.ranges.length || (ranges.length === best.ranges.length && distinctSum < best.distinctSum)))) {
+            best = { ranges, widths, cost, distinctSum };
+        }
+    }
+    const merged = [];
+    best.ranges.forEach(([first, last], i) => {
+        const width = best.widths[i];
+        const previous = merged[merged.length - 1];
+        if (previous && previous.width === width)
+            previous.last = last;
+        else
+            merged.push({ first, last, width });
+    });
+    const sources = [];
+    for (let i = merged.length - 1; i >= 0; i--) {
+        const range = merged[i];
+        sources.push({
+            width: range.width,
+            media: i === 0 ? undefined : `(min-width: ${byCssWidth[range.first].viewportWidth}px)`,
+        });
+    }
+    const widthByOrder = new Array(count);
+    for (const range of merged) {
+        for (let k = range.first; k <= range.last; k++)
+            widthByOrder[byCssWidth[k].order] = range.width;
+    }
+    const perViewport = snapped.map((s) => ({ viewport: s.viewport, need: s.need, width: widthByOrder[s.order] }));
+    const widths = [...new Set(merged.map((r) => r.width))].sort((a, b) => a - b);
+    const conditions = sources.flatMap((s) => (s.media === undefined ? [] : [s.media]));
+    return { widths, perViewport, sources, conditions, containerDriven };
+}
+/**
+ * The plans for `max` = 1, 2 and 3, for `audit`, which reports the bytes per view at each count and leaves the pick
+ * to the agent.
+ */
+export function widthOptions(needs, sourceWidth) {
+    return [1, 2, 3].map((max) => clusterVideoWidths(needs, max, sourceWidth));
+}
+/** A GIF bigger than this is recommended as `<video>`; a smaller one as an animated AVIF/WebP image. */
+export const GIF_VIDEO_THRESHOLD = 1_000_000;
+/**
+ * Chooses the target for an animated GIF by where it is used. A CSS background cannot use `<video>` in a way that keeps
+ * the same markup, so it gets animated AVIF or WebP only. A small `<img>` GIF only changes `src`. A big `<img>` GIF
+ * is best as `<video autoplay muted loop playsinline>`, with the animated image kept as an alternative.
+ */
+export function animatedTarget(context, avifBytes) {
+    if (context === "css-background")
+        return { main: "animated-image", alternatives: ["animated-avif", "animated-webp"] };
+    if (avifBytes === undefined || avifBytes <= GIF_VIDEO_THRESHOLD) {
+        return { main: "animated-image", alternatives: ["animated-avif", "animated-webp", "video"] };
+    }
+    return { main: "video", alternatives: ["animated-avif", "animated-webp"] };
+}
+/**
+ * Splits the saving of a re-encode into levers, so that nothing is double-counted. The stages are first made
+ * non-increasing (a stage that grows the file is held at the level before it), so every step is at least zero and
+ * the four steps sum to start − the lowest stage. When the last stage is the lowest, that is start − final. If the
+ * last stage grows the file, the sum is start − recoded: a growing stage cannot carry a negative lever.
+ */
+export function attributeLevers(chain) {
+    const noAudio = Math.min(chain.noAudio, chain.start);
+    const resized = Math.min(chain.resized, noAudio);
+    const recoded = Math.min(chain.recoded, resized);
+    const final = Math.min(chain.final, recoded);
+    return {
+        audio: chain.start - noAudio,
+        resolution: noAudio - resized,
+        codec: resized - recoded,
+        quality: recoded - final,
+    };
+}
+/** Scales the bytes of a sample clip to the full duration. A sample with no length returns its bytes unchanged. */
+export function extrapolate(sampleBytes, sampleSeconds, totalSeconds) {
+    if (sampleSeconds <= 0)
+        return sampleBytes;
+    return Math.round((sampleBytes * totalSeconds) / sampleSeconds);
+}
+/**
+ * Start offsets, in seconds, of the 2-second sample clips. A clip of up to 6 s is sampled once, centred. A longer one
+ * is sampled at 1/6, 1/2 and 5/6 of its length, each shifted back by 1 s so the clip sits around that point, and kept
+ * inside the file. Clips under 2 s are sampled from the start.
+ */
+export function sampleOffsets(durationS) {
+    if (durationS < 2)
+        return [0];
+    if (durationS <= 6)
+        return [Math.max(0, (durationS - 2) / 2)];
+    return [1 / 6, 1 / 2, 5 / 6].map((f) => Math.min(Math.max(0, durationS * f - 1), durationS - 2));
+}
+/**
+ * Orders assets for the encode budget: heaviest per-view bytes first, then per-play bytes, then key. The per-view bytes are
+ * `rankView` when the asset has one (the largest per-view bytes of one viewport), else `perView`: the claim is averaged over
+ * the viewports, and an average would rank a video shown at one viewport of two at half its weight. Duplicate keys are
+ * dropped, keeping the first (heaviest) copy. The first `budget` assets are encoded; the rest are skipped and still get
+ * their cheap hints. The input is not mutated.
+ */
+export function rankForBudget(assets, budget) {
+    const rank = (a) => a.rankView ?? a.perView;
+    const sorted = [...assets].sort((a, b) => rank(b) - rank(a) || b.perPlay - a.perPlay || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const seen = new Set();
+    const unique = [];
+    for (const a of sorted) {
+        if (seen.has(a.key))
+            continue;
+        seen.add(a.key);
+        unique.push(a);
+    }
+    const cut = Math.max(0, Math.floor(budget));
+    return { encode: unique.slice(0, cut), skipped: unique.slice(cut) };
+}