browser-commander 0.31.1 → 0.32.0

package/src/browser/real-browser.js

@@ -9,7 +9,9 @@ import { findBrowserSource } from './browser-sources.js';
 import { launchSafari } from './safari-launch.js';
 import { isSafariChannel } from './safari-support.js';
 
-import { startProcess } from '../utilities/subprocess.js';
+import { interruptionMode, startProcess } from '../utilities/subprocess.js';
+import { installHandoff } from './browser-handoff.js';
+import { closeRemoteBrowser } from './cdp-browser-endpoint.js';
 import { withDeadline } from '../traces/deadline.js';
 import {
   applyAutomationParityArgs,
@@ -256,8 +258,16 @@ export async function waitForCdpEndpoint({
   }
 }
 
-function spawnWithStartProcess(executablePath, args, { env, verbose }) {
-  return startProcess(executablePath, args, { env, forwardOutput: verbose });
+function spawnWithStartProcess(
+  executablePath,
+  args,
+  { env, verbose, interruption }
+) {
+  return startProcess(executablePath, args, {
+    env,
+    forwardOutput: verbose,
+    interruption,
+  });
 }
 
 async function waitForExit(browserProcess, timeout) {
@@ -310,12 +320,20 @@ function createCloser({
   closeTimeout,
   closeConnection,
   verbose,
+  handoffState = {},
 }) {
   const originalClose = closeConnection ?? browser?.close;
   let closing;
   const close = () => {
     closing ??= (async () => {
-      if (browserProcess.exitCode === null && originalClose) {
+      if (browserProcess.exitCode === null && handoffState.detached) {
+        // The engine connection was handed off; ask the browser directly.
+        await withDeadline(
+          closeRemoteBrowser(handoffState.webSocketDebuggerUrl),
+          closeTimeout,
+          'browser close'
+        ).catch(() => {});
+      } else if (browserProcess.exitCode === null && originalClose) {
         // A signal can sever the engine transport while its close RPC is pending.
         // Keep the existing close budget active until owned-process cleanup runs.
         await withDeadline(
@@ -348,6 +366,14 @@ function createCloser({
   return close;
 }
 
+/**
+ * Selenium attaches through a chromedriver the launch starts; the driver
+ * follows the browser's interruption ownership (issue #174).
+ */
+function driverInterruption(engine, interruption) {
+  return engine === 'selenium' ? { interruption } : {};
+}
+
 /**
  * Spawn a genuine installed Chrome-family browser with a dedicated profile,
  * wait for its loopback CDP endpoint, and attach through {@link connectBrowser}.
@@ -400,6 +426,7 @@ async function spawnOnFreePort({
   argOptions,
   env,
   verbose,
+  interruption,
   userDataDir,
   startupTimeout,
   dependencies,
@@ -421,6 +448,7 @@ async function spawnOnFreePort({
       browserProcess = await spawnBrowser(executablePath, browserArgs, {
         env,
         verbose: false,
+        interruption,
       });
     } catch (error) {
       throw launchFailure(error, {
@@ -650,8 +678,10 @@ export async function launchAndConnectRealBrowserWithDependencies(
     preferences,
     localState,
     firstRun,
+    interruption: requestedInterruption,
     ...connectionOptions
   } = options;
+  const interruption = interruptionMode(requestedInterruption);
   const argOptions = {
     headless,
     restrictions,
@@ -731,6 +761,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
       argOptions,
       env: childEnv,
       verbose,
+      interruption,
       userDataDir,
       startupTimeout,
       dependencies,
@@ -756,9 +787,11 @@ export async function launchAndConnectRealBrowserWithDependencies(
       engine,
       cdpEndpoint: resolvedCdpEndpoint,
       ...connectionOptions,
+      ...driverInterruption(engine, interruption),
       seedCookies,
       verbose,
     });
+    const handoffState = { detached: false };
     const close = createCloser({
       engine,
       browser: connection.browser,
@@ -768,8 +801,9 @@ export async function launchAndConnectRealBrowserWithDependencies(
       closeTimeout,
       closeConnection: engine === 'selenium' ? connection.close : undefined,
       verbose,
+      handoffState,
     });
-    return await installSessionPersistence(
+    const session = await installSessionPersistence(
       {
         ...connection,
         close,
@@ -785,6 +819,23 @@ export async function launchAndConnectRealBrowserWithDependencies(
       },
       options
     );
+    return installHandoff(
+      session,
+      {
+        engine,
+        cdpEndpoint: resolvedCdpEndpoint,
+        userDataDir,
+        temporaryProfile,
+        remoteDebuggingPort: launched.port,
+        executablePath,
+        pid: () => browserProcess.pid,
+        connectedBrowser: () => connection.browser,
+        // The browser outlives this controller: no SIGINT forwarding, and
+        // its handle no longer keeps this program running.
+        release: () => browserProcess.detach?.(),
+      },
+      handoffState
+    );
   } catch (error) {
     if (browserProcess.exitCode === null) {
       browserProcess.kill();

package/src/browser/session-persistence.js

@@ -54,11 +54,15 @@ export async function installSessionPersistence(result, options) {
   const persistAndClose = () =>
     (closing ??= (async () => {
       try {
-        const state = await saveStorageState(result.page);
-        await writeRestrictedState(file, {
-          cookies: state.cookies.filter((cookie) => !(cookie.expires > 0)),
-          origins: [],
-        });
+        // A handed-off session no longer has an engine connection to save
+        // from; the controller that reconnects owns persistence.
+        if (!result.detached) {
+          const state = await saveStorageState(result.page);
+          await writeRestrictedState(file, {
+            cookies: state.cookies.filter((cookie) => !(cookie.expires > 0)),
+            origins: [],
+          });
+        }
       } finally {
         await close();
       }

package/src/browser/webdriver.js

@@ -30,6 +30,7 @@ import path from 'node:path';
 import { createWebDriverPage } from '../core/webdriver-page.js';
 import { isVerboseEnabled } from '../core/logger.js';
 import {
+  interruptionMode,
   runCommand as defaultRunCommand,
   startProcess as defaultStartProcess,
 } from '../utilities/subprocess.js';
@@ -483,6 +484,7 @@ async function teardown({
  * @param {Object<string,string>} [options.env] - Extra environment for the driver and browser
  * @param {number} [options.startupTimeout=30000]
  * @param {boolean} [options.verbose=false] - Mirror the driver server's output
+ * @param {'managed'|'caller'} [options.interruption='managed'] - Who handles Ctrl+C for the driver server and the browser under it; see `startProcess`
  * @param {Object} [dependencies] - Injected selenium modules, runCommand, startProcess, fetch, reservePort, environment, platform (tests)
  * @returns {Promise<{driver: Object, page: Object, close: function(): Promise<void>, serverUrl: string, driverProcess: Object, driverPath: string, driverSource: string, browser: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>, bidi: boolean}>}
  */
@@ -564,6 +566,7 @@ async function launchWebDriverOnce(options, dependencies) {
     startupTimeout = 30_000,
     verbose = false,
     debuggerAddress,
+    interruption,
   } = options;
   assertBrowser(browser);
   const safari = isSafariChannel(browser);
@@ -607,7 +610,11 @@ async function launchWebDriverOnce(options, dependencies) {
     driverProcess = startProcess(
       resolved.driverPath,
       buildDriverServerArgs(browser, port),
-      { env: childEnv, forwardOutput: verbose }
+      {
+        env: childEnv,
+        forwardOutput: verbose,
+        interruption: interruptionMode(interruption),
+      }
     );
     for (const stream of [driverProcess.stdout, driverProcess.stderr]) {
       stream?.on('data', (chunk) => {

package/src/core/engine-adapter.js

@@ -284,13 +284,6 @@ export class PlaywrightAdapter extends EngineAdapter {
   // ============================================================================
 
   createLocator(selector) {
-    // Handle :nth-of-type() pseudo-selectors which don't work in Playwright locators
-    const nthOfTypeMatch = selector.match(/^(.+):nth-of-type\((\d+)\)$/);
-    if (nthOfTypeMatch) {
-      const baseSelector = nthOfTypeMatch[1];
-      const index = parseInt(nthOfTypeMatch[2], 10) - 1; // Convert to 0-based
-      return this.page.locator(baseSelector).nth(index);
-    }
     return this.page.locator(selector);
   }
 

package/src/elements/locators.js

@@ -6,7 +6,7 @@ import {
 
 /**
  * Helper to create Playwright locator from selector string
- * Handles :nth-of-type() pseudo-selectors which don't work in Playwright locators
+ * Preserves native CSS and text selector semantics.
  * @param {Object} options - Configuration options
  * @param {Object} options.page - Browser page object
  * @param {string} options.selector - CSS selector
@@ -22,15 +22,6 @@ export function createPlaywrightLocator(options = {}) {
   const { page, selector } = options;
 
   requireSelector(selector);
-  // Check if selector has :nth-of-type(n) pattern
-  const nthOfTypeMatch = selector.match(/^(.+):nth-of-type\((\d+)\)$/);
-
-  if (nthOfTypeMatch) {
-    const baseSelector = nthOfTypeMatch[1];
-    const index = parseInt(nthOfTypeMatch[2], 10) - 1; // Convert to 0-based index
-    return page.locator(baseSelector).nth(index);
-  }
-
   return page.locator(selector);
 }
 

package/src/elements/selectors.js

@@ -4,6 +4,7 @@ import {
   recoverWaitError,
 } from '../core/navigation-safety.js';
 import { createPlaywrightLocator, requireSelector } from './locators.js';
+import { textSelectorInPage } from './text-selector.js';
 
 /**
  * Query single element
@@ -80,75 +81,18 @@ export async function findByText(options = {}) {
   }
 }
 
-/**
- * Check if a selector is a Playwright-specific text selector
- * @param {string} selector - The selector to check
- * @returns {boolean} - True if selector contains Playwright text pseudo-selectors
- */
-function isPlaywrightTextSelector(selector) {
-  if (typeof selector !== 'string') {
-    return false;
-  }
-  return selector.includes(':has-text(') || selector.includes(':text-is(');
-}
-
-/**
- * Split `base:<pseudo>("text")` into its base selector and text.
- *
- * String operations rather than a regular expression: the former
- * /^(.+?):has-text\("(.+?)"\)$/ backtracked quadratically on long selectors
- * that do not match (CodeQL js/polynomial-redos). The base is everything before
- * the first `:<pseudo>("`, as the lazy `(.+?)` made it; base and text must be
- * non-empty.
- * @param {string} selector - Selector to split
- * @param {string} pseudo - Pseudo-class name, e.g. 'has-text'
- * @returns {{baseSelector: string, text: string}|null} - Parts, or null
- */
-function splitTextPseudo(selector, pseudo) {
-  const open = `:${pseudo}("`;
-  const start = selector.indexOf(open, 1);
-  if (start === -1 || !selector.endsWith('")')) {
-    return null;
-  }
-  const text = selector.slice(start + open.length, -2);
-  if (!text) {
-    return null;
-  }
-  return { baseSelector: selector.slice(0, start), text };
-}
-
-/**
- * Parse a Playwright text selector to extract base selector and text
- * @param {string} selector - Playwright text selector like 'a:has-text("text")'
- * @returns {Object|null} - { baseSelector, text, exact } or null if not parseable
- */
-function parsePlaywrightTextSelector(selector) {
-  // Match patterns like 'a:has-text("text")' or 'button:text-is("exact text")'
-  const hasText = splitTextPseudo(selector, 'has-text');
-  if (hasText) {
-    return { ...hasText, exact: false };
-  }
-
-  const textIs = splitTextPseudo(selector, 'text-is');
-  if (textIs) {
-    return { ...textIs, exact: true };
-  }
-
-  return null;
-}
-
 /**
  * Normalize selector to handle both Puppeteer and Playwright text selectors
- * Converts engine-specific text selectors to valid CSS selectors for browser context
+ * Preserves native Playwright strings; resolves text objects to unique CSS paths.
  *
  * @param {Object} options - Configuration options
  * @param {Object} options.page - Browser page object
  * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
  * @param {string|Object} options.selector - CSS selector or text selector object
- * @returns {Promise<string|null>} - Valid CSS selector or null if not found
+ * @returns {Promise<string|null>} - Native selector, unique CSS path, or null
  */
 export async function normalizeSelector(options = {}) {
-  const { page, engine, selector } = options;
+  const { page, selector } = options;
 
   requireSelector(selector);
 
@@ -171,59 +115,6 @@ export async function normalizeSelector(options = {}) {
     return null;
   }
 
-  // Handle Playwright text selectors (strings containing :has-text or :text-is)
-  // These are valid for Playwright's locator API but NOT for document.querySelectorAll
-  if (
-    typeof selector === 'string' &&
-    engine === 'playwright' &&
-    isPlaywrightTextSelector(selector)
-  ) {
-    const parsed = parsePlaywrightTextSelector(selector);
-    if (!parsed) {
-      // Could not parse, return as-is and hope for the best
-      return selector;
-    }
-
-    try {
-      // Use page.evaluate to find matching element and generate a valid CSS selector
-      const result = await page.evaluate(({ baseSelector, text, exact }) => {
-        const elements = Array.from(document.querySelectorAll(baseSelector));
-        const matchingElement = elements.find((el) => {
-          const elementText = el.textContent.trim();
-          return exact ? elementText === text : elementText.includes(text);
-        });
-
-        if (!matchingElement) {
-          return null;
-        }
-
-        // Generate a unique selector using data-qa or nth-of-type
-        const dataQa = matchingElement.getAttribute('data-qa');
-        if (dataQa) {
-          return `[data-qa="${dataQa}"]`;
-        }
-
-        // Use nth-of-type as fallback
-        const tagName = matchingElement.tagName.toLowerCase();
-        const siblings = Array.from(
-          matchingElement.parentElement.children
-        ).filter((el) => el.tagName.toLowerCase() === tagName);
-        const index = siblings.indexOf(matchingElement);
-        return `${tagName}:nth-of-type(${index + 1})`;
-      }, parsed);
-
-      return result;
-    } catch (error) {
-      if (isNavigationError(error)) {
-        console.log(
-          '⚠️  Navigation detected during normalizeSelector (Playwright), returning null'
-        );
-        return null;
-      }
-      throw error;
-    }
-  }
-
   // Plain string selector - return as-is
   if (typeof selector === 'string') {
     return selector;
@@ -233,36 +124,11 @@ export async function normalizeSelector(options = {}) {
   if (selector._isPuppeteerTextSelector) {
     try {
       // Find element by text and generate a unique selector
-      const result = await page.evaluate(
-        (baseSelector, text, exact) => {
-          const elements = Array.from(document.querySelectorAll(baseSelector));
-          const matchingElement = elements.find((el) => {
-            const elementText = el.textContent.trim();
-            return exact ? elementText === text : elementText.includes(text);
-          });
-
-          if (!matchingElement) {
-            return null;
-          }
-
-          // Generate a unique selector using data-qa or nth-of-type
-          const dataQa = matchingElement.getAttribute('data-qa');
-          if (dataQa) {
-            return `[data-qa="${dataQa}"]`;
-          }
-
-          // Use nth-of-type as fallback
-          const tagName = matchingElement.tagName.toLowerCase();
-          const siblings = Array.from(
-            matchingElement.parentElement.children
-          ).filter((el) => el.tagName.toLowerCase() === tagName);
-          const index = siblings.indexOf(matchingElement);
-          return `${tagName}:nth-of-type(${index + 1})`;
-        },
-        selector.baseSelector,
-        selector.text,
-        selector.exact
-      );
+      const result = await page.evaluate(textSelectorInPage, {
+        baseSelector: selector.baseSelector,
+        text: selector.text,
+        exact: selector.exact,
+      });
 
       return result;
     } catch (error) {
@@ -296,6 +162,7 @@ export function withTextSelectorSupport(fn, engine, page) {
     // selenium)
     if (
       engine !== 'playwright' &&
+      selector &&
       typeof selector === 'object' &&
       selector._isPuppeteerTextSelector
     ) {
@@ -305,18 +172,6 @@ export function withTextSelectorSupport(fn, engine, page) {
       }
     }
 
-    // Normalize Playwright text selectors (string format with :has-text or :text-is)
-    if (
-      engine === 'playwright' &&
-      typeof selector === 'string' &&
-      isPlaywrightTextSelector(selector)
-    ) {
-      selector = await normalizeSelector({ page, engine, selector });
-      if (!selector) {
-        throw new Error('Element with specified text not found');
-      }
-    }
-
     return fn({ ...options, selector });
   };
 }

package/src/elements/text-selector.js

@@ -0,0 +1,23 @@
+/** Resolve a text match to an unambiguous CSS path without changing the DOM. */
+export function textSelectorInPage({ baseSelector, text, exact }) {
+  const matching = Array.from(document.querySelectorAll(baseSelector)).find(
+    (element) => {
+      const content = element.textContent.trim();
+      return exact ? content === text : content.includes(text);
+    }
+  );
+  if (!matching) {
+    return null;
+  }
+  const steps = [];
+  for (let node = matching; node; node = node.parentElement) {
+    const siblings = Array.from(node.parentElement?.children ?? []).filter(
+      (sibling) => sibling.localName === node.localName
+    );
+    const index = siblings.indexOf(node) + 1;
+    steps.unshift(
+      `${window.CSS.escape(node.localName)}:nth-of-type(${Math.max(1, index)})`
+    );
+  }
+  return steps.join(' > ');
+}

package/src/exports.js

@@ -70,6 +70,12 @@ export {
   launchAndConnectRealBrowser,
   launchRealBrowser,
 } from './browser/real-browser.js';
+export {
+  BROWSER_HANDOFF_VERSION,
+  BrowserHandoffError,
+  reconnectBrowser,
+} from './browser/browser-handoff.js';
+export { INTERRUPTION_MODES } from './utilities/subprocess.js';
 export {
   classifyDifferences,
   compareCommandLines,