imgtune 0.1.0 → 0.3.0

package/dist/image-file.js

@@ -3,17 +3,24 @@
 // (SSIMULACRA2 90 by default, visually lossless; --min-score sets another). The lowest quality per format that meets the
 // bar is reported. With --width the file is also measured at the width it is needed at (width x dpr). Files are read,
 // never written, unless --write names a directory for optimised copies.
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+//
+// Media (animated GIF, WebP and APNG, MP4, MOV and WebM) is read from local files only (media-file.ts): an animated file
+// gets the candidates of the animated codecs, and `--reference <original>` checks a candidate against the original with
+// the video bars (VMAF and the still-frame guard), exiting 0 on pass and 1 on fail.
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import sharp from "sharp";
 import { isLocalTarget } from "./address.js";
 import { encode, ENCODER_ID, loadReference } from "./encode.js";
 import { makeFetcher, MAX_IMAGE_BYTES } from "./fetch.js";
-import { gpuNote, parseGpuDevice, startGpuScorer } from "./gpu.js";
+import { gpuNote, startGpuScorer, gpuSettingOf, gpuSettingOne } from "./gpu.js";
+import { probeFfmpeg, withGpu } from "./ffmpeg.js";
 import { makeScorer } from "./metric.js";
 import { minPassingQuality } from "./search.js";
 import { cacheScope, CACHE_DIR, ResultCache } from "./result-cache.js";
-import { decodeRaw, pixelSize, safeText, SCAN_TOLERANCE, scorerOf } from "./remote.js";
+import { compareReferenceFile, describeVideo, measureAnimated, mediaKindOf, renderAnimated, renderReference, renderVideo } from "./media-file.js";
+import { DEFAULT_VIDEO_BAR, DEFAULT_VIDEO_STILL_BAR, decodeRaw, pixelSize, safeText, SCAN_TOLERANCE, scorerOf } from "./remote.js";
 import { IMGTUNE_VERSION } from "./version.js";
 const ALL_FORMATS = ["avif", "webp", "jpeg"];
 /** Most inputs (files, globs and URLs together) one run measures. */
@@ -24,12 +31,18 @@ const MAX_GLOB_MATCHES = 1000;
 const START_QUALITY = 90;
 /** The SSIMULACRA2 bar a file must meet against itself, when --min-score is not given: visually lossless. */
 export const DEFAULT_FILE_BAR = 90;
-const USAGE = "usage: imgtune image <file|url|glob> [...] [--width <css px>] [--dpr 1,2] [--formats avif,webp,jpeg] [--min-score <n>] [--write <dir>] [--format text|json] [--gpu] [--gpu-device <n>]";
+const USAGE = "usage: imgtune image <file|url|glob> [...] [--width <css px>] [--dpr 1,2] [--formats avif,webp,jpeg] [--min-score <n>] [--write <dir>] [--format text|json|--json] [--gpu] [--gpu-device <n>] [--reference <original file>] [--video-bar <n>] [--video-still-bar <n>]";
 function positiveNumber(name, text) {
     if (!/^\d+(\.\d+)?$/.test(text) || Number(text) <= 0)
         throw new Error(`${name} needs a number above 0, not ${safeText(text)}`);
     return Number(text);
 }
