framewatch-mcp-server 0.1.0 → 0.2.0

package/dist/utils/arabic-text.js

@@ -0,0 +1,193 @@
+import { MAX_ARABIC_INJECTION_LENGTH } from "../constants.js";
+/**
+ * Arabic stand-in text, matched to the length of what it replaces.
+ *
+ * `framewatch_rtl` can replace every visible string on a page with Arabic, so
+ * that the layout is tested against text that actually renders right-to-left
+ * rather than against English sitting inside an RTL container. English in an
+ * RTL page is a bidirectional edge case of its own and hides the ordinary
+ * bugs: the Latin run keeps its own direction, so a container that never
+ * mirrored still *looks* plausible.
+ *
+ * The length matching is the part that matters. If "Add to cart" became a
+ * three-character word, the button would shrink and any overflow the tool
+ * reported afterwards would be an artifact of the substitution rather than a
+ * property of the page — and if it became a paragraph, every page would
+ * overflow. So each replacement is built to within a few characters of the
+ * string it replaces, and the report's overflow findings mean what they say.
+ *
+ * Nothing here touches a browser: it is a string in, a string out, so every
+ * case is unit-testable without launching Chromium.
+ */
+/**
+ * The vocabulary, grouped by length so a replacement can be assembled to fit.
+ *
+ * Real words, not lorem ipsum: an Arabic reader glancing at a screenshot
+ * should see a plausible interface, and the shaping/ligature behaviour of real
+ * words is what stresses the text rendering. These are the words a UI is
+ * actually made of — actions, labels, navigation.
+ */
+const WORDS = [
+    // 2–4 characters
+    "نعم",
+    "لا",
+    "حسنا",
+    "بحث",
+    "إغلاق",
+    "حفظ",
+    "فتح",
+    "التالي",
+    "السابق",
+    "رجوع",
+    // 5–8
+    "تسجيل",
+    "الدخول",
+    "الخروج",
+    "الرئيسية",
+    "المنتجات",
+    "الخدمات",
+    "الطلبات",
+    "الحساب",
+    "الإعدادات",
+    "المفضلة",
+    // 9+
+    "أضف إلى السلة",
+    "إتمام الشراء",
+    "تواصل معنا",
+    "من نحن",
+    "الشروط والأحكام",
+    "سياسة الخصوصية",
+    "اشترك في النشرة",
+    "عرض جميع النتائج",
+];
+/** A sentence's worth, for replacing paragraphs rather than labels. */
+const SENTENCES = [
+    "مرحبا بك في متجرنا الإلكتروني",
+    "نقدم لك أفضل المنتجات بأسعار تنافسية",
+    "يمكنك تصفح الأقسام والاطلاع على العروض",
+    "خدمة التوصيل متاحة إلى جميع المناطق",
+    "فريق الدعم جاهز للإجابة عن أسئلتك",
+];
+/**
+ * Arabic-Indic digits, so a number reads as Arabic too.
+ *
+ * Kept as a separate mapping rather than being replaced by words: a price, a
+ * quantity or a date is still a number in an Arabic interface, and turning
+ * "24" into a word would change what the element is rather than what language
+ * it is in — which is the opposite of what this substitution is for.
+ */
+const ARABIC_DIGITS = ["٠", "١", "٢", "٣", "٤", "٥", "٦", "٧", "٨", "٩"];
+/**
+ * Build Arabic text about as long as `original`.
+ *
+ * `seed` makes the choice deterministic and varied: the same string in the
+ * same place gets the same replacement on every run (so two runs of the tool
+ * are comparable, and the LTR and RTL passes agree), while two different
+ * elements of the same length do not all get the same word.
+ *
+ * A string that is only digits and punctuation keeps its shape and is merely
+ * transliterated — see `ARABIC_DIGITS`.
+ */
+export function arabicFor(original, seed = 0) {
+    const source = String(original ?? "");
+    const trimmed = source.trim();
+    if (trimmed === "")
+        return source;
+    // Numbers, prices, times: keep the shape, change the digits. Replacing
+    // "١٢:٣٠" with a word would be a different element, not a translated one.
+    if (!/\p{L}/u.test(trimmed))
+        return toArabicDigits(source);
+    const target = Math.min(trimmed.length, MAX_ARABIC_INJECTION_LENGTH);
+    const built = target > 24 ? buildSentence(target, seed) : buildPhrase(target, seed);
+    // Leading/trailing whitespace is layout — a label may rely on it — so the
+    // original's edges are preserved and only the text between them replaced.
+    const leading = source.slice(0, source.length - source.trimStart().length);
+    const trailing = source.slice(source.trimEnd().length);
+    return `${leading}${built}${trailing}`;
+}
+/**
+ * Words joined until they are about `target` characters long.
+ *
+ * Each step picks the word that gets closest to the remaining space rather
+ * than taking the first candidate and giving up when it does not fit. Giving
+ * up is the trap: a 19-character string whose first word happens to be 10
+ * characters would stop there, nine short, and every button on the page would
+ * come back narrower than it really is — which is exactly the measurement
+ * error this whole module exists to avoid.
+ */
+function buildPhrase(target, seed) {
+    // A starting word no longer than the target, so a 3-character label does
+    // not become a 13-character phrase.
+    const candidates = WORDS.filter((word) => word.length <= Math.max(3, target));
+    const pool = candidates.length > 0 ? candidates : WORDS;
+    let out = pool[hash(seed) % pool.length];
+    let step = 1;
+    while (out.length < target - 1 && step <= 40) {
+        const remaining = target - out.length - 1;
+        const next = bestFit(pool, remaining, seed + step);
+        // Nothing left in the vocabulary fits the gap: stop rather than overshoot.
+        if (next === null)
+            break;
+        out = `${out} ${next}`;
+        step += 1;
+    }
+    return out;
+}
+/**
+ * The word closest to `remaining` characters without overshooting by more
+ * than a hair, chosen deterministically among equally good candidates.
+ */
+function bestFit(pool, remaining, seed) {
+    if (remaining <= 0)
+        return null;
+    // A slight overshoot is better than a large undershoot: landing two
+    // characters long is invisible, landing nine short is a different layout.
+    const fitting = pool.filter((word) => word.length <= remaining + 2);
+    if (fitting.length === 0)
+        return null;
+    let best = fitting[0].length;
+    for (const word of fitting) {
+        if (Math.abs(word.length - remaining) < Math.abs(best - remaining))
+            best = word.length;
+    }
+    const closest = fitting.filter((word) => word.length === best);
+    return closest[hash(seed) % closest.length];
+}
+/** Sentences joined until they are about `target` characters long. */
+function buildSentence(target, seed) {
+    let out = SENTENCES[hash(seed) % SENTENCES.length];
+    let step = 1;
+    while (out.length < target - 4) {
+        const next = SENTENCES[hash(seed + step) % SENTENCES.length];
+        if (out.length + 2 + next.length > target + 8) {
+            // No whole sentence fits the remainder; pad with words instead of
+            // overshooting, so a long paragraph still lands near its original length.
+            const filler = buildPhrase(target - out.length - 1, seed + step);
+            out = `${out}، ${filler}`;
+            break;
+        }
+        out = `${out}، ${next}`;
+        step += 1;
+        if (step > 40)
+            break;
+    }
+    return out;
+}
+/** Latin digits to Arabic-Indic, leaving everything else alone. */
+export function toArabicDigits(value) {
+    return String(value ?? "").replace(/[0-9]/g, (digit) => ARABIC_DIGITS[Number(digit)]);
+}
+/**
+ * A small deterministic hash.
+ *
+ * Not for security — for repeatability. `Math.random()` would make two runs of
+ * the same audit disagree about which element overflowed, which is exactly the
+ * kind of flakiness that makes a testing tool untrusted.
+ */
+function hash(seed) {
+    let value = (seed | 0) + 0x9e3779b9;
+    value = Math.imul(value ^ (value >>> 16), 0x21f0aaad);
+    value = Math.imul(value ^ (value >>> 15), 0x735a2d97);
+    return Math.abs(value ^ (value >>> 15));
+}
+//# sourceMappingURL=arabic-text.js.map

