@trusty-squire/mcp 1.1.4 → 1.1.5

package/dist/bot/browser.js

@@ -2251,6 +2251,324 @@ export class BrowserController {
         const safeIndex = Math.max(0, Math.floor(index));
         await this.page.locator(selector).nth(safeIndex).click({ force: true, timeout: 8000 });
     }
+    // Resolve a locator-form operate_act target (`text=…` / `css=…`) DIRECTLY
+    // against the live page, bypassing the extracted-inventory list. This is the
+    // escape hatch for a control the inventory never emitted: a bare click-handler
+    // <div> with no role/label/testid that the SELECTOR walk skips and that the
+    // card scan drops once its MAX_CARDS budget is spent on earlier cursor:pointer
+    // divs (Casetify's Add-To-Cart is element #45 of the eligible cards; the cap is
+    // 16). Because there is no ref for such an element, `text=`/`css=` is the only
+    // way the host can click it.
+    //
+    // Resolution rules (kept deliberately strict so the click can't land on the
+    // wrong element):
+    //   • text mode — matches an element whose rendered text (innerText, so hidden
+    //     descendants don't leak) equals (or, if nothing equals, contains) the
+    //     query AND that carries a real click affordance (button/a/label/select
+    //     tag, an interactive ARIA role, an onclick / action-type attribute, or
+    //     cursor:pointer). Plain prose that merely contains the words is excluded.
+    //     Open shadow roots are pierced.
+    //   • css mode — the author's selector, restricted to VISIBLE matches.
+    //   • A weak (cursor-only) descendant inside a strong control collapses away;
+    //     weak ancestors and two GENUINE nested controls stay ambiguous rather
+    //     than being silently merged.
+    //   • 0 matches → {ok:false, reason:"none"}; >1 → {ok:false, reason:"ambiguous"}
+    //     with the candidate texts so the host can disambiguate. Exactly 1 returns
+    //     a live ElementHandle to the winner. The caller acts through the handle
+    //     (never a DOM-visible marker), so a page MutationObserver cannot re-aim
+    //     the click at a decoy between resolution and click, and disposes it after.
+    async resolvePageTarget(mode, value) {
+        if (!this.page)
+            throw new Error("Browser not started");
+        const resultHandle = await this.page.evaluateHandle(({ mode, value }) => {
+            const norm = (s) => (s ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+            // Rendered text, NOT textContent: innerText reflects what the user
+            // actually sees, excluding display:none / visibility:hidden descendants.
+            // Matching on textContent let a visible "Cancel" button that hides a
+            // "Delete account" span be selected by text="Delete account" (codex).
+            // Display form: whitespace-collapsed but ORIGINAL case (for the trace /
+            // audit / candidate list). `rendered` lowercases it for matching only.
+            const renderedRaw = (el) => {
+                const it = el.innerText;
+                return (typeof it === "string" ? it : (el.textContent ?? "")).replace(/\s+/g, " ").trim();
+            };
+            const rendered = (el) => renderedRaw(el).toLowerCase();
+            const safetyMetadata = (value) => (value ?? "")
+                .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+                .replace(/[_.\/-]+/g, " ")
+                .replace(/\s+/g, " ")
+                .trim()
+                .toLowerCase();
+            const safetySignalsFor = (el) => {
+                const safetyText = [
+                    renderedRaw(el),
+                    el.getAttribute("aria-label"),
+                    el.getAttribute("title"),
+                    el.getAttribute("alt"),
+                    el.getAttribute("action-type"),
+                    el.getAttribute("name"),
+                    el.getAttribute("id"),
+                    el.getAttribute("value"),
+                ]
+                    .map((part) => safetyMetadata(part))
+                    .filter((part) => part.length > 0)
+                    .join(" ");
+                // Keep these predicates in sync with isBillingObjectActionTarget and
+                // isAccountSetupActionTarget in provision-session.ts.
+                return {
+                    billingObject: /\b(create|save|add|finish)\b/i.test(safetyText) &&
+                        /\b(product|price|pricing|subscription|billing|payment|invoice|checkout)\b/i.test(safetyText),
+                    accountSetup: /\b(?:create|finish|complete|set up|setup)\s+(?:your\s+)?(?:account|profile|organization|workspace|business)\b/i.test(safetyText),
+                };
+            };
+            // Visibility walks the ANCESTOR chain (crossing shadow-host boundaries):
+            // opacity does not inherit, so a button under an opacity:0 wrapper keeps
+            // its own computed opacity 1 and a self-only check would wrongly treat it
+            // as visible and click an invisible control (codex).
+            const isVisible = (el) => {
+                const r = el.getBoundingClientRect();
+                if (r.width < 2 || r.height < 2)
+                    return false;
+                let node = el;
+                while (node !== null) {
+                    const s = window.getComputedStyle(node);
+                    if (s.display === "none" || s.visibility === "hidden" || s.opacity === "0")
+                        return false;
+                    const parentEl = node.parentElement;
+                    if (parentEl !== null) {
+                        node = parentEl;
+                    }
+                    else {
+                        const root = node.getRootNode();
+                        node = root instanceof ShadowRoot ? root.host : null;
+                    }
+                }
+                return true;
+            };
+            // "Strong" = real interactive semantics (a genuine control), as opposed
+            // to an element that merely inherits cursor:pointer from a clickable
+            // ancestor (a decorative wrapper / inner label span).
+            const isStrong = (el) => {
+                const tag = el.tagName.toLowerCase();
+                const role = el.getAttribute("role");
+                if (tag === "button" ||
+                    tag === "a" ||
+                    tag === "label" ||
+                    tag === "select" ||
+                    tag === "summary")
+                    return true;
+                if (role === "button" ||
+                    role === "link" ||
+                    role === "radio" ||
+                    role === "checkbox" ||
+                    role === "menuitem" ||
+                    role === "menuitemradio" ||
+                    role === "option" ||
+                    role === "tab" ||
+                    role === "switch")
+                    return true;
+                return el.hasAttribute("onclick") || el.hasAttribute("action-type");
+            };
+            const hasClickAffordance = (el) => isStrong(el) || window.getComputedStyle(el).cursor === "pointer";
+            // Gather candidates across the light DOM and every OPEN shadow root.
+            const all = [];
+            const collect = (root) => {
+                if (root == null || typeof root.querySelectorAll !== "function")
+                    return;
+                let nodes = [];
+                if (mode === "css") {
+                    try {
+                        nodes = Array.from(root.querySelectorAll(value));
+                    }
+                    catch {
+                        nodes = [];
+                    }
+                }
+                else {
+                    nodes = Array.from(root.querySelectorAll("*"));
+                }
+                for (const n of nodes)
+                    all.push(n);
+                for (const el of Array.from(root.querySelectorAll("*"))) {
+                    const sr = el.shadowRoot;
+                    if (sr != null)
+                        collect(sr);
+                }
+            };
+            collect(document);
+            let pool;
+            if (mode === "css") {
+                pool = all.filter(isVisible);
+            }
+            else {
+                const want = norm(value);
+                if (want.length === 0) {
+                    return {
+                        element: null,
+                        count: 0,
+                        candidates: [],
+                        text: "",
+                        safetySignals: { billingObject: false, accountSetup: false },
+                    };
+                }
+                const affordable = all.filter((el) => isVisible(el) && hasClickAffordance(el));
+                const exact = affordable.filter((el) => rendered(el) === want);
+                // Prefer exact-text matches; only fall back to "contains" (with a
+                // length guard so a big wrapper doesn't swallow the query) when no
+                // element's rendered text equals the query.
+                pool =
+                    exact.length > 0
+                        ? exact
+                        : affordable.filter((el) => {
+                            const t = rendered(el);
+                            return t.includes(want) && t.length <= Math.max(80, want.length + 20);
+                        });
+            }
+            // Bound the O(n²) nesting-collapse below: a broad selector (css=* /
+            // css=div) can match thousands of nodes, and a pairwise `contains` scan
+            // over all of them would block the page for seconds. A pool this large
+            // is ambiguous by any measure (the caller wants exactly one), so
+            // short-circuit to ambiguous before the quadratic pass (no-mistakes review).
+            const AMBIGUOUS_POOL_CAP = 40;
+            if (pool.length > AMBIGUOUS_POOL_CAP) {
+                return {
+                    element: null,
+                    count: pool.length,
+                    candidates: pool.slice(0, 8).map((el) => renderedRaw(el).slice(0, 60)),
+                    text: "",
+                    safetySignals: { billingObject: false, accountSetup: false },
+                };
+            }
+            // Collapse nesting WITHOUT silently merging two genuine controls. A
+            // STRONG candidate (real interactive semantics) always survives. A WEAK
+            // candidate (only inherits cursor:pointer — a decorative wrapper or the
+            // inner label span of a real control) is dropped only when it sits
+            // inside a strong candidate (it's part of that control's subtree, e.g.
+            // Casetify's <span> inside the button <div>). Two WEAK candidates in a
+            // nesting relationship — each a bare click-handler div with its own
+            // listener — are NOT collapsed:
+            // dropping the outer would pick the inner, whose click bubbles to the
+            // outer and fires BOTH handlers (a double add-to-cart). They both
+            // survive → reported ambiguous rather than silently double-clicked (codex).
+            const leaves = pool.filter((el) => {
+                if (isStrong(el))
+                    return true;
+                for (const other of pool) {
+                    if (other === el)
+                        continue;
+                    if (other.contains(el) && isStrong(other))
+                        return false;
+                }
+                return true;
+            });
+            const uniq = Array.from(new Set(leaves));
+            const candidates = uniq.slice(0, 8).map((el) => renderedRaw(el).slice(0, 60));
+            const win = uniq.length === 1 ? uniq[0] : null;
+            return {
+                element: win,
+                count: uniq.length,
+                candidates,
+                text: win !== null ? renderedRaw(win).slice(0, 120) : "",
+                safetySignals: win !== null ? safetySignalsFor(win) : { billingObject: false, accountSetup: false },
+            };
+        }, { mode, value });
+        const meta = await resultHandle.evaluate((r) => ({
+            count: r.count,
+            candidates: r.candidates,
+            text: r.text,
+            safetySignals: r.safetySignals,
+        }));
+        if (meta.count !== 1) {
+            await resultHandle.dispose();
+            return {
+                ok: false,
+                reason: meta.count === 0 ? "none" : "ambiguous",
+                candidates: meta.candidates,
+            };
+        }
+        // Pull out a live ElementHandle to the winning node; dispose the wrapper.
+        const winHandle = await resultHandle.evaluateHandle((r) => r.element);
+        await resultHandle.dispose();
+        const asElement = winHandle.asElement();
+        if (asElement === null) {
+            await winHandle.dispose();
+            return { ok: false, reason: "none", candidates: meta.candidates };
+        }
+        return {
+            ok: true,
+            handle: asElement,
+            text: meta.text ?? "",
+            safetySignals: meta.safetySignals ?? { billingObject: false, accountSetup: false },
+        };
+    }
+    async locatorClickState(handle) {
+        return await handle.evaluate((el) => {
+            if (!el.isConnected)
+                return "detached";
+            if (typeof el.matches === "function" && el.matches(":disabled"))
+                return "disabled";
+            let n = el;
+            while (n !== null) {
+                if (n.getAttribute("aria-disabled") === "true")
+                    return "disabled";
+                const parentEl = n.parentElement;
+                if (parentEl !== null) {
+                    n = parentEl;
+                }
+                else {
+                    const root = n.getRootNode();
+                    n = root instanceof ShadowRoot ? root.host : null;
+                }
+            }
+            return "ok";
+        });
+    }
+    async clickHandle(handle) {
+        const state = await this.locatorClickState(handle);
+        if (state === "detached") {
+            throw new Error("locator target detached from the page before the click");
+        }
+        if (state === "disabled") {
+            throw new Error("locator target is disabled");
+        }
+        await handle.click({ timeout: 8000, noWaitAfter: true });
+    }
+    async jsClickHandle(handle) {
+        const state = await this.locatorClickState(handle);
+        if (state === "detached") {
+            throw new Error("locator target detached from the page before the click");
+        }
+        if (state === "disabled") {
+            throw new Error("locator target is disabled");
+        }
+        const dispatchState = await handle.evaluate((el) => {
+            if (!el.isConnected)
+                return "detached";
+            if (typeof el.matches === "function" && el.matches(":disabled"))
+                return "disabled";
+            let n = el;
+            while (n !== null) {
+                if (n.getAttribute("aria-disabled") === "true")
+                    return "disabled";
+                const parentEl = n.parentElement;
+                if (parentEl !== null) {
+                    n = parentEl;
+                }
+                else {
+                    const root = n.getRootNode();
+                    n = root instanceof ShadowRoot ? root.host : null;
+                }
+            }
+            el.click();
+            return "ok";
+        });
+        if (dispatchState === "detached") {
+            throw new Error("locator target detached from the page before the click");
+        }
+        if (dispatchState === "disabled") {
+            throw new Error("locator target is disabled");
+        }
+    }
     // Dispatch a DOM .click() in the page context. Some React copy buttons fire
     // their onClick (and thus navigator.clipboard.writeText) on the synthetic
     // event a real Playwright mouse click doesn't reliably reproduce (deepinfra's
@@ -3015,14 +3333,19 @@ export class BrowserController {
                         .find((o) => o.textContent?.toLowerCase().includes(needle));
                     return hit !== undefined ? { value: hit.value } : null;
                 }, matcherLower);
