playwriter 0.0.89 → 0.0.103

package/src/mcp.ts

@@ -17,6 +17,8 @@ import dedent from 'string-dedent'
 import { LOG_FILE_PATH, VERSION, parseRelayHost } from './utils.js'
 import { ensureRelayServer, RELAY_PORT } from './relay-client.js'
 import { PlaywrightExecutor, CodeExecutionTimeoutError } from './executor.js'
+import { discoverChromeInstances, resolveDirectInput, appendSessionToWsUrl } from './chrome-discovery.js'
+import crypto from 'node:crypto'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -87,11 +89,57 @@ async function ensureRelayServerForMcp(): Promise<void> {
   await ensureRelayServer({ logger: mcpLogger })
 }
 
+/**
+ * Resolve direct CDP config from PLAYWRITER_DIRECT env var.
+ * - "auto" / "1" / "true": auto-discover Chrome on default port 9222
+ * - "ws://..." / "wss://...": use explicit WebSocket endpoint
+ * - "host:port": resolve to ws:// URL via HTTP probe + DevToolsActivePort fallback
+ */
+async function getDirectCdpConfig(): Promise<{ directCdpUrl: string } | null> {
+  const directEnv = process.env.PLAYWRITER_DIRECT
+  if (!directEnv) {
+    return null
+  }
+
+  // Auto-discover: check default port 9222
+  if (directEnv === '1') {
+    const instances = await discoverChromeInstances()
+    if (instances.length === 0) {
+      throw new Error(
+        'PLAYWRITER_DIRECT is set but no Chrome found on port 9222. ' +
+          'Enable debugging at chrome://inspect/#remote-debugging or launch with --remote-debugging-port=9222.',
+      )
+    }
+    const sessionId = crypto.randomUUID()
+    const wsUrl = appendSessionToWsUrl(instances[0].wsUrl, sessionId)
+    mcpLog(`Direct CDP: using ${instances[0].browser} on port ${instances[0].port}`)
+    return { directCdpUrl: wsUrl }
+  }
+
+  // ws://, wss://, or host:port — resolveDirectInput handles all three
+  const resolved = await resolveDirectInput(directEnv)
+  const sessionId = crypto.randomUUID()
+  const directCdpUrl = appendSessionToWsUrl(resolved, sessionId)
+  mcpLog(`Direct CDP: resolved ${directEnv} → ${directCdpUrl}`)
+  return { directCdpUrl }
+}
+
 async function getOrCreateExecutor(): Promise<PlaywrightExecutor> {
   if (executor) {
     return executor
   }
 
+  // Direct CDP mode takes priority over relay/remote
+  const directConfig = await getDirectCdpConfig()
+  if (directConfig) {
+    executor = new PlaywrightExecutor({
+      cdpConfig: directConfig,
+      logger: mcpLogger,
+      cwd: process.cwd(),
+    })
+    return executor
+  }
+
   const remote = getRemoteConfig()
   if (!remote) {
     await ensureRelayServerForMcp()
@@ -194,17 +242,31 @@ server.tool(
   async ({ code, timeout }) => {
     try {
       // Check relay server on every execute to auto-recover from crashes
-      const remote = getRemoteConfig()
-      if (!remote) {
-        await ensureRelayServerForMcp()
+      // (skip in direct CDP mode — no relay involved)
+      if (!process.env.PLAYWRITER_DIRECT) {
+        const remote = getRemoteConfig()
+        if (!remote) {
+          await ensureRelayServerForMcp()
+        }
       }
 
       const exec = await getOrCreateExecutor()
       const result = await exec.execute(code, timeout)
 
       // Transform executor result to MCP format
+      // Append screenshot metadata to text for MCP (image is included inline as content)
+      const MAX_TEXT = 10000
+      let text = result.text
+      for (const s of result.screenshots) {
+        text += `\nScreenshot saved to: ${s.path} (image included below, ${s.labelCount} labels)\n`
+        text += `Accessibility snapshot:\n${s.snapshot}\n`
+      }
+      if (text.length > MAX_TEXT) {
+        text = text.slice(0, MAX_TEXT) + '\n\n[Truncated]'
+      }
+
       const content: Array<{ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string }> = [
-        { type: 'text', text: result.text },
+        { type: 'text', text },
       ]
 
       for (const image of result.images) {
@@ -255,9 +317,12 @@ server.tool(
   async () => {
     try {
       // Check relay server to auto-recover from crashes
-      const remote = getRemoteConfig()
-      if (!remote) {
-        await ensureRelayServerForMcp()
+      // (skip in direct CDP mode — no relay involved)
+      if (!process.env.PLAYWRITER_DIRECT) {
+        const remote = getRemoteConfig()
+        if (!remote) {
+          await ensureRelayServerForMcp()
+        }
       }
 
       const exec = await getOrCreateExecutor()
@@ -288,12 +353,17 @@ export async function startMcp(options: { host?: string; token?: string } = {})
     process.env.PLAYWRITER_TOKEN = options.token
   }
 
-  const remote = getRemoteConfig()
-  if (!remote) {
-    await ensureRelayServerForMcp()
+  // In direct CDP mode (PLAYWRITER_DIRECT env var), no relay server needed
+  if (process.env.PLAYWRITER_DIRECT) {
+    mcpLog(`Using direct CDP connection: ${process.env.PLAYWRITER_DIRECT}`)
   } else {
-    mcpLog(`Using remote CDP relay server: ${remote.host}`)
-    await checkRemoteServer(remote)
+    const remote = getRemoteConfig()
+    if (!remote) {
+      await ensureRelayServerForMcp()
+    } else {
+      mcpLog(`Using remote CDP relay server: ${remote.host}`)
+      await checkRemoteServer(remote)
+    }
   }
 
   const transport = new StdioServerTransport()

package/src/package-paths.ts

@@ -0,0 +1,36 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+export function getInstalledPlaywriterPackageDir(): string {
+  const localPackageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+  const localPackageJsonPath = path.join(localPackageDir, 'package.json')
+  if (fs.existsSync(localPackageJsonPath)) {
+    return localPackageDir
+  }
+
+  const packageJsonPath = require.resolve('playwriter/package.json')
+  return path.dirname(packageJsonPath)
+}
+
+export function getBundledExtensionPath(): string {
+  const packageDir = getInstalledPlaywriterPackageDir()
+  const candidates = [
+    path.join(packageDir, 'dist', 'extension'),
+    path.join(packageDir, '..', 'extension', 'dist'),
+  ]
+
+  for (const extensionPath of candidates) {
+    const manifestPath = path.join(extensionPath, 'manifest.json')
+    if (fs.existsSync(manifestPath)) {
+      return extensionPath
+    }
+  }
+
+  throw new Error(
+    `Bundled Playwriter extension not found under ${packageDir}. Rebuild or reinstall the playwriter package.`,
+  )
+}

package/src/relay-core.test.ts

@@ -264,11 +264,11 @@ describe('Relay Core Tests', () => {
 
     expect(summary).toMatchInlineSnapshot(`
       {
-        "hasBrowserDownloadProgress": false,
-        "hasBrowserDownloadWillBegin": false,
+        "hasBrowserDownloadProgress": true,
+        "hasBrowserDownloadWillBegin": true,
         "hasBrowserSetDownloadBehavior": true,
-        "hasPageDownloadProgress": false,
-        "hasPageDownloadWillBegin": false,
+        "hasPageDownloadProgress": true,
+        "hasPageDownloadWillBegin": true,
         "hasPageSetDownloadBehavior": true,
       }
     `)
@@ -475,11 +475,18 @@ describe('Relay Core Tests', () => {
       name: 'hacker-news',
       url: 'https://news.ycombinator.com/item?id=1',
       expectedContent: ['role=link', 'Hacker News'],
+      waitForCode: js`
+        await state.page.locator('a[href="news"]').first().waitFor({ timeout: 10000 });
+        await state.page.locator('a.hnuser').first().waitFor({ timeout: 10000 });
+      `,
     },
     {
       name: 'shadcn-ui',
       url: 'https://ui.shadcn.com/',
       expectedContent: ['shadcn'],
+      waitForCode: js`
+        await state.page.locator('text=shadcn/ui').first().waitFor({ timeout: 10000 });
+      `,
     },
   ]
 
@@ -502,7 +509,10 @@ describe('Relay Core Tests', () => {
         name: 'execute',
         arguments: {
           code: js`
+              // External pages can expose a partial AX tree right after domcontentloaded,
+              // so wait for stable page-specific content before snapshotting.
               await state.page.goto('${testCase.url}', { waitUntil: 'domcontentloaded' });
+              ${testCase.waitForCode}
               const snap = await snapshot({ page: state.page, showDiffSinceLastCall: false, interactiveOnly: true });
               return snap;
             `,

package/src/relay-navigation.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest'
 import { chromium, type Page } from '@xmorse/playwright-core'
 import WebSocket from 'ws'
+import path from 'node:path'
 import { getCdpUrl } from './utils.js'
 import {
   setupTestContext,
@@ -13,12 +14,18 @@ import {
 import './test-declarations.js'
 
 const TEST_PORT = 19992
+const FIXTURE_EXTENSION_PATH = path.resolve('../extension/test-fixtures/fixture-extension')
 
 describe('Relay Navigation Tests', () => {
   let testCtx: TestContext | null = null
 
   beforeAll(async () => {
-    testCtx = await setupTestContext({ port: TEST_PORT, tempDirPrefix: 'pw-nav-test-', toggleExtension: true })
+    testCtx = await setupTestContext({
+      port: TEST_PORT,
+      tempDirPrefix: 'pw-nav-test-',
+      toggleExtension: true,
+      additionalExtensions: [FIXTURE_EXTENSION_PATH],
+    })
   }, 600000)
 
   afterAll(async () => {
@@ -757,4 +764,102 @@ describe('Relay Navigation Tests', () => {
       await server.close()
     }
   }, 30000)
+
+  it('should not crash when page has chrome-extension:// iframe from another extension', async () => {
+    // Reproduces https://github.com/remorses/playwriter/issues/18
+    // Extensions like LastPass, SurfingKeys inject chrome-extension:// iframes into every page.
+    // When playwriter attaches the debugger and Target.setAutoAttach is active, Chrome
+    // auto-attaches to these restricted iframe targets. Without filtering, the relay tries
+    // to send Runtime.runIfWaitingForDebugger to the restricted child session, which Chrome
+    // blocks with "Cannot access a chrome-extension:// URL of a different extension",
+    // causing the entire debugger to detach.
+
+    const browserContext = getBrowserContext()
+    const serviceWorker = await getExtensionServiceWorker(browserContext)
+
+    // Discover the fixture extension's ID from its service worker
+    const playwriterExtId = serviceWorker.url().match(/chrome-extension:\/\/([^/]+)/)?.[1]
+    expect(playwriterExtId).toBeTruthy()
+
+    let fixtureExtId: string | undefined
+    for (let i = 0; i < 50; i++) {
+      const allSws = browserContext.serviceWorkers()
+      const fixtureSw = allSws.find((sw) => {
+        const id = sw.url().match(/chrome-extension:\/\/([^/]+)/)?.[1]
+        return id && id !== playwriterExtId
+      })
+      if (fixtureSw) {
+        fixtureExtId = fixtureSw.url().match(/chrome-extension:\/\/([^/]+)/)?.[1]
+        break
+      }
+      await new Promise((r) => {
+        setTimeout(r, 100)
+      })
+    }
+    expect(fixtureExtId).toBeTruthy()
+    console.log('Fixture extension ID:', fixtureExtId)
+
+    // Create a page that embeds the fixture extension's page as an iframe,
+    // reproducing what extensions like SurfingKeys/LastPass do.
+    const server = await createSimpleServer({
+      routes: {
+        '/': `<!doctype html><html><body>
+          <h1>Main page</h1>
+          <iframe src="chrome-extension://${fixtureExtId}/page.html" id="ext-iframe"></iframe>
+        </body></html>`,
+      },
+    })
+
+    const page = await browserContext.newPage()
+    try {
+      await page.goto(server.baseUrl, { waitUntil: 'domcontentloaded' })
+      await page.bringToFront()
+
+      // Enable playwriter on this page — this must NOT crash the debugger
+      await withTimeout({
+        promise: serviceWorker.evaluate(async () => {
+          await globalThis.toggleExtensionForActiveTab()
+        }),
+        timeoutMs: 5000,
+        errorMessage: 'Timed out toggling extension on page with chrome-extension:// iframe',
+      })
+
+      // Give time for any async errors (Target.attachedToTarget for the iframe) to surface
+      await new Promise((r) => {
+        setTimeout(r, 1500)
+      })
+
+      // Verify the extension is still connected by connecting over CDP and interacting
+      const browser = await withTimeout({
+        promise: chromium.connectOverCDP(getCdpUrl({ port: TEST_PORT })),
+        timeoutMs: 5000,
+        errorMessage: 'Timed out connecting over CDP — extension likely crashed',
+      })
+      const context = browser.contexts()[0]
+      const cdpPage = context.pages().find((p) => p.url().startsWith(server.baseUrl))
+      expect(cdpPage).toBeDefined()
+
+      // Verify we can execute JS on the page (proves the debugger session is alive)
+      const title = await cdpPage!.evaluate(() => document.querySelector('h1')?.textContent)
+      expect(title).toBe('Main page')
+
+      // Verify the chrome-extension:// iframe did NOT get exposed as a frame
+      // (it should be filtered out as a restricted target)
+      const frames = cdpPage!.frames()
+      const extFrame = frames.find((f) => f.url().startsWith('chrome-extension://'))
+      expect(extFrame).toBeUndefined()
+
+      await browser.close()
+    } finally {
+      // Toggle off to clean up
+      await page.bringToFront()
+      await serviceWorker
+        .evaluate(async () => {
+          await globalThis.toggleExtensionForActiveTab()
+        })
+        .catch(() => {})
+      await page.close()
+      await server.close()
+    }
+  }, 30000)
 })

package/src/scoped-fs.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Regression tests for session-scoped filesystem resolution and session cwd reporting.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { describe, expect, test } from 'vitest'
+import { ExecutorManager, type SessionMetadata } from './executor.js'
+import { createScopedFS } from './scoped-fs.js'
+
+function createTempDir(prefix: string): string {
+  const tempRoot = path.join(process.cwd(), 'tmp')
+  fs.mkdirSync(tempRoot, { recursive: true })
+  return fs.mkdtempSync(path.join(tempRoot, prefix))
+}
+
+describe('ScopedFS', () => {
+  test('resolves relative paths from the session cwd instead of the relay cwd', () => {
+    const sessionDir = createTempDir('scoped-fs-session-')
+    const relayDir = createTempDir('scoped-fs-relay-')
+    const originalCwd = process.cwd()
+
+    try {
+      process.chdir(relayDir)
+
+      const scopedFs = createScopedFS([sessionDir], sessionDir)
+      scopedFs.writeFileSync('note.txt', 'hello from session')
+
+      expect(fs.readFileSync(path.join(sessionDir, 'note.txt'), 'utf-8')).toBe('hello from session')
+      expect(fs.existsSync(path.join(relayDir, 'note.txt'))).toBe(false)
+    } finally {
+      process.chdir(originalCwd)
+      fs.rmSync(sessionDir, { recursive: true, force: true })
+      fs.rmSync(relayDir, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('ExecutorManager.listSessions', () => {
+  test('includes the resolved cwd for each session', () => {
+    const sessionDir = createTempDir('executor-session-')
+    const sessionMetadata: SessionMetadata = {
+      extensionId: 'profile:test',
+      browser: 'Chrome',
+      profile: { email: 'test@example.com', id: 'profile-1' },
+    }
+
+    try {
+      const manager = new ExecutorManager({
+        cdpConfig: { port: 19988 },
+        logger: {
+          log: () => {},
+          error: () => {},
+        },
+      })
+
+      manager.getExecutor({
+        sessionId: '7',
+        cwd: sessionDir,
+        sessionMetadata,
+      })
+
+      expect(manager.listSessions()).toEqual([
+        {
+          id: '7',
+          stateKeys: [],
+          extensionId: 'profile:test',
+          browser: 'Chrome',
+          profile: { email: 'test@example.com', id: 'profile-1' },
+          cwd: sessionDir,
+        },
+      ])
+    } finally {
+      fs.rmSync(sessionDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/scoped-fs.ts

@@ -7,7 +7,7 @@ import os from 'node:os'
  * Any attempt to access files outside the allowed directories will throw an EPERM error.
  *
  * By default, allows access to:
- * - Current working directory (process.cwd())
+ * - The base directory captured when the sandbox is created
  * - /tmp
  * - os.tmpdir()
  *
@@ -15,10 +15,13 @@ import os from 'node:os'
  */
 export class ScopedFS {
   private allowedDirs: string[]
+  private baseDir: string
 
-  constructor(allowedDirs?: string[]) {
-    // Default allowed directories: cwd, /tmp, os.tmpdir()
-    const defaultDirs = [process.cwd(), '/tmp', os.tmpdir()]
+  constructor(allowedDirs?: string[], baseDir?: string) {
+    this.baseDir = path.resolve(baseDir || process.cwd())
+
+    // Default allowed directories: session cwd, /tmp, os.tmpdir()
+    const defaultDirs = [this.baseDir, '/tmp', os.tmpdir()]
 
     // Use provided dirs or defaults, resolve all to absolute paths
     const dirs = allowedDirs ?? defaultDirs
@@ -40,8 +43,8 @@ export class ScopedFS {
    */
   private resolvePath(filePath: string): string {
     // If it's an absolute path, use it directly
-    // If it's relative, resolve from cwd
-    const resolved = path.resolve(filePath)
+    // If it's relative, resolve from the session cwd captured when the sandbox was created.
+    const resolved = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(this.baseDir, filePath)
 
     if (!this.isPathAllowed(resolved)) {
       const error = new Error(
@@ -410,8 +413,8 @@ export class ScopedFS {
 
 /**
  * Create a scoped fs instance with allowed directories.
- * Defaults to cwd, /tmp, and os.tmpdir() if no directories specified.
+ * Defaults to the captured base directory, /tmp, and os.tmpdir() if no directories specified.
  */
-export function createScopedFS(allowedDirs?: string[]): ScopedFS {
-  return new ScopedFS(allowedDirs)
+export function createScopedFS(allowedDirs?: string[], baseDir?: string): ScopedFS {
+  return new ScopedFS(allowedDirs, baseDir)
 }

package/src/screen-recording.ts

@@ -9,37 +9,23 @@
 import os from 'node:os'
 import path from 'node:path'
 import type { BrowserContext, Page } from '@xmorse/playwright-core'
+import { shouldUseHeadlessByDefault } from './browser-config.js'
 import type {
   StartRecordingResult,
   StopRecordingResult,
   IsRecordingResult,
   CancelRecordingResult,
 } from './protocol.js'
-import { EXTENSION_IDS } from './utils.js'
 import { RecordingGhostCursorController } from './recording-ghost-cursor.js'
 
 /**
- * Generate a shell command to quit and restart Chrome with flags that allow automatic tab capture.
- * This enables screen recording without user interaction (clicking extension icon).
- *
- * Required flags:
- * - --allowlisted-extension-id=<id> - grants the extension special privileges (one per extension)
- * - --auto-accept-this-tab-capture - auto-accepts tab capture permission requests
+ * Generate a CLI command that starts a managed Playwriter browser with the
+ * bundled extension preloaded. This enables screen recording without a manual
+ * extension click on fresh automation sessions.
  */
 export function getChromeRestartCommand(): string {
-  const platform = os.platform()
-  const extensionFlags = EXTENSION_IDS.map((id) => `--allowlisted-extension-id=${id}`).join(' ')
-  // --profile-directory=Default skips the profile picker on startup, preventing Chrome from hanging
-  const flags = `${extensionFlags} --auto-accept-this-tab-capture --profile-directory=Default`
-
-  if (platform === 'darwin') {
-    return `osascript -e 'quit app "Google Chrome"' && sleep 1 && open -a "Google Chrome" --args ${flags}`
-  }
-  if (platform === 'win32') {
-    return `taskkill /IM chrome.exe /F & timeout /t 1 & start chrome.exe ${flags}`
-  }
-  // Linux
-  return `pkill chrome; sleep 1; google-chrome ${flags}`
+  const headlessFlag = shouldUseHeadlessByDefault({ platform: os.platform() }) ? ' --headless' : ''
+  return `playwriter browser start${headlessFlag}`
 }
 
 const DEFAULT_ASPECT_RATIO = { width: 16, height: 9 }
@@ -331,8 +317,7 @@ export async function startRecording(options: StartRecordingOptions): Promise<Re
       const restartCmd = getChromeRestartCommand()
       throw new Error(
         `Failed to start recording: ${errorMsg}\n\n` +
-          `For automated recording, Chrome must be restarted with special flags.\n` +
-          `WARNING: This will close all Chrome windows. Save your work first!\n\n` +
+          `For automated recording, start a managed Playwriter browser with the bundled extension loaded:\n\n` +
           `  ${restartCmd}\n\n` +
           `Or click the Playwriter extension icon on the tab once to grant permission.`,
       )

package/src/skill.md

@@ -44,6 +44,34 @@ Reset a session if the browser connection is stale or broken:
 playwriter session reset <sessionId>
 ```
 
+### Direct CDP connection (--direct)
+
+Only use `--direct` when the user explicitly asks for it. This mode requires the user to accept a debugging approval dialog in Chrome, so it cannot be used autonomously.
+
+`--direct` connects to Chrome's DevTools Protocol without the extension. Unlike extension mode, it gives access to **all existing pages** in the browser — no need to enable per tab. Works with any Chromium browser (Chrome, Brave, Arc, Edge, etc.).
+
+The user must first enable debugging in Chrome:
+- Open `chrome://inspect/#remote-debugging` in Chrome, or
+- Launch Chrome with `chrome --remote-debugging-port=9222`
+
+Then create a session:
+
+```bash
+playwriter session new --direct
+```
+
+By default, `context` is bound to the first Chrome profile. If the user has multiple profiles open, use `browser.contexts()` to access other profiles' pages and cookies:
+
+```js
+const contexts = browser.contexts()
+// contexts[0] = first profile, contexts[1] = second profile, etc.
+const otherProfilePage = contexts[1].pages()[0]
+```
+
+`browser.contexts()` only makes sense when using `--direct`. in extension mode there is just one context for each session.
+
+**Limitations:** screen recording (`recording.start/stop`) is unavailable in direct mode.
+
 ### Execute code
 
 ```bash
@@ -758,6 +786,8 @@ await editor.edit({ url: matches[0].url, oldString: 'DEBUG = false', newString:
 
 **screenshotWithAccessibilityLabels** - take a screenshot with Vimium-style visual labels overlaid on interactive elements. Shows labels, captures screenshot, then removes labels. The image and accessibility snapshot are automatically included in the response. Can be called multiple times to capture multiple screenshots. Use a timeout of **20 seconds** for complex pages.
 
+This is only for **finding interactive elements** on the page. To share a screenshot with the user or save an image, use `page.screenshot()` + `resizeImageForAgent()` instead (see "taking screenshots" section below).
+
 Prefer this for pages with grids, image galleries, maps, or complex visual layouts where spatial position matters. For simple text-heavy pages, `snapshot` with search is faster and uses fewer tokens.
 
 ```js
@@ -775,7 +805,7 @@ await screenshotWithAccessibilityLabels({ page: state.page })
 
 Labels are color-coded: yellow=links, orange=buttons, coral=inputs, pink=checkboxes, peach=sliders, salmon=menus, amber=tabs.
 
-**resizeImage** - shrink an image in-place so it consumes fewer tokens when read back into context. `await resizeImage({ input: './screenshot.png' })`. Also accepts `width`, `height`, `maxDimension`, `quality`, `output`.
+**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`.
 
 **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`).
 
@@ -844,7 +874,7 @@ await state.page.screenshot({ path: 'shot.png', scale: 'css' })
 If you want to read back the image file into context, resize it first so it consumes fewer tokens:
 
 ```js
-await resizeImage({ input: './shot.png' })
+await resizeImageForAgent({ input: './shot.png' })
 ```
 
 ## page.evaluate

package/src/snapshot-tools.test.ts

@@ -986,14 +986,13 @@ describe('Snapshot & Screenshot Tests', () => {
     const textContent = content.find((c) => c.type === 'text')
     expect(textContent).toBeDefined()
     expect(textContent.text).toContain('Screenshot saved to:')
-    expect(textContent.text).toContain('.jpg')
-    expect(textContent.text).toContain('Labels shown:')
+    expect(textContent.text).toContain('image included below')
     expect(textContent.text).toContain('Accessibility snapshot:')
     expect(textContent.text).toContain('Submit Form')
 
     const imageContent = content.find((c) => c.type === 'image')
     expect(imageContent).toBeDefined()
-    expect(imageContent.mimeType).toBe('image/jpeg')
+    expect(imageContent.mimeType).toBe('image/png')
     expect(imageContent.data).toBeDefined()
     expect(imageContent.data.length).toBeGreaterThan(100)
 
@@ -1009,7 +1008,7 @@ describe('Snapshot & Screenshot Tests', () => {
     console.log('Screenshot dimensions:', dimensions.width, 'x', dimensions.height)
     console.log('Window viewport:', viewport)
 
-    expect(dimensions.type).toBe('jpg')
+    expect(dimensions.type).toBe('png')
     expect(dimensions.width).toBeGreaterThan(0)
     expect(dimensions.height).toBeGreaterThan(0)