arise-browser 0.1.0

package/dist/src/browser/action-executor.js

@@ -0,0 +1,2726 @@
+/**
+ * ActionExecutor — Executes high-level actions on a Playwright Page.
+ *
+ * Action types: click, type, select, wait, extract, scroll, enter,
+ * mouse_control, mouse_drag, press_key, navigate, back, forward,
+ * hover, focus
+ *
+ * Click: supports aria-ref/CSS selector, prefers regular click,
+ * and validates observable state change to avoid false success.
+ * Mouse control: JS elementFromPoint + dispatchEvent.
+ */
+import { BrowserConfig } from "./config.js";
+import { createLogger } from "../logger.js";
+const logger = createLogger("action-executor");
+function escapeRef(ref) {
+    return ref.replace(/['"\\]/g, "");
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export class ActionExecutor {
+    page;
+    session;
+    defaultTimeout;
+    shortTimeout;
+    maxScrollAmount;
+    constructor(page, session) {
+        this.page = page;
+        this.session = session;
+        this.defaultTimeout = BrowserConfig.actionTimeout;
+        this.shortTimeout = BrowserConfig.shortTimeout;
+        this.maxScrollAmount = BrowserConfig.maxScrollAmount;
+    }
+    async execute(action) {
+        if (!action) {
+            return { success: false, message: "No action to execute", details: {} };
+        }
+        const actionType = action.type;
+        if (!actionType) {
+            return { success: false, message: "Error: action has no type", details: {} };
+        }
+        try {
+            const handlers = {
+                click: (a) => this._click(a),
+                type: (a) => this._type(a),
+                select: (a) => this._select(a),
+                wait: (a) => this._wait(a),
+                extract: (a) => this._extract(a),
+                scroll: (a) => this._scroll(a),
+                enter: (a) => this._enter(a),
+                mouse_control: (a) => this._mouseControl(a),
+                mouse_drag: (a) => this._mouseDrag(a),
+                press_key: (a) => this._pressKey(a),
+                navigate: (a) => this._navigate(a),
+                back: (a) => this._back(a),
+                forward: (a) => this._forward(a),
+                hover: (a) => this._hover(a),
+                focus: (a) => this._focus(a),
+            };
+            const handler = handlers[actionType];
+            if (!handler) {
+                return {
+                    success: false,
+                    message: `Error: Unknown action type '${actionType}'`,
+                    details: { action_type: actionType },
+                };
+            }
+            const result = await handler(action);
+            return { success: result.success, message: result.message, details: result.details };
+        }
+        catch (exc) {
+            logger.error({ actionType, err: exc }, "Action execution failed");
+            return {
+                success: false,
+                message: `Error executing ${actionType}: ${exc}`,
+                details: { action_type: actionType, error: String(exc) },
+            };
+        }
+    }
+    static shouldUpdateSnapshot(action) {
+        const changeTypes = new Set([
+            "click", "type", "select", "scroll", "navigate",
+            "enter", "back", "forward", "mouse_control", "mouse_drag", "press_key",
+            "hover", "focus",
+        ]);
+        return changeTypes.has(action.type);
+    }
+    // ===== Click =====
+    async _click(action) {
+        const ref = action.ref;
+        const selector = action.selector;
+        const requestedIntent = this._normalizeClickIntent(action.clickIntent);
+        const requestedExpectedEffect = this._normalizeClickExpectedEffect(action.expectedEffect);
+        const requestedExpectedHref = typeof action.expectedHref === "string" && action.expectedHref.trim()
+            ? action.expectedHref.trim()
+            : null;
+        const requestedExpectedText = typeof action.expectedText === "string" && action.expectedText.trim()
+            ? action.expectedText.trim()
+            : null;
+        if (!ref && !selector) {
+            return { success: false, message: "Error: click requires ref or selector", details: { error: "missing_target" } };
+        }
+        let target = ref ? `[aria-ref='${escapeRef(ref)}']` : selector;
+        const details = {
+            ref: ref ?? null,
+            selector: selector ?? null,
+            target,
+            strategies_tried: [],
+            successful_strategy: null,
+            click_method: null,
+            new_tab_created: false,
+            click_intent_requested: requestedIntent,
+            expected_effect_requested: requestedExpectedEffect,
+            expected_href: requestedExpectedHref,
+            expected_text: requestedExpectedText,
+        };
+        let cleanupMarker = null;
+        try {
+            let element = this.page.locator(target).first();
+            let count = await element.count();
+            if (count === 0 && ref && (requestedExpectedHref || requestedExpectedText)) {
+                details.recovery_attempted = true;
+                const recovered = await this._recoverClickTarget(requestedExpectedHref, requestedExpectedText);
+                details.recovery_result = recovered.reason;
+                if (recovered.candidateCount !== undefined) {
+                    details.recovery_candidate_count = recovered.candidateCount;
+                }
+                if (recovered.matchedHref) {
+                    details.recovered_href = recovered.matchedHref;
+                }
+                if (recovered.matchedText) {
+                    details.recovered_text = recovered.matchedText;
+                }
+                if (!recovered.locator || !recovered.selector || !recovered.marker) {
+                    details.error = recovered.reason;
+                    return { success: false, message: `Error: Click failed, ${recovered.reason}`, details };
+                }
+                cleanupMarker = recovered.marker;
+                target = recovered.selector;
+                details.target = target;
+                details.recovered_target = target;
+                element = recovered.locator;
+                count = await element.count();
+            }
+            if (count === 0) {
+                details.error = "element_not_found";
+                return { success: false, message: "Error: Click failed, element not found", details };
+            }
+            details.successful_strategy = target;
+            let clickTarget = element;
+            // Collect element diagnostics
+            let elementDiag = null;
+            try {
+                const diag = await element.evaluate((el) => {
+                    const text = (el.innerText || el.textContent || "").trim();
+                    const rect = el.getBoundingClientRect();
+                    const inViewport = rect.width > 0 &&
+                        rect.height > 0 &&
+                        rect.bottom >= 0 &&
+                        rect.right >= 0 &&
+                        rect.top <= (window.innerHeight || document.documentElement.clientHeight) &&
+                        rect.left <= (window.innerWidth || document.documentElement.clientWidth);
+                    const closestLink = el.closest("a");
+                    const descendantLinks = el.querySelectorAll("a[href]");
+                    const descendantLink = descendantLinks.length === 1 ? descendantLinks[0] : null;
+                    const descendantText = descendantLink
+                        ? (descendantLink.innerText || descendantLink.textContent || "").trim()
+                        : "";
+                    return {
+                        tag: el.tagName,
+                        href: el.getAttribute("href"),
+                        closestHref: closestLink ? closestLink.getAttribute("href") : null,
+                        role: el.getAttribute("role"),
+                        text: text ? text.slice(0, 200) : "",
+                        descendantHref: descendantLink ? descendantLink.getAttribute("href") : null,
+                        descendantText: descendantText ? descendantText.slice(0, 200) : "",
+                        descendantCount: descendantLinks.length,
+                        onclick: !!el.getAttribute("onclick") || typeof el.onclick === "function",
+                        inViewport,
+                    };
+                });
+                elementDiag = diag;
+                logger.debug({ elementDiag }, "Click element diagnostics");
+            }
+            catch (e) {
+                logger.debug({ err: e }, "Click diagnostics failed");
+            }
+            // Conservative redirect: if container wraps a single link, prefer that link
+            try {
+                if (elementDiag) {
+                    const tag = elementDiag.tag;
+                    const href = elementDiag.href;
+                    const closestHref = elementDiag.closestHref;
+                    const hasOnclick = elementDiag.onclick;
+                    const descendantCount = elementDiag.descendantCount;
+                    const descendantHref = elementDiag.descendantHref;
+                    const sourceText = (elementDiag.text || "").trim();
+                    const descendantText = (elementDiag.descendantText || "").trim();
+                    const role = elementDiag.role;
+                    const roleIsLink = (role || "").toLowerCase() === "link";
+                    if (["LI", "DIV", "SPAN"].includes(tag) &&
+                        !href &&
+                        !closestHref &&
+                        !roleIsLink &&
+                        !hasOnclick &&
+                        descendantCount === 1 &&
+                        descendantHref &&
+                        sourceText &&
+                        descendantText &&
+                        (sourceText.toLowerCase().includes(descendantText.toLowerCase()) ||
+                            descendantText.toLowerCase().includes(sourceText.toLowerCase()))) {
+                        const descendantLocator = element.locator(":scope a[href]").first();
+                        if ((await descendantLocator.count()) > 0 &&
+                            (await descendantLocator.isVisible()) &&
+                            (await descendantLocator.isEnabled())) {
+                            clickTarget = descendantLocator;
+                            details.redirected_click_target = "descendant_a";
+                            details.descendant_href = descendantHref;
+                            logger.debug({ descendantHref }, "Redirecting click to descendant <a>");
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                logger.debug({ err: e }, "Descendant link check failed");
+            }
+            const beforeObservation = await this._captureClickObservation(clickTarget);
+            details.before_observation = beforeObservation;
+            const resolvedExpectedHref = this._resolveExpectedHref(requestedExpectedHref, elementDiag, beforeObservation.pageUrl);
+            const isLikelyLink = this._isLikelyLink(elementDiag) || !!resolvedExpectedHref;
+            const clickIntent = this._deriveClickIntent(requestedIntent, isLikelyLink, beforeObservation.pageUrl, resolvedExpectedHref);
+            details.click_intent = clickIntent;
+            details.expected_href = resolvedExpectedHref;
+            if (clickIntent === "auto") {
+                return await this._executeAutoClick(clickTarget, target, details, isLikelyLink, beforeObservation, requestedExpectedEffect);
+            }
+            if (clickIntent === "new_tab" && this.session) {
+                const newTabResult = await this._attemptCtrlClickNewTab(clickTarget, target, details, resolvedExpectedHref);
+                if (newTabResult) {
+                    return newTabResult;
+                }
+                details.new_tab_fallback = "same_tab";
+            }
+            if (clickIntent === "same_tab" || (clickIntent === "new_tab" && isLikelyLink)) {
+                return await this._executeSameTabLinkClick(clickTarget, target, details, resolvedExpectedHref, beforeObservation.pageUrl);
+            }
+            return await this._executeUiClick(clickTarget, target, details, beforeObservation, requestedExpectedEffect);
+        }
+        finally {
+            if (cleanupMarker) {
+                await this._clearRecoveryMarker(cleanupMarker);
+            }
+        }
+    }
+    // ===== Type =====
+    async _type(action) {
+        const ref = action.ref;
+        const text = action.text || "";
+        if (!ref) {
+            return { success: false, message: "Error: type requires ref", details: { error: "missing_ref" } };
+        }
+        const target = `[aria-ref='${escapeRef(ref)}']`;
+        const details = { ref, target, text, text_length: text.length };
+        const control = this.page.locator(target).first();
+        try {
+            const count = await control.count();
+            if (count === 0) {
+                details.error = "element_not_found";
+                return { success: false, message: "Error: type failed, element not found", details };
+            }
+            const identity = await this._readTypeIdentity(control);
+            details.identity = identity;
+            const beforeState = await this._readTypeState(control);
+            details.before_state = beforeState;
+            const preferKeyboard = this._shouldPreferKeyboardTyping(beforeState);
+            details.prefer_keyboard = preferKeyboard;
+            const strategies = preferKeyboard
+                ? ["keyboard_type", "fill"]
+                : ["fill", "keyboard_type"];
+            for (const strategy of strategies) {
+                if (strategy === "fill") {
+                    try {
+                        await control.fill(text, { timeout: this.shortTimeout });
+                    }
+                    catch (exc) {
+                        details.fill_error = String(exc);
+                        continue;
+                    }
+                }
+                else {
+                    try {
+                        try {
+                            await control.click({ timeout: this.shortTimeout });
+                            details.keyboard_focus_method = "click";
+                        }
+                        catch {
+                            await control.focus();
+                            details.keyboard_focus_method = "focus";
+                        }
+                        try {
+                            await control.press("ControlOrMeta+A", { timeout: this.shortTimeout });
+                        }
+                        catch {
+                            try {
+                                await control.press("Control+A", { timeout: this.shortTimeout });
+                            }
+                            catch {
+                                // Best-effort select-all; continue with backspace/delete fallback.
+                            }
+                        }
+                        try {
+                            await control.press("Backspace", { timeout: this.shortTimeout });
+                        }
+                        catch {
+                            // Best effort.
+                        }
+                        try {
+                            await control.press("Delete", { timeout: this.shortTimeout });
+                        }
+                        catch {
+                            // Best effort.
+                        }
+                        await this.page.keyboard.type(text, { delay: 45 });
+                    }
+                    catch (exc) {
+                        details.keyboard_type_error = String(exc);
+                        continue;
+                    }
+                }
+                await this.page.waitForTimeout(180);
+                const afterRead = await this._readTypeStateWithFallback(control, identity);
+                details[`${strategy}_state_read_mode`] = afterRead.mode;
+                if (afterRead.error) {
+                    details[`${strategy}_state_read_error`] = afterRead.error;
+                }
+                if (!afterRead.state) {
+                    continue;
+                }
+                const afterState = afterRead.state;
+                details[`${strategy}_after_state`] = afterState;
+                const verified = this._typeStateMatchesExpected(afterState, text);
+                details[`${strategy}_verified`] = verified;
+                if (verified) {
+                    details.strategy = strategy;
+                    return { success: true, message: `Typed '${text}' into ${target}`, details };
+                }
+            }
+            const finalRead = await this._readTypeStateWithFallback(control, identity);
+            details.after_state_read_mode = finalRead.mode;
+            if (finalRead.error) {
+                details.after_state_read_error = finalRead.error;
+            }
+            details.after_state = finalRead.state;
+            details.error = "value_not_verified";
+            return {
+                success: false,
+                message: `Type failed: could not verify text '${text}' in ${target}`,
+                details,
+            };
+        }
+        catch (exc) {
+            details.error = String(exc);
+            return { success: false, message: `Type failed: ${exc}`, details };
+        }
+    }
+    // ===== Select =====
+    async _select(action) {
+        const ref = action.ref;
+        const selector = action.selector;
+        const value = action.value || "";
+        if (!ref && !selector) {
+            return { success: false, message: "Error: select requires ref or selector", details: { error: "missing_target" } };
+        }
+        const target = ref ? `[aria-ref='${escapeRef(ref)}']` : selector;
+        const details = { ref: ref ?? null, selector: selector ?? null, target, value };
+        const control = this.page.locator(target).first();
+        try {
+            const beforeModel = await this._readSelectModel(control, this.defaultTimeout);
+            if (!beforeModel) {
+                details.error = "element_not_found";
+                return { success: false, message: "Error: Select failed, element not found", details };
+            }
+            details.before_state = this._toSelectStateDebug(beforeModel);
+            details.control_kind = beforeModel.kind;
+            if (beforeModel.kind === "native_select") {
+                const resolution = this._resolveSelectOption(beforeModel.options, value);
+                details.resolution = this._toSelectResolutionDebug(resolution);
+                if (!resolution) {
+                    details.error = "option_not_found";
+                    return {
+                        success: false,
+                        message: `Select failed: could not match option '${value}' in ${target}`,
+                        details,
+                    };
+                }
+                try {
+                    if (resolution.option.value) {
+                        details.native_selected_values = await control.selectOption({ value: resolution.option.value }, { timeout: this.defaultTimeout });
+                    }
+                    else if (resolution.option.label) {
+                        details.native_selected_values = await control.selectOption({ label: resolution.option.label }, { timeout: this.defaultTimeout });
+                    }
+                    else {
+                        details.native_selected_values = await control.selectOption({ index: beforeModel.options.indexOf(resolution.option) }, { timeout: this.defaultTimeout });
+                    }
+                }
+                catch (nativeErr) {
+                    details.native_error = String(nativeErr);
+                    details.error = "native_select_failed";
+                    return { success: false, message: `Select failed: ${nativeErr}`, details };
+                }
+                const afterModel = await this._reacquireSelectModel(target, beforeModel.identity);
+                details.after_state = this._toSelectStateDebug(afterModel);
+                if (afterModel && this._selectModelMatchesResolution(afterModel, resolution)) {
+                    details.strategy = "native_select";
+                    return { success: true, message: `Selected '${value}' in ${target}`, details };
+                }
+                details.error = "selection_not_verified";
+                return {
+                    success: false,
+                    message: `Select failed: could not verify selection '${value}' in ${target}`,
+                    details,
+                };
+            }
+            const popup = await this._openCustomSelectScope(control, beforeModel, details);
+            if (!popup) {
+                details.error = "popup_scope_not_found";
+                return {
+                    success: false,
+                    message: `Select failed: could not determine option scope for ${target}`,
+                    details,
+                };
+            }
+            const popupOptions = await this._readScopedSelectOptions(popup);
+            details.popup_options = popupOptions.map((option) => this._toSelectOptionDebug(option));
+            const resolution = this._resolveSelectOption(popupOptions, value);
+            details.resolution = this._toSelectResolutionDebug(resolution);
+            if (!resolution) {
+                details.error = "option_not_found";
+                return {
+                    success: false,
+                    message: `Select failed: could not match option '${value}' in ${target}`,
+                    details,
+                };
+            }
+            const customClicked = await this._clickScopedSelectOption(popup, resolution.option, details);
+            const afterModel = await this._reacquireSelectModel(target, beforeModel.identity);
+            details.after_state = this._toSelectStateDebug(afterModel);
+            if (customClicked && afterModel && this._selectModelMatchesResolution(afterModel, resolution)) {
+                details.strategy = "custom_select";
+                return { success: true, message: `Selected '${value}' in ${target}`, details };
+            }
+            details.error = "selection_not_verified";
+            return { success: false, message: `Select failed: could not verify selection '${value}' in ${target}`, details };
+        }
+        catch (err) {
+            details.error = String(err);
+            return { success: false, message: `Select failed: ${err}`, details };
+        }
+    }
+    // ===== Wait =====
+    async _wait(action) {
+        const details = {
+            wait_type: null,
+            timeout: null,
+            selector: null,
+        };
+        if ("timeout" in action) {
+            const ms = Math.min(Math.max(0, Number(action.timeout) || 0), 30_000);
+            details.wait_type = "timeout";
+            details.timeout = ms;
+            await new Promise((resolve) => setTimeout(resolve, ms));
+            return { success: true, message: `Waited ${ms}ms`, details };
+        }
+        if ("selector" in action) {
+            const sel = action.selector;
+            details.wait_type = "selector";
+            details.selector = sel;
+            await this.page.waitForSelector(sel, { timeout: this.defaultTimeout });
+            return { success: true, message: `Waited for ${sel}`, details };
+        }
+        return { success: false, message: "Error: wait requires timeout/selector", details };
+    }
+    // ===== Extract =====
+    async _extract(action) {
+        const ref = action.ref;
+        if (!ref) {
+            return { success: false, message: "Error: extract requires ref", details: { error: "missing_ref" } };
+        }
+        const target = `[aria-ref='${escapeRef(ref)}']`;
+        const details = { ref, target };
+        try {
+            await this.page.waitForSelector(target, { timeout: this.defaultTimeout });
+            const txt = await this.page.textContent(target);
+            details.extracted_text = txt;
+            details.text_length = txt ? txt.length : 0;
+            return {
+                success: true,
+                message: `Extracted: ${txt ? txt.slice(0, 100) : "None"}`,
+                details,
+            };
+        }
+        catch (e) {
+            details.error = String(e);
+            return { success: false, message: `Error: extract failed: ${e}`, details };
+        }
+    }
+    // ===== Scroll =====
+    async _scroll(action) {
+        const direction = action.direction || "down";
+        const amount = action.amount !== undefined ? Number(action.amount) : 300;
+        const details = {
+            direction,
+            requested_amount: amount,
+            actual_amount: null,
+            scroll_offset: null,
+        };
+        if (direction !== "up" && direction !== "down") {
+            return { success: false, message: "Error: direction must be 'up' or 'down'", details };
+        }
+        let amountInt;
+        try {
+            amountInt = Math.round(amount);
+            amountInt = Math.max(-this.maxScrollAmount, Math.min(this.maxScrollAmount, amountInt));
+            details.actual_amount = amountInt;
+        }
+        catch {
+            return { success: false, message: "Error: amount must be a valid number", details };
+        }
+        const scrollOffset = direction === "down" ? amountInt : -amountInt;
+        details.scroll_offset = scrollOffset;
+        await this.page.evaluate((offset) => window.scrollBy(0, offset), scrollOffset);
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        return { success: true, message: `Scrolled ${direction} by ${Math.abs(amountInt)}px`, details };
+    }
+    // ===== Enter =====
+    async _enter(_action) {
+        const details = { action_type: "enter", target: "focused_element" };
+        await this.page.keyboard.press("Enter");
+        return { success: true, message: "Pressed Enter on focused element", details };
+    }
+    // ===== Mouse Control =====
+    async _mouseControl(action) {
+        const control = action.control || "click";
+        const xCoord = Number(action.x) || 0;
+        const yCoord = Number(action.y) || 0;
+        const details = {
+            action_type: "mouse_control",
+            target: `coordinates : (${xCoord}, ${yCoord})`,
+        };
+        try {
+            if (!this._validCoordinates(xCoord, yCoord)) {
+                throw new Error(`Invalid coordinates, outside viewport bounds: (${xCoord}, ${yCoord})`);
+            }
+            if (control === "click") {
+                const found = await this.page.evaluate(([x, y]) => {
+                    const el = document.elementFromPoint(x, y);
+                    if (!el)
+                        return false;
+                    const opts = { bubbles: true, cancelable: true, clientX: x, clientY: y, button: 0 };
+                    el.dispatchEvent(new MouseEvent("mousedown", opts));
+                    el.dispatchEvent(new MouseEvent("mouseup", opts));
+                    el.dispatchEvent(new MouseEvent("click", opts));
+                    if (el.tagName === "INPUT" ||
+                        el.tagName === "TEXTAREA" ||
+                        el.isContentEditable)
+                        el.focus();
+                    return true;
+                }, [xCoord, yCoord]);
+                if (!found)
+                    throw new Error(`No element found at coordinates (${xCoord}, ${yCoord})`);
+                return { success: true, message: "Action 'click' performed on the target", details };
+            }
+            else if (control === "right_click") {
+                const found = await this.page.evaluate(([x, y]) => {
+                    const el = document.elementFromPoint(x, y);
+                    if (!el)
+                        return false;
+                    const opts = { bubbles: true, cancelable: true, clientX: x, clientY: y, button: 2 };
+                    el.dispatchEvent(new MouseEvent("mousedown", opts));
+                    el.dispatchEvent(new MouseEvent("mouseup", opts));
+                    el.dispatchEvent(new MouseEvent("contextmenu", opts));
+                    return true;
+                }, [xCoord, yCoord]);
+                if (!found)
+                    throw new Error(`No element found at coordinates (${xCoord}, ${yCoord})`);
+                return { success: true, message: "Action 'right_click' performed on the target", details };
+            }
+            else if (control === "dblclick") {
+                const found = await this.page.evaluate(([x, y]) => {
+                    const el = document.elementFromPoint(x, y);
+                    if (!el)
+                        return false;
+                    const opts = { bubbles: true, cancelable: true, clientX: x, clientY: y, button: 0 };
+                    el.dispatchEvent(new MouseEvent("mousedown", opts));
+                    el.dispatchEvent(new MouseEvent("mouseup", opts));
+                    el.dispatchEvent(new MouseEvent("click", opts));
+                    el.dispatchEvent(new MouseEvent("mousedown", opts));
+                    el.dispatchEvent(new MouseEvent("mouseup", opts));
+                    el.dispatchEvent(new MouseEvent("click", opts));
+                    el.dispatchEvent(new MouseEvent("dblclick", opts));
+                    if (el.tagName === "INPUT" ||
+                        el.tagName === "TEXTAREA" ||
+                        el.isContentEditable)
+                        el.focus();
+                    return true;
+                }, [xCoord, yCoord]);
+                if (!found)
+                    throw new Error(`No element found at coordinates (${xCoord}, ${yCoord})`);
+                return { success: true, message: "Action 'dblclick' performed on the target", details };
+            }
+            else {
+                return { success: false, message: `Error: Invalid control action '${control}'`, details };
+            }
+        }
+        catch (e) {
+            return { success: false, message: `Action failed: ${e}`, details };
+        }
+    }
+    // ===== Mouse Drag =====
+    async _mouseDrag(action) {
+        const fromRef = action.from_ref;
+        const toRef = action.to_ref;
+        if (!fromRef || !toRef) {
+            return {
+                success: false,
+                message: "Error: mouse_drag requires from_ref and to_ref",
+                details: { error: "missing_refs" },
+            };
+        }
+        const fromSelector = `[aria-ref='${escapeRef(fromRef)}']`;
+        const toSelector = `[aria-ref='${escapeRef(toRef)}']`;
+        const details = {
+            action_type: "mouse_drag",
+            from_ref: fromRef,
+            to_ref: toRef,
+            from_selector: fromSelector,
+            to_selector: toSelector,
+        };
+        try {
+            const fromElement = this.page.locator(fromSelector);
+            if ((await fromElement.count()) === 0) {
+                throw new Error(`Source element with ref '${fromRef}' not found`);
+            }
+            const toElement = this.page.locator(toSelector);
+            if ((await toElement.count()) === 0) {
+                throw new Error(`Target element with ref '${toRef}' not found`);
+            }
+            const fromBox = await fromElement.first().boundingBox();
+            const toBox = await toElement.first().boundingBox();
+            if (!fromBox)
+                throw new Error(`Could not get bounding box for source element with ref '${fromRef}'`);
+            if (!toBox)
+                throw new Error(`Could not get bounding box for target element with ref '${toRef}'`);
+            const fromX = fromBox.x + fromBox.width / 2;
+            const fromY = fromBox.y + fromBox.height / 2;
+            const toX = toBox.x + toBox.width / 2;
+            const toY = toBox.y + toBox.height / 2;
+            details.from_coordinates = { x: fromX, y: fromY };
+            details.to_coordinates = { x: toX, y: toY };
+            const dragSuccess = await this.page.evaluate(([fX, fY, tX, tY]) => {
+                const fromEl = document.elementFromPoint(fX, fY);
+                const toEl = document.elementFromPoint(tX, tY);
+                if (!fromEl)
+                    return false;
+                const dt = new DataTransfer();
+                const common = { bubbles: true, cancelable: true, button: 0, dataTransfer: dt };
+                fromEl.dispatchEvent(new MouseEvent("mousedown", { ...common, clientX: fX, clientY: fY }));
+                fromEl.dispatchEvent(new DragEvent("dragstart", { ...common, clientX: fX, clientY: fY }));
+                const moveTarget = toEl || fromEl;
+                moveTarget.dispatchEvent(new DragEvent("dragover", { ...common, clientX: tX, clientY: tY }));
+                moveTarget.dispatchEvent(new DragEvent("drop", { ...common, clientX: tX, clientY: tY }));
+                moveTarget.dispatchEvent(new MouseEvent("mouseup", { ...common, clientX: tX, clientY: tY }));
+                fromEl.dispatchEvent(new DragEvent("dragend", { ...common, clientX: tX, clientY: tY }));
+                return true;
+            }, [fromX, fromY, toX, toY]);
+            if (!dragSuccess) {
+                throw new Error(`No element found at source coordinates (${fromX}, ${fromY})`);
+            }
+            return {
+                success: true,
+                message: `Dragged from element [ref=${fromRef}] to element [ref=${toRef}]`,
+                details,
+            };
+        }
+        catch (e) {
+            return { success: false, message: `Action failed: ${e}`, details };
+        }
+    }
+    // ===== Press Key =====
+    async _pressKey(action) {
+        const keys = action.keys;
+        if (!keys || keys.length === 0) {
+            return {
+                success: false,
+                message: "Error: No keys specified",
+                details: { action_type: "press_key", keys: "" },
+            };
+        }
+        const combinedKeys = keys.join("+");
+        const details = { action_type: "press_key", keys: combinedKeys };
+        try {
+            await this.page.keyboard.press(combinedKeys);
+            return { success: true, message: "Pressed keys in the browser", details };
+        }
+        catch (e) {
+            return { success: false, message: `Action failed: ${e}`, details };
+        }
+    }
+    // ===== Navigate =====
+    async _navigate(action) {
+        const url = action.url;
+        if (!url) {
+            return { success: false, message: "Error: navigate requires url", details: { error: "missing_url" } };
+        }
+        const details = { action_type: "navigate", url };
+        try {
+            await this.page.goto(url, { timeout: BrowserConfig.navigationTimeout });
+            await this.page.waitForLoadState("domcontentloaded");
+            return { success: true, message: `Navigated to ${url}`, details };
+        }
+        catch (e) {
+            details.error = String(e);
+            return { success: false, message: `Navigation failed: ${e}`, details };
+        }
+    }
+    // ===== Back / Forward =====
+    async _back(_action) {
+        const details = { action_type: "back" };
+        try {
+            await this.page.goBack({ timeout: BrowserConfig.navigationTimeout });
+            return { success: true, message: "Navigated back", details };
+        }
+        catch (e) {
+            details.error = String(e);
+            return { success: false, message: `Back navigation failed: ${e}`, details };
+        }
+    }
+    async _forward(_action) {
+        const details = { action_type: "forward" };
+        try {
+            await this.page.goForward({ timeout: BrowserConfig.navigationTimeout });
+            return { success: true, message: "Navigated forward", details };
+        }
+        catch (e) {
+            details.error = String(e);
+            return { success: false, message: `Forward navigation failed: ${e}`, details };
+        }
+    }
+    // ===== Hover (new — Pinchtab compat) =====
+    async _hover(action) {
+        const ref = action.ref;
+        if (!ref) {
+            return { success: false, message: "Error: hover requires ref", details: { error: "missing_ref" } };
+        }
+        const target = `[aria-ref='${escapeRef(ref)}']`;
+        const details = { ref, target, action_type: "hover" };
+        try {
+            const count = await this.page.locator(target).count();
+            if (count === 0) {
+                details.error = "element_not_found";
+                return { success: false, message: "Error: Hover failed, element not found", details };
+            }
+            await this.page.locator(target).first().hover({ timeout: this.defaultTimeout });
+            return { success: true, message: `Hovered over ${target}`, details };
+        }
+        catch (e) {
+            details.error = String(e);
+            return { success: false, message: `Hover failed: ${e}`, details };
+        }
+    }
+    // ===== Focus (new — Pinchtab compat) =====
+    async _focus(action) {
+        const ref = action.ref;
+        if (!ref) {
+            return { success: false, message: "Error: focus requires ref", details: { error: "missing_ref" } };
+        }
+        const target = `[aria-ref='${escapeRef(ref)}']`;
+        const details = { ref, target, action_type: "focus" };
+        try {
+            const count = await this.page.locator(target).count();
+            if (count === 0) {
+                details.error = "element_not_found";
+                return { success: false, message: "Error: Focus failed, element not found", details };
+            }
+            await this.page.locator(target).first().focus({ timeout: this.defaultTimeout });
+            return { success: true, message: `Focused on ${target}`, details };
+        }
+        catch (e) {
+            details.error = String(e);
+            return { success: false, message: `Focus failed: ${e}`, details };
+        }
+    }
+    // ===== Utilities =====
+    _normalizeClickIntent(intent) {
+        const raw = typeof intent === "string" ? intent.trim().toLowerCase() : "";
+        if (raw === "same_tab" || raw === "new_tab" || raw === "ui") {
+            return raw;
+        }
+        return "auto";
+    }
+    _normalizeClickExpectedEffect(effect) {
+        const raw = typeof effect === "string" ? effect.trim().toLowerCase() : "";
+        if (raw === "focus" || raw === "ui_change" || raw === "navigation" || raw === "calendar_change") {
+            return raw;
+        }
+        return "any";
+    }
+    _deriveClickIntent(requestedIntent, isLikelyLink, baseUrl, expectedHref) {
+        if (requestedIntent === "auto") {
+            return "auto";
+        }
+        if (requestedIntent === "ui") {
+            return "ui";
+        }
+        if (!isLikelyLink && !expectedHref) {
+            return "ui";
+        }
+        const hrefKind = this._classifyExpectedHref(baseUrl, expectedHref);
+        if (hrefKind === "custom") {
+            return "ui";
+        }
+        return requestedIntent;
+    }
+    _resolveExpectedHref(explicitHref, diag, baseUrl) {
+        const rawHref = explicitHref || diag?.href || diag?.closestHref || diag?.descendantHref || null;
+        return this._resolveAbsoluteUrl(rawHref, baseUrl);
+    }
+    _resolveAbsoluteUrl(url, baseUrl) {
+        if (!url)
+            return null;
+        try {
+            return new URL(url, baseUrl).href;
+        }
+        catch {
+            return null;
+        }
+    }
+    _classifyExpectedHref(baseUrl, expectedHref) {
+        if (!expectedHref)
+            return "none";
+        const expected = this._tryParseUrl(expectedHref, baseUrl);
+        if (!expected)
+            return "custom";
+        if (!["http:", "https:"].includes(expected.protocol)) {
+            return "custom";
+        }
+        const base = this._tryParseUrl(baseUrl, expected.href);
+        if (base &&
+            base.origin === expected.origin &&
+            this._normalizePath(base.pathname) === this._normalizePath(expected.pathname) &&
+            base.search === expected.search &&
+            !!expected.hash) {
+            return "hash";
+        }
+        return "standard";
+    }
+    _tryParseUrl(url, baseUrl) {
+        if (!url)
+            return null;
+        try {
+            return new URL(url, baseUrl);
+        }
+        catch {
+            return null;
+        }
+    }
+    _normalizePath(pathname) {
+        const normalized = pathname.replace(/\/+$/, "");
+        return normalized || "/";
+    }
+    _urlMatchesExpected(currentUrl, expectedUrl) {
+        const current = this._tryParseUrl(currentUrl, expectedUrl);
+        const expected = this._tryParseUrl(expectedUrl, currentUrl);
+        if (!current || !expected)
+            return currentUrl === expectedUrl;
+        if (current.origin !== expected.origin)
+            return false;
+        if (this._normalizePath(current.pathname) !== this._normalizePath(expected.pathname))
+            return false;
+        if (expected.hash && current.hash !== expected.hash)
+            return false;
+        const expectedKeys = Array.from(new Set(expected.searchParams.keys()));
+        for (const key of expectedKeys) {
+            const currentValues = current.searchParams.getAll(key).sort();
+            const expectedValues = expected.searchParams.getAll(key).sort();
+            if (!this._arraysEqual(currentValues, expectedValues))
+                return false;
+        }
+        return true;
+    }
+    _arraysEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((value, index) => value === b[index]);
+    }
+    async _recoverClickTarget(expectedHref, expectedText) {
+        if (!expectedHref && !expectedText) {
+            return { locator: null, selector: null, reason: "element_not_found" };
+        }
+        const marker = {
+            attr: "data-arise-click-recovery",
+            value: `recovery-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
+        };
+        const recovered = await this.page.evaluate(({ expectedHref, expectedText, markerAttr, markerValue }) => {
+            const normalizeText = (value) => (value || "").replace(/\s+/g, " ").trim().toLowerCase();
+            const normalizeHref = (value) => {
+                if (!value)
+                    return null;
+                try {
+                    return new URL(value, window.location.href).href;
+                }
+                catch {
+                    return null;
+                }
+            };
+            const expectedHrefAbs = normalizeHref(expectedHref);
+            const expectedTextNorm = normalizeText(expectedText);
+            const candidates = [];
+            const elements = Array.from(document.querySelectorAll("a[href], [role='link']"));
+            for (const element of elements) {
+                const anchorLike = element.tagName.toLowerCase() === "a"
+                    ? element
+                    : element.querySelector("a[href]");
+                const rawHref = element.getAttribute("href") ||
+                    anchorLike?.getAttribute("href") ||
+                    element.closest("a[href]")?.getAttribute("href") ||
+                    null;
+                const href = normalizeHref(rawHref);
+                const text = (element.innerText || element.textContent || "")
+                    .replace(/\s+/g, " ")
+                    .trim()
+                    .slice(0, 200);
+                const textNorm = normalizeText(text);
+                const hrefMatch = !!expectedHrefAbs && href === expectedHrefAbs;
+                const textMatch = !!expectedTextNorm &&
+                    !!textNorm &&
+                    (textNorm === expectedTextNorm ||
+                        textNorm.includes(expectedTextNorm) ||
+                        expectedTextNorm.includes(textNorm));
+                let score = 0;
+                if (hrefMatch)
+                    score += 4;
+                if (textMatch)
+                    score += 2;
+                if (element.tagName.toLowerCase() === "a")
+                    score += 1;
+                const matches = (expectedHrefAbs && hrefMatch) ||
+                    (!expectedHrefAbs && expectedTextNorm && textMatch);
+                if (matches && score > 0) {
+                    candidates.push({ element, score, href, text });
+                }
+            }
+            if (candidates.length === 0) {
+                return {
+                    status: "not_found",
+                    reason: "stale_ref_unresolved",
+                    candidateCount: 0,
+                };
+            }
+            candidates.sort((a, b) => b.score - a.score);
+            const bestScore = candidates[0].score;
+            const topCandidates = candidates.filter((candidate) => candidate.score === bestScore);
+            if (topCandidates.length !== 1) {
+                return {
+                    status: "ambiguous",
+                    reason: "stale_ref_ambiguous",
+                    candidateCount: topCandidates.length,
+                };
+            }
+            const winner = topCandidates[0];
+            winner.element.setAttribute(markerAttr, markerValue);
+            return {
+                status: "ok",
+                reason: "recovered",
+                candidateCount: 1,
+                matchedHref: winner.href,
+                matchedText: winner.text,
+            };
+        }, {
+            expectedHref,
+            expectedText,
+            markerAttr: marker.attr,
+            markerValue: marker.value,
+        });
+        if (recovered.status !== "ok") {
+            return {
+                locator: null,
+                selector: null,
+                reason: recovered.reason,
+                candidateCount: recovered.candidateCount,
+            };
+        }
+        const selector = `[${marker.attr}='${marker.value}']`;
+        const locator = this.page.locator(selector).first();
+        if ((await locator.count()) === 0) {
+            return {
+                locator: null,
+                selector: null,
+                reason: "stale_ref_unresolved",
+            };
+        }
+        return {
+            locator,
+            selector,
+            reason: recovered.reason,
+            candidateCount: recovered.candidateCount,
+            matchedHref: recovered.matchedHref ?? null,
+            matchedText: recovered.matchedText ?? null,
+            marker,
+        };
+    }
+    async _clearRecoveryMarker(marker) {
+        try {
+            await this.page.evaluate(({ attr, value }) => {
+                document
+                    .querySelectorAll(`[${attr}='${value}']`)
+                    .forEach((element) => element.removeAttribute(attr));
+            }, marker);
+        }
+        catch {
+            // Ignore cleanup failures after navigation.
+        }
+    }
+    async _executeAutoClick(clickTarget, target, details, isLikelyLink, beforeObservation, expectedEffect) {
+        let clickPerformed = false;
+        if (isLikelyLink && this.session) {
+            try {
+                const context = this.page.context();
+                const t0 = performance.now();
+                const tabsBefore = new Set((await this.session.getTabInfo()).map((t) => t.tab_id));
+                const newPagePromise = context.waitForEvent("page", {
+                    timeout: this.shortTimeout,
+                });
+                newPagePromise.catch(() => { });
+                await clickTarget.click({ modifiers: ["ControlOrMeta"] });
+                logger.debug("Click executed, waiting for page event...");
+                const newPage = await newPagePromise;
+                const elapsedMs = Math.round(performance.now() - t0);
+                await newPage.waitForLoadState("domcontentloaded");
+                const tabsAfter = await this.session.getTabInfo();
+                const newTabInfo = tabsAfter.find((t) => !tabsBefore.has(t.tab_id) && t.url !== "(closed)" && t.url !== "(error)");
+                const newTabId = newTabInfo?.tab_id;
+                if (newTabId) {
+                    await this.session.switchToTab(newTabId);
+                }
+                details.click_method = "ctrl_click_new_tab";
+                details.new_tab_created = true;
+                details.new_tab_index = newTabId;
+                details.ctrl_click_elapsed_ms = elapsedMs;
+                return {
+                    success: true,
+                    message: `Clicked element, opened in new tab ${newTabId}`,
+                    details,
+                };
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                if (msg.includes("Timeout") || msg.includes("timeout")) {
+                    details.click_method = "ctrl_click_same_tab";
+                    clickPerformed = true;
+                }
+                else {
+                    details.strategies_tried.push({
+                        selector: target,
+                        method: "ctrl_click",
+                        error: msg,
+                    });
+                }
+            }
+        }
+        if (!clickPerformed) {
+            try {
+                await clickTarget.click({ timeout: this.defaultTimeout });
+                details.click_method = "click";
+                clickPerformed = true;
+            }
+            catch (e) {
+                details.strategies_tried.push({
+                    selector: target,
+                    method: "click",
+                    error: String(e),
+                });
+            }
+        }
+        if (!clickPerformed) {
+            logger.debug("Falling back to force click...");
+            try {
+                await clickTarget.click({ force: true, timeout: this.defaultTimeout });
+                details.click_method = "force_click";
+                clickPerformed = true;
+            }
+            catch (e) {
+                logger.debug({ err: e }, "Force click also failed");
+                details.click_method = "all_failed";
+                details.error = String(e);
+                return {
+                    success: false,
+                    message: `Error: All click strategies failed for ${target}`,
+                    details,
+                };
+            }
+        }
+        await this.page.waitForTimeout(180);
+        const afterObservation = await this._captureClickObservation(clickTarget);
+        details.after_observation = afterObservation;
+        const observationDelta = this._getClickObservationDelta(beforeObservation, afterObservation);
+        details.observation_delta = observationDelta;
+        details.expected_effect = expectedEffect;
+        const effectEvaluation = this._evaluateObservedClickEffect(expectedEffect, observationDelta);
+        details.effect_satisfied = effectEvaluation.satisfied;
+        if (effectEvaluation.satisfied && !observationDelta.changed) {
+            details.no_state_change = true;
+            details.warning = "no_state_change";
+            return {
+                success: true,
+                message: `Clicked element (${details.click_method}): ${target} (no observable page state change)`,
+                details,
+            };
+        }
+        if (effectEvaluation.satisfied && observationDelta.focusOnly) {
+            details.focus_only_change = true;
+            details.warning = "focus_only_change";
+            return {
+                success: true,
+                message: this._formatFocusOnlyClickMessage(String(details.click_method || "click"), target),
+                details,
+            };
+        }
+        if (!effectEvaluation.satisfied) {
+            details.error = effectEvaluation.errorCode;
+            details.expected_effect_failure = effectEvaluation.errorCode;
+            return {
+                success: false,
+                message: effectEvaluation.message || `Error: Click did not satisfy expected effect for ${target}`,
+                details,
+            };
+        }
+        return { success: true, message: `Clicked element (${details.click_method}): ${target}`, details };
+    }
+    async _attemptCtrlClickNewTab(clickTarget, target, details, expectedHref) {
+        if (!this.session)
+            return null;
+        try {
+            const context = this.page.context();
+            const t0 = performance.now();
+            const tabsBefore = new Set((await this.session.getTabInfo()).map((t) => t.tab_id));
+            const newPagePromise = context.waitForEvent("page", { timeout: this.shortTimeout });
+            newPagePromise.catch(() => { });
+            await clickTarget.click({ modifiers: ["ControlOrMeta"] });
+            const newPage = await newPagePromise;
+            const elapsedMs = Math.round(performance.now() - t0);
+            await newPage.waitForLoadState("domcontentloaded").catch(() => { });
+            const tabsAfter = await this.session.getTabInfo();
+            const newTabInfo = tabsAfter.find((tab) => !tabsBefore.has(tab.tab_id) && tab.url !== "(closed)" && tab.url !== "(error)");
+            const newTabId = newTabInfo?.tab_id ?? null;
+            const newTabUrl = newPage.url();
+            const matchedExpected = expectedHref ? this._urlMatchesExpected(newTabUrl, expectedHref) : true;
+            details.click_method = "ctrl_click_new_tab";
+            details.new_tab_created = true;
+            details.new_tab_index = newTabId;
+            details.ctrl_click_elapsed_ms = elapsedMs;
+            details.link_verification = {
+                mode: "new_tab",
+                current_url: newTabUrl,
+                expected_url: expectedHref,
+                matched_expected: matchedExpected,
+            };
+            if (!matchedExpected) {
+                details.error = "unexpected_new_tab_url";
+                return {
+                    success: false,
+                    message: `Error: Click opened unexpected new tab for ${target}`,
+                    details,
+                };
+            }
+            if (newTabId) {
+                await this.session.switchToTab(newTabId);
+            }
+            return {
+                success: true,
+                message: `Clicked element, opened in new tab ${newTabId ?? "(untracked)"}`,
+                details,
+            };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            details.strategies_tried.push({
+                selector: target,
+                method: "ctrl_click",
+                error: msg,
+            });
+            if (msg.includes("Timeout") || msg.includes("timeout")) {
+                details.ctrl_click_timeout = true;
+            }
+            return null;
+        }
+    }
+    async _executeSameTabLinkClick(clickTarget, target, details, expectedHref, beforeUrl) {
+        const firstAttempt = await this._clickAndVerifyLinkAttempt(clickTarget, "click", expectedHref, beforeUrl);
+        details.click_method = "click";
+        if (firstAttempt.clickError) {
+            details.strategies_tried.push({
+                selector: target,
+                method: "click",
+                error: firstAttempt.clickError,
+            });
+        }
+        if (firstAttempt.verification) {
+            details.link_verification = firstAttempt.verification;
+        }
+        if (firstAttempt.ok && firstAttempt.verification) {
+            if (firstAttempt.verification.newTabId) {
+                details.new_tab_created = true;
+                details.new_tab_index = firstAttempt.verification.newTabId;
+            }
+            return {
+                success: true,
+                message: `Clicked element (click): ${target}`,
+                details,
+            };
+        }
+        const canRetryWithForce = !!firstAttempt.clickError ||
+            (!!firstAttempt.verification &&
+                firstAttempt.verification.currentUrl === beforeUrl &&
+                !firstAttempt.verification.newTabUrl &&
+                !firstAttempt.verification.downloadTriggered);
+        if (!canRetryWithForce) {
+            details.error = firstAttempt.verification?.reason || firstAttempt.clickError || "link_click_no_navigation";
+            return {
+                success: false,
+                message: `Error: Link click did not reach expected destination for ${target}`,
+                details,
+            };
+        }
+        logger.debug("Link click did not navigate, retrying with force click...");
+        const secondAttempt = await this._clickAndVerifyLinkAttempt(clickTarget, "force_click", expectedHref, beforeUrl);
+        details.click_method = "force_click";
+        if (secondAttempt.clickError) {
+            details.strategies_tried.push({
+                selector: target,
+                method: "force_click",
+                error: secondAttempt.clickError,
+            });
+        }
+        if (secondAttempt.verification) {
+            details.link_verification = secondAttempt.verification;
+        }
+        if (secondAttempt.ok && secondAttempt.verification) {
+            if (secondAttempt.verification.newTabId) {
+                details.new_tab_created = true;
+                details.new_tab_index = secondAttempt.verification.newTabId;
+            }
+            return {
+                success: true,
+                message: `Clicked element (force_click): ${target}`,
+                details,
+            };
+        }
+        details.error = secondAttempt.verification?.reason || secondAttempt.clickError || "link_click_no_navigation";
+        return {
+            success: false,
+            message: `Error: Link click did not reach expected destination for ${target}`,
+            details,
+        };
+    }
+    async _clickAndVerifyLinkAttempt(clickTarget, method, expectedHref, beforeUrl) {
+        const verificationTimeout = Math.min(this.shortTimeout, 2500);
+        let observedNewPage = null;
+        let downloadTriggered = false;
+        const tabsBefore = this.session
+            ? new Set((await this.session.getTabInfo()).map((tab) => tab.tab_id))
+            : null;
+        if (this.session) {
+            void this.page.context()
+                .waitForEvent("page", { timeout: verificationTimeout })
+                .then(async (page) => {
+                observedNewPage = page;
+                await page.waitForLoadState("domcontentloaded").catch(() => { });
+            })
+                .catch(() => { });
+        }
+        void this.page
+            .waitForEvent("download", { timeout: verificationTimeout })
+            .then(() => {
+            downloadTriggered = true;
+        })
+            .catch(() => { });
+        try {
+            if (method === "force_click") {
+                await clickTarget.click({ force: true, timeout: this.defaultTimeout });
+            }
+            else {
+                await clickTarget.click({ timeout: this.defaultTimeout });
+            }
+        }
+        catch (e) {
+            return { ok: false, clickError: String(e) };
+        }
+        const verification = await this._waitForLinkVerification({
+            beforeUrl,
+            expectedHref,
+            timeoutMs: verificationTimeout,
+            getObservedNewPage: () => observedNewPage,
+            didDownload: () => downloadTriggered,
+            tabsBefore,
+        });
+        return { ok: verification.ok, verification };
+    }
+    async _waitForLinkVerification(options) {
+        const expectedUrl = options.expectedHref
+            ? this._resolveAbsoluteUrl(options.expectedHref, options.beforeUrl)
+            : null;
+        const hrefKind = this._classifyExpectedHref(options.beforeUrl, expectedUrl);
+        const deadline = Date.now() + options.timeoutMs;
+        while (Date.now() < deadline) {
+            const newPage = options.getObservedNewPage();
+            if (newPage) {
+                const newTabUrl = newPage.url();
+                const matchedExpected = expectedUrl ? this._urlMatchesExpected(newTabUrl, expectedUrl) : true;
+                let newTabId = null;
+                if (this.session && options.tabsBefore) {
+                    const tabsAfter = await this.session.getTabInfo();
+                    const newTab = tabsAfter.find((tab) => !options.tabsBefore.has(tab.tab_id) && tab.url !== "(closed)" && tab.url !== "(error)");
+                    newTabId = newTab?.tab_id ?? null;
+                    if (newTabId) {
+                        await this.session.switchToTab(newTabId);
+                    }
+                }
+                if (matchedExpected) {
+                    return {
+                        ok: true,
+                        mode: "new_tab",
+                        currentUrl: newTabUrl,
+                        expectedUrl,
+                        matchedExpected,
+                        newTabId,
+                        newTabUrl,
+                        downloadTriggered: options.didDownload(),
+                    };
+                }
+                return {
+                    ok: false,
+                    mode: "new_tab",
+                    reason: "unexpected_new_tab_url",
+                    currentUrl: newTabUrl,
+                    expectedUrl,
+                    matchedExpected,
+                    newTabId,
+                    newTabUrl,
+                    downloadTriggered: options.didDownload(),
+                };
+            }
+            if (options.didDownload()) {
+                return {
+                    ok: true,
+                    mode: "download",
+                    currentUrl: this.page.url(),
+                    expectedUrl,
+                    matchedExpected: true,
+                    downloadTriggered: true,
+                };
+            }
+            const currentUrl = this.page.url();
+            const matchedExpected = expectedUrl
+                ? this._urlMatchesExpected(currentUrl, expectedUrl)
+                : currentUrl !== options.beforeUrl;
+            if (matchedExpected) {
+                return {
+                    ok: true,
+                    mode: hrefKind === "hash" ? "hash" : "same_tab",
+                    currentUrl,
+                    expectedUrl,
+                    matchedExpected,
+                    downloadTriggered: false,
+                };
+            }
+            await this.page.waitForTimeout(100);
+        }
+        const currentUrl = this.page.url();
+        return {
+            ok: false,
+            mode: "unknown",
+            reason: expectedUrl ? "expected_navigation_not_observed" : "navigation_not_observed",
+            currentUrl,
+            expectedUrl,
+            matchedExpected: expectedUrl ? this._urlMatchesExpected(currentUrl, expectedUrl) : currentUrl !== options.beforeUrl,
+            downloadTriggered: options.didDownload(),
+        };
+    }
+    async _executeUiClick(clickTarget, target, details, beforeObservation, expectedEffect) {
+        if (expectedEffect === "calendar_change") {
+            return await this._executeCalendarClick(clickTarget, target, details, beforeObservation);
+        }
+        const attempts = [
+            { method: "click", force: false },
+            { method: "force_click", force: true },
+        ];
+        for (const attempt of attempts) {
+            try {
+                await clickTarget.click({
+                    timeout: this.defaultTimeout,
+                    ...(attempt.force ? { force: true } : {}),
+                });
+            }
+            catch (e) {
+                details.strategies_tried.push({
+                    selector: target,
+                    method: attempt.method,
+                    error: String(e),
+                });
+                continue;
+            }
+            details.click_method = attempt.method;
+            await this.page.waitForTimeout(180);
+            const afterObservation = await this._captureClickObservation(clickTarget);
+            details.after_observation = afterObservation;
+            const observationDelta = this._getClickObservationDelta(beforeObservation, afterObservation);
+            details.observation_delta = observationDelta;
+            details.expected_effect = expectedEffect;
+            if (expectedEffect === "any") {
+                details.effect_satisfied = observationDelta.meaningful || observationDelta.focusOnly;
+                if (observationDelta.meaningful) {
+                    return {
+                        success: true,
+                        message: `Clicked element (${attempt.method}): ${target}`,
+                        details,
+                    };
+                }
+                if (observationDelta.focusOnly) {
+                    details.focus_only_change = true;
+                    details.warning = "focus_only_change";
+                    return {
+                        success: true,
+                        message: this._formatFocusOnlyClickMessage(attempt.method, target),
+                        details,
+                    };
+                }
+                continue;
+            }
+            const effectEvaluation = this._evaluateObservedClickEffect(expectedEffect, observationDelta);
+            details.effect_satisfied = effectEvaluation.satisfied;
+            if (effectEvaluation.satisfied) {
+                if (observationDelta.focusOnly) {
+                    details.focus_only_change = true;
+                    details.warning = "focus_only_change";
+                    return {
+                        success: true,
+                        message: this._formatFocusOnlyClickMessage(attempt.method, target),
+                        details,
+                    };
+                }
+                return {
+                    success: true,
+                    message: `Clicked element (${attempt.method}): ${target}`,
+                    details,
+                };
+            }
+        }
+        details.no_state_change = true;
+        details.error =
+            expectedEffect === "ui_change"
+                ? "ui_effect_not_observed"
+                : expectedEffect === "navigation"
+                    ? "navigation_effect_not_observed"
+                    : expectedEffect === "focus"
+                        ? "focus_effect_not_observed"
+                        : "no_meaningful_state_change";
+        return {
+            success: false,
+            message: expectedEffect === "any"
+                ? `Error: Click had no meaningful effect for ${target}`
+                : `Error: Click did not satisfy expected effect '${expectedEffect}' for ${target}`,
+            details,
+        };
+    }
+    async _executeCalendarClick(clickTarget, target, details, beforeObservation) {
+        const attempts = [
+            { method: "click", force: false },
+            { method: "force_click", force: true },
+        ];
+        const targetKind = this._classifyCalendarTarget(beforeObservation.targetState);
+        const beforeCalendarObservation = await this._captureCalendarObservation();
+        details.before_calendar_observation = beforeCalendarObservation;
+        details.calendar_target_kind = targetKind;
+        for (const attempt of attempts) {
+            try {
+                await clickTarget.click({
+                    timeout: this.defaultTimeout,
+                    ...(attempt.force ? { force: true } : {}),
+                });
+            }
+            catch (e) {
+                details.strategies_tried.push({
+                    selector: target,
+                    method: attempt.method,
+                    error: String(e),
+                });
+                continue;
+            }
+            details.click_method = attempt.method;
+            let afterCalendarObservation = beforeCalendarObservation;
+            for (let i = 0; i < 6; i += 1) {
+                await this.page.waitForTimeout(i === 0 ? 120 : 100);
+                afterCalendarObservation = await this._captureCalendarObservation();
+                const evaluation = this._evaluateCalendarObservationChange(targetKind, beforeCalendarObservation, afterCalendarObservation);
+                details.after_calendar_observation = afterCalendarObservation;
+                details.calendar_effect_satisfied = evaluation.satisfied;
+                details.calendar_effect_reason = evaluation.reason;
+                if (evaluation.satisfied) {
+                    if (evaluation.focusOnly) {
+                        details.focus_only_change = true;
+                        details.warning = "focus_only_change";
+                        return {
+                            success: true,
+                            message: this._formatFocusOnlyClickMessage(attempt.method, target),
+                            details,
+                        };
+                    }
+                    return {
+                        success: true,
+                        message: `Clicked element (${attempt.method}): ${target}`,
+                        details,
+                    };
+                }
+            }
+        }
+        details.no_state_change = true;
+        details.error = "calendar_effect_not_observed";
+        details.expected_effect_failure = "calendar_effect_not_observed";
+        return {
+            success: false,
+            message: `Error: Click did not satisfy expected effect 'calendar_change' for ${target}`,
+            details,
+        };
+    }
+    _classifyCalendarTarget(state) {
+        if (!state)
+            return "other";
+        const combined = `${state.ariaLabel || ""} ${state.text || ""} ${state.value || ""}`
+            .replace(/\s+/g, " ")
+            .trim()
+            .toLowerCase();
+        if (/^next\b/.test(combined))
+            return "next";
+        if (/^previous\b/.test(combined))
+            return "previous";
+        if (/^done\b/.test(combined))
+            return "done";
+        if ((state.role === "textbox" || state.role === "combobox" || !!state.value) &&
+            /\b(departure|return)\b/.test(combined)) {
+            return "field";
+        }
+        const text = (state.text || "").trim();
+        if (/^\d{1,2}(?:\b|[^0-9])/.test(text) || /^\d{1,2}(?:\b|[^0-9])/.test(combined)) {
+            return "date";
+        }
+        return "other";
+    }
+    async _captureCalendarObservation() {
+        const script = String.raw `(() => {
+      function normalize(value) {
+        return String(value ?? "").replace(/\s+/g, " ").trim();
+      }
+
+      function isVisible(el) {
+        if (!el) return false;
+        const style = window.getComputedStyle(el);
+        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") {
+          return false;
+        }
+        const rect = el.getBoundingClientRect();
+        return (
+          rect.width > 0 &&
+          rect.height > 0 &&
+          rect.bottom >= 0 &&
+          rect.right >= 0 &&
+          rect.top <= window.innerHeight &&
+          rect.left <= window.innerWidth
+        );
+      }
+
+      function readText(el) {
+        if (!el) return "";
+        return normalize(el.innerText || el.textContent || "");
+      }
+
+      function readAttr(el, name) {
+        if (!el || typeof el.getAttribute !== "function") return "";
+        return normalize(el.getAttribute(name) || "");
+      }
+
+      function collectVisibleDialogs() {
+        const dialogs = [];
+        const nodes = document.querySelectorAll("[role='dialog'], [aria-modal='true'], dialog");
+        for (let i = 0; i < nodes.length; i += 1) {
+          const el = nodes[i];
+          if (isVisible(el)) dialogs.push(el);
+        }
+        return dialogs;
+      }
+
+      function detectActiveField(active) {
+        const activeText = normalize(
+          readAttr(active, "aria-label") + " " + readAttr(active, "placeholder") + " " + readText(active),
+        ).toLowerCase();
+        if (/\bdeparture\b/.test(activeText)) return "departure";
+        if (/\breturn\b/.test(activeText)) return "return";
+        return "";
+      }
+
+      const visibleDialogs = collectVisibleDialogs();
+      const root = visibleDialogs.length > 0 ? visibleDialogs[0] : document.body;
+      const active = document.activeElement instanceof Element ? document.activeElement : null;
+      const activeField = detectActiveField(active);
+      const monthRe =
+        /\b(January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{4}\b/i;
+      const visibleMonths = [];
+      const seenMonths = new Set();
+      const monthNodes = root.querySelectorAll("h1, h2, h3, h4, h5, h6, [role='heading'], div, span");
+      for (let i = 0; i < monthNodes.length; i += 1) {
+        const el = monthNodes[i];
+        if (!isVisible(el)) continue;
+        const match = readText(el).match(monthRe);
+        if (!match) continue;
+        const label = normalize(match[0]);
+        if (!label || seenMonths.has(label)) continue;
+        seenMonths.add(label);
+        visibleMonths.push(label);
+        if (visibleMonths.length >= 6) break;
+      }
+
+      const formValues = [];
+      const seenValues = new Set();
+      const formNodes = document.querySelectorAll(
+        "input, textarea, select, [role='combobox'], [role='textbox']",
+      );
+      for (let i = 0; i < formNodes.length; i += 1) {
+        const el = formNodes[i];
+        if (!isVisible(el)) continue;
+        const label = normalize(
+          readAttr(el, "aria-label") + " " + readAttr(el, "placeholder") + " " + readAttr(el, "name"),
+        );
+        if (!/\b(departure|return)\b/.test(label.toLowerCase())) continue;
+        const value = normalize((typeof el.value === "string" ? el.value : "") || readText(el));
+        const token = (label || el.tagName.toLowerCase()) + "=" + value;
+        if (!value || seenValues.has(token)) continue;
+        seenValues.add(token);
+        formValues.push(token);
+      }
+
+      const selectedDates = [];
+      const seenSelected = new Set();
+      const selectedNodes = root.querySelectorAll(
+        "[aria-selected='true'], [aria-pressed='true'], [aria-current='date'], [aria-current='true']",
+      );
+      for (let i = 0; i < selectedNodes.length; i += 1) {
+        const el = selectedNodes[i];
+        if (!isVisible(el)) continue;
+        const token = normalize(readAttr(el, "aria-label") + " " + readText(el));
+        if (!token || seenSelected.has(token)) continue;
+        seenSelected.add(token);
+        selectedDates.push(token);
+        if (selectedDates.length >= 10) break;
+      }
+
+      let summary = "";
+      const controlNodes = root.querySelectorAll("button, [role='button']");
+      for (let i = 0; i < controlNodes.length; i += 1) {
+        const el = controlNodes[i];
+        if (!isVisible(el)) continue;
+        const label = normalize(readAttr(el, "aria-label") || readText(el));
+        if (/^done\b/i.test(label)) {
+          summary = label.slice(0, 220);
+          break;
+        }
+      }
+
+      const activeTag = active?.tagName?.toLowerCase() || "";
+      const activeId = active?.id || "";
+      const activeRole = readAttr(active, "role");
+      const activeRef = readAttr(active, "aria-ref");
+      return {
+        open: visibleDialogs.length > 0,
+        dialogCount: visibleDialogs.length,
+        activeElement: activeTag + "#" + activeId + "[role=" + activeRole + "][ref=" + activeRef + "]",
+        activeField,
+        visibleMonths,
+        formValues,
+        selectedDates,
+        summary,
+      };
+    })()`;
+        return await this.page.evaluate(script);
+    }
+    _evaluateCalendarObservationChange(targetKind, before, after) {
+        const activeChanged = before.activeElement !== after.activeElement || before.activeField !== after.activeField;
+        const monthsChanged = JSON.stringify(before.visibleMonths) !== JSON.stringify(after.visibleMonths);
+        const valuesChanged = JSON.stringify(before.formValues) !== JSON.stringify(after.formValues);
+        const selectedChanged = JSON.stringify(before.selectedDates) !== JSON.stringify(after.selectedDates);
+        const summaryChanged = before.summary !== after.summary;
+        const dialogChanged = before.dialogCount !== after.dialogCount || before.open !== after.open;
+        if (targetKind === "field") {
+            if (valuesChanged || selectedChanged || summaryChanged) {
+                return { satisfied: true, focusOnly: false, reason: "calendar_field_state_changed" };
+            }
+            if (activeChanged) {
+                return { satisfied: true, focusOnly: true, reason: "calendar_field_focus_changed" };
+            }
+            return { satisfied: false, focusOnly: false, reason: "calendar_field_no_change" };
+        }
+        if (targetKind === "next" || targetKind === "previous") {
+            if (monthsChanged || valuesChanged || summaryChanged || selectedChanged) {
+                return { satisfied: true, focusOnly: false, reason: "calendar_navigation_changed" };
+            }
+            return { satisfied: false, focusOnly: false, reason: "calendar_navigation_no_change" };
+        }
+        if (targetKind === "done") {
+            if (dialogChanged || !after.open) {
+                return { satisfied: true, focusOnly: false, reason: "calendar_dialog_closed" };
+            }
+            return { satisfied: false, focusOnly: false, reason: "calendar_done_no_change" };
+        }
+        if (targetKind === "date") {
+            if (valuesChanged || selectedChanged || summaryChanged || activeChanged) {
+                return { satisfied: true, focusOnly: false, reason: "calendar_date_changed" };
+            }
+            return { satisfied: false, focusOnly: false, reason: "calendar_date_no_change" };
+        }
+        if (monthsChanged || valuesChanged || selectedChanged || summaryChanged || dialogChanged) {
+            return { satisfied: true, focusOnly: false, reason: "calendar_state_changed" };
+        }
+        if (activeChanged) {
+            return { satisfied: true, focusOnly: true, reason: "calendar_focus_changed" };
+        }
+        return { satisfied: false, focusOnly: false, reason: "calendar_no_change" };
+    }
+    _didMeaningfulUiChange(before, after) {
+        return this._getClickObservationDelta(before, after).meaningful;
+    }
+    _isLikelyLink(diag) {
+        if (!diag)
+            return false;
+        const tag = (diag.tag || "").toLowerCase();
+        const role = (diag.role || "").toLowerCase();
+        return (tag === "a" ||
+            role === "link" ||
+            !!diag.href ||
+            !!diag.closestHref ||
+            !!diag.descendantHref);
+    }
+    async _captureClickObservation(target) {
+        const pageUrl = this.page.url();
+        const pageState = await this.page.evaluate(() => {
+            const active = document.activeElement;
+            const activeTag = active?.tagName?.toLowerCase() || "";
+            const activeId = active?.id || "";
+            const activeRole = active?.getAttribute?.("role") || "";
+            const activeRef = active?.getAttribute?.("aria-ref") || "";
+            const activeSig = `${activeTag}#${activeId}[role=${activeRole}][ref=${activeRef}]`;
+            const dialogLabels = [];
+            const seenDialogLabels = new Set();
+            for (const element of Array.from(document.querySelectorAll("[role='dialog'], [aria-modal='true']"))) {
+                const htmlElement = element;
+                const style = window.getComputedStyle(htmlElement);
+                if (style.display === "none" || style.visibility === "hidden")
+                    continue;
+                const rect = htmlElement.getBoundingClientRect();
+                if (rect.width <= 0 || rect.height <= 0)
+                    continue;
+                if (rect.bottom < 0 || rect.right < 0 || rect.top > window.innerHeight || rect.left > window.innerWidth)
+                    continue;
+                let label = (element.getAttribute("aria-label") || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                if (!label) {
+                    const labelledBy = (element.getAttribute("aria-labelledby") || "").trim();
+                    if (labelledBy) {
+                        const parts = [];
+                        for (const id of labelledBy.split(/\s+/)) {
+                            const labelledNode = document.getElementById(id);
+                            const text = (labelledNode?.innerText || labelledNode?.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                            if (text)
+                                parts.push(text);
+                        }
+                        label = parts.join(" ").replace(/\s+/g, " ").trim().slice(0, 180);
+                    }
+                }
+                if (!label) {
+                    const heading = element.querySelector("h1, h2, h3, h4, h5, h6, [role='heading']");
+                    label = (heading?.innerText || heading?.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                }
+                if (!label || seenDialogLabels.has(label))
+                    continue;
+                seenDialogLabels.add(label);
+                dialogLabels.push(label);
+                if (dialogLabels.length >= 6)
+                    break;
+            }
+            const headingTexts = [];
+            const seenHeadingTexts = new Set();
+            for (const element of Array.from(document.querySelectorAll("h1, h2, h3, h4, h5, h6, [role='heading']"))) {
+                const htmlElement = element;
+                const style = window.getComputedStyle(htmlElement);
+                if (style.display === "none" || style.visibility === "hidden")
+                    continue;
+                const rect = htmlElement.getBoundingClientRect();
+                if (rect.width <= 0 || rect.height <= 0)
+                    continue;
+                if (rect.bottom < 0 || rect.right < 0 || rect.top > window.innerHeight || rect.left > window.innerWidth)
+                    continue;
+                const text = (htmlElement.innerText || element.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                if (!text || seenHeadingTexts.has(text))
+                    continue;
+                seenHeadingTexts.add(text);
+                headingTexts.push(text);
+                if (headingTexts.length >= 8)
+                    break;
+            }
+            const formValues = [];
+            const seenFormValues = new Set();
+            for (const element of Array.from(document.querySelectorAll("input, textarea, select, [role='combobox'], [role='textbox']"))) {
+                const htmlElement = element;
+                const style = window.getComputedStyle(htmlElement);
+                if (style.display === "none" || style.visibility === "hidden")
+                    continue;
+                const rect = htmlElement.getBoundingClientRect();
+                if (rect.width <= 0 || rect.height <= 0)
+                    continue;
+                if (rect.bottom < 0 || rect.right < 0 || rect.top > window.innerHeight || rect.left > window.innerWidth)
+                    continue;
+                const inputLike = element;
+                let label = (element.getAttribute("aria-label") || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                if (!label) {
+                    const labelledBy = (element.getAttribute("aria-labelledby") || "").trim();
+                    if (labelledBy) {
+                        const parts = [];
+                        for (const id of labelledBy.split(/\s+/)) {
+                            const labelledNode = document.getElementById(id);
+                            const text = (labelledNode?.innerText || labelledNode?.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                            if (text)
+                                parts.push(text);
+                        }
+                        label = parts.join(" ").replace(/\s+/g, " ").trim().slice(0, 180);
+                    }
+                }
+                if (!label) {
+                    const labelNode = element.closest("label");
+                    label = (labelNode?.innerText || labelNode?.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                }
+                if (!label) {
+                    label = (element.getAttribute("name")
+                        || element.getAttribute("placeholder")
+                        || htmlElement.id
+                        || element.tagName.toLowerCase()).replace(/\s+/g, " ").trim().slice(0, 180);
+                }
+                const value = (inputLike.value || htmlElement.innerText || element.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                if (!value)
+                    continue;
+                const token = `${label}=${value}`.replace(/\s+/g, " ").trim().slice(0, 220);
+                if (!token || seenFormValues.has(token))
+                    continue;
+                seenFormValues.add(token);
+                formValues.push(token);
+                if (formValues.length >= 8)
+                    break;
+            }
+            const selectedStateTokens = [];
+            const seenSelectedStateTokens = new Set();
+            for (const element of Array.from(document.querySelectorAll("[aria-selected='true'], [aria-pressed='true'], [aria-current], [aria-checked='true']"))) {
+                const htmlElement = element;
+                const style = window.getComputedStyle(htmlElement);
+                if (style.display === "none" || style.visibility === "hidden")
+                    continue;
+                const rect = htmlElement.getBoundingClientRect();
+                if (rect.width <= 0 || rect.height <= 0)
+                    continue;
+                if (rect.bottom < 0 || rect.right < 0 || rect.top > window.innerHeight || rect.left > window.innerWidth)
+                    continue;
+                let label = (element.getAttribute("aria-label") || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                if (!label) {
+                    const labelledBy = (element.getAttribute("aria-labelledby") || "").trim();
+                    if (labelledBy) {
+                        const parts = [];
+                        for (const id of labelledBy.split(/\s+/)) {
+                            const labelledNode = document.getElementById(id);
+                            const text = (labelledNode?.innerText || labelledNode?.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                            if (text)
+                                parts.push(text);
+                        }
+                        label = parts.join(" ").replace(/\s+/g, " ").trim().slice(0, 180);
+                    }
+                }
+                if (!label) {
+                    label = (htmlElement.innerText || element.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+                }
+                const states = [
+                    element.getAttribute("aria-selected") === "true" ? "selected" : "",
+                    element.getAttribute("aria-pressed") === "true" ? "pressed" : "",
+                    element.getAttribute("aria-current") ? `current=${(element.getAttribute("aria-current") || "").replace(/\s+/g, " ").trim().slice(0, 60)}` : "",
+                    element.getAttribute("aria-checked") === "true" ? "checked" : "",
+                ].filter(Boolean).join(",");
+                const token = `${(element.getAttribute("role") || "").replace(/\s+/g, " ").trim().slice(0, 60)}:${label}:${states}`
+                    .replace(/\s+/g, " ")
+                    .trim()
+                    .slice(0, 220);
+                if (!token || seenSelectedStateTokens.has(token))
+                    continue;
+                seenSelectedStateTokens.add(token);
+                selectedStateTokens.push(token);
+                if (selectedStateTokens.length >= 10)
+                    break;
+            }
+            return {
+                activeElement: activeSig,
+                dialogCount: document.querySelectorAll("[role='dialog'], [aria-modal='true']").length,
+                listboxCount: document.querySelectorAll("[role='listbox']").length,
+                menuCount: document.querySelectorAll("[role='menu'], [role='menuitem'], [role='menuitemradio']").length,
+                expandedCount: document.querySelectorAll("[aria-expanded='true']").length,
+                dialogLabels,
+                headingTexts,
+                formValues,
+                selectedStateTokens,
+            };
+        });
+        let targetPresent = false;
+        let targetState = null;
+        try {
+            const count = await target.count();
+            targetPresent = count > 0;
+            if (targetPresent) {
+                targetState = await target.evaluate((node) => {
+                    const el = node;
+                    const inputLike = node;
+                    const labelledBy = (node.getAttribute("aria-labelledby") || "")
+                        .split(/\s+/)
+                        .map((id) => document.getElementById(id))
+                        .filter((item) => !!item)
+                        .map((item) => (item.innerText || item.textContent || "").replace(/\s+/g, " ").trim())
+                        .filter(Boolean)
+                        .join(" ");
+                    return {
+                        role: node.getAttribute("role") || "",
+                        ariaLabel: node.getAttribute("aria-label")
+                            || labelledBy
+                            || "",
+                        ariaExpanded: node.getAttribute("aria-expanded"),
+                        ariaSelected: node.getAttribute("aria-selected"),
+                        ariaPressed: node.getAttribute("aria-pressed"),
+                        ariaCurrent: node.getAttribute("aria-current"),
+                        value: inputLike.value || "",
+                        checked: typeof inputLike.checked === "boolean" ? inputLike.checked : null,
+                        text: (el.innerText || node.textContent || "").replace(/\s+/g, " ").trim().slice(0, 200),
+                        disabled: inputLike.disabled || node.getAttribute("aria-disabled") === "true",
+                        className: (el.className || "").toString().slice(0, 200),
+                    };
+                });
+            }
+        }
+        catch {
+            targetPresent = false;
+            targetState = null;
+        }
+        return {
+            pageUrl,
+            activeElement: pageState.activeElement,
+            targetPresent,
+            targetState,
+            dialogCount: pageState.dialogCount,
+            listboxCount: pageState.listboxCount,
+            menuCount: pageState.menuCount,
+            expandedCount: pageState.expandedCount,
+            dialogLabels: pageState.dialogLabels,
+            headingTexts: pageState.headingTexts,
+            formValues: pageState.formValues,
+            selectedStateTokens: pageState.selectedStateTokens,
+        };
+    }
+    _didClickObservationChange(before, after) {
+        return this._getClickObservationDelta(before, after).changed;
+    }
+    _toMeaningfulClickTargetState(state) {
+        if (!state)
+            return null;
+        return {
+            role: state.role,
+            ariaLabel: state.ariaLabel,
+            ariaExpanded: state.ariaExpanded,
+            ariaSelected: state.ariaSelected,
+            ariaPressed: state.ariaPressed,
+            ariaCurrent: state.ariaCurrent,
+            value: state.value,
+            checked: state.checked,
+            text: state.text,
+            disabled: state.disabled,
+        };
+    }
+    _toSemanticPageVector(observation) {
+        return {
+            pageUrl: observation.pageUrl,
+            targetPresent: observation.targetPresent,
+            dialogCount: observation.dialogCount,
+            listboxCount: observation.listboxCount,
+            menuCount: observation.menuCount,
+            expandedCount: observation.expandedCount,
+            dialogLabels: observation.dialogLabels,
+            headingTexts: observation.headingTexts,
+            formValues: observation.formValues,
+            selectedStateTokens: observation.selectedStateTokens,
+        };
+    }
+    _evaluateObservedClickEffect(expectedEffect, observationDelta) {
+        if (expectedEffect === "any") {
+            return { satisfied: true };
+        }
+        if (expectedEffect === "focus") {
+            return observationDelta.changed
+                ? { satisfied: true }
+                : {
+                    satisfied: false,
+                    errorCode: "focus_effect_not_observed",
+                    message: "Error: Click did not move focus or change page state",
+                };
+        }
+        if (expectedEffect === "navigation") {
+            return observationDelta.urlChanged
+                ? { satisfied: true }
+                : {
+                    satisfied: false,
+                    errorCode: "navigation_effect_not_observed",
+                    message: "Error: Click did not trigger navigation",
+                };
+        }
+        return observationDelta.meaningful
+            ? { satisfied: true }
+            : {
+                satisfied: false,
+                errorCode: "ui_effect_not_observed",
+                message: "Error: Click did not cause a meaningful UI change",
+            };
+    }
+    _getClickObservationDelta(before, after) {
+        const activeChanged = before.activeElement !== after.activeElement;
+        const urlChanged = before.pageUrl !== after.pageUrl;
+        const targetChanged = JSON.stringify(this._toMeaningfulClickTargetState(before.targetState))
+            !== JSON.stringify(this._toMeaningfulClickTargetState(after.targetState));
+        const pageSemanticChanged = JSON.stringify(this._toSemanticPageVector(before))
+            !== JSON.stringify(this._toSemanticPageVector(after));
+        const meaningful = urlChanged || targetChanged || pageSemanticChanged;
+        return {
+            changed: meaningful || activeChanged,
+            meaningful,
+            focusOnly: !meaningful && activeChanged,
+            urlChanged,
+            targetChanged,
+            pageSemanticChanged,
+        };
+    }
+    _formatFocusOnlyClickMessage(method, target) {
+        return `Clicked element (${method}): ${target} (focus changed only; no dialog/listbox/menu/url change observed)`;
+    }
+    async _readTypeIdentity(control, timeoutMs = this.shortTimeout) {
+        const handle = await control.elementHandle({ timeout: timeoutMs });
+        if (!handle) {
+            throw new Error("type_target_not_found");
+        }
+        try {
+            return await handle.evaluate((node) => {
+                const inputLike = node;
+                return {
+                    tagName: node.tagName.toLowerCase(),
+                    role: node.getAttribute("role") || "",
+                    type: inputLike.type || "",
+                    id: inputLike.id || "",
+                    name: inputLike.name || "",
+                    ariaLabel: node.getAttribute("aria-label") || "",
+                    placeholder: inputLike.placeholder || "",
+                };
+            });
+        }
+        finally {
+            await handle.dispose().catch(() => undefined);
+        }
+    }
+    async _readTypeState(control, timeoutMs = this.shortTimeout) {
+        const handle = await control.elementHandle({ timeout: timeoutMs });
+        if (!handle) {
+            throw new Error("type_target_not_found");
+        }
+        try {
+            return await handle.evaluate((node) => {
+                const el = node;
+                const inputLike = node;
+                return {
+                    tagName: node.tagName.toLowerCase(),
+                    role: node.getAttribute("role") || "",
+                    type: inputLike.type || "",
+                    value: inputLike.value || "",
+                    text: (el.innerText || node.textContent || "").replace(/\s+/g, " ").trim().slice(0, 200),
+                    ariaAutocomplete: node.getAttribute("aria-autocomplete"),
+                    ariaExpanded: node.getAttribute("aria-expanded"),
+                    placeholder: inputLike.placeholder || "",
+                    active: document.activeElement === node,
+                    listboxCount: document.querySelectorAll("[role='listbox']").length,
+                    optionCount: document.querySelectorAll("[role='option']").length,
+                };
+            });
+        }
+        finally {
+            await handle.dispose().catch(() => undefined);
+        }
+    }
+    async _readTypeStateWithFallback(control, identity) {
+        try {
+            return { state: await this._readTypeState(control), mode: "ref" };
+        }
+        catch (exc) {
+            const directError = String(exc);
+            const reacquired = await this._reacquireTypeControl(identity);
+            if (!reacquired) {
+                return { state: null, mode: "ref_missing", error: directError };
+            }
+            try {
+                return {
+                    state: await this._readTypeState(reacquired),
+                    mode: "identity_reacquired",
+                };
+            }
+            catch (inner) {
+                return {
+                    state: null,
+                    mode: "identity_reacquired_failed",
+                    error: `${directError} | ${String(inner)}`,
+                };
+            }
+        }
+    }
+    async _reacquireTypeControl(identity) {
+        for (const locator of this._buildTypeIdentityLocators(identity)) {
+            try {
+                await locator.elementHandle({ timeout: this.shortTimeout });
+                return locator;
+            }
+            catch {
+                // Try the next candidate.
+            }
+        }
+        return null;
+    }
+    _buildTypeIdentityLocators(identity) {
+        const locators = [];
+        const tagName = identity.tagName || "*";
+        const escapedRole = identity.role ? this._escapeAttributeValue(identity.role) : "";
+        const escapedType = identity.type ? this._escapeAttributeValue(identity.type) : "";
+        const escapedId = identity.id ? this._escapeAttributeValue(identity.id) : "";
+        const escapedName = identity.name ? this._escapeAttributeValue(identity.name) : "";
+        const escapedAriaLabel = identity.ariaLabel ? this._escapeAttributeValue(identity.ariaLabel) : "";
+        const escapedPlaceholder = identity.placeholder ? this._escapeAttributeValue(identity.placeholder) : "";
+        const exactParts = [];
+        if (identity.id)
+            exactParts.push(`[id="${escapedId}"]`);
+        if (identity.name)
+            exactParts.push(`[name="${escapedName}"]`);
+        if (identity.ariaLabel)
+            exactParts.push(`[aria-label="${escapedAriaLabel}"]`);
+        if (identity.placeholder && ["input", "textarea"].includes(tagName)) {
+            exactParts.push(`[placeholder="${escapedPlaceholder}"]`);
+        }
+        if (identity.role)
+            exactParts.push(`[role="${escapedRole}"]`);
+        if (identity.type && tagName === "input")
+            exactParts.push(`[type="${escapedType}"]`);
+        if (exactParts.length > 0) {
+            locators.push(this.page.locator(`${tagName}${exactParts.join("")}`).first());
+        }
+        if (identity.id) {
+            locators.push(this.page.locator(`${tagName}[id="${escapedId}"]`).first());
+        }
+        if (identity.name) {
+            locators.push(this.page.locator(`${tagName}[name="${escapedName}"]`).first());
+        }
+        if (identity.ariaLabel) {
+            locators.push(this.page.locator(`${tagName}[aria-label="${escapedAriaLabel}"]`).first());
+        }
+        if (identity.placeholder && ["input", "textarea"].includes(tagName)) {
+            locators.push(this.page.getByPlaceholder(identity.placeholder, { exact: true }).first());
+        }
+        if (identity.role) {
+            let roleSelector = `${tagName}[role="${escapedRole}"]`;
+            if (identity.type && tagName === "input") {
+                roleSelector += `[type="${escapedType}"]`;
+            }
+            locators.push(this.page.locator(roleSelector).first());
+        }
+        if (["input", "textarea"].includes(tagName)) {
+            locators.push(this.page.locator(`${tagName}:focus`).first());
+        }
+        return locators;
+    }
+    _shouldPreferKeyboardTyping(state) {
+        const role = state.role.toLowerCase();
+        const type = state.type.toLowerCase();
+        return (role === "combobox" ||
+            role === "searchbox" ||
+            type === "search" ||
+            !!state.ariaAutocomplete);
+    }
+    _typeStateMatchesExpected(state, expected) {
+        const normalizedExpected = this._normalizeTypeToken(expected);
+        const normalizedValue = this._normalizeTypeToken(state.value);
+        const normalizedText = this._normalizeTypeToken(state.text);
+        if (!normalizedExpected) {
+            return normalizedValue.length === 0 && normalizedText.length === 0;
+        }
+        if (normalizedValue === normalizedExpected)
+            return true;
+        if (normalizedText === normalizedExpected)
+            return true;
+        if (this._shouldPreferKeyboardTyping(state)) {
+            if (normalizedValue && normalizedExpected.includes(normalizedValue))
+                return true;
+            if (normalizedValue && normalizedValue.includes(normalizedExpected))
+                return true;
+        }
+        return false;
+    }
+    _normalizeTypeToken(value) {
+        return (value || "").replace(/\s+/g, " ").trim().toLowerCase();
+    }
+    _normalizeSelectToken(value) {
+        return (value || "").replace(/\s+/g, " ").trim().toLowerCase();
+    }
+    _escapeAttributeValue(value) {
+        return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    }
+    _parseTimeToken(value) {
+        const raw = this._normalizeSelectToken(value);
+        if (!raw)
+            return null;
+        const amPmMatch = raw.match(/^(\d{1,2})(?::(\d{2}))?\s*([ap])\.?m\.?$/i);
+        if (amPmMatch) {
+            let hours = Number(amPmMatch[1]);
+            const minutes = Number(amPmMatch[2] || "0");
+            const meridiem = amPmMatch[3].toLowerCase();
+            if (hours > 12 || minutes > 59)
+                return null;
+            if (meridiem === "p" && hours < 12)
+                hours += 12;
+            if (meridiem === "a" && hours === 12)
+                hours = 0;
+            return hours * 60 + minutes;
+        }
+        const colonMatch = raw.match(/^(\d{1,2}):(\d{2})$/);
+        if (colonMatch) {
+            const hours = Number(colonMatch[1]);
+            const minutes = Number(colonMatch[2]);
+            if (hours > 23 || minutes > 59)
+                return null;
+            return hours * 60 + minutes;
+        }
+        const compactMatch = raw.match(/^(\d{3,4})$/);
+        if (compactMatch) {
+            const compact = compactMatch[1].padStart(4, "0");
+            const hours = Number(compact.slice(0, 2));
+            const minutes = Number(compact.slice(2, 4));
+            if (hours > 23 || minutes > 59)
+                return null;
+            return hours * 60 + minutes;
+        }
+        return null;
+    }
+    _parseCountToken(value) {
+        const raw = this._normalizeSelectToken(value);
+        if (!raw || raw.includes(":") || /(?:a\.?m\.?|p\.?m\.?)/i.test(raw))
+            return null;
+        const match = raw.match(/(?:^|\b)(\d{1,3})(?:\b|$)/);
+        return match ? Number(match[1]) : null;
+    }
+    _inferSelectDomain(options) {
+        if (options.length === 0)
+            return "generic";
+        let timeLike = 0;
+        let countLike = 0;
+        for (const option of options) {
+            if ([option.value, option.text, option.label, option.dataValue, option.ariaLabel]
+                .some((token) => this._parseTimeToken(token) !== null)) {
+                timeLike += 1;
+            }
+            if ([option.value, option.text, option.label, option.dataValue, option.ariaLabel]
+                .some((token) => this._parseCountToken(token) !== null)) {
+                countLike += 1;
+            }
+        }
+        if (timeLike >= 2 && timeLike / options.length >= 0.5)
+            return "time";
+        if (countLike >= 2 && countLike / options.length >= 0.5)
+            return "count";
+        return "generic";
+    }
+    _resolveSelectOption(options, requestedValue) {
+        const normalizedRequested = this._normalizeSelectToken(requestedValue);
+        if (!normalizedRequested || options.length === 0)
+            return null;
+        const exactMatches = options.filter((option) => {
+            const tokens = [option.value, option.text, option.label, option.dataValue, option.ariaLabel]
+                .map((token) => this._normalizeSelectToken(token))
+                .filter(Boolean);
+            return tokens.includes(normalizedRequested);
+        });
+        if (exactMatches.length === 1) {
+            return { domain: "generic", reason: "exact_token_match", option: exactMatches[0] };
+        }
+        const domain = this._inferSelectDomain(options);
+        if (domain === "time") {
+            const requestedMinutes = this._parseTimeToken(requestedValue);
+            if (requestedMinutes !== null) {
+                const matches = options.filter((option) => [option.value, option.text, option.label, option.dataValue, option.ariaLabel]
+                    .map((token) => this._parseTimeToken(token))
+                    .some((token) => token === requestedMinutes));
+                if (matches.length === 1) {
+                    return { domain, reason: "semantic_time_match", option: matches[0] };
+                }
+            }
+        }
+        if (domain === "count") {
+            const requestedCount = this._parseCountToken(requestedValue);
+            if (requestedCount !== null) {
+                const matches = options.filter((option) => [option.value, option.text, option.label, option.dataValue, option.ariaLabel]
+                    .map((token) => this._parseCountToken(token))
+                    .some((token) => token === requestedCount));
+                if (matches.length === 1) {
+                    return { domain, reason: "semantic_count_match", option: matches[0] };
+                }
+            }
+        }
+        return null;
+    }
+    _selectStateMatchesOption(state, resolution) {
+        if (!state)
+            return false;
+        const stateTokens = [
+            state.value,
+            state.selectedText,
+            state.text,
+            state.ariaLabel,
+            state.ariaValueText,
+        ];
+        const optionTokens = [
+            resolution.option.value,
+            resolution.option.text,
+            resolution.option.label,
+            resolution.option.ariaLabel,
+            resolution.option.dataValue,
+        ];
+        if (resolution.domain === "time") {
+            const expected = optionTokens
+                .map((token) => this._parseTimeToken(token))
+                .find((token) => token !== null);
+            if (expected === undefined)
+                return false;
+            return stateTokens
+                .map((token) => this._parseTimeToken(token))
+                .some((token) => token === expected);
+        }
+        if (resolution.domain === "count") {
+            const expected = optionTokens
+                .map((token) => this._parseCountToken(token))
+                .find((token) => token !== null);
+            if (expected === undefined)
+                return false;
+            return stateTokens
+                .map((token) => this._parseCountToken(token))
+                .some((token) => token === expected);
+        }
+        const normalizedOptionTokens = optionTokens
+            .map((token) => this._normalizeSelectToken(token))
+            .filter(Boolean);
+        const normalizedStateTokens = stateTokens
+            .map((token) => this._normalizeSelectToken(token))
+            .filter(Boolean);
+        return normalizedStateTokens.some((token) => normalizedOptionTokens.includes(token));
+    }
+    _selectModelMatchesResolution(model, resolution) {
+        return this._selectStateMatchesOption(model, resolution);
+    }
+    async _readSelectModel(control, timeoutMs) {
+        try {
+            const handle = await control.elementHandle({ timeout: timeoutMs });
+            if (!handle)
+                return null;
+            try {
+                return await handle.evaluate((node) => {
+                    const el = node;
+                    const inputLike = node;
+                    const tagName = (node.tagName || "").toLowerCase();
+                    const role = node.getAttribute("role") || "";
+                    const labelTexts = [];
+                    if ("labels" in inputLike && inputLike.labels) {
+                        for (const labelNode of Array.from(inputLike.labels)) {
+                            const text = (labelNode.innerText || labelNode.textContent || "").replace(/\s+/g, " ").trim();
+                            if (text)
+                                labelTexts.push(text);
+                        }
+                    }
+                    if (labelTexts.length === 0) {
+                        const parentLabel = el.closest("label");
+                        const text = (parentLabel?.innerText || parentLabel?.textContent || "").replace(/\s+/g, " ").trim();
+                        if (text)
+                            labelTexts.push(text);
+                    }
+                    if (labelTexts.length === 0) {
+                        const id = inputLike.id || node.getAttribute("id") || "";
+                        if (id) {
+                            const externalLabel = document.querySelector(`label[for="${id.replace(/"/g, '\\"')}"]`);
+                            const text = (externalLabel?.textContent || "").replace(/\s+/g, " ").trim();
+                            if (text)
+                                labelTexts.push(text);
+                        }
+                    }
+                    const selectedText = tagName === "select"
+                        ? Array.from((node.selectedOptions || []))
+                            .map((opt) => (opt.textContent || "").trim())
+                            .filter((txt) => !!txt)
+                            .join(" ")
+                        : "";
+                    const options = tagName === "select"
+                        ? Array.from(node.options || []).map((opt) => ({
+                            value: opt.value || "",
+                            text: (opt.textContent || "").replace(/\s+/g, " ").trim(),
+                            label: opt.label || "",
+                            disabled: opt.disabled,
+                            selected: opt.selected,
+                            role: "option",
+                            dataValue: opt.getAttribute("data-value") || "",
+                            ariaLabel: opt.getAttribute("aria-label") || "",
+                        }))
+                        : [];
+                    return {
+                        kind: tagName === "select" ? "native_select" : "custom_select",
+                        tagName,
+                        role,
+                        value: inputLike.value || "",
+                        selectedText,
+                        text: (el.innerText || node.textContent || "").replace(/\s+/g, " ").trim(),
+                        ariaLabel: node.getAttribute("aria-label") || "",
+                        ariaValueText: node.getAttribute("aria-valuetext") || "",
+                        identity: {
+                            tagName,
+                            role,
+                            id: inputLike.id || node.getAttribute("id") || "",
+                            name: inputLike.name || node.getAttribute("name") || "",
+                            ariaLabel: node.getAttribute("aria-label") || "",
+                            labelText: labelTexts.join(" ").replace(/\s+/g, " ").trim().slice(0, 200),
+                            dataTestId: node.getAttribute("data-testid") || node.getAttribute("data-test-id") || "",
+                        },
+                        ariaControls: node.getAttribute("aria-controls") || "",
+                        ariaOwns: node.getAttribute("aria-owns") || "",
+                        ariaExpanded: node.getAttribute("aria-expanded"),
+                        options,
+                    };
+                });
+            }
+            finally {
+                await handle.dispose().catch(() => { });
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    async _clickFirstVisible(locator, label, debugLog) {
+        let count = 0;
+        try {
+            count = await locator.count();
+        }
+        catch (e) {
+            debugLog.push({ label, count: 0, error: String(e) });
+            return false;
+        }
+        const inspectCount = Math.min(count, 8);
+        for (let i = 0; i < inspectCount; i++) {
+            const candidate = locator.nth(i);
+            const visible = await candidate.isVisible().catch(() => false);
+            if (!visible)
+                continue;
+            const enabled = await candidate.isEnabled().catch(() => true);
+            if (!enabled)
+                continue;
+            try {
+                await candidate.click({ timeout: this.shortTimeout });
+                debugLog.push({ label, index: i, clicked: true });
+                await this.page.waitForTimeout(100);
+                return true;
+            }
+            catch (e) {
+                debugLog.push({ label, index: i, clicked: false, error: String(e) });
+            }
+        }
+        return false;
+    }
+    async _readScopedSelectOptions(scope) {
+        try {
+            const handle = await scope.elementHandle({ timeout: this.defaultTimeout });
+            if (!handle)
+                return [];
+            try {
+                return await handle.evaluate((node) => {
+                    const seen = new Set();
+                    const options = [];
+                    const candidates = Array.from(node.querySelectorAll("[role='option'], [role='menuitem'], [role='menuitemradio'], option, [data-value]"));
+                    for (const candidate of candidates) {
+                        const html = candidate;
+                        const style = window.getComputedStyle(html);
+                        if (style.display === "none" || style.visibility === "hidden")
+                            continue;
+                        const rect = html.getBoundingClientRect();
+                        if (rect.width <= 0 || rect.height <= 0)
+                            continue;
+                        const text = (html.innerText || candidate.textContent || "").replace(/\s+/g, " ").trim();
+                        const value = candidate.value || candidate.getAttribute("value") || "";
+                        const label = candidate.getAttribute("label") || "";
+                        const ariaLabel = candidate.getAttribute("aria-label") || "";
+                        const dataValue = candidate.getAttribute("data-value") || "";
+                        const role = candidate.getAttribute("role") || candidate.tagName.toLowerCase();
+                        const key = [role, value, text, label, ariaLabel, dataValue].join("||");
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        options.push({
+                            value,
+                            text,
+                            label,
+                            disabled: candidate.disabled
+                                || candidate.getAttribute("aria-disabled") === "true",
+                            selected: candidate.selected
+                                || candidate.getAttribute("aria-selected") === "true"
+                                || candidate.getAttribute("aria-checked") === "true",
+                            role,
+                            dataValue,
+                            ariaLabel,
+                        });
+                    }
+                    return options;
+                });
+            }
+            finally {
+                await handle.dispose().catch(() => { });
+            }
+        }
+        catch {
+            return [];
+        }
+    }
+    async _reacquireSelectModel(target, identity) {
+        for (const locator of this._buildSelectIdentityLocators(target, identity)) {
+            const model = await this._readSelectModel(locator, this.defaultTimeout);
+            if (model)
+                return model;
+        }
+        return null;
+    }
+    _buildSelectIdentityLocators(target, identity) {
+        const locators = [];
+        locators.push(this.page.locator(target).first());
+        const tagName = identity.tagName || "*";
+        if (identity.id) {
+            const escaped = this._escapeAttributeValue(identity.id);
+            locators.push(this.page.locator(`${tagName}[id="${escaped}"]`).first());
+        }
+        if (identity.dataTestId) {
+            const escaped = this._escapeAttributeValue(identity.dataTestId);
+            locators.push(this.page.locator(`[data-testid="${escaped}"]`).first());
+            locators.push(this.page.locator(`[data-test-id="${escaped}"]`).first());
+        }
+        if (identity.name) {
+            const escaped = this._escapeAttributeValue(identity.name);
+            locators.push(this.page.locator(`${tagName}[name="${escaped}"]`).first());
+        }
+        if (identity.ariaLabel) {
+            const escaped = this._escapeAttributeValue(identity.ariaLabel);
+            locators.push(this.page.locator(`${tagName}[aria-label="${escaped}"]`).first());
+        }
+        if (identity.labelText && ["select", "input", "textarea"].includes(tagName)) {
+            locators.push(this.page.getByLabel(identity.labelText, { exact: true }).first());
+        }
+        return locators;
+    }
+    async _openCustomSelectScope(control, beforeModel, details) {
+        const debugLog = [];
+        details.custom_attempts = debugLog;
+        try {
+            await control.click({ timeout: this.defaultTimeout });
+            debugLog.push({ step: "open_control", success: true });
+            await this.page.waitForTimeout(120);
+        }
+        catch (e) {
+            debugLog.push({ step: "open_control", success: false, error: String(e) });
+            return null;
+        }
+        const ownedIds = [beforeModel.ariaControls, beforeModel.ariaOwns]
+            .flatMap((value) => value.split(/\s+/))
+            .map((value) => value.trim())
+            .filter(Boolean);
+        for (const id of ownedIds) {
+            const locator = this.page.locator(`[id="${this._escapeAttributeValue(id)}"]`).first();
+            if (await locator.isVisible().catch(() => false)) {
+                debugLog.push({ step: "use_owned_popup", id });
+                return locator;
+            }
+        }
+        const nearestScope = await this._findVisiblePopupScope(control);
+        if (nearestScope) {
+            debugLog.push({ step: "use_nearest_popup_scope", success: true });
+            return nearestScope;
+        }
+        return null;
+    }
+    async _findVisiblePopupScope(control) {
+        const popupLocator = this.page.locator("[role='listbox'], [role='menu'], [role='dialog']");
+        const popupCount = await popupLocator.count().catch(() => 0);
+        if (popupCount === 0)
+            return null;
+        const controlBox = await control.boundingBox().catch(() => null);
+        let bestIndex = -1;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < Math.min(popupCount, 8); i++) {
+            const candidate = popupLocator.nth(i);
+            const visible = await candidate.isVisible().catch(() => false);
+            if (!visible)
+                continue;
+            if (!controlBox)
+                return candidate;
+            const box = await candidate.boundingBox().catch(() => null);
+            if (!box)
+                continue;
+            const dx = box.x + box.width / 2 - (controlBox.x + controlBox.width / 2);
+            const dy = box.y + box.height / 2 - (controlBox.y + controlBox.height / 2);
+            const distance = Math.sqrt(dx * dx + dy * dy);
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                bestIndex = i;
+            }
+        }
+        return bestIndex >= 0 ? popupLocator.nth(bestIndex) : null;
+    }
+    async _clickScopedSelectOption(scope, option, details) {
+        const debugLog = Array.isArray(details.custom_attempts)
+            ? details.custom_attempts
+            : [];
+        const attempts = [];
+        if (option.value) {
+            const escapedValue = this._escapeAttributeValue(option.value);
+            attempts.push({
+                label: `option[value="${option.value}"]`,
+                locator: scope.locator(`option[value="${escapedValue}"]`),
+            });
+        }
+        if (option.dataValue) {
+            const escapedDataValue = this._escapeAttributeValue(option.dataValue);
+            attempts.push({
+                label: `[data-value="${option.dataValue}"]`,
+                locator: scope.locator(`[data-value="${escapedDataValue}"]`),
+            });
+        }
+        const displayName = option.text || option.label || option.ariaLabel;
+        if (displayName) {
+            attempts.push({
+                label: `scope text exact "${displayName}"`,
+                locator: scope.getByText(displayName, { exact: true }),
+            });
+            if (option.ariaLabel) {
+                attempts.push({
+                    label: `scope aria-label "${option.ariaLabel}"`,
+                    locator: scope.locator(`[aria-label="${this._escapeAttributeValue(option.ariaLabel)}"]`),
+                });
+            }
+        }
+        for (const attempt of attempts) {
+            const clicked = await this._clickFirstVisible(attempt.locator, attempt.label, debugLog);
+            if (clicked)
+                return true;
+        }
+        return false;
+    }
+    _toSelectStateDebug(model) {
+        if (!model)
+            return null;
+        return {
+            kind: model.kind,
+            tagName: model.tagName,
+            role: model.role,
+            value: model.value,
+            selectedText: model.selectedText,
+            ariaValueText: model.ariaValueText,
+            identity: model.identity,
+            optionCount: model.options.length,
+        };
+    }
+    _toSelectOptionDebug(option) {
+        if (!option)
+            return null;
+        return {
+            value: option.value,
+            text: option.text,
+            label: option.label,
+            role: option.role,
+            dataValue: option.dataValue,
+            ariaLabel: option.ariaLabel,
+        };
+    }
+    _toSelectResolutionDebug(resolution) {
+        if (!resolution)
+            return null;
+        return {
+            domain: resolution.domain,
+            reason: resolution.reason,
+            option: this._toSelectOptionDebug(resolution.option),
+        };
+    }
+    _validCoordinates(xCoord, yCoord) {
+        const viewport = this.page.viewportSize();
+        if (!viewport) {
+            throw new Error("Viewport size not available from current page.");
+        }
+        return xCoord >= 0 && xCoord <= viewport.width && yCoord >= 0 && yCoord <= viewport.height;
+    }
+}
+//# sourceMappingURL=action-executor.js.map