package/dist/utils/arabic-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arabic-text.js","sourceRoot":"","sources":["../../src/utils/arabic-text.ts"],"names":[],"mappings":"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","sourcesContent":["import { MAX_ARABIC_INJECTION_LENGTH } from \"../constants.js\";\n\n/**\n * Arabic stand-in text, matched to the length of what it replaces.\n *\n * `framewatch_rtl` can replace every visible string on a page with Arabic, so\n * that the layout is tested against text that actually renders right-to-left\n * rather than against English sitting inside an RTL container. English in an\n * RTL page is a bidirectional edge case of its own and hides the ordinary\n * bugs: the Latin run keeps its own direction, so a container that never\n * mirrored still *looks* plausible.\n *\n * The length matching is the part that matters. If \"Add to cart\" became a\n * three-character word, the button would shrink and any overflow the tool\n * reported afterwards would be an artifact of the substitution rather than a\n * property of the page — and if it became a paragraph, every page would\n * overflow. So each replacement is built to within a few characters of the\n * string it replaces, and the report's overflow findings mean what they say.\n *\n * Nothing here touches a browser: it is a string in, a string out, so every\n * case is unit-testable without launching Chromium.\n */\n\n/**\n * The vocabulary, grouped by length so a replacement can be assembled to fit.\n *\n * Real words, not lorem ipsum: an Arabic reader glancing at a screenshot\n * should see a plausible interface, and the shaping/ligature behaviour of real\n * words is what stresses the text rendering. These are the words a UI is\n * actually made of — actions, labels, navigation.\n */\nconst WORDS: readonly string[] = [\n  // 2–4 characters\n  \"نعم\",\n  \"لا\",\n  \"حسنا\",\n  \"بحث\",\n  \"إغلاق\",\n  \"حفظ\",\n  \"فتح\",\n  \"التالي\",\n  \"السابق\",\n  \"رجوع\",\n  // 5–8\n  \"تسجيل\",\n  \"الدخول\",\n  \"الخروج\",\n  \"الرئيسية\",\n  \"المنتجات\",\n  \"الخدمات\",\n  \"الطلبات\",\n  \"الحساب\",\n  \"الإعدادات\",\n  \"المفضلة\",\n  // 9+\n  \"أضف إلى السلة\",\n  \"إتمام الشراء\",\n  \"تواصل معنا\",\n  \"من نحن\",\n  \"الشروط والأحكام\",\n  \"سياسة الخصوصية\",\n  \"اشترك في النشرة\",\n  \"عرض جميع النتائج\",\n];\n\n/** A sentence's worth, for replacing paragraphs rather than labels. */\nconst SENTENCES: readonly string[] = [\n  \"مرحبا بك في متجرنا الإلكتروني\",\n  \"نقدم لك أفضل المنتجات بأسعار تنافسية\",\n  \"يمكنك تصفح الأقسام والاطلاع على العروض\",\n  \"خدمة التوصيل متاحة إلى جميع المناطق\",\n  \"فريق الدعم جاهز للإجابة عن أسئلتك\",\n];\n\n/**\n * Arabic-Indic digits, so a number reads as Arabic too.\n *\n * Kept as a separate mapping rather than being replaced by words: a price, a\n * quantity or a date is still a number in an Arabic interface, and turning\n * \"24\" into a word would change what the element is rather than what language\n * it is in — which is the opposite of what this substitution is for.\n */\nconst ARABIC_DIGITS = [\"٠\", \"١\", \"٢\", \"٣\", \"٤\", \"٥\", \"٦\", \"٧\", \"٨\", \"٩\"] as const;\n\n/**\n * Build Arabic text about as long as `original`.\n *\n * `seed` makes the choice deterministic and varied: the same string in the\n * same place gets the same replacement on every run (so two runs of the tool\n * are comparable, and the LTR and RTL passes agree), while two different\n * elements of the same length do not all get the same word.\n *\n * A string that is only digits and punctuation keeps its shape and is merely\n * transliterated — see `ARABIC_DIGITS`.\n */\nexport function arabicFor(original: string, seed = 0): string {\n  const source = String(original ?? \"\");\n  const trimmed = source.trim();\n  if (trimmed === \"\") return source;\n\n  // Numbers, prices, times: keep the shape, change the digits. Replacing\n  // \"١٢:٣٠\" with a word would be a different element, not a translated one.\n  if (!/\\p{L}/u.test(trimmed)) return toArabicDigits(source);\n\n  const target = Math.min(trimmed.length, MAX_ARABIC_INJECTION_LENGTH);\n  const built = target > 24 ? buildSentence(target, seed) : buildPhrase(target, seed);\n\n  // Leading/trailing whitespace is layout — a label may rely on it — so the\n  // original's edges are preserved and only the text between them replaced.\n  const leading = source.slice(0, source.length - source.trimStart().length);\n  const trailing = source.slice(source.trimEnd().length);\n  return `${leading}${built}${trailing}`;\n}\n\n/**\n * Words joined until they are about `target` characters long.\n *\n * Each step picks the word that gets closest to the remaining space rather\n * than taking the first candidate and giving up when it does not fit. Giving\n * up is the trap: a 19-character string whose first word happens to be 10\n * characters would stop there, nine short, and every button on the page would\n * come back narrower than it really is — which is exactly the measurement\n * error this whole module exists to avoid.\n */\nfunction buildPhrase(target: number, seed: number): string {\n  // A starting word no longer than the target, so a 3-character label does\n  // not become a 13-character phrase.\n  const candidates = WORDS.filter((word) => word.length <= Math.max(3, target));\n  const pool = candidates.length > 0 ? candidates : WORDS;\n\n  let out = pool[hash(seed) % pool.length];\n  let step = 1;\n  while (out.length < target - 1 && step <= 40) {\n    const remaining = target - out.length - 1;\n    const next = bestFit(pool, remaining, seed + step);\n    // Nothing left in the vocabulary fits the gap: stop rather than overshoot.\n    if (next === null) break;\n    out = `${out} ${next}`;\n    step += 1;\n  }\n  return out;\n}\n\n/**\n * The word closest to `remaining` characters without overshooting by more\n * than a hair, chosen deterministically among equally good candidates.\n */\nfunction bestFit(pool: readonly string[], remaining: number, seed: number): string | null {\n  if (remaining <= 0) return null;\n  // A slight overshoot is better than a large undershoot: landing two\n  // characters long is invisible, landing nine short is a different layout.\n  const fitting = pool.filter((word) => word.length <= remaining + 2);\n  if (fitting.length === 0) return null;\n\n  let best = fitting[0].length;\n  for (const word of fitting) {\n    if (Math.abs(word.length - remaining) < Math.abs(best - remaining)) best = word.length;\n  }\n  const closest = fitting.filter((word) => word.length === best);\n  return closest[hash(seed) % closest.length];\n}\n\n/** Sentences joined until they are about `target` characters long. */\nfunction buildSentence(target: number, seed: number): string {\n  let out = SENTENCES[hash(seed) % SENTENCES.length];\n  let step = 1;\n  while (out.length < target - 4) {\n    const next = SENTENCES[hash(seed + step) % SENTENCES.length];\n    if (out.length + 2 + next.length > target + 8) {\n      // No whole sentence fits the remainder; pad with words instead of\n      // overshooting, so a long paragraph still lands near its original length.\n      const filler = buildPhrase(target - out.length - 1, seed + step);\n      out = `${out}، ${filler}`;\n      break;\n    }\n    out = `${out}، ${next}`;\n    step += 1;\n    if (step > 40) break;\n  }\n  return out;\n}\n\n/** Latin digits to Arabic-Indic, leaving everything else alone. */\nexport function toArabicDigits(value: string): string {\n  return String(value ?? \"\").replace(/[0-9]/g, (digit) => ARABIC_DIGITS[Number(digit)]);\n}\n\n/**\n * A small deterministic hash.\n *\n * Not for security — for repeatability. `Math.random()` would make two runs of\n * the same audit disagree about which element overflowed, which is exactly the\n * kind of flakiness that makes a testing tool untrusted.\n */\nfunction hash(seed: number): number {\n  let value = (seed | 0) + 0x9e3779b9;\n  value = Math.imul(value ^ (value >>> 16), 0x21f0aaad);\n  value = Math.imul(value ^ (value >>> 15), 0x735a2d97);\n  return Math.abs(value ^ (value >>> 15));\n}\n"]}

