jumpy-lion 0.1.6-beta.9 → 1.0.0-beta.4

package/dist/input/dropdown-selector.js

@@ -0,0 +1,394 @@
+/**
+ * DropdownSelector - the deep module beside ElementTarget that owns the whole
+ * select/dropdown protocol: native `<select>` handling, custom-dropdown
+ * trigger detection, idempotent open (triggers TOGGLE, so blind clicks are
+ * racy), and option selection with bounded scrolling for virtualized lists
+ * and bounded polling for late-rendering options.
+ *
+ * Talks to the page only through the narrow {@link DropdownSelectorPort}
+ * (ElementTargetPort + waitForSelector + the loose visibility check), so the
+ * protocol is unit-testable with a scripted port. ElementTarget decides WHERE
+ * and WHEN for coordinate clicks; DropdownSelector orchestrates the
+ * select-specific sequence on top of the same port.
+ */
+import { humanizedClickTarget } from './element-target.js';
+export const SCROLL_ANIMATION_DELAY_MS = 200; // ms to wait for scroll animations
+export const OPTION_LOAD_DELAY_MS = 300; // ms to wait for new options to load in dropdowns
+export const DROPDOWN_OPEN_DELAY_MS = 300; // ms to wait for dropdown to open
+export const DEFAULT_SELECT_TIMEOUT_MS = 30000;
+export class DropdownSelector {
+    constructor(port, elements) {
+        Object.defineProperty(this, "port", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: port
+        });
+        Object.defineProperty(this, "elements", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: elements
+        });
+    }
+    /**
+     * Selects one or more options from a select element or dropdown.
+     *
+     * Automatically handles both regular HTML select elements and custom dropdowns:
+     * - For <select> elements: Directly selects options within the select
+     * - For custom dropdowns: Automatically detects and clicks triggers to open dropdowns,
+     *   then selects the specified options with intelligent scrolling for virtualized lists
+     */
+    async selectOption(dropdownSelector, optionSelector, options) {
+        const timeout = options?.timeout ?? DEFAULT_SELECT_TIMEOUT_MS;
+        const force = options?.force ?? false;
+        const waitForOptions = options?.waitForOptions ?? true;
+        const maxScrollAttempts = options?.maxScrollAttempts ?? 10;
+        // Normalize target selectors to array
+        const targetSelectors = Array.isArray(optionSelector) ? optionSelector : [optionSelector];
+        // Wait for dropdown element to exist
+        await this.port.waitForSelector(dropdownSelector, { timeout });
+        // Check if this is a regular select element
+        const isSelectElement = await this.port.evaluate((sel) => {
+            const element = document.querySelector(sel);
+            return element?.tagName === 'SELECT';
+        }, dropdownSelector);
+        // For regular select elements, do visibility and disabled checks upfront
+        if (isSelectElement) {
+            // Check if element is visible (unless force is true)
+            if (!force) {
+                const isVisible = await this.elements.isVisible(dropdownSelector);
+                if (!isVisible) {
+                    throw new Error(`Element is not visible: ${dropdownSelector}. Use force: true to bypass this check.`);
+                }
+            }
+            // Check if element is disabled (unless force is true)
+            if (!force) {
+                const isDisabled = await this.port.evaluate((sel) => {
+                    const element = document.querySelector(sel);
+                    return element?.hasAttribute('disabled') || element?.getAttribute('disabled') === 'true';
+                }, dropdownSelector);
+                if (isDisabled) {
+                    throw new Error(`Element is disabled: ${dropdownSelector}. Use force: true to bypass this check.`);
+                }
+            }
+            // Scroll element into view if needed
+            await this.elements.scrollIntoView(dropdownSelector);
+            // Wait for scroll animations to complete
+            await new Promise(resolve => setTimeout(resolve, SCROLL_ANIMATION_DELAY_MS));
+            await this._handleRegularSelect(dropdownSelector, targetSelectors);
+        }
+        else {
+            // Handle custom dropdown - the dropdownSelector is the container
+            await this._handleCustomDropdown(dropdownSelector, targetSelectors, {
+                timeout,
+                force,
+                waitForOptions,
+                maxScrollAttempts,
+            });
+        }
+    }
+    /**
+     * Turn an in-page {@link ClickHandoff} into an actual click, and report
+     * whether the element ended up clicked.
+     *
+     * Preferred path: a measured rect -> a trusted CDP Input click at a point
+     * inside it (randomized under mouse humanization, exact centre otherwise, so
+     * deterministic tests are unaffected). The in-page synthetic fallback is
+     * already-done work and simply reports success.
+     */
+    async _completeHandoff(handoff) {
+        if (!handoff?.found)
+            return false;
+        if (handoff.clickedInPage)
+            return true;
+        const { rect } = handoff;
+        // The in-page step already clipped the box to the viewport, so any
+        // remaining area is a valid Input.dispatchMouseEvent target. A zero-area
+        // box means nothing visible was left to aim at.
+        if (!rect || rect.width <= 0 || rect.height <= 0) {
+            return false;
+        }
+        const point = this.port.humanization().mouse
+            ? humanizedClickTarget(rect)
+            : { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+        await this.port.clickAt(point.x, point.y);
+        return true;
+    }
+    /**
+     * Handles selection for regular HTML select elements
+     */
+    async _handleRegularSelect(selectSelector, targetSelectors) {
+        const result = await this.port.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 within the select element
+                const option = select.querySelector(targetSelector);
+                if (option) {
+                    option.selected = true;
+                    optionFound = true;
+                    foundSelectors.push(targetSelector);
+                }
+                if (optionFound) {
+                    foundCount++;
+                }
+            }
+            // Fire `input` then `change`, matching the real browser event order
+            // for a user selection. React/Vue controlled <select>s listen for
+            // `input`; dispatching only `change` desyncs their state. Only when
+            // something was actually selected - firing them after a failed
+            // lookup told the page the value changed when it had not, and the
+            // driver then threw anyway.
+            if (foundCount > 0) {
+                select.dispatchEvent(new Event('input', { bubbles: true }));
+                select.dispatchEvent(new Event('change', { bubbles: true }));
+            }
+            return { foundCount, foundSelectors, totalOptions: select.options.length };
+        }, selectSelector, targetSelectors);
+        // A closed page resolves evaluate() to undefined.
+        if (!result) {
+            throw new Error(`Could not read <select> state for ${selectSelector}: the page is closed.`);
+        }
+        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.
+     * Automatically detects and clicks triggers using multiple strategies:
+     * - Common trigger patterns ([aria-haspopup], .dropdown-trigger, etc.)
+     * - Previous sibling elements
+     * - ID pattern matching (menu → trigger)
+     */
+    async _handleCustomDropdown(dropdownContainer, targetSelectors, options) {
+        const { timeout, force, waitForOptions, maxScrollAttempts, dropdownOpenDelay = DROPDOWN_OPEN_DELAY_MS } = options;
+        // Locate the dropdown's trigger and click it (through CDP Input) to
+        // toggle the menu open. Returns true when a trigger was found and
+        // clicked. Used by the idempotent open loop below (only invoked while
+        // the menu is still closed, so the toggle never accidentally re-closes
+        // an already-open menu).
+        const clickTrigger = async () => {
+            const handoff = await this.port.evaluate((containerSel) => {
+                const container = document.querySelector(containerSel);
+                if (!container)
+                    return { found: false };
+                // Scroll the trigger into view, then measure it CLIPPED to the
+                // viewport so the driver can dispatch a trusted click at a point
+                // that is genuinely visible. Only an element with no visible
+                // area at all falls back to a synthetic click.
+                // NOTE: byte-identical to the option lookup's copy below. It
+                // cannot be hoisted - this function is shipped to the page via
+                // Function.toString() and so may not reference module scope.
+                const handOff = (el) => {
+                    el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'auto' });
+                    const r = el.getBoundingClientRect();
+                    const left = Math.max(r.left, 0);
+                    const top = Math.max(r.top, 0);
+                    const right = Math.min(r.right, window.innerWidth);
+                    const bottom = Math.min(r.bottom, window.innerHeight);
+                    if (right - left > 0 && bottom - top > 0) {
+                        return {
+                            found: true,
+                            rect: { x: left, y: top, width: right - left, height: bottom - top },
+                        };
+                    }
+                    el.click();
+                    return { found: true, clickedInPage: true };
+                };
+                // Strategy 1: Look for sibling trigger elements with common patterns
+                const parent = container.parentElement;
+                if (parent) {
+                    const triggers = parent.querySelectorAll('[role="button"], button, [data-toggle], [aria-haspopup], .dropdown-trigger, .select-trigger');
+                    for (const trigger of triggers) {
+                        if (trigger !== container) {
+                            return handOff(trigger);
+                        }
+                    }
+                    // Strategy 2: Look for previous sibling that might be the trigger
+                    const prevSibling = container.previousElementSibling;
+                    if (prevSibling && prevSibling.tagName !== 'LABEL') {
+                        return handOff(prevSibling);
+                    }
+                }
+                // Strategy 3: Look for element with similar ID (e.g., menu -> trigger)
+                const containerId = container.id;
+                if (containerId) {
+                    const triggerPatterns = [
+                        containerId.replace('menu', 'trigger').replace('dropdown', 'trigger'),
+                        containerId.replace('-menu', '-trigger'),
+                        containerId.replace('_menu', '_trigger'),
+                        `${containerId}-trigger`,
+                        `trigger-${containerId}`,
+                    ];
+                    for (const triggerId of triggerPatterns) {
+                        const trigger = document.getElementById(triggerId);
+                        if (trigger && trigger !== container) {
+                            return handOff(trigger);
+                        }
+                    }
+                }
+                return { found: false };
+            }, dropdownContainer);
+            return await this._completeHandoff(handoff);
+        };
+        if (waitForOptions) {
+            await this.port.waitForSelector(dropdownContainer, { timeout });
+        }
+        // Idempotent open: dropdown triggers usually TOGGLE on click, so a
+        // single blind click is racy - if the menu was already open it closes
+        // it, and a timing hiccup can leave it closed while the option lookup
+        // below silently fails. Instead, only click while the menu is closed
+        // and re-check until it is actually visible (or the budget runs out).
+        if (!force) {
+            // Use the LOOSE display/visibility check, NOT the strict
+            // ElementTarget.isVisible: a menu opened with a CSS opacity/transform
+            // fade-in reads opacity:0 for the first frames, which the strict
+            // check counts as "not visible" - that would make the loop re-click
+            // the trigger and TOGGLE the just-opened menu shut. `display: block`
+            // is the real open signal.
+            const OPEN_ATTEMPTS = 5;
+            let opened = await this.port.isLooselyVisible(dropdownContainer);
+            for (let attempt = 0; attempt < OPEN_ATTEMPTS && !opened; attempt++) {
+                await clickTrigger();
+                await new Promise(resolve => setTimeout(resolve, dropdownOpenDelay));
+                opened = await this.port.isLooselyVisible(dropdownContainer);
+            }
+            if (!opened) {
+                throw new Error(`Dropdown container is not visible after trigger click: ${dropdownContainer}. Use force: true to bypass this check.`);
+            }
+        }
+        else {
+            // Force path: open once, best-effort.
+            await clickTrigger();
+            await new Promise(resolve => setTimeout(resolve, dropdownOpenDelay));
+        }
+        // Select each target selector
+        for (const targetSelector of targetSelectors) {
+            await this._selectOptionFromDropdown(dropdownContainer, targetSelector, {
+                timeout,
+                maxScrollAttempts,
+            });
+        }
+    }
+    /**
+     * Selects a single option from a dropdown container.
+     * Handles virtualized lists with intelligent scrolling to find options that may not be initially visible.
+     */
+    async _selectOptionFromDropdown(dropdownSelector, targetSelector, dropdownOptions) {
+        const { timeout, maxScrollAttempts } = dropdownOptions;
+        const startTime = Date.now();
+        let scrollAttempts = 0;
+        let optionFound = false;
+        // Custom dropdowns frequently render their options asynchronously after
+        // the trigger click, so the very first lookup can miss an option that
+        // appears a moment later. Poll a bounded number of times before
+        // concluding the option is genuinely absent - without this grace the
+        // selection is racy and fails intermittently on slower runs.
+        let notFoundPolls = 0;
+        const MAX_NOT_FOUND_POLLS = 10;
+        while (scrollAttempts < maxScrollAttempts && !optionFound && (Date.now() - startTime) < timeout) {
+            // Try to find and click the option; if it is absent but the list is
+            // still scrollable, scroll down within the SAME evaluate so a single
+            // round-trip covers both the lookup and the scroll for this
+            // iteration. The effective sequence is unchanged
+            // (find → scroll → wait → find → …); only the extra CDP round-trip
+            // that used to do the scroll separately is removed.
+            const result = await this.port.evaluate((dropdownSel, targetSel) => {
+                const dropdown = document.querySelector(dropdownSel);
+                if (!dropdown)
+                    return { found: false, scrolled: false };
+                // Try to find the target element directly first
+                const targetOption = dropdown.querySelector(targetSel);
+                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;
+                    if (isScrollable && !isAtBottom) {
+                        // Scroll down to load more options (same amount as before).
+                        dropdown.scrollTop += dropdown.clientHeight * 0.8;
+                        return { found: false, scrolled: true };
+                    }
+                    return { found: false, scrolled: false };
+                }
+                // The option exists in the DOM - center it (instant scroll)
+                // and measure it CLIPPED to the viewport, so the driver can
+                // dispatch a TRUSTED click at a genuinely visible point. We
+                // deliberately do NOT gate on a rect-within-rect visibility
+                // test: that races layout / open-transitions, which made the
+                // loop spin until the timeout and intermittently throw
+                // "not found".
+                // NOTE: byte-identical to the trigger lookup's copy above.
+                // It cannot be hoisted - this function is shipped to the page
+                // via Function.toString() and so may not reference module scope.
+                const handOff = (el) => {
+                    el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'auto' });
+                    const r = el.getBoundingClientRect();
+                    const left = Math.max(r.left, 0);
+                    const top = Math.max(r.top, 0);
+                    const right = Math.min(r.right, window.innerWidth);
+                    const bottom = Math.min(r.bottom, window.innerHeight);
+                    if (right - left > 0 && bottom - top > 0) {
+                        return {
+                            found: true,
+                            rect: { x: left, y: top, width: right - left, height: bottom - top },
+                        };
+                    }
+                    el.click();
+                    return { found: true, clickedInPage: true };
+                };
+                return { ...handOff(targetOption), scrolled: false };
+            }, dropdownSelector, targetSelector);
+            // A closed page resolves evaluate() to undefined; treat it as "no
+            // result this round" rather than dereferencing it.
+            if (!result)
+                break;
+            if (result.found) {
+                optionFound = await this._completeHandoff(result);
+                if (optionFound)
+                    break;
+                // Located but unclickable (no geometry and no in-page fallback):
+                // fall through to the not-found polling below.
+            }
+            if (result.scrolled) {
+                scrollAttempts++;
+                await new Promise(resolve => setTimeout(resolve, OPTION_LOAD_DELAY_MS)); // Wait for new options to load
+            }
+            else {
+                // Option not present and dropdown not scrollable - it may still
+                // be rendering after the trigger click. Poll a bounded number of
+                // times before giving up so a late-rendering option is found,
+                // without burning the full timeout when it is genuinely absent.
+                notFoundPolls++;
+                if (notFoundPolls >= MAX_NOT_FOUND_POLLS) {
+                    break;
+                }
+                await new Promise(resolve => setTimeout(resolve, OPTION_LOAD_DELAY_MS));
+            }
+        }
+        if (!optionFound) {
+            throw new Error(`Option "${targetSelector}" not found in dropdown "${dropdownSelector}"`);
+        }
+    }
+}
+//# sourceMappingURL=dropdown-selector.js.map

