cbrowser 19.3.7 → 19.3.9

package/dist/browser.js

@@ -204,6 +204,21 @@ export class CBrowser {
     static MAX_PENDING_REQUESTS = 2000;
     harEntries = [];
     isRecordingHar = false;
+    /**
+     * Console capture, one ring buffer per tab (v8 B27, 2026-10-10). Filled by a
+     * single page.on("console") + page.on("pageerror") pair attached when the tab
+     * is created, so it holds what was logged during page load and what the
+     * browser itself reports (a 404 is "Failed to load resource", not a console.*
+     * call). Measured on 19.3.6: get_console_messages returned [] for a page that
+     * had logged and 404'd, because it patched console.* on its first call; and
+     * navigate added a listener per call (6 -> 9 over three navigates). Keyed by
+     * Page so a tab switched to by manage_tabs reads its own buffer.
+     */
+    consoleBuffers = new WeakMap();
+    /** Increases on every captured message, across tabs; navigate slices by it. */
+    consoleSeq = 0;
+    static CONSOLE_BUFFER_CAP = 500;
+    static CONSOLE_TEXT_CAP = 2000;
     skipSessionRestore;
     // Modular components (extracted for maintainability)
     sessionManager;
@@ -616,6 +631,15 @@ For more help: https://playwright.dev/docs/browsers
                     console.log(`🌐 Using proxy: ${this.config.proxy.server}`);
                 }
             }
+            // Console capture for every tab of this context: the ones open now, and
+            // any opened later by the site (popups), followPopups, or manage_tabs,
+            // which calls context.newPage() directly (v8 B27, 2026-10-10).
+            const ctx = this.context;
+            if (ctx) {
+                ctx.on("page", (p) => this.attachConsoleCapture(p));
+                for (const p of ctx.pages())
+                    this.attachConsoleCapture(p);
+            }
             // Live-journey mode: when a click opens a new tab, swap the journey's
             // active page to it and bring it to the front so VNC stream follows.
             // Closes the old page after a short grace period so its DOM is freed.
@@ -1354,6 +1378,95 @@ For more help: https://playwright.dev/docs/browsers
         this.pendingRequests.clear();
     }
     // =========================================================================
