imgtune 0.1.0 → 0.3.0

package/dist/hints.js

@@ -7,7 +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) {
@@ -98,7 +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) {
-    return (result.images ?? []).filter(hasFix).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
@@ -117,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,
@@ -169,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
@@ -202,15 +212,63 @@ 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)
+                hint.src = record.current.src;
+            // The animated saving is the encode's alone (est.): the target is encoded at the needed width, so perViewBytes less the
+            // target's bytes already holds the width change. Adding the record's sizes part would count it twice. A real sizes
+            // proposal is still printed as information (renderHint), but it adds nothing to the saving.
+            const encoded = animatedSavingOf(record.fix.animated);
+            hint.bytes = { saved: encoded, addedForSharpness: record.fix.bytes.addedForSharpness, quality: encoded };
+        }
         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();
@@ -227,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")
@@ -242,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.
@@ -269,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];
@@ -278,10 +442,22 @@ 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.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)
         lines.push(`   alternative: sizes="${safeText(hint.sizesAuto)}" (Chrome, Edge, Firefox 150+; Safari falls back to ${safeText(hint.sizes.proposed ?? "-")})`);
     if (hint.via === "prod-sourcemap") {
@@ -292,6 +468,8 @@ export function renderHint(hint, rank) {
     }
     else if (hint.file === undefined && hint.find === undefined && hint.kind !== "owner")
         lines.push("   owner unknown");
+    if (hint.animated !== undefined)
+        lines.push(...animatedLines(hint.animated, hint.src, hint.alt));
     const parts = [];
     if (hint.quality)
         parts.push(`quality ${hint.quality.current}${qualityTarget(hint.quality)} (max of ${hint.quality.samples}, ${safeText(hint.quality.group)})`);
@@ -301,7 +479,11 @@ export function renderHint(hint, rank) {
         lines.push(`   ${parts.join("  ")}`);
     if (hint.qualityNote !== undefined)
         lines.push(`   ${safeText(hint.qualityNote)}`);
-    lines.push(`   ${savesText(hint)}, +${kb(hint.bytes.addedForSharpness)} sharpness (separate)  rung ${hint.rung}`);
+    // 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. */
@@ -412,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)`;
@@ -436,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}`;
@@ -468,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(", ");
@@ -478,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) {
@@ -493,6 +689,11 @@ export function renderGroup(group, rank) {
     const ids = group.hints.map((h) => h.id);
     const shown = ids.slice(0, 8).join(" ");
     lines.push(`   ids ${shown}${ids.length > 8 ? ` (+${ids.length - 8} more; --flat lists each image)` : ""}`);
+    // An animated image's hint is its own (its target and bytes are not a sizes or quality change), so it is printed here.
+    for (const hint of group.hints) {
+        if (hint.animated !== undefined)
+            lines.push(`   ${safeText(hint.id)}`, ...animatedLines(hint.animated, hint.src));
+    }
     return lines;
 }
 /** The text of a grouped selection: a count line, then each group. */
@@ -511,6 +712,450 @@ export function renderHints(hints, total, offset, page) {
     const body = hints.flatMap((hint, i) => renderHint(hint, offset + i + 1));
     return `${head}${body.join("\n")}\n`;
 }
+// ---------------------------------------------------------------------------------------------------------------------
+// Animated images and `<video>` (Task 8): the text of their hints and of the Video section of a page. Every estimated byte
+// figure is marked "est."; a hint names the sample encodes once. Page-derived names and attributes are JSON strings.
+// ---------------------------------------------------------------------------------------------------------------------
+/** The note that marks a figure as an estimate from the 2-second sample encodes. A hint says it once. */
+export const SAMPLE_NOTE = "(estimate from 2 s samples)";
+/** The `type` of the two sources a video hint names: AV1 first, H.264 as the fallback. */
+const AV1_TYPE = 'video/mp4; codecs=av01.0.08M.08';
+const H264_TYPE = 'video/mp4; codecs=avc1.640028';
+/** The H.264 fallback recipe an animated GIF's video hint gives. It is not encoded by imgtune (performance first). */
+const H264_RECIPE = "libx264 -preset veryfast -crf 23 -pix_fmt yuv420p -movflags +faststart -an";
+const FORMAT_LABEL = { gif: "GIF", webp: "WebP", apng: "APNG" };
+/**
+ * The label of a candidate's bytes. An NVENC candidate's bytes are its GPU encode scaled to a CPU encode (÷1.4), so the label
+ * says so: performance before precision, but the number is never presented as a measured CPU encode.
+ */
+export function estLabel(c) {
+    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
+ * the recipe's CRF is approximate. Empty for a CPU encode.
+ */
+export function qualityApprox(c) {
+    return c.encoder === "nvenc" ? " (approx.)" : "";
+}
+/** The smallest candidate of one codec, or undefined. The first of equal bytes wins. */
+export function smallestCandidate(candidates, codec) {
+    let best;
+    for (const c of candidates ?? []) {
+        if (c.codec === codec && (best === undefined || c.bytes < best.bytes))
+            best = c;
+    }
+    return best;
+}
+/**
+ * The quality evidence of an encode: VMAF with its bar, and the still-frame guard with its bar. A bar the candidate does not
+ * carry is said so, not guessed: the run's flag is not in the scan file.
+ */
+export function evidenceOf(c) {
+    const bar = (value) => (value === undefined ? "bar not recorded" : `bar ${value}`);
+    return `VMAF ${c.vmaf.toFixed(1)} (${bar(c.vmafBar)}), still ${c.still.toFixed(1)} (${bar(c.stillBar)})`;
+}
+/** The codec as a hint names it: "av1", "h264", or the codec's own name. */
+function codecName(codec) {
+    return codec === "av1-mp4" ? "av1" : codec === "h264-mp4" ? "h264" : codec;
+}
+/** The targets of an animated image's encode (see AnimatedTargets). The main one's bytes are the saving's basis. */
+export function animatedTargetsOf(animated) {
+    const avif = smallestCandidate(animated.estimate, "animated-avif");
+    const webp = smallestCandidate(animated.estimate, "animated-webp");
+    const av1 = smallestCandidate(animated.estimate, "av1-mp4");
+    const h264 = smallestCandidate(animated.estimate, "h264-mp4");
+    const video = av1 !== undefined && (animated.target?.main === "video" || (avif === undefined && webp === undefined));
+    return { avif, webp, av1, h264, video, main: video ? av1 : (avif ?? webp) };
+}
+/** The bytes per view an animated image saves: its bytes per view less the main target's encode, floored at 0 (est.). */
+export function animatedSavingOf(animated) {
+    const main = animatedTargetsOf(animated).main;
+    return main === undefined ? 0 : Math.max(0, animated.perViewBytes - main.bytes);
+}
+/**
+ * The fallback of an image-target hint, built only from the candidates that exist: the `<picture>` with an AVIF source (for
+ * AVIF, with or without WebP), a plain `src` swap for WebP alone (WebP animates everywhere it shows an image), and for a CSS
+ * background an `image-set()` with the existing types.
+ */
+function imageFallbackOf(context, targets, src) {
+    if (context === "css-background") {
+        const types = [
+            targets.avif !== undefined ? 'url(<avif>) type("image/avif")' : undefined,
+            targets.webp !== undefined ? 'url(<webp>) type("image/webp")' : undefined,
+        ].filter((t) => t !== undefined);
+        return `fallback: image-set(${types.join(", ")})`;
+    }
+    if (targets.avif !== undefined) {
+        return `fallback: <picture><source type="image/avif" srcset="…"><img src=${JSON.stringify(src ?? "")}></picture>`;
+    }
+    return "plain src swap to the animated WebP (WebP animates in every browser that shows the image)";
+}
+/** Browser coverage of each option, as the hint states it (the caniuse data is not in the repo: these are the stated facts). */
+const COVERAGE = {
+    webp: "animated WebP: all current browsers",
+    avif: "animated AVIF: Chrome 85+, Firefox 113+, Safari 16.4+",
+    av1: "AV1 video: Chrome, Firefox, Edge; Safari only on devices with AV1 hardware decode, so keep the H.264 fallback",
+};
+/**
+ * The exact encoder settings of a candidate, as an agent runs them: the encoder, its preset and CRF (or q), and the pixel
+ * format and container options that follow. An AV1 CRF is a CRF, never a q (see the quality label in animatedLines).
+ */
+export function encoderRecipe(codec, c) {
+    const av1 = c.av1Encoder === "libaom-av1" ? `libaom-av1 -cpu-used 8 -row-mt 1 -crf ${c.quality} -b:v 0` : `libsvtav1 -preset 10 -crf ${c.quality}`;
+    switch (codec) {
+        case "av1-mp4":
+            return `${av1} -pix_fmt yuv420p -movflags +faststart`;
+        case "animated-avif":
+            return `${av1}, -f avif`;
+        case "animated-webp":
+            return `libwebp_anim -q:v ${c.quality} -loop 0`;
+        case "h264-mp4":
+            return `libx264 -preset veryfast -crf ${c.quality} -pix_fmt yuv420p -movflags +faststart -an`;
+    }
+}
+/**
+ * The line that says a target is capped at the file's own width: the device width needs more than the file has, so the
+ * target is the file's width and a wider one would add bytes, not detail. Undefined when the target is not capped.
+ */
+export function sourceCapLine(need, sourceWidth, served) {
+    if (need === undefined || sourceWidth === undefined || !(need > sourceWidth) || served !== sourceWidth)
+        return undefined;
+    return `   source is ${sourceWidth}px wide; needed ${need}px: serve ${sourceWidth}px (upscaling adds bytes, not detail)`;
+}
+/**
+ * The lines of an animated image's hint. An image target (AVIF and/or WebP, with a fallback built from the candidates that
+ * exist) when the encode offers one; the `<video>` replacement with its AV1 source and the H.264 recipe when the target is
+ * video. With no encode, the bytes per view and the reason. `src` is the served file's URL, printed as a JSON string; `alt`
+ * is the image's alt text, which the `<video>` keeps as its accessible name.
+ */
+export function animatedLines(animated, src, alt) {
+    const { info, perViewBytes } = animated;
+    const head = `animated ${FORMAT_LABEL[info.format]} ${(info.durationMs / 1000).toFixed(1)} s, ${info.frames} frames`;
+    const targets = animatedTargetsOf(animated);
+    const { avif, webp, av1, h264, main } = targets;
+    if (main === undefined) {
+        return [`   ${head}: ${kb(perViewBytes)}/view; not encoded: ${safeText(reasonText(animated.notEncoded ?? "no passing quality"))}`];
+    }
+    const saves = animatedSavingOf(animated);
+    const offered = [
+        avif !== undefined ? `animated AVIF CRF ${avif.quality}${qualityApprox(avif)} at ${avif.width}px (${encoderRecipe("animated-avif", avif)}): ${kb(avif.bytes)} ${estLabel(avif)}` : undefined,
+        webp !== undefined ? `animated WebP q${webp.quality} at ${webp.width}px (${encoderRecipe("animated-webp", webp)}): ${kb(webp.bytes)} ${estLabel(webp)}` : undefined,
+    ].filter((part) => part !== undefined);
+    const coverage = [];
+    if (avif !== undefined)
+        coverage.push(COVERAGE.avif);
+    if (webp !== undefined)
+        coverage.push(COVERAGE.webp);
+    const cap = sourceCapLine(animated.need, animated.sourceWidth, main.width);
+    if (targets.video && av1 !== undefined) {
+        // An empty alt is a decorative image: the <video> is hidden from assistive technology, with no label. Otherwise the alt is
+        // kept as the accessible name (role="img", aria-label).
+        const decorative = alt !== undefined && alt.trim() === "";
+        const altPart = decorative
+            ? ' aria-hidden="true"'
+            : alt !== undefined
+                ? ` role="img" aria-label=${JSON.stringify(safeText(alt))}`
+                : "";
+        const lines = [`   ${head}: replace with <video autoplay muted loop playsinline poster="<first frame>"${altPart}>`];
+        if (decorative)
+            lines.push('     the image is decorative (alt=""): the <video> is aria-hidden, with no label');
+        else if (alt !== undefined)
+            lines.push("     the image's alt text is kept as the <video>'s aria-label (role=\"img\"): the accessible name does not change");
+        lines.push(`     <source src="…-${av1.width}.av1.mp4" type="${AV1_TYPE}"> AV1 MP4 (${encoderRecipe("av1-mp4", av1)}), CRF ${av1.quality}${qualityApprox(av1)}, ${av1.width}px, ${kb(av1.bytes)} ${estLabel(av1)}`);
+        lines.push(h264 !== undefined
+            ? `     <source src="…-${h264.width}.h264.mp4" type="${H264_TYPE}"> H.264 MP4 (${encoderRecipe("h264-mp4", h264)}), ${h264.width}px, ${kb(h264.bytes)} ${estLabel(h264)}`
+            : `     <source src="…-${av1.width}.h264.mp4" type="${H264_TYPE}"> H.264 fallback, not measured: ${H264_RECIPE} at ${av1.width}px wide`);
+        if (cap !== undefined)
+            lines.push(cap);
+        lines.push(`   evidence: ${evidenceOf(av1)}`);
+        lines.push(`   browsers: ${COVERAGE.av1}`);
+        if (offered.length > 0)
+            lines.push(`   alternative: ${offered.join(", ")}`);
+        if (offered.length > 0)
+            lines.push(...coverage.map((line) => `   browsers: ${line}`));
+        lines.push(`   saves ${kb(saves)}/view est. ${SAMPLE_NOTE}`);
+        return lines;
+    }
+    const fallback = imageFallbackOf(animated.context, targets, src);
+    const lines = [`   ${head}: serve ${offered.join(", ")}; ${fallback}; saves ${kb(saves)}/view est. ${SAMPLE_NOTE}`];
+    if (cap !== undefined)
+        lines.push(cap);
+    lines.push(`   evidence: ${evidenceOf(main)}`);
+    lines.push(...coverage.map((line) => `   browsers: ${line}`));
+    return lines;
+}
+/** The name a video records by: where it is in the page, a file or component, else its selector. */
+export function videoWhere(video) {
+    if (video.locator.file !== undefined)
+        return `${video.locator.file}:${video.locator.line ?? 0}`;
+    return video.locator.component[0] ?? video.locator.selector;
+}
+/**
+ * The bytes a view and a play save, est. The lever steps are per play (the full file less the encode); the view's share is
+ * the same fraction of the bytes the page loads per view.
+ */
+export function videoSavingOf(video) {
+    if (video.steps === undefined || video.estimate === undefined)
+        return { view: 0, play: 0 };
+    const { audio, resolution, codec, quality } = video.steps;
+    const play = audio + resolution + codec + quality;
+    const { perView, perPlay } = video.bytes;
+    return { view: perPlay > 0 ? (play * perView) / perPlay : 0, play };
+}
+/**
+ * One record per file of each page: a URL that two `<video>` elements of a page use is one file, fetched once per page view.
+ * Of the records sharing a URL, the one with the most bytes per view stands for it (the page's own elements keep their rows).
+ */
+export function onePerFile(videos) {
+    const byFile = new Map();
+    for (const video of videos) {
+        const key = `${video.page}\n${video.src}`;
+        const current = byFile.get(key);
+        if (current === undefined || video.bytes.perView > current.bytes.perView)
+            byFile.set(key, video);
+    }
+    return [...byFile.values()];
+}
+/**
+ * The Video section's totals: bytes per view and per play over the files (each URL once per page, see onePerFile), and the
+ * saveable bytes (an estimate, marked when any video has steps). Undefined with no video.
+ */
+export function videoTotalsLine(videos) {
+    if (videos.length === 0)
+        return undefined;
+    const files = onePerFile(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." : "";
+    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) {
+    const e = video.estimate;
+    if (e === undefined)
+        return `not encoded: ${safeText(reasonText(video.notEncoded ?? "no passing quality"))}`;
+    return `${codecName(e.codec)} CRF ${e.quality}${qualityApprox(e)}, ${e.width}px, ${kb(e.bytes)} ${estLabel(e)}`;
+}
+/** One video as a row of a page's Video section: its place (quoted by the caller), its bytes, and its encode or reason. */
+export function videoRowOf(video, quote) {
+    return `${quote(videoWhere(video))}: ${kb(video.bytes.perView)}/view, ${kb(video.bytes.perPlay)}/play; ${videoStatusOf(video)}`;
+}
+/** What the bytes per view are, as a hint says it: the autoplay full file, the bytes seen in the scan, or none. */
+function viewBasisOf(video) {
+    const b = video.bytes;
+    if (b.perViewBasis === "full-file")
+        return "autoplay: full file";
+    if (b.perViewBasis === "none")
+        return "not loaded before play";
+    return b.browserDependent ? "preload=auto: browser-dependent, bytes seen in the scan" : "bytes seen in the scan";
+}
+/**
+ * The bytes per view of a width plan (audit), est. (scaled): each viewport's bytes at its width are the encode's bytes times
+ * (w / w_encoded)², the pixel ratio, and the per-view share of the file. They are summed over the viewports and divided by
+ * their count, the same average the image savings use. Without an encode, "not encoded" and the reason.
+ */
+function bytesAtPlan(video, plan) {
+    const est = video.estimate;
+    if (est === undefined || video.bytes.perPlay <= 0) {
+        return `not encoded${video.notEncoded !== undefined ? `: ${safeText(reasonText(video.notEncoded))}` : ""}`;
+    }
+    if (plan.perViewport.length === 0)
+        return "-";
+    const ratio = video.bytes.perView / video.bytes.perPlay;
+    const total = plan.perViewport.reduce((sum, v) => sum + est.bytes * (v.width / est.width) ** 2 * ratio, 0);
+    return `${kb(total / plan.perViewport.length)}/view est. (scaled)`;
+}
+/** Audit: each viewport's need, and the bytes per view at one, two and three widths. No pick: the agent chooses. */
+function widthOptionLines(options) {
+    const lines = [];
+    const first = options[0];
+    if (first !== undefined && first.perViewport.length > 0) {
+        lines.push(`   viewports: ${first.perViewport.map((v) => `${JSON.stringify(safeText(v.viewport))} needs ${v.need}px`).join(", ")}`);
+    }
+    lines.push("   widths → bytes/view (audit: no pick)");
+    return lines;
+}
+/**
+ * The line that says a video's served width is capped at its file's own: a viewport needs more than the file has, and the
+ * plan serves the file's width. Undefined when no viewport is capped (or the file's width is not known).
+ */
+export function videoSourceCapLine(video) {
+    const source = video.probe?.width;
+    const plan = video.widths;
+    if (plan === undefined || source === undefined || !(source > 0))
+        return undefined;
+    // The plan's needs are already capped at the file's width, so the need is taken from the boxes: what the page shows.
+    const need = Math.max(0, ...video.perViewport.filter((v) => v.boxWidth > 0).map((v) => Math.ceil(v.boxWidth * v.dpr)));
+    if (!(need > source) || !plan.perViewport.some((row) => row.width === source))
+        return undefined;
+    return sourceCapLine(need, source, source);
+}
+/** Scan: the `<source>` list of the planned widths, AV1 then H.264 for each, with the encode's CRF and bytes at its width. */
+function targetLines(video, plan) {
+    if (plan.containerDriven) {
+        return plan.perViewport.map((row) => {
+            const box = video.perViewport.find((v) => v.viewport === row.viewport);
+            const boxText = box !== undefined ? `box ${box.boxWidth} px at ${box.dpr}x` : "box not read";
+            return `     viewport ${JSON.stringify(safeText(row.viewport))}: ${boxText}, serve ${row.width}px`;
+        });
+    }
+    const est = video.estimate;
+    const lines = [];
+    for (const source of plan.sources) {
+        const media = source.media !== undefined ? `media="${source.media}" ` : "";
+        for (const kind of ["av1", "h264"]) {
+            const codec = kind === "av1" ? "av1-mp4" : "h264-mp4";
+            const label = kind === "av1" ? "AV1" : "H.264";
+            // Every source names the exact encoder settings an agent runs: the estimate's codec, preset and CRF. At the estimate's
+            // own width that is measured; at another width the same settings apply, which is not measured there.
+            const same = est !== undefined && est.codec === codec ? est : undefined;
+            let at;
+            if (same !== undefined && same.width === source.width) {
+                at = ` ${label} MP4 (${encoderRecipe(codec, same)}), CRF ${same.quality}${qualityApprox(same)}, ${same.width}px, ${kb(same.bytes)} ${estLabel(same)}`;
+            }
+            else if (same !== undefined) {
+                at = ` ${label} MP4 (${encoderRecipe(codec, same)}), CRF ${same.quality}${qualityApprox(same)}, ${source.width}px: same settings, not measured at this width`;
+            }
+            else if (kind === "h264") {
+                at = ` H.264 MP4 (${H264_RECIPE}), ${source.width}px: not measured (no H.264 encode for this video)`;
+            }
+            else {
+                at = ` AV1 MP4 (libsvtav1 -preset 10 -pix_fmt yuv420p -movflags +faststart), CRF not measured: no AV1 encode passed for this video`;
+            }
+            lines.push(`     <source ${media}src="…-${source.width}.${kind}.mp4" type="${kind === "av1" ? AV1_TYPE : H264_TYPE}">${at}`);
+        }
+    }
+    return lines;
+}
+/**
+ * The lines of one video's hint: where and the bytes; the levers of the encode (audio, resolution, re-encode, one line each
+ * with its bytes per play; never a quality line, as the encode's quality is the re-encode); the loading, codec and poster
+ * levers; the target sources (or the widths table in audit); the evidence; and the saving. Without steps, the target and its
+ * bytes only. Without an encode, the reason.
+ */
+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;
+        lines.push(`   audio: drop the track (muted video): saves ${kb(s.audio)}/play est.`);
+        lines.push(`   resolution: serve ${est.width}px: saves ${kb(s.resolution)}/play est.`);
+        lines.push(`   re-encode (${codecName(est.codec)} CRF ${est.quality}): saves ${kb(s.codec)}/play est.`);
+    }
+    if (video.levers.loading !== undefined) {
+        const loading = video.levers.loading;
+        const attr = video.attributes.preload === "" ? "no preload attribute" : `preload=${JSON.stringify(safeText(video.attributes.preload))}`;
+        const action = video.attributes.autoplay
+            ? "autoplay fetches the file on load: lazy-load the video until it is in view"
+            : loading.belowFold
+                ? 'below the fold: set preload="none"'
+                : 'set preload="metadata"';
+        lines.push(`   loading: ${attr} loads ${kb(loading.perViewBytes)}/view before play: ${action}`);
+    }
+    if (video.levers.codec !== undefined)
+        lines.push("   codec: no AV1 source: serve AV1 first, H.264 fallback");
+    if (video.levers.posterMissing === true)
+        lines.push('   poster: none: add poster="<first frame>" (audited as an image)');
+    for (const note of video.levers.info)
+        lines.push(`   info: ${safeText(note)}`);
+    if (video.widthOptions !== undefined) {
+        lines.push(...widthOptionLines(video.widthOptions));
+        for (const plan of video.widthOptions) {
+            lines.push(`     ${plan.widths.length} width(s): ${plan.widths.map((w) => `${w}px`).join(", ")} → ${bytesAtPlan(video, plan)}`);
+        }
+    }
+    else if (video.widths !== undefined) {
+        lines.push(...targetLines(video, video.widths));
+        const cap = videoSourceCapLine(video);
+        if (cap !== undefined)
+            lines.push(cap);
+    }
+    if (est !== undefined)
+        lines.push(`   evidence: ${evidenceOf(est)}`);
+    else if (video.notEncoded !== undefined)
+        lines.push(`   not encoded: ${safeText(reasonText(video.notEncoded))}`);
+    if (est !== undefined && video.steps !== undefined) {
+        const s = videoSavingOf(video);
+        lines.push(`   saves ${kb(s.view)}/view est., ${kb(s.play)}/play est. ${SAMPLE_NOTE}`);
+    }
+    else if (est !== undefined) {
+        lines.push(`   ${SAMPLE_NOTE}`);
+    }
+    return lines;
+}
+/** The hints command's Video part: each video's hint, numbered. Empty with no video. */
+export function renderVideoHints(videos) {
+    if (videos.length === 0)
+        return "";
+    const body = videos.flatMap((video, i) => videoLines(video, i + 1));
+    return `${videos.length} video(s) on the page(s), self-hosted files:\n${body.join("\n")}\n`;
+}
 /**
  * The line that says where the sources of a file came from: the dev page it was located on, or, when hinted images still
  * have no file:line, the command that locates them. Undefined when every hint has its source.
@@ -538,6 +1183,25 @@ function planJson(plan) {
         estTotalBytes: Math.round(plan.total),
     };
 }
+/** The videos of the selected pages, for the hints command (none when a --component filter is given: videos have no sizes). */
+function videosOf(results, args) {
+    if (args.component !== undefined)
+        return [];
+    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);
@@ -568,12 +1232,14 @@ export async function hintsCommand(argv, cwd) {
     if (dropped > 0)
         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)}`, 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;
@@ -602,14 +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);
+        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);
@@ -624,10 +1293,12 @@ export async function hintsCommand(argv, cwd) {
             truncated: args.offset + selected.length < filtered.length,
             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);
+    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. */
@@ -644,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
@@ -659,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`,