playwriter 0.0.33 → 0.0.34

package/src/prompt.md

@@ -1,259 +1,283 @@
-playwriter execute is a tool to control the user browser instance via extension also called playwriter MCP.
+# playwriter execute
 
-if you get an error Extension not running tell user to install and enable the playwriter extension first, clicking on the extension icon on the tab the user wants to control
+Control user's Chrome browser via playwright code snippets. Prefer single-line code with semicolons between statements. If you get "Extension not running" error, tell user to click the playwriter extension icon on the tab they want to control.
 
-execute tool let you run playwright js code snippets to control user Chrome window, these js code snippets are preferred to be in a single line to make them more readable in agent interface. separating statements with semicolons
+You can collaborate with the user - they can help with captchas, difficult elements, or reproducing bugs.
 
-you can extract data from your script using `console.log`. But remember that console.log in `page.evaluate` callbacks are run in the browser, so you will not see them. Instead log the evaluate result
+## context variables
 
-to keep some variables between calls, you can use `state` global object. constants and variables are reset between runs. Instead use code like `state.newPage = await browser.newPage();` to reuse the created page in later calls
+- `state` - object persisted between calls, use to store data/pages (e.g., `state.myPage = await context.newPage()`)
+- `page` - default page the user activated, use this unless working with multiple pages
+- `context` - browser context, access all pages via `context.pages()`
+- `require` - load node modules (e.g., `require('node:fs')`)
+- Node.js globals: `setTimeout`, `setInterval`, `fetch`, `URL`, `Buffer`, `crypto`, etc.
 
-you MUST use multiple execute tool calls for running complex logic. this ensures 
-- you have clear understanding of intermediate state between interactions
-- you can split finding an element from interacting with it. making it simpler to understand what is the issue when an action is not successful
+## rules
 
-it will control an existing user Chrome window. The js code  will be run in a sandbox with some variables in context:
+- **Multiple calls**: use multiple execute calls for complex logic - helps understand intermediate state and isolate which action failed
+- **Never close**: never call `browser.close()` or `context.close()`. Only close pages you created or if user asks
+- **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 `page.removeAllListeners()` at end of message to prevent leaks
+- **CDP sessions**: use `getCDPSession({ page })` not `page.context().newCDPSession()` - the latter doesn't work through playwriter relay
+- **Wait for load**: use `page.waitForLoadState('load')` not `page.waitForEvent('load')` - waitForEvent times out if already loaded
+- **Avoid timeouts**: prefer proper waits over `page.waitForTimeout()` - there are better ways to wait for elements
 
-- state: an object shared between runs that you can mutate to persist functions and objects. for example `state.requests = []` to monitor network requests between runs
-- context: the playwright browser context. you can do things like `await context.pages()` to see user connected pages
-- page, the first page the user opened and made it accessible to this MCP. do things like `page.url()` to see current url. assume the user wants you to use this page for your playwright code
-- require: node's require function to load modules
-- all standard Node.js globals: setTimeout, setInterval, clearTimeout, clearInterval, URL, URLSearchParams, fetch, Buffer, TextEncoder, TextDecoder, crypto, AbortController, AbortSignal, structuredClone
+## checking page state
 
-the chrome window can have more than one page. you can see other pages with `context.pages().find((p) => p.url().includes('localhost'))`. you can also open and close pages: `state.newPage = await context.newPage()`. store the page in state so that you can reuse it later
+After any action (click, submit, navigate), verify what happened:
 
-you can control the browser in collaboration with the user. the user can help you get unstuck from  captchas or difficult to find elements or reproducing a bug
+```js
+console.log('url:', page.url()); console.log(await accessibilitySnapshot({ page }).then(x => x.split('\n').slice(0, 30).join('\n')));
+```
 
-## capabilities
+If nothing changed, try `await page.waitForLoadState('networkidle', {timeout: 3000})` or you may have clicked the wrong element.
+
+## accessibility snapshots
+
+```js
+await accessibilitySnapshot({ page, search?, contextLines?, showDiffSinceLastCall? })
+```
 
