npm - playwriter - Versions diffs - 0.0.63 → 0.0.89 - Mend

playwriter 0.0.63 → 0.0.89

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 (223) hide show

package/dist/a11y-client.js +18 -8
package/dist/aria-snapshot.d.ts +41 -3
package/dist/aria-snapshot.d.ts.map +1 -1
package/dist/aria-snapshot.js +134 -55
package/dist/aria-snapshot.js.map +1 -1
package/dist/aria-snapshot.test.js +5 -2
package/dist/aria-snapshot.test.js.map +1 -1
package/dist/aria-snapshot.unit.test.js +83 -41
package/dist/aria-snapshot.unit.test.js.map +1 -1
package/dist/assets/cursors/screen-studio/pointer-macos-tahoe-data-url.d.ts +5 -0
package/dist/assets/cursors/screen-studio/pointer-macos-tahoe-data-url.d.ts.map +1 -0
package/dist/assets/cursors/screen-studio/pointer-macos-tahoe-data-url.js +5 -0
package/dist/assets/cursors/screen-studio/pointer-macos-tahoe-data-url.js.map +1 -0
package/dist/bippy.js +1 -1
package/dist/cdp-log.d.ts +1 -1
package/dist/cdp-log.d.ts.map +1 -1
package/dist/cdp-log.js +1 -1
package/dist/cdp-log.js.map +1 -1
package/dist/cdp-relay.d.ts.map +1 -1
package/dist/cdp-relay.js +492 -298
package/dist/cdp-relay.js.map +1 -1
package/dist/cdp-session.d.ts.map +1 -1
package/dist/cdp-session.js.map +1 -1
package/dist/cdp-types.d.ts.map +1 -1
package/dist/cdp-types.js +7 -7
package/dist/cdp-types.js.map +1 -1
package/dist/clean-html.d.ts.map +1 -1
package/dist/clean-html.js +4 -5
package/dist/clean-html.js.map +1 -1
package/dist/cli.js +45 -27
package/dist/cli.js.map +1 -1
package/dist/create-logger.d.ts.map +1 -1
package/dist/create-logger.js +3 -1
package/dist/create-logger.js.map +1 -1
package/dist/debugger-examples-types.d.ts.map +1 -1
package/dist/debugger.d.ts.map +1 -1
package/dist/debugger.js +1 -3
package/dist/debugger.js.map +1 -1
package/dist/diff-utils.d.ts.map +1 -1
package/dist/diff-utils.js +1 -4
package/dist/diff-utils.js.map +1 -1
package/dist/editor-api.md +12 -2
package/dist/editor-examples.d.ts +1 -1
package/dist/editor-examples.d.ts.map +1 -1
package/dist/editor-examples.js +1 -1
package/dist/editor-examples.js.map +1 -1
package/dist/editor.d.ts +1 -1
package/dist/editor.d.ts.map +1 -1
package/dist/editor.js +1 -1
package/dist/editor.js.map +1 -1
package/dist/executor.d.ts +26 -3
package/dist/executor.d.ts.map +1 -1
package/dist/executor.js +297 -64
package/dist/executor.js.map +1 -1
package/dist/executor.unit.test.js +38 -1
package/dist/executor.unit.test.js.map +1 -1
package/dist/extension-connection.test.js +139 -36
package/dist/extension-connection.test.js.map +1 -1
package/dist/ffmpeg.d.ts +148 -0
package/dist/ffmpeg.d.ts.map +1 -0
package/dist/ffmpeg.js +523 -0
package/dist/ffmpeg.js.map +1 -0
package/dist/ghost-browser.d.ts.map +1 -1
package/dist/ghost-browser.js.map +1 -1
package/dist/ghost-cursor-client.js +287 -0
package/dist/ghost-cursor.d.ts +27 -0
package/dist/ghost-cursor.d.ts.map +1 -0
package/dist/ghost-cursor.js +63 -0
package/dist/ghost-cursor.js.map +1 -0
package/dist/htmlrewrite.d.ts.map +1 -1
package/dist/htmlrewrite.js +17 -55
package/dist/htmlrewrite.js.map +1 -1
package/dist/htmlrewrite.test.js.map +1 -1
package/dist/kill-port.d.ts.map +1 -1
package/dist/kill-port.js +1 -3
package/dist/kill-port.js.map +1 -1
package/dist/locator-selector.test.d.ts +2 -0
package/dist/locator-selector.test.d.ts.map +1 -0
package/dist/locator-selector.test.js +96 -0
package/dist/locator-selector.test.js.map +1 -0
package/dist/mcp-client.js.map +1 -1
package/dist/mcp.d.ts.map +1 -1
package/dist/mcp.js +8 -3
package/dist/mcp.js.map +1 -1
package/dist/on-mouse-action.test.d.ts +2 -0
package/dist/on-mouse-action.test.d.ts.map +1 -0
package/dist/on-mouse-action.test.js +155 -0
package/dist/on-mouse-action.test.js.map +1 -0
package/dist/page-markdown.js +4 -4
package/dist/page-markdown.js.map +1 -1
package/dist/prompt.md +450 -377
package/dist/protocol.d.ts +4 -0
package/dist/protocol.d.ts.map +1 -1
package/dist/readability.js +16 -2
package/dist/recording-ghost-cursor.d.ts +41 -0
package/dist/recording-ghost-cursor.d.ts.map +1 -0
package/dist/recording-ghost-cursor.js +79 -0
package/dist/recording-ghost-cursor.js.map +1 -0
package/dist/recording-relay.d.ts.map +1 -1
package/dist/recording-relay.js +8 -8
package/dist/recording-relay.js.map +1 -1
package/dist/relay-client.d.ts +17 -4
package/dist/relay-client.d.ts.map +1 -1
package/dist/relay-client.js +45 -11
package/dist/relay-client.js.map +1 -1
package/dist/relay-core.test.d.ts.map +1 -1
package/dist/relay-core.test.js +515 -26
package/dist/relay-core.test.js.map +1 -1
package/dist/relay-navigation.test.d.ts.map +1 -1
package/dist/relay-navigation.test.js +169 -31
package/dist/relay-navigation.test.js.map +1 -1
package/dist/relay-session.test.d.ts.map +1 -1
package/dist/relay-session.test.js +113 -65
package/dist/relay-session.test.js.map +1 -1
package/dist/relay-state.d.ts +158 -0
package/dist/relay-state.d.ts.map +1 -0
package/dist/relay-state.js +306 -0
package/dist/relay-state.js.map +1 -0
package/dist/relay-state.test.d.ts +2 -0
package/dist/relay-state.test.d.ts.map +1 -0
package/dist/relay-state.test.js +472 -0
package/dist/relay-state.test.js.map +1 -0
package/dist/scoped-fs.d.ts.map +1 -1
package/dist/scoped-fs.js.map +1 -1
package/dist/screen-recording.d.ts +66 -4
package/dist/screen-recording.d.ts.map +1 -1
package/dist/screen-recording.js +150 -13
package/dist/screen-recording.js.map +1 -1
package/dist/screen-recording.test.d.ts +2 -0
package/dist/screen-recording.test.d.ts.map +1 -0
package/dist/screen-recording.test.js +102 -0
package/dist/screen-recording.test.js.map +1 -0
package/dist/selector-generator.js +1 -1
package/dist/snapshot-tools.test.js +71 -28
package/dist/snapshot-tools.test.js.map +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 +1 -1
package/dist/start-relay-server.js.map +1 -1
package/dist/styles-api.md +8 -1
package/dist/styles-examples.d.ts +1 -1
package/dist/styles-examples.d.ts.map +1 -1
package/dist/styles-examples.js +1 -1
package/dist/styles-examples.js.map +1 -1
package/dist/styles.d.ts.map +1 -1
package/dist/styles.js +1 -3
package/dist/styles.js.map +1 -1
package/dist/test-declarations.d.ts.map +1 -1
package/dist/test-utils.d.ts +1 -1
package/dist/test-utils.d.ts.map +1 -1
package/dist/test-utils.js +7 -5
package/dist/test-utils.js.map +1 -1
package/dist/utils.d.ts.map +1 -1
package/dist/utils.js.map +1 -1
package/dist/wait-for-page-load.d.ts.map +1 -1
package/dist/wait-for-page-load.js +1 -1
package/dist/wait-for-page-load.js.map +1 -1
package/package.json +4 -3
package/src/a11y-client.ts +5 -4
package/src/aria-snapshot.test.ts +5 -2
package/src/aria-snapshot.ts +306 -117
package/src/aria-snapshot.unit.test.ts +199 -141
package/src/aria-snapshots/github-interactive.txt +2 -0
package/src/aria-snapshots/github-raw.txt +5 -1
package/src/aria-snapshots/hackernews-interactive.txt +238 -241
package/src/aria-snapshots/hackernews-raw.txt +265 -269
package/src/assets/aria-labels-example.png +0 -0
package/src/assets/aria-labels-github.png +0 -0
package/src/assets/aria-labels-hacker-news.png +0 -0
package/src/assets/aria-labels-old-reddit.png +0 -0
package/src/assets/cursors/screen-studio/pointer-macos-tahoe-data-url.ts +5 -0
package/src/assets/cursors/screen-studio/pointer-macos-tahoe.svg +18 -0
package/src/cdp-log.ts +4 -1
package/src/cdp-relay.ts +1059 -737
package/src/cdp-session.ts +12 -3
package/src/cdp-types.ts +51 -51
package/src/clean-html.ts +4 -5
package/src/cli.ts +82 -55
package/src/create-logger.ts +5 -3
package/src/debugger-examples-types.ts +4 -1
package/src/debugger.ts +1 -5
package/src/diff-utils.ts +2 -5
package/src/editor-examples.ts +11 -1
package/src/editor.ts +10 -2
package/src/executor.ts +374 -73
package/src/executor.unit.test.ts +48 -1
package/src/extension-connection.test.ts +612 -488
package/src/ffmpeg.ts +769 -0
package/src/ghost-browser.ts +4 -6
package/src/ghost-cursor-client.ts +369 -0
package/src/ghost-cursor.ts +110 -0
package/src/htmlrewrite.test.ts +6 -2
package/src/htmlrewrite.ts +348 -386
package/src/kill-port.ts +1 -3
package/src/locator-selector.test.ts +115 -0
package/src/mcp-client.ts +1 -1
package/src/mcp.ts +21 -15
package/src/on-mouse-action.test.ts +196 -0
package/src/page-markdown.ts +7 -7
package/src/protocol.ts +73 -57
package/src/recording-ghost-cursor.ts +113 -0
package/src/recording-relay.ts +20 -12
package/src/relay-client.ts +85 -18
package/src/relay-core.test.ts +1117 -578
package/src/relay-navigation.test.ts +648 -483
package/src/relay-session.test.ts +984 -929
package/src/relay-state.test.ts +570 -0
package/src/relay-state.ts +497 -0
package/src/resource.md +21 -49
package/src/scoped-fs.ts +9 -3
package/src/screen-recording.test.ts +111 -0
package/src/screen-recording.ts +256 -31
package/src/skill.md +476 -396
package/src/snapshot-tools.test.ts +580 -528
package/src/snapshots/shadcn-ui-accessibility-full.md +8 -8
package/src/snapshots/shadcn-ui-accessibility-interactive.md +8 -8
package/src/start-relay-server.ts +14 -11
package/src/styles-examples.ts +8 -1
package/src/styles.ts +20 -21
package/src/test-declarations.ts +6 -6
package/src/test-utils.ts +104 -91
package/src/utils.ts +2 -1
package/src/wait-for-page-load.ts +6 -1

