playwriter 0.0.63 → 0.0.89

package/src/cdp-session.ts

@@ -14,9 +14,15 @@ export interface ICDPSession {
     sessionId?: string | null,
   ): Promise<ProtocolMapping.Commands[K]['returnType']>
 
-  on<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): unknown
+  on<K extends keyof ProtocolMapping.Events>(
+    event: K,
+    callback: (params: ProtocolMapping.Events[K][0]) => void,
+  ): unknown
 
-  off<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): unknown
+  off<K extends keyof ProtocolMapping.Events>(
+    event: K,
+    callback: (params: ProtocolMapping.Events[K][0]) => void,
+  ): unknown
 
   detach(): Promise<void>
   getSessionId?(): string | null
@@ -46,7 +52,10 @@ export class PlaywrightCDPSessionAdapter implements ICDPSession {
     return this
   }
 
-  off<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): this {
+  off<K extends keyof ProtocolMapping.Events>(
+    event: K,
+    callback: (params: ProtocolMapping.Events[K][0]) => void,
+  ): this {
     this._playwrightSession.off(event as never, callback as never)
     return this
   }

package/src/cdp-types.ts

@@ -1,55 +1,55 @@
-import type { Protocol } from 'devtools-protocol';
-import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
+import type { Protocol } from 'devtools-protocol'
+import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js'
 
-export type CDPCommandSource = 'playwriter';
+export type CDPCommandSource = 'playwriter'
 
 export type CDPCommandFor<T extends keyof ProtocolMapping.Commands> = {
-  id: number;
-  sessionId?: string;
-  method: T;
-  params?: ProtocolMapping.Commands[T]['paramsType'][0];
-  source?: CDPCommandSource;
-};
+  id: number
+  sessionId?: string
+  method: T
+  params?: ProtocolMapping.Commands[T]['paramsType'][0]
+  source?: CDPCommandSource
+}
 
 export type CDPCommand = {
-  [K in keyof ProtocolMapping.Commands]: CDPCommandFor<K>;
-}[keyof ProtocolMapping.Commands];
+  [K in keyof ProtocolMapping.Commands]: CDPCommandFor<K>
+}[keyof ProtocolMapping.Commands]
 
 export type CDPResponseFor<T extends keyof ProtocolMapping.Commands> = {
-  id: number;
-  sessionId?: string;
-  result?: ProtocolMapping.Commands[T]['returnType'];
-  error?: { code?: number; message: string };
-};
+  id: number
+  sessionId?: string
+  result?: ProtocolMapping.Commands[T]['returnType']
+  error?: { code?: number; message: string }
+}
 
 export type CDPResponse = {
-  [K in keyof ProtocolMapping.Commands]: CDPResponseFor<K>;
-}[keyof ProtocolMapping.Commands];
+  [K in keyof ProtocolMapping.Commands]: CDPResponseFor<K>
+}[keyof ProtocolMapping.Commands]
 
 export type CDPEventFor<T extends keyof ProtocolMapping.Events> = {
-  method: T;
-  sessionId?: string;
-  params?: ProtocolMapping.Events[T][0];
-};
+  method: T
+  sessionId?: string
+  params?: ProtocolMapping.Events[T][0]
+}
 
 export type CDPEvent = {
-  [K in keyof ProtocolMapping.Events]: CDPEventFor<K>;
-}[keyof ProtocolMapping.Events];
+  [K in keyof ProtocolMapping.Events]: CDPEventFor<K>
+}[keyof ProtocolMapping.Events]
 
 export type CDPResponseBase = {
-  id: number;
-  sessionId?: string;
-  result?: unknown;
-  error?: { code?: number; message: string };
-};
+  id: number
+  sessionId?: string
+  result?: unknown
+  error?: { code?: number; message: string }
+}
 
 export type CDPEventBase = {
-  method: string;
-  sessionId?: string;
-  params?: unknown;
-};
+  method: string
+  sessionId?: string
+  params?: unknown
+}
 
