imgtune 0.2.0 → 0.3.0

package/dist/cli.js

@@ -21,6 +21,8 @@ const progress = (message) => {
 const OPTION_HELP = {
     out: ["--out <dir>", "directory for the JSON files (default: .imgtune/scan)"],
     noCache: ["--no-cache", "do not read or write the result cache in .imgtune/cache (the numbers are computed again)"],
+    noResources: ["--no-resources", "skip the resource phase: no capture of the non-image responses, so none of the resource findings (compression, favicons, fonts, SVG, Lottie, 3D, audio)"],
+    resourceTime: ["--resource-time <s>", "time limit of the heavy resource work (3D, fonts, SVG, audio, lottie re-encodes), in seconds, 0 to 3600 (default 60); items over it are reported as not measured"],
     gpuEncode: [
         "--gpu-encode",
         "EXPERIMENTAL: encode the videos and animated images on the GPU (NVENC, CUDA VMAF); off by default (CPU encodes). Bytes are scaled to a CPU encode (÷1.4)",
@@ -66,6 +68,10 @@ const OPTION_HELP = {
         "--media-budget <N>",
         "sample-encode at most N animated images and videos per run, heaviest first, 0 to 1000 (default 20); the rest keep their cheap hints",
     ],
+    svgBudget: [
+        "--svg-budget <N>",
+        "trace at most N flat images (logos, icons, flat illustrations) to SVG and check them, heaviest first, 0 to 1000 (default 50; 0 traces none)",
+    ],
     mediaTime: ["--media-time <s>", "time limit of the media encodes, in seconds, 1 to 3600 (default 600)"],
     videoBar: ["--video-bar <n>", "minimum VMAF of a video or animated encode, 0 to 100 (default 93)"],
     videoStillBar: ["--video-still-bar <n>", "minimum SSIMULACRA2 of the still-frame guard, 0 to 100 (default 65)"],
@@ -149,6 +155,8 @@ const SCAN_HELP = commandHelp("imgtune scan <url> [<url> ...] [options]", [
     "out",
     "root",
     "noCache",
+    "noResources",
+    "resourceTime",
     "gpuEncode",
     "aggressive",
     "viewports",
@@ -163,6 +171,7 @@ const SCAN_HELP = commandHelp("imgtune scan <url> [<url> ...] [options]", [
     "maxPages",
     "maxImages",
     "mediaBudget",
+    "svgBudget",
     "mediaTime",
     "videoBar",
     "videoStillBar",
@@ -211,9 +220,12 @@ Options:
   --gpu-encode                    EXPERIMENTAL: encode the deep pages' videos and animated images on the GPU (see scan --help)
   --page-concurrency <N>          pages at once in the deep phase (default 1)
   --idle-timeout <ms>             cap on the network-idle wait in the deep phase (default 10000)
+  --svg-budget <N>                trace at most N flat images of the deep pages to SVG (default 50; 0 traces none)
   --block-third-party             abort the requests to other sites (off by default; can drop images a page loads from its API)
   --allow-host <h1,h2>            with --block-third-party: keep the requests to these hosts
   --no-cache                      do not read or write the result cache
+  --no-resources                  skip the resource phase (compression, favicons, fonts, SVG, Lottie, 3D and audio findings; no capture of the other responses)
+  --resource-time <s>             time limit of the heavy resource work (3D, fonts, SVG, audio, Lottie re-encodes), in seconds, 0 to 3600 (default 60)
   --ignore-robots                 scan pages robots.txt disallows (owned or authorised sites only)
   --storage-state <file>          a logged-in session (holds cookies: never commit it)
   -h, --help                      show this help
@@ -247,9 +259,12 @@ Options:
   --gpu-encode                    EXPERIMENTAL: encode the deep pages' videos and animated images on the GPU (see scan --help)
   --page-concurrency <N>          pages at once in the deep phase (default 1)
   --idle-timeout <ms>             cap on the network-idle wait in the deep phase (default 10000)
+  --svg-budget <N>                trace at most N flat images of the deep pages to SVG (default 50; 0 traces none)
   --block-third-party             abort the requests to other sites (off by default; can drop images a page loads from its API)
   --allow-host <h1,h2>            with --block-third-party: keep the requests to these hosts
   --no-cache                      do not read or write the result cache
+  --no-resources                  skip the resource phase (compression, favicons, fonts, SVG, Lottie, 3D and audio findings; no capture of the other responses)
+  --resource-time <s>             time limit of the heavy resource work (3D, fonts, SVG, audio, Lottie re-encodes), in seconds, 0 to 3600 (default 60)
   --ignore-robots                 scan pages robots.txt disallows (owned or authorised sites only)
   --storage-state <file>          a logged-in session (holds cookies: never commit it)
   -h, --help                      show this help
@@ -278,7 +293,10 @@ Options:
   --gpu-encode                    EXPERIMENTAL: encode the deep pages' videos and animated images on the GPU (see scan --help)
   --page-concurrency <N>          pages at once in the survey (default 4) and in the deep phase (default 1)
   --idle-timeout <ms>             cap on the network-idle wait (default 3000 in the survey, 10000 in the deep phase)
+  --svg-budget <N>                trace at most N flat images of the deep pages to SVG (default 50; 0 traces none)
   --no-cache                      do not read or write the result cache
+  --no-resources                  skip the resource phase (compression, favicons, fonts, SVG, Lottie, 3D and audio findings; no capture of the other responses)
+  --resource-time <s>             time limit of the heavy resource work (3D, fonts, SVG, audio, Lottie re-encodes), in seconds, 0 to 3600 (default 60)
   --root <dir>                    the source folder for --dev (a monorepo sub-folder)
   --storage-state <file>          a logged-in session (holds cookies: never commit it)
   --ignore-robots                 scan pages robots.txt disallows (owned or authorised sites only)
@@ -374,6 +392,8 @@ Options:
 `;
 const USAGE = `Usage: imgtune <command> [options]
 
+imgtune measures page weight on live pages (images, video, hidden downloads, fonts, compression, 3D, audio, Lottie, SVG) and prints the fix for each.
+
 Commands:
   scan      measure live pages by URL, with no source, config or dev server (writes JSON to --out)
   hints     print a batch of the per-image fix hints of a scan file

package/dist/egress-proxy.js

@@ -38,8 +38,9 @@ function connectionFor(hostname, policy, onRefused) {
     const checked = guardedLookup(policy.resolver, policy.allowPrivate, policy.connectAddress);
     const lookup = ((name, options, callback) => {
         checked(name, options, (err, ...rest) => {
+            // The name a lookup could not resolve: the page may still load it in a browser (see the scan's unresolved hosts).
             if (err)
-                onRefused();
+                onRefused(name);
             callback(err, ...rest);
         });
     });

package/dist/ffmpeg.js

@@ -493,3 +493,38 @@ export function parseRate(rate) {
     const fps = n / d;
     return fps > 0 ? fps : undefined;
 }
+/** Turns ffprobe's JSON into an AudioProbe, or undefined when there is no audio stream with a codec. */
+export function parseAudioProbeJson(json) {
+    const audio = (json.streams ?? []).find((s) => s.codec_type === "audio");
+    if (!audio?.codec_name)
+        return undefined;
+    const bitrate = toNumber(json.format?.bit_rate) ?? toNumber(audio.bit_rate);
+    const probe = {
+        codec: audio.codec_name,
+        durationS: toNumber(json.format?.duration) ?? toNumber(audio.duration) ?? 0,
+        channels: typeof audio.channels === "number" && audio.channels > 0 ? audio.channels : 0,
+    };
+    if (bitrate !== undefined && bitrate > 0)
+        probe.bitrate = bitrate;
+    const sampleRate = toNumber(audio.sample_rate);
+    if (sampleRate !== undefined && sampleRate > 0)
+        probe.sampleRate = sampleRate;
+    return probe;
+}
+/**
+ * Reads an audio file with ffprobe. `input` is an absolute file path or an http(s) URL (see inputOptions). Resolves
+ * undefined when ffprobe fails, times out or finds no audio stream. Never throws for a bad file.
+ */
+export async function probeAudio(input, timeoutMs, opts = {}) {
+    if (/^https?:\/\//i.test(input) && opts.proxy === undefined)
+        return undefined;
+    try {
+        const result = await runBinary(ffprobeBin(), ["-v", "error", "-print_format", "json", "-show_streams", "-show_format", ...inputOptions(input, opts.proxy), "-i", input], { timeoutMs });
+        if (result.code !== 0)
+            return undefined;
+        return parseAudioProbeJson(JSON.parse(result.stdout.toString("utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hints.js

@@ -7,8 +7,13 @@ import { safeText } from "./text.js";
 import { cleanLocate } from "./locate-join.js";
 import { DEFAULT_VIEWPORTS } from "./config.js";
 import { fitSizes, maxPerWidth } from "./group-sizes.js";
+import { srcsetWidthLabel, srcsetWidthsOf } from "./candidates.js";
 import { MAX_MAX_QUALITIES, MIN_MAX_QUALITIES, planQualityCap, qualitiesLine } from "./qualities-cap.js";
 import { reasonText } from "./media-model.js";
+import { NEVER_SHOWN } from "./media-phase.js";
+import { resourceLinesOf } from "./resources/report.js";
+import { VECTOR_BAR, VECTOR_LOOKS_MIN_BYTES } from "./vector-art.js";
+import { perViewBytesOf } from "./vector-phase.js";
 export const DEFAULT_HINT_LIMIT = 10;
 const usage = "usage: imgtune hints <scan.json> [<scan.json> ...] [--page <text>] [--component <name>] [--limit N] [--offset N] [--min-kb N] [--format text|json] [--flat] [--qualities 75,85,100] [--max-qualities N]";
 function nonNegativeInteger(name, text) {
@@ -99,8 +104,9 @@ export function parseHintsArgs(argv) {
  * planQualityCap); it applies only when no --qualities list was given (that list is the framework's own).
  */
 export function hintsOf(result, qualities, plan) {
-    // An animated image is a hint even without a sizes or byte saving: its saving is an encode (see animatedLines).
-    return (result.images ?? []).filter((record) => hasFix(record) || record.fix.animated !== undefined).map((record) => {
+    // An animated image is a hint even without a sizes or byte saving: its saving is an encode (see animatedLines). So is a
+    // loaded-but-not-shown image: its bytes are the fix's (see hiddenLines).
+    return (result.images ?? []).filter((record) => hasFix(record) || record.fix.animated !== undefined || vectorHinted(record) || record.hidden !== undefined).map((record) => {
         const served = record.current.format;
         const rawTarget = served !== undefined ? record.fix.quality?.perFormat[served] : undefined;
         // With the framework's allowed qualities, the target goes up to one of them. The quality saving was estimated at the
@@ -119,7 +125,7 @@ export function hintsOf(result, qualities, plan) {
             sizes: { current: record.current.sizes, proposed: record.fix.sizes?.value, basis: record.fix.sizes?.basis },
             // A raise (the list has no lower value for this usage) adds bytes: its quality saving is then none, not negative.
             bytes: capped !== undefined
-                ? { ...record.fix.bytes, saved: (record.fix.bytes.sizes ?? 0) + Math.max(0, capped.saved), quality: Math.max(0, capped.saved) }
+                ? { ...record.fix.bytes, saved: (record.fix.bytes.sizes ?? 0) + (record.fix.bytes.resize ?? 0) + Math.max(0, capped.saved), quality: Math.max(0, capped.saved) }
                 : { ...record.fix.bytes },
             rung: record.evidence.rung,
             notes: record.evidence.notes,
@@ -171,6 +177,8 @@ export function hintsOf(result, qualities, plan) {
             hint.measured = measured;
         if (record.fix.width !== undefined)
             hint.width = record.fix.width;
+        if (record.fix.srcset !== undefined)
+            hint.srcset = { ...record.fix.srcset };
         const cdn = record.fix.cdnQuality;
         if (cdn !== undefined) {
             hint.qualityNote = cdn.handled
@@ -204,12 +212,16 @@ export function hintsOf(result, qualities, plan) {
                 quality.snapFrom = snapFrom;
                 quality.void = true;
                 if (hint.bytes.sizes !== undefined)
-                    hint.bytes = { ...hint.bytes, saved: hint.bytes.sizes, quality: 0 };
+                    hint.bytes = { ...hint.bytes, saved: hint.bytes.sizes + (hint.bytes.resize ?? 0), quality: 0 };
             }
             hint.quality = quality;
         }
         if (record.fix.format !== undefined || served !== undefined)
             hint.format = { current: served, best: record.fix.format };
+        if (record.fix.vector !== undefined)
+            hint.vector = { ...record.fix.vector, servedPerView: Math.round(perViewBytesOf(record)) };
+        if (record.hidden !== undefined)
+            hint.hidden = record.hidden;
         if (record.fix.animated !== undefined) {
             hint.animated = record.fix.animated;
             if (record.current.src !== undefined)
@@ -223,6 +235,40 @@ export function hintsOf(result, qualities, plan) {
         return hint;
     });
 }
+/**
+ * An image gets a vector hint when its SVG passed the check (a claim), or when it is flat, was not traced to a passing SVG,
+ * and is big enough to matter (an informational note with no byte claim).
+ */
+export function vectorHinted(record) {
+    const vector = record.fix.vector;
+    if (vector === undefined)
+        return false;
+    if (vector.passed === true)
+        return true;
+    return perViewBytesOf(record) >= VECTOR_LOOKS_MIN_BYTES;
+}
+/** The vector check's lines of a hint: the SVG that passed, or the note on a flat image with no passing SVG. */
+export function vectorLines(vector) {
+    if (vector.passed === true && vector.svgBytes !== undefined && vector.score !== undefined) {
+        const traced = vector.tracedFile !== undefined ? `, traced one: ${safeText(vector.tracedFile)}` : "";
+        return [
+            `   vector art: serve SVG, ~${kb1(vector.svgBytes)} (br) vs ${kb1(vector.servedPerView)} now, sharp at every DPR; fidelity ${Math.round(vector.score)} at half size (bar ${VECTOR_BAR}); prefer your source SVG${traced}`,
+        ];
+    }
+    if (vector.servedPerView >= VECTOR_LOOKS_MIN_BYTES)
+        return ["   looks like vector art (flat colors); if a source SVG exists, serve it"];
+    return [];
+}
+/**
+ * The one-line summary of a page's loaded-but-not-shown images: the count, bytes per view and the cases, as the text, Markdown
+ * and check outputs all print it. Undefined when there are none.
+ */
+export function hiddenSummaryLine(hidden) {
+    if (hidden === undefined || hidden.images === 0)
+        return undefined;
+    const { responsive, lazy, "never-shown-on-load": never } = hidden.cases;
+    return `loaded but not shown: ${hidden.images} image(s), ${kb(hidden.bytesPerView)}/view (responsive ${responsive}, lazy ${lazy}, never shown on load ${never}); not in the savings`;
+}
 /** The hints an argument set asks for: filtered, sorted by bytes saved (largest first), then offset and limited. */
 export function selectHints(hints, args) {
     const page = args.page?.toLowerCase();
@@ -239,6 +285,7 @@ export function selectHints(hints, args) {
         .slice(args.offset, args.offset + args.limit);
 }
 const kb = (bytes) => `${(bytes / 1024).toFixed(0)} KB`;
+const kb1 = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;
 /** The mark after a hint's file:line: an owner call site, or an unverified source. */
 export function locationNote(hint) {
     if (hint.kind === "owner")
@@ -254,17 +301,118 @@ export function qualityTarget(quality) {
     const allowed = quality.allowed !== undefined ? ` (allowed: ${quality.allowed.join(",")})` : "";
     return quality.snapFrom !== undefined ? ` q${quality.snapFrom} -> ${quality.target}${allowed}` : ` -> ${quality.target}${allowed}`;
 }
+/** The srcset advice of a plain image with no srcset: the variants to serve, and the srcset and sizes to add. */
+export function srcsetLineOf(srcset) {
+    const candidates = srcset.widths.map((w) => `… ${w}w`).join(", ");
+    const sizes = srcset.sizes !== undefined ? safeText(srcset.sizes) : "the rendered CSS width per viewport";
+    return `srcset: no srcset today; serve variants at ${srcsetWidthLabel(srcset.widths)} (largest needed ${srcset.largest} px) and add srcset="${candidates}" sizes="${sizes}"`;
+}
+/**
+ * The srcset advice of a call site, when every image in it is a plain image with no srcset: the union of their widths (at
+ * most the variant limit), the largest need, and the first measured sizes value. Undefined for any other group.
+ */
+export function groupSrcsetOf(group) {
+    const all = group.hints.flatMap((h) => (h.srcset !== undefined ? [h.srcset] : []));
+    if (all.length === 0 || all.length !== group.hints.length)
+        return undefined;
+    const widths = srcsetWidthsOf(all.flatMap((s) => s.widths), undefined);
+    const sizes = all.find((s) => s.sizes !== undefined)?.sizes;
+    return { widths, largest: Math.max(...all.map((s) => s.largest)), ...(sizes !== undefined ? { sizes } : {}) };
+}
 /**
  * The saving of one image or one call site, per view, split into its parts when the scan gave them: "saves 15 KB/view =
  * sizes 12 KB + quality 3 KB". A quality part that a snap voided is printed as void, not as a number.
  */
 export function savesText(hint) {
-    const { saved, sizes, quality } = hint.bytes;
+    const { saved, sizes, quality, resize } = hint.bytes;
+    if (resize !== undefined) {
+        const parts = [sizes !== undefined && sizes > 0 ? `sizes ${kb(sizes)}` : undefined, `resize ${kb(resize)}`, (quality ?? 0) > 0 ? `quality ${kb(quality ?? 0)}` : undefined];
+        return `saves ${kb(saved)}/view = ${parts.filter((p) => p !== undefined).join(" + ")}`;
+    }
     if (sizes === undefined)
         return `saves ${kb(saved)}/view`;
     const qualityPart = hint.quality?.void === true ? "quality void after snap" : `quality ${kb(quality ?? 0)}`;
     return `saves ${kb(saved)}/view = sizes ${kb(sizes)} + ${qualityPart}`;
 }
+/** The media condition that splits a responsive twin's viewports: a min-width or max-width at the default widths. */
+function twinMediaOf(hidden) {
+    const hiddenAt = hidden.viewports.map((name) => hidden.widths[name]);
+    const shownAt = hidden.shownIn.map((name) => hidden.widths[name]);
+    if (hiddenAt.some((w) => !(w > 0)) || shownAt.some((w) => !(w > 0)))
+        return "(min-width: <breakpoint>px)";
+    // Shown at the wider viewports: the file goes from the breakpoint up, at the narrowest shown width.
+    if (Math.max(...hiddenAt) < Math.min(...shownAt))
+        return `(min-width: ${Math.min(...shownAt)}px)`;
+    // Shown at the narrower viewports: the file goes up to the widest shown width.
+    if (Math.min(...hiddenAt) > Math.max(...shownAt))
+        return `(max-width: ${Math.max(...shownAt)}px)`;
+    return "(min-width: <breakpoint>px)";
+}
+/**
+ * The lines of a loaded-but-not-shown image: where it is hidden, its bytes per view (kept apart from the saving), and the fix
+ * for its case (see HiddenFix.action). Page-derived viewport names are printed as JSON strings.
+ */
+export function hiddenLines(hidden) {
+    const names = (list) => list.map((v) => JSON.stringify(safeText(v))).join(", ");
+    const reasons = [
+        ...hidden.reasons,
+        ...(hidden.inPanel ? ["in a tab panel, a hidden subtree or a closed details"] : []),
+        ...(hidden.hover === true ? ["shown on hover"] : []),
+    ].join(", ");
+    const lines = [
+        `   loaded but not shown on load: ${kb(hidden.perViewBytes)}/view, hidden at ${hidden.viewports.length} of ${hidden.of} viewport(s) (${names(hidden.viewports)}): ${safeText(reasons)}; not in the saving`,
+    ];
+    if (hidden.unstable === "unknown")
+        lines.push("   unstable: unknown (not verified: a name on the page did not resolve, or the candidate cap was reached): the reason is the first read's; check it in a browser");
+    if (hidden.action === "responsive") {
+        lines.push(`   responsive twin, shown on load at ${names(hidden.shownIn)}: serve one file per viewport. Replace the two elements with <picture><source media="${twinMediaOf(hidden)}" srcset="<the file shown there>"><img …></picture>, or delete the hidden copy if the design does not need it.`);
+    }
+    else if (hidden.action === "lazy") {
+        const what = hidden.hover === true ? "a hover swap" : hidden.inPanel ? "a tab panel, a hidden subtree or a closed details" : "a carousel slide or other clipped box";
+        if (hidden.alreadyLazy === true) {
+            // loading="lazy" is already there: the browser still loads it because it is inside its lazy-load distance, so adding it again changes nothing.
+            lines.push(`   ${what} (${names(hidden.viewports)}): already lazy (loading="lazy") and still loaded, as it is within the browser's lazy-load distance of the viewport. Render it on activation (when the tab, details or hover opens), do not add lazy again.`);
+        }
+        else {
+            lines.push(`   ${what} (${names(hidden.viewports)}): add loading="lazy", or load it on demand (when the tab, details or hover opens).`);
+        }
+    }
+    else {
+        lines.push(`   never shown on load at any of ${hidden.of} viewport(s): remove it, or load it on demand (when the menu, modal or hover opens).`);
+    }
+    return lines;
+}
+/**
+ * The loaded-but-not-shown lines of one video (see HiddenFix): its bytes per view, the case and the fix. The responsive case
+ * names the one element with <source media>; the lazy one preload none, no autoplay until shown; the never-shown one removal
+ * or an on-demand load. The bytes are not in the saving, as an image's are not.
+ */
+export function videoHiddenLines(hidden) {
+    const names = (list) => list.map((v) => JSON.stringify(safeText(v))).join(", ");
+    const reasons = [
+        ...hidden.reasons,
+        ...(hidden.inPanel ? ["in a tab panel, a hidden subtree or a closed details"] : []),
+        ...(hidden.hover === true ? ["shown on hover"] : []),
+    ].join(", ");
+    const lines = [
+        `   loaded but not shown on load: ${kb(hidden.perViewBytes)}/view, hidden at ${hidden.viewports.length} of ${hidden.of} viewport(s) (${names(hidden.viewports)}): ${safeText(reasons)}; not in the savings`,
+    ];
+    if (hidden.unstable === "unknown")
+        lines.push("   unstable: unknown (not verified: a name on the page did not resolve, or the candidate cap was reached): the reason is the first read's; check it in a browser");
+    if (hidden.action === "responsive") {
+        const media = twinMediaOf(hidden);
+        lines.push(`   responsive twin, shown on load at ${names(hidden.shownIn)}: one <video> for both viewports, not two: <video autoplay muted playsinline poster="<first frame>"> with <source media="${media}" src="<the file shown at ${names(hidden.viewports)}>" type="video/mp4"> first, then <source src="<the file shown at ${names(hidden.shownIn)}>" type="video/mp4"> with no media. Or delete the hidden copy if the design does not need it.`);
+        lines.push(`     <source media> on video: Chrome and Edge 120+ and Firefox 120+ restored support; Safari has always supported it. A browser that ignores it takes the first source, so the fallback is a script that sets src from matchMedia("${media}") and reloads on change.`);
+    }
+    else if (hidden.action === "lazy") {
+        const what = hidden.hover === true ? "a hover swap" : hidden.inPanel ? "a tab panel, a hidden subtree or a closed details" : "a carousel slide or other clipped box";
+        lines.push(`   ${what} (${names(hidden.viewports)}): preload="none", no autoplay until it is shown (an IntersectionObserver, or the tab, details or hover opens), and the poster only.`);
+    }
+    else {
+        lines.push(`   never shown on load at any of ${hidden.of} viewport(s): remove it, or load it on demand (when the modal, menu or hover opens).`);
+    }
+    return lines;
+}
 /** One hint as four short lines: where, sizes, quality and format, bytes and rung. */
 export function renderHint(hint, rank) {
     // Page-derived names and attributes are printed as JSON strings, so a newline or an instruction inside them stays data.
@@ -281,6 +429,10 @@ export function renderHint(hint, rank) {
     ].filter((a) => a !== undefined);
     if (attributes.length > 0)
         lines.push(`   ${attributes.join("  ")}`);
+    // A vector check that wins leads the hint; otherwise it follows the raster fixes (see below).
+    const vector = hint.vector !== undefined ? vectorLines(hint.vector) : [];
+    if (hint.vector?.wins === true)
+        lines.push(...vector);
     // The name is an identifier (COMPONENT_NAME), so it prints bare; the glob is built from the same name.
     if (hint.kind === "owner") {
         const name = hint.component[0];
@@ -290,9 +442,20 @@ export function renderHint(hint, rank) {
     }
     if (hint.find)
         lines.push(`   find: ${hint.find.component} in ${hint.find.glob}`);
+    if (hint.hidden !== undefined)
+        lines.push(...hiddenLines(hint.hidden));
+    // An image never shown has no sizes, quality or format change to print: its fix is the hidden block above.
+    if (hint.hidden !== undefined && hint.hidden.shownIn.length === 0) {
+        if (hint.file === undefined && hint.find === undefined && hint.kind !== "owner")
+            lines.push("   owner unknown");
+        lines.push(`   rung ${hint.rung}`);
+        return lines;
+    }
     if (hint.width !== undefined)
         lines.push(`   width ${hint.width}px (device pixels needed)`);
-    else if (hint.animated === undefined || hint.sizes.proposed !== undefined) {
+    if (hint.srcset !== undefined)
+        lines.push(`   ${srcsetLineOf(hint.srcset)}`);
+    else if (hint.width === undefined && (hint.animated === undefined || hint.sizes.proposed !== undefined)) {
         lines.push(`   sizes ${safeText(hint.sizes.current ?? "none")} -> ${safeText(hint.sizes.proposed ?? "-")} (${hint.sizes.basis ?? "-"})`);
     }
     if (hint.sizesAuto !== undefined)
@@ -319,6 +482,8 @@ export function renderHint(hint, rank) {
     // An animated hint's saving is an estimate from the sample encodes, and its rung is that estimate, not the image measurement.
     const animated = hint.animated !== undefined;
     lines.push(`   ${savesText(hint)}${animated ? " est." : ""}, +${kb(hint.bytes.addedForSharpness)} sharpness (separate)  rung ${animated ? "estimate" : hint.rung}`);
+    if (hint.vector !== undefined && hint.vector.wins !== true)
+        lines.push(...vector);
     return lines;
 }
 /** The group a hint belongs to: its file:line, else its nearest component, else its selector. */
@@ -429,6 +594,8 @@ export function groupSizesOf(group) {
  * otherwise the pages' values: when they differ, the component is shared and each caller passes its own sizes.
  */
 export function combinedSizes(group) {
+    if (groupSrcsetOf(group) !== undefined)
+        return "no sizes: the images have no srcset (see srcset)";
     const fitted = groupSizesOf(group);
     if (fitted?.mode === "one") {
         return `${fitted.value} (one formula over ${group.hints.length} image(s), checked at ${fitted.views} viewport(s): never below a measured width)`;
@@ -453,7 +620,14 @@ export function groupHeadLine(group, rank) {
         : JSON.stringify(first.component[0] ?? first.selector);
     const name = first.file !== undefined && first.component[0] !== undefined ? ` (${JSON.stringify(first.component[0])})` : "";
     const sizes = group.hints.every((h) => h.bytes.sizes !== undefined) ? group.hints.reduce((sum, h) => sum + (h.bytes.sizes ?? 0), 0) : undefined;
-    const split = sizes !== undefined ? ` = sizes ${kb(sizes)} + quality ${kb(group.saved - sizes)}` : "";
+    const resize = group.hints.every((h) => h.bytes.resize !== undefined) ? group.hints.reduce((sum, h) => sum + (h.bytes.resize ?? 0), 0) : undefined;
+    let split = sizes !== undefined ? ` = sizes ${kb(sizes)} + quality ${kb(group.saved - sizes)}` : "";
+    if (resize !== undefined) {
+        const sized = sizes ?? 0;
+        const quality = Math.max(0, group.saved - sized - resize);
+        const parts = [sized > 0 ? `sizes ${kb(sized)}` : undefined, `resize ${kb(resize)}`, quality > 0 ? `quality ${kb(quality)}` : undefined];
+        split = ` = ${parts.filter((p) => p !== undefined).join(" + ")}`;
+    }
     const lcp = group.hints.find((h) => h.lcp === true);
     const lcpPrefix = lcp !== undefined ? `LCP image (${(lcp.lcpViewports ?? []).map((v) => safeText(v)).join(", ")}): ` : "";
     return `${rank}. ${lcpPrefix}${where}${name}  ${group.hints.length} image(s), ${group.pages.length} page(s)  saves ${kb(group.saved)}/view${split}`;
@@ -485,7 +659,8 @@ export function renderGroup(group, rank) {
         }
     }
     const fitted = groupSizesOf(group);
-    lines.push(`   sizes: ${safeText(combinedSizes(group))}`);
+    const srcset = groupSrcsetOf(group);
+    lines.push(srcset !== undefined ? `   ${srcsetLineOf(srcset)}` : `   sizes: ${safeText(combinedSizes(group))}`);
     for (const page of group.pages) {
         const mine = group.hints.filter((h) => h.page === page);
         const current = [...new Set(mine.map((h) => h.sizes.current ?? "none"))].map((v) => JSON.stringify(safeText(v))).join(", ");
@@ -495,7 +670,11 @@ export function renderGroup(group, rank) {
             : [...new Set(mine.map((h) => h.sizes.proposed ?? "-"))].map((v) => JSON.stringify(safeText(v))).join(", ");
         const widths = mine.flatMap((h) => (h.rendered ? [h.rendered.min, h.rendered.max] : []));
         const rendered = widths.length > 0 ? `${Math.min(...widths)}-${Math.max(...widths)} px` : "not rendered";
-        lines.push(`   ${JSON.stringify(pathOf(page))}  ${mine.length} image(s)  current ${current}  proposed ${proposed}  rendered ${rendered}`);
+        // A srcset group has no sizes change to print: its page line keeps the images and the rendered widths only.
+        if (srcset !== undefined)
+            lines.push(`   ${JSON.stringify(pathOf(page))}  ${mine.length} image(s)  rendered ${rendered}`);
+        else
+            lines.push(`   ${JSON.stringify(pathOf(page))}  ${mine.length} image(s)  current ${current}  proposed ${proposed}  rendered ${rendered}`);
     }
     const targets = group.hints.flatMap((h) => (h.quality ? [h.quality] : []));
     if (targets.length > 0) {
@@ -550,7 +729,8 @@ const FORMAT_LABEL = { gif: "GIF", webp: "WebP", apng: "APNG" };
  * says so: performance before precision, but the number is never presented as a measured CPU encode.
  */
 export function estLabel(c) {
-    return c.encoder === "nvenc" ? "est. (GPU-encoded, scaled to a CPU encode ÷1.4)" : "est.";
+    const base = c.encoder === "nvenc" ? "est. (GPU-encoded, scaled to a CPU encode ÷1.4)" : "est.";
+    return c.timeLimited === true ? `${base}, search stopped at the time limit` : base;
 }
 /**
  * The quality mark of a candidate: an NVENC candidate's cq is read as the CPU CRF (the same number, a fixed offset of 0), so
@@ -749,7 +929,63 @@ export function videoTotalsLine(videos) {
     const sum = (values) => values.reduce((total, v) => total + v, 0);
     const savings = files.map(videoSavingOf);
     const est = files.some((v) => v.steps !== undefined && v.estimate !== undefined) ? " est." : "";
-    return `video: ${kb(sum(files.map((v) => v.bytes.perView)))}/view, ${kb(sum(files.map((v) => v.bytes.perPlay)))}/play, saveable ${kb(sum(savings.map((s) => s.view)))}/view (${kb(sum(savings.map((s) => s.play)))}/play)${est}`;
+    const hidden = hiddenVideoTotalOf(videos);
+    const loaded = hidden === undefined ? "" : `; loaded but not shown ${kb(hidden.bytes)}/view in ${hidden.count} video(s), not in the savings`;
+    return `video: ${kb(sum(files.map((v) => v.bytes.perView)))}/view, ${kb(sum(files.map((v) => v.bytes.perPlay)))}/play, saveable ${kb(sum(savings.map((s) => s.view)))}/view (${kb(sum(savings.map((s) => s.play)))}/play)${est}${loaded}`;
+}
+/**
+ * The loaded-but-not-shown total of some videos: the records that have a hidden fix, their count and bytes per view. A file
+ * several hidden records share (the same src) counts its bytes once, at its largest record, as the images do (hiddenTotalsOf).
+ */
+function hiddenVideoTotalOf(videos) {
+    const hidden = videos.flatMap((v, index) => (v.hidden !== undefined ? [{ key: v.src || `#${index}`, fix: v.hidden }] : []));
+    if (hidden.length === 0)
+        return undefined;
+    const cases = { responsive: 0, lazy: 0, "never-shown-on-load": 0 };
+    const perFile = new Map();
+    for (const { key, fix } of hidden) {
+        cases[fix.action]++;
+        perFile.set(key, Math.max(perFile.get(key) ?? 0, fix.perViewBytes));
+    }
+    return { count: hidden.length, bytes: [...perFile.values()].reduce((sum, bytes) => sum + bytes, 0), cases };
+}
+/**
+ * The one-line summary of a page's loaded-but-not-shown videos, as the text, Markdown and check outputs print it. Undefined
+ * when no video has a hidden fix.
+ */
+export function hiddenVideoSummaryLine(videos) {
+    const total = hiddenVideoTotalOf(videos);
+    return total === undefined ? undefined : hiddenVideoLine(total);
+}
+/** The one-line text of a video total (the page's line, or the PR comment's over all pages). */
+function hiddenVideoLine(total) {
+    const { responsive, lazy, "never-shown-on-load": never } = total.cases;
+    return `loaded but not shown: ${total.count} video(s), ${kb(total.bytes)}/view (responsive ${responsive}, lazy ${lazy}, never shown on load ${never}); not in the savings`;
+}
+/**
+ * The loaded-but-not-shown line of the PR comment for videos: all ok pages together. Each page counts its own files (a file
+ * shared between two pages is two files' bytes), as hiddenPagesLine does for images.
+ */
+export function hiddenVideoPagesLine(results) {
+    const totals = {
+        count: 0,
+        bytes: 0,
+        cases: { responsive: 0, lazy: 0, "never-shown-on-load": 0 },
+    };
+    for (const page of results) {
+        if (page.status !== "ok")
+            continue;
+        const total = hiddenVideoTotalOf(page.videos ?? []);
+        if (total === undefined)
+            continue;
+        totals.count += total.count;
+        totals.bytes += total.bytes;
+        for (const key of Object.keys(totals.cases))
+            totals.cases[key] += total.cases[key];
+    }
+    if (totals.count === 0)
+        return undefined;
+    return hiddenVideoLine(totals);
 }
 /** A video's encode in one phrase: the encode at its width with its bytes, or why it was not encoded. */
 export function videoStatusOf(video) {
@@ -858,6 +1094,13 @@ function targetLines(video, plan) {
 export function videoLines(video, rank = 1) {
     const lines = [`${rank}. ${safeText(video.id)}  ${JSON.stringify(safeText(videoWhere(video)))}  ${safeText(video.page)}`];
     lines.push(`   bytes: ${kb(video.bytes.perView)}/view (${viewBasisOf(video)}), ${kb(video.bytes.perPlay)}/play`);
+    if (video.hidden !== undefined)
+        lines.push(...videoHiddenLines(video.hidden));
+    // A video no viewport shows has no claim: no encode, source, width, loading or codec line, only its hidden fix.
+    if (video.hidden !== undefined && video.hidden.shownIn.length === 0) {
+        lines.push(`   not encoded: ${reasonText(NEVER_SHOWN)}`);
+        return lines;
+    }
     const est = video.estimate;
     if (est !== undefined && video.steps !== undefined) {
         const s = video.steps;
@@ -947,6 +1190,18 @@ function videosOf(results, args) {
     const page = args.page?.toLowerCase();
     return results.flatMap((r) => r.videos ?? []).filter((v) => page === undefined || v.page.toLowerCase().includes(page));
 }
+/** The resource findings of the selected pages, one row per finding with its page (the JSON's `resources`). */
+function resourceRowsOf(results) {
+    return results.flatMap((r) => (r.resources ?? []).map((f) => ({ page: r.url, kind: f.kind, url: f.url, bytes: f.bytes, savedBytes: f.savedBytes, estimate: f.estimate, title: f.title, fix: f.fix })));
+}
+/** The text block of the resource findings, one heading per page that has any (none when no page has any). */
+function renderResourceHints(results) {
+    const pages = results.filter((r) => (r.resources ?? []).length > 0);
+    if (pages.length === 0)
+        return "";
+    const body = pages.flatMap((r) => [`${pathOf(r.url)} (resources)`, ...resourceLinesOf(r.resources ?? [], (text) => safeText(text))]);
+    return `${body.join("\n")}\n`;
+}
 /** `imgtune hints <scan.json> [<scan.json> ...] ...`: reads the pages' scan files, returns the text or JSON to print. */
 export async function hintsCommand(argv, cwd) {
     const args = parseHintsArgs(argv);
@@ -978,12 +1233,13 @@ export async function hintsCommand(argv, cwd) {
         notes.push(`${dropped} sizes proposal(s) left out: no saving (their predicted outcome adds bytes or changes nothing)`);
     const filtered = selectHints(all, { ...args, limit: Number.MAX_SAFE_INTEGER, offset: 0 });
     const videos = videosOf(results, args);
+    const resourceRows = resourceRowsOf(results);
     if (args.top !== undefined) {
         const top = groupHints(filtered).slice(0, args.top);
         if (args.format === "json") {
-            return { output: `${JSON.stringify({ top: top.map((g, i) => ({ rank: i + 1, key: g.key, saved: g.saved, images: g.hints.length, pages: g.pages.map((p) => pathOf(p)), file: g.hints[0].file ?? null, line: g.hints[0].line ?? null, component: g.hints[0].component, sizes: combinedSizes(g) })), qualities: planJson(plan) }, null, 2)}\n`, exitCode: 0 };
+            return { output: `${JSON.stringify({ top: top.map((g, i) => ({ rank: i + 1, key: g.key, saved: g.saved, images: g.hints.length, pages: g.pages.map((p) => pathOf(p)), file: g.hints[0].file ?? null, line: g.hints[0].line ?? null, component: g.hints[0].component, sizes: combinedSizes(g), srcset: groupSrcsetOf(g) ?? null })), qualities: planJson(plan) }, null, 2)}\n`, exitCode: 0 };
         }
-        return { output: `${notes.length > 0 ? `${notes.join("\n")}\n` : ""}${renderTop(top)}${renderVideoHints(videos)}`, exitCode: 0 };
+        return { output: `${notes.length > 0 ? `${notes.join("\n")}\n` : ""}${renderTop(top)}${renderVideoHints(videos)}${renderResourceHints(results)}`, exitCode: 0 };
     }
     // JSON is not cut to the text default: it is all of it unless --limit is passed, and `truncated` says whether it is.
     const jsonLimit = args.limitGiven ? args.limit : Number.MAX_SAFE_INTEGER;
@@ -1012,15 +1268,17 @@ export async function hintsCommand(argv, cwd) {
                     saved: group.saved,
                     sizes: combinedSizes(group),
                     sizesFitted: groupSizesOf(group) ?? null,
+                    srcset: groupSrcsetOf(group) ?? null,
                     callers: callerMapOf(group) ?? null,
                     ids: group.hints.map((h) => h.id),
                     hints: group.hints,
                 })),
                 ...(videos.length > 0 ? { videos } : {}),
+                ...(resourceRows.length > 0 ? { resources: resourceRows } : {}),
             };
             return { output: `${JSON.stringify(body, null, 2)}\n`, exitCode: 0 };
         }
-        const text = `${renderGroups(selectedGroups, groups.length, filtered.length, args.offset, args.page)}${renderVideoHints(videos)}`;
+        const text = `${renderGroups(selectedGroups, groups.length, filtered.length, args.offset, args.page)}${renderVideoHints(videos)}${renderResourceHints(results)}`;
         return { output: notes.length > 0 ? `${notes.join("\n")}\n${text}` : text, exitCode: 0 };
     }
     const selected = selectHints(all, args.format === "json" ? { ...args, limit: jsonLimit } : args);
@@ -1036,10 +1294,11 @@ export async function hintsCommand(argv, cwd) {
             qualities: planJson(plan),
             hints: selected,
             ...(videos.length > 0 ? { videos } : {}),
+            ...(resourceRows.length > 0 ? { resources: resourceRows } : {}),
         };
         return { output: `${JSON.stringify(body, null, 2)}\n`, exitCode: 0 };
     }
-    const text = `${renderHints(selected, filtered.length, args.offset, args.page)}${renderVideoHints(videos)}`;
+    const text = `${renderHints(selected, filtered.length, args.offset, args.page)}${renderVideoHints(videos)}${renderResourceHints(results)}`;
     return { output: notes.length > 0 ? `${notes.join("\n")}\n${text}` : text, exitCode: 0 };
 }
 /** How many hints the PR comment lists. */
@@ -1056,6 +1315,21 @@ export function commentHints(results, limit = COMMENT_HINTS, maxQualities) {
     const top = selectHints(all, { limit, offset: 0 });
     return { total: all.length, lines: top.map((hint, i) => `${i + 1}. ${commentLine(hint)}`) };
 }
+/** The loaded-but-not-shown line of the PR comment: all ok pages together (the same numbers as the text output). */
+export function hiddenPagesLine(results) {
+    const pages = results.filter((r) => r.status === "ok" && r.hidden !== undefined);
+    if (pages.length === 0)
+        return undefined;
+    const totals = { images: 0, bytesPerView: 0, cases: { responsive: 0, lazy: 0, "never-shown-on-load": 0 } };
+    for (const page of pages) {
+        const hidden = page.hidden;
+        totals.images += hidden.images;
+        totals.bytesPerView += hidden.bytesPerView;
+        for (const key of Object.keys(totals.cases))
+            totals.cases[key] += hidden.cases[key];
+    }
+    return hiddenSummaryLine(totals);
+}
 /**
  * A page-derived value in the comment: capped at COMMENT_FIELD characters, then JSON-quoted the way the CLI text prints it
  * (so an instruction inside a name stays a quoted string). The block is fenced, and GitHub does not decode entities inside
@@ -1071,9 +1345,11 @@ function commentLine(hint) {
         ? `${quoted(`${hint.file}:${hint.line ?? 0}`)}${locationNote(hint)}`
         : quoted(hint.component[0] ?? hint.selector);
     const component = hint.file !== undefined && hint.component[0] !== undefined ? ` (${quoted(hint.component[0])})` : "";
-    const sizes = hint.width !== undefined
-        ? `width ${hint.width}px`
-        : `sizes ${quoted(hint.sizes.current ?? "none")} -> ${quoted(hint.sizes.proposed ?? "-")}`;
+    const sizes = hint.srcset !== undefined
+        ? `serve variants at ${srcsetWidthLabel(hint.srcset.widths)}`
+        : hint.width !== undefined
+            ? `width ${hint.width}px`
+            : `sizes ${quoted(hint.sizes.current ?? "none")} -> ${quoted(hint.sizes.proposed ?? "-")}`;
     const parts = [
         hint.lcp === true ? `LCP image (${(hint.lcpViewports ?? []).map((v) => quoted(v)).join(", ")})` : undefined,
         `${savesText(hint)}, +${kb(hint.bytes.addedForSharpness)} sharpness`,