cbrowser 19.2.0 → 19.2.2

package/dist/mcp-tools/base/visual-testing-tools.js

@@ -8,17 +8,56 @@ import { z } from "zod";
 import { getDefaultConfig } from "../../config.js";
 import { resolveValuesForPersona } from "../../values/persona-values.js";
 import { writeArtifact } from "../../artifact-store.js";
+import { buildContentWithPreviews } from "../inline-image.js";
 /**
- * Largest heatmap returned inline, in base64 characters.
+ * Resolve a persona before anything is measured, or return the tool's refusal.
  *
- * Hosts truncate tool results near 150k characters and substitute a file
- * pointer in place of the payload, which downstream arrives as unparseable
- * text. Measured: a 1280x800 heatmap is ~738k characters, five times the cap,
- * so shipping it inline destroyed the JSON it accompanied. Anything above this
- * goes through artifact_fetch instead.
+ * Loads the calling account's CMS personas first (scoped to that account), so a
+ * custom persona resolves exactly as list_cognitive_personas shows it. An
+ * unknown name is refused here: it used to reach the relevance LLM as a bare
+ * string, which role-played it from the name alone. (2026-10-09)
  */
-const INLINE_IMAGE_BUDGET = 100_000;
+async function resolveOrRefuse(requested) {
+    try {
+        const { loadAccountPersonas } = await import("../account-personas.js");
+        const { getSessionApiKey } = await import("./cognitive-tools.js");
+        await loadAccountPersonas(getSessionApiKey());
+    }
+    catch { /* falls back to disk and built-ins */ }
+    const { resolvePersonaForTool, UnknownPersonaError } = await import("../../personas.js");
+    try {
+        const r = resolvePersonaForTool(requested);
+        return { ok: true, name: r.name, ...(r.resolvedFrom ? { resolvedFrom: r.resolvedFrom } : {}) };
+    }
+    catch (e) {
+        if (!(e instanceof UnknownPersonaError))
+            throw e;
+        return { ok: false, result: { isError: true, content: [{ type: "text", text: JSON.stringify({
+                            error: e.message, code: e.code, persona: requested, suggestions: e.suggestions,
+                        }, null, 2) }] } };
+    }
+}
 import { runVisualRegression, runCrossBrowserTest, runResponsiveTest, runABComparison, crossBrowserDiff, } from "../../visual/index.js";
+/**
+ * attention_analysis's result: the JSON, then the heatmap as an image block.
+ *
+ * Hosts truncate tool results near 150k characters and substitute a file
+ * pointer for the payload, which downstream arrives as unparseable text.
+ * Measured: a 1280x800 heatmap PNG is ~738k characters of base64, five times
+ * the cap, so shipping it inline destroyed the JSON it accompanied (28e5786).
+ * That fix kept the cap by dropping the picture whenever it was over a fixed
+ * 100k budget -- which, at real page sizes, was always, so the tool whose
+ * finding IS the heatmap returned no heatmap.
+ *
+ * The picture now always rides along as a JPEG preview fitted to what the JSON
+ * leaves of the cap, `heatmapPreview` says exactly what was attached, and the
+ * full-resolution PNG stays at heatmapUrl / heatmapFile for artifact_fetch.
+ */
+export async function assembleAttentionContent(data, heatmapPng, fullResolution) {
+    if (!heatmapPng)
+        return [{ type: "text", text: JSON.stringify(data, null, 2) }];
+    return buildContentWithPreviews(data, [{ name: "heatmap", png: heatmapPng, fullResolution }], (p) => ({ heatmapPreview: p.heatmap }));
+}
 /**
  * Register visual testing tools (6 tools: visual_baseline, visual_regression, cross_browser_test, cross_browser_diff, responsive_test, ab_comparison)
  */