-export type CDPMessage = CDPCommand | CDPResponse | CDPEvent;
+export type CDPMessage = CDPCommand | CDPResponse | CDPEvent
 
 export type RelayServerEvents = {
   'cdp:command': (data: { clientId: string; command: CDPCommand }) => void
@@ -57,14 +57,14 @@ export type RelayServerEvents = {
   'cdp:response': (data: { clientId: string; response: CDPResponseBase; command: CDPCommand }) => void
 }
 
-export { Protocol, ProtocolMapping };
+export { Protocol, ProtocolMapping }
 
 // types tests. to see if types are right with some simple examples
 if (false as any) {
   const browserVersionCommand = {
     id: 1,
     method: 'Browser.getVersion',
-  } satisfies CDPCommand;
+  } satisfies CDPCommand
 
   const browserVersionResponse = {
     id: 1,
@@ -74,8 +74,8 @@ if (false as any) {
       revision: '123',
       userAgent: 'Mozilla/5.0',
       jsVersion: 'V8',
-    }
-  } satisfies CDPResponse;
+    },
+  } satisfies CDPResponse
 
   const targetAttachCommand = {
     id: 2,
@@ -83,13 +83,13 @@ if (false as any) {
     params: {
       autoAttach: true,
       waitForDebuggerOnStart: false,
-    }
-  } satisfies CDPCommand;
+    },
+  } satisfies CDPCommand
 
   const targetAttachResponse = {
     id: 2,
     result: undefined,
-  } satisfies CDPResponse;
+  } satisfies CDPResponse
 
   const attachedToTargetEvent = {
     method: 'Target.attachedToTarget',
@@ -104,8 +104,8 @@ if (false as any) {
         canAccessOpener: false,
       },
       waitingForDebugger: false,
-    }
-  } satisfies CDPEvent;
+    },
+  } satisfies CDPEvent
 
   const consoleMessageEvent = {
     method: 'Runtime.consoleAPICalled',
@@ -114,23 +114,23 @@ if (false as any) {
       args: [],
       executionContextId: 1,
       timestamp: 123456789,
-    }
-  } satisfies CDPEvent;
+    },
+  } satisfies CDPEvent
 
   const pageNavigateCommand = {
     id: 3,
     method: 'Page.navigate',
     params: {
       url: 'https://example.com',
-    }
-  } satisfies CDPCommand;
+    },
+  } satisfies CDPCommand
 
   const pageNavigateResponse = {
     id: 3,
     result: {
       frameId: 'frame-1',
-    }
-  } satisfies CDPResponse;
+    },
+  } satisfies CDPResponse
 
   const networkRequestEvent = {
     method: 'Network.requestWillBeSent',
@@ -153,6 +153,6 @@ if (false as any) {
       },
       redirectHasExtraInfo: false,
       type: 'XHR',
-    }
-  } satisfies CDPEvent;
+    },
+  } satisfies CDPEvent
 }

package/src/clean-html.ts

