imgtune 0.1.0 → 0.3.0

package/dist/webp-animation.js

@@ -0,0 +1,283 @@
+// An animated WebP read one frame at a time. ffmpeg cannot read an animated WebP, and sharp can extract one page only by
+// decoding every page before it (its cost grows with the page index), so the frames are read here instead: each ANMF frame is
+// split out as a still WebP, decoded alone by sharp, and composited onto a canvas as the WebP spec describes (the frame's
+// rectangle, its blend mode, and the previous frame's dispose). Memory is about one canvas and one frame, whatever the length.
+//
+// Random access is cheap where the file allows it: a frame that covers the whole canvas and either does not blend or is opaque
+// does not depend on the canvas before it (a keyframe), so composition restarts there. Between keyframes the frames are
+// composed in order, so a sequential read (which is how every caller reads) costs one decode per frame.
+import sharp from "sharp";
+import { MAX_INPUT_PIXELS_FFMPEG, PixelsTooLarge } from "./media-limits.js";
+/** The shortest frame a browser shows: a frame of 0 ms is shown for 10 ms. */
+const MIN_FRAME_MS = 10;
+/** The ticks of a constant-rate timeline: at least one, the frame on screen at each tick (see cfrIndices). */
+export function ticksOf(delaysMs, fps) {
+    const total = delaysMs.reduce((acc, d) => acc + d, 0);
+    return Math.max(1, Math.round((total * fps) / 1000));
+}
+/**
+ * The indices of the frames on screen at each constant-rate tick. Frame i covers [start, start + delay) in ms, and tick k is
+ * at (k + phase) × 1000 / fps: phase 0 is the tick's start, 0.5 its middle. A frame that lasts several ticks repeats; the
+ * last frame holds to the end.
+ */
+export function cfrIndices(delaysMs, fps, ticks, phase = 0) {
+    const out = [];
+    let frame = 0;
+    let start = 0;
+    for (let k = 0; k < ticks; k++) {
+        const at = ((k + phase) * 1000) / fps;
+        while (frame < delaysMs.length - 1 && start + delaysMs[frame] <= at) {
+            start += delaysMs[frame];
+            frame++;
+        }
+        out.push(frame);
+    }
+    return out;
+}
+/** A RIFF chunk: its four-character type and its payload (the padding byte is not in the payload). */
+function chunksOf(bytes, start, end) {
+    const out = [];
+    let pos = start;
+    while (pos + 8 <= end) {
+        const type = bytes.toString("latin1", pos, pos + 4);
+        const size = bytes.readUInt32LE(pos + 4);
+        const dataEnd = Math.min(pos + 8 + size, end);
+        out.push({ type, data: bytes.subarray(pos + 8, dataEnd) });
+        pos = pos + 8 + size + (size & 1);
+    }
+    return out;
+}
+/** A RIFF file of the given chunks, as a WebP. */
+function riffWebp(chunks) {
+    const parts = [];
+    for (const chunk of chunks) {
+        const head = Buffer.alloc(8);
+        head.write(chunk.type, 0, "latin1");
+        head.writeUInt32LE(chunk.data.length, 4);
+        parts.push(head, chunk.data);
+        if (chunk.data.length & 1)
+            parts.push(Buffer.alloc(1));
+    }
+    const body = Buffer.concat([Buffer.from("WEBP", "latin1"), ...parts]);
+    const head = Buffer.alloc(8);
+    head.write("RIFF", 0, "latin1");
+    head.writeUInt32LE(body.length, 4);
+    return Buffer.concat([head, body]);
+}
+/** The VP8X chunk of a still with alpha, on a canvas of the frame's size. */
+function vp8xChunk(width, height, alpha) {
+    const data = Buffer.alloc(10);
+    data[0] = alpha ? 0x10 : 0;
+    data.writeUIntLE(width - 1, 4, 3);
+    data.writeUIntLE(height - 1, 7, 3);
+    return { type: "VP8X", data };
+}
+/**
+ * The size of a still WebP from its bitstream header (VP8 or VP8L), or undefined when it has neither.
+ */
+function stillSizeOf(top) {
+    const vp8 = top.find((c) => c.type === "VP8 ");
+    if (vp8 !== undefined && vp8.data.length >= 10 && vp8.data[3] === 0x9d && vp8.data[4] === 0x01 && vp8.data[5] === 0x2a) {
+        return { width: vp8.data.readUInt16LE(6) & 0x3fff, height: vp8.data.readUInt16LE(8) & 0x3fff };
+    }
+    const vp8l = top.find((c) => c.type === "VP8L");
+    if (vp8l !== undefined && vp8l.data.length >= 5 && vp8l.data[0] === 0x2f) {
+        const bits = vp8l.data.readUInt32LE(1);
+        return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+    }
+    return undefined;
+}
+/**
+ * Splits an animated WebP into its frames. A still WebP (one image, which an encoder writes when its frames are all alike) is
+ * one frame held for `stillMs` (at least MIN_FRAME_MS): that is how a candidate of a sample is read. Throws when the file is not
+ * a WebP, or has no image. The pixels are not decoded here; each frame's standalone still is kept for decoding when it is needed.
+ */
+export function parseWebpAnimation(bytes, stillMs = 0) {
+    if (bytes.length < 12 || bytes.toString("latin1", 0, 4) !== "RIFF" || bytes.toString("latin1", 8, 12) !== "WEBP") {
+        throw new Error("not a WebP file");
+    }
+    const top = chunksOf(bytes, 12, bytes.length);
+    const canvas = top.find((c) => c.type === "VP8X");
+    if (canvas === undefined || canvas.data.length < 10 || (canvas.data[0] & 0x02) === 0) {
+        const size = stillSizeOf(top);
+        const image = top.find((c) => c.type === "VP8 " || c.type === "VP8L");
+        if (size === undefined || image === undefined)
+            throw new Error("not an animated WebP");
+        const still = riffWebp([image]);
+        const frame = {
+            x: 0,
+            y: 0,
+            width: size.width,
+            height: size.height,
+            durationMs: Math.max(MIN_FRAME_MS, stillMs),
+            noBlend: true,
+            dispose: false,
+            keyframe: true,
+            still,
+        };
+        return { canvasWidth: size.width, canvasHeight: size.height, frames: [frame] };
+    }
+    const canvasWidth = 1 + canvas.data.readUIntLE(4, 3);
+    const canvasHeight = 1 + canvas.data.readUIntLE(7, 3);
+    const raw = top.filter((c) => c.type === "ANMF");
+    if (raw.length === 0)
+        throw new Error("the animated WebP has no frame");
+    const frames = raw.map((anmf, index) => {
+        const d = anmf.data;
+        if (d.length < 16)
+            throw new Error(`frame ${index} is truncated`);
+        const x = 2 * d.readUIntLE(0, 3);
+        const y = 2 * d.readUIntLE(3, 3);
+        const width = 1 + d.readUIntLE(6, 3);
+        const height = 1 + d.readUIntLE(9, 3);
+        const durationMs = Math.max(MIN_FRAME_MS, d.readUIntLE(12, 3));
+        const flags = d[15];
+        const parts = chunksOf(d, 16, d.length);
+        const alph = parts.find((c) => c.type === "ALPH");
+        const vp8 = parts.find((c) => c.type === "VP8 ");
+        const vp8l = parts.find((c) => c.type === "VP8L");
+        let still;
+        let opaque;
+        if (vp8l !== undefined) {
+            still = riffWebp([vp8l]);
+            opaque = false;
+        }
+        else if (vp8 !== undefined) {
+            const chunks = alph !== undefined ? [vp8xChunk(width, height, true), alph, vp8] : [vp8xChunk(width, height, false), vp8];
+            still = riffWebp(chunks);
+            opaque = alph === undefined;
+        }
+        else {
+            throw new Error(`frame ${index} has no image data`);
+        }
+        const noBlend = (flags & 0x02) !== 0;
+        const covers = x === 0 && y === 0 && width === canvasWidth && height === canvasHeight;
+        return { x, y, width, height, durationMs, noBlend, dispose: (flags & 0x01) !== 0, keyframe: covers && (noBlend || opaque), still };
+    });
+    return { canvasWidth, canvasHeight, frames };
+}
+/**
+ * An animated WebP, read frame by frame at the constant-rate timeline of `fps`. The frames are composed in order and decoded
+ * on demand: `page(i)` returns the canvas as it stands at frame i (a copy, so the caller may keep it). The per-frame pixel limit
+ * is checked from the header, before any frame is decoded.
+ */
+export class WebpAnimation {
+    width;
+    height;
+    /** The frames of the animation. */
+    pages;
+    /** The duration of each frame, in ms (at least MIN_FRAME_MS). */
+    delaysMs;
+    /** The frame on screen at each constant-rate tick (see cfrIndices). */
+    tickPages;
+    /** The whole animation's length, in ms. */
+    durationMs;
+    /** The constant rate the ticks are taken at. */
+    fps;
+    frames;
+    prevKeyframe;
+    framePixelLimit;
+    canvas;
+    /** The frame the canvas holds, or -1 before the first frame. */
+    index = -1;
+    /**
+     * `phase` places the ticks inside their intervals (see cfrIndices): 0 for the source, where a tick is the frame on screen at
+     * its start; 0.5 for an encoded candidate, whose rounded frame starts would otherwise shift a tick into the frame before.
+     */
+    constructor(bytes, fps, framePixelLimit = MAX_INPUT_PIXELS_FFMPEG, stillMs = 0, phase = 0) {
+        this.fps = fps;
+        const parsed = parseWebpAnimation(bytes, stillMs);
+        if (parsed.canvasWidth * parsed.canvasHeight > framePixelLimit) {
+            throw new PixelsTooLarge(parsed.canvasWidth, parsed.canvasHeight, framePixelLimit);
+        }
+        this.width = parsed.canvasWidth;
+        this.height = parsed.canvasHeight;
+        this.frames = parsed.frames;
+        this.pages = parsed.frames.length;
+        this.delaysMs = parsed.frames.map((f) => f.durationMs);
+        this.durationMs = this.delaysMs.reduce((acc, d) => acc + d, 0);
+        this.tickPages = cfrIndices(this.delaysMs, fps, ticksOf(this.delaysMs, fps), phase);
+        this.prevKeyframe = [];
+        let last = -1;
+        parsed.frames.forEach((f, i) => {
+            if (f.keyframe)
+                last = i;
+            this.prevKeyframe.push(last);
+        });
+        this.canvas = new Uint8ClampedArray(this.width * this.height * 4);
+        this.framePixelLimit = framePixelLimit;
+    }
+    /** The canvas at frame `index`, as a copy. Frames are read in order; going back restarts at the last keyframe before. */
+    async page(index) {
+        if (index < 0 || index >= this.pages)
+            throw new Error(`frame ${index} is out of range`);
+        if (index < this.index || this.prevKeyframe[index] > this.index) {
+            const key = this.prevKeyframe[index];
+            this.canvas.fill(0);
+            this.index = -1;
+            if (key >= 0) {
+                await this.compose(key);
+                this.index = key;
+            }
+        }
+        while (this.index < index) {
+            const next = this.index + 1;
+            if (next > 0 && this.frames[next - 1].dispose)
+                this.clear(this.frames[next - 1]);
+            await this.compose(next);
+            this.index = next;
+        }
+        return { data: new Uint8ClampedArray(this.canvas), width: this.width, height: this.height };
+    }
+    /** The canvas of the ticks [from, to), one frame copy per tick, for a raw video stream (see the sample cut). */
+    async *ticks(from, to) {
+        for (let k = from; k < to; k++) {
+            const frame = await this.page(this.tickPages[Math.min(k, this.tickPages.length - 1)]);
+            yield Buffer.from(frame.data.buffer, frame.data.byteOffset, frame.data.byteLength);
+        }
+    }
+    /** Decodes frame `index` alone and draws it onto the canvas. */
+    async compose(index) {
+        const frame = this.frames[index];
+        const { data, info } = await sharp(frame.still, { limitInputPixels: this.framePixelLimit })
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        if (info.width !== frame.width || info.height !== frame.height)
+            throw new Error(`frame ${index} decoded at the wrong size`);
+        const src = new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength);
+        const cw = this.width;
+        const dst = this.canvas;
+        for (let row = 0; row < frame.height; row++) {
+            for (let col = 0; col < frame.width; col++) {
+                const s = (row * frame.width + col) * 4;
+                const d = ((frame.y + row) * cw + frame.x + col) * 4;
+                const sa = src[s + 3];
+                if (frame.noBlend || sa === 255) {
+                    dst[d] = src[s];
+                    dst[d + 1] = src[s + 1];
+                    dst[d + 2] = src[s + 2];
+                    dst[d + 3] = sa;
+                }
+                else if (sa !== 0) {
+                    // Source-over blending of non-premultiplied colour (the WebP "alpha-blend" mode).
+                    const a = sa / 255;
+                    const da = dst[d + 3] / 255;
+                    const outA = a + da * (1 - a);
+                    if (outA > 0) {
+                        for (let c = 0; c < 3; c++)
+                            dst[d + c] = (src[s + c] * a + dst[d + c] * da * (1 - a)) / outA;
+                    }
+                    dst[d + 3] = outA * 255;
+                }
+            }
+        }
+    }
+    /** Clears a frame's rectangle to transparent (its dispose). */
+    clear(frame) {
+        for (let row = 0; row < frame.height; row++) {
+            const start = ((frame.y + row) * this.width + frame.x) * 4;
+            this.canvas.fill(0, start, start + frame.width * 4);
+        }
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "imgtune",
-  "version": "0.1.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.