@roxybrowser/playwright 2.0.2-beta.0

package/README.md

@@ -0,0 +1,115 @@
+# @roxybrowser/playwright
+
+`@roxybrowser/playwright` is a Playwright-style automation library with humanized behavior by default.
+
+## Design goals
+
+- Keep the public API familiar to Playwright users.
+- Route all browser operations through a protocol-agnostic adapter layer.
+- Start with `chrome-remote-interface` over CDP.
+- Keep CDP and BiDi as the supported protocol backends.
+- Make click, type, hover, and scroll behavior humanized by default instead of adding a second API.
+
+## Package layout
+
+- `src/browser*.ts`: public browser, context, and browser type objects.
+- `src/page.ts` and `src/locator.ts`: Playwright-style page and locator APIs.
+- `src/protocol/*`: protocol abstraction plus CDP and BiDi backend entry points.
+- `src/human/*`: humanization profiles and controller contracts.
+- `docs/architecture.md`: detailed architecture notes and implementation plan.
+
+## Current state
+
+This branch establishes the package scaffold, API shape, and protocol boundaries. The CDP runtime is intentionally skeletal so the architecture can be reviewed before we lock implementation details.
+
+## Testing
+
+- `pnpm test` runs the unit suite in `tests/unit`.
+- `pnpm test:e2e` runs a real-browser CDP flow in `tests/e2e`.
+- `pnpm test:e2e:bidi` runs the Firefox BiDi e2e suite in `tests/e2e/bidi`.
+
+The e2e suite writes a temporary HTML fixture, launches Chrome or Edge in headless mode, and verifies the public API against a real page through CDP. If auto-detection is not enough for your machine or CI image, set `ROXY_E2E_EXECUTABLE_PATH` to a Chromium-based browser binary before running the e2e command.
+
+The BiDi e2e suite prefers connecting to an existing Firefox BiDi websocket when `ROXY_BIDI_WS_ENDPOINT` is set. Without that variable, it launches a local Firefox binary with a temporary test profile and will use `ROXY_BIDI_EXECUTABLE_PATH` when provided. Set `ROXY_BIDI_USE_ROXYBROWSER_API=1` to opt into opening a Firefox profile through the RoxyBrowser local API; the helper closes the connected browser/profile after each test by default so repeated local runs do not leak Firefox windows. Set `ROXY_BIDI_KEEP_BROWSER_OPEN=1` only when deliberately debugging a shared endpoint and you intentionally want the Firefox window to stay open after a test. See `.env.example` for the supported local settings.
+
+## Browser launch
+
+`chromium.launch()` uses a locally installed Chromium-family browser. Launch resolution order is:
+
+- `executablePath`: use an explicit browser binary.
+- `channel`: resolve a known local install such as `chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`, `msedge-dev`, `msedge-canary`, or `chromium`.
+- auto-detection: fall back to the default Chrome, Chromium, and Edge candidate paths for the current platform.
+
+`firefox.launch()` now uses the BiDi backend by default and launches a locally installed Firefox binary directly. The current Firefox BiDi path supports browser launch, context creation, page creation, navigation, title lookup, script evaluation, and locator-based `click`, `hover`, `fill`, `type`, `press`, `textContent`, and `isVisible` flows.
+
+Firefox launch requires a local Firefox binary with BiDi remote debugging support. If auto-detection is not enough for your machine or CI image, set `ROXY_EXECUTABLE_PATH` or pass `executablePath` explicitly.
+
+## CDP connect
+
+`chromium.connectOverCDP()` currently supports direct WebSocket DevTools endpoints such as `ws://127.0.0.1:9222/devtools/browser/<id>`.
+
+- `ws://` and `wss://` endpoints are supported.
+- `http://` discovery endpoints are not supported yet.
+- custom `headers` are not supported for WebSocket endpoints yet.
+
+## Examples
+
+The [`examples`](/Users/macos/code/roxy-company/roxybrowser-playwright-mcp/examples) directory contains runnable scripts that import the package by its published name, `@roxybrowser/playwright`.
+
+- `pnpm example:launch`
+  Launches a locally installed browser, opens a temporary `file://` fixture, and prints the result.
+- `pnpm example:connect-cdp`
+  Connects to an existing CDP WebSocket endpoint from `ROXY_CDP_WS_ENDPOINT` and runs the same flow.
+- `pnpm example:page-events`
+  Launches a local browser, starts a temporary HTTP fixture, logs `page.on(...)` events, removes a `request` listener, and writes a screenshot to a temporary file.
+
+Useful environment variables:
+
+- `ROXY_BROWSER_CHANNEL=chrome|msedge|chromium`
+- `ROXY_BROWSER_NAME=chromium|firefox`
+- `ROXY_EXECUTABLE_PATH=/absolute/path/to/browser`
+- `ROXY_HEADLESS=false`
+- `ROXY_CDP_WS_ENDPOINT=ws://127.0.0.1:9222/devtools/browser/<id>`
+- `ROXY_MCP_OUTPUT_DIR=/absolute/path/to/output`
+
+## MCP output directory
+
+The MCP tools that save files, such as `browser_snapshot`, `browser_take_screenshot`,
+`browser_network_requests`, `browser_network_request`, `browser_console_messages`,
+and `browser_evaluate`, support a shared output directory.
+
+- Set `ROXY_MCP_OUTPUT_DIR` to choose the default directory for MCP-generated files.
+- `PLAYWRIGHT_MCP_OUTPUT_DIR` is also recognized for compatibility with Playwright MCP.
+- If a tool receives a relative `filename`, it will be resolved inside the output directory.
+- If a tool receives an absolute `filename`, it will be used as-is.
+- If no output directory is configured, the default is `.roxybrowser-mcp` under the current working directory, or the system temp directory when the cwd is not writable.
+
+You can also set `outputDir` directly when creating the MCP server or transports:
+
+```ts
+import {
+  createRoxyBrowserMcpInMemory,
+  createRoxyBrowserMcpServer,
+  startRoxyBrowserMcpHttp,
+  startRoxyBrowserMcpStdio
+} from "@roxybrowser/playwright/mcp";
+
+const outputDir = "/absolute/path/to/output";
+
+createRoxyBrowserMcpServer({
+  outputDir
+});
+
+await createRoxyBrowserMcpInMemory({
+  outputDir
+});
+
+await startRoxyBrowserMcpHttp({
+  port: 3000,
+  outputDir
+});
+
+await startRoxyBrowserMcpStdio({
+  outputDir
+});
+```

