cbrowser 18.73.2 → 18.74.0

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;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAoDtE;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,IAAI,CA4rC7F"}

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

@@ -5,8 +5,52 @@
  * @license MIT
  */
 import { z } from "zod";
+import { randomBytes } from "crypto";
+import { htmlUiResource, attachUiResource, uiResourcesEnabled } from "../../mcp-ui-resources.js";
+import { writeArtifact } from "../../artifact-store.js";
 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 {};
+    const safe = String(persona || "persona").toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+    const out = {};
+    // Local copy, as before — the CLI and anything on this box reads this.
+    try {
+        const dir = join(process.env.CBROWSER_DATA_DIR || join(homedir(), ".cbrowser"), "audit-screenshots");
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const path = join(dir, `empathy-${safe}-${Date.now()}.png`);
+        writeFileSync(path, Buffer.from(base64, "base64"));
+        out.path = path;
+    }
+    catch { /* a screenshot is not worth failing an audit over */ }
+    // Served copy, so the barrier overlay has an image an MCP host can fetch.
+    // The name carries 12 random hex chars rather than only a timestamp: these
+    // are captures of a CUSTOMER'S page served from a public path, and a
+    // timestamped name is guessable by anyone who knows roughly when an audit
+    // ran. Unguessability is the only access control this path has. (2026-07-29)
+    try {
+        const nonce = randomBytes(6).toString("hex");
+        const written = writeArtifact(Buffer.from(base64, "base64"), `empathy-${safe}-${nonce}.png`);
+        if (written)
+            out.url = written.url;
+    }
+    catch { /* overlay is optional; the audit is not */ }
+    return out;
+}
 /**
  * Register audit tools (4 tools + site_cognitive_assessment + visual_cognitive_story)
  */
