imgtune 0.2.0 → 0.3.0

package/dist/vector-phase.js

@@ -0,0 +1,222 @@
+// The vector phase of a scan: after every page is measured, the flat still rasters of all pages (fix.vector, see
+// vector-art.ts) are ranked by their bytes per view, and the heaviest ones within --svg-budget are traced and checked.
+// Each unique URL is traced once per run. Its numbers are kept in the result cache, keyed by the content hash, so a
+// rescan does not score it again. A passing SVG is written to the scan's svg/ folder. Nothing here throws: a failure
+// becomes the record's notChecked reason, and the scan always finishes.
+import { mkdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { writeFileAtomic } from "./atomic.js";
+import { mapLimit } from "./concurrency.js";
+import { CACHE_VERSION, contentHash } from "./result-cache.js";
+import { measure } from "./timing.js";
+import { VECTOR_BAR, VECTOR_CAP_MS, VECTOR_MIN_SAVING, VECTORIZER_VERSION, loadVectorizer, svgBytes, svgFidelity, traceSvg, } from "./vector-art.js";
+/** The note printed once when the vectorizer is missing: what installing it adds. */
+export const VECTOR_NOTE = "install @neplex/vectorizer to check vector art";
+/** Images traced at once. */
+export const VECTOR_CONCURRENCY = 4;
+/** The folder of the traced SVGs, under the scan's folder. */
+export const VECTOR_SVG_DIR = "svg";
+/** Bumped when the trace or the scoring changes (input size, render, flat rule), so the cached numbers of the old ones are not read. */
+const TRACE_VERSION = "poster-3";
+const TIMED_OUT = Symbol("timed out");
+/**
+ * The served bytes of the flat images, as the browser got them, for the vector check: the check traces the file the page
+ * used, not a fresh download. Bounded: it keeps the `capacity` largest files seen (the ones the budget would trace), so
+ * the memory is the budget times a file, whatever the site has. A URL it does not keep is fetched instead.
+ */
+export class FlatBuffers {
+    capacity;
+    entries = new Map();
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    /** Keeps `buffer` for `url` when it is among the `capacity` largest seen so far. */
+    offer(url, buffer, bytes) {
+        if (this.capacity <= 0 || buffer === undefined || this.entries.has(url))
+            return;
+        if (this.entries.size < this.capacity) {
+            this.entries.set(url, { buffer, bytes });
+            return;
+        }
+        let smallest;
+        for (const [key, entry] of this.entries) {
+            if (smallest === undefined || entry.bytes < (this.entries.get(smallest)?.bytes ?? Infinity))
+                smallest = key;
+        }
+        if (smallest !== undefined && bytes > (this.entries.get(smallest)?.bytes ?? 0)) {
+            this.entries.delete(smallest);
+            this.entries.set(url, { buffer, bytes });
+        }
+    }
+    get(url) {
+        return this.entries.get(url)?.buffer;
+    }
+}
+/** The bytes per page view of an image: the mean over its viewports. */
+export function perViewBytesOf(record) {
+    return record.perViewport.reduce((sum, p) => sum + p.servedBytes, 0) / Math.max(1, record.perViewport.length);
+}
+/** The flat images of the pages, one per URL, heaviest first. A record without a URL cannot be traced and is left out. */
+function candidatesOf(pages) {
+    const byUrl = new Map();
+    for (const page of pages) {
+        for (const record of page.images ?? []) {
+            if (record.fix.vector === undefined || record.current.src === undefined)
+                continue;
+            const url = record.current.src;
+            const perView = perViewBytesOf(record);
+            const known = byUrl.get(url);
+            if (known === undefined || perView > known.perView)
+                byUrl.set(url, { url, id: known?.id ?? record.id, perView });
+        }
+    }
+    return [...byUrl.values()].sort((a, b) => b.perView - a.perView || a.url.localeCompare(b.url));
+}
+/** Runs the vector check over the flat images of the pages (see the file comment). */
+export async function runVectorPhase(pages, opts, deps) {
+    const byUrl = new Map();
+    const candidates = candidatesOf(pages);
+    if (candidates.length === 0)
+        return { byUrl };
+    const skip = opts.survey ? "survey" : !opts.quality ? "quality off" : opts.budget === 0 ? "svg-budget 0" : undefined;
+    if (skip !== undefined) {
+        for (const c of candidates)
+            byUrl.set(c.url, { notChecked: skip });
+        return { byUrl };
+    }
+    if ((await loadVectorizer()) === undefined) {
+        for (const c of candidates)
+            byUrl.set(c.url, { notChecked: "vectorizer not installed" });
+        return { byUrl, note: VECTOR_NOTE };
+    }
+    const chosen = candidates.slice(0, opts.budget);
+    for (const c of candidates.slice(opts.budget))
+        byUrl.set(c.url, { notChecked: "over --svg-budget" });
+    opts.log(`vector: tracing ${chosen.length} of ${candidates.length} flat image(s) (--svg-budget ${opts.budget})`);
+    const traced = await mapLimit(chosen, VECTOR_CONCURRENCY, async (c) => [c.url, await traceOne(c.url, c.id, opts, deps)]);
+    for (const [url, outcome] of traced)
+        byUrl.set(url, outcome);
+    const passed = traced.filter(([, o]) => o.passed === true).length;
+    opts.log(`vector: ${passed} of ${traced.length} traced image(s) pass at SSIMULACRA2 ${VECTOR_BAR} (half size)`);
+    return { byUrl };
+}
+/** One URL: its numbers from the cache, or traced and scored within VECTOR_CAP_MS. Never throws. */
+async function traceOne(url, id, opts, deps) {
+    const buffer = await deps.fetch(url).catch(() => undefined);
+    if (buffer === undefined)
+        return { notChecked: "trace failed" };
+    const key = `vector|${CACHE_VERSION}|${contentHash(buffer)}|${VECTORIZER_VERSION}|${TRACE_VERSION}|bar${VECTOR_BAR}`;
+    const cached = await opts.cache?.getJson(key);
+    let numbers = isCachedNumbers(cached) ? cached : undefined;
+    let svg;
+    if (numbers === undefined) {
+        // The cap aborts the trace itself (the vectorizer stops, and stops using CPU); the score is dropped with it.
+        const controller = new AbortController();
+        const traced = await within(measure("vector: trace and score", () => measureOne(buffer, controller.signal)), VECTOR_CAP_MS, controller);
+        if (traced === TIMED_OUT)
+            return { notChecked: "timeout" };
+        if (traced === undefined)
+            return { notChecked: "trace failed" };
+        numbers = traced.numbers;
+        svg = traced.svg;
+        await opts.cache?.putJson(key, numbers);
+    }
+    else if (numbers.passed) {
+        // The numbers say it passes, but its file is written from a trace: a trace is cheap, the score is not repeated.
+        const controller = new AbortController();
+        const traced = await within(traceSvg(buffer, controller.signal), VECTOR_CAP_MS, controller);
+        if (traced === TIMED_OUT)
+            return { notChecked: "timeout" };
+        if (traced === undefined)
+            return { notChecked: "trace failed" };
+        svg = traced;
+    }
+    const outcome = { svgBytes: numbers.svgBytes, score: numbers.score, badPixelShare: numbers.badPixelShare, passed: numbers.passed };
+    if (!numbers.passed)
+        return outcome;
+    if (svg === undefined)
+        return { notChecked: "trace failed" };
+    try {
+        const dir = join(opts.outDir, VECTOR_SVG_DIR);
+        await mkdir(dir, { recursive: true });
+        const file = join(dir, `${id}.svg`);
+        await writeFileAtomic(file, svg, { root: opts.outDir });
+        // Relative to the project folder when the file is inside it; absolute otherwise (a scan into another folder).
+        const named = relative(opts.cwd, file);
+        return { ...outcome, tracedFile: named.startsWith("..") ? file : named };
+    }
+    catch {
+        return { notChecked: "trace failed" };
+    }
+}
+/** The trace of an image and its numbers: the SVG, its brotli size, and the fidelity against the served bytes. */
+async function measureOne(buffer, signal) {
+    const svg = await traceSvg(buffer, signal);
+    if (svg === undefined || signal.aborted)
+        return undefined;
+    const bytes = svgBytes(svg);
+    const fidelity = await svgFidelity(buffer, svg);
+    const passed = fidelity.score >= VECTOR_BAR && bytes <= buffer.length * (1 - VECTOR_MIN_SAVING);
+    return { svg, numbers: { svgBytes: bytes, score: Math.round(fidelity.score * 10) / 10, badPixelShare: fidelity.badPixelShare, passed } };
+}
+/**
+ * The value, or TIMED_OUT when it is not ready in `ms` (the controller is then aborted, so the work stops), or undefined when
+ * it fails.
+ */
+async function within(work, ms, controller) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            resolve(TIMED_OUT);
+        }, ms);
+    });
+    try {
+        return await Promise.race([work.catch(() => undefined), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function isCachedNumbers(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (Number.isFinite(v.svgBytes) &&
+        Number.isFinite(v.score) &&
+        Number.isFinite(v.badPixelShare) &&
+        typeof v.passed === "boolean");
+}
+/**
+ * A page with the phase's outcomes written into its flat images' fix.vector. The saving of a passing SVG is the served bytes
+ * per view minus the SVG's, averaged over the page's viewports (as the other savings are). The record's claimed saving is
+ * the larger of the raster fix and the SVG; the SVG wins only when it is larger, and the raster fix stays as the fallback.
+ */
+export function applyVector(page, run) {
+    const flat = (page.images ?? []).some((record) => record.fix.vector !== undefined);
+    if (!flat)
+        return page;
+    const viewportCount = Math.max(1, page.viewports.length);
+    const images = (page.images ?? []).map((record) => {
+        const vector = record.fix.vector;
+        if (vector === undefined)
+            return record;
+        const outcome = record.current.src !== undefined ? run.byUrl.get(record.current.src) : undefined;
+        const next = { ...vector, ...(outcome ?? { notChecked: "trace failed" }) };
+        if (outcome?.passed === true && outcome.svgBytes !== undefined) {
+            const svg = outcome.svgBytes;
+            const saved = record.perViewport.reduce((sum, p) => sum + Math.max(0, p.servedBytes - svg), 0) / viewportCount;
+            next.savedPerView = Math.round(saved);
+            if (saved > record.fix.bytes.saved) {
+                next.wins = true;
+                return {
+                    ...record,
+                    fix: { ...record.fix, vector: next, bytes: { saved: Math.round(saved), addedForSharpness: record.fix.bytes.addedForSharpness } },
+                };
+            }
+        }
+        return { ...record, fix: { ...record.fix, vector: next } };
+    });
+    const hasNote = images.some((record) => record.fix.vector !== undefined);
+    return { ...page, images, ...(run.note !== undefined && hasNote ? { vectorNote: run.note } : {}) };
+}

package/dist/video-analysis.js

@@ -4,6 +4,7 @@
 // so it is added to the page's images here, before the image pipeline runs.
 import { sha1 } from "./atomic.js";
 import { COMPONENT_NAME, sanitizeText } from "./locate.js";
+import { hiddenFixCore } from "./images.js";
 import { adapterFor, formatAutoOf } from "./loaders.js";
 import { clusterVideoWidths, videoBytes, widthOptions, } from "./media-model.js";
 /** Widths kept per video in scan mode (`--max-video-widths`, before the flag is wired). */
@@ -163,11 +164,65 @@ function hasAv1(video) {
     const urls = [video.currentSrc, ...video.sources.map((s) => s.src)];
     return urls.some((u) => /\.av1\.mp4(?:[?#]|$)/i.test(u));
 }
+/**
+ * The fresh load's media bytes behind each observation. A resized viewport shares its group's page load, so its media map
+ * holds the bytes of every earlier step too. A hidden copy's bytes at a resized viewport are taken from the fresh load's map
+ * (see hiddenBytesOf), so a file fetched only for another viewport is not counted there.
+ */
+function freshMediaOf(observations) {
+    const fresh = new Map();
+    let current;
+    for (const obs of observations) {
+        if (obs.load === "fresh" || current === undefined)
+            current = obs;
+        fresh.set(obs, current);
+    }
+    return fresh;
+}
+/** The poster URL of a video that is a file the page can fetch (not a data: URI), or undefined. */
+function fetchablePosterOf(video) {
+    return video.poster !== undefined && !video.poster.startsWith("data:") ? video.poster : undefined;
+}
+/**
+ * The bytes a hidden copy costs per view at its viewport: the file the browser fetched for it (the same preload rules as a
+ * shown video, see videoBytes), plus its poster when the poster was fetched in the fresh load and no shown image of the
+ * viewport uses that URL. Zero when the copy's file is also shown at the viewport (one fetch, counted there), or when a
+ * resized viewport's copy does not fetch on load (its bytes are not the fresh load's).
+ */
+function hiddenBytesOf(member, shownUrls, freshOf) {
+    const { obs, video } = member;
+    const url = video.currentSrc;
+    if (shownUrls.has(url))
+        return 0;
+    const kind = preloadKindOf(video);
+    const fresh = freshOf.get(obs) ?? obs;
+    // A copy that does not fetch on load (preload none or metadata) has nothing of the page load to count at a resized viewport.
+    const fetchesOnLoad = kind === "autoplay" || kind === "auto" || kind === "default";
+    if (obs.load !== "fresh" && !fetchesOnLoad)
+        return 0;
+    const observed = observedBytesOf(obs.load === "fresh" ? obs : fresh, url);
+    const bytes = videoBytes({
+        kind,
+        playing: !video.paused || video.errorCode === 4,
+        observedBytes: observed,
+        fullBytes: observed,
+        visible: true,
+    }).perView;
+    const poster = fetchablePosterOf(video);
+    const posterBytes = poster !== undefined && obs.load === "fresh" && !obs.images.some((img) => img.currentSrc === poster && img.hidden === undefined)
+        ? (obs.responses.get(poster)?.bytes ?? 0)
+        : 0;
+    return bytes + posterBytes;
+}
 /**
  * The VideoRecords of a page, from its observations. Each `<video>` is one record across the viewports it appears in.
  *
- * Bytes: the record takes the viewport where the video costs most per view, so the claim is never low. The full file is
- * `fullBytes` (see fullBytesOf) and is shown per play for every video.
+ * Bytes: the claim is the shown copies only. The record takes the viewport where a shown copy costs most per view, so the
+ * claim is never low. The full file is `fullBytes` (see fullBytesOf) and is shown per play for every video.
+ *
+ * Hidden: a copy that is not shown at a viewport (see ObservedVideo.hidden) is a loaded-but-not-shown fix when the browser
+ * fetched bytes for it (hiddenBytesOf). Its bytes are the fix's, apart from the claim. A video shown at no viewport is never
+ * shown on load: it has no width, no levers and no claim.
  *
  * Widths: the viewports the video is shown in (hidden ones are left out) are clustered to at most `maxWidths` widths in
  * scan mode, and the plans for one, two and three widths are kept in audit mode, where the agent chooses.
@@ -179,21 +234,63 @@ export function videoRecordsOf(page, observations, fullBytes, mode, maxWidths, s
     const records = [];
     // The records of each file so far: a file's videos are told apart by their document order (see videoIdOf).
     const perFile = new Map();
+    const freshOf = freshMediaOf(observations);
+    // The file each viewport shows in full, over every video of the page: a hidden copy of one of them adds no bytes there.
+    const shownAt = new Map();
+    for (const obs of observations) {
+        const urls = shownAt.get(obs.viewport.name) ?? new Set();
+        for (const video of obs.videos ?? [])
+            if (!video.hidden)
+                urls.add(video.currentSrc);
+        shownAt.set(obs.viewport.name, urls);
+    }
     for (const [key, members] of groupVideos(observations)) {
-        const ref = members[0].video;
+        const shown = members.filter((m) => !m.video.hidden);
+        // The record's own file and attributes come from a shown copy when there is one.
+        const ref = (shown[0] ?? members[0]).video;
         const source = sources?.get(ref);
         const src = ref.currentSrc;
         const observedMax = Math.max(0, ...members.map((m) => observedBytesOf(m.obs, m.video.currentSrc)));
         const full = fullBytes.get(src) ?? observedMax;
-        const views = members.map((m) => videoBytes({
+        // The claim: the shown copies. A video shown nowhere costs nothing in the claim.
+        const views = shown.map((m) => videoBytes({
             kind: preloadKindOf(m.video),
             playing: !m.video.paused || m.video.errorCode === 4,
             observedBytes: observedBytesOf(m.obs, m.video.currentSrc),
             fullBytes: full,
-            visible: !m.video.hidden,
+            visible: true,
         }));
-        const heaviest = views.reduce((best, cur) => (cur.perView > best.perView ? cur : best));
-        const shown = members.filter((m) => !m.video.hidden);
+        const none = videoBytes({ kind: "none", playing: false, observedBytes: 0, fullBytes: full, visible: false });
+        const heaviest = views.length > 0 ? views.reduce((best, cur) => (cur.perView > best.perView ? cur : best)) : none;
+        // The claim is per viewport, averaged over the viewports (as an image's is): each viewport loads its own shown copy, so a
+        // twin pair counts once, not twice. Bounded by the file's own length (perPlay), as the single-copy figure is.
+        const shownBytesAt = new Map();
+        shown.forEach((m, i) => shownBytesAt.set(m, views[i].perView));
+        const claimPerView = Math.min(heaviest.perPlay, observations.length > 0 ? views.reduce((sum, v) => sum + v.perView, 0) / observations.length : 0);
+        // The hidden fix: one entry per viewport the video is in, shown or hidden. A hidden copy with no bytes is not reported.
+        const entries = [];
+        const copies = [];
+        for (const m of members) {
+            const viewport = { name: m.obs.viewport.name, width: m.obs.viewport.width };
+            if (!m.video.hidden) {
+                entries.push({ viewport, bytes: 0, inPanel: false, hover: false });
+                continue;
+            }
+            const bytes = hiddenBytesOf(m, shownAt.get(m.obs.viewport.name) ?? new Set(), freshOf);
+            shownBytesAt.set(m, bytes);
+            if (bytes <= 0)
+                continue;
+            const reason = m.video.hiddenReason ?? "display";
+            entries.push({ viewport, bytes, hidden: reason, inPanel: m.video.inPanel === true, hover: m.video.hover === true, unstable: m.video.unstable === "unknown" });
+            copies.push({ viewport: viewport.name, src: m.video.currentSrc, bytes, reason });
+        }
+        const hiddenBase = hiddenFixCore(entries, observations.length);
+        const hidden = hiddenBase !== undefined ? { ...hiddenBase, copies } : undefined;
+        const shownNow = shown.length > 0;
+        const info = [];
+        const handled = formatHandledNote(src, page);
+        if (handled !== undefined)
+            info.push(handled);
         const knownWidth = shown.map((m) => m.video.videoWidth).find((w) => w !== undefined && w > 0);
         const needs = shown.map((m) => ({
             viewport: m.obs.viewport.name,
@@ -201,26 +298,24 @@ export function videoRecordsOf(page, observations, fullBytes, mode, maxWidths, s
             boxWidth: m.video.renderedWidth,
             dpr: m.obs.viewport.dpr,
         }));
-        const info = [];
-        const handled = formatHandledNote(src, page);
-        if (handled !== undefined)
-            info.push(handled);
         let sourceWidth = knownWidth;
         if (sourceWidth === undefined) {
             // Without the source width the widths are capped at the largest display need, which is all the page shows.
             sourceWidth = Math.max(1, ...shown.map((m) => Math.ceil(m.video.renderedWidth * m.obs.viewport.dpr)));
-            if (shown.length > 0)
+            if (shownNow)
                 info.push("source width not read: widths are capped at the largest display need");
         }
-        const belowFold = members.every((m) => !m.video.inFirstViewport);
-        const levers = { info };
-        if (heaviest.perView > 0 && (belowFold || ref.preload === "auto")) {
-            levers.loading = { perViewBytes: heaviest.perView, belowFold };
+        const belowFold = shown.every((m) => !m.video.inFirstViewport);
+        const levers = { info: shownNow ? info : [] };
+        if (shownNow) {
+            if (claimPerView > 0 && (belowFold || ref.preload === "auto")) {
+                levers.loading = { perViewBytes: claimPerView, belowFold };
+            }
+            if (handled === undefined && !hasAv1(ref))
+                levers.codec = { missing: "av1" };
+            if (ref.poster === undefined)
+                levers.posterMissing = true;
         }
-        if (handled === undefined && !hasAv1(ref))
-            levers.codec = { missing: "av1" };
-        if (ref.poster === undefined)
-            levers.posterMissing = true;
         const locator = {
             component: source?.component.length ? source.component : componentsOf(ref.locator.owners),
             selector: sanitizeText(ref.locator.selector, 300),
@@ -254,14 +349,17 @@ export function videoRecordsOf(page, observations, fullBytes, mode, maxWidths, s
                 preload: ref.preload,
                 ...(ref.poster !== undefined ? { poster: ref.poster } : {}),
             },
-            bytes: { ...heaviest, fullBytesKnown: false },
+            bytes: { ...heaviest, perView: claimPerView, fullBytesKnown: false },
             perViewport: members.map((m) => ({
                 viewport: m.obs.viewport.name,
                 boxWidth: m.video.renderedWidth,
                 dpr: m.obs.viewport.dpr,
                 inFirstViewport: m.video.inFirstViewport,
+                ...(m.video.hidden ? { hidden: m.video.hiddenReason ?? "display" } : {}),
+                bytes: shownBytesAt.get(m) ?? 0,
             })),
             levers,
+            ...(hidden !== undefined ? { hidden } : {}),
         };
         if (mode === "audit")
             record.widthOptions = widthOptions(needs, sourceWidth);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "imgtune",
-  "version": "0.2.0",
-  "description": "Finds the image waste on live pages: the sizes, quality and format for each image, checked with SSIMULACRA2, and the line of code that renders it.",
+  "version": "0.3.0",
+  "description": "Finds the wasted bytes on live pages (images, video, hidden downloads, fonts, compression, 3D and audio) and gives the fix for each, checked with SSIMULACRA2 and VMAF. Image and video fixes name the file and line when they resolve.",
   "license": "MIT",
   "author": "indicozy",
   "keywords": [
@@ -18,7 +18,18 @@
     "cli",
     "next/image",
     "sizes",
-    "lcp"
+    "lcp",
+    "page-weight",
+    "web-performance",
+    "video",
+    "fonts",
+    "woff2",
+    "compression",
+    "brotli",
+    "lottie",
+    "svg",
+    "gltf",
+    "lazy-loading"
   ],
   "homepage": "https://indicozy.github.io/imgtune/",
   "repository": {
@@ -62,11 +73,21 @@
   "packageManager": "pnpm@10.8.0",
   "dependencies": {
     "playwright": "^1.64.1",
-    "sharp": "^0.35.5"
+    "sharp": "^0.35.5",
+    "subset-font": "^2.9.0",
+    "svgo": "^4.1.0",
+    "wawoff2": "^2.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5"
+  },
+  "optionalDependencies": {
+    "@neplex/vectorizer": "0.1.0",
+    "@gltf-transform/core": "^4.5.1",
+    "@gltf-transform/extensions": "^4.5.1",
+    "@gltf-transform/functions": "^4.5.1",
+    "meshoptimizer": "^1.3.0"
   }
 }

package/skills/imgtune/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: imgtune
-description: Reduce image weight and fix slow pages in any web framework. Use when asked to optimise or optimize images, cut page weight, improve LCP, fix image sizes, next/image sizes, the LCP image, images Lighthouse flags as oversized, badly encoded or old-format, or make a live page send fewer image bytes. imgtune measures each image on the live page at six viewports and gives per-image fix hints (sizes, quality, format) with the component and line that renders each one, which you apply in the source.
+description: Cut page weight and fix slow pages in any web framework. Use when asked to optimise or optimize images or video, cut page weight, improve LCP, fix image sizes or next/image sizes, shrink fonts or subset them, find files served without compression, lazy-load hidden images or videos, or shrink 3D models, audio, Lottie or SVG. imgtune measures the live page at six viewports and gives per-item fix hints with the expected bytes and the component and line that renders each one, which you apply in the source.
 ---
 
 # imgtune
@@ -11,9 +11,13 @@ format) with two byte numbers. Run `npx imgtune --help`, or `<command> --help` f
 ## When to use
 
 The user asks to cut image weight or improve LCP; Lighthouse flags images as oversized, badly encoded or old-format; or
-pages are heavy and the images are most of the bytes. Not for scripts, fonts or video. Do not use it on sites the user
+pages are heavy and the images are most of the bytes. It also covers video, hidden downloads, fonts, compression, 3D, audio, Lottie, SVG and favicons (below). It does not edit JavaScript or CSS: those get only the compression check. Do not use it on sites the user
 does not own or run, unless they say they are authorised.
 
+## Other page weight
+
+`resources` in each scan JSON lists the findings for compression, favicons, fonts, SVG, Lottie, 3D models and audio, with their own bytes; they are not in the image totals. Images and videos the browser downloads but no viewport shows are in the hidden group (`images[].hidden`, `videos[].hidden`): their fix is lazy loading, a responsive `<picture>`, or removal, not a size change. `npx imgtune hints <scan.json> --format json` gives the resource findings as a top-level `resources` array, each with its page.
+
 ## Fix the images
 
 Use this when the user asks to fix image sizes, next/image sizes, or the LCP image, or after a scan has hints to apply.
@@ -21,8 +25,8 @@ Use this when the user asks to fix image sizes, next/image sizes, or the LCP ima
 1. **Scan** the pages on a built server into a folder: `npx imgtune scan <url> [<url> ...] --out .imgtune/scan`.
 2. **Read the hints in batches**: `npx imgtune hints .imgtune/scan/*.json --limit 10`. The LCP image comes first, and its line
    starts with `LCP image`. Take it first in every batch.
-3. **Open each hint's file and line**, check that it renders that image, then apply the hint's `sizes` (or `width` for a
-   plain image), its quality and its format, as `reference.md` says. A hint marked `(unverified)`, or with no file and line,
+3. **Open each hint's file and line**, check that it renders that image, then apply the hint's `sizes` (or, for a plain
+   `<img>` with no srcset, its `srcset` variants and the `sizes`), its quality and its format, as `reference.md` says. A hint marked `(unverified)`, or with no file and line,
    is not edited: say so in the report.
 4. **Apply the site-level `next.config: images.qualities: [...]` line once**, in `next.config`, and keep it as printed. Never
    lower a quality below the hint's target.

package/skills/imgtune/reference.md

@@ -336,4 +336,4 @@ failed, skipped and unmatched usages).
 ## Top call sites
 
 `imgtune hints <scan.json> --top 10` prints the ten call sites with the most saving per view, one line each (where, the
-images and pages, the saving split into sizes and quality). Several scan files group across pages.
+images and pages, the saving split into sizes, resize and quality). Several scan files group across pages.