playwriter 0.3.1 → 0.4.0

package/src/playwright-import.ts

@@ -0,0 +1,58 @@
+/**
+ * Conditional playwright-core import. When patchright mode is enabled via
+ * PLAYWRITER_PATCHRIGHT=1 env var, imports from @playwriter/patchright-core
+ * instead of @xmorse/playwright-core. Both packages expose identical APIs.
+ *
+ * Type imports continue to use @xmorse/playwright-core directly (types are
+ * the same in both packages) so TypeScript resolution works without the
+ * optional patchright dep being installed.
+ */
+
+export type {
+  Page,
+  Frame,
+  Browser,
+  BrowserContext,
+  Locator,
+  FrameLocator,
+  ElementHandle,
+  CDPSession,
+  MouseActionEvent,
+} from '@xmorse/playwright-core'
+
+export type { BrowserType } from '@xmorse/playwright-core'
+
+type Chromium = typeof import('@xmorse/playwright-core').chromium
+
+let _chromium: Chromium | undefined
+
+/**
+ * Returns the chromium BrowserType, loading from patchright-core if enabled.
+ * Caches after first call.
+ */
+export async function getChromium(): Promise<Chromium> {
+  if (_chromium) {
+    return _chromium
+  }
+  if (isPatchrightEnabled()) {
+    try {
+      // Dynamic import — @playwriter/patchright-core is an optional dependency.
+      // Types come from @xmorse/playwright-core (identical API surface).
+      const mod: { chromium: Chromium } = await import('@playwriter/patchright-core' as string)
+      _chromium = mod.chromium
+    } catch (e: unknown) {
+      throw new Error(
+        '@playwriter/patchright-core is not installed. Install it with: pnpm add @playwriter/patchright-core',
+        { cause: e },
+      )
+    }
+  } else {
+    const mod = await import('@xmorse/playwright-core')
+    _chromium = mod.chromium
+  }
+  return _chromium!
+}
+
+export function isPatchrightEnabled(): boolean {
+  return process.env.PLAYWRITER_PATCHRIGHT === '1' || process.env.PLAYWRITER_PATCHRIGHT === 'true'
+}

package/src/relay-state.test.ts

@@ -55,6 +55,38 @@ describe('createRelayStore', () => {
   })
 })
 