@@ -92,8 +136,14 @@ 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."),
+            uiResource: z.boolean().optional().default(true).describe("Return an interactive HTML report as an MCP UI resource alongside the JSON. Hosts that support MCP Apps render it inline; others ignore it. Set false for scripted callers that diff whole responses."),
         },
         annotations: {
             title: "Empathy Accessibility Audit",
@@ -102,7 +152,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, uiResource }) => {
         try {
             // Auto-limit to 1 persona to avoid MCP client timeout on Claude.ai (~60s limit)
             const allPersonas = listAccessibilityPersonas();
@@ -140,11 +190,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 +217,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
@@ -166,34 +232,123 @@ export function registerAuditTools(server, context) {
                 }),
                 allWcagViolations: result.allWcagViolations,
                 topBarriers: result.topBarriers.slice(0, 5),
+                // A barrier's affectedPersonas names the personas it hits HARDEST. It
+                // is not an exclusion list, which is why a persona absent from it can
+                // still take a deduction — susceptibility is applied as a weight, not
+                // a gate (see scoreContext.appliedBarrierWeights). Stating it here
+                // because the pairing otherwise reads as a contradiction: a
+                // touch_target barrier listing motor and elderly personas, scored
+                // against cognitive-adhd. (2026-07-29)
+                barrierFieldNotes: {
+                    affectedPersonas: "Exemplars — the personas this barrier affects most. NOT an exclusion list; every tested persona is scored against every barrier, weighted by susceptibility.",
+                    severity: "On topBarriers entries this is the group maximum across all elements of that type (severityIsGroupMax), not one element's severity.",
+                },
                 topRemediation: result.combinedRemediation.slice(0, 5),
                 duration: result.duration,
                 // 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 }
+                        : (() => {
+                            const shot = writeAuditScreenshot(r.pageScreenshot, r.persona);
+                            return {
+                                screenshotPath: shot.path,
+                                screenshotUrl: shot.url,
+                                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)
+                    // Rects are now DOCUMENT coordinates (scroll offset added at capture),
+                    // so they are stable across the scrolling that scope:"full_page" does.
+                    // They were previously labelled "viewport" while holding values from
+                    // several scroll positions at once — y:-274 and y:3951 in one list.
+                    coordinateSpace: "document",
+                    // Height of the captured image in document space. A viewport capture
+                    // covers only the scroll position it was taken at; a full_page capture
+                    // covers the document. Without this the bounds test compared document
+                    // coordinates against a viewport height and flagged EVERY rect,
+                    // including ones plainly inside the image. (2026-07-29)
+                    captureHeight: (scope === "full_page" ? (r.documentHeight ?? undefined) : r.viewportSize?.height),
+                    barrierRects: r.barriers?.filter((b) => b.rect).map((b) => {
+                        const vp = r.viewportSize;
+                        const bound = scope === "full_page" ? (r.documentHeight ?? Infinity) : (vp?.height ?? Infinity);
+                        const outside = !!b.rect && (b.rect.y + b.rect.height < 0 || b.rect.x + b.rect.width < 0 ||
+                            b.rect.y > bound || (!!vp && 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) {
                 response.note = `Limited to 1 persona to avoid timeout. For full coverage, call again with: ${remainingPersonas.slice(0, 3).join(", ")}${remainingPersonas.length > 3 ? `, and ${remainingPersonas.length - 3} more` : ""}`;
                 response.remainingPersonas = remainingPersonas;
             }
-            // Auto-save handled by tier-gate wrapper
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(response, null, 2),
-                    },
-                ],
-            };
+            // Auto-save handled by tier-gate wrapper.
+            //
+            // The UI resource is APPENDED to the text block, never substituted for
+            // it: content[0] stays the same JSON every CLI and CI caller already
+            // parses. `generateEmpathyAuditHtmlReport` is the report the --html flag
+            // has always produced — self-contained, no remote refs — so this is a
+            // transport seam rather than new UI. If it cannot be produced safely,
+            // htmlUiResource returns null and the response is exactly as before.
+            // (2026-07-29)
+            const content = [
+                { type: "text", text: JSON.stringify(response, null, 2) },
+            ];
+            if (uiResourcesEnabled(uiResource)) {
+                // The overlay goes FIRST. It is the thing that makes a score
+                // falsifiable by eye — barriers drawn on the page at their real
+                // positions — and the text report is the detail behind it.
+                try {
+                    const { buildBarrierOverlayHtml } = await import("../../visual/barrier-overlay-html.js");
+                    const shots = (response.pageScreenshots ?? []);
+                    for (const shot of shots) {
+                        const overlayHtml = buildBarrierOverlayHtml({
+                            imageUrl: shot.screenshotUrl,
+                            imageWidth: shot.viewportSize?.width,
+                            captureHeight: shot.captureHeight ?? shot.viewportSize?.height,
+                            barrierRects: shot.barrierRects ?? [],
+                            persona: String(shot.persona ?? testedPersona),
+                            pageUrl: String(result.url),
+                            score: result.overallScore,
+                        });
+                        attachUiResource(content, htmlUiResource(`ui://cbrowser/barrier-overlay/${encodeURIComponent(String(shot.persona ?? testedPersona))}`, overlayHtml ?? undefined, { frameSize: ["100%", "820px"] }));
+                    }
+                }
+                catch { /* overlay is additive; never fail the audit for it */ }
+                let reportHtml;
+                try {
+                    const { generateEmpathyAuditHtmlReport } = await import("../../analysis/accessibility-empathy.js");
+                    reportHtml = generateEmpathyAuditHtmlReport(result);
+                }
+                catch {
+                    reportHtml = undefined;
+                }
+                attachUiResource(content, htmlUiResource(`ui://cbrowser/empathy-audit/${encodeURIComponent(testedPersona)}`, reportHtml, { frameSize: ["100%", "760px"] }));
+            }
+            return { content };
         }
         catch (error) {
             // Categorize the error for better user feedback
@@ -747,9 +902,11 @@ export function registerAuditTools(server, context) {
                 const page = await browser.getPage();
                 const ssPath = join(tmpdir(), `story-${Date.now()}.png`);
                 await page.screenshot({ path: ssPath, fullPage: false });
-                const webDir = "/var/www/cbrowser-web/heatmaps";
-                if (!existsSync(webDir))
-                    mkdirSync(webDir, { recursive: true });
+                // webDir removed: this pointed at /var/www/cbrowser-web/heatmaps, a
+                // FIFTH directory nginx does not serve (it serves /heatmaps/ from
+                // /var/www/cbrowser-data/heatmaps). All four story overlays below wrote
+                // there and returned cbrowser.ai URLs that 404'd. (2026-07-29)
+                // (directory creation is the artifact store's job now)
                 const ts = Date.now();
                 const images = [];
                 const urls = {};
@@ -768,8 +925,9 @@ export function registerAuditTools(server, context) {
                         const { generateHeatmapOverlay } = await import("../../visual/heatmap-overlay.js");
                         const heatB64 = await generateHeatmapOverlay(ssPath, attnResult.saliencyMap.cells, attnResult.saliencyMap.rows, attnResult.saliencyMap.cols, `${persona} Attention`);
                         const heatId = `story-attn-${persona}-${ts}`;
-                        writeFileSync(join(webDir, `${heatId}.png`), Buffer.from(heatB64, "base64"));
-                        urls.attention = `https://cbrowser.ai/heatmaps/${heatId}.png`;
+                        const w_attention = writeArtifact(Buffer.from(heatB64, "base64"), `${heatId}.png`);
+                        if (w_attention)
+                            urls.attention = w_attention.url;
                         images.push({ type: "image", data: heatB64, mimeType: "image/png" });
                         // Auto-save to gallery
                         try {
@@ -815,8 +973,9 @@ export function registerAuditTools(server, context) {
                     const cssVW = await page.evaluate(() => window.innerWidth).catch(() => 1920);
                     const motorB64 = await generateMotorOverlay(ssPath, motorElements, persona, cssVW);
                     const motorId = `story-motor-${persona}-${ts}`;
-                    writeFileSync(join(webDir, `${motorId}.png`), Buffer.from(motorB64, "base64"));
-                    urls.motor = `https://cbrowser.ai/heatmaps/${motorId}.png`;
+                    const w_motor = writeArtifact(Buffer.from(motorB64, "base64"), `${motorId}.png`);
+                    if (w_motor)
+                        urls.motor = w_motor.url;
                     images.push({ type: "image", data: motorB64, mimeType: "image/png" });
                     try {
                         const { saveVisualReport } = await import("../visual-report-saver.js");
@@ -892,8 +1051,9 @@ export function registerAuditTools(server, context) {
                             const cssVW2 = await page.evaluate(() => window.innerWidth).catch(() => 1920);
                             const qualB64 = await generateAttentionQualityOverlay(ssPath, overlayTargets, persona, cssVW2);
                             const qualId = `story-quality-${persona}-${ts}`;
-                            writeFileSync(join(webDir, `${qualId}.png`), Buffer.from(qualB64, "base64"));
-                            urls.quality = `https://cbrowser.ai/heatmaps/${qualId}.png`;
+                            const w_quality = writeArtifact(Buffer.from(qualB64, "base64"), `${qualId}.png`);
+                            if (w_quality)
+                                urls.quality = w_quality.url;
                             images.push({ type: "image", data: qualB64, mimeType: "image/png" });
                             try {
                                 const { saveVisualReport } = await import("../visual-report-saver.js");
@@ -963,8 +1123,9 @@ export function registerAuditTools(server, context) {
                     const cssVW3 = await page.evaluate(() => window.innerWidth).catch(() => 1920);
                     const combinedB64 = await generateCombinedStoryOverlay(ssPath, attentionData?.saliencyMap?.cells ?? null, attentionData?.saliencyMap?.rows ?? 0, attentionData?.saliencyMap?.cols ?? 0, motorEls, qualTargets, persona, cssVW3);
                     const combId = `story-combined-${persona}-${ts}`;
-                    writeFileSync(join(webDir, `${combId}.png`), Buffer.from(combinedB64, "base64"));
-                    urls.combined = `https://cbrowser.ai/heatmaps/${combId}.png`;
+                    const w_combined = writeArtifact(Buffer.from(combinedB64, "base64"), `${combId}.png`);
+                    if (w_combined)
+                        urls.combined = w_combined.url;
                     images.push({ type: "image", data: combinedB64, mimeType: "image/png" });
                     try {
                         const { saveVisualReport } = await import("../visual-report-saver.js");