package/dist/input/dropdown-selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dropdown-selector.js","sourceRoot":"","sources":["../../src/input/dropdown-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,oBAAoB,EAA+D,MAAM,qBAAqB,CAAC;AAExH,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC,CAAC,mCAAmC;AACjF,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC,CAAC,kDAAkD;AAC3F,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC,CAAC,kCAAkC;AAC7E,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC;AA8E/C,MAAM,OAAO,gBAAgB;IACzB,YACqB,IAA0B,EAC1B,QAAuB;QADxC;;;;mBAAiB,IAAI;WAAsB;QAC3C;;;;mBAAiB,QAAQ;WAAe;IACzC,CAAC;IAEJ;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CACd,gBAAwB,EACxB,cAAiC,EACjC,OAA6B;QAE7B,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,yBAAyB,CAAC;QAC9D,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,KAAK,CAAC;QACtC,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;QACvD,MAAM,iBAAiB,GAAG,OAAO,EAAE,iBAAiB,IAAI,EAAE,CAAC;QAE3D,sCAAsC;QACtC,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;QAE1F,qCAAqC;QACrC,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,gBAAgB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAE/D,4CAA4C;QAC5C,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAU,CAAC,GAAW,EAAE,EAAE;YACtE,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAgB,CAAC;YAC3D,OAAO,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC;QACzC,CAAC,EAAE,gBAAgB,CAAC,CAAC;QAErB,yEAAyE;QACzE,IAAI,eAAe,EAAE,CAAC;YAClB,qDAAqD;YACrD,IAAI,CAAC,KAAK,EAAE,CAAC;gBACT,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;gBAClE,IAAI,CAAC,SAAS,EAAE,CAAC;oBACb,MAAM,IAAI,KAAK,CAAC,2BAA2B,gBAAgB,yCAAyC,CAAC,CAAC;gBAC1G,CAAC;YACL,CAAC;YAED,sDAAsD;YACtD,IAAI,CAAC,KAAK,EAAE,CAAC;gBACT,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAU,CAAC,GAAW,EAAE,EAAE;oBACjE,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAgB,CAAC;oBAC3D,OAAO,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,IAAI,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,KAAK,MAAM,CAAC;gBAC7F,CAAC,EAAE,gBAAgB,CAAC,CAAC;gBACrB,IAAI,UAAU,EAAE,CAAC;oBACb,MAAM,IAAI,KAAK,CAAC,wBAAwB,gBAAgB,yCAAyC,CAAC,CAAC;gBACvG,CAAC;YACL,CAAC;YAED,qCAAqC;YACrC,MAAM,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC;YAErD,yCAAyC;YACzC,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC;YAE7E,MAAM,IAAI,CAAC,oBAAoB,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;QACvE,CAAC;aAAM,CAAC;YACJ,iEAAiE;YACjE,MAAM,IAAI,CAAC,qBAAqB,CAAC,gBAAgB,EAAE,eAAe,EAAE;gBAChE,OAAO;gBACP,KAAK;gBACL,cAAc;gBACd,iBAAiB;aACpB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACK,KAAK,CAAC,gBAAgB,CAAC,OAAwC;QACnE,IAAI,CAAC,OAAO,EAAE,KAAK;YAAE,OAAO,KAAK,CAAC;QAClC,IAAI,OAAO,CAAC,aAAa;YAAE,OAAO,IAAI,CAAC;QAEvC,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;QACzB,mEAAmE;QACnE,yEAAyE;QACzE,gDAAgD;QAChD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YAC/C,OAAO,KAAK,CAAC;QACjB,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,KAAK;YACxC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC;YAC5B,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,oBAAoB,CAC9B,cAAsB,EACtB,eAAyB;QAEzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAI7B,CAAC,GAAW,EAAE,UAAoB,EAAE,EAAE;YAC5C,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAsB,CAAC;YAChE,IAAI,CAAC,MAAM,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,6BAA6B,GAAG,EAAE,CAAC,CAAC;YACxD,CAAC;YAED,yCAAyC;YACzC,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5C,MAAM,IAAI,KAAK,CAAC,6DAA6D,UAAU,CAAC,MAAM,mCAAmC,CAAC,CAAC;YACvI,CAAC;YAED,4BAA4B;YAC5B,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBAClB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;oBACxC,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC;gBAC5B,CAAC,CAAC,CAAC;YACP,CAAC;YAED,IAAI,UAAU,GAAG,CAAC,CAAC;YACnB,MAAM,cAAc,GAAa,EAAE,CAAC;YAEpC,qCAAqC;YACrC,KAAK,MAAM,cAAc,IAAI,UAAU,EAAE,CAAC;gBACtC,IAAI,WAAW,GAAG,KAAK,CAAC;gBAExB,wDAAwD;gBACxD,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,cAAc,CAAsB,CAAC;gBAEzE,IAAI,MAAM,EAAE,CAAC;oBACT,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC;oBACvB,WAAW,GAAG,IAAI,CAAC;oBACnB,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;gBACxC,CAAC;gBAED,IAAI,WAAW,EAAE,CAAC;oBACd,UAAU,EAAE,CAAC;gBACjB,CAAC;YACL,CAAC;YAED,oEAAoE;YACpE,kEAAkE;YAClE,oEAAoE;YACpE,+DAA+D;YAC/D,kEAAkE;YAClE,4BAA4B;YAC5B,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;gBACjB,MAAM,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;gBAC5D,MAAM,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACjE,CAAC;YAED,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAC/E,CAAC,EAAE,cAAc,EAAE,eAAe,CAAC,CAAC;QAEpC,kDAAkD;QAClD,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,qCAAqC,cAAc,uBAAuB,CAAC,CAAC;QAChG,CAAC;QAED,IAAI,MAAM,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,mCAAmC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,wBAAwB,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QAChI,CAAC;QAED,IAAI,MAAM,CAAC,UAAU,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;YAC7C,MAAM,gBAAgB,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YACzF,MAAM,IAAI,KAAK,CAAC,6BAA6B,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC5H,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,qBAAqB,CAC/B,iBAAyB,EACzB,eAAyB,EACzB,OAAwB;QAExB,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,GAAG,sBAAsB,EAAE,GAAG,OAAO,CAAC;QAElH,oEAAoE;QACpE,kEAAkE;QAClE,sEAAsE;QACtE,uEAAuE;QACvE,yBAAyB;QACzB,MAAM,YAAY,GAAG,KAAK,IAAsB,EAAE;YAC9C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAsB,CAAC,YAAoB,EAAE,EAAE;gBACnF,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAgB,CAAC;gBACtE,IAAI,CAAC,SAAS;oBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBAExC,+DAA+D;gBAC/D,iEAAiE;gBACjE,6DAA6D;gBAC7D,+CAA+C;gBAC/C,6DAA6D;gBAC7D,+DAA+D;gBAC/D,6DAA6D;gBAC7D,MAAM,OAAO,GAAG,CAAC,EAAe,EAAE,EAAE;oBAChC,EAAE,CAAC,cAAc,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;oBAC3E,MAAM,CAAC,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;oBACrC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;oBACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;oBAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;oBACnD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;oBACtD,IAAI,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC;wBACvC,OAAO;4BACH,KAAK,EAAE,IAAI;4BACX,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE;yBACvE,CAAC;oBACN,CAAC;oBACD,EAAE,CAAC,KAAK,EAAE,CAAC;oBACX,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;gBAChD,CAAC,CAAC;gBAEF,qEAAqE;gBACrE,MAAM,MAAM,GAAG,SAAS,CAAC,aAAa,CAAC;gBACvC,IAAI,MAAM,EAAE,CAAC;oBACT,MAAM,QAAQ,GAAG,MAAM,CAAC,gBAAgB,CAAC,6FAA6F,CAAC,CAAC;oBACxI,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;wBAC7B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;4BACxB,OAAO,OAAO,CAAC,OAAsB,CAAC,CAAC;wBAC3C,CAAC;oBACL,CAAC;oBAED,kEAAkE;oBAClE,MAAM,WAAW,GAAG,SAAS,CAAC,sBAAsB,CAAC;oBACrD,IAAI,WAAW,IAAI,WAAW,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;wBACjD,OAAO,OAAO,CAAC,WAA0B,CAAC,CAAC;oBAC/C,CAAC;gBACL,CAAC;gBAED,uEAAuE;gBACvE,MAAM,WAAW,GAAG,SAAS,CAAC,EAAE,CAAC;gBACjC,IAAI,WAAW,EAAE,CAAC;oBACd,MAAM,eAAe,GAAG;wBACpB,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC;wBACrE,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC;wBACxC,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC;wBACxC,GAAG,WAAW,UAAU;wBACxB,WAAW,WAAW,EAAE;qBAC3B,CAAC;oBAEF,KAAK,MAAM,SAAS,IAAI,eAAe,EAAE,CAAC;wBACtC,MAAM,OAAO,GAAG,QAAQ,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;wBACnD,IAAI,OAAO,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;4BACnC,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;wBAC5B,CAAC;oBACL,CAAC;gBACL,CAAC;gBAED,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAC5B,CAAC,EAAE,iBAAiB,CAAC,CAAC;YAEtB,OAAO,MAAM,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAChD,CAAC,CAAC;QAEF,IAAI,cAAc,EAAE,CAAC;YACjB,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,mEAAmE;QACnE,sEAAsE;QACtE,sEAAsE;QACtE,qEAAqE;QACrE,sEAAsE;QACtE,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,yDAAyD;YACzD,sEAAsE;YACtE,iEAAiE;YACjE,oEAAoE;YACpE,qEAAqE;YACrE,2BAA2B;YAC3B,MAAM,aAAa,GAAG,CAAC,CAAC;YACxB,IAAI,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;YACjE,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,aAAa,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;gBAClE,MAAM,YAAY,EAAE,CAAC;gBACrB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;gBACrE,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;YACjE,CAAC;YACD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,0DAA0D,iBAAiB,yCAAyC,CAAC,CAAC;YAC1I,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,sCAAsC;YACtC,MAAM,YAAY,EAAE,CAAC;YACrB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;QACzE,CAAC;QAED,8BAA8B;QAC9B,KAAK,MAAM,cAAc,IAAI,eAAe,EAAE,CAAC;YAC3C,MAAM,IAAI,CAAC,yBAAyB,CAAC,iBAAiB,EAAE,cAAc,EAAE;gBACpE,OAAO;gBACP,iBAAiB;aACpB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,yBAAyB,CACnC,gBAAwB,EACxB,cAAsB,EACtB,eAAyC;QAEzC,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,GAAG,eAAe,CAAC;QACvD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,IAAI,cAAc,GAAG,CAAC,CAAC;QACvB,IAAI,WAAW,GAAG,KAAK,CAAC;QACxB,wEAAwE;QACxE,sEAAsE;QACtE,gEAAgE;QAChE,qEAAqE;QACrE,6DAA6D;QAC7D,IAAI,aAAa,GAAG,CAAC,CAAC;QACtB,MAAM,mBAAmB,GAAG,EAAE,CAAC;QAE/B,OAAO,cAAc,GAAG,iBAAiB,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,OAAO,EAAE,CAAC;YAC9F,oEAAoE;YACpE,qEAAqE;YACrE,4DAA4D;YAC5D,iDAAiD;YACjD,mEAAmE;YACnE,oDAAoD;YACpD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CACnC,CAAC,WAAmB,EAAE,SAAiB,EAAE,EAAE;gBACvC,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC,WAAW,CAAgB,CAAC;gBACpE,IAAI,CAAC,QAAQ;oBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;gBAExD,gDAAgD;gBAChD,MAAM,YAAY,GAAG,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAgB,CAAC;gBAEtE,IAAI,CAAC,YAAY,EAAE,CAAC;oBAChB,kDAAkD;oBAClD,MAAM,YAAY,GAAG,QAAQ,CAAC,YAAY,GAAG,QAAQ,CAAC,YAAY,CAAC;oBACnE,MAAM,UAAU,GAAG,QAAQ,CAAC,SAAS,GAAG,QAAQ,CAAC,YAAY,IAAI,QAAQ,CAAC,YAAY,GAAG,CAAC,CAAC;oBAE3F,IAAI,YAAY,IAAI,CAAC,UAAU,EAAE,CAAC;wBAC9B,4DAA4D;wBAC5D,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,YAAY,GAAG,GAAG,CAAC;wBAClD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;oBAC5C,CAAC;oBAED,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;gBAC7C,CAAC;gBAED,4DAA4D;gBAC5D,4DAA4D;gBAC5D,4DAA4D;gBAC5D,4DAA4D;gBAC5D,6DAA6D;gBAC7D,uDAAuD;gBACvD,eAAe;gBACf,2DAA2D;gBAC3D,8DAA8D;gBAC9D,iEAAiE;gBACjE,MAAM,OAAO,GAAG,CAAC,EAAe,EAAE,EAAE;oBAChC,EAAE,CAAC,cAAc,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;oBAC3E,MAAM,CAAC,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;oBACrC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;oBACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;oBAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;oBACnD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;oBACtD,IAAI,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC;wBACvC,OAAO;4BACH,KAAK,EAAE,IAAI;4BACX,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE;yBACvE,CAAC;oBACN,CAAC;oBACD,EAAE,CAAC,KAAK,EAAE,CAAC;oBACX,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;gBAChD,CAAC,CAAC;gBACF,OAAO,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YACzD,CAAC,EACD,gBAAgB,EAChB,cAAc,CACjB,CAAC;YAEF,kEAAkE;YAClE,mDAAmD;YACnD,IAAI,CAAC,MAAM;gBAAE,MAAM;YAEnB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACf,WAAW,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;gBAClD,IAAI,WAAW;oBAAE,MAAM;gBACvB,iEAAiE;gBACjE,+CAA+C;YACnD,CAAC;YAED,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBAClB,cAAc,EAAE,CAAC;gBACjB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC,+BAA+B;YAC5G,CAAC;iBAAM,CAAC;gBACJ,gEAAgE;gBAChE,iEAAiE;gBACjE,8DAA8D;gBAC9D,gEAAgE;gBAChE,aAAa,EAAE,CAAC;gBAChB,IAAI,aAAa,IAAI,mBAAmB,EAAE,CAAC;oBACvC,MAAM;gBACV,CAAC;gBACD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC;YAC5E,CAAC;QACL,CAAC;QAED,IAAI,CAAC,WAAW,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,WAAW,cAAc,4BAA4B,gBAAgB,GAAG,CAAC,CAAC;QAC9F,CAAC;IACL,CAAC;CACJ"}