-examples of things playwriter MCP can do:
-- monitor logs for a page while the user reproduces a but to let you understand what is causing a bug
-- monitor logs while also controlling the page, then read collected logs and debug an issue
-- monitor xhr network requests while scrolling an infinite scroll page to extract data from a website
-- get accessibility snapshot to see clickable elements on the page, then click or interact with them to automate a task like ordering pizza
+- `search` - string/regex to filter results (returns first 10 matches with context)
+- `contextLines` - lines of context around matches (default: 10)
+- `showDiffSinceLastCall` - returns diff since last snapshot (useful after actions)
 
-## finding the page to execute code in
+Example output:
 
-if you plan to control a specific page for an url you can store it in `state` so you can reuse it later on:
+```md
+- banner [ref=e3]:
+    - link "Home" [ref=e5] [cursor=pointer]:
+        - /url: /
+    - navigation [ref=e12]:
+        - link "Docs" [ref=e13] [cursor=pointer]:
+            - /url: /docs
+```
+
+Use `aria-ref` to interact - **no quotes around the ref value**:
 
 ```js
-const pages = context.pages().filter(x => x.url().includes('localhost'));
-if (pages.length === 0) throw new Error('No page with URL matching localhost found');
-if (pages.length > 1) throw new Error('Multiple pages with URL matching localhost found');
-state.localhostPage = pages[0];
-// do things with the page
-await state.localhostPage.bringToFront();
+await page.locator('aria-ref=e13').click()
 ```
 
-IMPORTANT! never call bringToFront unless specifically asked by the user. It is very bothering to the user otherwise! you don't need to call bringToFront before being able to interact. you can very well interact without calling it first. on any page in the background you have access to.
+Search for specific elements:
 
-## rules
+```js
+const snapshot = await accessibilitySnapshot({ page, search: /button|submit/i })
+```
 
-- only call `page.close()` if the user asks you so or if you previously created this page yourself with `newPage`. do not close user created pages unless asked
-- try to never sleep or run `page.waitForTimeout` unless you have to. there are better ways to wait for an element
-- use `page.waitForLoadState('load')` instead of `page.waitForEvent('load')`. `waitForEvent` waits for a future event and will timeout if the page is already loaded, while `waitForLoadState` resolves immediately if already in that state
-- never close browser or context. NEVER call `browser.close()`
-- NEVER use `page.context().newCDPSession()` or `browser.newCDPSession()` - these do not work through the playwriter relay. If you need to send raw CDP commands, use the `getCDPSession` utility function instead.
+## selector best practices
 
+**For unknown websites**: use `accessibilitySnapshot()` with `aria-ref` - it shows what's actually interactive.
 
-## always check the current page state after an action
+**For development** (when you have source code access), prefer stable selectors in this order:
 
-after you click a button or submit a form you ALWAYS have to then check what is the current state of the page. you cannot assume what happened after doing an action. instead run the following code to know what happened after the action:
+1. **Best**: `[data-testid="submit"]` - explicit test attributes, never change accidentally
+2. **Good**: `getByRole('button', { name: 'Save' })` - accessible, semantic
+3. **Good**: `getByText('Sign in')`, `getByLabel('Email')` - readable, user-facing
+4. **OK**: `input[name="email"]`, `button[type="submit"]` - semantic HTML
+5. **Avoid**: `.btn-primary`, `#submit` - classes/IDs change frequently
+6. **Last resort**: `div.container > form > button` - fragile, breaks easily
 
-`console.log('url:', page.url()); console.log(await accessibilitySnapshot({ page }).then(x => x.split('\n').slice(0, 30).join('\n')));`
+Combine locators for precision:
 
-if nothing happened you may need to wait before the action completes, using something like `page.waitForNavigation({timeout: 3000})` or `await page.waitForLoadState('networkidle', {timeout: 3000})`
+```js
+page.locator('tr').filter({ hasText: 'John' }).locator('button').click()
+page.locator('button').nth(2).click()
+```
 
