cbrowser 18.73.2 → 18.73.4

package/dist/mcp-tools/base/analysis-tools.js

@@ -5,15 +5,21 @@
  * @license MIT
  */
 import { z } from "zod";
+import { refuseUnboundSession } from "../session-policy.js";
 import { findElementByIntent, runAIReadinessBenchmark } from "../../analysis/index.js";
 /**
  * Register analysis tools (4 tools: analyze_page, generate_tests, find_element_by_intent, ai_benchmark)
  */
-export function registerAnalysisTools(server, { getBrowser }) {
+export function registerAnalysisTools(server, { getBrowser, getBrowserByToken }) {
     server.registerTool("analyze_page", {
         title: "Analyze Page Structure",
-        description: "Analyze page structure for forms, buttons, links",
-        inputSchema: {},
+        description: "Analyze page structure for forms, buttons, links. MUST pass _browserToken from a previous tool call to analyze the same page — without it a blank page is analyzed and every count comes back zero.",
+        inputSchema: {
+            // Took no arguments at all, so on the HTTP transport it always analysed a
+            // fresh blank page: 0 forms, 0 buttons, 0 links, hasLogin false. Reads as a
+            // real analysis of a sparse page rather than as an error. (2026-07-28)
+            _browserToken: z.string().optional().describe("Browser session token from a previous tool call"),
+        },
         annotations: {
             title: "Analyze Page Structure",
             readOnlyHint: true,
@@ -21,14 +27,29 @@ export function registerAnalysisTools(server, { getBrowser }) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async () => {
-        const b = await getBrowser();
+    }, async ({ _browserToken }) => {
+        // Reports on page structure, so a blank-page answer (0 forms, 0 buttons,
+        // 0 links) reads as a real finding rather than an error.
+        const unbound = refuseUnboundSession("analyze_page", { getBrowserByToken }, _browserToken);
+        if (unbound)
+            return unbound;
+        let b;
+        let token;
+        if (getBrowserByToken) {
+            const resolved = await getBrowserByToken(_browserToken);
+            b = resolved.browser;
+            token = resolved.token;
+        }
+        else {
+            b = await getBrowser();
+        }
         const analysis = await b.analyzePage();
         return {
             content: [
                 {
                     type: "text",
                     text: JSON.stringify({
+                        ...(token ? { _browserToken: token } : {}),
                         title: analysis.title,
                         forms: analysis.forms.length,
                         buttons: analysis.buttons.length,
@@ -46,6 +67,10 @@ export function registerAnalysisTools(server, { getBrowser }) {
         description: "Generate test scenarios for a page",
         inputSchema: {
             url: z.string().url().optional().describe("URL to analyze (uses current page if not provided)"),
+            // "uses current page if not provided" was unreachable on the HTTP transport:
+            // omitting url fell back to a blank page, so the no-url branch generated
+            // tests for about:blank. (2026-07-28)
+            _browserToken: z.string().optional().describe("Browser session token from a previous tool call — required when url is omitted"),
         },
         annotations: {
             title: "Generate Test Cases",
@@ -54,20 +79,52 @@ export function registerAnalysisTools(server, { getBrowser }) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ url }) => {
-        const b = await getBrowser();
+    }, async ({ url, _browserToken }) => {
+        // Only when it is being asked about "the current page". With an explicit
+        // url it navigates itself and needs no session.
+        if (!url) {
+            const unbound = refuseUnboundSession("generate_tests", { getBrowserByToken }, _browserToken);
+            if (unbound)
+                return unbound;
+        }
+        let b;
+        let token;
+        if (getBrowserByToken) {
+            const resolved = await getBrowserByToken(_browserToken);
+            b = resolved.browser;
+            token = resolved.token;
+        }
+        else {
+            b = await getBrowser();
+        }
         const result = await b.generateTests(url);
         return {
             content: [
                 {
                     type: "text",
                     text: JSON.stringify({
+                        ...(token ? { _browserToken: token } : {}),
                         testsGenerated: result.tests.length,
+                        // `steps` used to be t.steps.length — a bare count. A caller got
+                        // "3 steps" with no way to see or run them, so there was no handoff
+                        // into nl_test_inline / nl_test_file and the tool could only be
+                        // read, not used. The step text and a runnable script were both
+                        // already computed and then discarded. (2026-07-29)
                         tests: result.tests.map(t => ({
                             name: t.name,
                             description: t.description,
-                            steps: t.steps.length,
+                            stepCount: t.steps.length,
+                            steps: t.steps.map(st => ({
+                                action: st.action,
+                                ...(st.target ? { target: st.target } : {}),
+                                ...(st.value !== undefined ? { value: st.value } : {}),
+                                description: st.description,
+                            })),
+                            assertions: t.assertions,
                         })),
+                        // Ready to paste straight into nl_test_inline.
+                        cbrowserScript: result.cbrowserScript,
+                        usage: "Pass cbrowserScript to nl_test_inline as `content`, or write it to a file and use nl_test_file.",
                     }, null, 2),
                 },
             ],
@@ -79,6 +136,11 @@ export function registerAnalysisTools(server, { getBrowser }) {
         inputSchema: {
             intent: z.string().describe("Natural language description like 'the cheapest product' or 'login form'"),
             verbose: z.boolean().optional().describe("Include alternative matches with confidence scores and AI suggestions"),
+            // Without this, the tool searched a blank browser on the HTTP transport and
+            // returned `confidence: 0, "No match found"` with empty alternatives — a
+            // plausible "nothing here" that is indistinguishable from a real miss.
+            // (2026-07-28)
+            _browserToken: z.string().optional().describe("Browser session token from a previous tool call"),
         },
         annotations: {
             title: "Find Element by Intent",
@@ -87,8 +149,19 @@ export function registerAnalysisTools(server, { getBrowser }) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ intent, verbose }) => {
-        const b = await getBrowser();
+    }, async ({ intent, verbose, _browserToken }) => {
+        // Searches the page, so a blank-browser search returns "no match found"
+        // with confidence 0 — indistinguishable from a genuine miss.
+        const unbound = refuseUnboundSession("find_element_by_intent", { getBrowserByToken }, _browserToken);
+        if (unbound)
+            return unbound;
+        let b;
+        if (getBrowserByToken) {
+            b = (await getBrowserByToken(_browserToken)).browser;
+        }
+        else {
+            b = await getBrowser();
+        }
         const result = await findElementByIntent(b, intent, { verbose });
         if (result && result.confidence > 0) {
             return {

package/dist/mcp-tools/base/analysis-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-tools.js","sourceRoot":"","sources":["../../../src/mcp-tools/base/analysis-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"analysis-tools.js","sourceRoot":"","sources":["../../../src/mcp-tools/base/analysis-tools.ts"],"names":[],"mappings":"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"}

package/dist/mcp-tools/base/assertion-tools.d.ts

@@ -8,5 +8,5 @@ import type { McpServer, ToolRegistrationContext } from "../types.js";
 /**
  * Register assertion tools (1 tool: assert)
  */
-export declare function registerAssertionTools(server: McpServer, { getBrowser }: ToolRegistrationContext): void;
+export declare function registerAssertionTools(server: McpServer, { getBrowser, getBrowserByToken }: ToolRegistrationContext): void;
 //# sourceMappingURL=assertion-tools.d.ts.map

package/dist/mcp-tools/base/assertion-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assertion-tools.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/base/assertion-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAEtE;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,EAAE,UAAU,EAAE,EAAE,uBAAuB,GACtC,IAAI,CAgCN"}
+{"version":3,"file":"assertion-tools.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/base/assertion-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAGtE;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,EAAE,UAAU,EAAE,iBAAiB,EAAE,EAAE,uBAAuB,GACzD,IAAI,CAqDN"}

package/dist/mcp-tools/base/assertion-tools.js

@@ -5,15 +5,22 @@
  * @license MIT
  */
 import { z } from "zod";
+import { refuseUnboundSession } from "../session-policy.js";
 /**
  * Register assertion tools (1 tool: assert)
  */
-export function registerAssertionTools(server, { getBrowser }) {
+export function registerAssertionTools(server, { getBrowser, getBrowserByToken }) {
     server.registerTool("assert", {
         title: "Assert Page State",
         description: "Assert a condition using natural language",
         inputSchema: {
             assertion: z.string().describe("Natural language assertion like \"page contains 'Welcome'\" or \"title is 'Home'\""),
+            // Without this, assert could not bind to the session navigate created on the
+            // HTTP transport: it asserted against a blank page and returned
+            // `passed:false, actual:""`. Worse than a crash — a NEGATIVE assertion
+            // ("page does not contain 'error'") then PASSED against nothing, so a whole
+            // suite could report green while testing an empty browser. (2026-07-28)
+            _browserToken: z.string().optional().describe("Browser session token from a previous tool call"),
         },
         annotations: {
             title: "Assert Page State",
@@ -22,8 +29,23 @@ export function registerAssertionTools(server, { getBrowser }) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ assertion }) => {
-        const b = await getBrowser();
+    }, async ({ assertion, _browserToken }) => {
+        // Adding the token was only half the fix: omitting it entirely still
+        // asserted against a blank page and returned a confident verdict, with a
+        // fresh _browserToken attached that made it look session-backed.
+        const unbound = refuseUnboundSession("assert", { getBrowserByToken }, _browserToken);
+        if (unbound)
+            return unbound;
+        let b;
+        let token;
+        if (getBrowserByToken) {
+            const resolved = await getBrowserByToken(_browserToken);
+            b = resolved.browser;
+            token = resolved.token;
+        }
+        else {
+            b = await getBrowser();
+        }
         const result = await b.assert(assertion);
         return {
             content: [
@@ -34,6 +56,7 @@ export function registerAssertionTools(server, { getBrowser }) {
                         message: result.message,
                         actual: result.actual,
                         expected: result.expected,
+                        ...(token ? { _browserToken: token } : {}),
                     }, null, 2),
                 },
             ],

package/dist/mcp-tools/base/assertion-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"assertion-tools.js","sourceRoot":"","sources":["../../../src/mcp-tools/base/assertion-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAiB,EACjB,EAAE,UAAU,EAA2B;IAEvC,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE;QAC5B,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,2CAA2C;QACxD,WAAW,EAAE;YACX,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oFAAoF,CAAC;SACrH;QACD,WAAW,EAAE;YACX,KAAK,EAAE,mBAAmB;YAC1B,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,KAAK;SACrB;KACF,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;QACvB,MAAM,CAAC,GAAG,MAAM,UAAU,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACzC,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;wBACrB,OAAO,EAAE,MAAM,CAAC,OAAO;wBACvB,MAAM,EAAE,MAAM,CAAC,MAAM;wBACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;qBAC1B,EAAE,IAAI,EAAE,CAAC,CAAC;iBACZ;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"assertion-tools.js","sourceRoot":"","sources":["../../../src/mcp-tools/base/assertion-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAiB,EACjB,EAAE,UAAU,EAAE,iBAAiB,EAA2B;IAE1D,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE;QAC5B,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,2CAA2C;QACxD,WAAW,EAAE;YACX,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oFAAoF,CAAC;YACpH,6EAA6E;YAC7E,gEAAgE;YAChE,uEAAuE;YACvE,4EAA4E;YAC5E,wEAAwE;YACxE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;SACjG;QACD,WAAW,EAAE;YACX,KAAK,EAAE,mBAAmB;YAC1B,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,KAAK;SACrB;KACF,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,EAAE,EAAE;QACtC,qEAAqE;QACrE,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,OAAO,GAAG,oBAAoB,CAAC,QAAQ,EAAE,EAAE,iBAAiB,EAAE,EAAE,aAAa,CAAC,CAAC;QACrF,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;QAE5B,IAAI,CAAC,CAAC;QACN,IAAI,KAAyB,CAAC;QAC9B,IAAI,iBAAiB,EAAE,CAAC;YACtB,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,aAAa,CAAC,CAAC;YACxD,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC;YACrB,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,CAAC,GAAG,MAAM,UAAU,EAAE,CAAC;QACzB,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACzC,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;wBACrB,OAAO,EAAE,MAAM,CAAC,OAAO;wBACvB,MAAM,EAAE,MAAM,CAAC,MAAM;wBACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;wBACzB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBAC3C,EAAE,IAAI,EAAE,CAAC,CAAC;iBACZ;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/mcp-tools/base/audit-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-tools.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/base/audit-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAStE;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,IAAI,CA2jC7F"}
+{"version":3,"file":"audit-tools.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/base/audit-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAmCtE;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,IAAI,CA8mC7F"}

package/dist/mcp-tools/base/audit-tools.js

@@ -7,6 +7,34 @@
 import { z } from "zod";
 import { runAgentReadyAudit, runCompetitiveBenchmark, runEmpathyAudit, runWebMCPReadyAudit, } from "../../analysis/index.js";
 import { listAccessibilityPersonas } from "../../personas.js";
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+/**
+ * Persist an audit screenshot and return its path.
+ *
+ * empathy_audit inlined base64 page screenshots, which routinely overflowed an
+ * MCP client's context and made the tool untestable through a normal client.
+ * Writing them out keeps the overlay data usable without carrying megabytes
+ * through the transport. Returns undefined rather than throwing if the write
+ * fails — a screenshot is not worth failing an audit over. (2026-07-29)
+ */
+function writeAuditScreenshot(base64, persona) {
+    if (!base64)
+        return undefined;
+    try {
+        const dir = join(process.env.CBROWSER_DATA_DIR || join(homedir(), ".cbrowser"), "audit-screenshots");
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const safe = String(persona || "persona").toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+        const path = join(dir, `empathy-${safe}-${Date.now()}.png`);
+        writeFileSync(path, Buffer.from(base64, "base64"));
+        return path;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Register audit tools (4 tools + site_cognitive_assessment + visual_cognitive_story)
  */
@@ -92,6 +120,11 @@ export function registerAuditTools(server, context) {
             wcagLevel: z.enum(["A", "AA", "AAA"]).optional().default("AA").describe("WCAG conformance level"),
             maxSteps: z.number().optional().default(5).describe("Max cognitive journey steps (keep low for MCP)"),
             maxTime: z.number().optional().default(20).describe("Max time per persona in seconds"),
+            // Base64 page screenshots are large enough to blow an MCP client's context
+            // on a single call — every empathy_audit in the 18.73.3 test pass had to be
+            // read off disk instead. Off by default; images go to disk and their paths
+            // are returned. (2026-07-29)
+            includeScreenshots: z.boolean().optional().default(false).describe("Inline base64 page screenshots in the response. Off by default because they are large enough to overflow an MCP client's context; when off, screenshots are written to disk and screenshotPath is returned instead."),
             scope: z.enum(["viewport", "full_page"]).optional().default("viewport").describe("What to score: 'viewport' (first impression, above-the-fold only — default) or 'full_page' (scroll through entire page, all barriers). Use 'viewport' for landing page optimization; 'full_page' for WCAG compliance audits."),
             device: z.string().optional().describe("Device emulation: 'mobile', 'tablet', 'desktop', or specific device like 'iPhone 15', 'Pixel 7'. Essential for mobile WCAG audits — touch targets, viewport sizing, and responsive barriers differ significantly on mobile."),
         },
@@ -102,7 +135,7 @@ export function registerAuditTools(server, context) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ url, goal, disabilities, wcagLevel, maxSteps, maxTime, scope, device }) => {
+    }, async ({ url, goal, disabilities, wcagLevel, maxSteps, maxTime, scope, device, includeScreenshots }) => {
         try {
             // Auto-limit to 1 persona to avoid MCP client timeout on Claude.ai (~60s limit)
             const allPersonas = listAccessibilityPersonas();
@@ -140,11 +173,23 @@ export function registerAuditTools(server, context) {
                         goalAchieved: r.goalAchieved,
                         empathyScore: r.empathyScore,
                         // v18.22.0: Added score context for transparency
+                        // Whitelist projection: anything added to scoreContext upstream is
+                        // invisible to the caller unless named here. The blend breakdown
+                        // below is what lets the deductions reconcile to a score the
+                        // caller can actually see. (2026-07-28)
                         scoreContext: r.scoreContext ? {
                             explanation: r.scoreContext.explanation,
                             deductionsByType: r.scoreContext.deductionsByType,
+                            totalBarrierDeduction: r.scoreContext.totalBarrierDeduction,
                             frictionDeduction: r.scoreContext.frictionDeduction,
                             goalDeduction: r.scoreContext.goalDeduction,
+                            cognitiveOverloadPenalty: r.scoreContext.cognitiveOverloadPenalty,
+                            appliedBarrierWeights: r.scoreContext.appliedBarrierWeights,
+                            explainsScore: r.scoreContext.explainsScore,
+                            barrierOnlyScore: r.scoreContext.barrierOnlyScore,
+                            perceptualScore: r.scoreContext.perceptualScore,
+                            blendWeights: r.scoreContext.blendWeights,
+                            finalScore: r.scoreContext.finalScore,
                         } : undefined,
                         barrierTypeCount: uniqueTypes.size,
                         barrierTypes: Array.from(uniqueTypes),
@@ -155,6 +200,10 @@ export function registerAuditTools(server, context) {
                         empathyScoreBarrierOnly: r.empathyScoreBarrierOnly || undefined,
                         // v18.27.0: Cognitive load estimation (optimal transport)
                         cognitiveLoad: r.cognitiveLoad || undefined,
+                        // Names the three different "cognitive load" numbers in this
+                        // payload and what each measures. Same whitelist caveat as
+                        // scoreContext above: set upstream, invisible unless named here.
+                        cognitiveLoadReadings: r.cognitiveLoadReadings || undefined,
                         // v18.28.0: Attention transport analysis (W₂ saliency)
                         attentionAnalysis: r.attentionAnalysis || undefined,
                         // v18.29.0: Journey validation — evidence, path, forensics
@@ -171,14 +220,42 @@ export function registerAuditTools(server, context) {
                 // v18.60.0: Include per-result screenshots and element rects for WCAG overlay
                 pageScreenshots: result.results?.map((r) => ({
                     persona: r.persona,
-                    screenshot: r.pageScreenshot,
+                    ...(includeScreenshots
+                        ? { screenshot: r.pageScreenshot }
+                        : {
+                            screenshotPath: writeAuditScreenshot(r.pageScreenshot, r.persona),
+                            screenshotNote: "Pass includeScreenshots:true to inline the base64 instead.",
+                        }),
                     viewportSize: r.viewportSize,
-                    barrierRects: r.barriers?.filter((b) => b.rect).map((b) => ({
-                        type: b.type, severity: b.severity, element: b.element,
-                        description: b.description, rect: b.rect,
-                        wcag: b.wcagCriteria,
-                    })),
-                })).filter((s) => s.screenshot),
+                    // Rects come from getBoundingClientRect with no scroll compensation,
+                    // so they are VIEWPORT coordinates — which is correct here, because
+                    // the screenshot above is captured with fullPage: false and these are
+                    // meant to overlay it. Converting them to document coordinates would
+                    // break that alignment.
+                    //
+                    // The real hazard is scope: "full_page", where the audit scrolls and
+                    // rects captured at different offsets land in one list against a
+                    // single viewport image; anything above the captured viewport then
+                    // carries a negative y and would render off-canvas. Say which space
+                    // these are in and flag the ones that fall outside the image rather
+                    // than emitting silent negatives. (2026-07-28)
+                    coordinateSpace: "viewport",
+                    barrierRects: r.barriers?.filter((b) => b.rect).map((b) => {
+                        const vp = r.viewportSize;
+                        const outside = !!vp && !!b.rect && (b.rect.y + b.rect.height < 0 || b.rect.x + b.rect.width < 0 ||
+                            b.rect.y > vp.height || b.rect.x > vp.width);
+                        return {
+                            type: b.type, severity: b.severity, element: b.element,
+                            description: b.description, rect: b.rect,
+                            wcag: b.wcagCriteria,
+                            ...(outside ? { outsideScreenshot: true } : {}),
+                        };
+                    }),
+                    // Keep entries that carry EITHER the inline image or a path to it.
+                    // Filtering on `screenshot` alone silently dropped every entry once
+                    // the default stopped inlining base64, taking the barrierRects with
+                    // them. (2026-07-29)
+                })).filter((s) => s.screenshot || s.screenshotPath),
             };
             // Add guidance if we limited the request
             if (wasLimited) {