package/dist/utils/budget.d.ts

@@ -0,0 +1,41 @@
+import type { CallToolResult, ImageContent } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * The image budget.
+ *
+ * Claude Code caps one MCP tool result at `MAX_MCP_OUTPUT_TOKENS` (25,000 by
+ * default) and counts base64 image data toward it. A result over the cap is
+ * written to a file and replaced with a reference, so the model sees no
+ * images at all — and a single screenshot of a real page is 180 KB of PNG,
+ * which is over on its own. Every result therefore passes through here on
+ * its way out: each image is encoded the cheapest way that is still faithful,
+ * and if the result still does not fit it is degraded in a fixed order —
+ * crops first, then frame size, then frames from the middle — and says so.
+ * Fewer images that arrive beat all of them lost.
+ */
+export interface ImageMark {
+    /** A `crop` duplicates part of a frame and is the first thing to go. */
+    role?: "frame" | "crop";
+    /** Never dropped while any unmarked frame remains (first/last/interaction frames). */
+    keep?: boolean;
+}
+/** Stamp an image block with its role, for `fitToBudget` to read (and strip). */
+export declare function markImage(block: ImageContent, mark: ImageMark): ImageContent;
+/** The cap in force: what the shell that started Claude Code exported, or the default. */
+export declare function capFromEnv(env?: NodeJS.ProcessEnv): number;
+/** Base64 characters of image data a result may carry once its text is paid for. */
+export declare function imageBudgetChars(capTokens: number, textChars: number): number;
+export interface BudgetStats {
+    total: number;
+    kept: number;
+    crops_dropped: number;
+    frames_dropped: number;
+    /** Width the surviving frames were shrunk to, or undefined when untouched. */
+    width?: number;
+    cap_tokens: number;
+}
+export declare function describeBudget(stats: BudgetStats): string;
+export interface FitOptions {
+    /** Override the cap (tests); defaults to `capFromEnv()`. */
+    cap_tokens?: number;
+}
+export declare function fitToBudget(result: CallToolResult, options?: FitOptions): Promise<CallToolResult>;

package/dist/utils/budget.js

