imgtune 0.1.0 → 0.2.0

package/dist/image-file.js

@@ -3,17 +3,24 @@
 // (SSIMULACRA2 90 by default, visually lossless; --min-score sets another). The lowest quality per format that meets the
 // bar is reported. With --width the file is also measured at the width it is needed at (width x dpr). Files are read,
 // never written, unless --write names a directory for optimised copies.
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+//
+// Media (animated GIF, WebP and APNG, MP4, MOV and WebM) is read from local files only (media-file.ts): an animated file
+// gets the candidates of the animated codecs, and `--reference <original>` checks a candidate against the original with
+// the video bars (VMAF and the still-frame guard), exiting 0 on pass and 1 on fail.
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import sharp from "sharp";
 import { isLocalTarget } from "./address.js";
 import { encode, ENCODER_ID, loadReference } from "./encode.js";
 import { makeFetcher, MAX_IMAGE_BYTES } from "./fetch.js";
-import { gpuNote, parseGpuDevice, startGpuScorer } from "./gpu.js";
+import { gpuNote, startGpuScorer, gpuSettingOf, gpuSettingOne } from "./gpu.js";
+import { probeFfmpeg, withGpu } from "./ffmpeg.js";
 import { makeScorer } from "./metric.js";
 import { minPassingQuality } from "./search.js";
 import { cacheScope, CACHE_DIR, ResultCache } from "./result-cache.js";
-import { decodeRaw, pixelSize, safeText, SCAN_TOLERANCE, scorerOf } from "./remote.js";
+import { compareReferenceFile, describeVideo, measureAnimated, mediaKindOf, renderAnimated, renderReference, renderVideo } from "./media-file.js";
+import { DEFAULT_VIDEO_BAR, DEFAULT_VIDEO_STILL_BAR, decodeRaw, pixelSize, safeText, SCAN_TOLERANCE, scorerOf } from "./remote.js";
 import { IMGTUNE_VERSION } from "./version.js";
 const ALL_FORMATS = ["avif", "webp", "jpeg"];
 /** Most inputs (files, globs and URLs together) one run measures. */
@@ -24,12 +31,18 @@ const MAX_GLOB_MATCHES = 1000;
 const START_QUALITY = 90;
 /** The SSIMULACRA2 bar a file must meet against itself, when --min-score is not given: visually lossless. */
 export const DEFAULT_FILE_BAR = 90;
-const USAGE = "usage: imgtune image <file|url|glob> [...] [--width <css px>] [--dpr 1,2] [--formats avif,webp,jpeg] [--min-score <n>] [--write <dir>] [--format text|json] [--gpu] [--gpu-device <n>]";
+const USAGE = "usage: imgtune image <file|url|glob> [...] [--width <css px>] [--dpr 1,2] [--formats avif,webp,jpeg] [--min-score <n>] [--write <dir>] [--format text|json|--json] [--gpu] [--gpu-device <n>] [--reference <original file>] [--video-bar <n>] [--video-still-bar <n>]";
 function positiveNumber(name, text) {
     if (!/^\d+(\.\d+)?$/.test(text) || Number(text) <= 0)
         throw new Error(`${name} needs a number above 0, not ${safeText(text)}`);
     return Number(text);
 }
