npm - playwriter - Versions diffs - 0.1.0 → 0.3.0 - Mend

playwriter 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/dist/bippy.js +5 -5
package/dist/cdp-log.d.ts +4 -1
package/dist/cdp-log.d.ts.map +1 -1
package/dist/cdp-log.js +39 -2
package/dist/cdp-log.js.map +1 -1
package/dist/cdp-log.test.d.ts +2 -0
package/dist/cdp-log.test.d.ts.map +1 -0
package/dist/cdp-log.test.js +109 -0
package/dist/cdp-log.test.js.map +1 -0
package/dist/cdp-relay.d.ts.map +1 -1
package/dist/cdp-relay.js +120 -11
package/dist/cdp-relay.js.map +1 -1
package/dist/cli-help.test.js +22 -0
package/dist/cli-help.test.js.map +1 -1
package/dist/cli.js +69 -25
package/dist/cli.js.map +1 -1
package/dist/executor.d.ts +4 -0
package/dist/executor.d.ts.map +1 -1
package/dist/executor.js +140 -33
package/dist/executor.js.map +1 -1
package/dist/extension/background.js +343 -62
package/dist/extension/manifest.json +1 -1
package/dist/mcp.d.ts.map +1 -1
package/dist/mcp.js +6 -1
package/dist/mcp.js.map +1 -1
package/dist/performance-examples.d.ts +5 -0
package/dist/performance-examples.d.ts.map +1 -0
package/dist/performance-examples.js +112 -0
package/dist/performance-examples.js.map +1 -0
package/dist/performance-profiling.md +417 -0
package/dist/prompt.md +51 -18
package/dist/react-source.d.ts +44 -0
package/dist/react-source.d.ts.map +1 -1
package/dist/react-source.js +207 -20
package/dist/react-source.js.map +1 -1
package/dist/readability.js +1 -1
package/dist/relay-client.d.ts +11 -0
package/dist/relay-client.d.ts.map +1 -1
package/dist/relay-client.js +46 -1
package/dist/relay-client.js.map +1 -1
package/dist/relay-core.test.js +10 -6
package/dist/relay-core.test.js.map +1 -1
package/dist/relay-session.test.js +43 -7
package/dist/relay-session.test.js.map +1 -1
package/dist/relay-state.test.js +57 -1
package/dist/relay-state.test.js.map +1 -1
package/dist/screen-recording.d.ts.map +1 -1
package/dist/screen-recording.js +19 -4
package/dist/screen-recording.js.map +1 -1
package/dist/selector-generator.js +1 -1
package/dist/start-relay-server.d.ts +1 -1
package/dist/start-relay-server.d.ts.map +1 -1
package/dist/start-relay-server.js +23 -1
package/dist/start-relay-server.js.map +1 -1
package/dist/utils.d.ts +2 -1
package/dist/utils.d.ts.map +1 -1
package/dist/utils.js +4 -1
package/dist/utils.js.map +1 -1
package/package.json +3 -3
package/src/cdp-log.test.ts +131 -0
package/src/cdp-log.ts +44 -2
package/src/cdp-relay.ts +127 -10
package/src/cli-help.test.ts +22 -0
package/src/cli.ts +74 -24
package/src/executor.ts +166 -39
package/src/mcp.ts +6 -1
package/src/performance-examples.ts +186 -0
package/src/react-source.ts +310 -24
package/src/relay-client.ts +62 -5
package/src/relay-core.test.ts +10 -6
package/src/relay-session.test.ts +45 -11
package/src/relay-state.test.ts +67 -1
package/src/screen-recording.ts +20 -4
package/src/skill.md +62 -19
package/src/start-relay-server.ts +22 -1
package/src/utils.ts +5 -0

package/src/relay-core.test.ts CHANGED Viewed

@@ -730,6 +730,7 @@ describe('Relay Core Tests', () => {
             console.error('Test error 67890');
             console.warn('Test warning 11111');
             console.log('Test log 2 with', { data: 'object' });
+            setTimeout(() => { throw new Error('Test pageerror 22222'); }, 0);
           });
           // Wait for logs to be captured
           await new Promise(resolve => setTimeout(resolve, 100));