@@ -0,0 +1,182 @@
+import sharp from "sharp";
+import { BUDGET_CHARS_PER_TOKEN, BUDGET_JPEG_QUALITY, BUDGET_LAST_RESORT_WIDTHS, BUDGET_MARGIN_TOKENS, BUDGET_SUGGESTED_TOKENS, BUDGET_WIDTHS, DEFAULT_MCP_OUTPUT_TOKENS, } from "../constants.js";
+const META_KEY = "framewatch";
+/** Stamp an image block with its role, for `fitToBudget` to read (and strip). */
+export function markImage(block, mark) {
+    return { ...block, _meta: { ...(block._meta ?? {}), [META_KEY]: mark } };
+}
+/** The cap in force: what the shell that started Claude Code exported, or the default. */
+export function capFromEnv(env = process.env) {
+    const raw = Number(env.MAX_MCP_OUTPUT_TOKENS);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MCP_OUTPUT_TOKENS;
+}
+/** Base64 characters of image data a result may carry once its text is paid for. */
+export function imageBudgetChars(capTokens, textChars) {
+    const textTokens = Math.ceil(textChars / BUDGET_CHARS_PER_TOKEN);
+    return Math.max(0, (capTokens - textTokens - BUDGET_MARGIN_TOKENS) * BUDGET_CHARS_PER_TOKEN);
+}
+export function describeBudget(stats) {
+    const cuts = [];
+    if (stats.crops_dropped > 0)
+        cuts.push(`${stats.crops_dropped} crop${stats.crops_dropped === 1 ? "" : "s"} dropped`);
+    if (stats.frames_dropped > 0)
+        cuts.push(`${stats.frames_dropped} frame${stats.frames_dropped === 1 ? "" : "s"} dropped`);
+    if (stats.width !== undefined)
+        cuts.push(`frames at ${stats.width}px`);
+    const kb = Math.round((imageBudgetChars(stats.cap_tokens, 0) * 0.75) / 1024);
+    return (`Image budget: ${stats.kept} of ${stats.total} images kept — ${cuts.join(", ")} — to fit MAX_MCP_OUTPUT_TOKENS=${stats.cap_tokens} ` +
+        `(~${kb} KB of images per result). Set MAX_MCP_OUTPUT_TOKENS=${BUDGET_SUGGESTED_TOKENS} in the shell that starts Claude Code for full results.`);
+}
+const OMITTED = "(image omitted — see the Image budget line)";
+export async function fitToBudget(result, options = {}) {
+    const content = result.content;
+    const slots = [];
+    for (let i = 0; i < content.length; i++) {
+        const block = content[i];
+        if (block.type !== "image")
+            continue;
+        const mark = ((block._meta ?? {})[META_KEY] ?? {});
+        const source = Buffer.from(block.data, "base64");
+        let width = 0;
+        try {
+            width = (await sharp(source).metadata()).width ?? 0;
+        }
+        catch {
+            // Not an image sharp can read: leave the block exactly as it is.
+            continue;
+        }
+        slots.push({
+            index: i,
+            original: { data: block.data, mimeType: block.mimeType },
+            role: mark.role === "crop" ? "crop" : "frame",
+            keep: mark.keep === true,
+            source,
+            width,
+            encoded: new Map(),
+            dropped: false,
+            at: width,
+        });
+    }
+    if (slots.length === 0)
+        return result;
+    const cap = options.cap_tokens ?? capFromEnv();
+    const textChars = content.reduce((n, c) => (c.type === "text" ? n + c.text.length : n), 0);
+    // Leave room for the note this may have to add.
+    const budget = imageBudgetChars(cap, textChars + 400);
+    const encode = async (slot, width) => {
+        const target = Math.min(width, slot.width);
+        const cached = slot.encoded.get(target);
+        if (cached)
+            return cached;
+        let image = sharp(slot.source);
+        if (target < slot.width)
+            image = image.resize(target, null, { fit: "inside", withoutEnlargement: true });
+        const [png, jpeg] = await Promise.all([
+            image.clone().png({ quality: 80, effort: 1, compressionLevel: 6 }).toBuffer(),
+            image.clone().jpeg({ quality: BUDGET_JPEG_QUALITY, mozjpeg: true }).toBuffer(),
+        ]);
+        let best = jpeg.length < png.length
+            ? { data: jpeg.toString("base64"), mimeType: "image/jpeg" }
+            : { data: png.toString("base64"), mimeType: "image/png" };
+        // At its own size, what the tool produced is a candidate too — and when
+        // it is already the smallest, it goes out untouched.
+        if (target === slot.width && slot.original.data.length <= best.data.length)
+            best = slot.original;
+        slot.encoded.set(target, best);
+        return best;
+    };
+    const total = async () => {
+        let sum = 0;
+        for (const slot of slots) {
+            if (slot.dropped)
+                continue;
+            sum += (await encode(slot, slot.at)).data.length;
+        }
+        return sum;
+    };
+    const fits = async () => (await total()) <= budget;
+    let cropsDropped = 0;
+    let framesDropped = 0;
+    let width;
+    if (!(await fits())) {
+        // 1. Crops duplicate what a frame already shows.
+        for (const slot of slots) {
+            if (slot.role === "crop" && !slot.dropped) {
+                slot.dropped = true;
+                cropsDropped++;
+            }
+        }
+    }
+    // 2. Smaller frames, all of them together, so they still compare.
+    for (const step of BUDGET_WIDTHS) {
+        if (await fits())
+            break;
+        for (const slot of slots)
+            if (!slot.dropped)
+                slot.at = Math.min(slot.at, step);
+        width = step;
+    }
+    // 3. Frames from the middle outwards: unprotected first, then protected,
+    //    never the last one standing.
+    if (!(await fits())) {
+        const live = () => slots.filter((s) => !s.dropped);
+        const order = (protectedToo) => {
+            const alive = live();
+            const first = alive[0];
+            const last = alive[alive.length - 1];
+            const candidates = alive.filter((s) => s !== first && s !== last && (protectedToo || !s.keep));
+            // Middle outwards: sort by distance from the centre, farthest last.
+            const centre = (alive.length - 1) / 2;
+            return candidates.sort((a, b) => Math.abs(alive.indexOf(a) - centre) - Math.abs(alive.indexOf(b) - centre));
+        };
+        for (const protectedToo of [false, true]) {
+            for (const slot of order(protectedToo)) {
+                if (await fits())
+                    break;
+                slot.dropped = true;
+                framesDropped++;
+            }
+        }
+        // Down to the first and the last; then the first goes too.
+        while (!(await fits()) && live().length > 1) {
+            live()[0].dropped = true;
+            framesDropped++;
+        }
+    }
+    // 4. One image left and still over: shrink it as far as it takes.
+    for (const step of BUDGET_LAST_RESORT_WIDTHS) {
+        if (await fits())
+            break;
+        for (const slot of slots)
+            if (!slot.dropped)
+                slot.at = Math.min(slot.at, step);
+        width = step;
+    }
+    const degraded = cropsDropped > 0 || framesDropped > 0 || width !== undefined;
+    const out = [];
+    for (let i = 0; i < content.length; i++) {
+        const slot = slots.find((s) => s.index === i);
+        if (!slot) {
+            out.push(content[i]);
+            continue;
+        }
+        if (slot.dropped) {
+            out.push({ type: "text", text: OMITTED });
+            continue;
+        }
+        const best = await encode(slot, slot.at);
+        const block = content[i];
+        const { _meta, ...rest } = block;
+        const meta = _meta ? Object.fromEntries(Object.entries(_meta).filter(([key]) => key !== META_KEY)) : undefined;
+        out.push({ ...rest, data: best.data, mimeType: best.mimeType, ...(meta && Object.keys(meta).length > 0 ? { _meta: meta } : {}) });
+    }
+    if (degraded) {
+        const kept = slots.filter((s) => !s.dropped).length;
+        out.push({
+            type: "text",
+            text: describeBudget({ total: slots.length, kept, crops_dropped: cropsDropped, frames_dropped: framesDropped, width, cap_tokens: cap }),
+        });
+    }
+    return { ...result, content: out };
+}
+//# sourceMappingURL=budget.js.map

