cbrowser 19.1.7 → 19.1.8

package/dist/browser.js

@@ -2006,18 +2006,31 @@ For more help: https://playwright.dev/docs/browsers
      */
     async click(selector, options = {}) {
         const page = await this.getPage();
-        // Classify action zone
-        const zone = this.classifyAction("click", selector);
+        // Classify action zone from the selector string (unchanged: a string that names a dangerous action
+        // is refused before anything is resolved, exactly as before).
+        let zone = this.classifyAction("click", selector);
         if (zone === "red" && !options.force) {
             return {
                 success: false,
                 screenshot: await this.screenshot(),
                 message: `Red zone action requires --force: click "${selector}"`,
+                zone,
             };
         }
         try {
             // Try multiple selector strategies
             const element = await this.findElement(selector);
+            // Classify the ELEMENT, not only the string. A selector says how an element is addressed
+            // (#delete-account, [data-testid=...], button:nth-of-type(3)); the element says what it is
+            // ("Delete account"). The zone must be the same whichever way the element is addressed.
+            let target;
+            if (element) {
+                const gate = await this.gateElement("click", selector, element, zone, options.force);
+                if (gate.refusal)
+                    return gate.refusal;
+                zone = gate.zone;
+                target = gate.target;
+            }
             if (!element) {
                 const result = {
                     success: false,
@@ -2097,6 +2110,20 @@ For more help: https://playwright.dev/docs/browsers
             if (targetBlankRemoved && options.verbose) {
                 console.log('Removed target="_blank" to navigate in same tab');
             }
+            // Re-judge what is about to be clicked, immediately before dispatch. The first gate ran when the
+            // selector resolved; since then clickTarget may have moved to an ancestor anchor and a re-rendering
+            // page may have swapped the node a locator resolves to. One round trip remains between this check
+            // and Playwright's own resolution at click time.
+            // For a container the judged point is pinned: the click goes exactly where the gate looked.
+            let clickPosition;
+            {
+                const gate = await this.gateElement("click", selector, clickTarget, zone, options.force);
+                if (gate.refusal)
+                    return gate.refusal;
+                zone = gate.zone;
+                target = gate.target ?? target;
+                clickPosition = gate.position;
+            }
             // Check for sticky element interception before clicking
             const interception = await this.checkForInterception(clickTarget);
             if (interception.intercepted && interception.interceptorSelector) {
@@ -2104,7 +2131,7 @@ For more help: https://playwright.dev/docs/browsers
                     console.log(`Sticky element detected: ${interception.interceptorInfo}`);
                 }
                 // Try to handle the interception
-                const handled = await this.handleStickyInterception(clickTarget, interception.interceptorSelector, { verbose: options.verbose });
+                const handled = await this.handleStickyInterception(clickTarget, interception.interceptorSelector, { verbose: options.verbose, position: clickPosition });
                 if (!handled.success) {
                     return {
                         success: false,
@@ -2118,7 +2145,7 @@ For more help: https://playwright.dev/docs/browsers
             }
             else {
                 // No interception, normal click
-                await clickTarget.click();
+                await clickTarget.click(clickPosition ? { position: clickPosition } : undefined);
             }
             // Wait for any navigation or network activity
             await page.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => { });
@@ -2127,6 +2154,8 @@ For more help: https://playwright.dev/docs/browsers
                 success: true,
                 screenshot: await this.screenshot(),
                 message: `Clicked: ${selector}`,
+                zone,
+                target,
             };
         }
         catch (error) {
@@ -2149,6 +2178,12 @@ For more help: https://playwright.dev/docs/browsers
                     // Find the last filled input and press Enter on it
                     const lastInput = await this.findElement(this.lastFilledInputSelector);
                     if (lastInput) {
+                        // Enter submits the input's form: gate on the form's action and default button, so a hidden
+                        // "Pay now" cannot be reached by pressing Enter in the card-number field.
+                        const gate = await this.gateElement("click", `${selector} (Enter-fallback)`, lastInput, zone, options.force, { implicitSubmit: true });
+                        if (gate.refusal)
+                            return gate.refusal;
+                        zone = gate.zone;
                         await lastInput.focus();
                         await page.keyboard.press('Enter');
                         // Wait for navigation or network activity
@@ -2158,6 +2193,7 @@ For more help: https://playwright.dev/docs/browsers
                             success: true,
                             screenshot: await this.screenshot(),
                             message: `Submitted via Enter key (button "${selector}" was not visible)`,
+                            zone,
                         };
                     }
                 }
@@ -2317,6 +2353,8 @@ For more help: https://playwright.dev/docs/browsers
      * Handle a sticky element intercepting a click by trying multiple strategies.
      */
     async handleStickyInterception(element, interceptorSelector, options = {}) {
+        // A container's click goes to the point the red-zone gate judged, whichever strategy clicks it.
+        const at = options.position ? { position: options.position } : undefined;
         const page = await this.getPage();
         // Strategy 1: Scroll element to viewport center (away from sticky headers/footers)
         try {
@@ -2332,7 +2370,7 @@ For more help: https://playwright.dev/docs/browsers
             // Check if still intercepted
             const recheck = await this.checkForInterception(element);
             if (!recheck.intercepted) {
-                await element.click();
+                await element.click(at);
                 return { success: true, strategy: 'scroll-to-safe-zone' };
             }
         }
@@ -2353,7 +2391,7 @@ For more help: https://playwright.dev/docs/browsers
             });
             await page.waitForTimeout(50);
             // Click the element
