scenescout 3.15.0 → 3.17.0

package/dist/engine/open.js

@@ -0,0 +1,118 @@
+/**
+ * Opening the live view and the report in the user's default browser.
+ *
+ * The live view's address and the report's path are printed in tool results,
+ * but a person in a chat client may never see or follow them. The `open`
+ * setting has the engine open them itself: the live view when a session
+ * attaches, the report when scout_report writes it.
+ *
+ * Whether to open is decided here, by a pure function of the setting and the
+ * environment, so every case is table-tested. Opening goes through the
+ * platform opener with no shell, and only ever hands it a loopback URL or an
+ * absolute file path. The live view's own rules (loopback only, a token on
+ * every path, ADR 7) are unchanged: opening an address reaches nobody new.
+ *
+ * Nothing here imports Playwright, and the spawn is injected, so a test never
+ * launches a browser.
+ */
+import path from "node:path";
+import { isCiEnv } from "./capture.js";
+/** The environment variable that sets `open` for every session of the server. A `scout_attach` `open` wins over it. */
+export const OPEN_ENV = "SCENESCOUT_OPEN";
+export const OPEN_CHOICES = ["live", "report", "both", "none"];
+/** `SCENESCOUT_OPEN`, or undefined when unset. A value outside the choices is refused rather than ignored. */
+export function openChoiceFromEnv(env) {
+    const raw = (env[OPEN_ENV] ?? "").trim();
+    if (raw === "")
+        return undefined;
+    if (!OPEN_CHOICES.includes(raw))
+        throw new Error(`${OPEN_ENV} must be one of ${OPEN_CHOICES.join(", ")}, not ${JSON.stringify(raw)}`);
+    return raw;
+}
+/**
+ * Nobody would see a window opened from here: a session over SSH, where the
+ * browser would open on the remote machine if at all, or a Linux or other
+ * Unix machine with no display server. macOS and Windows always have one.
+ */
+export function noDisplay(env, platform) {
+    if (env.SSH_CONNECTION || env.SSH_TTY)
+        return true;
+    if (platform === "darwin" || platform === "win32")
+        return false;
+    return !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+const both = (choice, why) => ({
+    live: choice === "live" || choice === "both",
+    report: choice === "report" || choice === "both",
+    why,
+});
+/**
+ * What opens. A setting, from the attach or the environment, is followed as
+ * given. With none, both open on a local desktop session, whether the
+ * session's browser is headed or headless and whatever the MCP client
+ * declares: what a client declares is outside this project's control, and a
+ * person in a chat client is the one who most needs the page opened. Nothing
+ * opens in CI or where no display would show it. A developer who wants no
+ * tabs sets SCENESCOUT_OPEN=none.
+ */
+export function decideOpen(choice, ctx) {
+    if (choice)
+        return both(choice, `open is set to ${choice}`);
+    if (isCiEnv(ctx.env))
+        return both("none", "a CI run");
+    if (noDisplay(ctx.env, ctx.platform))
+        return both("none", "no display to show a window on");
+    return both("both", "a local desktop session");
+}
+/**
+ * Only what the engine itself produced may be opened: the live view's
+ * loopback address (plain http, no credentials) or an absolute path to a file.
+ * Anything else — a remote URL, a relative path, something that could read as
+ * an option to the opener — is refused.
+ */
+export function openableTarget(target) {
+    if (target === "" || /[\0-\x1f\x7f]/.test(target) || target.startsWith("-"))
+        return false;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target)) {
+        let u;
+        try {
+            u = new URL(target);
+        }
+        catch {
+            return false;
+        }
+        return u.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname) && !u.username && !u.password;
+    }
+    return path.isAbsolute(target) || path.win32.isAbsolute(target);
+}
+/**
+ * The platform's opener, run directly with the target as its only argument.
+ * Windows' `start` is a cmd.exe built-in and cannot run without a shell, so
+ * Windows uses the URL protocol handler `start` itself relies on.
+ */
+export function openerCommand(platform, target) {
+    if (platform === "darwin")
+        return { command: "open", args: [target] };
+    if (platform === "win32")
+        return { command: "rundll32", args: ["url.dll,FileProtocolHandler", target] };
+    return { command: "xdg-open", args: [target] };
+}
+/**
+ * Hand a target to the platform opener. Refuses a target openableTarget does
+ * not accept. The opener runs detached and is not waited for; a failure to
+ * start it (no xdg-open installed, say) arrives later through onError.
+ */
+export function openInBrowser(target, deps) {
+    if (!openableTarget(target))
+        return { ok: false, why: "only the live view's loopback address or an absolute file path is opened" };
+    const { command, args } = openerCommand(deps.platform, target);
+    try {
+        const child = deps.spawn(command, args, { shell: false, stdio: "ignore", detached: true });
+        child.on("error", (err) => deps.onError(`${command} could not start: ${err.message}`));
+        child.unref();
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, why: `${command} could not start: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/dist/engine/oracles.js

@@ -1,4 +1,15 @@
 import { redactSecrets } from "./memory.js";
+/** Every kind of violation the oracles record. One list, so the report's plain wording can be held equal to it. */
+export const ORACLE_KINDS = [
+    "console_error",
+    "page_error",
+    "request_failed",
+    "http_error",
+    "dom_injection",
+    "refused_empty",
+    "false_success",
+    "postmessage_token",
+];
 /** How an HTTP error violation states its request. One formatter, so a reader of the detail (the check) cannot drift from its writer. */
 export function httpErrorDetail(method, url, status) {
     return `${method} ${url.slice(0, 200)} → HTTP ${status}`;
@@ -21,6 +32,19 @@ export function redactViolation(v) {
 }
 /** How long after a write-policy block a generic "fetch failed" error is still attributed to it. */
 export const POLICY_BLOCK_WINDOW_MS = 2000;
+/**
+ * How a block surfaces in an error's wording: the browser's own lines for a
+ * dropped request or the stand-in 403, the status as HTTP clients word their
+ * rejection ("Request failed with status code 403", "403 Forbidden"), and the
+ * stand-in body's own sentence echoed into an error. A 403 alone with neither
+ * word is left out: "Error 403 at line 12" is not the policy.
+ */
+const POLICY_INDUCED_RE = [
+    /ERR_BLOCKED_BY_CLIENT|Failed to fetch|NetworkError when attempting to fetch|Load failed|the server responded with a status of 403\b/i,
+    /\bstatus(?: code)?:? 403\b/i,
+    /\b403\b[^\n]{0,40}\b(?:forbidden|refused)\b|\b(?:forbidden|refused)\b[^\n]{0,40}\b403\b/i,
+    /refused by the tester's [a-z-]+ write policy/i,
+];
 /**
  * Is this console or page error a consequence of the tester's OWN write-policy
  * block rather than something the app did?
@@ -42,7 +66,7 @@ export function isPolicyInduced(v, msSincePolicyBlock) {
         return false;
     if (v.kind !== "page_error" && v.kind !== "console_error")
         return false;
-    return /ERR_BLOCKED_BY_CLIENT|Failed to fetch|NetworkError when attempting to fetch|Load failed|the server responded with a status of 403\b/i.test(v.detail);
+    return POLICY_INDUCED_RE.some((re) => re.test(v.detail));
 }
 /**
  * The request a console message is the browser's own echo of, or null when it
@@ -424,6 +448,22 @@ export class OracleMonitor {
         return out;
     }
 }
+/**
+ * Violations a plan run with onViolation "continue" goes on past: an error
+ * status, and the console's echo of one. They say a step's page answered
+ * badly, which in a sweep of independent steps (tabs, filters, pages) is a
+ * result to list, not a reason the next step cannot run. Anything else (an
+ * uncaught exception, a failed request, typed markup coming back, a page
+ * contradicting the server, a token posted to any origin) stops a plan either way.
+ */
+export const CONTINUABLE_KINDS = new Set(["http_error", "console_error"]);
+/** Whether these violations, drained after one plan step, end the plan. Repeats of already-reported violations never do. */
+export function planStopsAt(violations, rule) {
+    const fresh = violations.filter((v) => !v.repeat);
+    if (fresh.length === 0)
+        return false;
+    return rule === "stop" || fresh.some((v) => !CONTINUABLE_KINDS.has(v.kind));
+}
 export function formatViolations(violations) {
     if (violations.length === 0)
         return "";

package/dist/engine/plain.js

@@ -0,0 +1,268 @@
+/**
+ * The report in plain words, for a reader who does not read request
+ * signatures and route patterns: a QA tester, a product owner, anyone who
+ * needs to act on a finding without decoding it first.
+ *
+ * It is a view over the same findings the technical report prints, never a
+ * replacement: each item keeps its technical detail one click away, and the
+ * `report` setting chooses which parts a document carries. Everything here is
+ * pure string work, so the wording and the step translation are table-tested.
+ */
+import { seenOnOf } from "./memory.js";
+/** Which parts a report carries: the plain view and the technical one ("both"), or one of them. */
+export const REPORT_AUDIENCES = ["both", "qa", "dev"];
+/** Both, so nobody loses the part they rely on unless they ask to. */
+export const DEFAULT_REPORT_AUDIENCE = "both";
+/**
+ * The plain wording for every finding category and every oracle kind, in one
+ * table. contract-test holds its keys equal to FINDING_CATEGORIES and
+ * ORACLE_KINDS, so a new category or oracle cannot ship without its words.
+ */
+export const PLAIN_WORDING = {
+    // Finding categories.
+    "console-error": { problem: "The page reported an error behind the scenes", expected: "The page works without reporting errors." },
+    "page-error": { problem: "Something on the page broke while it was being used", expected: "The page keeps working while it is used." },
+    "http-error": { problem: "The server refused or failed a request", expected: "The action completes, or the page says clearly why it could not." },
+    network: { problem: "A request to the server did not get through", expected: "The page loads what it needs, or says what is missing." },
+    "dead-end": { problem: "A path led nowhere", expected: "Every link and button leads somewhere useful, with a way back." },
+    "ux-confusing": { problem: "Something is confusing to use", expected: "It is clear what to do and what happened." },
+    "ux-polish": { problem: "Something feels unfinished", expected: "The page looks finished and consistent." },
+    visual: { problem: "Something looks wrong on screen", expected: "Everything is visible, readable and in its place." },
+    a11y: { problem: "Some people cannot use this part", expected: "Everyone can use it, including with a keyboard or a screen reader." },
+    "permission-leak": { problem: "Someone can see or do something they should not", expected: "Each person sees and does only what their role allows." },
+    "data-inconsistency": { problem: "The information shown does not add up", expected: "The same information agrees everywhere it is shown." },
+    "stale-state": { problem: "The page shows out-of-date information", expected: "The page shows the current state after every change." },
+    "data-loss": { problem: "Work or information was lost", expected: "What a person enters is kept." },
+    performance: { problem: "Something is too slow", expected: "The page responds without a noticeable wait." },
+    security: { problem: "A security weakness", expected: "The app keeps people's data and accounts safe." },
+    "missing-testid": { problem: "A control automated tests cannot find reliably", expected: "Every control can be found reliably by automated tests." },
+    other: { problem: "Something else is wrong", expected: "The app behaves the way a person using it would expect." },
+    // Oracle kinds: what the automatic checks notice on every page.
+    console_error: { problem: "The page reported an error behind the scenes", expected: "The page works without reporting errors." },
+    page_error: { problem: "Something on the page broke while it was being used", expected: "The page keeps working while it is used." },
+    request_failed: { problem: "A request to the server did not get through", expected: "The page loads what it needs, or says what is missing." },
+    http_error: { problem: "The server refused or failed a request", expected: "The action completes, or the page says clearly why it could not." },
+    dom_injection: { problem: "Text typed into a field came back as part of the page itself", expected: "What a person types is always shown as plain text." },
+    refused_empty: {
+        problem: "The server refused a request and the page showed nothing instead of an error",
+        expected: "When something fails, the page says so.",
+    },
+    false_success: { problem: "The page said something worked when the server had refused it", expected: "The page reports only what really happened." },
+    postmessage_token: { problem: "The page handed a sign-in token to any site that asked", expected: "Sign-in details go only to the app's own pages." },
+};
+/** The words for a category or oracle kind; one the table does not know (an older finding's) reads as "other". */
+export function plainWording(kind) {
+    return Object.prototype.hasOwnProperty.call(PLAIN_WORDING, kind) ? PLAIN_WORDING[kind] : PLAIN_WORDING.other;
+}
+/** Severity as its effect on the people using the app. */
+export const IMPACT = { high: "Blocks users", medium: "Annoying", low: "Cosmetic" };
+/** What a control's role is called in a sentence. */
+const ROLE_WORD = {
+    button: "button",
+    link: "link",
+    textbox: "field",
+    searchbox: "search box",
+    combobox: "list",
+    listbox: "list",
+    checkbox: "checkbox",
+    radio: "option",
+    switch: "switch",
+    tab: "tab",
+    menuitem: "menu item",
+    option: "option",
+    spinbutton: "field",
+    slider: "slider",
+    row: "row",
+    cell: "cell",
+};
+/** `role "name"` as "the "name" button"; a target that is not that shape is quoted as it is. */
+function control(target) {
+    const m = /^(\w+) "(.*)"$/.exec(target.trim());
+    if (!m)
+        return target.trim();
+    const word = ROLE_WORD[m[1]] ?? m[1];
+    return m[2] ? `the "${m[2]}" ${word}` : `the unnamed ${word}`;
+}
+/** One action-log step, split into what was done, to what, and on which page. */
+function splitStep(line) {
+    const at = line.lastIndexOf(" @ ");
+    const head = at >= 0 ? line.slice(0, at) : line;
+    const url = at >= 0 ? line.slice(at + 3) : "";
+    const space = head.indexOf(" ");
+    return space < 0 ? { action: head, target: "", url } : { action: head.slice(0, space), target: head.slice(space + 1), url };
+}
+/** Actions that move to a page, and so start the steps that matter. */
+const OPENS = new Set(["navigate", "crawl"]);
+/**
+ * One repro step as a person would do it, or null for a step only the tester
+ * takes (a snapshot, a screenshot, an audit, the write policy's own notes).
+ */
+export function plainStep(line) {
+    const { action: raw, target, url } = splitStep(line);
+    // A plan's step is the same action, run from a list.
+    const action = raw.replace(/^plan:/, "");
+    if (OPENS.has(action))
+        return `Go to ${url || target}`;
+    let m;
+    if ((m = /^click(?:×(\d+))?$/.exec(action))) {
+        const times = Number(m[1] ?? 1);
+        const verb = times === 2 ? "Double-click" : times > 2 ? `Click ${times} times on` : "Click";
+        return `${verb} ${control(target)}`;
+    }
+    if (action === "type") {
+        const t = /^(\w+ ".*") ← ("(?:[^"\\]|\\.)*")( \+ Enter)?/.exec(target);
+        if (!t)
+            return `Type into ${control(target)}`;
+        return `Type ${t[2]} into ${control(t[1])}${t[3] ? " and press Enter" : ""}`;
+    }
+    if (action === "select") {
+        const s = /^(\w+ ".*") = (.*)$/.exec(target);
+        return s ? `Choose "${s[2]}" in ${control(s[1])}` : `Choose an option in ${control(target)}`;
+    }
+    if (action === "upload") {
+        const u = / ← (.+?) \(/.exec(target);
+        return u ? `Attach the file "${u[1]}"` : "Attach a file";
+    }
+    if (action === "hover")
+        return `Point at ${control(target)}`;
+    if (action === "press")
+        return `Press ${target}`;
+    if (action === "scroll")
+        return target ? `Scroll ${target}` : "Scroll the page";
+    if (action === "back")
+        return "Go back to the previous page";
+    return null;
+}
+/** The page a step was on, for the first step when the trace has no navigation of its own. */
+function pageOf(line) {
+    return line ? splitStep(line).url : "";
+}
+/**
+ * A finding's repro trace as numbered steps a person can follow. It starts at
+ * the last time the run went to a page, since what came before that was on
+ * another page; when it never did, it starts by going to the page the trace
+ * began on. Steps only the tester takes are left out.
+ */
+export function plainSteps(repro) {
+    let start = -1;
+    for (let i = repro.length - 1; i >= 0; i--) {
+        if (OPENS.has(splitStep(repro[i]).action.replace(/^plan:/, ""))) {
+            start = i;
+            break;
+        }
+    }
+    const steps = (start >= 0 ? repro.slice(start) : repro).map(plainStep).filter((s) => s !== null);
+    if (start < 0) {
+        const first = pageOf(repro[0]);
+        if (first)
+            steps.unshift(`Go to ${first}`);
+    }
+    return steps;
+}
+/** A relative path inside the run's folder, safe to put in a document: no scheme, no `..`, nothing absolute. */
+export function isSafeRelativePath(p) {
+    return /^[A-Za-z0-9._-][A-Za-z0-9._/-]*$/.test(p) && !p.split("/").includes("..") && !p.includes("//");
+}
+/**
+ * The picture of a finding, as a path relative to the run's folder, or
+ * undefined. A finding's own picture comes first: `picture`, a path relative
+ * to the run's folder, is the slot a capture taken when a finding is filed
+ * fills, and no finding carries one yet. On a recorded run the last frame on
+ * screen before the finding was filed stands in. A value that is not a safe relative path is ignored, since the file is
+ * read back without a schema and the path goes into a page.
+ */
+export function pictureOf(f, lastFrame) {
+    const own = f.picture;
+    for (const p of [own, lastFrame])
+        if (typeof p === "string" && isSafeRelativePath(p))
+            return p;
+    return undefined;
+}
+const count = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/** "a, b and c". */
+function joinAnd(parts) {
+    return parts.length <= 1 ? parts.join("") : `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+/** The short summary that opens the plain section. */
+export function plainSummary(input) {
+    const lines = [];
+    const { current } = input;
+    const by = (s) => current.filter((f) => f.severity === s).length;
+    const where = input.routes && input.routes.total > 0 ? ` It went to ${input.routes.visited} of the ${input.routes.total} pages it knew about.` : "";
+    if (current.length === 0) {
+        lines.push(`This run found no problems.${where}`);
+    }
+    else {
+        const split = [
+            ["high", "blocks users", "block users"],
+            ["medium", "is annoying", "are annoying"],
+            ["low", "is cosmetic", "are cosmetic"],
+        ]
+            .filter(([s]) => by(s) > 0)
+            .map(([s, one, many]) => `${by(s)} ${by(s) === 1 ? one : many}`);
+        lines.push(`This run found ${count(current.length, "problem")}: ${joinAnd(split)}.${where}`);
+    }
+    const elsewhere = input.audience === "qa" ? "" : " They are listed in the technical detail below.";
+    if (input.historical > 0) {
+        lines.push(``, `${count(input.historical, "problem")} found by earlier runs ${input.historical === 1 ? "was" : "were"} not checked again this time.${elsewhere}`);
+    }
+    if (input.worthALook > 0) {
+        lines.push(``, `${count(input.worthALook, "observation")} ${input.worthALook === 1 ? "is a problem" : "are problems"} only if your project follows a particular convention, so ${input.worthALook === 1 ? "it is" : "they are"} not counted here.${elsewhere}`);
+    }
+    const kinds = new Map();
+    for (const v of input.violations)
+        kinds.set(v.kind, (kinds.get(v.kind) ?? 0) + 1);
+    if (kinds.size > 0) {
+        lines.push(``, `While it worked, the automatic checks noticed:`, ``);
+        for (const [kind, n] of [...kinds.entries()].sort((a, b) => b[1] - a[1]))
+            lines.push(`- ${plainWording(kind).problem} (${n === 1 ? "once" : `${n} times`})`);
+    }
+    if (input.gaps.length > 0) {
+        lines.push(``, `The run left ${count(input.gaps.length, "thing")} unchecked.${input.audience === "qa" ? "" : " The gap ledger below says which."}`);
+        if (input.audience === "qa") {
+            lines.push(``);
+            for (const g of input.gaps)
+                lines.push(`- ${g}`);
+        }
+    }
+    return lines;
+}
+/** One finding in plain words, with its technical detail folded beneath it. */
+export function plainFinding(f, index, input) {
+    const words = plainWording(f.category);
+    // One cause in a shared part of the app is seen on every page that shows it.
+    const also = seenOnOf(f);
+    const lines = [
+        `### ${index}. ${f.title}`,
+        ``,
+        `**${IMPACT[f.severity]}** · ${words.problem} · on ${f.url}${also.length > 0 ? `, and also seen on ${also.join(", ")}` : ""}`,
+        ``,
+    ];
+    const picture = pictureOf(f, input.lastFrames?.get(f.id));
+    if (picture)
+        lines.push(`![What the page showed](${picture})`, ``);
+    const steps = plainSteps(f.repro);
+    if (steps.length > 0) {
+        lines.push(`**What was done:**`, ``);
+        steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+        lines.push(``);
+    }
+    lines.push(`**What was expected:** ${words.expected}`, ``, `**What happened:** ${f.detail.replace(/\r?\n+/g, " ")}`, ``);
+    lines.push(`<details><summary>Technical detail</summary>`, ``);
+    // "Finding id", not "Id": the HTML and the live view hang a finding's recorded
+    // frames under the list that names its "Id", and that is the full entry's.
+    lines.push(`- **Finding id:** \`${f.id}\` · **Category:** ${f.category} · **Severity:** ${f.severity}`);
+    if (f.evidence)
+        lines.push(`- **Evidence:** \`${f.evidence}\``);
+    lines.push(`- **Route:** \`${f.state}\``);
+    if (input.audience !== "qa")
+        lines.push(`- The full entry, with the repro trace and a test skeleton, is under the same id in the technical detail below.`);
+    lines.push(``, `</details>`, ``);
+    return lines;
+}
+/** The whole plain section: the summary, then each problem this run found, worst first. */
+export function formatPlainSection(input) {
+    const lines = [`## In plain words`, ``, ...plainSummary(input), ``, ...(input.tickets ?? [])];
+    input.current.forEach((f, i) => lines.push(...plainFinding(f, i + 1, input)));
+    return lines;
+}

package/dist/engine/png.js

@@ -236,3 +236,130 @@ export function diffImages(before, after, threshold = DIFF_THRESHOLD) {
         image: { width, height, data },
     };
 }
+/**
+ * Shrinks a picture to `width` × `height` by averaging the source pixels each
+ * output pixel covers, so text and thin lines fade rather than vanish the way
+ * picking one pixel in every few would make them. Never enlarges: a size
+ * larger than the source in either direction is the source's in it.
+ */
+export function shrinkImage(img, width, height) {
+    const w = Math.max(1, Math.min(img.width, Math.floor(width)));
+    const h = Math.max(1, Math.min(img.height, Math.floor(height)));
+    if (w === img.width && h === img.height)
+        return img;
+    const data = new Uint8Array(w * h * 4);
+    const sx = img.width / w;
+    const sy = img.height / h;
+    for (let y = 0; y < h; y++) {
+        const y0 = Math.floor(y * sy);
+        const y1 = Math.max(y0 + 1, Math.floor((y + 1) * sy));
+        for (let x = 0; x < w; x++) {
+            const x0 = Math.floor(x * sx);
+            const x1 = Math.max(x0 + 1, Math.floor((x + 1) * sx));
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            for (let yy = y0; yy < y1; yy++) {
+                for (let xx = x0; xx < x1; xx++) {
+                    const i = (yy * img.width + xx) * 4;
+                    r += img.data[i];
+                    g += img.data[i + 1];
+                    b += img.data[i + 2];
+                    a += img.data[i + 3];
+                }
+            }
+            const n = (y1 - y0) * (x1 - x0);
+            const o = (y * w + x) * 4;
+            data[o] = Math.round(r / n);
+            data[o + 1] = Math.round(g / n);
+            data[o + 2] = Math.round(b / n);
+            data[o + 3] = Math.round(a / n);
+        }
+    }
+    return { width: w, height: h, data };
+}
+/**
+ * Writes a picture as a PNG as small as this encoder makes one: three
+ * channels when every pixel is opaque (a screenshot always is), and each row
+ * filtered by whichever of the five PNG filters leaves the smallest sum, the
+ * usual heuristic. encodePng stays as it is, since the diff is written by it.
+ */
+export function encodePngCompact(img) {
+    if (img.data.length !== img.width * img.height * 4)
+        throw new Error("the pixel data is not width × height × 4 bytes");
+    let opaque = true;
+    for (let i = 3; i < img.data.length; i += 4)
+        if (img.data[i] !== 255) {
+            opaque = false;
+            break;
+        }
+    const channels = opaque ? 3 : 4;
+    const stride = img.width * channels;
+    const rows = new Uint8Array(img.height * stride);
+    if (opaque) {
+        for (let i = 0, j = 0; i < img.data.length; i += 4, j += 3) {
+            rows[j] = img.data[i];
+            rows[j + 1] = img.data[i + 1];
+            rows[j + 2] = img.data[i + 2];
+        }
+    }
+    else
+        rows.set(img.data);
+    const raw = Buffer.alloc(img.height * (stride + 1));
+    const trial = new Uint8Array(stride);
+    for (let y = 0; y < img.height; y++) {
+        const row = y * stride;
+        let best = Infinity;
+        const out = y * (stride + 1);
+        for (let filter = 0; filter <= 4; filter++) {
+            let sum = 0;
+            for (let x = 0; x < stride; x++) {
+                const left = x >= channels ? rows[row + x - channels] : 0;
+                const up = y > 0 ? rows[row - stride + x] : 0;
+                const upLeft = y > 0 && x >= channels ? rows[row - stride + x - channels] : 0;
+                const v = rows[row + x];
+                const p = filter === 0 ? 0 : filter === 1 ? left : filter === 2 ? up : filter === 3 ? (left + up) >> 1 : paeth(left, up, upLeft);
+                const f = (v - p) & 0xff;
+                trial[x] = f;
+                sum += f < 128 ? f : 256 - f;
+            }
+            if (sum < best) {
+                best = sum;
+                raw[out] = filter;
+                raw.set(trial, out + 1);
+            }
+        }
+    }
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(img.width, 0);
+    header.writeUInt32BE(img.height, 4);
+    header[8] = 8;
+    header[9] = opaque ? 2 : 6;
+    return Buffer.concat([SIGNATURE, chunk("IHDR", header), chunk("IDAT", deflateSync(raw, { level: 9 })), chunk("IEND", new Uint8Array(0))]);
+}
+/** The most a picture is shrunk to fit its bytes: below this on its longer side it is no longer worth showing. */
+export const FIT_MIN_SIDE = 120;
+/**
+ * A picture within `maxSide` pixels on its longer side and `maxBytes` as a
+ * PNG: shrunk to the side first, then, while the file is still too large,
+ * shrunk again in proportion to how far over it is. Null when even
+ * FIT_MIN_SIDE on its longer side is over the bytes: nothing worth looking at
+ * fits, and the caller says so rather than keeping a smudge.
+ */
+export function fitPicture(img, maxSide, maxBytes) {
+    const longer = Math.max(img.width, img.height);
+    let scale = Math.min(1, maxSide / longer);
+    for (let attempt = 0; attempt < 8; attempt++) {
+        const width = Math.max(1, Math.round(img.width * scale));
+        const height = Math.max(1, Math.round(img.height * scale));
+        const png = encodePngCompact(shrinkImage(img, width, height));
+        if (png.length <= maxBytes)
+            return { png, width, height, shrunk: width !== img.width || height !== img.height };
+        if (Math.max(width, height) <= FIT_MIN_SIDE)
+            return null;
+        // Bytes go roughly with area, so the side goes with the square root; a little under, so one more pass usually fits.
+        scale = Math.max(FIT_MIN_SIDE / longer, scale * Math.sqrt(maxBytes / png.length) * 0.9);
+    }
+    return null;
+}