package/dist/utils/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/utils/budget.ts"],"names":[],"mappings":"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","sourcesContent":["import sharp from \"sharp\";\nimport type { CallToolResult, ImageContent } from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  BUDGET_CHARS_PER_TOKEN,\n  BUDGET_JPEG_QUALITY,\n  BUDGET_LAST_RESORT_WIDTHS,\n  BUDGET_MARGIN_TOKENS,\n  BUDGET_SUGGESTED_TOKENS,\n  BUDGET_WIDTHS,\n  DEFAULT_MCP_OUTPUT_TOKENS,\n} from \"../constants.js\";\n\n/**\n * The image budget.\n *\n * Claude Code caps one MCP tool result at `MAX_MCP_OUTPUT_TOKENS` (25,000 by\n * default) and counts base64 image data toward it. A result over the cap is\n * written to a file and replaced with a reference, so the model sees no\n * images at all — and a single screenshot of a real page is 180 KB of PNG,\n * which is over on its own. Every result therefore passes through here on\n * its way out: each image is encoded the cheapest way that is still faithful,\n * and if the result still does not fit it is degraded in a fixed order —\n * crops first, then frame size, then frames from the middle — and says so.\n * Fewer images that arrive beat all of them lost.\n */\n\nexport interface ImageMark {\n  /** A `crop` duplicates part of a frame and is the first thing to go. */\n  role?: \"frame\" | \"crop\";\n  /** Never dropped while any unmarked frame remains (first/last/interaction frames). */\n  keep?: boolean;\n}\n\nconst META_KEY = \"framewatch\";\n\n/** Stamp an image block with its role, for `fitToBudget` to read (and strip). */\nexport function markImage(block: ImageContent, mark: ImageMark): ImageContent {\n  return { ...block, _meta: { ...(block._meta ?? {}), [META_KEY]: mark } };\n}\n\n/** The cap in force: what the shell that started Claude Code exported, or the default. */\nexport function capFromEnv(env: NodeJS.ProcessEnv = process.env): number {\n  const raw = Number(env.MAX_MCP_OUTPUT_TOKENS);\n  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MCP_OUTPUT_TOKENS;\n}\n\n/** Base64 characters of image data a result may carry once its text is paid for. */\nexport function imageBudgetChars(capTokens: number, textChars: number): number {\n  const textTokens = Math.ceil(textChars / BUDGET_CHARS_PER_TOKEN);\n  return Math.max(0, (capTokens - textTokens - BUDGET_MARGIN_TOKENS) * BUDGET_CHARS_PER_TOKEN);\n}\n\nexport interface BudgetStats {\n  total: number;\n  kept: number;\n  crops_dropped: number;\n  frames_dropped: number;\n  /** Width the surviving frames were shrunk to, or undefined when untouched. */\n  width?: number;\n  cap_tokens: number;\n}\n\nexport function describeBudget(stats: BudgetStats): string {\n  const cuts: string[] = [];\n  if (stats.crops_dropped > 0) cuts.push(`${stats.crops_dropped} crop${stats.crops_dropped === 1 ? \"\" : \"s\"} dropped`);\n  if (stats.frames_dropped > 0) cuts.push(`${stats.frames_dropped} frame${stats.frames_dropped === 1 ? \"\" : \"s\"} dropped`);\n  if (stats.width !== undefined) cuts.push(`frames at ${stats.width}px`);\n  const kb = Math.round((imageBudgetChars(stats.cap_tokens, 0) * 0.75) / 1024);\n  return (\n    `Image budget: ${stats.kept} of ${stats.total} images kept — ${cuts.join(\", \")} — to fit MAX_MCP_OUTPUT_TOKENS=${stats.cap_tokens} ` +\n    `(~${kb} KB of images per result). Set MAX_MCP_OUTPUT_TOKENS=${BUDGET_SUGGESTED_TOKENS} in the shell that starts Claude Code for full results.`\n  );\n}\n\nexport interface FitOptions {\n  /** Override the cap (tests); defaults to `capFromEnv()`. */\n  cap_tokens?: number;\n}\n\ninterface Candidate {\n  data: string;\n  mimeType: string;\n}\n\ninterface Slot {\n  /** Index into `result.content`. */\n  index: number;\n  /** The block as the tool produced it — kept verbatim when nothing beats it. */\n  original: Candidate;\n  role: \"frame\" | \"crop\";\n  keep: boolean;\n  source: Buffer;\n  width: number;\n  /** Encodings by width, filled lazily. */\n  encoded: Map<number, Candidate>;\n  dropped: boolean;\n  /** Width in force for this slot (its own width when untouched). */\n  at: number;\n}\n\nconst OMITTED = \"(image omitted — see the Image budget line)\";\n\nexport async function fitToBudget(result: CallToolResult, options: FitOptions = {}): Promise<CallToolResult> {\n  const content = result.content;\n  const slots: Slot[] = [];\n  for (let i = 0; i < content.length; i++) {\n    const block = content[i];\n    if (block.type !== \"image\") continue;\n    const mark = ((block._meta ?? {})[META_KEY] ?? {}) as ImageMark;\n    const source = Buffer.from(block.data, \"base64\");\n    let width = 0;\n    try {\n      width = (await sharp(source).metadata()).width ?? 0;\n    } catch {\n      // Not an image sharp can read: leave the block exactly as it is.\n      continue;\n    }\n    slots.push({\n      index: i,\n      original: { data: block.data, mimeType: block.mimeType },\n      role: mark.role === \"crop\" ? \"crop\" : \"frame\",\n      keep: mark.keep === true,\n      source,\n      width,\n      encoded: new Map(),\n      dropped: false,\n      at: width,\n    });\n  }\n  if (slots.length === 0) return result;\n\n  const cap = options.cap_tokens ?? capFromEnv();\n  const textChars = content.reduce((n, c) => (c.type === \"text\" ? n + c.text.length : n), 0);\n  // Leave room for the note this may have to add.\n  const budget = imageBudgetChars(cap, textChars + 400);\n\n  const encode = async (slot: Slot, width: number): Promise<Candidate> => {\n    const target = Math.min(width, slot.width);\n    const cached = slot.encoded.get(target);\n    if (cached) return cached;\n    let image = sharp(slot.source);\n    if (target < slot.width) image = image.resize(target, null, { fit: \"inside\", withoutEnlargement: true });\n    const [png, jpeg] = await Promise.all([\n      image.clone().png({ quality: 80, effort: 1, compressionLevel: 6 }).toBuffer(),\n      image.clone().jpeg({ quality: BUDGET_JPEG_QUALITY, mozjpeg: true }).toBuffer(),\n    ]);\n    let best: Candidate =\n      jpeg.length < png.length\n        ? { data: jpeg.toString(\"base64\"), mimeType: \"image/jpeg\" }\n        : { data: png.toString(\"base64\"), mimeType: \"image/png\" };\n    // At its own size, what the tool produced is a candidate too — and when\n    // it is already the smallest, it goes out untouched.\n    if (target === slot.width && slot.original.data.length <= best.data.length) best = slot.original;\n    slot.encoded.set(target, best);\n    return best;\n  };\n  const total = async (): Promise<number> => {\n    let sum = 0;\n    for (const slot of slots) {\n      if (slot.dropped) continue;\n      sum += (await encode(slot, slot.at)).data.length;\n    }\n    return sum;\n  };\n  const fits = async (): Promise<boolean> => (await total()) <= budget;\n\n  let cropsDropped = 0;\n  let framesDropped = 0;\n  let width: number | undefined;\n\n  if (!(await fits())) {\n    // 1. Crops duplicate what a frame already shows.\n    for (const slot of slots) {\n      if (slot.role === \"crop\" && !slot.dropped) {\n        slot.dropped = true;\n        cropsDropped++;\n      }\n    }\n  }\n  // 2. Smaller frames, all of them together, so they still compare.\n  for (const step of BUDGET_WIDTHS) {\n    if (await fits()) break;\n    for (const slot of slots) if (!slot.dropped) slot.at = Math.min(slot.at, step);\n    width = step;\n  }\n  // 3. Frames from the middle outwards: unprotected first, then protected,\n  //    never the last one standing.\n  if (!(await fits())) {\n    const live = () => slots.filter((s) => !s.dropped);\n    const order = (protectedToo: boolean): Slot[] => {\n      const alive = live();\n      const first = alive[0];\n      const last = alive[alive.length - 1];\n      const candidates = alive.filter((s) => s !== first && s !== last && (protectedToo || !s.keep));\n      // Middle outwards: sort by distance from the centre, farthest last.\n      const centre = (alive.length - 1) / 2;\n      return candidates.sort((a, b) => Math.abs(alive.indexOf(a) - centre) - Math.abs(alive.indexOf(b) - centre));\n    };\n    for (const protectedToo of [false, true]) {\n      for (const slot of order(protectedToo)) {\n        if (await fits()) break;\n        slot.dropped = true;\n        framesDropped++;\n      }\n    }\n    // Down to the first and the last; then the first goes too.\n    while (!(await fits()) && live().length > 1) {\n      live()[0].dropped = true;\n      framesDropped++;\n    }\n  }\n  // 4. One image left and still over: shrink it as far as it takes.\n  for (const step of BUDGET_LAST_RESORT_WIDTHS) {\n    if (await fits()) break;\n    for (const slot of slots) if (!slot.dropped) slot.at = Math.min(slot.at, step);\n    width = step;\n  }\n\n  const degraded = cropsDropped > 0 || framesDropped > 0 || width !== undefined;\n  const out: CallToolResult[\"content\"] = [];\n  for (let i = 0; i < content.length; i++) {\n    const slot = slots.find((s) => s.index === i);\n    if (!slot) {\n      out.push(content[i]);\n      continue;\n    }\n    if (slot.dropped) {\n      out.push({ type: \"text\", text: OMITTED });\n      continue;\n    }\n    const best = await encode(slot, slot.at);\n    const block = content[i] as ImageContent;\n    const { _meta, ...rest } = block;\n    const meta = _meta ? Object.fromEntries(Object.entries(_meta).filter(([key]) => key !== META_KEY)) : undefined;\n    out.push({ ...rest, data: best.data, mimeType: best.mimeType, ...(meta && Object.keys(meta).length > 0 ? { _meta: meta } : {}) });\n  }\n  if (degraded) {\n    const kept = slots.filter((s) => !s.dropped).length;\n    out.push({\n      type: \"text\",\n      text: describeBudget({ total: slots.length, kept, crops_dropped: cropsDropped, frames_dropped: framesDropped, width, cap_tokens: cap }),\n    });\n  }\n  return { ...result, content: out };\n}\n"]}

