imgtune 0.1.0 → 0.3.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,12 +5,12 @@ 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";
 import { DEFAULT_THIRD_PARTY, parseAllowHosts, thirdPartyFromFlags } from "./third-party.js";
-import { MAX_IDLE_TIMEOUT_MS, MAX_PAGE_CONCURRENCY, pageFileName, parseLimit, parseRange, readStorageState, rootOf, runScan, scanPlan, } from "./remote.js";
+import { MAX_IDLE_TIMEOUT_MS, MAX_PAGE_CONCURRENCY, MAX_RESOURCE_TIME, MAX_SVG_BUDGET, pageFileName, parseLimit, parseRange, readStorageState, rootOf, runScan, scanPlan, } from "./remote.js";
 import { sampleByPattern, urlsFromSource } from "./urls.js";
 import { groupRoutes, parseRouteMap } from "./routes.js";
 import { selectDeepPages } from "./deep.js";
@@ -43,6 +43,10 @@ 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 === "--no-resources")
+            args.noResources = true;
         else if (arg === "--ignore-robots")
             args.ignoreRobots = true;
         else if (arg === "--block-third-party")
@@ -51,11 +55,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" ||
@@ -63,6 +67,8 @@ export function parseRunArgs(argv) {
             arg === "--deep" ||
             arg === "--page-concurrency" ||
             arg === "--idle-timeout" ||
+            arg === "--svg-budget" ||
+            arg === "--resource-time" ||
             arg === "--dev" ||
             arg === "--qualities" ||
             arg === "--root" ||
@@ -83,6 +89,10 @@ export function parseRunArgs(argv) {
                 args.pageConcurrency = parseRange(arg, value, 1, MAX_PAGE_CONCURRENCY);
             else if (arg === "--idle-timeout")
                 args.idleTimeoutMs = parseRange(arg, value, 0, MAX_IDLE_TIMEOUT_MS);
+            else if (arg === "--svg-budget")
+                args.svgBudget = parseRange(arg, value, 0, MAX_SVG_BUDGET);
+            else if (arg === "--resource-time")
+                args.resourceTime = parseRange(arg, value, 0, MAX_RESOURCE_TIME);
             else if (arg === "--dev")
                 args.dev = new URL(parseHttpUrl(value, "--dev")).origin;
             else if (arg === "--qualities")
@@ -169,6 +179,7 @@ export async function runCommand(argv, cwd, log) {
         ignoreRobots: args.ignoreRobots,
         aggressive: false,
         thirdParty: args.thirdParty,
+        resources: args.noResources !== true,
     };
     const base = { urls: [], out: outRoot, aggressive: false, quality: true, thirdParty: DEFAULT_THIRD_PARTY };
     const surveyPlan = scanPlan({ ...base, survey: true, pageConcurrency: args.pageConcurrency, idleTimeoutMs: args.idleTimeoutMs });
@@ -243,6 +254,7 @@ export async function runCommand(argv, cwd, log) {
         pageConcurrency: fullPlan.pageConcurrency,
         idleTimeoutMs: fullPlan.idleTimeoutMs,
         gpu: args.gpu,
+        svgBudget: args.svgBudget,
         expectImages: (url) => expected.get(url),
     });
     phases.push(phaseOf("deep", deepStart, deep));
@@ -338,6 +350,12 @@ function runFlags(args) {
         common.push("--ignore-robots");
     if (args.noCache)
         common.push("--no-cache");
+    if (args.gpuEncode)
+        common.push("--gpu-encode");
+    if (args.noResources)
+        common.push("--no-resources");
+    if (args.resourceTime !== undefined)
+        common.push("--resource-time", String(args.resourceTime));
     if (args.pageConcurrency !== undefined)
         common.push("--page-concurrency", String(args.pageConcurrency));
     if (args.idleTimeoutMs !== undefined)
@@ -348,7 +366,9 @@ 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(","));
+    if (args.svgBudget !== undefined)
+        deep.push("--svg-budget", String(args.svgBudget));
     return { survey: common, deep };
 }
 function recordBroken(broken, phase, page) {
@@ -379,7 +399,7 @@ async function exists(path) {
         return false;
     }
 }
