browser-commander 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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

@@ -318,6 +318,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.6.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",

package/tests/unit/factory.test.js

@@ -170,5 +170,62 @@ describe('factory', () => {
       // Should not throw
       await commander.destroy();
     });
+
+    // Extensibility escape hatch tests (issue #39)
+    it('should expose the raw page object as commander.page (extensibility escape hatch)', () => {
+      const page = createMockPlaywrightPage();
+      page.locator = (sel) => ({
+        count: async () => 1,
+        waitFor: async () => {},
+      });
+      page.context = () => ({});
+
+      const commander = makeBrowserCommander({ page });
+
+      // commander.page must be the exact same object as the raw page passed in
+      // This is the official extensibility escape hatch for APIs not yet in browser-commander
+      assert.strictEqual(
+        commander.page,
+        page,
+        'commander.page must be the raw engine page (not a wrapper)'
+      );
+    });
+
+    it('should allow using commander.page to call engine-specific APIs not in browser-commander', () => {
+      const page = createMockPlaywrightPage();
+      page.locator = (sel) => ({
+        count: async () => 1,
+        waitFor: async () => {},
+      });
+      page.context = () => ({});
+
+      // Add a custom method to simulate engine-specific API (e.g. page.pdf(), page.emulateMedia())
+      page.customEngineMethod = () => 'engine-specific-result';
+
+      const commander = makeBrowserCommander({ page });
+
+      // Users can call engine-specific APIs via commander.page without needing _page hacks
+      const result = commander.page.customEngineMethod();
+      assert.strictEqual(
+        result,
+        'engine-specific-result',
+        'commander.page should allow calling engine-specific APIs'
+      );
+    });
+
+    it('should expose raw page with Puppeteer page too (extensibility escape hatch)', () => {
+      const page = createMockPuppeteerPage();
+      delete page.locator;
+      delete page.context;
+      page.$eval = async () => {};
+
+      const commander = makeBrowserCommander({ page });
+
+      assert.strictEqual(
+        commander.page,
+        page,
+        'commander.page must be the raw Puppeteer page (not a wrapper)'
+      );
+    });
   });
 });