package/src/kill-port.ts CHANGED Viewed

@@ -148,9 +148,7 @@ export async function getListeningPidsForPort({ port }: { port: number }): Promi
     throw new Error(`Invalid port: ${port}`)
   }
-  return os.platform() === 'win32'
-    ? await getPidsForPortWindows(port)
-    : await getPidsForPortUnix(port)
+  return os.platform() === 'win32' ? await getPidsForPortWindows(port) : await getPidsForPortUnix(port)
 }
 function toError(value: unknown): Error {

package/src/locator-selector.test.ts ADDED Viewed

@@ -0,0 +1,115 @@
+// Tests for Locator.selector() — verifies the raw selector strings returned
+// by various locator creation methods (getByRole, locator, getByText, etc.)
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { chromium, type Page, type Browser } from '@xmorse/playwright-core'
+const HTML = `<!DOCTYPE html>
+<html>
+<body>
+  <div id="main">
+    <button>Submit</button>
+    <button>Cancel</button>
+    <button class="primary">Save</button>
+    <input type="text" placeholder="Enter name" />
+    <input type="email" placeholder="Enter email" />
+    <a href="/about">About Us</a>
+    <h1>Page Title</h1>
+    <p>Some paragraph text</p>
+    <div class="card">
+      <span>Card content</span>
+    </div>
+    <div class="card">
+      <span>Another card</span>
+    </div>
+    <div class="card">
+      <span>Third card</span>
+    </div>
+    <label for="age">Age</label>
+    <input id="age" type="number" />
+    <img alt="Logo" src="/logo.png" />
+    <div data-testid="dashboard">Dashboard</div>
+  </div>
+</body>
+</html>`
+describe('Locator.selector()', () => {
+  let browser: Browser
+  let page: Page
+  beforeAll(async () => {
+    browser = await chromium.launch({ headless: true })
+    const context = await browser.newContext()
+    page = await context.newPage()
+    await page.setContent(HTML)
+  })
+  afterAll(async () => {
+    await browser.close()
+  })
+  it('CSS selectors', () => {
+    expect(page.locator('#main').selector()).toMatchInlineSnapshot(`"#main"`)
+    expect(page.locator('.card').selector()).toMatchInlineSnapshot(`".card"`)
+    expect(page.locator('button').selector()).toMatchInlineSnapshot(`"button"`)
+    expect(page.locator('div.card > span').selector()).toMatchInlineSnapshot(`"div.card > span"`)
+    expect(page.locator('#main .card:first-child').selector()).toMatchInlineSnapshot(`"#main .card:first-child"`)
+  })
+  it('getByRole', () => {
+    expect(page.getByRole('button').selector()).toMatchInlineSnapshot(`"internal:role=button"`)
+    expect(page.getByRole('button', { name: 'Submit' }).selector()).toMatchInlineSnapshot(`"internal:role=button[name="Submit"i]"`)
+    expect(page.getByRole('link').selector()).toMatchInlineSnapshot(`"internal:role=link"`)
+    expect(page.getByRole('heading').selector()).toMatchInlineSnapshot(`"internal:role=heading"`)
+    expect(page.getByRole('textbox').selector()).toMatchInlineSnapshot(`"internal:role=textbox"`)
+  })
+  it('getByText', () => {
+    expect(page.getByText('Submit').selector()).toMatchInlineSnapshot(`"internal:text="Submit"i"`)
+    expect(page.getByText('Some paragraph').selector()).toMatchInlineSnapshot(`"internal:text="Some paragraph"i"`)
+    expect(page.getByText(/card/i).selector()).toMatchInlineSnapshot(`"internal:text=/card/i"`)
+  })
+  it('getByPlaceholder', () => {
+    expect(page.getByPlaceholder('Enter name').selector()).toMatchInlineSnapshot(`"internal:attr=[placeholder="Enter name"i]"`)
+    expect(page.getByPlaceholder('Enter email').selector()).toMatchInlineSnapshot(`"internal:attr=[placeholder="Enter email"i]"`)
+  })
+  it('getByLabel', () => {
+    expect(page.getByLabel('Age').selector()).toMatchInlineSnapshot(`"internal:label="Age"i"`)
+  })
+  it('getByAltText', () => {
+    expect(page.getByAltText('Logo').selector()).toMatchInlineSnapshot(`"internal:attr=[alt="Logo"i]"`)
+  })
+  it('getByTestId', () => {
+    expect(page.getByTestId('dashboard').selector()).toMatchInlineSnapshot(`"internal:testid=[data-testid="dashboard"s]"`)
+  })
+  it('chained locators', () => {
+    expect(page.locator('#main').locator('.card').selector()).toMatchInlineSnapshot(`"#main >> .card"`)
+    expect(page.locator('.card').first().selector()).toMatchInlineSnapshot(`".card >> nth=0"`)
+    expect(page.locator('.card').last().selector()).toMatchInlineSnapshot(`".card >> nth=-1"`)
+    expect(page.locator('.card').nth(1).selector()).toMatchInlineSnapshot(`".card >> nth=1"`)
+  })
+  it('filtered locators', () => {
+    expect(page.locator('button').filter({ hasText: 'Save' }).selector()).toMatchInlineSnapshot(`"button >> internal:has-text="Save"i"`)
+    expect(page.locator('div').filter({ has: page.locator('span') }).selector()).toMatchInlineSnapshot(`"div >> internal:has="span""`)
+    expect(page.locator('button').filter({ hasNotText: 'Cancel' }).selector()).toMatchInlineSnapshot(`"button >> internal:has-not-text="Cancel"i"`)
+  })
+  it('described locators', () => {
+    expect(page.locator('button').describe('main action button').selector()).toMatchInlineSnapshot(`"button >> internal:describe="main action button""`)
+  })
+  it('combined with and/or', () => {
+    expect(
+      page.locator('button').and(page.locator('.primary')).selector(),
+    ).toMatchInlineSnapshot(`"button >> internal:and=".primary""`)
+    expect(
+      page.locator('button').or(page.locator('a')).selector(),
+    ).toMatchInlineSnapshot(`"button >> internal:or="a""`)
+  })
+})

package/src/mcp-client.ts CHANGED Viewed

@@ -17,7 +17,7 @@ export async function createTransport({ args = [], port }: { args?: string[]; po
   stderr: Stream | null
 }> {
   const env: Record<string, string> = {
-    ...process.env as Record<string, string>,
+    ...(process.env as Record<string, string>),
     DEBUG: 'playwriter:mcp:test',
     DEBUG_COLORS: '0',
     DEBUG_HIDE_DATE: '1',

package/src/mcp.ts CHANGED Viewed

@@ -91,12 +91,12 @@ async function getOrCreateExecutor(): Promise<PlaywrightExecutor> {
   if (executor) {
     return executor
   }
   const remote = getRemoteConfig()
   if (!remote) {
     await ensureRelayServerForMcp()
   }
   // Pass config instead of pre-generated URL so executor can generate unique URLs for each connection
   const cdpConfig = remote || { port: RELAY_PORT }
   executor = new PlaywrightExecutor({
@@ -104,7 +104,7 @@ async function getOrCreateExecutor(): Promise<PlaywrightExecutor> {
     logger: mcpLogger,
     cwd: process.cwd(),
   })
   return executor
 }
@@ -198,39 +198,42 @@ server.tool(
       if (!remote) {
         await ensureRelayServerForMcp()
       }
       const exec = await getOrCreateExecutor()
       const result = await exec.execute(code, timeout)
       // Transform executor result to MCP format
       const content: Array<{ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string }> = [
         { type: 'text', text: result.text },
       ]
       for (const image of result.images) {
         content.push({ type: 'image', data: image.data, mimeType: image.mimeType })
       }
       if (result.isError) {
         return { content, isError: true }
       }
       return { content }
     } catch (error: any) {
       const errorStack = error.stack || error.message
-      const isTimeoutError = error instanceof CodeExecutionTimeoutError || error.name === 'TimeoutError'
+      const isTimeoutError =
+        error instanceof CodeExecutionTimeoutError || error?.name === 'TimeoutError' || error?.name === 'AbortError'
       console.error('Error in execute tool:', errorStack)
       if (!isTimeoutError) {
         sendLogToRelayServer('error', 'Error in execute tool:', errorStack)
       }
       const resetHint = isTimeoutError
         ? ''
         : '\n\n[HINT: If this is an internal Playwright error, page/browser closed, or connection issue, call the `reset` tool to reconnect. Do NOT reset for other non-connection non-internal errors.]'
+      // timeout stacks are internal noise (Promise.race / setTimeout); only show the message
+      const errorText = isTimeoutError ? error.message : errorStack
       return {
-        content: [{ type: 'text', text: `Error executing code: ${error.message}\n${errorStack}${resetHint}` }],
+        content: [{ type: 'text', text: `Error executing code: ${errorText}${resetHint}` }],
         isError: true,
       }
     }
@@ -256,13 +259,16 @@ server.tool(
       if (!remote) {
         await ensureRelayServerForMcp()
       }
       const exec = await getOrCreateExecutor()
       const { page, context } = await exec.reset()
       const pagesCount = context.pages().length
       return {
         content: [
-          { type: 'text', text: `Connection reset successfully. ${pagesCount} page(s) available. Current page URL: ${page.url()}` },
+          {
+            type: 'text',
+            text: `Connection reset successfully. ${pagesCount} page(s) available. Current page URL: ${page.url()}`,
+          },
         ],
       }
     } catch (error: any) {

package/src/on-mouse-action.test.ts ADDED Viewed

@@ -0,0 +1,196 @@
+/**
+ * Test for the page.onMouseAction callback added to the playwright fork.
+ * Verifies the callback fires for both explicit page.mouse.* calls
+ * and locator-initiated actions like page.locator().click().
+ */
+import { chromium } from '@xmorse/playwright-core'
+import type { MouseActionEvent, Page } from '@xmorse/playwright-core'
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { getCdpUrl } from './utils.js'
+import { enableGhostCursor, applyGhostCursorMouseAction, disableGhostCursor } from './ghost-cursor.js'
+import {
+  setupTestContext,
+  cleanupTestContext,
+  getExtensionServiceWorker,
+  type TestContext,
+  safeCloseCDPBrowser,
+} from './test-utils.js'
+import './test-declarations.js'
+const TEST_PORT = 19994
+describe('onMouseAction callback', () => {
+  let cleanup: (() => Promise<void>) | null = null
+  let testCtx: TestContext | null = null
+  beforeAll(async () => {
+    testCtx = await setupTestContext({
+      port: TEST_PORT,
+      tempDirPrefix: 'pw-mouse-action-test-',
+      toggleExtension: true,
+    })
+  }, 600000)
+  afterAll(async () => {
+    await cleanupTestContext(testCtx, cleanup)
+    cleanup = null
+    testCtx = null
+  })
+  it('should fire onMouseAction for page.mouse.click()', async () => {
+    const browserContext = testCtx!.browserContext
+    const serviceWorker = await getExtensionServiceWorker(browserContext)
+    const page = await browserContext.newPage()
+    await page.goto('data:text/html,<html><body><button id="btn">Click me</button></body></html>')
+    await page.bringToFront()
+    await serviceWorker.evaluate(async () => {
+      await (globalThis as any).toggleExtensionForActiveTab()
+    })
+    await new Promise((r) => { setTimeout(r, 200) })
+    const directBrowser = await chromium.connectOverCDP(getCdpUrl({ port: TEST_PORT }))
+    const contexts = directBrowser.contexts()
+    const pages = contexts[0].pages()
+    const targetPage = pages.find((p) => p.url().startsWith('data:'))
+    expect(targetPage).toBeDefined()
+    const events: MouseActionEvent[] = []
+    targetPage!.onMouseAction = async (event) => {
+      events.push({ ...event })
+    }
+    await targetPage!.mouse.click(100, 100)
+    // click dispatches: move → down → up
+    const types = events.map((e) => e.type)
+    expect(types).toContain('move')
+    expect(types).toContain('down')
+    expect(types).toContain('up')
+    // All events should have coordinates
+    for (const event of events) {
+      expect(typeof event.x).toBe('number')
+      expect(typeof event.y).toBe('number')
+      expect(typeof event.button).toBe('string')
+    }
+    // The move event should have the target coordinates
+    const moveEvent = events.find((e) => e.type === 'move')!
+    expect(moveEvent.x).toBe(100)
+    expect(moveEvent.y).toBe(100)
+    await safeCloseCDPBrowser(directBrowser)
+  }, 30000)
+  it('should fire onMouseAction for locator.click()', async () => {
+    const browserContext = testCtx!.browserContext
+    const directBrowser = await chromium.connectOverCDP(getCdpUrl({ port: TEST_PORT }))
+    const contexts = directBrowser.contexts()
+    const pages = contexts[0].pages()
+    const targetPage = pages.find((p) => p.url().startsWith('data:'))
+    expect(targetPage).toBeDefined()
+    const events: MouseActionEvent[] = []
+    targetPage!.onMouseAction = async (event) => {
+      events.push({ ...event })
+    }
+    // locator.click() resolves coordinates server-side, then calls server Mouse
+    await targetPage!.locator('#btn').click()
+    const types = events.map((e) => e.type)
+    expect(types).toContain('move')
+    expect(types).toContain('down')
+    expect(types).toContain('up')
+    // The button center should be somewhere reasonable (not 0,0)
+    const moveEvent = events.find((e) => e.type === 'move')!
+    expect(moveEvent.x).toBeGreaterThan(0)
+    expect(moveEvent.y).toBeGreaterThan(0)
+    await safeCloseCDPBrowser(directBrowser)
+  }, 30000)
+  it('should animate ghost cursor from onMouseAction callback', async () => {
+    const browserContext = testCtx!.browserContext
+    const directBrowser = await chromium.connectOverCDP(getCdpUrl({ port: TEST_PORT }))
+    let targetPage: Page | null = null
+    try {
+      const contexts = directBrowser.contexts()
+      const pages = contexts[0].pages()
+      targetPage = pages.find((p) => p.url().startsWith('data:'))!
+      expect(targetPage).toBeDefined()
+      const pageForTest = targetPage
+      await enableGhostCursor({ page: pageForTest })
+      pageForTest.onMouseAction = async (event) => {
+        await applyGhostCursorMouseAction({ page: pageForTest, event })
+      }
+      await pageForTest.mouse.click(140, 120)
+      const cursorState = await pageForTest.evaluate(() => {
+        const cursorElement = document.getElementById('__playwriter_ghost_cursor__')
+        if (!cursorElement) {
+          return { exists: false, transform: '' }
+        }
+        return {
+          exists: true,
+          transform: cursorElement.getAttribute('style') || '',
+        }
+      })
+      expect(cursorState.exists).toBe(true)
+      const translateMatch = cursorState.transform.match(/translate3d\(([-\d.]+)px, ([-\d.]+)px, 0(?:px)?\)/)
+      expect(translateMatch).toBeTruthy()
+      const translateX = Number(translateMatch![1])
+      const translateY = Number(translateMatch![2])
+      // Screen Studio cursor uses a hotspot offset, so CSS position is slightly above/left of click target.
+      expect(translateX).toBeLessThanOrEqual(140)
+      expect(translateY).toBeLessThanOrEqual(120)
+      expect(translateX).toBeGreaterThan(120)
+      expect(translateY).toBeGreaterThan(100)
+      await disableGhostCursor({ page: pageForTest })
+      const hasGhostCursor = await pageForTest.evaluate(() => {
+        return Boolean(document.getElementById('__playwriter_ghost_cursor__'))
+      })
+      expect(hasGhostCursor).toBe(false)
+    } finally {
+      if (targetPage) {
+        targetPage.onMouseAction = null
+        await disableGhostCursor({ page: targetPage })
+      }
+      await safeCloseCDPBrowser(directBrowser)
+    }
+  }, 30000)
+  it('should not fire when onMouseAction is set to null', async () => {
+    const browserContext = testCtx!.browserContext
+    const directBrowser = await chromium.connectOverCDP(getCdpUrl({ port: TEST_PORT }))
+    const contexts = directBrowser.contexts()
+    const pages = contexts[0].pages()
+    const targetPage = pages.find((p) => p.url().startsWith('data:'))
+    expect(targetPage).toBeDefined()
+    const events: MouseActionEvent[] = []
+    targetPage!.onMouseAction = async (event) => {
+      events.push({ ...event })
+    }
+    // Disable callback
+    targetPage!.onMouseAction = null
+    await targetPage!.mouse.click(50, 50)
+    expect(events).toHaveLength(0)
+    await safeCloseCDPBrowser(directBrowser)
+  }, 30000)
+})

package/src/page-markdown.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 /**
  * Extract page content as markdown using Mozilla Readability.
- *
+ *
  * This utility injects the Readability library into the page and extracts
  * the main content, similar to Firefox Reader View.
  */
@@ -65,12 +65,12 @@ function isRegExp(value: unknown): value is RegExp {
 /**
  * Extract page content as markdown using Mozilla Readability.
- *
+ *
  * Injects Readability into the page if not already present, then extracts
  * the main content. Returns plain text content (no HTML).
  */
 export async function getPageMarkdown(options: GetPageMarkdownOptions): Promise<string> {
-  const { page, search, showDiffSinceLastCall = true } = options
+  const { page, search, showDiffSinceLastCall = !search } = options
   // Check if readability is already injected
   const hasReadability = await page.evaluate(() => !!(globalThis as any).__readability)
@@ -81,7 +81,7 @@ export async function getPageMarkdown(options: GetPageMarkdownOptions): Promise<
   }
   // Extract content using Readability
-  const result = await page.evaluate(() => {
+  const result = (await page.evaluate(() => {
     const readability = (globalThis as any).__readability
     if (!readability) {
       throw new Error('Readability not loaded')
@@ -131,11 +131,11 @@ export async function getPageMarkdown(options: GetPageMarkdownOptions): Promise<
       publishedTime: article.publishedTime || null,
       wordCount: (article.textContent || '').split(/\s+/).filter(Boolean).length,
     }
-  }) as PageMarkdownResult & { _notReadable?: boolean }
+  })) as PageMarkdownResult & { _notReadable?: boolean }
   // Format output
   const lines: string[] = []
   if (result.title) {
     lines.push(`# ${result.title}`)
     lines.push('')
@@ -172,7 +172,7 @@ export async function getPageMarkdown(options: GetPageMarkdownOptions): Promise<
   const previousSnapshot = lastMarkdownSnapshots.get(page)
   lastMarkdownSnapshots.set(page, markdown)
-  // Return diff if we have a previous snapshot and diff mode is enabled
+  // Diff defaults off when search is provided, but agent can explicitly enable both
   if (showDiffSinceLastCall && previousSnapshot) {
     const diffResult = createSmartDiff({
       oldContent: previousSnapshot,

package/src/protocol.ts CHANGED Viewed

@@ -2,19 +2,18 @@ import { CDPEventFor, ProtocolMapping } from './cdp-types.js'
 export const VERSION = 1
-type ForwardCDPCommand =
-  {
-    [K in keyof ProtocolMapping.Commands]: {
-      id: number
-      method: 'forwardCDPCommand'
-      params: {
-        method: K
-        sessionId?: string
-        params?: ProtocolMapping.Commands[K]['paramsType'][0]
-        source?: 'playwriter'
-      }
+type ForwardCDPCommand = {
+  [K in keyof ProtocolMapping.Commands]: {
+    id: number
+    method: 'forwardCDPCommand'
+    params: {
+      method: K
+      sessionId?: string
+      params?: ProtocolMapping.Commands[K]['paramsType'][0]
+      source?: 'playwriter'
     }
-  }[keyof ProtocolMapping.Commands]
+  }
+}[keyof ProtocolMapping.Commands]
 export type ExtensionCommandMessage = ForwardCDPCommand
@@ -29,18 +28,17 @@ export type ExtensionResponseMessage = {
  * This produces a discriminated union for narrowing, similar to ForwardCDPCommand,
  * but for forwarded CDP events. Uses CDPEvent to maintain proper type extraction.
  */
-export type ExtensionEventMessage =
-  {
-    [K in keyof ProtocolMapping.Events]: {
-      id?: undefined
-      method: 'forwardCDPEvent'
-      params: {
-        method: CDPEventFor<K>['method']
-        sessionId?: string
-        params?: CDPEventFor<K>['params']
-      }
+export type ExtensionEventMessage = {
+  [K in keyof ProtocolMapping.Events]: {
+    id?: undefined
+    method: 'forwardCDPEvent'
+    params: {
+      method: CDPEventFor<K>['method']
+      sessionId?: string
+      params?: CDPEventFor<K>['params']
     }
-  }[keyof ProtocolMapping.Events]
+  }
+}[keyof ProtocolMapping.Events]
 export type ExtensionLogMessage = {
   id?: undefined
@@ -78,10 +76,17 @@ export type RecordingCancelledMessage = {
   }
 }
-export type ExtensionMessage = ExtensionResponseMessage | ExtensionEventMessage | ExtensionLogMessage | ExtensionPongMessage | RecordingDataMessage | RecordingCancelledMessage
+export type ExtensionMessage =
+  | ExtensionResponseMessage
+  | ExtensionEventMessage
+  | ExtensionLogMessage
+  | ExtensionPongMessage
+  | RecordingDataMessage
+  | RecordingCancelledMessage
 // Recording command messages (MCP -> Extension via relay)
 export type StartRecordingParams = {
+  /** CDP tab session ID (pw-tab-*) to identify which tab to record. */
   sessionId?: string
   frameRate?: number
   audio?: boolean
@@ -95,14 +100,17 @@ export type StartRecordingBody = StartRecordingParams & {
 }
 export type StopRecordingParams = {
+  /** CDP tab session ID (pw-tab-*) to identify which tab to stop recording. */
   sessionId?: string
 }
 export type IsRecordingParams = {
+  /** CDP tab session ID (pw-tab-*) to identify which tab to check. */
   sessionId?: string
 }
 export type CancelRecordingParams = {
+  /** CDP tab session ID (pw-tab-*) to identify which tab to cancel. */
   sessionId?: string
 }
@@ -137,36 +145,42 @@ export type RecordingCommandMessage =
   | CancelRecordingMessage
 // Recording result types
-export type StartRecordingResult = {
-  success: true
-  tabId: number
-  startedAt: number
-} | {
-  success: false
-  error: string
-}
+export type StartRecordingResult =
+  | {
+      success: true
+      tabId: number
+      startedAt: number
+    }
+  | {
+      success: false
+      error: string
+    }
 /** Result from extension - doesn't include path/size since relay writes the file */
-export type ExtensionStopRecordingResult = {
-  success: true
-  tabId: number
-  duration: number
-} | {
-  success: false
-  error: string
-}
+export type ExtensionStopRecordingResult =
+  | {
+      success: true
+      tabId: number
+      duration: number
+    }
+  | {
+      success: false
+      error: string
+    }
 /** Final result from relay - includes path/size after file is written */
-export type StopRecordingResult = {
-  success: true
-  tabId: number
-  duration: number
-  path: string
-  size: number
-} | {
-  success: false
-  error: string
-}
+export type StopRecordingResult =
+  | {
+      success: true
+      tabId: number
+      duration: number
+      path: string
+      size: number
+    }
+  | {
+      success: false
+      error: string
+    }
 export type IsRecordingResult = {
   isRecording: boolean
@@ -193,10 +207,12 @@ export type GhostBrowserCommandMessage = {
   }
 }
-export type GhostBrowserCommandResult = {
-  success: true
-  result: unknown
-} | {
-  success: false
-  error: string
-}
+export type GhostBrowserCommandResult =
+  | {
+      success: true
+      result: unknown
+    }
+  | {
+      success: false
+      error: string
+    }