-            await element.click();
+            await element.click(at);
             // Restore the interceptor
             await interceptor.evaluate((el, original) => {
                 el.style.display = original;
@@ -2763,6 +2801,18 @@ For more help: https://playwright.dev/docs/browsers
      */
     async hoverClick(selector, options = {}) {
         const page = await this.getPage();
+        // Same gate as click(): the string first, then the element it resolves to. hoverClick is also the
+        // daemon's click path (daemon.ts), so without this every daemon-mode click skipped the red zone.
+        const stringZone = this.classifyAction("click", selector);
+        if (stringZone === "red" && !options.force) {
+            this.audit("hoverClick", selector, "red", "blocked");
+            return {
+                success: false,
+                screenshot: await this.screenshot(),
+                message: `Red zone action requires --force: hoverClick "${selector}"`,
+                zone: stringZone,
+            };
+        }
         try {
             // STEP 1: Detect the likely parent menu from selector text
             // e.g., "International Admissions" → parent is likely "Admissions"
@@ -2822,13 +2872,18 @@ For more help: https://playwright.dev/docs/browsers
                             await page.waitForTimeout(400);
                             const found = await this.findElement(selector);
                             if (found) {
-                                await found.click();
+                                const gate = await this.gateElement("hoverClick", selector, found, stringZone, options.force);
+                                if (gate.refusal)
+                                    return gate.refusal;
+                                await found.click(gate.position ? { position: gate.position } : undefined);
                                 await page.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => { });
-                                this.audit("hoverClick", selector, "yellow", "success");
+                                this.audit("hoverClick", selector, gate.zone, "success");
                                 return {
                                     success: true,
                                     screenshot: await this.screenshot(),
                                     message: `Hover-clicked (nav scan): ${selector}`,
+                                    zone: gate.zone,
+                                    target: gate.target,
                                 };
                             }
                         }
@@ -2844,13 +2899,18 @@ For more help: https://playwright.dev/docs/browsers
                 };
             }
             // STEP 4: Click the element (parent should still be hovered)
-            await element.click();
+            const gate = await this.gateElement("hoverClick", selector, element, stringZone, options.force);
+            if (gate.refusal)
+                return gate.refusal;
+            await element.click(gate.position ? { position: gate.position } : undefined);
             await page.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => { });
-            this.audit("hoverClick", selector, "yellow", "success");
+            this.audit("hoverClick", selector, gate.zone, "success");
             return {
                 success: true,
                 screenshot: await this.screenshot(),
                 message: `Hover-clicked: ${selector}`,
+                zone: gate.zone,
+                target: gate.target,
             };
         }
         catch (error) {
@@ -3183,6 +3243,12 @@ For more help: https://playwright.dev/docs/browsers
                 screenshot: result.screenshot,
             };
         }
+        // A red-zone refusal is a request for --force, not a selector that needs healing. Retrying
+        // with a shorter alternative ("Delete" for "Delete account") used to route around the gate.
+        const refusedRed = (r) => !r.success && r.zone === "red" && !options.force;
+        if (refusedRed(result)) {
+            return { success: false, attempts, message: result.message, screenshot: result.screenshot, zone: "red" };
+        }
         // Try to find alternative selectors
         const alternatives = await this.findAlternativeSelectors(selector);
         for (let i = 0; i < Math.min(maxRetries - 1, alternatives.length); i++) {
@@ -3197,6 +3263,9 @@ For more help: https://playwright.dev/docs/browsers
                 alternativeUsed: alt.reason,
                 screenshot: result.screenshot,
             });