-if nothing happens it could also means that you clicked the wrong button or link. try to search for other appropriate elements to click or submit
+If a locator matches multiple elements, Playwright throws "strict mode violation". Use `.first()`, `.last()`, or `.nth(n)`:
 
+```js
+await page.locator('button').first().click()  // first match
+await page.locator('.item').last().click()    // last match
+await page.locator('li').nth(3).click()       // 4th item (0-indexed)
+```
 
-## event listeners
+## working with pages
 
-always detach event listener you create at the end of a message using `page.removeAllListeners()` or similar so that you never leak them in future messages
+Find a specific page:
 
-## utility functions
+```js
+const pages = context.pages().filter(x => x.url().includes('localhost'));
+if (pages.length !== 1) throw new Error(`Expected 1 page, found ${pages.length}`);
+state.targetPage = pages[0];
+```
 
-you have access to some functions in addition to playwright methods:
-
-- `async accessibilitySnapshot({ page, search, contextLines, showDiffSinceLastCall })`: gets a human readable snapshot of clickable elements on the page. useful to see the overall structure of the page and what elements you can interact with.
-    - `page`: the page object to snapshot
-    - `search`: (optional) a string or regex to filter the snapshot. If provided, returns the first 10 matches with surrounding context
-    - `contextLines`: (optional) number of lines of context to show around each match (default: 10). Also controls context lines in diff output.
-    - `showDiffSinceLastCall`: (optional) if true, returns a unified diff patch showing only changes since the last non-diff snapshot call for this page. Disables search when enabled. Useful to see what changed after an action. Note: diff calls do not update the stored snapshot, so you can call diff multiple times and always compare against the same baseline.
-- `getLatestLogs({ page, count, search })`: retrieves browser console logs. The system automatically captures and stores up to 5000 logs per page. Logs are cleared when a page reloads or navigates.
-    - `page`: (optional) filter logs by a specific page instance. Only returns logs from that page
-    - `count`: (optional) limit number of logs to return. If not specified, returns all available logs
-    - `search`: (optional) string or regex to filter logs. Only returns logs that match
-- `waitForPageLoad({ page, timeout, pollInterval, minWait })`: smart network-aware page load detection. Playwright's `networkidle` waits for ALL requests to finish, which often times out on sites with analytics/ads. This function ignores those and returns when meaningful content is loaded.
-    - `page`: the page object to wait on
-    - `timeout`: (optional) max wait time in ms (default: 30000)
-    - `pollInterval`: (optional) how often to check in ms (default: 100)
-    - `minWait`: (optional) minimum wait before checking in ms (default: 500)
-    - Returns: `{ success, readyState, pendingRequests, waitTimeMs, timedOut }`
-    - Filters out: ad networks (doubleclick, googlesyndication), analytics (google-analytics, mixpanel, segment), social (facebook.net, twitter), support widgets (intercom, zendesk), and slow fonts/images
-- `getCDPSession({ page })`: creates a CDP session to send raw Chrome DevTools Protocol commands. Use this instead of `page.context().newCDPSession()` which does not work through the playwriter relay. Sessions are cached per page.
-    - `page`: the page object to create the session for
-    - Returns: `{ send(method, params?), on(event, callback), off(event, callback) }`
-    - Example: `const cdp = await getCDPSession({ page }); const metrics = await cdp.send('Page.getLayoutMetrics');`
-- `createDebugger({ cdp })`: creates a Debugger instance for setting breakpoints, stepping, and inspecting variables. Read the `https://playwriter.dev/resources/debugger-api.md` resource for full API docs and examples.
-- `createEditor({ cdp })`: creates an Editor instance for viewing and live-editing page scripts and CSS stylesheets. Read the `https://playwriter.dev/resources/editor-api.md` resource for full API docs and examples.
-- `getStylesForLocator({ locator })`: gets the CSS styles applied to an element, similar to browser DevTools "Styles" panel. Read the `https://playwriter.dev/resources/styles-api.md` resource for full API docs and examples.
-- `getReactSource({ locator })`: gets the React component source location (file, line, column) for an element.
-    - `locator`: a Playwright Locator or ElementHandle for the element to inspect
-    - Returns: `{ fileName, lineNumber, columnNumber, componentName }` or `null` if not found
-    - **Important**: Only works on **local dev servers** (localhost with Vite, Next.js, CRA in dev mode). Production builds strip source info.
-
-example:
+Create new page:
 
