browser-commander 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.8.0
+
+### Minor Changes
+
+- a681a87: Add unified `page.pdf(options)` method to `EngineAdapter`, `PlaywrightAdapter`, and `PuppeteerAdapter`, eliminating the need for users to access raw page objects via the `page._page || page` workaround. The `pdf()` method is also exposed on the `BrowserCommander` facade via `commander.pdf({ pdfOptions })`.
+
+## 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

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

package/examples/pdf-generation.js

@@ -0,0 +1,76 @@
+/**
+ * Example: PDF generation via browser-commander
+ *
+ * This example shows how to use the unified page.pdf() method
+ * instead of the old workaround: `const rawPage = page._page || page`.
+ *
+ * Supports both Playwright and Puppeteer engines.
+ *
+ * Usage (Playwright):
+ *   node examples/pdf-generation.js playwright
+ *
+ * Usage (Puppeteer):
+ *   node examples/pdf-generation.js puppeteer
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { makeBrowserCommander } from '../src/factory.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const engine = process.argv[2] || 'playwright';
+
+async function generatePdf() {
+  let browser;
+  let page;
+
+  if (engine === 'playwright') {
+    const { chromium } = await import('playwright');
+    browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext();
+    page = await context.newPage();
+  } else if (engine === 'puppeteer') {
+    const puppeteer = await import('puppeteer');
+    browser = await puppeteer.launch({ headless: true });
+    page = await browser.newPage();
+  } else {
+    console.error(
+      `Unknown engine: ${engine}. Use 'playwright' or 'puppeteer'.`
+    );
+    process.exit(1);
+  }
+
+  try {
+    const commander = makeBrowserCommander({ page, verbose: false });
+
+    // Navigate to a page
+    await page.goto('https://example.com');
+
+    // Generate PDF using the unified API (no workarounds needed!)
+    const pdfBuffer = await commander.pdf({
+      pdfOptions: {
+        format: 'A4',
+        printBackground: true,
+        margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' },
+      },
+    });
+
+    const outputPath = path.join(__dirname, 'output.pdf');
+    fs.writeFileSync(outputPath, pdfBuffer);
+
+    console.log(
+      `PDF generated successfully: ${outputPath} (${pdfBuffer.length} bytes)`
+    );
+
+    await commander.destroy();
+  } finally {
+    await browser.close();
+  }
+}
+
+generatePdf().catch((error) => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.6.0",
+  "version": "0.8.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,8 @@ import {
   checkAndClearFlag,
   findToggleButton,
 } from './high-level/universal-logic.js';
+import { pdf } from './browser/pdf.js';
+import { pressKey, typeText, keyDown, keyUp } from './interactions/keyboard.js';
 
 /**
  * Create bound functions for a browser commander instance
@@ -191,6 +194,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 +216,15 @@ export function createBoundFunctions(options = {}) {
       findByText: findByTextBound,
     });
 
+  // Bound pdf generation
+  const pdfBound = (opts = {}) => pdf({ ...opts, page, engine });
+
+  // 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 +282,7 @@ export function createBoundFunctions(options = {}) {
 
     // Main API functions
     wait: waitBound,
+    emulateMedia: emulateMediaBound,
     fillTextArea: fillTextAreaWrapped,
     clickButton: clickButtonWrapped,
     evaluate: evaluateBound,
@@ -294,5 +310,23 @@ export function createBoundFunctions(options = {}) {
     installClickListener: installClickListenerBound,
     checkAndClearFlag: checkAndClearFlagBound,
     findToggleButton: findToggleButtonBound,
+
+    // PDF generation
+    pdf: pdfBound,
+
+    // 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/browser/pdf.js

@@ -0,0 +1,31 @@
+/**
+ * PDF generation support
+ *
+ * Wraps Playwright/Puppeteer's page.pdf() method behind a unified interface.
+ * Both engines expose identical options: format, printBackground, margin, etc.
+ *
+ * Note: PDF generation only works in Chromium headless mode.
+ * Playwright Firefox and WebKit do not support page.pdf().
+ */
+
+import { createEngineAdapter } from '../core/engine-adapter.js';
+
+/**
+ * Generate a PDF of the current page
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Playwright or Puppeteer page object
+ * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
+ * @param {Object} options.pdfOptions - PDF generation options passed to the engine
+ * @param {string} [options.pdfOptions.format] - Paper format (e.g. 'A4', 'Letter')
+ * @param {boolean} [options.pdfOptions.printBackground] - Print background graphics
+ * @param {Object} [options.pdfOptions.margin] - Page margins { top, right, bottom, left }
+ * @param {string} [options.pdfOptions.path] - File path to save the PDF (optional)
+ * @param {string} [options.pdfOptions.scale] - Scale of the webpage rendering (0.1–2)
+ * @returns {Promise<Buffer>} - PDF as a Buffer
+ */
+export async function pdf(options = {}) {
+  const { page, engine, pdfOptions = {} } = options;
+  const adapter = createEngineAdapter(page, engine);
+  return await adapter.pdf(pdfOptions);
+}

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,
+  };
+}