@olib-ai/owl-browser-sdk 2.0.5 → 2.0.7

package/dist/playwright/page.js

@@ -0,0 +1,1698 @@
+/**
+ * Playwright-compatible Page class for Owl Browser.
+ *
+ * This is the primary interface for browser interaction. Each Page instance
+ * maps to a single browser context + tab in Owl Browser, translating
+ * Playwright API calls into the corresponding tool executions.
+ *
+ * Supports: navigation, interaction, content extraction, screenshots,
+ * evaluation, waiting, network interception (route/unroute), dialog
+ * handling, console monitoring, downloads, file upload, clipboard,
+ * scrolling, zoom, viewport, frames, tabs, video recording, and emulation.
+ */
+import { writeFile } from 'node:fs/promises';
+import { queryAll as extractQueryAll, queryFirst as extractQueryFirst, extractTable as extractTableFn, extractMeta as extractMetaFn, extractStructuredData as extractStructuredDataFn, countElements as countElementsFn, } from './extractor.js';
+import { Buffer } from 'node:buffer';
+import { createResponse } from './response.js';
+import { Keyboard } from './keyboard.js';
+import { Mouse } from './mouse.js';
+import { Frame, FrameLocator } from './frame.js';
+import { Locator, NthLocator } from './locator.js';
+import { Route, Dialog, ConsoleMessage, Download, Video, } from './page-helpers.js';
+/**
+ * Page provides the main API for interacting with a single browser tab.
+ *
+ * Mirrors the Playwright Page API surface. All async methods translate
+ * to Owl Browser tool executions via the underlying OwlBrowser client.
+ *
+ * @example
+ * ```typescript
+ * const page = await context.newPage();
+ * await page.goto('https://example.com');
+ * await page.click('#submit');
+ * const title = await page.title();
+ * ```
+ */
+export class Page {
+    _client;
+    _contextId;
+    _keyboard;
+    _mouse;
+    _mainFrame;
+    _url = 'about:blank';
+    _viewport = null;
+    _closed = false;
+    _tabId;
+    _routes = [];
+    _eventHandlers = new Map();
+    _video = null;
+    _dialogPollTimer = null;
+    _consolePollTimer = null;
+    _consoleLogOffset = 0;
+    _dialogSetupReady = null;
+    constructor(client, contextId, tabId) {
+        this._client = client;
+        this._contextId = contextId;
+        this._tabId = tabId ?? null;
+        this._keyboard = new Keyboard(client, contextId);
+        this._mouse = new Mouse(client, contextId);
+        this._mainFrame = new Frame(client, contextId, null, 'main');
+    }
+    // ==================== Properties ====================
+    /** The Keyboard instance for this page. */
+    get keyboard() {
+        return this._keyboard;
+    }
+    /** The Mouse instance for this page. */
+    get mouse() {
+        return this._mouse;
+    }
+    /** The main Frame of this page. */
+    mainFrame() {
+        return this._mainFrame;
+    }
+    /** The current page URL (synchronous getter). */
+    get url() {
+        return this._url;
+    }
+    /** Whether the page has been closed. */
+    isClosed() {
+        return this._closed;
+    }
+    /** The current viewport size, or null if not set. */
+    viewportSize() {
+        return this._viewport;
+    }
+    /** The underlying context ID. */
+    get contextId() {
+        return this._contextId;
+    }
+    /**
+     * Execute a browser tool with auto-injected context_id.
+     *
+     * @internal Used by Locator and other classes to execute tools.
+     * @param toolName - Browser tool name (e.g., 'browser_click')
+     * @param params - Tool parameters (context_id is auto-injected)
+     * @returns Tool execution result
+     */
+    async _execute(toolName, params = {}) {
+        return this._client.execute(toolName, {
+            context_id: this._contextId,
+            ...params,
+        });
+    }
+    // ==================== Navigation ====================
+    /**
+     * Navigate to a URL.
+     *
+     * @param url - Target URL (must include protocol)
+     * @param options - Navigation options (waitUntil, timeout, referer)
+     * @returns Response object or null
+     */
+    async goto(url, options) {
+        const waitUntil = mapWaitUntil(options?.waitUntil);
+        const params = {
+            context_id: this._contextId,
+            url,
+        };
+        if (waitUntil) {
+            params['wait_until'] = waitUntil;
+        }
+        if (options?.timeout !== undefined) {
+            params['timeout'] = String(options.timeout);
+        }
+        const result = await this._client.execute('browser_navigate', params);
+        this._url = url;
+        await this._syncUrl();
+        return createResponse(result);
+    }
+    /**
+     * Navigate back in history.
+     *
+     * @param options - Navigation options
+     * @returns Response object or null
+     */
+    async goBack(options) {
+        const params = {
+            context_id: this._contextId,
+        };
+        if (options?.waitUntil) {
+            params['wait_until'] = mapWaitUntil(options.waitUntil);
+        }
+        if (options?.timeout !== undefined) {
+            params['timeout'] = String(options.timeout);
+        }
+        const result = await this._client.execute('browser_go_back', params);
+        await this._syncUrl();
+        return createResponse(result);
+    }
+    /**
+     * Navigate forward in history.
+     *
+     * @param options - Navigation options
+     * @returns Response object or null
+     */
+    async goForward(options) {
+        const params = {
+            context_id: this._contextId,
+        };
+        if (options?.waitUntil) {
+            params['wait_until'] = mapWaitUntil(options.waitUntil);
+        }
+        if (options?.timeout !== undefined) {
+            params['timeout'] = String(options.timeout);
+        }
+        const result = await this._client.execute('browser_go_forward', params);
+        await this._syncUrl();
+        return createResponse(result);
+    }
+    /**
+     * Reload the page.
+     *
+     * @param options - Navigation options
+     * @returns Response object or null
+     */
+    async reload(options) {
+        const params = {
+            context_id: this._contextId,
+        };
+        if (options?.waitUntil) {
+            params['wait_until'] = mapWaitUntil(options.waitUntil);
+        }
+        if (options?.timeout !== undefined) {
+            params['timeout'] = String(options.timeout);
+        }
+        const result = await this._client.execute('browser_reload', params);
+        return createResponse(result);
+    }
+    // ==================== Content ====================
+    /** Get the page title. */
+    async title() {
+        const result = await this._client.execute('browser_get_page_info', {
+            context_id: this._contextId,
+        });
+        const res = result;
+        return String(res['title'] ?? '');
+    }
+    /** Get the full HTML content of the page. */
+    async content() {
+        const result = await this._client.execute('browser_get_html', {
+            context_id: this._contextId,
+        });
+        // Result is a raw HTML string
+        if (typeof result === 'string')
+            return result;
+        const res = result;
+        return String(res['html'] ?? res['result'] ?? '');
+    }
+    /**
+     * Set the HTML content of the page.
+     *
+     * @param html - HTML string to load
+     * @param options - Set content options
+     */
+    async setContent(html, options) {
+        void options;
+        await this._client.execute('browser_set_content', {
+            context_id: this._contextId,
+            html,
+        });
+    }
+    // ==================== Schema-Driven Extraction ====================
+    /**
+     * Extract structured data from all elements matching a CSS selector.
+     *
+     * Fetches the page HTML once and parses it SDK-side using cheerio.
+     * Each matching container element has the given fields extracted from it.
+     *
+     * Field syntax:
+     *   `"selector"` → textContent of the matched child element
+     *   `"selector@attr"` → attribute value of the matched child element
+     *   `"@attr"` → attribute on the container element itself
+     *
+     * @param selector - CSS selector for repeating container elements
+     * @param fields - Mapping of output names to extraction specs
+     * @returns Array of objects with extracted values
+     *
+     * @example
+     * ```typescript
+     * const products = await page.queryAll('.product-card', {
+     *   name: 'h2',
+     *   price: '.price',
+     *   image: 'img@src',
+     *   link: 'a@href',
+     * });
+     * ```
+     */
+    async queryAll(selector, fields) {
+        const html = await this.content();
+        return extractQueryAll(html, selector, fields);
+    }
+    /**
+     * Extract structured data from the first element matching a CSS selector.
+     *
+     * @param selector - CSS selector for the container element
+     * @param fields - Mapping of output names to extraction specs
+     * @returns Single record or null if no match
+     */
+    async queryFirst(selector, fields) {
+        const html = await this.content();
+        return extractQueryFirst(html, selector, fields);
+    }
+    /**
+     * Extract a <table> as an array of records.
+     *
+     * @param selector - CSS selector for the table (default: 'table')
+     * @param options - Optional headers override
+     * @returns Array of records with header keys
+     */
+    async extractTable(selector, options) {
+        const html = await this.content();
+        return extractTableFn(html, selector ?? 'table', options);
+    }
+    /**
+     * Extract JSON-LD structured data from the page.
+     *
+     * @returns Array of parsed JSON-LD objects
+     */
+    async extractStructuredData() {
+        const html = await this.content();
+        return extractStructuredDataFn(html);
+    }
+    /**
+     * Extract meta tags from the page.
+     *
+     * @returns MetaData with title, description, canonical, og, twitter, other
+     */
+    async extractMeta() {
+        const html = await this.content();
+        return extractMetaFn(html);
+    }
+    /**
+     * Count elements matching a CSS selector.
+     *
+     * @param selector - CSS selector
+     * @returns Number of matching elements
+     */
+    async count(selector) {
+        const html = await this.content();
+        return countElementsFn(html, selector);
+    }
+    /**
+     * Extract structured data across multiple pages or scroll loads.
+     *
+     * Supports two pagination modes:
+     * - **Click-next**: clicks a "next" button and waits for page update.
+     * - **Infinite scroll**: scrolls to bottom and waits for new content.
+     *
+     * Automatically detects end of data: next button gone/disabled/hidden,
+     * no new items after dedup, or max pages/scrolls reached.
+     *
+     * @param selector - CSS selector for repeating container elements
+     * @param options - Scrape options (fields, next, scroll, limits)
+     * @returns Deduplicated array of all extracted records across pages
+     */
+    async scrape(selector, options) {
+        const { fields, next, maxPages = 10, wait = 2000, scroll = false, maxScrolls = 20, scrollWait = 2000, urls, urlPattern, startPage = 1, endPage, pageStep = 1, follow, onPageDone, retries = 0, retryDelay = 1000, } = options;
+        const allItems = [];
+        const seen = new Set();
+        // Helper: extract and dedup items from current page
+        const extractPage = async (pageNum) => {
+            const html = await this.content();
+            const items = extractQueryAll(html, selector, fields);
+            let newCount = 0;
+            for (const item of items) {
+                const key = JSON.stringify(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)));
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    allItems.push(item);
+                    newCount++;
+                }
+            }
+            onPageDone?.({ page: pageNum, newItems: newCount, totalItems: allItems.length });
+            return newCount;
+        };
+        // Helper: retry a function
+        const withRetry = async (fn) => {
+            let lastError;
+            for (let attempt = 0; attempt <= retries; attempt++) {
+                try {
+                    return await fn();
+                }
+                catch (e) {
+                    lastError = e;
+                    if (attempt < retries) {
+                        await this.waitForTimeout(retryDelay);
+                    }
+                }
+            }
+            throw lastError;
+        };
+        // Mode 3: URL pagination
+        if (urls || urlPattern) {
+            const urlList = [];
+            if (urls) {
+                urlList.push(...urls);
+            }
+            else if (urlPattern) {
+                const end = endPage ?? (startPage + maxPages - 1);
+                for (let p = startPage; p <= end; p += pageStep) {
+                    const offset = (p - 1) * pageStep;
+                    urlList.push(urlPattern
+                        .replace(/\{page\}/g, String(p))
+                        .replace(/\{offset\}/g, String(offset)));
+                }
+            }
+            for (let i = 0; i < urlList.length; i++) {
+                await withRetry(async () => {
+                    await this.goto(urlList[i]);
+                    await this.waitForLoadState();
+                    if (wait > 0)
+                        await this.waitForTimeout(wait);
+                });
+                const newCount = await extractPage(i + 1);
+                if (newCount === 0)
+                    break;
+            }
+        }
+        // Mode 1 & 2: Click-next or Infinite scroll
+        else {
+            const limit = scroll ? maxScrolls : maxPages;
+            for (let i = 0; i < limit; i++) {
+                const newCount = await extractPage(i + 1);
+                if (newCount === 0)
+                    break;
+                if (scroll) {
+                    await this.scrollToBottom();
+                    await this.waitForTimeout(scrollWait);
+                }
+                else if (next) {
+                    const loc = this.locator(next);
+                    try {
+                        const count = await loc.count();
+                        if (count === 0)
+                            break;
+                    }
+                    catch {
+                        break;
+                    }
+                    if (!(await loc.isVisible()) || !(await loc.isEnabled()))
+                        break;
+                    await loc.click();
+                    await this.waitForLoadState();
+                    await this.waitForTimeout(wait);
+                }
+                else {
+                    break;
+                }
+            }
+        }
+        // Detail page following
+        if (follow) {
+            const followWait = follow.wait ?? 1000;
+            for (const item of allItems) {
+                // Extract the URL from the item using the urlSelector as a string spec
+                const detailUrl = item[follow.urlSelector]
+                    ?? extractQueryFirst(await this.content(), selector, { _url: follow.urlSelector })?.['_url'];
+                if (!detailUrl || typeof detailUrl !== 'string')
+                    continue;
+                // Resolve relative URLs
+                let fullUrl = detailUrl;
+                if (!detailUrl.startsWith('http://') && !detailUrl.startsWith('https://')) {
+                    try {
+                        fullUrl = new URL(detailUrl, this.url).href;
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                const prevUrl = this.url;
+                try {
+                    await withRetry(async () => {
+                        await this.goto(fullUrl);
+                        await this.waitForLoadState();
+                        if (followWait > 0)
+                            await this.waitForTimeout(followWait);
+                    });
+                    const detailHtml = await this.content();
+                    const detailData = extractQueryFirst(detailHtml, 'body', follow.fields)
+                        ?? extractQueryFirst(detailHtml, selector, follow.fields);
+                    if (detailData) {
+                        Object.assign(item, detailData);
+                    }
+                }
+                catch {
+                    // Skip failed detail pages
+                }
+                // Navigate back
+                try {
+                    await this.goto(prevUrl);
+                    await this.waitForLoadState();
+                }
+                catch {
+                    // Best effort
+                }
+            }
+        }
+        return allItems;
+    }
+    /**
+     * Get the page content as Markdown.
+     *
+     * @returns Markdown representation of the page
+     */
+    async markdown() {
+        const result = await this._client.execute('browser_get_markdown', {
+            context_id: this._contextId,
+        });
+        // Result is a raw markdown string
+        if (typeof result === 'string')
+            return result;
+        const res = result;
+        return String(res['markdown'] ?? res['result'] ?? '');
+    }
+    // ==================== Interaction ====================
+    /**
+     * Click an element.
+     *
+     * @param selector - CSS selector, XY coordinates, or natural language description
+     * @param options - Click options (button, clickCount, etc.)
+     */
+    async click(selector, options) {
+        // Ensure dialog setup is complete before interacting (prevents race condition)
+        if (this._dialogSetupReady) {
+            await this._dialogSetupReady;
+            this._dialogSetupReady = null;
+        }
+        if (options?.button === 'right') {
+            await this._client.execute('browser_right_click', {
+                context_id: this._contextId,
+                selector,
+            });
+            return;
+        }
+        if (options?.clickCount === 2) {
+            await this._client.execute('browser_double_click', {
+                context_id: this._contextId,
+                selector,
+            });
+            return;
+        }
+        await this._client.execute('browser_click', {
+            context_id: this._contextId,
+            selector,
+        });
+    }
+    /** Double-click an element. */
+    async dblclick(selector, options) {
+        void options;
+        await this._client.execute('browser_double_click', {
+            context_id: this._contextId,
+            selector,
+        });
+    }
+    /**
+     * Fill an input element (clears existing content first).
+     *
+     * @param selector - Target input element
+     * @param value - Text to fill
+     * @param options - Fill options
+     */
+    async fill(selector, value, options) {
+        void options;
+        await this._client.execute('browser_clear_input', {
+            context_id: this._contextId,
+            selector,
+        });
+        await this._client.execute('browser_type', {
+            context_id: this._contextId,
+            selector,
+            text: value,
+        });
+    }
+    /**
+     * Type text into an element (does NOT clear existing content).
+     *
+     * @param selector - Target input element
+     * @param text - Text to type
+     * @param options - Type options
+     */
+    async type(selector, text, options) {
+        void options;
+        await this._client.execute('browser_type', {
+            context_id: this._contextId,
+            selector,
+            text,
+        });
+    }
+    /**
+     * Focus an element and press a key.
+     *
+     * For special keys (Enter, Tab, Escape, etc.) uses browser_press_key.
+     * For single character keys (a-z, 0-9, etc.) uses browser_type to simulate typing.
+     */
+    async press(selector, key, options) {
+        void options;
+        await this._client.execute('browser_focus', {
+            context_id: this._contextId,
+            selector,
+        });
+        // Delegate to keyboard which handles the special-key vs character distinction
+        await this._keyboard.press(key);
+    }
+    /** Hover over an element. */
+    async hover(selector, options) {
+        void options;
+        await this._client.execute('browser_hover', {
+            context_id: this._contextId,
+            selector,
+        });
+    }
+    /** Focus an element. */
+    async focus(selector, options) {
+        void options;
+        await this._client.execute('browser_focus', {
+            context_id: this._contextId,
+            selector,
+        });
+    }
+    /** Blur the currently focused element. */
+    async blur(selector) {
+        await this._client.execute('browser_blur', {
+            context_id: this._contextId,
+            selector,
+        });
+    }
+    /** Select option(s) from a dropdown. Calls browser_pick once per value. */
+    async selectOption(selector, values, options) {
+        void options;
+        const valueList = extractSelectValues(values);
+        for (const value of valueList) {
+            await this._client.execute('browser_pick', {
+                context_id: this._contextId,
+                selector,
+                value,
+            });
+        }
+        return valueList;
+    }
+    /** Check a checkbox (no-op if already checked). */
+    async check(selector, options) {
+        void options;
+        const checked = await this.isChecked(selector);
+        if (!checked) {
+            await this.click(selector);
+        }
+    }
+    /** Uncheck a checkbox (no-op if already unchecked). */
+    async uncheck(selector, options) {
+        void options;
+        const checked = await this.isChecked(selector);
+        if (checked) {
+            await this.click(selector);
+        }
+    }
+    /** Drag an element and drop it onto another element. */
+    async dragAndDrop(source, target, options) {
+        void options;
+        // Use browser_html5_drag_drop which accepts CSS selectors.
+        // browser_drag_drop requires pixel coordinates and is for non-HTML5 drag.
+        await this._client.execute('browser_html5_drag_drop', {
+            context_id: this._contextId,
+            source_selector: source,
+            target_selector: target,
+        });
+    }
+    /**
+     * Upload files to a file input element.
+     *
+     * @param selector - CSS selector for the file input element
+     * @param files - File path(s) to upload
+     * @param options - Upload options
+     */
+    async setInputFiles(selector, files, options) {
+        void options;
+        const filePaths = Array.isArray(files) ? files : [files];
+        await this._client.execute('browser_upload_file', {
+            context_id: this._contextId,
+            selector,
+            file_paths: JSON.stringify(filePaths),
+        });
+    }
+    /** Submit a form. */
+    async submitForm(selector) {
+        await this._client.execute('browser_submit_form', {
+            context_id: this._contextId,
+            selector,
+        });
+    }
+    /** Select all text in the focused element. */
+    async selectAll() {
+        await this._client.execute('browser_select_all', {
+            context_id: this._contextId,
+        });
+    }
+    // ==================== Queries ====================
+    /** Get the text content of an element. */
+    async textContent(selector) {
+        const result = await this._client.execute('browser_extract_text', {
+            context_id: this._contextId,
+            selector,
+        });
+        // Result is a raw string (the text content)
+        if (result === null || result === undefined)
+            return null;
+        if (typeof result === 'string')
+            return result;
+        const res = result;
+        return res['text'] ?? String(res['result'] ?? '');
+    }
+    /** Get the inner HTML of an element. */
+    async innerHTML(selector) {
+        const result = await this._client.execute('browser_get_html', {
+            context_id: this._contextId,
+            selector,
+        });
+        if (typeof result === 'string')
+            return result;
+        const res = result;
+        return String(res['html'] ?? res['result'] ?? '');
+    }
+    /** Get the inner text of an element (visible text only). */
+    async innerText(selector) {
+        const text = await this.textContent(selector);
+        return text ?? '';
+    }
+    /** Get an attribute value from an element. */
+    async getAttribute(selector, name) {
+        const result = await this._client.execute('browser_get_attribute', {
+            context_id: this._contextId,
+            selector,
+            attribute: name,
+        });
+        if (result === null || result === undefined)
+            return null;
+        if (typeof result === 'string')
+            return result.length > 0 ? result : null;
+        const res = result;
+        const val = res['value'] ?? res['result'];
+        if (val === undefined || val === null)
+            return null;
+        return String(val);
+    }
+    /** Get the bounding box of an element. */
+    async boundingBox(selector) {
+        try {
+            const result = await this._client.execute('browser_get_bounding_box', {
+                context_id: this._contextId,
+                selector,
+            });
+            const res = result;
+            return {
+                x: Number(res['x'] ?? 0),
+                y: Number(res['y'] ?? 0),
+                width: Number(res['width'] ?? 0),
+                height: Number(res['height'] ?? 0),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // ==================== Element State ====================
+    /** Check if an element is visible. */
+    async isVisible(selector) {
+        const result = await this._client.execute('browser_is_visible', {
+            context_id: this._contextId,
+            selector,
+        });
+        const res = result;
+        if (res['error_code'] === 'visible' || res['visible'] === true)
+            return true;
+        if (res['error_code'] === 'hidden')
+            return false;
+        return false;
+    }
+    /** Check if an element is enabled. */
+    async isEnabled(selector) {
+        const result = await this._client.execute('browser_is_enabled', {
+            context_id: this._contextId,
+            selector,
+        });
+        const res = result;
+        if (res['error_code'] === 'enabled' || res['enabled'] === true)
+            return true;
+        if (res['error_code'] === 'disabled')
+            return false;
+        return false;
+    }
+    /** Check if a checkbox/radio is checked. */
+    async isChecked(selector) {
+        const result = await this._client.execute('browser_is_checked', {
+            context_id: this._contextId,
+            selector,
+        });
+        const res = result;
+        if (res['error_code'] === 'checked' || res['checked'] === true)
+            return true;
+        if (res['error_code'] === 'unchecked')
+            return false;
+        return false;
+    }
+    // ==================== Screenshots & PDF ====================
+    /**
+     * Take a screenshot of the page.
+     *
+     * @param options - Screenshot options (path, type, fullPage, etc.)
+     * @returns PNG image data as Buffer
+     */
+    async screenshot(options) {
+        const params = {
+            context_id: this._contextId,
+        };
+        if (options?.fullPage) {
+            params['full_page'] = true;
+        }
+        const result = await this._client.execute('browser_screenshot', params);
+        // Result is a raw base64 string (not an object)
+        const base64Data = typeof result === 'string'
+            ? result
+            : String(result['data'] ?? result['screenshot'] ?? result['image'] ?? '');
+        const buffer = Buffer.from(base64Data, 'base64');
+        if (options?.path) {
+            await writeFile(options.path, buffer);
+        }
+        return buffer;
+    }
+    /**
+     * Generate a PDF of the page.
+     *
+     * Stub: Owl Browser does not directly support PDF generation.
+     * Returns an empty buffer.
+     *
+     * @param options - PDF options
+     * @returns Empty Buffer
+     */
+    async pdf(options) {
+        void options;
+        return Buffer.alloc(0);
+    }
+    // ==================== Evaluate ====================
+    /**
+     * Evaluate JavaScript in the page context.
+     *
+     * @param pageFunction - Function or expression string to evaluate
+     * @param arg - Optional argument to pass to the function
+     * @returns The result of the evaluation
+     */
+    async evaluate(pageFunction, arg) {
+        // Ensure dialog setup is complete before evaluating (prevents race condition)
+        if (this._dialogSetupReady) {
+            await this._dialogSetupReady;
+            this._dialogSetupReady = null;
+        }
+        const expression = typeof pageFunction === 'function'
+            ? `(${pageFunction.toString()})(${arg !== undefined ? JSON.stringify(arg) : ''})`
+            : pageFunction;
+        const result = await this._client.execute('browser_evaluate', {
+            context_id: this._contextId,
+            expression,
+        });
+        return result;
+    }
+    /**
+     * Evaluate JavaScript and return a handle (simplified).
+     *
+     * @param pageFunction - Function or expression string
+     * @param arg - Optional argument
+     * @returns Evaluation result
+     */
+    async evaluateHandle(pageFunction, arg) {
+        return this.evaluate(pageFunction, arg);
+    }
+    /**
+     * Add a script to evaluate when a new document is created.
+     *
+     * @param script - JavaScript code or path to script file
+     * @param arg - Optional argument
+     */
+    async addInitScript(script, arg) {
+        void arg;
+        const code = typeof script === 'string' ? script : '';
+        if (code) {
+            await this._client.execute('browser_evaluate', {
+                context_id: this._contextId,
+                script: code,
+                return_value: false,
+            });
+        }
+    }
+    /**
+     * Expose a function in the page's global scope.
+     *
+     * Stub: Creates a global function that logs calls via console.
+     *
+     * @param name - Function name to expose
+     * @param callback - Function implementation
+     */
+    async exposeFunction(name, callback) {
+        void callback;
+        await this._client.execute('browser_evaluate', {
+            context_id: this._contextId,
+            script: `window['${name}'] = function() { console.log('${name} called', ...arguments); }`,
+            return_value: false,
+        });
+    }
+    // ==================== Waiting ====================
+    /** Wait for a selector to appear in the DOM. */
+    async waitForSelector(selector, options) {
+        const params = {
+            context_id: this._contextId,
+            selector,
+        };
+        if (options?.timeout !== undefined) {
+            params['timeout'] = options.timeout;
+        }
+        await this._client.execute('browser_wait_for_selector', params);
+    }
+    /** Wait for a fixed amount of time. */
+    async waitForTimeout(timeout) {
+        await this._client.execute('browser_wait', {
+            context_id: this._contextId,
+            timeout,
+        });
+    }
+    /** Wait for the page URL to match. */
+    async waitForURL(url, options) {
+        const isRegex = url instanceof RegExp;
+        const urlString = typeof url === 'string'
+            ? url
+            : url instanceof RegExp
+                ? url.source
+                : '*';
+        const params = {
+            context_id: this._contextId,
+            url_pattern: urlString,
+        };
+        if (isRegex) {
+            params['is_regex'] = true;
+        }
+        if (options?.timeout !== undefined) {
+            params['timeout'] = options.timeout;
+        }
+        await this._client.execute('browser_wait_for_url', params);
+        await this._syncUrl();
+    }
+    /** Wait for a JavaScript function to return truthy. */
+    async waitForFunction(pageFunction, arg, options) {
+        const fn = typeof pageFunction === 'function'
+            ? `(${pageFunction.toString()})(${arg !== undefined ? JSON.stringify(arg) : ''})`
+            : pageFunction;
+        const params = {
+            context_id: this._contextId,
+            js_function: fn,
+        };
+        if (options?.timeout !== undefined) {
+            params['timeout'] = String(options.timeout);
+        }
+        if (options?.polling !== undefined && options.polling !== 'raf') {
+            params['polling'] = String(options.polling);
+        }
+        await this._client.execute('browser_wait_for_function', params);
+    }
+    /** Wait for the page to reach a specific load state. */
+    async waitForLoadState(state, options) {
+        const params = {
+            context_id: this._contextId,
+        };
+        if (options?.timeout !== undefined) {
+            params['timeout'] = options.timeout;
+        }
+        if (state === 'domcontentloaded') {
+            await this._client.execute('browser_wait_for_selector', {
+                ...params,
+                selector: 'body',
+            });
+        }
+        else if (state === 'load') {
+            await this._client.execute('browser_wait_for_function', {
+                ...params,
+                js_function: 'document.readyState === "complete"',
+            });
+        }
+        else {
+            // 'networkidle' or undefined — default behavior
+            await this._client.execute('browser_wait_for_network_idle', params);
+        }
+    }
+    /** Wait for a specific event to fire. */
+    async waitForEvent(event, optionsOrPredicate) {
+        const options = typeof optionsOrPredicate === 'function'
+            ? { predicate: optionsOrPredicate }
+            : optionsOrPredicate;
+        const timeout = options?.timeout ?? 30000;
+        if (event === 'download') {
+            return this._waitForDownload(timeout);
+        }
+        if (event === 'dialog') {
+            return this._waitForDialog(timeout);
+        }
+        if (event === 'console') {
+            return this._waitForConsole(timeout);
+        }
+        // Generic wait fallback
+        await this.waitForTimeout(Math.min(timeout, 1000));
+        return null;
+    }
+    /**
+     * Wait for a network response matching the given URL/predicate.
+     *
+     * Enables network logging and polls browser_get_network_log for matches.
+     *
+     * @param urlOrPredicate - URL string, RegExp, or predicate function
+     * @param options - Wait options (timeout)
+     * @returns A Response object for the matching network entry
+     */
+    async waitForResponse(urlOrPredicate, options) {
+        const timeout = options?.timeout ?? 30000;
+        await this._client.execute('browser_enable_network_logging', {
+            context_id: this._contextId,
+            enable: true,
+        });
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const result = await this._client.execute('browser_get_network_log', {
+                context_id: this._contextId,
+            });
+            const res = result;
+            // browser_get_network_log returns { requests: [...], responses: [...] }
+            const entries = (res['responses'] ?? []);
+            if (Array.isArray(entries)) {
+                for (const entry of entries) {
+                    const entryUrl = String(entry['url'] ?? '');
+                    const status = Number(entry['status'] ?? entry['statusCode'] ?? 0);
+                    if (typeof urlOrPredicate === 'string') {
+                        if (entryUrl.includes(urlOrPredicate) && status > 0) {
+                            return createResponse({ url: entryUrl, status });
+                        }
+                    }
+                    else if (urlOrPredicate instanceof RegExp) {
+                        if (urlOrPredicate.test(entryUrl) && status > 0) {
+                            return createResponse({ url: entryUrl, status });
+                        }
+                    }
+                    // Predicate support would require constructing a full Response first
+                }
+            }
+            await this.waitForTimeout(200);
+        }
+        throw new Error(`Timeout waiting for response (${timeout}ms)`);
+    }
+    /**
+     * Wait for a network request matching the given URL/predicate.
+     *
+     * @param urlOrPredicate - URL string or RegExp to match
+     * @param options - Wait options (timeout)
+     */
+    async waitForRequest(urlOrPredicate, options) {
+        const timeout = options?.timeout ?? 30000;
+        await this._client.execute('browser_enable_network_logging', {
+            context_id: this._contextId,
+            enable: true,
+        });
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const result = await this._client.execute('browser_get_network_log', {
+                context_id: this._contextId,
+            });
+            const res = result;
+            // browser_get_network_log returns { requests: [...], responses: [...] }
+            const entries = (res['requests'] ?? []);
+            if (Array.isArray(entries)) {
+                for (const entry of entries) {
+                    const entryUrl = String(entry['url'] ?? '');
+                    const method = String(entry['method'] ?? 'GET');
+                    if (typeof urlOrPredicate === 'string') {
+                        if (entryUrl.includes(urlOrPredicate)) {
+                            return { url: () => entryUrl, method: () => method };
+                        }
+                    }
+                    else if (urlOrPredicate instanceof RegExp) {
+                        if (urlOrPredicate.test(entryUrl)) {
+                            return { url: () => entryUrl, method: () => method };
+                        }
+                    }
+                }
+            }
+            await this.waitForTimeout(200);
+        }
+        throw new Error(`Timeout waiting for request (${timeout}ms)`);
+    }
+    // ==================== Network Interception ====================
+    /**
+     * Intercept network requests matching a URL pattern.
+     *
+     * @param url - URL pattern (glob) or RegExp to match
+     * @param handler - Handler function to process intercepted requests
+     * @param options - Route options (e.g., times)
+     */
+    async route(url, handler, options) {
+        const urlPattern = url instanceof RegExp ? url.source : url;
+        // Enable network interception
+        await this._client.execute('browser_enable_network_interception', {
+            context_id: this._contextId,
+            enable: true,
+        });
+        // Add a block rule first (handler will override with fulfill/abort/continue)
+        const result = await this._client.execute('browser_add_network_rule', {
+            context_id: this._contextId,
+            url_pattern: urlPattern,
+            action: 'block',
+            is_regex: url instanceof RegExp,
+        });
+        const res = result;
+        const ruleId = String(res['rule_id'] ?? '');
+        this._routes.push({
+            urlPattern,
+            ruleId,
+            handler,
+            remaining: options?.times ?? null,
+        });
+        // Invoke handler with a Route instance
+        const route = new Route(this._client, this._contextId, ruleId, urlPattern);
+        await handler(route);
+    }
+    /**
+     * Remove a previously registered route handler.
+     *
+     * @param url - URL pattern that was registered
+     * @param handler - Optional specific handler to remove
+     */
+    async unroute(url, handler) {
+        const urlPattern = url instanceof RegExp ? url.source : url;
+        for (let i = this._routes.length - 1; i >= 0; i--) {
+            const entry = this._routes[i];
+            if (entry && entry.urlPattern === urlPattern) {
+                if (handler === undefined || entry.handler === handler) {
+                    try {
+                        await this._client.execute('browser_remove_network_rule', {
+                            context_id: this._contextId,
+                            rule_id: entry.ruleId,
+                        });
+                    }
+                    catch {
+                        // Rule may already be removed
+                    }
+                    this._routes.splice(i, 1);
+                }
+            }
+        }
+    }
+    /** Remove all route handlers. */
+    async unrouteAll() {
+        for (const entry of this._routes) {
+            try {
+                await this._client.execute('browser_remove_network_rule', {
+                    context_id: this._contextId,
+                    rule_id: entry.ruleId,
+                });
+            }
+            catch {
+                // Ignore
+            }
+        }
+        this._routes.length = 0;
+    }
+    // ==================== Events ====================
+    /**
+     * Register an event handler.
+     *
+     * @param event - Event name ('dialog', 'console', 'download', etc.)
+     * @param handler - Event handler function
+     */
+    on(event, handler) {
+        const handlers = this._eventHandlers.get(event) ?? [];
+        handlers.push(handler);
+        this._eventHandlers.set(event, handlers);
+        // Start background polling when relevant event listeners are registered
+        if (event === 'dialog' && !this._dialogPollTimer) {
+            this._startDialogPolling();
+        }
+        if (event === 'console' && !this._consolePollTimer) {
+            this._startConsolePolling();
+        }
+        return this;
+    }
+    /**
+     * Register a one-time event handler.
+     *
+     * @param event - Event name
+     * @param handler - Event handler function (called once then removed)
+     */
+    once(event, handler) {
+        const wrapper = (...args) => {
+            this.off(event, wrapper);
+            return handler(...args);
+        };
+        return this.on(event, wrapper);
+    }
+    /**
+     * Remove an event handler.
+     *
+     * @param event - Event name
+     * @param handler - Handler to remove
+     */
+    off(event, handler) {
+        const handlers = this._eventHandlers.get(event);
+        if (handlers) {
+            const idx = handlers.indexOf(handler);
+            if (idx >= 0) {
+                handlers.splice(idx, 1);
+            }
+        }
+        return this;
+    }
+    /**
+     * Remove all event handlers for an event (or all events).
+     *
+     * @param event - Optional event name
+     */
+    removeAllListeners(event) {
+        if (event) {
+            this._eventHandlers.delete(event);
+        }
+        else {
+            this._eventHandlers.clear();
+        }
+        return this;
+    }
+    // ==================== Viewport & Emulation ====================
+    /** Set the viewport size. */
+    async setViewportSize(size) {
+        await this._client.execute('browser_set_viewport', {
+            context_id: this._contextId,
+            width: size.width,
+            height: size.height,
+        });
+        this._viewport = { ...size };
+    }
+    /**
+     * Emulate media features.
+     *
+     * @param options - Media emulation options (colorScheme, reducedMotion)
+     */
+    async emulateMedia(options) {
+        if (options?.colorScheme) {
+            await this.evaluate(`document.documentElement.style.colorScheme = '${options.colorScheme}'`);
+        }
+        // Media type and other options require CDP which Owl wraps differently
+    }
+    /**
+     * Set extra HTTP headers for all requests.
+     *
+     * No-op: Owl Browser does not support runtime header injection.
+     * Custom headers should be configured at context creation via VM profiles.
+     */
+    async setExtraHTTPHeaders(headers) {
+        void headers;
+        // Not supported — requires VM profile configuration at context creation
+    }
+    // ==================== Scrolling & Zoom ====================
+    /** Scroll by pixel delta. */
+    async scrollBy(deltaX, deltaY) {
+        const params = {
+            context_id: this._contextId,
+            y: Math.round(deltaY),
+        };
+        if (deltaX !== 0) {
+            params['x'] = Math.round(deltaX);
+        }
+        await this._client.execute('browser_scroll_by', params);
+    }
+    /** Scroll an element into view. */
+    async scrollToElement(selector) {
+        await this._client.execute('browser_scroll_to_element', {
+            context_id: this._contextId,
+            selector,
+        });
+    }
+    /** Scroll to the top of the page. */
+    async scrollToTop() {
+        await this._client.execute('browser_scroll_to_top', {
+            context_id: this._contextId,
+        });
+    }
+    /** Scroll to the bottom of the page. */
+    async scrollToBottom() {
+        await this._client.execute('browser_scroll_to_bottom', {
+            context_id: this._contextId,
+        });
+    }
+    /** Zoom in the page. */
+    async zoomIn() {
+        await this._client.execute('browser_zoom_in', {
+            context_id: this._contextId,
+        });
+    }
+    /** Zoom out the page. */
+    async zoomOut() {
+        await this._client.execute('browser_zoom_out', {
+            context_id: this._contextId,
+        });
+    }
+    /** Reset zoom to 100%. */
+    async zoomReset() {
+        await this._client.execute('browser_zoom_reset', {
+            context_id: this._contextId,
+        });
+    }
+    // ==================== Clipboard ====================
+    /** Read text from the clipboard. */
+    async clipboardRead() {
+        const result = await this._client.execute('browser_clipboard_read', {
+            context_id: this._contextId,
+        });
+        const res = result;
+        return String(res['text'] ?? res['content'] ?? '');
+    }
+    /** Write text to the clipboard. */
+    async clipboardWrite(text) {
+        await this._client.execute('browser_clipboard_write', {
+            context_id: this._contextId,
+            text,
+        });
+    }
+    /** Clear the clipboard. */
+    async clipboardClear() {
+        await this._client.execute('browser_clipboard_clear', {
+            context_id: this._contextId,
+        });
+    }
+    // ==================== Console ====================
+    /**
+     * Get console log entries.
+     *
+     * @param options - Filter options (level, filter text, limit)
+     * @returns Array of ConsoleMessage objects
+     */
+    async getConsoleMessages(options) {
+        const params = {
+            context_id: this._contextId,
+        };
+        if (options?.level)
+            params['level'] = options.level;
+        if (options?.filter)
+            params['filter'] = options.filter;
+        if (options?.limit !== undefined)
+            params['limit'] = String(options.limit);
+        const result = await this._client.execute('browser_get_console_log', params);
+        const res = result;
+        const logs = res['logs'] ?? res['entries'] ?? [];
+        if (!Array.isArray(logs))
+            return [];
+        return logs.map((entry) => {
+            const e = entry;
+            return new ConsoleMessage(String(e['level'] ?? 'log'), String(e['message'] ?? e['text'] ?? ''), e['url'], e['line'], e['column']);
+        });
+    }
+    /** Clear console logs. */
+    async clearConsole() {
+        await this._client.execute('browser_clear_console_log', {
+            context_id: this._contextId,
+        });
+    }
+    // ==================== Video ====================
+    /**
+     * Get the Video instance for this page (if recording is active).
+     *
+     * @returns Video instance or null
+     */
+    video() {
+        return this._video;
+    }
+    /**
+     * Start video recording for this page.
+     *
+     * @param options - Recording options (fps, codec)
+     */
+    async startVideoRecording(options) {
+        const params = {
+            context_id: this._contextId,
+        };
+        if (options?.fps !== undefined)
+            params['fps'] = String(options.fps);
+        if (options?.codec)
+            params['codec'] = options.codec;
+        await this._client.execute('browser_start_video_recording', params);
+        this._video = new Video(this._client, this._contextId);
+        return this._video;
+    }
+    /** Stop video recording. */
+    async stopVideoRecording() {
+        await this._client.execute('browser_stop_video_recording', {
+            context_id: this._contextId,
+        });
+    }
+    // ==================== Locators ====================
+    /** Create a Locator for the given selector. */
+    locator(selector) {
+        return new Locator(this, selector);
+    }
+    /** Query a single element (alias for locator). */
+    $(selector) {
+        return new Locator(this, selector);
+    }
+    /** Query all matching elements (returns locators for each match). */
+    async $$(selector) {
+        const loc = new Locator(this, selector);
+        const n = await loc.count();
+        const locators = [];
+        for (let i = 0; i < n; i++) {
+            locators.push(new NthLocator(this, loc._selector, i));
+        }
+        return locators;
+    }
+    /** Get a locator by text content. */
+    getByText(text, options) {
+        void options;
+        const textStr = text instanceof RegExp ? text.source : text;
+        return new Locator(this, `text=${textStr}`);
+    }
+    /** Get a locator by role. */
+    getByRole(role, options) {
+        if (options?.name) {
+            const name = options.name instanceof RegExp ? options.name.source : options.name;
+            return new Locator(this, `role=${role}[name="${name}"]`);
+        }
+        return new Locator(this, `role=${role}`);
+    }
+    /** Get a locator by placeholder text. */
+    getByPlaceholder(text, options) {
+        void options;
+        const textStr = text instanceof RegExp ? text.source : text;
+        return new Locator(this, `placeholder=${textStr}`);
+    }
+    /** Get a locator by label text. */
+    getByLabel(text, options) {
+        void options;
+        const textStr = text instanceof RegExp ? text.source : text;
+        return new Locator(this, `label=${textStr}`);
+    }
+    /** Get a locator by alt text. */
+    getByAltText(text, options) {
+        void options;
+        const textStr = text instanceof RegExp ? text.source : text;
+        return new Locator(this, `alt=${textStr}`);
+    }
+    /** Get a locator by title attribute. */
+    getByTitle(text, options) {
+        void options;
+        const textStr = text instanceof RegExp ? text.source : text;
+        return new Locator(this, `title=${textStr}`);
+    }
+    /** Get a locator by data-testid attribute. */
+    getByTestId(testId) {
+        const idStr = testId instanceof RegExp ? testId.source : testId;
+        return new Locator(this, `data-testid=${idStr}`);
+    }
+    // ==================== Frames ====================
+    /** Get all frames on the page (cached, returns main frame). */
+    frames() {
+        return [this._mainFrame];
+    }
+    /** Get all frames by querying the browser. */
+    async framesAsync() {
+        try {
+            const result = await this._client.execute('browser_list_frames', {
+                context_id: this._contextId,
+            });
+            // browser_list_frames returns a JSON array directly
+            const frames = Array.isArray(result) ? result : [];
+            if (frames.length === 0)
+                return [this._mainFrame];
+            return frames.map((f) => {
+                const entry = f;
+                const id = String(entry['frame_id'] ?? entry['id'] ?? '');
+                const name = String(entry['name'] ?? '');
+                return new Frame(this._client, this._contextId, id, name || id);
+            });
+        }
+        catch {
+            return [this._mainFrame];
+        }
+    }
+    /** Get a frame by name or URL. */
+    frame(nameOrUrl) {
+        if (typeof nameOrUrl === 'string') {
+            return new Frame(this._client, this._contextId, nameOrUrl, nameOrUrl);
+        }
+        const selector = nameOrUrl.name ?? '';
+        return new Frame(this._client, this._contextId, selector, selector);
+    }
+    /**
+     * Get a FrameLocator for interacting with iframe content.
+     *
+     * @param selector - CSS selector for the iframe element
+     * @returns A FrameLocator scoped to the iframe
+     */
+    frameLocator(selector) {
+        return new FrameLocator(this._client, this._contextId, selector, this);
+    }
+    // ==================== Tab Management ====================
+    /** Close the page/tab. */
+    async close() {
+        this._closed = true;
+        if (this._dialogPollTimer) {
+            clearTimeout(this._dialogPollTimer);
+            this._dialogPollTimer = null;
+        }
+        if (this._consolePollTimer) {
+            clearTimeout(this._consolePollTimer);
+            this._consolePollTimer = null;
+        }
+        if (this._tabId) {
+            try {
+                await this._client.execute('browser_close_tab', {
+                    context_id: this._contextId,
+                    tab_id: this._tabId,
+                });
+            }
+            catch {
+                // Tab may already be closed
+            }
+        }
+    }
+    /** Bring the page tab to front. */
+    async bringToFront() {
+        if (this._tabId) {
+            await this._client.execute('browser_switch_tab', {
+                context_id: this._contextId,
+                tab_id: this._tabId,
+            });
+        }
+    }
+    // ==================== Downloads ====================
+    /**
+     * Set the download directory path.
+     *
+     * @param path - Absolute directory path for downloads
+     */
+    async setDownloadPath(path) {
+        await this._client.execute('browser_set_download_path', {
+            context_id: this._contextId,
+            path,
+        });
+    }
+    /**
+     * Get all downloads for this context.
+     *
+     * @returns Array of Download objects
+     */
+    async getDownloads() {
+        const result = await this._client.execute('browser_get_downloads', {
+            context_id: this._contextId,
+        });
+        const res = result;
+        const downloads = res['downloads'] ?? [];
+        if (!Array.isArray(downloads))
+            return [];
+        return downloads.map((d) => {
+            const entry = d;
+            return new Download(this._client, this._contextId, String(entry['id'] ?? entry['download_id'] ?? ''), String(entry['url'] ?? ''), String(entry['filename'] ?? entry['suggested_filename'] ?? ''));
+        });
+    }
+    // ==================== Dialog Handling ====================
+    /**
+     * Configure automatic dialog handling.
+     *
+     * @param dialogType - Dialog type ('alert', 'confirm', 'prompt', 'beforeunload')
+     * @param action - Action ('accept', 'dismiss', 'accept_with_text')
+     * @param promptText - Text for prompt dialogs
+     */
+    async setDialogAction(dialogType, action, promptText) {
+        const params = {
+            context_id: this._contextId,
+            dialog_type: dialogType,
+            action,
+        };
+        if (promptText !== undefined) {
+            params['prompt_text'] = promptText;
+        }
+        await this._client.execute('browser_set_dialog_action', params);
+    }
+    // ==================== Internal Helpers ====================
+    /** Sync the internal URL cache with the actual page URL. */
+    async _syncUrl() {
+        try {
+            const result = await this._client.execute('browser_get_page_info', {
+                context_id: this._contextId,
+            });
+            const res = result;
+            if (typeof res['url'] === 'string') {
+                this._url = res['url'];
+            }
+        }
+        catch {
+            // Non-critical; URL cache may be stale
+        }
+    }
+    /** Start polling for dialogs and dispatching to event handlers. */
+    _startDialogPolling() {
+        // Set all dialog types to "wait" mode so dialogs stay pending for our poll
+        this._dialogSetupReady = Promise.allSettled(['alert', 'confirm', 'prompt', 'beforeunload'].map(dt => this._client.execute('browser_set_dialog_action', {
+            context_id: this._contextId,
+            dialog_type: dt,
+            action: 'wait',
+        }))).then(() => { });
+        const poll = async () => {
+            if (this._closed)
+                return;
+            try {
+                const result = await this._client.execute('browser_get_pending_dialog', {
+                    context_id: this._contextId,
+                });
+                const res = result;
+                const dialogType = res['dialog_type'] ?? res['type'];
+                if (dialogType) {
+                    const dialog = new Dialog(this._client, String(dialogType), String(res['message'] ?? ''), String(res['default_value'] ?? ''), String(res['dialog_id'] ?? res['id'] ?? ''));
+                    const handlers = this._eventHandlers.get('dialog') ?? [];
+                    for (const handler of handlers) {
+                        try {
+                            await handler(dialog);
+                        }
+                        catch {
+                            // Handler error; ignore
+                        }
+                    }
+                }
+            }
+            catch {
+                // No dialog pending or error; ignore
+            }
+            if (!this._closed) {
+                this._dialogPollTimer = setTimeout(poll, 250);
+            }
+        };
+        this._dialogPollTimer = setTimeout(poll, 250);
+    }
+    /** Start polling for console messages and dispatching to event handlers. */
+    _startConsolePolling() {
+        const poll = async () => {
+            if (this._closed)
+                return;
+            try {
+                const messages = await this.getConsoleMessages();
+                const newMessages = messages.slice(this._consoleLogOffset);
+                this._consoleLogOffset = messages.length;
+                const handlers = this._eventHandlers.get('console') ?? [];
+                for (const msg of newMessages) {
+                    for (const handler of handlers) {
+                        try {
+                            await handler(msg);
+                        }
+                        catch {
+                            // Handler error; ignore
+                        }
+                    }
+                }
+            }
+            catch {
+                // Error polling console; ignore
+            }
+            if (!this._closed) {
+                this._consolePollTimer = setTimeout(poll, 500);
+            }
+        };
+        this._consolePollTimer = setTimeout(poll, 500);
+    }
+    /** Wait for a download event. */
+    async _waitForDownload(timeout) {
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const result = await this._client.execute('browser_get_downloads', {
+                context_id: this._contextId,
+            });
+            const res = result;
+            const downloads = res['downloads'];
+            if (Array.isArray(downloads) && downloads.length > 0) {
+                const latest = downloads[downloads.length - 1];
+                return new Download(this._client, this._contextId, String(latest['id'] ?? latest['download_id'] ?? ''), String(latest['url'] ?? ''), String(latest['filename'] ?? latest['suggested_filename'] ?? ''));
+            }
+            await this.waitForTimeout(200);
+        }
+        throw new Error(`Timeout waiting for download (${timeout}ms)`);
+    }
+    /** Wait for a dialog event. */
+    async _waitForDialog(timeout) {
+        const params = {
+            context_id: this._contextId,
+        };
+        if (timeout) {
+            params['timeout'] = String(timeout);
+        }
+        const result = await this._client.execute('browser_wait_for_dialog', params);
+        const res = result;
+        return new Dialog(this._client, String(res['dialog_type'] ?? res['type'] ?? 'alert'), String(res['message'] ?? ''), String(res['default_value'] ?? ''), String(res['dialog_id'] ?? res['id'] ?? ''));
+    }
+    /** Wait for a console message event. */
+    async _waitForConsole(timeout) {
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const messages = await this.getConsoleMessages({ limit: 1 });
+            if (messages.length > 0 && messages[0]) {
+                return messages[0];
+            }
+            await this.waitForTimeout(200);
+        }
+        throw new Error(`Timeout waiting for console message (${timeout}ms)`);
+    }
+}
+/** Map Playwright waitUntil values to Owl Browser equivalents. */
+function mapWaitUntil(value) {
+    switch (value) {
+        case 'load':
+            return 'load';
+        case 'domcontentloaded':
+            return 'domcontentloaded';
+        case 'networkidle':
+            return 'networkidle';
+        case 'commit':
+            return '';
+        default:
+            return 'load';
+    }
+}
+/** Extract all option values from SelectOptionValue as an array. */
+function extractSelectValues(values) {
+    if (typeof values === 'string')
+        return [values];
+    if (Array.isArray(values)) {
+        return values.map((v) => {
+            if (typeof v === 'string')
+                return v;
+            return v.value ?? v.label ?? '';
+        }).filter(Boolean);
+    }
+    return [values.value ?? values.label ?? ''].filter(Boolean);
+}
+//# sourceMappingURL=page.js.map