+            if (refusedRed(result)) {
+                return { success: false, attempts, message: result.message, screenshot: result.screenshot, zone: "red" };
+            }
             if (result.success) {
                 // v11.8.0: Gate success on confidence threshold
                 const meetsConfidence = alt.confidence >= minConfidence;
@@ -5246,10 +5315,13 @@ For more help: https://playwright.dev/docs/browsers
      * - YELLOW: Interactive actions (click, fill) - log and proceed
      * - GREEN: Read-only actions - auto-execute
      */
-    classifyAction(action, target) {
+    classifyAction(action, target, options = {}) {
         const lowerTarget = target.toLowerCase();
         // =========================================================================
         // BLACK ZONE - Security violations, never execute
+        // ignoreBlack: the black patterns describe an INSTRUCTION ("bypass the login"), not a control on a
+        // page. classifyElement skips them so page text like "SQL injection course" is not a violation and a
+        // red label that happens to sit next to a black word still classifies red.
         // =========================================================================
         const blackPatterns = [
             /bypass/i,
@@ -5259,7 +5331,7 @@ For more help: https://playwright.dev/docs/browsers
             /sql\s*injection/i,
             /xss/i,
         ];
-        if (blackPatterns.some(p => p.test(lowerTarget))) {
+        if (!options.ignoreBlack && blackPatterns.some(p => p.test(lowerTarget))) {
             return "black";
         }
         // =========================================================================
@@ -5349,6 +5421,660 @@ For more help: https://playwright.dev/docs/browsers
         // =========================================================================
         return "yellow";
     }
+    /**
+     * Classify a RESOLVED element by what it is, with the same patterns classifyAction applies to a
+     * string. Reads the control a click would act on (the element, its nearest interactive ancestor in the
+     * composed tree, or the control under the point the click lands on) and runs classifyAction over every
+     * description of it: aria-label, resolved aria-labelledby, a button's value, title, its own visible
+     * text, names that live below it and belong to it (an icon's aria-label or <title>, an image's alt,
+     * an image input's alt, open-shadow-root and slotted text), and the action - or the submitter's
+     * formaction - of the form it submits. The most severe zone wins.
+     *
+     * Not judged, because acting on them has no consequence of its own: a text field (typed text and the
+     * field's label are data; clicking into "Reason you want to close account" closes nothing) and a choice
+     * control (checkbox, radio, switch, select, option: choosing a value; the submit that commits it is
+     * judged when it is clicked).
+     *
+     * implicitSubmit: the caller is about to press Enter, which submits the focused field's form. The
+     * form's action and its default submit button are then the descriptions that matter.
+     * skipHit: the element is already the deepest element at a known point (a coordinate click, a drag
+     * endpoint, the focused element); do not hit-test its centre.
+     *
+     * position: for an element that is not itself a control (a section, a card, <main>), the point that was
+     * judged, relative to the element's padding box. Callers pass it to the click so the point judged is the
+     * point clicked.
+     *
+     * Returns null when the element cannot be read (detached, frame gone); the caller keeps the string zone.
+     */
+    async classifyElement(element, options = {}) {
+        const inPage = (node, arg) => {
+            const norm = (s, max) => (s || "").replace(/\s+/g, " ").trim().slice(0, max);
+            const INTERACTIVE = "a,button,input,select,textarea,summary,label,[role='button'],[role='link'],[role='menuitem'],[role='menuitemcheckbox'],[role='menuitemradio'],[role='tab'],[role='option'],[role='checkbox'],[role='radio'],[role='switch'],[onclick]";
+            // Native checkboxes, radios and selects choose a value; role=checkbox/radio/switch likewise. NOT role=option or
+            // menu items: command palettes (cmdk / shadcn Command) render every command as role=option and run it on click.
+            const CHOICE = "input[type=checkbox],input[type=radio],select,option,[role='checkbox'],[role='radio'],[role='switch']";
+            const BUTTON_INPUT = /^(submit|button|reset|image)$/i;
+            const isTextField = (el) => el.tagName === "TEXTAREA" || el.isContentEditable ||
+                (el.tagName === "INPUT" && !BUTTON_INPUT.test(el.type || "") && !/^(checkbox|radio)$/i.test(el.type || ""));
+            const isData = (el) => isTextField(el) || el.matches(CHOICE);
+            // Composed-tree walk: a slotted node's parent is its slot, a shadow root's parent is its host, and
+            // a same-origin frame's document hangs under its <iframe>.
+            const up = (e) => {
+                const slot = e.assignedSlot;
+                if (slot)
+                    return slot;
+                if (e.parentElement)
+                    return e.parentElement;
+                const r = e.getRootNode();
+                if (r.host)
+                    return r.host;
+                try {
+                    return e.ownerDocument.defaultView?.frameElement ?? null;
+                }
+                catch {
+                    return null;
+                }
+            };
+            const composedClosest = (e) => { for (let n = e; n; n = up(n))
+                if (n.matches(INTERACTIVE))
+                    return n; return null; };
+            const composedContains = (a, b) => { for (let n = b; n; n = up(n))
+                if (n === a)
+                    return true; return false; };
+            // The element a pointer at viewport (x, y) actually reaches: beneath anything not inside `within`
+            // (a cookie bar, a loading overlay), into open shadow roots and same-origin frames.
+            const deepAt = (x, y, within) => {
+                const hitRoot = (within ? within.getRootNode() : document);
+                const stack = hitRoot.elementsFromPoint(x, y);
+                let e = within ? (stack.find(s => composedContains(within, s)) ?? null) : (stack[0] ?? null);
+                let ox = 0, oy = 0;
+                for (let i = 0; e && i < 12; i++) {
+                    const sr = e.shadowRoot;
+                    if (sr) {
+                        const inner = sr.elementFromPoint(x - ox, y - oy);
+                        if (inner && inner !== e) {
+                            e = inner;
+                            continue;
+                        }
+                        // The point is on the host's own light-DOM text, rendered through a <slot>: that slot's control
+                        // is what the click activates.
+                        const host = e;
+                        const slot = Array.from(sr.querySelectorAll("slot")).find(s => s.assignedNodes().some(n => n.parentNode === host));
+                        if (slot) {
+                            e = slot;
+                            break;
+                        }
+                    }
+                    if (e.tagName === "IFRAME" || e.tagName === "FRAME") {
+                        let d = null;
+                        try {
+                            d = e.contentDocument;
+                        }
+                        catch {
+                            d = null;
+                        }
+                        if (d) {
+                            const r = e.getBoundingClientRect();
+                            ox += r.left + e.clientLeft;
+                            oy += r.top + e.clientTop;
+                            const inner = d.elementFromPoint(x - ox, y - oy);
+                            if (inner) {
+                                e = inner;
+                                continue;
+                            }
+                        }
+                    }
+                    break;
+                }
+                return e;
+            };
+            // Something that is not an interactive element can still act as one: a <div> with a click listener
+            // shows it by a pointer cursor, a tabindex or an inline pointer handler.
+            const clickable = (el) => {
+                if (el.hasAttribute("tabindex"))
+                    return true;
+                for (const a of Array.from(el.attributes))
+                    if (/^on(click|mousedown|mouseup|pointerdown|pointerup|touchstart|touchend)$/i.test(a.name))
+                        return true;
+                // cursor is inherited: the clickable element is where a pointer cursor STARTS, not every child of it
+                // (the icon inside a pointer-cursor menu item is not the item).
+                try {
+                    const cs = (n) => (n.ownerDocument.defaultView || window).getComputedStyle(n).cursor;
+                    if (cs(el) !== "pointer")
+                        return false;
+                    const p = up(el);
+                    return !p || cs(p) !== "pointer";
+                }
+                catch {
+                    return false;
+                }
+            };
+            // An element's own text: its visible text minus the text of controls nested inside it. A text node counts
+            // when no interactive element sits between it and `el` (el itself need not be an interactive element).
+            const ownText = (el) => {
+                if (!el.querySelector(INTERACTIVE))
+                    return el.innerText;
+                const parts = [];
+                const walker = (el.ownerDocument || document).createTreeWalker(el, NodeFilter.SHOW_TEXT);
+                for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+                    const p = n.parentElement;
+                    if (!p)
+                        continue;
+                    const c = p.closest(INTERACTIVE);
+                    if (!c || c === el || !el.contains(c))
+                        parts.push(n.textContent || "");
+                }
+                return parts.join(" ");
+            };
+            // What a pointer on `e` activates: its nearest interactive element; else the nearest ancestor that shows a
+            // click affordance (a pointer-cursor <div> menu item whose icon was hit); else the nearest element whose own
+            // text is label-sized (a listener-only item, "Delete account"), never a prose paragraph. Kept strictly inside
+            // `stopAt` when given.
+            const activatorOf = (e, stopAt) => {
+                const inside = (n) => !stopAt || (n !== stopAt && composedContains(stopAt, n));
+                const c = composedClosest(e);
+                if (c)
+                    return inside(c) ? c : null;
+                for (let n = e, i = 0; n && i < 8 && inside(n); n = up(n), i++) {
+                    if (n === n.ownerDocument.body || n === n.ownerDocument.documentElement)
+                        break;
+                    if (clickable(n))
+                        return n;
+                }
+                for (let n = e, i = 0; n && i < 3 && inside(n); n = up(n), i++) {
+                    if (n === n.ownerDocument.body || n === n.ownerDocument.documentElement)
+                        break;
+                    const tx = norm(ownText(n), 200);
+                    if (tx && tx.length <= 60)
+                        return n;
+                }
+                return null;
+            };
+            // For an element that is already the deepest one at a known point (a coordinate click, a drag end, the
+            // focused element), the thing activated may be an ancestor without an interactive role.
+            const control = composedClosest(node) || (arg.skipHit ? activatorOf(node, null) : null) || node;
+            const isContainer = !composedClosest(node);
+            const viaActivator = control !== node && isContainer;
+            // Where a click on this element lands: the centre of its first box clipped to the viewport (what
+            // Playwright clicks), after scrolling it into view if none of it is visible. Not computed for a key
+            // press or an element that is already the deepest one at a known point.
+            let position = null;
+            const hitControl = (() => {
+                if (arg.implicitSubmit || arg.skipHit)
+                    return null;
+                const firstBox = () => node.getClientRects()[0] ?? node.getBoundingClientRect();
+                const clip = (b) => ({ l: Math.max(b.left, 0), t: Math.max(b.top, 0), r: Math.min(b.right, innerWidth), b: Math.min(b.bottom, innerHeight) });
+                let box = firstBox();
+                if (!box || box.width === 0 || box.height === 0)
+                    return null;
+                let v = clip(box);
+                if (v.r <= v.l || v.b <= v.t) {
+                    node.scrollIntoView({ block: "center", inline: "center" });
+                    box = firstBox();
+                    v = clip(box);
+                }
+                if (v.r <= v.l || v.b <= v.t)
+                    return null;
+                const px = (v.l + v.r) / 2;
+                const py = (v.t + v.b) / 2;
+                position = { x: px - box.left - node.clientLeft, y: py - box.top - node.clientTop };
+                const deep = deepAt(px, py, node);
+                if (!deep || deep === node)
+                    return null;
+                const c = activatorOf(deep, node);
+                return c && c !== control ? c : null;
+            })();
+            const nodes = [node, control, hitControl].filter((e, i, a) => !!e && a.indexOf(e) === i);
+            const root = node.getRootNode();
+            const byIdIn = (el, id) => {
+                const r = el.getRootNode();
+                return r.getElementById ? r.getElementById(id) : root.getElementById?.(id) ?? null;
+            };
+            const labelledBy = (el) => (el.getAttribute("aria-labelledby") || "").split(/\s+/).filter(Boolean)
+                .map(id => byIdIn(el, id)).filter(Boolean).map(n => n.innerText || n.textContent || "").join(" ");
+            const descriptors = [];
+            const push = (s, max = 200) => { const v = norm(s, max); if (v && !descriptors.includes(v))
+                descriptors.push(v); };
+            // A form's action names the consequence ("/checkout", "/account/close"). Paths name the object
+            // first; the patterns read verb first ("close account"), so push both orders. A submitter's
+            // formaction overrides the form's action for that button.
+            const pushPath = (path) => {
+                if (!path)
+                    return;
+                let p = path;
+                try {
+                    p = decodeURIComponent(p);
+                }
+                catch { /* keep raw */ }
+                const words = norm(p.replace(/^[a-z]+:\/\/[^/]+/i, "").replace(/[/\-_.?=&+%#]+/g, " "), 120);
+                push(words);
+                push(words.split(" ").reverse().join(" "));
+            };
+            const pushSubmit = (form, submitter) => {
+                const fa = submitter?.getAttribute("formaction");
+                pushPath(fa ? fa : form.getAttribute("action"));
+            };
+            // The DOM's own submit test: a <button> with no or an invalid type is a submit button.
+            const isSubmitter = (el) => (el.tagName === "BUTTON" && el.type === "submit") ||
+                (el.tagName === "INPUT" && /^(submit|image)$/.test(el.type));
+            const pushControl = (el) => {
+                push(el.getAttribute("aria-label"));
+                push(labelledBy(el));
+                if (el.tagName === "BUTTON" || (el.tagName === "INPUT" && BUTTON_INPUT.test(el.type || ""))) {
+                    push(el.value);
+                }
+                if (el.tagName === "INPUT" && el.type === "image")
+                    push(el.getAttribute("alt"));
+                if (el.tagName === "IMG")
+                    push(el.alt);
+                // <label for> names a button or submit input too.
+                const labels = el.labels;
+                if (labels)
+                    for (const l of Array.from(labels))
+                        push(l.innerText);
+                push(el.getAttribute("title"));
+            };
+            // A descendant's name belongs to `el` only when no other control sits between them: the icon inside
+            // a button labels the button; the icon button inside a clickable row does not label the row.
+            const owns = (el, d) => { const c = composedClosest(d); return !c || c === el || composedContains(c, el); };
+            const pushBelow = (el) => {
+                Array.from(el.querySelectorAll("[aria-label]")).filter(d => owns(el, d)).slice(0, 5).forEach(d => push(d.getAttribute("aria-label")));
+                Array.from(el.querySelectorAll("svg title")).filter(d => owns(el, d)).slice(0, 5).forEach(d => push(d.textContent));
+                Array.from(el.querySelectorAll("img[alt]")).filter(d => owns(el, d)).slice(0, 5).forEach(d => push(d.alt));
+                const sr = el.shadowRoot;
+                if (sr) {
+                    push(sr.textContent, 120);
+                    Array.from(sr.querySelectorAll("img[alt],[aria-label]")).slice(0, 5).forEach(d => push(d.getAttribute("alt") || d.getAttribute("aria-label")));
+                }
+                // A control inside a shadow root shows its host's light-DOM text through a <slot>.
+                Array.from(el.querySelectorAll("slot")).slice(0, 5).forEach(s => push(s.assignedNodes({ flatten: true }).map(n => n.textContent || "").join(" "), 120));
+            };
+            let label = "";
+            let submitsVia = "";
+            const nameOf = (el) => {
+                const lb = norm(labelledBy(el), 200);
+                if (lb)
+                    return lb;
+                const al = el.getAttribute("aria-label");
+                if (al && al.trim())
+                    return norm(al, 200);
+                if (el.tagName === "INPUT" && el.value && BUTTON_INPUT.test(el.type || ""))
+                    return norm(el.value, 200);
+                if (el.tagName === "INPUT" && el.type === "image" && el.getAttribute("alt"))
+                    return norm(el.getAttribute("alt"), 200);
+                if (el.tagName === "IMG" && el.alt)
+                    return norm(el.alt, 200);
+                if (isData(el)) {
+                    const labels = el.labels;
+                    const lt = labels ? Array.from(labels).map(l => l.innerText).join(" ") : "";
+                    return norm(lt || el.getAttribute("placeholder") || el.getAttribute("name"), 200);
+                }
+                const t = norm(el.innerText, 200);
+                if (t)
+                    return t;
+                const slotted = Array.from(el.querySelectorAll("slot")).map(s => s.assignedNodes({ flatten: true }).map(n => n.textContent || "").join(" ")).join(" ");
+                const below = norm(slotted, 200) || el.querySelector("[aria-label]")?.getAttribute("aria-label") || el.querySelector("svg title")?.textContent
+                    || el.querySelector("img[alt]")?.alt
+                    || el.shadowRoot?.textContent;
+                if (below && below.trim())
+                    return norm(below, 200);
+                const lbl = el.labels;
+                if (lbl && lbl.length)
+                    return norm(Array.from(lbl).map(l => l.innerText).join(" "), 200);
+                return norm(el.getAttribute("title"), 200);
+            };
+            for (const el of nodes) {
+                const isControl = (el === control && (!isContainer || viaActivator)) || el === hitControl;
+                if (!isData(el)) {
+                    // Judged by its own names: a control, or something acting as one. A control's own text counts in
+                    // full; an acting-as-control element's own text by its opening 120 characters (a long div-button is
+                    // labelled by how it starts). A plain container or inert text is not a label: the hit-test above
+                    // judges the control a click on it lands on.
+                    const isLeaf = !el.querySelector(INTERACTIVE);
+                    // The resolved element as a leaf is judged by how its text starts, affordance or not: a refused inert
+                    // heading costs one force retry, a missed listener-only "Delete account" div cannot be undone.
+                    const actsAsControl = isControl || (el === node && isLeaf) || clickable(el);
+                    if (actsAsControl) {
+                        pushControl(el);
+                        push(norm(ownText(el), isControl ? 300 : 120), 300);
+                        pushBelow(el);
+                    }
+                    else if (el === node) {
+                        // A listener-only row that also holds a help link or an info button: its own opening text.
+                        push(norm(ownText(el), 120), 120);
+                    }
+                    const form = el.form;
+                    if (form && isSubmitter(el))
+                        pushSubmit(form, el);
+                }
+                else if (arg.implicitSubmit && el.tagName !== "TEXTAREA") {
+                    // Enter in a field submits its form through the form's default button.
+                    const form = el.form;
+                    if (form) {
+                        // The default button is the first submit button in tree order; if it is disabled, Enter submits nothing.
+                        const def = Array.from(form.elements).find(isSubmitter) ?? null;
+                        if (!(def && def.disabled))
+                            pushSubmit(form, def);
+                        if (def && !def.disabled) {
+                            pushControl(def);
+                            pushBelow(def);
+                            push(def.innerText);
+                            submitsVia = nameOf(def);
+                        }
+                    }
+                }
+                if (!label)
+                    label = nameOf(el);
+            }
+            if (submitsVia)
+                label = `${label} (Enter submits "${submitsVia}")`;
+            if (hitControl)
+                label = `${label} (click lands on <${hitControl.tagName.toLowerCase()}> "${nameOf(hitControl)}")`;
+            return { tag: control.tagName.toLowerCase(), label, descriptors, position: isContainer ? position : null };
+        };
+        const arg = { implicitSubmit: !!options.implicitSubmit, skipHit: !!options.skipHit };
+        let info = null;
+        try {
+            info = "count" in element
+                ? await element.evaluate(inPage, arg, { timeout: 3000 })
+                : await element.evaluate(inPage, arg);
+        }
+        catch {
+            return null;
+        }
+        if (!info)
+            return null;
+        let zone = "yellow";
+        for (const d of info.descriptors)
+            zone = this.maxZone(zone, this.classifyAction("click", d, { ignoreBlack: true }));
+        return { zone, tag: info.tag, label: info.label, descriptors: info.descriptors, position: info.position ?? undefined };
+    }
+    /**
+     * Gate a resolved element before it is activated. Returns a refusal when the element is red and the
+     * caller did not pass force; otherwise the effective zone (the more severe of the string zone and the
+     * element zone), the element's tag and label for the result and the audit trail, and - for a
+     * container - the position that was judged, which the caller must click.
+     */
+    async gateElement(verb, selector, element, stringZone, force, options = {}) {
+        const el = await this.classifyElement(element, options);
+        if (!el)
+            return { zone: stringZone };
+        const target = { tag: el.tag, label: el.label };
+        const zone = this.maxZone(stringZone, el.zone);
+        if (el.zone === "red" && !force) {
+            this.audit(verb, selector, "red", "blocked");
+            return {
+                zone,
+                target,
+                refusal: {
+                    success: false,
+                    screenshot: await this.screenshot(),
+                    message: `Red zone action requires --force: ${verb} "${selector}" resolves to <${el.tag}> "${el.label}"`,
+                    zone,
+                    target,
+                },
+            };
+        }
+        return { zone, target, position: el.position };
+    }
+    /**
+     * The element a pointer at viewport (x, y) reaches: the topmost element there, followed into open shadow
+     * roots and same-origin frames. Cross-origin frames stop at the <iframe>. (classifyElement carries the
+     * same walk for a container's hit-test; the two are kept identical.)
+     */
+    async deepElementAt(x, y) {
+        const page = await this.getPage();
+        const h = await page.evaluateHandle(([px, py]) => {
+            let e = document.elementFromPoint(px, py);
+            let ox = 0, oy = 0;
+            for (let i = 0; e && i < 12; i++) {
+                const sr = e.shadowRoot;
+                if (sr) {
+                    const inner = sr.elementFromPoint(px - ox, py - oy);
+                    if (inner && inner !== e) {
+                        e = inner;
+                        continue;
+                    }
+                    const host = e;
+                    const slot = Array.from(sr.querySelectorAll("slot")).find(s => s.assignedNodes().some(n => n.parentNode === host));
+                    if (slot) {
+                        e = slot;
+                        break;
+                    }
+                }
+                if (e.tagName === "IFRAME" || e.tagName === "FRAME") {
+                    let d = null;
+                    try {
+                        d = e.contentDocument;
+                    }
+                    catch {
+                        d = null;
+                    }
+                    if (d) {
+                        const r = e.getBoundingClientRect();
+                        ox += r.left + e.clientLeft;
+                        oy += r.top + e.clientTop;
+                        const inner = d.elementFromPoint(px - ox, py - oy);
+                        if (inner) {
+                            e = inner;
+                            continue;
+                        }
+                    }
+                }
+                break;
+            }
+            return e;
+        }, [x, y]);
+        const el = h.asElement();
+        if (!el)
+            await h.dispose();
+        return el;
+    }
+    /**
+     * Refusal message when a click at viewport point (x, y) would activate a red-zone control, else null.
+     * Used by the NL test runner's "click at X, Y".
+     */
+    async pointRedZone(x, y, force) {
+        if (force)
+            return null;
+        const handle = await this.deepElementAt(x, y);
+        if (!handle)
+            return null;
+        try {
+            const el = await this.classifyElement(handle, { skipHit: true });
+            if (el?.zone !== "red")
+                return null;
+            this.audit("click", `at:${x},${y}`, "red", "blocked");
+            return `Red zone action requires --force: click at ${x},${y} lands on <${el.tag}> "${el.label}"`;
+        }
+        finally {
+            await handle.dispose().catch(() => { });
+        }
+    }
+    /**
+     * Refusal message when dragging `source` onto `target` would click a red-zone control, else null.
+     * A drag is a mousedown where the pointer is over the source's centre and a mouseup over the target's
+     * centre, and the browser fires click on the nearest common ancestor of the two elements actually under
+     * the pointer. So the press and release points are resolved the way the pointer reaches them (beneath
+     * nothing, into shadow roots and same-origin frames), each after scrolling its element into view as the
+     * drag itself does, and the control containing both is judged.
+     */
+    async dragRedZone(source, target, force) {
+        if (force)
+            return null;
+        const page = await this.getPage();
+        const pointOf = async (sel) => {
+            const loc = page.locator(sel).first();
+            await loc.scrollIntoViewIfNeeded({ timeout: 3000 }).catch(() => { });
+            // Playwright presses the centre of the element's first box (a wrapped inline element's first line),
+            // clipped to the viewport.
+            const p = await loc.evaluate((el) => {
+                const r = el.getClientRects()[0] ?? el.getBoundingClientRect();
+                const l = Math.max(r.left, 0), rr = Math.min(r.right, innerWidth);
+                const tp = Math.max(r.top, 0), bt = Math.min(r.bottom, innerHeight);
+                return rr > l && bt > tp ? { x: (l + rr) / 2, y: (tp + bt) / 2 } : null;
+            }, undefined, { timeout: 3000 }).catch(() => null);
+            const at = p ? await this.deepElementAt(p.x, p.y) : null;
+            return at ?? (await loc.elementHandle({ timeout: 3000 }).catch(() => null));
+        };
+        const a = await pointOf(source);
+        const b = a ? await pointOf(target) : null;
+        if (!a || !b) {
+            await a?.dispose();
+            return null;
+        }
+        const common = (await page.evaluateHandle(([x, y]) => {
+            const up = (e) => {
+                const slot = e.assignedSlot;
+                if (slot)
+                    return slot;
+                if (e.parentElement)
+                    return e.parentElement;
+                const r = e.getRootNode();
+                if (r.host)
+                    return r.host;
+                try {
+                    return e.ownerDocument.defaultView?.frameElement ?? null;
+                }
+                catch {
+                    return null;
+                }
+            };
+            const chain = new Set();
+            for (let n = x; n; n = up(n))
+                chain.add(n);
+            let n = y;
+            while (n && !chain.has(n))
+                n = up(n);
+            return n;
+        }, [a, b])).asElement();
+        try {
+            if (!common)
+                return null;
+            const el = await this.classifyElement(common, { skipHit: true });
+            if (el?.zone !== "red")
+                return null;
+            this.audit("drag", `${source} -> ${target}`, "red", "blocked");
+            return `Red zone action requires --force: dragging "${source}" onto "${target}" clicks <${el.tag}> "${el.label}"`;
+        }
+        finally {
+            await Promise.all([a.dispose(), b.dispose(), common?.dispose()].map(p => p?.catch(() => { })));
+        }
+    }
+    /**
+     * Zone of pressing `key` on whatever has focus. Enter activates the focused control or submits the
+     * form of the focused field; Space activates a focused button-like control. Any other key, or nothing
+     * focused, returns null (no activation to gate). Focus is followed into open shadow roots and
+     * same-origin frames (a design-system app shell's host is not what has focus). Used by the keyboard
+     * paths through keystrokeRedZone.
+     */
+    async classifyKeyActivation(key) {
+        const raw = key.split("+").pop() || "";
+        const last = raw.trim();
+        // Playwright maps "\n" and "\r" to Enter, so they are Enter here too.
+        const isEnter = /^(enter|numpadenter)$/i.test(last) || raw === "\n" || raw === "\r";
+        const isSpace = last === "" ? key.endsWith(" ") : /^(space|spacebar)$/i.test(last);
+        if (!isEnter && !isSpace)
+            return null;
+        const page = await this.getPage();
+        const h = await page.evaluateHandle(() => {
+            let a = document.activeElement;
+            for (let i = 0; a && i < 12; i++) {
+                const sr = a.shadowRoot;
+                if (sr?.activeElement) {
+                    a = sr.activeElement;
+                    continue;
+                }
+                if (a.tagName === "IFRAME" || a.tagName === "FRAME") {
+                    let d = null;
+                    try {
+                        d = a.contentDocument;
+                    }
+                    catch {
+                        d = null;
+                    }
+                    if (d?.activeElement && d.activeElement !== d.body) {
+                        a = d.activeElement;
+                        continue;
+                    }
+                }
+                break;
+            }
+            return a && a !== document.body && a !== document.documentElement ? a : null;
+        });
+        const focused = h.asElement();
+        if (!focused) {
+            await h.dispose();
+            return null;
+        }
+        try {
+            if (isSpace) {
+                const buttonLike = await focused.evaluate((el) => el.matches("button,summary,input[type=submit],input[type=button],input[type=reset],input[type=image],[role=button],[role=menuitem],[role=tab]")).catch(() => false);
+                if (!buttonLike)
+                    return null;
+            }
+            const el = await this.classifyElement(focused, { implicitSubmit: isEnter, skipHit: true });
+            // A combobox or listbox keeps focus on itself and points at the highlighted item with
+            // aria-activedescendant; Enter activates that item (a command palette runs it) and, in a form, may also
+            // submit the form. Both are judged and the more severe wins. The id is looked up only in the field's own
+            // root, so a same-id element elsewhere on the page is never the one judged.
+            let item = null;
+            if (isEnter) {
+                const ih = await focused.evaluateHandle((a) => {
+                    const ad = a.getAttribute("aria-activedescendant");
+                    return ad ? a.getRootNode().getElementById(ad) : null;
+                }).catch(() => null);
+                const ie = ih?.asElement() ?? null;
+                if (ie) {
+                    const c = await this.classifyElement(ie, { skipHit: true });
+                    if (c)
+                        item = { zone: c.zone, tag: c.tag, label: c.label };
+                }
+                await ih?.dispose().catch(() => { });
+            }
+            const own = el ? { zone: el.zone, tag: el.tag, label: el.label } : null;
+            if (own && item)
+                return this.maxZone(own.zone, item.zone) === item.zone && item.zone !== own.zone ? item : own;
+            return own ?? item;
+        }
+        finally {
+            await focused.dispose().catch(() => { });
+        }
+    }
+    /**
+     * Refusal message when a keystroke would activate a red-zone control, else null. A key press is
+     * checked as itself; typed text is checked for the activating characters it contains (a newline is
+     * Enter, a space is Space). Every user-directed keyboard path calls this: the press_key and type_text
+     * MCP tools, the CLI's press / type / keyboard commands and the daemon's equivalents.
+     * Checked against what has focus now; a Tab inside typed text that moves focus first is not followed.
+     */
+    async keystrokeRedZone(input, force) {
+        if (force)
+            return null;
+        const keys = [];
+        if (input.key)
+            keys.push(input.key);
+        if (input.text !== undefined) {
+            if (/[\r\n]/.test(input.text))
+                keys.push("Enter");
+            if (input.text.includes(" "))
+                keys.push(" ");
+        }
+        for (const key of keys) {
+            const a = await this.classifyKeyActivation(key);
+            if (a?.zone === "red") {
+                const what = input.key ? key : key === "Enter" ? "a newline in the typed text" : "a space in the typed text";
+                this.audit("keyboard", input.key ?? JSON.stringify(input.text), "red", "blocked");
+                return `Red zone action requires --force: ${what} would activate <${a.tag}> "${a.label}"`;
+            }
+        }
+        return null;
+    }
+    /** The more severe of two zones (green < yellow < red < black). */
+    maxZone(a, b) {
+        const rank = { green: 0, yellow: 1, red: 2, black: 3 };
+        return rank[b] > rank[a] ? b : a;
+    }
     /**
      * Log an action to the audit trail.
      */