@bridge_gpt/mcp-server 0.2.18 → 0.2.19

package/build/visual-diff.js

@@ -0,0 +1,632 @@
+/**
+ * visual-diff.ts — orchestration for the deterministic `visual_diff` MCP tool
+ * (BAPI-563).
+ *
+ * `index.ts` stays the thin registration surface; the browser render, image
+ * sniffing/dimension logic, comp resolution, and worker dispatch live here so
+ * they are unit-testable without launching a real browser or spawning worker
+ * threads. `runVisualDiff` renders `target_url` with Playwright, screenshots it,
+ * diffs it pixel-for-pixel against a design comp, and returns an MCP content
+ * array: a JSON text block plus a native `type: "image"` heatmap. Every internal
+ * failure is caught and returned as a structured JSON envelope — it never throws
+ * to the MCP transport.
+ *
+ * Determinism discipline is baked in: viewport auto-matches the comp's intrinsic
+ * pixel dimensions, the browser runs at deviceScaleFactor 1, animations /
+ * transitions / caret are disabled, fonts settle, and mask selectors black out
+ * dynamic content in BOTH images before the diff. The pass gate uses a non-zero
+ * mismatch budget (never 0%, which AA/font rendering makes unreachable).
+ */
+import path from "path";
+import { Worker } from "worker_threads";
+import { computePngVisualDiff, DEFAULT_PASS_MISMATCH_PCT, PIXELMATCH_COLOR_THRESHOLD, } from "./visual-diff-worker.js";
+// ---------------------------------------------------------------------------
+// Constants (bounded resource / timeout guards)
+// ---------------------------------------------------------------------------
+/** Navigation timeout (ms) for page.goto. */
+export const NAV_TIMEOUT_MS = 30_000;
+/** Network-idle settle timeout (ms). */
+export const NETWORK_IDLE_TIMEOUT_MS = 15_000;
+/** document.fonts.ready settle timeout (ms). Best-effort — proceeds on timeout. */
+export const FONTS_READY_TIMEOUT_MS = 5_000;
+/** Screenshot capture timeout (ms). */
+export const SCREENSHOT_TIMEOUT_MS = 20_000;
+/** Conservative per-axis pixel guard to avoid unbounded local CPU/memory use. */
+export const MAX_VIEWPORT_DIMENSION = 16_384;
+/** Conservative total-pixel guard. */
+export const MAX_VIEWPORT_PIXELS = 32_000_000;
+/** Conservative comp byte-size guard (~25 MB). */
+export const MAX_COMP_BYTES = 25 * 1024 * 1024;
+/** Deterministic CSS injected before capture to stop flaky pixels. */
+export const DETERMINISTIC_CSS = "* { animation: none !important; transition: none !important; caret-color: transparent !important; }";
+// ---------------------------------------------------------------------------
+// MCP envelope helpers
+// ---------------------------------------------------------------------------
+export function textJson(value) {
+    return { type: "text", text: JSON.stringify(value, null, 2) };
+}
+export function errorContent(error, status, message, extra) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error, status, message, ...(extra ?? {}) }),
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Image format detection + intrinsic dimensions
+// ---------------------------------------------------------------------------
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+export function sniffImageFormat(bytes) {
+    if (bytes.length >= 8 && PNG_MAGIC.every((b, i) => bytes[i] === b)) {
+        return "png";
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return "jpeg";
+    }
+    return null;
+}
+export function readPngDimensions(bytes) {
+    // 8-byte signature, then IHDR chunk: 4 length + 4 "IHDR" + 4 width + 4 height.
+    if (bytes.length < 24 || sniffImageFormat(bytes) !== "png") {
+        return { ok: false, message: "Not a valid PNG header." };
+    }
+    if (bytes[12] !== 0x49 || // 'I'
+        bytes[13] !== 0x48 || // 'H'
+        bytes[14] !== 0x44 || // 'D'
+        bytes[15] !== 0x52 // 'R'
+    ) {
+        return { ok: false, message: "PNG IHDR chunk not found." };
+    }
+    const width = readUInt32BE(bytes, 16);
+    const height = readUInt32BE(bytes, 20);
+    if (width <= 0 || height <= 0) {
+        return { ok: false, message: "PNG reports non-positive dimensions." };
+    }
+    return { ok: true, width, height };
+}
+export function readJpegDimensions(bytes) {
+    if (sniffImageFormat(bytes) !== "jpeg") {
+        return { ok: false, message: "Not a valid JPEG header." };
+    }
+    let offset = 2; // skip SOI (0xFFD8)
+    const len = bytes.length;
+    while (offset + 1 < len) {
+        if (bytes[offset] !== 0xff) {
+            offset++;
+            continue;
+        }
+        let marker = bytes[offset + 1];
+        // Skip fill bytes (0xFF padding).
+        while (marker === 0xff && offset + 1 < len) {
+            offset++;
+            marker = bytes[offset + 1];
+        }
+        offset += 2;
+        // Standalone markers (no length): RSTn, SOI, EOI, TEM.
+        if ((marker >= 0xd0 && marker <= 0xd9) ||
+            marker === 0x01) {
+            continue;
+        }
+        if (offset + 1 >= len)
+            break;
+        const segLen = readUInt16BE(bytes, offset);
+        // SOF markers carry intrinsic dimensions (exclude DHT/DAC/DQT/JPGn variants).
+        const isSof = marker >= 0xc0 &&
+            marker <= 0xcf &&
+            marker !== 0xc4 &&
+            marker !== 0xc8 &&
+            marker !== 0xcc;
+        if (isSof) {
+            if (offset + 5 >= len)
+                break;
+            const height = readUInt16BE(bytes, offset + 3);
+            const width = readUInt16BE(bytes, offset + 5);
+            if (width <= 0 || height <= 0) {
+                return { ok: false, message: "JPEG SOF reports non-positive dimensions." };
+            }
+            return { ok: true, width, height };
+        }
+        offset += segLen;
+    }
+    return { ok: false, message: "No supported JPEG SOF marker found." };
+}
+function readUInt32BE(b, o) {
+    return (b[o] * 0x1000000) + (b[o + 1] << 16) + (b[o + 2] << 8) + b[o + 3];
+}
+function readUInt16BE(b, o) {
+    return (b[o] << 8) + b[o + 1];
+}
+function isPositiveInt(n) {
+    return Number.isInteger(n) && n > 0;
+}
+export function resolveViewport(input, compDimensions) {
+    const vp = input.viewport ?? compDimensions;
+    if (!isPositiveInt(vp.width) || !isPositiveInt(vp.height)) {
+        return {
+            ok: false,
+            error: "INVALID_VIEWPORT",
+            status: 400,
+            message: `Viewport must be positive integers, got ${vp.width}x${vp.height}.`,
+        };
+    }
+    if (vp.width > MAX_VIEWPORT_DIMENSION ||
+        vp.height > MAX_VIEWPORT_DIMENSION ||
+        vp.width * vp.height > MAX_VIEWPORT_PIXELS) {
+        return {
+            ok: false,
+            error: "IMAGE_TOO_LARGE",
+            status: 413,
+            message: `Requested render area ${vp.width}x${vp.height} exceeds the local pixel guard.`,
+        };
+    }
+    return { ok: true, viewport: { width: vp.width, height: vp.height } };
+}
+function toUint8(bytes) {
+    return bytes instanceof Uint8Array ? bytes : Buffer.from(bytes);
+}
+export async function resolveCompRef(compRef, deps) {
+    // 1. Local file resolution first (absolute as-is; relative against project
+    //    root, then cwd as a secondary candidate).
+    const candidates = [];
+    if (path.isAbsolute(compRef)) {
+        candidates.push(compRef);
+    }
+    else {
+        const root = await deps.getProjectRoot();
+        candidates.push(path.resolve(root, compRef));
+        const cwdCandidate = path.resolve(process.cwd(), compRef);
+        if (!candidates.includes(cwdCandidate))
+            candidates.push(cwdCandidate);
+    }
+    for (const candidate of candidates) {
+        try {
+            const st = await deps.stat(candidate);
+            if (st && st.isFile()) {
+                const bytes = toUint8(await deps.readFile(candidate));
+                return { ok: true, bytes, source: "local", sourcePath: candidate, warnings: [] };
+            }
+        }
+        catch {
+            // Not present / not accessible — try the next candidate.
+        }
+    }
+    // 2. Attachment resolution. Numeric-looking refs are attachment ids; anything
+    //    else is treated as a filename.
+    const trimmed = compRef.trim();
+    const lookup = /^\d+$/.test(trimmed)
+        ? { kind: "attachment_id", attachment_id: trimmed }
+        : { kind: "filename", filename: compRef };
+    const fetched = await deps.fetchAttachmentBytes(lookup);
+    if (!fetched.ok) {
+        return { ok: false, error: fetched.error, status: fetched.status, message: fetched.message };
+    }
+    const bytes = toUint8(fetched.bytes);
+    // Persist a local copy under visual-diffs (warn-only: never fail the diff once
+    // the bytes are already in hand).
+    const warnings = [];
+    try {
+        const dir = await deps.getDocsPath("visual-diffs");
+        const rawName = fetched.filename ||
+            (lookup.kind === "attachment_id" ? `attachment-${lookup.attachment_id}` : lookup.filename);
+        const base = path.basename(rawName); // strips any path traversal in the name
+        const target = path.resolve(dir, `comp-${deps.safeTimestampForFilename()}-${base}`);
+        if (!target.startsWith(path.resolve(dir) + path.sep)) {
+            warnings.push("Skipped saving attachment comp copy: resolved path escaped the visual-diffs directory.");
+        }
+        else {
+            await deps.mkdir(dir, { recursive: true });
+            await deps.writeFile(target, Buffer.from(bytes));
+        }
+    }
+    catch (err) {
+        warnings.push(`Attachment comp copy could not be saved locally: ${err instanceof Error ? err.message : "unknown error"}`);
+    }
+    return { ok: true, bytes, source: "attachment", warnings };
+}
+// ---------------------------------------------------------------------------
+// Browser loading + deterministic capture
+// ---------------------------------------------------------------------------
+export async function loadPlaywright() {
+    try {
+        // A non-literal specifier keeps tsc from requiring the optional package at
+        // compile time and keeps esbuild from inlining it — mirroring the
+        // better-sqlite3 optional-native gating precedent.
+        const specifier = "playwright";
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = await import(specifier);
+        const chromium = mod?.chromium ?? mod?.default?.chromium;
+        if (!chromium || typeof chromium.launch !== "function") {
+            return { ok: false };
+        }
+        return { ok: true, playwright: { chromium } };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+export async function launchBrowser(playwright) {
+    try {
+        const browser = await playwright.chromium.launch({ headless: true });
+        return { ok: true, browser };
+    }
+    catch (err) {
+        // Missing browser binary and launch failures both degrade to BROWSER_UNAVAILABLE.
+        return {
+            ok: false,
+            error: "BROWSER_UNAVAILABLE",
+            status: 503,
+            message: `Chromium could not be launched: ${err instanceof Error ? err.message : "unknown error"}. Run "npx playwright install chromium".`,
+        };
+    }
+}
+/** Clip, integer-round, and deterministically sort raw mask boxes. */
+export function normalizeMaskBoxes(raw, viewport) {
+    const boxes = [];
+    for (const r of raw) {
+        const x0 = Math.max(0, Math.floor(r.x));
+        const y0 = Math.max(0, Math.floor(r.y));
+        const x1 = Math.min(viewport.width, Math.ceil(r.x + r.width));
+        const y1 = Math.min(viewport.height, Math.ceil(r.y + r.height));
+        const width = x1 - x0;
+        const height = y1 - y0;
+        if (width > 0 && height > 0) {
+            boxes.push({ x: x0, y: y0, width, height });
+        }
+    }
+    boxes.sort((a, b) => {
+        if (a.y !== b.y)
+            return a.y - b.y;
+        if (a.x !== b.x)
+            return a.x - b.x;
+        if (a.width !== b.width)
+            return a.width - b.width;
+        return a.height - b.height;
+    });
+    return boxes;
+}
+export async function collectMaskBoxes(page, selectors, viewport) {
+    if (!selectors || selectors.length === 0)
+        return [];
+    const raw = (await page.evaluate((sels) => {
+        const out = [];
+        for (const sel of sels) {
+            // eslint-disable-next-line no-undef
+            document.querySelectorAll(sel).forEach((el) => {
+                const rect = el.getBoundingClientRect();
+                out.push({ x: rect.x, y: rect.y, width: rect.width, height: rect.height });
+            });
+        }
+        return out;
+    }, selectors));
+    return normalizeMaskBoxes(Array.isArray(raw) ? raw : [], viewport);
+}
+export async function captureRenderPng(browser, targetUrl, viewport, maskSelectors) {
+    const context = await browser.newContext({ viewport, deviceScaleFactor: 1 });
+    let page;
+    try {
+        page = await context.newPage();
+        try {
+            await page.goto(targetUrl, { timeout: NAV_TIMEOUT_MS, waitUntil: "load" });
+            await page.waitForLoadState("networkidle", { timeout: NETWORK_IDLE_TIMEOUT_MS });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: isTimeoutError(err) ? "PAGE_TIMEOUT" : "PAGE_LOAD_FAILED",
+                status: isTimeoutError(err) ? 504 : 502,
+                message: `Failed to load ${targetUrl}: ${err instanceof Error ? err.message : "unknown error"}`,
+            };
+        }
+        // Deterministic settling: kill animations/transitions/caret, then wait fonts.
+        await page.addStyleTag({ content: DETERMINISTIC_CSS });
+        await settleFonts(page);
+        const maskBoxes = await collectMaskBoxes(page, maskSelectors, viewport);
+        let png;
+        try {
+            png = await page.screenshot({
+                clip: { x: 0, y: 0, width: viewport.width, height: viewport.height },
+                timeout: SCREENSHOT_TIMEOUT_MS,
+                animations: "disabled",
+            });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: isTimeoutError(err) ? "PAGE_TIMEOUT" : "PAGE_LOAD_FAILED",
+                status: isTimeoutError(err) ? 504 : 502,
+                message: `Screenshot capture failed: ${err instanceof Error ? err.message : "unknown error"}`,
+            };
+        }
+        return { ok: true, png: toUint8(png), maskBoxes, dimensions: viewport };
+    }
+    finally {
+        try {
+            if (page)
+                await page.close();
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            await context.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+async function settleFonts(page) {
+    try {
+        await Promise.race([
+            page.evaluate(() => {
+                // eslint-disable-next-line no-undef
+                const d = document;
+                return d.fonts && d.fonts.ready ? d.fonts.ready.then(() => true) : true;
+            }),
+            new Promise((resolve) => setTimeout(resolve, FONTS_READY_TIMEOUT_MS)),
+        ]);
+    }
+    catch {
+        // Font readiness is best-effort; never fail capture on it.
+    }
+}
+function isTimeoutError(err) {
+    const msg = err instanceof Error ? err.message : String(err ?? "");
+    return /timeout|timed out|TimeoutError/i.test(msg);
+}
+// ---------------------------------------------------------------------------
+// JPEG -> PNG normalization (through the already-launched browser)
+// ---------------------------------------------------------------------------
+export async function normalizeCompToPng(browser, compBytes, format, dims) {
+    if (format === "png") {
+        return { ok: true, png: Buffer.from(compBytes) };
+    }
+    // JPEG: decode + re-encode as PNG in the browser at intrinsic dimensions so
+    // both diff inputs are PNG without a native image dependency.
+    const context = await browser.newContext({ viewport: dims, deviceScaleFactor: 1 });
+    let page;
+    try {
+        page = await context.newPage();
+        if (page.setContent) {
+            await page.setContent("<!doctype html><html><body></body></html>");
+        }
+        const dataUrl = `data:image/jpeg;base64,${Buffer.from(compBytes).toString("base64")}`;
+        const pngDataUrl = (await page.evaluate(async (arg) => {
+            // eslint-disable-next-line no-undef
+            const img = new Image();
+            await new Promise((resolve, reject) => {
+                img.onload = () => resolve();
+                img.onerror = () => reject(new Error("image load failed"));
+                img.src = arg.url;
+            });
+            // eslint-disable-next-line no-undef
+            const canvas = document.createElement("canvas");
+            canvas.width = arg.w;
+            canvas.height = arg.h;
+            const ctx = canvas.getContext("2d");
+            if (!ctx)
+                throw new Error("no 2d context");
+            ctx.drawImage(img, 0, 0, arg.w, arg.h);
+            return canvas.toDataURL("image/png");
+        }, { url: dataUrl, w: dims.width, h: dims.height }));
+        const base64 = pngDataUrl.split(",")[1] ?? "";
+        if (!base64) {
+            return {
+                ok: false,
+                error: "IMAGE_DECODE_FAILED",
+                status: 422,
+                message: "Browser-side JPEG normalization produced no PNG data.",
+            };
+        }
+        return { ok: true, png: Buffer.from(base64, "base64") };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: "UNSUPPORTED_COMP_IMAGE",
+            status: 400,
+            message: `Failed to normalize JPEG comp to PNG: ${err instanceof Error ? err.message : "unknown error"}`,
+        };
+    }
+    finally {
+        try {
+            if (page)
+                await page.close();
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            await context.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+export async function computeVisualDiffInWorker(args, deps) {
+    try {
+        return await runInWorker(args);
+    }
+    catch (err) {
+        // Worker spawning can fail in bundled/edge runtimes; the deterministic
+        // engine is pure, so fall back to computing inline rather than failing.
+        deps?.logger?.(`visual_diff: worker unavailable, computing inline (${err instanceof Error ? err.message : "unknown error"}).`);
+        try {
+            return computePngVisualDiff(args);
+        }
+        catch (inlineErr) {
+            return {
+                ok: false,
+                error: "DIFF_FAILED",
+                status: 500,
+                message: `Diff computation failed: ${inlineErr instanceof Error ? inlineErr.message : "unknown error"}`,
+            };
+        }
+    }
+}
+function runInWorker(args) {
+    return new Promise((resolve, reject) => {
+        // Variable specifier so esbuild does not treat the worker as a bundled
+        // asset; it resolves to the tsc-emitted build/visual-diff-worker.js sibling.
+        const workerRelative = "./visual-diff-worker.js";
+        const workerUrl = new URL(workerRelative, import.meta.url);
+        let settled = false;
+        let worker;
+        try {
+            worker = new Worker(workerUrl, { workerData: args });
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        worker.once("message", (msg) => {
+            settled = true;
+            resolve(msg);
+            void worker.terminate();
+        });
+        worker.once("error", (err) => {
+            if (!settled)
+                reject(err);
+        });
+        worker.once("exit", (code) => {
+            if (!settled && code !== 0) {
+                reject(new Error(`diff worker exited with code ${code}`));
+            }
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Heatmap persistence (warn-only)
+// ---------------------------------------------------------------------------
+export async function saveHeatmap(heatmapBase64, deps) {
+    try {
+        const dir = await deps.getDocsPath("visual-diffs");
+        const target = path.resolve(dir, `visual-diff-${deps.safeTimestampForFilename()}.png`);
+        if (!target.startsWith(path.resolve(dir) + path.sep)) {
+            return { ok: false, warning: "Heatmap not saved: resolved path escaped the visual-diffs directory." };
+        }
+        await deps.mkdir(dir, { recursive: true });
+        await deps.writeFile(target, Buffer.from(heatmapBase64, "base64"));
+        return { ok: true, path: target };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            warning: `Heatmap could not be saved locally: ${err instanceof Error ? err.message : "unknown error"}`,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// High-level orchestration
+// ---------------------------------------------------------------------------
+export async function runVisualDiff(input, deps) {
+    try {
+        const warnings = [];
+        // 1. Resolve comp bytes (local path first, then Jira attachment).
+        const resolved = await resolveCompRef(input.comp_ref, deps);
+        if (!resolved.ok) {
+            return errorContent(resolved.error, resolved.status, resolved.message);
+        }
+        warnings.push(...resolved.warnings);
+        const compBytes = resolved.bytes;
+        if (compBytes.length > MAX_COMP_BYTES) {
+            return errorContent("IMAGE_TOO_LARGE", 413, `Comp image is ${compBytes.length} bytes, exceeding the ${MAX_COMP_BYTES}-byte guard.`);
+        }
+        // 2. Detect format + intrinsic comp dimensions.
+        const format = sniffImageFormat(compBytes);
+        if (!format) {
+            return errorContent("UNSUPPORTED_COMP_IMAGE", 400, "comp_ref resolved but is not a decodable PNG or JPEG image.");
+        }
+        const dims = format === "png" ? readPngDimensions(compBytes) : readJpegDimensions(compBytes);
+        if (!dims.ok) {
+            return errorContent("UNSUPPORTED_COMP_IMAGE", 400, dims.message);
+        }
+        const compDimensions = { width: dims.width, height: dims.height };
+        // 3. Resolve viewport (auto-match comp unless caller overrode it).
+        const vp = resolveViewport(input, compDimensions);
+        if (!vp.ok) {
+            return errorContent(vp.error, vp.status, vp.message);
+        }
+        // 4. Load Playwright (degrade cleanly when the optional runtime is absent).
+        const loader = deps.loadPlaywright ?? loadPlaywright;
+        const loaded = await loader();
+        if (!loaded.ok) {
+            return errorContent("BROWSER_UNAVAILABLE", 503, 'The optional Playwright browser runtime is not available. Install it with "npm i playwright && npx playwright install chromium".');
+        }
+        // 5. Launch browser.
+        const launch = await launchBrowser(loaded.playwright);
+        if (!launch.ok) {
+            return errorContent(launch.error, launch.status, launch.message);
+        }
+        const browser = launch.browser;
+        let capture;
+        let normalized;
+        try {
+            capture = await captureRenderPng(browser, input.target_url, vp.viewport, input.mask_selectors);
+            if (!capture.ok) {
+                return errorContent(capture.error, capture.status, capture.message);
+            }
+            normalized = await normalizeCompToPng(browser, compBytes, format, compDimensions);
+            if (!normalized.ok) {
+                return errorContent(normalized.error, normalized.status, normalized.message);
+            }
+        }
+        finally {
+            try {
+                await browser.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        // 6. Diff (worker thread, inline fallback).
+        const passMismatchPct = typeof input.threshold === "number" ? input.threshold : DEFAULT_PASS_MISMATCH_PCT;
+        const diff = await computeVisualDiffInWorker({
+            compPngBuffer: normalized.png,
+            renderPngBuffer: capture.png,
+            maskBoxes: capture.maskBoxes,
+            passMismatchPct,
+            pixelmatchColorThreshold: PIXELMATCH_COLOR_THRESHOLD,
+        }, deps);
+        if (!diff.ok) {
+            return errorContent(diff.error, diff.status, diff.message);
+        }
+        // 7. Persist heatmap (warn-only).
+        const saved = await saveHeatmap(diff.heatmap_base64, deps);
+        const heatmapPath = saved.ok ? saved.path : null;
+        if (!saved.ok)
+            warnings.push(saved.warning);
+        // 8. Assemble the MCP content: JSON text block first, image second.
+        const result = {
+            mismatch_pct: diff.mismatch_pct,
+            dimension_match: diff.dimension_match,
+            diff_regions: diff.diff_regions,
+            heatmap_path: heatmapPath,
+            comp_dimensions: diff.comp_dimensions,
+            render_dimensions: diff.render_dimensions,
+            threshold_used: passMismatchPct,
+            passed: diff.passed,
+        };
+        if (!diff.dimension_match) {
+            result.message =
+                `Render dimensions ${diff.render_dimensions.width}x${diff.render_dimensions.height} differ from ` +
+                    `comp dimensions ${diff.comp_dimensions.width}x${diff.comp_dimensions.height}. Images were NOT rescaled, ` +
+                    "so this result is automatically not passed; the diff covers the union region.";
+        }
+        if (warnings.length > 0) {
+            result.warnings = warnings;
+        }
+        const content = [
+            textJson(result),
+            { type: "image", data: diff.heatmap_base64, mimeType: "image/png" },
+        ];
+        return { content };
+    }
+    catch (err) {
+        return errorContent("VISUAL_DIFF_FAILED", 500, `visual_diff failed: ${err instanceof Error ? err.message : "unknown error"}`);
+    }
+}