package/dist/apiRequestContext.d.ts

@@ -0,0 +1,52 @@
+import type { APIRequestContext, APIRequestFetchOptions, APIRequestOptions, APIResponse, Request } from "./types/api.js";
+export declare class RoxyAPIRequestContext implements APIRequestContext {
+    private closedReason;
+    private readonly cookies;
+    delete(url: string, options?: APIRequestOptions): Promise<APIResponse>;
+    dispose(options?: {
+        reason?: string;
+    }): Promise<void>;
+    fetch(urlOrRequest: string | Request, options?: APIRequestFetchOptions): Promise<APIResponse>;
+    get(url: string, options?: APIRequestOptions): Promise<APIResponse>;
+    head(url: string, options?: APIRequestOptions): Promise<APIResponse>;
+    patch(url: string, options?: APIRequestOptions): Promise<APIResponse>;
+    post(url: string, options?: APIRequestOptions): Promise<APIResponse>;
+    put(url: string, options?: APIRequestOptions): Promise<APIResponse>;
+    storageState(options?: {
+        indexedDB?: boolean;
+        path?: string;
+    }): Promise<{
+        cookies: Array<{
+            name: string;
+            value: string;
+            domain: string;
+            path: string;
+            expires: number;
+            httpOnly: boolean;
+            secure: boolean;
+            sameSite: "Strict" | "Lax" | "None";
+        }>;
+        origins: Array<{
+            origin: string;
+            localStorage: Array<{
+                name: string;
+                value: string;
+            }>;
+        }>;
+    }>;
+    [Symbol.asyncDispose](): Promise<void>;
+    private applyCookieHeader;
+    private cookiesForUrl;
+    private storeResponseCookies;
+}
+export declare function createApiResponse(fetchResponse: globalThis.Response): APIResponse;
+export declare function fetchWithRetries(url: string, options: {
+    allowGetOrHeadBody?: boolean;
+    body?: Buffer;
+    headers: Record<string, string>;
+    maxRedirects?: number;
+    maxRetries?: number;
+    method: string;
+    signal?: AbortSignal;
+}): Promise<globalThis.Response>;
+//# sourceMappingURL=apiRequestContext.d.ts.map

package/dist/apiRequestContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiRequestContext.d.ts","sourceRoot":"","sources":["../src/apiRequestContext.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,OAAO,EACR,MAAM,gBAAgB,CAAC;AAiBxB,qBAAa,qBAAsB,YAAW,iBAAiB;IAC7D,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAExC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOtE,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,KAAK,CACT,YAAY,EAAE,MAAM,GAAG,OAAO,EAC9B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,WAAW,CAAC;IA8CjB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOnE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOpE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOrE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOpE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOnE,YAAY,CAAC,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAC5E,OAAO,EAAE,KAAK,CAAC;YACb,IAAI,EAAE,MAAM,CAAC;YACb,KAAK,EAAE,MAAM,CAAC;YACd,MAAM,EAAE,MAAM,CAAC;YACf,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC;YAChB,QAAQ,EAAE,OAAO,CAAC;YAClB,MAAM,EAAE,OAAO,CAAC;YAChB,QAAQ,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;SACrC,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,CAAC;YACb,MAAM,EAAE,MAAM,CAAC;YACf,YAAY,EAAE,KAAK,CAAC;gBAClB,IAAI,EAAE,MAAM,CAAC;gBACb,KAAK,EAAE,MAAM,CAAC;aACf,CAAC,CAAC;SACJ,CAAC,CAAC;KACJ,CAAC;IAqBI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,oBAAoB;CAyB7B;AA8VD,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,UAAU,CAAC,QAAQ,GAAG,WAAW,CAqCjF;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IACP,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GACA,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAa9B"}