neoagent 3.2.1-beta.1 → 3.2.1-beta.3

package/server/services/browser/controller.js

@@ -1,7 +1,11 @@
+'use strict';
+
 const path = require('path');
 const fs = require('fs');
 const { spawn } = require('child_process');
 const { DATA_DIR } = require('../../../runtime/paths');
+const { validateCloudUrlWithDns } = require('../../utils/cloud-security');
+const { runProcess } = require('../android/process');
 const {
   chooseBrowserIdentity,
   detectBotChallenge,
@@ -127,40 +131,66 @@ function resolveBrowserExecutablePath() {
   return platformCandidates.find((candidate) => fs.existsSync(candidate)) || null;
 }
 
-function installPlaywrightBrowserBinary(browserName) {
+async function installPlaywrightBrowserBinary(browserName, options = {}) {
   const packageRoot = path.dirname(require.resolve('playwright-chromium/package.json'));
   const cliPath = path.join(packageRoot, 'cli.js');
-  return new Promise((resolve, reject) => {
-    const args = [cliPath, 'install', '--no-shell', browserName];
-    const child = spawn(process.execPath, args, {
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
+  await runProcess(process.execPath, [cliPath, 'install', '--no-shell', browserName], {
+    signal: options.signal,
+    timeoutMs: 10 * 60 * 1000,
+    maxOutputBytes: 32 * 1024 * 1024,
+  });
+}
 
-    child.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-    child.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-    child.on('error', (error) => {
-      const detail = String(error?.message || `playwright install ${browserName} failed`).trim();
-      reject(new Error(detail));
-    });
-    child.on('close', (code) => {
-      if (code === 0) {
-        resolve();
-        return;
-      }
-      const detail = String(stderr || stdout || `playwright install ${browserName} exited with code ${code ?? 'unknown'}`).trim();
-      reject(new Error(detail));
-    });
+function createAbortError(signal, fallback = 'Browser operation aborted.') {
+  if (signal?.reason instanceof Error) return signal.reason;
+  const error = new Error(String(signal?.reason || fallback));
+  error.name = 'AbortError';
+  error.code = 'ABORT_ERR';
+  return error;
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw createAbortError(signal);
+}
+
+function sleep(ms, signal = null) {
+  throwIfAborted(signal);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(createAbortError(signal));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
   });
 }
 
-function sleep(ms) {
-  return new Promise(r => setTimeout(r, ms));
+function isAbortError(error, signal = null) {
+  return Boolean(
+    signal?.aborted
+    || error?.name === 'AbortError'
+    || error?.code === 'ABORT_ERR',
+  );
+}
+
+async function raceWithSignal(promise, signal) {
+  throwIfAborted(signal);
+  if (!signal) return promise;
+  let onAbort;
+  const aborted = new Promise((_, reject) => {
+    onAbort = () => reject(createAbortError(signal));
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted) onAbort();
+  });
+  try {
+    return await Promise.race([promise, aborted]);
+  } finally {
+    signal.removeEventListener('abort', onAbort);
+  }
 }
 
 async function waitForFile(filePath, options = {}) {
@@ -171,7 +201,7 @@ async function waitForFile(filePath, options = {}) {
   }
   const startedAt = Date.now();
   while (Date.now() - startedAt < timeoutMs) {
-    await sleep(intervalMs);
+    await sleep(intervalMs, options.signal);
     if (fs.existsSync(filePath)) {
       return true;
     }
@@ -197,6 +227,17 @@ function normalizeWaitUntil(waitUntil) {
   return 'domcontentloaded';
 }
 
+function normalizePointCoordinate(value, label) {
+  if (value == null || value === '') {
+    throw new Error(`${label} coordinate is required.`);
+  }
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized)) {
+    throw new Error(`${label} coordinate must be a finite number.`);
+  }
+  return Math.round(normalized);
+}
+
 function clearChromiumSingletonLocks(profileDir) {
   const lockEntries = [
     'SingletonLock',
@@ -213,6 +254,18 @@ function clearChromiumSingletonLocks(profileDir) {
   }
 }
 
+function chooseVirtualDisplay() {
+  for (let number = 90; number < 200; number += 1) {
+    if (
+      !fs.existsSync(`/tmp/.X11-unix/X${number}`)
+      && !fs.existsSync(`/tmp/.X${number}-lock`)
+    ) {
+      return `:${number}`;
+    }
+  }
+  throw new Error('No free X11 display is available for the browser.');
+}
+
 class BrowserController {
   constructor(options = {}) {
     this.io = options.io || null;
@@ -226,9 +279,15 @@ class BrowserController {
     this.page = null;
     this.displayProcess = null;
     this.displayValue = process.env.DISPLAY || null;
+    this._managedDisplayValue = null;
     this.launching = false;
     this.launchPromise = null;
     this.browserBinaryInstallPromise = null;
+    this._launchAbortController = null;
+    this._urlValidator = options.urlValidator || validateCloudUrlWithDns;
+    this._boundPages = new WeakSet();
+    this._closing = false;
+    this._closePromise = null;
     this.headless = false;
     this.profileDir = path.join(BROWSER_PROFILE_ROOT, this.userId || 'default');
     if (!fs.existsSync(this.profileDir)) fs.mkdirSync(this.profileDir, { recursive: true });
@@ -251,6 +310,122 @@ class BrowserController {
     return this.close();
   }
 
+  _contextIsOpen() {
+    if (!this.context) return false;
+    if (typeof this.context.isClosed === 'function' && this.context.isClosed()) return false;
+    return !this.browser
+      || typeof this.browser.isConnected !== 'function'
+      || this.browser.isConnected();
+  }
+
+  _clearBrowserReferences(context, browser) {
+    if (context && this.context !== context) return;
+    if (!context && browser && this.browser !== browser) return;
+    this.context = null;
+    this.browser = null;
+    this.page = null;
+  }
+
+  _bindPage(page, options = {}) {
+    if (!page) return;
+    if (!this._boundPages.has(page)) {
+      this._boundPages.add(page);
+      const clearPage = () => {
+        if (this.page === page) this.page = null;
+      };
+      page.on?.('close', clearPage);
+      page.on?.('crash', clearPage);
+    }
+    if (options.makeActive !== false) this.page = page;
+  }
+
+  _bindContextLifecycle(context, browser) {
+    context.on?.('close', () => this._clearBrowserReferences(context, browser));
+    context.on?.('page', (page) => {
+      this._bindPage(page);
+      this._applyStealthToPage(page).catch(() => {});
+    });
+    browser?.on?.('disconnected', () => this._clearBrowserReferences(context, browser));
+    for (const page of context.pages?.() || []) this._bindPage(page, { makeActive: false });
+  }
+
+  async _networkUrlAllowed(url) {
+    let parsed;
+    try {
+      parsed = new URL(String(url || ''));
+    } catch {
+      return false;
+    }
+    const protocol = parsed.protocol.toLowerCase();
+    if (protocol === 'about:' && parsed.href === 'about:blank') return true;
+    if (protocol === 'blob:' || protocol === 'data:') return true;
+    if (protocol === 'ws:' || protocol === 'wss:') {
+      parsed.protocol = protocol === 'ws:' ? 'http:' : 'https:';
+    } else if (protocol !== 'http:' && protocol !== 'https:') {
+      return false;
+    }
+    const result = await this._urlValidator(parsed.href);
+    return result?.allowed === true;
+  }
+
+  async _assertNavigationAllowed(url, options = {}) {
+    let result = null;
+    try {
+      result = await this._urlValidator(String(url || ''), { signal: options.signal });
+    } catch (error) {
+      if (isAbortError(error, options.signal)) throw error;
+    }
+    if (result?.allowed !== true) {
+      const error = new Error('This URL is not permitted.');
+      error.code = 'URL_BLOCKED';
+      throw error;
+    }
+  }
+
+  async _installNetworkGuard(context) {
+    await context.route('**/*', async (route) => {
+      let allowed = false;
+      try {
+        allowed = await this._networkUrlAllowed(route.request().url());
+      } catch {}
+      if (!allowed) {
+        await route.abort('blockedbyclient').catch(() => {});
+        return;
+      }
+      await route.continue().catch(() => {});
+    });
+
+    if (typeof context.routeWebSocket === 'function') {
+      await context.routeWebSocket('**', async (webSocket) => {
+        let allowed = false;
+        try {
+          allowed = await this._networkUrlAllowed(webSocket.url());
+        } catch {}
+        if (!allowed) {
+          await webSocket.close({ code: 1008, reason: 'Blocked by network policy' }).catch(() => {});
+          return;
+        }
+        webSocket.connectToServer();
+      });
+    }
+  }
+
+  async _withPageCancellation(page, signal, operation) {
+    throwIfAborted(signal);
+    if (!signal) return operation();
+    const closeOnAbort = () => {
+      if (!page?.isClosed?.()) {
+        page.close({ runBeforeUnload: false, reason: 'Browser operation cancelled' }).catch(() => {});
+      }
+    };
+    signal.addEventListener('abort', closeOnAbort, { once: true });
+    try {
+      return await raceWithSignal(Promise.resolve().then(operation), signal);
+    } finally {
+      signal.removeEventListener('abort', closeOnAbort);
+    }
+  }
+
   async _applyStealthToPage(page) {
     const ua = this._userAgent;
     const vp = this._viewport;
@@ -308,7 +483,6 @@ class BrowserController {
             arr.item = i => arr[i];
             arr.namedItem = n => arr.find(p => p.name === n) || null;
             arr.refresh = () => {};
-            Object.defineProperty(arr, 'length', { get: () => arr.length });
             return arr;
           }
         });
@@ -345,17 +519,6 @@ class BrowserController {
             return originalFillText.apply(this, args);
         };
 
-        // Media Devices Spoofing
-        if (navigator.mediaDevices && navigator.mediaDevices.enumerateDevices) {
-            const originalEnumerateDevices = navigator.mediaDevices.enumerateDevices.bind(navigator.mediaDevices);
-            navigator.mediaDevices.enumerateDevices = async () => {
-                return [
-                    { kind: 'audioinput', deviceId: 'default', groupId: 'a', label: 'MacBook Pro Microphone' },
-                    { kind: 'audiooutput', deviceId: 'default', groupId: 'b', label: 'MacBook Pro Speakers' },
-                    { kind: 'videoinput', deviceId: 'default', groupId: 'c', label: 'FaceTime HD Camera' }
-                ];
-            };
-        }
       })();
     `;
     if (typeof page.evaluateOnNewDocument === 'function') {
@@ -365,23 +528,42 @@ class BrowserController {
     }
   }
 
-  async ensureBrowser() {
-    if (this.browser && this.browser.isConnected()) return;
+  async ensureBrowser(options = {}) {
+    let signal = options.signal;
+    throwIfAborted(signal);
+    if (this._closePromise) await raceWithSignal(this._closePromise, signal);
+    if (this._contextIsOpen()) return;
     if (this.launchPromise) {
-      await this.launchPromise;
+      await raceWithSignal(this.launchPromise, signal);
       return;
     }
 
+    const staleContext = this.context;
+    const staleBrowser = this.browser;
+    this._clearBrowserReferences(staleContext, staleBrowser);
+    if (staleContext) await staleContext.close().catch(() => {});
+    else if (staleBrowser) await staleBrowser.close().catch(() => {});
+
+    const launchAbortController = new AbortController();
+    this._launchAbortController = launchAbortController;
+    const externalSignal = signal;
+    const forwardAbort = () => launchAbortController.abort(externalSignal.reason);
+    externalSignal?.addEventListener('abort', forwardAbort, { once: true });
+    if (externalSignal?.aborted) forwardAbort();
+    signal = launchAbortController.signal;
+
     this.launching = true;
     this.launchPromise = (async () => {
       const runtimeReady = await waitForFile(BROWSER_READY_MARKER, {
         timeoutMs: 10 * 60 * 1000,
         intervalMs: 1000,
+        signal,
       });
       if (!runtimeReady) {
         throw new Error('Browser runtime provisioning is still in progress inside the VM. Retry shortly.');
       }
-      await this.ensureVirtualDisplay();
+      await this.ensureVirtualDisplay({ signal });
+      throwIfAborted(signal);
 
       this._identity = chooseBrowserIdentity(this.userId || this.profileDir);
       this._userAgent = this._identity.userAgent;
@@ -394,10 +576,10 @@ class BrowserController {
       let executablePath = resolveBrowserExecutablePath();
       if (!executablePath) {
         if (!this.browserBinaryInstallPromise) {
-          this.browserBinaryInstallPromise = installPlaywrightBrowserBinary(this.engine);
+          this.browserBinaryInstallPromise = installPlaywrightBrowserBinary(this.engine, { signal });
         }
         try {
-          await this.browserBinaryInstallPromise;
+          await raceWithSignal(this.browserBinaryInstallPromise, signal);
         } finally {
           this.browserBinaryInstallPromise = null;
         }
@@ -444,7 +626,7 @@ class BrowserController {
 
       const playwright = require('playwright-chromium');
       clearChromiumSingletonLocks(this.profileDir);
-      this.context = await playwright.chromium.launchPersistentContext(this.profileDir, {
+      const launchPromise = playwright.chromium.launchPersistentContext(this.profileDir, {
         headless: false,
         executablePath,
         env: launchEnv,
@@ -453,98 +635,137 @@ class BrowserController {
         userAgent: this._userAgent,
         locale: 'en-US',
         ignoreHTTPSErrors: false,
+        serviceWorkers: 'block',
         timeout: 120000,
       });
-      this.browser = typeof this.context.browser === 'function' ? this.context.browser() : null;
+      let context;
+      try {
+        context = await raceWithSignal(launchPromise, signal);
+      } catch (error) {
+        launchPromise.then((lateContext) => lateContext.close().catch(() => {})).catch(() => {});
+        throw error;
+      }
+      const browser = typeof context.browser === 'function' ? context.browser() : null;
+      this.context = context;
+      this.browser = browser;
+      this._bindContextLifecycle(context, browser);
 
       // Cloud security: deny access to local devices on every page in this context.
-      await this.context.addInitScript(DEVICE_DENY_SCRIPT);
+      await context.addInitScript(DEVICE_DENY_SCRIPT);
+      await this._installNetworkGuard(context);
 
-      this.page = this.context.pages()[0] || await this.context.newPage();
+      this.page = context.pages()[0] || await context.newPage();
+      this._bindPage(this.page);
       await this._applyStealthToPage(this.page);
     })();
 
     try {
-      await this.launchPromise;
+      await raceWithSignal(this.launchPromise, signal);
+    } catch (error) {
+      const failedContext = this.context;
+      const failedBrowser = this.browser;
+      this._clearBrowserReferences(failedContext, failedBrowser);
+      if (failedContext) await failedContext.close().catch(() => {});
+      else if (failedBrowser) await failedBrowser.close().catch(() => {});
+      await this._stopVirtualDisplay();
+      throw error;
     } finally {
+      externalSignal?.removeEventListener('abort', forwardAbort);
+      if (this._launchAbortController === launchAbortController) {
+        this._launchAbortController = null;
+      }
       this.launchPromise = null;
       this.launching = false;
     }
   }
 
-  async ensurePage() {
-    await this.ensureBrowser();
+  async ensurePage(options = {}) {
+    const signal = options.signal;
+    await this.ensureBrowser(options);
+    throwIfAborted(signal);
     if (!this.page || this.page.isClosed()) {
+      let pagePromise;
       if (this.context && typeof this.context.newPage === 'function') {
-        this.page = await this.context.newPage();
+        pagePromise = this.context.newPage();
       } else {
-        this.page = await this.browser.newPage();
+        pagePromise = this.browser.newPage();
+      }
+      try {
+        this.page = await raceWithSignal(pagePromise, signal);
+      } catch (error) {
+        pagePromise.then((latePage) => latePage.close().catch(() => {})).catch(() => {});
+        throw error;
       }
+      this._bindPage(this.page);
       await this._applyStealthToPage(this.page);
     }
     return this.page;
   }
 
   async takeScreenshot(options = {}) {
-    const page = await this.ensurePage();
-    let artifactRecord = null;
-    let filename = `screenshot_${Date.now()}.png`;
-    let filepath = path.join(SCREENSHOTS_DIR, filename);
-    if (this.artifactStore && this.userId != null) {
-      artifactRecord = this.artifactStore.allocateFile(this.userId, {
-        kind: 'browser-screenshot',
-        backend: this.runtimeBackend,
-        extension: 'png',
-        contentType: 'image/png',
-        filenameBase: 'browser-screenshot',
-        metadata: {
-          selector: options.selector || null,
-          fullPage: options.fullPage === true,
-        },
-      });
-      filepath = artifactRecord.storagePath;
-      filename = path.basename(filepath);
-    }
+    const page = await this.ensurePage(options);
+    return this._withPageCancellation(page, options.signal, async () => {
+      let artifactRecord = null;
+      let filename = `screenshot_${Date.now()}.png`;
+      let filepath = path.join(SCREENSHOTS_DIR, filename);
+      if (this.artifactStore && this.userId != null) {
+        artifactRecord = this.artifactStore.allocateFile(this.userId, {
+          kind: 'browser-screenshot',
+          backend: this.runtimeBackend,
+          extension: 'png',
+          contentType: 'image/png',
+          filenameBase: 'browser-screenshot',
+          metadata: {
+            selector: options.selector || null,
+            fullPage: options.fullPage === true,
+          },
+        });
+        filepath = artifactRecord.storagePath;
+        filename = path.basename(filepath);
+      }
 
-    const screenshotOptions = { path: filepath, type: 'png' };
-    if (options.fullPage) screenshotOptions.fullPage = true;
-    if (options.selector) {
-      const element = await page.$(options.selector);
-      if (element) {
-        await element.screenshot(screenshotOptions);
+      const screenshotOptions = { path: filepath, type: 'png' };
+      if (options.fullPage) screenshotOptions.fullPage = true;
+      if (options.selector) {
+        const element = await page.$(options.selector);
+        if (element) {
+          await element.screenshot(screenshotOptions);
+        } else {
+          await page.screenshot(screenshotOptions);
+        }
       } else {
         await page.screenshot(screenshotOptions);
       }
-    } else {
-      await page.screenshot(screenshotOptions);
-    }
 
-    if (artifactRecord) {
-      this.artifactStore.finalizeFile(artifactRecord.artifactId, filepath);
-    }
+      if (artifactRecord) {
+        this.artifactStore.finalizeFile(artifactRecord.artifactId, filepath);
+      }
 
-    return {
-      screenshotPath: artifactRecord ? artifactRecord.url : `/screenshots/${filename}`,
-      artifactId: artifactRecord?.artifactId || null,
-      filename,
-      fullPath: filepath,
-    };
+      return {
+        screenshotPath: artifactRecord ? artifactRecord.url : `/screenshots/${filename}`,
+        artifactId: artifactRecord?.artifactId || null,
+        filename,
+        fullPath: filepath,
+      };
+    });
   }
 
   async screenshotJpeg(quality = 80, options = {}) {
-    const page = await this.ensurePage();
-    const screenshotOptions = {
-      type: 'jpeg',
-      quality: Math.min(95, Math.max(30, Math.floor(Number(quality) || 80))),
-      fullPage: options.fullPage === true,
-    };
-    if (options.selector) {
-      const element = await page.$(options.selector);
-      if (element) {
-        return element.screenshot(screenshotOptions);
+    const page = await this.ensurePage(options);
+    return this._withPageCancellation(page, options.signal, async () => {
+      const screenshotOptions = {
+        type: 'jpeg',
+        quality: Math.min(95, Math.max(30, Math.floor(Number(quality) || 80))),
+        fullPage: options.fullPage === true,
+      };
+      if (options.selector) {
+        const element = await page.$(options.selector);
+        if (element) {
+          return element.screenshot(screenshotOptions);
+        }
       }
-    }
-    return page.screenshot(screenshotOptions);
+      return page.screenshot(screenshotOptions);
+    });
   }
 
   async _navigatePage(page, url, options = {}) {
@@ -552,9 +773,21 @@ class BrowserController {
     const waitUntil = normalizeWaitUntil(options.waitUntil);
     if (referrerMode === 'current' && page.url() && page.url() !== 'about:blank') {
       const previousUrl = page.url();
-      await page.evaluate((nextUrl) => { window.location.href = nextUrl; }, url);
-      await page.waitForFunction((oldUrl) => window.location.href !== oldUrl, previousUrl, { timeout: 10000 }).catch(() => {});
-      await page.waitForLoadState(waitUntil, { timeout: 30000 }).catch(() => {});
+      const urlChanged = typeof page.waitForURL === 'function'
+        ? page.waitForURL(
+            (nextUrl) => String(nextUrl) !== previousUrl,
+            { waitUntil, timeout: 30000 },
+          )
+        : page.waitForFunction(
+            (oldUrl) => window.location.href !== oldUrl,
+            previousUrl,
+            { timeout: 30000 },
+          );
+      await Promise.all([
+        urlChanged,
+        page.evaluate((nextUrl) => { window.location.href = nextUrl; }, url),
+      ]);
+      await page.waitForLoadState(waitUntil, { timeout: 30000 });
       return null;
     }
 
@@ -581,80 +814,89 @@ class BrowserController {
   }
 
   async navigate(url, options = {}) {
-    const page = await this.ensurePage();
-
+    let page = null;
     try {
-      const requestedReferrerMode = normalizeReferrerMode(options.referrerMode);
-      let activeReferrerMode = requestedReferrerMode;
-      let response = await this._navigatePage(page, url, {
-        ...options,
-        referrerMode: activeReferrerMode,
-      });
-
-      if (options.waitFor) {
-        await page.waitForSelector(options.waitFor, { timeout: 10000 }).catch(() => { });
-      }
-
-      // Simulate human reading delay
-      await sleep(rand(700, 1800));
-
-      let rawHtml = await page.content();
-      const { extractForLLM } = require('./contentExtractor');
-      let extraction = extractForLLM(rawHtml, { url: page.url() });
-      let botDetection = await this._getBotDetection(page, rawHtml, extraction.markdown);
-      let challengeRetried = false;
-
-      if (
-        botDetection.detected
-        && normalizeChallengeRetry(options.challengeRetry)
-        && requestedReferrerMode === 'direct'
-      ) {
-        challengeRetried = true;
-        activeReferrerMode = 'google';
-        await sleep(rand(1200, 2600));
-        response = await this._navigatePage(page, url, {
+      await this._assertNavigationAllowed(url, options);
+      page = await this.ensurePage(options);
+      return await this._withPageCancellation(page, options.signal, async () => {
+        const requestedReferrerMode = normalizeReferrerMode(options.referrerMode);
+        let activeReferrerMode = requestedReferrerMode;
+        let response = await this._navigatePage(page, url, {
           ...options,
           referrerMode: activeReferrerMode,
         });
+
         if (options.waitFor) {
-          await page.waitForSelector(options.waitFor, { timeout: 10000 }).catch(() => { });
+          await page.waitForSelector(options.waitFor, { timeout: 10000 });
         }
-        await sleep(rand(900, 2200));
-        rawHtml = await page.content();
-        extraction = extractForLLM(rawHtml, { url: page.url() });
-        botDetection = await this._getBotDetection(page, rawHtml, extraction.markdown);
-      }
 
-      const title = await page.title();
-      const currentUrl = page.url();
+        // Simulate human reading delay.
+        await sleep(rand(700, 1800), options.signal);
+
+        let rawHtml = await page.content();
+        const { extractForLLM } = require('./contentExtractor');
+        let extraction = extractForLLM(rawHtml, { url: page.url() });
+        let botDetection = await this._getBotDetection(page, rawHtml, extraction.markdown);
+        let challengeRetried = false;
+
+        if (
+          botDetection.detected
+          && normalizeChallengeRetry(options.challengeRetry)
+          && requestedReferrerMode === 'direct'
+        ) {
+          challengeRetried = true;
+          activeReferrerMode = 'google';
+          await sleep(rand(1200, 2600), options.signal);
+          response = await this._navigatePage(page, url, {
+            ...options,
+            referrerMode: activeReferrerMode,
+          });
+          if (options.waitFor) {
+            await page.waitForSelector(options.waitFor, { timeout: 10000 });
+          }
+          await sleep(rand(900, 2200), options.signal);
+          rawHtml = await page.content();
+          extraction = extractForLLM(rawHtml, { url: page.url() });
+          botDetection = await this._getBotDetection(page, rawHtml, extraction.markdown);
+        }
 
-      let screenshot = null;
-      if (options.screenshot !== false) {
-        screenshot = await this.takeScreenshot({ fullPage: options.fullPage });
-      }
+        const title = await page.title();
+        const currentUrl = page.url();
 
-      return {
-        title,
-        url: currentUrl,
-        status: response?.status() || 0,
-        pageContent: extraction.markdown,
-        botDetection,
-        referrerMode: activeReferrerMode,
-        challengeRetried,
-        screenshotPath: screenshot?.screenshotPath || null,
-        artifactId: screenshot?.artifactId || null,
-        fullPath: screenshot?.fullPath || null
-      };
+        let screenshot = null;
+        if (options.screenshot !== false) {
+          screenshot = await this.takeScreenshot({
+            fullPage: options.fullPage,
+            signal: options.signal,
+          });
+        }
+
+        return {
+          title,
+          url: currentUrl,
+          status: response?.status() || 0,
+          pageContent: extraction.markdown,
+          botDetection,
+          referrerMode: activeReferrerMode,
+          challengeRetried,
+          screenshotPath: screenshot?.screenshotPath || null,
+          artifactId: screenshot?.artifactId || null,
+          fullPath: screenshot?.fullPath || null,
+        };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       let screenshot = null;
-      try { screenshot = await this.takeScreenshot(); } catch { }
+      if (page && !page.isClosed()) {
+        try { screenshot = await this.takeScreenshot(); } catch {}
+      }
       return {
         error: err.message,
         url,
         botDetection: { detected: false, provider: null },
         screenshotPath: screenshot?.screenshotPath || null,
         artifactId: screenshot?.artifactId || null,
-        fullPath: screenshot?.fullPath || null
+        fullPath: screenshot?.fullPath || null,
       };
     }
   }
@@ -668,7 +910,7 @@ class BrowserController {
     for (const point of path) {
       await page.mouse.move(point.x, point.y);
       if (!options.fast) {
-        await sleep(rand(2, 10));
+        await sleep(rand(2, 10), options.signal);
       }
     }
     this._mousePosition = target;
@@ -689,271 +931,327 @@ class BrowserController {
     };
   }
 
-  async click(selector, text, screenshot = true) {
-    const page = await this.ensurePage();
+  async click(selector, text, screenshot = true, options = {}) {
+    const page = await this.ensurePage(options);
 
     try {
-      let target = null;
-
-      if (text && !selector) {
-        const elements = await page.$$('a, button, [role="button"], input[type="submit"], [onclick]');
-        for (const el of elements) {
-          const elText = await page.evaluate(e => e.innerText || e.value || e.getAttribute('aria-label') || '', el);
-          if (elText.toLowerCase().includes(text.toLowerCase())) {
-            target = el;
-            break;
+      return await this._withPageCancellation(page, options.signal, async () => {
+        let target = null;
+
+        if (text && !selector) {
+          const elements = await page.$$('a, button, [role="button"], input[type="submit"], [onclick]');
+          for (const el of elements) {
+            const elText = await page.evaluate(e => e.innerText || e.value || e.getAttribute('aria-label') || '', el);
+            if (elText.toLowerCase().includes(String(text).toLowerCase())) {
+              target = el;
+              break;
+            }
           }
+          if (!target) return { error: `No clickable element found with text: ${text}` };
+        } else if (selector) {
+          target = await page.$(selector);
+          if (!target) return { error: `Element not found: ${selector}` };
+        } else {
+          return { error: 'Either selector or text required' };
         }
-        if (!target) return { error: `No clickable element found with text: ${text}` };
-      } else if (selector) {
-        target = await page.$(selector);
-        if (!target) return { error: `Element not found: ${selector}` };
-      } else {
-        return { error: 'Either selector or text required' };
-      }
 
-      const point = await this._pointForElement(target);
-      if (!point) return { error: 'Element has no visible clickable area' };
+        const point = await this._pointForElement(target);
+        if (!point) return { error: 'Element has no visible clickable area' };
 
-      await this._moveMouseTo(page, point.x, point.y);
-      await sleep(rand(170, 320));
-      await page.mouse.down();
-      await sleep(rand(80, 260));
-      await page.mouse.up();
+        await this._moveMouseTo(page, point.x, point.y, { signal: options.signal });
+        await sleep(rand(170, 320), options.signal);
+        await page.mouse.down();
+        await sleep(rand(80, 260), options.signal);
+        await page.mouse.up();
 
-      await sleep(rand(800, 1800));
+        await sleep(rand(800, 1800), options.signal);
 
-      let screenshotResult = null;
-      if (screenshot) screenshotResult = await this.takeScreenshot();
+        let screenshotResult = null;
+        if (screenshot) screenshotResult = await this.takeScreenshot({ signal: options.signal });
 
-      return {
-        success: true,
-        url: page.url(),
-        title: await page.title(),
-        screenshotPath: screenshotResult?.screenshotPath || null,
-        artifactId: screenshotResult?.artifactId || null,
-        fullPath: screenshotResult?.fullPath || null
-      };
+        return {
+          success: true,
+          url: page.url(),
+          title: await page.title(),
+          screenshotPath: screenshotResult?.screenshotPath || null,
+          artifactId: screenshotResult?.artifactId || null,
+          fullPath: screenshotResult?.fullPath || null,
+        };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       return { error: err.message };
     }
   }
 
-  async clickPoint(x, y, screenshot = true) {
-    const page = await this.ensurePage();
+  async clickPoint(x, y, screenshot = true, options = {}) {
+    const page = await this.ensurePage(options);
 
     try {
-      const px = Math.max(0, Math.round(Number(x) || 0));
-      const py = Math.max(0, Math.round(Number(y) || 0));
-      await this._moveMouseTo(page, px, py);
-      await sleep(rand(90, 220));
-      await page.mouse.down();
-      await sleep(rand(70, 240));
-      await page.mouse.up();
-      await sleep(rand(500, 1200));
-
-      let screenshotResult = null;
-      if (screenshot) screenshotResult = await this.takeScreenshot();
-
-      return {
-        success: true,
-        x: px,
-        y: py,
-        url: page.url(),
-        title: await page.title(),
-        screenshotPath: screenshotResult?.screenshotPath || null,
-        artifactId: screenshotResult?.artifactId || null,
-        fullPath: screenshotResult?.fullPath || null
-      };
+      return await this._withPageCancellation(page, options.signal, async () => {
+        const px = Math.max(0, normalizePointCoordinate(x, 'x'));
+        const py = Math.max(0, normalizePointCoordinate(y, 'y'));
+        await this._moveMouseTo(page, px, py, { signal: options.signal });
+        await sleep(rand(90, 220), options.signal);
+        await page.mouse.down();
+        await sleep(rand(70, 240), options.signal);
+        await page.mouse.up();
+        await sleep(rand(500, 1200), options.signal);
+
+        let screenshotResult = null;
+        if (screenshot) screenshotResult = await this.takeScreenshot({ signal: options.signal });
+
+        return {
+          success: true,
+          x: px,
+          y: py,
+          url: page.url(),
+          title: await page.title(),
+          screenshotPath: screenshotResult?.screenshotPath || null,
+          artifactId: screenshotResult?.artifactId || null,
+          fullPath: screenshotResult?.fullPath || null,
+        };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       return { error: err.message };
     }
   }
 
   async hoverPoint(x, y, options = {}) {
-    const page = await this.ensurePage();
+    const page = await this.ensurePage(options);
     try {
-      const px = Math.max(0, Math.round(Number(x) || 0));
-      const py = Math.max(0, Math.round(Number(y) || 0));
-      await this._moveMouseTo(page, px, py, { fast: Number(options.steps) <= 1 });
-      return {
-        success: true,
-        x: px,
-        y: py,
-        url: page.url(),
-        title: await page.title()
-      };
+      return await this._withPageCancellation(page, options.signal, async () => {
+        const px = Math.max(0, normalizePointCoordinate(x, 'x'));
+        const py = Math.max(0, normalizePointCoordinate(y, 'y'));
+        await this._moveMouseTo(page, px, py, {
+          fast: Number(options.steps) <= 1,
+          signal: options.signal,
+        });
+        return {
+          success: true,
+          x: px,
+          y: py,
+          url: page.url(),
+          title: await page.title(),
+        };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       return { error: err.message };
     }
   }
 
-  async scroll(deltaX = 0, deltaY = 0, screenshot = true) {
-    const page = await this.ensurePage();
+  async scroll(deltaX = 0, deltaY = 0, screenshot = true, options = {}) {
+    const page = await this.ensurePage(options);
 
     try {
-      const x = Math.max(10, Math.min(this._viewport.width - 10, this._mousePosition.x + rand(-80, 80)));
-      const y = Math.max(10, Math.min(this._viewport.height - 10, this._mousePosition.y + rand(-80, 80)));
-      await this._moveMouseTo(page, x, y);
-      const totalX = Math.round(Number(deltaX) || 0);
-      const totalY = Math.round(Number(deltaY) || 0);
-      const chunks = Math.max(1, Math.min(6, Math.ceil(Math.max(Math.abs(totalX), Math.abs(totalY)) / 450)));
-      for (let i = 0; i < chunks; i += 1) {
-        await page.mouse.wheel({
-          deltaX: Math.round(totalX / chunks),
-          deltaY: Math.round(totalY / chunks),
-        });
-        await sleep(rand(120, 360));
-      }
+      return await this._withPageCancellation(page, options.signal, async () => {
+        const x = Math.max(10, Math.min(this._viewport.width - 10, this._mousePosition.x + rand(-80, 80)));
+        const y = Math.max(10, Math.min(this._viewport.height - 10, this._mousePosition.y + rand(-80, 80)));
+        await this._moveMouseTo(page, x, y, { signal: options.signal });
+        const totalX = Math.round(Number(deltaX) || 0);
+        const totalY = Math.round(Number(deltaY) || 0);
+        const chunks = Math.max(1, Math.min(6, Math.ceil(Math.max(Math.abs(totalX), Math.abs(totalY)) / 450)));
+        for (let i = 0; i < chunks; i += 1) {
+          await page.mouse.wheel({
+            deltaX: Math.round(totalX / chunks),
+            deltaY: Math.round(totalY / chunks),
+          });
+          await sleep(rand(120, 360), options.signal);
+        }
 
-      let screenshotResult = null;
-      if (screenshot) screenshotResult = await this.takeScreenshot();
+        let screenshotResult = null;
+        if (screenshot) screenshotResult = await this.takeScreenshot({ signal: options.signal });
 
-      return {
-        success: true,
-        url: page.url(),
-        title: await page.title(),
-        screenshotPath: screenshotResult?.screenshotPath || null,
-        artifactId: screenshotResult?.artifactId || null,
-        fullPath: screenshotResult?.fullPath || null
-      };
+        return {
+          success: true,
+          url: page.url(),
+          title: await page.title(),
+          screenshotPath: screenshotResult?.screenshotPath || null,
+          artifactId: screenshotResult?.artifactId || null,
+          fullPath: screenshotResult?.fullPath || null,
+        };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       return { error: err.message };
     }
   }
 
   async type(selector, text, options = {}) {
-    const page = await this.ensurePage();
+    const page = await this.ensurePage(options);
 
     try {
-      if (options.clear !== false) {
+      return await this._withPageCancellation(page, options.signal, async () => {
+        const value = String(text ?? '');
         const element = await page.$(selector);
-        if (element) {
-          const point = await this._pointForElement(element);
-          if (point) {
-            await this._moveMouseTo(page, point.x, point.y);
-            await sleep(rand(120, 260));
+        if (!element) return { error: `Element not found: ${selector}` };
+        const point = await this._pointForElement(element);
+        if (point) {
+          await this._moveMouseTo(page, point.x, point.y, { signal: options.signal });
+          await sleep(rand(120, 260), options.signal);
+        }
+
+        const locator = typeof page.locator === 'function' ? page.locator(selector) : null;
+        if (options.clear !== false) {
+          if (locator && typeof locator.fill === 'function') {
+            await locator.fill('');
+          } else {
+            await page.click(selector, { clickCount: 3, delay: rand(40, 120) });
+            await page.keyboard.press('Backspace');
           }
         }
-        await page.click(selector, { clickCount: 3, delay: rand(40, 120) });
-        await page.keyboard.press('Backspace');
-      }
 
-      for (const char of text) {
-        await page.type(selector, char, { delay: rand(45, 180) });
-      }
+        if (locator && typeof locator.pressSequentially === 'function') {
+          await locator.pressSequentially(value, { delay: rand(45, 140) });
+        } else {
+          await page.type(selector, value, { delay: rand(45, 140) });
+        }
 
-      if (options.pressEnter) {
-        await page.keyboard.press('Enter');
-        await sleep(1000);
-      }
+        if (options.pressEnter) {
+          if (locator && typeof locator.press === 'function') await locator.press('Enter');
+          else await page.keyboard.press('Enter');
+          await sleep(1000, options.signal);
+        }
 
-      let screenshotResult = null;
-      if (options.screenshot !== false) screenshotResult = await this.takeScreenshot();
+        let screenshotResult = null;
+        if (options.screenshot !== false) {
+          screenshotResult = await this.takeScreenshot({ signal: options.signal });
+        }
 
-      return {
-        success: true,
-        typed: text,
-        screenshotPath: screenshotResult?.screenshotPath || null,
-        artifactId: screenshotResult?.artifactId || null,
-        fullPath: screenshotResult?.fullPath || null
-      };
+        return {
+          success: true,
+          typed: value,
+          screenshotPath: screenshotResult?.screenshotPath || null,
+          artifactId: screenshotResult?.artifactId || null,
+          fullPath: screenshotResult?.fullPath || null,
+        };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       return { error: err.message };
     }
   }
 
   async typeText(text, options = {}) {
-    const page = await this.ensurePage();
+    const page = await this.ensurePage(options);
 
     try {
-      for (const char of String(text || '')) {
-        await page.keyboard.type(char, { delay: rand(45, 160) });
-      }
+      return await this._withPageCancellation(page, options.signal, async () => {
+        const value = String(text ?? '');
+        await page.keyboard.type(value, { delay: rand(45, 140) });
 
-      if (options.pressEnter) {
-        await page.keyboard.press('Enter');
-        await sleep(800);
-      }
+        if (options.pressEnter) {
+          await page.keyboard.press('Enter');
+          await sleep(800, options.signal);
+        }
 
-      let screenshotResult = null;
-      if (options.screenshot !== false) screenshotResult = await this.takeScreenshot();
+        let screenshotResult = null;
+        if (options.screenshot !== false) {
+          screenshotResult = await this.takeScreenshot({ signal: options.signal });
+        }
 
-      return {
-        success: true,
-        typed: String(text || ''),
-        screenshotPath: screenshotResult?.screenshotPath || null,
-        artifactId: screenshotResult?.artifactId || null,
-        fullPath: screenshotResult?.fullPath || null
-      };
+        return {
+          success: true,
+          typed: value,
+          screenshotPath: screenshotResult?.screenshotPath || null,
+          artifactId: screenshotResult?.artifactId || null,
+          fullPath: screenshotResult?.fullPath || null,
+        };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       return { error: err.message };
     }
   }
 
-  async pressKey(key, screenshot = true) {
-    const page = await this.ensurePage();
+  async pressKey(key, screenshot = true, options = {}) {
+    const page = await this.ensurePage(options);
 
     try {
-      const normalized = String(key || '').trim();
-      if (!normalized) {
-        return { error: 'key required' };
-      }
-      await page.keyboard.press(normalized);
-      await sleep(rand(250, 700));
-
-      let screenshotResult = null;
-      if (screenshot) screenshotResult = await this.takeScreenshot();
-
-      return {
-        success: true,
-        key: normalized,
-        screenshotPath: screenshotResult?.screenshotPath || null,
-        artifactId: screenshotResult?.artifactId || null,
-        fullPath: screenshotResult?.fullPath || null
-      };
+      return await this._withPageCancellation(page, options.signal, async () => {
+        const normalized = String(key || '').trim();
+        if (!normalized) {
+          return { error: 'key required' };
+        }
+        await page.keyboard.press(normalized);
+        await sleep(rand(250, 700), options.signal);
+
+        let screenshotResult = null;
+        if (screenshot) screenshotResult = await this.takeScreenshot({ signal: options.signal });
+
+        return {
+          success: true,
+          key: normalized,
+          screenshotPath: screenshotResult?.screenshotPath || null,
+          artifactId: screenshotResult?.artifactId || null,
+          fullPath: screenshotResult?.fullPath || null,
+        };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       return { error: err.message };
     }
   }
 
-  async extract(selector, attribute, all = false) {
-    const page = await this.ensurePage();
+  async extract(selector, attribute, all = false, options = {}) {
+    const page = await this.ensurePage(options);
 
     try {
-      const rawHtml = await page.content().catch(() => '');
-      const botDetection = await this._getBotDetection(page, rawHtml, '').catch(() => ({ detected: false, provider: null }));
-      if (all) {
-        const results = await page.$$eval(selector || 'body', (elements, attr) => {
-          return elements.map(el => {
-            if (attr === 'innerHTML') return el.innerHTML;
-            if (attr === 'outerHTML') return el.outerHTML;
-            if (attr) return el.getAttribute(attr) || '';
-            return el.innerText || '';
-          });
-        }, attribute);
-        return { results: results.slice(0, 100), botDetection };
-      }
+      return await this._withPageCancellation(page, options.signal, async () => {
+        const rawHtml = await page.content().catch(() => '');
+        const botDetection = await this._getBotDetection(page, rawHtml, '')
+          .catch(() => ({ detected: false, provider: null }));
+        if (all) {
+          const results = await page.$$eval(selector || 'body', (elements, attr) => {
+            return elements.slice(0, 100).map(el => {
+              let value = '';
+              if (attr === 'innerHTML') value = el.innerHTML;
+              else if (attr === 'outerHTML') value = el.outerHTML;
+              else if (attr) value = el.getAttribute(attr) || '';
+              else value = el.innerText || '';
+              return String(value).slice(0, 50000);
+            });
+          }, attribute);
+          return { results, botDetection };
+        }
 
-      const result = await page.$eval(selector || 'body', (el, attr) => {
-        if (attr === 'innerHTML') return el.innerHTML;
-        if (attr === 'outerHTML') return el.outerHTML;
-        if (attr) return el.getAttribute(attr) || '';
-        return el.innerText || '';
-      }, attribute);
+        const result = await page.$eval(selector || 'body', (el, attr) => {
+          if (attr === 'innerHTML') return el.innerHTML;
+          if (attr === 'outerHTML') return el.outerHTML;
+          if (attr) return el.getAttribute(attr) || '';
+          return el.innerText || '';
+        }, attribute);
 
-      return { result: typeof result === 'string' ? result.slice(0, 50000) : result, botDetection };
+        return { result: typeof result === 'string' ? result.slice(0, 50000) : result, botDetection };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       return { error: err.message };
     }
   }
 
-  async evaluate(script) {
-    const page = await this.ensurePage();
+  async evaluate(script, options = {}) {
+    const source = String(script || '');
+    if (!source) return { error: 'script required' };
+    if (source.length > 10000) return { error: 'script exceeds maximum length (10000)' };
+    const page = await this.ensurePage(options);
     try {
-      const result = await page.evaluate(buildIsolatedEvaluationExpression(script));
-      return { result: typeof result === 'object' ? JSON.stringify(result) : String(result) };
+      return await this._withPageCancellation(page, options.signal, async () => {
+        const result = await page.evaluate(buildIsolatedEvaluationExpression(source));
+        const serialized = typeof result === 'object' && result !== null
+          ? JSON.stringify(result)
+          : String(result);
+        const output = serialized ?? 'undefined';
+        const maxChars = 1024 * 1024;
+        return {
+          result: output.slice(0, maxChars),
+          truncated: output.length > maxChars,
+        };
+      });
     } catch (err) {
+      if (isAbortError(err, options.signal)) throw err;
       return { error: err.message };
     }
   }
@@ -963,14 +1261,12 @@ class BrowserController {
   }
 
   async launch(options = {}) {
-    void options;
-    await this.ensureBrowser();
+    await this.ensureBrowser(options);
     return { success: true };
   }
 
   isLaunched() {
-    if (this.context) return true;
-    return !!(this.browser && typeof this.browser.isConnected === 'function' && this.browser.isConnected());
+    return this._contextIsOpen();
   }
 
   getPageCount() {
@@ -981,84 +1277,139 @@ class BrowserController {
     try { return this.browser.pages ? 1 : 0; } catch { return 0; }
   }
 
-  async fill(selector, value) {
-    return this.type(selector, String(value));
+  async fill(selector, value, options = {}) {
+    return this.type(selector, String(value), options);
   }
 
   async extractContent(options = {}) {
-    return this.extract(options.selector, options.attribute, options.all);
+    return this.extract(options.selector, options.attribute, options.all, options);
   }
 
-  async executeJS(code) {
-    return this.evaluate(code);
+  async executeJS(code, options = {}) {
+    return this.evaluate(code, options);
   }
 
-  async getPageInfo() {
+  async getPageInfo(options = {}) {
+    throwIfAborted(options.signal);
     if (!this.page || this.page.isClosed()) return { url: null, title: null };
     return {
       url: this.page.url(),
-      title: await this.page.title()
+      title: await raceWithSignal(this.page.title(), options.signal),
     };
   }
 
-  async getCookies() {
-    await this.ensureBrowser();
+  async getCookies(options = {}) {
+    await this.ensureBrowser(options);
     if (!this.context || typeof this.context.cookies !== 'function') {
       return { cookies: [] };
     }
-    const cookies = await this.context.cookies().catch(() => []);
+    const cookies = await raceWithSignal(this.context.cookies(), options.signal);
     return {
       cookies: Array.isArray(cookies) ? cookies : [],
     };
   }
 
   async close() {
-    if (this.page && !this.page.isClosed()) {
-      await this.page.close().catch(() => { });
-    }
-    if (this.context) {
-      await this.context.close().catch(() => { });
-      this.context = null;
-      this.browser = null;
+    if (this._closePromise) return this._closePromise;
+    this._closing = true;
+    this._launchAbortController?.abort(new Error('Browser controller is closing.'));
+    this._closePromise = (async () => {
+      const launchPromise = this.launchPromise;
+      if (launchPromise) await launchPromise.catch(() => {});
+
+      const page = this.page;
+      const context = this.context;
+      const browser = this.browser;
       this.page = null;
-      return;
-    }
-    if (this.browser) {
-      await this.browser.close().catch(() => { });
+      this.context = null;
       this.browser = null;
-      this.page = null;
+
+      if (context) {
+        await context.close({ reason: 'Browser controller closed' }).catch(() => {});
+      } else if (browser) {
+        await browser.close().catch(() => {});
+      } else if (page && !page.isClosed()) {
+        await page.close({ runBeforeUnload: false, reason: 'Browser controller closed' }).catch(() => {});
+      }
+      await this._stopVirtualDisplay();
+    })();
+    try {
+      await this._closePromise;
+    } finally {
+      this._closePromise = null;
+      this._closing = false;
     }
   }
 
-  async ensureVirtualDisplay() {
+  async ensureVirtualDisplay(options = {}) {
     if (process.platform !== 'linux') {
       return;
     }
-    if (this.displayProcess && !this.displayProcess.killed) {
+    if (this.displayProcess && this.displayProcess.exitCode == null) {
       return;
     }
     if (this.displayValue && String(this.displayValue).trim()) {
       return;
     }
 
-    const display = ':99';
+    const display = chooseVirtualDisplay();
     const child = spawn('Xvfb', [display, '-screen', '0', '1440x900x24', '-ac', '-nolisten', 'tcp'], {
       stdio: ['ignore', 'ignore', 'pipe'],
     });
+    this.displayProcess = child;
 
     let launchError = '';
     child.stderr.on('data', (chunk) => {
-      launchError += chunk.toString();
+      if (launchError.length < 64 * 1024) launchError += chunk.toString();
+    });
+    child.once('close', () => {
+      if (this.displayProcess === child) {
+        this.displayProcess = null;
+        if (this.displayValue === display) this.displayValue = process.env.DISPLAY || null;
+        if (this._managedDisplayValue === display) this._managedDisplayValue = null;
+      }
     });
 
-    await sleep(1000);
-    if (child.exitCode != null) {
-      throw new Error(`Failed to start Xvfb: ${String(launchError || `exit code ${child.exitCode}`).trim()}`);
+    try {
+      await Promise.race([
+        sleep(1000, options.signal),
+        new Promise((_, reject) => child.once('error', reject)),
+      ]);
+      if (child.exitCode != null) {
+        throw new Error(`Failed to start Xvfb: ${String(launchError || `exit code ${child.exitCode}`).trim()}`);
+      }
+    } catch (error) {
+      await this._stopVirtualDisplay();
+      throw error;
     }
 
-    this.displayProcess = child;
     this.displayValue = display;
+    this._managedDisplayValue = display;
+  }
+
+  async _stopVirtualDisplay() {
+    const child = this.displayProcess;
+    const managedDisplay = this._managedDisplayValue;
+    this.displayProcess = null;
+    this._managedDisplayValue = null;
+    if (managedDisplay && this.displayValue === managedDisplay) {
+      this.displayValue = process.env.DISPLAY || null;
+    }
+    if (!child || child.exitCode != null) return;
+
+    const exited = new Promise((resolve) => child.once('close', resolve));
+    try { child.kill('SIGTERM'); } catch {}
+    await Promise.race([exited, sleep(1000)]);
+    if (child.exitCode == null) {
+      try { child.kill('SIGKILL'); } catch {}
+      await Promise.race([exited, sleep(1000)]);
+    }
   }
 }
 
-module.exports = { BrowserController, resolveBrowserExecutablePath, buildIsolatedEvaluationExpression, normalizeWaitUntil };
+module.exports = {
+  BrowserController,
+  buildIsolatedEvaluationExpression,
+  normalizeWaitUntil,
+  resolveBrowserExecutablePath,
+};