jumpy-lion 0.1.6-beta.7 → 1.0.0-beta.0

package/dist/page.js

@@ -1,230 +1,221 @@
 import { EventEmitter } from 'events';
 import { load as cheerioLoad } from 'cheerio';
-import CDP from 'chrome-remote-interface';
 import { log } from 'crawlee';
+import { PageSession } from './connection/page-session.js';
 import { PAGE_CLOSED, PAGE_CREATED } from './events.js';
 import { humanScrollToElement } from './fingerprinting/fingerprint-overrides/index.js';
-import { describeChar, MODIFIER_SHIFT } from './keyboard-layout.js';
+import { DropdownSelector } from './input/dropdown-selector.js';
+import { ElementTarget } from './input/element-target.js';
+import { InputEmulator } from './input/input-emulator.js';
+import { CdpInputTransport } from './input/input-transport.js';
+import { PageNavigation } from './navigation/page-navigation.js';
+import { NetworkWatch } from './network/network-watch.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
-const HUMAN_KEYBOARD_DELAY_MIN_MS = 45;
-const HUMAN_KEYBOARD_DELAY_MAX_MS = 160;
-const HUMAN_MOUSE_MOVE_DELAY_MIN_MS = 6;
-const HUMAN_MOUSE_MOVE_DELAY_MAX_MS = 18;
-/** Bit values for `MouseEvent.buttons` per the UI Events spec. */
-const MOUSE_BUTTON_BITS = {
-    left: 1,
-    right: 2,
-    middle: 4,
-};
+// (mouse/keyboard humanization timing + button bitmask moved to src/input/input-emulator.ts)
 // 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
