imgtune 0.1.0 → 0.2.0

package/dist/result-cache.js

@@ -15,13 +15,22 @@ export const CACHE_DIR = join(".imgtune", "cache");
 /** The most the cache may hold; the oldest entries go first. */
 export const CACHE_MAX_BYTES = 500 * 1024 * 1024;
 /** Bumped when what an entry means changes, so the old entries are never read again. */
-export const CACHE_VERSION = 2;
+export const CACHE_VERSION = 3;
 const ENTRY_NAME = /^[0-9a-f]{64}\.json$/;
 /** An entry is a key and a number: anything larger is not one of ours. */
 const MAX_ENTRY_BYTES = 1024;
 /** Keys are short and built here; a longer one is refused rather than hashed or written. */
 const MAX_KEY_LENGTH = 4096;
+/**
+ * A key longer than this is stored by its hash, `sha256:<hex>`, in the entry's `k` field (its file name is the hash already).
+ * Signed and CDN video URLs are often longer than an entry can hold, and their encodes must still be cached.
+ */
+const LONG_KEY = 512;
 const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+/** The `k` an entry of `key` carries: the key itself, or its hash when the key is long (see LONG_KEY). */
+function keyTagOf(key) {
+    return key.length > LONG_KEY ? `sha256:${sha256(key)}` : key;
+}
 /** The scope every key of one reference and scorer carries: its original's content hash, width, scorer, encoder and tool. */
 export function cacheScope(original, width, scorerId, encoderId) {
     return [sha256(original), `w${width}`, scorerId, encoderId, `imgtune ${IMGTUNE_VERSION}`, `cache ${CACHE_VERSION}`].join("|");
@@ -60,7 +69,7 @@ export class ResultCache {
             const parsed = JSON.parse(await readFile(file, "utf8"));
             if (parsed === null || typeof parsed !== "object")
                 return undefined;
-            if (parsed.k !== key || typeof parsed.v !== "number" || !Number.isFinite(parsed.v))
+            if (parsed.k !== keyTagOf(key) || typeof parsed.v !== "number" || !Number.isFinite(parsed.v))
                 return undefined;
             return parsed.v;
         }
@@ -77,12 +86,56 @@ export class ResultCache {
                 await mkdir(this.dir, { recursive: true });
                 this.dirReady = true;
             }
-            await writeFileAtomic(this.fileOf(key), JSON.stringify({ k: key, v: value }), { root: this.dir });
+            await writeFileAtomic(this.fileOf(key), JSON.stringify({ k: keyTagOf(key), v: value }), { root: this.dir });
         }
         catch {
             // Ignored: the number is recomputed the next time.
         }
     }