+    // Console Capture (v8 B27)
+    // =========================================================================
+    /**
+     * Give a tab its one console + pageerror listener pair. Idempotent.
+     *
+     * The buffer is NOT reset on navigation (decided 2026-10-10, v8 B27). A flow
+     * that submits a form and lands on a confirmation page would otherwise lose
+     * the form page's errors, which are usually what the caller is looking for,
+     * and Playwright's public API cannot tell a new document from a pushState
+     * route change, so a reset would also wipe an SPA's load errors on its first
+     * client-side navigation. Each entry carries pageUrl instead; clear starts
+     * fresh.
+     */
+    attachConsoleCapture(page) {
+        if (this.consoleBuffers.has(page))
+            return;
+        const buffer = { entries: [], dropped: 0 };
+        this.consoleBuffers.set(page, buffer);
+        const push = (msg) => {
+            if (msg.text.length > CBrowser.CONSOLE_TEXT_CAP) {
+                const extra = msg.text.length - CBrowser.CONSOLE_TEXT_CAP;
+                msg.text = `${msg.text.slice(0, CBrowser.CONSOLE_TEXT_CAP)}... [${extra} more characters]`;
+            }
+            buffer.entries.push({ seq: ++this.consoleSeq, msg });
+            if (buffer.entries.length > CBrowser.CONSOLE_BUFFER_CAP) {
+                buffer.entries.shift();
+                buffer.dropped++;
+            }
+        };
+        const pageUrl = () => {
+            try {
+                return page.url();
+            }
+            catch {
+                return "";
+            }
+        };
+        page.on("console", (m) => {
+            let loc;
+            try {
+                loc = m.location();
+            }
+            catch { /* no location */ }
+            push({
+                type: m.type(),
+                text: m.text(),
+                timestamp: Date.now(),
+                source: "console",
+                // For "Failed to load resource" Chrome puts the failed resource here,
+                // not in the text (same finding as hunt_bugs v5 B24).
+                ...(loc?.url ? { url: loc.url, lineNumber: loc.lineNumber } : {}),
+                pageUrl: pageUrl(),
+            });
+        });
+        page.on("pageerror", (err) => {
+            push({
+                type: "error",
+                text: `${err.name || "Error"}: ${err.message}`,
+                timestamp: Date.now(),
+                source: "pageerror",
+                pageUrl: pageUrl(),
+            });
+        });
+    }
+    /**
+     * The current tab's console messages, oldest first: the latest 500 since the
+     * tab opened or since clearConsoleMessages(), across navigations, including
+     * uncaught exceptions (source "pageerror") and browser-generated messages
+     * such as a resource 404. `dropped` counts older ones the ring evicted.
+     */
+    getConsoleMessages() {
+        const buffer = this.page ? this.consoleBuffers.get(this.page) : undefined;
+        if (!buffer)
+            return { messages: [], dropped: 0 };
+        return { messages: buffer.entries.map((e) => ({ ...e.msg })), dropped: buffer.dropped };
+    }
+    /** Empty the current tab's console buffer and its dropped count. */
+    clearConsoleMessages() {
+        const buffer = this.page ? this.consoleBuffers.get(this.page) : undefined;
+        if (buffer) {
+            buffer.entries = [];
+            buffer.dropped = 0;
+        }
+    }
+    /** What a tab logged after sequence number `afterSeq` (navigate's own slice). */
+    consoleMessagesSince(page, afterSeq) {
+        return (this.consoleBuffers.get(page)?.entries ?? []).filter((e) => e.seq > afterSeq).map((e) => e.msg);
+    }
+    // =========================================================================
     // Performance Metrics
     // =========================================================================
     /**
@@ -1421,6 +1534,14 @@ For more help: https://playwright.dev/docs/browsers
             const resources = performance.getEntriesByType("resource");
             result.resourceCount = resources.length;
             result.transferSize = resources.reduce((sum, r) => sum + (r.transferSize || 0), 0);
+            // Timings are high-resolution DOMHighResTimeStamps (ttfb printed as
+            // 53.69999998807907): whole milliseconds, and CLS to 4 dp. (v8 B41)
+            for (const k of ["ttfb", "domContentLoaded", "load", "fcp", "lcp"]) {
+                if (typeof result[k] === "number")
+                    result[k] = Math.round(result[k]);
+            }
+            if (typeof result.cls === "number")
+                result.cls = Math.round(result.cls * 10000) / 10000;
             return result;
         });
         // Rate the metrics
@@ -1699,17 +1820,27 @@ For more help: https://playwright.dev/docs/browsers
         const page = await this.getPage();
         this.skipSessionRestore = prevSkip;
         const startTime = Date.now();
-        const errors = [];
         const warnings = [];
-        // Capture console errors
-        page.on("console", (msg) => {
-            if (msg.type() === "error") {
-                errors.push(msg.text());
-            }
-            else if (msg.type() === "warning") {
-                warnings.push(msg.text());
+        // This navigation's console errors and warnings are the tab's capture
+        // buffer sliced from here (v8 B27, 2026-10-10). The page.on("console") that
+        // used to be added here was never removed, so every navigate left one more
+        // listener on the tab (measured 6 -> 9 over three calls). Uncaught
+        // exceptions stay out of `errors`, as before. The attach is a no-op for any
+        // tab this CBrowser opened; it covers a page swapped in from elsewhere.
+        this.attachConsoleCapture(page);
+        const consoleStart = this.consoleSeq;
+        const loggedHere = () => {
+            const logged = { errors: [], warnings: [] };
+            for (const m of this.consoleMessagesSince(page, consoleStart)) {
+                if (m.source !== "console")
+                    continue;
+                if (m.type === "error")
+                    logged.errors.push(m.text);
+                else if (m.type === "warning")
+                    logged.warnings.push(m.text);
             }
-        });
+            return logged;
+        };
         // v11.3.0: Configurable wait strategy
         const waitStrategy = options.waitStrategy || "auto";
         const waitTimeout = options.waitTimeout ?? 10000;
@@ -1839,12 +1970,13 @@ For more help: https://playwright.dev/docs/browsers
             if (this.config.verbose) {
                 console.log(`⚠️ Page context desync detected: expected ${expectedHost}, got ${actualHost}`);
             }
+            const logged = loggedHere();
             return {
                 url: actualUrl,
                 title: actualTitle,
                 screenshot,
-                errors: [...errors, `Page context desync: navigated to ${url} but landed on ${actualUrl}`],
-                warnings: [...warnings, `Expected domain: ${expectedHost}, Actual domain: ${actualHost}`],
+                errors: [...logged.errors, `Page context desync: navigated to ${url} but landed on ${actualUrl}`],
+                warnings: [...logged.warnings, ...warnings, `Expected domain: ${expectedHost}, Actual domain: ${actualHost}`],
                 loadTime,
                 success: false,
                 desyncDetected: true,
@@ -1852,12 +1984,13 @@ For more help: https://playwright.dev/docs/browsers
             };
         }
         const screenshot = await this.screenshot();
+        const logged = loggedHere();
         return {
             url: actualUrl,
             title: actualTitle,
             screenshot,
-            errors,
-            warnings,
+            errors: logged.errors,
+            warnings: [...logged.warnings, ...warnings],
             loadTime,
             success: true,
             ...(waitSelectorTimedOut ? { waitSelectorTimedOut: true } : {}),
@@ -3506,7 +3639,7 @@ For more help: https://playwright.dev/docs/browsers
         }
         const page = await this.getPage();
         const analysis = await this.analyzePage();
-        const tests = this.generateTestScenarios(analysis);
+        const tests = this.generateTestScenarios(analysis, await this.clickTargetZones(analysis));
         return {
             url: page.url(),
             analysis,
@@ -3515,6 +3648,38 @@ For more help: https://playwright.dev/docs/browsers
             playwrightCode: this.generatePlaywrightCode(tests, page.url()),
         };
     }
+    /**
+     * The click gate's zone for every element generate_tests might click, keyed by selector: the selector
+     * string as click() judges it, the element's names, and the element itself through elementZone (the
+     * gate's own classifyElement, so a benign label on a button whose form posts to /account/delete is still
+     * red). The generator used to click whatever it found: a fixture with a "Delete account" button got
+     * `click text="Delete account"` as an unremarked step, which nl_test_inline then refuses, and the
+     * Playwright export would simply run. (v8 b39, 2026-10-10)
+     */
+    async clickTargetZones(analysis) {
+        const zones = new Map();
+        const candidates = [
+            ...analysis.buttons,
+            ...analysis.links,
+            ...analysis.forms.map(f => f.submitButton).filter((b) => !!b),
+        ].filter(el => !el.hidden && !el.inPage);
+        for (const el of candidates) {
+            // ignoreBlack throughout: the gate refuses red only, and black words describe an instruction, not a
+            // control (the classifyElement rule), so a black match must not mask a red one.
+            let zone = zones.get(el.selector) ?? "yellow";
+            for (const name of [el.selector, el.text, el.ariaLabel]) {
+                if (name)
+                    zone = this.maxZone(zone, this.classifyAction("click", name, { ignoreBlack: true }));
+            }
+            if (!zones.has(el.selector)) {
+                const judged = await this.elementZone(el.selector).catch(() => null);
+                if (judged)
+                    zone = this.maxZone(zone, judged.zone);
+            }
+            zones.set(el.selector, zone);
+        }
+        return zones;
+    }
     /**
      * Analyze page structure for testable elements.
      */