+/** A bar from 0 to 100 (a VMAF or still-guard bar). Throws with the message the CLI prints. */
+function barNumber(name, text) {
+    if (!/^\d+(\.\d+)?$/.test(text) || Number(text) > 100)
+        throw new Error(`${name} needs a number from 0 to 100, not ${safeText(text)}`);
+    return Number(text);
+}
 /** The arguments after `image`. Throws with the message the CLI prints. */
 export function parseImageArgs(argv) {
     const args = { inputs: [], dprs: [1, 2], formats: [...ALL_FORMATS], format: "text" };
@@ -40,13 +53,21 @@ export function parseImageArgs(argv) {
             continue;
         }
         if (arg === "--gpu") {
-            args.gpu ??= { device: 0 };
+            args.gpu ??= gpuSettingOne(0);
             continue;
         }
         if (arg === "--no-cache") {
             args.noCache = true;
             continue;
         }
+        if (arg === "--gpu-encode") {
+            args.gpuEncode = true;
+            continue;
+        }
+        if (arg === "--json") {
+            args.format = "json";
+            continue;
+        }
         const value = argv[i + 1];
         if (value === undefined || value.startsWith("--"))
             throw new Error(`${arg} needs a value (${USAGE})`);
@@ -73,9 +94,18 @@ export function parseImageArgs(argv) {
             args.minScore = score;
         }
         else if (arg === "--gpu-device")
-            args.gpu = { device: parseGpuDevice(value) };
+            args.gpu = gpuSettingOf(value);
         else if (arg === "--write")
             args.write = value;
+        else if (arg === "--reference") {
+            if (/^https?:\/\//i.test(value))
+                throw new Error(`--reference is a local file: media is not read from a URL here (local files only, not ${safeText(value)})`);
+            args.reference = value;
+        }
+        else if (arg === "--video-bar")
+            args.videoBar = barNumber(arg, value);
+        else if (arg === "--video-still-bar")
+            args.videoStillBar = barNumber(arg, value);
         else if (arg === "--format") {
             if (value !== "text" && value !== "json")
                 throw new Error(`--format is text or json, not ${safeText(value)}`);
@@ -198,6 +228,8 @@ async function readInput(input, cwd, userAgent) {
         const body = await fetcher.get(input.url, { maxBytes: MAX_IMAGE_BYTES, allowPrivate: isLocalTarget(input.url) });
         if (body === undefined)
             throw new Error(`${safeText(input.url)} was not fetched (blocked, failed, or larger than ${MAX_IMAGE_BYTES / (1024 * 1024)} MB)`);
+        if (mediaKindOf(body) !== undefined)
+            throw new Error(`${safeText(input.url)} is a video or animated file: media is local files only (download it and pass the file)`);
         return body;
     }
     const path = resolve(cwd, input.path);
@@ -287,8 +319,9 @@ export async function measureFile(input, buffer, args, score, cached) {
     const placeholder = { bar, sizes: [] };
     if (!info)
         return { ...base, width: { source: args.width ? "user" : "file", css: args.width }, ...placeholder, error: "not a decodable image" };
-    if (info.format === "svg" || info.format === "gif") {
-        return { ...base, width: { source: args.width ? "user" : "file", css: args.width }, ...placeholder, error: `${info.format} is not measured (not a raster format the encoders take)` };
+    // A static GIF is a raster image like a PNG (sharp reads its first frame). An animated one never reaches here: it is media.
+    if (info.format === "svg") {
+        return { ...base, width: { source: args.width ? "user" : "file", css: args.width }, ...placeholder, error: "svg is not measured (not a raster format the encoders take)" };
     }
     const targets = args.width === undefined ? [{ px: info.width }] : args.dprs.map((dpr) => ({ px: Math.min(Math.ceil(args.width * dpr), info.width), dpr }));
     const sizes = [];
@@ -378,7 +411,7 @@ export async function writeCopies(results, inputs, cwd, dir, buffers) {
     return notes;
 }
 /** `imgtune image`: measures each input and returns the text or JSON to print. */
-export async function imageCommand(argv, cwd, userAgent = `imgtune/${IMGTUNE_VERSION}`, log = (message) => process.stderr.write(`imgtune: ${message}\n`)) {
+export async function imageCommand(argv, cwd, userAgent = `imgtune/${IMGTUNE_VERSION}`, log = (message) => process.stderr.write(`imgtune: ${message}\n`), signal) {
     const args = parseImageArgs(argv);
     const gpu = args.gpu !== undefined ? await startGpuScorer(args.gpu.device, log) : undefined;
     const store = args.noCache === true ? undefined : new ResultCache(join(cwd, CACHE_DIR));
@@ -387,47 +420,134 @@ export async function imageCommand(argv, cwd, userAgent = `imgtune/${IMGTUNE_VER
         ? undefined
         : { store, scorerId: gpu !== undefined ? `gpu:${gpu.deviceName}` : "cpu", cpuScored: gpu ? () => gpu.cpuScores : undefined };
     try {
-        return await measureInputs(args, cwd, userAgent, gpu, cache);
+        return await measureInputs(args, cwd, userAgent, gpu, cache, signal);
     }
     finally {
         gpu?.close();
     }
 }
-async function measureInputs(args, cwd, userAgent, gpu, cache) {
+async function measureInputs(args, cwd, userAgent, gpu, cache, signal) {
     const inputs = await resolveInputs(args.inputs, cwd);
     const score = makeScorer("ssimulacra2", { projectDir: cwd, gpu });
+    const scorer = gpu !== undefined ? scorerOf(gpu, gpu.fallbackScores) : { name: "cpu" };
+    if (args.reference !== undefined)
+        return compareMode(args, inputs, cwd, score, scorer, signal);
     const results = [];
+    const media = [];
     const buffers = new Map();
-    for (const input of inputs) {
-        let buffer;
-        try {
-            buffer = await readInput(input, cwd, userAgent);
-        }
-        catch (err) {
-            results.push({
-                label: input.label,
-                evidence: "file-mode",
-                imgtuneVersion: IMGTUNE_VERSION,
-                current: { width: 0, height: 0, bytes: 0 },
-                width: { source: args.width ? "user" : "file", css: args.width },
-                bar: barOf(args.minScore),
-                sizes: [],
-                error: err.message,
-            });
-            continue;
+    // Scratch for the media encodes of this run, removed when the run ends.
+    let scratch;
+    const mediaContext = async () => {
+        scratch ??= await mkdtemp(join(tmpdir(), "imgtune-media-file-"));
+        // The media is encoded on the CPU unless --gpu-encode asks for the GPU; its encoders are proven on that GPU first.
+        const device = args.gpuEncode === true ? (args.gpu?.device ?? 0) : undefined;
+        const caps = await withGpu(await probeFfmpeg(), device);
+        return {
+            caps,
+            gpu: caps.av1Nvenc || caps.h264Nvenc ? device : undefined,
+            score,
+            dir: scratch,
+            videoBar: args.videoBar ?? DEFAULT_VIDEO_BAR,
+            videoStillBar: args.videoStillBar ?? DEFAULT_VIDEO_STILL_BAR,
+            signal,
+        };
+    };
+    try {
+        for (const input of inputs) {
+            let buffer;
+            try {
+                buffer = await readInput(input, cwd, userAgent);
+            }
+            catch (err) {
+                results.push({
+                    label: input.label,
+                    evidence: "file-mode",
+                    imgtuneVersion: IMGTUNE_VERSION,
+                    current: { width: 0, height: 0, bytes: 0 },
+                    width: { source: args.width ? "user" : "file", css: args.width },
+                    bar: barOf(args.minScore),
+                    sizes: [],
+                    error: err.message,
+                });
+                continue;
+            }
+            buffers.set(input.label, buffer);
+            const kind = mediaKindOf(buffer);
+            if (kind !== undefined && input.path !== undefined) {
+                const file = { label: input.label, path: resolve(cwd, input.path), buffer };
+                const ctx = await mediaContext();
+                const dir = join(ctx.dir, `file-${media.length}`);
+                media.push(kind === "animated" ? await measureAnimated(file, args.width, ctx, dir) : await describeVideo(file, ctx, dir));
+                continue;
+            }
+            results.push(await measureFile(input, buffer, args, score, cache && { ...cache, original: buffer }));
         }
-        buffers.set(input.label, buffer);
-        results.push(await measureFile(input, buffer, args, score, cache && { ...cache, original: buffer }));
+    }
+    finally {
+        if (scratch !== undefined)
+            await rm(scratch, { recursive: true, force: true });
     }
     const notes = args.write !== undefined ? await writeCopies(results, inputs, cwd, args.write, buffers) : [];
-    const failed = results.filter((r) => r.error !== undefined).length;
-    const scorer = gpu !== undefined ? scorerOf(gpu, gpu.fallbackScores) : { name: "cpu" };
+    const failed = results.filter((r) => r.error !== undefined).length + media.filter((m) => m.error !== undefined).length;
     if (args.format === "json") {
-        const body = { evidence: "file-mode", scorer, files: results, copies: notes };
+        const body = { evidence: "file-mode", scorer, files: results, media, copies: notes };
         return { output: `${JSON.stringify(body, null, 2)}\n`, exitCode: failed > 0 ? 1 : 0 };
     }
     const head = gpu !== undefined ? `${gpuNote(gpu.device, gpu.deviceName, gpu.fallbackScores)}\n\n` : "";
     const text = results.map(renderFile).join("\n");
+    const mediaText = media.map((m) => (m.kind === "animated" ? renderAnimated(m) : renderVideo(m))).join("\n");
     const tail = notes.length > 0 ? `copies:\n${notes.map((n) => `  ${n}`).join("\n")}\n` : "";
-    return { output: `${head}${text}${tail}`, exitCode: failed > 0 ? 1 : 0 };
+    return { output: `${head}${text}${mediaText}${tail}`, exitCode: failed > 0 ? 1 : 0 };
+}
+/**
+ * `--reference <original>`: one candidate (a local media file) compared with the original. The verdict is the exit code:
+ * 0 on pass, 1 on fail or on any error. Input that cannot be compared is an error, not a fail verdict on the file.
+ */
+async function compareMode(args, inputs, cwd, score, scorer, signal) {
+    const reference = args.reference;
+    const fail = (message) => {
+        if (args.format === "json")
+            return { output: `${JSON.stringify({ evidence: "media-reference", scorer, error: message }, null, 2)}\n`, exitCode: 1 };
+        return { output: `${safeText(message)}\n`, exitCode: 1 };
+    };
+    if (inputs.length !== 1)
+        return fail(`--reference compares one file: give one candidate (${inputs.length} match)`);
+    const [candidate] = inputs;
+    if (candidate.url !== undefined)
+        return fail("--reference takes local files only: the candidate is a URL, and media is not read from a URL here");
+    const refPath = resolve(cwd, reference);
+    const refInfo = await stat(refPath).catch(() => undefined);
+    if (!refInfo?.isFile())
+        return fail(`--reference ${safeText(reference)} is not a file`);
+    if (refInfo.size > MAX_IMAGE_BYTES)
+        return fail(`--reference ${safeText(reference)} is larger than ${MAX_IMAGE_BYTES / (1024 * 1024)} MB`);
+    const refBuffer = await readFile(refPath);
+    if (mediaKindOf(refBuffer) === undefined)
+        return fail(`--reference ${safeText(reference)} is not a video or animated file`);
+    const candBuffer = await readInput(candidate, cwd, "");
+    if (mediaKindOf(candBuffer) === undefined)
+        return fail(`${safeText(candidate.label)} is not a video or animated file: --reference compares media`);
+    const caps = await probeFfmpeg();
+    if (!caps.ffmpeg)
+        return fail("ffmpeg is not on PATH: --reference needs it (ffmpeg enables the full hints)");
+    const dir = await mkdtemp(join(tmpdir(), "imgtune-compare-"));
+    let result;
+    try {
+        const ctx = {
+            caps,
+            score,
+            dir,
+            videoBar: args.videoBar ?? DEFAULT_VIDEO_BAR,
+            videoStillBar: args.videoStillBar ?? DEFAULT_VIDEO_STILL_BAR,
+            signal,
+        };
+        result = await compareReferenceFile({ label: candidate.label, path: resolve(cwd, candidate.path), buffer: candBuffer }, { label: relative(cwd, refPath) || reference, path: refPath, buffer: refBuffer }, args.width, ctx, dir);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+    const exitCode = result.error === undefined && result.pass ? 0 : 1;
+    if (args.format === "json")
+        return { output: `${JSON.stringify(result, null, 2)}\n`, exitCode };
+    return { output: renderReference(result), exitCode };
 }

package/dist/image-open.js

@@ -0,0 +1,9 @@
+// sharp over a downloaded file, with the pixel limit every scan applies. Kept apart from remote.ts so the image helpers
+// (vector-art.ts, the media code) can open a file without importing the scan.
+import sharp from "sharp";
+/** The most input pixels sharp accepts for a downloaded file. */
+export const MAX_INPUT_PIXELS = 100_000_000;
+/** sharp over a downloaded file, refusing inputs above `limit` pixels. */
+export function openImage(buffer, limit = MAX_INPUT_PIXELS) {
+    return sharp(buffer, { limitInputPixels: limit });
+}

package/dist/images.js

@@ -4,9 +4,10 @@
 import { sha1 } from "./atomic.js";
 import { deriveSizesFromLayout, sameStructure, slotAt, } from "./layout.js";
 import { COMPONENT_NAME, loaderName, sanitizeText, urlPattern } from "./locate.js";
-import { undersizedProposal } from "./candidates.js";
+import { srcsetWidthsOf, undersizedProposal } from "./candidates.js";
 import { sizesBranchAt, sizesSlotAt } from "./sizes.js";
 import { parseSrcset } from "./srcset-parse.js";
+import { animatedTarget } from "./media-model.js";
 /** The first path segment of a harness route: a page the agent adds to measure a component in isolation. */
 export const HARNESS_SEGMENT = "__imgtune";
 /**
@@ -43,6 +44,77 @@ export function searchHintsOf(locator) {
         hints.urlPattern = locator.urlPattern;
     return Object.keys(hints).length > 0 ? hints : undefined;
 }
+/**
+ * Whether a served format takes the lossless rules (a local resize and the AVIF proposal): a jpeg or png, or a static GIF
+ * (a palette file, judged as a PNG). An animated GIF does not: its saving is an encode.
+ */
+export function losslessServed(format, animated) {
+    return format === "jpeg" || format === "png" || (format === "gif" && !animated);
+}
+/** The hidden fix of an element from its entries (one per viewport it was measured at), or undefined when it is shown on load everywhere. */
+export function hiddenFixCore(entries, viewportCount) {
+    const hidden = entries.filter((e) => e.hidden !== undefined);
+    if (hidden.length === 0)
+        return undefined;
+    const reasons = [...new Set(hidden.map((e) => e.hidden).filter((r) => r !== undefined))];
+    const inPanel = hidden.some((e) => e.inPanel);
+    const hover = hidden.some((e) => e.hover);
+    const unstable = hidden.some((e) => e.unstable === true);
+    const shownIn = entries.filter((e) => e.hidden === undefined).map((e) => e.viewport.name);
+    const alreadyLazy = hidden.some((e) => e.lazy === true);
+    const onlyClipped = reasons.every((r) => r === "clipped");
+    // A responsive twin: shown on load somewhere, and hidden by a rule that is not a carousel's clipping.
+    const action = shownIn.length > 0 && !onlyClipped ? "responsive" : reasons.includes("clipped") || inPanel || hover ? "lazy" : "never-shown-on-load";
+    return {
+        reasons,
+        inPanel,
+        ...(hover ? { hover: true } : {}),
+        ...(unstable ? { unstable: "unknown" } : {}),
+        viewports: hidden.map((e) => e.viewport.name),
+        of: viewportCount,
+        widths: Object.fromEntries(entries.map((e) => [e.viewport.name, e.viewport.width])),
+        shownIn,
+        action,
+        ...(alreadyLazy ? { alreadyLazy: true } : {}),
+        perViewBytes: hidden.reduce((sum, e) => sum + e.bytes, 0) / viewportCount,
+    };
+}
+/** The hidden fix of an image element from its instances (one per viewport). */
+export function hiddenFixOf(members, viewportCount) {
+    return hiddenFixCore(members.map((m) => ({
+        viewport: { name: m.viewport.name, width: m.viewport.width },
+        bytes: m.bytes,
+        hidden: m.kind === "hidden" ? m.img.hidden : undefined,
+        inPanel: m.img.inPanel === true,
+        hover: m.img.hover === true,
+        lazy: m.img.lazy === true,
+        unstable: m.img.unstable === "unknown",
+    })), viewportCount);
+}
+/**
+ * The page's loaded-but-not-shown totals, counted over the records (one record per element or background layer, so the
+ * count and the cases are the same unit). Undefined when no record is hidden.
+ */
+export function hiddenTotalsOf(records, viewportCount) {
+    const hidden = records.flatMap((r) => (r.hidden !== undefined ? [r] : []));
+    if (hidden.length === 0)
+        return undefined;
+    const cases = { responsive: 0, lazy: 0, "never-shown-on-load": 0 };
+    for (const r of hidden)
+        cases[r.hidden.action]++;
+    // A file several records share (background layers of one image, or a repeated element) is one file: its bytes count once,
+    // at the largest of its records. A record with no URL is its own file.
+    const perFile = new Map();
+    hidden.forEach((r, index) => {
+        const key = r.current.src ?? `#${index}`;
+        perFile.set(key, Math.max(perFile.get(key) ?? 0, r.hidden.perViewBytes));
+    });
+    return {
+        images: hidden.length,
+        bytesPerView: [...perFile.values()].reduce((sum, bytes) => sum + bytes, 0),
+        cases,
+    };
+}
 const round1 = (value) => Math.round(value * 10) / 10;
 const round2 = (value) => Math.round(value * 100) / 100;
 /**
@@ -110,7 +182,7 @@ function tunableOf(member, pageUrl, loader) {
 /** The measured viewports of a group as the proposal check reads them. */
 function measuredPoints(members) {
     return members
-        .filter((m) => m.renderedWidth >= 1)
+        .filter((m) => m.renderedWidth >= 1 && m.kind !== "hidden")
         .map((m) => ({ viewport: m.viewport.name, viewportWidth: m.viewport.width, dpr: m.viewport.dpr, renderedWidth: m.renderedWidth, srcset: m.img.srcset }));
 }
 function sizesOf(measured) {
@@ -125,6 +197,17 @@ function sizesOf(measured) {
 export function hasFix(record) {
     return record.fix.bytes.saved > 0 || (record.fix.sizes !== undefined && record.fix.sizes.value !== record.current.sizes);
 }
+/**
+ * A plain image with no srcset at all, from a same-origin file or a CDN host no adapter knows: its saving is a resize, and
+ * its fix is variant files with a srcset (see srcsetWidthsOf). A known loader (next/image, a named CDN adapter) keeps its own
+ * advice, and so does a page with Next.js detected.
+ */
+export function isPlainNoSrcset(kind, srcset, loader, framework) {
+    if (kind !== "plain" || framework || srcset.trim() !== "")
+        return false;
+    // "generic" is the adapter name of an origin no adapter matched (Instance.loader); the locator names it plain-img or cdn:<host>.
+    return loader === "plain-img" || loader === "unknown" || loader === "generic" || loader.startsWith("cdn:");
+}
 /** Builds the image records of one page from its analysed instances. */
 export function buildImageRecords(input) {
     const { pageUrl, observations, instances, refName, resolved } = input;
@@ -184,6 +267,8 @@ export function buildImageRecords(input) {
                 loaded: inst.url !== "" && obs.responses.get(inst.url)?.buffer !== undefined,
                 lcp: obs.lcp?.kind === "image" && obs.lcp.index === inst.element,
             };
+            if (inst.kind === "hidden" && inst.img.hidden !== undefined)
+                entry.hidden = inst.img.hidden;
             if (inst.pixelWidth > 0)
                 entry.servedPx = inst.pixelWidth;
             if (inst.pixelWidth > 0 && inst.needed > 0)
@@ -211,7 +296,7 @@ export function buildImageRecords(input) {
             };
         }
         const measured = members
-            .filter((m) => m.renderedWidth >= 1)
+            .filter((m) => m.renderedWidth >= 1 && m.kind !== "hidden")
             .map((m) => ({
             viewportWidth: m.viewport.width,
             renderedWidth: m.renderedWidth,
@@ -228,23 +313,55 @@ export function buildImageRecords(input) {
         const keepSizes = sizes !== undefined && left === undefined;
         const savedEff = keepSizes ? saved : saved - savedSizes;
         const savedSizesEff = keepSizes ? savedSizes : 0;
+        // A plain image with no srcset: the sizes attribute does nothing without one, so no sizes proposal; its saving is the
+        // resize (est.), not a re-encode.
+        const plainNoSrcset = isPlainNoSrcset(member.kind, member.img.srcset, locator.loader, input.nextjs === true);
         const served = member.format;
-        const best = served === "jpeg" || served === "png" ? (saved > 0 ? "avif" : served) : served;
-        const fix = { bytes: { saved: savedEff, addedForSharpness, sizes: savedSizesEff, quality: savedEff - savedSizesEff } };
+        const animatedMember = members.find((m) => m.animated !== undefined);
+        const lossless = losslessServed(served, animatedMember !== undefined);
+        const best = lossless ? (saved > 0 ? "avif" : served) : served;
+        // A hidden fix first: an element never shown on load gets no animated encode either (its bytes are not a saving).
+        const hiddenFix = hiddenFixOf(members, viewportCount);
+        const fix = {
+            bytes: plainNoSrcset
+                ? { saved: savedEff, addedForSharpness, sizes: 0, resize: savedEff, quality: 0 }
+                : { saved: savedEff, addedForSharpness, sizes: savedSizesEff, quality: savedEff - savedSizesEff },
+        };
         if (member.cdnQuality !== undefined)
             fix.cdnQuality = { ...member.cdnQuality };
-        if (member.formatAuto === true && (served === "jpeg" || served === "png"))
+        if (member.formatAuto === true && lossless)
             fix.formatHandled = true;
+        if (animatedMember?.animated !== undefined && hiddenFix?.shownIn.length !== 0) {
+            fix.animated = {
+                info: animatedMember.animated,
+                context: "img",
+                target: animatedTarget("img", undefined),
+                perViewBytes: members.reduce((sum, m) => sum + m.bytes, 0) / viewportCount,
+            };
+        }
         if (sizes && left !== undefined) {
             fix.noSaving = `sizes proposal left out: ${left}`;
             notes.push(`sizes proposal left out: ${left}`);
         }
-        if (keepSizes) {
+        if (plainNoSrcset && savedEff > 0) {
+            const naturalWidth = member.pixelWidth > 0 ? member.pixelWidth : undefined;
+            const needs = members.map((m) => m.needed);
+            const widths = srcsetWidthsOf(needs, naturalWidth);
+            if (widths.length > 0) {
+                fix.srcset = { widths, largest: Math.max(...needs), ...(keepSizes && sizes !== undefined ? { sizes: sizes.value } : {}) };
+                notes.push(`srcset: no srcset today; variants at ${widths.join("w, ")}w (the saving is a resize)`);
+            }
+        }
+        else if (keepSizes && !plainNoSrcset) {
             fix.sizes = { value: sizes.value, basis: sizes.basis, rung, branches: sizes.branches };
             const sized = sizes.branches.map((b) => b.basis);
             const formulas = sized.filter((b) => b === "layout-formula").length;
             notes.push(`sizes: ${sizes.basis} (${formulas} of ${sized.length} media branch(es) from the layout formula, checked at ${measured.length} of ${viewportCount} viewports)`);
         }
+        const flatMember = members.find((m) => m.flatness?.flat === true);
+        // Never on a hidden element: the vector check and the hidden fix do not stack on one record.
+        if (flatMember?.flatness !== undefined && hiddenFix === undefined)
+            fix.vector = { flatness: { ...flatMember.flatness } };
         if (member.kind === "plain")
             fix.width = member.needed;
         if (best !== undefined)
@@ -252,6 +369,7 @@ export function buildImageRecords(input) {
         const record = {
             id: sha1(`${pageUrl}\n${key}`).slice(0, 12),
             page: pageUrl,
+            ...(member.img.posterOf !== undefined ? { poster: true } : {}),
             locator,
             tunable: tunableOf(member, pageUrl, locator.loader),
             current: {
@@ -286,6 +404,12 @@ export function buildImageRecords(input) {
             notes.push(`quality handled by ${locator.loader} (q_auto): its est. quality saving is not counted`);
         if (fix.formatHandled === true)
             notes.push(`format handled by ${locator.loader} (f_auto): no format change proposed`);
+        if (member.img.posterOf !== undefined)
+            notes.push(`poster of video ${sanitizeText(member.img.posterOf, 120)} (sized to its box)`);
+        if (fix.animated !== undefined) {
+            const { frames, durationMs, loop } = fix.animated.info;
+            notes.push(`animated ${fix.animated.info.format}: ${frames} frame(s), ${Math.round(durationMs / 100) / 10} s per loop, loops ${loop === 0 ? "forever" : loop}`);
+        }
         if (layoutChain?.truncated)
             notes.push("layout chain cut at the depth cap");
         if (layoutChain && layoutChain.skipped.length > 0)
@@ -296,6 +420,15 @@ export function buildImageRecords(input) {
                 continue;
             own.set(m.format, Math.max(own.get(m.format) ?? -Infinity, m.qualityInfo.target));
         }
+        // A loaded-but-not-shown element has no vector claim (the vector check and the hidden fix never stack), and a copy that
+        // is never shown on load has no sizes claim either: its bytes are the hidden fix's. A responsive twin keeps the sizes of
+        // the viewports that show it (see the hidden-images tests).
+        if (hiddenFix !== undefined) {
+            record.hidden = hiddenFix;
+            delete record.fix.vector;
+            if (hiddenFix.shownIn.length === 0)
+                delete record.fix.sizes;
+        }
         targets.set(record, own);
         records.push(record);
     }
@@ -319,7 +452,8 @@ export function buildImageRecords(input) {
         for (const [format, target] of entry.max)
             perFormat[format] = target;
         for (const record of entry.records) {
-            if (record.current.quality === undefined)
+            // An image never shown has no quality claim: its file is not on screen at any viewport.
+            if (record.current.quality === undefined || record.hidden?.shownIn.length === 0)
                 continue;
             record.fix.quality = {
                 perFormat,

package/dist/layout.js

@@ -1,7 +1,4 @@
-// Layout chains and the CSS `sizes` value derived from them. Pure: no DOM, no network. The browser side (remote.ts) records
-// a chain per image and viewport; this module walks the chain down from the viewport to the image and states the image's
-// width as a linear function of the viewport width (a * vw + b). The function is checked against the widths the browser
-// rendered, branch by branch, and printed as CSS.
+import { offsetPx, wholePx } from "./px.js";
 /** Rounding of the coefficients: the printed value is the value the check uses. */
 const round = (value, digits) => {
     const scale = 10 ** digits;
@@ -95,16 +92,19 @@ export function formatLinear(l) {
     const vwPercent = round(l.a * 100, 2);
     const px = round(l.b, 2);
     if (vwPercent === 0)
-        return `${Math.max(0, px)}px`;
+        return `${Math.max(0, wholePx(px))}px`;
     if (px === 0)
         return `${vwPercent}vw`;
-    return `calc(${vwPercent}vw ${px < 0 ? "-" : "+"} ${Math.abs(px)}px)`;
+    const offset = offsetPx(px);
+    if (offset === 0)
+        return `${vwPercent}vw`;
+    return `calc(${vwPercent}vw ${offset < 0 ? "-" : "+"} ${Math.abs(offset)}px)`;
 }
 /** A fitted line held outside the range it was measured in: the viewport is clamped to [lo, hi] (CSS clamp()). */
 export function formatHeldFit(l, lo, hi) {
     if (Math.abs(l.a) < 1e-9)
         return formatLinear({ a: 0, b: l.b });
-    const b = round(l.b, 2);
+    const b = offsetPx(round(l.b, 2));
     return `calc(${round(l.a, 4)} * clamp(${Math.round(lo)}px, 100vw, ${Math.round(hi)}px) ${b < 0 ? "-" : "+"} ${Math.abs(b)}px)`;
 }
 /** The value of a held fit at a viewport: the line at the viewport clamped to [lo, hi]. */

package/dist/lcp.js

@@ -32,7 +32,8 @@ export function lcpImagesOf(result) {
             servedBytes: served.reduce((sum, p) => sum + p.servedBytes, 0) / served.length,
             savedBytes: record.fix.bytes.saved,
             exactBytes: record.fix.bytes.sizes ?? 0,
-            estBytes: record.fix.bytes.quality ?? 0,
+            // The resize of a plain image with no srcset is an estimate too (see ImageFix.bytes).
+            estBytes: (record.fix.bytes.quality ?? 0) + (record.fix.bytes.resize ?? 0),
             ...(skipped !== undefined ? { skipped } : {}),
         });
     }