-```md
-- generic [active] [ref=e1]:
-    - generic [ref=e2]:
-        - banner [ref=e3]:
-            - generic [ref=e5]:
-                - link "shadcn/ui" [ref=e6] [cursor=pointer]:
-                    - /url: /
-                    - img
-                    - generic [ref=e11] [cursor=pointer]: shadcn/ui
-                - navigation [ref=e12]:
-                    - link "Docs" [ref=e13] [cursor=pointer]:
-                        - /url: /docs/installation
-                    - link "Components" [ref=e14] [cursor=pointer]:
-                        - /url: /docs/components
+```js
+state.newPage = await context.newPage();
+await state.newPage.goto('https://example.com');
 ```
 
-Then you can use `page.locator(`aria-ref=${ref}`)` to get an element with a specific `ref` and interact with it.
+## common patterns
 
-`const componentsLink = page.locator('aria-ref=e14').click()` 
+**Popups** - capture before triggering:
 
-IMPORTANT: notice that we do not add any quotes in `aria-ref`! it MUST be called without quotes
+```js
+const [popup] = await Promise.all([page.waitForEvent('popup'), page.click('a[target=_blank]')]);
+await popup.waitForLoadState(); console.log('Popup URL:', popup.url());
+```
 
-## getting a stable selector for an element (getLocatorStringForElement)
+**Downloads** - capture and save:
 
-The `aria-ref` values from accessibility snapshots are ephemeral - they change on page reload and when components remount. Use `getLocatorStringForElement(element)` to get a stable Playwright locator string that you can reuse programmatically.
+```js
+const [download] = await Promise.all([page.waitForEvent('download'), page.click('button.download')]);
+await download.saveAs(`/tmp/${download.suggestedFilename()}`);
+```
 
-This is useful for:
-- Getting a selector you can store and reuse across page reloads
-- Finding similar elements in a list (modify the selector pattern)
-- Debugging which selector Playwright would use for an element
+**iFrames** - use frameLocator:
 
 ```js
-const loc = page.locator('aria-ref=e14');
-const selector = await getLocatorStringForElement(loc);
-console.log(selector);
-// => "getByRole('button', { name: 'Save' })"
+const frame = page.frameLocator('#my-iframe');
+await frame.locator('button').click();
+```
+
+**Dialogs** - handle alerts/confirms/prompts:
 
-// use the selector programmatically with eval:
-const stableLocator = page.getByRole('button', { name: 'Save' })
-await stableLocator.click();
+```js
+page.on('dialog', async dialog => { console.log(dialog.message()); await dialog.accept(); });
+await page.click('button.trigger-alert');
 ```
 
-## pinned elements (user right-click to pin)
+## utility functions
 
-Users can right-click an element and select "Pin to Playwriter" to store it in `globalThis.playwriterPinnedElem1` (increments for each pin). The variable name is copied to clipboard.
+**getLatestLogs** - retrieve captured browser console logs (up to 5000 per page, cleared on navigation):
 
 ```js