package/dist/input/element-target.d.ts

@@ -0,0 +1,152 @@
+/**
+ * ElementTarget - the deep module that turns a CSS selector into a stable,
+ * in-viewport coordinate target (or a typed failure: not found, invisible,
+ * unclickable, no box model, out of viewport).
+ *
+ * Sits beside InputEmulator: ElementTarget decides WHERE and WHEN to dispatch
+ * (geometry, visibility, scroll, position stabilization); InputEmulator
+ * decides HOW (paths, cadence, transport events). It talks to the page only
+ * through the narrow ElementTargetPort, so the whole acquire-protocol is
+ * unit-testable with a scripted port - same pattern as InputTransport's
+ * recording adapter.
+ */
+export declare const HUMAN_DELAY_MS = 200;
+export declare const POSITION_STABILITY_TIMEOUT_MS = 2000;
+export declare const POSITION_CHECK_INTERVAL_MS = 100;
+export declare const POSITION_STABILITY_THRESHOLD = 3;
+export declare const POSITION_TOLERANCE_PX = 1;
+export declare const VIEWPORT_TOLERANCE_PX = 50;
+/** An axis-aligned content box in viewport CSS pixels - the click surface. */
+export interface ContentBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Pick a click target inside an element's content box. Real users do NOT
+ * click the exact mathematical center - eye-tracking studies cluster
+ * clicks in the 30-70% range of each axis. Behavioral ML on click landing
+ * distributions (Cloudflare Turnstile 2025+, HUMAN Bot Defender) flags
+ * sessions whose clicks all hit pixel-perfect centers.
+ *
+ * Takes the axis-aligned {@link ContentBox} directly. The previous 8-element
+ * positional quad [x0,y0,...x3,y3] was synthesized from `getBoundingClientRect`
+ * (already axis-aligned) only to be reduced back via min/max over corners - a
+ * no-op for an axis-aligned box, so the box is passed straight through now.
+ */
+export declare function humanizedClickTarget(box: ContentBox): {
+    x: number;
+    y: number;
+};
+export interface ElementInfo {
+    nodeId: number;
+    boundingBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    isVisible: boolean;
+    isClickable: boolean;
+}
+/** One-shot existence + visibility + clickability result from {@link probeElement}. */
+export interface ElementProbe {
+    found: boolean;
+    isVisible: boolean;
+    isClickable: boolean;
+    boundingBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * The narrow set of page capabilities ElementTarget consumes. The production
+ * adapter is built by CdpPage over its CDP client; tests supply a scripted
+ * port.
+ */
+export interface ElementTargetPort {
+    evaluate<T>(pageFunction: Function | string, ...args: any[]): Promise<T>;
+    /** Humanized scroll-to-element (curved wheel events); may throw on hidden nodes. */
+    humanScrollToElement(selector: string): Promise<void>;
+    /** Live humanization toggles - read at call time, not construction time. */
+    humanization(): {
+        mouse: boolean;
+        scroll: boolean;
+    };
+}
+export declare class ElementTarget {
+    private readonly port;
+    constructor(port: ElementTargetPort);
+    /**
+     * Gets detailed information about an element, or null when it is absent.
+     *
+     * Delegates to the shared {@link probeElement} like `isVisible`/`isClickable`
+     * do. It used to inline its own copy of the checks, which had already
+     * drifted: that copy ignored `opacity: 0` and ancestor-overflow clipping, so
+     * it reported `isVisible: true` for elements `acquire()` rejects as hidden.
+     * One implementation means the three can never disagree again.
+     */
+    getElementInfo(selector: string): Promise<ElementInfo | null>;
+    /**
+     * Enhanced visibility check (display/visibility/opacity + ancestor-overflow
+     * clipping). Delegates to the shared {@link probeElement} so it can never
+     * drift from the check `acquire` enforces. Returns false for a missing element.
+     */
+    isVisible(selector: string): Promise<boolean>;
+    /**
+     * Enhanced clickable check (disabled/pointer-events/dimensions/opacity;
+     * readonly is intentionally NOT a blocker). Delegates to the shared
+     * {@link probeElement}. Returns false for a missing element.
+     */
+    isClickable(selector: string): Promise<boolean>;
+    /**
+     * Whether a form element is editable: present, not disabled, not readonly.
+     * Exposed separately from {@link isClickable} because readonly elements are
+     * clickable/focusable but not editable.
+     */
+    isEditable(selector: string): Promise<boolean>;
+    /**
+     * Enhanced scroll into view with better positioning
+     */
+    scrollIntoView(selector: string): Promise<void>;
+    /**
+     * Waits for an element's position to stabilize before interacting with it.
+     * Useful for letting scroll animations or dynamic layout changes settle.
+     * Times out silently - some elements never stabilize; callers proceed at their own risk.
+     *
+     * The observation runs entirely in-page in a SINGLE evaluate round-trip:
+     * a `requestAnimationFrame` loop samples the element's position, but only
+     * once every `checkInterval` ms of wall-clock, so the settle window matches
+     * the historical driver-side poll (N stable samples spaced `checkInterval`
+     * apart). The behaviour observable to the site is identical - it still waits
+     * the same duration for layout to settle before the click; only the internal
+     * transport changes (one round-trip instead of one evaluate per tick). A
+     * setTimeout hard-cap guarantees termination even if rAF is paused (a
+     * backgrounded tab), matching the old loop which always ended at `timeout`.
+     */
+    waitForPositionToStabilize(selector: string, timeout?: number, checkInterval?: number, stabilityThreshold?: number, tolerance?: number): Promise<void>;
+    /**
+     * Check if element is within the viewport (with some tolerance)
+     */
+    isInViewport(selector: string): Promise<boolean>;
+    /**
+     * The full pre-click targeting protocol: existence + visibility +
+     * clickability checks, scroll into view, position stabilization, box-model
+     * geometry, humanized (or exact-center) point selection, and a final
+     * in-viewport check. Returns the coordinates to click; throws a typed
+     * failure otherwise.
+     *
+     * With `force: true` every check is bypassed and a hidden element falls
+     * back to its bounding-box center.
+     */
+    acquire(selector: string, options?: {
+        force?: boolean;
+    }): Promise<{
+        x: number;
+        y: number;
+    }>;
+}
+//# sourceMappingURL=element-target.d.ts.map

package/dist/input/element-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-target.d.ts","sourceRoot":"","sources":["../../src/input/element-target.ts"],"names":[],"mappings":"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"}