-/** Every file of the run directory, relative to it, by the folder it is in. */
+/** Every file of the run directory, relative to it, by the folder it is in (folders inside them are not listed). */
 export async function filesOf(outRoot) {
     const files = [{ path: "urls.txt", kind: "urls" }];
     const folders = [
@@ -390,8 +410,10 @@ export async function filesOf(outRoot) {
     for (const [folder, kind] of folders) {
         if (!(await exists(join(outRoot, folder))))
             continue;
-        for (const name of (await readdir(join(outRoot, folder))).sort())
-            files.push({ path: `${folder}/${name}`, kind });
+        // Files only: a folder in it (the traced SVGs of the vector check, under svg/) is not a page file.
+        const entries = await readdir(join(outRoot, folder), { withFileTypes: true });
+        for (const entry of entries.filter((e) => e.isFile()).sort((a, b) => a.name.localeCompare(b.name)))
+            files.push({ path: `${folder}/${entry.name}`, kind });
     }
     if (await exists(join(outRoot, "hints.json")))
         files.push({ path: "hints.json", kind: "hints" });
@@ -418,6 +440,8 @@ export async function writeManifest(outRoot, cwd, run) {
             pageConcurrency: args.pageConcurrency,
             idleTimeoutMs: args.idleTimeoutMs,
             noCache: args.noCache,
+            ...(args.noResources ? { noResources: true } : {}),
+            ...(args.resourceTime !== undefined ? { resourceTime: args.resourceTime } : {}),
             root: args.root,
             ignoreRobots: args.ignoreRobots,
             storageState: args.storageState !== undefined,

package/dist/sizes.js

@@ -1,3 +1,4 @@
+import { offsetPx, wholePx } from "./px.js";
 /** Mobile/desktop split used in the emitted media query. */
 export const MOBILE_MAX_WIDTH = 768;
 /** Max residual (px) for a mobile/desktop group to count as a linear fit. */
@@ -34,15 +35,16 @@ function expressionFor(points) {
         const maxResidual = Math.max(...points.map((p) => Math.abs(p.renderedWidth - (a * p.viewportWidth + b))));
         if (maxResidual <= FIT_TOLERANCE_PX) {
             if (a * 100 < 1)
-                return `${Math.round(maxWidth)}px`;
+                return `${wholePx(maxWidth)}px`;
             if (Math.abs(b) < 1)
                 return `${Math.round(a * 100)}vw`;
-            return b < 0
-                ? `calc(${Math.round(a * 100)}vw - ${Math.round(-b)}px)`
-                : `calc(${Math.round(a * 100)}vw + ${Math.round(b)}px)`;
+            const offset = offsetPx(b);
+            return offset < 0
+                ? `calc(${Math.round(a * 100)}vw - ${-offset}px)`
+                : `calc(${Math.round(a * 100)}vw + ${offset}px)`;
         }
     }
-    return `${Math.ceil(maxWidth)}px`;
+    return `${wholePx(maxWidth)}px`;
 }
 /**
  * Derives the mobile and desktop width expressions from measured rendered widths across viewports.

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 { hiddenVideoSummaryLine, 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";
@@ -46,6 +46,7 @@ export function labelOf(url) {
     }
 }
 const kbText = (kb) => kb.toFixed(1);
+const kb = (bytes) => `${(bytes / 1024).toFixed(0)} KB`;
 const pctText = (value) => `${value.toFixed(1)}%`;
 /** The lines of the summary, capped at MAX_SUMMARY_LINES (the row limits keep it under the cap; the cap is the backstop). */
 export function renderSummary(input) {
@@ -57,6 +58,13 @@ 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));
+    const vectorNote = input.deep.find((p) => p.vectorNote !== undefined)?.vectorNote;
+    if (vectorNote !== undefined)
+        lines.push(safeText(vectorNote));
     lines.push("");
     if (input.stop !== undefined) {
         lines.push(`STOPPED before the deep phase: ${safeText(input.stop.reason)}`, `  fix: ${safeText(input.stop.fix)}`, "");
@@ -67,6 +75,12 @@ export function renderSummary(input) {
         lines.push(safeText(input.surveyLabel), "");
     if (input.deep.length > 0)
         lines.push(...deepBlock(input.deep), "");
+    const vector = vectorLine(input.deep);
+    if (vector !== undefined)
+        lines.push(vector, "");
+    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)
@@ -124,10 +138,58 @@ function deepBlock(deep) {
         lines.push(`  ${APPROX_NOTE}`);
     return lines;
 }
+/**
+ * The vector check over the pages: the flat images, the ones traced to an SVG that passes, and the SVG's saving per view
+ * (the bytes the passing SVGs save over their served files). Undefined when no image is flat.
+ */
+export function vectorLine(pages) {
+    let flat = 0;
+    let passed = 0;
+    let savedPerView = 0;
+    for (const page of pages) {
+        for (const image of page.images ?? []) {
+            if (image.fix.vector === undefined)
+                continue;
+            flat++;
+            if (image.fix.vector.passed === true) {
+                passed++;
+                savedPerView += image.fix.vector.savedPerView ?? 0;
+            }
+        }
+    }
+    if (flat === 0)
+        return undefined;
+    return `vector art: ${flat} image(s) look like vector art, ${passed} traced to a smaller SVG, ${kbText(savedPerView / 1024)} KB/view`;
+}
 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 ?? []) ?? ""}`);
+    }
+    // The loaded-but-not-shown group: the videos the browser fetched that no viewport shows in full, largest first.
+    const hidden = pages.flatMap((page) => (page.videos ?? []).filter((video) => video.hidden !== undefined).map((video) => ({ page, video })));
+    const hiddenLine = hiddenVideoSummaryLine(hidden.map((h) => h.video));
+    if (hiddenLine !== undefined) {
+        lines.push(`  ${hiddenLine}`);
+        const rows = [...hidden].sort((a, b) => (b.video.hidden?.perViewBytes ?? 0) - (a.video.hidden?.perViewBytes ?? 0)).slice(0, HIDDEN_VIDEO_ROWS);
+        for (const row of rows) {
+            const hiddenFix = row.video.hidden;
+            const where = row.video.locator.file !== undefined ? `${row.video.locator.file}:${row.video.locator.line ?? 0}` : row.video.locator.selector;
+            lines.push(`    ${JSON.stringify(safeText(where))}  hidden at ${hiddenFix.viewports.length} of ${hiddenFix.of}  ${kb(hiddenFix.perViewBytes)}/view  ${hiddenFix.action}`);
+        }
+        if (hidden.length > rows.length)
+            lines.push(`    (+${hidden.length - rows.length} more: see imgtune hints)`);
+    }
+    return lines;
+}
+/** The loaded-but-not-shown video rows the summary lists per run. */
+const HIDDEN_VIDEO_ROWS = 5;
 function callSiteBlock(sites) {
     if (sites.length === 0)
         return ["call sites by saving per view: none (no deep page has a fix hint)"];
@@ -159,8 +221,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/vector-art.js

@@ -0,0 +1,294 @@
+// Vector art: a flat raster (a logo, an icon, a flat illustration) that could be an SVG. The cheap check reads the pixels
+// of a still image at 256x256 and calls it flat when a few colours cover it. The proof traces it with vtracer
+// (@neplex/vectorizer, an optional dependency), renders the SVG back at the served size and scores it against the served
+// image at half size: an antialiased raster is not ground truth, and the traced SVG is sharper at the edges. Nothing here
+// throws on a bad image or a missing vectorizer: the caller gets undefined and says why.
+import { createRequire } from "node:module";
+import { Worker } from "node:worker_threads";
+import { brotliCompressSync, constants } from "node:zlib";
+import sharp from "sharp";
+import { openImage } from "./image-open.js";
+import { score } from "./metric.js";
+/** The vectorizer version the package pins (optionalDependencies). It is part of the cache key of a trace. */
+export const VECTORIZER_VERSION = "0.1.0";
+/** The fidelity bar: the half-size SSIMULACRA2 of the rendered SVG against the served image. */
+export const VECTOR_BAR = 70;
+/** The SVG must be at least this much smaller than the served bytes for the hint to be given. */
+export const VECTOR_MIN_SAVING = 0.3;
+/** The side of the square the flatness is read at (nearest kernel). */
+export const FLAT_SIZE = 256;
+/** A flat image: the 16 most common colours cover at least this share of its pixels... */
+export const FLAT_TOP16_MIN = 0.97;
+/** ...and it has at most this many colours (after 5-bit quantisation of each channel). */
+export const FLAT_MAX_COLORS = 300;
+/**
+ * ...and at most this share of its neighbouring pixel pairs differ by a small step (1 to 8 levels in some channel). Soft
+ * shading and photo-like gradients are made of small steps; flat art has none, or hard edges.
+ */
+export const FLAT_SMOOTH_MAX = 0.12;
+/** A larger image is not traced at all (decoding and tracing it cost seconds, and the screens it comes from are not art). */
+export const VECTOR_MAX_MEGAPIXELS = 5;
+/** The trace input: at most this many pixels, and this long side. */
+export const TRACE_MAX_PIXELS = 1_000_000;
+export const TRACE_MAX_SIDE = 1024;
+/** Smaller files are not worth a vector check: their bytes are too few to matter. */
+export const VECTOR_MIN_BYTES = 2048;
+/** A flat image this big or bigger in bytes gets the "looks like vector art" note when no SVG was traced. */
+export const VECTOR_LOOKS_MIN_BYTES = 10 * 1024;
+/** The time allowed for one image's trace and fidelity check, in ms. The trace cannot be stopped: a late result is dropped. */
+export const VECTOR_CAP_MS = 2000;
+/** The most pixels the fidelity check scores: the half-size pair is scaled down to this (both images alike). */
+export const SCORE_MAX_PIXELS = 1_000_000;
+/** A pixel counts as a bad pixel when its RGB L1 difference from the served image is above this. */
+const BAD_PIXEL_L1 = 96;
+/** The raster formats the vector check reads: a still image in one of them. */
+const STILL_FORMATS = new Set(["png", "webp", "jpeg", "avif", "gif"]);
+/**
+ * The flatness of a served file the vector check can read: a still raster of at least VECTOR_MIN_BYTES. Undefined otherwise
+ * (an animated file, a format it does not read, or a file too small to matter). Never throws.
+ */
+export async function stillFlatness(response, served, animated) {
+    if (animated || response.buffer === undefined || response.bytes < VECTOR_MIN_BYTES)
+        return undefined;
+    if (served.format === undefined || !STILL_FORMATS.has(served.format))
+        return undefined;
+    return flatnessOf(response.buffer);
+}
+const WHITE = "#ffffff";
+const flatMemo = new WeakMap();
+/**
+ * How flat an image is, read at FLAT_SIZE with the nearest kernel. Undefined when the bytes do not decode. Memoised per
+ * buffer, so one response is read once.
+ */
+export function flatnessOf(buffer) {
+    let pending = flatMemo.get(buffer);
+    if (pending === undefined) {
+        pending = computeFlatness(buffer);
+        flatMemo.set(buffer, pending);
+    }
+    return pending;
+}
+async function computeFlatness(buffer) {
+    try {
+        const { data, info } = await openImage(buffer)
+            .rotate()
+            .resize(FLAT_SIZE, FLAT_SIZE, { fit: "inside", kernel: "nearest", withoutEnlargement: true })
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        const pixels = info.width * info.height;
+        if (pixels === 0)
+            return undefined;
+        const counts = new Map();
+        let binary = 0;
+        for (let i = 0; i < data.length; i += 4) {
+            const key = ((data[i] >> 3) << 15) | ((data[i + 1] >> 3) << 10) | ((data[i + 2] >> 3) << 5) | (data[i + 3] >> 3);
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+            if (data[i + 3] === 0 || data[i + 3] === 255)
+                binary++;
+        }
+        const top16 = [...counts.values()].sort((a, b) => b - a).slice(0, 16).reduce((sum, n) => sum + n, 0);
+        const top16Share = top16 / pixels;
+        const uniqueColors = counts.size;
+        const smoothShare = smallStepShare(data, info.width, info.height);
+        const size = await displayedSize(buffer);
+        const megapixels = size === undefined ? 0 : round3((size.width * size.height) / 1e6);
+        return {
+            uniqueColors,
+            top16Share: round3(top16Share),
+            alphaBinaryShare: round3(binary / pixels),
+            smoothShare: round3(smoothShare),
+            megapixels,
+            flat: top16Share >= FLAT_TOP16_MIN && uniqueColors <= FLAT_MAX_COLORS && smoothShare <= FLAT_SMOOTH_MAX && megapixels <= VECTOR_MAX_MEGAPIXELS,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The share of horizontal and vertical neighbour pairs whose largest channel difference is a small step (1 to 8). */
+function smallStepShare(data, width, height) {
+    let small = 0;
+    let pairs = 0;
+    const diff = (i, j) => Math.max(Math.abs(data[i] - data[j]), Math.abs(data[i + 1] - data[j + 1]), Math.abs(data[i + 2] - data[j + 2]));
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = (y * width + x) * 4;
+            if (x + 1 < width) {
+                const d = diff(i, i + 4);
+                pairs++;
+                if (d >= 1 && d <= 8)
+                    small++;
+            }
+            if (y + 1 < height) {
+                const d = diff(i, i + width * 4);
+                pairs++;
+                if (d >= 1 && d <= 8)
+                    small++;
+            }
+        }
+    }
+    return pairs === 0 ? 0 : small / pairs;
+}
+/** The size of an image as it is displayed (orientation applied), from its header. Undefined when it cannot be read. */
+export async function displayedSize(buffer) {
+    try {
+        const meta = await openImage(buffer).metadata();
+        if (!meta.width || !meta.height)
+            return undefined;
+        const turned = (meta.orientation ?? 1) >= 5;
+        return turned ? { width: meta.height, height: meta.width } : { width: meta.width, height: meta.height };
+    }
+    catch {
+        return undefined;
+    }
+}
+let vectorizer;
+/** The vectorizer module, loaded once. Undefined when the optional dependency is not installed or will not load. Never throws. */
+export function loadVectorizer() {
+    vectorizer ??= import("@neplex/vectorizer").then((mod) => (typeof mod.vectorize === "function" && mod.Preset !== undefined ? mod : undefined), () => undefined);
+    return vectorizer;
+}
+/**
+ * The SVG traced from an image, with the Poster preset, after the trace input is downscaled (traceInput) and the cleanup.
+ * Undefined when the vectorizer is missing or the trace fails. Never throws.
+ */
+export async function traceSvg(buffer, signal) {
+    if (signal?.aborted || (await loadVectorizer()) === undefined)
+        return undefined;
+    try {
+        const svg = await traceInWorker(await traceInput(buffer), signal);
+        return svg === undefined ? undefined : cleanSvg(svg);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The vectorizer runs in a worker thread, so an abort really stops it: the native trace does not honour an AbortSignal once it
+ * has started, and only ending the thread stops the CPU. A worker is started per trace (a few per run, under the budget).
+ * Undefined when the trace fails, the worker dies, or the signal aborts (the worker is then terminated).
+ */
+const TRACE_WORKER = `
+const { parentPort, workerData } = require("node:worker_threads");
+const vectorizer = require(workerData.entry);
+vectorizer.vectorize(Buffer.from(workerData.png), vectorizer.Preset.Poster).then(
+  (svg) => parentPort.postMessage({ svg }),
+  () => parentPort.postMessage({ error: true }),
+);
+`;
+function traceInWorker(png, signal) {
+    return new Promise((resolve) => {
+        const entry = createRequire(import.meta.url).resolve("@neplex/vectorizer");
+        const worker = new Worker(TRACE_WORKER, { eval: true, workerData: { entry, png } });
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", onAbort);
+            void worker.terminate();
+            resolve(value);
+        };
+        const onAbort = () => finish(undefined);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        worker.on("message", (message) => finish(typeof message.svg === "string" ? message.svg : undefined));
+        worker.on("error", () => finish(undefined));
+        worker.on("exit", () => finish(undefined));
+        if (signal?.aborted)
+            onAbort();
+    });
+}
+/**
+ * The image as a PNG for the trace, rotated as displayed and downscaled to at most TRACE_MAX_PIXELS with a long side of at most
+ * TRACE_MAX_SIDE: a bigger input costs seconds of tracing for no gain in a vector.
+ */
+async function traceInput(buffer) {
+    const size = await displayedSize(buffer);
+    if (size === undefined)
+        throw new Error("not an image");
+    const { width, height } = size;
+    const scale = Math.min(1, Math.sqrt(TRACE_MAX_PIXELS / (width * height)), TRACE_MAX_SIDE / Math.max(width, height));
+    let img = openImage(buffer).rotate();
+    if (scale < 1)
+        img = img.resize(Math.max(1, Math.round(width * scale)), Math.max(1, Math.round(height * scale)), { kernel: "lanczos3" });
+    return img.png().toBuffer();
+}
+/**
+ * Light cleanup of a traced SVG: whitespace between tags goes, and the numbers of path data are rounded to one decimal
+ * (a 1/10 px change at most). The fidelity is scored on the cleaned SVG, so the rounding is measured, not assumed.
+ */
+export function cleanSvg(svg) {
+    return svg
+        .replace(/>\s+</g, "><")
+        .replace(/\sd="([^"]*)"/g, (_match, d) => ` d="${d.replace(/-?\d+\.\d+/g, (n) => (Math.round(Number(n) * 10) / 10).toFixed(1))}"`)
+        .trim();
+}
+/** The brotli (quality 11) size of an SVG: the bytes it costs on the wire, the same at every DPR. */
+export function svgBytes(svg) {
+    return brotliCompressSync(Buffer.from(svg, "utf8"), { params: { [constants.BROTLI_PARAM_QUALITY]: 11 } }).length;
+}
+/**
+ * The fidelity of an SVG against the served image it traces. The SVG is rendered back at the served size; the score is
+ * SSIMULACRA2 at half size (both images halved with lanczos3, so the raster's antialiasing is not the ground truth; capped
+ * at SCORE_MAX_PIXELS for a very large image), and badPixelShare is the share of pixels at that scoring size whose RGB L1
+ * difference is over BAD_PIXEL_L1. Both are on white.
+ */
+export async function svgFidelity(served, svg) {
+    const full = await decodeOnWhite(openImage(served).rotate());
+    // Scored at half size, and at most SCORE_MAX_PIXELS: a large logo costs seconds at full size, and the scale is the same
+    // for both images, so the score is the same kind of number.
+    const scale = Math.min(0.5, Math.sqrt(SCORE_MAX_PIXELS / (full.width * full.height)));
+    const width = Math.max(1, Math.round(full.width * scale));
+    const height = Math.max(1, Math.round(full.height * scale));
+    const ref = await resizeTo(full, width, height);
+    const test = await drawAt(svg, width, height);
+    // ssimulacra2 needs at least 8 px a side: a smaller image is scored at the size it has.
+    const value = width >= 8 && height >= 8 ? await score("ssimulacra2", ref, test) : await score("ssimulacra2", full, await drawAt(svg, full.width, full.height));
+    return { score: value, badPixelShare: badPixelShareOf(ref, test) };
+}
+/**
+ * The SVG drawn at width x height, the same way the served image is brought to that size (lanczos3). When the trace is
+ * smaller than the target (a large image, traced from a downscaled input), it is drawn at the target as vectors: resizing a
+ * small raster up would blur its edges.
+ */
+async function drawAt(svg, width, height) {
+    const root = /<svg[^>]*?\swidth="([\d.]+)"\s+height="([\d.]+)"/.exec(svg);
+    const traced = root === null ? { width, height } : { width: Number(root[1]), height: Number(root[2]) };
+    const drawn = traced.width >= width && traced.height >= height ? traced : { width, height };
+    const vector = svgSized(svg, root, drawn.width, drawn.height, traced);
+    const raster = await decodeOnWhite(sharp(Buffer.from(vector)));
+    return drawn.width === width && drawn.height === height ? raster : resizeTo(raster, width, height);
+}
+/** The SVG with its own size set to width x height, and a viewBox of its traced size (vectors scale without loss). */
+function svgSized(svg, root, width, height, traced) {
+    if (root === null)
+        return svg;
+    return svg.replace(root[0], root[0].replace(`width="${root[1]}" height="${root[2]}"`, `width="${width}" height="${height}" viewBox="0 0 ${traced.width} ${traced.height}"`));
+}
+async function decodeOnWhite(img) {
+    const { data, info } = await img.flatten({ background: WHITE }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    return { data: new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength), width: info.width, height: info.height };
+}
+async function resizeTo(img, width, height) {
+    const { data, info } = await sharp(Buffer.from(img.data.buffer, img.data.byteOffset, img.data.byteLength), {
+        raw: { width: img.width, height: img.height, channels: 4 },
+    })
+        .resize(width, height, { kernel: "lanczos3", fit: "fill" })
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    return { data: new Uint8ClampedArray(data.buffer, data.byteOffset, data.byteLength), width: info.width, height: info.height };
+}
+function badPixelShareOf(ref, test) {
+    const pixels = ref.width * ref.height;
+    if (pixels === 0)
+        return 0;
+    let bad = 0;
+    for (let i = 0; i < ref.data.length; i += 4) {
+        const d = Math.abs(ref.data[i] - test.data[i]) + Math.abs(ref.data[i + 1] - test.data[i + 1]) + Math.abs(ref.data[i + 2] - test.data[i + 2]);
+        if (d > BAD_PIXEL_L1)
+            bad++;
+    }
+    return round3(bad / pixels);
+}
+const round3 = (value) => Math.round(value * 1000) / 1000;