-const el = await page.evaluateHandle(() => globalThis.playwriterPinnedElem1);
-await el.click();
-const selector = await getLocatorStringForElement(el);
+await getLatestLogs({ page?, count?, search? })
+// Examples:
+const errors = await getLatestLogs({ search: /error/i, count: 50 })
+const pageLogs = await getLatestLogs({ page })
 ```
 
-## finding specific elements with snapshot
+For custom log collection across runs, store in state: `state.logs = []; page.on('console', m => state.logs.push(m.text()))`
+
+**waitForPageLoad** - smart load detection that ignores analytics/ads:
 
-You can use `search` to find specific elements in the snapshot without reading the whole page structure. This is useful for finding forms, textareas, or specific text.
+```js
+await waitForPageLoad({ page, timeout?, pollInterval?, minWait? })
+// Returns: { success, readyState, pendingRequests, waitTimeMs, timedOut }
+```
 
-Example: find a textarea or form using case-insensitive regex:
+**getCDPSession** - send raw CDP commands:
 
 ```js
-const snapshot = await accessibilitySnapshot({ page, search: /textarea|form/i })
-console.log(snapshot)
+const cdp = await getCDPSession({ page });
+const metrics = await cdp.send('Page.getLayoutMetrics');
 ```
 
-Example: find elements containing "Login":
+**getLocatorStringForElement** - get stable selector from ephemeral aria-ref:
 
 ```js
-const snapshot = await accessibilitySnapshot({ page, search: "Login" })
-console.log(snapshot)
+const selector = await getLocatorStringForElement(page.locator('aria-ref=e14'));
+// => "getByRole('button', { name: 'Save' })"
 ```
 
-## getting outputs of code execution
+**getReactSource** - get React component source location (dev mode only):
 
-You can use `console.log` to print values you want to see in the tool call result. For seeing logs across runs you can store then in `state.logs` and then print them later, filtering and paginating them too.
+```js
+const source = await getReactSource({ locator: page.locator('aria-ref=e5') });
+// => { fileName, lineNumber, columnNumber, componentName }
+```
 
-## using page.evaluate
+**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 read `https://playwriter.dev/resources/styles-api.md` first.
 
-you can execute client side JavaScript code using `page.evaluate()`
+```js
+const styles = await getStylesForLocator({ locator: page.locator('.btn'), cdp: await getCDPSession({ page }) });
+console.log(formatStylesAsText(styles));
+```
 
-When executing code with `page.evaluate()`, return values directly from the evaluate function. Use `console.log()` outside of evaluate to display results:
+**createDebugger** - set breakpoints, step through code, inspect variables at runtime. Useful for debugging issues that only reproduce in browser, understanding code flow, and inspecting state at specific points. Can pause on exceptions, evaluate expressions in scope, and blackbox framework code. ALWAYS read `https://playwriter.dev/resources/debugger-api.md` first.
 
 ```js
-// Get data from the page by returning it
-const title = await page.evaluate(() => document.title)
-console.log('Page title:', title)
-
-// Return multiple values as an object
-const pageInfo = await page.evaluate(() => ({
-    url: window.location.href,
-    buttonCount: document.querySelectorAll('button').length,
-    readyState: document.readyState,
-}))
-console.log(pageInfo)
+const cdp = await getCDPSession({ page }); const dbg = createDebugger({ cdp }); await dbg.enable();
+const scripts = await dbg.listScripts({ search: 'app' });
+await dbg.setBreakpoint({ file: scripts[0].url, line: 42 });
+// when paused: dbg.inspectLocalVariables(), dbg.stepOver(), dbg.resume()
 ```
 
-## read logs during interactions
+**createEditor** - view and live-edit page scripts and CSS at runtime. Edits are in-memory (persist until reload). Useful for testing quick fixes, searching page scripts with grep, and toggling debug flags. ALWAYS read `https://playwriter.dev/resources/editor-api.md` first.
 
-you can see logs during interactions with `page.on('console', msg => console.log(`Browser log: [${msg.type()}] ${msg.text()}`))`
+```js
+const cdp = await getCDPSession({ page }); const editor = createEditor({ cdp }); await editor.enable();
+const matches = await editor.grep({ regex: /console\.log/ });
+await editor.edit({ url: matches[0].url, oldString: 'DEBUG = false', newString: 'DEBUG = true' });
+```
 
-then remember to call `context.removeAllListeners()` or `page.removeAllListeners('console')` to not see logs in next execute calls.
+## pinned elements
 