@@ -752,6 +753,7 @@ describe('Relay Core Tests', () => {
     expect(output).toContain('[log] Test log 12345')
     expect(output).toContain('[error] Test error 67890')
     expect(output).toContain('[warning] Test warning 11111')
+    expect(output).toContain('[pageerror] Test pageerror 22222')
     // Test filtering by search string
     const errorLogsResult = await client.callTool({
@@ -769,7 +771,7 @@ describe('Relay Core Tests', () => {
     // With context lines (5 above/below), nearby logs are also included
     expect(errorOutput).toContain('[log] Test log 12345')
-    // Test that logs are cleared on page reload
+    // Test that logs persist across page reload
     await client.callTool({
       name: 'execute',
       arguments: {
@@ -812,7 +814,9 @@ describe('Relay Core Tests', () => {
       },
     })
-    // Check logs after reload - old logs should be gone
+    // Check logs after reload - old logs persist (no longer cleared on navigation)
+    // so both pre- and post-reload logs are present. Use sinceLastCall to get
+    // only new logs if needed.
     const afterReloadResult = await client.callTool({
       name: 'execute',
       arguments: {
@@ -826,7 +830,7 @@ describe('Relay Core Tests', () => {
     const afterReloadOutput = (afterReloadResult as any).content[0].text
     expect(afterReloadOutput).toContain('[log] After reload 88888')
-    expect(afterReloadOutput).not.toContain('[log] Before reload 99999')
+    expect(afterReloadOutput).toContain('[log] Before reload 99999')
     // Clean up
     await client.callTool({
@@ -943,7 +947,7 @@ describe('Relay Core Tests', () => {
     expect(allOutput).toContain('[log] PageA log 11111')
     expect(allOutput).toContain('[log] PageB log 33333')
-    // Test that reloading page A clears only page A logs
+    // Test that reloading page A preserves logs (no longer cleared on navigation)
     await client.callTool({
       name: 'execute',
       arguments: {
@@ -957,7 +961,7 @@ describe('Relay Core Tests', () => {
       },
     })
-    // Check page A logs - should only have new log
+    // Check page A logs - logs persist across navigation, so both old and new are present
     const pageAAfterReloadResult = await client.callTool({
       name: 'execute',
       arguments: {
@@ -971,7 +975,7 @@ describe('Relay Core Tests', () => {
     const pageAAfterReloadOutput = (pageAAfterReloadResult as any).content[0].text
     expect(pageAAfterReloadOutput).toContain('[log] PageA after reload 55555')
-    expect(pageAAfterReloadOutput).not.toContain('[log] PageA log 11111')
+    expect(pageAAfterReloadOutput).toContain('[log] PageA log 11111')
     // Check page B logs - should still have original logs
     const pageBAfterAReloadResult = await client.callTool({

package/src/relay-session.test.ts CHANGED Viewed

@@ -921,12 +921,24 @@ describe('CDP Session Tests', () => {
             <body>
                 <div id="root"></div>
                 <script>
-                    function MyComponent() {
-                        return React.createElement('button', { id: 'react-btn' }, 'Click me');
+                    function SaveButton(props) {
+                        return React.createElement('button', { id: 'react-btn' }, props.label);
+                    }
+                    function Panel() {
+                        return React.createElement('section', null, React.createElement(SaveButton, {
+                          label: 'Click me',
+                          count: 3,
+                          config: { variant: 'primary' },
+                          onClick: () => {}
+                        }));
+                    }
+                    function App() {
+                        return React.createElement(Panel);
                     }
                     const root = ReactDOM.createRoot(document.getElementById('root'));
-                    root.render(React.createElement(MyComponent));
+                    root.render(React.createElement(App));
                 </script>
+                <button id="plain-btn">Plain</button>
             </body>
             </html>
         `)
@@ -946,40 +958,54 @@ describe('CDP Session Tests', () => {
     const btnCount = await btn.count()
     expect(btnCount).toBe(1)
-    const hasBippyBefore = await cdpPage!.evaluate(() => !!(globalThis as any).__bippy)
+    const hasBippyBefore = await cdpPage!.evaluate(() => !!globalThis.__bippy)
     expect(hasBippyBefore).toBe(false)
     const wsUrl = getCdpUrl({ port: TEST_PORT })
     const cdpSession = await getCDPSessionForPage({ page: cdpPage! })
-    const { getReactSource } = await import('./react-source.js')
+    const { getReactSource, getReactComponentInfo } = await import('./react-source.js')
     const source = await getReactSource({ locator: btn, cdp: cdpSession })
+    const info = await getReactComponentInfo({ locator: btn, cdp: cdpSession })
+    const plainInfo = await getReactComponentInfo({ locator: cdpPage!.locator('#plain-btn'), cdp: cdpSession })
-    const hasBippyAfter = await cdpPage!.evaluate(() => !!(globalThis as any).__bippy)
+    const hasBippyAfter = await cdpPage!.evaluate(() => !!globalThis.__bippy)
     expect(hasBippyAfter).toBe(true)
     const hasFiber = await btn.evaluate((el) => {
-      const bippy = (globalThis as any).__bippy
+      const bippy = globalThis.__bippy
+      if (!bippy) return false
       const fiber = bippy.getFiberFromHostInstance(el)
       return !!fiber
     })
     expect(hasFiber).toBe(true)
     const componentName = await btn.evaluate((el) => {
-      const bippy = (globalThis as any).__bippy
+      const bippy = globalThis.__bippy
+      if (!bippy) return null
       const fiber = bippy.getFiberFromHostInstance(el)
       let current = fiber
       while (current) {
         if (bippy.isCompositeFiber(current)) {
           return bippy.getDisplayName(current.type)
         }
-        current = current.return
+        current = current.return ?? null
       }
       return null
     })
-    expect(componentName).toBe('MyComponent')
+    expect(componentName).toBe('SaveButton')
+    expect(plainInfo).toBe(null)
+    expect(info?.componentName).toBe('SaveButton')
+    expect(info?.hierarchy.map((item) => item.componentName)).toEqual(['SaveButton', 'Panel', 'App'])
+    expect(info?.props).toEqual({
+      label: 'Click me',
+      count: 3,
+      config: { variant: 'primary' },
+      onClick: '[function]',
+    })
     console.log('Component name from fiber:', componentName)
+    console.log('React component info:', info)
     console.log('Source location (null for UMD React, works on local dev servers with JSX transform):', source)
     await browser.close()
@@ -1251,7 +1277,15 @@ describe('Auto-enable Tests', () => {
     })
     expect(tabCountBefore).toBe(0)
-    const browser = await chromium.connectOverCDP(getCdpUrl({ port: TEST_PORT }))
+    const previousAutoEnable = process.env.PLAYWRITER_AUTO_ENABLE
+    delete process.env.PLAYWRITER_AUTO_ENABLE
+    const browser = await chromium.connectOverCDP(getCdpUrl({ port: TEST_PORT, autoEnable: true })).finally(() => {
+      if (previousAutoEnable === undefined) {
+        delete process.env.PLAYWRITER_AUTO_ENABLE
+        return
+      }
+      process.env.PLAYWRITER_AUTO_ENABLE = previousAutoEnable
+    })
     const pages = browser.contexts()[0].pages()
     expect(pages.length).toBeGreaterThan(0)

package/src/relay-state.test.ts CHANGED Viewed

@@ -2,7 +2,7 @@
  * Unit tests for relay state transitions.
  * Data-in / data-out transitions for the unified extension map.
  */
-import { describe, test, expect } from 'vitest'
+import { describe, test, expect, beforeAll, afterAll } from 'vitest'
 import type { WSContext } from 'hono/ws'
 import type { Protocol } from './cdp-types.js'
 import * as relayState from './relay-state.js'
@@ -568,3 +568,69 @@ describe('store.setState with transitions', () => {
     expect(state.playwrightClients.size).toBe(1)
   })
 })
+// ---------------------------------------------------------------------------
+// DNS rebinding protection — Host header validation
+// Node.js fetch/undici treats Host as a forbidden header, so we use the raw
+// http module to send requests with arbitrary Host values.
+// ---------------------------------------------------------------------------
+import http from 'node:http'
+function httpGet({ port, path, host }: { port: number; path: string; host: string }): Promise<{ status: number; body: string }> {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ hostname: '127.0.0.1', port, path, method: 'GET', headers: { Host: host } }, (res) => {
+      let body = ''
+      res.on('data', (chunk: Buffer) => {
+        body += chunk.toString()
+      })
+      res.on('end', () => {
+        resolve({ status: res.statusCode!, body })
+      })
+    })
+    req.on('error', reject)
+    req.end()
+  })
+}
+describe('Host header validation (DNS rebinding protection)', () => {
+  let server: { close(): void } | null = null
+  const TEST_PORT = 19996
+  beforeAll(async () => {
+    const { startPlayWriterCDPRelayServer } = await import('./cdp-relay.js')
+    server = await startPlayWriterCDPRelayServer({ port: TEST_PORT })
+  })
+  afterAll(async () => {
+    server?.close()
+    server = null
+  })
+  test('rejects requests with non-localhost Host header', async () => {
+    // DNS rebinding: evil.com resolves to 127.0.0.1
+    const res = await httpGet({ port: TEST_PORT, path: '/', host: 'evil.com' })
+    expect(res.status).toBe(403)
+    expect(res.body).toContain('Invalid Host header')
+    // With port suffix
+    const res2 = await httpGet({ port: TEST_PORT, path: '/version', host: 'evil.com:19996' })
+    expect(res2.status).toBe(403)
+  })
+  test('allows requests with localhost Host headers', async () => {
+    const localhostVariants = [
+      `localhost:${TEST_PORT}`,
+      `127.0.0.1:${TEST_PORT}`,
+      `[::1]:${TEST_PORT}`,
+      'localhost',
+      '127.0.0.1',
+      'LOCALHOST',
+    ]
+    for (const hostValue of localhostVariants) {
+      const res = await httpGet({ port: TEST_PORT, path: '/', host: hostValue })
+      expect(res.status, `Expected 200 for Host: ${hostValue}`).toBe(200)
+    }
+  })
+})

package/src/screen-recording.ts CHANGED Viewed

@@ -18,6 +18,21 @@ import type {
 } from './protocol.js'
 import { GhostCursorController } from './ghost-cursor-controller.js'
+/**
+ * Build headers for the relay's privileged /recording/* HTTP endpoints.
+ * Reads PLAYWRITER_TOKEN from env so in-process callers (executor running
+ * inside `playwriter serve --token …`) authenticate against their own relay.
+ * The `serve` command sets the env var at startup.
+ */
+function recordingHeaders(): Record<string, string> {
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+  const token = process.env.PLAYWRITER_TOKEN
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`
+  }
+  return headers
+}
 /**
  * Generate a CLI command that starts a managed Playwriter browser with the
  * bundled extension preloaded. This enables screen recording without a manual
@@ -293,7 +308,7 @@ export async function startRecording(options: StartRecordingOptions): Promise<Re
   const response = await fetch(`http://127.0.0.1:${relayPort}/recording/start`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: recordingHeaders(),
     body: JSON.stringify({
       sessionId,
       frameRate,
@@ -341,7 +356,7 @@ export async function stopRecording(
   const response = await fetch(`http://127.0.0.1:${relayPort}/recording/stop`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: recordingHeaders(),
     body: JSON.stringify({ sessionId }),
   })
@@ -368,7 +383,8 @@ export async function isRecording(options: {
   if (sessionId) {
     url.searchParams.set('sessionId', sessionId)
   }
-  const response = await fetch(url.toString())
+  // GET request — only the Authorization header matters here
+  const response = await fetch(url.toString(), { headers: recordingHeaders() })
   const result = (await response.json()) as IsRecordingResult
   return { isRecording: result.isRecording, startedAt: result.startedAt, tabId: result.tabId }
@@ -386,7 +402,7 @@ export async function cancelRecording(options: {
   const response = await fetch(`http://127.0.0.1:${relayPort}/recording/cancel`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: recordingHeaders(),
     body: JSON.stringify({ sessionId }),
   })

package/src/skill.md CHANGED Viewed

@@ -93,7 +93,7 @@ playwriter -s 1 -e 'await state.page.click("button")'
 playwriter -s 1 -e 'await state.page.title()'
 # Take a screenshot
-playwriter -s 1 -e 'await state.page.screenshot({ path: "screenshot.png", scale: "css" })'
+playwriter -s 1 -e 'await state.page.screenshot({ path: "/absolute/path/to/screenshot.png", scale: "css" })'
 # Get accessibility snapshot
 playwriter -s 1 -e 'await snapshot({ page: state.page })'
@@ -129,6 +129,16 @@ console.log({ title, url });
 - **Heredoc** (`<<'EOF'`): best for multiline code. The quoted `'EOF'` delimiter disables all bash expansion. Any character works inside, including `$`, backticks, and single quotes.
 - **`$'...'`**: allows `\'` escaping but `\n`, `\t`, `\\` become special — conflicts with JS regex patterns.
+### Execute from file
+For longer scripts, use `-f` instead of `-e` to execute JavaScript from a file:
+```bash
+playwriter -s 1 -f script.js
+```
+The file is read from disk and executed in the same sandbox as `-e`. All context variables (`state`, `page`, `context`, etc.) are available. `-e` and `-f` cannot be used together.
 ### Debugging playwriter issues
 If some internal critical error happens you can read the relay server logs to understand the issue. The log file is located in the user home directory:
@@ -193,10 +203,19 @@ You can collaborate with the user - they can help with captchas, difficult eleme
 - `page` - a default page (may be shared with other agents). Prefer creating your own page and storing it in `state` (see "working with pages")
 - `context` - browser context, access all pages via `context.pages()`
 - `require` - load Node.js modules (e.g., `const fs = require('node:fs')`). ESM `import` is not available in the sandbox
-- Node.js globals: `setTimeout`, `setInterval`, `fetch`, `URL`, `Buffer`, `crypto`, etc.
+- Node.js globals: `setTimeout`, `setInterval`, `fetch`, `URL`, `Buffer`, `crypto`, `process`, etc.
+**Not available in the sandbox:** `__dirname`, `__filename`, `import`.
 **Important:** `state` is **session-isolated** but pages are **shared** across all sessions. See "working with pages" for how to avoid interference.
+**Sandboxed `fs` write restrictions:** `require('node:fs')` is scoped. Writes (writeFileSync, mkdirSync, etc.) only succeed in:
+- The **directory where `playwriter` CLI was invoked** (the session's cwd)
+- `/tmp`
+- The OS temp directory (`os.tmpdir()`, e.g. `/var/folders/.../T/` on macOS)
+Writing to any other path (e.g. `~/Downloads`, `~/Desktop`) throws `EPERM: operation not permitted, access outside allowed directories`. To save files elsewhere, write to a temp path first, then move the file using a shell command outside the sandbox.
 ## rules
 - **Initialize state.page first**: see "working with pages" — at the start of a task, assign `state.page` (reuse `about:blank` or create one) and use `state.page` for all automation steps.
@@ -205,10 +224,12 @@ You can collaborate with the user - they can help with captchas, difficult eleme
 - **No bringToFront**: never call unless user asks - it's disruptive and unnecessary, you can interact with background pages
 - **Check state after actions**: always verify page state after clicking/submitting (see next section)
 - **Clean up listeners**: call `state.page.removeAllListeners()` at end of message to prevent leaks
+- **Always print page logs after every action**: call `getLatestLogs({ page: state.page, sinceLastCall: true })` after every goto, click, or submit to catch console errors and warnings. Do not manually collect `page.on('console')` events; manual listeners miss logs emitted before the listener is attached. The first `sinceLastCall` call returns all buffered logs including startup and hydration errors.
 - **CDP sessions**: use `getCDPSession({ page: state.page })` not `state.page.context().newCDPSession()` - NEVER use `newCDPSession()` method, it doesn't work through playwriter relay
 - **Wait for load**: use `state.page.waitForLoadState('domcontentloaded')` not `state.page.waitForEvent('load')` - waitForEvent times out if already loaded
 - **Minimize timeouts**: prefer proper waits (`waitForSelector`, `waitForPageLoad`) over `state.page.waitForTimeout()`. Short timeouts (1-2s) are acceptable for non-deterministic events like animations, tab opens, or async UI updates where no specific selector is available
 - **Snapshot before screenshot**: always use `snapshot()` first to understand page state (text-based, fast, cheap). Only use `screenshot` when you specifically need visual/spatial information. Never take a screenshot just to check if a page loaded or to read text content — snapshot gives you that instantly without burning image tokens
+- **Always use absolute file paths for Playwright artifact APIs**: for `page.screenshot({ path })`, `locator.screenshot({ path })`, `elementHandle.screenshot({ path })`, `page.pdf({ path })`, `download.saveAs(path)`, and `video.saveAs(path)`, always pass an absolute path. Relative paths are resolved by Playwright client internals, not the sandboxed `fs`, so they may use the relay server cwd instead of your session cwd.
 - **Snapshot replaces page.evaluate() for inspection**: do NOT write `page.evaluate()` calls to manually query class names, bounding boxes, child counts, or visibility flags. `snapshot()` already shows every interactive element with its text, role, and a ready-to-use locator. If you catch yourself writing `document.querySelector` or `getBoundingClientRect` inside evaluate — stop and use `snapshot()` instead. Reserve `page.evaluate()` for actions that modify page state (e.g., `localStorage.clear()`, scroll manipulation) or extract non-DOM data (e.g., `window.__CONFIG__`)
 ## interaction feedback loop
@@ -216,18 +237,21 @@ You can collaborate with the user - they can help with captchas, difficult eleme
 Every browser interaction must follow **observe → act → observe**. Never chain multiple actions blindly.
 1. **Open page** — get or create your page, navigate to URL
-2. **Observe** — print `state.page.url()` + `snapshot()`. Always print URL — pages can redirect unexpectedly.
+2. **Observe** — print `state.page.url()` + `snapshot()` + `getLatestLogs({ sinceLastCall: true })`. Always print URL — pages can redirect unexpectedly.
 3. **Check** — if page isn't ready (loading, wrong URL, content missing), wait and observe again
 4. **Act** — perform one action (click, type, submit)
-5. **Observe again** — print URL + snapshot to verify the action's effect
+5. **Observe again** — print URL + snapshot + page logs to verify the action's effect
 6. **Repeat** from step 3 until task is complete
+**Always print page logs after every action** using `getLatestLogs({ sinceLastCall: true })`. This returns only new console messages and errors since the last call, so you catch hydration errors, failed network requests, and runtime exceptions without duplicates. The first call returns all buffered logs from the page, including logs emitted before your script started.
 ```js
 // Each step should be a separate execute call:
 // Step 1: navigate + observe
 state.page = context.pages().find((p) => p.url() === 'about:blank') ?? (await context.newPage())
 await state.page.goto('https://example.com', { waitUntil: 'domcontentloaded' })
 console.log('URL:', state.page.url())
+console.log('Page logs:', await getLatestLogs({ page: state.page, sinceLastCall: true }))
 await snapshot({ page: state.page }).then(console.log)
 ```
@@ -235,25 +259,26 @@ await snapshot({ page: state.page }).then(console.log)
 // Step 2: act + observe
 await state.page.locator('button:has-text("Submit")').click()
 console.log('URL:', state.page.url())
+console.log('Page logs:', await getLatestLogs({ page: state.page, sinceLastCall: true }))
 await snapshot({ page: state.page }).then(console.log)
 ```
 If nothing changed after an action, try `waitForPageLoad({ page: state.page, timeout: 3000 })` or you may have clicked the wrong element.
-**Deeper observation** — when snapshots aren't enough to understand what happened, combine multiple channels:
+**Deeper observation** — when snapshots aren't enough to understand what happened, combine snapshot with filtered logs:
 ```js
-// Check console for errors after an action
+// Search for specific errors in all logs (not just since last call)
 const errors = await getLatestLogs({ page: state.page, search: /error|fail/i, count: 20 })
-// Combine snapshot + logs for full picture
+// Combine snapshot + filtered logs for full picture
 const snap = await snapshot({ page: state.page, search: /dialog|error|message/ })
 const logs = await getLatestLogs({ page: state.page, search: /error/i, count: 10 })
 console.log('UI:', snap)
 console.log('Logs:', logs)
 ```
-Use `getLatestLogs()` for console errors, `state.page.url()` for navigation, screenshots only for visual layout issues.
+Use `getLatestLogs({ sinceLastCall: true })` after every action, `getLatestLogs({ search })` for targeted debugging, `state.page.url()` for navigation, screenshots only for visual layout issues.
 ## common mistakes to avoid
@@ -601,7 +626,7 @@ Instead, use simpler alternatives (single download via `a.click()`, store data i
 ```js
 const [download] = await Promise.all([state.page.waitForEvent('download'), state.page.click('button.download')])
-await download.saveAs(`/tmp/${download.suggestedFilename()}`)
+await download.saveAs(`/absolute/path/${download.suggestedFilename()}`)
 ```
 **iFrames** - two approaches depending on what you need:
@@ -669,17 +694,22 @@ For carousels or lazy-loaded galleries, you may need to click navigation arrows
 ## utility functions
-**getLatestLogs** - retrieve captured browser console logs (up to 5000 per page, cleared on navigation):
+**getLatestLogs** - retrieve captured browser console logs and page errors (up to 5000 per page):
+Always use this helper when inspecting browser logs. Do not attach new `page.on('console')` listeners for debugging because they only see future events and can miss logs emitted during page startup or hydration.
+Use `sinceLastCall: true` after every action to get only new logs since the previous call. The first call returns all buffered logs including pre-existing ones. Logs persist across navigations so you never miss errors from page transitions.
 ```js
-await getLatestLogs({ page?, count?, search? })
-// Examples:
+await getLatestLogs({ page?, count?, search?, sinceLastCall? })
+// After every action: get only new logs
+const newLogs = await getLatestLogs({ page: state.page, sinceLastCall: true })
+// Search all logs (ignores cursor):
 const errors = await getLatestLogs({ search: /error/i, count: 50 })
-const pageLogs = await getLatestLogs({ page: state.page })
+const pageLogs = await getLatestLogs({ page: state.page, count: 100 })
+const hydrationErrors = await getLatestLogs({ page: state.page, search: /hydration|pageerror|React/i })
 ```
-For custom log collection across runs, store in state: `state.logs = []; state.page.on('console', m => state.logs.push(m.text()))`
 **getCleanHTML** - get cleaned HTML from a locator or page, with search and diffing:
 ```js
@@ -754,6 +784,19 @@ const source = await getReactSource({ locator: state.page.locator('[data-testid=
 // => { fileName, lineNumber, columnNumber, componentName }
 ```
+**getReactComponentInfo** - get best-effort React component info for an element. Returns `null` for non-React elements and never throws just because an element was not rendered by React. Source locations are usually only available in React dev builds. Props are sanitized and truncated so functions, DOM nodes, circular refs, and huge objects do not flood the output.
+```js
+const info = await getReactComponentInfo({ locator: state.page.locator('[data-testid="submit-btn"]') })
+// => { componentName, source, hierarchy, props } | null
+```
+**inspectPinnedElement** - inspect a Playwriter pinned element and print the element `outerHTML` plus React component info when available. Used by the in-page toolbar and right-click copy flow.
+```js
+await inspectPinnedElement('https://example.com', 'globalThis.playwriterPinnedElem1')
+```
 **getStylesForLocator** - inspect CSS styles applied to an element, like browser DevTools "Styles" panel. Useful for debugging styling issues, finding where a CSS property is defined (file:line), and checking inherited styles. Returns selector, source location, and declarations for each matching rule. ALWAYS fetch `https://playwriter.dev/resources/styles-api.md` first with curl or webfetch tool.
 ```js
@@ -806,7 +849,7 @@ await screenshotWithAccessibilityLabels({ page: state.page })
 Labels are color-coded: yellow=links, orange=buttons, coral=inputs, pink=checkboxes, peach=sliders, salmon=menus, amber=tabs.
-**resizeImageForAgent** - shrink an image so it consumes fewer tokens when read back into context. The resized image is automatically included in the response (visible to the LLM). `await resizeImageForAgent({ input: './screenshot.png' })`. Also accepts `width`, `height`, `maxDimension`, `quality`, `format` (default: `'png'`), `output`. Alias: `resizeImage`.
+**resizeImageForAgent** - shrink an image so it consumes fewer tokens when read back into context. The resized image is automatically included in the response (visible to the LLM). `await resizeImageForAgent({ input: '/absolute/path/to/screenshot.png' })`. Also accepts `width`, `height`, `maxDimension`, `quality`, `format` (default: `'png'`), `output`. Alias: `resizeImage`.
 **recording.start / recording.stop** - record the page as a video at native FPS (30-60fps). Uses `chrome.tabCapture` so **recording survives page navigation**. Auto-overlays a ghost cursor that follows mouse actions. Requires user to have clicked the Playwriter extension icon on the tab. Auto-resizes viewport to 16:9 (override with `aspectRatio: null`). Auto-stops after 15 min (override with `maxDurationMs`).
@@ -815,7 +858,7 @@ For demos, use interaction methods (`locator.click()`, `page.mouse.move()`) inst
 ```js
 await recording.start({
   page: state.page,
-  outputPath: './recording.mp4',
+  outputPath: '/absolute/path/to/recording.mp4',
   frameRate: 30, // default
   audio: false, // default (tab audio)
   videoBitsPerSecond: 2500000,
@@ -869,7 +912,7 @@ await el.click()
 Always use `scale: 'css'` to avoid 2-4x larger images on high-DPI displays:
 ```js
-await state.page.screenshot({ path: 'shot.png', scale: 'css' })
+await state.page.screenshot({ path: '/absolute/path/to/shot.png', scale: 'css' })
 ```
 If you want to read back the image file into context, resize it first so it consumes fewer tokens:
@@ -1048,7 +1091,7 @@ await state.page.setViewportSize({ width: 1280, height: 720 })
 ### region screenshot (zoom equivalent)
 ```js
-await state.page.screenshot({ path: 'region.png', scale: 'css', clip: { x: 100, y: 200, width: 400, height: 300 } })
+await state.page.screenshot({ path: '/absolute/path/to/region.png', scale: 'css', clip: { x: 100, y: 200, width: 400, height: 300 } })
 ```
 Prefer locator-based actions over coordinates — locators are stable across scroll/resize, auto-wait for elements, and don't require screenshot round-trips that burn ~800 image tokens per cycle.

package/src/start-relay-server.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 import { startPlayWriterCDPRelayServer } from './cdp-relay.js'
 import { createFileLogger } from './create-logger.js'
+import { waitForRelayVersion } from './relay-client.js'
 import { LOG_CDP_FILE_PATH } from './utils.js'
 process.title = 'playwriter-ws-server'
@@ -25,7 +26,27 @@ export async function startServer({
   host = '127.0.0.1',
   token,
 }: { port?: number; host?: string; token?: string } = {}) {
-  const server = await startPlayWriterCDPRelayServer({ port, host, token, logger })
+  let server
+  try {
+    server = await startPlayWriterCDPRelayServer({ port, host, token, logger })
+  } catch (err: unknown) {
+    // When two relay processes race to start (issue #75), the loser gets
+    // EADDRINUSE. Check if the winner is a valid relay and exit cleanly
+    // instead of crashing with a scary error in the logs.
+    const errWithCode = err as NodeJS.ErrnoException
+    if (errWithCode?.code === 'EADDRINUSE') {
+      // The winner may have bound the port but not be ready to answer /version
+      // yet, so poll for up to 2 seconds before giving up.
+      const version = await waitForRelayVersion({ port })
+      if (version) {
+        await logger.log(`Another relay (v${version}) already bound to port ${port}, exiting gracefully`)
+        process.exit(0)
+      }
+      await logger.error(`Port ${port} is in use by a non-relay process`)
+      process.exit(1)
+    }
+    throw err
+  }
   console.log('CDP Relay Server running. Press Ctrl+C to stop.')
   console.log('Logs are being written to:', logger.logFilePath)

package/src/utils.ts CHANGED Viewed

@@ -36,11 +36,13 @@ export function getCdpUrl({
   host = '127.0.0.1',
   token,
   extensionId,
+  autoEnable,
 }: {
   port?: number
   host?: string
   token?: string
   extensionId?: string | null
+  autoEnable?: boolean
 } = {}) {
   const id = `${Math.random().toString(36).substring(2, 15)}_${Date.now()}`
   const params = new URLSearchParams()
@@ -50,6 +52,9 @@ export function getCdpUrl({
   if (extensionId) {
     params.set('extensionId', extensionId)
   }
+  if (autoEnable) {
+    params.set('autoEnable', '1')
+  }
   const queryString = params.toString()
   const suffix = queryString ? `?${queryString}` : ''
   const { wsBaseUrl } = parseRelayHost(host, port)