@@ -26,17 +26,16 @@ function isRegExp(value: any): value is RegExp {
 
 function getSnapshotKey(locator: Locator | Page): string {
   if (isPage(locator)) {
-    return '__page__'
+    return 'page'
   }
-  // For locators, use a string representation
-  return (locator as any)._selector || '__locator__'
+  return `locator:${locator.selector()}`
 }
 
 export async function getCleanHTML(options: GetCleanHTMLOptions): Promise<string> {
   const {
     locator,
     search,
-    showDiffSinceLastCall = true,
+    showDiffSinceLastCall = !search,
     includeStyles = false,
     maxAttrLen = 200,
     maxContentLen = 500,
@@ -76,7 +75,7 @@ export async function getCleanHTML(options: GetCleanHTMLOptions): Promise<string
   const previousSnapshot = pageSnapshots.get(snapshotKey)
   pageSnapshots.set(snapshotKey, htmlStr)
 
-  // 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/cli.ts

@@ -5,6 +5,7 @@ import path from 'node:path'
 import util from 'node:util'
 import { fileURLToPath } from 'node:url'
 import { cac } from '@xmorse/cac'
+import pc from 'picocolors'
 
 // Prevent Buffers from dumping hex bytes in util.inspect output.
 Buffer.prototype[util.inspect.custom] = function () {
@@ -12,7 +13,14 @@ Buffer.prototype[util.inspect.custom] = function () {
 }
 import { killPortProcess } from './kill-port.js'
 import { VERSION, LOG_FILE_PATH, LOG_CDP_FILE_PATH, parseRelayHost } from './utils.js'
-import { ensureRelayServer, RELAY_PORT, waitForExtension, getExtensionOutdatedWarning, getExtensionStatus } from './relay-client.js'
+import {
+  ensureRelayServer,
+  RELAY_PORT,
+  waitForConnectedExtensions,
+  getExtensionOutdatedWarning,
+  getExtensionStatus,
+  type ExtensionStatus,
+} from './relay-client.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
@@ -20,15 +28,6 @@ const cliRelayEnv = { PLAYWRITER_AUTO_ENABLE: '1' }
 
 const cli = cac('playwriter')
 
-type ExtensionStatus = {
-  extensionId: string
-  stableKey?: string
-  browser: string | null
-  profile: { email: string; id: string } | null
-  activeTargets: number
-  playwriterVersion?: string | null
-}
-
 cli
   .command('', 'Start the MCP server or controls the browser with -e')
   .option('--host <host>', 'Remote relay server host to connect to (or use PLAYWRITER_HOST env var)')
@@ -76,7 +75,7 @@ async function fetchExtensionsStatus(host?: string): Promise<ExtensionStatus[]>
       if (!fallback.ok) {
         return []
       }
-      const fallbackData = await fallback.json() as {
+      const fallbackData = (await fallback.json()) as {
         connected: boolean
         activeTargets: number
         browser: string | null
@@ -86,16 +85,18 @@ async function fetchExtensionsStatus(host?: string): Promise<ExtensionStatus[]>
       if (!fallbackData?.connected) {
         return []
       }
-      return [{
-        extensionId: 'default',
-        stableKey: undefined,
-        browser: fallbackData?.browser,
-        profile: fallbackData?.profile,
-        activeTargets: fallbackData?.activeTargets,
-        playwriterVersion: fallbackData?.playwriterVersion || null,
-      }]
+      return [
+        {
+          extensionId: 'default',
+          stableKey: undefined,
+          browser: fallbackData?.browser,
+          profile: fallbackData?.profile,
+          activeTargets: fallbackData?.activeTargets,
+          playwriterVersion: fallbackData?.playwriterVersion || null,
+        },
+      ]
     }
-    const data = await response.json() as {
+    const data = (await response.json()) as {
       extensions: ExtensionStatus[]
     }
     return data?.extensions || []
@@ -128,8 +129,12 @@ async function executeCode(options: {
   if (!host && !process.env.PLAYWRITER_HOST) {
     const restarted = await ensureRelayServer({ logger: console, env: cliRelayEnv })
     if (restarted) {
-      const connected = await waitForExtension({ logger: console, timeoutMs: 10000 })
-      if (!connected) {
+      const connectedExtensions = await waitForConnectedExtensions({
+        logger: console,
+        timeoutMs: 10000,
+        pollIntervalMs: 250,
+      })
+      if (connectedExtensions.length === 0) {
         console.error('Warning: Extension not connected. Commands may fail.')
       }
     }
@@ -150,7 +155,9 @@ async function executeCode(options: {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        ...(token || process.env.PLAYWRITER_TOKEN ? { 'Authorization': `Bearer ${token || process.env.PLAYWRITER_TOKEN}` } : {}),
+        ...(token || process.env.PLAYWRITER_TOKEN
+          ? { Authorization: `Bearer ${token || process.env.PLAYWRITER_TOKEN}` }
+          : {}),
       },
       body: JSON.stringify({ sessionId, code, timeout, cwd }),
     })
@@ -161,7 +168,11 @@ async function executeCode(options: {
       process.exit(1)
     }
 
-    const result = await response.json() as { text: string; images: Array<{ data: string; mimeType: string }>; isError: boolean }
+    const result = (await response.json()) as {
+      text: string
+      images: Array<{ data: string; mimeType: string }>
+      isError: boolean
+    }
 
     // Print output
     if (result.text) {
@@ -198,16 +209,30 @@ cli
   .option('--host <host>', 'Remote relay server host')
   .option('--browser <stableKey>', 'Stable browser key when multiple browsers are connected')
   .action(async (options: { host?: string; browser?: string }) => {
-    if (!options.host && !process.env.PLAYWRITER_HOST) {
+    const isLocal = !options.host && !process.env.PLAYWRITER_HOST
+
+    let extensions: ExtensionStatus[] = []
+
+    if (isLocal) {
       await ensureRelayServer({ logger: console, env: cliRelayEnv })
-      await waitForExtension({
-        timeoutMs: 3000,
+      extensions = await waitForConnectedExtensions({
+        timeoutMs: 12000,
+        pollIntervalMs: 250,
         logger: console,
       })
-    }
 
+      if (extensions.length === 0) {
+        console.log(pc.dim('Waiting briefly for extension to reconnect...'))
+        extensions = await waitForConnectedExtensions({
+          timeoutMs: 10000,
+          pollIntervalMs: 250,
+          logger: console,
+        })
+      }
+    } else {
+      extensions = await fetchExtensionsStatus(options.host)
+    }
 
-    const extensions = await fetchExtensionsStatus(options.host)
     if (extensions.length === 0) {
       console.error('No connected browsers detected. Click the Playwriter extension icon.')
       process.exit(1)
@@ -253,9 +278,10 @@ cli
 
     try {
       const serverUrl = await getServerUrl(options.host)
-      const extensionId = selectedExtension.extensionId === 'default'
-        ? null
-        : (selectedExtension.stableKey || selectedExtension.extensionId)
+      const extensionId =
+        selectedExtension.extensionId === 'default'
+          ? null
+          : selectedExtension.stableKey || selectedExtension.extensionId
       const cwd = process.cwd()
       const response = await fetch(`${serverUrl}/cli/session/new`, {
         method: 'POST',
@@ -267,7 +293,7 @@ cli
         console.error(`Error: ${response.status} ${text}`)
         process.exit(1)
       }
-      const result = await response.json() as { id: string; extensionId: string | null }
+      const result = (await response.json()) as { id: string; extensionId: string | null }
       console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`)
     } catch (error: any) {
       console.error(`Error: ${error.message}`)
@@ -300,7 +326,7 @@ cli
         console.error(`Error: ${response.status} ${await response.text()}`)
         process.exit(1)
       }
-      const result = await response.json() as {
+      const result = (await response.json()) as {
         sessions: Array<{
           id: string
           stateKeys: string[]
@@ -335,7 +361,7 @@ cli
         '  ' +
         'EXT'.padEnd(extensionWidth) +
         '  ' +
-        'STATE KEYS'
+        'STATE KEYS',
     )
     console.log('-'.repeat(idWidth + browserWidth + profileWidth + extensionWidth + stateWidth + 8))
 
@@ -351,7 +377,7 @@ cli
           '  ' +
           (session.extensionId || '-').padEnd(extensionWidth) +
           '  ' +
-          stateStr
+          stateStr,
       )
     }
   })
@@ -374,7 +400,7 @@ cli
       })
 
       if (!response.ok) {
-        const result = await response.json() as { error: string }
+        const result = (await response.json()) as { error: string }
         console.error(`Error: ${result.error}`)
         process.exit(1)
       }
@@ -410,8 +436,10 @@ cli
         process.exit(1)
       }
 
-      const result = await response.json() as { success: boolean; pageUrl: string; pagesCount: number }
-      console.log(`Connection reset successfully. ${result.pagesCount} page(s) available. Current page URL: ${result.pageUrl}`)
+      const result = (await response.json()) as { success: boolean; pageUrl: string; pagesCount: number }
+      console.log(
+        `Connection reset successfully. ${result.pagesCount} page(s) available. Current page URL: ${result.pageUrl}`,
+      )
     } catch (error: any) {
       console.error(`Error: ${error.message}`)
       process.exit(1)
@@ -419,9 +447,12 @@ cli
   })
 
 cli
-  .command('serve', 'Start the CDP relay server for remote MCP connections')
-  .option('--host <host>', 'Host to bind to', { default: '0.0.0.0' })
-  .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
+  .command(
+    'serve',
+    `Start the relay server on this machine (must be the same host where Chrome is running). Remote clients (Docker, other machines) connect via PLAYWRITER_HOST. Use --host localhost for Docker (no token needed) — containers reach it via host.docker.internal. Use --host 0.0.0.0 for LAN/internet access (requires --token).`,
+  )
+  .option('--host <host>', 'Host to bind to (use "localhost" for Docker, "0.0.0.0" for remote access)', { default: '0.0.0.0' })
+  .option('--token <token>', 'Authentication token, required when --host is 0.0.0.0 (or use PLAYWRITER_TOKEN env var)')
   .option('--replace', 'Kill existing server if running')
   .action(async (options: { host: string; token?: string; replace?: boolean }) => {
     const token = options.token || process.env.PLAYWRITER_TOKEN
@@ -512,20 +543,16 @@ cli
     })
   })
 
-cli
-  .command('logfile', 'Print the path to the relay server log file')
-  .action(() => {
-    console.log(`relay: ${LOG_FILE_PATH}`)
-    console.log(`cdp: ${LOG_CDP_FILE_PATH}`)
-  })
+cli.command('logfile', 'Print the path to the relay server log file').action(() => {
+  console.log(`relay: ${LOG_FILE_PATH}`)
+  console.log(`cdp: ${LOG_CDP_FILE_PATH}`)
+})
 
-cli
-  .command('skill', 'Print the full playwriter usage instructions')
-  .action(() => {
-    const skillPath = path.join(__dirname, '..', 'src', 'skill.md')
-    const content = fs.readFileSync(skillPath, 'utf-8')
-    console.log(content)
-  })
+cli.command('skill', 'Print the full playwriter usage instructions').action(() => {
+  const skillPath = path.join(__dirname, '..', 'src', 'skill.md')
+  const content = fs.readFileSync(skillPath, 'utf-8')
+  console.log(content)
+})
 
 cli.help()
 cli.version(VERSION)

package/src/create-logger.ts

@@ -21,9 +21,11 @@ export function createFileLogger({ logFilePath }: { logFilePath?: string } = {})
   let queue: Promise<void> = Promise.resolve()
 
   const log = (...args: unknown[]): Promise<void> => {
-    const message = args.map(arg =>
-      typeof arg === 'string' ? arg : util.inspect(arg, { depth: null, colors: false, maxStringLength: 1000 })
-    ).join(' ')
+    const message = args
+      .map((arg) =>
+        typeof arg === 'string' ? arg : util.inspect(arg, { depth: null, colors: false, maxStringLength: 1000 }),
+      )
+      .join(' ')
     queue = queue.then(() => fs.promises.appendFile(resolvedLogFilePath, stripAnsi(message) + '\n'))
     return queue
   }

package/src/debugger-examples-types.ts

@@ -8,6 +8,9 @@ export declare const page: Page
 export declare const getCDPSession: (options: { page: Page }) => Promise<ICDPSession>
 export declare const createDebugger: (options: { cdp: ICDPSession }) => Debugger
 export declare const createEditor: (options: { cdp: ICDPSession }) => Editor
-export declare const getStylesForLocator: (options: { locator: Locator; includeUserAgentStyles?: boolean }) => Promise<StylesResult>
+export declare const getStylesForLocator: (options: {
+  locator: Locator
+  includeUserAgentStyles?: boolean
+}) => Promise<StylesResult>
 export declare const formatStylesAsText: (styles: StylesResult) => string
 export declare const console: { log: (...args: unknown[]) => void }

package/src/debugger.ts

@@ -24,8 +24,6 @@ export interface EvaluateResult {
   value: unknown
 }
 
-
-
 export interface ScriptInfo {
   scriptId: string
   url: string
@@ -533,9 +531,7 @@ export class Debugger {
   async listScripts({ search }: { search?: string } = {}): Promise<ScriptInfo[]> {
     await this.enable()
     const scripts = Array.from(this.scripts.values())
-    const filtered = search
-      ? scripts.filter((s) => s.url.toLowerCase().includes(search.toLowerCase()))
-      : scripts
+    const filtered = search ? scripts.filter((s) => s.url.toLowerCase().includes(search.toLowerCase())) : scripts
     return filtered.slice(0, 20)
   }
 

package/src/diff-utils.ts

@@ -16,7 +16,7 @@ export interface CreateSmartDiffOptions {
 
 /**
  * Creates a smart diff that returns full content when changes exceed threshold.
- * 
+ *
  * When more than `threshold` (default 50%) of lines have changed, showing a diff
  * is not useful - we return the full new content instead.
  */
@@ -54,10 +54,7 @@ export function createSmartDiff(options: CreateSmartDiffOptions): SmartDiffResul
   const changeRatio = Math.min(changedLines / maxLines, 1) // Cap at 100%
 
   // Build unified diff string from structured patch
-  const diffLines: string[] = [
-    `--- ${label} (previous)`,
-    `+++ ${label} (current)`,
-  ]
+  const diffLines: string[] = [`--- ${label} (previous)`, `+++ ${label} (current)`]
   for (const hunk of patch.hunks) {
     diffLines.push(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`)
     diffLines.push(...hunk.lines)

package/src/editor-examples.ts

@@ -145,4 +145,14 @@ async function searchStyles() {
   console.log(matches)
 }
 
-export { listScripts, readScript, editScript, searchScripts, writeScript, editInlineScript, readStylesheet, editStylesheet, searchStyles }
+export {
+  listScripts,
+  readScript,
+  editScript,
+  searchScripts,
+  writeScript,
+  editInlineScript,
+  readStylesheet,
+  editStylesheet,
+  searchStyles,
+}

package/src/editor.ts

@@ -294,7 +294,7 @@ export class Editor {
   private async setSource(
     id: { scriptId: string } | { styleSheetId: string },
     content: string,
-    dryRun = false
+    dryRun = false,
   ): Promise<EditResult> {
     if ('styleSheetId' in id) {
       await this.cdp.send('CSS.setStyleSheetText', { styleSheetId: id.styleSheetId, text: content })
@@ -410,7 +410,15 @@ export class Editor {
    * @param options.content - New content
    * @param options.dryRun - If true, validate without applying (default false, only works for JS)
    */
-  async write({ url, content, dryRun = false }: { url: string; content: string; dryRun?: boolean }): Promise<EditResult> {
+  async write({
+    url,
+    content,
+    dryRun = false,
+  }: {
+    url: string
+    content: string
+    dryRun?: boolean
+  }): Promise<EditResult> {
     await this.enable()
     const id = this.getIdByUrl(url)
     return this.setSource(id, content, dryRun)