-## reading past logs
+Users can right-click → "Copy Playwriter Element Reference" to store elements in `globalThis.playwriterPinnedElem1` (increments for each pin). The reference is copied to clipboard:
 
-you can keep track of logs using `state.logs = []; page.on('console', msg => state.logs.push({ type: msg.type(), text: msg.text() }))`
+```js
+const el = await page.evaluateHandle(() => globalThis.playwriterPinnedElem1);
+await el.click();
+```
 
-later, you can read logs that you care about. For example, to get the last 100 logs that contain the word "error":
+## page.evaluate
 
-`console.log('errors:'); state.logs.filter(log => log.type === 'error').slice(-100).forEach(x => console.log(x))`
+Code inside `page.evaluate()` runs in the browser - use plain JavaScript only, no TypeScript syntax. Return values and log outside (console.log inside evaluate runs in browser, not visible):
 
-then to reset logs: `state.logs = []` and to stop listening: `page.removeAllListeners('console')`
+```js
+const title = await page.evaluate(() => document.title);
+console.log('Title:', title);
+
+const info = await page.evaluate(() => ({
+    url: location.href,
+    buttons: document.querySelectorAll('button').length,
+}));
+console.log(info);
+```
 
-## using getLatestLogs to read browser console logs
+## loading files
 
-The system automatically captures and stores up to 5000 browser console logs per page. Logs are automatically cleared when a page reloads or navigates to a new URL. You can retrieve logs using the `getLatestLogs` function:
+Fill inputs with file content:
 
 ```js
-// Get all browser console logs from all pages (up to 5000 per page)
-const allLogs = await getLatestLogs()
-console.log(allLogs)
-
-// Get last 50 browser error logs
-const errorLogs = await getLatestLogs({ count: 50, search: /\[error\]/ })
-console.log(errorLogs)
+const fs = require('node:fs'); const content = fs.readFileSync('./README.md', 'utf-8'); await page.locator('textarea').fill(content);
+```
 
-// Get all browser logs from the current page only
-const pageLogs = await getLatestLogs({ page })
-console.log(pageLogs)
+## network interception
 
-// Find browser logs containing specific text
-const authLogs = await getLatestLogs({ search: 'authentication failed' })
-console.log(authLogs)
+For scraping or reverse-engineering APIs, intercept network requests instead of scrolling DOM. Store in `state` to analyze across calls:
 
-// Example output format:
-// [log] User clicked login button
-// [error] Failed to fetch /api/auth
-// [warn] Session expiring soon
+```js
+state.requests = []; state.responses = [];
+page.on('request', req => { if (req.url().includes('/api/')) state.requests.push({ url: req.url(), method: req.method(), headers: req.headers() }); });
+page.on('response', async res => { if (res.url().includes('/api/')) { try { state.responses.push({ url: res.url(), status: res.status(), body: await res.json() }); } catch {} } });
 ```
 
-## loading file content into inputs
+Then trigger actions (scroll, click, navigate) and analyze captured data:
+
+```js
+console.log('Captured', state.responses.length, 'API calls');
+state.responses.forEach(r => console.log(r.status, r.url.slice(0, 80)));
+```
 
-you can use the `require` function to read files and fill inputs with their content:
+Inspect a specific response to understand schema:
 
 ```js
-const fs = require('node:fs'); const content = fs.readFileSync('/path/to/file.txt', 'utf-8'); await page.locator('textarea').fill(content)
+const resp = state.responses.find(r => r.url.includes('users'));
+console.log(JSON.stringify(resp.body, null, 2).slice(0, 2000));
 ```
 
-for example, to fill a textarea with the content of a markdown file:
+Replay API directly (useful for pagination):
 
 ```js
-const fs = require('node:fs'); const readme = fs.readFileSync('./README.md', 'utf-8'); await page.locator('#description').fill(readme); console.log('Filled textarea with README content')
+const { url, headers } = state.requests.find(r => r.url.includes('feed'));
+const data = await page.evaluate(async ({ url, headers }) => { const res = await fetch(url, { headers }); return res.json(); }, { url, headers });
+console.log(data);
 ```
 