+describe('buildStableExtensionKey', () => {
+  test('uses install id before account identity so same-account profiles stay separate', () => {
+    const profiles = ['profile-a-install', 'profile-b-install'].map((installId) => {
+      return relayState.buildStableExtensionKey(
+        {
+          browser: 'Chrome',
+          email: 'tommy@example.com',
+          id: 'same-google-account-id',
+          installId,
+        },
+        'connection-fallback',
+      )
+    })
+
+    expect(profiles).toMatchInlineSnapshot(`
+      [
+        "install:Chrome:profile-a-install",
+        "install:Chrome:profile-b-install",
+      ]
+    `)
+  })
+
+  test('falls back to account identity for older extensions without install ids', () => {
+    const key = relayState.buildStableExtensionKey(
+      { browser: 'Chrome', email: 'tommy@example.com', id: 'google-account-id' },
+      'connection-fallback',
+    )
+
+    expect(key).toMatchInlineSnapshot(`"profile:google-account-id"`)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // addExtension / removeExtension
 // ---------------------------------------------------------------------------

package/src/relay-state.ts

@@ -94,6 +94,25 @@ export function findExtensionByStableKey(state: RelayState, stableKey: string):
   return match
 }
 
+export function buildStableExtensionKey(info: ExtensionInfo, connectionId: string): string {
+  // chrome.identity ids and emails identify the signed-in Google account, not
+  // the Chrome profile. Use the per-profile extension storage install id first
+  // so two profiles signed into the same account never replace each other.
+  if (info.installId) {
+    return `install:${info.browser || 'unknown'}:${info.installId}`
+  }
+  if (info.id) {
+    return `profile:${info.id}`
+  }
+  if (info.email) {
+    return `email:${info.email}`
+  }
+  if (info.browser) {
+    return `browser:${info.browser}`
+  }
+  return `connection:${connectionId}`
+}
+
 /** Find which extension owns a CDP tab sessionId (e.g. "pw-tab-1"). */
 export function findExtensionIdByCdpSession(state: RelayState, cdpSessionId: string): string | null {
   for (const [connectionId, ext] of state.extensions.entries()) {
@@ -494,4 +513,3 @@ export function updateTargetUrl(
   newExtensions.set(extensionId, { ...ext, connectedTargets: newTargets })
   return { ...state, extensions: newExtensions }
 }
-

package/src/skill.md

@@ -44,33 +44,141 @@ Reset a session if the browser connection is stale or broken:
 playwriter session reset <sessionId>
 ```
 
-### Direct CDP connection (--direct)
+### Remote access (control browser from another machine)
 
-Only use `--direct` when the user explicitly asks for it. This mode requires the user to accept a debugging approval dialog in Chrome, so it cannot be used autonomously.
+Playwriter can control a Chrome browser running on a different machine over the internet. The host machine runs `playwriter serve` with a [traforo](https://traforo.dev) tunnel, and the remote machine connects through the tunnel URL.
 
-`--direct` connects to Chrome's DevTools Protocol without the extension. Unlike extension mode, it gives access to **all existing pages** in the browser — no need to enable per tab. Works with any Chromium browser (Chrome, Brave, Arc, Edge, etc.).
+```bash
+# Host machine (has Chrome + extension)
+npx -y traforo -p 19988 -- npx -y playwriter serve --token MY_SECRET_TOKEN
+
+# Remote machine
+export PLAYWRITER_HOST=https://<tunnel-id>-tunnel.traforo.dev
+export PLAYWRITER_TOKEN=MY_SECRET_TOKEN
+playwriter session new
+playwriter -s 1 -e "await page.goto('https://example.com')"
+```
+
+For the full guide (Docker, LAN, MCP config, security), see: https://playwriter.dev/docs/remote-access
+
+### Direct CDP connection (no extension needed)
+
+Playwriter can connect directly to a Chrome instance via the Chrome DevTools Protocol, bypassing the browser extension entirely. This is useful for:
 
-The user must first enable debugging in Chrome:
-- Open `chrome://inspect/#remote-debugging` in Chrome, or
-- Launch Chrome with `chrome --remote-debugging-port=9222`
+- Chrome running with remote debugging enabled (CI, Docker, headless environments)
+- Cloud browser providers that expose a CDP endpoint (e.g. `wss://xxx.cdp.browser-use.com`)
+- Any service or machine that gives you a `ws://` or `wss://` URL to a Chrome DevTools session
 
-Then create a session:
+**Prerequisites:** you need a CDP-enabled Chrome. Either:
+
+- Open `chrome://inspect/#remote-debugging` in Chrome
+- Launch Chrome with `--remote-debugging-port=9222`
+- Use `playwriter browser start` (enables debugging automatically)
+- Use a cloud browser provider URL (no local Chrome needed)
+
+**CLI usage:**
 
 ```bash
+# Auto-discover local Chrome instances with debugging enabled
 playwriter session new --direct
+
+# Connect to a specific CDP endpoint (local or cloud browser provider)
+playwriter session new --direct ws://localhost:9222/devtools/browser/...
+playwriter session new --direct wss://xxx.cdp.browser-use.com
+
+# Connect to a remote Chrome instance (host:port auto-resolves to ws://)
+playwriter session new --direct 192.168.1.50:9222
+
+# Then use the session normally
+playwriter -s 1 -e "await page.goto('https://example.com')"
 ```
 
-By default, `context` is bound to the first Chrome profile. If the user has multiple profiles open, use `browser.contexts()` to access other profiles' pages and cookies:
+**MCP configuration** (for AI assistants): set the `PLAYWRITER_DIRECT` env var in your MCP client config. If the user provides a CDP URL (like `wss://xxx.cdp.browser-use.com`), use it as the value:
 
-```js
-const contexts = browser.contexts()
-// contexts[0] = first profile, contexts[1] = second profile, etc.
-const otherProfilePage = contexts[1].pages()[0]
+```json
+{
+  "mcpServers": {
+    "playwriter": {
+      "command": "npx",
+      "args": ["-y", "playwriter@latest"],
+      "env": {
+        "PLAYWRITER_DIRECT": "wss://xxx.cdp.browser-use.com"
+      }
+    }
+  }
+}
+```
+
+`PLAYWRITER_DIRECT` accepts:
+
+- `1` — auto-discover Chrome on port 9222
+- `ws://` or `wss://` URL — explicit WebSocket endpoint (local or cloud browser provider)
+- `host:port` — resolves via HTTP probe to a ws:// URL
+
+**Limitations:** screen recording (`recording.start`/`recording.stop`) is not available in direct CDP mode since it relies on the extension's `chrome.tabCapture` API.
+
+### Headless browser (no extension, no user browser)
+
+Launch a headless Chrome automatically. No extension setup, no user browser involvement. Useful when the user doesn't want their personal browser used, in CI/server environments, or for fully autonomous automation.
+
+```bash
+# Install Chrome for Testing (first time only, if no Chrome is available)
+playwriter browser install
+
+# Launch headless Chrome and create a session
+playwriter session new --browser headless
+
+# Use the session normally
+playwriter -s 1 -e "await page.goto('https://example.com')"
+playwriter -s 1 -e "console.log(await snapshot({ page }))"
 ```
 
-`browser.contexts()` only makes sense when using `--direct`. in extension mode there is just one context for each session.
+Multiple sessions reuse the same headless Chrome process. Recording is not available in headless mode.
+
+If no Chrome binary is found, `playwriter session new --browser headless` will tell you to run `playwriter browser install` first to download Chrome for Testing.
+
+### Cloud browsers (stealth, proxies, CAPTCHA solving)
+
+Cloud browsers are full Chromium instances running in the cloud. They work exactly like a local Chrome session but with stealth and anti-detection built in. No local Chrome or extension needed.
 
-**Limitations:** screen recording (`recording.start/stop`) is unavailable in direct mode.
+**When to use cloud browsers:**
+
+- **CAPTCHA bypass.** Cloudflare Turnstile, reCAPTCHA v2/v3, and hCaptcha are solved automatically via token injection. No API keys, no manual solving, no extra code.
+- **Anti-detection.** Stealth Chromium patches remove `navigator.webdriver`, CDP leak fingerprints, and other automation signals. Sites that block Playwright, Puppeteer, or Selenium work normally.
+- **Residential proxies.** Route traffic through residential IPs in 195+ countries with `--proxy <region>`. Proxy is disabled by default to save cost; enable it only when you need anti-detection or geo-targeting.
+- **VPS and headless environments.** Run browser automation from any server without installing Chrome. The cloud browser runs remotely and you connect via CDP.
+- **Parallel execution.** Spin up multiple cloud browsers to run tasks in parallel with subagents. Each browser is an isolated instance with its own IP, fingerprint, and cookie jar.
+- **Multiple identities.** Control separate logged-in accounts on the same site simultaneously. Each cloud browser has independent cookies and storage, so sessions don't interfere with each other.
+
+**Authentication:** two options depending on your environment.
+
+```bash
+# Option 1: Interactive login (opens browser for OAuth)
+playwriter cloud login
+
+# Option 2: API key (for CI, VPS, headless — no browser needed)
+# Create one at https://playwriter.dev/dashboard, then:
+export PLAYWRITER_API_KEY=pw_xxxxx
+```
+
+```bash
+# Check active cloud sessions
+playwriter cloud status
+
+# Start a cloud browser session (no proxy, cheapest)
+playwriter session new --browser cloud
+
+# Start with US residential proxy (for anti-detection / geo-targeting)
+playwriter session new --browser cloud --proxy us
+
+# Use a different region
+playwriter session new --browser cloud --proxy de
+
+# Use a custom proxy
+playwriter session new --browser cloud --custom-proxy user:pass@host:8080
+```
+
+Cloud sessions auto-stop after 10 minutes of inactivity. When proxy is enabled, raster images are blocked by default to reduce bandwidth costs. Pass `--disable-proxy-bandwidth-acceleration` if you need images to load.
 
 ### Execute code
 
@@ -197,6 +305,24 @@ start chrome.exe --profile-directory=Default --allowlisted-extension-id=jfeammnj
 
 You can collaborate with the user - they can help with captchas, difficult elements, or reproducing bugs.
 
+**Direct CDP mode (no extension needed):** Playwriter can connect directly to Chrome's DevTools Protocol, bypassing the extension. This is useful in CI, Docker, headless environments, when Chrome has `--remote-debugging-port=9222`, or with cloud browser providers (e.g. `wss://xxx.cdp.browser-use.com`). If the user provides a CDP URL, set `PLAYWRITER_DIRECT` in the MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "playwriter": {
+      "command": "npx",
+      "args": ["-y", "playwriter@latest"],
+      "env": {
+        "PLAYWRITER_DIRECT": "wss://xxx.cdp.browser-use.com"
+      }
+    }
+  }
+}
+```
+
+`PLAYWRITER_DIRECT` accepts `1` (auto-discover Chrome on port 9222), a `ws://` or `wss://` endpoint (including cloud browser providers), or `host:port`. Screen recording is not available in direct CDP mode since it relies on the extension's `chrome.tabCapture` API.
+
 ## context variables
 
 - `state` - object persisted between calls **within your session**. Each session has its own isolated state. Use to store pages, data, listeners (e.g., `state.page = await context.newPage()`)
@@ -597,6 +723,20 @@ console.log(cookies)
 
 MUST use this for page-scoped cookies in extension mode. `Storage.getCookies` is a root-session command and will fail in playwriter.
 
+**NEVER use `Network.clearBrowserCookies` or `Network.clearBrowserCache`** — these CDP commands are **profile-wide destructive operations** that wipe ALL cookies/cache across every domain in the user's Chrome profile. They will log the user out of Gmail, GitHub, and every authenticated session.
+
+**Clear cookies for a specific domain** — use `Network.getCookies` to fetch cookies scoped to URLs, then delete them individually with `Network.deleteCookies`:
+
+```js
+const cdp = await getCDPSession({ page: state.page })
+const { cookies } = await cdp.send('Network.getCookies', {
+  urls: ['https://example.com', 'https://www.example.com'],
+})
+for (const cookie of cookies) {
+  await cdp.send('Network.deleteCookies', { name: cookie.name, domain: cookie.domain })
+}
+```
+
 **Downloading large data** - console output truncates large strings. Trigger a browser download instead:
 
 ```js