-
- */
-// @ts-expect-error not used now
-function createReconnectingPageProxy(page) {
-    const MAX_RETRIES = 3;
-    const INITIAL_BACKOFF = 1000;
-    async function executeWithRetries(operation, methodName) {
-        let lastError = null;
-        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-            try {
-                // Wait for any ongoing reconnection
-                while (page.isReconnecting) {
-                    await new Promise(resolve => setTimeout(resolve, 100));
-                }
-                // @ts-expect-error Accessing internal WebSocket
-                const ws = page._rawClient._ws;
-                // Check connection state before method call
-                if (ws && (ws.readyState !== ws.OPEN || ws.readyState === ws.CLOSING)) {
-                    const backoff = INITIAL_BACKOFF * 2 ** attempt;
-                    log.info(`WebSocket not connected before ${methodName}, attempting to reconnect... (attempt ${attempt + 1}/${MAX_RETRIES})`);
-                    try {
-                        await page.reconnectSession();
-                        await new Promise(resolve => setTimeout(resolve, backoff));
-                    }
-                    catch (reconnectError) {
-                        const error = reconnectError instanceof Error ? reconnectError : new Error(String(reconnectError));
-                        log.error('Reconnection failed:', { error });
-                        continue;
-                    }
-                }
-                return await operation();
-            }
-            catch (error) {
-                lastError = error instanceof Error ? error : new Error(String(error));
-                if (error instanceof Error && error.message?.includes('WebSocket is not open')) {
-                    const backoff = INITIAL_BACKOFF * 2 ** attempt;
-                    log.info(`WebSocket error during ${methodName}, attempting to reconnect... (attempt ${attempt + 1}/${MAX_RETRIES})`);
-                    try {
-                        await page.reconnectSession();
-                        await new Promise(resolve => setTimeout(resolve, backoff));
-                        continue;
-                    }
-                    catch (reconnectError) {
-                        const reconnectErr = reconnectError instanceof Error ? reconnectError : new Error(String(reconnectError));
-                        log.error('Reconnection failed:', { error: reconnectErr });
-                    }
-                }
-                throw error;
-            }
-        }
-        throw lastError || new Error(`Failed to execute ${methodName} after ${MAX_RETRIES} attempts`);
-    }
-    return new Proxy(page, {
-        get(target, property) {
-            const original = target[property];
-            const propertyName = String(property);
-            // Special handling for close method
-            if (propertyName === 'close') {
-                return original;
-            }
-            // Only proxy public methods that return promises
-            if (typeof original === 'function' &&
-                !propertyName.startsWith('_') &&
-                !propertyName.startsWith('on') &&
-                propertyName !== 'emit' &&
-                propertyName !== 'addListener' &&
-                propertyName !== 'removeListener') {
-                return async (...args) => {
-                    // @ts-expect-error Accessing private property
-                    if (target.isClosed) {
-                        log.debug(`Operation '${propertyName}' skipped - page is closed`);
-                        return;
-                    }
-                    return executeWithRetries(() => original.apply(target, args), propertyName);
-                };
-            }
-            return original;
-        },
-    });
-}
 export default class CdpPage extends EventEmitter {
-    constructor(client) {
+    /**
+     * Navigation + load-wait protocol - navigate, race dom/load events vs
+     * timeout, reconcile URL via getNavigationHistory - lives in PageNavigation
+     * behind NavigationPort. The port closures read the current client through
+     * the session accessor, so a reconnect client swap is picked up. The
+     * `loadedUrl` cache lives inside the module, not on this object.
+     */
+    get navigation() {
+        this._navigation ?? (this._navigation = new PageNavigation(this.navigationPort()));
+        return this._navigation;
+    }
+    navigationPort() {
+        return {
+            enablePage: async () => this.ensurePageEnabled(),
+            navigate: async (url) => {
+                this._documentNodeId = undefined;
+                await this.client.Page.navigate({ url });
+            },
+            reload: async () => {
+                this._documentNodeId = undefined;
+                await this.client.Page.reload({});
+            },
+            // chrome-remote-interface returns an unsubscribe fn from an event
+            // subscription; surface it so PageNavigation can detach the
+            // milestone listener after every navigation (incl. timeouts).
+            onDomContent: (handler) => this.client.Page.domContentEventFired(() => handler()),
+            onLoad: (handler) => this.client.Page.loadEventFired(() => handler()),
+            navigationHistory: async () => this.client.Page.getNavigationHistory(),
+            evaluateUrl: async () => this.evaluate('window.location.href'),
+        };
+    }
+    /**
+     * Network interception protocol - match/timeout/cleanup races live in
+     * NetworkWatch behind NetworkWatchPort. The port closures read
+     * `this.client` at call time, so a reconnectSession() client swap is
+     * picked up automatically.
+     */
+    get networkWatch() {
+        this._networkWatch ?? (this._networkWatch = new NetworkWatch({
+            ensureNetworkEnabled: async () => this.ensureNetworkEnabled(),
+            onResponseReceived: (handler) => {
+                const client = this.client;
+                client.on('Network.responseReceived', handler);
+                return () => client.removeListener('Network.responseReceived', handler);
+            },
+            getResponseBody: async (requestId) => this.client.Network.getResponseBody({ requestId }),
+            setRequestInterception: async (patterns) => {
+                await this.client.Network.setRequestInterception({ patterns });
+            },
+            onRequestIntercepted: (handler) => {
+                this.client.Network.on('requestIntercepted', handler);
+            },
+            continueInterceptedRequest: async (params) => {
+                await this.client.Network.continueInterceptedRequest(params);
+            },
+        }));
+        return this._networkWatch;
+    }
+    constructor(client, sessionOptions) {
         super();
-        Object.defineProperty(this, "_rawClient", {
+        /**
+         * Owns the live CDP session for this page: the current client, reconnect +
+         * heartbeat, the `isReconnecting` latch, and domain re-bind on swap. CDP
+         * methods route through `session.run(op)`; consumers read the current
+         * client through `session.client()`. See src/connection/page-session.ts.
+         */
+        Object.defineProperty(this, "session", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "client", {
+        Object.defineProperty(this, "_navigation", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "loadedUrl", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: null
-        });
-        Object.defineProperty(this, "isReconnecting", {
+        /**
+         * Cached document root nodeId for {@link getNodeId}. Populated on first
+         * lookup and reused across clicks so we don't re-issue DOM.getDocument on
+         * every element resolution. Invalidated on main-frame navigation (the
+         * navigate/reload closures below) because a new document reassigns node
+         * IDs; getNodeId additionally self-heals with a fresh getDocument if a
+         * stale root slips through.
+         */
+        Object.defineProperty(this, "_documentNodeId", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: false
+            value: void 0
         });
-        Object.defineProperty(this, "enabledDomains", {
+        Object.defineProperty(this, "_networkWatch", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: new Set()
+            value: void 0
         });
-        Object.defineProperty(this, "connectionMonitor", {
+        Object.defineProperty(this, "humanization", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: void 0
+            value: {
+                mouse: false,
+                keyboard: false,
+                scroll: false,
+            }
         });
-        Object.defineProperty(this, "isClosed", {
+        Object.defineProperty(this, "launchSnapshot", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: false
+            value: {}
         });
-        Object.defineProperty(this, "humanization", {
+        /**
+         * Human-like input emulation (mouse, keyboard, IME) over a transport bound
+         * to the live CDP client - see src/input/input-emulator.ts. The lazy
+         * `() => this.client` accessor keeps the transport pointed at the current
+         * connection across session reconnects, which swap `this.client`.
+         */
+        Object.defineProperty(this, "input", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: {
-                mouse: false,
-                keyboard: false,
-                scroll: false,
-            }
+            value: void 0
         });
-        Object.defineProperty(this, "lastMousePosition", {
+        /**
+         * Element targeting (geometry, visibility, scroll, position stabilization)
+         * over the narrow ElementTargetPort - see src/input/element-target.ts.
+         * Decides WHERE/WHEN to interact; `input` decides HOW.
+         */
+        Object.defineProperty(this, "elements", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: { x: 0, y: 0 }
+            value: void 0
         });
         /**
-         * Set of currently-held mouse buttons. Resolved to the `MouseEvent.buttons`
-         * bitmask (left=1, right=2, middle=4) on every `Input.dispatchMouseEvent`
-         * so JS sees the spec-correct value during press / drag / release. Without
-         * this, every press reads `event.buttons === 0` — a one-line bot signal.
+         * Select/dropdown protocol (native <select>, custom-dropdown trigger
+         * detection, idempotent open, virtualized-list scrolling) over the same
+         * port - see src/input/dropdown-selector.ts.
          */
-        Object.defineProperty(this, "heldMouseButtons", {
+        Object.defineProperty(this, "dropdowns", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: new Set()
+            value: void 0
         });
-        this._rawClient = client;
-        this.client = client;
+        this.session = new PageSession({ initialClient: client, ...sessionOptions });
+        this.input = new InputEmulator(new CdpInputTransport(() => this.client), this.humanization);
+        const targetPort = {
+            evaluate: async (fn, ...args) => this.evaluate(fn, ...args),
+            humanScrollToElement: async (selector) => {
+                await Promise.all([
+                    this._enableDomain('DOM'),
+                    this._enableDomain('Input'),
+                ]);
+                await humanScrollToElement(this.client, selector);
+            },
+            humanization: () => this.humanization,
+        };
+        this.elements = new ElementTarget(targetPort);
+        this.dropdowns = new DropdownSelector({
+            ...targetPort,
+            waitForSelector: async (selector, options) => this.waitForSelector(selector, options),
+            isLooselyVisible: async (selector) => this.isVisible(selector),
+            // Trusted coordinate click for dropdown triggers/options: the same
+            // CDP Input path CdpPage.click uses, so dropdown interactions carry
+            // isTrusted === true like every other click we make.
+            clickAt: async (x, y) => {
+                await Promise.all([
+                    this._enableDomain('DOM'),
+                    this._enableDomain('Input'),
+                ]);
+                await this.input.clickAt(x, y);
+            },
+        }, this.elements);
         this.emit(PAGE_CREATED);
-        // this._attachConnectionMonitor();
     }
-    _attachConnectionMonitor() {
-        if (this.connectionMonitor) {
-            clearInterval(this.connectionMonitor);
-        }
-        // @ts-expect-error Accessing internal WebSocket
-        const ws = this._rawClient._ws;
-        if (!ws)
-            return;
-        ws.on('error', (error) => {
-            log.error('WebSocket error occurred:', { error });
-        });
-        // Only monitor connection health
-        this.connectionMonitor = setInterval(() => {
-            if (ws.readyState === ws.OPEN) {
-                ws.ping(() => { });
-            }
-            else if (!this.isReconnecting && ws.readyState !== ws.CONNECTING) {
-                log.debug('Connection health check failed, clearing monitor');
-                if (this.connectionMonitor)
-                    clearInterval(this.connectionMonitor);
-            }
-        }, 5000);
-        this.once(PAGE_CLOSED, () => {
-            if (this.connectionMonitor)
-                clearInterval(this.connectionMonitor);
-        });
+    /** The current CDP client. Reads through PageSession so a reconnect swap is picked up. */
+    get client() {
+        return this.session.client();
+    }
+    /** The current raw CDP client (some consumers reach for `_ws` directly). */
+    get _rawClient() {
+        return this.session.client();
+    }
+    /** True while the page session is mid-reconnect. */
+    get isReconnecting() {
+        return this.session.isReconnecting;
     }
     // @TODO: The enabling of API can cause blocking.
     // We need to discover this more and add options to the crawler.
-    static async create(client) {
-        const page = new CdpPage(client);
+    static async create(client, sessionOptions) {
+        const page = new CdpPage(client, sessionOptions);
         await page.initialize();
-        // const proxiedPage = createReconnectingPageProxy(page);
-        log.debug('Created proxied page instance');
+        log.debug('Created page instance');
         return page;
     }
     async initialize() {
@@ -245,13 +236,8 @@ export default class CdpPage extends EventEmitter {
      * Once enabled, subsequent calls are no-ops.
      */
     async ensurePageEnabled() {
-        if (this.enabledDomains.has('Page')) {
-            return; // Already enabled
-        }
         try {
-            await this.client.Page.enable();
-            this.enabledDomains.add('Page');
-            log.debug('Page domain enabled lazily for script injection');
+            await this.session.enableDomain('Page');
         }
         catch (error) {
             log.error('Failed to enable Page domain:', { error });
@@ -264,12 +250,7 @@ export default class CdpPage extends EventEmitter {
      * Once enabled, subsequent calls are no-ops.
      */
     async ensureNetworkEnabled() {
-        if (this.enabledDomains.has('Network')) {
-            return; // Already enabled
-        }
-        await this.client.Network.enable();
-        this.enabledDomains.add('Network');
-        log.debug('Network domain enabled (lazy)');
+        await this.session.enableDomain('Network');
     }
     setHumanizationOptions(options) {
         this.humanization = {
@@ -277,86 +258,33 @@ export default class CdpPage extends EventEmitter {
             keyboard: options?.keyboard ?? false,
             scroll: options?.scroll ?? false,
         };
+        this.input.setHumanization(this.humanization);
     }
     async url() {
-        if (!this.loadedUrl) {
-            return await this._getCurrentUrlWithoutRuntime();
-        }
-        return this.loadedUrl;
-    }
-    /**
-     * Get current URL without activating the Runtime domain.
-     * Uses Page.getNavigationHistory which only requires the Page domain.
-     */
-    async _getCurrentUrlWithoutRuntime() {
-        try {
-            await this.ensurePageEnabled();
-            const { currentIndex, entries } = await this.client.Page.getNavigationHistory();
-            if (entries && entries.length > 0 && currentIndex >= 0) {
-                return entries[currentIndex].url;
-            }
-        }
-        catch {
-            // Fallback: if Page.getNavigationHistory fails, try evaluate
-            log.debug('getNavigationHistory failed, falling back to evaluate');
-        }
-        return await this.evaluate('window.location.href');
+        return this.navigation.url();
     }
-    // Navigation method
+    // Navigation method - protocol lives in PageNavigation (src/navigation/page-navigation.ts)
     async goto(url, options) {
-        const { Page } = this.client;
-        const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
-        await Page.navigate({ url });
-        const waitUntil = options?.waitUntil ?? 'load';
-        let waitEvent;
-        switch (waitUntil) {
-            case 'load':
-                waitEvent = new Promise((resolve) => Page.loadEventFired(() => resolve()));
-                break;
-            case 'domcontentloaded':
-                waitEvent = new Promise((resolve) => Page.domContentEventFired(() => resolve()));
-                break;
-            default:
-                throw new Error(`Unsupported waitUntil event: ${waitUntil}`);
-        }
-        await Promise.race([
-            waitEvent,
-            new Promise((_, reject) => setTimeout(() => reject(new Error('Navigation timeout')), timeout)),
-        ]);
-        // Use Page.getNavigationHistory instead of Runtime.evaluate to avoid
-        // activating the Runtime domain (which is detection vector #1)
-        this.loadedUrl = await this._getCurrentUrlWithoutRuntime();
+        // Transparently heal a dropped CDP socket; a closed page is a no-op.
+        await this.session.run(async () => this.navigation.goto(url, options));
     }
     /**
      * Reloads the current page.
      * @param options - Options for waiting and timeout, similar to goto.
      */
     async reload(options) {
-        const { Page } = this.client;
-        const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
-        const waitUntil = options?.waitUntil ?? 'load';
-        await Page.reload({});
-        let waitEvent;
-        switch (waitUntil) {
-            case 'load':
-                waitEvent = new Promise((resolve) => Page.loadEventFired(() => resolve()));
-                break;
-            case 'domcontentloaded':
-                waitEvent = new Promise((resolve) => Page.domContentEventFired(() => resolve()));
-                break;
-            default:
-                throw new Error(`Unsupported waitUntil event: ${waitUntil}`);
-        }
-        await Promise.race([
-            waitEvent,
-            new Promise((_, reject) => setTimeout(() => reject(new Error('Reload timeout')), timeout)),
-        ]);
-        // Use Page.getNavigationHistory instead of Runtime.evaluate
-        this.loadedUrl = await this._getCurrentUrlWithoutRuntime();
+        // Transparently heal a dropped CDP socket; a closed page is a no-op.
+        await this.session.run(async () => this.navigation.reload(options));
     }
     // Evaluate method
     // eslint-disable-next-line @typescript-eslint/ban-types
     async evaluate(pageFunction, ...args) {
+        // Transparently heal a dropped CDP socket; a closed page resolves to
+        // undefined rather than throwing.
+        return await this.session.run(async () => this._evaluateInner(pageFunction, ...args));
+    }
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    async _evaluateInner(pageFunction, ...args) {
         await this._enableDomain('Runtime');
         const { Runtime } = this.client;
         let expression;
@@ -387,7 +315,6 @@ export default class CdpPage extends EventEmitter {
             this._enableDomain('DOM'),
             this._enableDomain('Input'),
         ]);
-        const { DOM, Input } = this.client;
         const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
         const force = options?.force ?? false;
         const delay = options?.delay ?? 0;
@@ -395,469 +322,73 @@ export default class CdpPage extends EventEmitter {
         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);
-        // 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}`);
-                }
-            }
-        }
+        // Resolve the selector into a stable, in-viewport coordinate target
+        // (visibility/clickability checks, scroll, position stabilization,
+        // humanized point selection) - see src/input/element-target.ts.
+        const { x, y } = await this.elements.acquire(selector, { force });
         // 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.
-     * Note: screenX/screenY compensation is handled browser-side via fingerprint
-     * overrides that set realistic window.screenX/screenY values, which Chrome
-     * uses when constructing MouseEvent from CDP dispatch.
-     */
-    async _performClick(Input, x, y, button, clickCount, delay) {
-        await this._moveMouseTo(Input, x, y);
-        // Small delay to simulate human behavior
-        if (delay > 0) {
-            await new Promise(resolve => setTimeout(resolve, delay));
-        }
-        else if (this.humanization.mouse) {
-            await new Promise(resolve => setTimeout(resolve, 40 + Math.floor(Math.random() * 120)));
-        }
-        // Press: add to held set FIRST so `event.buttons` includes it on mousedown
-        // (matches real hardware where mousedown fires with the button already in the bitmask).
-        this.heldMouseButtons.add(button);
-        await Input.dispatchMouseEvent({
-            type: 'mousePressed',
-            x,
-            y,
-            button,
-            clickCount,
-            buttons: this._buttonsBitmask(),
-            pointerType: 'mouse',
-        });
-        // Small delay between press and release
-        await new Promise(resolve => setTimeout(resolve, PRESS_RELEASE_DELAY_MS));
-        // Release: remove from held set FIRST so `event.buttons` reflects the post-release
-        // state on mouseup (per UI Events spec — the released button is no longer pressed).
-        this.heldMouseButtons.delete(button);
-        await Input.dispatchMouseEvent({
-            type: 'mouseReleased',
-            x,
-            y,
-            button,
-            clickCount,
-            buttons: this._buttonsBitmask(),
-            pointerType: 'mouse',
-        });
-        this.lastMousePosition = { x, y };
-    }
-    _buttonsBitmask() {
-        let mask = 0;
-        for (const button of this.heldMouseButtons) {
-            mask += MOUSE_BUTTON_BITS[button];
-        }
-        return mask;
-    }
-    async _moveMouseTo(Input, x, y) {
-        if (!this.humanization.mouse) {
-            await Input.dispatchMouseEvent({
-                type: 'mouseMoved',
-                x,
-                y,
-                buttons: this._buttonsBitmask(),
-                pointerType: 'mouse',
-            });
-            this.lastMousePosition = { x, y };
-            return;
-        }
-        const fromX = this.lastMousePosition.x;
-        const fromY = this.lastMousePosition.y;
-        const path = await this.evaluate((startX, startY, endX, endY) => {
-            const fallback = [{ x: endX, y: endY }];
-            const globalStealth = window.__stealth;
-            if (!globalStealth || typeof globalStealth.humanizeMouse !== 'function') {
-                return fallback;
-            }
-            const points = globalStealth.humanizeMouse(startX, startY, endX, endY);
-            return Array.isArray(points) && points.length > 0 ? points : fallback;
-        }, fromX, fromY, x, y);
-        for (const point of path) {
-            await Input.dispatchMouseEvent({
-                type: 'mouseMoved',
-                x: point.x,
-                y: point.y,
-                buttons: this._buttonsBitmask(),
-                pointerType: 'mouse',
-            });
-            const delay = HUMAN_MOUSE_MOVE_DELAY_MIN_MS
-                + Math.floor(Math.random() * (HUMAN_MOUSE_MOVE_DELAY_MAX_MS - HUMAN_MOUSE_MOVE_DELAY_MIN_MS + 1));
-            await new Promise(resolve => setTimeout(resolve, delay));
-        }
-        this.lastMousePosition = { x, y };
-    }
-    /**
-     * 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) {
-        if (this.humanization.scroll) {
-            try {
-                await Promise.all([
-                    this._enableDomain('DOM'),
-                    this._enableDomain('Input'),
-                ]);
-                await humanScrollToElement(this.client, selector);
-                await this.evaluate((sel) => {
-                    const element = document.querySelector(sel);
-                    element?.scrollIntoView({ behavior: 'auto', block: 'center', inline: 'center' });
-                }, selector);
-                return;
-            }
-            catch {
-                // Some hidden/offscreen nodes do not expose a box model.
-                // Fall back to native DOM scrolling for robustness.
-            }
-        }
-        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.
+        await this.input.clickAt(x, y, { button, clickCount, delay });
     }
     // 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);
+        return this.elements.waitForPositionToStabilize(selector, timeout, checkInterval, stabilityThreshold, tolerance);
     }
     // Type method
     async type(selector, text, options) {
-        const { Input } = this.client;
-        await this.click(selector);
-        const delay = options?.delay ?? 0;
-        for (const char of text) {
-            await this._typeChar(Input, char);
-            if (delay > 0 || this.humanization.keyboard) {
-                const effectiveDelay = delay > 0
-                    ? delay
-                    : HUMAN_KEYBOARD_DELAY_MIN_MS + Math.floor(Math.random() * (HUMAN_KEYBOARD_DELAY_MAX_MS - HUMAN_KEYBOARD_DELAY_MIN_MS + 1));
-                await new Promise((resolve) => setTimeout(resolve, effectiveDelay));
-            }
+        // Focus the field, then delegate keystroke emulation (ANSI key
+        // sequences, CJK IME composition, humanized cadence) to the
+        // InputEmulator - see src/input/input-emulator.ts. With mouse
+        // humanization on, focus goes through the full humanized click path;
+        // otherwise a single in-page element.focus() round-trip skips the
+        // mouse-move emulation and click dispatch entirely.
+        if (this.humanization.mouse) {
+            await this.click(selector);
+        }
+        else {
+            await this.focusElement(selector);
         }
+        await this.input.typeText(text, { delay: options?.delay ?? 0 });
     }
     /**
-     * Dispatch a single character as a realistic key sequence:
-     *   rawKeyDown (with code/key/keyCode/modifiers) → char (fires keypress + beforeinput + input)
-     *   → keyUp.
-     *
-     * Characters outside the US ANSI printable set fall back to `Input.insertText`,
-     * which still produces beforeinput/input but no keyboard events (matches IME
-     * behaviour for Unicode/emoji input).
+     * Focus an element in a single Runtime.evaluate round-trip. Mirrors the
+     * wait-then-act semantics the click path gets from `waitForSelector`
+     * (MutationObserver wait, same timeout, same timeout error for a missing
+     * element), but collapses the wait and the `element.focus()` call into
+     * one CDP round-trip.
      */
-    async _typeChar(Input, char) {
-        const mapping = describeChar(char);
-        if (!mapping) {
-            await Input.insertText({ text: char });
-            return;
+    async focusElement(selector, timeout = DEFAULT_TIMEOUT_MS) {
+        const focused = await this.evaluate(async (sel, timeoutMs) => {
+            return new Promise((resolve) => {
+                const tryFocus = () => {
+                    const el = document.querySelector(sel);
+                    if (!el)
+                        return false;
+                    el.focus();
+                    resolve(true);
+                    return true;
+                };
+                if (tryFocus())
+                    return;
+                let timer;
+                const observer = new MutationObserver(() => {
+                    if (tryFocus()) {
+                        clearTimeout(timer);
+                        observer.disconnect();
+                    }
+                });
+                // Same observation surface as waitForSelector: childList+subtree
+                // catches insertion; attributes+characterData catch an existing
+                // node becoming matching.
+                observer.observe(document, { childList: true, subtree: true, attributes: true, characterData: true });
+                timer = setTimeout(() => {
+                    observer.disconnect();
+                    resolve(false);
+                }, timeoutMs);
+            });
+        }, selector, timeout);
+        if (!focused) {
+            throw new Error(`Timeout waiting for selector: ${selector}`);
         }
-        const { descriptor, shift } = mapping;
-        const modifiers = shift ? MODIFIER_SHIFT : 0;
-        const text = descriptor.text ?? descriptor.key;
-        await Input.dispatchKeyEvent({
-            type: 'rawKeyDown',
-            modifiers,
-            key: descriptor.key,
-            code: descriptor.code,
-            windowsVirtualKeyCode: descriptor.keyCode,
-            location: descriptor.location ?? 0,
-        });
-        await Input.dispatchKeyEvent({
-            type: 'char',
-            modifiers,
-            key: descriptor.key,
-            code: descriptor.code,
-            text,
-            unmodifiedText: text,
-            windowsVirtualKeyCode: descriptor.keyCode,
-            location: descriptor.location ?? 0,
-        });
-        await Input.dispatchKeyEvent({
-            type: 'keyUp',
-            modifiers,
-            key: descriptor.key,
-            code: descriptor.code,
-            windowsVirtualKeyCode: descriptor.keyCode,
-            location: descriptor.location ?? 0,
-        });
     }
     /**
      * Deletes (clears) the value of an input field specified by selector.
@@ -893,60 +424,42 @@ export default class CdpPage extends EventEmitter {
     // Wait for selector
     async waitForSelector(selector, options) {
         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, POLLING_INTERVAL_MS));
-            attempts++;
+        // Single in-page round-trip: resolve as soon as the selector matches via
+        // a MutationObserver (with an initial querySelector for elements already
+        // present), instead of re-issuing an evaluate on a fixed poll interval.
+        // The in-page promise resolves true on match / false on timeout; the
+        // observer is always torn down before resolving.
+        const found = await this.evaluate(async (sel, timeoutMs) => {
+            return new Promise((resolve) => {
+                if (document.querySelector(sel)) {
+                    resolve(true);
+                    return;
+                }
+                let timer;
+                const observer = new MutationObserver(() => {
+                    if (document.querySelector(sel)) {
+                        clearTimeout(timer);
+                        observer.disconnect();
+                        resolve(true);
+                    }
+                });
+                // childList+subtree catches insertion; attributes+characterData catch
+                // an already-present node becoming matching via a class/attribute/text
+                // change - the old 100ms querySelector poll caught those too.
+                observer.observe(document, { childList: true, subtree: true, attributes: true, characterData: true });
+                timer = setTimeout(() => {
+                    observer.disconnect();
+                    resolve(false);
+                }, timeoutMs);
+            });
+        }, selector, timeout);
+        if (!found) {
+            throw new Error(`Timeout waiting for selector: ${selector}`);
         }
-        throw new Error(`Timeout waiting for selector: ${selector}`);
     }
-    // Wait for response
+    // Wait for response - protocol lives in NetworkWatch (src/network/network-watch.ts)
     async waitForResponse(urlPart, statusCode = 200, timeout = 180000) {
-        await this.ensureNetworkEnabled(); // Lazy enable Network only when needed
-        return new Promise((resolve, reject) => {
-            let timer;
-            const onResponseReceived = async ({ requestId, response }) => {
-                if (response.url.includes(urlPart) && response.status === statusCode) {
-                    clearTimeout(timer);
-                    try {
-                        const { body } = await this.client.Network.getResponseBody({ requestId });
-                        resolve({
-                            ...response,
-                            body: JSON.parse(body),
-                        });
-                    }
-                    catch (err) {
-                        // Retry logic with exponential backoff
-                        for (let attempt = 1; attempt <= 3; attempt++) {
-                            try {
-                                await this.ensureNetworkEnabled();
-                                await new Promise((resolveTimeout) => setTimeout(resolveTimeout, 1000 * 2 ** attempt)); // Exponential backoff
-                                const { body } = await this.client.Network.getResponseBody({ requestId });
-                                resolve({
-                                    ...response,
-                                    body: JSON.parse(body),
-                                });
-                                return;
-                            }
-                            catch (retryErr) {
-                                if (attempt === 3)
-                                    reject(new Error(`Failed to get response body after ${attempt} attempts`));
-                            }
-                        }
-                    }
-                }
-            };
-            // @ts-expect-error it exists
-            this.client.Network.on('responseReceived', onResponseReceived);
-            timer = setTimeout(() => {
-                reject(new Error(`Timeout after ${timeout / 1000} seconds`));
-            }, timeout);
-        });
+        return this.networkWatch.waitForResponse(urlPart, statusCode, timeout);
     }
     async screenshot(options) {
         const { Page } = this.client;
@@ -980,7 +493,7 @@ export default class CdpPage extends EventEmitter {
     // Close method
     async close() {
         const { Page } = this.client;
-        this.isClosed = true;
+        this.session.markClosed();
         await Page.close();
         this.emit(PAGE_CLOSED);
     }
@@ -1015,71 +528,42 @@ export default class CdpPage extends EventEmitter {
     }
     // Add proper Fetch Metadata headers to avoid CDP detection
     async setupFetchMetadataHeaders() {
-        const { Network } = this.client;
-        await this._enableDomain('Network');
-        await Network.setRequestInterception({ patterns: [{ urlPattern: '*' }] });
-        Network.on('requestIntercepted', async (params) => {
-            const { request, interceptionId } = params;
-            const url = new URL(request.url);
-            // Add proper fetch metadata headers
-            const headers = { ...request.headers };
-            // Set sec-fetch-* headers based on request type and destination
-            if (request.method === 'GET' && !headers['sec-fetch-dest']) {
-                if (url.pathname.endsWith('.js')) {
-                    headers['sec-fetch-dest'] = 'script';
-                    headers['sec-fetch-mode'] = 'no-cors';
-                    headers['sec-fetch-site'] = url.origin === headers.origin ? 'same-origin' : 'cross-site';
-                }
-                else if (url.pathname.endsWith('.css')) {
-                    headers['sec-fetch-dest'] = 'style';
-                    headers['sec-fetch-mode'] = 'no-cors';
-                    headers['sec-fetch-site'] = url.origin === headers.origin ? 'same-origin' : 'cross-site';
-                }
-                else if (url.pathname.match(/\.(png|jpg|jpeg|gif|webp|svg)$/i)) {
-                    headers['sec-fetch-dest'] = 'image';
-                    headers['sec-fetch-mode'] = 'no-cors';
-                    headers['sec-fetch-site'] = url.origin === headers.origin ? 'same-origin' : 'cross-site';
-                }
-                else if (url.pathname === '/' || !url.pathname.includes('.')) {
-                    headers['sec-fetch-dest'] = 'document';
-                    headers['sec-fetch-mode'] = 'navigate';
-                    headers['sec-fetch-site'] = 'none';
-                    headers['sec-fetch-user'] = '?1';
-                }
-            }
-            // Continue the request with modified headers
-            await Network.continueInterceptedRequest({
-                interceptionId,
-                headers,
-            });
-        });
+        return this.networkWatch.setupFetchMetadataHeaders();
     }
     // Block requests matching URL patterns
     async blockRequests(urlPatterns) {
-        const { Network } = this.client;
-        await this.ensureNetworkEnabled(); // Lazy enable Network only when needed
-        await Network.setRequestInterception({ patterns: [{ urlPattern: '*' }] });
-        Network.on('requestIntercepted', async (params) => {
-            const shouldBlock = urlPatterns.some((pattern) => {
-                const regex = new RegExp(pattern.replace(/\*/g, '.*'));
-                return regex.test(params.request.url);
-            });
-            if (shouldBlock) {
-                await Network.continueInterceptedRequest({
-                    interceptionId: params.interceptionId,
-                    errorReason: 'Aborted',
-                });
-            }
-            else {
-                await Network.continueInterceptedRequest({ interceptionId: params.interceptionId });
-            }
-        });
+        return this.networkWatch.blockRequests(urlPatterns);
     }
-    // Helper method to get node ID from selector
+    /**
+     * Resolve a CSS selector to a CDP DOM nodeId. Retained as public page API
+     * for callers that need a node handle for direct CDP DOM work; the click
+     * hot-path no longer uses it (geometry now comes from in-page
+     * getBoundingClientRect - see ElementTarget.acquire). Reuses a cached
+     * document root and self-heals a stale root with a fresh getDocument.
+     */
     async getNodeId(selector) {
         const { DOM } = this.client;
-        const { root: { nodeId: documentNodeId } } = await DOM.getDocument();
-        const { nodeId } = await DOM.querySelector({ selector, nodeId: documentNodeId });
+        // Reuse a cached document root nodeId to skip a per-call DOM.getDocument
+        // round-trip. querySelector still runs on every call.
+        if (this._documentNodeId === undefined) {
+            const { root: { nodeId } } = await DOM.getDocument();
+            this._documentNodeId = nodeId;
+        }
+        try {
+            const { nodeId } = await DOM.querySelector({ selector, nodeId: this._documentNodeId });
+            if (nodeId) {
+                return { nodeId };
+            }
+        }
+        catch {
+            // Cached root may be stale (e.g. a navigation we did not observe).
+            // Fall through to the fresh-document retry below.
+        }
+        // Defensive retry: refetch the document root once and try again before
+        // reporting the selector as missing. Covers a stale cached root.
+        const { root: { nodeId: freshRoot } } = await DOM.getDocument();
+        this._documentNodeId = freshRoot;
+        const { nodeId } = await DOM.querySelector({ selector, nodeId: freshRoot });
         if (!nodeId) {
             throw new Error(`No node found for selector: ${selector}`);
         }
@@ -1089,9 +573,8 @@ export default class CdpPage extends EventEmitter {
         if (cookies.length === 0) {
             return;
         }
-        for (const cookie of cookies) {
-            await this.client.Network.setCookie(cookie);
-        }
+        // One batched CDP call instead of a round-trip per cookie.
+        await this.client.Network.setCookies({ cookies });
     }
     /**
       * Retrieves all cookies associated with the given URLs or all cookies for the current page if no URLs are provided.
@@ -1109,6 +592,17 @@ export default class CdpPage extends EventEmitter {
         const cookiesResult = await Network.getCookies({ urls });
         return cookiesResult.cookies;
     }
+    /**
+     * Records launch-time inputs (fingerprint config, resolved locale, user-data-dir, …)
+     * that `saveSession()` needs to assemble a SessionBundle. Called by the browser
+     * controller after fingerprint injection - not part of the user-facing API.
+     */
+    setLaunchSnapshot(snapshot) {
+        this.launchSnapshot = { ...this.launchSnapshot, ...snapshot };
+    }
+    getLaunchSnapshot() {
+        return this.launchSnapshot;
+    }
     // Add this method to your CdpPage class
     /**
      * Evaluates a function across multiple elements matching the given selector.
@@ -1127,87 +621,16 @@ export default class CdpPage extends EventEmitter {
         }, selector, pageFunction.toString(), ...args);
     }
     /**
-     * Enables a CDP domain only if it hasn't been enabled yet
+     * Enables a CDP domain only if it hasn't been enabled yet. Tracking lives
+     * in PageSession so a reconnect re-binds exactly the enabled domains.
      * @private
      */
     async _enableDomain(domain) {
-        if (this.enabledDomains.has(domain))
-            return;
-        const domainApi = this.client[domain];
-        if (domainApi?.enable) {
-            await domainApi.enable();
-            this.enabledDomains.add(domain);
-            log.debug(`Enabled ${domain} domain`);
-        }
+        await this.session.enableDomain(domain);
     }
+    /** Re-bind the page's CDP session after a transport drop. Delegates to PageSession. */
     async reconnectSession(retries = 3) {
-        if (this.isReconnecting) {
-            log.debug('Reconnection skipped - already in progress');
-            return;
-        }
-        if (this.isClosed) {
-            log.debug('Reconnection skipped - page is closed');
-            return;
-        }
-        let attempt = 0;
-        this.isReconnecting = true;
-        try {
-            while (attempt < retries) {
-                try {
-                    // Wait with exponential backoff before retrying
-                    if (attempt > 0) {
-                        const backoffMs = Math.min(1000 * (2 ** attempt), 10000);
-                        log.info(`Waiting ${backoffMs}ms before reconnection attempt ${attempt + 1}/${retries}`);
-                        await new Promise(resolve => setTimeout(resolve, backoffMs));
-                    }
-                    // Create a fresh CDP connection
-                    const newSession = await CDP({
-                        port: this._rawClient.port,
-                        local: true,
-                    });
-                    try {
-                        // Get available targets
-                        const { targetInfos } = await newSession.Target.getTargets();
-                        const pageTarget = targetInfos.find(t => t.type === 'page' && !t.url.includes('chrome://'));
-                        if (!pageTarget) {
-                            log.debug('No valid page target found, stopping reconnection');
-                            return;
-                        }
-                        // Connect to the specific page target
-                        const pageSession = await CDP({
-                            target: pageTarget.targetId,
-                            port: this._rawClient.port,
-                            local: true,
-                        });
-                        // Re-enable only the domains that were previously enabled
-                        const enablePromises = Array.from(this.enabledDomains).map(domain => pageSession[domain].enable());
-                        await Promise.all(enablePromises);
-                        // Update references
-                        this._rawClient = pageSession;
-                        this.client = pageSession;
-                        this._attachConnectionMonitor();
-                        log.info(`Page session reconnected successfully on attempt ${attempt + 1}`);
-                        return;
-                    }
-                    catch (error) {
-                        // Clean up the session if anything fails
-                        await newSession.close().catch(() => { });
-                        throw error;
-                    }
-                }
-                catch (error) {
-                    attempt++;
-                    if (attempt === retries) {
-                        log.debug('Reconnection stopped - max retries reached');
-                        return;
-                    }
-                    log.error('Failed to reconnect page session', { error });
-                }
-            }
-        }
-        finally {
-            this.isReconnecting = false;
-        }
+        await this.session.reconnect(retries);
     }
     /**
      * Selects one or more options from a select element or dropdown.
@@ -1236,249 +659,7 @@ export default class CdpPage extends EventEmitter {
             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;
-        // Normalize target selectors to array
-        const targetSelectors = Array.isArray(optionSelector) ? optionSelector : [optionSelector];
-        // Wait for dropdown element to exist
-        await this.waitForSelector(dropdownSelector, { timeout });
-        // Check if this is a regular select element
-        const isSelectElement = await this.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._isElementVisible(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.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._scrollElementIntoView(dropdownSelector);
-            // Wait for scroll animations to complete
-            await new Promise(resolve => setTimeout(resolve, SCROLL_ANIMATION_DELAY_MS));
-        }
-        if (isSelectElement) {
-            // Handle regular select element
-            await this._handleRegularSelect(dropdownSelector, targetSelectors, {
-                timeout,
-                force,
-            });
-        }
-        else {
-            // Handle custom dropdown - the dropdownSelector is the container
-            await this._handleCustomDropdown(dropdownSelector, targetSelectors, {
-                timeout,
-                force,
-                waitForOptions,
-                maxScrollAttempts,
-            });
-        }
-    }
-    /**
-     * Handles selection for regular HTML select elements
-     */
-    async _handleRegularSelect(selectSelector, targetSelectors, _options) {
-        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 within the select element
-                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 };
-        }, selectSelector, 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.
-     * 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;
-        // For custom dropdowns, always try to find and click a trigger to open
-        // Most custom dropdowns need a trigger click to become visible
-        await this.evaluate((containerSel) => {
-            const container = document.querySelector(containerSel);
-            if (!container)
-                return false;
-            // 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) {
-                        trigger.click();
-                        return true;
-                    }
-                }
-                // Strategy 2: Look for previous sibling that might be the trigger
-                const prevSibling = container.previousElementSibling;
-                if (prevSibling && prevSibling.tagName !== 'LABEL') {
-                    prevSibling.click();
-                    return true;
-                }
-            }
-            // 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) {
-                        trigger.click();
-                        return true;
-                    }
-                }
-            }
-            return false;
-        }, dropdownContainer);
-        // Wait for dropdown to open
-        await new Promise(resolve => setTimeout(resolve, dropdownOpenDelay));
-        // Wait for dropdown to be visible
-        if (waitForOptions) {
-            await this.waitForSelector(dropdownContainer, { timeout });
-        }
-        // Now check if dropdown is visible (unless force is true)
-        if (!force) {
-            const isVisible = await this._isElementVisible(dropdownContainer);
-            if (!isVisible) {
-                throw new Error(`Dropdown container is not visible after trigger click: ${dropdownContainer}. Use force: true to bypass this check.`);
-            }
-        }
-        // Select each target selector
-        for (const targetSelector of targetSelectors) {
-            await this._selectOptionFromDropdown(dropdownContainer, targetSelector, {
-                timeout,
-                force,
-                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;
-        while (scrollAttempts < maxScrollAttempts && !optionFound && (Date.now() - startTime) < timeout) {
-            // Try to find and click the option
-            const result = await this.evaluate((dropdownSel, targetSel) => {
-                const dropdown = document.querySelector(dropdownSel);
-                if (!dropdown)
-                    return { found: false, needsScroll: 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;
-                    return { found: false, needsScroll: isScrollable && !isAtBottom };
-                }
-                // Check if option is visible within the dropdown
-                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);
-            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 in dropdown "${dropdownSelector}"`);
-        }
+        await this.dropdowns.selectOption(dropdownSelector, optionSelector, options);
     }
     /**
      * Checks if the element specified by selector is visible (not display:none and not visibility:hidden).