browser-commander 0.26.3 → 0.28.0

package/src/elements/reusable.js

@@ -0,0 +1,92 @@
+import { count, isVisible } from './visibility.js';
+import { getLocatorOrElement } from './locators.js';
+import { clickButton } from '../interactions/click.js';
+import { evaluate } from '../utilities/wait.js';
+
+/** Return the first selector in caller order with a match (optionally visible). */
+export async function findFirst({
+  selectors,
+  visible = false,
+  ...options
+} = {}) {
+  if (!Array.isArray(selectors)) {
+    throw new TypeError('selectors must be an array');
+  }
+  for (const selector of selectors) {
+    if (
+      (await count({ ...options, selector })) > 0 &&
+      (!visible || (await isVisible({ ...options, selector })))
+    ) {
+      return selector;
+    }
+  }
+  return null;
+}
+
+/** Match any phrase in body text; Unicode whitespace includes nonbreaking spaces. */
+export function hasText({
+  texts,
+  normalizeWhitespace = false,
+  ...options
+} = {}) {
+  if (!Array.isArray(texts) || texts.some((text) => typeof text !== 'string')) {
+    throw new TypeError('texts must be strings');
+  }
+  return evaluate({
+    ...options,
+    fn: (phrases, normalize) => {
+      const clean = (text) =>
+        normalize ? text.replace(/\s+/gu, ' ').trim() : text;
+      const body = clean(document.body?.textContent ?? '');
+      return phrases.some((text) => body.includes(clean(text)));
+    },
+    args: [texts, normalizeWhitespace],
+  });
+}
+
+/** Observe checked state of the selected checkbox or radio. */
+export async function isChecked(options = {}) {
+  const element = await getLocatorOrElement(options);
+  if (!element) {
+    return false;
+  }
+  const probe = (el) => Boolean(el.checked);
+  return options.engine === 'playwright'
+    ? element.evaluate(probe)
+    : options.page.evaluate(probe, element);
+}
+
+/** Idempotently set a checkbox or radio and verify the resulting state. */
+export async function check({ checked = true, ...options } = {}) {
+  const element = await getLocatorOrElement(options);
+  if (!element) {
+    return { checked: false, changed: false, verified: false };
+  }
+  const type =
+    options.engine === 'playwright'
+      ? await element.evaluate((el) => el.type)
+      : await options.page.evaluate((el) => el.type, element);
+  if (!['checkbox', 'radio'].includes(type)) {
+    throw new TypeError('check requires a checkbox or radio');
+  }
+  if (type === 'radio' && !checked) {
+    throw new TypeError('A radio cannot be unchecked by clicking');
+  }
+  const before = await isChecked({ ...options, selector: element });
+  if (before === checked) {
+    return { checked: before, changed: false, verified: true };
+  }
+  await clickButton({
+    ...options,
+    selector: element,
+    verify: false,
+    waitAfterClick: 0,
+    waitForNavigation: false,
+  });
+  const after = await isChecked({ ...options, selector: element });
+  return {
+    checked: after,
+    changed: before !== after,
+    verified: after === checked,
+  };
+}

package/src/elements/selectors.js

@@ -1,5 +1,9 @@
-import { isNavigationError } from '../core/navigation-safety.js';
-import { createPlaywrightLocator } from './locators.js';
+import {
+  isNavigationError,
+  waitNavigationState,
+  recoverWaitError,
+} from '../core/navigation-safety.js';
+import { createPlaywrightLocator, requireSelector } from './locators.js';
 
 /**
  * Query single element
@@ -9,67 +13,38 @@ import { createPlaywrightLocator } from './locators.js';
  * @param {string} options.selector - CSS selector
  * @returns {Promise<Object|null>} - Element handle or null
  */