+/** A bar from 0 to 100 (a VMAF or still-guard bar). Throws with the message the CLI prints. */
+function barNumber(name, text) {
+    if (!/^\d+(\.\d+)?$/.test(text) || Number(text) > 100)
+        throw new Error(`${name} needs a number from 0 to 100, not ${safeText(text)}`);
+    return Number(text);
+}
 /** The arguments after `image`. Throws with the message the CLI prints. */
 export function parseImageArgs(argv) {
     const args = { inputs: [], dprs: [1, 2], formats: [...ALL_FORMATS], format: "text" };
@@ -40,13 +53,21 @@ export function parseImageArgs(argv) {
             continue;
         }
         if (arg === "--gpu") {
-            args.gpu ??= { device: 0 };
+            args.gpu ??= gpuSettingOne(0);
             continue;
         }
         if (arg === "--no-cache") {
             args.noCache = true;
             continue;
         }
+        if (arg === "--gpu-encode") {
+            args.gpuEncode = true;
+            continue;
+        }
+        if (arg === "--json") {
+            args.format = "json";
+            continue;
+        }
         const value = argv[i + 1];
         if (value === undefined || value.startsWith("--"))
             throw new Error(`${arg} needs a value (${USAGE})`);
@@ -73,9 +94,18 @@ export function parseImageArgs(argv) {
             args.minScore = score;
         }
         else if (arg === "--gpu-device")
-            args.gpu = { device: parseGpuDevice(value) };
+            args.gpu = gpuSettingOf(value);
         else if (arg === "--write")
             args.write = value;
+        else if (arg === "--reference") {
+            if (/^https?:\/\//i.test(value))
+                throw new Error(`--reference is a local file: media is not read from a URL here (local files only, not ${safeText(value)})`);
+            args.reference = value;
+        }
+        else if (arg === "--video-bar")
+            args.videoBar = barNumber(arg, value);
+        else if (arg === "--video-still-bar")
+            args.videoStillBar = barNumber(arg, value);
         else if (arg === "--format") {
             if (value !== "text" && value !== "json")
                 throw new Error(`--format is text or json, not ${safeText(value)}`);
@@ -198,6 +228,8 @@ async function readInput(input, cwd, userAgent) {
         const body = await fetcher.get(input.url, { maxBytes: MAX_IMAGE_BYTES, allowPrivate: isLocalTarget(input.url) });
         if (body === undefined)
             throw new Error(`${safeText(input.url)} was not fetched (blocked, failed, or larger than ${MAX_IMAGE_BYTES / (1024 * 1024)} MB)`);
+        if (mediaKindOf(body) !== undefined)
+            throw new Error(`${safeText(input.url)} is a video or animated file: media is local files only (download it and pass the file)`);
         return body;
     }
     const path = resolve(cwd, input.path);
@@ -287,8 +319,9 @@ export async function measureFile(input, buffer, args, score, cached) {
     const placeholder = { bar, sizes: [] };
     if (!info)
         return { ...base, width: { source: args.width ? "user" : "file", css: args.width }, ...placeholder, error: "not a decodable image" };
-    if (info.format === "svg" || info.format === "gif") {
-        return { ...base, width: { source: args.width ? "user" : "file", css: args.width }, ...placeholder, error: `${info.format} is not measured (not a raster format the encoders take)` };
+    // A static GIF is a raster image like a PNG (sharp reads its first frame). An animated one never reaches here: it is media.
+    if (info.format === "svg") {
+        return { ...base, width: { source: args.width ? "user" : "file", css: args.width }, ...placeholder, error: "svg is not measured (not a raster format the encoders take)" };
     }
     const targets = args.width === undefined ? [{ px: info.width }] : args.dprs.map((dpr) => ({ px: Math.min(Math.ceil(args.width * dpr), info.width), dpr }));
     const sizes = [];
@@ -378,7 +411,7 @@ export async function writeCopies(results, inputs, cwd, dir, buffers) {
     return notes;
 }
 /** `imgtune image`: measures each input and returns the text or JSON to print. */
-export async function imageCommand(argv, cwd, userAgent = `imgtune/${IMGTUNE_VERSION}`, log = (message) => process.stderr.write(`imgtune: ${message}\n`)) {
+export async function imageCommand(argv, cwd, userAgent = `imgtune/${IMGTUNE_VERSION}`, log = (message) => process.stderr.write(`imgtune: ${message}\n`), signal) {
     const args = parseImageArgs(argv);
     const gpu = args.gpu !== undefined ? await startGpuScorer(args.gpu.device, log) : undefined;
     const store = args.noCache === true ? undefined : new ResultCache(join(cwd, CACHE_DIR));
@@ -387,47 +420,134 @@ export async function imageCommand(argv, cwd, userAgent = `imgtune/${IMGTUNE_VER
         ? undefined
         : { store, scorerId: gpu !== undefined ? `gpu:${gpu.deviceName}` : "cpu", cpuScored: gpu ? () => gpu.cpuScores : undefined };
     try {
-        return await measureInputs(args, cwd, userAgent, gpu, cache);
+        return await measureInputs(args, cwd, userAgent, gpu, cache, signal);
     }
     finally {
         gpu?.close();
     }
 }
-async function measureInputs(args, cwd, userAgent, gpu, cache) {
+async function measureInputs(args, cwd, userAgent, gpu, cache, signal) {
     const inputs = await resolveInputs(args.inputs, cwd);
     const score = makeScorer("ssimulacra2", { projectDir: cwd, gpu });
+    const scorer = gpu !== undefined ? scorerOf(gpu, gpu.fallbackScores) : { name: "cpu" };
+    if (args.reference !== undefined)
+        return compareMode(args, inputs, cwd, score, scorer, signal);
     const results = [];
+    const media = [];
     const buffers = new Map();
-    for (const input of inputs) {
-        let buffer;
-        try {
-            buffer = await readInput(input, cwd, userAgent);
-        }
-        catch (err) {
-            results.push({
-                label: input.label,
-                evidence: "file-mode",
-                imgtuneVersion: IMGTUNE_VERSION,
-                current: { width: 0, height: 0, bytes: 0 },
-                width: { source: args.width ? "user" : "file", css: args.width },
-                bar: barOf(args.minScore),
-                sizes: [],
-                error: err.message,
-            });
-            continue;
+    // Scratch for the media encodes of this run, removed when the run ends.
+    let scratch;
+    const mediaContext = async () => {
+        scratch ??= await mkdtemp(join(tmpdir(), "imgtune-media-file-"));
+        // The media is encoded on the CPU unless --gpu-encode asks for the GPU; its encoders are proven on that GPU first.
+        const device = args.gpuEncode === true ? (args.gpu?.device ?? 0) : undefined;
+        const caps = await withGpu(await probeFfmpeg(), device);
+        return {
+            caps,
+            gpu: caps.av1Nvenc || caps.h264Nvenc ? device : undefined,
+            score,
+            dir: scratch,
+            videoBar: args.videoBar ?? DEFAULT_VIDEO_BAR,
+            videoStillBar: args.videoStillBar ?? DEFAULT_VIDEO_STILL_BAR,
+            signal,
+        };
+    };
+    try {
+        for (const input of inputs) {
+            let buffer;
+            try {
+                buffer = await readInput(input, cwd, userAgent);
+            }
+            catch (err) {
+                results.push({
+                    label: input.label,
+                    evidence: "file-mode",
+                    imgtuneVersion: IMGTUNE_VERSION,
+                    current: { width: 0, height: 0, bytes: 0 },
+                    width: { source: args.width ? "user" : "file", css: args.width },
+                    bar: barOf(args.minScore),
+                    sizes: [],
+                    error: err.message,
+                });
+                continue;
+            }
+            buffers.set(input.label, buffer);
+            const kind = mediaKindOf(buffer);
+            if (kind !== undefined && input.path !== undefined) {
+                const file = { label: input.label, path: resolve(cwd, input.path), buffer };
+                const ctx = await mediaContext();
+                const dir = join(ctx.dir, `file-${media.length}`);
+                media.push(kind === "animated" ? await measureAnimated(file, args.width, ctx, dir) : await describeVideo(file, ctx, dir));
+                continue;
+            }
+            results.push(await measureFile(input, buffer, args, score, cache && { ...cache, original: buffer }));
         }
-        buffers.set(input.label, buffer);
-        results.push(await measureFile(input, buffer, args, score, cache && { ...cache, original: buffer }));
+    }
+    finally {
+        if (scratch !== undefined)
+            await rm(scratch, { recursive: true, force: true });
     }
     const notes = args.write !== undefined ? await writeCopies(results, inputs, cwd, args.write, buffers) : [];
-    const failed = results.filter((r) => r.error !== undefined).length;
-    const scorer = gpu !== undefined ? scorerOf(gpu, gpu.fallbackScores) : { name: "cpu" };
+    const failed = results.filter((r) => r.error !== undefined).length + media.filter((m) => m.error !== undefined).length;
     if (args.format === "json") {
-        const body = { evidence: "file-mode", scorer, files: results, copies: notes };
+        const body = { evidence: "file-mode", scorer, files: results, media, copies: notes };
         return { output: `${JSON.stringify(body, null, 2)}\n`, exitCode: failed > 0 ? 1 : 0 };
     }
     const head = gpu !== undefined ? `${gpuNote(gpu.device, gpu.deviceName, gpu.fallbackScores)}\n\n` : "";
     const text = results.map(renderFile).join("\n");
+    const mediaText = media.map((m) => (m.kind === "animated" ? renderAnimated(m) : renderVideo(m))).join("\n");
     const tail = notes.length > 0 ? `copies:\n${notes.map((n) => `  ${n}`).join("\n")}\n` : "";
-    return { output: `${head}${text}${tail}`, exitCode: failed > 0 ? 1 : 0 };
+    return { output: `${head}${text}${mediaText}${tail}`, exitCode: failed > 0 ? 1 : 0 };
+}
+/**
+ * `--reference <original>`: one candidate (a local media file) compared with the original. The verdict is the exit code:
+ * 0 on pass, 1 on fail or on any error. Input that cannot be compared is an error, not a fail verdict on the file.
+ */
+async function compareMode(args, inputs, cwd, score, scorer, signal) {
+    const reference = args.reference;
+    const fail = (message) => {
+        if (args.format === "json")
+            return { output: `${JSON.stringify({ evidence: "media-reference", scorer, error: message }, null, 2)}\n`, exitCode: 1 };
+        return { output: `${safeText(message)}\n`, exitCode: 1 };
+    };
+    if (inputs.length !== 1)
+        return fail(`--reference compares one file: give one candidate (${inputs.length} match)`);
+    const [candidate] = inputs;
+    if (candidate.url !== undefined)
+        return fail("--reference takes local files only: the candidate is a URL, and media is not read from a URL here");
+    const refPath = resolve(cwd, reference);
+    const refInfo = await stat(refPath).catch(() => undefined);
+    if (!refInfo?.isFile())
+        return fail(`--reference ${safeText(reference)} is not a file`);
+    if (refInfo.size > MAX_IMAGE_BYTES)
+        return fail(`--reference ${safeText(reference)} is larger than ${MAX_IMAGE_BYTES / (1024 * 1024)} MB`);
+    const refBuffer = await readFile(refPath);
+    if (mediaKindOf(refBuffer) === undefined)
+        return fail(`--reference ${safeText(reference)} is not a video or animated file`);
+    const candBuffer = await readInput(candidate, cwd, "");
+    if (mediaKindOf(candBuffer) === undefined)
+        return fail(`${safeText(candidate.label)} is not a video or animated file: --reference compares media`);
+    const caps = await probeFfmpeg();
+    if (!caps.ffmpeg)
+        return fail("ffmpeg is not on PATH: --reference needs it (ffmpeg enables the full hints)");
+    const dir = await mkdtemp(join(tmpdir(), "imgtune-compare-"));
+    let result;
+    try {
+        const ctx = {
+            caps,
+            score,
+            dir,
+            videoBar: args.videoBar ?? DEFAULT_VIDEO_BAR,
+            videoStillBar: args.videoStillBar ?? DEFAULT_VIDEO_STILL_BAR,
+            signal,
+        };
+        result = await compareReferenceFile({ label: candidate.label, path: resolve(cwd, candidate.path), buffer: candBuffer }, { label: relative(cwd, refPath) || reference, path: refPath, buffer: refBuffer }, args.width, ctx, dir);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+    const exitCode = result.error === undefined && result.pass ? 0 : 1;
+    if (args.format === "json")
+        return { output: `${JSON.stringify(result, null, 2)}\n`, exitCode };
+    return { output: renderReference(result), exitCode };
 }

package/dist/images.js

@@ -7,6 +7,7 @@ import { COMPONENT_NAME, loaderName, sanitizeText, urlPattern } from "./locate.j
 import { undersizedProposal } from "./candidates.js";
 import { sizesBranchAt, sizesSlotAt } from "./sizes.js";
 import { parseSrcset } from "./srcset-parse.js";
+import { animatedTarget } from "./media-model.js";
 /** The first path segment of a harness route: a page the agent adds to measure a component in isolation. */
 export const HARNESS_SEGMENT = "__imgtune";
 /**
@@ -43,6 +44,13 @@ export function searchHintsOf(locator) {
         hints.urlPattern = locator.urlPattern;
     return Object.keys(hints).length > 0 ? hints : undefined;
 }
+/**
+ * Whether a served format takes the lossless rules (a local resize and the AVIF proposal): a jpeg or png, or a static GIF
+ * (a palette file, judged as a PNG). An animated GIF does not: its saving is an encode.
+ */
+export function losslessServed(format, animated) {
+    return format === "jpeg" || format === "png" || (format === "gif" && !animated);
+}
 const round1 = (value) => Math.round(value * 10) / 10;
 const round2 = (value) => Math.round(value * 100) / 100;
 /**
@@ -229,12 +237,22 @@ export function buildImageRecords(input) {
         const savedEff = keepSizes ? saved : saved - savedSizes;
         const savedSizesEff = keepSizes ? savedSizes : 0;
         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 fix = { bytes: { saved: savedEff, addedForSharpness, sizes: savedSizesEff, quality: savedEff - savedSizesEff } };
         if (member.cdnQuality !== undefined)
             fix.cdnQuality = { ...member.cdnQuality };
-        if (member.formatAuto === true && (served === "jpeg" || served === "png"))
+        if (member.formatAuto === true && lossless)
             fix.formatHandled = true;
+        if (animatedMember?.animated !== undefined) {
+            fix.animated = {
+                info: animatedMember.animated,
+                context: "img",
+                target: animatedTarget("img", undefined),
+                perViewBytes: members.reduce((sum, m) => sum + m.bytes, 0) / viewportCount,
+            };
+        }
         if (sizes && left !== undefined) {
             fix.noSaving = `sizes proposal left out: ${left}`;
             notes.push(`sizes proposal left out: ${left}`);
@@ -252,6 +270,7 @@ export function buildImageRecords(input) {
         const record = {
             id: sha1(`${pageUrl}\n${key}`).slice(0, 12),
             page: pageUrl,
+            ...(member.img.posterOf !== undefined ? { poster: true } : {}),
             locator,
             tunable: tunableOf(member, pageUrl, locator.loader),
             current: {
@@ -286,6 +305,12 @@ export function buildImageRecords(input) {
             notes.push(`quality handled by ${locator.loader} (q_auto): its est. quality saving is not counted`);
         if (fix.formatHandled === true)
             notes.push(`format handled by ${locator.loader} (f_auto): no format change proposed`);
+        if (member.img.posterOf !== undefined)
+            notes.push(`poster of video ${sanitizeText(member.img.posterOf, 120)} (sized to its box)`);
+        if (fix.animated !== undefined) {
+            const { frames, durationMs, loop } = fix.animated.info;
+            notes.push(`animated ${fix.animated.info.format}: ${frames} frame(s), ${Math.round(durationMs / 100) / 10} s per loop, loops ${loop === 0 ? "forever" : loop}`);
+        }
         if (layoutChain?.truncated)
             notes.push("layout chain cut at the depth cap");
         if (layoutChain && layoutChain.skipped.length > 0)

package/dist/locate-join.js

@@ -18,8 +18,91 @@ export function isFlagged(record) {
     // A CSS background is not an <img>: the dev page's images cannot join it, so it is never located.
     if (record.kind === "css-background")
         return false;
+    // A poster is a video's image: no <img> of the dev page is its element, so it is never located (its evidence names the video).
+    if (record.poster === true)
+        return false;
     return record.fix.bytes.saved > 0 || record.fix.bytes.addedForSharpness > 0;
 }
+/** A video costs bytes per view, so a locate asks for it. Posters are image records and follow isFlagged. */
+export function isFlaggedVideo(record) {
+    return record.bytes.perView > 0;
+}
+/**
+ * Joins the flagged measured videos to the dev page's videos by URL (each side's URLs are keyed against its own page, see
+ * devVideosOf). A pair is made only when the URL is on exactly one measured video and exactly one dev video; a URL on
+ * several is not guessed at (the videos count as not joined). Videos have no element order to fall back on, so there is
+ * no second rule.
+ */
+export function joinVideos(records, devVideos, flagged) {
+    const measured = records.filter(flagged).map((record) => ({ record, key: joinKeyOfUrls([record.src], record.page) }));
+    const measuredCount = new Map();
+    for (const { key } of measured)
+        measuredCount.set(key, (measuredCount.get(key) ?? 0) + 1);
+    const devCount = new Map();
+    for (const dev of devVideos) {
+        const list = devCount.get(dev.pattern);
+        if (list)
+            list.push(dev);
+        else
+            devCount.set(dev.pattern, [dev]);
+    }
+    const pairs = new Map();
+    let notJoined = 0;
+    for (const { record, key } of measured) {
+        const devs = devCount.get(key) ?? [];
+        if (key !== "" && measuredCount.get(key) === 1 && devs.length === 1)
+            pairs.set(record, devs[0]);
+        else
+            notJoined++;
+    }
+    return { pairs, notJoined, devLeft: devVideos.length - pairs.size };
+}
+/** The videos of a dev page's viewport, keyed by URL against that page, with the source the dev build resolved for each. */
+export function devVideosOf(observation, pageUrl, resolved) {
+    return (observation.videos ?? []).map((video) => {
+        const source = resolved.get(video);
+        const dev = { index: video.index, pattern: joinKeyOfUrls([video.currentSrc], pageUrl), currentSrc: video.currentSrc, component: source?.component ?? [] };
+        if (source?.file !== undefined) {
+            dev.file = source.file;
+            dev.line = source.line;
+            dev.kind = source.check;
+            dev.via = source.via;
+            dev.ownerChain = source.ownerChain;
+        }
+        return dev;
+    });
+}
+/**
+ * The located videos: each paired record's locator takes the dev video's file:line and its source check, and its component.
+ * The record's id and bytes do not change: a locate only says where the element is in the source.
+ */
+export function applyLocateVideos(records, join) {
+    return records.map((record) => {
+        const dev = join.pairs.get(record);
+        if (dev === undefined)
+            return record;
+        const locator = { ...record.locator };
+        delete locator.file;
+        delete locator.line;
+        delete locator.kind;
+        delete locator.verified;
+        delete locator.via;
+        delete locator.ownerChain;
+        if (dev.file !== undefined && dev.line !== undefined) {
+            locator.file = dev.file;
+            locator.line = dev.line;
+            if (dev.via !== undefined)
+                locator.via = dev.via;
+            locator.kind = dev.kind ?? "unchecked";
+            locator.verified = locator.kind === "image";
+            if (dev.ownerChain?.length)
+                locator.ownerChain = dev.ownerChain;
+        }
+        if (dev.component.length > 0)
+            locator.component = dev.component;
+        return { ...record, locator };
+    });
+}
 /** A URL with the page's own origin taken out, so a built server and a dev server give the same pattern. */
 export function joinUrl(url, pageUrl) {
     let origin;
@@ -102,6 +185,9 @@ export function joinLocate(records, viewport, devImages, flagged) {
     const notMeasured = [];
     let noOrder = 0;
     for (const record of records) {
+        // A poster never joins an <img> (see isFlagged): skipped, so it can never take another element's file:line.
+        if (record.poster === true)
+            continue;
         const entry = record.perViewport.find((p) => p.viewport === viewport);
         if (!entry) {
             if (flagged(record))

package/dist/locate-only.js

@@ -5,7 +5,7 @@ import { mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { writeFileAtomic } from "./atomic.js";
 import { DEFAULT_VIEWPORTS } from "./config.js";
-import { applyLocate, devImagesOf, isFlagged, joinLocate, joinKeyOfImage, joinKeyOfRecord, readMeasuredScan, reasonCounts } from "./locate-join.js";
+import { applyLocate, applyLocateVideos, devImagesOf, devVideosOf, isFlagged, isFlaggedVideo, joinLocate, joinKeyOfImage, joinKeyOfRecord, joinVideos, readMeasuredScan, reasonCounts } from "./locate-join.js";
 import { observeLight, rootOf } from "./remote.js";
 import { parseAllowHosts, thirdPartyFromFlags } from "./third-party.js";
 import { unreadSourceNote } from "./source-root.js";
@@ -119,6 +119,7 @@ export async function locateCommand(argv, cwd, log) {
         ignoreRobots: args.ignoreRobots,
         wanted: (img, pageUrl) => flaggedPatterns.has(joinKeyOfImage(img, pageUrl)),
         thirdParty: args.thirdParty,
+        videos: true,
     });
     if (light.status !== "ok") {
         return { output: `locate: the dev page is ${light.status}${light.error ? `: ${safeText(light.error)}` : ""}\n`, exitCode: 1 };
@@ -127,6 +128,9 @@ export async function locateCommand(argv, cwd, log) {
     const devImages = devImagesOf(observation, args.url, light.resolved);
     const unread = await unreadSourceNote(devImages.flatMap((d) => (d.kind === "unread" && d.file !== undefined ? [d.file] : [])), cwd, root);
     const join = joinLocate(measured.images, viewport, devImages, (record) => flaggedSet.has(record));
+    // Videos are joined by URL (no element order): a flagged video (one that costs bytes per view) gets its dev file:line.
+    const videoJoin = joinVideos(measured.videos ?? [], devVideosOf(observation, args.url, light.resolvedVideos), isFlaggedVideo);
+    const flaggedVideos = (measured.videos ?? []).filter(isFlaggedVideo).length;
     const seconds = (Date.now() - started) / 1000;
     const summary = {
         url: args.url,
@@ -141,7 +145,12 @@ export async function locateCommand(argv, cwd, log) {
         noOrder: join.noOrder,
         reasons: reasonCounts(join),
     };
-    const located = { ...measured, locate: summary, images: applyLocate(measured.images, join, viewport) };
+    const located = {
+        ...measured,
+        locate: summary,
+        images: applyLocate(measured.images, join, viewport),
+        ...(measured.videos !== undefined ? { videos: applyLocateVideos(measured.videos, videoJoin) } : {}),
+    };
     const outPath = resolve(cwd, args.out ?? defaultLocateOut(args.from));
     if (outPath === resolve(cwd, args.from))
         throw new Error("--locate-out must not be the measured scan itself");
@@ -153,12 +162,14 @@ export async function locateCommand(argv, cwd, log) {
     ];
     for (const [code, count] of Object.entries(summary.reasons))
         lines.push(`  not located, ${count}: ${REASON_TEXT[code] ?? code}`);
+    if (flaggedVideos > 0)
+        lines.push(`flagged videos: ${flaggedVideos}; located: ${videoJoin.pairs.size}; not located: ${videoJoin.notJoined}`);
     if (summary.devLeft > 0)
         lines.push(`dev images of a flagged URL with no measured partner: ${summary.devLeft}`);
     if (summary.noOrder > 0)
         lines.push(`measured elements without an element order: ${summary.noOrder} (the scan is older: scan again)`);
     lines.push(`wrote ${safeText(outPath)}`);
-    const exitCode = flagged.length > 0 && summary.joined === 0 ? 1 : 0;
+    const exitCode = flagged.length + flaggedVideos > 0 && summary.joined + videoJoin.pairs.size === 0 ? 1 : 0;
     if (exitCode !== 0)
         lines.push("nothing located: is this the dev page of the measured scan, with the same images?");
     else

package/dist/locate.js

@@ -347,8 +347,12 @@ export const SOURCE_WINDOW = 3;
 const OPENING_SEARCH = 30;
 /** Largest project file read for the check. */
 export const MAX_SOURCE_READ = 2 * 1024 * 1024;
-/** An opening image tag or a srcset prop. */
-const IMAGE_TOKEN = /<(?:img|Image|picture|source)(?=[\s/>]|$)|\bsrc[sS]et\s*[={]/;
+/**
+ * An opening image tag or a srcset prop. A <video> opening and a <source> child count too: a video's poster is an image
+ * record that carries the video's locator, so its owner line is the <video> element (and the sources sit on their own
+ * lines). Lowercase only, so a component such as <VideoPlayer> is not taken for the element.
+ */
+const IMAGE_TOKEN = /<(?:img|Image|picture|source|video)(?=[\s/>]|$)|\bsrc[sS]et\s*[={]/;
 /**
  * Whether a project source line (1-based) renders an image: an image token within SOURCE_WINDOW lines of it, an opening
  * image tag above it with no closing tag between, or the definition (`function Name`, `const Name`) of the component