imgtune 0.1.0 → 0.3.0

package/dist/vector-phase.js

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

package/dist/video-analysis.js

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