@@ -3548,9 +3713,68 @@ For more help: https://playwright.dev/docs/browsers
                     return `text="${text}"`;
                 return el.tagName.toLowerCase();
             };
+            // What a user cannot see, flagged so generate_tests makes no step of it: no box at all (display:none
+            // here or on an ancestor, <input type=hidden>), visibility:hidden, a 1-2px box (sr-only), parked
+            // off-screen (left:-9999px, top:-40px, translateY(-100%)), or clipped the sr-only way. The clip and
+            // class rules are empathy_audit's target exemptions (accessibility-empathy.ts). The generator turned
+            // a skip link into "Click Skip to content". (v8 b39, 2026-10-10)
+            const srOnly = (el, style) => ((style.position === "absolute" || style.position === "fixed") &&
+                (style.clip === "rect(0px, 0px, 0px, 0px)" || style.clip === "rect(1px, 1px, 1px, 1px)" || style.clipPath === "inset(50%)")) ||
+                el.classList.contains("sr-only") || el.classList.contains("visually-hidden") || el.classList.contains("screen-reader-text");
+            const hiddenFromView = (el) => {
+                if (el.getClientRects().length === 0)
+                    return true;
+                // opacity:0 here or on an ancestor, and content-visibility:hidden, where the engine can say so.
+                if (typeof el.checkVisibility === "function" && !el.checkVisibility({ opacityProperty: true, visibilityProperty: true }))
+                    return true;
+                const style = getComputedStyle(el);
+                if (style.visibility === "hidden" || style.visibility === "collapse")
+                    return true;
+                if (style.opacity === "0")
+                    return true;
+                const rect = el.getBoundingClientRect();
+                if (rect.width <= 2 || rect.height <= 2)
+                    return true;
+                if (rect.right + window.scrollX <= 0 || rect.bottom + window.scrollY <= 0)
+                    return true;
+                if (srOnly(el, style))
+                    return true;
+                // A wrapper hides what it holds: a link inside an sr-only div keeps its own full-size box, and became
+                // `click text="Hidden child link"` plus a url assertion; a button at opacity:0 was clicked. So every
+                // ancestor is judged too: sr-only (clipped or classed), opacity:0 (for engines without
+                // checkVisibility), or a 1-2px box that clips its overflow. display:contents has no box to measure.
+                // (v8 b39, 2026-10-10)
+                for (let p = el.parentElement; p && p !== document.documentElement; p = p.parentElement) {
+                    const s = getComputedStyle(p);
+                    if (s.display === "contents")
+                        continue;
+                    if (srOnly(p, s) || s.opacity === "0")
+                        return true;
+                    if (s.overflowX !== "visible" || s.overflowY !== "visible") {
+                        const r = p.getBoundingClientRect();
+                        if (r.width <= 2 || r.height <= 2)
+                            return true;
+                    }
+                }
+                return false;
+            };
+            // A link to a fragment of this same page ("#main", "#") scrolls or moves focus; it never navigates.
+            const inPageLink = (el) => {
+                if (!(el.getAttribute("href") || "").includes("#"))
+                    return false;
+                try {
+                    const u = new URL(el.href);
+                    return u.origin + u.pathname + u.search === location.origin + location.pathname + location.search;
+                }
+                catch {
+                    return false;
+                }
+            };
+            const visibility = (el) => (hiddenFromView(el) ? { hidden: true } : {});
             // Analyze forms
             const forms = Array.from(document.querySelectorAll("form")).map(form => {
                 const fields = Array.from(form.querySelectorAll("input, select, textarea")).map(el => ({
+                    ...visibility(el),
                     type: el.tagName.toLowerCase(),
                     selector: getSelector(el),
                     name: el.getAttribute("name") || undefined,
@@ -3562,6 +3786,7 @@ For more help: https://playwright.dev/docs/browsers
                 }));
                 const submitBtn = form.querySelector('button[type="submit"], input[type="submit"]');
                 const submitButton = submitBtn ? {
+                    ...visibility(submitBtn),
                     type: "button",
                     selector: getSelector(submitBtn),
                     text: submitBtn.textContent?.trim(),
@@ -3646,6 +3871,7 @@ For more help: https://playwright.dev/docs/browsers
             const buttons = Array.from(document.querySelectorAll('button, [role="button"], input[type="button"]'))
                 .slice(0, 20)
                 .map(el => ({
+                ...visibility(el),
                 type: "button",
                 selector: getSelector(el),
                 text: el.textContent?.trim(),
@@ -3657,6 +3883,8 @@ For more help: https://playwright.dev/docs/browsers
             const links = Array.from(document.querySelectorAll("a[href]"))
                 .slice(0, 20)
                 .map(el => ({
+                ...visibility(el),
+                ...(inPageLink(el) ? { inPage: true } : {}),
                 type: "link",
                 selector: getSelector(el),
                 text: el.textContent?.trim(),
@@ -3708,57 +3936,118 @@ For more help: https://playwright.dev/docs/browsers
     }
     /**
      * Generate test scenarios from page analysis.
+     *
+     * zones: the click gate's zone per selector (clickTargetZones). A red control is never an exploratory
+     * click: it is left out and named in the test's notes. A form's own submit that is red stays (the test
+     * means nothing without it) but is marked zone "red" and says it will be refused. Hidden elements and
+     * in-page links make no step at all. (v8 b39, 2026-10-10)
      */
-    generateTestScenarios(analysis) {
+    generateTestScenarios(analysis, zones = new Map()) {
         const tests = [];
+        const isRed = (target) => (zones.get(target) ?? this.classifyAction("click", target, { ignoreBlack: true })) === "red";
+        const REFUSED = "the click gate refuses it without force: true, and NL test steps never pass force";
+        const clickStep = (target, description) => isRed(target)
+            ? { action: "click", target, description: `${description} (red zone: ${REFUSED})`, zone: "red" }
+            : { action: "click", target, description };
+        // The first n elements that are not red; each red one passed over is named in notes.
+        const notRed = (els, n, notes) => {
+            const picked = [];
+            for (const el of els) {
+                if (picked.length >= n)
+                    break;
+                if (isRed(el.selector)) {
+                    // One line: a note is emitted as a comment, and a newline from textContent would end the comment
+                    // and leave the rest as a script step or as Playwright code.
+                    const note = `Not clicked: "${el.text || el.ariaLabel || el.selector}" (${el.selector}) is a red-zone control; ${REFUSED}.`;
+                    notes.push(note.replace(/\s+/g, " "));
+                    continue;
+                }
+                picked.push(el);
+            }
+            return picked;
+        };
+        // Notes ride on the test they explain; when every candidate was red there is no such test, and they
+        // ride on the smoke test instead, so the caller still learns the control exists.
+        const unplaced = [];
+        const withNotes = (test, notes) => (notes.length ? { ...test, notes } : test);
+        // A form's submit click, or none. A submit hidden from view is no target: falling back to the bare word
+        // made `click Search` and `page.locator('Search')`, which resolve to nothing (6fbeda6 clicked the hidden
+        // button itself). The NL dialect has no key press ("press Enter" parses as a click on "Enter"), so there
+        // is no Enter step to offer instead: the click is left out and a note says why. A form with no submit
+        // button at all keeps the word fallback it had before. (v8 b39, 2026-10-10)
+        const submitSteps = (form, fallback, description) => form.submitButton?.hidden ? [] : [clickStep(form.submitButton?.selector || fallback, description)];
+        const submitNotes = (form) => {
+            const btn = form.submitButton;
+            if (!btn?.hidden)
+                return [];
+            const note = `Not clicked: the form's submit "${btn.text || btn.selector}" (${btn.selector}) is hidden from view, and NL test steps have no key press; submit it by pressing Enter in the last field.`;
+            return [note.replace(/\s+/g, " ")];
+        };
         // Generate form tests
         for (const form of analysis.forms) {
+            // A form whose every field is hidden (a collapsed search drawer) is not one a user can fill.
+            const fields = form.fields.filter(f => !f.hidden);
+            if (form.fields.length > 0 && fields.length === 0)
+                continue;
+            const formNotes = submitNotes(form);
             if (form.purpose === "login") {
-                tests.push({
+                tests.push(withNotes({
                     name: "Login Form Submission",
                     description: "Test the login form with valid credentials",
                     steps: [
                         { action: "navigate", target: analysis.url, description: "Navigate to page" },
-                        ...form.fields.filter(f => f.inputType !== "submit").map(f => ({
+                        ...fields.filter(f => f.inputType !== "submit").map(f => ({
                             action: "fill",
                             target: f.selector,
                             value: f.inputType === "email" ? "test@example.com" : f.inputType === "password" ? "TestPassword123" : "test value",
                             description: `Fill ${f.name || f.placeholder || "field"}`,
                         })),
-                        { action: "click", target: form.submitButton?.selector || "Submit", description: "Submit form" },
+                        ...submitSteps(form, "Submit", "Submit form"),
                         { action: "wait", value: "1000", description: "Wait for response" },
                     ],
                     assertions: ["url contains '/dashboard' OR url contains '/home'", "page does not contain 'error'"],
-                });
-                tests.push({
+                }, formNotes));
+                tests.push(withNotes({
                     name: "Login Form Validation",
                     description: "Test login form with invalid credentials",
                     steps: [
                         { action: "navigate", target: analysis.url, description: "Navigate to page" },
-                        { action: "fill", target: form.fields.find(f => f.inputType === "email")?.selector || "", value: "invalid", description: "Enter invalid email" },
-                        { action: "click", target: form.submitButton?.selector || "Submit", description: "Submit form" },
+                        { action: "fill", target: fields.find(f => f.inputType === "email")?.selector || "", value: "invalid", description: "Enter invalid email" },
+                        ...submitSteps(form, "Submit", "Submit form"),
                     ],
                     assertions: ["page contains 'error' OR page contains 'invalid'"],
-                });
+                }, formNotes));
             }
             if (form.purpose === "search") {
-                tests.push({
+                tests.push(withNotes({
                     name: "Search Functionality",
                     description: "Test search with a query",
                     steps: [
                         { action: "navigate", target: analysis.url, description: "Navigate to page" },
-                        { action: "fill", target: form.fields[0]?.selector || "[type='search']", value: "test query", description: "Enter search term" },
-                        { action: "click", target: form.submitButton?.selector || "Search", description: "Submit search" },
+                        { action: "fill", target: fields[0]?.selector || "[type='search']", value: "test query", description: "Enter search term" },
+                        ...submitSteps(form, "Search", "Submit search"),
                     ],
                     assertions: ["url contains 'search' OR url contains 'q='", "page contains 'result'"],
-                });
+                }, formNotes));
             }
         }
         // Generate navigation tests
         if (analysis.hasNavigation) {
-            const navLinks = analysis.links.filter(l => l.href?.startsWith(analysis.url.split("/").slice(0, 3).join("/")));
+            // Not a skip link or any other "#fragment" link (it never navigates), nothing a user cannot see, and
+            // no red control.
+            const navNotes = [];
+            const navLinks = notRed(analysis.links.filter(l => l.href?.startsWith(analysis.url.split("/").slice(0, 3).join("/")) && !l.hidden && !l.inPage), 5, navNotes);
+            // Each pass starts again from the page under test, which is "home" only when it is the site root: a
+            // page at /account/settings said "Start from home" for every link. (v8 b39, 2026-10-10)
+            let startPath = analysis.url;
+            try {
+                const u = new URL(analysis.url);
+                startPath = u.pathname + u.search;
+            }
+            catch { /* keep the url */ }
+            const startDescription = startPath === "/" ? "Start from home" : `Start from ${startPath}`;
             if (navLinks.length > 0) {
-                tests.push({
+                tests.push(withNotes({
                     name: "Navigation Links",
                     description: "Test main navigation links work",
                     // A same-page link has pathname "/", and `assert url contains '/'` is
@@ -3766,7 +4055,7 @@ For more help: https://playwright.dev/docs/browsers
                     // than no step, because it reads in the report as verified navigation.
                     // Emit the assertion only when the path can actually distinguish the
                     // destination from the origin. (2026-07-29)
-                    steps: navLinks.slice(0, 5).flatMap(link => {
+                    steps: navLinks.flatMap(link => {
                         let path = "";
                         try {
                             path = new URL(link.href || "", analysis.url).pathname;
@@ -3776,7 +4065,7 @@ For more help: https://playwright.dev/docs/browsers
                         }
                         const discriminating = path.length > 1 && path !== new URL(analysis.url).pathname;
                         return [
-                            { action: "navigate", target: analysis.url, description: "Start from home" },
+                            { action: "navigate", target: analysis.url, description: startDescription },
                             { action: "click", target: link.selector, description: `Click ${link.text || "link"}` },
                             ...(discriminating
                                 ? [{ action: "assert", target: `url contains '${path}'`, description: "Verify navigation" }]
@@ -3784,28 +4073,35 @@ For more help: https://playwright.dev/docs/browsers
                         ];
                     }),
                     assertions: ["no console errors"],
-                });
+                }, navNotes));
+            }
+            else {
+                unplaced.push(...navNotes);
             }
         }
         // Generate button interaction tests
-        const actionButtons = analysis.buttons.filter(b => b.text && !b.text.toLowerCase().includes("submit") && b.text.length < 30);
+        const buttonNotes = [];
+        const actionButtons = notRed(analysis.buttons.filter(b => b.text && !b.text.toLowerCase().includes("submit") && b.text.length < 30 && !b.hidden), 3, buttonNotes);
         if (actionButtons.length > 0) {
-            tests.push({
+            tests.push(withNotes({
                 name: "Button Interactions",
                 description: "Test clickable buttons respond correctly",
                 steps: [
                     { action: "navigate", target: analysis.url, description: "Navigate to page" },
-                    ...actionButtons.slice(0, 3).map(btn => ({
+                    ...actionButtons.map(btn => ({
                         action: "click",
                         target: btn.selector,
                         description: `Click "${btn.text}"`,
                     })),
                 ],
                 assertions: ["no console errors", "page is interactive"],
-            });
+            }, buttonNotes));
+        }
+        else {
+            unplaced.push(...buttonNotes);
         }
         // Default smoke test
-        tests.push({
+        tests.push(withNotes({
             name: "Page Load Smoke Test",
             description: "Verify page loads without errors",
             steps: [
@@ -3813,7 +4109,7 @@ For more help: https://playwright.dev/docs/browsers
                 { action: "assert", target: `title contains '${analysis.title.split(" ")[0]}'`, description: "Verify title" },
             ],
             assertions: ["page loads successfully", "no console errors"],
-        });
+        }, unplaced));
         return tests;
     }
     /**
@@ -3824,6 +4120,11 @@ For more help: https://playwright.dev/docs/browsers
         for (const test of tests) {
             script += `# ${test.name}\n`;
             script += `# ${test.description}\n`;
+            // `//`, not `#`: parseNLTestSuite drops `//` lines, but reads every `#` line as a new test header,
+            // so a `#` note would rename the test or split it in two. (v8 b39, 2026-10-10)
+            for (const note of test.notes ?? []) {
+                script += `// note: ${note}\n`;
+            }
             // This must be the dialect src/testing/nl-test-suite.ts PARSES, because the
             // MCP tool tells callers to paste it straight into nl_test_inline. It used
             // to emit a `verb "quoted-arg"` form of its own invention, and every line
@@ -3837,6 +4138,9 @@ For more help: https://playwright.dev/docs/browsers
                         script += `go to ${step.target}\n`;
                         break;
                     case "click":
+                        if (step.zone === "red") {
+                            script += `// red zone: the next click is refused without force: true, and NL test steps never pass force\n`;
+                        }
                         // Unquoted: the parser takes the rest of the line as the target.
                         script += `click ${step.target}\n`;
                         break;
@@ -3872,20 +4176,27 @@ For more help: https://playwright.dev/docs/browsers
         for (const testDef of tests) {
             const _testName = testDef.name.toLowerCase().replace(/\s+/g, "-");
             code += `test('${testDef.name}', async ({ page }) => {\n`;
-            code += `  // ${testDef.description}\n\n`;
+            code += `  // ${testDef.description}\n`;
+            for (const note of testDef.notes ?? []) {
+                code += `  // note: ${note}\n`;
+            }
+            code += `\n`;
             for (const step of testDef.steps) {
                 switch (step.action) {
                     case "navigate":
                         code += `  await page.goto('${step.target}');\n`;
                         break;
-                    case "click":
-                        if (step.target?.startsWith("text=")) {
-                            code += `  await page.getByText('${step.target.replace("text=", "").replace(/"/g, "")}').click();\n`;
-                        }
-                        else {
-                            code += `  await page.locator('${step.target}').click();\n`;
-                        }
+                    case "click": {
+                        const click = step.target?.startsWith("text=")
+                            ? `await page.getByText('${step.target.replace("text=", "").replace(/"/g, "")}').click();`
+                            : `await page.locator('${step.target}').click();`;
+                        // Playwright has no zone gate: an exported red click would simply run. It ships commented out.
+                        // (v8 b39, 2026-10-10)
+                        code += step.zone === "red"
+                            ? `  // red zone: cbrowser refuses this click without force; left commented out so this test cannot run it.\n  // ${click}\n`
+                            : `  ${click}\n`;
                         break;
+                    }
                     case "fill":
                         code += `  await page.locator('${step.target}').fill('${step.value}');\n`;
                         break;
@@ -5255,12 +5566,16 @@ For more help: https://playwright.dev/docs/browsers
             this.config.viewportHeight = persona.context.viewport[1];
         }
         const page = await this.getPage();
-        const steps = [];
         const consoleLogs = [];
         const frictionPoints = [];
         const startTime = Date.now();
-        // Capture console logs
-        page.on("console", (msg) => {
+        // Capture console logs. Removed in the finally below (v8 B27, 2026-10-10):
+        // it used to stay on the tab, which is the shared page in a hosted session,
+        // so every heuristic journey left one more listener and log array behind
+        // (measured 4 -> 7 console listeners over three runs). Not read from the
+        // tab's console buffer instead: that keeps 500 entries and omits an empty
+        // location, so a noisy page or an inline script would change consoleLogs.
+        const onConsole = (msg) => {
             const entry = {
                 type: msg.type(),
                 text: msg.text().substring(0, 500),
@@ -5272,7 +5587,19 @@ For more help: https://playwright.dev/docs/browsers
             if (msg.type() === "error") {
                 frictionPoints.push(`Console error: ${msg.text().substring(0, 100)}`);
             }
-        });
+        };
+        page.on("console", onConsole);
+        try {
+            return await this.heuristicJourney(page, persona, options, consoleLogs, frictionPoints, startTime);
+        }
+        finally {
+            page.off("console", onConsole);
+        }
+    }
+    /** journey()'s heuristic exploration; journey's listener fills `consoleLogs`. */
+    async heuristicJourney(page, persona, options, consoleLogs, frictionPoints, startTime) {
+        const { persona: personaName, startUrl, goal, maxSteps = 20 } = options;
+        const steps = [];
         // Navigate to start
         await this.navigate(startUrl);
         steps.push({