@boxlite-ai/boxlite 0.2.4 → 0.2.6

package/dist/browserbox.d.ts

@@ -1,67 +1,79 @@
 /**
- * BrowserBox - Secure browser with remote debugging.
+ * BrowserBox - Secure browser with Playwright Server.
  *
  * Provides a minimal, elegant API for running isolated browsers that can be
- * controlled from outside using standard tools like Puppeteer or Playwright.
+ * controlled from outside using Playwright. Supports all browser types:
+ * chromium, firefox, and webkit.
  */
-import { SimpleBox, type SimpleBoxOptions } from './simplebox.js';
+import { SimpleBox, type SimpleBoxOptions } from "./simplebox.js";
 /**
  * Browser type supported by BrowserBox.
  */
-export type BrowserType = 'chromium' | 'firefox' | 'webkit';
+export type BrowserType = "chromium" | "firefox" | "webkit";
 /**
  * Options for creating a BrowserBox.
  */
-export interface BrowserBoxOptions extends Omit<SimpleBoxOptions, 'image' | 'cpus' | 'memoryMib'> {
+export interface BrowserBoxOptions extends Omit<SimpleBoxOptions, "image" | "cpus" | "memoryMib"> {
     /** Browser type (default: 'chromium') */
     browser?: BrowserType;
     /** Memory in MiB (default: 2048) */
     memoryMib?: number;
     /** Number of CPU cores (default: 2) */
     cpus?: number;
+    /** Host port for Playwright Server WebSocket connection (default: 3000) */
+    port?: number;
+    /** Host port for CDP/Puppeteer connection (default: 9222) */
+    cdpPort?: number;
 }
 /**
- * Secure browser environment with remote debugging.
+ * Secure browser environment with Playwright Server.
  *
- * Auto-starts a browser with Chrome DevTools Protocol enabled.
- * Connect from outside using Puppeteer, Playwright, Selenium, or DevTools.
+ * Auto-starts a browser with Playwright Server enabled for remote control.
+ * Connect from outside using Playwright's `connect()` method.
  *
  * ## Usage
  *
  * ```typescript
- * const browser = new BrowserBox();
+ * import { BrowserBox } from '@boxlite-ai/boxlite';
+ * import { chromium } from 'playwright-core';
+ *
+ * const box = new BrowserBox({ browser: 'chromium' });
  * try {
- *   await browser.start();  // Manually start browser
- *   console.log(`Connect to: ${browser.endpoint()}`);
- *   // Use Puppeteer/Playwright from your host to connect
- *   await new Promise(resolve => setTimeout(resolve, 60000));
+ *   const ws = await box.playwrightEndpoint();
+ *   const browser = await chromium.connect(ws);
+ *
+ *   const page = await browser.newPage();
+ *   await page.goto('https://example.com');
+ *   console.log(await page.title());
+ *
+ *   await browser.close();
  * } finally {
- *   await browser.stop();
+ *   await box.stop();
  * }
  * ```
  *
- * ## Example with custom options
+ * ## All browsers supported
  *
  * ```typescript
- * const browser = new BrowserBox({
- *   browser: 'firefox',
- *   memoryMib: 4096,
- *   cpus: 4
- * });
- * try {
- *   await browser.start();
- *   const endpoint = browser.endpoint();
- *   // Connect using Playwright or Puppeteer
- * } finally {
- *   await browser.stop();
- * }
+ * // WebKit works!
+ * const box = new BrowserBox({ browser: 'webkit' });
+ * const ws = await box.playwrightEndpoint();
+ * const browser = await webkit.connect(ws);
  * ```
  */
 export declare class BrowserBox extends SimpleBox {
+    /** Playwright Docker image with all browsers pre-installed */
     private static readonly DEFAULT_IMAGE;
-    private static readonly PORTS;
+    /** Playwright version - must match the Docker image */
+    private static readonly PLAYWRIGHT_VERSION;
+    /** Default port for Playwright Server */
+    private static readonly DEFAULT_PORT;
     private readonly _browser;
-    private readonly _port;
+    private readonly _guestPort;
+    private readonly _hostPort;
+    private readonly _cdpGuestPort;
+    private _playwrightStarted;
+    private _cdpStarted;
     /**
      * Create a new BrowserBox.
      *
@@ -70,7 +82,7 @@ export declare class BrowserBox extends SimpleBox {
      * @example
      * ```typescript
      * const browser = new BrowserBox({
-     *   browser: 'chromium',
+     *   browser: 'webkit',  // All browsers work!
      *   memoryMib: 2048,
      *   cpus: 2
      * });
@@ -78,68 +90,120 @@ export declare class BrowserBox extends SimpleBox {
      */
     constructor(options?: BrowserBoxOptions);
     /**
-     * Start the browser with remote debugging enabled.
+     * Start the Playwright Server with the configured browser.
      *
-     * Call this method after creating the BrowserBox to start the browser process.
-     * Waits for the browser to be ready before returning.
+     * The Playwright Server binds to 0.0.0.0, so no proxy is needed.
+     * It handles all browser types natively.
      *
-     * @param timeout - Maximum time to wait for browser to start in seconds (default: 30)
-     * @throws {TimeoutError} If browser doesn't start within timeout
+     * @param timeout - Maximum time to wait for server to start in seconds (default: 60)
+     * @throws {TimeoutError} If server doesn't start within timeout
+     */
+    start(timeout?: number): Promise<void>;
+    /** Start Playwright Server (works for ALL browsers). */
+    private _startPlaywrightServer;
+    /** Wait for Playwright Server to be ready. */
+    private _waitForPlaywrightServer;
+    /** Start browser with remote debugging for Puppeteer (CDP for Chromium, WebDriver BiDi for Firefox). */
+    private _startCdpBrowser;
+    /** Start Chromium with CDP remote debugging. */
+    private _startChromiumCdp;
+    /** Start Firefox with WebDriver BiDi remote debugging. */
+    private _startFirefoxBiDi;
+    /** Wait for Firefox WebDriver BiDi server to be ready. */
+    private _waitForBiDiServer;
+    /** Start Python TCP forwarder to route traffic through the working port 3000. */
+    private _startCdpForwarder;
+    /** Wait for CDP server to be ready. */
+    private _waitForCdpServer;
+    /** Ensure Playwright server is started. */
+    private _ensurePlaywrightStarted;
+    /** Ensure CDP browser is started. */
+    private _ensureCdpStarted;
+    /**
+     * Get the WebSocket endpoint for Playwright connect().
+     *
+     * This is the primary method for Playwright connections.
+     * The returned URL can be used with Playwright's `connect()` method.
+     *
+     * @param timeout - Optional timeout to wait for server to start (starts automatically if not started)
+     * @returns WebSocket endpoint URL (e.g., 'ws://localhost:3000/')
      *
      * @example
      * ```typescript
-     * const browser = new BrowserBox();
-     * try {
-     *   await browser.start();
-     *   console.log(`Connect to: ${browser.endpoint()}`);
-     * } finally {
-     *   await browser.stop();
-     * }
+     * const box = new BrowserBox({ browser: 'chromium' });
+     * const ws = await box.playwrightEndpoint();
+     * const browser = await chromium.connect(ws);
      * ```
      */
-    start(timeout?: number): Promise<void>;
+    playwrightEndpoint(timeout?: number): Promise<string>;
     /**
-     * Wait for the browser process to be running.
-     *
-     * @param processPattern - Pattern to match browser process name
-     * @param timeout - Maximum wait time in seconds
-     * @throws {TimeoutError} If browser doesn't start within timeout
+     * @deprecated Use playwrightEndpoint() instead.
      */
-    private waitForBrowser;
+    wsEndpoint(timeout?: number): Promise<string>;
     /**
-     * Get the connection endpoint for remote debugging.
+     * Get the WebSocket endpoint for CDP/BiDi connections.
      *
-     * Returns the HTTP endpoint URL for Chrome DevTools Protocol.
-     * Use this with Puppeteer, Playwright, or Selenium to connect to the browser.
+     * This is the generic endpoint that works with Puppeteer, Selenium, or any
+     * other CDP/BiDi client. Works with chromium (CDP) and firefox (WebDriver BiDi).
+     * WebKit is not supported - use playwrightEndpoint() with Playwright instead.
      *
-     * @returns HTTP endpoint URL (e.g., 'http://localhost:9222')
+     * @param timeout - Optional timeout to wait for browser to start
+     * @returns WebSocket endpoint URL
+     * @throws {BoxliteError} If browser type is webkit
      *
      * @example
      * ```typescript
-     * const browser = new BrowserBox();
-     * try {
-     *   await browser.start();
-     *   const url = browser.endpoint();
+     * // Chromium (CDP)
+     * const box = new BrowserBox({ browser: 'chromium' });
+     * const wsEndpoint = await box.endpoint();
+     * const browser = await puppeteer.connect({ browserWSEndpoint: wsEndpoint });
      *
-     *   // Use with Puppeteer:
-     *   // const browserWSEndpoint = await fetch(`${url}/json/version`)
-     *   //   .then(r => r.json())
-     *   //   .then(d => d.webSocketDebuggerUrl);
-     *   // const browser = await puppeteer.connect({ browserWSEndpoint });
+     * // Firefox (WebDriver BiDi)
+     * const box = new BrowserBox({ browser: 'firefox' });
+     * const wsEndpoint = await box.endpoint();
+     * const browser = await puppeteer.connect({
+     *   browserWSEndpoint: wsEndpoint,
+     *   protocol: 'webDriverBiDi'
+     * });
+     * // Note: Firefox headless has a limitation where newPage() hangs.
+     * // Use browser.pages()[0] instead of browser.newPage().
+     * const page = (await browser.pages())[0];
+     * ```
+     */
+    endpoint(timeout?: number): Promise<string>;
+    /**
+     * @deprecated Use endpoint() instead.
+     */
+    puppeteerEndpoint(timeout?: number): Promise<string>;
+    /**
+     * @deprecated Use endpoint() instead. This method only works with chromium.
+     */
+    cdpEndpoint(timeout?: number): Promise<string>;
+    /**
+     * Connect to the browser using Playwright.
+     *
+     * Convenience method that returns a connected Playwright Browser instance.
+     * Requires playwright-core to be installed.
      *
-     *   // Use with Playwright:
-     *   // const browser = await chromium.connectOverCDP(url);
-     * } finally {
-     *   await browser.stop();
-     * }
+     * @param options - Connection options
+     * @returns Connected Playwright Browser instance
+     *
+     * @example
+     * ```typescript
+     * const box = new BrowserBox({ browser: 'webkit' });
+     * const browser = await box.connect();
+     * const page = await browser.newPage();
+     * await page.goto('https://example.com');
      * ```
      */
-    endpoint(): string;
+    connect(options?: {
+        timeout?: number;
+    }): Promise<unknown>;
     /**
-     * Override async disposal to start browser automatically.
+     * Get the browser type.
      *
-     * @internal
+     * @returns The browser type ('chromium', 'firefox', or 'webkit')
      */
-    [Symbol.asyncDispose](): Promise<void>;
+    get browser(): BrowserType;
 }
 //# sourceMappingURL=browserbox.d.ts.map

package/dist/browserbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browserbox.d.ts","sourceRoot":"","sources":["../lib/browserbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIlE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC;IAC/F,yCAAyC;IACzC,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,UAAW,SAAQ,SAAS;IACvC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAgD;IAErF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAI3B;IAEF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;;;;;;;;;;;OAaG;gBACS,OAAO,GAAE,iBAAsB;IAmB3C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,KAAK,CAAC,OAAO,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkChD;;;;;;OAMG;YACW,cAAc;IAuB5B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;OAIG;IACG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7C"}
+{"version":3,"file":"browserbox.d.ts","sourceRoot":"","sources":["../lib/browserbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIlE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAK5D;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAC7C,gBAAgB,EAChB,OAAO,GAAG,MAAM,GAAG,WAAW,CAC/B;IACC,yCAAyC;IACzC,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,UAAW,SAAQ,SAAS;IACvC,8DAA8D;IAC9D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CACU;IAE/C,uDAAuD;IACvD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAY;IAEtD,yCAAyC;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAEjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,WAAW,CAAkB;IAErC;;;;;;;;;;;;;OAaG;gBACS,OAAO,GAAE,iBAAsB;IAuC3C;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,wDAAwD;YAC1C,sBAAsB;IAUpC,8CAA8C;YAChC,wBAAwB;IA2BtC,wGAAwG;YAC1F,gBAAgB;IA2B9B,gDAAgD;YAClC,iBAAiB;IAwB/B,0DAA0D;YAC5C,iBAAiB;IAyB/B,0DAA0D;YAC5C,kBAAkB;IA4BhC,iFAAiF;YACnE,kBAAkB;IAkDhC,uCAAuC;YACzB,iBAAiB;IAqC/B,2CAA2C;YAC7B,wBAAwB;IAMtC,qCAAqC;YACvB,iBAAiB;IAM/B;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK3D;;OAEG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiCjD;;OAEG;IACG,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D;;OAEG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASpD;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAgB/D;;;;OAIG;IACH,IAAI,OAAO,IAAI,WAAW,CAEzB;CACF"}