imgtune 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,177 @@
 # Changelog
 
+## 0.3.0 (date TBD)
+
+- Page weight, not only images. `scan` now reports what else a page downloads, each with its bytes per view and a fix an
+  agent can apply: images and video that are loaded but never shown, fonts, compression, favicons, vector art, SVG, Lottie
+  files, 3D models and audio. Images and video stay the headline. The positioning is in the README, the site and the skill.
+- Loaded but not shown: images and videos. `scan` reports the images and `<video>` elements the browser downloads but no
+  viewport shows: `display:none`, `visibility:hidden`, `opacity: 0`, a zero-size box, an offscreen slide of a track, a closed
+  `<details>`, `content-visibility: hidden`, a hover swap, a tab panel, and a CSS background layer whose file a hidden element
+  loaded. A copy counts as hidden only if it reads hidden on two reads at least 1 s apart and again after a scroll; anything
+  that toggles (a carousel, a crossfade, a reveal) counts as shown, and a copy seen visible at any step of the scroll pass is
+  shown. Each case gets its own fix: a `<picture>` with a media condition for a responsive twin, `loading="lazy"` or render on
+  activation for a carousel, tab or hover copy, and removal or an on-demand load for an image no viewport shows on load. A
+  hidden copy's bytes are kept apart from the savings, and it gets no sizes, quality or encode claim at the viewports that hide
+  it. An image that already has `loading="lazy"` is no longer advised to get it. The JSON gains `images[].hidden` and
+  `videos[].hidden`. See the Hidden images guide.
+- Video: the claim is per viewport. A `<video>`'s per-view bytes are counted at each viewport (what that viewport loads) and
+  averaged over the viewports, the same as images. A desktop and a mobile copy of one video count once. A video that only some
+  viewports load therefore claims less than it did in 0.2. A video no viewport shows is never encoded (`never-shown`).
+- `<source media>` support is stated as reported in the hints: Chrome and Edge 120 or later, Firefox 120 or later, Safari
+  (version not verified).
+- Fonts. `scan` reports each web font file's bytes per view and its savings: a re-encode to WOFF2 (measured for small files,
+  estimated for large ones), a subset to the Unicode scripts the page's text uses (the subset keeps Basic Latin, Latin-1,
+  punctuation and currency), and faces the browser downloaded but no rendered text uses. Icon fonts are not subset, and a
+  family of several static weights is noted as a candidate for one variable font, with no saving. Each finding names the
+  command and the expected bytes. See the Fonts guide.
+- Compression. Text served with no `Content-Encoding` (JavaScript, CSS, HTML, JSON, XML, SVG, WASM, TTF and OTF, at least 1 KB)
+  is reported with its brotli-11 saving, grouped per host and content type. The fix is the server or CDN setting. See the
+  Compression guide.
+- Favicons. A favicon over 10 KB, or an apple-touch-icon over 30 KB, is reported with the saving of a re-encode to 32 px or
+  180 px. Each icon is fetched once per run. See the Favicons guide.
+- Vector art. A still raster that is flat (a few colours cover most of it: logos, icons, flat illustrations) gets a vector
+  check. `scan` traces the heaviest such images (`--svg-budget`, default 50, 0 to 1000; 0 traces none) with vtracer, through
+  the optional `@neplex/vectorizer` dependency, and renders each SVG back at the served size. The fidelity is SSIMULACRA2 at
+  half size against the served image (bar 70). A passing SVG must be at least 30% smaller than the served file, and its saving
+  is the record's claim when it is the larger one; the raster fix stays as the fallback. The traced file is written to
+  `svg/<id>.svg` in the scan folder. Without the vectorizer, a flat image gets one note and no byte claim. `fix.vector` in the
+  JSON, a `vector` field on hints, and the summary and the check report count the flat and traced images. See the Vector art
+  guide.
+- SVG files. Each SVG of 2 KB to 5 MB is optimised with SVGO (floatPrecision 2) and reported when the brotli size drops by at
+  least 20% and the render still scores 70 or more on SSIMULACRA2 at half size. SVGs with embedded `data:` rasters are listed.
+  Inline `<svg>` is not checked.
+- Lottie animations. `scan` reads each Lottie JSON and `.lottie` file the page loads: the size, layers, frame rate and duration,
+  and the savings: embedded rasters re-encoded to WebP at the display size, numbers rounded to three decimals, and a `.lottie`
+  repack (an estimate). A huge animation shown small gets a hint to export at the display size. See the Lottie guide.
+- 3D models. `scan` checks glTF and GLB files: the geometry saving with meshopt is measured (the file is repacked with
+  gltf-transform), base64 buffers get the GLB repack, and PNG or JPEG textures get a WebP estimate. Draco and meshopt files are
+  reported as compressed. USDZ, OBJ, FBX, KTX2, splats and PLY are informational. See the 3D models guide.
+- Audio. `scan` probes each audio file with ffprobe. WAV and FLAC, lossy files above 128 kbps stereo (64 kbps mono), and stereo
+  files with identical channels get an Opus re-encode, measured on a 10 s sample. A file the page loads on page load gets the
+  `preload="none"` fix. Without ffmpeg only the bytes are reported. See the Audio guide.
+- Resources, as one group. The non-image checks above run on every response the page makes, and their findings are reported in
+  a Resources section (after Video), in the JSON as `resources`, and in a Resources block of the PR comment. They are not in
+  the image totals. A file on another site is labelled "third-party (ask the vendor)" and totalled apart from first-party
+  savings; a small saving of a kind that is weak for its cost (SVG, Lottie, favicons) is a "lead" and sorts after the real
+  savings. The heavy steps (brotli-11 sizes, SVGO and render, WOFF2 and subset encodes, Lottie re-encodes, 3D meshopt, audio
+  sample encodes) are computed once per run for each distinct content, not once per viewport and page. `--resource-time <s>`
+  (default 60) caps the heavy work of a run; a file over the budget keeps its cheap finding, marked as an estimate or not
+  measured. The resources overview is in the guide.
+- A plain `<img>` with no `srcset`, served much wider than it is shown (from a same-origin file or a CDN host no adapter knows),
+  gets resized variants instead of a `sizes` change. `sizes` does nothing without `srcset`. The hint says to serve the variants
+  at concrete widths (1 to 3, from the device pixels each viewport needs) and to add the `srcset` and `sizes`. The summary's top
+  group reads `no srcset -> serve <widths> + srcset/sizes`, and the saving is booked as `resize`, not `quality`. Known loaders and
+  pages with Next.js detected keep their advice. The same resize booking applies to CSS background layers. The JSON gains
+  `bytes.resize` and `srcset`.
+- Measuring browser: `--disable-software-rasterizer` is no longer passed to Chromium (`--disable-gpu` stays). With it WebGL was
+  off, so a page with a 3D viewer never requested its model. Only WebGL pages pay the extra CPU.
+- Flags. `--no-resources` skips the resource checks and their capture (`scan`, `check`, `run` and `audit`). A page scanned that
+  way is recorded with `resources: false`. `--resource-time <s>` (`scan`, `check`, `run`, `audit`; default 60, 0 to 3600) caps
+  the heavy resource work. `--svg-budget <N>` (`scan`, `check`, `run`, `audit`; default 50, 0 to 1000) sets how many flat images
+  are traced.
+- Optional dependencies. `@neplex/vectorizer` (0.1.0) is used for the vector trace. `@gltf-transform/core`,
+  `@gltf-transform/extensions`, `@gltf-transform/functions` and `meshoptimizer` are used for the 3D measurements. Each is loaded
+  when a check needs it. If one is missing, its check gives one note and no measured saving; the rest of the scan runs.
+- Smaller fixes: a hidden copy's hints carry its URL and its bytes per viewport (`revealCapped` marks candidates past the
+  per-viewport limit that were not re-read after a scroll); a `<details>` closed on load is not counted as shown. A failed
+  linked stylesheet makes a page `broken` only when no linked stylesheet applied (otherwise it is a warning); a challenge page
+  (WAF or Cloudflare) is `blocked` whatever its images; a search the time limit cut short is labelled "est., search stopped at
+  the time limit"; a page that reloads itself is read between its reloads.
+
+### Changed for 0.2 users
+
+- The JSON gains `resources` (a page file's findings, present unless the scan ran with `--no-resources`), `images[].hidden` and
+  `videos[].hidden`, `fix.vector` on a still raster that looks like vector art, and `bytes.resize` (with `srcset`) on a plain
+  image with no `srcset`. Existing fields keep their meaning, except as noted below.
+- Video numbers change: the per-view claim is averaged over the viewports (see above), so a video loaded at some viewports only
+  claims less than in 0.2. Compare the `videos[].bytes.perView` of a 0.2 run with a 0.3 run only with that in mind.
+- Plain images with no `srcset`: the saving moves from `quality` (and `sizes`) to `resize`, so the quality total of a page can
+  fall by the same amount. The hint asks for resized variants, not a `sizes` change.
+- Hidden images and videos used to be dropped silently. They are now reported, in their own lines and in the JSON, and kept out
+  of the savings, so a page's totals can differ from 0.2 even when no image changed.
+- The Chromium flags changed: WebGL is on for the scan (see above). A page with a WebGL viewer may now load more bytes than it
+  did in 0.2, and those bytes are reported.
+- The result cache: `CACHE_VERSION` is still 3, but the cache keys include the imgtune version, so 0.2 entries are not reused and
+  the first 0.3 scan is cold.
+- New flags: `--no-resources`, `--resource-time` and `--svg-budget`. See the CLI reference.
+- New optional dependencies: `@neplex/vectorizer`, `@gltf-transform/core`, `@gltf-transform/extensions`, `@gltf-transform/functions`
+  and `meshoptimizer`. They install with the package as optional dependencies; none is required.
+
+## 0.2.0 (2026-11-14)
+
+- Animated media and video. `scan` measures animated GIFs (in an `<img>` or a CSS background), animated WebP and APNG, and
+  self-hosted `<video>` elements with a plain file source. Each page gets a Video section with the bytes per view and per
+  play, and the levers (audio, width, codec, preload, poster). Adaptive streams (HLS, DASH, Mux, Cloudflare Stream) and
+  third-party iframes (YouTube, Vimeo) are not reported. A video hosted on another site follows the third-party rules.
+- Hints for animated media. A large animated GIF gets `<video autoplay muted loop playsinline>` with AV1 first and an H.264
+  fallback. The H.264 fallback is a recipe (libx264, CRF 23, yuv420p, faststart), marked not measured. The animated-image
+  alternative is shown with its size. A small `<img>` GIF or a CSS background gets an animated AVIF or WebP, and only its
+  `src` changes. A `<video>` hint names each lever: the width per breakpoint (`<source media>`), the CRF, the codec, the
+  audio track of a muted video, and `preload`. A poster is audited through the image pipeline. Duration and frame rate are
+  informational notes only, never part of the claim.
+- Static GIFs (one frame) get the normal image hints. Animated images stay in the image totals.
+- Bytes per view and per play. Per view is what the first view fetches: an autoplay video counts its full file,
+  `preload="auto"` counts the bytes the scan saw (labelled browser-dependent), and `preload="metadata"` or `"none"` counts 0.
+  Per play is the full file, shown for every video, so a large click-to-play file is not missed. A URL's bytes are the union
+  of the byte ranges read, capped at the file length, and a length probe reads the size when the server sends no
+  Content-Length, so a looping video is not counted once per loop. Posters count as images.
+- Quality bars. A candidate must reach VMAF 93 (`--video-bar`) against the served file at its display size. A still-frame
+  guard (SSIMULACRA2 on the stillest frames) catches blurred text in screen recordings. Its bar is `--video-still-bar`
+  (default 65), lowered to at most 10 points below the best the same codec reaches on that content, and never below 20. The
+  relative bar catches the loss the encode adds, not what a format can never reproduce, such as GIF dither. For GIF sources
+  both frames of the guard are blurred slightly (Gaussian, sigma 1) before scoring, so dither the eye averages out does not
+  fail it.
+- Encodes and budget. Encodes run on the heaviest animated assets first (by per-view bytes), at most `--media-budget` per run
+  (default 20) and within `--media-time` seconds (default 600). Assets over the budget keep their cheap hints and are marked
+  "over --media-budget". The CRF search runs on 2 s sample clips: one for a video of up to 6 s, three for a longer one. The
+  full-file bytes are extrapolated from the samples and labelled as an estimate; nothing is encoded in full. Each asset is
+  encoded once per run, keyed by URL and content hash in the result cache. Widths are snapped to a few buckets first.
+- Video widths. `scan` and `check` serve each video at most `--max-video-widths` widths (default 2): each viewport gets the
+  smallest kept width that covers its display width times its device pixel ratio. `audit` does not choose: it reports each
+  viewport's needed width and the bytes per view at one, two and three widths.
+- ffmpeg. The system ffmpeg on `PATH` is used; ImgTune does not bundle it. Without it, animated media is still detected, and
+  its bytes and needed width are still reported, with one note: `install ffmpeg for verified video and GIF hints`. ffmpeg and
+  ffprobe read only the protocols they need, and a URL input goes through the egress proxy (the scan's own policy for
+  private addresses), so a scanned page cannot reach a private host through a video.
+- `imgtune image` accepts GIF, animated WebP and APNG (candidates: animated AVIF, animated WebP and AV1 MP4 at `--width`),
+  and MP4 and WebM. `--reference <original>` checks a candidate against the original with the same VMAF and still-frame bars.
+  It prints one line, `VMAF <v> (bar <b>) still p10 <s> (bar <sb>): pass|fail`, and exits 0 or 1.
+- `audit` locates `<video>` and GIF elements at `file:line`, as it locates images. `hints` prints the animated and video hints.
+- Network idle. A streaming media request does not hold the wait for network idle, so an autoplay video does not hold each
+  resize up to `--idle-timeout`.
+- Scan JSON. Each page gains `videos` and `mediaNote`, and an animated image record gains `fix.animated`. The resume record
+  gains the media settings (`mediaBudget`, `mediaTime`, `videoBar`, `videoStillBar`, `maxVideoWidths`, `ffmpeg`).
+- New flags, with their defaults: `--media-budget <N>` (20, 0 to 1000), `--media-time <s>` (600, 1 to 3600), `--video-bar <n>`
+  (93), `--video-still-bar <n>` (65), `--max-video-widths <n>` (2, 1 to 3). `--survey` and `--no-quality` make no encodes.
+  `image` takes `--reference`, `--video-bar` and `--video-still-bar`.
+- `--gpu-encode` (experimental, off by default). The media encodes run on the GPU with NVENC (`av1_nvenc`, `h264_nvenc`), and
+  VMAF runs on the GPU with `libvmaf_cuda` when the ffmpeg on `PATH` has it. The NVENC bytes are scaled by 1 / 1.4 to a CPU
+  encode and labelled `est. (GPU-encoded, scaled to a CPU encode ÷1.4)`. Each GPU is proven by a small test encode first, and
+  a width under 144 px is encoded on the CPU. In our measurements it was slower than the CPU on 2 s samples (CUDA starts once
+  per ffmpeg process), so the CPU stays the default.
+- `--gpu-device` takes a comma list (`0,1`). The first GPU scores. With `--gpu-encode`, each listed GPU gets its own encode
+  workers beside the CPU ones. `--gpu` alone is unchanged.
+- Ctrl-C and SIGTERM stop the whole run: the media phase is aborted, the pages already written are kept, and the process
+  exits 130 (SIGINT) or 143 (SIGTERM) within 2 s.
+- Media fetches and the ffmpeg reads of a page's videos go through the egress proxy. ffmpeg's `httpproxy` tunnel is allowed,
+  so `https` videos are read through it.
+- Animated WebP and APNG are decoded one frame at a time, only for the frames of each 2 s sample window, and streamed to
+  ffmpeg. A long animation does not fill memory, and the pixel limit applies to each frame.
+- A measured page's JSON is written after its image estimates and before the media phase, so a long media phase does not
+  hold back the results.
+- Cache: `CACHE_VERSION` is 3. Entries from 0.1 are not read, so the first scan on 0.2 is cold.
+- Changes for 0.1 users:
+  - A scan that encodes media takes longer. The encodes are bounded by `--media-time` (600 s) and `--media-budget` (20
+    assets); `--no-quality` or `--survey` keeps the 0.1 timing.
+  - Without ffmpeg on `PATH`, `scan` prints one note and gives no encode hints.
+  - `--resume` scans a 0.1 page again when the new run encodes media, because its record has no media settings. A run with
+    no encodes (`--no-quality`, `--survey`, or no ffmpeg) resumes 0.1 pages as before.
+  - The JSON gains fields (`videos`, `mediaNote`, `fix.animated`, the resume media settings); existing fields are unchanged.
+    Animated GIFs, WebP and APNG keep their place in the image totals, but their hint is now a video or animated-image hint.
+  - `<video>` elements are not image records: their bytes are in the Video section, and their posters are images.
+  - The cache is not reused across the version change (see above).
+
 ## 0.1.0 (2026-11-03)
 
 - LCP first. Each scanned page reads the largest contentful paint before its first scroll, per viewport. A page's report

package/README.md

@@ -2,20 +2,32 @@
 
 [![npm version](https://img.shields.io/npm/v/imgtune.svg)](https://www.npmjs.com/package/imgtune)
 
-**ImgTune measures image waste on any live site.**
+**imgtune measures page weight on any live site: images first, and everything else the page downloads.**
 
 Website: https://indicozy.github.io/imgtune/ · [Try the demo](https://indicozy.github.io/imgtune/demo) · [Docs](https://indicozy.github.io/imgtune/guide/getting-started)
 
-Lighthouse tells you your images are too big. ImgTune tells you the `sizes`, quality and format to set for each image,
-points at the line of code that renders it (when your dev server is running), and checks each quality target with
-SSIMULACRA2. Your coding agent applies the change, and a rescan checks it.
+Lighthouse tells you your page is heavy. imgtune tells you which bytes to cut and how: the `sizes`, quality and format for each image, the codec and width for each video, images and videos that load but are never shown, fonts to subset or drop, files served without compression, and 3D models, audio, Lottie and SVG that could be smaller. Each fix comes with the expected bytes and, for images and video with your dev server running, the line of code to change. Your coding agent applies it, and a rescan checks it.
 
 **Works with your image CDN.** Cloudinary, imgix and `next/image` resize to whatever width `sizes` asks for, so a wrong
 `sizes` is waste that no CDN removes. ImgTune works on top of a CDN, not instead of one. Already on Cloudinary auto
 quality (`q_auto`)? ImgTune focuses on `sizes`, which no CDN can fix for you. A format the CDN picks per request
 (Cloudinary `f_auto`, imgix `auto=format`) is not proposed as a change.
 
-**Built for image-heavy sites:** e-commerce catalogs, media, marketplaces.
+**Built for heavy sites:** e-commerce catalogs, media, marketplaces, and marketing pages with video and 3D.
+
+**What it checks**, one guide each:
+
+- [Images](https://indicozy.github.io/imgtune/guide/how-it-measures)
+- [Video and animated images](https://indicozy.github.io/imgtune/guide/video-and-gifs)
+- [Loaded but not shown](https://indicozy.github.io/imgtune/guide/hidden-images)
+- [Fonts](https://indicozy.github.io/imgtune/guide/fonts)
+- [Compression](https://indicozy.github.io/imgtune/guide/compression)
+- [Vector art (raster to SVG)](https://indicozy.github.io/imgtune/guide/vector-art)
+- [SVG](https://indicozy.github.io/imgtune/guide/svg)
+- [Lottie](https://indicozy.github.io/imgtune/guide/lottie)
+- [3D models](https://indicozy.github.io/imgtune/guide/3d-models)
+- [Audio](https://indicozy.github.io/imgtune/guide/audio)
+- [Favicons](https://indicozy.github.io/imgtune/guide/favicons)
 
 ## Two ways to measure
 
@@ -129,6 +141,14 @@ desktop at 1x), scrolls it to the end, and records every image.
 - Production check: `imgtune check` (see [Two ways to measure](#two-ways-to-measure)) and `imgtune audit` do the same
   survey and deep scan for a whole site, with no source needed for `check`.
 
+## Resources
+
+`scan` also reads the page's other responses (not images) and runs seven checks on them: compression, favicons, fonts,
+SVG, Lottie, 3D models and audio. They are reported on their own, not in the image totals. Guides:
+[compression](https://indicozy.github.io/imgtune/guide/compression), [favicons](https://indicozy.github.io/imgtune/guide/favicons), [fonts](https://indicozy.github.io/imgtune/guide/fonts), [SVG](https://indicozy.github.io/imgtune/guide/svg), [Lottie](https://indicozy.github.io/imgtune/guide/lottie),
+[3D models](https://indicozy.github.io/imgtune/guide/3d-models) and [audio](https://indicozy.github.io/imgtune/guide/audio). The [resources overview](https://indicozy.github.io/imgtune/guide/resources) covers the labels, the budget
+and the flags: `--no-resources` turns all seven off, and `--resource-time` caps the heavy work.
+
 ## The evidence ladder
 
 Every fix hint is labelled with the strength of its evidence, the rung it stands on:
@@ -143,6 +163,89 @@ Every fix hint is labelled with the strength of its evidence, the rung it stands
 A ceiling is never derived from the existing `sizes` value. When a usage is measured, its `sizes` comes from the layout
 the browser resolved, not from a guess.
 
+## Lottie and SVG
+
+`scan` also reads the Lottie animations and the SVG files a page loads. A Lottie report gives the size, layers, frame rate and
+duration, and its savings: embedded rasters re-encoded to WebP at the display size, a `.lottie` repack (an estimate), and
+numbers rounded to three decimals. An SVG is optimised with SVGO and reported when the brotli size drops by 20% or more and
+the render still scores 70 or more on SSIMULACRA2 at half size. Guides: [Lottie](https://indicozy.github.io/imgtune/guide/lottie) and [SVG](https://indicozy.github.io/imgtune/guide/svg).
+
+## 3D models and audio
+
+`scan` also reads the 3D models and audio files a page loads. A glTF or GLB gets a measured meshopt saving (the file is
+repacked with gltf-transform), base64 buffers get the GLB repack, and PNG or JPEG textures get a WebP estimate. An audio
+file that is lossless, above 128 kbps stereo, or stereo with identical channels gets an Opus re-encode, measured on a 10 s
+sample with ffmpeg. Guides: [3D models](https://indicozy.github.io/imgtune/guide/3d-models) and [audio](https://indicozy.github.io/imgtune/guide/audio).
+
+## Vector art
+
+A flat logo, icon or illustration served as PNG, WebP or JPEG can often be an SVG: smaller, and sharp at every density.
+`scan` traces the heaviest flat images (`--svg-budget`, default 50) with an optional dependency, `@neplex/vectorizer`,
+renders each SVG back, and keeps it only when it scores at least 70 at half size and is at least 30% smaller. A passing
+trace is written to `svg/` in the scan folder. Without the dependency, a flat image gets one note and no byte claim. See [the guide](https://indicozy.github.io/imgtune/guide/vector-art).
+
+## Loaded but not shown
+
+`scan` also finds the images the browser downloads without showing: a desktop image hidden on phones (or the reverse), an
+offscreen slide of a carousel, a tab panel, an element with `opacity: 0` or `visibility: hidden`, and a zero-size box. Their
+bytes per view are reported on their own line ("loaded but not shown") and kept out of the savings. Each one gets the fix
+for its case: a `<picture>` with a media condition for a responsive twin, `loading="lazy"` or render-on-activation for a
+carousel, tab or hover copy, and an on-demand load or removal for an image no viewport shows on load. See [the guide](https://indicozy.github.io/imgtune/guide/hidden-images).
+
+## GIFs and video
+
+`scan` also measures animated media: animated GIFs in an `<img>` or a CSS background, animated WebP and APNG, and
+self-hosted `<video>` elements with a plain file source. Static GIFs get the normal image hints.
+
+- **Out of scope, not reported:** adaptive streams (HLS, DASH, Mux, Cloudflare Stream) and third-party iframes (YouTube,
+  Vimeo). A video hosted on another site follows the third-party rules (`--block-third-party`, `--allow-host`).
+- **ffmpeg** is used from `PATH`; ImgTune does not bundle it. Without it, `scan` still reports each animated image's and
+  video's bytes and the width it needs, and prints one note: `install ffmpeg for verified video and GIF hints`. The encodes,
+  and so the fix hints with a size, need it.
+- **Encodes run on the CPU by default.** `--gpu-encode` is **experimental**: it moves the sample encodes to the GPU (NVENC
+  `av1_nvenc` / `h264_nvenc`, preset p4, constant quality in VBR; `libvmaf_cuda` for the VMAF). It uses the `--gpu-device`
+  list, else GPU 0, in workers beside the CPU ones. Each GPU is proven by a tiny test encode first; a width under 144 px or
+  an NVENC failure is encoded on the CPU for that candidate. NVENC is larger at equal quality, so its bytes are reported as
+  NVENC bytes ÷ 1.4, labelled `est. (GPU-encoded, scaled to a CPU encode ÷1.4)`. In our measurements `--gpu-encode` was
+  slower than the CPU (per-process CUDA start-up); see the report before using it. `--gpu` and `--gpu-device` only pick the
+  SSIMULACRA2 GPU scorer (the first device) unless `--gpu-encode` is given. The hint's recipe is the CPU one (`libsvtav1` / `libx264`), and an NVENC
+  quality is marked `approx.` (CRF = cq).
+- **Hints.** A large animated GIF gets `<video autoplay muted loop playsinline>` with AV1 first and an H.264 fallback, and
+  the animated-image alternative with its size. A small `<img>` GIF or a CSS background gets an animated AVIF or WebP. A
+  `<video>` hint names each lever: the width per breakpoint (`<source media>`), the CRF, the codec, the audio track of a
+  muted video, and `preload`. A poster is audited as an image. Duration and frame rate are informational only.
+- **Bytes: per view and per play.** Per view is counted at each viewport and averaged over the viewports, as for images. An
+  autoplay video counts its full file,
+  `preload="auto"` counts the bytes the scan saw (browser-dependent), and `preload="metadata"` or `"none"` counts 0. Per
+  play is the full file. Both are shown for every video, so a large click-to-play file is not missed. Animated images stay
+  in the image totals; `<video>` has its own Video section, and posters count as images.
+- **Estimates come from 2 s samples.** One sample for a video of up to 6 s, three for a longer one. The full-file bytes
+  are extrapolated from the samples and labelled as an estimate; nothing is encoded in full.
+- **Quality bars.** VMAF must reach `--video-bar` (default 93) against the served file at its display size. A still-frame
+  guard (SSIMULACRA2 on the stillest frames) catches blurred text in screen recordings and must reach `--video-still-bar`
+  (default 65), lowered to at most 10 points below the best the codec reaches on that content, and never below 20. The
+  relative bar catches the loss the encode adds, not what the format can never reproduce, such as GIF dither.
+- **Budget and widths.** Encodes run on the heaviest animated assets first, at most `--media-budget` per run (default 20)
+  and within `--media-time` seconds (default 600). Assets over the budget keep their cheap hints and are marked "over
+  --media-budget". A video is served at most `--max-video-widths` widths (default 2): each viewport gets the smallest
+  kept width that covers its display width times its device pixel ratio. `audit` reports the bytes at one, two and three
+  widths instead, and the agent chooses. `--no-quality` and `--survey` make no encodes.
+- **Check an agent's output** with `imgtune image <candidate> --reference <original>`: the same VMAF and still-frame bar,
+  exit 0 on pass and 1 on fail (see the table below).
+
+## Fonts
+
+`scan` reports each web font file the page downloads: its bytes per view, and what it could save.
+
+- **WOFF2:** a TTF, OTF or WOFF that is not WOFF2 is re-encoded (measured for small files, estimated for large ones).
+- **Subsetting:** a font with far more glyphs than the page's scripts need (the Unicode blocks its text uses, plus Basic
+  Latin, Latin-1, punctuation and currency) is subset to them. The fix gives the `pyftsubset` command.
+- **Unused faces:** a face the browser downloaded but no rendered text uses is wasted bytes. Icon fonts, and faces the
+  browser rendered with (even as a fallback), are never called unused.
+- **Static weights:** three or more static faces of one family are noted as a candidate for one variable font (no saving).
+
+See [the Fonts guide](https://indicozy.github.io/imgtune/guide/fonts).
+
 ## Commands
 
 | command | what it does |
@@ -155,6 +258,7 @@ the browser resolved, not from a guess.
 | `imgtune summary <run dir \| scan.json ...>` | the one-screen summary of a run directory (`run.json`) or of scan files |
 | `imgtune scan --recheck <scan.json> [--ids a,b,c]` | rescans only the named images at the viewports where they rendered; prints before and after; exits 1 on a failed check |
 | `imgtune image <file\|url\|glob>` | measures image files without a page: bytes now, the lowest quality per format that meets the bar, and at a `--width` the bytes at each needed width; `--min-score` sets the bar (default 90), `--write <dir>` writes optimised copies |
+| `imgtune image <animated.gif\|.webp\|.png\|video> --reference <original>` | checks a re-encoded video or animated file against the original: `VMAF … still p10 …: pass\|fail` with exit 0 or 1; `--video-bar` (default 93) and `--video-still-bar` (default 65) set the bars; without `--reference` an animated file gets its candidates (needs ffmpeg) |
 | `imgtune compare <before.json> <after.json>` | compares two scans of one page image by image: the bytes saved and the sharpness bytes added, as two numbers; drift (a changed layout, server variance, a view not loaded) is excluded and its totals printed; `--format json`, `--limit` |
 | `imgtune report` | a Markdown run report from the agent's ledger (`.imgtune/ledger.jsonl`); `--compare <file>` adds the bytes from `imgtune compare --format json`; `--out <file>` writes it |
 

package/dist/animated.js

@@ -0,0 +1,176 @@
+// Animation detection by byte parsing: GIF, animated WebP and APNG. It needs no decoder and no sharp, so a scan can
+// tell an animated file from a still one from the bytes it already downloaded. Only the container structure is read
+// (block headers, chunk lengths and the timing fields); pixels are never decoded.
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/**
+ * Returns the animation in a file, or undefined when the file is not animated (one frame, another format, or a
+ * format this does not read). A truncated or corrupt file never throws: it reports what was readable before the
+ * damage, or undefined. Used by the scan to decide whether an image is a GIF or animated WebP/APNG that a video
+ * encode could replace.
+ */
+export function animationOf(buffer) {
+    try {
+        const info = detect(buffer);
+        return info && info.frames > 1 ? info : undefined;
+    }
+    catch {
+        // Every read below is bounds-checked, so this is a last guard for a malformed buffer, not a normal path.
+        return undefined;
+    }
+}
+function detect(b) {
+    const head6 = b.toString("latin1", 0, 6);
+    if (head6 === "GIF87a" || head6 === "GIF89a")
+        return parseGif(b);
+    if (b.length >= 12 && b.toString("latin1", 0, 4) === "RIFF" && b.toString("latin1", 8, 12) === "WEBP") {
+        return parseWebp(b);
+    }
+    if (b.length >= 8 && b.subarray(0, 8).equals(PNG_SIGNATURE))
+        return parseApng(b);
+    return undefined;
+}
+/** Colour-table size in bytes for a packed-flags byte whose table flag is set (3 bytes per entry, 2^(n+1) entries). */
+function colourTableBytes(packed) {
+    return 3 * 2 ** ((packed & 0x07) + 1);
+}
+/**
+ * Skips a run of GIF data sub-blocks (a size byte, then that many bytes, ending with a zero-size block) starting at
+ * p, and returns the offset just after the terminator. A run that runs past the end returns an offset past the end,
+ * which the caller's loop treats as the end of the file.
+ */
+function skipSubBlocks(b, p) {
+    while (p < b.length) {
+        const size = b[p];
+        if (size === 0)
+            return p + 1;
+        p += size + 1;
+    }
+    return p;
+}
+/**
+ * Walks GIF blocks. Frames are counted as image descriptors (0x2C); each frame's delay comes from the Graphic
+ * Control Extension (0x21 0xF9) just before it, in hundredths of a second. The loop count comes from the NETSCAPE2.0
+ * application extension.
+ */
+function parseGif(b) {
+    if (b.length < 13)
+        return undefined;
+    let pos = 13;
+    if (b[10] & 0x80)
+        pos += colourTableBytes(b[10]);
+    let frames = 0;
+    let durationMs = 0;
+    let pendingDelayCs = 0;
+    let loop;
+    while (pos < b.length) {
+        const introducer = b[pos];
+        if (introducer === 0x3b)
+            break; // trailer: end of the GIF
+        if (introducer === 0x21) {
+            // Extension: label, then sub-blocks. Application extensions start with an 11-byte identifier sub-block.
+            if (pos + 2 > b.length)
+                break;
+            const label = b[pos + 1];
+            if (label === 0xf9 && pos + 6 <= b.length) {
+                pendingDelayCs = b.readUInt16LE(pos + 4);
+            }
+            else if (label === 0xff && pos + 3 + 11 <= b.length) {
+                const identifier = b.toString("latin1", pos + 3, pos + 14);
+                if (identifier === "NETSCAPE2.0" || identifier === "ANIMEXTS1.0") {
+                    const loopBlock = pos + 14;
+                    if (loopBlock + 5 <= b.length && b[loopBlock] === 3 && b[loopBlock + 1] === 1) {
+                        loop = b.readUInt16LE(loopBlock + 2);
+                    }
+                }
+            }
+            pos = skipSubBlocks(b, pos + 2);
+        }
+        else if (introducer === 0x2c) {
+            // Image descriptor: separator, 4 x u16 position and size, packed flags, then LZW code size and sub-blocks.
+            if (pos + 10 > b.length)
+                break;
+            const packed = b[pos + 9];
+            let p = pos + 10;
+            if (packed & 0x80)
+                p += colourTableBytes(packed);
+            p += 1; // LZW minimum code size
+            frames += 1;
+            // A delay of 0 or 1 cs is shown as 10 cs (100 ms), as browsers show it, so the length is not understated.
+            durationMs += (pendingDelayCs <= 1 ? 10 : pendingDelayCs) * 10;
+            pendingDelayCs = 0;
+            pos = skipSubBlocks(b, p);
+        }
+        else {
+            break; // not a block introducer: the file is corrupt from here on
+        }
+    }
+    return { format: "gif", frames, durationMs, loop: loop ?? 1 };
+}
+/**
+ * Walks RIFF chunks of a WebP. Animation needs the VP8X animation flag (bit 1 of its first byte). ANIM holds the loop
+ * count (u16 at data offset 4). Each ANMF chunk is one frame, and its 24-bit duration is at data offset 12.
+ */
+function parseWebp(b) {
+    let pos = 12;
+    let animated = false;
+    let loop = 0;
+    let frames = 0;
+    let durationMs = 0;
+    while (pos + 8 <= b.length) {
+        const type = b.toString("latin1", pos, pos + 4);
+        const size = b.readUInt32LE(pos + 4);
+        const data = pos + 8;
+        if (type === "VP8X" && data + 1 <= b.length) {
+            animated = (b[data] & 0x02) !== 0;
+        }
+        else if (type === "ANIM" && data + 6 <= b.length) {
+            loop = b.readUInt16LE(data + 4);
+        }
+        else if (type === "ANMF" && data + 15 <= b.length) {
+            frames += 1;
+            durationMs += b.readUIntLE(data + 12, 3);
+        }
+        pos = data + size + (size & 1); // chunks are padded to an even length
+    }
+    if (!animated)
+        return undefined;
+    return { format: "webp", frames, durationMs, loop };
+}
+/**
+ * Walks PNG chunks of an APNG. The acTL chunk must come before the first IDAT; it holds num_frames and num_plays (0
+ * means loop forever). Each fcTL chunk is one frame, and its delay is delay_num / delay_den seconds (a zero
+ * delay_den means 100).
+ */
+function parseApng(b) {
+    let pos = 8;
+    let frames;
+    let loop = 0;
+    let durationMs = 0;
+    let sawIdat = false;
+    while (pos + 8 <= b.length) {
+        const length = b.readUInt32BE(pos);
+        const type = b.toString("latin1", pos + 4, pos + 8);
+        const data = pos + 8;
+        if (data + length > b.length)
+            break; // a chunk cut short by truncation
+        if (type === "IDAT") {
+            sawIdat = true;
+        }
+        else if (type === "acTL" && !sawIdat && length >= 8) {
+            frames = b.readUInt32BE(data);
+            loop = b.readUInt32BE(data + 4);
+        }
+        else if (type === "fcTL" && length >= 26) {
+            const delayNum = b.readUInt16BE(data + 20);
+            const delayDen = b.readUInt16BE(data + 22) || 100;
+            durationMs += (delayNum * 1000) / delayDen;
+        }
+        else if (type === "IEND") {
+            break;
+        }
+        pos = data + length + 4; // skip the CRC
+    }
+    if (frames === undefined)
+        return undefined;
+    return { format: "apng", frames, durationMs: Math.round(durationMs), loop };
+}

package/dist/audit.js

@@ -232,6 +232,7 @@ async function preflight(prod, settings, outRoot, cwd, log, storageState) {
         ignoreRobots: settings.ignoreRobots,
         aggressive: false,
         quality: false,
+        resources: false,
         thirdParty: settings.thirdParty,
         outDir: join(outRoot, "preflight"),
         viewports: viewportsOf(plan.viewports),

package/dist/backgrounds.js

@@ -6,7 +6,8 @@
 // Pure parsing and sizing here; the measurement (fetches, decodes, resize estimates) is in remote.ts, and the records are
 // built in buildBackgroundRecords below.
 import { sha1 } from "./atomic.js";
-import { rungOfPage, searchHintsOf } from "./images.js";
+import { hiddenFixCore, losslessServed, rungOfPage, searchHintsOf } from "./images.js";
+import { animatedTarget } from "./media-model.js";
 import { loaderName, sanitizeText, urlPattern } from "./locate.js";
 /** The most background elements read per viewport: a page with more keeps the first of them in document order. */
 export const MAX_BACKGROUND_ELEMENTS = 1000;
@@ -263,7 +264,8 @@ export function buildBackgroundRecords(input) {
     }
     const records = [];
     for (const [key, members] of byKey) {
-        const member = members.find((m) => m.viewport.name === refName) ?? members[0];
+        // The reference member is shown when some viewport shows the layer: a hidden copy names no size.
+        const member = members.find((m) => m.viewport.name === refName && m.hidden === undefined) ?? members.find((m) => m.hidden === undefined) ?? members[0];
         const source = sources.get(member.bg.index);
         const url = member.url;
         const perViewport = [];
@@ -286,11 +288,27 @@ export function buildBackgroundRecords(input) {
                 entry.overFetchRatio = Math.round((inst.pixelWidth / inst.needed) * 100) / 100;
             if (inst.skipped !== undefined)
                 entry.skipped = inst.skipped;
+            if (inst.hidden !== undefined)
+                entry.hidden = inst.hidden;
             perViewport.push(entry);
         }
+        // A layer's entries: the viewports it is shown at, and those it is hidden at with its file downloaded (a hidden layer that
+        // was not downloaded is not an entry: there are no bytes to report).
+        const entries = members
+            .filter((m) => m.hidden !== undefined || m.skipped !== "hidden")
+            .map((m) => ({
+            viewport: { name: m.viewport.name, width: m.viewport.width },
+            bytes: m.bytes,
+            hidden: m.hidden,
+            inPanel: m.inPanel === true,
+            hover: m.hover === true,
+        }));
+        const hiddenFix = hiddenFixCore(entries, input.viewports.length);
         const saved = members.reduce((sum, m) => sum + m.est, 0) / viewportCount;
         const served = member.format;
-        const best = served === "jpeg" || served === "png" ? (saved > 0 ? "avif" : served) : served;
+        const animatedMember = members.find((m) => m.animated !== undefined);
+        const lossless = losslessServed(served, animatedMember !== undefined);
+        const best = lossless ? (saved > 0 ? "avif" : served) : served;
         const locator = locatorOfBackground(pageUrl, url, member.bg, source);
         const notes = [
             `css background: layer ${member.layer + 1}, background-size "${sanitizeText(member.size, 60)}", drawn ${Math.round(member.displayedCss)} CSS px at the reference viewport`,
@@ -321,19 +339,36 @@ export function buildBackgroundRecords(input) {
             },
             perViewport,
             fix: {
-                width: member.needed > 0 ? member.needed : undefined,
-                bytes: { saved, addedForSharpness: 0, sizes: 0, quality: saved },
+                width: member.hidden === undefined && member.needed > 0 ? member.needed : undefined,
+                // A layer's saving is a resize to its needed width (est.), not a re-encode: booked as resize.
+                bytes: { saved, addedForSharpness: 0, sizes: 0, resize: saved, quality: 0 },
             },
             evidence: { rung: rungOfPage(pageUrl, input.harness), notes },
         };
         if (best !== undefined)
             record.fix.format = best;
+        if (animatedMember?.animated !== undefined && hiddenFix?.shownIn.length !== 0) {
+            record.fix.animated = {
+                info: animatedMember.animated,
+                context: "css-background",
+                target: animatedTarget("css-background", undefined),
+                perViewBytes: members.reduce((sum, m) => sum + m.bytes, 0) / viewportCount,
+            };
+        }
+        // A hidden layer is not a vector claim: the vector check and the hidden fix never stack on one record.
+        if (hiddenFix !== undefined)
+            record.hidden = hiddenFix;
+        else {
+            const flatMember = members.find((m) => m.flatness?.flat === true);
+            if (flatMember?.flatness !== undefined)
+                record.fix.vector = { flatness: { ...flatMember.flatness } };
+        }
         records.push(record);
     }
     return records.filter((r) => r.perViewport.some((p) => p.loaded || p.skipped !== undefined));
 }
 export function backgroundTotals(instances) {
-    const measured = instances.filter((i) => i.skipped === undefined);
+    const measured = instances.filter((i) => i.skipped === undefined && i.hidden === undefined);
     return {
         measured: measured.length,
         servedBytes: measured.reduce((sum, i) => sum + i.bytes, 0),
@@ -342,7 +377,7 @@ export function backgroundTotals(instances) {
     };
 }
 export function backgroundPage(instances, viewportCount, records) {
-    const measured = instances.filter((i) => i.skipped === undefined);
+    const measured = instances.filter((i) => i.skipped === undefined && i.hidden === undefined);
     return {
         layers: records.filter((r) => r.perViewport.some((p) => p.loaded)).length,
         servedBytes: measured.reduce((sum, i) => sum + i.bytes, 0) / viewportCount,

package/dist/broken.js

@@ -25,7 +25,11 @@ export function brokenOf(result, expectedImages) {
             fix: "the URL does not serve this page: check the path, and that the server being scanned serves this route",
         };
     }
-    if (result.stylesheetsFailed !== undefined && Object.keys(result.stylesheetsFailed).length > 0) {
+    // A failed stylesheet breaks the page only when the page is unstyled (no linked stylesheet applied) or empty (no images).
+    // A partly styled page with a failed sheet, usually a third-party CDN's, is measured and warned about (the scan prints it).
+    const unstyled = (result.stylesheetsLoaded ?? 0) === 0;
+    const empty = result.counts.images === 0;
+    if (result.stylesheetsFailed !== undefined && Object.keys(result.stylesheetsFailed).length > 0 && (unstyled || empty)) {
         const hosts = result.stylesheetHosts ?? [];
         // The most failed in any one view: the same sheet at two viewports is one sheet, not two.
         const count = Math.max(...Object.values(result.stylesheetsFailed));