+    /**
+     * The JSON value stored under `key` (see putJson), or undefined: absent, corrupt, of another key, a number entry, or
+     * a value that is null. The value is untrusted data: callers check its shape before use.
+     */
+    async getJson(key) {
+        if (key.length > MAX_KEY_LENGTH)
+            return undefined;
+        const file = this.fileOf(key);
+        try {
+            const info = await stat(file);
+            if (!info.isFile() || info.size > MAX_ENTRY_BYTES)
+                return undefined;
+            const parsed = JSON.parse(await readFile(file, "utf8"));
+            if (parsed === null || typeof parsed !== "object")
+                return undefined;
+            if (parsed.k !== keyTagOf(key) || parsed.j === undefined || parsed.j === null)
+                return undefined;
+            return parsed.j;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Stores a JSON value under `key`, for small results such as a sample encode's outcome. A value that does not fit an
+     * entry (MAX_ENTRY_BYTES) or a key that is too long is not stored, and a failed write is ignored, as for put.
+     */
+    async putJson(key, value) {
+        if (key.length > MAX_KEY_LENGTH || value === undefined)
+            return;
+        const text = JSON.stringify({ k: keyTagOf(key), j: value });
+        if (text === undefined || Buffer.byteLength(text, "utf8") > MAX_ENTRY_BYTES)
+            return;
+        try {
+            if (!this.dirReady) {
+                await mkdir(this.dir, { recursive: true });
+                this.dirReady = true;
+            }
+            await writeFileAtomic(this.fileOf(key), text, { root: this.dir });
+        }
+        catch {
+            // Ignored: the value is computed again the next time.
+        }
+    }
     /** Removes the oldest entries until the folder holds at most 90% of the limit. Only files named like entries are touched. */
     async trim() {
         return trimCache(this.dir, this.maxBytes);

package/dist/run.js

@@ -5,7 +5,7 @@ import { mkdir, readdir, readFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { DEFAULT_VIEWPORTS } from "./config.js";
 import { writeFileAtomic } from "./atomic.js";
-import { parseGpuDevice } from "./gpu.js";
+import { gpuSettingOf, gpuSettingOne } from "./gpu.js";
 import { hintsCommand, parseQualities } from "./hints.js";
 import { locateCommand } from "./locate-only.js";
 import { surveyStop, BROKEN_EXIT } from "./broken.js";
@@ -43,6 +43,8 @@ export function parseRunArgs(argv) {
         const arg = argv[i];
         if (arg === "--no-cache")
             args.noCache = true;
+        else if (arg === "--gpu-encode")
+            args.gpuEncode = true;
         else if (arg === "--ignore-robots")
             args.ignoreRobots = true;
         else if (arg === "--block-third-party")
@@ -51,11 +53,11 @@ export function parseRunArgs(argv) {
         else if (arg === "--allow-third-party")
             continue;
         else if (arg === "--gpu")
-            args.gpu ??= { device: 0 };
+            args.gpu ??= gpuSettingOne(0);
         else if (arg === "--gpu-device") {
             const value = argValue(argv, i, arg);
             i++;
-            args.gpu = { device: parseGpuDevice(value) };
+            args.gpu = gpuSettingOf(value);
         }
         else if (arg === "--out" ||
             arg === "--urls-from" ||
@@ -338,6 +340,8 @@ function runFlags(args) {
         common.push("--ignore-robots");
     if (args.noCache)
         common.push("--no-cache");
+    if (args.gpuEncode)
+        common.push("--gpu-encode");
     if (args.pageConcurrency !== undefined)
         common.push("--page-concurrency", String(args.pageConcurrency));
     if (args.idleTimeoutMs !== undefined)
@@ -348,7 +352,7 @@ function runFlags(args) {
         common.push("--allow-host", shellWord(args.thirdParty.allowHosts.join(",")));
     const deep = [...common];
     if (args.gpu !== undefined)
-        deep.push("--gpu-device", String(args.gpu.device));
+        deep.push("--gpu-device", args.gpu.devices.join(","));
     return { survey: common, deep };
 }
 function recordBroken(broken, phase, page) {

package/dist/summary.js

@@ -2,7 +2,7 @@
 // MAX_SUMMARY_LINES lines, so an agent decides the next step from it without opening the JSON.
 import { readdir, readFile, stat } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
-import { hintsCommand } from "./hints.js";
+import { hintsCommand, videoTotalsLine } from "./hints.js";
 import { safeText, shellWord } from "./text.js";
 import { APPROX_MARK, APPROX_NOTE, pageFileName, siteNumbers, surveyLabelOf } from "./remote.js";
 import { candidatesOf, patternRanking } from "./worst.js";
@@ -57,6 +57,10 @@ export function renderSummary(input) {
         const parts = input.timings.map((t) => `${safeText(t.name)} ${t.seconds.toFixed(0)} s`).join(", ");
         lines.push(`time: ${total.toFixed(0)} s total (${parts})`);
     }
+    // The media phase's note is printed once, at the top (the same note is on each page that has media).
+    const media = [...(input.survey ?? []), ...input.deep].find((p) => p.mediaNote !== undefined)?.mediaNote;
+    if (media !== undefined)
+        lines.push(safeText(media));
     lines.push("");
     if (input.stop !== undefined) {
         lines.push(`STOPPED before the deep phase: ${safeText(input.stop.reason)}`, `  fix: ${safeText(input.stop.fix)}`, "");
@@ -67,6 +71,9 @@ export function renderSummary(input) {
         lines.push(safeText(input.surveyLabel), "");
     if (input.deep.length > 0)
         lines.push(...deepBlock(input.deep), "");
+    const withVideo = input.deep.filter((p) => p.status === "ok" && (p.videos ?? []).length > 0);
+    if (withVideo.length > 0)
+        lines.push(...videoBlock(withVideo), "");
     if (input.callSites !== undefined)
         lines.push(...callSiteBlock(input.callSites), "");
     if (input.warnings.length > 0)
@@ -128,6 +135,15 @@ const exactOf = (page) => {
     const n = page.page;
     return (n.meanImageBytes * n.exactPct) / 100;
 };
+/** The deep pages with a `<video>`: one line each, the page's video totals (per view, per play, saveable est.). */
+function videoBlock(pages) {
+    const shown = Math.min(DEEP_ROWS, pages.length);
+    const lines = [`videos: ${pages.length} deep page(s) with <video> (${shown} of ${pages.length} shown)`];
+    for (const page of pages.slice(0, DEEP_ROWS)) {
+        lines.push(`  ${trim(labelOf(page.url), LABEL_WIDTH).padEnd(LABEL_WIDTH)}  ${videoTotalsLine(page.videos ?? []) ?? ""}`);
+    }
+    return lines;
+}
 function callSiteBlock(sites) {
     if (sites.length === 0)
         return ["call sites by saving per view: none (no deep page has a fix hint)"];
@@ -159,8 +175,12 @@ export async function readPages(dir) {
         return [];
     }
     const pages = [];
-    for (const name of names)
-        pages.push(await readPageFile(join(dir, name)));
+    for (const name of names) {
+        const page = await readPageFile(join(dir, name));
+        // A page without the completeness marker is an interrupted run's: its media results are not in yet (see remote.ts).
+        if (page.complete === true)
+            pages.push(page);
+    }
     return pages;
 }
 async function readPageFile(file) {

package/dist/video-analysis.js

@@ -0,0 +1,273 @@
+// Records for animated images and `<video>` elements: the cheap levers only (no ffmpeg; the encodes come later). An
+// animated image gets an `animated` fix on its ImageRecord (images.ts), and a video gets its own VideoRecord with its
+// bytes per view and per play, its widths and the levers that need no probe. A fetched poster is audited as an image,
+// 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 { 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). */
+export const SCAN_MAX_VIDEO_WIDTHS = 2;
+/**
+ * The first index a poster takes as an image element. A poster is not an <img>, so its index is placed far above any
+ * real one (the page's <img> indexes), keeping its element identity apart in the image pipeline.
+ */
+export const POSTER_INDEX_BASE = 1_000_000;
+/**
+ * The id of a video. Without a source file it is the group key, as before. With one it is the file step (the rule of the
+ * image ids, images.ts baseKey), with the ordinal of the video among those of its file in document order, so two videos
+ * of one file keep distinct ids. The id is `video:` and 12 hex digits of the hash.
+ */
+function videoIdOf(page, key, file, perFile) {
+    if (file === undefined)
+        return `video:${sha1(`${page}\n${key}`).slice(0, 12)}`;
+    const n = perFile.get(file) ?? 0;
+    perFile.set(file, n + 1);
+    return `video:${sha1(`${page}\nfile:${file}#${n}`).slice(0, 12)}`;
+}
+/**
+ * Components above a video, nearest first: the same rule as remote.ts (componentNamesOf), capped at its MAX_OWNERS (8).
+ * Written out here, not imported, so that this module does not import remote.ts at run time.
+ */
+function componentsOf(owners) {
+    return owners
+        .flatMap((o) => (o.name !== undefined && COMPONENT_NAME.test(o.name) && o.name.length > 2 ? [o.name] : []))
+        .slice(0, 8);
+}
+/** The `preload` kind of a video, as the byte rules read it: the autoplay attribute wins over preload. */
+export function preloadKindOf(video) {
+    if (video.autoplay)
+        return "autoplay";
+    switch (video.preload) {
+        case "auto":
+            return "auto";
+        case "metadata":
+            return "metadata";
+        case "none":
+            return "none";
+        default:
+            return "default";
+    }
+}
+/**
+ * The full-file bytes of each media URL: the largest bytes the scan saw for it in any viewport. A URL's bytes are the
+ * bytes the page moved, so a partial (range) read can be smaller than the file; the largest read is the closest the
+ * headers give without a range total.
+ */
+export function fullBytesOf(observations) {
+    const full = new Map();
+    for (const obs of observations) {
+        for (const [url, record] of obs.media ?? [])
+            full.set(url, Math.max(full.get(url) ?? 0, record.bytes));
+    }
+    return full;
+}
+/**
+ * The observations with each fetched poster added to its viewport as an image, sized to the video's box. A poster that
+ * was not fetched, or a hidden video's, is not added. The added image carries `posterOf` (the video's selector), so its
+ * record says it is a poster. Returns new observations; the ones given are not changed.
+ */
+export function withPosterImages(observations) {
+    return observations.map((obs) => {
+        const posters = [];
+        for (const video of obs.videos ?? []) {
+            if (video.poster === undefined || video.hidden || video.poster.startsWith("data:"))
+                continue;
+            if (!obs.responses.get(video.poster)?.buffer)
+                continue;
+            posters.push({
+                index: POSTER_INDEX_BASE + video.index,
+                currentSrc: video.poster,
+                renderedWidth: video.renderedWidth,
+                renderedHeight: video.renderedHeight,
+                srcset: "",
+                classes: "",
+                nextImage: false,
+                inFirstViewport: video.inFirstViewport,
+                locator: video.locator,
+                posterOf: video.locator.selector,
+            });
+        }
+        return posters.length > 0 ? { ...obs, images: [...obs.images, ...posters] } : obs;
+    });
+}
+/** The key that finds a video across viewports: its components, else its test id, else its DOM path (as the images). */
+function baseKeyOf(video) {
+    const components = componentsOf(video.locator.owners);
+    if (components.length > 0)
+        return `component:${components.join(">")}`;
+    if (video.locator.testid)
+        return `testid:${video.locator.testid}`;
+    return `css:${video.locator.selector}`;
+}
+/** The videos of the page, grouped by element across viewports, in document order. */
+function groupVideos(observations) {
+    const groups = new Map();
+    for (const obs of observations) {
+        const ordinals = new Map();
+        for (const video of obs.videos ?? []) {
+            const base = baseKeyOf(video);
+            const n = ordinals.get(base) ?? 0;
+            ordinals.set(base, n + 1);
+            const key = `${base}#${n}`;
+            const list = groups.get(key);
+            if (list)
+                list.push({ obs, video });
+            else
+                groups.set(key, [{ obs, video }]);
+        }
+    }
+    return groups;
+}
+/** The bytes the scan saw for a media URL in one viewport (0 when the page did not load it there). */
+function observedBytesOf(obs, url) {
+    return obs.media?.get(url)?.bytes ?? 0;
+}
+/**
+ * True when a Cloudinary video URL (`/<cloud>/video/upload/<transforms>/<file>`) has `f_auto` among its transforms. The
+ * image loader (loaders.ts) reads `image/upload` only, so the video path is read here.
+ */
+function cloudinaryVideoFormatAuto(url) {
+    if (url.hostname !== "res.cloudinary.com")
+        return false;
+    const upload = /^\/[^/]+\/video\/upload\/(.+)$/.exec(url.pathname);
+    if (!upload)
+        return false;
+    return upload[1].split("/").slice(0, -1).some((segment) => segment.split(",").includes("f_auto"));
+}
+/**
+ * The info note of a video whose URL the CDN already serves in the format the browser takes (Cloudinary `f_auto`, imgix
+ * `auto=format`): the codec lever does not apply, because the CDN negotiates the format per request. Undefined otherwise.
+ */
+export function formatHandledNote(src, page) {
+    let url;
+    try {
+        url = new URL(src, page);
+    }
+    catch {
+        return undefined;
+    }
+    if (cloudinaryVideoFormatAuto(url))
+        return "format handled by Cloudinary (f_auto): the CDN serves AV1 or H.264 per browser, no codec change";
+    if (!formatAutoOf(src, page))
+        return undefined;
+    const name = adapterFor(src, page).adapter.name;
+    if (name === "imgix")
+        return "format handled by imgix (auto=format): the CDN serves the format per browser, no codec change";
+    return "format handled by the CDN (f_auto): the CDN serves the format per browser, no codec change";
+}
+/** True when the video's sources name an AV1 stream, by type or by an `.av1.mp4` file name. */
+function hasAv1(video) {
+    if (video.sources.some((s) => /av01|av1/i.test(s.type ?? "")))
+        return true;
+    const urls = [video.currentSrc, ...video.sources.map((s) => s.src)];
+    return urls.some((u) => /\.av1\.mp4(?:[?#]|$)/i.test(u));
+}
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Levers (no probe here): `loading` when a video costs bytes on load and is below the fold (or preloads), `codec` when
+ * no source is AV1, and `posterMissing` when there is no poster.
+ */
+export function videoRecordsOf(page, observations, fullBytes, mode, maxWidths, sources) {
+    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();
+    for (const [key, members] of groupVideos(observations)) {
+        const ref = 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({
+            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,
+        }));
+        const heaviest = views.reduce((best, cur) => (cur.perView > best.perView ? cur : best));
+        const shown = members.filter((m) => !m.video.hidden);
+        const knownWidth = shown.map((m) => m.video.videoWidth).find((w) => w !== undefined && w > 0);
+        const needs = shown.map((m) => ({
+            viewport: m.obs.viewport.name,
+            viewportWidth: m.obs.viewport.width,
+            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)
+                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 };
+        }
+        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),
+            classes: "",
+            loader: "video",
+        };
+        if (ref.locator.testid !== undefined)
+            locator.testid = sanitizeText(ref.locator.testid, 120);
+        if (source?.file !== undefined) {
+            // The project file:line of the element, when the owner resolved (see remote.ts resolveVideoSources).
+            locator.file = source.file;
+            locator.line = source.line;
+            if (source.via !== undefined)
+                locator.via = source.via;
+            locator.kind = source.check ?? "unchecked";
+            locator.verified = locator.kind === "image";
+            if (source.ownerChain?.length)
+                locator.ownerChain = source.ownerChain;
+        }
+        const record = {
+            id: videoIdOf(page, key, source?.file, perFile),
+            page,
+            locator,
+            src,
+            sources: ref.sources,
+            attributes: {
+                autoplay: ref.autoplay,
+                muted: ref.muted,
+                loop: ref.loop,
+                playsinline: ref.playsinline,
+                preload: ref.preload,
+                ...(ref.poster !== undefined ? { poster: ref.poster } : {}),
+            },
+            bytes: { ...heaviest, fullBytesKnown: false },
+            perViewport: members.map((m) => ({
+                viewport: m.obs.viewport.name,
+                boxWidth: m.video.renderedWidth,
+                dpr: m.obs.viewport.dpr,
+                inFirstViewport: m.video.inFirstViewport,
+            })),
+            levers,
+        };
+        if (mode === "audit")
+            record.widthOptions = widthOptions(needs, sourceWidth);
+        else
+            record.widths = clusterVideoWidths(needs, maxWidths, sourceWidth);
+        records.push(record);
+    }
+    return records;
+}