-if user seems happy or compliments playwriter ask them to review in chrome web store extension jfeammnjpkecdekppnclgkkffahnhfhe
+Clean up listeners when done: `page.removeAllListeners('request'); page.removeAllListeners('response');`
+
+## capabilities
+
+Examples of what playwriter can do:
+- Monitor console logs while user reproduces a bug
+- Intercept network requests to reverse-engineer APIs and build SDKs
+- Scrape data by replaying paginated API calls instead of scrolling DOM
+- Get accessibility snapshot to find elements, then automate interactions
+- Debug issues by collecting logs and controlling the page simultaneously
+- Handle popups, downloads, iframes, and dialog boxes

package/src/protocol.ts

@@ -19,6 +19,7 @@ export type ExtensionCommandMessage = ForwardCDPCommand
 
 export type ExtensionResponseMessage = {
   id: number
+  method?: undefined
   result?: any
   error?: string
 }
@@ -30,6 +31,7 @@ export type ExtensionResponseMessage = {
 export type ExtensionEventMessage =
   {
     [K in keyof ProtocolMapping.Events]: {
+      id?: undefined
       method: 'forwardCDPEvent'
       params: {
         method: CDPEventFor<K>['method']
@@ -40,6 +42,7 @@ export type ExtensionEventMessage =
   }[keyof ProtocolMapping.Events]
 
 export type ExtensionLogMessage = {
+  id?: undefined
   method: 'log'
   params: {
     level: 'log' | 'debug' | 'info' | 'warn' | 'error'
@@ -47,4 +50,14 @@ export type ExtensionLogMessage = {
   }
 }
 
-export type ExtensionMessage = ExtensionResponseMessage | ExtensionEventMessage | ExtensionLogMessage
+export type ExtensionPongMessage = {
+  id?: undefined
+  method: 'pong'
+}
+
+export type ServerPingMessage = {
+  method: 'ping'
+  id?: undefined
+}
+
+export type ExtensionMessage = ExtensionResponseMessage | ExtensionEventMessage | ExtensionLogMessage | ExtensionPongMessage

package/src/react-source.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { Page, Locator, ElementHandle } from 'playwright-core'
-import type { CDPSession } from './cdp-session.js'
+import type { ICDPSession, CDPSession } from './cdp-session.js'
 
 export interface ReactSourceLocation {
   fileName: string | null
@@ -25,11 +25,13 @@ function getBippyCode(): string {
 
 export async function getReactSource({
   locator,
-  cdp,
+  cdp: cdpSession,
 }: {
   locator: Locator | ElementHandle
-  cdp: CDPSession
+  cdp: ICDPSession
 }): Promise<ReactSourceLocation | null> {
+  // Cast to CDPSession for internal type safety - at runtime both are compatible
+  const cdp = cdpSession as CDPSession
   const page: Page = 'page' in locator && typeof locator.page === 'function' ? locator.page() : (locator as any)._page
 
   if (!page) {

package/src/styles.ts

@@ -1,4 +1,4 @@
-import type { CDPSession } from './cdp-session.js'
+import type { ICDPSession, CDPSession } from './cdp-session.js'
 import type { Locator } from 'playwright-core'
 
 export interface StyleSource {
@@ -66,13 +66,15 @@ interface CSSStyleSheetHeader {
 
 export async function getStylesForLocator({
   locator,
-  cdp,
+  cdp: cdpSession,
   includeUserAgentStyles = false,
 }: {
   locator: Locator
-  cdp: CDPSession
+  cdp: ICDPSession
   includeUserAgentStyles?: boolean
 }): Promise<StylesResult> {
+  // Cast to CDPSession for internal type safety - at runtime both are compatible
+  const cdp = cdpSession as CDPSession
   await cdp.send('DOM.enable')
   await cdp.send('CSS.enable')