browser-commander 0.5.4 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- Add emulateMedia API for unified color scheme emulation across all engines
+
+  Implements `emulateMedia({ colorScheme })` as a unified API for color scheme emulation (prefers-color-scheme) across Playwright and Puppeteer engines. Also adds `colorScheme` as a launch option to `launchBrowser`.
+
+  Fixes #36
+
+- 785eb13: Add unified dialog event handling API (`page.on('dialog', handler)`)
+  - New `DialogManager` (`core/dialog-manager.js`) that registers `page.on('dialog')` for both Playwright and Puppeteer
+  - `commander.onDialog(handler)` — register a handler for browser dialogs (alert, confirm, prompt, beforeunload)
+  - `commander.offDialog(handler)` — remove a previously registered handler
+  - `commander.clearDialogHandlers()` — remove all dialog handlers
+  - Auto-dismiss behavior when no handlers are registered (prevents page from freezing)
+  - `enableDialogManager` option (default: `true`) to opt out if needed
+  - Exports `createDialogManager` for low-level usage
+  - 19 new unit tests covering all dialog handling scenarios
+
+- 80ec5f7: Add page-level keyboard interaction support (issue #37)
+
+  Expose keyboard input methods on the commander object, enabling users to press
+  keys, type text, and hold modifier keys without accessing the raw page object
+  directly. New API: `commander.keyboard.press()`, `commander.keyboard.type()`,
+  `commander.keyboard.down()`, `commander.keyboard.up()`, and flat aliases
+  `commander.pressKey()`, `commander.typeText()`, `commander.keyDown()`,
+  `commander.keyUp()`.
+
+## 0.6.0
+
+### Minor Changes
+
+- 7d83530: Document extensibility escape hatch: `commander.page` and `launchBrowser()` return values expose the raw underlying Playwright/Puppeteer page object as an official mechanism for accessing engine-specific APIs not yet supported by browser-commander (e.g. `page.pdf()`, `page.emulateMedia()`, `page.keyboard`, `page.on('dialog', ...)`). Adds tests verifying `commander.page` is the exact raw page object.
+
 ## 0.5.4
 
 ### Patch Changes

package/README.md

@@ -206,6 +206,38 @@ const { browser, page } = await launchBrowser({
 
 The `args` option allows passing custom Chrome arguments, which is useful for headless server environments (Docker, CI/CD) that require flags like `--no-sandbox`.
 
+The `colorScheme` option allows setting the initial color scheme (`'light'`, `'dark'`, or `'no-preference'`) at launch time for screenshot services and testing tools:
+
+```javascript
+const { browser, page } = await launchBrowser({
+  engine: 'playwright',
+  colorScheme: 'dark', // 'light', 'dark', or 'no-preference'
+});
+```
+
+### commander.emulateMedia(options)
+
+Emulate media features (e.g. `prefers-color-scheme`) for the current page:
+
+```javascript
+// Set dark mode
+await commander.emulateMedia({ colorScheme: 'dark' });
+
+// Set light mode
+await commander.emulateMedia({ colorScheme: 'light' });
+
+// Reset to system default
+await commander.emulateMedia({ colorScheme: null });
+```
+
+Works with both Playwright (`page.emulateMedia`) and Puppeteer (`page.emulateMediaFeatures`). Can also be used as a standalone function:
+
+```javascript
+import { emulateMedia } from 'browser-commander';
+
+await emulateMedia({ page, engine: 'playwright', colorScheme: 'dark' });
+```
+
 ### makeBrowserCommander(options)
 
 ```javascript
@@ -318,6 +350,67 @@ action: async (ctx) => {
 };
 ```
 
+## Extensibility / Escape Hatch
+
+`browser-commander` cannot anticipate every browser API. When you need an API that is not yet supported, you can access the raw underlying engine objects directly as an **official extensibility escape hatch**.
+
+### Using `commander.page` for engine-specific APIs
+
+`makeBrowserCommander` exposes `commander.page` — this is the **raw Playwright or Puppeteer page object**, not a wrapper. Use it directly for APIs browser-commander doesn't yet support:
+
+```javascript
+const { browser, page } = await launchBrowser({ engine: 'playwright' });
+const commander = makeBrowserCommander({ page });
+
+// Access engine-specific API via commander.page
+// Example: PDF generation (issue #35)
+const pdfBuffer = await commander.page.pdf({
+  format: 'A4',
+  printBackground: true,
+  margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' },
+});
+
+// Example: Color scheme emulation (issue #36)
+await commander.page.emulateMedia({ colorScheme: 'dark' });
+
+// Example: Keyboard interactions (issue #37)
+await commander.page.keyboard.press('Escape');
+
+// Example: Dialog handling (issue #38)
+commander.page.on('dialog', async (dialog) => {
+  await dialog.dismiss();
+});
+```
+
+### Using `launchBrowser` raw return values
+
+`launchBrowser()` returns the raw `{ browser, page }` objects from the underlying engine. You can use these directly:
+
+```javascript
+const { browser, page } = await launchBrowser({ engine: 'playwright' });
+
+// Use raw page directly for engine-specific APIs
+await page.pdf({ format: 'A4' });
+
+// Or create a commander for the unified API
+const commander = makeBrowserCommander({ page });
+```
+
+### No more `_page` hacks
+
+If you previously used `page._page || page` to access the raw page, replace it with `commander.page`:
+
+```javascript
+// BEFORE (fragile hack):
+const rawPage = page._page || page;
+await rawPage.pdf({ format: 'A4' });
+
+// AFTER (official API):
+await commander.page.pdf({ format: 'A4' });
+```
+
+This is the **official extensibility mechanism** while awaiting browser-commander to add first-class support for these APIs. Please [report missing APIs](https://github.com/link-foundation/browser-commander/issues) so they can be added.
+
 ## Debugging
 
 Enable verbose mode for detailed logs:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.5.4",
+  "version": "0.7.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",

package/src/README.md

@@ -341,6 +341,7 @@ browser-commander/
 ├── interactions/
 │   ├── click.js                # clickButton, clickElement
 │   ├── fill.js                 # fillTextArea
+│   ├── keyboard.js             # pressKey, typeText, keyDown, keyUp
 │   └── scroll.js               # scrollIntoView
 ├── utilities/
 │   ├── wait.js                 # wait(), evaluate()
@@ -436,6 +437,36 @@ await commander.fillTextArea({
 });
 ```
 
+### commander.keyboard
+
+Page-level keyboard input, independent of any specific element. Useful for
+dismissing dialogs, submitting forms via Enter, tab navigation, etc.
+
+```javascript
+// Press a key (e.g. dismiss a modal)
+await commander.keyboard.press('Escape');
+
+// Type text at the page level (sent to the currently focused element)
+await commander.keyboard.type('Hello World');
+
+// Modifier key combinations
+await commander.keyboard.down('Control');
+await commander.keyboard.press('a'); // Select All
+await commander.keyboard.up('Control');
+```
+
+Also available as flat functions:
+
+```javascript
+await commander.pressKey({ key: 'Enter' });
+await commander.typeText({ text: 'some text' });
+await commander.keyDown({ key: 'Shift' });
+await commander.keyUp({ key: 'Shift' });
+```
+
+Key names follow the [Playwright keyboard convention](https://playwright.dev/docs/api/class-keyboard#keyboard-press):
+`'Escape'`, `'Enter'`, `'Tab'`, `'ArrowUp'`, `'ArrowDown'`, `'Control'`, `'Shift'`, `'Alt'`, etc.
+
 ### commander.destroy()
 
 ```javascript

package/src/bindings.js

@@ -12,6 +12,7 @@ import {
   waitForPageReady,
   waitAfterAction,
 } from './browser/navigation.js';
+import { emulateMedia } from './browser/media.js';
 import {
   createPlaywrightLocator,
   getLocatorOrElement,
@@ -52,6 +53,7 @@ import {
   checkAndClearFlag,
   findToggleButton,
 } from './high-level/universal-logic.js';
+import { pressKey, typeText, keyDown, keyUp } from './interactions/keyboard.js';
 
 /**
  * Create bound functions for a browser commander instance
@@ -191,6 +193,9 @@ export function createBoundFunctions(options = {}) {
   const fillTextAreaBound = (opts) =>
     fillTextArea({ ...opts, page, engine, wait: waitBound, log });
 
+  // Bound media emulation
+  const emulateMediaBound = (opts) => emulateMedia({ ...opts, page, engine });
+
   // Bound high-level
   const waitForUrlConditionBound = (opts) =>
     waitForUrlCondition({
@@ -210,6 +215,12 @@ export function createBoundFunctions(options = {}) {
       findByText: findByTextBound,
     });
 
+  // Bound keyboard
+  const pressKeyBound = (opts) => pressKey({ ...opts, page, engine });
+  const typeTextBound = (opts) => typeText({ ...opts, page, engine });
+  const keyDownBound = (opts) => keyDown({ ...opts, page, engine });
+  const keyUpBound = (opts) => keyUp({ ...opts, page, engine });
+
   // Wrap functions with text selector support
   const fillTextAreaWrapped = withTextSelectorSupport(
     fillTextAreaBound,
@@ -267,6 +278,7 @@ export function createBoundFunctions(options = {}) {
 
     // Main API functions
     wait: waitBound,
+    emulateMedia: emulateMediaBound,
     fillTextArea: fillTextAreaWrapped,
     clickButton: clickButtonWrapped,
     evaluate: evaluateBound,
@@ -294,5 +306,20 @@ export function createBoundFunctions(options = {}) {
     installClickListener: installClickListenerBound,
     checkAndClearFlag: checkAndClearFlagBound,
     findToggleButton: findToggleButtonBound,
+
+    // Page-level keyboard interaction
+    // Usage: await commander.keyboard.press('Escape')
+    keyboard: {
+      press: (key) => pressKeyBound({ key }),
+      type: (text) => typeTextBound({ text }),
+      down: (key) => keyDownBound({ key }),
+      up: (key) => keyUpBound({ key }),
+    },
+
+    // Also expose as individual flat functions for functional-style usage
+    pressKey: pressKeyBound,
+    typeText: typeTextBound,
+    keyDown: keyDownBound,
+    keyUp: keyUpBound,
   };
 }

package/src/browser/launcher.js

@@ -2,6 +2,7 @@ import path from 'path';
 import os from 'os';
 import { CHROME_ARGS } from '../core/constants.js';
 import { disableTranslateInPreferences } from '../core/preferences.js';
+import { emulateMedia } from './media.js';
 
 /**
  * Launch browser with default configuration
@@ -12,6 +13,7 @@ import { disableTranslateInPreferences } from '../core/preferences.js';
  * @param {number} options.slowMo - Slow down operations by ms (default: 150 for Playwright, 0 for Puppeteer)
  * @param {boolean} options.verbose - Enable verbose logging (default: false)
  * @param {string[]} options.args - Custom Chrome arguments to append to the default CHROME_ARGS
+ * @param {string|null} [options.colorScheme] - Emulate color scheme: 'light', 'dark', 'no-preference', or null to reset
  * @returns {Promise<Object>} - Object with browser and page
  */
 export async function launchBrowser(options = {}) {
@@ -22,6 +24,7 @@ export async function launchBrowser(options = {}) {
     slowMo = engine === 'playwright' ? 150 : 0,
     verbose = false,
     args = [],
+    colorScheme,
   } = options;
 
   // Combine default CHROME_ARGS with custom args
@@ -50,14 +53,22 @@ export async function launchBrowser(options = {}) {
 
   if (engine === 'playwright') {
     const { chromium } = await import('playwright');
-    browser = await chromium.launchPersistentContext(userDataDir, {
+    const contextOptions = {
       headless,
       slowMo,
       chromiumSandbox: true,
       viewport: null,
       args: chromeArgs,
       ignoreDefaultArgs: ['--enable-automation'],
-    });
+    };
+    // Playwright supports colorScheme as a context-level launch option
+    if (colorScheme !== undefined) {
+      contextOptions.colorScheme = colorScheme;
+    }
+    browser = await chromium.launchPersistentContext(
+      userDataDir,
+      contextOptions
+    );
     page = browser.pages()[0];
   } else {
     const puppeteer = await import('puppeteer');
@@ -75,6 +86,20 @@ export async function launchBrowser(options = {}) {
     console.log(`✅ Browser launched with ${engine} engine`);
   }
 
+  // Apply color scheme emulation if requested (Puppeteer needs page-level emulation)
+  if (colorScheme !== undefined && engine === 'puppeteer') {
+    try {
+      await emulateMedia({ page, engine, colorScheme });
+      if (verbose) {
+        console.log(`✅ Color scheme set to "${colorScheme}"`);
+      }
+    } catch (error) {
+      if (verbose) {
+        console.log(`⚠️  Could not set color scheme: ${error.message}`);
+      }
+    }
+  }
+
   // Unfocus address bar automatically after browser launch
   // Using page.bringToFront() - confirmed working solution
   try {

package/src/browser/media.js

@@ -0,0 +1,57 @@
+/**
+ * Browser Commander - Media Emulation
+ * Provides unified color scheme emulation across Playwright and Puppeteer.
+ */
+
+const VALID_COLOR_SCHEMES = ['light', 'dark', 'no-preference'];
+
+/**
+ * Emulate media features (e.g. prefers-color-scheme) for the page.
+ *
+ * @param {Object} options
+ * @param {Object} options.page - Playwright or Puppeteer page object
+ * @param {string} options.engine - Engine type: 'playwright' or 'puppeteer'
+ * @param {string|null} [options.colorScheme] - Color scheme: 'light', 'dark', 'no-preference', or null to reset
+ * @returns {Promise<void>}
+ */
+export async function emulateMedia({ page, engine, colorScheme } = {}) {
+  if (!page) {
+    throw new Error('page is required in emulateMedia');
+  }
+  if (!engine) {
+    throw new Error('engine is required in emulateMedia');
+  }
+
+  if (colorScheme !== null && colorScheme !== undefined) {
+    if (!VALID_COLOR_SCHEMES.includes(colorScheme)) {
+      throw new Error(
+        `Invalid colorScheme: "${colorScheme}". Expected one of: ${VALID_COLOR_SCHEMES.join(', ')}, or null`
+      );
+    }
+  }
+
+  if (engine === 'playwright') {
+    // Playwright supports emulateMedia natively
+    const mediaOptions = {};
+    if (colorScheme !== undefined) {
+      mediaOptions.colorScheme = colorScheme;
+    }
+    await page.emulateMedia(mediaOptions);
+  } else if (engine === 'puppeteer') {
+    // Puppeteer supports emulateMediaFeatures since v5.4.0
+    if (colorScheme === null || colorScheme === undefined) {
+      // Reset to default
+      await page.emulateMediaFeatures([
+        { name: 'prefers-color-scheme', value: '' },
+      ]);
+    } else {
+      await page.emulateMediaFeatures([
+        { name: 'prefers-color-scheme', value: colorScheme },
+      ]);
+    }
+  } else {
+    throw new Error(
+      `Unsupported engine: ${engine}. Expected 'playwright' or 'puppeteer'`
+    );
+  }
+}

package/src/core/dialog-manager.js

@@ -0,0 +1,158 @@
+/**
+ * DialogManager - Centralized dialog/alert event handling
+ *
+ * This module provides:
+ * - Unified dialog event handling for Playwright and Puppeteer
+ * - Session-aware handler registration (auto-cleanup on navigation)
+ * - Support for alert, confirm, prompt, and beforeunload dialogs
+ *
+ * Both Playwright and Puppeteer expose page.on('dialog', handler)
+ * with a Dialog object that has accept(), dismiss(), message(), and type().
+ */
+
+/**
+ * Create a DialogManager instance for a page
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Playwright or Puppeteer page object
+ * @param {string} options.engine - 'playwright' or 'puppeteer'
+ * @param {Function} options.log - Logger instance
+ * @returns {Object} - DialogManager API
+ */
+export function createDialogManager(options = {}) {
+  const { page, engine, log } = options;
+
+  if (!page) {
+    throw new Error('page is required in options');
+  }
+
+  // User-registered dialog handlers
+  const handlers = [];
+
+  // Whether we are currently listening to the page's dialog event
+  let isListening = false;
+
+  /**
+   * Internal handler that is registered on the page.
+   * It calls all user-registered handlers in order.
+   * If no handler has accepted/dismissed the dialog after all handlers run,
+   * we auto-dismiss to prevent the page from freezing.
+   */
+  async function handleDialog(dialog) {
+    const type =
+      typeof dialog.type === 'function' ? dialog.type() : dialog.type;
+    const message =
+      typeof dialog.message === 'function' ? dialog.message() : dialog.message;
+
+    log.debug(() => `💬 Dialog event: type="${type}", message="${message}"`);
+
+    if (handlers.length === 0) {
+      log.debug(
+        () =>
+          `⚠️  No dialog handlers registered — auto-dismissing "${type}" dialog`
+      );
+      try {
+        await dialog.dismiss();
+      } catch (e) {
+        log.debug(() => `⚠️  Failed to auto-dismiss dialog: ${e.message}`);
+      }
+      return;
+    }
+
+    let handled = false;
+
+    for (const fn of handlers) {
+      try {
+        await fn(dialog);
+        handled = true;
+      } catch (e) {
+        log.debug(() => `⚠️  Error in dialog handler: ${e.message}`);
+      }
+    }
+
+    // Safety net: if no handler successfully ran, auto-dismiss
+    if (!handled) {
+      log.debug(
+        () =>
+          `⚠️  All dialog handlers failed — auto-dismissing "${type}" dialog`
+      );
+      try {
+        await dialog.dismiss();
+      } catch (e) {
+        log.debug(() => `⚠️  Failed to auto-dismiss dialog: ${e.message}`);
+      }
+    }
+  }
+
+  /**
+   * Add a dialog event handler
+   * @param {Function} handler - Async function receiving (dialog) object
+   *   dialog.type()    → 'alert' | 'confirm' | 'prompt' | 'beforeunload'
+   *   dialog.message() → The dialog message text
+   *   dialog.accept(text?) → Accept / confirm (optional text for prompts)
+   *   dialog.dismiss() → Dismiss / cancel the dialog
+   */
+  function onDialog(handler) {
+    if (typeof handler !== 'function') {
+      throw new Error('Dialog handler must be a function');
+    }
+    handlers.push(handler);
+    log.debug(() => `🔌 Dialog handler registered (total: ${handlers.length})`);
+  }
+
+  /**
+   * Remove a dialog event handler
+   * @param {Function} handler - The handler function to remove
+   */
+  function offDialog(handler) {
+    const index = handlers.indexOf(handler);
+    if (index !== -1) {
+      handlers.splice(index, 1);
+      log.debug(
+        () => `🔌 Dialog handler removed (remaining: ${handlers.length})`
+      );
+    }
+  }
+
+  /**
+   * Remove all dialog event handlers
+   */
+  function clearDialogHandlers() {
+    handlers.length = 0;
+    log.debug(() => '🔌 All dialog handlers cleared');
+  }
+
+  /**
+   * Start listening for dialog events on the page
+   */
+  function startListening() {
+    if (isListening) {
+      return;
+    }
+    page.on('dialog', handleDialog);
+    isListening = true;
+    log.debug(() => '🔌 Dialog manager started');
+  }
+
+  /**
+   * Stop listening for dialog events on the page
+   */
+  function stopListening() {
+    if (!isListening) {
+      return;
+    }
+    page.off('dialog', handleDialog);
+    isListening = false;
+    log.debug(() => '🔌 Dialog manager stopped');
+  }
+
+  return {
+    // Handler registration
+    onDialog,
+    offDialog,
+    clearDialogHandlers,
+
+    // Lifecycle
+    startListening,
+    stopListening,
+  };
+}

package/src/core/engine-adapter.js

@@ -176,6 +176,46 @@ export class EngineAdapter {
     throw new Error('focus() must be implemented by subclass');
   }
 
+  // ============================================================================
+  // Page-level Keyboard Operations
+  // ============================================================================
+
+  /**
+   * Press a key at the page level (e.g. 'Escape', 'Enter', 'Tab')
+   * @param {string} key - Key name (Playwright/Puppeteer key format)
+   * @returns {Promise<void>}
+   */
+  async keyboardPress(key) {
+    throw new Error('keyboardPress() must be implemented by subclass');
+  }
+
+  /**
+   * Type text at the page level (dispatches key events for each character)
+   * @param {string} text - Text to type
+   * @returns {Promise<void>}
+   */
+  async keyboardType(text) {
+    throw new Error('keyboardType() must be implemented by subclass');
+  }
+
+  /**
+   * Hold a key down at the page level
+   * @param {string} key - Key name
+   * @returns {Promise<void>}
+   */
+  async keyboardDown(key) {
+    throw new Error('keyboardDown() must be implemented by subclass');
+  }
+
+  /**
+   * Release a held key at the page level
+   * @param {string} key - Key name
+   * @returns {Promise<void>}
+   */
+  async keyboardUp(key) {
+    throw new Error('keyboardUp() must be implemented by subclass');
+  }
+
   // ============================================================================
   // Page-level Operations
   // ============================================================================
@@ -298,6 +338,26 @@ export class PlaywrightAdapter extends EngineAdapter {
     await locatorOrElement.focus();
   }
 
+  // ============================================================================
+  // Page-level Keyboard Operations
+  // ============================================================================
+
+  async keyboardPress(key) {
+    await this.page.keyboard.press(key);
+  }
+
+  async keyboardType(text) {
+    await this.page.keyboard.type(text);
+  }
+
+  async keyboardDown(key) {
+    await this.page.keyboard.down(key);
+  }
+
+  async keyboardUp(key) {
+    await this.page.keyboard.up(key);
+  }
+
   // ============================================================================
   // Page-level Operations
   // ============================================================================
@@ -433,6 +493,26 @@ export class PuppeteerAdapter extends EngineAdapter {
     await locatorOrElement.focus();
   }
 
+  // ============================================================================
+  // Page-level Keyboard Operations
+  // ============================================================================
+
+  async keyboardPress(key) {
+    await this.page.keyboard.press(key);
+  }
+
+  async keyboardType(text) {
+    await this.page.keyboard.type(text);
+  }
+
+  async keyboardDown(key) {
+    await this.page.keyboard.down(key);
+  }
+
+  async keyboardUp(key) {
+    await this.page.keyboard.up(key);
+  }
+
   // ============================================================================
   // Page-level Operations
   // ============================================================================

package/src/exports.js

@@ -20,6 +20,7 @@ export {
 export { createNetworkTracker } from './core/network-tracker.js';
 export { createNavigationManager } from './core/navigation-manager.js';
 export { createPageSessionFactory } from './core/page-session.js';
+export { createDialogManager } from './core/dialog-manager.js';
 
 // Re-export engine adapter
 export {
@@ -42,6 +43,7 @@ export {
 
 // Re-export browser management
 export { launchBrowser } from './browser/launcher.js';
+export { emulateMedia } from './browser/media.js';
 export {
   waitForUrlStabilization,
   goto,
@@ -109,6 +111,8 @@ export {
   verifyFill,
 } from './interactions/fill.js';
 
+export { pressKey, typeText, keyDown, keyUp } from './interactions/keyboard.js';
+
 // Re-export utilities
 export { wait, evaluate, safeEvaluate } from './utilities/wait.js';
 export { getUrl, unfocusAddressBar } from './utilities/url.js';