chrome-e2e-sdk 0.0.0-stage → 1.0.0

package/dist/browser/Page.js

@@ -0,0 +1,979 @@
+import { MCPClient } from '../client/MCPClient.js';
+import { Locator } from './Locator.js';
+import { Network } from '../network/Network.js';
+import {} from '../network/Network.js';
+import { E2EError, E2EErrorCode } from '../errors/E2EError.js';
+import { readFile } from 'node:fs/promises';
+/** Snapshot node keys that describe the node itself rather than its attributes. */
+const SNAPSHOT_RESERVED_KEYS = new Set([
+    'id',
+    'uid',
+    'role',
+    'name',
+    'text',
+    'tagName',
+    'children',
+    'attributes',
+    'elementHandle',
+    'backendNodeId',
+    'loaderId'
+]);
+export class PageLocalStorage {
+    page;
+    constructor(page) {
+        this.page = page;
+    }
+    async setItem(key, value, options = {}) {
+        await this.page.evaluate(`(storageKey, storageValue) => {
+        window.localStorage.setItem(storageKey, storageValue)
+      }`, [key, value], options);
+    }
+    async getItem(key, options = {}) {
+        return this.page.evaluate(`(storageKey) => window.localStorage.getItem(storageKey)`, [key], options);
+    }
+    async removeItem(key, options = {}) {
+        await this.page.evaluate(`(storageKey) => {
+        window.localStorage.removeItem(storageKey)
+      }`, [key], options);
+    }
+    /** Keys currently present, in insertion order. */
+    async keys(options = {}) {
+        return this.page.evaluate(`() => Object.keys(window.localStorage)`, undefined, options);
+    }
+    async clear(options = {}) {
+        await this.page.evaluate(`() => {
+        window.localStorage.clear()
+      }`, undefined, options);
+    }
+}
+export class Page {
+    mcpClient;
+    pageId;
+    defaultTimeout;
+    closed = false;
+    networkInstance;
+    localStorageInstance;
+    _url = '';
+    _title = '';
+    _active = false;
+    logger;
+    constructor(mcpClient, pageId, defaultTimeout) {
+        this.mcpClient = mcpClient;
+        this.pageId = pageId;
+        this.defaultTimeout = defaultTimeout;
+        this.networkInstance = new Network(mcpClient, this.pageId, defaultTimeout);
+        this.localStorageInstance = new PageLocalStorage(this);
+        this.logger = this.createLogger();
+    }
+    createLogger() {
+        return (level, message) => {
+            if (process.env['DEBUG']?.includes('chrome-e2e')) {
+                console.error(`[ChromeE2E:Page:${this.pageId}] ${level.toUpperCase()}: ${message}`);
+            }
+        };
+    }
+    // Navigation
+    async goto(url, options) {
+        this.ensureNotClosed();
+        const timeout = options?.timeout ?? this.defaultTimeout;
+        this.logger('debug', `Navigating to: ${url}`);
+        try {
+            const result = await this.withTimeout(this.mcpClient.call('navigate_page', { pageId: this.pageId, type: 'url', url }), timeout, `Navigation to ${url}`);
+            // chrome-devtools-mcp reports navigation problems as a response line instead
+            // of raising, so the message has to be inspected to surface the failure.
+            const failure = this.parseNavigationFailure(result);
+            if (failure) {
+                throw E2EError.navigationError(url, new Error(failure));
+            }
+            await this.waitForLoadState(options?.waitUntil ?? 'load', { timeout });
+            // The title is invalidated because the document was replaced. The URL is
+            // not overwritten with the requested one: the browser may have redirected,
+            // normalised the trailing slash, or dropped a fragment, and a cache
+            // holding the request instead of the destination is what made url()
+            // disagree with the page.
+            this._title = '';
+        }
+        catch (err) {
+            if (err instanceof E2EError) {
+                throw err;
+            }
+            throw E2EError.navigationError(url, err instanceof Error ? err : undefined);
+        }
+    }
+    async reload(options) {
+        this.ensureNotClosed();
+        const timeout = options?.timeout ?? this.defaultTimeout;
+        this.logger('debug', 'Reloading page');
+        await this.withTimeout(this.mcpClient.call('navigate_page', { pageId: this.pageId, type: 'reload' }), timeout, 'Page reload');
+    }
+    async back(options) {
+        this.ensureNotClosed();
+        const timeout = options?.timeout ?? this.defaultTimeout;
+        this.logger('debug', 'Going back');
+        await this.withTimeout(this.mcpClient.call('navigate_page', { pageId: this.pageId, type: 'back' }), timeout, 'Go back');
+    }
+    async forward(options) {
+        this.ensureNotClosed();
+        const timeout = options?.timeout ?? this.defaultTimeout;
+        this.logger('debug', 'Going forward');
+        await this.withTimeout(this.mcpClient.call('navigate_page', { pageId: this.pageId, type: 'forward' }), timeout, 'Go forward');
+    }
+    async waitForTimeout(timeout) {
+        if (!Number.isFinite(timeout) || timeout < 0) {
+            throw E2EError.invalidArgument('timeout', 'non-negative number', timeout);
+        }
+        await new Promise((resolve) => setTimeout(resolve, timeout));
+    }
+    async waitForURL(url, options = {}) {
+        this.ensureNotClosed();
+        const timeout = options.timeout ?? this.defaultTimeout;
+        const startedAt = Date.now();
+        // A wait is nearly always called right after triggering a navigation, which
+        // is exactly when the execution context is torn down and evaluate throws.
+        // That is a transient state, not a failure, so it is swallowed and the poll
+        // continues; only the timeout is allowed to end it.
+        let lastError;
+        while (Date.now() - startedAt < timeout) {
+            try {
+                const currentURL = await this.evaluate('() => ({ url: window.location.href })');
+                if (this.matchesURL(currentURL, url)) {
+                    return;
+                }
+                lastError = undefined;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : String(error);
+            }
+            await this.waitForTimeout(100);
+        }
+        const suffix = lastError ? ` (last read failed: ${firstLine(lastError)})` : '';
+        throw E2EError.timeout(`Wait for URL: ${this.describeURLMatcher(url)}${suffix}`, timeout, { lastError });
+    }
+    async waitForLoadState(state = 'load', options = {}) {
+        this.ensureNotClosed();
+        const timeout = options.timeout ?? this.defaultTimeout;
+        const startedAt = Date.now();
+        // Kept so the timeout can say what the page was actually doing. A bare
+        // "load timed out" is indistinguishable from a hung browser, a blocked
+        // subresource and a page that never started navigating.
+        let lastReadyState;
+        while (Date.now() - startedAt < timeout) {
+            lastReadyState = await this.evaluate('() => document.readyState');
+            if (this.matchesLoadState(lastReadyState, state)) {
+                return;
+            }
+            await this.waitForTimeout(100);
+        }
+        // Read only on failure. Polling for it would double the round-trips of
+        // every successful wait to produce a message nobody sees.
+        const url = await this.url().catch(() => undefined);
+        throw E2EError.timeout(`Wait for load state "${state}" on ${url ?? 'unknown URL'}: ` +
+            `still at readyState "${lastReadyState ?? 'unknown'}" after ${timeout}ms. ` +
+            `"load" waits for every subresource, so one slow request is enough; ` +
+            `retry with waitUntil: 'domcontentloaded'.`, timeout, { state, readyState: lastReadyState, url, pageId: this.pageId });
+    }
+    waitForRequest(options) {
+        return this.network.waitForRequest(options);
+    }
+    waitForResponse(options) {
+        return this.network.waitForResponse(options);
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.logger('debug', 'Closing page');
+        try {
+            await this.mcpClient.call('close_page', { pageId: this.pageId });
+        }
+        catch {
+            // ignore
+        }
+        this.closed = true;
+    }
+    // Page info
+    //
+    // Both of these read live rather than serving a cache. The cache went stale
+    // after any navigation the SDK did not perform itself - a form submit, a
+    // link click, history.pushState - and even straight after goto(), which
+    // stored the URL that was requested instead of the one the browser landed
+    // on. toHaveURL() and toHaveURLContaining() read url(), so after submitting
+    // a search they compared against the pre-submit address and polled until
+    // they timed out, on a page that had navigated correctly.
+    async url() {
+        this.ensureNotClosed();
+        try {
+            const result = await this.evaluate('() => ({ url: window.location.href })');
+            if (result.url) {
+                this._url = result.url;
+                return result.url;
+            }
+        }
+        catch {
+            // Mid-navigation, or the page is gone. The last known value beats
+            // nothing, and the caller is about to be told the wait timed out anyway.
+        }
+        return this._url;
+    }
+    async title() {
+        this.ensureNotClosed();
+        try {
+            const result = await this.evaluate('() => ({ title: document.title })');
+            if (result.title) {
+                this._title = result.title;
+                return result.title;
+            }
+        }
+        catch {
+            // Same reasoning as url(): a best-effort read, never a hard failure.
+        }
+        return this._title;
+    }
+    isActive() {
+        return this._active;
+    }
+    /**
+     * Update cached page info without replacing the instance, so Locator and
+     * Network objects created from this page stay attached to it.
+     *
+     * @internal
+     */
+    updatePageInfo(url, title, active) {
+        if (url !== undefined)
+            this._url = url;
+        if (title !== undefined)
+            this._title = title;
+        if (active !== undefined)
+            this._active = active;
+    }
+    // Snapshot & Screenshot
+    async snapshot() {
+        this.ensureNotClosed();
+        this.logger('debug', 'Taking page snapshot');
+        const result = await this.mcpClient.call('take_snapshot', {
+            pageId: this.pageId,
+            verbose: true
+        });
+        return this.parseSnapshot(result);
+    }
+    async screenshot(options = {}) {
+        this.ensureNotClosed();
+        this.logger('debug', 'Taking screenshot');
+        const result = await this.mcpClient.call('take_screenshot', {
+            pageId: this.pageId,
+            fullPage: options.fullPage ?? false,
+            format: options.type ?? 'png',
+            // quality is ignored for PNG and rejected for unknown values upstream
+            ...(options.type && options.type !== 'png' && options.quality !== undefined
+                ? { quality: options.quality }
+                : {})
+        });
+        if (typeof result === 'string') {
+            return this.readSavedScreenshot(result);
+        }
+        // Convert base64 to Buffer
+        const base64Data = result.data.replace(/^data:image\/\w+;base64,/, '');
+        return Buffer.from(base64Data, 'base64');
+    }
+    /**
+     * Screenshot a single element identified by its snapshot uid.
+     * Shared with `Locator.screenshot()` so both handle the base64 and the
+     * "saved to file" response shapes identically.
+     *
+     * @internal
+     */
+    async screenshotElement(uid, options = {}) {
+        this.ensureNotClosed();
+        const result = await this.mcpClient.call('take_screenshot', {
+            pageId: this.pageId,
+            uid,
+            format: 'png'
+        });
+        if (typeof result === 'string') {
+            return this.readSavedScreenshot(result);
+        }
+        const base64Data = result.data.replace(/^data:image\/\w+;base64,/, '');
+        return Buffer.from(base64Data, 'base64');
+    }
+    async resize(options) {
+        this.ensureNotClosed();
+        const timeout = options.timeout ?? this.defaultTimeout;
+        await this.withTimeout(this.mcpClient.call('resize_page', {
+            pageId: this.pageId,
+            width: options.width,
+            height: options.height
+        }), timeout, `Resize page to ${options.width}x${options.height}`);
+    }
+    // Locator factory methods
+    getByText(text, options) {
+        return new Locator(this, { text, exact: options?.exact });
+    }
+    getByRole(role, options) {
+        return new Locator(this, { role, name: options?.name, exact: options?.exact });
+    }
+    getByLabel(label, options) {
+        return new Locator(this, { label, exact: options?.exact });
+    }
+    locator(selector) {
+        return new Locator(this, { css: selector });
+    }
+    click(selector, options) {
+        return new Locator(this, this.toSelector(selector, options)).click(options);
+    }
+    fill(selector, value, options) {
+        return new Locator(this, this.toSelector(selector, options)).fill(value, options);
+    }
+    toSelector(selector, options) {
+        if (typeof selector === 'string') {
+            return { text: selector, exact: options?.exact };
+        }
+        return {
+            ...selector,
+            exact: selector.exact ?? options?.exact
+        };
+    }
+    /**
+     * Resolve a selector to a Chrome DevTools node uid.
+     * CSS and label selectors go through injected scripts; role, name and text
+     * selectors are matched against the a11y snapshot.
+     *
+     * @internal
+     */
+    async resolve(selector) {
+        this.ensureNotClosed();
+        this.logger('debug', `Resolving selector: ${JSON.stringify(selector)}`);
+        if (selector.css) {
+            return this.resolveCssSelector(selector);
+        }
+        if (selector.label) {
+            return this.resolveLabelSelector(selector);
+        }
+        // Take snapshot to get current DOM
+        const snapshot = await this.snapshot();
+        // Find matching element
+        const element = this.findElement(snapshot, selector);
+        if (!element) {
+            throw E2EError.elementNotFound(selector, this._url);
+        }
+        return { uid: element.uid };
+    }
+    /** @internal */
+    async callTool(name, arguments_) {
+        this.ensureNotClosed();
+        const result = await this.mcpClient.call(name, arguments_);
+        // evaluate_script is the one tool whose "structured" content is not
+        // structured: upstream has no field for it and drops the whole reply,
+        // fenced value and all, into `message`. Every caller of that tool assumes
+        // it got the script's return value, so the envelope is unwrapped here
+        // rather than at each of the ten call sites.
+        return (name === 'evaluate_script' ? unwrapScriptResult(result) : result);
+    }
+    /** @internal */
+    async evaluateLocator(selector, body, operation, options = {}) {
+        const timeout = options.timeout ?? this.defaultTimeout;
+        if (selector.css) {
+            return this.withTimeout(this.callTool('evaluate_script', {
+                pageId: this.pageId,
+                function: `() => {
+            const elements = Array.from(document.querySelectorAll(${JSON.stringify(selector.css)}));
+            const element = elements[${selector.index ?? 0}];
+            if (!element) return false;
+            ${body}
+          }`,
+                waitForStableDom: false
+            }), timeout, operation).then((result) => {
+                if (result === false) {
+                    throw E2EError.elementNotFound(selector);
+                }
+                return result;
+            });
+        }
+        if (selector.label) {
+            return this.withTimeout(this.callTool('evaluate_script', {
+                pageId: this.pageId,
+                function: `() => {
+            ${this.labelFinderSource(selector)}
+            const element = findByLabel();
+            if (!element) return false;
+            ${body}
+          }`,
+                waitForStableDom: false
+            }), timeout, operation).then((result) => {
+                if (result === false) {
+                    throw E2EError.elementNotFound(selector);
+                }
+                return result;
+            });
+        }
+        throw E2EError.invalidArgument('selector', 'one of role, name, text, label or css', selector);
+    }
+    /**
+     * Injected helper that locates the form control a visible label refers to.
+     *
+     * Covers the shapes `getByLabel` has to survive in real pages: `aria-label`,
+     * `<label for>` / wrapping labels, and components that render a label
+     * element next to the input inside a `.el-form-item`-style row.
+     */
+    labelFinderSource(selector) {
+        return `
+      const expected = ${JSON.stringify(selector.label)};
+      const exact = ${JSON.stringify(selector.exact ?? false)};
+      const index = ${selector.index ?? 0};
+      const controlSelector = 'input, textarea, select, [contenteditable="true"], [role="textbox"]';
+      const normalize = (value) => (value ?? '').replace(/\\s+/g, ' ').trim();
+      const matches = (value) => {
+        const text = normalize(value);
+        return exact ? text === expected : text.includes(expected);
+      };
+      const ownText = (node) => normalize(Array.from(node.childNodes)
+        .filter((child) => child.nodeType === Node.TEXT_NODE)
+        .map((child) => child.textContent)
+        .join(' '));
+      const findControlNear = (node) => {
+        if (!node) return null;
+        if (node.matches?.(controlSelector)) return node;
+        const inside = node.querySelector?.(controlSelector);
+        if (inside) return inside;
+        const container = node.closest?.('.w-search-item, .el-form-item, [class*="search-item"], [class*="form-item"], label, td, tr, li, div');
+        return container?.querySelector?.(controlSelector) ?? null;
+      };
+      const unique = (elements) => Array.from(new Set(elements));
+      const findByLabel = () => {
+        const matchesByAria = Array.from(document.querySelectorAll(controlSelector))
+          .filter((element) => matches(element.getAttribute('aria-label')));
+        const nativeLabelMatches = Array.from(document.querySelectorAll('label'))
+          .filter((element) => matches(element.textContent))
+          .map((element) => element.htmlFor ? document.getElementById(element.htmlFor) : findControlNear(element))
+          .filter(Boolean);
+        const directTextMatches = Array.from(document.querySelectorAll('body *'))
+          .filter((element) => matches(ownText(element)))
+          .map((element) => findControlNear(element))
+          .filter(Boolean);
+        const descendantTextMatches = Array.from(document.querySelectorAll('body *'))
+          .filter((element) => matches(element.textContent))
+          .sort((left, right) => left.querySelectorAll('*').length - right.querySelectorAll('*').length)
+          .map((element) => findControlNear(element))
+          .filter(Boolean);
+        return unique([...matchesByAria, ...nativeLabelMatches, ...directTextMatches, ...descendantTextMatches])[index] ?? null;
+      };
+    `;
+    }
+    findElement(snapshot, selector) {
+        for (const node of snapshot.nodes) {
+            // Match by role
+            if (selector.role && node.role === selector.role) {
+                if (!selector.name || this.matchName(node.name, selector.name, selector.exact)) {
+                    return { uid: node.uid };
+                }
+            }
+            // Match by text
+            if (selector.text && node.text && this.matchName(node.text, selector.text, selector.exact)) {
+                return { uid: node.uid };
+            }
+            // Match by label (aria-label, aria-labelledby, etc.)
+            if (selector.label && node.attributes) {
+                const ariaLabel = node.attributes['aria-label'] || node.attributes['aria-labelledby'];
+                if (ariaLabel && this.matchName(ariaLabel, selector.label, selector.exact)) {
+                    return { uid: node.uid };
+                }
+            }
+        }
+        return null;
+    }
+    async resolveCssSelector(selector) {
+        return this.resolveViaMarker(selector, `
+      const elements = Array.from(document.querySelectorAll(${JSON.stringify(selector.css)}));
+      const element = elements[${selector.index ?? 0}];
+    `);
+    }
+    async resolveLabelSelector(selector) {
+        return this.resolveViaMarker(selector, `
+      ${this.labelFinderSource(selector)}
+      const element = findByLabel();
+    `);
+    }
+    /**
+     * Tag the target element with a throwaway attribute, read its snapshot uid
+     * back, then remove the attribute. `evaluate_script` only accepts element
+     * uids as arguments, so this is how a CSS or label selector is turned into
+     * something the uid-based tools understand.
+     */
+    async resolveViaMarker(selector, findSource) {
+        const marker = `chrome-e2e-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        const marked = await this.callTool('evaluate_script', {
+            pageId: this.pageId,
+            function: `() => {
+        ${findSource}
+        if (!element) return false;
+        element.setAttribute('data-chrome-e2e-resolve', ${JSON.stringify(marker)});
+        return true;
+      }`,
+            waitForStableDom: false
+        });
+        if (marked === false) {
+            throw E2EError.elementNotFound(selector, this._url);
+        }
+        try {
+            const snapshot = await this.snapshot();
+            const element = snapshot.nodes.find((node) => node.attributes?.['data-chrome-e2e-resolve'] === marker);
+            if (!element) {
+                throw E2EError.elementNotFound(selector, this._url);
+            }
+            return { uid: element.uid };
+        }
+        finally {
+            await this.callTool('evaluate_script', {
+                pageId: this.pageId,
+                function: `() => {
+          document.querySelectorAll(${JSON.stringify(`[data-chrome-e2e-resolve="${marker}"]`)}).forEach((element) => {
+            element.removeAttribute('data-chrome-e2e-resolve');
+          });
+          return true;
+        }`,
+                waitForStableDom: false
+            })
+                .catch(() => undefined);
+        }
+    }
+    parseNavigationFailure(result) {
+        if (typeof result !== 'string') {
+            return null;
+        }
+        const match = result.match(/Unable to navigate[^:]*:\s*(.+)/);
+        return match?.[1]?.trim() ?? null;
+    }
+    matchName(actual, expected, exact = false) {
+        if (!actual)
+            return false;
+        if (exact)
+            return actual === expected;
+        return actual.includes(expected);
+    }
+    matchesURL(actual, expected) {
+        const actualURL = typeof actual === 'string' ? actual : actual.url;
+        if (typeof expected === 'function') {
+            return expected(actualURL);
+        }
+        if (expected instanceof RegExp) {
+            return expected.test(actualURL);
+        }
+        return actualURL.includes(expected);
+    }
+    describeURLMatcher(matcher) {
+        if (typeof matcher === 'function')
+            return 'function';
+        if (matcher instanceof RegExp)
+            return matcher.toString();
+        return matcher;
+    }
+    matchesLoadState(actual, expected) {
+        if (expected === 'domcontentloaded') {
+            return actual === 'interactive' || actual === 'complete';
+        }
+        if (expected === 'networkidle') {
+            return actual === 'complete';
+        }
+        return actual === 'complete';
+    }
+    // Wait for any of the given texts to appear on the page
+    async waitForText(texts, options = {}) {
+        this.ensureNotClosed();
+        const list = Array.isArray(texts) ? texts : [texts];
+        if (list.length === 0) {
+            throw E2EError.invalidArgument('texts', 'non-empty string or string[]', list);
+        }
+        const timeout = options.timeout ?? this.defaultTimeout;
+        await this.withTimeout(this.callTool('wait_for', { pageId: this.pageId, text: list, timeout }), timeout, `Wait for text: ${list.join(' | ')}`);
+    }
+    /**
+     * Fill several form controls in one call. `chrome-devtools-mcp` documents
+     * `fill_form` as strongly preferred over repeated `fill` calls: it is faster
+     * and more reliable because every control is resolved from one snapshot.
+     */
+    async fillForm(fields, options = {}) {
+        this.ensureNotClosed();
+        if (!Array.isArray(fields) || fields.length === 0) {
+            throw E2EError.invalidArgument('fields', 'non-empty array of { label | uid, value }', fields);
+        }
+        const timeout = options.timeout ?? this.defaultTimeout;
+        const explicit = new Map();
+        const labels = new Map();
+        fields.forEach((field, index) => {
+            if ('uid' in field && field.uid) {
+                explicit.set(index, field.uid);
+            }
+            else {
+                labels.set(index, field.label);
+            }
+        });
+        // Label lookups are marked in one script and read back from a single
+        // snapshot, so a multi-field form costs one snapshot instead of one each.
+        const resolved = labels.size > 0 ? await this.resolveLabels([...labels.values()]) : new Map();
+        const elements = fields.map((field, index) => ({
+            uid: explicit.get(index) ?? resolved.get(index),
+            value: field.value
+        }));
+        await this.withTimeout(this.callTool('fill_form', { pageId: this.pageId, elements }), timeout, `Fill form (${fields.length} fields)`);
+    }
+    /**
+     * Resolve several label selectors at once: mark every match, take a single
+     * snapshot, then read each uid back and clean up.
+     */
+    async resolveLabels(labels) {
+        const marker = `chrome-e2e-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        const attribute = 'data-chrome-e2e-resolve';
+        const source = labels.map((label, index) => {
+            const selector = { label };
+            return `
+        {
+          ${this.labelFinderSource(selector)}
+          const target = findByLabel();
+          if (target) target.setAttribute(${JSON.stringify(attribute)}, ${JSON.stringify(`${marker}-${index}`)});
+        }`;
+        }).join('\n');
+        await this.callTool('evaluate_script', {
+            pageId: this.pageId,
+            function: `() => {
+        ${source}
+        return true;
+      }`,
+            waitForStableDom: false
+        });
+        try {
+            const snapshot = await this.snapshot();
+            const byMarker = new Map();
+            for (const node of snapshot.nodes) {
+                const value = node.attributes?.[attribute];
+                if (value)
+                    byMarker.set(value, node.uid);
+            }
+            const result = new Map();
+            labels.forEach((label, index) => {
+                const uid = byMarker.get(`${marker}-${index}`);
+                if (!uid) {
+                    throw E2EError.elementNotFound({ label }, this._url);
+                }
+                result.set(index, uid);
+            });
+            return result;
+        }
+        finally {
+            await this.callTool('evaluate_script', {
+                pageId: this.pageId,
+                function: `() => {
+          document.querySelectorAll(${JSON.stringify(`[${attribute}^="${marker}-"]`)}).forEach((element) => {
+            element.removeAttribute(${JSON.stringify(attribute)});
+          });
+          return true;
+        }`,
+                waitForStableDom: false
+            }).catch(() => undefined);
+        }
+    }
+    /**
+     * Emulate network, CPU, user agent, colour scheme, viewport or geolocation.
+     * Omitting a key leaves that dimension untouched upstream; `clearEmulation()`
+     * resets all of them at once.
+     */
+    async emulate(options = {}) {
+        this.ensureNotClosed();
+        const timeout = options.timeout ?? this.defaultTimeout;
+        const params = { pageId: this.pageId };
+        if (options.networkConditions !== undefined)
+            params['networkConditions'] = options.networkConditions;
+        if (options.cpuThrottlingRate !== undefined)
+            params['cpuThrottlingRate'] = options.cpuThrottlingRate;
+        if (options.userAgent !== undefined)
+            params['userAgent'] = options.userAgent;
+        if (options.colorScheme !== undefined)
+            params['colorScheme'] = options.colorScheme;
+        if (options.viewport !== undefined)
+            params['viewport'] = options.viewport;
+        if (options.geolocation !== undefined)
+            params['geolocation'] = options.geolocation;
+        await this.withTimeout(this.callTool('emulate', params), timeout, 'Emulate');
+    }
+    /** Reset every emulated dimension. */
+    async clearEmulation(options = {}) {
+        this.ensureNotClosed();
+        const timeout = options.timeout ?? this.defaultTimeout;
+        await this.withTimeout(this.callTool('emulate', { pageId: this.pageId }), timeout, 'Clear emulation');
+    }
+    /** Fetch one console message with its arguments and stack trace. */
+    async getConsoleMessage(messageId) {
+        this.ensureNotClosed();
+        const result = await this.mcpClient.call('get_console_message', { pageId: this.pageId, msgid: messageId });
+        if (typeof result === 'object' && result !== null && result.consoleMessage) {
+            return result.consoleMessage;
+        }
+        if (typeof result === 'string') {
+            return this.parseDetailedConsoleMessage(result, messageId);
+        }
+        throw E2EError.mcpError(`get_console_message returned no message for id ${messageId}`);
+    }
+    // Network access
+    get network() {
+        return this.networkInstance;
+    }
+    get localStorage() {
+        return this.localStorageInstance;
+    }
+    // Console messages
+    async consoleMessages(options = {}) {
+        this.ensureNotClosed();
+        const result = await this.mcpClient.call('list_console_messages', {
+            pageId: this.pageId,
+            includeStackTraces: options.includeStackTraces ?? false
+        });
+        if (Array.isArray(result))
+            return result;
+        if (typeof result === 'object' && result !== null && Array.isArray(result.consoleMessages)) {
+            return result.consoleMessages;
+        }
+        return this.parseConsoleMessages(String(result));
+    }
+    // Evaluate script in page context
+    async evaluate(script, args, options) {
+        this.ensureNotClosed();
+        const timeout = options?.timeout ?? this.defaultTimeout;
+        if (!args || args.length === 0) {
+            return this.withTimeout(this.callTool('evaluate_script', { pageId: this.pageId, function: script }), timeout, 'Evaluate script');
+        }
+        return this.withTimeout(this.callTool('evaluate_script', {
+            pageId: this.pageId,
+            function: `() => {
+          const fn = (${script});
+          return fn(...${JSON.stringify(args)});
+        }`
+        }), timeout, 'Evaluate script');
+    }
+    // Page ID getter
+    getPageId() {
+        return this.pageId;
+    }
+    isClosed() {
+        return this.closed;
+    }
+    getDefaultTimeout() {
+        return this.defaultTimeout;
+    }
+    setDefaultTimeout(timeout) {
+        if (!Number.isFinite(timeout) || timeout < 0) {
+            throw E2EError.invalidArgument('timeout', 'non-negative number', timeout);
+        }
+        this.defaultTimeout = timeout;
+        this.networkInstance.setDefaultTimeout(timeout);
+    }
+    ensureNotClosed() {
+        if (this.closed) {
+            throw E2EError.browserClosed();
+        }
+    }
+    parseSnapshot(result) {
+        if (typeof result === 'object' && result !== null && result.snapshot) {
+            return this.parseStructuredSnapshot(result.snapshot);
+        }
+        const text = String(result);
+        const nodes = [];
+        for (const line of text.split(/\r?\n/)) {
+            const uidMatch = line.match(/uid=([^\s]+)/);
+            const uid = uidMatch?.[1];
+            if (!uid)
+                continue;
+            const rest = line.slice(line.indexOf(uidMatch[0]) + uidMatch[0].length).trim();
+            const role = rest.match(/^([^\s"]+)/)?.[1] ?? '';
+            const name = rest.match(/"([^"]*)"/)?.[1];
+            const attributes = Object.fromEntries(Array.from(rest.matchAll(/\s([a-zA-Z][\w-]*)="([^"]*)"/g))
+                .filter((match) => match[1] && match[2] !== undefined)
+                .map((match) => [match[1], match[2]]));
+            nodes.push({
+                uid,
+                tagName: role,
+                attributes,
+                children: [],
+                text: name,
+                role,
+                name
+            });
+        }
+        return { nodes };
+    }
+    parseStructuredSnapshot(snapshot) {
+        // `chrome-devtools-mcp` returns a single nested tree rooted at the document node.
+        if (typeof snapshot === 'object' && snapshot !== null && !Array.isArray(snapshot)) {
+            return { nodes: this.flattenSnapshotNodes(snapshot) };
+        }
+        if (Array.isArray(snapshot)) {
+            return {
+                nodes: snapshot
+                    .filter((node) => typeof node === 'object' && node !== null)
+                    .flatMap((node) => this.flattenSnapshotNodes(node))
+            };
+        }
+        return this.parseSnapshot(String(snapshot));
+    }
+    flattenSnapshotNodes(node) {
+        const normalized = this.normalizeSnapshotNode(node);
+        const children = Array.isArray(node['children']) ? node['children'] : [];
+        return [
+            normalized,
+            ...children
+                .filter((child) => typeof child === 'object' && child !== null)
+                .flatMap((child) => this.flattenSnapshotNodes(child))
+        ];
+    }
+    /**
+     * `chrome-devtools-mcp` serializes each snapshot node as a flat object where
+     * `id`, `role` and `name` sit next to every extracted DOM attribute
+     * (`aria-label`, `placeholder`, `disabled`, ...). Both that flat shape and a
+     * nested `attributes` object are accepted.
+     */
+    normalizeSnapshotNode(node) {
+        const uid = String(node['uid'] ?? node['id'] ?? '');
+        const role = typeof node['role'] === 'string' ? node['role'] : '';
+        const name = typeof node['name'] === 'string' ? node['name'] : undefined;
+        const text = typeof node['text'] === 'string' ? node['text'] : name;
+        const attributes = {};
+        for (const [key, value] of Object.entries(node)) {
+            if (SNAPSHOT_RESERVED_KEYS.has(key))
+                continue;
+            if (value === null || value === undefined)
+                continue;
+            if (typeof value === 'object')
+                continue;
+            attributes[key] = String(value);
+        }
+        if (typeof node['attributes'] === 'object' && node['attributes'] !== null) {
+            for (const [key, value] of Object.entries(node['attributes'])) {
+                attributes[key] = String(value);
+            }
+        }
+        return {
+            uid,
+            tagName: typeof node['tagName'] === 'string' ? node['tagName'] : role,
+            attributes,
+            // Children are nested node objects upstream; expose their uids for traversal.
+            children: Array.isArray(node['children'])
+                ? node['children']
+                    .map((child) => typeof child === 'object' && child !== null
+                    ? String(child['id'] ?? child['uid'] ?? '')
+                    : String(child))
+                    .filter(Boolean)
+                : [],
+            text,
+            role,
+            name
+        };
+    }
+    parseConsoleMessages(text) {
+        const messages = [];
+        for (const line of text.split(/\r?\n/)) {
+            const match = line.match(/^msgid=(\d+)\s+\[([^\]]+)\]\s+(.*?)\s+\((\d+)\s+args\)(?:\s+\[(\d+) times\])?/);
+            if (match?.[2] && match[3] !== undefined) {
+                messages.push({
+                    id: match[1] ? Number(match[1]) : undefined,
+                    type: match[2],
+                    text: match[3],
+                    argsCount: match[4] ? Number(match[4]) : undefined,
+                    count: match[5] ? Number(match[5]) : undefined
+                });
+            }
+        }
+        return messages;
+    }
+    /**
+     * `get_console_message` answers with text when structured content is off:
+     *
+     * ```text
+     * ID: 7
+     * Message: error> Uncaught TypeError
+     * ### Arguments
+     * Arg #0: undefined
+     * ### Stack trace
+     * at ...
+     * ```
+     */
+    parseDetailedConsoleMessage(text, messageId) {
+        const id = Number(text.match(/^ID:\s*(\d+)/m)?.[1] ?? messageId);
+        const messageLine = text.match(/^Message:\s*([a-z]+)>(.*)$/m);
+        if (!messageLine) {
+            throw E2EError.mcpError(`Could not parse get_console_message response for id ${messageId}`);
+        }
+        const detail = {
+            id,
+            type: messageLine[1] ?? 'log',
+            text: (messageLine[2] ?? '').trim()
+        };
+        const argsBlock = text.match(/### Arguments\n([\s\S]*?)(?=\n###|$)/);
+        if (argsBlock?.[1]) {
+            detail.args = argsBlock[1]
+                .split('\n')
+                .map((line) => line.replace(/^Arg #\d+:\s*/, '').trim())
+                .filter(Boolean);
+        }
+        const stackBlock = text.match(/### Stack trace\n([\s\S]*?)(?=\n###|$)/);
+        if (stackBlock?.[1]) {
+            detail.stackTrace = stackBlock[1].trim();
+        }
+        return detail;
+    }
+    async readSavedScreenshot(text) {
+        const match = text.match(/Saved screenshot to (.+?)(?:\r?\n|$)/);
+        if (!match?.[1]) {
+            throw E2EError.mcpError('Screenshot response did not include image data or a saved file path');
+        }
+        return readFile(match[1].replace(/\.$/, ''));
+    }
+    async withTimeout(promise, ms, operation) {
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => reject(E2EError.timeout(operation, ms)), ms);
+        });
+        try {
+            return await Promise.race([promise, timeoutPromise]);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+/** The first line of a message, so an error stays readable on one line. */
+function firstLine(message) {
+    return message.split('\n')[0]?.trim() ?? message;
+}
+/**
+ * Unwraps the envelope `evaluate_script` returns.
+ *
+ * The tool has no dedicated structured field, so upstream falls back to
+ * `structuredContent.message` and leaves the whole human-readable reply in it,
+ * fenced value included:
+ *
+ *   { message: 'Script ran on page and returned:\n```json\n"complete"\n```' }
+ *
+ * Returning that verbatim makes every caller believe the script returned an
+ * object. `waitForLoadState` compared it against 'complete', never matched, and
+ * polled until the timeout fired on a page that had in fact loaded instantly.
+ * Every other evaluate-backed helper was silently broken the same way.
+ */
+export function unwrapScriptResult(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return raw;
+    }
+    const message = raw.message;
+    if (typeof message !== 'string') {
+        return raw;
+    }
+    const fenced = message.match(/```json\s*([\s\S]*?)\s*```/);
+    if (!fenced?.[1]) {
+        // No fenced value: the script threw, or wrote a file. Either way the
+        // message itself is the useful part, so pass it through as text.
+        return message;
+    }
+    try {
+        return JSON.parse(fenced[1]);
+    }
+    catch {
+        return message;
+    }
+}
+//# sourceMappingURL=Page.js.map