@@ -405,7 +444,7 @@ export function registerVisualTestingTools(server) {
     // ── Attention Transport (v18.28.0) ──
     server.registerTool("attention_analysis", {
         title: "Attention Saliency Analysis",
-        description: "Analyze where a persona's attention goes on a page. Two-layer model: (1) visual saliency via W₂ on CIE-Lab (what POPS), (2) DOM semantic analysis (what MATTERS — CTAs, headings, forms, nav). Blended 35/65 so a gray search bar a power-user prioritizes outweighs a flashy banner they ignore. Returns heatmap overlay, attention metrics, and quality score.",
+        description: "Analyze where a persona's attention goes on a page. Two-layer model: (1) visual saliency via W₂ on CIE-Lab (what POPS), (2) DOM semantic analysis (what MATTERS — CTAs, headings, forms, nav). Blended 35/65 so a gray search bar a power-user prioritizes outweighs a flashy banner they ignore. Returns attention metrics, a quality score, and the heatmap overlay: inline as a JPEG preview sized to fit the result (described in heatmapPreview), with the full-resolution PNG at heatmapUrl / artifact_fetch({ file: heatmapFile }).",
         inputSchema: {
             url: z.string().describe("URL to analyze"),
             persona: z.string().optional().default("first-timer").describe("Persona name"),
@@ -426,7 +465,11 @@ export function registerVisualTestingTools(server) {
         // Declares the attention view. The heatmap is the finding here, and a JSON
         // list of scores is a lossy description of where a persona actually looks.
         _meta: { ui: { resourceUri: "ui://cbrowser/attention" } },
-    }, async ({ url, persona, goal, cellSize, heatmap, device, useValues, freezeAnimations: doFreeze }) => {
+    }, async ({ url, persona: requestedPersona, goal, cellSize, heatmap, device, useValues, freezeAnimations: doFreeze }) => {
+        const resolved = await resolveOrRefuse(requestedPersona);
+        if (!resolved.ok)
+            return resolved.result;
+        const persona = resolved.name;
         const { CBrowser } = await import("../../browser.js");
         const browser = new CBrowser({
             headless: true,
@@ -486,14 +529,7 @@ export function registerVisualTestingTools(server) {
             }));
             // Run attention analysis with DOM semantic layer (visual + semantic blend)
             const { analyzeAttention } = await import("../../visual/attention-transport.js");
-            // Same reason as capture: a persona created through the account lives in
-            // the CMS, and attention_analysis resolves personas through the registry.
-            try {
-                const { loadAccountPersonas } = await import("../account-personas.js");
-                const { getSessionApiKey } = await import("./cognitive-tools.js");
-                await loadAccountPersonas(getSessionApiKey());
-            }
-            catch { /* falls back to disk and built-ins */ }
+            // Account personas were loaded by resolveOrRefuse, before the browser.
             const domAttentionElements = await collectDomAttentionElements(page).catch(() => []);
             // Persona-judged relevance, replacing keyword overlap in the semantic
             // layer. Computed HERE rather than inside analyzeAttention so the one
@@ -585,93 +621,93 @@ export function registerVisualTestingTools(server) {
                 narrativeReconciliation = reconcileAttentionNarrative(relevanceReasoning, attentionQuality);
             }
             catch { /* annotation only; never block the result on it */ }
-            const content = [{
-                    type: "text",
-                    text: JSON.stringify({
-                        persona: result.persona,
-                        // Stated, because two tools silently rendering at different sizes is
-                        // exactly what made these coordinates incomparable with a CTC run.
-                        // A reader can now check instead of assuming they match.
-                        renderedViewport: device
-                            ? `device: ${device.toLowerCase()}`
-                            : `${getDefaultConfig().viewportWidth}x${getDefaultConfig().viewportHeight}`,
-                        coordinateSpace: "CSS pixels in the rendered viewport above — compare only against runs reporting the same renderedViewport",
-                        // What actually ran, not what was asked for. A freeze that silently
-                        // failed would produce exactly the variance it was asked to remove,
-                        // under a label saying it had been removed.
-                        animationState,
-                        ...(animationsStillRunning >= 0 ? { animationsRunning: animationsStillRunning } : {}),
-                        ...(animationState === "frozen" && animationsStillRunning > 0 ? {
-                            animationWarning: `freezeAnimations was requested but ${animationsStillRunning} animation(s) are still running; this run is NOT reproducible.`,
-                        } : {}),
-                        ...(animationState === "live" && animationsStillRunning > 0 ? {
-                            animationNote: `${animationsStillRunning} animation(s) were running during capture, so saliency will vary slightly between runs. Pass freezeAnimations:true to compare runs.`,
-                        } : {}),
-                        alignmentScore: result.alignmentScore,
-                        entropy: result.entropy,
-                        concentration: result.concentration,
-                        transportCost: result.transportCost,
-                        topAttentionAreas: result.attentionCompetitors,
-                        ...(attentionQuality ? { attentionQuality } : {}),
-                        // Why this persona attends where it does, and by which method.
-                        // The scores were already being used to build the map while the
-                        // reasoning behind them was computed and thrown away — a judgement
-                        // with no stated reason is one the caller cannot argue with, which
-                        // was the point of leaving keyword matching.
-                        ...(relevanceReasoning ? { attentionReasoning: relevanceReasoning } : {}),
-                        // Only present when a checkable claim in the narrative actually
-                        // contradicts a computed metric. Silent otherwise — a spurious
-                        // "these disagree" on a narrative that was fine is its own defect.
-                        ...(narrativeReconciliation?.contradictsMetrics ? {
-                            narrativeReconciliation: {
-                                contradictsMetrics: true,
-                                contradictingClaims: narrativeReconciliation.contradictingClaims,
-                                note: narrativeReconciliation.reconciliationNote,
-                            },
-                        } : {}),
-                        ...(relevanceSource ? { relevanceMethod: relevanceSource } : {}),
-                        // These two lines used to read as a contradiction — "Scattered
-                        // attention (overwhelmed)" printed directly above "Attention
-                        // concentrated on few areas". The numbers were never wrong; the
-                        // prose was. They answer different questions:
-                        //   entropy       = normalized Shannon entropy, 1 = evenly spread
-                        //                   across every cell that gets any attention
-                        //   concentration = share of total saliency in the top 20% of cells,
-                        //                   whose floor is 0.2 for a perfectly uniform page,
-                        //                   NOT 0
-                        // Saliency spread evenly within a small region scores high on both
-                        // (measured: entropy 0.692 with concentration 1.0), and both
-                        // readings are correct. Each string now names its own basis, and
-                        // `pattern` gives the single combined verdict a caller actually
-                        // wants. (2026-07-28)
-                        interpretation: {
-                            // Each verdict names its BASIS, because two of them in one payload
-                            // read as a contradiction otherwise.
-                            //
-                            // Measured: attentionQuality.interpretation said "design intent is
-                            // working" while this line said "attention diverges from intended
-                            // design", in the same response, off an alignmentScore of 0.484.
-                            // Both were right about different questions -- one asks whether
-                            // the CTAs captured attention, the other whether the overall
-                            // distribution matches where the design puts emphasis -- and a
-                            // reader has no way to know that from two bare verdicts.
-                            // (2026-08-02)
-                            alignment: `${result.alignmentScore > 0.8 ? "Attention follows intended design" : result.alignmentScore > 0.5 ? "Moderate attention alignment" : "Attention diverges from intended design"} (alignmentScore ${result.alignmentScore.toFixed(3)}: how closely the whole attention distribution matches where the design places emphasis — a different question from whether the CTAs specifically captured attention, which attentionQuality answers)`,
-                            entropy: `Evenness of attention across the areas that draw it: ${result.entropy > 0.8 ? "very even" : result.entropy > 0.5 ? "moderately even" : "sharply peaked"} (${result.entropy.toFixed(2)} of 1.0)`,
-                            concentration: `Share of attention landing in the top 20% of the page: ${(result.concentration * 100).toFixed(0)}% (a perfectly uniform page scores 20%)`,
-                            pattern: result.concentration > 0.6
-                                ? (result.entropy > 0.5
-                                    ? "Attention pools into a small part of the page, and spreads evenly once there — a dense hotspot rather than a single focal point."
-                                    : "Attention locks onto one or two focal points and ignores the rest of the page.")
-                                : (result.entropy > 0.5
-                                    ? "Attention is spread broadly across the page with no dominant focal point."
-                                    : "Attention is split between a few separate areas, with the rest of the page largely unseen."),
-                        },
-                        computeTimeMs: Math.round(result.computeTimeMs),
-                        hasHeatmap: heatmap !== false,
-                    }, null, 2),
-                }];
+            const data = {
+                persona: result.persona,
+                ...(resolved.resolvedFrom ? { resolvedFrom: resolved.resolvedFrom } : {}),
+                // Stated, because two tools silently rendering at different sizes is
+                // exactly what made these coordinates incomparable with a CTC run.
+                // A reader can now check instead of assuming they match.
+                renderedViewport: device
+                    ? `device: ${device.toLowerCase()}`
+                    : `${getDefaultConfig().viewportWidth}x${getDefaultConfig().viewportHeight}`,
+                coordinateSpace: "CSS pixels in the rendered viewport above — compare only against runs reporting the same renderedViewport",
+                // What actually ran, not what was asked for. A freeze that silently
+                // failed would produce exactly the variance it was asked to remove,
+                // under a label saying it had been removed.
+                animationState,
+                ...(animationsStillRunning >= 0 ? { animationsRunning: animationsStillRunning } : {}),
+                ...(animationState === "frozen" && animationsStillRunning > 0 ? {
+                    animationWarning: `freezeAnimations was requested but ${animationsStillRunning} animation(s) are still running; this run is NOT reproducible.`,
+                } : {}),
+                ...(animationState === "live" && animationsStillRunning > 0 ? {
+                    animationNote: `${animationsStillRunning} animation(s) were running during capture, so saliency will vary slightly between runs. Pass freezeAnimations:true to compare runs.`,
+                } : {}),
+                alignmentScore: result.alignmentScore,
+                entropy: result.entropy,
+                concentration: result.concentration,
+                transportCost: result.transportCost,
+                topAttentionAreas: result.attentionCompetitors,
+                ...(attentionQuality ? { attentionQuality } : {}),
+                // Why this persona attends where it does, and by which method.
+                // The scores were already being used to build the map while the
+                // reasoning behind them was computed and thrown away — a judgement
+                // with no stated reason is one the caller cannot argue with, which
+                // was the point of leaving keyword matching.
+                ...(relevanceReasoning ? { attentionReasoning: relevanceReasoning } : {}),
+                // Only present when a checkable claim in the narrative actually
+                // contradicts a computed metric. Silent otherwise — a spurious
+                // "these disagree" on a narrative that was fine is its own defect.
+                ...(narrativeReconciliation?.contradictsMetrics ? {
+                    narrativeReconciliation: {
+                        contradictsMetrics: true,
+                        contradictingClaims: narrativeReconciliation.contradictingClaims,
+                        note: narrativeReconciliation.reconciliationNote,
+                    },
+                } : {}),
+                ...(relevanceSource ? { relevanceMethod: relevanceSource } : {}),
+                // These two lines used to read as a contradiction — "Scattered
+                // attention (overwhelmed)" printed directly above "Attention
+                // concentrated on few areas". The numbers were never wrong; the
+                // prose was. They answer different questions:
+                //   entropy       = normalized Shannon entropy, 1 = evenly spread
+                //                   across every cell that gets any attention
+                //   concentration = share of total saliency in the top 20% of cells,
+                //                   whose floor is 0.2 for a perfectly uniform page,
+                //                   NOT 0
+                // Saliency spread evenly within a small region scores high on both
+                // (measured: entropy 0.692 with concentration 1.0), and both
+                // readings are correct. Each string now names its own basis, and
+                // `pattern` gives the single combined verdict a caller actually
+                // wants. (2026-07-28)
+                interpretation: {
+                    // Each verdict names its BASIS, because two of them in one payload
+                    // read as a contradiction otherwise.
+                    //
+                    // Measured: attentionQuality.interpretation said "design intent is
+                    // working" while this line said "attention diverges from intended
+                    // design", in the same response, off an alignmentScore of 0.484.
+                    // Both were right about different questions -- one asks whether
+                    // the CTAs captured attention, the other whether the overall
+                    // distribution matches where the design puts emphasis -- and a
+                    // reader has no way to know that from two bare verdicts.
+                    // (2026-08-02)
+                    alignment: `${result.alignmentScore > 0.8 ? "Attention follows intended design" : result.alignmentScore > 0.5 ? "Moderate attention alignment" : "Attention diverges from intended design"} (alignmentScore ${result.alignmentScore.toFixed(3)}: how closely the whole attention distribution matches where the design places emphasis — a different question from whether the CTAs specifically captured attention, which attentionQuality answers)`,
+                    entropy: `Evenness of attention across the areas that draw it: ${result.entropy > 0.8 ? "very even" : result.entropy > 0.5 ? "moderately even" : "sharply peaked"} (${result.entropy.toFixed(2)} of 1.0)`,
+                    concentration: `Share of attention landing in the top 20% of the page: ${(result.concentration * 100).toFixed(0)}% (a perfectly uniform page scores 20%)`,
+                    pattern: result.concentration > 0.6
+                        ? (result.entropy > 0.5
+                            ? "Attention pools into a small part of the page, and spreads evenly once there — a dense hotspot rather than a single focal point."
+                            : "Attention locks onto one or two focal points and ignores the rest of the page.")
+                        : (result.entropy > 0.5
+                            ? "Attention is spread broadly across the page with no dominant focal point."
+                            : "Attention is split between a few separate areas, with the rest of the page largely unseen."),
+                },
+                computeTimeMs: Math.round(result.computeTimeMs),
+                hasHeatmap: heatmap !== false,
+            };
             // Generate heatmap overlay and save as public URL
+            let heatmapPng;
+            let heatmapFullResolution = "";
             if (heatmap !== false && result.saliencyMap) {
                 try {
                     const { generateHeatmapOverlay } = await import("../../visual/heatmap-overlay.js");
@@ -689,10 +725,12 @@ export function registerVisualTestingTools(server) {
                     const cbrowserDir = join(homedir(), ".cbrowser", "heatmaps");
                     let savedPath = "";
                     let publicUrl = "";
-                    const written = writeArtifact(Buffer.from(heatmapBase64, "base64"), `${heatmapId}.png`);
+                    const png = Buffer.from(heatmapBase64, "base64");
+                    const written = writeArtifact(png, `${heatmapId}.png`);
                     if (written) {
                         savedPath = written.path;
                         publicUrl = written.url;
+                        heatmapFullResolution = "the PNG at heatmapUrl, or artifact_fetch({ file: heatmapFile })";
                     }
                     else {
                         // Served store unavailable — keep the local copy, and return the
@@ -700,44 +738,17 @@ export function registerVisualTestingTools(server) {
                         if (!existsSync(cbrowserDir))
                             mkdirSync(cbrowserDir, { recursive: true });
                         savedPath = join(cbrowserDir, `${heatmapId}.png`);
-                        writeFileSync(savedPath, Buffer.from(heatmapBase64, "base64"));
+                        writeFileSync(savedPath, png);
                         publicUrl = savedPath;
+                        heatmapFullResolution = "the PNG at the local path in heatmapUrl (the artifact store was unavailable, so artifact_fetch cannot serve it)";
                     }
-                    // Return both image content and URL
-                    // The heatmap is 700KB+ of base64. Shipping it inline pushed the
-                    // whole result past the host's ~150k cap, at which point the host
-                    // substitutes a file pointer -- so the JSON above arrived as
-                    // unparseable text and the view rendered nothing, while the image
-                    // it was meant to show was the reason it broke.
-                    //
-                    // Small heatmaps still ride along, because a host with no view
-                    // support should not lose the picture entirely. Anything larger is
-                    // left to artifact_fetch, which is the channel built for it.
-                    const inlineChars = heatmapBase64.length;
-                    const inlineOk = inlineChars <= INLINE_IMAGE_BUDGET;
-                    if (inlineOk) {
-                        content.push({
-                            type: "image",
-                            data: heatmapBase64,
-                            mimeType: "image/png",
-                        });
-                    }
-                    // Add URL to the text response
-                    const firstBlock = content[0];
-                    if (firstBlock.type === "text") {
-                        const textContent = JSON.parse(firstBlock.text);
-                        textContent.heatmapUrl = publicUrl;
-                        if (!inlineOk) {
-                            textContent.inlineHeatmapOmitted =
-                                `Heatmap is ${(inlineChars / 1024).toFixed(0)}KB of base64, over the ${(INLINE_IMAGE_BUDGET / 1024).toFixed(0)}KB inline budget. Fetch it with artifact_fetch using heatmapFile, or open heatmapUrl.`;
-                        }
-                        // The filename, not just the URL: the widget sandbox cannot fetch
-                        // that URL, so the view asks artifact_fetch for these bytes over
-                        // the MCP connection instead.
-                        textContent.heatmapFile = `${heatmapId}.png`;
-                        textContent.heatmapNote = "Show this heatmap image to the user. The red areas show where this persona's attention concentrates. Blue areas receive little attention.";
-                        content[0] = { type: "text", text: JSON.stringify(textContent, null, 2) };
-                    }
+                    data.heatmapUrl = publicUrl;
+                    // The filename, not just the URL: the widget sandbox cannot fetch
+                    // that URL, so the view asks artifact_fetch for these bytes over
+                    // the MCP connection instead.
+                    data.heatmapFile = `${heatmapId}.png`;
+                    data.heatmapNote = "Show this heatmap image to the user. The red areas show where this persona's attention concentrates. Blue areas receive little attention.";
+                    heatmapPng = png;
                     // Auto-save to Visual Reports gallery
                     try {
                         const { saveVisualReport } = await import("../visual-report-saver.js");
@@ -761,7 +772,7 @@ export function registerVisualTestingTools(server) {
                 unlinkSync(screenshotPath);
             }
             catch { }
-            return { content };
+            return { content: await assembleAttentionContent(data, heatmapPng, heatmapFullResolution) };
         }
         finally {
             await browser.close();
@@ -769,7 +780,7 @@ export function registerVisualTestingTools(server) {
     });
     server.registerTool("attention_compare", {
         title: "Compare Persona Attention",
-        description: "Compare attention patterns between two personas on the same page. Shows where they look differently and the Wasserstein divergence between their saliency maps.",
+        description: "Compare attention patterns between two personas on the same page. Shows where they look differently and the Wasserstein divergence between their saliency maps. The comparison map comes back inline as a JPEG preview sized to fit the result (described in comparisonHeatmapPreview), with the full-resolution PNG at comparisonHeatmapUrl / artifact_fetch({ file: comparisonHeatmapFile }).",
         inputSchema: {
             url: z.string().describe("URL to analyze"),
             personaA: z.string().describe("First persona"),
@@ -782,7 +793,17 @@ export function registerVisualTestingTools(server) {
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async ({ url, personaA, personaB }) => {
+    }, async ({ url, personaA: requestedA, personaB: requestedB }) => {
+        // Both refused before measuring: an unknown name compared as "maximally
+        // different" from power-user, more than the extreme real pair. (2026-10-09)
+        const resolvedA = await resolveOrRefuse(requestedA);
+        if (!resolvedA.ok)
+            return resolvedA.result;
+        const resolvedB = await resolveOrRefuse(requestedB);
+        if (!resolvedB.ok)
+            return resolvedB.result;
+        const personaA = resolvedA.name;
+        const personaB = resolvedB.name;
         const { CBrowser } = await import("../../browser.js");
         // Same configured viewport as attention_analysis. This tool COMPARES two
         // attention runs, so rendering at a size no other tool uses meant its
@@ -815,16 +836,17 @@ export function registerVisualTestingTools(server) {
             }));
             const { compareAttention } = await import("../../visual/attention-transport.js");
             const result = await compareAttention(screenshotPath, personaA, personaB, 4, domEls);
-            const content = [];
             const responseData = {
                 personaA: {
                     name: personaA,
+                    ...(resolvedA.resolvedFrom ? { resolvedFrom: resolvedA.resolvedFrom } : {}),
                     alignment: result.personaA.alignmentScore,
                     entropy: result.personaA.entropy,
                     concentration: result.personaA.concentration,
                 },
                 personaB: {
                     name: personaB,
+                    ...(resolvedB.resolvedFrom ? { resolvedFrom: resolvedB.resolvedFrom } : {}),
                     alignment: result.personaB.alignmentScore,
                     entropy: result.personaB.entropy,
                     concentration: result.personaB.concentration,
@@ -838,30 +860,44 @@ export function registerVisualTestingTools(server) {
                 divergentRegions: result.divergentRegions.slice(0, 5),
             };
             // Generate comparison heatmap overlay
+            let comparisonPng;
+            let comparisonFullResolution = "";
             if (result.personaA.saliencyMap && result.personaB.saliencyMap) {
                 try {
                     const { generateComparisonHeatmap } = await import("../../visual/visual-overlays.js");
                     const compBase64 = await generateComparisonHeatmap(screenshotPath, result.personaA.saliencyMap.cells, result.personaB.saliencyMap.cells, result.personaA.saliencyMap.rows, result.personaA.saliencyMap.cols, personaA, personaB);
                     // Save to public URL
                     const heatmapId = `cmp-${personaA}-${personaB}-${Date.now()}`;
-                    const written = writeArtifact(Buffer.from(compBase64, "base64"), `${heatmapId}.png`);
+                    comparisonPng = Buffer.from(compBase64, "base64");
+                    const written = writeArtifact(comparisonPng, `${heatmapId}.png`);
                     // Only advertise a URL when the artifact actually landed in the
                     // served directory. A URL for a file that was not written is the
                     // defect the artifact store exists to end.
-                    if (written)
+                    if (written) {
                         responseData.comparisonHeatmapUrl = written.url;
+                        responseData.comparisonHeatmapFile = `${heatmapId}.png`;
+                        comparisonFullResolution = "the PNG at comparisonHeatmapUrl, or artifact_fetch({ file: comparisonHeatmapFile })";
+                    }
+                    else {
+                        comparisonFullResolution = "not available (the artifact store was unavailable, so the full-resolution PNG was not saved)";
+                    }
                     responseData.heatmapNote = `Blue = ${personaA} looks here more. Red = ${personaB} looks here more. Transparent = similar attention.`;
-                    content.push({ type: "image", data: compBase64, mimeType: "image/png" });
                 }
                 catch (e) {
                     console.debug(`[attention_compare] Comparison heatmap failed: ${e.message}`);
                 }
             }
-            content.unshift({ type: "text", text: JSON.stringify(responseData, null, 2) });
             try {
                 unlinkSync(screenshotPath);
             }
             catch { }
+            // The comparison map was pushed inline at full PNG size, ~500 KB of
+            // base64 against a ~150k result cap, so on a real page this tool
+            // blew the cap that attention_analysis was fixed for. Same remedy:
+            // a JPEG preview fitted to what the JSON leaves.
+            const content = comparisonPng
+                ? await buildContentWithPreviews(responseData, [{ name: "comparison", png: comparisonPng, fullResolution: comparisonFullResolution }], (p) => ({ comparisonHeatmapPreview: p.comparison }))
+                : [{ type: "text", text: JSON.stringify(responseData, null, 2) }];
             return { content };
         }
         finally {