-                if (matched !== null) {
-                    chosenValue = matched.value;
+                if (matched === null) {
+                    throw new Error(`<select> ${activeSelector}: no option matched ${JSON.stringify(optionMatcher)}`);
                 }
+                chosenValue = matched.value;
             }
             if (chosenValue === undefined) {
                 throw new Error(`<select> ${activeSelector} has no selectable option`);
             }
             await this.page.selectOption(activeSelector, chosenValue);
+            const committedValue = await this.page.locator(activeSelector).first().inputValue();
+            if (committedValue !== chosenValue) {
+                throw new Error(`<select> ${activeSelector}: selected value ${JSON.stringify(chosenValue)} did not stick`);
+            }
             // rc.17 — mark the element as touched so subsequent inventory
             // reads can suppress the DEFAULTED-dropdown warning for it.
             // Without this, a select whose committed value is "" (Railway's
@@ -3043,40 +3366,252 @@ export class BrowserController {
         // — every modern React picker emits role=option on its items.
         await this.selectFromCombobox(activeSelector, optionMatcher);
     }
-    // F11 (+rc.7 hardening): click a combobox trigger, wait for the
-    // listbox to open, click an option.
-    //
-    // Tries option-selector patterns in priority order — each tier
-    // targets one combobox-library convention. The text-based final
-    // tier catches libraries that ship NO ARIA roles at all.
-    //
-    //   1. [role=option]            — Radix, Headless UI, React Aria, cmdk
-    //   2. [role=menuitem]          — ARIA menu pattern (libs that model
-    //                                 a dropdown as a menu)
-    //   3. [role=menuitemradio]     — react-select's per-row permission
-    //                                 picker shape (rc.15 — Sentry's
-    //                                 token-create grid). Identical shape
-    //                                 to menuitem for selection purposes,
-    //                                 distinct role string. Without this
-    //                                 tier Sentry's "Team permission =
-    //                                 Admin" never resolves and the loop
-    //                                 burns the post-verify budget.
-    //   4. [id^="react-select-"]    — defense-in-depth for any react-
-    //                                 select instance that drops the
-    //                                 role attribute. The id prefix is
-    //                                 baked into the library and is the
-    //                                 most stable signal short of the
-    //                                 role.
-    //   5. [role=listbox] li        — listbox container without role
-    //                                 attribute on its children
-    //   6. text-based (matcher only) — after the trigger click, any newly-
-    //                                 visible element whose text matches
-    //                                 the planner-supplied label is
-    //                                 almost certainly the option. Only
-    //                                 enabled when a matcher exists,
-    //                                 since "first text on the page"
-    //                                 with no matcher would catch
-    //                                 unrelated UI text.
+    // Set the country on a phone-number field backed by a phone-local native
+    // <select>, including react-phone-number-input's opacity:0 country select.
+    // The inventory walker omits that hidden control and Playwright refuses to
+    // select it, so this path uses the native value setter, dispatches change,
+    // and verifies the selected value. Custom phone widget families are not
+    // supported and fail loudly.
+    async setPhoneCountry(country) {
+        if (!this.page)
+            throw new Error("Browser not started");
+        const query = classifyPhoneCountryQuery(country);
+        if (query.dialCode === undefined && query.iso2 === undefined && query.name === undefined) {
+            throw new Error("setPhoneCountry: empty country argument");
+        }
+        await this.clearPhoneCountryMarkers();
+        if (await this.trySetPhoneCountryNativeSelect(query))
+            return;
+        throw new Error("set_phone_country: no supported native phone-country <select> found " +
+            "(this widget family is not supported yet) — enter a valid contact number instead.");
+    }
+    // Strategy 1 — a native <select> that governs the phone country (react-
+    // phone-number-input's `opacity:0` PhoneInputCountrySelect, or any bespoke
+    // widget backed by a real <select>). Detection is deliberately conservative
+    // so it does NOT grab the address "country" select that lives elsewhere on
+    // the checkout: a select qualifies only when its class/name/id names it a
+    // PHONE control and its options carry country evidence, or its options look
+    // like countries AND it is a direct sibling of the tel input or lives in an
+    // immediately adjacent wrapper.
+    // Returns false when no such select exists; throws when one is found but the
+    // requested country isn't among its options.
+    async trySetPhoneCountryNativeSelect(query) {
+        if (!this.page)
+            throw new Error("Browser not started");
+        const candidates = await this.page.evaluate(() => {
+            const out = [];
+            const selects = Array.from(document.querySelectorAll("select"));
+            selects.forEach((sel, i) => {
+                if (!(sel instanceof HTMLSelectElement))
+                    return;
+                const hay = `${sel.className} ${sel.getAttribute("name") ?? ""} ${sel.id}`.toLowerCase();
+                const phoneNamed = /phone|dial|calling/.test(hay);
+                let telDistance = Number.POSITIVE_INFINITY;
+                const isTel = (el) => el?.matches('input[type="tel"]') === true;
+                const parent = sel.parentElement;
+                if (parent !== null &&
+                    parent.tagName !== "FORM" &&
+                    (isTel(sel.previousElementSibling) || isTel(sel.nextElementSibling))) {
+                    telDistance = 0;
+                }
+                else if (parent !== null &&
+                    parent.tagName !== "FORM" &&
+                    Array.from(parent.children).some(isTel)) {
+                    telDistance = 1;
+                }
+                const options = Array.from(sel.options).map((o) => ({
+                    value: o.value,
+                    text: (o.textContent ?? "").replace(/\s+/g, " ").trim(),
+                }));
+                const isoish = options.filter((o) => /^[A-Za-z]{2}$/.test(o.value)).length;
+                const dialish = options.filter((o) => /\+\d/.test(o.text) || /^\+?\d{1,4}$/.test(o.value)).length;
+                const explicitDialish = options.filter((o) => /\+\d/.test(o.text) || /^\+\d{1,4}$/.test(o.value)).length;
+                const countryish = options.length >= 10 && (isoish >= 5 || dialish >= 5);
+                const countryNamed = /country|nation|iso/.test(hay);
+                const dialCodeNamed = /dial|calling/.test(hay);
+                const phoneCountryish = countryish ||
+                    explicitDialish > 0 ||
+                    (dialCodeNamed && dialish >= 2) ||
+                    (countryNamed && isoish >= 2);
+                if ((phoneNamed && phoneCountryish) || (countryish && telDistance <= 1)) {
+                    sel.setAttribute("data-ts-phone-cc", String(i));
+                    out.push({
+                        marker: i,
+                        options,
+                        phoneNamed,
+                        telDistance: telDistance === Number.POSITIVE_INFINITY ? 99 : telDistance,
+                    });
+                }
+            });
+            return out;
+        });
+        if (candidates.length === 0)
+            return false;
+        // Prefer a phone-NAMED select, then the one physically closest to a tel
+        // input — the strongest evidence it's the dial-code control, not address.
+        candidates.sort((a, b) => Number(b.phoneNamed) - Number(a.phoneNamed) || a.telDistance - b.telDistance);
+        const best = candidates[0];
+        if (best === undefined)
+            return false;
+        const opts = best.options.map((o) => ({
+            text: o.text.length > 0 ? o.text : undefined,
+            iso2: /^[A-Za-z]{2}$/.test(o.value) ? o.value.toUpperCase() : undefined,
+            dialCode: /^\+?\d{1,4}$/.test(o.value) ? o.value.replace(/\D/g, "") : undefined,
+        }));
+        const idx = pickPhoneCountryOption(query, opts);
+        const chosenOpt = idx === -1 ? undefined : best.options[idx];
+        if (chosenOpt === undefined) {
+            await this.clearPhoneCountryMarkers();
+            const sample = best.options
+                .map((o) => o.text)
+                .filter((t) => t.length > 0)
+                .slice(0, 6)
+                .join(" | ");
+            throw new Error(`setPhoneCountry: native phone <select> found but no option matched ` +
+                `${JSON.stringify(query)} (sample: ${sample})`);
+        }
+        const value = chosenOpt.value;
+        // Set through the native value setter + a dispatched `change` so a React-
+        // controlled select (react-phone-number-input) sees the update: assigning
+        // .value directly is swallowed by React's value tracker, so we go through
+        // the prototype setter the tracker also patches, then fire the event React
+        // listens on. Works on the opacity:0 select without a visibility check.
+        const assigned = await this.page.evaluate(({ marker, val }) => {
+            const sel = document.querySelector(`select[data-ts-phone-cc="${marker}"]`);
+            if (!(sel instanceof HTMLSelectElement))
+                return false;
+            const desc = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, "value");
+            if (desc?.set !== undefined)
+                desc.set.call(sel, val);
+            else
+                sel.value = val;
+            sel.dispatchEvent(new Event("input", { bubbles: true }));
+            sel.dispatchEvent(new Event("change", { bubbles: true }));
+            return true;
+        }, { marker: best.marker, val: value });
+        const committedValue = assigned
+            ? await this.page
+                .locator(`select[data-ts-phone-cc="${best.marker}"]`)
+                .inputValue()
+                .catch(() => "")
+            : "";
+        await this.clearPhoneCountryMarkers();
+        if (!assigned || committedValue !== value) {
+            throw new Error(`setPhoneCountry: native phone <select> did not retain value ${JSON.stringify(value)}`);
+        }
+        return true;
+    }
+    async clearPhoneCountryMarkers() {
+        if (!this.page)
+            return;
+        await this.page
+            .evaluate(() => {
+            document.querySelectorAll("[data-ts-phone-cc]").forEach((el) => {
+                el.removeAttribute("data-ts-phone-cc");
+            });
+        })
+            .catch(() => { });
+    }
+    async markComboboxPreexistingElements() {
+        if (!this.page)
+            throw new Error("Browser not started");
+        await this.page.evaluate(() => {
+            const visible = (el) => {
+                const rect = el.getBoundingClientRect();
+                if (rect.width < 2 || rect.height < 2)
+                    return false;
+                const style = getComputedStyle(el);
+                return (style.display !== "none" &&
+                    style.visibility !== "hidden" &&
+                    parseFloat(style.opacity || "1") > 0.01);
+            };
+            const popupSelector = '[role="listbox"],[role="menu"],[role="dialog"],[id*="listbox" i],[id*="dropdown" i],[id*="popover" i],[id*="menu" i],[id*="options" i],[class*="listbox" i],[class*="dropdown" i],[class*="popover" i],[class*="menu" i],[class*="options" i]';
+            document
+                .querySelectorAll(popupSelector)
+                .forEach((el) => visible(el) && el.setAttribute("data-ts-select-preexisting-popup", "1"));
+        });
+    }
+    async refreshComboboxMarkers(triggerSelector) {
+        if (!this.page)
+            throw new Error("Browser not started");
+        await this.page
+            .locator(triggerSelector)
+            .first()
+            .evaluate((trigger) => {
+            const visible = (el) => {
+                const rect = el.getBoundingClientRect();
+                if (rect.width < 2 || rect.height < 2)
+                    return false;
+                const style = getComputedStyle(el);
+                return (style.display !== "none" &&
+                    style.visibility !== "hidden" &&
+                    parseFloat(style.opacity || "1") > 0.01);
+            };
+            document
+                .querySelectorAll("[data-ts-select-popup],[data-ts-select-option-tier]")
+                .forEach((el) => {
+                el.removeAttribute("data-ts-select-popup");
+                el.removeAttribute("data-ts-select-option-tier");
+            });
+            const popupSelector = '[role="listbox"],[role="menu"],[role="dialog"],[id*="listbox" i],[id*="dropdown" i],[id*="popover" i],[id*="menu" i],[id*="options" i],[class*="listbox" i],[class*="dropdown" i],[class*="popover" i],[class*="menu" i],[class*="options" i]';
+            const controlledPopups = [];
+            for (const attr of ["aria-controls", "aria-owns"]) {
+                for (const id of (trigger.getAttribute(attr) ?? "").split(/\s+/).filter(Boolean)) {
+                    const popup = trigger.ownerDocument.getElementById(id);
+                    if (popup !== null && visible(popup) && !controlledPopups.includes(popup)) {
+                        controlledPopups.push(popup);
+                    }
+                }
+            }
+            const openedPopups = [];
+            trigger.ownerDocument.querySelectorAll(popupSelector).forEach((el) => {
+                if (!el.hasAttribute("data-ts-select-preexisting-popup") &&
+                    visible(el) &&
+                    !openedPopups.includes(el)) {
+                    openedPopups.push(el);
+                }
+            });
+            const singlePopup = (candidates) => {
+                const semantic = candidates.filter((el) => el.matches('[role="listbox"],[role="dialog"],[role="menu"]'));
+                const pool = semantic.length > 0 ? semantic : candidates;
+                const innermost = pool.filter((candidate) => !pool.some((other) => other !== candidate && candidate.contains(other)));
+                return innermost.length === 1 ? innermost[0] : undefined;
+            };
+            const popup = controlledPopups.length > 0 ? singlePopup(controlledPopups) : singlePopup(openedPopups);
+            popup?.setAttribute("data-ts-select-popup", "1");
+            const optionSelectors = [
+                '[role="option"]',
+                '[role="menuitem"]',
+                '[role="menuitemradio"]',
+                "mat-option",
+                ".mat-mdc-option",
+                '[id^="react-select-"][role*="menu"]',
+                '[role="listbox"] li',
+            ];
+            optionSelectors.forEach((selector, tier) => {
+                trigger.ownerDocument.querySelectorAll(selector).forEach((el) => {
+                    if (popup !== undefined && visible(el) && (popup === el || popup.contains(el))) {
+                        el.setAttribute("data-ts-select-option-tier", String(tier));
+                    }
+                });
+            });
+        });
+    }
+    async clearComboboxMarkers() {
+        if (!this.page)
+            return;
+        await this.page
+            .evaluate(() => {
+            document
+                .querySelectorAll("[data-ts-select-preexisting-popup],[data-ts-select-popup],[data-ts-select-option-tier]")
+                .forEach((el) => {
+                el.removeAttribute("data-ts-select-preexisting-popup");
+                el.removeAttribute("data-ts-select-popup");
+                el.removeAttribute("data-ts-select-option-tier");
+            });
+        })
+            .catch(() => { });
+    }
     async selectFromCombobox(triggerSelector, optionMatcher) {
         if (!this.page)
             throw new Error("Browser not started");
@@ -3091,67 +3626,36 @@ export class BrowserController {
         // label to its associated input here so downstream tiers (the
         // keyboard fallback in particular) actually see an input target.
         const normalizedSelector = await this.resolveLabelToInput(triggerSelector);
-        await this.humanClick(normalizedSelector);
-        const patternSelectors = [
-            '[role="option"]:visible',
-            '[role="menuitem"]:visible',
-            '[role="menuitemradio"]:visible',
-            "mat-option:visible",
-            ".mat-mdc-option:visible",
-            '[id^="react-select-"][role*="menu"]:visible',
-            '[role="listbox"]:visible li:visible',
-        ];
-        const triedDescriptors = [];
-        for (const sel of patternSelectors) {
-            triedDescriptors.push(sel);
-            const locator = this.page.locator(sel);
-            try {
-                await locator.first().waitFor({ state: "visible", timeout: 1500 });
+        await this.markComboboxPreexistingElements();
+        try {
+            await this.humanClick(normalizedSelector);
+            await this.refreshComboboxMarkers(normalizedSelector);
+            let popup = this.page.locator('[data-ts-select-popup="1"]').first();
+            if ((await popup.count()) === 0) {
+                await this.openComboboxWithKeyboard(normalizedSelector);
+                await this.refreshComboboxMarkers(normalizedSelector);
+                popup = this.page.locator('[data-ts-select-popup="1"]').first();
+            }
+            if ((await popup.count()) === 0) {
+                throw new Error(`combobox ${triggerSelector}: no single opened popup could be resolved`);
+            }
+            const options = this.page.locator("[data-ts-select-option-tier]");
+            let target = options.first();
+            if (optionMatcher !== undefined) {
+                const matching = options.filter({ hasText: optionMatcher });
+                if ((await matching.count()) === 0) {
+                    throw new Error(`combobox ${triggerSelector}: no option matched ${JSON.stringify(optionMatcher)}`);
+                }
+                target = matching.first();
             }
-            catch {
-                continue;
+            else if ((await options.count()) === 0) {
+                throw new Error(`combobox ${triggerSelector}: opened popup has no actionable options`);
             }
-            const count = await locator.count();
-            if (count === 0)
-                continue;
-            await this.pickComboboxOption(locator, optionMatcher);
-            return;
-        }
-        // 0.8.2-rc.11 — keyboard-driven react-select fallback. Sentry's
-        // permission-grid combobox (Project--permission, Team--permission,
-        // …) is a react-select 5 instance: clicking the inner <input> only
-        // focuses it; the menu opens on keyboard activity. The standard
-        // pattern is: Alt+Down (or just type a character) to open + filter,
-        // then Enter to commit. Try Alt+Down first so an instance with
-        // visible options but no role="option" still works; then if a
-        // matcher was given, type-to-filter + Enter so a hidden listbox
-        // narrows directly to the right option.
-        if (await this.tryReactSelectKeyboardPick(normalizedSelector, optionMatcher)) {
-            return;
+            await this.clickComboboxOption(target);
         }
-        triedDescriptors.push("react-select keyboard (Alt+Down, type-to-filter, Enter)");
-        // ARIA tiers all empty. Text-based fallback, only if the planner
-        // told us WHICH option to pick — without a matcher, "first text
-        // on the page" would click unrelated UI.
-        if (optionMatcher !== undefined) {
-            const byText = this.page.getByText(optionMatcher, { exact: false }).first();
-            triedDescriptors.push(`text="${optionMatcher}"`);
-            try {
-                await byText.waitFor({ state: "visible", timeout: 2000 });
-                await this.humanClickLocator(byText);
-                await this.wait(0.5);
-                return;
-            }
-            catch {
-                // not found — fall through to error
-            }
+        finally {
+            await this.clearComboboxMarkers();
         }
-        throw new Error(`combobox ${triggerSelector}` +
-            (normalizedSelector !== triggerSelector ? ` (normalized to ${normalizedSelector})` : "") +
-            `: no options found after click. ` +
-            `Tried: ${triedDescriptors.join(", ")}. ` +
-            `The trigger may not have opened a popover, or the popover uses ` +
-            `an option pattern this executor doesn't recognize.`);
     }
     // 0.8.2-rc.11 — resolve a `<label for="X">` selector to `#X` so the
     // executor lands on the actual input rather than the label decoration.
@@ -3203,120 +3707,22 @@ export class BrowserController {
             return selector;
         }
     }
-    // 0.8.2-rc.11 — keyboard-driven react-select interaction. The
-    // trigger is the inner <input>; opening the menu via mouse click
-    // alone isn't reliable on every react-select instance (Sentry's
-    // permission grid). Sequence:
-    //   1. focus the trigger (the click already happened in
-    //      selectFromCombobox, but a defensive .focus() handles the
-    //      case where the click went to a sibling overlay).
-    //   2. press Alt+ArrowDown — react-select binds this to open the
-    //      menu and select the first option.
-    //   3. if a matcher was given, type its first 1-3 letters to filter
-    //      the menu down to the right option, then press Enter to
-    //      commit.
-    //   4. if no matcher, ArrowDown was already issued — press Enter to
-    //      commit the first option.
-    // Verify via the input's aria-activedescendant or value attribute
-    // changing (react-select updates one or the other on selection).
-    // Returns true on success, false when the page didn't react.
-    async tryReactSelectKeyboardPick(triggerSelector, optionMatcher) {
+    async openComboboxWithKeyboard(triggerSelector) {
         if (!this.page)
             throw new Error("Browser not started");
-        const triggerLocator = this.page.locator(triggerSelector);
-        try {
-            const tagName = await triggerLocator.first().evaluate((node) => node.tagName.toLowerCase());
-            // Limit this path to input-typed triggers; native <select> and
-            // <button role="combobox"> are handled by other tiers. The
-            // selectFromCombobox caller has already returned for matching
-            // [role="option"] tiers, so we only reach here on patterns where
-            // the trigger is an input.
-            if (tagName !== "input")
-                return false;
-        }
-        catch {
-            return false;
-        }
-        try {
-            await triggerLocator.first().focus({ timeout: 1500 });
-        }
-        catch {
-            return false;
-        }
-        // Snapshot the input's relevant attributes BEFORE opening so we
-        // can verify that the pick actually committed.
-        const before = await triggerLocator
-            .first()
-            .evaluate((node) => ({
-            activedescendant: node.getAttribute("aria-activedescendant") ?? "",
-            value: node instanceof HTMLInputElement ? node.value : "",
-            // react-select 5 mirrors the selected value into the closest
-            // .css-{hash}-singleValue node; grab the trigger's surrounding
-            // text so a successful pick produces an observable change.
-            surroundingText: node.parentElement?.parentElement?.parentElement?.textContent ?? "",
-        }))
-            .catch(() => ({ activedescendant: "", value: "", surroundingText: "" }));
-        // Press Alt+ArrowDown to open + highlight the first option, then
-        // if a matcher exists, type to filter, then Enter.
+        const trigger = this.page.locator(triggerSelector).first();
         try {
+            if ((await trigger.evaluate((node) => node.tagName.toLowerCase())) !== "input")
+                return;
+            await trigger.focus({ timeout: 1500 });
             await this.page.keyboard.press("Alt+ArrowDown");
+            await this.wait(0.4);
         }
         catch {
-            return false;
-        }
-        // Wait briefly for the menu to render.
-        await this.wait(0.4);
-        if (optionMatcher !== undefined && optionMatcher.length > 0) {
-            // Type a few characters to filter; react-select narrows on each
-            // keystroke. Capping at 6 keeps the input from overshooting on
-            // a long matcher when the first few characters already narrow
-            // to a single option ("Admin" → typing "Adm" is enough).
-            const typed = optionMatcher.slice(0, 6);
-            try {
-                await triggerLocator.first().pressSequentially(typed, { delay: 25 });
-            }
-            catch {
-                return false;
-            }
-            await this.wait(0.35);
-        }
-        try {
-            await this.page.keyboard.press("Enter");
-        }
-        catch {
-            return false;
+            return;
         }
-        await this.wait(0.5);
-        const after = await triggerLocator
-            .first()
-            .evaluate((node) => ({
-            activedescendant: node.getAttribute("aria-activedescendant") ?? "",
-            value: node instanceof HTMLInputElement ? node.value : "",
-            surroundingText: node.parentElement?.parentElement?.parentElement?.textContent ?? "",
-        }))
-            .catch(() => ({ activedescendant: "", value: "", surroundingText: "" }));
-        // A successful pick produces at least one observable change.
-        // react-select clears the input's value once a selection commits
-        // (the chosen label moves into a sibling singleValue node), so the
-        // surrounding-text diff is the strongest signal.
-        if (before.surroundingText !== after.surroundingText)
-            return true;
-        if (before.activedescendant !== after.activedescendant)
-            return true;
-        if (before.value !== after.value)
-            return true;
-        return false;
     }
-    // F11: pick an option from a Playwright Locator already-narrowed to
-    // candidates. Matcher → filter by hasText (case-insensitive by
-    // default in Playwright). No matcher → first.
-    async pickComboboxOption(options, matcher) {
-        let target = options.first();
-        if (matcher !== undefined) {
-            const filtered = options.filter({ hasText: matcher });
-            if ((await filtered.count()) > 0)
-                target = filtered.first();
-        }
+    async clickComboboxOption(target) {
         // cmdk (the command-menu library) does NOT commit a selection from the
         // bot's humanized page.mouse.click(x, y): cmdk re-renders + re-orders its
         // list as the search filters, so the cached click coordinates land on the
@@ -3337,11 +3743,9 @@ export class BrowserController {
             // full trusted pointer/mouse sequence at the element's center — what
             // cmdk's onSelect actually listens for.
             await target.click({ timeout: 5000 }).catch(async () => {
-                // Backup: dispatch the pointer pair directly, then Enter (the cmdk
-                // input is focused after type-to-filter and highlights this item).
-                await target.dispatchEvent("pointerdown").catch(() => { });
-                await target.dispatchEvent("pointerup").catch(() => { });
-                await this.page?.keyboard.press("Enter").catch(() => { });
+                await target.dispatchEvent("pointerdown");
+                await target.dispatchEvent("pointerup");
+                await target.dispatchEvent("click");
             });
             await this.wait(0.5);
             return;
@@ -6693,11 +7097,37 @@ export class BrowserController {
                     return { topmost: false, occludedBy: null };
                 const x = Math.min(window.innerWidth - 1, Math.max(0, r.left + r.width / 2));
                 const y = Math.min(window.innerHeight - 1, Math.max(0, r.top + r.height / 2));
-                const top = document.elementFromPoint(x, y);
+                let top = document.elementFromPoint(x, y);
                 if (top === null)
                     return { topmost: false, occludedBy: null };
+                // document.elementFromPoint returns the shadow HOST, not the control
+                // nested in its open shadow root — so a shadow-DOM CTA (Casetify's
+                // Add-to-Cart web component) hit-tested against its own host would be
+                // reported occludedBy that host and topmost:false, and the host agent
+                // would skip a button nothing actually covers. Re-hit-test inside each
+                // open shadow root at the same point to reach the deepest composed
+                // element, matching what the user's pointer would strike. Closed roots
+                // yield a null shadowRoot and the descent stops — same as the DOM.
+                while (top.shadowRoot !== null) {
+                    const deeper = top.shadowRoot.elementFromPoint(x, y);
+                    if (deeper === null || deeper === top)
+                        break;
+                    top = deeper;
+                }
                 if (top === el || el.contains(top))
                     return { topmost: true, occludedBy: null };
+                let owner = top;
+                while (owner !== null) {
+                    if (owner === el)
+                        return { topmost: true, occludedBy: null };
+                    const assignedSlot = owner instanceof Element || owner instanceof Text ? owner.assignedSlot : null;
+                    if (assignedSlot !== null) {
+                        owner = assignedSlot;
+                        continue;
+                    }
+                    const parent = owner.parentNode;
+                    owner = parent instanceof ShadowRoot ? parent.host : parent;
+                }
                 return { topmost: false, occludedBy: regionName(regionFor(top)) ?? elementKind(top) };
             };
             // N1 onboarding-wizard cards (2026-06-08). Chakra/React card pickers
@@ -7974,6 +8404,53 @@ export function isBareClickableCardTag(tag) {
         t === "label" ||
         t.includes("-"));
 }
+// Classify the operator's single country argument. WHY exact-signal buckets:
+// "+1" is a dial code, "US" an ISO2, "United States" a name — matching each
+// against the wrong DOM attribute (e.g. substring-matching "US" against option
+// text) produces false hits, so we commit to one interpretation per input.
+export function classifyPhoneCountryQuery(raw) {
+    const t = raw.trim();
+    if (t.length === 0)
+        return {};
+    // Dial code: an optional leading "+" then 1-4 digits and nothing else.
+    if (/^\+?\d{1,4}$/.test(t))
+        return { dialCode: t.replace(/\D/g, "") };
+    // ISO2: exactly two ASCII letters. Almost always an alpha-2 country code
+    // ("JP", "US"); a two-letter country NAME doesn't exist, so this is safe.
+    if (/^[A-Za-z]{2}$/.test(t))
+        return { iso2: t.toUpperCase() };
+    // Otherwise a free-text country name for case-insensitive substring match.
+    return { name: t.toLowerCase() };
+}
+// Decide whether a picker option satisfies the query. Exact-signal queries
+// (iso2/dialCode) match ONLY against the corresponding structured field (with
+// a dial-code fallback to a "+NN" embedded in native option text). A name query is a
+// case-insensitive substring test against the option's visible text.
+export function phoneCountryOptionMatches(query, opt) {
+    const digits = (s) => s.replace(/\D/g, "");
+    if (query.iso2 !== undefined) {
+        return opt.iso2 !== undefined && opt.iso2.toUpperCase() === query.iso2;
+    }
+    if (query.dialCode !== undefined) {
+        if (opt.dialCode !== undefined && digits(opt.dialCode) === query.dialCode)
+            return true;
+        if (opt.text !== undefined) {
+            const m = opt.text.match(/\+(\d{1,4})/);
+            if (m !== null && m[1] === query.dialCode)
+                return true;
+        }
+        return false;
+    }
+    if (query.name !== undefined) {
+        return opt.text !== undefined && opt.text.toLowerCase().includes(query.name);
+    }
+    return false;
+}
+// Index of the first option matching the query, or -1. Extracted so the
+// pick-a-row decision is unit-tested independently of the DOM read.
+export function pickPhoneCountryOption(query, options) {
+    return options.findIndex((o) => phoneCountryOptionMatches(query, o));
+}
 //
 // Exported for unit testing — the scoring is the load-bearing logic.
 export function pickSubmitButtonIndex(texts) {