-export async function querySelector(options = {}) {
-  const { page, engine, selector } = options;
-
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+export function querySelector(options = {}) {
+  return queryElements(options, true);
+}
 
-  try {
-    if (engine === 'playwright') {
-      const locator = createPlaywrightLocator({ page, selector }).first();
-      const count = await locator.count();
-      return count > 0 ? locator : null;
-    } else {
-      return await page.$(selector);
-    }
-  } catch (error) {
-    if (isNavigationError(error)) {
-      console.log(
-        '⚠️  Navigation detected during querySelector, returning null'
-      );
-      return null;
-    }
-    throw error;
-  }
+/** Return every matching element with the same navigation recovery as querySelector. */
+export function querySelectorAll(options = {}) {
+  return queryElements(options, false);
 }
 
-/**
- * Query all elements
- * @param {Object} options - Configuration options
- * @param {Object} options.page - Browser page object
- * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
- * @param {string} options.selector - CSS selector
- * @returns {Promise<Array>} - Array of element handles
- */
-export async function querySelectorAll(options = {}) {
+async function queryElements(options, single) {
+  requireSelector(options.selector);
   const { page, engine, selector } = options;
-
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
-
   try {
-    if (engine === 'playwright') {
-      const locator = createPlaywrightLocator({ page, selector });
-      const count = await locator.count();
-      const elements = [];
-      for (let i = 0; i < count; i++) {
-        elements.push(locator.nth(i));
-      }
-      return elements;
-    } else {
-      return await page.$$(selector);
+    if (engine !== 'playwright') {
+      return single ? await page.$(selector) : await page.$$(selector);
     }
+    const matching = createPlaywrightLocator({ page, selector });
+    const locator = single ? matching.first() : matching;
+    const total = await locator.count();
+    return single
+      ? total > 0
+        ? locator
+        : null
+      : Array.from({ length: total }, (_, index) => locator.nth(index));
   } catch (error) {
-    if (isNavigationError(error)) {
-      console.log(
-        '⚠️  Navigation detected during querySelectorAll, returning empty array'
-      );
-      return [];
+    if (!isNavigationError(error)) {
+      throw error;
     }
-    throw error;
+    console.log(
+      `⚠️  Navigation detected during ${single ? 'querySelector' : 'querySelectorAll'}, recovering gracefully`
+    );
+    return single ? null : [];
   }
 }
 
@@ -175,9 +150,7 @@ function parsePlaywrightTextSelector(selector) {
 export async function normalizeSelector(options = {}) {
   const { page, engine, selector } = options;
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
 
   // DEFENSIVE: Validate selector type - must be string or Puppeteer text selector object
   // Arrays and other invalid types should be rejected to prevent downstream querySelectorAll errors
@@ -360,19 +333,11 @@ export function withTextSelectorSupport(fn, engine, page) {
  * @returns {Promise<boolean>} - True if selector found, false on navigation
  */
 export async function waitForSelector(options = {}) {
-  const {
-    page,
-    engine,
-    selector,
-    visible = true,
-    timeout = 5000,
-    throwOnNavigation = true,
-  } = options;
-
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  const { page, engine, selector, visible = true, timeout = 5000 } = options;
+
+  requireSelector(selector);
 
+  const initial = waitNavigationState(page, options.navigationManager);
   try {
     if (engine === 'playwright') {
       const locator = createPlaywrightLocator({ page, selector });
@@ -384,16 +349,7 @@ export async function waitForSelector(options = {}) {
       await page.waitForSelector(selector, { visible, timeout });
     }
     return true;
-  } catch (error) {
-    if (isNavigationError(error)) {
-      console.log(
-        '⚠️  Navigation detected during waitForSelector, recovering gracefully'
-      );
-      if (throwOnNavigation) {
-        throw error;
-      }
-      return false;
-    }
-    throw error;
+  } catch (caught) {
+    return recoverWaitError(caught, options, initial, 'waitForSelector', false);
   }
 }

package/src/elements/visibility.js

@@ -1,6 +1,6 @@
 import { TIMING } from '../core/constants.js';
 import { isNavigationError } from '../core/navigation-safety.js';
-import { getLocatorOrElement } from './locators.js';
+import { getLocatorOrElement, requireSelector } from './locators.js';
 
 /**
  * Check if element is visible
@@ -13,13 +13,11 @@ import { getLocatorOrElement } from './locators.js';
 export async function isVisible(options = {}) {
   const { page, engine, selector } = options;
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
 
   try {
     if (engine === 'playwright') {
-      const locator = await getLocatorOrElement({ page, engine, selector });
+      const locator = await getLocatorOrElement(options);
       try {
         await locator.waitFor({
           state: 'visible',
@@ -30,7 +28,7 @@ export async function isVisible(options = {}) {
         return false;
       }
     } else {
-      const element = await getLocatorOrElement({ page, engine, selector });
+      const element = await getLocatorOrElement(options);
       if (!element) {
         return false;
       }
@@ -56,27 +54,20 @@ export async function isVisible(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 locator
- * @param {Array<string>} options.disabledClasses - Additional CSS classes that indicate disabled state (default: ['magritte-button_loading'])
+ * @param {Array<string>} options.disabledClasses - Additional CSS classes that indicate disabled state (default: ['disabled'])
  * @returns {Promise<boolean>} - True if enabled
  */
 export async function isEnabled(options = {}) {
-  const {
-    page,
-    engine,
-    selector,
-    disabledClasses = ['magritte-button_loading'],
-  } = options;
+  const { page, engine, selector, disabledClasses = ['disabled'] } = options;
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
 
   try {
     if (engine === 'playwright') {
       // For Playwright, use locator API
       const locator =
         typeof selector === 'string'
-          ? page.locator(selector).first()
+          ? (await getLocatorOrElement(options)).first()
           : selector;
       return await locator.evaluate((el, classes) => {
         const isDisabled =
@@ -87,7 +78,7 @@ export async function isEnabled(options = {}) {
       }, disabledClasses);
     } else {
       // For Puppeteer (selector should already be normalized by withTextSelectorSupport wrapper)
-      const element = await getLocatorOrElement({ page, engine, selector });
+      const element = await getLocatorOrElement(options);
       if (!element) {
         return false;
       }
@@ -124,9 +115,7 @@ export async function isEnabled(options = {}) {
 export async function count(options = {}) {
   const { page, engine, selector } = options;
 
-  if (!selector) {
-    throw new Error('selector is required in options');
-  }
+  requireSelector(selector);
 
   try {
     // Handle Puppeteer text selectors
@@ -155,9 +144,37 @@ export async function count(options = {}) {
     }
 
     if (engine === 'playwright') {
+      if (options.visible) {
+        return await page
+          .locator(selector)
+          .evaluateAll(
+            (elements) =>
+              elements.filter(
+                (element) =>
+                  element.getClientRects().length > 0 &&
+                  element.checkVisibility({ visibilityProperty: true })
+              ).length
+          );
+      }
       return await page.locator(selector).count();
     } else {
       const elements = await page.$$(selector);
+      if (options.visible) {
+        let visible = 0;
+        for (const element of elements) {
+          if (
+            await page.evaluate(
+              (element) =>
+                element.getClientRects().length > 0 &&
+                element.checkVisibility({ visibilityProperty: true }),
+              element
+            )
+          ) {
+            visible += 1;
+          }
+        }
+        return visible;
+      }
       return elements.length;
     }
   } catch (error) {

package/src/exports.js

@@ -328,3 +328,17 @@ export {
   SafariUnsupportedError,
   openSafariSettings,
 } from './browser/safari-support.js';
+
+export { BrowserLaunchError } from './browser/launch-diagnostics.js';
+
+export { findFirst, hasText, isChecked, check } from './elements/reusable.js';
+export { setCookies, clearCookies } from './browser/session-cookies.js';
+export {
+  readFlag,
+  uninstallClickListener,
+} from './high-level/universal-logic.js';
+
+export {
+  findSiteSessions,
+  readBrowserCookieSession,
+} from './browser/browser-cookie-session.js';

package/src/factory.js

@@ -22,7 +22,7 @@ import {
 } from './core/page-trigger-manager.js';
 import { createBoundFunctions } from './bindings.js';
 import { attachDownloads } from './downloads/attach.js';
-import { startTrace } from './traces/recorder.js';
+import { attachCommanderFeatures } from './core/commander-features.js';
 import { createCdpSession } from './browser/cdp-session.js';
 
 /**
@@ -66,7 +66,7 @@ export function makeBrowserCommander(options = {}) {
       page,
       engine,
       log,
-      idleTimeout: 30000, // Wait 30 seconds without requests before considering network idle
+      idleTimeout: options.networkIdleForMs ?? 30000, // Wait 30 seconds without requests before considering network idle
     });
     networkTracker.startTracking();
   }
@@ -92,6 +92,7 @@ export function makeBrowserCommander(options = {}) {
       log,
       networkTracker,
     });
+    navigationManager.configure(navigationOptions(options));
     navigationManager.startListening();
 
     // Create PageSession factory
@@ -159,7 +160,6 @@ export function makeBrowserCommander(options = {}) {
 
     // All bound functions
     ...boundFunctions,
-
     // Managed downloads (issue #88). Present once a manager is attached,
     // either by passing the one launchBrowser() returned or by calling
     // configureDownloads() on an existing commander.
@@ -192,15 +192,6 @@ export function makeBrowserCommander(options = {}) {
      */
     createCdpSession: () => createCdpSession(page, { engine }),
 
-    /**
-     * Start recording a privacy-aware trace of this session (issue #87).
-     *
-     * @param {Object} [traceOptions] - {output, mode, screenshots, dom, events, privacy, limits}
-     * @returns {Promise<Object>} The running trace: {checkpoint, event, stop}
-     */
-    startTrace: (traceOptions = {}) =>
-      startTrace({ commander, page, log, ...traceOptions }),
-
     // Lifecycle
     destroy,
 
@@ -215,16 +206,16 @@ export function makeBrowserCommander(options = {}) {
     // Subscribe to navigation events (legacy API)
     onNavigationStart: navigationManager
       ? (fn) => navigationManager.on('onNavigationStart', fn)
-      : () => {},
+      : () => () => {},
     onNavigationComplete: navigationManager
       ? (fn) => navigationManager.on('onNavigationComplete', fn)
-      : () => {},
+      : () => () => {},
     onUrlChange: navigationManager
       ? (fn) => navigationManager.on('onUrlChange', fn)
-      : () => {},
+      : () => () => {},
     onPageReady: navigationManager
       ? (fn) => navigationManager.on('onPageReady', fn)
-      : () => {},
+      : () => () => {},
 
     // Abort handling - check these to stop operations when navigation occurs
     shouldAbort: navigationManager
@@ -295,5 +286,15 @@ export function makeBrowserCommander(options = {}) {
     pageTriggerManager.initialize(commander);
   }
 
+  attachCommanderFeatures(commander, options, makeBrowserCommander);
   return commander;
 }
+
+function navigationOptions(options) {
+  return {
+    ...(options.navigationManager ?? {}),
+    ...(options.networkIdleTimeout === undefined
+      ? {}
+      : { networkIdleTimeout: options.networkIdleTimeout }),
+  };
+}

package/src/high-level/universal-logic.js

@@ -101,26 +101,29 @@ export async function installClickListener(options = {}) {
 
   const result = await safeEvaluate({
     fn: (text, key) => {
-      document.addEventListener(
-        'click',
-        (event) => {
-          let element = event.target;
-          while (element && element !== document.body) {
-            const elementText = element.textContent?.trim() || '';
-            if (
-              elementText === text ||
-              ((element.tagName === 'A' || element.tagName === 'BUTTON') &&
-                elementText.includes(text))
-            ) {
-              console.log(`[Click Listener] Detected click on ${text} button!`);
-              window.sessionStorage.setItem(key, 'true');
-              break;
-            }
-            element = element.parentElement;
+      window.__browserCommanderClickListeners ??= new Map();
+      const previous = window.__browserCommanderClickListeners.get(key);
+      if (previous) {
+        document.removeEventListener('click', previous, true);
+      }
+      const listener = (event) => {
+        let element = event.target;
+        while (element && element !== document.body) {
+          const elementText = element.textContent?.trim() || '';
+          if (
+            elementText === text ||
+            ((element.tagName === 'A' || element.tagName === 'BUTTON') &&
+              elementText.includes(text))
+          ) {
+            console.log(`[Click Listener] Detected click on ${text} button!`);
+            window.sessionStorage.setItem(key, 'true');
+            break;
           }
-        },
-        true
-      );
+          element = element.parentElement;
+        }
+      };
+      window.__browserCommanderClickListeners.set(key, listener);
+      document.addEventListener('click', listener, true);
     },
     args: [buttonText, storageKey],
   });
@@ -176,6 +179,7 @@ export async function findToggleButton(options = {}) {
     findByText,
     dataQaSelectors = [],
     textToFind,
+    texts = textToFind ? [textToFind] : [],
     elementTypes = ['button', 'a', 'span'],
   } = options;
 
@@ -188,10 +192,10 @@ export async function findToggleButton(options = {}) {
   }
 
   // Fallback to text search
-  if (textToFind) {
+  for (const text of texts) {
     for (const elementType of elementTypes) {
       const selector = await findByText({
-        text: textToFind,
+        text,
         selector: elementType,
       });
       const elemCount = await count({ selector });
@@ -203,3 +207,35 @@ export async function findToggleButton(options = {}) {
 
   return null;
 }
+
+/** Read without clearing; interruption is distinct from an unset flag. */
+export async function readFlag({ evaluate, storageKey } = {}) {
+  try {
+    const set = await evaluate({
+      fn: (key) => window.sessionStorage.getItem(key) === 'true',
+      args: [storageKey],
+    });
+    return { status: 'observed', set };
+  } catch (error) {
+    if (isNavigationError(error)) {
+      return { status: 'interrupted', set: null };
+    }
+    throw error;
+  }
+}
+
+/** Uninstall only the click listener installed for this storage key. */
+export function uninstallClickListener({ evaluate, storageKey } = {}) {
+  return evaluate({
+    fn: (key) => {
+      const listener = window.__browserCommanderClickListeners?.get(key);
+      if (!listener) {
+        return false;
+      }
+      document.removeEventListener('click', listener, true);
+      window.__browserCommanderClickListeners.delete(key);
+      return true;
+    },
+    args: [storageKey],
+  });
+}

package/src/index.js

@@ -18,3 +18,5 @@ export {
 
 // Re-export all public APIs from exports module
 export * from './exports.js';
+export * from './capture/index.js';
+export { connectOrLaunch } from './browser/persistent-session.js';

package/src/interactions/click.js

@@ -31,6 +31,25 @@ function isInterrupted(error) {
   return isNavigationError(error) || isActionStoppedError(error);
 }
 
+function waitInterruptedByNavigation({
+  error,
+  page,
+  navigationManager,
+  startUrl,
+  startSessionId,
+  preparationFinished,
+}) {
+  const timedOut =
+    error.name === 'TimeoutError' ||
+    error.name === 'NavigationInterruptedError' ||
+    /timeout|timed out/i.test(error.message);
+  const navigationChanged =
+    page.url() !== startUrl ||
+    (startSessionId !== undefined &&
+      navigationManager?.getSessionId?.() !== startSessionId);
+  return timedOut && navigationChanged && !preparationFinished;
+}
+
 /**
  * Read the target element's observable state under the click's own budget.
  *
@@ -709,6 +728,7 @@ async function prepareElement(options = {}) {
     log,
     verbose = false,
     selector,
+    index,
     scrollIntoView: shouldScroll = true,
     waitAfterScroll,
     smoothScroll = true,
@@ -719,6 +739,7 @@ async function prepareElement(options = {}) {
     page,
     engine,
     selector,
+    index,
     timeout,
   });
 
@@ -973,6 +994,7 @@ export async function clickButton(options = {}) {
 
   const startUrl = page.url();
   const startSessionId = navigationManager?.getSessionId?.();
+  let preparationFinished = false;
 
   try {
     const prepareResult = await prepareElement({
@@ -982,6 +1004,7 @@ export async function clickButton(options = {}) {
       log,
       verbose,
       selector,
+      index: options.index,
       scrollIntoView: activationOptions.scroll === CLICK_SCROLL.AUTO,
       waitAfterScroll,
       smoothScroll,
@@ -1009,6 +1032,7 @@ export async function clickButton(options = {}) {
       });
     }
 
+    preparationFinished = true;
     const clickResult = await clickElement({
       page,
       engine,
@@ -1052,6 +1076,29 @@ export async function clickButton(options = {}) {
       actionId,
     });
   } catch (error) {
+    if (
+      waitInterruptedByNavigation({
+        error,
+        page,
+        navigationManager,
+        startUrl,
+        startSessionId,
+        preparationFinished,
+      })
+    ) {
+      return makeClickResult({
+        status: CLICK_STATUS.INTERRUPTED,
+        dispatched: false,
+        effect: CLICK_EFFECT.NOT_OBSERVED,
+        navigated: true,
+        reason: 'navigation interrupted the element wait before the click',
+        evidence: [
+          evidence('interrupted', { message: error.message, phase: 'prepare' }),
+        ],
+        elapsedMs: elapsed(),
+        actionId,
+      });
+    }
     if (isInterrupted(error)) {
       log.debug(
         () =>