package/dist/utils/format.d.ts

@@ -1,5 +1,13 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { DiffCard } from "../types.js";
+import type { DiffCard, Viewport } from "../types.js";
+/**
+ * How the images relate to the page. Frames are shrunk to OUTPUT_MAX_WIDTH,
+ * but every coordinate a tool prints — change regions, boxes, click points —
+ * is in viewport pixels. A reader who measures a position off the image and
+ * clicks there lands 1.6× off on the default viewport, so every tool that
+ * returns frames says which it is.
+ */
+export declare function describeScale(viewport: Viewport): string;
 /** What became of a replayed interaction script. */
 export interface InteractionReport {
     /** Steps in the script. */
@@ -27,6 +35,8 @@ export interface CaptureSummary {
     dropped?: number;
     /** Present only when an interaction script was replayed. */
     interactions?: InteractionReport;
+    /** The viewport the frames were taken at; adds the image-scale line when known. */
+    viewport?: Viewport;
     /**
      * Remarks about the capture itself rather than about any one frame — a
      * context layer that hit its cap, requests still in flight when the

package/dist/utils/format.js

@@ -1,3 +1,19 @@
+import { OUTPUT_MAX_WIDTH } from "../constants.js";
+import { markImage } from "./budget.js";
+/**
+ * How the images relate to the page. Frames are shrunk to OUTPUT_MAX_WIDTH,
+ * but every coordinate a tool prints — change regions, boxes, click points —
+ * is in viewport pixels. A reader who measures a position off the image and
+ * clicks there lands 1.6× off on the default viewport, so every tool that
+ * returns frames says which it is.
+ */
+export function describeScale(viewport) {
+    const base = `viewport ${viewport.width}x${viewport.height}`;
+    if (viewport.width <= OUTPUT_MAX_WIDTH)
+        return `${base}, images at full size`;
+    const factor = (OUTPUT_MAX_WIDTH / viewport.width).toFixed(2);
+    return `${base}, images ${OUTPUT_MAX_WIDTH}px wide (${factor}×) — coordinates and regions are in viewport px`;
+}
 /**
  * Build the MCP CallToolResult for a capture, following the "MCP Response
  * Format" in CLAUDE.md: one summary text block, then per card an image block,
@@ -5,6 +21,10 @@
  */
 export function formatDiffCards(summary) {
     const lines = [formatSummaryLine(summary)];
+    if (summary.viewport) {
+        const scale = describeScale(summary.viewport);
+        lines.push(scale.charAt(0).toUpperCase() + scale.slice(1));
+    }
     if (summary.interactions) {
         lines.push(formatInteractionLine(summary.interactions));
     }
@@ -12,13 +32,16 @@ export function formatDiffCards(summary) {
         lines.push(note);
     }
     const content = [{ type: "text", text: lines.join("\n") }];
-    for (const card of summary.cards) {
-        content.push({ type: "image", data: card.full_frame, mimeType: "image/png" });
+    const last = summary.cards.length - 1;
+    summary.cards.forEach((card, i) => {
+        // First, last and event frames survive the image budget longest; crops go first.
+        const keep = i === 0 || i === last || card.trigger !== "animation";
+        content.push(markImage({ type: "image", data: card.full_frame, mimeType: "image/png" }, { role: "frame", keep }));
         content.push({ type: "text", text: formatCardMeta(card) });
         if (card.change_region?.crop) {
-            content.push({ type: "image", data: card.change_region.crop, mimeType: "image/png" });
+            content.push(markImage({ type: "image", data: card.change_region.crop, mimeType: "image/png" }, { role: "crop" }));
         }
-    }
+    });
     return { content };
 }
 /**

package/dist/utils/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport type { DiffCard } from \"../types.js\";\n\n/** What became of a replayed interaction script. */\nexport interface InteractionReport {\n  /** Steps in the script. */\n  total: number;\n  /** Steps that ran successfully. */\n  completed: number;\n  /** One-line description of each completed step, in order. */\n  steps: string[];\n  /** Message from the step that failed, if any (already a single line). */\n  error?: string;\n  /** 1-based position of the failing step. */\n  failed_index?: number;\n}\n\n/** Everything the formatter needs to describe one capture session. */\nexport interface CaptureSummary {\n  cards: DiffCard[];\n  total_frames: number;\n  duration_ms: number;\n  /** URL that was requested. */\n  url: string;\n  /** URL the page ended on (after redirects / in-page navigation). */\n  final_url?: string;\n  title?: string;\n  /** Frames dropped by the recorder (screenshot failures). */\n  dropped?: number;\n  /** Present only when an interaction script was replayed. */\n  interactions?: InteractionReport;\n  /**\n   * Remarks about the capture itself rather than about any one frame — a\n   * context layer that hit its cap, requests still in flight when the\n   * recording ended. One line each, after the summary.\n   */\n  notes?: string[];\n}\n\n/**\n * Build the MCP CallToolResult for a capture, following the \"MCP Response\n * Format\" in CLAUDE.md: one summary text block, then per card an image block,\n * a metadata text block and (when present) the change-region crop image.\n */\nexport function formatDiffCards(summary: CaptureSummary): CallToolResult {\n  const lines = [formatSummaryLine(summary)];\n  if (summary.interactions) {\n    lines.push(formatInteractionLine(summary.interactions));\n  }\n  for (const note of summary.notes ?? []) {\n    lines.push(note);\n  }\n  const content: CallToolResult[\"content\"] = [{ type: \"text\", text: lines.join(\"\\n\") }];\n  for (const card of summary.cards) {\n    content.push({ type: \"image\", data: card.full_frame, mimeType: \"image/png\" });\n    content.push({ type: \"text\", text: formatCardMeta(card) });\n    if (card.change_region?.crop) {\n      content.push({ type: \"image\", data: card.change_region.crop, mimeType: \"image/png\" });\n    }\n  }\n  return { content };\n}\n\n/**\n * One-line description of the whole capture. Always names the requested url;\n * appends the final url only when the page ended somewhere else, the page\n * title when known, and the dropped-frame count only when frames were lost.\n */\nfunction formatSummaryLine(summary: CaptureSummary): string {\n  const { cards, total_frames, duration_ms, url, final_url, title, dropped } = summary;\n  const recording = `from ${total_frames} raw frames (${duration_ms}ms recording) of ${url}`;\n  let text = cards.length === 0 ? `No frames captured ${recording}` : `Captured ${cards.length} meaningful frames ${recording}`;\n  if (final_url !== undefined && !isSameUrl(url, final_url)) {\n    text += ` → ${final_url}`;\n  }\n  if (title) {\n    text += ` — \"${title}\"`;\n  }\n  if (dropped !== undefined && dropped > 0) {\n    text += ` (${dropped} frames dropped)`;\n  }\n  return text;\n}\n\n/**\n * How the interaction script went: how many steps ran, what they were, and —\n * when one failed — which one and why. A failed step is a finding about the\n * page, not a tool failure, so it is reported here alongside the frames rather\n * than replacing them with an error.\n */\nexport function formatInteractionLine(report: InteractionReport): string {\n  let text = `Interactions: ${report.completed}/${report.total} replayed`;\n  if (report.steps.length > 0) {\n    text += ` — ${report.steps.join(\", \")}`;\n  }\n  if (report.error !== undefined) {\n    text += `. Step ${report.failed_index ?? report.completed + 1}: ${report.error}`;\n  }\n  return text;\n}\n\n/**\n * Compare two URLs as URLs, not as strings: `page.url()` returns the\n * WHATWG-normalised form, so a request for `http://localhost:3000` comes back\n * as `http://localhost:3000/` without anything having navigated.\n */\nfunction isSameUrl(a: string, b: string): boolean {\n  if (a === b) return true;\n  try {\n    return new URL(a).href === new URL(b).href;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * The metadata text block for one card (exported for tests and for reuse by\n * the interact tool). Line 1 is always `Frame N @ Tms [trigger]`; the\n * optional sections follow in a fixed order — Changed, Console, Network,\n * Performance, DOM — and are omitted entirely when their data is absent.\n */\nexport function formatCardMeta(card: DiffCard): string {\n  const lines: string[] = [`Frame ${card.index} @ ${card.timestamp_ms}ms [${card.trigger}]`];\n\n  const region = card.change_region;\n  if (region) {\n    if (region.change_percent === 0) {\n      lines.push(\"Changed: 0.0% — no visual change since previous frame\");\n    } else {\n      const { bbox } = region;\n      let changed = `Changed: ${region.change_percent.toFixed(1)}% — region: ${bbox.x},${bbox.y} ${bbox.width}x${bbox.height}`;\n      if (!region.crop) {\n        changed += \" (full-frame change, see frame image)\";\n      }\n      lines.push(changed);\n    }\n  }\n\n  if (card.console_entries?.length) {\n    lines.push(\"Console:\");\n    for (const entry of card.console_entries) {\n      lines.push(`  [${entry.level}] ${entry.text}`);\n    }\n  }\n\n  if (card.network_events?.length) {\n    lines.push(\"Network:\");\n    for (const event of card.network_events) {\n      // A request that never got a response has no status to print; what\n      // stopped it (or that it is still running) is the useful part.\n      const outcome = event.status > 0 ? String(event.status) : (event.error ?? \"no response\");\n      const why = event.status > 0 && event.error !== undefined ? ` ${event.error}` : \"\";\n      lines.push(`  ${event.method} ${event.url} → ${outcome}${why} (${event.duration_ms}ms)`);\n    }\n  }\n\n  const perf = card.performance;\n  if (perf) {\n    lines.push(\"Performance:\");\n    if (perf.paint_time_ms !== undefined) lines.push(`  paint ${perf.paint_time_ms}ms`);\n    if (perf.layout_shifts !== undefined) {\n      const score = perf.layout_shift_score !== undefined ? ` (score ${perf.layout_shift_score})` : \"\";\n      lines.push(`  layout shifts ${perf.layout_shifts}${score}`);\n    }\n    if (perf.lcp_ms !== undefined) lines.push(`  lcp ${perf.lcp_ms}ms`);\n  }\n\n  if (card.dom_snapshot) {\n    lines.push(`DOM:\\n${card.dom_snapshot}`);\n  }\n\n  return lines.join(\"\\n\");\n}\n"]}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport { OUTPUT_MAX_WIDTH } from \"../constants.js\";\nimport { markImage } from \"./budget.js\";\nimport type { DiffCard, Viewport } from \"../types.js\";\n\n/**\n * How the images relate to the page. Frames are shrunk to OUTPUT_MAX_WIDTH,\n * but every coordinate a tool prints — change regions, boxes, click points —\n * is in viewport pixels. A reader who measures a position off the image and\n * clicks there lands 1.6× off on the default viewport, so every tool that\n * returns frames says which it is.\n */\nexport function describeScale(viewport: Viewport): string {\n  const base = `viewport ${viewport.width}x${viewport.height}`;\n  if (viewport.width <= OUTPUT_MAX_WIDTH) return `${base}, images at full size`;\n  const factor = (OUTPUT_MAX_WIDTH / viewport.width).toFixed(2);\n  return `${base}, images ${OUTPUT_MAX_WIDTH}px wide (${factor}×) — coordinates and regions are in viewport px`;\n}\n\n/** What became of a replayed interaction script. */\nexport interface InteractionReport {\n  /** Steps in the script. */\n  total: number;\n  /** Steps that ran successfully. */\n  completed: number;\n  /** One-line description of each completed step, in order. */\n  steps: string[];\n  /** Message from the step that failed, if any (already a single line). */\n  error?: string;\n  /** 1-based position of the failing step. */\n  failed_index?: number;\n}\n\n/** Everything the formatter needs to describe one capture session. */\nexport interface CaptureSummary {\n  cards: DiffCard[];\n  total_frames: number;\n  duration_ms: number;\n  /** URL that was requested. */\n  url: string;\n  /** URL the page ended on (after redirects / in-page navigation). */\n  final_url?: string;\n  title?: string;\n  /** Frames dropped by the recorder (screenshot failures). */\n  dropped?: number;\n  /** Present only when an interaction script was replayed. */\n  interactions?: InteractionReport;\n  /** The viewport the frames were taken at; adds the image-scale line when known. */\n  viewport?: Viewport;\n  /**\n   * Remarks about the capture itself rather than about any one frame — a\n   * context layer that hit its cap, requests still in flight when the\n   * recording ended. One line each, after the summary.\n   */\n  notes?: string[];\n}\n\n/**\n * Build the MCP CallToolResult for a capture, following the \"MCP Response\n * Format\" in CLAUDE.md: one summary text block, then per card an image block,\n * a metadata text block and (when present) the change-region crop image.\n */\nexport function formatDiffCards(summary: CaptureSummary): CallToolResult {\n  const lines = [formatSummaryLine(summary)];\n  if (summary.viewport) {\n    const scale = describeScale(summary.viewport);\n    lines.push(scale.charAt(0).toUpperCase() + scale.slice(1));\n  }\n  if (summary.interactions) {\n    lines.push(formatInteractionLine(summary.interactions));\n  }\n  for (const note of summary.notes ?? []) {\n    lines.push(note);\n  }\n  const content: CallToolResult[\"content\"] = [{ type: \"text\", text: lines.join(\"\\n\") }];\n  const last = summary.cards.length - 1;\n  summary.cards.forEach((card, i) => {\n    // First, last and event frames survive the image budget longest; crops go first.\n    const keep = i === 0 || i === last || card.trigger !== \"animation\";\n    content.push(markImage({ type: \"image\", data: card.full_frame, mimeType: \"image/png\" }, { role: \"frame\", keep }));\n    content.push({ type: \"text\", text: formatCardMeta(card) });\n    if (card.change_region?.crop) {\n      content.push(markImage({ type: \"image\", data: card.change_region.crop, mimeType: \"image/png\" }, { role: \"crop\" }));\n    }\n  });\n  return { content };\n}\n\n/**\n * One-line description of the whole capture. Always names the requested url;\n * appends the final url only when the page ended somewhere else, the page\n * title when known, and the dropped-frame count only when frames were lost.\n */\nfunction formatSummaryLine(summary: CaptureSummary): string {\n  const { cards, total_frames, duration_ms, url, final_url, title, dropped } = summary;\n  const recording = `from ${total_frames} raw frames (${duration_ms}ms recording) of ${url}`;\n  let text = cards.length === 0 ? `No frames captured ${recording}` : `Captured ${cards.length} meaningful frames ${recording}`;\n  if (final_url !== undefined && !isSameUrl(url, final_url)) {\n    text += ` → ${final_url}`;\n  }\n  if (title) {\n    text += ` — \"${title}\"`;\n  }\n  if (dropped !== undefined && dropped > 0) {\n    text += ` (${dropped} frames dropped)`;\n  }\n  return text;\n}\n\n/**\n * How the interaction script went: how many steps ran, what they were, and —\n * when one failed — which one and why. A failed step is a finding about the\n * page, not a tool failure, so it is reported here alongside the frames rather\n * than replacing them with an error.\n */\nexport function formatInteractionLine(report: InteractionReport): string {\n  let text = `Interactions: ${report.completed}/${report.total} replayed`;\n  if (report.steps.length > 0) {\n    text += ` — ${report.steps.join(\", \")}`;\n  }\n  if (report.error !== undefined) {\n    text += `. Step ${report.failed_index ?? report.completed + 1}: ${report.error}`;\n  }\n  return text;\n}\n\n/**\n * Compare two URLs as URLs, not as strings: `page.url()` returns the\n * WHATWG-normalised form, so a request for `http://localhost:3000` comes back\n * as `http://localhost:3000/` without anything having navigated.\n */\nfunction isSameUrl(a: string, b: string): boolean {\n  if (a === b) return true;\n  try {\n    return new URL(a).href === new URL(b).href;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * The metadata text block for one card (exported for tests and for reuse by\n * the interact tool). Line 1 is always `Frame N @ Tms [trigger]`; the\n * optional sections follow in a fixed order — Changed, Console, Network,\n * Performance, DOM — and are omitted entirely when their data is absent.\n */\nexport function formatCardMeta(card: DiffCard): string {\n  const lines: string[] = [`Frame ${card.index} @ ${card.timestamp_ms}ms [${card.trigger}]`];\n\n  const region = card.change_region;\n  if (region) {\n    if (region.change_percent === 0) {\n      lines.push(\"Changed: 0.0% — no visual change since previous frame\");\n    } else {\n      const { bbox } = region;\n      let changed = `Changed: ${region.change_percent.toFixed(1)}% — region: ${bbox.x},${bbox.y} ${bbox.width}x${bbox.height}`;\n      if (!region.crop) {\n        changed += \" (full-frame change, see frame image)\";\n      }\n      lines.push(changed);\n    }\n  }\n\n  if (card.console_entries?.length) {\n    lines.push(\"Console:\");\n    for (const entry of card.console_entries) {\n      lines.push(`  [${entry.level}] ${entry.text}`);\n    }\n  }\n\n  if (card.network_events?.length) {\n    lines.push(\"Network:\");\n    for (const event of card.network_events) {\n      // A request that never got a response has no status to print; what\n      // stopped it (or that it is still running) is the useful part.\n      const outcome = event.status > 0 ? String(event.status) : (event.error ?? \"no response\");\n      const why = event.status > 0 && event.error !== undefined ? ` ${event.error}` : \"\";\n      lines.push(`  ${event.method} ${event.url} → ${outcome}${why} (${event.duration_ms}ms)`);\n    }\n  }\n\n  const perf = card.performance;\n  if (perf) {\n    lines.push(\"Performance:\");\n    if (perf.paint_time_ms !== undefined) lines.push(`  paint ${perf.paint_time_ms}ms`);\n    if (perf.layout_shifts !== undefined) {\n      const score = perf.layout_shift_score !== undefined ? ` (score ${perf.layout_shift_score})` : \"\";\n      lines.push(`  layout shifts ${perf.layout_shifts}${score}`);\n    }\n    if (perf.lcp_ms !== undefined) lines.push(`  lcp ${perf.lcp_ms}ms`);\n  }\n\n  if (card.dom_snapshot) {\n    lines.push(`DOM:\\n${card.dom_snapshot}`);\n  }\n\n  return lines.join(\"\\n\");\n}\n"]}