jumpy-lion 0.0.34 → 0.0.36

package/dist/page.js

@@ -3,6 +3,22 @@ import { load as cheerioLoad } from 'cheerio';
 import CDP from 'chrome-remote-interface';
 import { log } from 'crawlee';
 import { PAGE_CLOSED, PAGE_CREATED } from './events.js';
+// Constants for timing and delays
+const PRESS_RELEASE_DELAY_MS = 50; // ms between mouse press and release
+const SCROLL_ANIMATION_DELAY_MS = 200; // ms to wait for scroll animations
+const OPTION_LOAD_DELAY_MS = 300; // ms to wait for new options to load in dropdowns
+const DROPDOWN_OPEN_DELAY_MS = 300; // ms to wait for dropdown to open
+const HUMAN_DELAY_MS = 200; // ms delay for human-like interactions
+const SCROLL_COMPLETE_DELAY_MS = 300; // ms to wait for scroll to complete
+// Constants for stability and positioning
+const DEFAULT_TIMEOUT_MS = 30000; // Default timeout for operations
+const POSITION_STABILITY_TIMEOUT_MS = 2000; // Timeout for position stabilization
+const POSITION_CHECK_INTERVAL_MS = 100; // Interval for position checks
+const POSITION_STABILITY_THRESHOLD = 3; // Number of consecutive stable checks required
+const POSITION_TOLERANCE_PX = 1; // Maximum pixel difference to consider "stable"
+const VIEWPORT_TOLERANCE_PX = 50; // Tolerance for viewport positioning
+// Constants for polling and retries
+const POLLING_INTERVAL_MS = 100; // Default polling interval
 /**
  * Creates a proxy that wraps CdpPage methods with reconnection logic
 
@@ -192,7 +208,7 @@ export default class CdpPage extends EventEmitter {
     // Navigation method
     async goto(url, options) {
         const { Page, Runtime } = this.client;
-        const timeout = options?.timeout ?? 30000;
+        const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
         // Clear browser cache before navigation
         // await Network.clearBrowserCache().catch(e => log.error('Failed to clear cache:', e));
         await Page.navigate({ url });
@@ -221,7 +237,7 @@ export default class CdpPage extends EventEmitter {
      */
     async reload(options) {
         const { Page, Runtime } = this.client;
-        const timeout = options?.timeout ?? 30000;
+        const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
         const waitUntil = options?.waitUntil ?? 'load';
         await Page.reload({});
         let waitEvent;
@@ -270,23 +286,346 @@ export default class CdpPage extends EventEmitter {
         return result.value;
     }
     // Click method
-    async click(selector) {
+    async click(selector, options) {
         await Promise.all([
             this._enableDomain('DOM'),
             this._enableDomain('Input'),
         ]);
         const { DOM, Input } = this.client;
-        await this.waitForSelector(selector);
+        const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
+        const force = options?.force ?? false;
+        const delay = options?.delay ?? 0;
+        const button = options?.button ?? 'left';
+        const clickCount = options?.clickCount ?? 1;
+        // Wait for element to exist
+        await this.waitForSelector(selector, { timeout });
+        // Get element details and check visibility
+        const elementInfo = await this._getElementInfo(selector);
+        if (!elementInfo) {
+            throw new Error(`Element not found: ${selector}`);
+        }
+        // Check if element is visible (unless force is true)
+        if (!force) {
+            const isVisible = await this._isElementVisible(selector);
+            if (!isVisible) {
+                throw new Error(`Element is not visible: ${selector}. Use force: true to bypass the visibility check and attempt interaction anyway. Warning: Interacting with non-visible elements may lead to unexpected behavior or errors.`);
+            }
+        }
+        // Check if element is clickable (unless force is true)
+        if (!force) {
+            const isClickable = await this._isElementClickable(selector);
+            if (!isClickable) {
+                throw new Error(`Element is not clickable: ${selector}. Use force: true to bypass this check.`);
+            }
+        }
+        // Scroll element into view if needed
+        await this._scrollElementIntoView(selector);
+        // Wait for scroll animations to complete by polling for position stabilization
+        // Wait for the element's position to stabilize after scrolling.
+        // This is necessary because scroll animations or layout changes may cause the element's position
+        // to shift for a short period. If we attempt to click before the position is stable, the click
+        // may be sent to the wrong location, potentially missing the target element or causing unreliable
+        // automation. Polling for position stabilization ensures the click is performed accurately.
+        await this._waitForElementPositionToStabilize(selector, POSITION_STABILITY_TIMEOUT_MS, POSITION_CHECK_INTERVAL_MS);
+        // Get updated element position after scrolling
         const { nodeId } = await this.getNodeId(selector);
-        const { model } = await DOM.getBoxModel({ nodeId });
+        // For hidden elements, we need to handle the case where box model can't be computed
+        let model;
+        try {
+            const boxModelResult = await DOM.getBoxModel({ nodeId });
+            model = boxModelResult.model;
+        }
+        catch (error) {
+            if (force) {
+                // If force is true, try to get a default position
+                const fallbackElementInfo = await this._getElementInfo(selector);
+                if (fallbackElementInfo) {
+                    const x = fallbackElementInfo.boundingBox.x + fallbackElementInfo.boundingBox.width / 2;
+                    const y = fallbackElementInfo.boundingBox.y + fallbackElementInfo.boundingBox.height / 2;
+                    await this._performClick(Input, x, y, button, clickCount, delay);
+                    return;
+                }
+            }
+            throw new Error(`Could not get box model for node: ${nodeId}. Element might be hidden or not rendered.`);
+        }
         if (!model) {
             throw new Error(`Could not get box model for node: ${nodeId}`);
         }
+        // Calculate click coordinates (center of the element)
         const x = (model.content[0] + model.content[4]) / 2;
         const y = (model.content[1] + model.content[5]) / 2;
+        // Verify element is still in viewport after scrolling (with some tolerance)
+        if (!force) {
+            const isInViewport = await this._isElementInViewport(selector);
+            if (!isInViewport) {
+                // Give a bit more time for scroll animations to complete
+                await new Promise(resolve => setTimeout(resolve, HUMAN_DELAY_MS));
+                const isInViewportAfterDelay = await this._isElementInViewport(selector);
+                if (!isInViewportAfterDelay) {
+                    throw new Error(`Element is not in viewport after scrolling: ${selector}`);
+                }
+            }
+        }
+        // Perform the click with human-like interaction
+        await this._performClick(Input, x, y, button, clickCount, delay);
+    }
+    /**
+     * Performs a human-like click with proper mouse events
+     */
+    async _performClick(Input, x, y, button, clickCount, delay) {
+        // Move mouse cursor to target coordinates (x, y)
         await Input.dispatchMouseEvent({ type: 'mouseMoved', x, y });
-        await Input.dispatchMouseEvent({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 });
-        await Input.dispatchMouseEvent({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 });
+        // Small delay to simulate human behavior
+        if (delay > 0) {
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+        // Press mouse button
+        await Input.dispatchMouseEvent({
+            type: 'mousePressed',
+            x,
+            y,
+            button,
+            clickCount,
+        });
+        // Small delay between press and release
+        await new Promise(resolve => setTimeout(resolve, PRESS_RELEASE_DELAY_MS));
+        // Release mouse button
+        await Input.dispatchMouseEvent({
+            type: 'mouseReleased',
+            x,
+            y,
+            button,
+            clickCount,
+        });
+    }
+    /**
+     * Gets detailed information about an element
+     */
+    async _getElementInfo(selector) {
+        return await this.evaluate((sel) => {
+            const element = document.querySelector(sel);
+            if (!element)
+                return null;
+            const rect = element.getBoundingClientRect();
+            const style = window.getComputedStyle(element);
+            // Check if element is visible
+            const isVisible = style.display !== 'none' &&
+                style.visibility !== 'hidden' &&
+                rect.width > 0 &&
+                rect.height > 0;
+            // Check if element is clickable
+            const isClickable = !element.hasAttribute('disabled') &&
+                !element.classList.contains('disabled') &&
+                style.pointerEvents !== 'none' &&
+                rect.width > 0 &&
+                rect.height > 0;
+            return {
+                nodeId: 0, // Will be set by CDP
+                boundingBox: {
+                    x: rect.left,
+                    y: rect.top,
+                    width: rect.width,
+                    height: rect.height,
+                },
+                isVisible,
+                isClickable,
+            };
+        }, selector);
+    }
+    /**
+     * Enhanced visibility check that considers more factors
+     */
+    async _isElementVisible(selector) {
+        return await this.evaluate((sel) => {
+            const element = document.querySelector(sel);
+            if (!element)
+                return false;
+            const rect = element.getBoundingClientRect();
+            const style = window.getComputedStyle(element);
+            // Basic visibility checks
+            if (style.display === 'none' || style.visibility === 'hidden') {
+                return false;
+            }
+            // Check if element has dimensions
+            if (rect.width === 0 || rect.height === 0) {
+                return false;
+            }
+            // Check if element is not transparent
+            if (parseFloat(style.opacity) === 0) {
+                return false;
+            }
+            // Check if element is not clipped by overflow
+            const parent = element.parentElement;
+            if (parent) {
+                const parentStyle = window.getComputedStyle(parent);
+                if (parentStyle.overflow === 'hidden') {
+                    const parentRect = parent.getBoundingClientRect();
+                    if (rect.left >= parentRect.right ||
+                        rect.right <= parentRect.left ||
+                        rect.top >= parentRect.bottom ||
+                        rect.bottom <= parentRect.top) {
+                        return false;
+                    }
+                }
+            }
+            return true;
+        }, selector);
+    }
+    /**
+     * Enhanced clickable check that considers more factors
+     */
+    async _isElementClickable(selector) {
+        return await this.evaluate((sel) => {
+            const element = document.querySelector(sel);
+            if (!element)
+                return false;
+            const rect = element.getBoundingClientRect();
+            const style = window.getComputedStyle(element);
+            // Check if element is disabled
+            if (element.hasAttribute('disabled') || element.classList.contains('disabled')) {
+                return false;
+            }
+            // Check if pointer events are disabled
+            if (style.pointerEvents === 'none') {
+                return false;
+            }
+            // Check if element has dimensions
+            if (rect.width === 0 || rect.height === 0) {
+                return false;
+            }
+            // Check if element is not transparent
+            if (parseFloat(style.opacity) === 0) {
+                return false;
+            }
+            // Check if element is not read-only (for form elements)
+            if (element.hasAttribute('readonly')) {
+                return false;
+            }
+            return true;
+        }, selector);
+    }
+    /**
+     * Enhanced scroll into view with better positioning
+     */
+    async _scrollElementIntoView(selector) {
+        await this.evaluate((sel, tolerance) => {
+            const element = document.querySelector(sel);
+            if (!element)
+                return;
+            const rect = element.getBoundingClientRect();
+            const viewportHeight = window.innerHeight;
+            const viewportWidth = window.innerWidth;
+            // Check if element is already in viewport (with tolerance)
+            const isInViewport = rect.top >= -tolerance &&
+                rect.left >= -tolerance &&
+                rect.bottom <= viewportHeight + tolerance &&
+                rect.right <= viewportWidth + tolerance;
+            if (!isInViewport) {
+                // Scroll element into view with better positioning
+                element.scrollIntoView({
+                    behavior: 'smooth',
+                    block: 'center',
+                    inline: 'center',
+                });
+            }
+        }, selector, VIEWPORT_TOLERANCE_PX);
+    }
+    /**
+     * Waits for an element's position to stabilize by polling its position over time.
+     * This is useful for waiting for scroll animations or dynamic layout changes to complete.
+     *
+     * @param selector - The CSS selector for the element to monitor
+     * @param timeout - Maximum time to wait in milliseconds (default: 2000)
+     * @param checkInterval - How often to check position in milliseconds (default: 100)
+     * @param stabilityThreshold - Number of consecutive stable checks required (default: 3)
+     * @param tolerance - Maximum pixel difference to consider "stable" (default: 1)
+     */
+    async _waitForElementPositionToStabilize(selector, timeout = POSITION_STABILITY_TIMEOUT_MS, checkInterval = POSITION_CHECK_INTERVAL_MS, stabilityThreshold = POSITION_STABILITY_THRESHOLD, tolerance = POSITION_TOLERANCE_PX) {
+        const startTime = Date.now();
+        let stableCount = 0;
+        let lastPosition = null;
+        while (Date.now() - startTime < timeout) {
+            try {
+                const currentPosition = await this.evaluate((sel) => {
+                    const element = document.querySelector(sel);
+                    if (!element)
+                        return null;
+                    const rect = element.getBoundingClientRect();
+                    return {
+                        x: Math.round(rect.left),
+                        y: Math.round(rect.top),
+                        width: Math.round(rect.width),
+                        height: Math.round(rect.height),
+                    };
+                }, selector);
+                if (!currentPosition) {
+                    // Element not found, reset stability counter
+                    stableCount = 0;
+                    lastPosition = null;
+                }
+                else if (!lastPosition) {
+                    // First position reading
+                    lastPosition = currentPosition;
+                    stableCount = 1;
+                }
+                else {
+                    // Check if position is stable (within tolerance)
+                    const deltaX = Math.abs(currentPosition.x - lastPosition.x);
+                    const deltaY = Math.abs(currentPosition.y - lastPosition.y);
+                    const deltaWidth = Math.abs(currentPosition.width - lastPosition.width);
+                    const deltaHeight = Math.abs(currentPosition.height - lastPosition.height);
+                    const isStable = deltaX <= tolerance &&
+                        deltaY <= tolerance &&
+                        deltaWidth <= tolerance &&
+                        deltaHeight <= tolerance;
+                    if (isStable) {
+                        stableCount++;
+                        if (stableCount >= stabilityThreshold) {
+                            // Position has been stable for required number of checks
+                            return;
+                        }
+                    }
+                    else {
+                        // Position changed, reset counter
+                        stableCount = 1;
+                    }
+                    lastPosition = currentPosition;
+                }
+            }
+            catch (error) {
+                // Error reading position, reset stability counter
+                stableCount = 0;
+                lastPosition = null;
+            }
+            // Wait before next check
+            await new Promise(resolve => setTimeout(resolve, checkInterval));
+        }
+        // If we reach here, we timed out - this is acceptable as some elements may never stabilize
+        // If we reach here, we timed out. This means the element's position did not stabilize within the allotted time.
+        // Proceeding may cause interaction failures if the element is still moving or changing position.
+        // Callers should be aware that stabilization was not achieved and handle this case appropriately.
+    }
+    // Public wrapper for tests and external use
+    async waitForElementPositionToStabilize(selector, timeout = POSITION_STABILITY_TIMEOUT_MS, checkInterval = POSITION_CHECK_INTERVAL_MS, stabilityThreshold = POSITION_STABILITY_THRESHOLD, tolerance = POSITION_TOLERANCE_PX) {
+        return this._waitForElementPositionToStabilize(selector, timeout, checkInterval, stabilityThreshold, tolerance);
+    }
+    /**
+     * Check if element is within the viewport (with some tolerance)
+     */
+    async _isElementInViewport(selector) {
+        return await this.evaluate((sel, tolerance) => {
+            const element = document.querySelector(sel);
+            if (!element)
+                return false;
+            const rect = element.getBoundingClientRect();
+            const viewportHeight = window.innerHeight;
+            const viewportWidth = window.innerWidth;
+            // Add some tolerance for scroll positioning
+            return rect.top >= -tolerance &&
+                rect.left >= -tolerance &&
+                rect.bottom <= viewportHeight + tolerance &&
+                rect.right <= viewportWidth + tolerance;
+        }, selector, VIEWPORT_TOLERANCE_PX);
     }
     // Type method
     async type(selector, text, options) {
@@ -334,16 +673,15 @@ export default class CdpPage extends EventEmitter {
     }
     // Wait for selector
     async waitForSelector(selector, options) {
-        const timeout = options?.timeout ?? 30000;
-        const pollingInterval = 100;
-        const maxAttempts = Math.ceil(timeout / pollingInterval);
+        const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
+        const maxAttempts = Math.ceil(timeout / POLLING_INTERVAL_MS);
         let attempts = 0;
         while (attempts < maxAttempts) {
             const exists = await this.elementExists(selector);
             if (exists) {
                 return;
             }
-            await new Promise((resolve) => setTimeout(resolve, pollingInterval));
+            await new Promise((resolve) => setTimeout(resolve, POLLING_INTERVAL_MS));
             attempts++;
         }
         throw new Error(`Timeout waiting for selector: ${selector}`);
@@ -652,6 +990,231 @@ export default class CdpPage extends EventEmitter {
             this.isReconnecting = false;
         }
     }
+    /**
+     * Selects one or more options from a select element or dropdown.
+     * Supports both regular select elements and virtualized dropdowns with hidden options.
+     *
+     * @param selector - The CSS selector for the select element or dropdown trigger
+     * @param targetSelector - CSS selector(s) for the option(s) to select. Can be a single selector or array of selectors
+     * @param options - Additional options for the selection
+     */
+    async selectOption(selector, targetSelector, options) {
+        await Promise.all([
+            this._enableDomain('DOM'),
+            this._enableDomain('Input'),
+        ]);
+        // DOM and Input domains are enabled and actively used in this method
+        const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
+        const force = options?.force ?? false;
+        const waitForOptions = options?.waitForOptions ?? true;
+        const maxScrollAttempts = options?.maxScrollAttempts ?? 10;
+        const optionSelector = options?.optionSelector;
+        const dropdownSelector = options?.dropdownSelector;
+        // Normalize target selectors to array
+        const targetSelectors = Array.isArray(targetSelector) ? targetSelector : [targetSelector];
+        // Wait for element to exist
+        await this.waitForSelector(selector, { timeout });
+        // Check if element is visible (unless force is true)
+        if (!force) {
+            const isVisible = await this._isElementVisible(selector);
+            if (!isVisible) {
+                throw new Error(`Element is not visible: ${selector}. Use force: true to bypass this check.`);
+            }
+        }
+        // Check if element is disabled (unless force is true)
+        if (!force) {
+            const isDisabled = await this.evaluate((sel) => {
+                const element = document.querySelector(sel);
+                return element?.hasAttribute('disabled') || element?.getAttribute('disabled') === 'true';
+            }, selector);
+            if (isDisabled) {
+                throw new Error(`Element is disabled: ${selector}. Use force: true to bypass this check.`);
+            }
+        }
+        // Scroll element into view if needed
+        await this._scrollElementIntoView(selector);
+        // Wait for scroll animations to complete
+        await new Promise(resolve => setTimeout(resolve, SCROLL_ANIMATION_DELAY_MS));
+        // Check if this is a regular select element
+        const isSelectElement = await this.evaluate((sel) => {
+            const element = document.querySelector(sel);
+            return element?.tagName === 'SELECT';
+        }, selector);
+        if (!isSelectElement) {
+            // For non-select elements, both dropdownSelector and optionSelector are required
+            if (!dropdownSelector) {
+                throw new Error(`Element at ${selector} is not a select element. For custom dropdowns, you must provide a dropdownSelector option.`);
+            }
+            if (!optionSelector) {
+                throw new Error(`Element at ${selector} is not a select element. For custom dropdowns, you must provide an optionSelector option.`);
+            }
+            // Handle custom dropdown
+            await this._handleCustomDropdown(selector, targetSelectors, {
+                timeout,
+                force,
+                waitForOptions,
+                maxScrollAttempts,
+                optionSelector,
+                dropdownSelector,
+            });
+        }
+        else {
+            // Handle regular select element - use 'option' as default
+            await this._handleRegularSelect(selector, targetSelectors, {
+                timeout,
+                force,
+                optionSelector: optionSelector ?? 'option',
+            });
+        }
+    }
+    /**
+     * Handles selection for regular HTML select elements
+     */
+    async _handleRegularSelect(selector, targetSelectors, _options) {
+        // Get option selector from options for HTML select element handling
+        const result = await this.evaluate((sel, targetSels) => {
+            const select = document.querySelector(sel);
+            if (!select) {
+                throw new Error(`Select element not found: ${sel}`);
+            }
+            // Check if multiple selection is allowed
+            if (!select.multiple && targetSels.length > 1) {
+                throw new Error(`Select element does not support multiple selection. Found ${targetSels.length} selectors but multiple is false.`);
+            }
+            // Clear previous selections
+            if (select.multiple) {
+                Array.from(select.options).forEach(option => {
+                    option.selected = false;
+                });
+            }
+            let foundCount = 0;
+            const foundSelectors = [];
+            // Select the options by CSS selector
+            for (const targetSelector of targetSels) {
+                let optionFound = false;
+                // Find option by CSS selector
+                const option = select.querySelector(targetSelector);
+                if (option) {
+                    option.selected = true;
+                    optionFound = true;
+                    foundSelectors.push(targetSelector);
+                }
+                if (optionFound) {
+                    foundCount++;
+                }
+            }
+            // Trigger change event
+            const event = new Event('change', { bubbles: true });
+            select.dispatchEvent(event);
+            return { foundCount, foundSelectors, totalOptions: select.options.length };
+        }, selector, targetSelectors);
+        if (result.foundCount === 0) {
+            throw new Error(`No options found for selectors: ${targetSelectors.join(', ')}. Available options: ${result.totalOptions}`);
+        }
+        if (result.foundCount < targetSelectors.length) {
+            const missingSelectors = targetSelectors.filter(s => !result.foundSelectors.includes(s));
+            throw new Error(`Some selectors not found: ${missingSelectors.join(', ')}. Found: ${result.foundSelectors.join(', ')}`);
+        }
+    }
+    /**
+     * Handles selection for custom dropdown elements
+     */
+    async _handleCustomDropdown(selector, targetSelectors, options) {
+        const { timeout, force, waitForOptions, maxScrollAttempts, optionSelector, dropdownSelector: dropdownSel, dropdownOpenDelay = DROPDOWN_OPEN_DELAY_MS } = options;
+        // Click to open the dropdown
+        await this.click(selector, { force });
+        // Wait for dropdown to open
+        await new Promise(resolve => setTimeout(resolve, dropdownOpenDelay));
+        // Use the provided dropdown selector (required for custom dropdowns)
+        const dropdownContainer = dropdownSel;
+        // Wait for dropdown to be visible
+        if (waitForOptions) {
+            await this.waitForSelector(dropdownContainer, { timeout });
+        }
+        // Select each target selector
+        for (const targetSelector of targetSelectors) {
+            await this._selectOptionFromDropdown(dropdownContainer, targetSelector, {
+                timeout,
+                force,
+                maxScrollAttempts,
+                optionSelector,
+            });
+        }
+    }
+    /**
+     * Selects a single option from a dropdown container, handling virtualized lists
+     */
+    async _selectOptionFromDropdown(dropdownSelector, targetSelector, dropdownOptions) {
+        const { timeout, maxScrollAttempts, optionSelector } = dropdownOptions;
+        const startTime = Date.now();
+        let scrollAttempts = 0;
+        let optionFound = false;
+        while (scrollAttempts < maxScrollAttempts && !optionFound && (Date.now() - startTime) < timeout) {
+            // Try to find and click the option
+            const result = await this.evaluate((dropdownSel, targetSel, optSel) => {
+                const dropdown = document.querySelector(dropdownSel);
+                if (!dropdown)
+                    return { found: false, needsScroll: false };
+                // Look for option elements using the provided selector
+                const options = Array.from(dropdown.querySelectorAll(optSel));
+                let targetOption = null;
+                for (const option of options) {
+                    // Check if the option matches the target selector
+                    if (option.matches(targetSel)) {
+                        targetOption = option;
+                        break;
+                    }
+                }
+                if (!targetOption) {
+                    // Check if we need to scroll to find more options
+                    const isScrollable = dropdown.scrollHeight > dropdown.clientHeight;
+                    const isAtBottom = dropdown.scrollTop + dropdown.clientHeight >= dropdown.scrollHeight - 1;
+                    return { found: false, needsScroll: isScrollable && !isAtBottom };
+                }
+                // Check if option is visible
+                const rect = targetOption.getBoundingClientRect();
+                const dropdownRect = dropdown.getBoundingClientRect();
+                const isVisible = rect.top >= dropdownRect.top &&
+                    rect.bottom <= dropdownRect.bottom &&
+                    rect.left >= dropdownRect.left &&
+                    rect.right <= dropdownRect.right;
+                if (!isVisible) {
+                    // Scroll to make the option visible
+                    targetOption.scrollIntoView({ block: 'center', behavior: 'smooth' });
+                    return { found: false, needsScroll: false, scrolled: true };
+                }
+                // Click the option
+                targetOption.click();
+                return { found: true, needsScroll: false };
+            }, dropdownSelector, targetSelector, optionSelector);
+            if (result.found) {
+                optionFound = true;
+                break;
+            }
+            if (result.needsScroll) {
+                // Scroll down to load more options
+                await this.evaluate((dropdownSel) => {
+                    const dropdown = document.querySelector(dropdownSel);
+                    if (dropdown) {
+                        dropdown.scrollTop += dropdown.clientHeight * 0.8;
+                    }
+                }, dropdownSelector);
+                scrollAttempts++;
+                await new Promise(resolve => setTimeout(resolve, OPTION_LOAD_DELAY_MS)); // Wait for new options to load
+            }
+            else if (result.scrolled) {
+                // Option was scrolled into view, try clicking it now
+                await new Promise(resolve => setTimeout(resolve, SCROLL_COMPLETE_DELAY_MS)); // Wait for scroll to complete
+            }
+            else {
+                // No more scrolling needed, option not found
+                break;
+            }
+        }
+        if (!optionFound) {
+            throw new Error(`Option "${targetSelector}" not found`);
+        }
+    }
     /**
      * Checks if the element specified by selector is visible (not display:none and not visibility:hidden).
      * The selector should be the root item which can be hidden, otherwise this function could return a false positive.